@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/foundations/grouping.d.ts

@@ -0,0 +1,281 @@
+/**
+ * LA AGRUPACIÓN, en N niveles.
+ *
+ * Context: agrupar es partir un conjunto por lo que sus filas comparten, y eso
+ * no tiene por qué ser UNA pregunta. «Por procedencia» es una; «por procedencia
+ * y después por mes» es la misma pregunta hecha dos veces, y la respuesta es un
+ * árbol y no una lista de montones.
+ *
+ * ── Qué se PIDE y qué se DIBUJA son dos cosas ──────────────────────
+ *
+ * `GroupLevel` es lo que alguien pidió: por qué campo partir y, si es una
+ * fecha, con qué grano. `Pile` es lo que se dibuja: un montón ya armado, con su
+ * rótulo, cuántas filas tiene y el nivel de abajo. Están separados porque los
+ * montones no siempre los arma esta máquina: los puede armar quien tenga los
+ * datos —y contar un catálogo entero es algo que sólo puede contestar quien lo
+ * guarda—. Por eso `pilesFrom` es un HELPER y no el único camino: una
+ * presentación recibe `piles` y no sabe ni le importa quién los contó.
+ *
+ * **Esto no conoce ningún motor.** Ni criteria, ni cursores, ni transporte: un
+ * montón acá es rótulo, conteo, hijos y filas. Quien traduzca la respuesta de un
+ * servidor a esta forma vive afuera, y por eso la misma presentación sirve para
+ * un agrupado hecho en el navegador y para uno contado a mil kilómetros.
+ *
+ * ── La identidad de un montón es su RUTA ────────────────────────────
+ *
+ * Y no su clave. Con un solo nivel alcanzaba la clave, porque no había dos
+ * montones que pudieran llamarse igual. Con N niveles sí: «2026-09» puede ser un
+ * mes adentro de «sintético» y otro adentro de «traído», y son montones
+ * distintos que se pliegan por separado. La ruta —`["sintético", "2026-09"]`—
+ * es lo único que los distingue, así que es lo que se guarda.
+ *
+ * ── La CLAVE identifica; el RÓTULO se lee ───────────────────────────
+ *
+ * Y son dos textos. «2026-09» es lo que el motor escribe: lo que se compara con
+ * lo que contó el servidor, lo que la ruta lleva, lo que queda plegado. Con eso
+ * a la vista la interfaz habla en máquina, así que el montón lleva además su
+ * rótulo —«Septiembre»— que es lo que se dibuja y lo único que cambia con el
+ * idioma. Al revés no se puede: con el rótulo por identidad, dos septiembres de
+ * años distintos se funden en un montón que no existe, y plegar un mes en
+ * español lo dejaría abierto en inglés.
+ *
+ * Para un campo que no es una fecha los dos textos son el mismo —«sintético» se
+ * identifica y se lee igual— y por eso el rótulo sólo se pone aparte donde hace
+ * falta: en las fechas, que las nombra `system/calendar.ts`.
+ */
+/** El grano de un nivel de fecha. Sin grano, un campo de fecha parte por
+ *  instante y cada fila termina en su propio montón, que es no agrupar. */
+export type GroupGrain = "day" | "week" | "month" | "quarter" | "year";
+/**
+ * De GRUESO a fino. Es el orden en que se anidan los granos de un mismo campo, y
+ * no es una preferencia: agrupar por día y después por mes daría montones de un
+ * día dentro de meses que ya no parten nada, porque un día entero vive adentro
+ * de un solo mes. La jerarquía de un calendario tiene una dirección y es ésta.
+ */
+export declare const GRAIN_ORDER: readonly GroupGrain[];
+/** Un NIVEL: por qué campo se parte, y con qué grano si es una fecha. Es lo que
+ *  alguien pidió, no lo que se dibuja. */
+export type GroupLevel = {
+    field: string;
+    grain?: GroupGrain;
+};
+/** Un campo por el que SE PUEDE agrupar, para que el control ofrezca algo. Los
+ *  granos se declaran acá y no se adivinan del tipo: quién sabe si una fecha se
+ *  mira por semana o por trimestre es el dominio, y ofrecer los cuatro siempre
+ *  es ofrecer tres que a nadie le sirven. */
+export type GroupableField = {
+    field: string;
+    label: string;
+    /** Presentes = es una fecha y estos son los cortes que tienen sentido. */
+    grains?: readonly GroupGrain[];
+};
+/**
+ * Un MONTÓN ya armado: lo que sus filas comparten, cuántas son, y el nivel de
+ * abajo.
+ */
+export type Pile<T> = {
+    /** La ruta desde la raíz, en CLAVES. Es la identidad del montón: lo que lo
+     *  pliega y lo que lo distingue de un hermano homónimo en otra rama. */
+    path: readonly string[];
+    /** Cuán adentro está. `0` es el primer nivel. Lo usa la sangría. */
+    depth: number;
+    /** Por qué campo se partió acá. Lo dibuja el encabezado a la izquierda del
+     *  valor: sin él, «2026-09» no dice si es cuándo se registró o cuándo se
+     *  corrió. */
+    field: string;
+    /** Lo que las filas COMPARTEN, en el idioma del motor: «2026-09». Es el último
+     *  tramo de la ruta, y lo que se compara con lo que contó el servidor. */
+    key: string;
+    /** El mismo valor, ya legible y en el idioma activo: «Septiembre». Es lo que
+     *  se dibuja, y lo único de un montón que cambia con el idioma. */
+    label: string;
+    /**
+     * Cuántas filas hay en el montón — TODAS, no las de la página.
+     *
+     * Es la diferencia entre «hay 187 sintéticos» y «se ven 12»: un conteo que
+     * cambia al pasar de página no es un conteo, es un largo de array. Cuando los
+     * montones los cuenta quien guarda los datos, este número viene de allá.
+     */
+    count: number;
+    /** Las filas, en el nivel MÁS PROFUNDO. Vacío en los de arriba: un montón que
+     *  tiene montones adentro no tiene filas propias. */
+    items: readonly T[];
+    /** El nivel de abajo. Vacío en el más profundo. */
+    piles: readonly Pile<T>[];
+};
+/**
+ * La identidad de un NIVEL: el campo y, si es fecha, su grano.
+ *
+ * El campo solo no alcanza desde que un mismo campo puede estar puesto con
+ * varios granos —«por mes y adentro por día» son dos niveles del mismo
+ * `registered_at`— y dos niveles que se llaman igual no se pueden ni sacar ni
+ * mover por separado.
+ */
+export declare function levelKey(level: GroupLevel): string;
+/**
+ * Los niveles, acomodados.
+ *
+ * Dos reglas, y las dos son del calendario y no del gusto de nadie:
+ *
+ *  1. Los niveles de un MISMO campo quedan juntos. Partir por mes, después por
+ *     procedencia y después por día del mismo campo deja dos cortes de la misma
+ *     fecha separados por otra cosa, y eso no es una jerarquía, es un tropiezo.
+ *  2. Adentro de un campo van de GRUESO a FINO. Tildar «día» y después «mes»
+ *     tiene que dar «mes › día», porque al revés el mes no parte nada: un día
+ *     entero ya vive adentro de un solo mes.
+ *
+ * El orden ENTRE campos lo decide quien agrupa —es una pregunta del dominio, no
+ * del calendario— así que se respeta el de primera aparición y se puede mover.
+ */
+export declare function normalizeLevels(levels: readonly GroupLevel[]): GroupLevel[];
+/**
+ * LO QUE HACE AGRUPABLE A UNA VISTA.
+ *
+ * Cualquier componente que dibuje N cosas —filas, tarjetas, celdas, líneas de un
+ * informe, puntos de una serie— puede agrupar aceptando ESTO y nada más. Es
+ * deliberadamente corto: cinco campos, ninguno opcional por capricho.
+ *
+ * ── Lo que el contrato SÍ fija ──────────────────────────────────────
+ *
+ *     levels     qué se pregunta, y en qué orden
+ *     of         a qué montón va cada cosa, ya legible
+ *     piles      el árbol ya armado, si lo contó alguien con el conjunto entero
+ *     collapsed  qué está plegado, por ruta
+ *     onToggle   cómo se pliega
+ *
+ * ── Lo que NO fija, y es el punto ───────────────────────────────────
+ *
+ * **Cómo se dibuja un montón.** La lista pone un encabezado con filete; la
+ * planilla, una banda pegada a la izquierda porque está virtualizada por índice
+ * y no puede anidar el marcado; la tabla usa una fila con `colSpan`; el informe
+ * hace una línea con sus subtotales; una serie haría una serie por montón. Las
+ * cinco son correctas y ninguna sirve para las otras — un contrato que además
+ * dictara el dibujo obligaría a todas a parecerse a la primera que se escribió.
+ *
+ * Por eso lo que se comparte es el ÁRBOL y no el render: quien implementa recibe
+ * `Pile[]` de `pilesOf()` y lo recorre como su presentación necesite.
+ *
+ * ── Cómo se implementa ──────────────────────────────────────────────
+ *
+ *     function MiVista<T>({ items, grouping }: { items: readonly T[]; grouping?: Grouping<T> }) {
+ *       const piles = pilesOf(items, grouping);
+ *       if (piles === null) return <>{items.map(dibujar)}</>;
+ *       return recorrer(piles);          // ← acá manda la presentación
+ *     }
+ */
+export type Grouping<T> = {
+    /**
+     * Los niveles pedidos, de afuera hacia adentro. Vacío = sin agrupar.
+     *
+     * El ORDEN es la jerarquía: `[origen, mes]` y `[mes, origen]` son dos lecturas
+     * distintas del mismo conjunto.
+     */
+    levels: readonly GroupLevel[];
+    /** A qué montón va cada cosa, en cada nivel: la CLAVE. Recortar una fecha a su
+     *  grano es de quien conoce el dato, no del sistema. */
+    of: PileOf<T>;
+    /** Cómo se lee una clave. Sin esto, una fecha la nombra el calendario del
+     *  sistema en el idioma activo y lo demás se dibuja tal cual. */
+    label?: PileLabelOf;
+    /**
+     * El árbol YA armado, cuando lo contó quien tiene el conjunto entero.
+     *
+     * Existe porque un conteo que sólo conoce la página no es un conteo: «187
+     * sintéticos» no lo pueden contestar las doce filas que se trajeron. Quién
+     * cuenta no es asunto de esta capa — dibuja el mismo árbol en los dos casos.
+     *
+     * Un árbol contado afuera llega con sus rótulos PUESTOS, y esta capa no se los
+     * toca: quien lo tradujo sabe cuál de sus claves es una fecha y cuál es un
+     * código con nombre propio. `dateLabel` está exportado para que los ponga con
+     * las mismas palabras que el árbol armado acá.
+     */
+    piles?: readonly Pile<T>[];
+    /** Qué montones están plegados, por `pathKey(pile.path)`. */
+    collapsed?: readonly string[];
+    onToggle?: (key: string) => void;
+};
+/**
+ * El árbol que hay que dibujar, o `null` si no se agrupa.
+ *
+ * Es la única línea que un componente necesita escribir para volverse agrupable:
+ * decide entre el árbol que le pasaron y el que arma con las cosas en la mano, y
+ * contesta `null` cuando no hay nada que partir — que es distinto de un árbol
+ * vacío, porque un árbol vacío significa «se agrupó y no quedó nada».
+ */
+export declare function pilesOf<T>(items: readonly T[], grouping: Grouping<T> | undefined): readonly Pile<T>[] | null;
+/** Si un montón está abierto, según lo plegado. Abierto es el default: agrupar y
+ *  después tener que abrir cada montón son dos gestos para lo que se pidió en
+ *  uno. */
+export declare function pileIsOpen<T>(pile: Pile<T>, grouping: Grouping<T> | undefined): boolean;
+/** La clave de plegado de una ruta. El separador es un carácter que no aparece
+ *  en un valor real, así que dos rutas distintas no pueden producir la misma
+ *  clave por concatenación — `["a", "b"]` y `["ab"]` sí podrían con un
+ *  separador escribible. */
+export declare function pathKey(path: readonly string[]): string;
+/** Qué montón le toca a cada fila en cada nivel: su CLAVE. Recortar una fecha a
+ *  su grano es cosa de quien conoce el dato —`dateKey` la recorta con el mismo
+ *  texto que el motor— y ponerle nombre es cosa del rótulo. */
+export type PileOf<T> = (item: T, level: GroupLevel) => string;
+/**
+ * Cómo se lee la clave de un montón.
+ *
+ * `within` son los granos que los montones de ARRIBA, del mismo campo, ya
+ * dijeron: con el año afuera, un mes se rotula «Septiembre» y no «Septiembre de
+ * 2026». Decirlo dos veces llena la sangría con lo que está dos renglones más
+ * arriba.
+ */
+export type PileLabelOf = (key: string, level: GroupLevel, within: readonly GroupGrain[]) => string;
+/** El rótulo por default: una fecha la nombra el calendario en el idioma activo,
+ *  y lo que no es una fecha se dibuja tal cual —«sintético» se identifica y se
+ *  lee con la misma palabra, y traducirlo sería inventar un valor que nadie
+ *  guardó. */
+export declare function pileLabel(key: string, level: GroupLevel, within: readonly GroupGrain[]): string;
+/**
+ * CÓMO SE LEE UNA RUTA de claves, tramo por tramo.
+ *
+ * La clave identifica y el rótulo se lee: «2026-09» es lo que el motor escribe y
+ * «Septiembre» lo que se dibuja. Cualquiera que tenga una ruta —el eje de un
+ * pivote, el título de un montón, una miga— la dice con esto, porque una ruta
+ * que se lee distinta según quién la dibuje es el mismo corte con dos caras.
+ *
+ * `within` sale de los niveles de ARRIBA del mismo campo: con el año afuera, el
+ * mes se dice «Septiembre» y no «Septiembre de 2026», porque eso ya está escrito
+ * un tramo antes.
+ */
+export declare function pathLabels(levels: readonly GroupLevel[], path: readonly string[], label?: PileLabelOf): string[];
+/**
+ * Arma el árbol de montones a partir de las filas que hay EN LA MANO.
+ *
+ * Sirve cuando el conjunto entero está en el navegador. Cuando no lo está —un
+ * catálogo de ciento ochenta y siete del que se bajaron doce—, los montones los
+ * cuenta quien los guarda y esto no se usa: la presentación recibe `piles` ya
+ * hechos. Las dos formas dibujan igual porque dibujan el mismo tipo.
+ *
+ * El orden de los montones es el de PRIMERA APARICIÓN de cada valor, en cada
+ * nivel. No se ordena alfabéticamente: el orden de las filas ya lo decidió
+ * alguien —una columna, un criterio, el motor— y reordenar los montones acá lo
+ * contradiría.
+ */
+export declare function pilesFrom<T>(items: readonly T[], levels: readonly GroupLevel[], of: PileOf<T>, label?: PileLabelOf): readonly Pile<T>[];
+/**
+ * La ruta de UNA fila: el montón que le toca en cada nivel.
+ *
+ * Es la identidad del montón más profundo que la contiene, sin armar el árbol.
+ * Sirve para preguntar «¿estas dos filas son vecinas?», que con un solo nivel se
+ * contestaba comparando una clave y con N hay que comparar la ruta entera: dos
+ * datasets del mismo mes son vecinos sólo si además comparten la procedencia,
+ * porque si no están en montones distintos aunque el último tramo coincida.
+ */
+export declare function itemPath<T>(item: T, levels: readonly GroupLevel[], of: PileOf<T>): string[];
+/** Las filas de un árbol, en el orden en que se dibujan. Lo usan las
+ *  presentaciones que necesitan la secuencia y no el árbol —la planilla
+ *  virtualizada, que cuenta índices— y el que quiera saber qué quedó visible. */
+export declare function pileItems<T>(piles: readonly Pile<T>[]): readonly T[];
+/** Cuántas filas hay en total. Suma los conteos del primer nivel, que ya
+ *  incluyen los de abajo — no recorre las filas, porque puede no tenerlas. */
+export declare function pileCount<T>(piles: readonly Pile<T>[]): number;
+/** Mueve un nivel `delta` lugares. Se queda en los bordes en vez de dar la
+ *  vuelta: llegar al primero y volver al último no es lo que nadie espera de una
+ *  flecha «subir». El orden de los niveles ES la jerarquía, así que esto cambia
+ *  la pregunta y no sólo la lista. */
+export declare function moveLevel(levels: readonly GroupLevel[], field: string, delta: number): GroupLevel[];

