@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/foundations/pivot.js

@@ -0,0 +1,198 @@
+import { pathKey, pathLabels, pileLabel, } from "./grouping.js";
+/**
+ * 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 function axisLabels(axis, key, label = pileLabel) {
+    return pathLabels(axis.levels, key, label);
+}
+/**
+ * El separador entre las dos rutas de un cruce.
+ *
+ * Es un carácter distinto del que separa los tramos de una ruta —ése es el NUL
+ * de `pathKey`— porque si fuera el mismo, una fila `["a"]` cruzada con una
+ * columna `["b","c"]` y una fila `["a","b"]` cruzada con `["c"]` producirían la
+ * misma clave, y serían dos celdas distintas de la grilla apuntando al mismo
+ * número.
+ */
+const CROSS = "
";
+function crossKey(row, column) {
+    return `${pathKey(row)}${CROSS}${pathKey(column)}`;
+}
+/** Sólo lo que es una celda, sin las claves con las que viajó. */
+function cellOf(one) {
+    return { count: one.count, values: one.values };
+}
+/**
+ * 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 function pivotOf(source) {
+    const crossings = new Map();
+    for (const one of source.crossings)
+        crossings.set(crossKey(one.row, one.column), cellOf(one));
+    const rowMargins = new Map();
+    for (const one of source.rowMargins ?? [])
+        rowMargins.set(pathKey(one.key), cellOf(one));
+    const columnMargins = new Map();
+    for (const one of source.columnMargins ?? [])
+        columnMargins.set(pathKey(one.key), cellOf(one));
+    return {
+        rows: source.rows,
+        columns: source.columns,
+        measures: source.measures,
+        cell: (row, column) => crossings.get(crossKey(row, column)),
+        /* Los márgenes se ofrecen sólo si vinieron. La alternativa —contestar
+           siempre y devolver `undefined` adentro— haría que la grilla dibujara una
+           banda de totales entera llena de agujeros. */
+        ...(source.rowMargins === undefined
+            ? {}
+            : { rowTotal: (row) => rowMargins.get(pathKey(row)) }),
+        ...(source.columnMargins === undefined
+            ? {}
+            : { columnTotal: (column) => columnMargins.get(pathKey(column)) }),
+        ...(source.total === undefined ? {} : { total: source.total }),
+    };
+}
+/** Las filas de un eje, agrupadas por su clave, en orden de primera aparición.
+ *  El orden de las filas ya lo decidió alguien —una columna, un criterio, el
+ *  motor— y reordenar los ejes acá lo contradiría. */
+function axisBuckets(items, levels, of) {
+    const out = new Map();
+    for (const item of items) {
+        const key = levels.map((level) => of(item, level));
+        const id = pathKey(key);
+        const bucket = out.get(id);
+        if (bucket === undefined)
+            out.set(id, { key, items: [item] });
+        else
+            bucket.items.push(item);
+    }
+    return out;
+}
+function fold(measures, items) {
+    const values = {};
+    for (const measure of measures)
+        values[measure.id] = measure.fold(items);
+    return { count: items.length, values };
+}
+/**
+ * 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 function pivotFrom(items, spec) {
+    const label = (level) => spec.labelOf?.(level) ?? level.field;
+    const rowBuckets = axisBuckets(items, spec.rows, spec.of);
+    const columnBuckets = axisBuckets(items, spec.columns, spec.of);
+    const crossings = new Map();
+    for (const row of rowBuckets.values()) {
+        const inside = axisBuckets(row.items, spec.columns, spec.of);
+        for (const [columnId, column] of inside) {
+            crossings.set(`${pathKey(row.key)}${CROSS}${columnId}`, fold(spec.measures, column.items));
+        }
+    }
+    const rowMargins = new Map();
+    for (const [id, row] of rowBuckets)
+        rowMargins.set(id, fold(spec.measures, row.items));
+    const columnMargins = new Map();
+    for (const [id, column] of columnBuckets) {
+        columnMargins.set(id, fold(spec.measures, column.items));
+    }
+    return {
+        rows: {
+            levels: spec.rows.map((one) => ({ ...one, label: label(one) })),
+            keys: [...rowBuckets.values()].map((one) => one.key),
+        },
+        columns: {
+            levels: spec.columns.map((one) => ({ ...one, label: label(one) })),
+            keys: [...columnBuckets.values()].map((one) => one.key),
+        },
+        measures: spec.measures.map((one) => ({
+            id: one.id,
+            header: one.header,
+            ...(one.format === undefined ? {} : { format: one.format }),
+            ...(one.numberFormat === undefined ? {} : { numberFormat: one.numberFormat }),
+        })),
+        cell: (row, column) => crossings.get(crossKey(row, column)),
+        rowTotal: (row) => rowMargins.get(pathKey(row)),
+        columnTotal: (column) => columnMargins.get(pathKey(column)),
+        total: fold(spec.measures, items),
+    };
+}
+/** 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 function pivotIsEmpty(pivot) {
+    return pivot.rows.keys.length === 0 || pivot.columns.keys.length === 0;
+}
+/**
+ * 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 function keyStarts(key, previous) {
+    let broken = previous === undefined;
+    return key.map((part, level) => {
+        if (broken)
+            return true;
+        /* Una vez que un nivel de arriba cambió, todos los de abajo arrancan de
+           nuevo aunque digan lo mismo: el «2026-09» de «Distribuidora Andina» no es la
+           continuación del «2026-09» de «Ferretería Sur». */
+        if (part !== previous?.[level]) {
+            broken = true;
+            return true;
+        }
+        return false;
+    });
+}
+/**
+ * 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 function axisSpans(axis, level) {
+    const keys = axis.keys;
+    const out = [];
+    keys.forEach((key, at) => {
+        const label = axisLabels(axis, key)[level] ?? "";
+        const last = out[out.length - 1];
+        /* Se compara el PREFIJO entero y no el rótulo: dos «2026-09» debajo de dos
+           clientes distintos son dos tramos, y fundirlos en uno dibujaría una
+           celda que abarca columnas que no son hermanas. */
+        const samePrefix = last !== undefined &&
+            last.label === label &&
+            key.slice(0, level).join(CROSS) === (keys[at - 1]?.slice(0, level).join(CROSS) ?? null);
+        if (samePrefix)
+            last.span += 1;
+        else
+            out.push({ label, span: 1, at });
+    });
+    return out;
+}

