altitude-design 0.2.0 → 0.3.0

package/dist/types-cjs/collections.d.cts

@@ -0,0 +1,246 @@
+import * as React from 'react';
+import { EditRegionBinder, EditRegionSaveResult } from './edit-region.cjs';
+import { Promised, SkeletonOption } from './suspense.cjs';
+export interface TableProps extends React.TableHTMLAttributes<HTMLTableElement> {
+    /** The table scrolls under its header past this height. */
+    maxHeight?: number | string;
+    /** Drawn inside the scroll area, beneath the rows (DataTable puts its landing slot here). */
+    underlay?: React.ReactNode;
+}
+/**
+ * Rows are the record: they sit on the ground with `line` dividers. The header stays flush until rows scroll under it,
+ * then rises. Rows that change place are carried there. Each row's height is drawn as one slab by its first cell.
+ */
+export declare const Table: React.ForwardRefExoticComponent<TableProps & React.RefAttributes<HTMLTableElement>>;
+export declare const TableHeader: ({ className, ...p }: React.HTMLAttributes<HTMLTableSectionElement>) => React.JSX.Element;
+export declare const TableBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableSectionElement> & React.RefAttributes<HTMLTableSectionElement>>;
+export declare const TableFooter: ({ className, ...p }: React.HTMLAttributes<HTMLTableSectionElement>) => React.JSX.Element;
+export declare const TableCaption: ({ className, ...p }: React.HTMLAttributes<HTMLTableCaptionElement>) => React.JSX.Element;
+export interface TableRowProps extends React.HTMLAttributes<HTMLTableRowElement> {
+    /** A stable id. With it, a row whose place changes (re-sorting, reordering) is carried there instead of jumping. */
+    rowId?: string;
+    /** Selected rows are tinted accent-soft and raised one level. Pair it with a checked Checkbox in the row. */
+    selected?: boolean;
+    /** Lifts on hover. Only when clicking the row does something. */
+    interactive?: boolean;
+    /** Focus+context filtering: match rises one level, miss sinks into a well. */
+    relevance?: 'match' | 'miss';
+    /** Afterglow: when the value changes, the row lifts, tints and settles back over dur-settle. true settles once on mount. */
+    settle?: unknown;
+    /** In someone's hand while it's being moved: level 3, tilted. */
+    held?: boolean;
+}
+export declare const TableRow: React.ForwardRefExoticComponent<TableRowProps & React.RefAttributes<HTMLTableRowElement>>;
+export interface TableHeadProps extends Omit<React.ThHTMLAttributes<HTMLTableCellElement>, 'align'> {
+    align?: 'start' | 'end';
+    /** This column's sort. With onSort, the header becomes a button and the th carries aria-sort. */
+    sort?: 'ascending' | 'descending' | 'none';
+    onSort?: () => void;
+}
+export declare function TableHead({ align, sort, onSort, className, children, ...rest }: TableHeadProps): React.JSX.Element;
+export interface TableCellProps extends Omit<React.TdHTMLAttributes<HTMLTableCellElement>, 'align'> {
+    align?: 'start' | 'end';
+}
+export declare function TableCell({ align, className, ...rest }: TableCellProps): React.JSX.Element;
+export interface DataTableColumn<T> {
+    key: string;
+    header: React.ReactNode;
+    /** Cell content. Default: the row's value at `key`. */
+    cell?: (row: T) => React.ReactNode;
+    /** Makes the column sortable by this value. */
+    sortValue?: (row: T) => string | number;
+    align?: 'start' | 'end';
+    width?: number | string;
+    /**
+     * The narrowest the column gets (#260): on a phone the table scrolls inside its frame rather than squeezing a column
+     * below this. Default: the header's width, and at least 6rem when the table is narrow.
+     */
+    minWidth?: number | string;
+    /** Keep this column in view while the table scrolls sideways, over a flush 1px edge (no shadow: it isn't live). */
+    sticky?: boolean;
+}
+export type TableSort = {
+    key: string;
+    direction: 'ascending' | 'descending';
+} | null;
+export interface DataTableProps<T> {
+    columns: DataTableColumn<T>[];
+    /** The rows. Undefined while your data loads, or a promise: until they arrive the table is its header over `skeleton.lines` imprinted rows (default 5). */
+    rows: Promised<T[]> | undefined;
+    /** While the rows are on their way: how many rows to imprint (`lines`). `false`: undefined rows render as empty, and a promise suspends to your own boundary. */
+    skeleton?: SkeletonOption;
+    getRowId: (row: T) => string;
+    /** A row's name, for screen readers (its checkbox, its move handle, announcements) and its button with onRowClick. */
+    getRowLabel?: (row: T) => string;
+    /** A checkbox column; selected rows rise, and the toolbar counts them. */
+    selectable?: boolean;
+    selected?: string[];
+    defaultSelected?: string[];
+    onSelectedChange?: (ids: string[]) => void;
+    /** Actions for the selected rows, shown beside their count. The second argument is the whole selection, which may be "all matching". */
+    actions?: (ids: string[], selection: TableSelection) => React.ReactNode;
+    /** The selection, when it can reach past the loaded rows: { kind: 'ids', ids } or { kind: 'query', total, except }. */
+    selection?: TableSelection;
+    onSelectionChange?: (selection: TableSelection) => void;
+    /** How many records match the current filter, across every page. Offers "Select all N matching" once a page is selected. */
+    matchingTotal?: number;
+    /** Where the count and actions sit: in the toolbar, in a bar floating at the bottom edge (level 3), or 'auto' (floating once the toolbar scrolls away). Default 'toolbar'. */
+    actionsPlacement?: 'toolbar' | 'floating' | 'auto';
+    /** What the rows are, plural ("users"), for "Select all 2,341 users". Default "rows". */
+    noun?: string;
+    /** Anything else for the toolbar's end (a filter field, a button). */
+    toolbar?: React.ReactNode;
+    sort?: TableSort;
+    defaultSort?: TableSort;
+    onSortChange?: (sort: TableSort) => void;
+    /** Makes rows interactive: the first column becomes the row's button, and clicking anywhere on the row calls this. */
+    onRowClick?: (row: T) => void;
+    /** Filter in place: matches rise, misses sink. Return undefined when no filter is active. */
+    relevance?: (row: T) => 'match' | 'miss' | undefined;
+    /** Adds move handles: rows can be picked up and dropped (pointer, or Space and the arrow keys). Hidden while sorted. */
+    onReorder?: (rows: T[]) => void;
+    maxHeight?: number | string;
+    /** Shown when there are no rows. */
+    empty?: React.ReactNode;
+    className?: string;
+    'aria-label'?: string;
+    /** Read-only detail: a disclosure button in the first column opens a full-width region under the row, on the ground. */
+    renderExpanded?: (row: T) => React.ReactNode;
+    /** With onSave, an Edit button opens the row's region as an EditRegion holding these fields; row and region rise together. */
+    renderEditor?: (field: EditRegionBinder<T & Record<string, unknown>>, row: T) => React.ReactNode;
+    onSave?: (draft: T, context: {
+        previousValue: T;
+        changed: (keyof T)[];
+    }) => EditRegionSaveResult<T & Record<string, unknown>> | Promise<EditRegionSaveResult<T & Record<string, unknown>>>;
+    /** Publishes a saved row's canonical record (a synchronous setter). */
+    onRowChange?: (canonical: T) => void;
+    /** Rows whose detail is open, by id. */
+    expanded?: string[];
+    defaultExpanded?: string[];
+    onExpandedChange?: (ids: string[]) => void;
+    /** 'single' (default): opening one closes the others. */
+    expandMode?: 'single' | 'multiple';
+    /** Which columns show, by key: false hides one. The first column in order always shows. */
+    columnVisibility?: Record<string, boolean>;
+    defaultColumnVisibility?: Record<string, boolean>;
+    onColumnVisibilityChange?: (visibility: Record<string, boolean>) => void;
+    /** The columns' order, by key. Keys left out keep their place after the ones given. */
+    columnOrder?: string[];
+    defaultColumnOrder?: string[];
+    onColumnOrderChange?: (order: string[]) => void;
+    /** Row density. 'compact' keeps every target at least 24px tall. Default 'comfortable'. */
+    density?: 'comfortable' | 'compact';
+    defaultDensity?: 'comfortable' | 'compact';
+    onDensityChange?: (density: 'comfortable' | 'compact') => void;
+    /** A "Columns" button in the toolbar: show, hide and reorder columns, and choose the density. */
+    columnsMenu?: boolean;
+    /** Rows paged by your server: Pagination in the footer, or "Load more". */
+    pagination?: DataTablePaging;
+}
+/** Rows chosen by id, or every record matching the query except some. */
+export type TableSelection = {
+    kind: 'ids';
+    ids: string[];
+} | {
+    kind: 'query';
+    total: number;
+    except: string[];
+};
+export type DataTablePaging = {
+    mode?: 'pages';
+    page: number;
+    pageCount?: number;
+    pageSize?: number;
+    total?: number;
+    onPageChange: (page: number) => void;
+    hrefFor?: (page: number) => string;
+    hasNext?: boolean;
+    /** The next page is loading: the rows stay at half strength and the page thumb is held pressed. */ loading?: boolean;
+    noun?: string;
+} | {
+    mode: 'more';
+    hasMore: boolean;
+    onLoadMore: () => void;
+    total?: number;
+    loading?: boolean;
+    noun?: string;
+};
+/**
+ * A table from data: sortable columns whose rows are carried to their new places, a checkbox column whose selected rows
+ * rise (counted by a floating Badge in the toolbar), filtering in place, interactive rows and reordering by hand.
+ */
+export declare function DataTable<T>({ skeleton, ...props }: DataTableProps<T>): React.JSX.Element;
+export interface BoardPlace {
+    column: string;
+    index: number;
+}
+export interface BoardMove {
+    cardId: string;
+    from: BoardPlace;
+    to: BoardPlace;
+}
+export interface BoardProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Called when a card is dropped somewhere new (pointer), or moved a step (keyboard). Update your data; the board carries the cards. */
+    onMove: (move: BoardMove) => void;
+    /** Default "Board". */
+    'aria-label'?: string;
+}
+/**
+ * Columns of cards. Columns are receptacles: flush at rest, they open into wells while a card is carried, and the one
+ * under it deepens. Cards are raised; one picked up floats at level 3, tilted, follows the pointer, and lands with a settle.
+ */
+export declare const Board: React.ForwardRefExoticComponent<BoardProps & React.RefAttributes<HTMLDivElement>>;
+export interface BoardColumnProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    id: string;
+    title: React.ReactNode;
+    /** A collapsed column is a Pile: its thickness and count say how many cards it holds. It still takes drops. */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Show the collapse button. */
+    collapsible?: boolean;
+    /** Adds an add slot at the foot of the column. Resolve after the new card is among the children. */
+    onCreate?: (title: string) => BoardCreateResult | Promise<BoardCreateResult>;
+    /** Default “Add a card”. */
+    addLabel?: string;
+}
+export type BoardCreateResult = {
+    ok: true;
+    value: {
+        id: string;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+export type BoardRenameResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function BoardColumn({ id, title, collapsed, defaultCollapsed, onCollapsedChange, collapsible, onCreate, addLabel, className, children, ...rest }: BoardColumnProps): React.JSX.Element;
+export interface BoardCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    id: string;
+    /** How announcements name the card. Default: its first line of text. */
+    label?: string;
+    /** A collaborator is holding it: lifted, wearing their colour and name. It can't be picked up meanwhile. */
+    heldBy?: {
+        name: string;
+        presence?: 1 | 2 | 3;
+    };
+    /** Afterglow: when this value changes the card arrives tinted and lifted, then settles. */
+    settle?: unknown;
+    /** Rename in place (F2, or the visible Rename button): InlineEdit's contract. Use with `label`. */
+    onRename?: (draft: string) => BoardRenameResult | Promise<BoardRenameResult>;
+    /** The card's record, for a fuller editor in its place (EditRegion). */
+    value?: Record<string, unknown>;
+    renderEditor?: (field: EditRegionBinder<Record<string, unknown>>) => React.ReactNode;
+    onSave?: (draft: Record<string, unknown>, context: {
+        previousValue: Record<string, unknown>;
+        changed: string[];
+    }) => EditRegionSaveResult<Record<string, unknown>> | Promise<EditRegionSaveResult<Record<string, unknown>>>;
+    onValueChange?: (canonical: Record<string, unknown>) => void;
+}
+export declare const BoardCard: React.ForwardRefExoticComponent<BoardCardProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types-cjs/color-picker.d.cts

@@ -0,0 +1,38 @@
+import * as React from 'react';
+export interface ColorSwatch {
+    value: string;
+    /** Every swatch has a name: colour is never the only way to tell them apart. */
+    name: string;
+}
+export interface ColorSwatchPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+    swatches: ColorSwatch[];
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string) => void;
+    'aria-label'?: string;
+}
+/**
+ * Colours as choices: each swatch is a trench the colour pours into, and the chosen one carries the raised white mark,
+ * which travels between swatches as RadioGroup's thumb does. A radio group: arrows move and choose.
+ */
+export declare function ColorSwatchPicker({ swatches, value, defaultValue, onValueChange, className, ...rest }: ColorSwatchPickerProps): React.JSX.Element;
+export interface ColorPickerProps {
+    /** What the colour is for ("Brand colour"). It names the swatches. */
+    label: string;
+    value?: string;
+    defaultValue?: string;
+    /** Called with a lower-case "#rrggbb". */
+    onValueChange?: (value: string) => void;
+    swatches?: ColorSwatch[];
+    /** A hex field and a full picker (area and hue) for any colour. Default false. */
+    allowCustom?: boolean;
+    /** Says in words whether white text and dark text on the colour reach 4.5:1. Default false. */
+    checkContrast?: boolean;
+    className?: string;
+}
+/**
+ * A brand or label colour: swatches as choices (trenches the colour pours into, one travelling mark), and, if allowed,
+ * a hex field that fills when it holds a whole colour and a full picker in a Popover. A contrast check says in words
+ * whether text on the colour passes, because the accent carries text.
+ */
+export declare function ColorPicker({ label, value, defaultValue, onValueChange, swatches, allowCustom, checkContrast, className }: ColorPickerProps): React.JSX.Element;

