Passer au contenu principal

Surface de l'API

Introduction​

Compte tenu de la nature du développement front-end, certains détails de l'implémentation, ou de son résultat, sont exposés aux utilisateurs. Toutefois, ils ne font pas tous partie de la surface de l'API.

Le présent document décrit les parties de Jutro Digital Platform (JDP) qui composent le contrat entre JDP et ses utilisateurs. Ces parties sont soumises aux politiques de modifications sans rupture, ce qui garantit que les versions mineures n'introduisent pas de modifications non rétrocompatibles.

Les rares exceptions à cette règle concernent les correctifs de sécurité nécessaires ou les corrections de bogues.

Warning: L'utilisation de tout élément autre qu'une API peut entraîner des problèmes de maintenance et de mise à niveau des applications.

Les modifications de rupture (modifications non rétrocompatibles) apportées à des aspects qui ne sont pas des API peuvent se produire dans des versions mineures sans aucune mention dans les notes de version.

Nous vous recommandons vivement de ne pas vous fier à ces aspects dans tout code de production.

API Jutro Design System et Bibliothèques d'interface utilisateur​

Les aspects suivants sont considérés comme un contrat Jutro Design System et Bibliothèques d'interface utilisateur :

Noms de package et structures publiques de package et de module ou signatures​

Les noms des packages JDP et leurs exportations publiques font partie du contrat, ainsi que les signatures et les types des différentes fonctions.

Warning: Seules les exportations directes à partir des points d'entrée indiqués sont considérées comme faisant partie du contrat. Pour en savoir plus, reportez-vous à la Présentation des packages.

Exemple : il ne s'agirait pas d'une exportation directe à partir d'un point d'entrée défini (@jutro/components), elle ne fait donc pas partie du contrat de bibliothèques JDP :

import { intlMessageShape } from '@jutro/components/types/types';

Dans ce cas, une importation valide à partir de ce point d’entrée serait la suivante :

import { Button } from '@jutro/components';

Exemples :

  • Le nom du package, le nom du composant MicroFrontend, son chemin d’importation et ses propriétés font partie du contrat.
import { MicroFrontend } from '@jutro/micro-frontends'

<MicroFrontend
    src='claimMicroFrontend@http://localhost:3001'
    jutro = {
        mode: 'isolated'
        router: {
            basename: '/welcome',
        }
    ...
    }
>

La propriété jutro peut ajouter de nouvelles propriétés ou étendre leurs valeurs acceptées, mais en conservant toujours la prise en charge des valeurs existantes.

  • Le crochet useAuth du package @jutro/auth renvoie les attributs ci-dessous, lesquels ne seront pas modifiés (ils pourraient être étendus) :
{
  isAuthenticated: boolean;
  isPending: boolean;
  userInfo: OidcUserInfo | null;
  error?: Error;
  login: AuthLogin;
  logout: AuthLogout;
  accessToken: string | null;
  idToken: string | null;
}
Warning: Des packages Jutro expérimentaux peuvent parfois être disponibles. Ils utilisent une convention de dénomination comme @jutro/experimental-*. Ces packages ne sont pas considérés comme faisant partie du contrat JDP et sont susceptibles d’évoluer, car ils sont en cours de développement.

Propriétés des composants React : noms, types et valeurs par défaut​

Les noms des composants et l'ensemble des propriétés acceptées font partie du contrat. Consultez la documentation des composants et les portes de sortie pour en savoir plus et connaître les options de personnalisation.

Exemple : rendre obligatoire une propriété facultative serait considéré comme une modification de rupture. Toutefois, le fait de rendre une propriété obligatoire facultative pourrait se produire dans une version mineure, car cela n'aurait pas d'impact sur les clients existants.

Aspects visuels et comportement des composants React​

Le comportement et la représentation visuelle des composants font partie du contrat et doivent rester stables.

Exemples de comportements :

  • Quand est-ce qu'un élément Tooltip doit être fermé par défaut ?
  • Statut par défaut (développé/réduit) des éléments AccordionCard
  • Événements déclenchés lors d'une interaction utilisateur : lorsque l'événement onChange est déclenché alors que l'utilisateur interagit avec un élément de saisie

La façon dont le composant (et chacune de ses variantes) est affiché par défaut restera stable et toute modification sera rétrocompatible. Toutefois, les composants fournissent également des options de personnalisation qui permettent aux utilisateurs de remplacer ces valeurs par défaut (par exemple, les jetons de conception).

Les options de personnalisation disponibles font partie du contrat, tandis que les valeurs appliquées dépendent du consommateur. Pour en savoir plus, reportez-vous à la section Création de thèmes : jetons de conception ci-dessous. La page Portes de sortie décrit également d'autres alternatives de personnalisation.

Arborescence d'accessibilité des composants React​

L'accessibilité est l'un des aspects clés de Jutro Design System, et l'arborescence d'accessibilité de chaque composant fait partie du contrat.

Warning: Les exigences en matière d'accessibilité des composants font l'objet d'une révision continue. Le non-respect de ce domaine est considéré comme un bogue et sa résolution peut impliquer des modifications dans l'arborescence d'accessibilité, par exemple : ajout, suppression ou modification d'un rôle ARIA d'élément.

Création de thèmes : jetons de conception​