package/dist/foundations/pivotSheet.d.ts

@@ -0,0 +1,61 @@
+import { type Pivot } from "./pivot.js";
+import { type XlsxSheet } from "./xlsx.js";
+/**
+ * EL PIVOTE COMO PLANILLA: la misma grilla, en un archivo.
+ *
+ * ── Por qué esto existe y no alcanza con «exportar la tabla» ────────
+ *
+ * Una grilla que sale a Excel como texto plano pierde las tres cosas que la
+ * hacían una grilla: el encabezado deja de ser una jerarquía, los números dejan
+ * de sumarse y los agujeros se vuelven ceros. Las tres se arreglan acá:
+ *
+ *     el encabezado    va con celdas COMBINADAS, así «2026» sigue cubriendo sus
+ *                      cuatro trimestres
+ *     los números      entran como números, con su formato — no como texto que
+ *                      parece un número y no se puede sumar
+ *     los agujeros     no se escriben. Una celda ausente en el archivo es lo
+ *                      mismo que un cruce sin filas en la pantalla
+ *
+ * Y los rótulos quedan congelados, por la misma razón que en la pantalla se
+ * quedan pegados.
+ *
+ * ── Lo que el archivo NO puede decir ────────────────────────────────
+ *
+ * En la grilla, un cruce vacío y una medida que no aplica se dibujan distinto:
+ * blanco el primero, un punto el segundo. En la planilla los dos son una celda
+ * vacía, y es deliberado — un punto adentro de una columna de números la
+ * convierte en una columna de texto, y ahí se pierde poder sumarla, que es para
+ * lo que alguien baja una planilla.
+ *
+ * ── Lo que esto exporta es lo que está en la mano ───────────────────
+ *
+ * Que es exactamente todo, y por eso el pivote es la presentación donde exportar
+ * desde el navegador no miente: la grilla entera ya bajó —son rótulos y números
+ * plegados, no los registros— así que el archivo dice lo mismo que la pantalla.
+ * Una lista paginada no tiene esa suerte y su exportación es otra conversación.
+ */
+export type PivotSheetOptions = {
+    /** El nombre de la pestaña, y del archivo cuando se baja. */
+    name?: string;
+    /** Un renglón arriba de todo que dice qué es esta grilla. */
+    caption?: string;
+};
+/**
+ * La grilla, como hoja de cálculo.
+ *
+ * Devuelve la FORMA y no el archivo: los mismos datos sirven para bajarlos acá,
+ * para mandarlos a un servidor que escriba el libro con más hojas, o para
+ * mirarlos en una prueba sin descomprimir nada.
+ */
+export declare function pivotSheet(pivot: Pivot, options?: PivotSheetOptions): XlsxSheet;
+/** Los bytes del `.xlsx` de una grilla. */
+export declare function pivotXlsx(pivot: Pivot, options?: PivotSheetOptions): Uint8Array;
+/**
+ * Bajar la grilla como planilla, en una línea.
+ *
+ * Existe para que el que la usa no vuelva a escribir el armado: tres consumidores
+ * encadenando `pivotSheet → writeXlsx → downloadXlsx` a mano son tres lugares
+ * donde alguien se olvida del título o del nombre del archivo, y entonces la
+ * misma grilla baja distinta según de qué pantalla salió.
+ */
+export declare function downloadPivot(pivot: Pivot, options?: PivotSheetOptions): void;