package/dist/types-cjs/command.d.cts

@@ -0,0 +1,66 @@
+import * as React from 'react';
+export interface CommandItem {
+    /** Stable key within its group. Defaults to the label. */
+    id?: string;
+    label: string;
+    /** A short second line of context (a path, a branch). Matched with less weight than the label. */
+    description?: string;
+    icon?: React.ReactNode;
+    /** Keys shown as Kbd hints, e.g. ['⌘', 'D']. Display only: bind the shortcut yourself. */
+    shortcut?: string[];
+    /** Other words that should find this item (synonyms, old names). */
+    keywords?: string[];
+    onSelect?: () => void;
+    disabled?: boolean;
+    tone?: 'critical';
+    /** Ephemeral adaptation: on opening, predicted items are there at once while the rest fade in over dur-onset. */
+    predicted?: boolean;
+}
+export interface CommandGroup {
+    /** Stable key. Defaults to the group's position. */
+    id?: string;
+    label?: React.ReactNode;
+    items: CommandItem[];
+    /** Every item in the group is predicted: a "Recent" or "Suggested" group. */
+    predicted?: boolean;
+}
+export interface CommandPaletteProps {
+    items: CommandGroup[];
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Called with the chosen item (after its own onSelect). */
+    onSelect?: (item: CommandItem, group: CommandGroup) => void;
+    placeholder?: string;
+    /** Score an item against the query: 0 hides it, higher ranks it nearer the top. Replaces the built-in fuzzy match. */
+    filter?: (item: CommandItem, query: string) => number;
+    /** Shown when nothing matches. A function receives the query. */
+    empty?: React.ReactNode | ((query: string) => React.ReactNode);
+    /** The letter that opens and closes the palette with ⌘ (macOS) or Ctrl. Default 'k'; false for none. */
+    shortcut?: string | false;
+    /** The query, controlled. The palette never clears it on opening: the caller owns it, e.g. a persistent field handing over what was typed. */
+    query?: string;
+    /** What the query is each time the palette opens, uncontrolled. Default ''. */
+    defaultQuery?: string;
+    onQueryChange?: (query: string) => void;
+    /** Close once an item is chosen. Default true. */
+    closeOnSelect?: boolean;
+    /**
+     * The key hints: the footer, the item shortcuts and the field's esc. 'auto' (default): shown where there's likely a
+     * keyboard, hidden on a touch-only device until a key is pressed (#262). true or false forces them.
+     */
+    hints?: boolean | 'auto';
+    className?: string;
+    'aria-label'?: string;
+}
+/**
+ * The built-in ranking. 0 means no match. An exact match beats a prefix, a prefix beats a word start, a word start
+ * beats a substring, and a substring beats letters found in order (fewer gaps rank higher).
+ */
+export declare function commandScore(text: string, query: string): number;
+/**
+ * The summit: a level-5 search over everything you can do, opened with ⌘K or Ctrl+K. The page recedes behind it
+ * as it does for Dialog. The query field is an opening built like Input; one highlight glides between results;
+ * when results change, surviving rows travel to their new places and new ones rise in, a few at a time.
+ */
+export declare function CommandPalette({ items, open, defaultOpen, onOpenChange, onSelect, placeholder, filter, empty, shortcut, query: queryProp, defaultQuery, onQueryChange, closeOnSelect, hints: hintsProp, className, ...rest }: CommandPaletteProps): React.JSX.Element | null;

