@lar-works/design-system 0.2.0 → 0.3.0

package/src/board/StatusGlyph.tsx

@@ -0,0 +1,70 @@
+// One glyph per status of Lar Factory's work, the way T3 marks a thread working, waiting or done, in the status's
+// colour (board/tokens.css's --st-* colours).
+
+import {
+    CheckIcon,
+    CircleArrowRightIcon,
+    CircleDashedIcon,
+    CircleDotIcon,
+    CircleIcon,
+    Clock3Icon,
+    EyeIcon,
+    GitMergeIcon,
+    ListIcon,
+} from 'lucide-react';
+
+import { SpinnerIcon } from '../feedback/Loading';
+import { ambientMotion } from '../foundations/AmbientMotion';
+import { type BoardStatus, statusColor } from './StatusColors';
+
+const sizes = { compact: 'size-3', default: 'size-3.5', title: 'size-4' } as const;
+
+/** The statuses whose glyph pulses while their work runs; In progress spins instead. */
+const pulses: BoardStatus[] = ['Shaping', 'Review', 'Verify', 'Ready to merge'];
+
+/**
+ * A status's glyph in its colour. `running` animates it while its work is known to run: In progress spins, and
+ * Shaping, Review, Verify and Ready to merge pulse. `presentation` sizes it: 12px beside small text, 14px by default,
+ * 16px beside a title.
+ */
+export function StatusGlyph({
+    status,
+    running = false,
+    presentation = 'default',
+}: {
+    status: BoardStatus;
+    running?: boolean;
+    presentation?: keyof typeof sizes;
+}) {
+    const pulse = running && pulses.includes(status);
+    const props = {
+        ref: pulse ? ambientMotion : undefined,
+        className: `shrink-0 ${sizes[presentation]}${pulse ? ' status-pulse' : ''}`,
+        style: { color: statusColor[status] },
+        strokeWidth: 2.25,
+    };
+
+    switch (status) {
+        case 'List':
+            return <ListIcon {...props} />;
+        case 'Needs you':
+        case 'Verify':
+            return <CircleDotIcon {...props} />;
+        case 'In progress':
+            return running ? <SpinnerIcon motion="status" {...props} /> : <CircleIcon {...props} />;
+        case 'Ready':
+            return <CircleArrowRightIcon {...props} />;
+        case 'Shaping':
+            return <CircleDashedIcon {...props} />;
+        case 'Review':
+            return <EyeIcon {...props} />;
+        case 'Ready to merge':
+            return <GitMergeIcon {...props} />;
+        case 'Done':
+            return <CheckIcon {...props} />;
+        case 'Queued':
+            return <Clock3Icon {...props} />;
+        default:
+            return <CircleIcon {...props} />;
+    }
+}

package/src/board/Threads.tsx

@@ -0,0 +1,38 @@
+// A piece of work's earlier T3 threads, in the item dialog.
+
+import type { ReactNode } from 'react';
+
+/** The earlier threads, one EarlierThread each, in small muted text. */
+export function EarlierThreadList({ children }: { children: ReactNode }) {
+    return (
+        <ul className="m-0 grid list-none gap-1 p-0 text-xs text-(--muted-foreground)" data-earlier-threads>
+            {children}
+        </ul>
+    );
+}
+
+/** An earlier thread: its `name`, linked when `href` opens it, then its `state`; `title` names it in full. */
+export function EarlierThread({
+    name,
+    title,
+    href,
+    state,
+}: {
+    name: string;
+    title: string;
+    href?: string | undefined;
+    state: ReactNode;
+}) {
+    return (
+        <li className="flex min-w-0 items-center gap-1.5" title={title}>
+            {href ? (
+                <a href={href} className="truncate underline">
+                    {name}
+                </a>
+            ) : (
+                <span className="truncate">{name}</span>
+            )}{' '}
+            <span className="shrink-0">· {state}</span>
+        </li>
+    );
+}

package/src/board/TrackerLabels.tsx