package/dist/foundations/slots.d.ts

@@ -0,0 +1,67 @@
+import { type ReactNode } from "react";
+/**
+ * LAS RANURAS — cómo un arquetipo se escribe como ÁRBOL.
+ *
+ * Context: la forma de una pantalla es opcional de una manera que una lista de
+ * props no sabe decir. ¿Hay riel? ¿Hay pestañas? ¿Hay paginador? ¿Esta lista se
+ * puede ver como tabla? Una lista de props contesta eso con `pager={undefined}`
+ * y con una segunda prop que declara qué caras se ofrecen — dos lugares que se
+ * pueden contradecir. Un árbol lo dice en voz alta: **si no está escrito, no
+ * está.**
+ *
+ *     <Record>
+ *       <Record.Rail>
+ *         <Record.Pager index={12} total={80} />   ← hay paginador
+ *       </Record.Rail>
+ *     </Record>
+ *
+ * ── Por qué una MARCA y no la identidad del componente ──────────────
+ *
+ * Reconocer una ranura comparando `node.type === Record.Pager` falla en
+ * silencio el día que hay dos copias del módulo en memoria —recarga en caliente,
+ * un bundle mal deduplicado— y entonces el árbol se dibuja vacío sin un solo
+ * error. La marca viaja con el componente y sobrevive a eso.
+ *
+ * ── Esto vive en `system/` y no adentro de un arquetipo ─────────────
+ *
+ * Porque lo hablan todos los que se escriben como árbol. Mientras estuvo
+ * escondido adentro de `Record.tsx`, ser un árbol era un privilegio de los
+ * registros: cualquier otro arquetipo tenía que copiar el mecanismo o quedarse
+ * con treinta y seis props.
+ */
+/** Un componente marcado como ranura. La marca es el nombre, así que un árbol la
+ *  lee sin saber de dónde salió el componente. */
+export type Slotted<Name extends string> = {
+    __slot?: Name;
+};
+/**
+ * Marca un componente como ranura y lo devuelve.
+ *
+ * El componente NO dibuja nada: existe para ser leído por el arquetipo, que es
+ * quien decide dónde va lo que trae adentro. Devolver `null` es lo correcto —
+ * una ranura que se dibujara sola aparecería dos veces, una donde la escribieron
+ * y otra donde el arquetipo la puso.
+ */
+export declare function slot<Name extends string, P>(name: Name, component: (props: P) => ReactNode): ((props: P) => ReactNode) & Slotted<Name>;
+/** Qué ranura es un nodo, si es alguna. */
+export declare function slotOf<Name extends string>(node: ReactNode): Name | undefined;
+/**
+ * Los hijos, con los fragmentos abiertos.
+ *
+ * `Children.toArray` aplana arreglos pero NO fragmentos, y un `<>…</>` en el
+ * medio del árbol —lo que escribe cualquiera que ponga dos ranuras bajo un
+ * condicional— escondería las ranuras que tiene adentro.
+ */
+export declare function flatten(children: ReactNode): ReactNode[];
+/** La primera ranura de ese nombre. */
+export declare function pick<Name extends string>(nodes: readonly ReactNode[], name: Name): ReactNode | undefined;
+/** Todas las ranuras de ese nombre, en el orden en que se escribieron. Lo usa el
+ *  que acepta varias hermanas —las páginas de un cuaderno. */
+export declare function pickAll<Name extends string>(nodes: readonly ReactNode[], name: Name): ReactNode[];
+/** Las props con las que se escribió una ranura. Es lo único que el arquetipo
+ *  necesita de ella: la ranura no dibuja, declara. */
+export declare function propsOf<P>(node: ReactNode | undefined): P | undefined;
+/** Lo que NO es ninguna de esas ranuras. Es la escotilla: lo que el arquetipo no
+ *  previó se dibuja igual, y que aparezca algo acá es la señal de que al
+ *  arquetipo le falta una pieza. */
+export declare function loose<Name extends string>(nodes: readonly ReactNode[], names: readonly Name[]): ReactNode[];

