// The shared control and row vocabulary (Master Control, revision 2). Every // list in the app is one row primitive with a fixed action column, and every // button is one of five controls. A view that cannot fit them grows a variant // here; it does not keep a private copy. import { type ComponentProps, createContext, type HTMLAttributes, type KeyboardEvent, type MouseEvent, type ReactNode, type Ref, useCallback, useContext, useState, } from "react"; import { Icon, type IconName, useArmed } from "./icons"; import { type ControlLook, chip, control, cx, toggle, toggleLamp, toggleState, type } from "./look"; export type Tone = "fault" | "warn"; export { cx } from "./look"; /** A boolean data attribute: present (empty) or absent. */ export function flag(on: boolean | undefined): "" | undefined { return on ? "" : undefined; } /* ---- controls ------------------------------------------------------------ */ export interface ControlProps extends ComponentProps<"button"> { /** The word on the plate. */ text: string; /** Secondary actions: ink on a hairline, never a toggle. */ quiet?: boolean; /** A leading glyph beside the word. */ glyph?: IconName; /** Fixed width, so a label that changes (GRAB → SENDING → SENT) never moves the row. */ fixed?: boolean; /** Full width, content at the start: a phone tray or a settings panel. */ fill?: boolean; danger?: boolean; state?: ControlLook["state"]; busy?: boolean; done?: boolean; failed?: boolean; } /** A word control: the primary action of a header or panel, or a quiet secondary one. */ export function Control({ text, quiet, glyph, fixed, fill, danger, state, busy, done, failed, className, ...rest }: ControlProps) { return ( ); } /** A 44px square glyph control. The label is the accessible name and nothing else. */ export function IconControl({ glyph, label, look, shape = "icon", className, ...rest }: ComponentProps<"button"> & { glyph: IconName; label: string; look?: ControlLook["look"]; shape?: "icon" | "chip"; }) { return ( ); } /** An external link wearing the icon control's skin. */ export function IconLink({ label, href, shape = "icon", children, }: { label: string; href: string; shape?: "icon" | "trailer"; children: ReactNode; }) { return ( {children} ); } /** * A rule that is on or off: a lamp plus the word, never a border colour * alone (the Word-Beside-The-Lamp rule). The state word has a fixed width, * so flipping it never moves anything. */ export function LampToggle({ label, pressed, fill = false, ...rest }: ComponentProps<"button"> & { label: string; pressed: boolean; /** Full width, content at the start: a phone tray or a settings panel. */ fill?: boolean; "data-focus-id"?: string; }) { return ( ); } /** * Show / hide at full control height. The verb swaps but the plate keeps * one width, and the count is tabular, so opening never moves the head. */ export function Disclosure({ noun = "", count, open, onToggle, }: { noun?: string; count: number; open: boolean; onToggle: () => void; }) { return ( ); } /** * The arm-then-confirm as a labelled control, for the ⋯ tray where a phone * spells the action out. Full width there, so the armed label can be longer. */ export function ArmedDeleteWord({ label, execute, }: { label: string; execute: () => Promise | undefined; }) { const { armed, spent, click, disarm } = useArmed(execute); return ( { if (armed) { disarm(); } }} /> ); } /* ---- status -------------------------------------------------------------- */ export interface Status { text: string; tone?: Tone; busy?: boolean; /** A way out carried by the sentence itself (a quiet control after it). */ action?: { label: string; run: () => void }; } /** * A status slot. The slot is always laid out — an empty one keeps its line — * so a message arriving or leaving never pushes the content below it. */ const SLOT = { // a page bar's one line, ellipsised: a message never pushes the page down head: "flex-1 min-w-0 m-0 overflow-hidden whitespace-nowrap text-ellipsis", // a section's line: reserved, and wraps only when the sentence must deck: "flex items-center flex-wrap gap-y-2 gap-x-3 min-h-chip-h mb-3", } as const; export function StatusSlot({ status, variant, }: { status: Status | null; variant: keyof typeof SLOT; }) { return (