@@ -0,0 +1,75 @@
+// The tracker's labels on a Lar Factory project's settings page: the list of them, each row with its chip, detail and
+// actions and the editor it opens, and the line that creates one.
+
+import type { FormEvent, ReactNode } from 'react';
+
+import type { DataAttributes } from './DataAttributes';
+
+/** The tracker's labels, a row each, in a bordered list that never grows past its section. */
+export function TrackerLabelList({ children }: { children: ReactNode }) {
+    return (
+        <ul className="m-0 grid list-none grid-cols-[minmax(0,1fr)] overflow-hidden rounded-lg border p-0">
+            {children}
+        </ul>
+    );
+}
+
+/**
+ * A label's row: its `chip`, its `detail` (truncating, its tooltip giving it whole), then its `actions`, with the
+ * `editor` it has open under them.
+ */
+export function TrackerLabelRow({
+    chip,
+    detail,
+    actions,
+    editor,
+    ...data
+}: {
+    chip: ReactNode;
+    detail?: string | undefined;
+    actions?: ReactNode;
+    editor?: ReactNode;
+} & DataAttributes) {
+    return (
+        <li {...data} className="border-b last:border-b-0">
+            <div className="flex min-w-0 items-center gap-3 px-3 py-1.5">
+                <span className="max-w-[45%] min-w-0">{chip}</span>
+                <span className="text-base-700 min-w-0 flex-1 truncate text-xs" title={detail}>
+                    {detail}
+                </span>
+                {actions && <span className="flex shrink-0 gap-1">{actions}</span>}
+            </div>
+            {editor}
+        </li>
+    );
+}
+
+/** The editor a label's row opens, ruled off under it on a faint tint. */
+export function TrackerLabelEditor({
+    onSubmit,
+    children,
+}: {
+    onSubmit: (event: FormEvent<HTMLFormElement>) => void;
+    children: ReactNode;
+}) {
+    return (
+        <form className="bg-base-200/40 grid gap-3 border-t p-3" onSubmit={onSubmit}>
+            {children}
+        </form>
+    );
+}
+
+/** The line that creates a label: its name field and the button that submits it, wrapping when they don't fit. */
+export function CreateLabelForm({
+    onSubmit,
+    children,
+}: {
+    onSubmit: (event: FormEvent<HTMLFormElement>) => void;
+    children: ReactNode;
+}) {
+    return (
+        <form className="flex max-w-full min-w-0 flex-wrap gap-2" onSubmit={onSubmit}>
+            {children}
+        </form>
+    );
+}

package/src/board/UpdatePill.tsx

