@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/views/list/types.d.ts

@@ -0,0 +1,284 @@
+import type { ListIdentity } from "../../components/listing/ListingBar.js";
+import type { ListPresent } from "../../components/listing/set.js";
+import type { SortField } from "../../components/listing/SortMenu.js";
+import type { Grouping, GroupLevel } from "../../foundations/grouping.js";
+import type { Pivot, PivotKey, PivotSpec } from "../../foundations/pivot.js";
+import type { Surface, Tone } from "../../foundations/types.js";
+import type { DataColumn, DataTableCreate } from "../../primitives/table/DataTable.js";
+import type { ReportColumn, ReportRow } from "../../primitives/table/ReportTable.js";
+import type { RowAction } from "../../primitives/table/RowActions.js";
+import type { SheetColumn } from "../../primitives/table/SheetTable.js";
+import type { SortState } from "../../primitives/table/Table.js";
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+/**
+ * Las seis maneras de mirar un conjunto. La unión vive en `list/set.ts`, que
+ * es donde ya vivía su copia.
+ *
+ * Las seis son el MISMO conjunto mirado distinto, y por eso comparten barra.
+ * Lo que cambia entre ellas es qué sabe el código de las columnas — y, en el
+ * pivote, que las filas de la pantalla ya no son las filas del conjunto.
+ */
+export type { ListPresent };
+/** What an item looks like when the presentation is rows. */
+export type RowOf = {
+    icon?: LucideIcon;
+    name: string;
+    tags?: ReactNode;
+    meta?: string;
+    /** What this resource produced, hanging underneath. */
+    children?: ReactNode;
+    actions?: ReactNode;
+};
+/** A crumb of the list: where I came from. */
+export type ListCrumb = {
+    label: string;
+    onClick?: () => void;
+};
+export type ListEmpty = {
+    sentence: string;
+    action?: ReactNode;
+    /** Empty because of a filter is ANOTHER situation: content is not missing,
+     *  there is an extra narrowing. Telling «importá tus facturas» to someone who has 180
+     *  and mistyped a name is answering a different question. */
+    whenFiltered?: {
+        sentence: string;
+        action?: ReactNode;
+    };
+};
+/**
+ * El agrupado de una lista: el CONTRATO de `system/grouping.ts` más lo único que
+ * una tabla necesita de más.
+ *
+ * Las seis presentaciones parten el conjunto con el MISMO árbol y las mismas
+ * claves — la tabla incluida. Lo único que una tabla agrega es una pregunta de
+ * VISIBILIDAD: agrupar por un campo cuya columna está escondida dejaría montones
+ * cuyo criterio no se ve en ninguna parte, así que esa columna se repone, y para
+ * reponerla hay que saber cuál es. Eso es `columnOf`, y nada más: la clave del
+ * montón no sale de una columna.
+ *
+ * Va acá y no en el contrato para que una vista que no tenga columnas no tenga
+ * que fingir que las tiene.
+ */
+export type ListGroup<T extends object> = Grouping<T> & {
+    /** Qué COLUMNA contesta por cada nivel, para reponerla cuando está escondida.
+     *  Sin esto, la que se llame como el campo o la que lo declare en `field`. */
+    columnOf?: (level: GroupLevel) => string | undefined;
+};
+/**
+ * La PLANILLA de una lista: las columnas y cómo se lee cada celda.
+ *
+ * Se declara cuando las columnas salen del ARCHIVO y el código no sabe cuáles
+ * son. Para un conjunto de registros no hace falta: sale de las `columns` que
+ * la lista ya declaró.
+ */
+export type ListSheet<T> = {
+    columns: readonly SheetColumn[];
+    /** El valor de una celda. `null` es un faltante y `""` una celda vacía: son
+     *  cosas distintas y el motor las distingue, así que la interfaz también. */
+    cell: (item: T, column: SheetColumn, columnIndex: number) => string | number | null;
+    /** Qué celdas se pintan y con qué: un valor imputado, uno fuera de rango. */
+    tone?: (item: T, column: SheetColumn, columnIndex: number) => Tone | undefined;
+    note?: (item: T, column: SheetColumn, columnIndex: number) => string | undefined;
+    height?: number | "auto";
+    /** Qué dice la columna fija de la izquierda. Sin esto, el número de fila. */
+    rowLabel?: (item: T, index: number) => string;
+    /** Presente = la planilla se edita como planilla. Recibe el texto crudo;
+     *  convertirlo al tipo de la columna es del dominio, no de acá. */
+    onCommit?: (item: T, column: SheetColumn, columnIndex: number, next: string) => void;
+    editable?: (item: T, column: SheetColumn, columnIndex: number) => boolean;
+    /** Present = the sheet adds rows: «add a row» under it, and `Enter` on the last row.
+     *  The consumer appends the item; the sheet lands on it. Not while grouped. */
+    onAddRow?: () => void;
+};
+/**
+ * El INFORME de una lista: los períodos y la jerarquía que termina en totales.
+ *
+ * Las filas van aparte de `items` y es deliberado: un balance no es la lista
+ * plana agrupada —«Total Activos» es una suma de sumas— y el arquetipo no puede
+ * inventar esa jerarquía. La arma quien conoce el dominio, como ya arma
+ * `columns`.
+ */
+export type ListReport = {
+    columns: readonly ReportColumn[];
+    /**
+     * Las líneas del informe, cuando el DOMINIO las arma.
+     *
+     * Un balance no es la lista plana agrupada —«Total Activos» es una suma de
+     * sumas— y el arquetipo no puede inventar esa jerarquía.
+     *
+     * **Sin esto, el informe se arma con los montones**: cada nivel es una línea
+     * con sus agregados, y el más profundo son las filas. Es el mismo conjunto que
+     * ven las otras cuatro presentaciones, contado — que es lo que alguien espera
+     * al pasar de «tabla» a «informe» con dos niveles puestos.
+     */
+    rows?: readonly ReportRow[];
+    /** Qué grupos arrancan abiertos. Por omisión ninguno: un balance con todo
+     *  desplegado son cuatrocientas líneas y lo que se mira primero son los
+     *  totales. */
+    defaultOpen?: readonly string[];
+    height?: number;
+};
+/**
+ * El PIVOTE de una lista: los dos ejes y las medidas que se pliegan en el cruce.
+ *
+ * Es la presentación en la que **las filas de la pantalla dejan de ser los
+ * registros**: una fila es un montón y una columna también, así que no hay nada
+ * que elegir ni que abrir, y lo que se lee está en el cruce.
+ *
+ * De ahí que venga plegado de dos lugares posibles, igual que los montones de
+ * una lista agrupada:
+ *
+ *     folded   lo plegó quien guarda los datos. Es el caso normal en cuanto el
+ *              conjunto no entra en el navegador: contar 187 vencidas no lo
+ *              pueden contestar las doce filas que se bajaron.
+ *     spec     lo pliega esta máquina, con las filas en la mano.
+ *
+ * Los dos dibujan igual porque dibujan el mismo tipo.
+ */
+export type ListPivot<T> = {
+    /** El pivote ya plegado. Gana sobre `spec` cuando están los dos: si alguien
+     *  con el conjunto entero ya contestó, no hay nada que recalcular. */
+    folded?: Pivot;
+    /**
+     * Cómo armarlo acá adentro. Las medidas traen su pliegue, y los márgenes salen
+     * de la BASE y no de sumar celdas — ver `system/pivot.ts`.
+     *
+     * Quien además necesite la grilla EN LA MANO —para bajarla como planilla con
+     * `downloadPivot`, por ejemplo— la pliega él con `pivotFrom` y la pasa por
+     * `folded`: así la que se dibuja y la que se baja son el mismo objeto, y no
+     * dos que podrían no coincidir.
+     */
+    spec?: PivotSpec<T>;
+    /** Qué pasa al tocar un cruce: abrir las filas que cayeron ahí. */
+    onCell?: (row: PivotKey, column: PivotKey) => void;
+    height?: number | string;
+};
+export type ListViewProps<T extends object> = {
+    items: readonly T[];
+    keyOf: (item: T) => string;
+    identity?: ListIdentity;
+    /** Where I came from. It goes above the bar, and only when the bar is chrome. */
+    crumbs?: readonly ListCrumb[];
+    /** The metrics that also NARROW: «2 por confirmar», «41 por entregar». They go
+     *  below the bar and above the rows — they belong to the set, not to the frame. */
+    metrics?: ReactNode;
+    /** The list is a FIELD of a record (a one2many / many2many) and not a screen: the bar
+     *  is one line — search, count, sort, columns, switcher, actions —, it does not stick
+     *  and it does not move into the frame's header. Identity and crumbs are not drawn: the
+     *  record around it already says them. See `ListingBar`'s header. */
+    embedded?: boolean;
+    /** Which surface the BAR sits on. `canvas` (the default) is a light control bar;
+     *  `chrome` turns it into a dark band — an explicit choice, since the application bar
+     *  is the screen's one dark band (same as the rail of a record). */
+    surface?: Surface;
+    /** The search field, already assembled. It is assembled by whoever holds the
+     *  domain declarations — the system does not know what a provenance is. */
+    search?: ReactNode;
+    pagination?: ReactNode;
+    /** Escape hatch: a custom switcher. Prefer `presents` so the archetype draws it. */
+    views?: ReactNode;
+    actions?: ReactNode;
+    row: (item: T) => RowOf;
+    /**
+     * Los rótulos de las zonas de una fila, arriba de todas. Sin esto no hay
+     * encabezado: `rows` no es una tabla y no toda lista tiene algo que rotular
+     * —una lista de cinco archivos con el nombre y nada más no lo necesita.
+     *
+     * No son columnas. Una fila tiene un nombre, UNA cadena de `meta` ya
+     * formateada y una columna de fichas: eso es lo que se rotula, y por eso los
+     * rótulos los escribe la vista y no salen de `columns`.
+     */
+    rowHeader?: {
+        name: string;
+        meta?: string;
+        tags?: string;
+    };
+    /** The table presentation. With this, `present="table"` draws a `DataTable`. */
+    columns?: readonly DataColumn<T>[];
+    /** Which table columns are on screen. Required columns stay even if omitted.
+     *  Owned by the view when omitted — catalog filters must not reset them. */
+    visibleColumnIds?: readonly string[];
+    onVisibleColumnIdsChange?: (ids: readonly string[]) => void;
+    /** The sorting of the table. It lives outside because it belongs to the SET
+     *  and not to the presentation: switching from table to rows has no reason to
+     *  lose it. */
+    sort?: SortState | null;
+    onSortChange?: (next: SortState | null) => void;
+    /**
+     * Por qué campos se puede ordenar, para las presentaciones que NO tienen
+     * encabezados donde hacer clic.
+     *
+     * Sin esto, ordenar existe sólo en la tabla — y entonces pasar a filas o a
+     * tablero no pierde el orden puesto, pierde la posibilidad de ordenar. La
+     * tabla sigue teniendo además sus encabezados: son dos puertas a lo mismo, y
+     * la de los encabezados es más rápida donde existe.
+     */
+    sortable?: readonly SortField<T>[];
+    /** The footer with the aggregates of the columns that declared one. */
+    totals?: boolean;
+    /** What gets done to ONE row without entering it, in the table presentation.
+     *  They are drawn hidden and appear on the row being pointed at. */
+    rowActions?: (item: T) => readonly RowAction[];
+    /** Write a new record as a row of the table presentation — Odoo's editable list. The
+     *  columns that declare `input` get a control in that row. See `DataTable`'s header.
+     *  While a record is being written the table shows even if the set is empty. */
+    create?: DataTableCreate<T>;
+    /** The board presentation. */
+    card?: (item: T) => ReactNode;
+    /**
+     * La PLANILLA. Con esto, `present="sheet"` dibuja un `SheetTable`.
+     *
+     * Es la presentación de los datos crudos, y por eso no recibe `DataColumn`:
+     * las columnas salen del archivo y el código no sabe cuáles son ni cuántas.
+     * El valor se pide por índice —igual que `SheetTable`, que está virtualizado—
+     * así que un millón de filas no se copia a ninguna otra estructura.
+     */
+    sheet?: ListSheet<T>;
+    /**
+     * El INFORME: una jerarquía que termina en totales. Con esto,
+     * `present="report"` dibuja un `ReportTable`.
+     *
+     * Las filas van aparte de `items` y es deliberado: un balance NO es la lista
+     * plana agrupada —«Total Activos» no es un montón de cuentas, es una suma de
+     * sumas— y el arquetipo no puede inventar esa jerarquía a partir del
+     * conjunto. La arma quien conoce el dominio, como ya arma `columns`.
+     */
+    report?: ListReport;
+    /**
+     * El PIVOTE: dos ejes a la vez. Con esto, `present="pivot"` dibuja un
+     * `PivotTable`.
+     *
+     * Va aparte de `group` y no derivado de él aunque los dos partan el conjunto,
+     * porque un pivote parte por DOS ejes y una lista agrupada por uno: los
+     * niveles de `group` no dicen cuál de ellos sería el eje horizontal, y
+     * elegirlo acá sería adivinar la pregunta.
+     */
+    pivot?: ListPivot<T>;
+    present?: ListPresent;
+    /** Which presentations this list offers. Two or more draw the switcher. */
+    presents?: readonly ListPresent[];
+    onPresentChange?: (next: ListPresent) => void;
+    group?: ListGroup<T>;
+    selection?: {
+        has: (id: string) => boolean;
+        toggle: (id: string) => void;
+        count: number;
+        clear: () => void;
+        actions?: ReactNode;
+    };
+    onOpen?: (item: T) => void;
+    onPeek?: (item: T) => void;
+    isPeeked?: (item: T) => boolean;
+    /** The three states, in a single place. Every view used to re-assemble them
+     *  with three nested ternaries, and that is why «empty because of a filter»
+     *  and «really empty» got mixed up in half the screens. */
+    state?: {
+        loading?: boolean;
+        error?: string | null;
+    };
+    filtered?: boolean;
+    empty?: ListEmpty;
+    /** The escape hatch. */
+    children?: ReactNode;
+};