Les jetons de conception définissent les différentes options de personnalisation disponibles et la façon dont elles sont appliquées aux différents composants. Bien que les valeurs des jetons de conception puissent évoluer, 2 parties resteront stables et rétrocompatibles dans la bibliothèque de composants React :

  1. Noms des jetons de conception
  2. Comment les jetons de conception sont appliqués à chaque composant
Note: Les jetons au niveau du composant représentent la façon dont les jetons de conception sont appliqués aux composants. Ils définissent les options de personnalisation prises en charge par chaque composant. Il est possible d'introduire de nouvelles options de personnalisation, mais celles qui existent déjà doivent rester disponibles.

Pour en savoir plus, reportez-vous à la documentation sur les jetons de conception

Clés de traduction​

Les bibliothèques JDP, y compris les composants Jutro Design System, fournissent des messages par défaut, par exemple, le message à afficher lorsqu'aucune option n'est disponible dans un Combobox. Celles-ci sont définies pour permettre leur internationalisation et fournir certaines valeurs par défaut.

 noResults: {
        id: 'jutro-components.fields.Combobox.noResults',
        defaultMessage: 'No results.',
    },

Les clés de message (id) font partie du contrat.

Prise en charge des principales dépendances tierces​

La prise en charge des versions de Node.js, React ou Webpack serait maintenue, mais la prise en charge de nouvelles versions pourrait être ajoutée.

Note: Les EoL ou EoS définies par les fournisseurs doivent être pris en compte, en particulier du point de vue de la sécurité.

En outre, les nouvelles fonctionnalités JDP peuvent obliger les clients à effectuer une mise à niveau vers des versions de dépendances plus récentes pour fonctionner.

Configuration : fichiers, noms de variables, valeurs par défaut et types​

Les variables de configuration existantes, les valeurs acceptées et leurs valeurs par défaut doivent rester disponibles et ne pas être modifiées. Il est possible d'étendre les options disponibles ou d'introduire de nouvelles alternatives.

Exemple : JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT est fournie, et accepte true / false, false étant la valeur par défaut.

Compatibilité d'imbrication de micro front-ends​

Le composant MicroFrontend et le SDK du micro front-end définissent une API claire et contiennent une couche encapsulée qui permet l'intégration de micro front-ends indépendamment de la version mineure des bibliothèques JDP que le shell et les applications micro front-end utilisent.

Pour en savoir plus, reportez-vous à la documentation sur les micro front-ends, y compris la référence aux API.

Commandes CLI : disponibilité, signature et objectif​

La liste des commandes disponibles dans les interfaces de ligne de commande fournies fait partie du contrat, ainsi que leurs différentes options de configuration.

Warning: Les résultats d'exécution des commandes CLI peuvent être modifiés pour les adapter aux dernières versions, pratiques et besoins en fonctionnalités.

Configuration des outils de développement fournis​

Les scripts utilisés pour générer l'application, les options de linting et les autres fonctionnalités associées resteront rétrocompatibles.

Warning: Bien que les scripts et les configurations restent disponibles, nous devrons peut-être les modifier ou les adapter en fonction de l'évolution des besoins des produits et des clients, ce qui peut entraîner une sortie différente de ces scripts.

Aspects ne faisant pas partie de l'API​

Voici une liste d'aspects qui ne font pas partie du contrat JDP, même s'ils sont exposés et disponibles :

  • Toute exportation depuis les chemins internal ou tout point d'entrée non répertorié sur la page Présentation des packages.
  • Toute exportation depuis les chemins experimental-*.
  • Balisage HTML de composant.
  • Noms de classe CSS.
  • Variables CSS.
  • Mixins CSS.
  • Modèles et exemples de conception, généralement écrits dans la documentation.
  • Messages pour les développeurs et les outils de compilation, tels que le texte d'erreur et les avertissements
  • Erreurs d'exécution : génération d'erreurs et codes d'erreur associés (les messages spécifiques et les propriétés supplémentaires ne font pas partie de l'API).
  • Modèles.

SDK Digital​

Reportez-vous à la documentation sur le cahier des charges de l'API du SDK Digital.

SDK Digital dans Jutro​

Lors de la génération du SDK Digital à l'aide de l'interface de ligne de commande de la plate-forme Jutro, les mêmes cahiers des charges que ceux définis dans la documentation sur le SDK Digital s'appliquent.

Toutefois, il existe des fonctionnalités spécifiques à Jutro disponibles pour l'initialisation et la configuration qui font également partie du cahier des charges JDP.

Extensions de l'interface utilisateur du SDK Digital​

Les extensions d'interface utilisateur du SDK Digital sont un ensemble d'abstractions générées qui étendent le SDK Digital pour fonctionner plus efficacement dans les applications React. Ces extensions ont leurs propres cahiers des charges définis dans le cahier des charges de l'API des extensions de l'interface utilisateur du SDK Digital.

Infrastructure de Jutro Digital Platform​

L'infrastructure de Jutro Digital Platform est fournie en tant que service. Cependant, dans le but de réduire les perturbations pour les clients, les aspects suivants ont été considérés comme faisant partie de son cahier des charges :

Format d'URL de déploiement généré automatiquement​

Format des URL de déploiement générées automatiquement utilisé lorsque les déploiements sont créés sans utiliser de domaines personnalisés.