@groupteknology/vuno 1.0.0 → 2.0.0

package/dist/runtime/app/types/table.d.ts

@@ -0,0 +1,287 @@
+import type { VunoColor, VunoSize } from './base.js';
+import type { VunoField } from './field.js';
+import type { VunoUi } from './slots.js';
+type WithType<TColumn, TType extends string> = TColumn & {
+    type: TType;
+};
+/**
+ * `Omit` que recorre la unión miembro a miembro.
+ *
+ * El `Omit` de TypeScript aplana la unión en un solo objeto con las claves
+ * comunes, y con ella se lleva por delante el discriminante: el resultado ya no
+ * distingue un `badge` de un `date`.
+ */
+type OmitEach<TUnion, TKey extends PropertyKey> = TUnion extends unknown ? Omit<TUnion, TKey> : never;
+export type VunoTableSortDirection = 'asc' | 'desc';
+export type VunoTableSort = {
+    column: string;
+    direction: VunoTableSortDirection;
+};
+/**
+ * Estado de consulta de la tabla. Es el `v-model:query` y la única fuente de
+ * verdad: en modo servidor el consumidor observa este objeto, pide su página
+ * y devuelve `data` y `total`.
+ */
+export type VunoTableFilters = Record<string, unknown>;
+export type VunoTableQuery = {
+    /** Valores del panel de filtros, indexados por el `name` de cada campo. */
+    filters: VunoTableFilters;
+    page: number;
+    pageSize: number;
+    search: string;
+    sort: null | VunoTableSort;
+};
+/**
+ * Fallo de la consulta, con el reintento DENTRO. Es un objeto y no dos props
+ * sueltas a propósito: así no se puede pintar un error sin ofrecer salida.
+ *
+ * Existe porque sin él una consulta fallida se normaliza a lista vacía
+ * (`data ?? []`) y la tabla dice «No hay resultados»: afirma que no hay nada
+ * cuando lo que pasa es que no se pudo saber.
+ */
+export type VunoTableFailure = {
+    hint?: string;
+    title?: string;
+    retry: () => void;
+};
+/** Qué mostrar cuando la consulta va bien y no hay ninguna fila. */
+export type VunoTableEmpty = {
+    hint?: string;
+    icon?: string;
+    title?: string;
+};
+export type VunoTableAlign = 'center' | 'end' | 'start';
+/**
+ * Una fila. `object` y no `Record<string, unknown>` a propósito: un `interface`
+ * de TypeScript no tiene firma de índice implícita, así que no satisface un
+ * `Record`, y los tipos de respuesta de una API se declaran como `interface`
+ * casi siempre. Con el `Record`, cada consumidor tenía que escribir
+ * `type Fila = SuInterface & Record<string, unknown>` para poder usar la tabla,
+ * y el error que salía —«no assignable to VunoTableRow»— no señalaba la causa.
+ *
+ * La firma de índice no hacía falta para nada: los valores se leen con
+ * `getPath`, que recorre el objeto en tiempo de ejecución y acepta `unknown`.
+ */
+export type VunoTableRow = object;
+/**
+ * Nota: no hay `searchable` por columna. La búsqueda la resuelve el endpoint,
+ * que es quien sabe sobre qué campos puede buscar; declararlo aquí sugeriría
+ * que la tabla filtra, y no lo hace.
+ */
+export type VunoTableColumnBase<TRow extends VunoTableRow = VunoTableRow> = {
+    align?: VunoTableAlign;
+    class?: string;
+    /**
+     * Ruta del valor en la fila. Admite anidado: `'proveedor.nombre'`.
+     *
+     * Sigue haciendo falta con `value`: nombra la columna para el orden y para
+     * el slot `cell-<key>`.
+     */
+    key: string;
+    label?: string;
+    sortable?: boolean;
+    ui?: VunoUi<'avatar' | 'badge' | 'cellBoolean' | 'cellCurrency' | 'cellDate' | 'cellNumber' | 'cellText' | 'menu'>;
+    width?: string;
+    /**
+     * Calcula el valor a partir de la fila entera, en lugar de leerlo de `key`.
+     *
+     * ```ts
+     * { key: 'role', type: 'badge', value: (row) => traducirRol(row.role) }
+     * ```
+     *
+     * Sustituye de dónde sale el valor, no cómo se pinta: lo que devuelve sigue
+     * pasando por el formato de su tipo de columna —moneda, fecha, el `map` de
+     * un badge—, así que se combinan.
+     *
+     * Cuidado al ordenar: `sortable` ordena en servidor por `key`, y el servidor
+     * no conoce esta función. Si el valor mostrado no se deriva de `key` de
+     * forma monótona, el orden no coincidirá con lo que se ve.
+     */
+    value?: (row: TRow) => unknown;
+};
+export type VunoTableColumnText<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow> & {
+    truncate?: boolean;
+};
+export type VunoTableColumnNumber<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow> & {
+    decimals?: number;
+};
+export type VunoTableColumnCurrency<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow> & {
+    currency?: string;
+    decimals?: number;
+};
+export type VunoTableColumnDate<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow> & {
+    dateStyle?: 'full' | 'long' | 'medium' | 'short';
+    timeStyle?: 'full' | 'long' | 'medium' | 'short';
+};
+export type VunoTableColumnBoolean<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow> & {
+    falseLabel?: string;
+    trueLabel?: string;
+};
+/** Traduce el valor crudo a una etiqueta con color, p. ej. estados. */
+export type VunoTableBadgeMap = Record<string, {
+    color?: VunoColor;
+    label?: string;
+}>;
+export type VunoTableColumnBadge<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow> & {
+    color?: VunoColor;
+    map?: VunoTableBadgeMap;
+};
+export type VunoTableColumnImage<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow> & {
+    alt?: string;
+    /** Clave de la fila de la que sacar el texto alternativo. */
+    altKey?: string;
+    size?: Exclude<VunoSize, 'xl'>;
+};
+/** Delega el contenido en el slot `cell-<key>`. */
+export type VunoTableColumnCustom<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow>;
+export type VunoTableAction<TRow extends VunoTableRow = VunoTableRow> = {
+    onSelect: (row: TRow) => void;
+    color?: VunoColor;
+    icon?: string;
+    label: string;
+    /** Dibuja un separador encima de la acción. */
+    separator?: boolean;
+    disabled?: (row: TRow) => boolean;
+    /** Oculta la acción para esa fila concreta. */
+    hidden?: (row: TRow) => boolean;
+};
+export type VunoTableColumnActions<TRow extends VunoTableRow = VunoTableRow> = VunoTableColumnBase<TRow> & {
+    actions: VunoTableAction<TRow>[];
+};
+/** Unión discriminada por `type`, igual que `VunoField` en los formularios. */
+export type VunoTableColumn<TRow extends VunoTableRow = VunoTableRow> = WithType<VunoTableColumnActions<TRow>, 'actions'> | WithType<VunoTableColumnBadge<TRow>, 'badge'> | WithType<VunoTableColumnBoolean<TRow>, 'boolean'> | WithType<VunoTableColumnCurrency<TRow>, 'currency'> | WithType<VunoTableColumnCustom<TRow>, 'custom'> | WithType<VunoTableColumnDate<TRow>, 'date'> | WithType<VunoTableColumnImage<TRow>, 'image'> | WithType<VunoTableColumnNumber<TRow>, 'number'> | WithType<VunoTableColumnText<TRow>, 'text'>;
+export type VunoTableColumnType = VunoTableColumn['type'];
+/** Extrae los props de un tipo concreto de columna: `VunoTableColumnOf<'badge'>`. */
+export type VunoTableColumnOf<TType extends VunoTableColumnType> = Extract<VunoTableColumn, {
+    type: TType;
+}>;
+/**
+ * Tipos que pinta una celda.
+ *
+ * `actions` y `custom` quedan fuera porque no los resuelve la celda: el menú de
+ * acciones y el slot propio los pinta la tabla, que es quien tiene los eventos.
+ */
+export type VunoTableCellType = Exclude<VunoTableColumnType, 'actions' | 'custom'>;
+/**
+ * La columna tal y como la ve una celda: la misma, sin `value`.
+ *
+ * `value` es lo único de una columna que depende del tipo de la fila, y la
+ * celda no lo usa: el valor le llega ya resuelto. Dejarlo fuera es lo que
+ * permite que una celda pinte la columna de cualquier tabla. Con él dentro, una
+ * `VunoTableColumn<TuFila>` no vale donde se espera una `VunoTableColumn`,
+ * porque una función que sabe leer tu fila no sabe leer un objeto cualquiera, y
+ * esa es una diferencia real y no un capricho del compilador.
+ */
+export type VunoTableCellColumn<TType extends VunoTableCellType = VunoTableCellType> = OmitEach<VunoTableColumnOf<TType>, 'value'>;
+/** Props comunes a toda celda. El valor llega resuelto para no repetir `getPath`. */
+export type VunoTableCellProps<TType extends VunoTableCellType = VunoTableCellType> = {
+    column: VunoTableCellColumn<TType>;
+    row: VunoTableRow;
+    value: unknown;
+};
+export type VunoTableDefinition<TRow extends VunoTableRow = VunoTableRow> = {
+    columns: VunoTableColumn<TRow>[];
+    /** Texto e icono cuando no hay ninguna fila. */
+    empty?: VunoTableEmpty;
+    /**
+     * Campos del panel lateral de filtros. Son los mismos de un formulario, así
+     * que un filtro se declara igual que se declara un campo.
+     */
+    filters?: VunoField[];
+    /** Tamaños ofrecidos en el selector de filas por página. */
+    pageSizes?: number[];
+    /**
+     * Si el endpoint pagina. Por defecto `true`.
+     *
+     * En `false` desaparecen el paginador y el selector de tamaño, y el pie
+     * pasa a decir cuántos resultados hay y nada más.
+     */
+    paginated?: boolean;
+    /** Campo que identifica la fila; se usa como clave de selección. */
+    rowKey?: string;
+    /**
+     * Con qué se **nombra** una fila para quien no ve la pantalla.
+     *
+     * No lo confundas con `rowKey`, que identifica para la selección y puede ser
+     * un número opaco: esto es lo que se lee en voz alta. Va dentro del nombre
+     * accesible de la casilla y del menú de acciones de cada fila —«Elegir
+     * Cafetera italiana», «Acciones de Cafetera italiana»—, que sin él se
+     * llamaban las veinte igual.
+     *
+     * **Sin declararlo se adivina**, y se adivina bien en el caso corriente: la
+     * primera columna de texto, que es la misma pista que usa quien mira la
+     * pantalla. Se declara cuando adivinar no vale — una tabla cuya primera
+     * columna de texto es un estado que se repite («Activo», «Activo»,
+     * «Activo»), o una donde lo que identifica la fila son dos columnas juntas.
+     *
+     * Las dos formas dicen cosas distintas:
+     *
+     * - Una **cadena es una ruta dentro de la fila**, igual que `rowKey` y que
+     *   la `key` de una columna: `'name'`, `'client.name'`. No es un rótulo
+     *   literal — un literal nombraría todas las filas igual, que es justo el
+     *   defecto que esto viene a quitar.
+     * - Una **función** es la salida para lo que no cabe en una ruta: juntar dos
+     *   campos, recortar, o componer un nombre que no está guardado.
+     *
+     * Lo que devuelva vacío cae al número de fila —«fila 3»— y **no** a la
+     * heurística: declarar es decir cuál es la fuente, y volver a adivinar por
+     * detrás dejaría unas filas nombradas por la columna declarada y otras por
+     * otra, sin que nada lo dijera.
+     */
+    rowLabel?: ((row: TRow) => string) | string;
+    /**
+     * Si el endpoint busca. Por defecto `true`.
+     *
+     * En `false` no se pinta la barra de búsqueda. No es cosmética: una barra
+     * que no filtra es una promesa que la pantalla no puede cumplir, y como
+     * funciona visualmente nadie la reporta como defecto.
+     *
+     * Es del endpoint y no de cada columna: quien decide sobre qué campos se
+     * busca es el servidor, no la tabla.
+     */
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    selectable?: boolean;
+};
+export type VunoTableQueryOptions = {
+    /**
+     * Nombres de los filtros que viajan en la URL. Hace falta declararlos
+     * porque al arrancar sin valores no habría forma de saber cuáles leer.
+     */
+    filterKeys?: string[];
+    filters?: VunoTableFilters;
+    /**
+     * Cómo se escribe en el historial del navegador.
+     *
+     * - `replace` (por defecto): no deja rastro. Recargar y compartir el
+     *   enlace funcionan, pero el botón atrás sale de la página en vez de
+     *   deshacer el último filtro.
+     * - `push`: cada cambio es una entrada, así que atrás deshace filtro a
+     *   filtro. A cambio, teclear en el buscador llena el historial —el
+     *   antirrebote de la tabla lo suaviza, pero no lo evita.
+     */
+    history?: 'push' | 'replace';
+    page?: number;
+    pageSize?: number;
+    /** Prefijo de los parámetros, para tener varias tablas en la misma página. */
+    prefix?: string;
+    search?: string;
+    /**
+     * Orden inicial de la tabla. Admite la forma corta `'sku'` (ascendente).
+     *
+     * Declararlo cambia el ciclo de la cabecera: en vez de asc → desc → sin
+     * orden, el tercer clic devuelve a este orden.
+     *
+     * Va aquí y no en la definición porque el primer `fetch` —el del servidor
+     * incluido— tiene que salir ya ordenado; aplicarlo al montar la tabla
+     * provocaría una segunda petición y un parpadeo.
+     */
+    sort?: null | string | VunoTableSort;
+    /**
+     * Guarda el estado en la query string: el enlace es compartible y recargar
+     * conserva los filtros. Si además quieres que el botón atrás los deshaga,
+     * usa `history: 'push'`.
+     */
+    url?: boolean;
+};
+export {};