@@ -0,0 +1,222 @@
+// The title bar's update pill, from T3 Code's update pill (apps/web/src/components/sidebar/SidebarUpdatePill.tsx at
+// d53873b) and its status icon (DesktopUpdateStatusIcon.tsx at 9a391eb), drawn as the board's other App controls are,
+// tinted in every state, instead of as T3's pill. Copyright (c) 2026 T3 Tools Inc. MIT License.
+
+import { ArrowDownToLineIcon, RotateCcwIcon } from 'lucide-react';
+import { type PointerEvent, type ReactNode, useEffect, useRef, useState } from 'react';
+
+import { Button } from '../actions/Button';
+import { Popover } from '../overlays/Popover';
+import { Tooltip, TooltipPopup, TooltipTrigger } from '../overlays/Tooltip';
+import { buttonKind } from './ButtonKinds';
+
+const RADIUS = 7;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+const CLOSE_DELAY_MS = 150;
+
+/** The pill's icon: an arrow for an available update, a progress ring in the primary colour while it downloads, and a
+ *  restart arrow once it's downloaded. 16 px, as every title bar icon is. */
+export function UpdateStatusIcon({
+    status,
+    percent = 0,
+}: {
+    status: 'available' | 'downloading' | 'downloaded';
+    /** The download's whole percentage, 0 to 100. */
+    percent?: number;
+}) {
+    if (status === 'downloading')
+        return (
+            <svg aria-hidden="true" className="size-4 shrink-0 -rotate-90" viewBox="0 0 20 20">
+                <circle
+                    cx="10"
+                    cy="10"
+                    r={RADIUS}
+                    fill="none"
+                    stroke="currentColor"
+                    strokeOpacity="0.2"
+                    strokeWidth="2"
+                />
+                <circle
+                    cx="10"
+                    cy="10"
+                    r={RADIUS}
+                    fill="none"
+                    className="stroke-primary transition-[stroke-dashoffset] duration-300 ease-out motion-reduce:transition-none"
+                    strokeDasharray={CIRCUMFERENCE}
+                    strokeDashoffset={CIRCUMFERENCE * (1 - percent / 100)}
+                    strokeLinecap="round"
+                    strokeWidth="2"
+                />
+            </svg>
+        );
+
+    const Icon = status === 'downloaded' ? RotateCcwIcon : ArrowDownToLineIcon;
+
+    return <Icon className="size-4 shrink-0" aria-hidden="true" />;
+}
+
+/** The pill while the update downloads: nothing to click, a progress bar to screen readers, with more in its tooltip.
+ *  `text` is what it says before the percentage, `label` its accessible name. */
+export function UpdateDownloading({
+    percent,
+    text,
+    label,
+    tooltip,
+}: {
+    percent: number;
+    text: string;
+    label: string;
+    tooltip: string;
+}) {
+    return (
+        <Tooltip>
+            <TooltipTrigger asChild>
+                <span
+                    tabIndex={0}
+                    role="progressbar"
+                    aria-label={label}
+                    aria-valuemin={0}
+                    aria-valuemax={100}
+                    aria-valuenow={percent}
+                    data-kind="control"
+                    className="update-button text-primary focus-visible:ring-primary inline-flex h-7 items-center gap-1.5 rounded-md bg-[color-mix(in_srgb,var(--color-primary)_10%,var(--color-base-100))] px-[11px] text-xs font-medium outline-none hover:bg-[color-mix(in_srgb,var(--color-primary)_18%,var(--color-base-100))] focus-visible:ring-2"
+                >
+                    <UpdateStatusIcon status="downloading" percent={percent} />
+                    {text} <span className="w-7 tabular-nums">{percent}%</span>
+                </span>
+            </TooltipTrigger>
+            <TooltipPopup side="bottom">{tooltip}</TooltipPopup>
+        </Tooltip>
+    );
+}
+
+/** Open while the pointer is on the pill or its popover, and for 150 ms after it leaves both. */
+function useHoverOpen() {
+    const [open, setOpen] = useState(false);
+    const timer = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+    useEffect(() => () => clearTimeout(timer.current), []);
+
+    const show = () => {
+        clearTimeout(timer.current);
+        setOpen(true);
+    };
+    const close = () => {
+        clearTimeout(timer.current);
+        setOpen(false);
+    };
+    const hover = {
+        // A touch has no hover: a tap runs the step.
+        onPointerEnter: (event: PointerEvent) => event.pointerType !== 'touch' && show(),
+        onPointerLeave: (event: PointerEvent) => {
+            if (event.pointerType === 'touch') return;
+
+            clearTimeout(timer.current);
+            timer.current = setTimeout(() => setOpen(false), CLOSE_DELAY_MS);
+        },
+    };
+
+    return { open, show, close, hover };
+}
+
+interface UpdatePillProps {
+    /** Whether the update is downloaded and waits for a restart, or still to download. */
+    status: 'available' | 'downloaded';
+    /** What the pill says, such as "Update available" or "Installing…". */
+    label: string;
+    /** The popover's heading, such as "Lar Factory 1.4.0 is available". */
+    heading: string;
+    /** The update's changes, such as ReleaseNotes. */
+    notes?: ReactNode;
+    /** The popover's button, such as "Download". */
+    actionLabel: string;
+    disabled: boolean;
+    /** Runs the step: the pill and the popover's button both run it. */
+    onRun: () => void;
+}
+
+/**
+ * The pill with an update to download or install. Clicking it runs that step. Hovering it, or focusing it from the
+ * keyboard, opens the changelog below it, with the step's button; it closes 150 ms after the pointer leaves both, and
+ * on Escape. The focus stays on the pill.
+ */
+export function UpdatePill({ status, label, heading, notes, actionLabel, disabled, onRun }: UpdatePillProps) {
+    const { open, show, close, hover } = useHoverOpen();
+
+    return (
+        <Popover open={open} onOpenChange={(next) => !next && close()}>
+            <Popover.Trigger asChild>
+                <Button
+                    {...buttonKind('control')}
+                    variant="tinted"
+                    aria-disabled={disabled || undefined}
+                    className={`update-button gap-1.5 font-medium ${disabled ? 'cursor-not-allowed' : ''}`}
+                    // The pill runs the step; the changelog opens on hover and focus, not on the click.
+                    onClick={(event) => {
+                        event.preventDefault();
+
+                        if (!disabled) onRun();
+                    }}
+                    onFocus={(event) => event.currentTarget.matches(':focus-visible') && show()}
+                    {...hover}
+                >
+                    <UpdateStatusIcon status={status} />
+                    {label}
+                </Button>
+            </Popover.Trigger>
+            <Popover.Content
+                side="bottom"
+                align="end"
+                onOpenAutoFocus={(event) => event.preventDefault()}
+                onCloseAutoFocus={(event) => event.preventDefault()}
+                {...hover}
+            >
+                <div className="grid w-80 max-w-full gap-3 text-left">
+                    <p className="update-heading text-base-content m-0 text-sm font-medium">{heading}</p>
+                    {notes ? <div className="max-h-[min(28rem,calc(100vh-10rem))] overflow-y-auto">{notes}</div> : null}
+                    <span className="justify-self-start">
+                        <Button {...buttonKind('main')} className="update-next" disabled={disabled} onClick={onRun}>
+                            {actionLabel}
+                        </Button>
+                    </span>
+                </div>
+            </Popover.Content>
+        </Popover>
+    );
+}
+
+export interface ReleaseNote {
+    version: string;
+    /** The section's heading, such as "What's changed" or "Changes in 1.3.0". */
+    title: string;
+    items: readonly string[];
+    /** What the app left out, such as "3 more changes in this Release". */
+    more?: string;
+}
+
+/** Each Release's changes, newest first, and a note of older Releases left out. */
+export function ReleaseNotes({ releases, older }: { releases: readonly ReleaseNote[]; older?: string }) {
+    return (
+        <>
+            {releases.map((note) => (
+                <section
+                    className="not-first:border-base-300 not-first:mt-3 not-first:border-t not-first:pt-3"
+                    key={note.version}
+                >
+                    <h3 className="text-base-content m-0 text-xs leading-4 font-semibold">{note.title}</h3>
+                    <ul className="text-base-700 m-0 mt-2 space-y-1.5 pl-4 text-xs leading-5">
+                        {note.items.map((item, i) => (
+                            <li className="list-disc break-words" key={i}>
+                                {item}
+                            </li>
+                        ))}
+                    </ul>
+                    {note.more ? <p className="text-base-700 m-0 mt-2 text-xs leading-5">{note.more}</p> : null}
+                </section>
+            ))}
+            {older ? (
+                <p className="border-base-300 text-base-700 m-0 mt-3 border-t pt-3 text-xs leading-5">{older}</p>
+            ) : null}
+        </>
+    );
+}

