@verdify/ui 0.1.0

package/dist/components/data-grid/data-grid.d.ts

@@ -0,0 +1,247 @@
+import * as React from "react";
+import { type DataGridCellVariantProps } from "./data-grid.variants";
+/** Row density (spec §3): `comfortable` (default) for read-and-act screens, `compact` for dense consoles. */
+export type DataGridDensity = "comfortable" | "compact";
+/** Selection model (spec §3): `none` (read-only) or `multiple` (adds the selection cell, select-all, and bulk bar). */
+export type DataGridSelection = "none" | "multiple";
+/** A status cell's reported state (spec §3/§4): a status color appears only inside a cell that reports a real state, paired with text. */
+export type DataGridCellStatus = NonNullable<DataGridCellVariantProps["status"]>;
+/** A sort direction (spec §4/§7): reflected as `aria-sort` on the column header and a non-color caret. */
+export type DataGridSortDirection = "ascending" | "descending" | "none";
+export interface DataGridProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * The TRUE total row count of the full set (spec §7), carried on the grid as `aria-rowcount` — NOT
+     * the rendered window. So a screen reader announces "row 4,210 of 12,000" even when only thirty
+     * rows are in the DOM. Reporting only the rendered window is the defining virtualization-a11y
+     * defect (spec §8 Don't).
+     */
+    rowCount: number;
+    /** The TRUE total column count of the full set (spec §7), carried on the grid as `aria-colcount`. */
+    colCount: number;
+    /** Row density (spec §3). `comfortable` (default) or `compact`. Applies to all cells via context. */
+    density?: DataGridDensity;
+    /**
+     * Selection model (spec §3). `none` (default, read-only) or `multiple` — `multiple` sets
+     * `aria-multiselectable` and is the model the selection cells + bulk bar belong to.
+     */
+    selection?: DataGridSelection;
+    /** The rows are resolving (spec §4 Loading). Marks the grid `aria-busy` without stealing focus. */
+    loading?: boolean;
+    /**
+     * The polite live-region message (spec §7, 4.1.3 Status Messages): the resolved row count after a
+     * load or filter, the new sort direction, or the selection count — announced as TEXT so it never
+     * rests on visual state alone. The caller owns the string (mirroring Table/CommandPalette).
+     */
+    announcement?: string;
+    /**
+     * A blocking row-load error (spec §4 Error / §7): announced through the ASSERTIVE region. State
+     * what failed and what to do next, in text, without blaming the reader — for example "These rows
+     * didn't load. The request timed out — retry, or narrow the date range."
+     */
+    errorMessage?: string;
+    /**
+     * Select all rows that match the current filter (spec §6 Ctrl+A). The grid owns the keydown, so
+     * Ctrl+A inside the grid calls this; the caller selects the full filtered set and announces the
+     * resolved count through `announcement` (never silently — spec §6 "announced as a count"). Only
+     * meaningful in a `multiple`-selection grid. Without it, Ctrl+A falls through to the browser.
+     */
+    onSelectAll?: () => void;
+}
+/**
+ * A DataGrid shows many rows of structured records in a scrollable, operable, two-dimensional grid
+ * you navigate one cell at a time (spec §1). Reach for it over a Table when rows run into the
+ * thousands and must virtualize, when columns sort/filter/resize/freeze, when rows select for bulk
+ * actions, or when each cell is its own focus stop — a trust-events log, an API-key inventory, an
+ * AI-agent-identity roster. Use the Table for short, read-mostly lists.
+ *
+ * It is a NEUTRAL data surface (spec §1/§3): neutrals carry roughly 90% of it. Verification and trust
+ * states inside it are STATUS, never brand — a verified row reads through the status aliases, never
+ * the Sovereign Violet brand accent, and the brand accent never marks a row as verified. Selection
+ * and the active cell are NEUTRAL action states, not Verified Green and not the brand violet
+ * (brand != state, G-U2). For a first-class verified result in a cell, use the VerifiedBadge molecule.
+ *
+ * The grid is a SINGLE tab stop: Tab lands on the active cell and Tab again leaves; inside, the arrow
+ * keys move the active cell (spec §6). It owns that roving-cell focus, so it is `'use client'`.
+ */
+export declare const DataGrid: React.ForwardRefExoticComponent<DataGridProps & React.RefAttributes<HTMLDivElement>>;
+export type DataGridStatusRegionProps = Record<string, never>;
+/**
+ * A no-op anatomy marker for the live status region (spec §2 status-region). The actual polite +
+ * assertive regions are owned by the DataGrid root (fed by its `announcement` / `errorMessage`
+ * props) and portaled outside the grid table, so the announcement contract holds even when this slot
+ * is omitted; render this in the grid's children to document the anatomy explicitly. It renders
+ * nothing itself — so it is harmless wherever the caller places it inside the grid.
+ */
+export declare function DataGridStatusRegion(_props: DataGridStatusRegionProps): null;
+export interface DataGridHeaderRowProps extends React.HTMLAttributes<HTMLTableRowElement> {
+    /** The header row's absolute 1-based `aria-rowindex` against the full set (spec §7). Conventionally 1. */
+    rowIndex: number;
+}
+/**
+ * The sticky column-header row (spec §2 column-header-row / §4). It is a `role="row"` holding the
+ * `columnheader` cells, pinned to the top of the scroll viewport on the raised surface so it reads
+ * above the scrolling rows (spec §4/§5). Its absolute `aria-rowindex` is carried for the full-set
+ * shape (spec §7); a header row is conventionally row 1.
+ */
+export declare const DataGridHeaderRow: React.ForwardRefExoticComponent<DataGridHeaderRowProps & React.RefAttributes<HTMLTableRowElement>>;
+export type DataGridBodyProps = React.HTMLAttributes<HTMLTableSectionElement>;
+/**
+ * The `<tbody>` holding the rendered window of data rows (spec §2). With virtualization only a window
+ * of rows is in the DOM — the full shape is carried by the grid's `aria-rowcount` and each row's
+ * absolute `aria-rowindex` (spec §7), not by the rendered count.
+ */
+export declare const DataGridBody: React.ForwardRefExoticComponent<DataGridBodyProps & React.RefAttributes<HTMLTableSectionElement>>;
+export interface DataGridRowProps extends React.HTMLAttributes<HTMLTableRowElement> {
+    /** The row's absolute 1-based `aria-rowindex` against the full set (spec §7) — e.g. 4210, not the rendered position. */
+    rowIndex: number;
+    /**
+     * The row is selected (spec §4 Selected). Sets `aria-selected` and the NEUTRAL selection-accent
+     * fill; selection is encoded by `aria-selected` + the selection checkbox, never by color alone, and
+     * NEVER a brand or status tint (brand != state, G-U2). Selecting a row never implies it is verified.
+     */
+    selected?: boolean;
+}
+/**
+ * One record row (spec §2 row / §4). A `role="row"` carrying its absolute `aria-rowindex` (spec §7),
+ * the restrained ghost row-hover affordance, and — when `selected` — the neutral selection accent +
+ * `aria-selected`. In a `multiple`-selection grid every body row reflects `aria-selected` (true or
+ * false) so selection state is never ambiguous to assistive tech.
+ */
+export declare const DataGridRow: React.ForwardRefExoticComponent<DataGridRowProps & React.RefAttributes<HTMLTableRowElement>>;
+export interface DataGridColumnHeaderProps extends Omit<React.ThHTMLAttributes<HTMLTableCellElement>, "onClick"> {
+    /** The header's absolute 1-based `aria-colindex` against the full set (spec §7). */
+    colIndex: number;
+    /** This column can be re-sorted from its header (spec §3 sortable): renders a real sort button + caret. */
+    sortable?: boolean;
+    /**
+     * The current sort direction for this column (spec §4 Sorted), reflected as `aria-sort` on the
+     * header and as the caret. Only one column is the sort column — set it here and `"none"` elsewhere.
+     */
+    sortDirection?: DataGridSortDirection;
+    /** Fired when the sortable header is activated (click / Enter), so the caller re-sorts and updates `sortDirection`. */
+    onSort?: () => void;
+    /** The column name used in the sort control's accessible name, when it differs from the children. */
+    sortLabel?: string;
+}
+/**
+ * One column header cell (spec §2 column-header / §7). A `th role="columnheader"` that is also a
+ * roving active-cell target (it carries the cell focus ring + tabindex). A plain header is a quiet,
+ * tracked label in the secondary text color. A `sortable` header wraps the label in a real `<button>`
+ * carrying the ghost-action accent, a caret, and the target-size floor; the header reflects
+ * `aria-sort` and Enter toggles the sort (spec §6) — so direction reaches assistive tech as data and
+ * never rests on color alone (1.4.1).
+ */
+export declare const DataGridColumnHeader: React.ForwardRefExoticComponent<DataGridColumnHeaderProps & React.RefAttributes<HTMLTableCellElement>>;
+/**
+ * How a cell relates to the interactive control(s) it holds (spec §2/§6 cell entry/exit model):
+ * - `undefined` — a plain VALUE cell (or one static, non-interactive node). The cell itself is the
+ *   focus stop; arrow keys move the active cell as normal.
+ * - `"single"` — the cell holds ONE interactive control (a link, a status chip, a row-action menu).
+ *   The cell DELEGATES focus to that control on entry, so the control is what you land on and operate
+ *   directly (spec §6 "delegates focus to it on entry").
+ * - `"multiple"` — the cell holds SEVERAL controls. The cell is ENTERED with Enter (focus moves to the
+ *   first control, and arrow keys stay free for the inner controls rather than moving the active cell)
+ *   and EXITED with Escape (focus returns to the cell), so arrow keys stay free for grid movement
+ *   outside it (spec §6 "entered with Enter and exited with Escape, so arrow keys stay free").
+ */
+export type DataGridCellControls = "single" | "multiple";
+export interface DataGridCellProps extends React.TdHTMLAttributes<HTMLTableCellElement>, Pick<DataGridCellVariantProps, "mono" | "secondary" | "status"> {
+    /** The cell's absolute 1-based `aria-colindex` against the full set (spec §7). */
+    colIndex: number;
+    /** The cell belongs to a body row at this absolute `aria-rowindex`; supplied by DataGridRow context where omitted. */
+    rowIndex?: number;
+    /**
+     * Whether this cell holds interactive control(s), and so how Enter/Escape behave for it (spec §6
+     * cell entry/exit model). Omit for a plain value cell. See {@link DataGridCellControls}.
+     */
+    controls?: DataGridCellControls;
+}
+/**
+ * One data cell — the focusable unit of the grid (spec §2 cell / §4/§7). A `td role="gridcell"`
+ * carrying its absolute `aria-colindex` (spec §7) and the roving active-cell tabindex + focus ring.
+ * A plain cell is neutral primary text; a `mono` cell takes the monospace role and stays LTR in RTL
+ * (an identifier/key/timestamp, G-U6); a `secondary` cell is de-emphasized; a `status` cell carries
+ * the status fg paired with text (a verification/trust state) — the status color lives in the cell
+ * only, never the row or header, and NEVER the brand (brand != state, G-U2). The cell hosts a value
+ * or a single interactive control; density is read from the grid via context.
+ */
+export declare const DataGridCell: React.ForwardRefExoticComponent<DataGridCellProps & React.RefAttributes<HTMLTableCellElement>>;
+export interface DataGridSelectionCellProps extends Omit<React.TdHTMLAttributes<HTMLTableCellElement>, "onChange"> {
+    /** The cell's absolute 1-based `aria-colindex` (spec §7). The selection cell is the leading column. */
+    colIndex: number;
+    /** Whether the row is selected (spec §4 Selected). */
+    checked: boolean;
+    /** Fired when the row's selection toggles (via the checkbox or Space on the cell). */
+    onCheckedChange?: (checked: boolean) => void;
+    /**
+     * Extend a range from the last selected row to this one (spec §6 Shift+Space). The grid does not
+     * track which row was selected last, so the caller owns the anchor and the resulting range; this
+     * fires on Shift+Space on the cell so the range reaches the same handler keyboard and pointer
+     * (Shift+click) would. Without it, Shift+Space falls back to toggling the single row.
+     */
+    onExtendSelection?: () => void;
+    /** The checkbox's accessible name (spec §7) — e.g. "Select sk_live_1". Never the placeholder. */
+    label: string;
+    /** The cell belongs to a body row at this absolute `aria-rowindex`; discovered from the row when omitted. */
+    rowIndex?: number;
+}
+/**
+ * The leading selection cell (spec §2 selection-cell / §4/§6): a `gridcell` holding the row's
+ * Checkbox. Space on the cell toggles the row's selection (spec §6). The checkbox is the committed
+ * Checkbox component — a checked box is the brand action accent (never status-verified, G-U2):
+ * selection is a neutral action state. It is a roving active-cell target like any other cell.
+ */
+export declare const DataGridSelectionCell: React.ForwardRefExoticComponent<DataGridSelectionCellProps & React.RefAttributes<HTMLTableCellElement>>;
+export interface DataGridSelectAllCellProps extends Omit<React.ThHTMLAttributes<HTMLTableCellElement>, "onChange"> {
+    /** The header cell's absolute 1-based `aria-colindex` (spec §7). The select-all is the leading column. */
+    colIndex: number;
+    /** Whether all rows are selected. */
+    checked: boolean;
+    /** Whether some-but-not-all rows are selected (the mixed/indeterminate state). */
+    indeterminate?: boolean;
+    /** Fired when the select-all toggles. */
+    onCheckedChange?: (checked: boolean) => void;
+    /** The select-all checkbox's accessible name (spec §7) — e.g. "Select all rows". */
+    label: string;
+}
+/**
+ * The select-all header cell (spec §2 selection-cell: "its header holds the select-all checkbox").
+ * A `columnheader` holding the parent Checkbox (the `variant="parent"` mixed model), so a partial
+ * selection reads as mixed to assistive tech. A roving active-cell target like any other header.
+ */
+export declare const DataGridSelectAllCell: React.ForwardRefExoticComponent<DataGridSelectAllCellProps & React.RefAttributes<HTMLTableCellElement>>;
+export interface DataGridBulkActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** How many rows are selected (spec §2/§7), announced in words so selection is never color alone. */
+    selectedCount: number;
+    /** Fired when Escape dismisses the bar (spec §6 "dismiss the bulk-action bar"). */
+    onDismiss?: () => void;
+}
+/**
+ * The bulk-action bar (spec §2 bulk-action-bar / §4/§6): a `role="toolbar"` that appears when one or
+ * more rows are selected, holding the selection actions and the selected-count label. It is a NEUTRAL
+ * surface — the color lives on the action buttons it holds, never on the bar (spec §3/§8). Escape
+ * dismisses it back to grid navigation (spec §6). Its accessible name names the selection count.
+ */
+export declare const DataGridBulkActionBar: React.ForwardRefExoticComponent<DataGridBulkActionBarProps & React.RefAttributes<HTMLDivElement>>;
+export interface DataGridBulkActionProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** A destructive bulk action (spec §5) — a risk signal in the ACTION tier (never a status color). */
+    destructive?: boolean;
+}
+/**
+ * One action in the bulk-action bar (spec §2/§5): a real `<button>`. The default action is the
+ * primary action accent; a `destructive` action (for example, revoke a key) is the destructive
+ * action accent — a risk signal named in TEXT, never a status color (spec §5/§8).
+ */
+export declare const DataGridBulkAction: React.ForwardRefExoticComponent<DataGridBulkActionProps & React.RefAttributes<HTMLButtonElement>>;
+export interface DataGridEmptyProps extends React.TdHTMLAttributes<HTMLTableCellElement> {
+    /** How many columns the empty line spans, so it fills the grid's own width (spec §2/§4 Empty). */
+    colSpan?: number;
+}
+/**
+ * The empty-state row (spec §2/§4 Empty): a single full-width cell stating why the grid is empty and
+ * what to do next, in plain words ending in a period — clear a filter, widen a date range. An empty
+ * grid is NOT an error and never reads as one (no status color), and it never blames you or ends with
+ * an exclamation mark (voice). Render it inside the body when a query returns nothing.
+ */
+export declare const DataGridEmpty: React.ForwardRefExoticComponent<DataGridEmptyProps & React.RefAttributes<HTMLTableCellElement>>;
+//# sourceMappingURL=data-grid.d.ts.map

package/dist/components/data-grid/data-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-grid.d.ts","sourceRoot":"","sources":["../../../src/components/data-grid/data-grid.tsx"],"names":[],"mappings":"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"}