package/dist/runtime/app/types/theme.d.ts

@@ -0,0 +1,251 @@
+import type { VunoSlots } from './base.js';
+import type { VunoFieldInputType, VunoFieldType } from './field-type.js';
+/**
+ * Claves tematizables, y **cada una se llama como su componente sin la `V`**:
+ * `VCard` se personaliza con `card`, `VNumberInput` con `numberInput`.
+ *
+ * No siempre fue así y por eso está escrito aquí: llegaron a convivir un
+ * prefijo `base` en veinte claves y un `app` en tres, que no describían el
+ * componente sino la carpeta donde estaba archivado, de modo que **solo 7 de
+ * los 30 componentes públicos tenían una clave adivinable**. Para personalizar
+ * había que consultar una tabla.
+ *
+ * Queda **una** excepción: `control` no es un componente sino la caja que
+ * comparten el campo de texto, el área y el combobox, para que los tres bordes
+ * no diverjan.
+ *
+ * Eran dos. La otra era `state`, compartida por `VEmptyState` y
+ * `VFailureState`, y se resolvió por donde había que resolverla: los dos eran
+ * el mismo bloque con una variante `tone`, así que ahora son un componente,
+ * `VState`, y la clave vuelve a llamarse como él. Una clave compartida por dos
+ * componentes era la señal de que sobraba uno.
+ *
+ * Y una advertencia sobre este mismo párrafo: **decía que
+ * `types-contract.test.ts` comprueba la regla y nombra las excepciones una a
+ * una, y no es verdad.** Ese test vigila otra cosa —que los tipos públicos
+ * vivan en `types/` y salgan por su índice—, y la regla de nombres no la
+ * comprueba nadie. Se escribió la frase con la intención puesta y nadie volvió
+ * a mirar; queda dicho aquí para que quien añada una excepción sepa que no hay
+ * red debajo.
+ */
+export type VunoThemeKey = 'alert' | 'avatar' | 'badge' | 'button' | 'card' | 'cellBoolean' | 'cellCurrency' | 'cellDate' | 'cellNumber' | 'cellText' | 'checkbox' | 'code' | 'confirm' | 'container' | 'control' | 'controlGroup' | 'fieldInput' | 'fileUpload' | 'form' | 'formField' | 'formModal' | 'formSection' | 'input' | 'menu' | 'modal' | 'navbar' | 'navigationList' | 'navigationMenu' | 'navigationToc' | 'numberInput' | 'page' | 'pagination' | 'radioGroup' | 'select' | 'slideover' | 'state' | 'switch' | 'table' | 'tabs' | 'tagsInput' | 'textarea' | 'toast' | 'toaster' | 'tooltip' | `field${Capitalize<Exclude<VunoFieldType, VunoFieldInputType>>}`;
+/**
+ * Slots que se aplican cuando una dimensión toma cierto valor: `color: 'error'`
+ * o `variant: 'solid'`. Se funden sobre los slots base en el orden en que el
+ * componente los pide.
+ */
+export type VunoThemeVariants = Record<string, Record<string, VunoSlots>>;
+/**
+ * Clases que solo se aplican cuando **coinciden varias variantes a la vez**.
+ *
+ * Las claves que no son `class` son las condiciones, y se cumplen todas o no se
+ * aplica ninguna: `{ color: 'neutral', variant: 'link', class: { base: '…' } }`
+ * solo entra cuando el botón es las dos cosas.
+ *
+ * Existe para lo que la variable de acento no alcanza. El mecanismo de serie
+ * —el color asigna `--vuno-accent` y la variante la consume— cubre el caso
+ * corriente sin escribir combinaciones, y por eso sigue siendo el primero al
+ * que acudir. Lo que no cubre es cuando una pareja concreta necesita algo que
+ * no es un color: un borde que solo esa combinación quiere, un relleno
+ * distinto. Antes de esto, la única salida era declarar la pareja como una
+ * variante más y perder la ortogonalidad.
+ */
+export type VunoThemeCompoundVariant = {
+    class: VunoSlots;
+} & Record<string, string | undefined | VunoSlots>;
+export type VunoThemeEntry = {
+    /**
+     * Las combinaciones, que se aplican **después** de las variantes sueltas de
+     * su mismo nivel. Ese orden es el que las hace útiles: lo específico llega
+     * al final y gana el conflicto que tailwind-merge deshace.
+     */
+    compoundVariants?: VunoThemeCompoundVariant[];
+    slots?: VunoSlots;
+    /**
+     * Evita declarar cada combinación: un botón con siete colores y cuatro
+     * variantes son veintiocho casos escritos a mano si cada uno fija sus
+     * clases. Aquí el color solo asigna las variables de acento
+     * —`--vuno-accent`, `--vuno-accent-contrast`— y la variante las consume
+     * con `bg-(--vuno-accent)`, así que son siete más cuatro y no hay
+     * combinaciones compuestas que mantener.
+     *
+     * Para lo que esa vía no alcanza está `compoundVariants`, que es la
+     * excepción y no el camino: cada entrada suya **sí** es una combinación que
+     * alguien mantiene.
+     */
+    variants?: VunoThemeVariants;
+};
+export type VunoThemeConfig = {
+    [TKey in VunoThemeKey]?: VunoThemeEntry;
+};
+export type VunoIcons = {
+    actions: string;
+    addItem: string;
+    /** Celda booleana sin etiquetas: el «no». */
+    booleanFalse: string;
+    /** Celda booleana sin etiquetas: el «sí». */
+    booleanTrue: string;
+    /** Separador entre segmentos de la ruta de navegación. */
+    breadcrumbSeparator: string;
+    clearSearch: string;
+    close: string;
+    codeCopied: string;
+    codeCopy: string;
+    confirm: string;
+    empty: string;
+    failure: string;
+    fileMoveDown: string;
+    fileMoveUp: string;
+    fileRemove: string;
+    fileUpload: string;
+    filter: string;
+    /** La flecha que despliega una rama de la navegación. */
+    navigationToggle: string;
+    /** Búsqueda o filtros sin coincidencias. */
+    noMatches: string;
+    notifyError: string;
+    notifyInfo: string;
+    notifySuccess: string;
+    notifyWarning: string;
+    numberDecrement: string;
+    numberIncrement: string;
+    /** Controles del paginador: primera, anterior, siguiente y última. */
+    paginationFirst: string;
+    paginationLast: string;
+    paginationNext: string;
+    paginationPrevious: string;
+    passwordHide: string;
+    passwordShow: string;
+    removeItem: string;
+    retry: string;
+    search: string;
+    /** La flecha del desplegable de un `select`. */
+    selectOpen: string;
+    /** La marca de la opción elegida. */
+    selectSelected: string;
+    slugEdit: string;
+    slugReset: string;
+    sort: string;
+    sortAsc: string;
+    sortDesc: string;
+};
+export type VunoMessages = {
+    addItem: string;
+    applyFilters: string;
+    /** Valores accesibles de una celda booleana que se representa visualmente con un icono. */
+    booleanFalse: string;
+    booleanTrue: string;
+    /** Nombre accesible de la ruta de navegación. */
+    breadcrumb: string;
+    cancel: string;
+    clearFilters: string;
+    /** Acción del estado «no hay coincidencias». */
+    clearQuery: string;
+    clearSearch: string;
+    clearSelection: string;
+    close: string;
+    codeCopied: string;
+    codeCopiedAnnouncement: string;
+    codeCopy: string;
+    codeCopyFailed: string;
+    codeRegion: string;
+    /** Distingue el selector del sistema del hexadecimal de al lado, que sin esto se anuncian igual. */
+    colorPicker: string;
+    confirm: string;
+    confirmDescription: string;
+    confirmTitle: string;
+    created: string;
+    deleted: string;
+    deleteFailed: string;
+    /** Título y nombre accesible del índice de una página de documentación. */
+    documentToc: string;
+    emptyArray: string;
+    /** Segunda línea del estado vacío. Vacía por defecto: vuno no sabe qué falta en una lista ajena. */
+    emptyHint: string;
+    emptyTable: string;
+    failureHint: string;
+    failureTitle: string;
+    fileMoveDown: string;
+    fileMoveUp: string;
+    fileRemove: string;
+    filters: string;
+    filtersTitle: string;
+    /**
+     * Nombre accesible de la barra de navegación.
+     *
+     * Lo lleva porque `VNavbar` es un `<nav>` y en la misma pantalla suele haber
+     * otro —la navegación lateral de la aplicación—: dos regiones de navegación
+     * sin nombre se anuncian igual y no se distinguen. Es el mismo defecto que
+     * ya se arregló en el paginador.
+     */
+    navbarLabel: string;
+    /** Lista vacía porque la búsqueda o los filtros no casan con nada. */
+    noMatches: string;
+    noMatchesHint: string;
+    /** Botones del campo numérico. */
+    numberDecrement: string;
+    numberIncrement: string;
+    of: string;
+    /** Compone el nombre de cada número: «Página 3». */
+    page: string;
+    /** Nombre accesible del selector de filas por página. */
+    pageSize: string;
+    paginationFirst: string;
+    /** Nombre accesible de la región del paginador, que es un `<nav>`. */
+    paginationLabel: string;
+    paginationLast: string;
+    paginationNext: string;
+    paginationPrevious: string;
+    passwordHide: string;
+    passwordShow: string;
+    removeItem: string;
+    /** Pie de una tabla que no pagina: «30 resultados». */
+    results: string;
+    retry: string;
+    /**
+     * Con qué se nombra una fila que no tiene nada que la nombre: «fila 3».
+     *
+     * Se usa como respaldo del nombre accesible de la casilla y del menú, donde
+     * la alternativa era que las veinte filas se llamaran igual.
+     */
+    row: string;
+    /** Acciones de una fila. Lleva detrás el nombre de la fila. */
+    rowActions: string;
+    rowSelected: string;
+    rowsSelected: string;
+    save: string;
+    saveFailed: string;
+    searchPlaceholder: string;
+    /** Nombres accesibles de las casillas de la tabla. */
+    selectAll: string;
+    selectPlaceholder: string;
+    /**
+     * Elegir **una** fila. Lleva detrás el nombre de la fila, como el botón de
+     * quitar un archivo lleva el del archivo: sin eso, las veinte casillas de
+     * una página se anuncian con el mismo nombre y no hay forma de saber cuál
+     * es cuál sin ver la pantalla.
+     */
+    selectRow: string;
+    /** Nombre accesible del disparador del `select`. */
+    selectToggle: string;
+    showing: string;
+    /** Enlace que salta las filas y deja el foco en el pie de la tabla. */
+    skipTable: string;
+    slugEdit: string;
+    slugReset: string;
+    updated: string;
+};
+/** Forma de `app.config.ts` → `vuno`. */
+export type VunoAppConfig = VunoThemeConfig & {
+    icons?: Partial<VunoIcons>;
+    /**
+     * Con qué idioma se formatean las fechas, los números y las monedas.
+     *
+     * Se declara en vez de leerse del navegador **a propósito**: con render en
+     * servidor, el servidor no tiene navegador del que leerlo, así que un
+     * idioma adivinado da un precio en el HTML y otro al hidratar. Se ve como
+     * un parpadeo del número y se diagnostica fatal.
+     */
+    locale?: string;
+    messages?: Partial<VunoMessages>;
+};

