Personalización

El comportamiento del proveedor de estilos se puede personalizar pasando parámetros a la función useStyleProvider. Además, puedes sobrescribir las variables globales del tema predeterminado o crear tu propio tema.

Parámetros de useStyleProvider

La función useStyleProvider acepta los siguientes parámetros:

• emulate: crea una emulación del proveedor de estilos en el navegador (no es necesario pasarla al servidor, la emulación se creará automáticamente).
• noscript: tras convertir la emulación del proveedor de estilos a una cadena, elimina el script, dejando solo los estilos CSS iniciales (útil para SSG).
• global (^4.2.0): guarda y utiliza el proveedor de estilos como objeto global.
• attrs - Atributos del proveedor de estilos:
  • pre - prefijo para los nombres de las hojas de estilo,
  • mode - modo para generar selectores con ámbito (a - atributos de datos, c - clases),
  • min - modo para generar selectores con ámbito minimizados (atributo booleano),
  • scheme (^4.14.0) - establece la propiedad de esquema de color para el documento HTML (light o dark),
  • size - sobrescribe la variable CSS global para el tamaño base,
  • space (^4.13.0) - sobrescribe la variable CSS global para el espaciado base,
  • radius (^4.14.0) - sobrescribe la variable CSS global para el radio base,
  • time - sobrescribe la variable CSS global para el tiempo base,
  • angle - sobrescribe la variable CSS global para el ángulo base,
  • color (^4.3.0) - sobrescribe la variable CSS global para el color base,
  • easing (^4.4.0): anula la variable CSS global para la función de suavizado base.
  • contrast (^4.8.0): anula la variable CSS global para el color de contraste.
  • sans (^4.14.0): anula la variable CSS global para la familia de fuentes sans-serif.
  • serif (^4.14.0): anula la variable CSS global para la familia de fuentes serif.
  • mono (^4.14.0): anula la variable CSS global para la familia de fuentes monoespaciada.

Temas

El tema EffCSS es un conjunto de variables CSS globales.

Los temas se crean, actualizan y eliminan mediante el objeto controlador de temas, disponible en la propiedad theme del objeto Style provider:

import { useStyleProvider } from 'effcss';

const provider = useStyleProvider();
const themeVars = {
    size: 18,
    time: 150,
    angle: 15,
    color: 'green',
    sz: {
        s: 10,
        m: 20,
        l: 30
    },
    coef: {
        1: 0.05,
        32: 220,
        15: 1.9
    },
    hue: {
        sec: 220,
    },
    $light: {
        lightness: {
            bg: {
                s: 0.785
            }
        },
        chroma: {
            fg: {
                rich: 0.145
            }
        }
    }
};
// you can override the default theme variables
provider.theme.update(themeVars);
// you can add a new theme
provider.theme.add(themeVars, 'custom');
// you can enable a new theme
provider.theme.switch('custom');

Tenga en cuenta las claves especiales de nivel superior $light y $dark, que establecen el contexto de las variables para los esquemas de color claro y oscuro, respectivamente.

Para acceder a las variables globales de tamaño, espacio, tiempo y ángulo, puede usar las utilidades theme.size, theme.space, theme.time y theme.angle, respectivamente. Para acceder a las variables globales de color primario, neutro y de contraste, use las utilidades theme.color, theme.neutral y theme.contrast, respectivamente. Estas variables admiten la configuración de múltiples valores y el acceso a dichos valores mediante su índice.

// through the setter
styleProvider.size = [16, 18, 24];

// or via an attribute
<script is="effcss-provider" size="16;18;24;"></script>

// inside the maker, values are available by index
export const maker: TStyleSheetMaker = ({ theme: {size} }) => {
    return {
        '.sz-s': {
            width: size
        },
        '.sz-m': {
            width: size[2]
        },
        '.sz-l': {
            width: size[3]
        },
        '.sz-2xl': {
            // you can set your own multiplier
            width: size[3](2)
        }
    };
};

Los coeficientes numéricos y sus rangos están disponibles mediante la utilidad coef.

Los objetos hue, lightness y chroma se utilizan en la utilidad palette.

Para usar variables de tema arbitrarias en las funciones de StyleSheet maker, utilice la utilidad theme.variable:

import { TStyleSheetMaker } from 'effcss';

type TGlobalVars = {
    sz: {
        s: string;
        m: string;
        l: string;
    }
};

