gridsmith-ui 0.32.0 → 0.33.0

package/dist/dashboard.d.ts

@@ -0,0 +1,207 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { IconName } from './icons.js';
+import { a as DropdownMenuEntry } from './DropdownMenu-DqT7ZQ0D.js';
+
+/**
+ * Sprint 32 (A2) — a dashboard's layout, as plain data: its widgets in reading order, each with a width in columns of 12
+ * and a height in rows of a fixed height. The grid lays them out as text is laid out: left to right, then the next row,
+ * each taking the first space after the one before that fits it (CSS grid's sparse auto-placement, never `dense`), so
+ * what's on screen, what a screen reader reads and where Tab goes are one order by construction.
+ *
+ * Server-safe: no React and no browser, so `gridsmith-ui/utils` exports the helpers (normaliseLayout, moveItem,
+ * resizeItem, addItem, removeItem) and a page that only adds a widget, or a test that checks a layout, needs no drag
+ * code. The rest is the grid's own: where widgets land (`placeLayout`, a copy of the browser's placement rule, held equal
+ * to Chrome's by a Chrome test), where a key or a pointer would take one (`stepTarget`, `nearestIndex`) and the words a
+ * screen reader hears for a size. Where things land is worked out here, from the layout, never measured from the
+ * screen: measuring a preview feeds back into it, the flicker sortable grids are known for.
+ */
+interface DashboardLayoutItem {
+    id: string;
+    /** Its width, in columns of 12. */
+    w: number;
+    /** Its height, in rows. */
+    h: number;
+    /** The narrowest it may be made, in columns (default 3, a quarter of the width; a widget is never narrower). */
+    minW?: number;
+    /** The shortest it may be made, in rows (default 2). */
+    minH?: number;
+    /** The widest it may be made, in columns (default 12). */
+    maxW?: number;
+    /** The tallest it may be made, in rows. */
+    maxH?: number;
+}
+type DashboardLayout = DashboardLayoutItem[];
+
+/**
+ * Sprint 32 (A1–A13) — the dashboard grid: a dashboard the people using the app arrange themselves. Its widgets sit in a
+ * reading order on 12 columns (lib/dashboard-layout.ts), each one of the library's titled frames, which the grid only
+ * places: no frame of its own, so never a card in a card (A3). In the view it is an ordinary page (custom_interaction#20):
+ * nothing drags, and a widget's own links and clicks work as anywhere else. In its edit mode, entered on purpose, each
+ * widget gets three controls beside its frame, never inside it (A4): a move handle, a ⋯ menu (Set up, Move, Size and the
+ * page's own actions) and a resize grip. Every drag has a keyboard way and a plain click way (accessibility#26), and
+ * everything is said in the grid's own polite live region, with the widget's name, never its id (A7).
+ *
+ * The pointer and touch go through dnd-kit 6.3.1, the Kanban's: the mouse sensor after 5 px and the touch sensor after a
+ * hold (never the pointer sensor, which also answers touch and would start on a 5 px swipe), its auto-scroll for the page,
+ * and nothing of its own said. The keyboard's moves are the grid's own state, never dnd-kit's keyboard sensor (A5).
+ */
+/** A kind of widget the palette offers (A8): its name, an optional description and icon, and the size it starts at. */
+interface DashboardWidgetKind {
+    id: string;
+    name: string;
+    description?: string;
+    icon?: IconName;
+    /** Its starting width, in columns of 12. A chart's kind starts tall enough to hold the chart's floor (5 rows). */
+    w: number;
+    /** Its starting height, in rows. */
+    h: number;
+}
+interface DashboardItemProps {
+    /** The widget's id, as its layout entry has it. */
+    id: string;
+    /**
+     * The widget's name, its frame's title on screen ("Cash balance"): what a screen reader hears on the grid's controls
+     * ("Move Cash balance") and in what the grid says ("Cash balance, position 3 of 8"). In development a label that
+     * differs from the frame's title is warned about.
+     */
+    label: string;
+    /** The widget: one of the library's titled frames (a ChartContainer, a StatsCard, a titled Table, a Card with a CardHeader). */
+    children: ReactNode;
+}
+interface DashboardGridProps {
+    /**
+     * The widgets in reading order, each with a width in columns of 12 and a height in rows: plain data the page saves as it
+     * likes. Authoritative: the grid draws what it's given, normalised (normaliseLayout), each widget once, in this order.
+     */
+    layout: readonly DashboardLayoutItem[];
+    /** The layout after a change the person made: once per change kept (a drop, a menu choice, a keyboard drop, a resize kept). */
+    onLayoutChange?: (layout: DashboardLayout) => void;
+    /**
+     * The edit mode, entered on purpose (custom_interaction#20): handles, grips and the column guides, and each widget's
+     * content inert, so a press on a chart never opens its report mid-edit. Off, the dashboard is an ordinary page.
+     */
+    editing?: boolean;
+    /**
+     * Edit mode only: the person chose a widget to set up, from its ⋯ menu's Set up or by a click on the widget (one that
+     * began on it, never the end of a drag or a resize). Show its settings in the page's side panel.
+     */
+    onSelect?: (id: string) => void;
+    /**
+     * A widget's own entries for its ⋯ menu (Duplicate, Remove…), after the grid's Set up, Move and Size, as a Kanban card's
+     * cardActions. A Remove that takes the widget out puts focus on the same control in the widget before, else after.
+     */
+    itemActions?: (id: string) => DropdownMenuEntry[];
+    /**
+     * A widget of this kind added from the palette, by a click on its row (at the end) or a drop (where it lands): add the
+     * page's widget and its layout entry (addItem), and return the new widget's id, or a promise of it for an id the server
+     * makes. Focus goes to the new widget's move handle (its ⋯ on a stacked grid).
+     */
+    onAdd?: (kind: DashboardWidgetKind, index: number) => string | PromiseLike<string>;
+    /** The widgets, each a DashboardItem: an array or a fragment of them. */
+    children?: ReactNode;
+    /**
+     * The name of the widgets' group while editing, as a screen reader hears it, and where focus goes when the last widget
+     * is removed. Default "Dashboard widgets".
+     */
+    "aria-label"?: string;
+    className?: string;
+}
+/**
+ * Sprint 32 (A8): the palette and the grid share one drag, so a widget library's kind can be dragged onto the grid. A
+ * page that uses both wraps them in a DashboardEditor (anywhere above both: the side panel and the page's content); a
+ * grid alone needs none. One grid to an editor: each tab's grid in turn, as only the open tab's is drawn.
+ */
+declare function DashboardEditor({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * One widget on a DashboardGrid (A3). The grid reads its props and draws it in a cell of its own, in the layout's order;
+ * on its own it draws its children.
+ */
+declare function DashboardItem({ children }: DashboardItemProps): react_jsx_runtime.JSX.Element;
+/** The grid drawn in a drag arena: an editor's, else one of its own (a grid alone needs no editor). */
+declare function DashboardGrid(props: DashboardGridProps): react_jsx_runtime.JSX.Element;
+
+interface DashboardPaletteProps {
+    /** The kinds of widget the page offers (headline number, line chart, table, text note, image…), in the order listed. */
+    kinds: DashboardWidgetKind[];
+    /** The list's name, as a screen reader hears it. Default "Widget library". */
+    label?: string;
+    /**
+     * The line above the list that says what a row does: by default "Select or drag to add" while the rows drag,
+     * and "Select a widget to add it" where they don't (a grid stacked at a narrow width); none while the grid isn't
+     * editing. A function gives other words for each case (it's told whether the rows drag); false draws none.
+     */
+    hint?: false | ((rowsDrag: boolean) => string);
+    className?: string;
+}
+/**
+ * Sprint 32 (A8): the widget library the briefs ask for, a list of the kinds of widget a page offers, each with its name,
+ * an optional description and icon. Each kind is one control, a button named "Add {kind}" (the look fixes, D5): a click,
+ * Enter or Space adds the widget at the end (the plain click way, accessibility#26), and a pointer's drag of the row
+ * places it where it's dropped (the grid's sensors tell the two apart: 5 px of movement for a mouse, a 250 ms press for a
+ * finger). The grid asks the page for the widget (its onAdd), focus goes to the new widget's move handle, and the grid's
+ * live region says where it went. It reaches the grid through the DashboardEditor round them both.
+ *
+ * Where it sits, so the grid keeps its width (the guidance's composition): in an AsidePanel with `width="312px"
+ * collapseBelow="xl" resizable={false}`, docked beside the grid from 1280 px and a drawer over the page below, its body
+ * padded as the panel's heading is (each row's hover tint and focus outline reach 8 px into that padding). An Add closes
+ * the overlay the panel has become, wherever it opens over the page (the drawer, or the phone's sheet), so the new widget
+ * isn't left under it; docked beside the grid, the panel stays open. Wherever the grid is stacked (narrower than 40rem)
+ * nothing drags, and focus goes to the new widget's ⋯, since a stacked grid has no handle. Adding and dragging are off
+ * while the grid isn't editing.
+ *
+ * A line above the list says what a row does (the owner's look at the second sheet: the rows drag, so say so), as visible
+ * text before the list rather than its description, which screen readers read unreliably: its words follow whether the
+ * rows drag (`hint`), and there are none while the grid isn't editing, outside a DashboardEditor, or with no kinds. The
+ * list keeps its name, its data attribute and the className, so the line is the list's sibling, not its wrapper.
+ */
+declare function DashboardPalette({ kinds, label, hint, className }: DashboardPaletteProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Sprint 32 (A10): a draft the person edits and then saves or cancels as a whole: a dashboard's tabs (added, renamed,
+ * reordered, removed), each tab's layout and each widget's settings, in whatever shape the page gives it. Every change can be
+ * undone and redone (custom_interaction#26), from the page's visible Undo and Redo buttons and from the keyboard:
+ * Ctrl+Z or ⌘Z undoes, with Shift it redoes, outside text fields only, so a field's own undo keeps working.
+ */
+interface DraftHistory<T> {
+    /** The draft now. */
+    value: T;
+    /**
+     * Changes the draft: a new value, or a function of the one before. Each change is a step that Undo takes back, and a
+     * change after an Undo drops what Redo had. Pass `merge` (a field's name, say) for a run of changes that is one step:
+     * each keystroke in a widget's title field, so Undo takes back the edit, not a letter. A change to the same value
+     * adds no step.
+     */
+    set: (next: T | ((prev: T) => T), merge?: string) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    /**
+     * The draft differs from what was last saved (the first value, or the last `reset`): `dirty` enables Save. Cancel always
+     * goes back to the view, calling `reset(saved)` first, so it's never disabled.
+     */
+    dirty: boolean;
+    /**
+     * Starts again from a saved value, with no steps to undo: after Save, `reset()` takes the draft as saved; Cancel
+     * passes the saved value back, `reset(saved)`, and the draft is that. A value loaded after the first render is passed
+     * here too.
+     */
+    reset: (next?: T) => void;
+}
+interface DraftHistoryOptions {
+    /** Ctrl+Z, ⌘Z and their Shift forms on the page. Default true; off where two drafts share a page, or a dialog has its own. */
+    shortcuts?: boolean;
+}
+/**
+ * A draft held whole until it's saved, with undo and redo: a dashboard's tabs, each tab's layout and each widget's
+ * settings in one value, or anything else a page edits before Save. `set` changes it, one step Undo takes back; `dirty`
+ * says it differs from what was last saved, and enables Save; Cancel always goes back to the view, calling
+ * `reset(saved)` first; `reset()` after Save. Ctrl+Z or ⌘Z undoes and with Shift redoes, outside text fields, unless
+ * `shortcuts` is false.
+ */
+declare function useDraftHistory<T>(initial: T | (() => T), { shortcuts }?: DraftHistoryOptions): DraftHistory<T>;
+
+export { DashboardEditor, DashboardGrid, type DashboardGridProps, DashboardItem, type DashboardItemProps, type DashboardLayout, type DashboardLayoutItem, DashboardPalette, type DashboardPaletteProps, type DashboardWidgetKind, type DraftHistory, type DraftHistoryOptions, useDraftHistory };