altitude-design 0.1.2 → 0.2.1

package/dist/types/collections.d.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { Promised, SkeletonOption } from './suspense';
 export interface TableProps extends React.TableHTMLAttributes<HTMLTableElement> {
     /** The table scrolls under its header past this height. */
     maxHeight?: number | string;
@@ -56,7 +57,10 @@ export type TableSort = {
 } | null;
 export interface DataTableProps<T> {
     columns: DataTableColumn<T>[];
-    rows: 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;
@@ -88,7 +92,7 @@ export interface DataTableProps<T> {
  * 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>({ columns, rows, getRowId, getRowLabel, selectable, selected, defaultSelected, onSelectedChange, actions, toolbar, sort, defaultSort, onSortChange, onRowClick, relevance, onReorder, maxHeight, empty, className, ...rest }: DataTableProps<T>): React.JSX.Element;
+export declare function DataTable<T>({ skeleton, ...props }: DataTableProps<T>): React.JSX.Element;
 export interface BoardPlace {
     column: string;
     index: number;

package/dist/types/command.d.ts

@@ -38,6 +38,10 @@ export interface CommandPaletteProps {
     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;
@@ -56,4 +60,4 @@ export declare function commandScore(text: string, query: string): number;
  * 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, onQueryChange, closeOnSelect, hints, className, ...rest }: CommandPaletteProps): React.JSX.Element | null;
+export declare function CommandPalette({ items, open, defaultOpen, onOpenChange, onSelect, placeholder, filter, empty, shortcut, query: queryProp, defaultQuery, onQueryChange, closeOnSelect, hints, className, ...rest }: CommandPaletteProps): React.JSX.Element | null;

package/dist/types/controls.d.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { DepthProps } from './core';
+import { Promised, SkeletonOption } from './suspense';
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
     size?: 'sm' | 'md' | 'lg';
@@ -13,12 +14,31 @@ export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React
 export interface CardProps extends React.HTMLAttributes<HTMLDivElement>, DepthProps {
     /** Lifts on hover and presses on click. Only set it when the whole card does something. */
     interactive?: boolean;
+    /**
+     * The card holds a Suspense boundary: while anything of yours inside it suspends, the card stays up and its body is an
+     * imprint (a title line and `lines` lines of text, default 3). `false` lets it suspend to your own boundary.
+     * It's also a loading scope: its optional parts (description, body text) wait while its required parts do.
+     */
+    skeleton?: SkeletonOption;
 }
 export declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;
 export declare const CardHeader: ({ className, ...p }: React.HTMLAttributes<HTMLDivElement>) => React.JSX.Element;
-export declare const CardTitle: ({ className, ...p }: React.HTMLAttributes<HTMLHeadingElement>) => React.JSX.Element;
-export declare const CardDescription: ({ className, ...p }: React.HTMLAttributes<HTMLParagraphElement>) => React.JSX.Element;
-export declare const CardContent: ({ className, ...p }: React.HTMLAttributes<HTMLDivElement>) => React.JSX.Element;
+/**
+ * Text that may still be on its way: `undefined` while your data loads (`{user?.name}`), a promise, or one promise among
+ * plain text. `null` renders nothing.
+ */
+type PromisedText<E> = Omit<React.HTMLAttributes<E>, 'children'> & {
+    children?: React.ReactNode | PromiseLike<React.ReactNode> | Array<React.ReactNode | PromiseLike<React.ReactNode>>;
+    /** While the text is on its way, its imprint: `lines` (one for a title, two for a description) and `width`. `false`: render what you pass as it is, and let promises suspend to your own boundary. */
+    skeleton?: SkeletonOption;
+};
+export declare const CardTitle: ({ className, children, skeleton, ...p }: PromisedText<HTMLHeadingElement>) => React.JSX.Element;
+export declare const CardDescription: ({ className, children, skeleton, ...p }: PromisedText<HTMLParagraphElement>) => React.JSX.Element;
+export interface CardContentProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The body holds a Suspense boundary: while anything of yours inside it suspends, or its text (`{user?.bio}`) is undefined while the card's other parts are, it's `lines` lines of imprint (default 3). `false` suspends to your own boundary. */
+    skeleton?: SkeletonOption;
+}
+export declare const CardContent: ({ className, skeleton, children, ...p }: CardContentProps) => React.JSX.Element;
 export declare const CardFooter: ({ className, ...p }: React.HTMLAttributes<HTMLDivElement>) => React.JSX.Element;
 export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
     invalid?: boolean;
@@ -115,7 +135,7 @@ export interface ProgressProps extends React.HTMLAttributes<HTMLDivElement> {
     'aria-label'?: string;
 }
 export declare function Progress({ value, max, className, ...rest }: ProgressProps): React.JSX.Element;
-export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'> {
     tone?: 'neutral' | 'accent' | 'positive' | 'caution' | 'critical';
     /**
      * plate (default): an indicator plate set flush into the page. tinted: the plate takes its tone's colour.
@@ -127,12 +147,18 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
     lamp?: boolean | 'pulse';
     /** @deprecated Use `lamp`. */
     dot?: boolean;
+    /** The label. Undefined while your data loads, or a promise: until it arrives the badge is a plate-shaped imprint. */
+    children?: React.ReactNode | PromiseLike<React.ReactNode> | Array<React.ReactNode | PromiseLike<React.ReactNode>>;
+    /** While the label is on its way: the imprint's `width` (default 64px; a count is round). `false`: render what you pass as it is, and let promises suspend to your own boundary. */
+    skeleton?: SkeletonOption;
 }
 /** A label stamped into the record. Status carries a lamp that relights when it changes; a changed label is re-stamped. */
-export declare function Badge({ tone, variant, lamp, dot, className, children, ...rest }: BadgeProps): React.JSX.Element;
+export declare function Badge({ children, skeleton, ...props }: BadgeProps): React.JSX.Element;
 export interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
-    name: string;
-    src?: string;
+    /** The accessible label. Undefined while your data loads (`user?.name`), or a promise: until it arrives the avatar is a round imprint of its size. */
+    name: Promised<string> | undefined;
+    /** May be a promise, like `name`. */
+    src?: Promised<string | undefined>;
     size?: number;
     /** Presence as height: active people hover above the page (their shadow drops away), idle ones rest on it, offline ones lie flat and grey. */
     status?: 'active' | 'idle' | 'offline';
@@ -142,9 +168,11 @@ export interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
     presence?: 1 | 2 | 3;
     /** The status lamp (green active, amber idle). Default: shown when there is a status and the avatar is 24px or larger. Never shown inside AvatarGroup. */
     lamp?: boolean;
+    /** `false`: no imprint. An undefined `name` renders an empty face; a promised one suspends to your own boundary. */
+    skeleton?: boolean;
 }
 /** A disc above its own shadow. The gap between them is how high the person is: how present they are right now. */