export const maker: TStyleSheetMaker = ({ theme: {variable} }) => {
    return {
        '.sz-m': {
            width: variable<TGlobalVars>('sz.m', '100px') // '100px' - fallback value
        }
    };
};

Matrices de valores (v4.12.0)

Si el parámetro del tema tiene un valor en forma de matriz, para cada elemento de la matriz, excepto el primero, se creará una variable CSS con un sufijo igual al índice de dicho valor. El primer elemento de la matriz tiene índice cero, por lo que se ignorará.

const themeVars = {
    custom: ['12px', '24px', '36px']
    // --f0-custom: 12px; --f0-custom-1: 24px; --f0-custom-2: 36px;
};

Para acceder a dichas variables CSS, puede utilizar la utilidad theme.variable:

export const maker: TStyleSheetMaker = ({ theme: {variable} }) => {
    return {
        '.sz-m': {
            width: variable<TGlobalVars>('custom.1', '100px')
        }
    };
};

Multitemas

Para usar un tema distinto al global en un elemento HTML específico, llama a la función use sin argumentos y pasa el modificador con el tema deseado al resolvedor resultante:

import type { TBaseStyleSheetMaker } from 'effcss';
import { useStyleProvider } from 'effcss';

const consumer = useStyleProvider();
const [resolver] = consumer.use();
const attrs = resolver<TBaseStyleSheetMaker>('..theme.custom');

Sobrescribir variables globales (^4.5.0)

En lugar de definir varios temas, puede establecer y redefinir variables globales para partes individuales del diseño utilizando el componente web effcss-override. Para ello, pase al atributo values una cadena preparada con la utilidad prepareOverrideValues:

import { prepareOverrideValues } from 'effcss';

const overridedValues = prepareOverrideValues({
    size: 32,
    hue: {
        pri: 10
    },
    $light: {
        lightness: {
            bg: {
                xl: 0.95
            }
        }
    }
});

export const Component = () => <effcss-override neutral="grey" color="purple" values={overridedValues}>
    <div>...</div>
<effcss-override>`

A partir de la versión ^4.8.0, también puede sobrescribir variables globales utilizando los mismos atributos que Style provider (por ejemplo, size, angle, color). Estos atributos tienen prioridad sobre el valor en values. A partir de la versión ^4.12.0, puede especificar varios valores separados por ;:

<effcss-override size="16;18;24;" color="purple;white;#2192a7"></effcss-override>

A partir de la versión ^4.9.0, puedes modificar la paleta de colores de un componente y su contenido mediante el atributo scheme. Este atributo puede tomar los valores light o dark.

El componente effcss-override tiene el estilo display:contents; por defecto, para evitar cambios en el diseño.

Ajuste de hojas de estilo (^4.13.0)

El ajuste es otra forma de flexibilizar las hojas de estilo. Permite definir variables de ajuste específicas para aplicaciones externas.

Puedes declarar variables de ajuste con su propio tipo de contrato e implementarlas mediante la utilidad theme.tuning:

type TMaker = {
    sz: 's' | 'm';
    rounded: '';
    card: {
        bg: 'pri' | 'sec';
        inv: '';
        footer: Record<string, never>;
    }
};

type TMakerTunings = {
    size: number;
    card: {
        color: string;
    }
};

const DEF_TUNING_VAL = 'rgb(82, 119, 119)';

const maker: TStyleSheetMaker = ({ select, theme: { tuning } }) => {
    const selector = select<TMaker>;
    const tuningVar = tuning<TMakerTunings>
    return {
        [selector('sz:s')]: {
            width: '10px'
        },
        [selector('card')]: {
            boxSizing: 'border-box'
        },
        // ...
        div: {
            background: tuningVar('card.color', DEF_TUNING_VAL)
        }
    };
};

Luego, en las aplicaciones, su hoja de estilos se puede ajustar mediante el método tune del Proveedor de estilos:

styleProvider.dx<TMaker>(maker, []);
const vars = styleProvider.tune<TMakerTunings>({
    card: {
        color: 'oklch(0.85 0.02 196.66)'
    }
}, maker);

const jsx = <div style={vars}>Welcome to the tuned area</div>;

INFO

El proveedor de estilos solo ajusta las hojas de estilo que ya hayas creado, así que asegúrate de definirlas mediante el método dx, cx o use.