@crewlethq/ui 0.39.0 → 0.40.0

package/dist/DataGrid/DataGrid.d.ts

@@ -0,0 +1,267 @@
+import { type MouseEvent as ReactMouseEvent, type KeyboardEvent as ReactKeyboardEvent, type ReactNode, type Ref } from 'react';
+/**
+ * What activated a row: a click, a key on the row's overlay, or the
+ * application's own keymap driving the cursor (a native `KeyboardEvent`).
+ * Each carries the modifier keys a handler reads to open in a new tab.
+ */
+export type DataGridActivationEvent = ReactMouseEvent | ReactKeyboardEvent | KeyboardEvent;
+/** One column of a [DataGrid]. */
+export interface DataGridColumn<T> {
+    key: string;
+    header: ReactNode;
+    cell: (row: T) => ReactNode;
+    /** The value sorted on. Omit to make the column unsortable. */
+    sortValue?: ((row: T) => string | number | null | undefined) | undefined;
+    align?: 'left' | 'right' | undefined;
+    /**
+     * The column's name where `header` cannot carry one: a glyph head, or none
+     * at all. Drawn by the card layout a grid takes on a phone, where every value
+     * names itself, and said to assistive technology over a glyph head.
+     */
+    label?: string | undefined;
+    /**
+     * A column of ROW ACTIONS: every cell is a control that names itself (a
+     * "Revoke" button, an icon button with its own label). On the phone's card
+     * such a cell draws no name beside it, since the control is its own name;
+     * its head stays empty, since a word over a column of buttons says nothing
+     * the buttons do not.
+     */
+    action?: boolean | undefined;
+    /** Shrink to content (up to a fifth of the grid) and never wrap. */
+    shrink?: boolean | undefined;
+    /**
+     * On a grid drawn with `phoneRows="compact"`, a cell of the row's FIRST line
+     * (what the row is: a key, a title), where every other cell is a fact about
+     * it on the line under.
+     */
+    phoneLead?: boolean | undefined;
+    /** Left off the compact phone row, whose contract is two lines. */
+    phoneOmit?: boolean | undefined;
+    /** An exact track, in place of the computed one. */
+    width?: string | undefined;
+    /** Hidden unless the column set (`cols`) names it. */
+    optional?: boolean | undefined;
+    /**
+     * The narrowest a FLEXIBLE column may be drawn: its track is
+     * `minmax(floor, 1fr)` rather than `minmax(0, 1fr)`. For the column that is
+     * the point of the list (a title, a name), which at zero gave way to every
+     * content-sized column beside it.
+     */
+    floor?: string | undefined;
+    /**
+     * The order this column GIVES WAY in when the grid cannot draw every column
+     * at its size: the lowest number goes first, and a column without one never
+     * goes. A grid that cannot fit drops columns rather than cutting them off at
+     * its clipped edge, and says which it dropped.
+     */
+    drop?: number | undefined;
+}
+/** One column a reader may turn on or off, as a [ColumnChooser] offers it. */
+export interface ColumnChoice {
+    key: string;
+    label: string;
+    /** Off until the column set names it. */
+    optional?: boolean | undefined;
+}
+/**
+ * The choices a chooser offers, DERIVED from the columns a grid draws, so a
+ * column added to a grid appears in its menu with no second edit. The cell
+ * renderers are never called: a name and a flag are properties of the column.
+ */
+export declare function columnChoicesOf<T>(columns: readonly DataGridColumn<T>[]): ColumnChoice[];
+/** One box in a [ChooserList]. */
+export interface ChooserItem<K extends string = string> {
+    key: K;
+    label: ReactNode;
+    checked: boolean;
+}
+export interface ChooserListProps<K extends string = string> {
+    /** The heading above the boxes, which also names the group. */
+    label: string;
+    items: readonly ChooserItem<K>[];
+    onToggle: (key: K) => void;
+}
+/**
+ * A short checklist of what a view shows, in two columns under a quiet
+ * heading: the columns a grid draws ([ColumnChooser]), the facts a card
+ * carries. Native checkboxes in a named group, each row its box's label, so
+ * the whole row takes the pointer.
+ */
+export declare function ChooserList<K extends string = string>({ label, items, onToggle }: ChooserListProps<K>): import("react").JSX.Element | null;
+export interface ColumnChooserProps {
+    choices: readonly ColumnChoice[];
+    /** The column set as it stands (`key,key`), empty for the default set. */
+    value: string;
+    onChange: (cols: string) => void;
+    /** The heading above the boxes. */
+    label?: string | undefined;
+}
+/**
+ * The checkbox list a reader chooses a grid's columns with.
+ *
+ * AN EMPTY VALUE IS THE DEFAULT SET, NOT AN EMPTY GRID, as [DataGrid] reads
+ * it, so the boxes show the default until somebody moves one. It writes the
+ * DECLARATION order, never the click order: the value carries an order as well
+ * as a selection, and a value built from the order boxes were ticked in would
+ * rearrange the grid with every tick.
+ */
+export declare function ColumnChooser({ choices, value, onChange, label }: ColumnChooserProps): import("react").JSX.Element;
+/** A group of rows, as a grouped answer sends it: its own count and a page of rows. */
+export interface DataGridBand<T> {
+    key: string;
+    label: ReactNode;
+    /** The group value's own mark, drawn before the label (a sibling, so no ellipsis eats it). */
+    mark?: ReactNode;
+    /** The count over the WHOLE group, where the source gave one. */
+    total?: number | undefined;
+    rows: T[];
+    /**
+     * The bands INSIDE this one, where the answer was grouped twice: a band
+     * carries rows OR sub-bands, never both, as the answer arrives.
+     */
+    bands?: DataGridBand<T>[] | undefined;
+    /** A per-band aggregate line, or the way to what the band did not fit. */
+    footer?: ReactNode;
+}
+/** The words a grid says, for an application that says them otherwise. */
+export interface DataGridLabels {
+    /** "Hidden to fit: Due and Updated". */
+    hiddenToFit: (names: string) => string;
+    loadMore: string;
+    showEveryColumn: string;
+    /** Joins the last two names of a list: "Due and Updated". */
+    and: string;
+}
+/**
+ * What an application drives a grid's cursor with. The grid binds no keys of
+ * its own: an application with a keymap decides which of several grids on a
+ * screen a keystroke is for, and moves that one.
+ */
+export interface DataGridHandle {
+    /** Moves the cursor row by `by` rows, clamped, and scrolls it into view. */
+    step: (by: number) => void;
+    /** Activates the cursor row, as a click on it would. False when there is none. */
+    activate: (event: ReactKeyboardEvent | KeyboardEvent) => boolean;
+    /** How many rows the grid draws, its bands' rows included. */
+    rowCount: () => number;
+}
+export interface DataGridProps<T> {
+    rows?: T[] | undefined;
+    bands?: DataGridBand<T>[] | undefined;
+    columns: DataGridColumn<T>[];
+    rowKey: (row: T) => string;
+    /** A plain click, or Enter on the cursor row. The row is still a link when `rowHref` is given. */
+    onRowActivate?: ((row: T, event: DataGridActivationEvent) => void) | undefined;
+    /** The row's object's page: a real link stretched over the row, so a new tab and copying it work. */
+    rowHref?: ((row: T) => string) | undefined;
+    /** The row the reader is on (the object a page or a side panel shows): tinted and announced as current. */
+    isSelected?: ((row: T) => boolean) | undefined;
+    isFailed?: ((row: T) => boolean) | undefined;
+    /**
+     * The sort as `key` or `-key` (descending), empty for the rows' own order.
+     * Controlled, so an application keeps it where it keeps state (an address).
+     */
+    sort?: string | undefined;
+    /** A sortable head pressed: ascending, then descending, then unsorted. */
+    onSortChange?: ((sort: string) => void) | undefined;
+    /** The rows arrive ordered by their source (a paged answer ordered over the whole set). */
+    serverSorted?: boolean | undefined;
+    /** The column set as `key,key`, in the order to draw it; empty for every column not `optional`. */
+    cols?: string | undefined;
+    /** The way back from a column set: drawn as "Show every column" while one is set. */
+    onColsChange?: ((cols: string) => void) | undefined;
+    /** What an empty grid says, and the one control that is its next step. */
+    empty?: {
+        title: ReactNode;
+        hint?: ReactNode;
+        icon?: ReactNode;
+        action?: ReactNode;
+    } | undefined;
+    footer?: ReactNode;
+    onLoadMore?: (() => void) | undefined;
+    /** "40 of 312 loaded": what an export would actually contain. */
+    loadedNote?: string | undefined;
+    /**
+     * HOW A ROW IS DRAWN ON A PHONE, where there are no columns: `labelled` (a
+     * card of one named line per value, which every grid can take) or `compact`
+     * (two lines with no names: the lead cells, then every other value as a run
+     * of marks, for a list scanned by the dozen).
+     */
+    phoneRows?: 'labelled' | 'compact' | undefined;
+    /**
+     * The grid is a card's body: no edge, corner or ground of its own and one
+     * rule above its head. A grid straight in a `Card` is flush without this.
+     */
+    flush?: boolean | undefined;
+    /** For an application driving the cursor from its own keymap. */
+    handleRef?: Ref<DataGridHandle> | undefined;
+    /** The reader pressed inside the grid: which grid the keyboard means. */
+    onPointerDown?: (() => void) | undefined;
+    labels?: Partial<DataGridLabels> | undefined;
+    /** What the table is, for assistive technology: its card's title, by id or in words. */
+    'aria-label'?: string | undefined;
+    'aria-labelledby'?: string | undefined;
+    className?: string | undefined;
+}
+/** `-updated` as `{key: "updated", desc: true}`. */
+export declare function parseGridSort(raw: string): {
+    key: string;
+    desc: boolean;
+} | null;
+/** What the fit has decided for one set of columns, at one width. */
+export interface GridFit {
+    /** The column set it was decided for. */
+    readonly set: string;
+    /** The grid's width when it last decided. */
+    readonly width: number;
+    /** The keys it dropped, in the order it dropped them. */
+    readonly dropped: readonly string[];
+}
+/**
+ * The next fit, or null when this one stands. PURE, so the rules are held
+ * without a layout engine:
+ *
+ * - the grid GREW past the width columns were dropped at: start again from all
+ *   of them (the next pass drops again only what still does not fit);
+ * - the tracks OVERRUN the grid: drop the visible column with the lowest
+ *   `drop`, if there is one;
+ * - otherwise remember a narrower width, so growing back past it re-tries.
+ */
+export declare function fitGridColumns({ fit, width, overflows, visible, }: {
+    fit: GridFit;
+    width: number;
+    overflows: boolean;
+    visible: readonly {
+        key: string;
+        drop?: number | undefined;
+    }[];
+}): GridFit | null;
+/**
+ * A list as columns: sortable heads, optional and give-way columns, bands for
+ * a grouped answer, a row link stretched over each row, and a card per row on
+ * a phone.
+ *
+ * ONE TRACK LIST, ON THE GRID. The head, the bands and every row are
+ * `subgrid` passthroughs, so a head cell and a cell twenty rows down size the
+ * same track; each row being its own grid sized its columns against its own
+ * cells alone, and no value sat under the head that named it.
+ *
+ * A SHRINK COLUMN IS CAPPED (`fit-content(20%)`): `max-content` grows without
+ * a ceiling and grid resolves it before any flexible column, so one long value
+ * starved the title to zero and still overflowed.
+ *
+ * COLUMNS THAT DO NOT FIT GIVE WAY IN ORDER (`drop`), measured after every
+ * commit in a layout effect so the intermediate shapes never paint, and the
+ * foot names what the width took. Not on a phone, where a row is a card.
+ *
+ * THE ROW'S LINK IS AN OVERLAY, NOT THE ROW: a row that was an anchor made
+ * every linking cell an anchor inside an anchor, and the parser closes the
+ * outer one at the inner, so the row stopped being clickable from that cell
+ * on. Stretched over the row it keeps a real href, and the cells' own links
+ * and buttons sit above it.
+ *
+ * The grid makes no scrollport of its own (`overflow: clip`), which is what
+ * lets its head stick against the page's scroller; an application whose
+ * scroller carries a sticky bar sets `--crewlet-data-grid-sticky-top`.
+ */
+export declare function DataGrid<T>({ rows, bands, columns, rowKey, onRowActivate, rowHref, isSelected, isFailed, sort: sortRaw, onSortChange, serverSorted, cols: colsRaw, onColsChange, empty, footer, onLoadMore, loadedNote, phoneRows, flush, handleRef, onPointerDown, labels, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, className, }: DataGridProps<T>): import("react").JSX.Element;

package/dist/DataGrid/index.d.ts

@@ -0,0 +1,3 @@
+import './DataGrid.css';
+export { ChooserList, ColumnChooser, DataGrid, columnChoicesOf, fitGridColumns, parseGridSort } from './DataGrid.js';
+export type { ColumnChoice, ChooserItem, ChooserListProps, ColumnChooserProps, DataGridActivationEvent, DataGridBand, DataGridColumn, DataGridHandle, DataGridLabels, DataGridProps, GridFit, } from './DataGrid.js';

package/dist/DataGrid/index.js

@@ -0,0 +1,7 @@
+export { ChooserList, ColumnChooser, DataGrid, columnChoicesOf, fitGridColumns, parseGridSort } from '../chunk-XIDD7PJO.js';
+import '../chunk-RA2ULG6H.js';
+import '../chunk-PQADV6P6.js';
+import '../chunk-RTPQDNW3.js';
+import '../chunk-OG6CL3EB.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';