-export declare function Avatar({ name, src, size, status, live, presence, lamp, className, style, onClick, ...rest }: AvatarProps): React.JSX.Element;
+export declare function Avatar({ skeleton, ...props }: AvatarProps): React.JSX.Element;
 export declare function AvatarGroup({ className, children, max, style, ...rest }: React.HTMLAttributes<HTMLDivElement> & {
     max?: number;
 }): React.JSX.Element;
@@ -246,3 +274,4 @@ export interface SortableListProps<T> {
 }
 /** Possession as depth: the item you pick up comes into your hand (level 3), the slot it will land in opens as a well, and it lands with a settle. */
 export declare function SortableList<T>({ items, getKey, onReorder, renderItem, getLabel, gap, className, ...rest }: SortableListProps<T>): React.JSX.Element;
+export {};

package/dist/types/core.d.ts

@@ -43,14 +43,35 @@ export declare const contrast: (a: string, b: string) => number;
  * every surface passed) and `accent-soft` (a tint of the ground).
  */
 export declare function deriveAccent(accent: string, surfaces: string[]): React.CSSProperties;
-export type Scheme = 'daylight' | 'nightfall' | 'mesa' | 'alpine';
+declare const SURFACES: readonly ["surface-trench", "surface-well", "surface-ground", "surface-raised", "surface-lifted", "surface-floating", "surface-overlay", "surface-modal"];
+export type SchemeColorToken = typeof SURFACES[number] | 'ink' | 'ink-muted' | 'ink-faint' | 'line' | 'line-control' | 'accent' | 'on-accent' | 'accent-ink' | 'accent-soft' | 'positive' | 'positive-soft' | 'caution' | 'caution-soft' | 'critical' | 'critical-soft' | 'on-critical' | 'presence-1' | 'presence-2' | 'presence-3' | 'on-presence' | 'scrim';
+export type SchemeShadowToken = 'trench' | 'well' | 'elev-0' | 'elev-1' | 'elev-2' | 'elev-3' | 'elev-4' | 'elev-5' | 'lip-top' | 'lip-bottom';
+/**
+ * Check a scheme against the invariants every scheme keeps: the surfaces climb in lightness (trench < well < ground
+ * < raised ≤ … ≤ modal) and text, control edges and presence colours hold their contrast on every surface. Pass the
+ * colour tokens by name (without `--`), or an element to read them from. Returns one sentence per problem; [] passes.
+ * Only hex values can be measured; any other value of a checked token is reported.
+ */
+export declare function checkScheme(colors: Partial<Record<SchemeColorToken, string>> | Element): string[];
+export interface CustomScheme {
+    /** Stamped as data-scheme on the provider's root. */
+    name: string;
+    /** The built-in scheme your tokens are laid over: any token you leave out comes from it, and so does light or dark
+     *  handling (casts, rims, walls). Use nightfall or alpine for a dark scheme. Default 'daylight'. */
+    base?: BuiltInScheme;
+    /** Colour and shadow tokens by name, without `--`. */
+    tokens: Partial<Record<SchemeColorToken | SchemeShadowToken, string>>;
+}
+export type BuiltInScheme = 'daylight' | 'nightfall' | 'mesa' | 'alpine';
+/** A built-in scheme, the name of your own [data-theme="…"] block, or a CustomScheme. */
+export type Scheme = BuiltInScheme | (string & {});
 type Ctx = {
     host: HTMLElement | null;
     pushLayer: () => () => void;
 };
 export declare const useAltitude: () => Ctx | null;
 export interface AltitudeProviderProps extends React.HTMLAttributes<HTMLDivElement> {
-    scheme?: Scheme;
+    scheme?: Scheme | CustomScheme;
     accent?: string;
     motion?: 'system' | 'full' | 'reduced';
     /** 'more' renders elevation as hard, high-contrast slabs (offset = height). 'system' follows prefers-contrast. */

package/dist/types/empty.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    /** A line icon, drawn in ink-muted: 24px, or 18px at size sm. */
+    icon?: React.ReactNode;
+    /** What is empty, as a statement: "No gift ideas yet". It names the region. */
+    title: React.ReactNode;
+    /** Why it's empty, or what will appear here. Linked as the region's description. */
+    description?: React.ReactNode;
+    /** The one obvious next step: usually a primary Button. */
+    action?: React.ReactNode;
+    /** A quieter alternative beside it: usually a ghost Button or a link. */
+    secondary?: React.ReactNode;
+    /** md fills a page or a panel; sm fits a widget or a list. Default 'md'. */
+    size?: 'sm' | 'md';
+    /** The title's heading level. Default 3. */
+    headingLevel?: 2 | 3 | 4;
+    /** Say it politely when it appears, for an empty that follows a change (a filter, a search). true says the title, if it's text; a string says that. */
+    announce?: boolean | string;
+}
+/**
+ * An opening the first record will fill. Nothing here yet is a well cut into the page (not a raised card, not an
+ * alert), with a dashed rim, a title that names what's empty and one next action standing in it.
+ */
+export declare function EmptyState({ icon, title, description, action, secondary, size, headingLevel, announce, className, children, ...rest }: EmptyStateProps): React.JSX.Element;

