@lar-works/design-system 0.2.1 → 0.3.0

package/src/board/AddItem.tsx

@@ -0,0 +1,259 @@
+// Lar Factory's Add item: the title bar's button that opens it, the New work pane's fields beside their details panel,
+// the panel's labelled fields and ticket part, the Create issue choice, and the Find a ticket pane with its search.
+
+import { SquarePenIcon } from 'lucide-react';
+import type { KeyboardEvent, ReactNode, Ref } from 'react';
+
+import { Button } from '../actions/Button';
+import { FormResult } from '../feedback/FormResult';
+import { FormFieldset } from '../forms/FormSection';
+import { Input } from '../forms/Input';
+import { tabbable } from '../foundations/KeyboardFocus';
+import { buttonKind } from './ButtonKinds';
+import { DetailsHeading } from './ItemDetails';
+
+/** The title bar's Add item button, a Main action named by its `label`, which folds away, for screen readers only, on a
+ *  title bar under 70rem; `title` gives it whole with its shortcut, which `keyShortcuts` names. */
+export function AddItemButton({
+    label,
+    title,
+    keyShortcuts,
+    onOpen,
+}: {
+    label: string;
+    title: string;
+    keyShortcuts?: string;
+    onOpen: () => void;
+}) {
+    return (
+        <Button
+            {...buttonKind('main')}
+            className="add-item px-2"
+            leftIcon={<SquarePenIcon />}
+            title={title}
+            aria-keyshortcuts={keyShortcuts}
+            onClick={onOpen}
+        >
+            <span className="@max-[70rem]:sr-only">{label}</span>
+        </Button>
+    );
+}
+
+/**
+ * A draft's fields as one group, which `disabled` locks: the `main` column (its title, editor and notes) beside the
+ * `details` panel, which `detailsLabel` names. Narrower than 40rem the panel stacks under the main column, which then
+ * grows with its text, and the two scroll as one; each row sizes to its content, so a long text pushes the panel down
+ * rather than running under it.
+ */
+export function DraftFields({
+    id,
+    disabled,
+    detailsLabel,
+    main,
+    details,
+}: {
+    id: string;
+    disabled: boolean;
+    detailsLabel: string;
+    main: ReactNode;
+    details: ReactNode;
+}) {
+    return (
+        <div className="@container flex min-h-0 flex-1 flex-col">
+            <FormFieldset
+                id={id}
+                presentation="group"
+                disabled={disabled}
+                className="border-base-300 grid min-h-0 flex-1 grid-cols-[minmax(0,1fr)_16rem] border-t @max-[40rem]:auto-rows-max @max-[40rem]:grid-cols-[minmax(0,1fr)] @max-[40rem]:content-start @max-[40rem]:overflow-y-auto"
+            >
+                <div className="flex min-h-0 flex-col gap-3 overflow-y-auto px-5 pt-4 pb-5 sm:px-6 @max-[40rem]:min-h-80 @max-[40rem]:overflow-visible">
+                    {main}
+                </div>
+                <aside
+                    aria-label={detailsLabel}
+                    className="border-base-300 bg-base-50/60 grid content-start gap-5 overflow-y-auto border-l px-4 py-4 @max-[40rem]:overflow-visible @max-[40rem]:border-t @max-[40rem]:border-l-0"
+                >
+                    {details}
+                </aside>
+            </FormFieldset>
+        </div>
+    );
+}
+
+/**
+ * A field of a details panel under its small uppercase `heading`, which labels the field `htmlFor` names; without
+ * `htmlFor`, the field is a group of controls that the heading names, such as a ticket's labels (`id` and `ref` reach
+ * the group).
+ */
+export function PanelField({
+    heading,
+    htmlFor,
+    id,
+    ref,
+    children,
+}: {
+    heading: string;
+    htmlFor?: string;
+    id?: string;
+    ref?: Ref<HTMLDivElement>;
+    children: ReactNode;
+}) {
+    if (htmlFor)
+        return (
+            <div className="grid gap-1.5">
+                <DetailsHeading presentation="label" as="label" htmlFor={htmlFor}>
+                    {heading}
+                </DetailsHeading>
+                {children}
+            </div>
+        );
+
+    return (
+        <div ref={ref} id={id} role="group" aria-label={heading} className="grid gap-1.5">
+            <DetailsHeading presentation="label" as="span">
+                {heading}
+            </DetailsHeading>
+            {children}
+        </div>
+    );
+}
+
+/** The details panel's ticket part, ruled off from the fields above it: a ticket's own fields, or what a draft without
+ *  one keeps. */
+export function DraftTicketPart({ children }: { children: ReactNode }) {
+    return <div className="border-base-300 grid gap-3 border-t pt-4">{children}</div>;
+}
+
+/** Create issue in the footer: its `checkbox`, then the `reason` it can't be ticked, kept to a readable width, and any
+ *  `error`. */
+export function CreateIssueChoice({
+    checkbox,
+    reason,
+    error,
+}: {
+    checkbox: ReactNode;
+    reason?: ReactNode;
+    error?: ReactNode;
+}) {
+    return (
+        <div className="grid gap-1">
+            {checkbox}
+            {reason && <div className="max-w-md">{reason}</div>}
+            {error}
+        </div>
+    );
+}
+
+/** The Find a ticket pane, ruled off from the header: its notes and fields, one under the other, scrolling above the
+ *  footer when a long result list needs it. */
+export function TicketSearchPane({ id, children }: { id: string; children: ReactNode }) {
+    return (
+        <div
+            id={id}
+            className="border-base-300 grid min-h-0 content-start gap-4 overflow-y-auto border-t px-5 pt-4 pb-5 sm:px-6"
+        >
+            {children}
+        </div>
+    );
+}
+
+/** A ticket a search found: its number, its title and a short `note`, such as that it is on the board already. */
+export interface TicketSearchMatch {
+    number: number;
+    title: string;
+    note?: string | undefined;
+}
+
+/**
+ * A search of a tracker's open tickets: the field (`fieldLabel` names it) with its Search button, which Enter also
+ * runs, the matches, each a button that picks it, and the search's `result`, announced. `id` prefixes the field's,
+ * the button's and the result's ids. `busy` stops a pick while a search or a pick runs, and `picking` marks the list
+ * as busy.
+ */
+export function TicketSearch({
+    id,
+    query,
+    onQueryChange,
+    onSearch,
+    fieldLabel,
+    placeholder,
+    searchLabel,
+    disabled = false,
+    searchDisabled = false,
+    tickets,
+    listLabel,
+    busy = false,
+    picking = false,
+    onPick,
+    result,
+}: {
+    id: string;
+    query: string;
+    onQueryChange: (query: string) => void;
+    onSearch: () => void;
+    fieldLabel: string;
+    placeholder: string;
+    searchLabel: string;
+    disabled?: boolean | undefined;
+    searchDisabled?: boolean;
+    tickets: readonly TicketSearchMatch[];
+    listLabel: string;
+    busy?: boolean;
+    picking?: boolean;
+    onPick: (number: number) => void;
+    result: string;
+}) {
+    const onKey = (event: KeyboardEvent<HTMLInputElement>) => {
+        if (event.key !== 'Enter') return;
+
+        event.preventDefault();
+        onSearch();
+    };
+
+    return (
+        <div className="grid gap-2" data-ticket-picker>
+            <div className="flex gap-2">
+                <Input
+                    id={`${id}-query`}
+                    type="search"
+                    value={query}
+                    onChange={(event) => onQueryChange(event.currentTarget.value)}
+                    onKeyDown={onKey}
+                    disabled={disabled}
+                    autoComplete="off"
+                    aria-label={fieldLabel}
+                    placeholder={placeholder}
+                    className="min-w-0 flex-1"
+                />
+                <Button {...buttonKind('other')} id={`${id}-search`} disabled={searchDisabled} onClick={onSearch}>
+                    {searchLabel}
+                </Button>
+            </div>
+            {tickets.length > 0 && (
+                <ul className="m-0 grid list-none gap-0.5 p-0" aria-label={listLabel} aria-busy={picking}>
+                    {tickets.map((ticket) => (
+                        <li key={ticket.number}>
+                            <button
+                                {...tabbable}
+                                type="button"
+                                data-ticket={ticket.number}
+                                disabled={busy}
+                                onClick={() => onPick(ticket.number)}
+                                className="hover:bg-base-200/70 focus-visible:outline-primary flex w-full min-w-0 items-baseline gap-2 rounded-md px-2 py-1.5 text-left text-sm focus-visible:outline-2 disabled:opacity-60"
+                            >
+                                <span className="shrink-0 text-(--muted-foreground) tabular-nums">
+                                    #{ticket.number}
+                                </span>
+                                <span className="min-w-0 flex-1 truncate">{ticket.title}</span>
+                                {ticket.note && (
+                                    <span className="shrink-0 text-xs text-(--muted-foreground)">{ticket.note}</span>
+                                )}
+                            </button>
+                        </li>
+                    ))}
+                </ul>
+            )}
+            <FormResult id={`${id}-result`} text={result} />
+        </div>
+    );
+}

