Forem: Simon

Ajout de l'auto-complétion sur les Web Components avec Stencil

Simon — Thu, 14 Mar 2024 08:00:46 +0000

Introduction

Chez MGDIS, nous mettons à jour nos services en passant de AngularJS, désormais obsolète, à Vue.js. Cependant, avec l'évolution rapide des frameworks et la transition de Vue 2 à Vue 3, ces changements ne sont pas sans difficultés. Pour cela, nous nous sommes tournés vers les Web Components, un standard indépendant de tout framework.

Au sein de la Core UI, nous développons mg-components, une bibliothèque de Web Components basée sur Stencil. Cette bibliothèque offre une collection de composants conçus pour faciliter le développement et garantir l'accessibilité de nos produits.
Note: Stencil n’est pas un framework mais une librairie qui permet de générer des Web Components.

Une demande fréquente des développeurs était l'auto-complétion dans leurs IDEs pour notre librairie mg-components. Cependant, les Web Components ne fournissent pas automatiquement cette fonctionnalité car cela nécessite des informations spécifiques sur les éléments et attributs personnalisés. Nous avons donc cherché une solution pour remédier à cette limitation.

La recherche de la solution

Nous avons d'abord exploré les options pour VS Code, nous avons rapidement découvert que Stencil propose l'export VS Code Documentation, basé sur les custom data, un format pris en charge par VS Code. Une fois le fichier généré, l'intégration est simple : il suffit d'ajouter un fichier de configuration dans le projet utilisant la librairie pour que l'auto-complétion fonctionne.

Cependant, nous avons également des développeurs qui utilisent WebStorm, pour lequel Stencil ne propose pas d'export de documentation. Pour contourner ce problème, nous avons utilisé les web types de JetBrains, qui sont un équivalent des custom data mais pour WebStorm.
Avec le package stenciljs-web-types-generator
nous sommes en mesure de générer ce fichier. Il suffit ensuite de le référencer à la propriété "web-types" dans le package.json de la librairie pour que le projet bénéficie de l'auto-complétion.

Ces solutions permettent d'obtenir l'auto-complétion pour les principaux IDE utilisés chez MGDIS mais dans l'idéal, nous souhaiterions également accéder aux informations détaillées sur les attributs, propriétés, événements et méthodes disponibles pour chaque élément, ainsi que connaître les valeurs possibles ou le type attendu par un attribut. Avoir des liens vers la documentation et le code source des composants serait aussi un gros plus.

Le développement de la solution

Pour générer nos deux fichiers, nous utilisons le build docs-custom proposé par Stencil. Cette fonctionnalité nous permet d'accéder à un JSON représentant la documentation de nos composants.
Ce JSON est ensuite transformé pour obtenir les formats attendus pour les custom data et web types.

Le générateur pour VS Code :

/**
 * Generate custom HTML datasets for VS Code
 * @param version - Library version
 * @param storybookBaseUrl - Storybook Base Url
 * @param jsonDocs - Stencil JSON doc
 * @returns custom HTML datasets
 */
export const vsCodeGenerator = (version: string, jsonDocs: JsonDocs, storybookBaseUrl: string, sourceBaseUrl: string) => ({
  version,
  tags: jsonDocs.components.map(component => {
    const references = getReferences(storybookBaseUrl, sourceBaseUrl, component.filePath);
    return {
      name: component.tag,
      description: getElementDescription(component),
      attributes: component.props.map(prop => ({
        name: prop.attr || prop.name,
        description: getAttributeDescription(prop),
        values: getValues(prop),
        references,
      })),
      references,
    };
  }),
  globalAttributes: [],
  valueSets: [],
});

Le générateur pour WebStorm :

/**
 * Generate Web Types metadata for IntelliJ's IDE
 * @param name - Library name
 * @param version - Library version
 * @param storybookBaseUrl - Storybook Base Url
 * @param jsonDocs - Stencil JSON doc
 * @returns Web Types metadata
 */