package/dist/types/index.d.ts

@@ -1,10 +1,11 @@
 /**
  * altitude-design: a React component library where height is the interface.
- * Docs and live previews: https://richlaconte.github.io/altitude/
+ * Docs and live previews: https://richlaconte.github.io/altitude/storybook/
  * Bugs, feature requests and new components: https://github.com/richlaconte/altitude/issues/new/choose
  * Agents: you may file issues too; see https://github.com/richlaconte/altitude/blob/main/AGENTS.md
  */
-export { AltitudeProvider, useAltitude, useDepth, useApproach, riseDelay, Layer, Surface, Kbd, Icons, Spinner, deriveAccent, contrast, usePresence } from './core';
+export { AltitudeProvider, useAltitude, useDepth, useApproach, riseDelay, Layer, Surface, Kbd, Icons, Spinner, deriveAccent, contrast, checkScheme, usePresence } from './core';
+export type { Scheme, BuiltInScheme, CustomScheme, SchemeColorToken, SchemeShadowToken } from './core';
 export { Button, Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter, Input, Textarea, Field, Checkbox, RadioGroup, Radio, Switch, Tabs, TabsList, TabsTrigger, TabsContent, Slider, Progress, Badge, Avatar, AvatarGroup, Skeleton, Alert, AlertStack, Accordion, HoldButton, ScrollArea, DropZone, SortableList, } from './controls';
 export { Pile } from './pile';
 export { Tooltip, HoverCard, Popover, DropdownMenu, Dialog, Toaster, toast } from './overlays';