package/src/board/Archive.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react';
+
+import { Text } from '../typography/Typography';
+
+/** A row's actions at its right, with what they last did and an error under them. */
+export function ActionStack({
+    children,
+    below,
+    error,
+}: {
+    children: ReactNode;
+    below?: ReactNode;
+    error?: string | null;
+}) {
+    return (
+        <span className="flex flex-col items-end gap-1">
+            <span className="flex flex-wrap items-center gap-2">{children}</span>
+            {below}
+            {error && (
+                <Text variant="caption" tone="danger" role="alert">
+                    {error}
+                </Text>
+            )}
+        </span>
+    );
+}
+
+/** A setting's confirmation, inline under it, before it saves: what it would do now, the work it names, and the
+ *  buttons that cancel or go ahead. */
+export function SettingConfirm({
+    label,
+    message,
+    items,
+    actions,
+}: {
+    label: string;
+    message: string;
+    items: readonly string[];
+    actions: ReactNode;
+}) {
+    return (
+        <div
+            className="grid gap-2 rounded-lg border border-(--border) p-3 text-sm"
+            role="alertdialog"
+            aria-label={label}
+            data-delete-confirm
+        >
+            <p className="m-0">{message}</p>
+            {items.length > 0 && (
+                <ul className="m-0 grid gap-0.5 pl-4">
+                    {items.map((item, index) => (
+                        <li key={index}>{item}</li>
+                    ))}
+                </ul>
+            )}
+            <span className="flex gap-2">{actions}</span>
+        </div>
+    );
+}
+
+/** What a setting's last run did, and each thing it kept with why. */
+export function SettingLastRun({ summary, kept }: { summary: string; kept: readonly string[] }) {
+    return (
+        <div className="grid gap-1 text-xs text-(--muted-foreground)" data-last-delete>
+            <p className="m-0">{summary}</p>
+            {kept.length > 0 && (
+                <ul className="m-0 grid gap-0.5 pl-4">
+                    {kept.map((line, index) => (
+                        <li key={index}>{line}</li>
+                    ))}
+                </ul>
+            )}
+        </div>
+    );
+}

