Saltar al contenido principal

Superficie de la API

Introducción​

Dada la naturaleza del desarrollo de front-end, hay algunos detalles de la implementación, o su resultado, que quedan expuestos a los consumidores. Sin embargo, no todos forman parte de la superficie de la API.

En este documento se describen las partes de Jutro Digital Platform (JDP) que componen el contrato entre JDP y sus consumidores. Estas partes están sujetas a las políticas de cambios sin interrupciones, lo que garantiza que las versiones de menor importancia no introduzcan cambios no retrocompatibles.

La excepción poco frecuente a esta regla son las correcciones de seguridad necesarias o las correcciones de errores.

Warning: Depender de cualquier elemento que no sea de la API puede causar problemas para el mantenimiento y la actualización de las aplicaciones.

En versiones de menor importancia, puede haber cambios importantes (cambios no retrocompatibles) a aspectos que no sean las API sin ninguna mención en las notas de la versión.

Le recomendamos encarecidamente que no se base en estos aspectos en ningún código de producción.

Jutro Design System y API de bibliotecas de interfaz de usuario​

Los siguientes aspectos se consideran contratos de Jutro Design System y las bibliotecas de interfaz de usuario:

Nombres de paquetes y estructuras públicas o firmas de paquetes y módulos​

Los nombres de los paquetes de JDP y sus exportaciones públicas forman parte del contrato, así como las firmas y tipos de las diferentes funciones.

Warning: Solo las exportaciones directas desde los puntos de entrada enumerados se consideran parte del contrato. Para obtener más información, consulte la información general sobre paquetes.

Ejemplo: esto no sería una exportación directa desde un punto de entrada definido (@jutro/components), por eso, no forma parte del contrato de las bibliotecas de JDP:

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

En este caso, una importación válida desde ese punto de entrada sería:

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

Ejemplos:

  • El nombre del paquete, el nombre del componente MicroFrontend, su ruta de importación y sus propiedades forman parte del contrato.
import { MicroFrontend } from '@jutro/micro-frontends'

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

La propiedad jutro podría añadir nuevas propiedades o ampliar sus valores aceptados, pero siempre debe mantener la compatibilidad para los existentes.

  • El gancho useAuth del paquete @jutro/auth devuelve los siguientes atributos y no se modificarán (podrían ampliarse):
{
  isAuthenticated: boolean;
  isPending: boolean;
  userInfo: OidcUserInfo | null;
  error?: Error;
  login: AuthLogin;
  logout: AuthLogout;
  accessToken: string | null;
  idToken: string | null;
}
Warning: A veces puede haber paquetes experimentales de Jutro. Utilizan una convención de nomenclatura como @jutro/experimental-*. Estos paquetes no se consideran parte del contrato de JDP y están sujetos a cambios, ya que están en desarrollo activo.

Propiedades de componentes de React: sus nombres, tipos y valores predeterminados​

Los nombres de los componentes y el conjunto de propiedades aceptadas forman parte del contrato. Revise la documentación de los componentes y las escotillas de escape para obtener más detalles y opciones de personalización.

Ejemplo: hacer que una propiedad opcional sea obligatoria se consideraría un cambio importante. Sin embargo, hacer que una propiedad obligatoria sea opcional podría ocurrir en una versión de menor importancia, ya que no afectaría de ninguna manera a los clientes existentes.

Aspectos visuales y comportamiento de los componentes de React​

El comportamiento y la representación visual de los componentes son parte del contrato y deben permanecer estables.

Ejemplo de comportamientos:

  • Cuándo debe cerrarse una Tooltip de forma predeterminada.
  • El estado predeterminado (expandido/contraído) de los elementos AccordionCard.
  • En el caso de eventos activados en la interacción del usuario, cuándo se activa el evento onChange mientras el usuario interactúa con un elemento de entrada.

La forma en que se muestra el componente (y cada una de sus variantes) de forma predeterminada permanecerá estable, y cualquier modificación será compatible con versiones anteriores. Sin embargo, los componentes también proporcionan opciones de personalización que permiten a los consumidores invalidar estos valores predeterminados (por ejemplo, tokens de diseño).

Las opciones de personalización disponibles forman parte del contrato, mientras que los valores aplicados dependen del consumidor. Consulte la sección Tematización: tokens de diseño a continuación para obtener más detalles. La página Escotillas de escape también describe otras alternativas de personalización.

Árbol de accesibilidad de los componentes de React​

La accesibilidad es uno de los aspectos clave de Jutro Design System, y el árbol de accesibilidad de cada componente forma parte del contrato.

Warning: Los requisitos de accesibilidad de los componentes están en revisión continua. La falta de cumplimiento con respecto a esta área se considera un error y su resolución podría implicar modificaciones en el árbol de accesibilidad. Por ejemplo, agregar, quitar o modificar un rol de ARIA de elemento.

Tematización: tokens de diseño​