@@ -13,4 +14,7 @@ export { Sheet, SheetHeader, SheetTitle, SheetDescription, SheetFooter } from '.
 export { CommandPalette, commandScore } from './command';
 export { Select, SelectItem, Combobox } from './select';
 export { Stepper } from './stepper';
+export { EmptyState } from './empty';
 export { Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption, DataTable, Board, BoardColumn, BoardCard } from './collections';
+export { Await, RevealGroup, readPromised, LoadingScope } from './suspense';
+export type { Promised, Pending, SkeletonOption, AwaitProps } from './suspense';

package/dist/types/overlays.d.ts

@@ -83,12 +83,15 @@ export interface ModalOptions {
     /** Move focus into the panel once it has risen. Default true. */
     autoFocus?: boolean;
     focusSelector?: string;
+    /** Put focus back where it was on close. Default: autoFocus. */
+    restoreFocus?: boolean;
 }
 /**
  * The machinery every layer above the page shares: presence (mount, rise, exit), the receding page,
  * scroll lock, focus in and back out, Escape and the Tab trap. Dialog, Sheet and CommandPalette use it.
  */
-export declare function useModal({ open, onDismiss, exitMs, panel, modal, dismissible, summit, autoFocus, focusSelector }: ModalOptions): {
+export declare const MODAL_FOCUS = "[data-autofocus], input, textarea, select";
+export declare function useModal({ open, onDismiss, exitMs, panel, modal, dismissible, summit, autoFocus, focusSelector, restoreFocus }: ModalOptions): {
     onKeyDown: (e: React.KeyboardEvent) => void;
     mounted: boolean;
     state: "open" | "closed";
@@ -106,9 +109,13 @@ export interface DialogProps {
     size?: 'sm' | 'md' | 'lg';
     /** Set false for decisions that must be answered: the scrim and Escape won't close it. */
     dismissible?: boolean;
+    /** Where focus goes once it has risen: the first field (the default), the title (for a read surface), or nowhere (you move it yourself). */
+    initialFocus?: 'first-field' | 'title' | false;
+    /** What 'first-field' looks for. Default '[data-autofocus], input, textarea, select'; the panel itself if nothing matches. */
+    focusSelector?: string;
     className?: string;
 }
-export declare function Dialog({ open, defaultOpen, onOpenChange, trigger, title, description, children, footer, size, dismissible, className }: DialogProps): React.JSX.Element;
+export declare function Dialog({ open, defaultOpen, onOpenChange, trigger, title, description, children, footer, size, dismissible, initialFocus, focusSelector, className }: DialogProps): React.JSX.Element;
 export type ToastTone = 'neutral' | 'positive' | 'caution' | 'critical';
 export interface ToastOptions {
     title: React.ReactNode;

package/dist/types/suspense.d.ts

@@ -0,0 +1,74 @@
+import * as React from 'react';
+/** A value, or a promise of one. A component that takes one shows its own imprint until it lands. */
+export type Promised<T> = T | PromiseLike<T>;
+/** Hints for a component's imprint, or `false` to let it suspend to your own boundary instead. */
+export type SkeletonOption = boolean | {
+    lines?: number;
+    width?: number | string;
+};
+export declare const isPromise: (v: unknown) => v is PromiseLike<unknown>;
+/** Content that may still be on its way: `undefined` while your data loads, or a promise. `null` means there is nothing. */
+export type Pending<T> = T | PromiseLike<T> | undefined;
+/** Children that hold a promise, at the top level or one level down (`Welcome back, {name}`). */
+export declare const hasPromise: (children: unknown) => boolean;
+/**
+ * Reads a promised value, suspending until it lands. React 19's `use()` when it's there; on React 18, the same contract
+ * by hand (the promise is thrown to the nearest Suspense boundary and its result remembered).
+ */
+export declare function readPromised<T>(v: Promised<T>): T;
+/** Reads promised children, at the top level or one level down. */
+export declare function readChildren(children: unknown): React.ReactNode;
+/**
+ * Turns "not here yet" into a suspension: while `waiting`, returns a promise that resolves once it stops, for the
+ * component's inner part to read (see Arrive), so its own boundary shows the imprint. Call it in the outer part, which
+ * stays mounted and re-renders when your data arrives.
+ */
+export declare function useArrival(waiting: boolean): PromiseLike<void> | null;
+/** Suspends while `when` is pending; renders its children once it isn't. */
+export declare function Arrive({ when, children }: {
+    when: PromiseLike<void> | null;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** True from the first render that waited onwards, so the boundary stays mounted and the content can rise out of it. */
+export declare function useHasWaited(waiting: boolean): boolean;
+export declare function LoadingScope({ children }: {
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** For required content (an avatar's name, a title, a badge's label, a table's rows): says whether it's still on its way. */
+export declare function useReportWaiting(waiting: boolean): void;
+/** For optional content: is the card it's in still waiting for its required parts? */
+export declare const useScopeWaiting: () => boolean;
+/**
+ * Imprints inside a RevealGroup land together: each one that finishes waits, still an imprint, until the slowest has
+ * landed, then they all rise at once (four at a time, as always). Group things that load from the same place.
+ */
+export declare function RevealGroup({ children }: {
+    children?: React.ReactNode;
+}): React.JSX.Element;
+export interface AwaitProps {
+    /** The imprint: the fallback while the children suspend. */
+    imprint: React.ReactNode;
+    /** The shape left behind as content rises out of it. `none` for containers: their content just rises. */
+    shape?: 'circle' | 'text' | 'block' | 'none';
+    /** Sits in a line of text or a row of controls (an avatar, a badge) rather than as a block. */
+    inline?: boolean;
+    /** `false`: no boundary; the children suspend to yours. */
+    enabled?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * A Suspense boundary whose fallback is an imprint, and whose content rises out of it. Every Suspense-native Altitude
+ * component holds one; use it in your own components to give them the same behaviour.
+ */
+export declare function Await({ imprint, shape, inline, enabled, className, children }: AwaitProps): React.JSX.Element;
+/** Lines of text, as tall as the text they stand for (each line is one line-height of the surrounding type). */
+export declare function TextImprint({ lines, width, className }: {
+    lines?: number;
+    width?: number | string;
+    className?: string;
+}): React.JSX.Element;
+export declare const hint: (s: SkeletonOption | undefined) => {
+    lines?: number;
+    width?: number | string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altitude-design",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "A React component library where height is the interface: the ground is the record.",
   "keywords": [
     "react",
@@ -29,6 +29,8 @@
       "require": "./dist/index.cjs"
     },
     "./altitude.css": "./dist/altitude.css",
+    "./altitude.no-fonts.css": "./dist/altitude.no-fonts.css",
+    "./fonts.css": "./dist/fonts.css",
     "./tokens.css": "./dist/tokens.css",
     "./tokens.json": "./dist/tokens.json",
     "./altitude.iife.js": "./dist/altitude.iife.js",
@@ -51,7 +53,8 @@
     "build": "node scripts/build-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit --declaration false --emitDeclarationOnly false",
     "storybook": "node scripts/stories.mjs && storybook dev -p 6006",
-    "build-storybook": "node scripts/stories.mjs && storybook build -o storybook-static --quiet"
+    "build-storybook": "node scripts/stories.mjs && storybook build -o storybook-static --quiet",
+    "build-site": "node scripts/build-site.mjs"
   },
   "devDependencies": {
     "@storybook/addon-docs": "10.6.1",