package/dist/foundations/index.d.ts

@@ -0,0 +1,14 @@
+export { currentCopy, currentCopyLocale, ENGLISH_COPY, fillCopy, installCopy, mergeCopy, type UiCopy, type UiCopyOverride, UiCopyProvider, useUiCopy, } from "./copy.js";
+export { byDensity, type Density, DensityProvider, useDensity, } from "./density.js";
+export { bySurface, SurfaceProvider, useSurface } from "./surface.js";
+export { applyTheme, isTheme, type ResolvedTheme, resolveTheme, type Theme, THEME_ATTRIBUTE, ThemeProvider, type ThemeProviderProps, THEMES, useTheme, } from "./theme.js";
+export type { Size, Surface, Tone } from "./types.js";
+/** El castellano del sistema, para quien lo quiera instalar entero. */
+export { SPANISH_COPY } from "./copy.es.js";
+export { flatten, loose, pick, pickAll, propsOf, slot, slotOf, type Slotted, } from "./slots.js";
+export { dateKey, dateLabel, grainName, monthName, } from "./calendar.js";
+export { GRAIN_ORDER, type GroupableField, type GroupGrain, type Grouping, type GroupLevel, itemPath, levelKey, moveLevel, normalizeLevels, pathKey, pathLabels, type Pile, pileCount, pileIsOpen, pileItems, pileLabel, type PileLabelOf, type PileOf, pilesFrom, pilesOf, } from "./grouping.js";
+export { axisLabels, axisSpans, keyStarts, type Pivot, type PivotAxis, type PivotCell, type PivotCrossing, type PivotFold, pivotFrom, pivotIsEmpty, type PivotKey, type PivotLevel, type PivotMargin, type PivotMeasure, pivotOf, type PivotSource, type PivotSpec, } from "./pivot.js";
+export { downloadPivot, pivotSheet, type PivotSheetOptions, pivotXlsx, } from "./pivotSheet.js";
+export { STICKY_TOP, stickyReset, stickyTop, useScrollBox, useStickyLayer, } from "./sticky.js";
+export { columnName, downloadXlsx, writeXlsx, type XlsxCell, type XlsxMerge, type XlsxSheet, } from "./xlsx.js";