package/dist/views/list/types.js

@@ -0,0 +1 @@
+export {};

package/dist/views/list/useNarrowList.d.ts

@@ -0,0 +1,17 @@
+import type { ListPresent } from "../../components/listing/set.js";
+import { type RefObject } from "react";
+/**
+ * A narrow LIST — a phone, a drawer, a panel among four — does not offer the presentations
+ * that need width: a seven-column table at 360 px is a horizontal scroll nobody reads.
+ * There the list shows rows (a stacked card per record: the name, its state, its facts)
+ * and the board, and the switcher offers only those. It is the width of the list's own
+ * container that decides, not the window's: a narrow panel on a wide screen is narrow.
+ *
+ * Attach `frame` to the list's root element; `offered` is what the switcher may show and
+ * `present` what to draw (a wide one that was asked for falls back to rows).
+ */
+export declare function useNarrowList(presents: readonly ListPresent[] | undefined, requested: ListPresent): {
+    frame: RefObject<HTMLDivElement | null>;
+    offered: readonly ListPresent[];
+    present: ListPresent;
+};

package/dist/views/list/useNarrowList.js

@@ -0,0 +1,32 @@
+"use client";
+import { HANDHELD_WIDTH } from "../../foundations/layout.js";
+import { WIDE_PRESENTS } from "./columns.js";
+import { useEffect, useRef, useState } from "react";
+/**
+ * A narrow LIST — a phone, a drawer, a panel among four — does not offer the presentations
+ * that need width: a seven-column table at 360 px is a horizontal scroll nobody reads.
+ * There the list shows rows (a stacked card per record: the name, its state, its facts)
+ * and the board, and the switcher offers only those. It is the width of the list's own
+ * container that decides, not the window's: a narrow panel on a wide screen is narrow.
+ *
+ * Attach `frame` to the list's root element; `offered` is what the switcher may show and
+ * `present` what to draw (a wide one that was asked for falls back to rows).
+ */
+export function useNarrowList(presents, requested) {
+    const frame = useRef(null);
+    const [narrow, setNarrow] = useState(false);
+    useEffect(() => {
+        const el = frame.current;
+        if (el === null || typeof ResizeObserver === "undefined")
+            return;
+        const watch = new ResizeObserver(([entry]) => {
+            if (entry !== undefined)
+                setNarrow(entry.contentRect.width < HANDHELD_WIDTH);
+        });
+        watch.observe(el);
+        return () => watch.disconnect();
+    }, []);
+    const offered = (presents ?? []).filter((p) => !narrow || !WIDE_PRESENTS.includes(p));
+    const present = narrow && WIDE_PRESENTS.includes(requested) ? "rows" : requested;
+    return { frame, offered, present };
+}