package/src/board/Attention.tsx

@@ -0,0 +1,135 @@
+// An expanded dossier's attention list: what keeps its work moving, as labelled rows of entries, and the parts and
+// references its entries name.
+
+import { BanIcon, CheckIcon, CircleHelpIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import type { DataAttributes } from './DataAttributes';
+import { ROW_OPENS } from './RowStyles';
+
+const TONE = {
+    yours: 'text-(--warning-foreground)',
+    decision: 'text-(--primary)',
+    blocked: 'text-(--st-review)',
+    waiting: 'text-(--muted-foreground)',
+    ready: 'text-(--st-now)',
+    fog: 'text-(--st-amber)',
+} as const;
+
+/** An attention row's tone, which colours its label. */
+export type AttentionTone = keyof typeof TONE;
+
+/** The attention rows, each a label in its tone with how many entries it has, then its entries. */
+export function AttentionList({
+    rows,
+}: {
+    rows: { key: string; label: string; tone: AttentionTone; entries: ReactNode[] }[];
+}) {
+    return (
+        // The labels' column is 7.5rem, or as wide as the longest label so none wraps ("To verify or merge" needs more).
+        <dl className="m-0 grid grid-cols-[minmax(7.5rem,max-content)_minmax(0,1fr)] gap-x-4 gap-y-2" data-attention>
+            {rows.map((r) => (
+                <div key={r.key} className="contents" data-attention-row={r.key}>
+                    <dt
+                        className={`pt-2 text-[11px] font-medium tracking-wide whitespace-nowrap uppercase ${TONE[r.tone]}`}
+                    >
+                        {r.label} <span className="tabular-nums">{r.entries.length}</span>
+                    </dt>
+                    <dd className="m-0 grid gap-1">{r.entries}</dd>
+                </div>
+            ))}
+        </dl>
+    );
+}
+
+/** What the attention list says when nothing holds the work up. */
+export function AttentionNone({ children }: { children: ReactNode }) {
+    return (
+        <p className="m-0 text-[13px] text-(--muted-foreground)" data-attention-none>
+            {children}
+        </p>
+    );
+}
+
+/** One entry of an attention row, with what it waits on or its next action at the right. */
+export function AttentionEntry({ main, side }: { main: ReactNode; side?: ReactNode }) {
+    return (
+        <div className="flex min-h-9 min-w-0 flex-wrap items-center justify-between gap-x-3 gap-y-1 rounded-md px-2 py-1.5 hover:bg-(--soft)">
+            <span className="min-w-0 flex-1 basis-64">{main}</span>
+            {side && <span className="ml-auto shrink-0 text-xs text-(--muted-foreground)">{side}</span>}
+        </div>
+    );
+}
+
+/** An entry's text as a plain button that opens what it names. */
+export function EntryButton({ onOpen, children }: { onOpen: () => void; children: ReactNode }) {
+    return (
+        <button type="button" onClick={onOpen}>
+            {children}
+        </button>
+    );
+}
+
+/** A reference to an item, such as `#12`, as a button that opens it; `title` names it. */
+export function RefButton({ title, onOpen, children }: { title: string; onOpen: () => void; children: ReactNode }) {
+    return (
+        <button
+            type="button"
+            onClick={onOpen}
+            title={title}
+            className="rounded px-0.5 font-medium text-(--primary) tabular-nums hover:bg-(--accent)"
+        >
+            {children}
+        </button>
+    );
+}
+
+const MARKS = {
+    blocked: <BanIcon className="mt-0.5 size-3.5 shrink-0 text-(--st-review)" />,
+    met: <CheckIcon className="mt-0.5 size-3.5 shrink-0 text-(--st-done)" />,
+    fog: <CircleHelpIcon className="mt-0.5 size-3.5 shrink-0 text-(--st-amber)" />,
+} as const;
+
+/** An entry's text after a mark: blocked, met, or an open question (fog). `clamp` keeps it to two lines. */
+export function AttentionMark({
+    mark,
+    clamp = false,
+    children,
+    ...data
+}: {
+    mark: keyof typeof MARKS;
+    clamp?: boolean;
+    children: ReactNode;
+} & DataAttributes) {
+    return (
+        <span {...data} className={`flex ${clamp ? 'min-w-0 ' : ''}items-start gap-1.5 text-[13px]`}>
+            {MARKS[mark]}
+            <span className={clamp ? 'line-clamp-2' : undefined}>{children}</span>
+        </span>
+    );
+}
+
+/** A part's source, status glyph and title, up to two lines. */
+export function PartName({ source, glyph, children }: { source: ReactNode; glyph: ReactNode; children: ReactNode }) {
+    return (
+        <span className="flex min-w-0 items-start gap-1.5 text-sm">
+            {source}
+            <span className="mt-0.5 inline-flex">{glyph}</span>
+            <span className="line-clamp-2">{children}</span>
+        </span>
+    );
+}
+
+/** A part's PartName as a button that opens it; `title` names it. */
+export function PartLink({ title, onOpen, children }: { title: string; onOpen: () => void; children: ReactNode }) {
+    return (
+        <button
+            type="button"
+            onClick={onOpen}
+            title={title}
+            className={`min-w-0 rounded text-left hover:underline ${ROW_OPENS}`}
+        >
+            {children}
+        </button>
+    );
+}

package/src/board/BoardShell.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+
+import { Loading } from '../feedback/Loading';
+
+/** Lar Factory's window: the board's main area filling the window, and beside it, outside `main`, what sits over the
+ *  board (its dialogs, live regions and notifications), so their announcements sit apart from the page. */
+export function BoardShell({ children, overlays }: { children: ReactNode; overlays?: ReactNode }) {
+    return (
+        <div className="fixed inset-0 flex flex-col bg-(--background) text-(--foreground)">
+            <main className="flex min-h-0 min-w-0 flex-1 flex-col">{children}</main>
+            {overlays}
+        </div>
+    );
+}
+
+/** Everything under the title bar, which scrolls as one page; nothing in it shrinks to fit. */
+export function BoardContent({ children }: { children: ReactNode }) {
+    return (
+        <div className="flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto px-6 pt-3 pb-4 *:shrink-0">{children}</div>
+    );
+}
+
+/** A line that stands in for content the board is still reading, centred in its area. */
+export function ReadingLine({ label }: { label: string }) {
+    return (
+        <p className="text-base-700 m-0 flex items-center justify-center gap-2 p-6 text-sm" data-reading>
+            <Loading label={label} presentation="line" />
+        </p>
+    );
+}

package/src/board/BoardTitleBar.tsx

@@ -0,0 +1,167 @@
+import type { ReactNode } from 'react';
+
+import { BrandMark } from '../display/BrandMark';
+import { TitleBar } from '../layout/TitleBar';
+import { Tooltip, TooltipPopup, TooltipTrigger } from '../overlays/Tooltip';
+
+/** The window drags from the bar, but never from a control in it. */
+const drag = '[-webkit-app-region:drag] [&_:is(button,a,[tabindex])]:[-webkit-app-region:no-drag]';
+
+interface BoardTitleBarProps {
+    /** The lockup on the left, such as BoardBrand. */
+    brand: ReactNode;
+    /** The page's heading, for screen readers only, as the brand is hidden from them. A closing dialog whose opener
+     *  went away can put the focus on it. */
+    heading?: string;
+    /** How the board is doing, in the status strip: the Refreshed time, then the counters after a divider. */
+    refreshed?: ReactNode;
+    counters?: ReactNode;
+    /** The search field, up to 26rem wide beside the actions. */
+    search?: ReactNode;
+    actions: ReactNode;
+    /** In the Mac app, where macOS draws the traffic lights; in a browser, grey stand-ins hold their place. */
+    nativeWindow: boolean;
+    /** Starts the bar past the traffic lights; off while full screen hides them. */
+    pastLights: boolean;
+}
+
+/**
+ * Lar Factory's title bar, laid out as lar-server's on the design system's TitleBar: the brand and how the board is
+ * doing on the left, the search field and what you can do on the right. The bar drags the window, except on its
+ * controls, and folds by its own width: below 48rem the actions take their own row and the status strip goes.
+ */
+export function BoardTitleBar({
+    brand,
+    heading,
+    refreshed,
+    counters,
+    search,
+    actions,
+    nativeWindow,
+    pastLights,
+}: BoardTitleBarProps) {
+    const status = refreshed || counters;
+
+    return (
+        <div
+            data-native-window={nativeWindow || undefined}
+            className={`title-bar border-base-300 shrink-0 border-b select-none ${pastLights ? 'pl-[74px]' : ''} ${drag}`}
+        >
+            {nativeWindow ? null : <TrafficLights />}
+            {heading ? (
+                <h1 className="sr-only" tabIndex={-1}>
+                    {heading}
+                </h1>
+            ) : null}
+            <TitleBar
+                brand={brand}
+                title={
+                    status || search ? (
+                        <>
+                            {status ? (
+                                <div className="status-strip border-base-300 bg-base-200/60 flex shrink-0 items-center gap-0.5 rounded-lg border pr-0.5 pl-1.5">
+                                    {refreshed}
+                                    {refreshed && counters ? (
+                                        <span
+                                            aria-hidden="true"
+                                            className="bg-base-300 mx-0.5 h-4 w-px @max-[40rem]:hidden"
+                                        />
+                                    ) : null}
+                                    {counters}
+                                </div>
+                            ) : null}
+                            {search}
+                        </>
+                    ) : null
+                }
+                actions={actions}
+            />
+        </div>
+    );
+}
+
+/** In a browser, the traffic lights' grey stand-ins, 16 px in and centred in the 52 px bar, where macOS draws them. */
+function TrafficLights() {
+    return (
+        <div className="browser-window-controls pointer-events-none fixed top-0 left-0 z-50 flex h-13 items-center">
+            <span className="traffic-lights absolute left-4 flex gap-2" aria-hidden="true">
+                {['close', 'minimize', 'zoom'].map((light) => (
+                    <span key={light} className="size-3 rounded-full bg-(--traffic-stand-in)" />
+                ))}
+            </span>
+        </div>
+    );
+}
+
+/** The product's lockup in the title bar: the Lar mark, "ar" and the product's name. Screen readers skip it: the
+ *  page's heading names the page. */
+export function BoardBrand({ product }: { product: string }) {
+    return (
+        <span className="brand inline-flex shrink-0" aria-hidden="true">
+            <BrandMark label={`Lar ${product}`} product={product} />
+        </span>
+    );
+}
+
+/** A divider between groups of the title bar's actions. */
+export function TitleBarDivider() {
+    return <span aria-hidden="true" className="app-divider bg-base-300 mx-1 h-5 w-px shrink-0" />;
+}
+
+export type RefreshHealth = 'waiting' | 'live' | 'stale' | 'disconnected';
+
+const dots: Record<RefreshHealth, string> = {
+    waiting: 'bg-base-500',
+    live: 'bg-success',
+    stale: 'bg-amber-500',
+    disconnected: 'bg-danger',
+};
+
+interface RefreshIndicatorProps {
+    health: RefreshHealth;
+    /** What the time says, such as "12s" or "Stale · 2m"; hidden on a narrow bar, where the dot speaks alone. */
+    label: ReactNode;
+    /** A count of reads landed while this page was open: each new one pings the dot once, while live. */
+    landed: number;
+    /** The tooltip's two lines: when the board last read, then how it reads or what went wrong. */
+    detail: string;
+    secondaryDetail: string;
+}
+
+/**
+ * How fresh the board is, in the title bar's status strip: a dot in the health's colour (amber when stale, red while
+ * the page has lost the board server) and the time since the last read, with more in a tooltip. A tab stop, so
+ * keyboard users reach its tooltip.
+ */
+export function RefreshIndicator({ health, label, landed, detail, secondaryDetail }: RefreshIndicatorProps) {
+    return (
+        <Tooltip>
+            <TooltipTrigger asChild>
+                <span
+                    tabIndex={0}
+                    className="refreshed text-base-700 focus-visible:ring-primary inline-flex h-6 shrink-0 items-center gap-1.5 rounded-sm px-1 text-xs whitespace-nowrap tabular-nums outline-none focus-visible:ring-2 @max-[40rem]:hidden @min-[48rem]:min-w-30"
+                >
+                    <span className="relative grid size-2 place-items-center">
+                        {landed > 0 && health === 'live' && (
+                            <span
+                                key={landed}
+                                data-ping
+                                className="bg-success absolute size-1.5 rounded-full motion-safe:animate-[refreshed-ping_1.2s_ease-out_forwards]"
+                            />
+                        )}
+                        <span data-dot className={`size-1.5 rounded-full ${dots[health]}`} />
+                    </span>
+                    <span className="@max-[48rem]:sr-only">{label}</span>
+                </span>
+            </TooltipTrigger>
+            <TooltipPopup side="bottom">
+                <span className="flex flex-col gap-0.5">
+                    <span data-line>{detail}</span>
+                    <span data-line className="text-base-700">
+                        {secondaryDetail}
+                    </span>
+                </span>
+            </TooltipPopup>
+        </Tooltip>
+    );
+}