package/dist/foundations/index.js

@@ -0,0 +1,30 @@
+/* What is shared by more than one family and belongs to none of them. */
+export { currentCopy, currentCopyLocale, ENGLISH_COPY, fillCopy, installCopy, mergeCopy, UiCopyProvider, useUiCopy, } from "./copy.js";
+export { byDensity, DensityProvider, useDensity, } from "./density.js";
+/* EL TEMA — claro, oscuro o el del sistema operativo. Las paletas viven en `tokens.css`; esto
+   sólo escribe `data-theme`. */
+export { bySurface, SurfaceProvider, useSurface } from "./surface.js";
+export { applyTheme, isTheme, resolveTheme, THEME_ATTRIBUTE, ThemeProvider, THEMES, useTheme, } from "./theme.js";
+/** El castellano del sistema, para quien lo quiera instalar entero. */
+export { SPANISH_COPY } from "./copy.es.js";
+/* LAS RANURAS — cómo un arquetipo se escribe como ÁRBOL. Vive acá y no adentro
+   de uno porque lo hablan todos los que lo son: mientras estuvo escondido en
+   `Record.tsx`, ser un árbol era un privilegio de los registros. */
+export { flatten, loose, pick, pickAll, propsOf, slot, slotOf, } from "./slots.js";
+/* EL CALENDARIO — de una fecha a una clave y de una clave a un rótulo. Los meses
+   y los días de la semana los dice `Intl` con el `locale` de la copia; la semana
+   y el trimestre son las dos únicas palabras que hay que escribir. */
+export { dateKey, dateLabel, grainName, monthName, } from "./calendar.js";
+/* LA AGRUPACIÓN — el vocabulario, que hablan las dos capas: la lista arma el
+   árbol de montones y la tabla lo dibuja. Vive acá y no en `contexts/list`
+   porque una primitiva no puede importar de un contexto. */
+export { GRAIN_ORDER, itemPath, levelKey, moveLevel, normalizeLevels, pathKey, pathLabels, pileCount, pileIsOpen, pileItems, pileLabel, pilesFrom, pilesOf, } from "./grouping.js";
+/* EL PIVOTE — el mismo reparto: el vocabulario acá, la grilla en `primitives`.
+   Que los márgenes vengan de la base y que un agujero no sea un cero son reglas
+   del CONTRATO, no del dibujo, y por eso viven de este lado. */
+export { axisLabels, axisSpans, keyStarts, pivotFrom, pivotIsEmpty, pivotOf, } from "./pivot.js";
+/* LA PLANILLA: la misma grilla, en un archivo. El escritor es genérico y no
+   sabe de pivotes; `pivotSheet` es el que traduce uno. */
+export { downloadPivot, pivotSheet, pivotXlsx, } from "./pivotSheet.js";
+export { STICKY_TOP, stickyReset, stickyTop, useScrollBox, useStickyLayer, } from "./sticky.js";
+export { columnName, downloadXlsx, writeXlsx, } from "./xlsx.js";