export const webTypesGenerator = (name: string, version: string, jsonDocs: JsonDocs, storybookBaseUrl: string) => ({
  '$schema': 'https://json.schemastore.org/web-types',
  name,
  version,
  'description-markup': 'markdown',
  'contributions': {
    html: {
      elements: jsonDocs.components.map(component => {
        const docUrl = getStorybookUrl(storybookBaseUrl, component.filePath);
        return {
          'name': component.tag,
          'description': getElementDescription(component),
          'doc-url': docUrl,
          'attributes': component.props
            .filter(prop => prop.attr)
            .map(prop => ({
              'name': prop.attr,
              'description': getAttributeDescription(prop),
              'doc-url': docUrl,
              'value': {
                type: prop.type,
                default: prop.default,
                required: prop.required,
              },
            })),
          'js': {
            properties: component.props.map(prop => ({
              'name': prop.name,
              'description': getAttributeDescription(prop),
              'doc-url': docUrl,
              'value': {
                type: prop.type,
                default: prop.default,
                required: prop.required,
              },
            })),
            events: component.events.map(event => ({
              name: event.event,
              description: event.docs,
            })),
          },
        };
      }),
    },
  },
});

Nous avons centralisé la génération des descriptions des éléments et des attributs dans les méthodes getElementDescription et getAttributeDescription pour garantir une expérience uniforme sur les deux IDEs, celles-ci seront disponibles au survol.

Code mutualisé :

/**
 * Get Component element description
 * @param component - Component
 * @returns Component element description
 */
const getElementDescription = (component: JsonDocsComponent): string => {
  // Init description
  let description = component.overview ? `${component.overview}\n\n` : '';
  // Attributes
  const attributes = component.props.filter(({ attr }) => attr !== undefined);
  if (attributes.length) {
    description += `Attributes:\n`;
    description += attributes.map(({ attr, docs }) => `- \`${attr}\`: ${docs}\n`).join('');
    description += '\n';
  }
  // Properties
  const properties = component.props.filter(({ attr }) => attr === undefined);
  if (properties.length) {
    description += `Properties:\n`;
    description += properties.map(({ name, docs }) => `- \`${name}\`: ${docs}\n`).join('');
    description += '\n';
  }
  // Methods
  if (component.methods.length) {
    description += `Methods:\n`;
    description += component.methods.map(({ name, docs }) => `- \`${name}\`: ${docs}\n`).join('');
    description += '\n';
  }
  // Events
  if (component.events.length) {
    description += `Events:\n`;
    description += component.events.map(({ event, docs }) => `- \`${event}\`: ${docs}\n`).join('');
    description += '\n';
  }
  // Listeners
  if (component.listeners.length) {
    description += `Listeners:\n`;
    description += component.listeners.map(({ event }) => `- \`${event}\`\n`).join('');
    description += '\n';
  }
  // Slots
  if (component.slots.length) {
    description += `Slots:\n`;
    description += component.slots.map(({ name, docs }) => `- \`${name}\`: ${docs}\n`).join('');
    description += '\n';
  }
  // Return
  return description;
};

/**
 * Get Props Description
 * @param prop - Component Property
 * @returns Props Description
 */
const getAttributeDescription = (prop: JsonDocsProp): string => {
  return `${prop.docs}\n\nType: \`${prop.type}\``;
};

A MGDIS nous avons deux librairies de Web Components réalisées avec Stencil : une pour le design system et l'autre pour les composants métier spécifiques à nos applications.
Afin d'éviter la duplication de code, nous avons centralisé le code de ces "générateurs" dans le package @mgdis/stencil-helpers de notre monorepo Core UI.

Intégration dans les projets

La mise en place de l'auto-complétion varie selon l’IDE utilisé. Pour VS Code, il est nécessaire d'ajouter aux projets utilisant la librairie un fichier settings.json dans le dossier .vscode avec la propriété suivante :

{
  "html.customData": ["packages/mg-components/ide/vscode/html-custom-data.json"]
}

Pour IntelliJ, le processus est plus simple. Nous avons ajouté la propriété "web-types" dans le package.json de la librairie avec le lien vers le fichier, ainsi tout projet qui charge la librairie profite de l'auto-complétion :

{
    ...
    "web-types": "ide/intellij/web-types.json",
    ...
}