package/dist/foundations/slots.js

@@ -0,0 +1,63 @@
+import { Children, Fragment, isValidElement } from "react";
+/**
+ * Marca un componente como ranura y lo devuelve.
+ *
+ * El componente NO dibuja nada: existe para ser leído por el arquetipo, que es
+ * quien decide dónde va lo que trae adentro. Devolver `null` es lo correcto —
+ * una ranura que se dibujara sola aparecería dos veces, una donde la escribieron
+ * y otra donde el arquetipo la puso.
+ */
+export function slot(name, component) {
+    const marked = component;
+    marked.__slot = name;
+    return marked;
+}
+/** Qué ranura es un nodo, si es alguna. */
+export function slotOf(node) {
+    if (!isValidElement(node))
+        return undefined;
+    const type = node.type;
+    return typeof type === "string" ? undefined : type.__slot;
+}
+/**
+ * Los hijos, con los fragmentos abiertos.
+ *
+ * `Children.toArray` aplana arreglos pero NO fragmentos, y un `<>…</>` en el
+ * medio del árbol —lo que escribe cualquiera que ponga dos ranuras bajo un
+ * condicional— escondería las ranuras que tiene adentro.
+ */
+export function flatten(children) {
+    const out = [];
+    for (const child of Children.toArray(children)) {
+        if (isValidElement(child) && child.type === Fragment) {
+            out.push(...flatten(child.props.children));
+        }
+        else {
+            out.push(child);
+        }
+    }
+    return out;
+}
+/** La primera ranura de ese nombre. */
+export function pick(nodes, name) {
+    return nodes.find((node) => slotOf(node) === name);
+}
+/** Todas las ranuras de ese nombre, en el orden en que se escribieron. Lo usa el
+ *  que acepta varias hermanas —las páginas de un cuaderno. */
+export function pickAll(nodes, name) {
+    return nodes.filter((node) => slotOf(node) === name);
+}
+/** Las props con las que se escribió una ranura. Es lo único que el arquetipo
+ *  necesita de ella: la ranura no dibuja, declara. */
+export function propsOf(node) {
+    return isValidElement(node) ? node.props : undefined;
+}
+/** Lo que NO es ninguna de esas ranuras. Es la escotilla: lo que el arquetipo no
+ *  previó se dibuja igual, y que aparezca algo acá es la señal de que al
+ *  arquetipo le falta una pieza. */
+export function loose(nodes, names) {
+    return nodes.filter((node) => {
+        const name = slotOf(node);
+        return name === undefined || !names.includes(name);
+    });
+}