package/src/board/Vocabulary.tsx

@@ -0,0 +1,155 @@
+// A project's kind vocabulary in Lar Factory's settings and onboarding: each kind's row, with its type and the chips of
+// its labels, and the chooser that picks them from the tracker's labels.
+
+import type { ReactNode } from 'react';
+
+import type { DataAttributes } from './DataAttributes';
+
+/**
+ * One kind's row: its `title`, its `type` control, then its labels' chips in a group `labelsLabel` names, which take a
+ * line of their own on a narrow page, ending with the `chooser` that edits them; what the row says about them (notes,
+ * problems, actions) follows under it.
+ */
+export function VocabularyRow({
+    title,
+    type,
+    labels,
+    labelsLabel,
+    chooser,
+    children,
+    ...data
+}: {
+    title: string;
+    type: ReactNode;
+    labels: ReactNode;
+    labelsLabel: string;
+    chooser: ReactNode;
+    children?: ReactNode;
+} & DataAttributes) {
+    return (
+        <div {...data} className="grid min-w-0 gap-2 px-3 py-3">
+            <div className="grid min-w-0 grid-cols-[minmax(0,1fr)_8.5rem] items-center gap-x-3 gap-y-2 sm:grid-cols-[5.5rem_8.5rem_minmax(0,1fr)]">
+                <span className="text-[13px] font-medium">{title}</span>
+                {type}
+                <div
+                    role="group"
+                    aria-label={labelsLabel}
+                    className="col-span-2 flex min-w-0 flex-wrap items-center gap-1 sm:col-span-1"
+                >
+                    {labels}
+                    <span className="ms-auto flex">{chooser}</span>
+                </div>
+            </div>
+            {children}
+        </div>
+    );
+}
+
+/** The chip that stands for the labels past the first few, which opens the chooser (`label` names it). */
+export function VocabularyMore({ label, onClick, children }: { label: string; onClick: () => void; children: string }) {
+    return (
+        <button
+            type="button"
+            className="cursor-pointer rounded-full bg-(--muted) px-2 text-xs"
+            aria-label={label}
+            onClick={onClick}
+        >
+            {children}
+        </button>
+    );
+}
+
+/** A suggested label, dashed, which a press maps. */
+export function VocabularySuggestion({
+    disabled = false,
+    onClick,
+    children,
+}: {
+    disabled?: boolean;
+    onClick: () => void;
+    children: ReactNode;
+}) {
+    return (
+        <button
+            type="button"
+            disabled={disabled}
+            className="cursor-pointer rounded-full border border-dashed border-(--border) px-2 py-0.5 text-xs"
+            onClick={onClick}
+        >
+            {children}
+        </button>
+    );
+}
+
+/** The chooser's panel inside its popover: the search field, the list, then its actions, one under the other. */
+export function LabelChooser({ children, ...data }: { children: ReactNode } & DataAttributes) {
+    return (
+        <div {...data} className="grid w-full min-w-0 gap-2">
+            {children}
+        </div>
+    );
+}
+
+/** The chooser's list of labels, which picks several (`label` names it); its wheel scrolls the list alone. */
+export function LabelChooserList({ id, label, children }: { id: string; label: string; children: ReactNode }) {
+    return (
+        <ul
+            id={id}
+            role="listbox"
+            aria-multiselectable
+            aria-label={label}
+            className="m-0 h-64 list-none overflow-y-auto overscroll-contain p-0"
+            onWheel={(event) => event.stopPropagation()}
+        >
+            {children}
+        </ul>
+    );
+}
+
+/** One label in the chooser's list, highlighted while `active`. A press picks it and keeps focus in the search field. */
+export function LabelChooserOption({
+    id,
+    selected,
+    disabled,
+    active,
+    onHover,
+    onPick,
+    children,
+}: {
+    id: string;
+    selected: boolean;
+    disabled: boolean;
+    active: boolean;
+    onHover: () => void;
+    onPick: () => void;
+    children: ReactNode;
+}) {
+    return (
+        <li
+            id={id}
+            role="option"
+            aria-selected={selected}
+            aria-disabled={disabled}
+            className={`cursor-pointer rounded px-2 py-1 text-[13px] wrap-anywhere ${active ? 'bg-(--muted)' : ''}`}
+            onMouseMove={onHover}
+            onMouseDown={(event) => event.preventDefault()}
+            onClick={onPick}
+        >
+            {children}
+        </li>
+    );
+}
+
+/** What the chooser's list says when no label matches, announced. */
+export function LabelChooserEmpty({ children }: { children: ReactNode }) {
+    return (
+        <li role="status" className="px-2 py-2 text-xs text-(--muted-foreground)">
+            {children}
+        </li>
+    );
+}
+
+/** The chooser's closing actions, at either end of a ruled line. */
+export function LabelChooserFooter({ children }: { children: ReactNode }) {
+    return <div className="flex justify-between gap-2 border-t border-(--border) pt-2">{children}</div>;
+}