Avec ces configurations en place, les projets utilisant la librairie auront l'auto-complétion et des éléments de documentation au survol, offrant ainsi une intégration simple et efficace.

Conclusion

L'ajout de l'auto-complétion et des éléments de documentation s'est révélé être une tâche relativement simple. Cependant, il est dommage que chaque IDE propose une solution différente.

J’ai apprécié l'approche d'IntelliJ, qui semble plus proche de la réalité en distinguant les attributs et propriétés, et en offrant une intégration transparente sans nécessiter de configuration supplémentaire.
D'un autre côté, j’ai trouvé la flexibilité et la personnalisation des liens proposés par VS Code plus intéressantes.
Idéalement, il faudrait avoir une norme commune pour tous les IDEs.

Il est également à noter que ces deux standards permettent aussi de documenter le CSS.
Nous travaillons sur un package pour les styles, il est probable que nous allons apporter une configuration similaire à celle que nous avons mise en place pour les Web Components.

Enfin, ce serait une amélioration intéressante si Stencil proposait aussi les web-types comme format dans ses exports de documentation.

Simplifier l'intégration des icônes depuis Figma : De la conception au design system

Simon — Mon, 19 Feb 2024 13:47:05 +0000

Introduction

Les icônes jouent un rôle crucial dans un design system, mais leur intégration peut être un processus fastidieux.

L'équipe Core UI de MGDIS se compose de deux développeurs frontend, deux designers et un alternant designer qui partagent leur temps entre le produit et le design system. Les designers créent les maquettes et les composants sur Figma, tandis que les développeurs travaillent sur un monorepo organisé en différents packages pour les composants, les styles, les images, etc.

Pour ajouter une seule icône à la bibliothèque du design system, le designer la concevait sur Figma, l'exportait au format SVG pour l'ajouter au ticket Jira. Ensuite, l'équipe de développement devait intervenir : télécharger l'icône, la nettoyer, ajouter les attributs nécessaires et mettre à jour les tests. Cette chaîne de tâches fastidieuses nous a poussés à chercher une solution pour automatiser le processus, de la conception à l'intégration dans le design system.

A la découverte de l'API de Figma

Parmi les différentes API proposées par Figma, c'est l'API REST qui va nous intérésser. Elle va nous permettre d'acceder au fichier Figma, d'en extraire les propriétés et récupérer les images.

La documentation de l'API REST de Figma s'est avérée plutôt claire, et nous avons commencé par générer un access token. Bien qu'il soit possible d'en générer un automatiquement depuis la documentation, il est important de noter que celui-ci est programmé pour ne durer qu'une journée. Il vaut donc mieux suivre les instructions pour obtenir un access token qui n'expire pas.

Dans notre cas, le seul scope dont nous avions besoin était "File content" en lecture seule. Avec l'access token en main, nous pouvons maintenant explorer les différents endpoints de la partie "Files" de l'API.

Endpoints

La partie "Files" de l'API propose quatre endpoints :

file : pour avoir des informations sur l'ensemble d'un fichier,
file nodes : pour avoir des informations sur des nœuds spécifiques,
image : pour avoir des rendus d'images à partir d'un fichier,
image fills : pour avoir des liens de téléchargement pour les images présentes dans le document Figma.

Pour utiliser ces endpoints, l'access token doit être inclus dans l'en-tête des appels, en utilisant la clé X-FIGMA-TOKEN.

Deux paramètres nous intéressent ici, l'identifiant du document :key et l'id de la page :ids où sont les icônes que nous souhaitons importer.
Pour l'URL suivante https://www.figma.com/file/blubliblobla/Design-System-MGDIS?node-id=16:64 nous aurons :key qui vaut blubliblobla et :ids qui vaut 16:64.

Pour accéder aux informations du document, nous avons choisi le file endpoint avec l'utilisation du paramètre ids, permettant de cibler la page contenant les icônes souhaitées. Avec ce paramètre la réponse est passée de 22 Mo à 400 Ko et nous permet de nous assurer que seules les icônes nécessaires sont renvoyées. Bien que le file nodes endpoint aurait pu être une alternative, nous avons préféré la structure de réponse du file endpoint.