package/dist/foundations/sticky.d.ts

@@ -0,0 +1,53 @@
+import { type CSSProperties, type RefObject } from "react";
+/** La variable que dice a qué altura arranca lo próximo que se pegue. */
+export declare const STICKY_TOP = "--sticky-top";
+/** Lo que va en `style` de algo pegajoso: se pega debajo de lo que ya hay. */
+export declare const stickyTop: CSSProperties;
+/** Para una caja con scroll propio: adentro, la pila arranca de cero. */
+export declare function stickyReset(): CSSProperties;
+/**
+ * LA CAJA DE UNA TABLA: cuándo tiene que ser un contenedor de scroll y cuándo no.
+ *
+ * Las tres tablas del sistema tienen el mismo dilema y lo resolvían con tres
+ * copias de la misma medición. El dilema es de CSS y no se puede esquivar:
+ * `overflow-x: auto` **obliga** a `overflow-y: auto` —la especificación dice que
+ * `visible` junto a un valor que no sea `visible` ni `clip` computa a `auto`—,
+ * así que en cuanto la caja permite scroll horizontal pasa a ser el scroller, y
+ * el encabezado pegajoso se pega a SU borde en vez de al de la página.
+ *
+ * De ahí salen los tres casos, y son los únicos:
+ *
+ *     alto propio      la caja scrollea de verdad. `auto`, y la pila de cosas
+ *                      pegadas arranca de cero adentro.
+ *     sin alto, entra  no hace falta ninguna caja. `clip` —recorta las esquinas
+ *                      redondeadas sin ser un scroller— y el encabezado se pega
+ *                      a la página, debajo de la barra de la lista.
+ *     sin alto, no entra   vuelve el scroll horizontal, y el encabezado se va
+ *                      con las filas. Es el precio, y es el que hay.
+ *
+ * Devuelve la clase y el estilo ya resueltos para que ninguna tabla vuelva a
+ * decidirlo por su cuenta.
+ */
+export declare function useScrollBox<T extends HTMLElement>(options: {
+    /** El alto declarado. `undefined` o `"auto"` = crece con el contenido. */
+    height?: number | string;
+}): {
+    ref: RefObject<T | null>;
+    className: string;
+    style: CSSProperties;
+};
+/**
+ * Mide el alto de un elemento y devuelve el estilo que empuja la pila para sus
+ * hermanos de abajo.
+ *
+ * `useLayoutEffect` y `ResizeObserver` y no un alto declarado: el alto depende
+ * de si las fichas del buscador envolvieron, y eso recién se sabe después de
+ * pintar.
+ */
+export declare function useStickyLayer<T extends HTMLElement>(): {
+    ref: RefObject<T | null>;
+    /** Va en el elemento que se pega. */
+    self: CSSProperties;
+    /** Va en lo que viene DEBAJO, para que se pegue más abajo todavía. */
+    below: CSSProperties;
+};

package/dist/foundations/sticky.js