{status?.busy && (

); } /** A status setter for one slot, with the same signature everywhere. */ export function useStatus(): [ Status | null, (text: string | null, tone?: Tone, busy?: boolean) => void, ] { const [status, setStatus] = useState(null); const set = useCallback((text: string | null, tone?: Tone, busy = false) => { setStatus(text === null ? null : { text, tone, busy }); }, []); return [status, set]; } /* ---- the row's note ---------------------------------------------------------- */ export interface Note { text: string; tone?: Tone; } export type Say = (text: string | null, tone?: Tone) => void; /** The row's status slot, in the tray. Null clears it. */ export function useNote(): [Note | null, Say] { const [note, setNote] = useState(null); const say = useCallback((text, tone) => { setNote(text === null ? null : { text, tone }); }, []); return [note, say]; } /** A note line outside a row, written the way a row's own slot is. */ export function NoteLine({ note, className }: { note: Note | null; className: string }) { return ( ); } /* ---- chips ------------------------------------------------------------------- */ export interface Explain { text: string; say: Say; tone?: Tone; } /** * A chip whose meaning would otherwise live in a tooltip. Touch has no hover, * so the chip becomes a button that writes its sentence into the row's own * status slot, and a second tap takes it away. */ function useExplain(explain: Explain | undefined) { const [open, setOpen] = useState(false); if (!explain) { return {}; } const toggle = (event: MouseEvent | KeyboardEvent) => { event.stopPropagation(); event.preventDefault(); const next = !open; setOpen(next); explain.say(next ? explain.text : null, explain.tone); }; return { role: "button", tabIndex: 0, "data-explain": "", "aria-expanded": open, onClick: toggle, onKeyDown: (event: KeyboardEvent) => { if (event.key === "Enter" || event.key === " ") { toggle(event); } }, }; } export interface ChipProps extends HTMLAttributes { /** The whole label is a glyph. */ glyph?: boolean; /** A live download's chip. */ download?: boolean; explain?: Explain; [data: `data-${string}`]: string | undefined; } /** A chip, the §9.3 column unit. Its look is read off its own data attributes. */ export function Chip({ glyph, download, className, explain, children, ...rest }: ChipProps) { const explainProps = useExplain(explain); return ( {children} ); } /* ---- the row --------------------------------------------------------------- */ /** One cell in a row's action column. An empty cell still takes its width. */ export interface ActionSlot { node: ReactNode | null; /** The width class: a glyph square, a lamp toggle, or a fixed word control. */ width: "icon" | "toggle" | "word"; /** Shown from 40rem up; on a phone this action lives in the ⋯ tray instead. */ wide?: boolean; /** Shown below 40rem only — an empty cell that keeps a phone column aligned. */ narrow?: boolean; /** A word or toggle control fills its column; an input keeps its own width. */ fill?: boolean; } export interface RowProps { /** `data-row`: which kind of row, for the few rules that differ by kind. */ kind: string; lead?: ReactNode; title?: ReactNode; titleClassName?: string; /** The chip line. */ meta?: ReactNode; sub?: ReactNode; /** The sub line opens to its full string on a tap. */ subExpands?: boolean; /** Body content between the chip line and the sub line. */ beforeSub?: ReactNode; /** Body content after the sub line. */ afterSub?: ReactNode; bodyClassName?: string; onBodyClick?: (event: MouseEvent) => void; actions?: ActionSlot[]; /** The phone tray: labelled, full-width versions of the wide-only actions. */ more?: ReactNode; /** The whole row opens something: a stretched button under the controls. */ open?: { label: string; run: (origin: HTMLElement) => void; chevron?: boolean; className?: string; expanded?: boolean; disabled?: boolean; }; note?: Note | null; /** Full-width area under the line: inline panels after the note. */ tray?: ReactNode; } /** A sub line that opens to its full string on a tap. */ export function Expandable({ className, children }: { className: string; children: ReactNode }) { const [full, setFull] = useState(false); return ( // biome-ignore lint/a11y/noStaticElementInteractions: a reading aid, the text is already all there for a screen reader // biome-ignore lint/a11y/useKeyWithClickEvents: same
setFull(!full)}> {children}
); } /** * The one row: `lead | body | actions`, plus a full-width tray. The body is * `minmax(0, 1fr)`, so a long title or a run of chips is clipped inside it * and can never push the actions onto a second line. */ export function Row(props: RowProps) { const [moreOpen, setMoreOpen] = useState(false); const { open, actions = [] } = props; return (
  • {open && (
  • ); } /** A row-shaped placeholder: same height and columns as the row it stands for. */ export function SkeletonRows({ count, withLead = true }: { count: number; withLead?: boolean }) { return Array.from({ length: count }, (_, index) => ( // biome-ignore lint/suspicious/noArrayIndexKey: placeholders have no identity )); } /** A list's one-line empty or error state, at row height. */ export function EmptyRow({ text, tone, children, }: { text: string; tone?: "fault"; children?: ReactNode; }) { return (
  • {text} {children}
  • ); } /* ---- page skeleton ------------------------------------------------------- */ /** * A page: the one centred column, and a container, so a row answers to the * page's width rather than the window's. The gutter belongs to the content; * a child marked `data-bleed` (the detail hero) reaches both edges. */ export function Deck({ label, detail = false, hidden, id, ref, onKeyDown, children, }: { label: string; /** A detail page opens on its hero, so the page drops its top padding. */ detail?: boolean; hidden?: boolean; id?: string; ref?: Ref; onKeyDown?: (event: KeyboardEvent) => void; children: ReactNode; }) { return (
    {children}
    ); } /** A page's line: title, count, a one-line status slot, the page's controls. */ export function PageBar({ title, count, status, children, }: { title: string; /** Absent leaves the count's slot out entirely. */ count?: string; status: Status | null; children?: ReactNode; }) { return (

    {title}

    {count !== undefined && {count}} {children}
    ); } /** Whether a section sits inside another: its head is then a quieter group label. */ const Nested = createContext(false); const InnerSection = createContext(false); /** A section of a page; `spacing` replaces the default gap after it. */ export function Section({ spacing = "mb-8", hidden, labelledBy, ref, className, children, }: { spacing?: string; hidden?: boolean; labelledBy?: string; ref?: Ref; /** A marker other rules still key on, such as `subs-lane`. */ className?: string; children: ReactNode; }) { const outer = useContext(Nested); return ( ); } /** A section head: the engraved label, a count, then whatever acts on it. */ export function DeckHead({ label, labelId, as: Heading = "h3", titled = "label", count, children, }: { label: string; labelId?: string; as?: "h3" | "h4"; /** A page's section title, or a group's engraved label. */ titled?: "section" | "label"; count?: string | number | null; children?: ReactNode; }) { // nested heads inside a section are group labels, one step quieter const nested = useContext(InnerSection); return (
    {label} {count !== undefined && {count ?? ""}} {children}
    ); } /** A list of rows, or of poster cards. */ export function Rows({ grid = false, className, hidden, children, }: { grid?: boolean; /** A marker other rules still key on, such as `seasons`. */ className?: string; hidden?: boolean; children?: ReactNode; }) { return (
      {children}
    ); } /** A group's one plain sentence, which opens to the long form on a tap. */ export function GroupNote({ short, more }: { short: string; more?: string }) { const [open, setOpen] = useState(false); return (

    {short}

    {more !== undefined && ( <> setOpen(!open)} look="faint" shape="chip" /> )}
    ); }