package/dist/foundations/layout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Context: `--container-handheld` (40rem, `tokens.css`) in pixels. A container query cannot
+ * swap a `<table>` for a list, so the two components that must decide in code — `ListView`
+ * (which presentations to offer) and `EditableTable` (grid or stacked cards) — ask a
+ * `ResizeObserver` for pixels and compare against this one figure. It used to be written
+ * twice, `HANDHELD` in one and `NARROW_LIST` in the other, and the day one moved the two
+ * would have disagreed about what a phone is. Keep it equal to the token.
+ */
+export declare const HANDHELD_WIDTH = 640;

package/dist/foundations/layout.js

@@ -0,0 +1,9 @@
+/**
+ * Context: `--container-handheld` (40rem, `tokens.css`) in pixels. A container query cannot
+ * swap a `<table>` for a list, so the two components that must decide in code — `ListView`
+ * (which presentations to offer) and `EditableTable` (grid or stacked cards) — ask a
+ * `ResizeObserver` for pixels and compare against this one figure. It used to be written
+ * twice, `HANDHELD` in one and `NARROW_LIST` in the other, and the day one moved the two
+ * would have disagreed about what a phone is. Keep it equal to the token.
+ */
+export const HANDHELD_WIDTH = 640;

package/dist/foundations/pivot.d.ts