@@ -0,0 +1,150 @@
+"use client";
+import { useLayoutEffect, useRef, useState } from "react";
+/* ==================================================================== *
+ *  LA PILA DE COSAS PEGADAS
+ *
+ *  Tres bandas se quedan arriba mientras se scrollea una vista larga, y cada
+ *  una tiene que quedar DEBAJO de la anterior:
+ *
+ *      ┌─ TopNav ─────────────────────────────────┐  top: 0
+ *      ├─ barra de la lista ──────────────────────┤  top: alto del TopNav
+ *      │  🔍 buscar…  ⚙3          1–80 / 187 ‹ ›  │
+ *      ├─ encabezado de la tabla ─────────────────┤  top: los dos de arriba
+ *      │  número │ cliente │ fecha │ total        │
+ *      ├──────────────────────────────────────────┤
+ *      │  …las filas, que sí se van…              │
+ *
+ *  **Ninguna de las tres tiene alto fijo.** El `TopNav` crece cuando envuelve;
+ *  la barra de la lista tiene dos renglones, o uno en compacto, o tres cuando
+ *  las fichas del buscador envuelven. Un `top-[52px]` escrito a mano acierta en
+ *  una ventana y deja un hueco o un solapamiento en las otras — y es la clase
+ *  de número que nadie vuelve a tocar cuando la barra cambia.
+ *
+ *  Por eso cada banda MIDE lo que ocupa y lo suma a `--sticky-top` para lo que
+ *  venga abajo. La variable cascadea, así que cada capa lee la de arriba sin
+ *  que ninguna sepa cuántas capas hay.
+ *
+ *  ── La regla del que abre una caja con scroll propio ────────────────
+ *
+ *  Adentro de una caja con alto y `overflow`, el que scrollea es la caja y no
+ *  la página, así que lo pegado se pega al borde de la caja: ahí la pila
+ *  arranca de cero otra vez. Eso es `stickyReset()`.
+ * ==================================================================== */
+/** La variable que dice a qué altura arranca lo próximo que se pegue. */
+export const STICKY_TOP = "--sticky-top";
+/** Lo que va en `style` de algo pegajoso: se pega debajo de lo que ya hay. */
+export const stickyTop = { top: `var(${STICKY_TOP}, 0px)` };
+/** Para una caja con scroll propio: adentro, la pila arranca de cero. */
+export function stickyReset() {
+    return { [STICKY_TOP]: "0px" };
+}
+/**
+ * LA CAJA DE UNA TABLA: cuándo tiene que ser un contenedor de scroll y cuándo no.
+ *
+ * Las tres tablas del sistema tienen el mismo dilema y lo resolvían con tres
+ * copias de la misma medición. El dilema es de CSS y no se puede esquivar:
+ * `overflow-x: auto` **obliga** a `overflow-y: auto` —la especificación dice que
+ * `visible` junto a un valor que no sea `visible` ni `clip` computa a `auto`—,
+ * así que en cuanto la caja permite scroll horizontal pasa a ser el scroller, y
+ * el encabezado pegajoso se pega a SU borde en vez de al de la página.
+ *
+ * De ahí salen los tres casos, y son los únicos:
+ *
+ *     alto propio      la caja scrollea de verdad. `auto`, y la pila de cosas
+ *                      pegadas arranca de cero adentro.
+ *     sin alto, entra  no hace falta ninguna caja. `clip` —recorta las esquinas
+ *                      redondeadas sin ser un scroller— y el encabezado se pega
+ *                      a la página, debajo de la barra de la lista.
+ *     sin alto, no entra   vuelve el scroll horizontal, y el encabezado se va
+ *                      con las filas. Es el precio, y es el que hay.
+ *
+ * Devuelve la clase y el estilo ya resueltos para que ninguna tabla vuelva a
+ * decidirlo por su cuenta.
+ */
+export function useScrollBox(options) {
+    const ref = useRef(null);
+    const crece = options.height === undefined || options.height === "auto";
+    const [desborda, setDesborda] = useState(false);
+    useLayoutEffect(() => {
+        const node = ref.current;
+        if (node === null || !crece)
+            return;
+        /* Se mide el CONTENIDO y no la caja, y es la diferencia entre que esto
+           funcione y que se trabe: con `overflow: clip` la caja deja de ser un
+           contenedor de scroll, así que su `scrollWidth` pasa a ser su propio ancho
+           y nunca volvería a reportar desborde. Una vez recortada, se quedaría
+           recortada para siempre. El hijo sí sabe cuánto mide de verdad. */
+        const dentro = node.firstElementChild;
+        const medir = () => {
+            const ancho = dentro === null ? node.scrollWidth : dentro.getBoundingClientRect().width;
+            setDesborda(ancho > node.clientWidth + 1);
+        };
+        medir();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(medir);
+        observer.observe(node);
+        /* También el contenido: las columnas cambian de ancho sin que la caja
+           cambie de tamaño. */
+        if (dentro !== null)
+            observer.observe(dentro);
+        return () => observer.disconnect();
+    }, [crece]);
+    const suelta = crece && !desborda;
+    return {
+        ref,
+        className: suelta ? "overflow-clip" : "overflow-auto",
+        style: suelta
+            ? {}
+            : {
+                ...(crece || options.height === undefined ? {} : { height: options.height }),
+                ...stickyReset(),
+            },
+    };
+}
+/**
+ * Mide el alto de un elemento y devuelve el estilo que empuja la pila para sus
+ * hermanos de abajo.
+ *
+ * `useLayoutEffect` y `ResizeObserver` y no un alto declarado: el alto depende
+ * de si las fichas del buscador envolvieron, y eso recién se sabe después de
+ * pintar.
+ */
+export function useStickyLayer() {
+    const ref = useRef(null);
+    const [top, setTop] = useState(0);
+    useLayoutEffect(() => {
+        const node = ref.current;
+        if (node === null)
+            return;
+        /* El valor de abajo se calcula en JS y se escribe en PÍXELES, no como
+           `calc(var(--sticky-top) + 44px)`. Context: esa forma parece la natural y
+           no funciona — poner `--sticky-top` en un elemento leyendo `var(--sticky-top)`
+           del MISMO elemento es un ciclo, CSS lo declara inválido, y los
+           descendientes heredan «nada»: todo se pegaba en 0 y las bandas se
+           superponían. Se midió en el navegador, no se dedujo. */
+        const measure = () => {
+            const inherited = Number.parseFloat(getComputedStyle(node).getPropertyValue(STICKY_TOP));
+            const above = Number.isFinite(inherited) ? inherited : 0;
+            setTop(above + node.getBoundingClientRect().height);
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(node);
+        /* La altura de una capa de ARRIBA cambia sin que este observador se entere
+           —el `TopNav` envuelve al angostar—, así que también se remide al cambiar
+           el tamaño de la ventana, que es cuando eso pasa. */
+        window.addEventListener("resize", measure);
+        return () => {
+            observer.disconnect();
+            window.removeEventListener("resize", measure);
+        };
+    }, []);
+    return {
+        ref,
+        self: stickyTop,
+        below: { [STICKY_TOP]: `${top}px` },
+    };
+}

package/dist/foundations/surface.d.ts

@@ -0,0 +1,9 @@
+import type { Surface } from "./types.js";
+import { type ReactNode } from "react";
+export declare function SurfaceProvider({ value, children, }: {
+    value: Surface;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useSurface(explicit?: Surface): Surface;
+/** Picks between two values according to the surface. The twin of `byDensity`. */
+export declare const bySurface: <T>(surface: Surface, canvas: T, chrome: T) => T;

package/dist/foundations/surface.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+/**
+ * Context: which surface whatever is inside is drawing on.
+ *
+ * It is a context and not a prop —the opposite of `Button`— for the same reason
+ * as density: a surface has to be UNIFORM inside. A chrome bar with a canvas
+ * search box inside is not a mix, it is a bug, and that happened: the status bar
+ * was drawn with the canvas palette on top of the navy because whoever put it
+ * there forgot to pass `surface="chrome"`.
+ *
+ * The pieces that live on both still accept it as a prop: the prop wins, and the
+ * context is only the default value. That way a one-off decision can be audited
+ * by reading the JSX, which is the system's rule for color.
+ */
+const Ctx = createContext("canvas");
+export function SurfaceProvider({ value, children, }) {
+    return _jsx(Ctx.Provider, { value: value, children: children });
+}
+export function useSurface(explicit) {
+    const inherited = useContext(Ctx);
+    return explicit ?? inherited;
+}
+/** Picks between two values according to the surface. The twin of `byDensity`. */
+export const bySurface = (surface, canvas, chrome) => surface === "chrome" ? chrome : canvas;