package/dist/types-cjs/comment-thread.d.cts

@@ -0,0 +1,48 @@
+import * as React from 'react';
+export interface ThreadComment {
+    id: string;
+    author: {
+        name: string;
+        avatar?: string;
+    };
+    /** Plain text; "@Name" for someone mentioned (their names in `mentions`). */
+    body: string;
+    createdAt: Date | string | number;
+    /** One you're posting: pending hovers ("Posting…"), failed drops to a trench with Retry and keeps the text. */
+    status?: 'pending' | 'failed';
+    /** Names mentioned in the body, drawn as plates. */
+    mentions?: string[];
+    /** Yours: it can be deleted. */
+    mine?: boolean;
+    /** Deleted: its result stays in its slot ("Comment deleted") with Undo. */
+    deleted?: boolean;
+}
+export interface Mentionable {
+    id: string;
+    name: string;
+}
+export interface CommentThreadProps {
+    comments: ThreadComment[];
+    /** The thread is resolved: stamped, muted and collapsed to one line, kept in place. */
+    resolved?: {
+        by: string;
+    } | false;
+    onPost?: (body: string, mentions: Mentionable[]) => void;
+    onResolve?: () => void;
+    onReopen?: () => void;
+    onRetry?: (id: string) => void;
+    onDelete?: (id: string) => void;
+    onUndoDelete?: (id: string) => void;
+    /** People who can be mentioned, for a query after "@". */
+    mentionable?: (query: string) => Mentionable[];
+    /** Other people typing now (shown with their presence, never announced). */
+    typing?: string[];
+    'aria-label'?: string;
+    className?: string;
+}
+/**
+ * Comments on a record. Posted comments are the record, flush on the ground; the composer is an opening that fills; a
+ * comment being posted hovers until it lands, or drops to a trench keeping its text. A resolved thread is stamped like a
+ * done Checklist item: muted, collapsed to one line, kept in place. Mentions are a listbox at level 3.
+ */
+export declare function CommentThread({ comments, resolved, onPost, onResolve, onReopen, onRetry, onDelete, onUndoDelete, mentionable, typing, 'aria-label': label, className }: CommentThreadProps): React.JSX.Element;

