@bettercms-ai/kit 0.1.0 → 1.0.0

package/schema/table.d.ts

@@ -0,0 +1,319 @@
+/**
+ * TABLE — the first-class `table` value of the schema language (CPO D42, SCHEMA_GAPS gap 12).
+ *
+ * One model, three places: a Table block on a page, a table island inside rich text, a Table block inside a slot.
+ * One renderer: `renderTableHtml()` writes the semantic HTML every surface shows (site canvas, Journal body, published
+ * preview, stored rich text); `<TableView>` (src/components/table) wraps it for live pages with visitor sort/filter.
+ *
+ * Why this shape (vs. Sanity's rows › cells › value, Storyblok's thead/tbody strings, Prismic's head/body):
+ *  - Columns are TYPED and KEYED (`_key`). Cells are keyed by column key, so reordering a column never misaligns a row.
+ *  - A cell is a bare value (string, number, boolean, link, reference) or `{ value, type?, note? }` when it needs a
+ *    per-cell type (a "limit" in a boolean pricing column) or a footnote.
+ *  - Header row + optional header column (row headers), column groups (`colgroup` headers), row groups (`tbody` with a
+ *    `rowgroup` header), footer rows (`tfoot`), caption (required), notes, footnotes. Body cells never merge: merged body
+ *    cells break sorting, Markdown and screen readers. Only group headers span (`colspan` + `scope="colgroup"`).
+ *
+ * Stored rich-text form (lossless, so the HTML IS the model — no JSON blob to drift):
+ *   <figure data-rt="table" data-id data-header-row data-header-col data-responsive data-sticky data-filter data-jsonld…>
+ *     <table aria-describedby="…-notes">
+ *       <caption>…</caption>
+ *       <colgroup><col data-key data-type data-unit data-currency …></colgroup>
+ *       <thead>[<tr data-groups><th scope="colgroup" colspan data-group>…</th>…</tr>]<tr><th scope="col" data-col>…</th>…</tr></thead>
+ *       <tbody [data-key data-label]>[<tr data-group-row><th scope="rowgroup" colspan>…</th></tr>]
+ *         <tr data-key><th scope="row" data-col>…</th><td data-col data-label [data-value] [data-type] [data-note]>…</td></tr></tbody>
+ *       <tfoot>…</tfoot>
+ *     </table>
+ *     <p data-notes id="…-notes">…</p><ol data-footnotes><li id="…-fn-1" data-key>…</li></ol>
+ *   </figure>
+ * Pure string work (no DOM) except `parseTableElement`, which reads a DOM element (ours or any site's).
+ */
+export type TableColumnType = "text" | "number" | "money" | "boolean" | "rating" | "link" | "richtext-inline" | "reference";
+export declare const TABLE_COLUMN_TYPES: {
+    value: TableColumnType;
+    label: string;
+    description: string;
+}[];
+export interface TableColumn {
+    _key: string;
+    /** Header text (plain). Required when the header row is on. */
+    label: string;
+    type: TableColumnType;
+    /** Explains the column; written as the header's title and in the notes of the Markdown twin. */
+    description?: string;
+    /** number: unit after the value ("kg", "%", "min"). */
+    unit?: string;
+    /** money: ISO 4217 code. Default USD. */
+    currency?: string;
+    /** number / money: fixed decimals. */
+    decimals?: number;
+    /** Default: numbers, money and ratings align end, everything else start (WAI: right-align numbers). */
+    align?: "start" | "center" | "end";
+    /** Visitors may sort by this column (live pages only). */
+    sortable?: boolean;
+    /** Column group key (a spanning header above this column). */
+    group?: string;
+    /** boolean: what the words say. Defaults "Included" / "Not included". */
+    trueLabel?: string;
+    falseLabel?: string;
+    /** rating: scale. Default 5. */
+    max?: number;
+    /** reference: allowed targets (collection ids or "page"). */
+    refTo?: string[];
+    /** Tint the column (the recommended plan). Visual only. */
+    highlight?: boolean;
+}
+export interface TableGroup {
+    _key: string;
+    label: string;
+}
+export interface TableLink {
+    label: string;
+    href: string;
+    /** set by the global link element (D57) */
+    newTab?: boolean;
+    rel?: "follow" | "nofollow" | "ugc" | "sponsored";
+}
+export interface TableRef {
+    ref: string;
+    label?: string;
+    href?: string;
+}
+export type TableCellValue = string | number | boolean | null | TableLink | TableRef;
+export interface TableCellObject {
+    value: TableCellValue;
+    /** Per-cell type (wins over the row's and the column's). */
+    type?: TableColumnType;
+    /** Footnote key. */
+    note?: string;
+    /**
+     * The body's own footnote markers after the cell's text (`<sup data-footnote="key">n</sup>`, a rich-text table's),
+     * kept as written: the table editor does not edit them, and the cell writes them back after its text.
+     */
+    marks?: string;
+}
+export type TableCell = TableCellValue | TableCellObject;
+export interface TableRow {
+    _key: string;
+    cells: Record<string, TableCell | undefined>;
+    /** Row group key. */
+    group?: string;
+    /** Totals / summary rows → <tfoot>. */
+    footer?: boolean;
+    /** Per-row type: pricing matrices mix yes/no rows with limit rows in the same plan columns. */
+    type?: TableColumnType;
+    /** Tint the row (the bestseller). Visual only — say WHY in a footnote, colour alone means nothing to a reader. */
+    highlight?: boolean;
+}
+export interface TableFootnote {
+    _key: string;
+    text: string;
+}
+export type TableResponsive = "scroll" | "stack" | "cards";
+export type TableJsonLdType = "none" | "ItemList" | "Dataset" | "Offers";
+export interface TableValue {
+    /** Stable id for anchors (footnotes, aria). */
+    id?: string;
+    /** What the table shows. Required: it names the table for screen readers, crawlers and AI answers. */
+    caption: string;
+    /** One or two sentences under the table: source, method, date. Linked with aria-describedby. */
+    notes?: string;
+    headerRow: boolean;
+    /** First column holds row headers (th scope=row). */
+    headerColumn: boolean;
+    columns: TableColumn[];
+    columnGroups?: TableGroup[];
+    rowGroups?: TableGroup[];
+    rows: TableRow[];
+    footnotes?: TableFootnote[];
+    /** Visitor UI on live pages: a filter box above the table. */
+    filterable?: boolean;
+    /** hideCaption: the caption stays in the HTML (screen readers, crawlers) but isn't drawn — when a heading above says it. */
+    design?: {
+        responsive?: TableResponsive;
+        sticky?: boolean;
+        striped?: boolean;
+        density?: "compact" | "comfortable";
+        hideCaption?: boolean;
+    };
+    /** Structured data from the table. Off by default: JSON-LD must describe what the page really offers. */
+    jsonLd?: {
+        type: TableJsonLdType;
+        axis?: "rows" | "columns";
+        priceRow?: string;
+    };
+}
+/** Field-level settings (`FieldSchema.table`). */
+export interface TableFieldOptions {
+    /** Column types an editor may choose. Default: all. */
+    columnTypes?: TableColumnType[];
+    /** Developer-defined columns: editors fill rows but can't add, remove, retype or reorder columns. */
+    lockColumns?: boolean;
+    minRows?: number;
+    maxRows?: number;
+    maxColumns?: number;
+    /** Default true. */
+    requireCaption?: boolean;
+    /** Row groups: "Add group" in the row list. Default true. */
+    allowGroups?: boolean;
+    /** Footnotes on cells, edited at the cell. Default true. */
+    allowFootnotes?: boolean;
+    /**
+     * CPO D52: what Table settings offers. Each key turns one setting on or off for this table kind, so the editor only sees
+     * what applies. Defaults: header row + first column, totals row, on phones (all three), highlight column ON; visitor
+     * sort and search OFF; JSON-LD only when `jsonLd` lists types.
+     */
+    settings?: TableSettingsOptions;
+    /** "Note under the table" (the source line, `notes`). Default true. Turn off when the block has its own source field. */
+    allowNote?: boolean;
+    /** JSON-LD types offered in Table settings ("Help search engines read this as"). Default: none offered. */
+    jsonLd?: TableJsonLdType[];
+}
+/**
+ * CPO D52: a table with no `table` options (a rich-text table, the Visuals Table block, a schema field without `table`) is a
+ * general table of any kind, so every setting is offered. Setting `table` on a field narrows it to that kind.
+ */
+export declare const GENERAL_TABLE: TableFieldOptions;
+/** CPO D52: the settings a table kind offers (`FieldSchema.table.settings`). */
+export interface TableSettingsOptions {
+    /** "Show column names" (header row) and "First column names each row" (row headers). Default true. */
+    headers?: boolean;
+    /** "Totals row": a footer row group at the end of the row list. Default true. */
+    totals?: boolean;
+    /** "On phones": the layouts offered. Default all three; one value fixes it, [] hides the setting. */
+    phones?: TableResponsive[];
+    /** "Highlight column": one column stands out (the recommended plan, your product). Default true. */
+    highlight?: boolean;
+    /** "Keep column names in view" (developer-only, `design.sticky`). Default true; off when the block owns a sticky-header field. */
+    sticky?: boolean;
+    /** "Visitors can sort columns". Default false (data tables turn it on). */
+    sort?: boolean;
+    /** "Visitors can search rows". Default false (long data tables turn it on). */
+    search?: boolean;
+}
+export declare const tkey: (p: string) => string;
+export declare function emptyTable(cols?: number, rows?: number): TableValue;
+export declare const isObjLike: (v: unknown) => v is Record<string, unknown>;
+export declare const isCellObject: (c: unknown) => c is TableCellObject;
+export declare const isTableValue: (v: unknown) => v is TableValue;
+/** Repair anything loaded (missing keys, missing arrays) so editors and renderers can trust the shape. */
+export declare function normalizeTable(v: unknown): TableValue;
+export declare const cellValue: (c: TableCell | undefined) => TableCellValue;
+export declare const cellNote: (c: TableCell | undefined) => string | undefined;
+export declare const cellType: (col: TableColumn, row?: TableRow, c?: TableCell) => TableColumnType;
+/** Write a value back, keeping the cell's per-cell type and footnote. */
+export declare function withValue(c: TableCell | undefined, value: TableCellValue): TableCell;
+export declare const isEmptyCell: (v: TableCellValue) => boolean;
+export declare function boolLabels(col: TableColumn): {
+    yes: string;
+    no: string;
+};
+export declare function formatNumber(n: number, decimals?: number): string;
+export declare function formatMoney(n: number, currency?: string, decimals?: number): string;
+export declare const toNumber: (v: unknown) => number | null;
+/** The words a cell says, for Markdown, CSV, sorting, search and screen readers. Empty → "". */
+export declare function cellText(col: TableColumn, row: TableRow | undefined, c: TableCell | undefined, resolveRef?: RefResolver): string;
+export declare function toBool(v: unknown): boolean | null;
+export type RefResolver = (id: string) => {
+    label: string;
+    href?: string;
+} | undefined;
+export interface RenderOptions {
+    /** Resolve reference cells to their current label + URL. */
+    resolveRef?: RefResolver;
+    /** Live-page visitor UI: sortable headers become buttons with aria-sort. Never stored. */
+    sort?: {
+        key: string;
+        dir: 1 | -1;
+    } | null;
+    interactive?: boolean;
+    /** Rows to show (filter). Keys. */
+    visibleRows?: Set<string>;
+    /** Write the editing marks (`data-*` model attributes). Off for clean published HTML. Default true. */
+    marks?: boolean;
+}
+/** Inline rich text in a cell: only inline marks and safe links survive (string-based, no DOM). */
+export declare function sanitizeInline(html: string): string;
+/** Rows in display order: body rows (ungrouped first, then each row group in its order), footer rows. */
+export declare function orderedRows(t: TableValue): {
+    bodies: {
+        group?: TableGroup;
+        rows: TableRow[];
+    }[];
+    foot: TableRow[];
+};
+/** Sort comparator over a column (numbers numerically, booleans true first, text by locale). */
+export declare function sortRows(t: TableValue, rows: TableRow[], key: string, dir: 1 | -1): TableRow[];
+/** The table as semantic HTML: <figure data-rt="table"> › <table> (caption, colgroup, thead, tbody…, tfoot) + notes. */
+export declare function renderTableHtml(input: TableValue, o?: RenderOptions): string;
+/**
+ * GFM has one header row and no spans, so: column groups prefix their columns ("Sizes · Chest"), row groups become a
+ * bold label row, the caption is a bold line above, notes and footnotes follow. Booleans say their words, never ✓.
+ */
+export declare function tableToMarkdown(input: TableValue, o?: {
+    resolveRef?: RefResolver;
+    abs?: (href: string) => string;
+}): string;
+/** RFC 4180 parser; the delimiter is a tab when the text has one (Excel / Sheets copy), else `;` or `,` by count. */
+export declare function parseDelimited(text: string, delim?: string): string[][];
+export declare function toDelimited(rows: string[][], delim?: string): string;
+/** Header + body rows as text (CSV export, "Copy as CSV"). */
+export declare function tableToRows(input: TableValue, resolveRef?: RefResolver): string[][];
+export interface InferredColumn {
+    type: TableColumnType;
+    unit?: string;
+    currency?: string;
+    max?: number;
+}
+/** Look at a column's non-empty values and pick the narrowest type every value fits. */
+export declare function inferColumn(values: string[]): InferredColumn;
+/** A raw string (CSV / paste / HTML cell) → a value of `type`. */
+export declare function coerce(raw: string, col: Pick<TableColumn, "type" | "max">): TableCellValue;
+/** Text rows (CSV, TSV, a pasted range) → a table. `header`: first row holds the column labels. */
+export declare function tableFromRows(rows: string[][], opts?: {
+    header?: boolean;
+    caption?: string;
+}): TableValue;
+/** Paste a text range into a table at (row, col), growing rows / columns as needed. Values coerce to column types. */
+export declare function pasteRange(input: TableValue, at: {
+    row: number;
+    col: number;
+}, grid: string[][], opts?: {
+    lockColumns?: boolean;
+}): TableValue;
+/**
+ * Read a DOM <table> (or our <figure data-rt="table">) into the model. Our own data-* marks round-trip losslessly;
+ * any other table is inferred: header rows from thead / th, row headers from tbody th[scope=row] or a th first cell,
+ * caption from <caption> / figcaption / aria-label, groups from thead colspans and multiple <tbody> / rowgroup rows,
+ * footer from <tfoot>, types from cell text (✓/✗ → boolean, $ → money, 4.5/5 → rating), footnote marks kept as notes.
+ * Body cells with colspan/rowspan are expanded (copied) — the model has no merged body cells.
+ */
+export declare function parseTableElement(el: Element): TableValue;
+/**
+ * Dataset  — a report or spec table (name = caption, description = notes, variableMeasured = columns).
+ * ItemList — a comparison: the things compared (row headers, or column labels) in order.
+ * Offers   — a pricing matrix: one Offer per plan (columns), price from the money row `priceRow`.
+ * Returns null when the table can't honestly support the type (no caption, no items, no prices).
+ */
+export declare function tableJsonLd(input: TableValue, o?: {
+    url?: string;
+    resolveRef?: RefResolver;
+}): Record<string, unknown> | null;
+export interface TableIssue {
+    level: "error" | "warning";
+    message: string;
+    /** where: "caption" · "col:<key>" · "row:<key>" · "cell:<row>:<col>" */
+    at?: string;
+}
+export declare function tableIssues(input: unknown, opts?: TableFieldOptions): TableIssue[];
+/** "4 rows × 3 columns" (array rows, summaries, breadcrumbs). */
+export declare function tableSummary(v: unknown): string;
+/** Build a table in code (seed data, Kit Library, migrations): header labels + rows of display strings. */
+export declare function tableFrom(caption: string, columns: (Partial<TableColumn> & {
+    label: string;
+})[], rows: (TableCell[] | {
+    cells: TableCell[];
+    group?: string;
+    footer?: boolean;
+    type?: TableColumnType;
+    highlight?: boolean;
+})[], extra?: Partial<Omit<TableValue, "columns" | "rows" | "caption">>): TableValue;