package/src/board/Warnings.tsx

@@ -0,0 +1,83 @@
+import type { MouseEvent, ReactNode } from 'react';
+
+import { BrandMark } from '../display/BrandMark';
+import { DismissButton } from '../feedback/DismissButton';
+
+interface BoardWarningsProps {
+    /** A warning shown open above the rest, such as a lost board server, which every number on the page depends on. */
+    lead?: ReactNode;
+    /** The collapsed list's summary, such as "2 connections need attention"; without it, no list. */
+    summary?: ReactNode;
+    /** The warnings in the collapsed list. */
+    children?: ReactNode;
+    /** At the banner's right, such as Diagnostics. */
+    action: ReactNode;
+}
+
+/** The board's warnings, in a banner under the title bar: connection problems stay in a collapsed list, inline
+ *  details that never open a notification or a dialog. */
+export function BoardWarnings({ lead, summary, children, action }: BoardWarningsProps) {
+    return (
+        <aside data-board-notices className="shrink-0 border-b bg-(--warning-surface) px-6 py-2 text-(--foreground)">
+            <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0 flex-1">
+                    {lead}
+                    {summary ? (
+                        <details>
+                            <summary className="cursor-pointer text-xs font-medium">{summary}</summary>
+                            <div className="mt-2 max-h-48 overflow-auto">{children}</div>
+                        </details>
+                    ) : null}
+                </div>
+                {action}
+            </div>
+        </aside>
+    );
+}
+
+interface BoardWarningProps {
+    /** What the warning is about, as `data-warning`. */
+    name: string;
+    title: string;
+    dismissLabel: string;
+    onDismiss: (event: MouseEvent<HTMLButtonElement>) => void;
+    /** Under the text, such as a button that fixes it. */
+    action?: ReactNode;
+    children: ReactNode;
+}
+
+/** One warning in the banner: its title, what to do, and a close button. Commands in it wrap anywhere. */
+export function BoardWarning({ name, title, dismissLabel, onDismiss, action, children }: BoardWarningProps) {
+    return (
+        <div data-slot="notice" className="relative border-t py-3 pr-8 text-xs first:border-t-0 first:py-1">
+            <div data-warning={name} className="[&_code]:wrap-anywhere">
+                <DismissButton label={dismissLabel} onClick={onDismiss} />
+                <div data-slot="title" className="font-medium">
+                    {title}
+                </div>
+                <div data-slot="description" className="text-base-700 mt-1">
+                    {children}
+                </div>
+                {action && <div className="mt-2">{action}</div>}
+            </div>
+        </div>
+    );
+}
+
+/** What fills the board's main area while a tool it can't work without is missing: the Lar mark, what's missing, why
+ *  and how to fix it, and a way to look again. */
+export function ToolMissing({ title, children, action }: { title: string; children: ReactNode; action: ReactNode }) {
+    return (
+        <div className="tool-missing grid flex-1 place-items-center p-5">
+            <div
+                className="tool-missing-box max-w-130 rounded-(--radius) border bg-(--card) px-6 py-5 [&_code]:wrap-anywhere [&_code]:text-(--foreground)"
+                role="alert"
+            >
+                <BrandMark label="Lar" />
+                <h1 className="mt-3 mb-0 text-(length:--text-base) font-semibold tracking-[-0.01em]">{title}</h1>
+                <p className="mt-3 mb-0 text-(--muted-foreground)">{children}</p>
+                <p className="mt-3 mb-0 text-(--muted-foreground)">{action}</p>
+            </div>
+        </div>
+    );
+}