package/dist/types-cjs/confirmation.d.cts

@@ -0,0 +1,60 @@
+import * as React from 'react';
+export type ConfirmationState = 'requested' | 'approved' | 'running' | 'done' | 'failed' | 'rejected' | 'expired';
+export interface ConfirmationProps {
+    state: ConfirmationState;
+    /** What's proposed ("Send campaign email"). */
+    title: React.ReactNode;
+    /** The concrete consequence, in words ("214 Pro customers will receive “October product update”."). */
+    consequence: React.ReactNode;
+    /** What exactly would change: a DiffView, a list, a preview. */
+    details?: React.ReactNode;
+    /** The verb and outcome ("Send 214 emails"). Default "Approve". */
+    approveLabel?: string;
+    /** Default "Reject". */
+    rejectLabel?: string;
+    /** While it runs ("Sending…"). Default "Working…". */
+    runningLabel?: string;
+    /** Once done ("Sent"). Default "Done". */
+    doneLabel?: string;
+    /** When it failed ("Couldn't send"). Default "Couldn't finish". */
+    failedLabel?: string;
+    /** For consequential actions: approving needs a hold, or a stationary Dialog for irreversible ones. */
+    escalate?: 'hold' | 'dialog';
+    /** Who resolved it and when, for rejected and done ("Maya"). */
+    resolvedBy?: string;
+    resolvedAt?: Date | string | number;
+    /** Who's asking. Default "The assistant". */
+    requestedBy?: string;
+    /**
+     * Wider ways to approve (#280): Approve becomes a SplitButton whose face approves once and whose menu ("More ways to
+     * approve") holds these. Ignored with `escalate`: an action that needs a hold or a dialog is never pre-approved.
+     */
+    scopes?: {
+        value: string;
+        label: string;
+        description?: string;
+    }[];
+    /**
+     * Fields to change the proposal before approving it (#281): an Edit action opens them in place inside the card.
+     * Keep `consequence` and `approveLabel` following the edited values, so Approve names what will happen.
+     */
+    edit?: React.ReactNode;
+    /** The proposal was changed: an "Edited" plate by the title, and "edited and approved by you" once done. */
+    edited?: boolean;
+    /** Cancel edit or Escape in the fields: put the values back. */
+    onEditCancel?: () => void;
+    /** The scope it was approved with ('once', or a scope's value), named in the resolved line. */
+    resolvedScope?: string;
+    /** Called with the scope: 'once' from the face, or a scope's value from the menu. */
+    onApprove?: (scope?: string) => void;
+    onReject?: () => void;
+    onRetry?: () => void;
+    className?: string;
+}
+/**
+ * Approve or reject an action an agent proposes. A proposal is raised, not pending: it's status that asks for action
+ * (Alert's raised rule), naming the consequence, with Approve and Reject. Nothing has been dispatched, so it mustn't
+ * hover. Once approved it becomes a pending write (hovers), then lands or drops to a trench. Rejected and expired are
+ * flush and muted, kept in the record.
+ */
+export declare function Confirmation({ state, title, consequence, details, approveLabel, rejectLabel, runningLabel, doneLabel, failedLabel, escalate, resolvedBy, resolvedAt, requestedBy, scopes, resolvedScope, edit, edited, onEditCancel, onApprove, onReject, onRetry, className }: ConfirmationProps): React.JSX.Element;

package/dist/types-cjs/context-menu.d.cts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { MenuEntry } from './overlays.cjs';
+export interface ContextMenuProps {
+    /** The actions on the thing. A function is called each time the menu opens. Submenus aren't offered: one floating surface at a time. */
+    items: MenuEntry[] | (() => MenuEntry[]);
+    /** The thing: one element. It gets the right-click, the long-press and Shift+F10 / the Menu key. */
+    children: React.ReactElement<any>;
+    /** Names the menu. Default "Actions". */
+    'aria-label'?: string;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * Actions on a thing, opened where you right-click or long-press it, or at it with Shift+F10 or the Menu key. The menu
+ * is DropdownMenu's, at level 3; the thing shows it's the subject with a 2px accent-ink outline, never a height, so a
+ * flush row doesn't lift out of its table. Every action here must also be reachable another way.
+ */
+export declare function ContextMenu({ items, children, 'aria-label': label, onOpenChange }: ContextMenuProps): React.JSX.Element;