Escotillas de escape
Descripción general
Las especificaciones de UX de Jutro Design System se basan en los casos de uso de UX identificados y describen los problemas y requisitos, junto con los enfoques y pautas recomendados para abordarlos. Los diferentes componentes de Jutro se crean con el objetivo de que se ajusten a estas especificaciones de UX, y todas las propiedades y características proporcionadas se basan en ellas.
Aunque el objetivo principal de los componentes es la unificación de UX, presentan algunas alternativas para personalizarlos que permiten a los desarrolladores ir un paso más allá del comportamiento predeterminado, y aquí es donde se introducen las escotillas de escape.
¿Qué es una escotilla de escape?
“Escotilla de escape” es un término adoptado en el desarrollo de software que se refiere a alternativas intencionales (espacio donde se produce una fuga) en el modelo que permiten a los usuarios “escaparse” y acceder a una capa de abstracción inferior. Incluso podría considerarse una puerta abierta para “hackear” el contrato de abstracción específico.
Un ejemplo relevante para los desarrolladores de Jutro serían las escotillas de escape de React.
Escotillas de escape de Jutro Design System
Tenga en cuenta los posibles efectos no deseados de cualquier escotilla de escape utilizada. Si bien proporcionan un mecanismo para ampliar un comportamiento o reducir las brechas con respecto a los requisitos, según el uso que se les dé pueden tener efectos inesperados. Algunos posibles efectos podrían ser características que no funcionan, problemas de accesibilidad y complicaciones futuras para la actualización.
Cada componente de Jutro puede proporcionar diferentes escotillas de escape, según el caso de uso y el tipo de componente. En algunos casos, se proporcionan como parte de la API estable del componente, pero se incluyen como escotillas de escape, ya que brindan opciones que permiten una flexibilidad adicional además de ajustarse a las especificaciones de UX.
A continuación, encontrará descripciones de algunas de las escotillas de escape más comunes proporcionadas por los componentes de Jutro. Si desea conocer las escotillas de escape de un componente en particular, consulte la documentación de dicho componente.
Tokens de diseño
Aunque son parte de la API de los componentes de Jutro, los tokens de diseño podrían considerarse una escotilla de escape, ya que permiten la personalización de la decisión de UX en lo que respecta al tema.
Consulte la sección Tokens de diseño para obtener más información.
Propiedades dangerouslySet
Algunos componentes incluyen una o más propiedades dangerouslySet.... Estas permiten al desarrollador invalidar por completo todo un elemento o aspecto del componente. En la mayoría de los casos, esta opción se proporcionará cuando las especificaciones de UX identifiquen un caso extremo, incluidas algunas alternativas desconocidas.
La propiedad dangerouslySet se escribirá como un ReactNode y, normalmente, habrá un gancho relacionado para proporcionar acceso al contexto del componente.
Ejemplo: El encabezado de AccordionCard por lo general tendrá solo un texto (propiedad title), pero se sabe que otros elementos también son necesarios, como íconos, etiquetas o incluso botones en algunos casos específicos; por eso, se proporcionará una propiedad dangerouslySetHeader.
function MyCustomHeader() {
const { disabled } = useComponentState(); // provided hook for context information
return <span>{disabled ? 'I am disabled' : 'I am not disabled'}</span>;
}
<AccordionCard title="some title" dangerouslySetHeader={{<MyCustomHeader />}}/>
Propiedad children
Aunque, en general, la propiedad de cada componente se escribirá para restringir los valores y las opciones proporcionados, en algunos casos puede dejarse completamente abierta (a través de children: ReactNode). La situación más común para este caso son aquellos componentes que están destinados principalmente a utilizarse como contenedores para otros tipos de contenidos (por ejemplo, modales).
Propiedad className
Por lo general, los componentes de Jutro se renderizarán con un atributo de clase HTML preestablecido. Algunos componentes pueden proporcionar una propiedad className que agregará una clase al elemento de nivel superior del componente. Por ejemplo, <DatePicker className="foo"> tendrá un elemento principal con una clase que se parecerá a <div class="foo fieldContainer_TIDj">.
Selectores que utilizan la estructura HTML subyacente
Si desea dar formato a elementos HTML específicos de un componente renderizado, inspeccione la estructura HTML subyacente que se genera y use los selectores CSS que los seleccionan. Por ejemplo, para el texto en negrita de cualquier elemento HTML de labelrenderizado por <DatePicker className="foo">, podría usar algo como esto:
.foo label {
font-weight: bold;
}
La estructura HTML subyacente de un componente no forma parte de la API del componente, por eso, puede estar sujeta a modificaciones sin que se consideren un cambio importante. Si bien el elemento de nivel superior del componente permanecería estable, el resto de la estructura interna puede modificarse.
Selectores que utilizan atributos de clase preestablecidos
También puede usar el atributo de clase preestablecido, en lugar de un className proporcionado. Por ejemplo, sin una propiedad className, su DatePicker se parecerá a <div class="fieldContainer_TIDj">. El elemento de rótulo de esto se puede seleccionar usando ese atributo de clase preestablecido con algo similar a esto:
.fieldContainer_TIDj label {
font-weight: bold;
}
La mayoría de los elementos internos también tendrán atributos de clase HTML preestablecidos. También puede usarlos para hacer selectores de CSS. Por ejemplo, si el elemento de rótulo renderizado es similar a esto:
<label class="labelContainer_wEwV"><span>Choose date</span></label>
A continuación, puede usar algo así para seleccionarlo:
.labelContainer_wEwV {
font-weight: bold;
}
Los atributos de clase HTML preestablecidos no forman parte de la API del componente, incluido el atributo de clase preestablecido del componente de nivel superior; por ello, estos valores podrían estar sujetos a modificaciones sin que se consideren un cambio importante.
Si usa los atributos de clase preestablecidos en cualquier parte del código, pueden variar de una actualización a la otra, lo que debe tenerse en cuenta.
Permitir el paso de atributos HTML predeterminados
Además de la API definida por Jutro, algunos componentes permitirán pasar un conjunto adicional de los atributos HTML nativos que el componente podría tener. Estos atributos adicionales se pasarán directamente al elemento de nivel superior o al elemento en particular especificado en la documentación del componente.
Un ejemplo de este caso de uso es que algunos de los componentes de “entrada” de Jutro podrían permitir pasar los atributos HTML estándares que un elemento input HTML nativo aceptaría: por ejemplo, id o name. La lista de atributos podría restringirse para evitar que dichos atributos interfieran con las propiedades y el comportamiento del componente. Por ejemplo, si el componente ya maneja la longitud máxima aceptada de su contenido, es posible que no se acepte el atributo native maxLength.
Al igual que en otros casos, deben tenerse en cuenta los efectos no deseados de los atributos al utilizarlos.
useId desde @jutro/platform para que la identificación sea única. Consulte la página Ganchos para obtener más información sobre el gancho useId.Propiedad ref y controladores imperativos
ref es una escotilla de escape que proporciona acceso a nodos DOM o a componentes de React para permitir a los desarrolladores modificar elementos fuera del flujo de renderización. En el caso de Jutro, esta opción podría considerarse en algunos componentes específicos, pero en general se implementará siguiendo el método del controlador imperativo: en lugar de solo proporcionar acceso a todo el elemento, se expondrán métodos o propiedades específicos en función de los casos de uso conocidos. Estos pueden evolucionar y aumentar en futuras versiones de la biblioteca.
Un ejemplo de esta opción sería la creación de una propiedad ref que solo proporcione acceso a funciones específicas, como establecer el foco en un campo o desplazarse hasta un elemento específico.
Propiedad de evento nativa
Los componentes de entrada de Jutro expondrán algunos eventos como onChange. Estos eventos normalmente incluirán, además de cualquier otro valor personalizado, el objeto nativo event que desencadenó el evento.
Se espera que, normalmente, los valores personalizados que se pasan al evento proporcionen suficiente información para el desarrollador, pero este event permitirá un mayor control sobre algunas funciones “básicas” como preventDefault.
Por ejemplo, un evento onChange se definiría como (event: React.ChangeEvent<HTMLInputElement>, newValue: T) => void, por eso, el desarrollador solo puede utilizar newValue para realizar validaciones o acciones basadas en la entrada del usuario, pero el evento nativo también está disponible para cualquier función adicional.