package/dist/views/record/Record.d.ts

@@ -0,0 +1,145 @@
+import { type ActivityProps } from "../../components/activity/Activity.js";
+import { type SheetField, type SheetLayout } from "../../components/form/Sheet.js";
+import type { Crumb } from "../../components/record/Breadcrumb.js";
+import type { DirtyState } from "../../components/record/DirtyActions.js";
+import { type RecordNoticeSpec } from "../../components/record/RecordNotices.js";
+import { RecordSkeleton } from "../../components/record/RecordSkeleton.js";
+import { type Stage } from "../../components/record/StatusBar.js";
+import type { Surface, Tone } from "../../foundations/types.js";
+import { type TabNotice } from "../../primitives/tabs/Tabs.js";
+import type { LucideIcon } from "lucide-react";
+import { type ReactNode } from "react";
+export type RecordIdentity = {
+    icon?: LucideIcon;
+    title: ReactNode;
+    /** Who or what it is about, under the title — the customer of an invoice, the
+     *  supplier of an order. Second in the hierarchy: bigger than a fact, smaller than
+     *  the title. */
+    subtitle?: ReactNode;
+    tag?: {
+        label: string;
+        tone?: Tone;
+    };
+    /** THE figure of the record — the total of an invoice, the balance of an account —
+     *  drawn as large as the title, on the right. A record usually has one number people
+     *  open it for; set among the facts at body size it is just another fact. */
+    figure?: {
+        label: string;
+        value: ReactNode;
+    };
+};
+/** What hangs off the record. It leads somewhere else; it is not a datum. */
+export type SmartLink = {
+    icon: LucideIcon;
+    count?: number;
+    label: string;
+    onClick?: () => void;
+};
+/** My place in the set I came from. Not pagination: it says I can move to the
+ *  next one without going back to the list. */
+export type RecordPager = {
+    index: number;
+    total: number;
+    onPrev?: () => void;
+    onNext?: () => void;
+};
+export type { SheetField };
+/** A notice of the record: the props of `Record.Notice` (a `Callout` without its × label,
+ *  which the record writes from the copy table). */
+export type RecordNotice = RecordNoticeSpec;
+type RailProps = {
+    children?: ReactNode;
+    /** The rail's surface. `canvas` (the default) is a light control bar; `chrome` is the dark
+     *  band, an explicit choice. The application bar is the screen's one dark band — a dark
+     *  rail under it reads as two headers and the record loses its top. */
+    surface?: Surface;
+};
+type CrumbsProps = {
+    crumbs: readonly Crumb[];
+};
+type SmartProps = {
+    links: readonly SmartLink[];
+};
+type ActionsProps = {
+    children?: ReactNode;
+};
+type StatusProps = {
+    stages?: readonly Stage[];
+    /** Cuál de las etapas es la de ahora. Sin esto, la primera. */
+    current?: string;
+    failed?: boolean;
+    /** La escotilla del estado, para lo que no es ninguna de las dos. */
+    children?: ReactNode;
+};
+type PaperProps = {
+    /** Cómo ponen la etiqueta los campos de adentro. `horizontal` es etiqueta |
+     *  valor, que es la forma de Odoo. */
+    layout?: SheetLayout;
+    columns?: 1 | 2 | 3 | 4;
+    children?: ReactNode;
+};
+type FactsProps = {
+    fields: readonly SheetField[];
+};
+type PagesProps = {
+    current?: string;
+    onChange?: (id: string) => void;
+    children?: ReactNode;
+};
+type PageProps = {
+    id: string;
+    label: string;
+    /** La marca de la cara. Con tres o más pestañas, el ícono es lo que se
+     *  reconoce sin leer. */
+    icon?: LucideIcon;
+    /** Cuántas cosas hay detrás. `0` se dibuja apagado: «no hay ninguna» es una
+     *  respuesta, y esconderla obliga a abrir la pestaña para averiguarla. */
+    count?: number;
+    /** Que algo de esta cara PIDE que lo mires — falló, cambió, llegó. Aparte del
+     *  contador, porque son dos preguntas: ver `TabNotice`. */
+    notice?: TabNotice;
+    children?: ReactNode;
+};
+/** The record's ACTIVITY panel, as DATA: its conversation, its history, its composer.
+ *  The record draws the `Activity` itself and gives it what only the record has — its
+ *  notices (the ones that are not blocking), and the indicator in the rail that opens the
+ *  panel on them.
+ *
+ *  Context: it was `<Record.Chatter><Chatter open onToggle …/></Record.Chatter>`, a node
+ *  the record could only place. Written as data — like `Record.Status` — the record owns
+ *  the panel's open state (`defaultOpen`, or `open` + `onOpenChange` to control it), so
+ *  «⚠ 2 avisos» in the rail can open it and move the focus to its notices. */
+export type RecordActivityProps = Omit<ActivityProps, "open" | "onToggle" | "alerts" | "alertsId"> & {
+    /** Starts OPEN unless this says otherwise: on a big screen you see what the record has. */
+    defaultOpen?: boolean;
+    /** Controls the panel: then `onOpenChange` must follow it. Remembering it between
+     *  records is the app's — the system only reports. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+};
+export type RecordProps = {
+    identity: RecordIdentity;
+    /** Lo que falló al operar sobre el registro. Va con los avisos que bloquean, primero:
+     *  entre el riel y el papel, siempre a la vista (ver `Record.Notice`). */
+    error?: string | null;
+    /** Hay cambios sin guardar. Su presencia REEMPLAZA los botones de acción por
+     *  guardar y descartar — ver la nota en `RecordHeader`. */
+    dirty?: DirtyState;
+    children?: ReactNode;
+};
+export declare function Record({ identity, error, dirty, children }: RecordProps): import("react").JSX.Element;
+export declare namespace Record {
+    var Skeleton: typeof RecordSkeleton;
+    var Rail: ((props: RailProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"rail">;
+    var Crumbs: ((props: CrumbsProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"crumbs">;
+    var Pager: ((props: RecordPager) => ReactNode) & import("../../foundations/slots.js").Slotted<"pager">;
+    var Smart: ((props: SmartProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"smart">;
+    var Actions: ((props: ActionsProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"actions">;
+    var Status: ((props: StatusProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"status">;
+    var Paper: ((props: PaperProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"paper">;
+    var Activity: ((props: RecordActivityProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"activity">;
+    var Facts: ((props: FactsProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"facts">;
+    var Pages: ((props: PagesProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"pages">;
+    var Page: ((props: PageProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"page">;
+    var Notice: ((props: RecordNoticeSpec) => ReactNode) & import("../../foundations/slots.js").Slotted<"notice">;
+}