@@ -0,0 +1,222 @@
+import { type GroupLevel, type PileLabelOf, type PileOf } from "./grouping.js";
+/**
+ * EL PIVOTE: montones cruzados por montones.
+ *
+ * Agrupar parte un conjunto por lo que sus filas comparten. Pivotear lo parte
+ * DOS VECES a la vez, por ejes distintos, y lee el número donde los dos cortes
+ * se encuentran: el cliente hacia abajo, el mes hacia la derecha, y en el
+ * cruce cuántas filas hay y cuánto suman.
+ *
+ * ── Tres reglas, y ninguna es cosmética ─────────────────────────────
+ *
+ *  1. **La grilla se dibuja desde los EJES, no desde los cruces.** `rows.keys` y
+ *     `columns.keys` traen cada clave que apareció, en orden; los cruces se
+ *     PREGUNTAN de a uno. Un pivote es mayormente agujeros —doce clientes
+ *     por veinticuatro meses son 288 celdas y cuarenta con filas— y deducir la
+ *     grilla recorriendo los cruces deja afuera el mes en que no pasó nada, que
+ *     es justo la columna que alguien está buscando.
+ *
+ *  2. **Los márgenes vienen plegados de la BASE.** Un promedio de promedios no
+ *     es un promedio y una mediana de medianas no es nada, así que `rowTotal`,
+ *     `columnTotal` y `total` se reciben: esta capa nunca los inventa sumando la
+ *     fila que acaba de dibujar. Sin ellos no hay banda de totales, que es la
+ *     respuesta honesta cuando nadie los calculó.
+ *
+ *  3. **Un agujero no es un cero.** `undefined` es «ahí no hay ninguna fila» y
+ *     `0` es «hay filas y suman cero». La grilla los dibuja distinto porque
+ *     significan cosas distintas.
+ *
+ * ── Qué se PIDE y qué se DIBUJA ─────────────────────────────────────
+ *
+ * Igual que con los montones: `PivotSpec` es lo que alguien pidió —por qué
+ * campos partir cada eje, qué medidas plegar— y `Pivot` es lo que se dibuja, ya
+ * plegado. Están separados porque plegar no siempre lo hace esta máquina: un
+ * libro de ventas de ciento ochenta y siete del que se bajaron doce lo pliega quien lo
+ * guarda, y `pivotFrom` es un helper para cuando el conjunto entero está en el
+ * navegador, no el único camino.
+ *
+ * **Esto no conoce ningún motor.** Ni criteria, ni cursores, ni transporte: un
+ * eje acá es una lista de rutas legibles y un cruce es un conteo con números al
+ * lado. Quien traduzca la respuesta de un servidor a esta forma vive afuera, y
+ * por eso la misma grilla sirve para un pivote armado en el navegador y para uno
+ * plegado a mil kilómetros.
+ */
+/**
+ * La clave de una fila o de una columna: la RUTA por los niveles de su eje, ya
+ * legible.
+ *
+ * Es una ruta y no un valor por la misma razón que la de un montón: con dos
+ * niveles puestos, «2026-09» puede ser un mes adentro de «Ferretería Sur» y otro
+ * adentro de «Distribuidora Andina», y son dos filas distintas de la grilla.
+ */
+export type PivotKey = readonly string[];
+/**
+ * UN NIVEL de un eje: por qué se partió, y cómo se lee.
+ *
+ * Lleva el nivel ENTERO y no sólo su rótulo porque el rótulo de un nivel no
+ * alcanza para leer sus claves: con «registrado» a la vista, «2026-09» sigue
+ * siendo «2026-09». El grano es lo que deja decir «Septiembre», y el campo es lo
+ * que deja saber que el mes cuelga del año de más arriba y entonces no hace
+ * falta repetirlo.
+ */
+export type PivotLevel = GroupLevel & {
+    /** Cómo se llama este corte: es lo que dice la esquina de la grilla. Sin él,
+     *  una columna no aclara si es cuándo se registró o cuándo se corrió. */
+    label: string;
+};
+/** Un EJE del pivote: qué se preguntó, y qué claves aparecieron. */
+export type PivotAxis = {
+    /** Los niveles, de afuera hacia adentro. */
+    levels: readonly PivotLevel[];
+    /** Cada clave que apareció, en orden. **La grilla se dibuja desde acá.** */
+    keys: readonly PivotKey[];
+};
+/**
+ * CÓMO SE LEE UNA CLAVE del eje, tramo por tramo.
+ *
+ * La clave identifica —«2026-09» es lo que el motor escribe y lo que se compara
+ * con lo que contó el servidor— y el rótulo se lee. Son dos textos, igual que en
+ * un montón, y por la misma razón: con el rótulo por identidad, dos septiembres
+ * de años distintos serían el mismo.
+ *
+ * `within` sale de los niveles de ARRIBA del mismo campo: con el año afuera, el
+ * mes se dice «Septiembre» y no «Septiembre de 2026», porque eso ya está escrito
+ * dos columnas antes.
+ */
+export declare function axisLabels(axis: PivotAxis, key: PivotKey, label?: PileLabelOf): readonly string[];
+/** Una MEDIDA: uno de los números que se pliegan en cada cruce. */
+export type PivotMeasure = {
+    id: string;
+    header: string;
+    /** Para un porcentaje o una variación, que no se leen como un importe. */
+    format?: (value: number) => string;
+    /**
+     * Cómo se lee la medida en una PLANILLA: el código de formato de Excel,
+     * `#,##0.00`, `0.0%`, `#,##0 "Bs."`.
+     *
+     * Va aparte de `format` porque son dos cosas distintas: `format` es una
+     * función de JavaScript, y un archivo no se puede llevar una función adentro.
+     * Sin esto el número sale con el formato general — sigue siendo un número y se
+     * sigue pudiendo sumar, que es lo que no se puede perder.
+     */
+    numberFormat?: string;
+};
+/**
+ * Un CRUCE ya plegado: cuántas filas hay debajo y qué dan las medidas.
+ *
+ * `count` va aparte de las medidas y no como una más: es la única que siempre se
+ * puede contestar, y es la que dice si una celda vacía está vacía porque no hay
+ * filas o porque las que hay no tienen ese número.
+ */
+export type PivotCell = {
+    count: number;
+    /** Un número por medida, por id. `null` es «esta medida no se contesta acá» y
+     *  es distinto de `0`. */
+    values: Readonly<Record<string, number | null>>;
+};
+/** EL PIVOTE, listo para dibujar. */
+export type Pivot = {
+    rows: PivotAxis;
+    columns: PivotAxis;
+    measures: readonly PivotMeasure[];
+    /** El cruce donde una fila encuentra a una columna, o `undefined` cuando no
+     *  hay ninguna fila ahí. Se pregunta y no se recorre: ver la regla 1. */
+    cell: (row: PivotKey, column: PivotKey) => PivotCell | undefined;
+    /** La fila entera, plegada de la base. Ausente = no hay banda de totales a la
+     *  derecha, porque nadie los calculó y acá no se suman celdas. */
+    rowTotal?: (row: PivotKey) => PivotCell | undefined;
+    /** La columna entera, plegada de la base. */
+    columnTotal?: (column: PivotKey) => PivotCell | undefined;
+    /** Todo lo que entró, plegado una vez. */
+    total?: PivotCell;
+};
+/** Un cruce, con sus dos claves. Es la forma en que viaja una grilla dispersa:
+ *  sólo los cruces que tienen filas. */
+export type PivotCrossing = PivotCell & {
+    row: PivotKey;
+    column: PivotKey;
+};
+/** Un margen: la clave de su eje y lo que da esa fila —o esa columna— entera. */
+export type PivotMargin = PivotCell & {
+    key: PivotKey;
+};
+export type PivotSource = {
+    rows: PivotAxis;
+    columns: PivotAxis;
+    measures: readonly PivotMeasure[];
+    /** Sólo los cruces con filas. Los que faltan son agujeros. */
+    crossings: readonly PivotCrossing[];
+    /** Uno por clave de fila. Sin esto no hay columna de totales. */
+    rowMargins?: readonly PivotMargin[];
+    /** Uno por clave de columna. Sin esto no hay fila de totales. */
+    columnMargins?: readonly PivotMargin[];
+    total?: PivotCell;
+};
+/**
+ * Indexa un pivote que ya viene plegado.
+ *
+ * Los cruces viajan como lista —es lo que sabe serializar cualquier transporte—
+ * y se dibujan preguntando de a uno, así que en el medio hace falta un índice.
+ * Se arma una vez acá y no en cada celda de cada render: una grilla de 288
+ * celdas buscando en una lista de 40 son 11.520 comparaciones por pintada.
+ */
+export declare function pivotOf(source: PivotSource): Pivot;
+/** Una medida y cómo se pliega. El pliegue recibe las filas de la BASE —las del
+ *  cruce, las de la fila entera, las de todo—, que es lo que hace que el margen
+ *  salga del mismo lugar que la celda y no de sumar celdas. */
+export type PivotFold<T> = PivotMeasure & {
+    fold: (items: readonly T[]) => number | null;
+};
+export type PivotSpec<T> = {
+    /** Los niveles del eje vertical, de afuera hacia adentro. */
+    rows: readonly GroupLevel[];
+    /** Los niveles del eje horizontal. */
+    columns: readonly GroupLevel[];
+    /** A qué montón va cada fila, en cada nivel de cada eje, ya legible. Es el
+     *  mismo contrato que agrupa una lista: recortar una fecha a su grano es de
+     *  quien conoce el dato. */
+    of: PileOf<T>;
+    measures: readonly PivotFold<T>[];
+    /** Cómo se llama cada nivel. Sin esto se muestra el nombre del campo. */
+    labelOf?: (level: GroupLevel) => string;
+};
+/**
+ * Arma el pivote con las filas que hay EN LA MANO.
+ *
+ * Sirve cuando el conjunto entero está en el navegador. Cuando no lo está, el
+ * pivote lo pliega quien guarda los datos y esto no se usa: la grilla recibe un
+ * `Pivot` de `pivotOf` y dibuja igual, porque dibuja el mismo tipo.
+ *
+ * **Los márgenes se pliegan sobre las filas de la base y no sobre los cruces**,
+ * que es la regla 2 escrita en código: el margen de «Ferretería Sur» pliega sus 187
+ * facturas de una, no los doce números mensuales que ya se dibujaron. Es
+ * lo único que hace que una medida que no sea una suma —un promedio, una
+ * mediana, un distintos— diga la verdad en el borde.
+ */
+export declare function pivotFrom<T>(items: readonly T[], spec: PivotSpec<T>): Pivot;
+/** Si el pivote no tiene ni una fila que cruzar. Un eje vacío no es un pivote
+ *  chico: es la vista vacía, y se dice con la frase del conjunto y no con una
+ *  grilla de un renglón. */
+export declare function pivotIsEmpty(pivot: Pivot): boolean;
+/**
+ * Los tramos de una clave que hay que ESCRIBIR, comparada con la anterior.
+ *
+ * En el área de filas de un pivote, el valor de un nivel se escribe sólo cuando
+ * cambia: repetir «Ferretería Sur» en las doce filas de sus doce meses convierte la
+ * jerarquía en una columna de ruido y hace desaparecer justamente el corte que
+ * se pidió. Devuelve, por nivel, si ese tramo arranca acá.
+ */
+export declare function keyStarts(key: PivotKey, previous: PivotKey | undefined): readonly boolean[];
+/**
+ * Cuánto abarca cada tramo del eje horizontal, nivel por nivel.
+ *
+ * El encabezado de un pivote es una jerarquía acostada: un renglón por nivel, y
+ * cada rótulo cubriendo las columnas que cuelgan de él. Esto lo resuelve una vez
+ * —de a tramos consecutivos iguales, que es lo que hace que «2026» cubra sus
+ * cuatro trimestres— y la grilla sólo lo dibuja.
+ */
+export declare function axisSpans(axis: PivotAxis, level: number): readonly {
+    label: string;
+    span: number;
+    at: number;
+}[];