curl -H 'X-FIGMA-TOKEN: figd_blublu' 'https://api.figma.com/v1/files/blubliblobla?ids=16:64'

{
  "document": {
    "id": "0:0",
    "name": "Document",
    "type": "DOCUMENT",
    "scrollBehavior": "SCROLLS",
    "children": []
  },
  "components": {
    "544:5714": {
      "key": "0b2def94349533e0123459c6c5484868b03b7249",
      "name": "Fill=true",
      "description": "",
      "remote": false,
      "componentSetId": "544:5715",
      "documentationLinks": []
    },
    "544:5713": {
      "key": "f6e9220714ce66f47d259a6df2b638214daa0ad5",
      "name": "Fill=false",
      "description": "",
      "remote": false,
      "componentSetId": "544:5715",
      "documentationLinks": []
    }
  },
  "componentSets": {
    "544:5715": {
      "key": "cf0c91d6be16254a549f0e66e3d482e6e0f99769",
      "name": "briefcase",
      "description": "",
      "documentationLinks": []
    }
  },
  "styles": {},
  "name": "Design System MGDIS",
  "lastModified": "2024-02-15T13:43:30Z",
  "thumbnailUrl": "",
  "version": "",
  "role": "viewer",
  "editorType": "figma",
  "linkAccess": "view"
}

Les propriétés qui nous intéressent dans la réponse sont components et componentSets. Toutes nos icônes se trouvent sous components et peuvent exister en deux variantes : "pleine" (fill) ou "contour" (outline). Nous utiliserons le componentSetId pour retrouver le nom du fichier final avec les componentSets.

Maintenant, nous pouvons utiliser le image endpoint pour obtenir les liens de téléchargement de nos icônes au format SVG en fournissant :key, les :ids des composants icônes et le format souhaité.

curl -H 'X-FIGMA-TOKEN: figd_blublu' 'https://api.figma.com/v1/images/blubliblobla?ids=544:5714,544:5713&format=svg'

{
  "err": null,
  "images": {
    "544:5714": "https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/...",
    "544:5713": "https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/..."
  }
}

Nous sommes désormais prêts à passer à la partie code !

Script

En résumé, le script doit :

Utiliser le file endpoint pour récupérer la liste des composants icônes.
Utiliser le image endpoint pour obtenir les liens des fichiers images.
Télécharger les images.

Voici le premier script fonctionnel que nous avons réalisé :

// Utilisation d'Axios pour les appels API, fs pour écrire les fichiers téléchargés.
const axios = require('axios');
const { writeFile } = require('fs').promises;

// Création d'une instance Axios pour les appels API.
const instance = axios.create({
  baseURL: 'https://api.figma.com/v1/',
  headers: { 'X-FIGMA-TOKEN': 'figd_blublu' },
});

(async () => {
  try {
    // Document et node Figma où l'on souhaite récuperer les icônes.
    const figmaFileKey = 'blubliblobla';
    const figmaNodeId = '16:64';

    // Appel du `file endpoint` pour obtenir les composants icônes.
    const { data: dataFileEndpoint } = await instance.get(`files/${figmaFileKey}`, { params: { ids: figmaNodeId } });

    // Récuperation des ids des nodes components.
    const nodeComponentsIds = Object.keys(dataFileEndpoint.components);

    // Appel du `images endpoint` pour obtenir les liens de téléchargement des images.
    const { data: dataImageEndpoint } = await instance.get(`files/${figmaFileKey}`, { params: { ids: nodeComponentsIds.join(','), format: 'svg' } });

    // Pour chaques liens images présents dans la réponse :
    for (const [id, url] of Object.entries(dataImageEndpoint.images)) {
      // On récupère le nom de fichier.
      let filename = dataFileEndpoint.components[id].name;
      // Les composants avec une variante dépendent d'un componentSet.
      if (dataFileEndpoint.components[id].componentSetId) {
        // Dans ce cas c'est lui qui porte le bon nom de fichier.
        filename = dataFileEndpoint.componentSets[componentSetId].name;
        // Et il faut différencier en fonction du variant défini
        if (dataFileEndpoint.components[id].name === 'Fill=false') {
          filename += '-outline';
        }
      }

      // On télecharge l'image SVG.
      const { data: svgSrc } = await instance.get(url);

      // Et on termine par l'écrire.
      writeFile(`icons/${filename}.svg`, svgSrc, err => {
        if (err) {
          console.error(err);
          return;
        }
      });
    }
  } catch (error) {
    console.log('ERROR', error);
  }
})();