package/dist/runtime/app/utils/format.d.ts

@@ -0,0 +1,18 @@
+export declare function formatSlug(value?: string): string;
+/**
+ * Los formateadores reciben el idioma ya resuelto —el de `useLocale`, que
+ * sale del `app.config` del proyecto— en lugar de fijar uno: qué idioma habla
+ * la aplicación lo decide quien la escribe, no este paquete.
+ */
+export declare function formatNumber(value: unknown, locale?: string, decimals?: number): string;
+export declare function formatCurrency(value: unknown, locale?: string, currency?: string, decimals?: number): string;
+export declare function formatDate(value: unknown, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Un color hexadecimal en su forma de seis cifras, o nada si no lo es.
+ *
+ * Existe porque `<input type="color">` **solo** entiende seis cifras: con
+ * `#fff` —que es válido en CSS y lo que se escribe a mano— se pone en negro sin
+ * avisar, así que la muestra pintaba blanco y el selector abría negro. Los dos
+ * controles del mismo campo decían cosas distintas.
+ */
+export declare function toHexColor(value?: string): string | undefined;

package/dist/runtime/app/utils/format.js

@@ -0,0 +1,36 @@
+export function formatSlug(value) {
+  if (!value) return "";
+  return value.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+export function formatNumber(value, locale, decimals) {
+  if (value === null || value === void 0 || value === "") return "";
+  const parsed = Number(value);
+  if (Number.isNaN(parsed)) return "";
+  return new Intl.NumberFormat(locale, {
+    maximumFractionDigits: decimals ?? 2,
+    minimumFractionDigits: decimals ?? 0
+  }).format(parsed);
+}
+export function formatCurrency(value, locale, currency = "EUR", decimals) {
+  if (value === null || value === void 0 || value === "") return "";
+  const parsed = Number(value);
+  if (Number.isNaN(parsed)) return "";
+  return new Intl.NumberFormat(locale, {
+    currency,
+    maximumFractionDigits: decimals ?? 2,
+    minimumFractionDigits: decimals ?? 2,
+    style: "currency"
+  }).format(parsed);
+}
+export function formatDate(value, locale, options) {
+  if (value === null || value === void 0 || value === "") return "";
+  const date = value instanceof Date ? value : new Date(String(value));
+  if (Number.isNaN(date.getTime())) return "";
+  return new Intl.DateTimeFormat(locale, options ?? { dateStyle: "medium" }).format(date);
+}
+export function toHexColor(value) {
+  if (!value) return void 0;
+  const shorthand = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/i.exec(value);
+  if (shorthand) return `#${shorthand[1]}${shorthand[1]}${shorthand[2]}${shorthand[2]}${shorthand[3]}${shorthand[3]}`.toLowerCase();
+  return /^#[0-9a-f]{6}$/i.test(value) ? value.toLowerCase() : void 0;
+}

package/dist/runtime/app/utils/pagination.d.ts

@@ -0,0 +1,41 @@
+/** Marca el salto entre dos páginas que no son consecutivas. */
+export type VunoPageGap = 'gap';
+/**
+ * Cuántas páginas hay. Cero cuando no hay nada que paginar, y también cuando el
+ * tamaño de página no es un número de filas: sin tamaño no hay páginas, y
+ * devolver `1` fingiría una que no se puede pedir.
+ */
+export declare function getPageCount(total: number, pageSize: number): number;
+/**
+ * La página que se puede enseñar, dado cuántas filas hay en total.
+ *
+ * Una página por encima del final no es un conjunto vacío: es un enlace
+ * guardado que dejó de valer, o un tamaño de página que cambió. Devolver la
+ * última con filas permite corregir la consulta en vez de afirmar que no hay
+ * nada, que sería falso sobre el conjunto entero.
+ *
+ * Con `total` en cero no se toca: ahí el vacío sí es real y la página en la que
+ * uno esté da igual.
+ */
+export declare function clampPage(page: number, total: number, pageSize: number): number;
+/**
+ * Qué se pinta en el paginador: los números y los saltos, en orden.
+ *
+ * Siempre aparecen la primera y la última —son los dos destinos que alguien
+ * busca sin saber su número— y las `siblings` a cada lado de la actual, que son
+ * las que se alcanzan de un clic. Entre dos que no se tocan va un `'gap'`.
+ *
+ * La regla de fondo es que **una elipsis que no ahorra sitio no se pone**, y de
+ * ahí salen los dos casos que más se fallan:
+ *
+ * - **Pocas páginas se enseñan enteras.** Un paginador con saltos ocupa como
+ *   mucho `2 × siblings + 5` posiciones —los dos extremos, los dos saltos y la
+ *   ventana—, así que por debajo de eso esconder páginas no estrecha nada y
+ *   solo quita destinos.
+ * - **Un hueco de una sola página se rellena.** Cambiar `4` por `…` ocupa lo
+ *   mismo y deja de ser un enlace.
+ *
+ * La página se acota antes de calcular: una fuera de rango —un enlace viejo—
+ * daría una ventana de vecinas que no existen y un paginador sin la actual.
+ */
+export declare function getPageItems(page: number, pageCount: number, siblings?: number): (number | VunoPageGap)[];

package/dist/runtime/app/utils/pagination.js

@@ -0,0 +1,32 @@
+export function getPageCount(total, pageSize) {
+  if (total <= 0) return 0;
+  if (pageSize <= 0) return 0;
+  return Math.ceil(total / pageSize);
+}
+export function clampPage(page, total, pageSize) {
+  const last = getPageCount(total, pageSize);
+  if (last <= 0) return page;
+  return Math.min(page, last);
+}
+export function getPageItems(page, pageCount, siblings = 1) {
+  if (pageCount <= 0) return [];
+  const current = Math.min(Math.max(page, 1), pageCount);
+  const around = Math.max(siblings, 0);
+  if (pageCount <= around * 2 + 5) return Array.from({ length: pageCount }, (_, index) => index + 1);
+  const shown = /* @__PURE__ */ new Set([1, pageCount]);
+  for (let candidate = current - around; candidate <= current + around; candidate++) {
+    if (candidate >= 1 && candidate <= pageCount) shown.add(candidate);
+  }
+  const pages = [...shown].sort((a, b) => a - b);
+  const items = [];
+  for (const [index, value] of pages.entries()) {
+    const previous = pages[index - 1];
+    if (previous !== void 0) {
+      const hole = value - previous - 1;
+      if (hole === 1) items.push(previous + 1);
+      else if (hole > 1) items.push("gap");
+    }
+    items.push(value);
+  }
+  return items;
+}