Los tokens de diseño definen las diferentes opciones de personalización y cómo se aplican a los diferentes componentes. Si bien los valores de los tokens de diseño pueden evolucionar, hay 2 partes que permanecerán estables y compatibles con versiones anteriores en la biblioteca de componentes de React:

  1. Nombres de tokens de diseño.
  2. Cómo se aplican los tokens de diseño a cada componente.
Note: Los tokens al nivel del componente representan la forma en que se aplican los tokens de diseño a los componentes. Definen las opciones de personalización que admite cada componente. Es posible introducir nuevas opciones de personalización, pero las existentes deben seguir existiendo.

Consulte la documentación sobre tokens de diseño para obtener más información.

Claves de traducción​

Las bibliotecas de JDP, incluidos los componentes de Jutro Design System, proporcionan mensajes predeterminados, por ejemplo, el mensaje que se mostrará cuando no haya ninguna opción disponible en un Combobox. Estos se definen para permitir su internacionalización y proporcionan algunos valores predeterminados.

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

Las claves de mensaje (id) son parte del contrato.

Compatibilidad con las principales dependencias de terceros​

Se mantendría la compatibilidad con las versiones de Node.js, React o Webpack, pero podría agregarse compatibilidad con nuevas versiones.

Note: Se deben tener en cuenta los proveedores definidos como EoL o EoS, especialmente desde el punto de vista de la seguridad.

Además, es posible que las nuevas características de JDP requieran que los clientes actualicen sus versiones a otras más recientes de dependencias para funcionar.

Configuración: archivos, nombres de variables, valores y tipos predeterminados​

Las variables de configuración existentes, los valores aceptados y sus valores predeterminados deben continuar existiendo sin modificaciones. Es posible ampliar las opciones disponibles o introducir nuevas alternativas.

Ejemplo: se proporciona JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT; acepta true/false y false es el valor predeterminado.

Compatibilidad de anidamiento de microfrontends​

El componente MicroFrontend y el Microfrontend SDK definen una API clara y contienen una capa de encapsulado que facilita la incrustación de microfrontends independientes de la versión de menor importancia de las bibliotecas de JDP que utilizan las aplicaciones de shell y microfrontend.

Consulte la documentación sobre microfrontends, incluida la referencia de la API, para obtener más información.

Comandos de la CLI: disponibilidad, firma y propósito​

La lista de comandos disponibles en las CLI proporcionadas forman parte del contrato, así como sus diferentes opciones de configuración.

Warning: Los resultados de la ejecución de los comandos de la CLI pueden modificarse para adaptarlos a las últimas versiones, prácticas y necesidades de funciones.

Configuración de las herramientas de desarrollador proporcionadas​

Los scripts utilizados para compilar la aplicación, las opciones para hacer linting y otras funcionalidades relacionadas seguirán siendo compatibles con versiones anteriores.

Warning: Aunque los scripts y las configuraciones seguirán existiendo, es posible que tengamos que cambiarlos o adaptarlos en función de la evolución del producto y de las necesidades de los clientes, lo que podría dar lugar a una salida diferente de estos scripts.

Aspectos que no forman parte de la API​

La siguiente lista de aspectos no forma parte del contrato de JDP, ni siquiera cuando están expuestos y disponibles:

  • Cualquier exportación desde debajo de las rutas internal o cualquier punto de entrada no enumerado en la página Descripción general de paquetes.
  • Cualquier exportación desde rutas experimental-*.
  • Marcado HTML del componente.
  • Nombres de clase CSS.
  • Variables CSS.
  • Combinaciones CSS.
  • Patrones y ejemplos de diseño, que por lo general están redactados en la documentación.
  • Mensajes de desarrolladores y de herramientas de compilación, como texto de error y advertencias.
  • Errores de tiempo de ejecución: lanzamiento de errores y códigos de error asociados (los mensajes específicos y las propiedades adicionales no forman parte de la API).
  • Plantillas.

SDK de Digital​

Consulte la documentación sobre el contrato de la API del SDK de Digital .

SDK de Digital en Jutro​

Cuando se genera el SDK de Digital mediante la CLI de la plataforma Jutro, se aplican los mismos contratos que se definen en la documentación del SDK de Digital .

Sin embargo, existen algunas funciones específicas de Jutro para la inicialización y la configuración que también forman parte del contrato de JDP.

Extensiones de la interfaz de usuario del SDK de Digital​

Las extensiones de la interfaz de usuario del SDK de Digital son un conjunto de abstracciones generadas que amplían el SDK de Digital para que funcione de manera más eficaz en aplicaciones basadas en React. Estas extensiones tienen sus propios contratos definidos en el contrato de la API de extensiones de la interfaz de usuario del SDK de Digital.

Infraestructura de Jutro Digital Platform​

La infraestructura de Jutro Digital Platform se proporciona como servicio. Sin embargo, con el objetivo de reducir las interrupciones para los clientes, los siguientes aspectos se han considerado parte de su contrato:

Formato de URL de implementación generada automáticamente​

El formato de las URL de implementación generadas automáticamente que se utiliza cuando las implementaciones se crean sin usar dominios personalizados.