Ce script nous a permis de rapidement valider la mécanique et est actuellement intégré à notre monorepo, avec quelques ajustements, notamment pour formater et optimiser les SVG téléchargés avant de les enregistrer.

Formatage des SVGs téléchargés

Les icônes sont importées telles quelles avec une couleur prédéfinie, généralement en noir. Cependant, nous souhaitons permettre la surcharge de cette couleur. Pour y parvenir, nous devons modifier le code téléchargé avant d'enregistrer le SVG.

Nous avons opté pour l'utilisation de la bibliothèque jsdom afin de manipuler le DOM et de remplacer les valeurs de couleur par currentColor. Cette méthode offre la possibilité de personnaliser facilement la couleur des icônes via CSS.

// Utilisation de la bibliothèque JSDOM
import { JSDOM } from 'jsdom';

// Création d'un objet JSDOM avec le contenu du SVG téléchargé
const { window } = new JSDOM(svgSrc, { contentType: 'image/svg+xml' });
const { document } = window;

// Modification de tous les attributs fill dont la valeur n'est pas "none"
const pathElements = document.querySelectorAll('[fill]:not([fill="none"])');
pathElements.forEach(pathElement => {
  pathElement.setAttribute('fill', 'currentColor');
});

// Modification de tous les attributs stroke
const strokeElements = document.querySelectorAll('[stroke]');
strokeElements.forEach(pathElement => {
  pathElement.setAttribute('stroke', 'currentColor');
});

// Le document contient maintenant le SVG modifié

Le SVG étant maintenant formaté, la prochaine étape consiste à l'optimiser avant de l'enregistrer. Pour cela, nous avons utilisé svgo, une bibliothèque spécialisée dans la compression des images SVG.

// Utilisation de la bibliothèque svgo
import { optimize } from 'svgo';

// Optimisation du SVG
const optimizedSVG = optimize(document.documentElement.outerHTML).data;

// Nous pouvons maintenant enregistrer l'icône.

En combinant ces méthodes, nous avons automatisé le processus d'importation des icônes depuis Figma, garantissant ainsi leur préparation pour une utilisation dans nos applications. Le script final que nous utilisons aujourd'hui est disponible sur notre monorepo.

Limites de l'automatisation

Bien que l'importation automatisée des SVGs soit désormais gérée par le package dédié aux images, certaines étapes requièrent toujours une intervention manuelle.

Par exemple, une fois les icônes importées, le package des composants doit mettre à jour sa liste pour refléter les nouvelles icônes disponibles. Cette mise à jour est généralement effectuée lors du processus de build. Cependant, en raison de notre volonté de fournir une couverture de tests complète, chaque nouvelle icône nécessite la création de snapshots Jest et de captures d'écran Playwright. De même, lorsqu'une icône existante est modifiée, il est nécessaire de mettre à jour ces snapshots et captures d'écran, ainsi que ceux des composants utilisant ces icônes.

Cette étape manuelle reste nécessaire car elle permet de vérifier visuellement que les icônes sont conformes aux attentes. Le script d'import des icônes est donc également exécuté manuellement.

Conclusion

Nous avons considérablement amélioré notre processus en simplifiant l'intégration des icônes dans notre design system. En utilisant l'API de Figma et des outils comme jsdom et svgo, nous avons automatisé plusieurs étapes, ce qui nous a fait gagner un temps précieux.

Notre travail ne va pas s'arrêter là. Nous souhaitons maintenant poursuivre dans cette direction en exploitant davantage les possibilités offertes par Figma. Les prochaines étapes seront certainement de faire la même chose pour l'importation des illustrations, puis celle des variables.

Vous pouvez explorer notre collection complète d'icônes et de composants dans notre Storybook.