@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/primitives/table/EditableTable.d.ts

@@ -0,0 +1,191 @@
+import { type Grouping } from "../../foundations/grouping.js";
+import { type FlagProps } from "../notice/Flag.js";
+import { type ReactNode } from "react";
+/** Where a column goes when the row is drawn as a stacked card (a narrow box).
+ *  `trail` sits at the top right, beside the title — a state, the row's buttons. */
+export type StackPlace = "title" | "detail" | "amount" | "trail" | "hidden";
+/** How the rows are drawn: `auto` measures the box and stacks them below
+ *  `--container-handheld`; `table` and `stacked` force one — a side panel that is
+ *  always narrow, a test that has no box to measure. */
+export type EditLayout = "auto" | "table" | "stacked";
+export interface EditColumn<T> {
+    id: string;
+    header: string;
+    width?: number;
+    numeric?: boolean;
+    /** How the cell reads when the row is NOT being edited. */
+    render: (row: T) => ReactNode;
+    /** The control, when the row is being edited. Without this the column is read
+     *  only: an identifier or a computed value. Give the control an `aria-label`
+     *  (the column's name, or a longer one): a cell has no `Field` to name it, and
+     *  `Tab` through the row reads each control by that name. */
+    edit?: (row: T, set: (next: T) => void) => ReactNode;
+    /** Where the column goes in the stacked card, below `--container-handheld`. By
+     *  default the first column is the `title`, the last numeric one the `amount` and
+     *  the rest `detail`. `hidden` for what another column's `brief` already says. */
+    stack?: StackPlace;
+    /** How the column reads inside the card's detail line, when «header value» is not
+     *  the way to say it: «12 × Bs. 120,00» for a quantity, «desc. 10 %» for a
+     *  discount. `null` or `""` leaves it out of that row's line — a zero discount is
+     *  not news. Without it the line reads «<header> <cell>». */
+    brief?: (row: T) => ReactNode;
+    /** Drawn on section and note rows too, instead of being covered by their text — the
+     *  row's buttons. `render` receives the band's row. */
+    onBands?: boolean;
+}
+/** What a row that is not a line is. See «sections and notes» in the file's header. */
+export type EditBands<T> = {
+    /** `section` heads the lines under it; `note` is a sentence between lines; `null` is a
+     *  line. */
+    kind: (row: T) => "section" | "note" | null;
+    /** The band's text as it reads. */
+    render: (row: T) => ReactNode;
+    /** Its control while the row is edited — a text field, named. */
+    edit?: (row: T, set: (next: T) => void) => ReactNode;
+    /** What a section's lines add up to in `column`, already formatted; `null` where the
+     *  column does not add up. The lines are the ones under it until the next section. */
+    total?: (column: EditColumn<T>, lines: readonly T[]) => ReactNode | null;
+};
+/** One more way to add, beside «add a line»: a section, a note. */
+export type EditAdd = {
+    label: string;
+    /** As `onAdd`: return the new row's id and it opens. */
+    onAdd: () => string | void | Promise<string | void>;
+};
+/** The lines each section heads: the rows after it up to the next section. Notes do not
+ *  cut a section, and are not lines. */
+export declare function sectionLines<T>(rows: readonly T[], getRowId: (row: T) => string, kind: (row: T) => "section" | "note" | null): Map<string, T[]>;
+/**
+ * Where each column goes in the stacked card, defaults resolved: a declared `stack`
+ * wins; otherwise the first undeclared column is the title (unless one was declared),
+ * the last undeclared numeric one is the amount (unless one was declared), and the rest
+ * are detail.
+ */
+export declare function stackPlaces(columns: readonly {
+    stack?: StackPlace;
+    numeric?: boolean;
+}[]): StackPlace[];
+/** The first control of a row being edited: the first one in an editable cell, else
+ *  anything focusable in the row (a column without `edit` may still hold a button). */
+export declare function firstControl(row: HTMLElement): HTMLElement | null;
+/** Where `Tab` goes from the edge of an edited row: the next or previous row opened, a new
+ *  row added, or out of the table the browser's way. */
+export type TabTarget = {
+    kind: "row";
+    id: string;
+} | {
+    kind: "add";
+} | {
+    kind: "leave";
+};
+/**
+ * Where `Tab` past the last control (`next`) or `Shift+Tab` before the first (`prev`) of
+ * the edited row `from` goes, over the rows in the order they are drawn.
+ *
+ * Past the last row it adds one when the table can — unless `from` is itself a row just
+ * added and still blank: one more `Tab` there means «I am done», not «another blank line».
+ */
+export declare function tabTarget(order: readonly string[], from: string, direction: "next" | "prev", { canAdd, blank }: {
+    canAdd: boolean;
+    blank: boolean;
+}): TabTarget;
+export type RowKey = "ArrowDown" | "ArrowUp" | "Home" | "End";
+/**
+ * One body row. Its own component so that it can hold React Aria's `useKeyboard`
+ * (a hook per row) and the timer that decides whether the focus really left it.
+ * The same row is a `<tr>` in the table and an `<li>` in the stacked list — and the row
+ * of a new record in `DataTable`: one keyboard model, three shapes. Exported for that
+ * family sibling only; it is not in the barrel.
+ */
+export declare function EditRow({ as, rowId, rowRef, editable, editing, tabbable, className, onStart, onCommit, onCancel, onMove, onFocusRow, onTabOut, children, }: {
+    as: "tr" | "li";
+    rowId: string;
+    rowRef: (node: HTMLElement | null) => void;
+    editable: boolean;
+    editing: boolean;
+    tabbable: boolean;
+    className: string;
+    onStart: (viaKeyboard: boolean) => void;
+    onCommit: (refocus: boolean) => void;
+    onCancel: () => void;
+    onMove: (key: RowKey) => void;
+    onFocusRow: () => void;
+    /** `Tab` left the row by one of its edges. `true` = the table took it (opened another
+     *  row, added one); `false` = the browser moves the focus as usual. */
+    onTabOut: (direction: "next" | "prev") => boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A table whose rows are edited in place, one row at a time.
+ *
+ * Mouse: touching a row opens it. Keyboard: the rows are one tab stop, the arrows walk
+ * them, `Enter` / `F2` open one, `Tab` walks its controls, `Enter` commits and `Escape`
+ * puts the row back as it was; both return the focus to the row. Leaving the row
+ * (click outside, tabbing past its last control) commits.
+ *
+ * Narrower than `--container-handheld`, each row is a stacked card (see the file's
+ * header): the same keys, and `onOpen` —when given— instead of editing in place.
+ */
+export declare function EditableTable<T>({ rows, columns, getRowId, onChange, onRemove, onAdd, addLabel, 
+/** The footer with the aggregates, already formatted. `null` on the columns
+ *  that do not add up. Whoever composes computes it, because whoever composes
+ *  knows what adding up means in their domain —a percentage is not summed, it
+ *  is averaged. */
+totals, empty, grouping, 
+/** El total de una columna DENTRO de un montón, ya formateado. Lo calcula quien
+ *  compone, por el mismo motivo que `totals`: sumar significa cosas distintas
+ *  según el dominio, y un porcentaje se promedia, no se suma. */
+groupTotal, height, layout, onOpen, onDiscard, bands, adds, flag, }: {
+    rows: readonly T[];
+    columns: readonly EditColumn<T>[];
+    getRowId: (row: T) => string;
+    onChange?: (id: string, next: T) => void;
+    onRemove?: (id: string) => void;
+    /** «Add a line». Return the new row's id —or a promise of it, when the backend makes
+     *  the record— and the table opens that row with the focus on its first control.
+     *  Return nothing and the row just appears, closed. */
+    onAdd?: () => string | void | Promise<string | void>;
+    addLabel?: string;
+    totals?: readonly (ReactNode | null)[];
+    empty?: string;
+    /**
+     * El agrupado, con el mismo contrato que el resto de las vistas de datos.
+     *
+     * Editar y agrupar no se estorban: la fila que se edita sigue siendo una fila,
+     * y el montón sólo decide dónde cae. Lo que no se hereda es el orden — las
+     * filas de un montón quedan juntas, así que agregar una fila nueva la pone al
+     * final de todo y no adentro del montón que estabas mirando, que es el
+     * comportamiento honesto: todavía no tiene valor en el campo por el que se
+     * agrupa.
+     */
+    grouping?: Grouping<T>;
+    groupTotal?: (column: EditColumn<T>, rows: readonly T[]) => ReactNode | null;
+    /** A height of its own, as `Table`'s: the lines scroll inside the box and the header
+     *  sticks to its top. A number means pixels; a string goes through as is (`20rem`).
+     *  Without it the table grows with its lines and the header sticks to the page. */
+    height?: number | string;
+    /** `auto` (the default) stacks the rows as cards when the box is narrower than
+     *  `--container-handheld`; `table` and `stacked` force one. */
+    layout?: EditLayout;
+    /** Only in the stacked layout: pressing a card (or `Enter` / `F2` on it) calls this
+     *  instead of editing the row in place — for a consumer that edits the whole row in a
+     *  form of its own, a dialog that is a bottom sheet on a phone. The table ignores it:
+     *  there the row is edited where it is read. */
+    onOpen?: (id: string) => void;
+    /** Take back a row `onAdd` opened when it is abandoned: `Escape` on it, or leaving it
+     *  without a single change. Not `onRemove`: nobody removed a line, so there is nothing
+     *  to undo or to announce. Without it the blank row stays. */
+    onDiscard?: (id: string) => void;
+    /** Rows that are not lines: sections and notes. See the file's header. */
+    bands?: EditBands<T>;
+    /** More ways to add, drawn beside «add» under the grid: «add a section», «add a note». */
+    adds?: readonly EditAdd[];
+    /** A warning about one row — stock, a price under cost — drawn as a `Flag` at its start.
+     *  `null` for the rows with nothing to say, which should be most of them. `owner` is what
+     *  the record's activity says it belongs to («Línea 3 · Impresora…»); without it, the
+     *  row's first value. */
+    flag?: (row: T) => (Omit<FlagProps, "children"> & {
+        detail?: ReactNode;
+        owner?: string;
+    }) | null;
+}): import("react").JSX.Element;