@lar-works/design-system 0.2.1 → 0.3.0

package/src/board/ButtonKinds.ts

@@ -0,0 +1,32 @@
+import type { ButtonProps } from '../actions/Button';
+
+/**
+ * Lar Factory's five kinds of button. A Main action, at most one per area, is filled; a Start is tinted, with the play
+ * icon; an Open is outlined, with the thread or pull request icon; an App control has no border and an icon; any Other
+ * button is outlined, with no icon. A dialog or a form is an area of its own, so its submit is its Main action. Every
+ * kind is the compact 28px Button and keeps its look while disabled.
+ */
+export type ButtonKind = 'main' | 'start' | 'open' | 'control' | 'other';
+
+const recipe = {
+    main: 'primary',
+    start: 'tinted',
+    open: 'secondary',
+    control: 'quiet',
+    other: 'secondary',
+} as const satisfies Record<ButtonKind, ButtonProps['variant']>;
+
+/** Props to spread on the design system's Button for a kind: its recipe, the compact size, and `data-kind`, which
+ *  names the kind for tests and the board's sheets. A destructive confirm, such as Reset or Abandon, is its
+ *  area's Main action filled in the danger colour. */
+export const buttonKind = <
+    K extends ButtonKind,
+    T extends (K extends 'main' ? 'danger' : never) | undefined = undefined,
+>(
+    kind: K,
+    tone?: T,
+) => ({
+    variant: (tone ? 'destructive' : recipe[kind]) as T extends 'danger' ? 'destructive' : (typeof recipe)[K],
+    compact: true,
+    'data-kind': kind,
+});

package/src/board/Cleanup.tsx

@@ -0,0 +1,19 @@
+// What removing work's old branches and worktrees would lose, in a confirmation.
+
+/** Each branch with the files and commits deleting it would lose, as a nested bulleted list. */
+export function LossList({ branches }: { branches: { name: string; losses: string[] }[] }) {
+    return (
+        <ul className="m-0 list-disc ps-5 wrap-anywhere">
+            {branches.map((branch) => (
+                <li key={branch.name}>
+                    <span>{branch.name}</span>
+                    <ul className="m-0 list-disc ps-5">
+                        {branch.losses.map((loss) => (
+                            <li key={loss}>{loss}</li>
+                        ))}
+                    </ul>
+                </li>
+            ))}
+        </ul>
+    );
+}

package/src/board/Counters.tsx

@@ -0,0 +1,224 @@
+import type { ReactNode } from 'react';
+
+import { Button } from '../actions/Button';
+import { Popover } from '../overlays/Popover';
+import { Tooltip, TooltipPopup, TooltipTrigger } from '../overlays/Tooltip';
+import { buttonKind } from './ButtonKinds';
+
+/** The title bar's counters, in its status strip after the Refreshed time. */
+export function BoardCounters({ children }: { children: ReactNode }) {
+    return <div className="counters flex shrink-0 items-center gap-0.5 whitespace-nowrap">{children}</div>;
+}
+
+/** How wide a counter's value stays from dash or loader to number: a count, a count over a limit, or a spend under
+ *  $1,000 with its plus. */
+const valueWidths = { count: 'min-w-[2ch]', limit: 'min-w-[4ch]', spend: 'min-w-[8ch]' };
+
+/** Which counters the title bar's width folds away: Shaping and Shipped below 54rem, then Spend below 66rem. */
+const folds = { never: '', medium: 'hidden @min-[54rem]:inline-flex', wide: 'hidden @min-[66rem]:inline-flex' };
+
+interface BoardCounterProps {
+    /** The status's glyph, in its own colour. */
+    icon: ReactNode;
+    value: ReactNode;
+    width?: keyof typeof valueWidths;
+    /** Names the counter for screen readers, with `hint`: "need you: 2 items waiting on your answer". */
+    label: string;
+    /** What the number means, in the tooltip. */
+    hint: string;
+    fold?: keyof typeof folds;
+    /** The panel's head: its title and, at its right, a figure such as the count. */
+    title: string;
+    sub?: ReactNode;
+    /** A note under the panel's list. */
+    foot?: ReactNode;
+    /** The panel's list, which scrolls. */
+    children: ReactNode;
+}
+
+/** One counter: an App control with a glyph and a tabular value, its tooltip, and the panel it opens, padded as a
+ *  menu, of everything behind the number. */
+export function BoardCounter({
+    icon,
+    value,
+    width = 'count',
+    label,
+    hint,
+    fold = 'never',
+    title,
+    sub,
+    foot,
+    children,
+}: BoardCounterProps) {
+    return (
+        <Popover>
+            <Tooltip>
+                <TooltipTrigger asChild>
+                    <Popover.Trigger asChild>
+                        <Button
+                            {...buttonKind('control')}
+                            aria-label={`${label}: ${hint}`}
+                            className={`text-base-700 hover:text-base-content data-[state=open]:bg-base-300/60 data-[state=open]:text-base-content min-w-0 gap-1.5 ${folds[fold]}`}
+                        >
+                            <span className="counter-icon grid size-4 shrink-0 place-items-center [&_svg]:size-4">
+                                {icon}
+                            </span>
+                            <span
+                                className={`counter-value text-base-content inline-flex items-center leading-4 font-medium tabular-nums [&_[data-loader]]:w-full [&_[data-loader]]:justify-center [&_svg]:size-3 ${valueWidths[width]}`}
+                            >
+                                {value}
+                            </span>
+                        </Button>
+                    </Popover.Trigger>
+                </TooltipTrigger>
+                <TooltipPopup side="bottom">{hint}</TooltipPopup>
+            </Tooltip>
+            <Popover.Content side="bottom" align="end" layout="fill" presentation="menu">
+                <div className="counter-popup flex max-h-112 min-h-0 w-96 max-w-full flex-col">
+                    <div className="counter-head text-base-700 flex h-7 shrink-0 items-center gap-2 px-2 text-xs font-medium">
+                        <span className="min-w-0 flex-1 truncate">{title}</span>
+                        {sub !== undefined && <span className="shrink-0 font-normal tabular-nums">{sub}</span>}
+                    </div>
+                    <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain">{children}</div>
+                    {foot !== undefined && (
+                        <div className="mt-1 shrink-0 border-t border-(--border) px-2 pt-1.5 pb-1 text-xs text-(--muted-foreground)">
+                            {foot}
+                        </div>
+                    )}
+                </div>
+            </Popover.Content>
+        </Popover>
+    );
+}
+
+/** The divider before the spend counter, which folds with it. */
+export function CounterDivider() {
+    return <span aria-hidden="true" className="mx-1 hidden h-4 w-px shrink-0 bg-(--border) @min-[66rem]:block" />;
+}
+
+/** A panel's list split by status, each part under its name and count. */
+export function CounterGroups({ children }: { children: ReactNode }) {
+    return <div className="grid gap-1">{children}</div>;
+}
+
+export function CounterGroup({ title, count, children }: { title: string; count: number; children: ReactNode }) {
+    return (
+        <section>
+            <h3 className="m-0 flex h-7 items-center gap-1 px-2 text-xs font-medium text-(--muted-foreground)">
+                {title} <span className="tabular-nums">{count}</span>
+            </h3>
+            {children}
+        </section>
+    );
+}
+
+/** What a panel says when its list is empty, or what is still loading. */
+export function CounterEmpty({ children }: { children: ReactNode }) {
+    return (
+        <p className="m-0 flex min-h-20 items-center justify-center px-2 py-4 text-center text-xs text-(--muted-foreground)">
+            {children}
+        </p>
+    );
+}
+
+export function CounterList({ children }: { children: ReactNode }) {
+    return <ul className="m-0 grid list-none grid-cols-[minmax(0,1fr)] gap-px p-0">{children}</ul>;
+}
+
+interface CounterItemProps {
+    /** The item's id, as `data-item`. */
+    item: string;
+    /** The row's accessible name, the item's name. */
+    label: string;
+    /** The item's status glyph and source icon. */
+    leading: ReactNode;
+    title: ReactNode;
+    /** At the right: CounterAge, or a figure such as its spend. */
+    trailing: ReactNode;
+    onOpen: () => void;
+}
+
+/** One item in a panel, as a menu's row; picking it closes the panel and opens the item. */
+export function CounterItem({ item, label, leading, title, trailing, onOpen }: CounterItemProps) {
+    return (
+        <li>
+            <Popover.Close asChild aria-label={label}>
+                <button
+                    type="button"
+                    onClick={onOpen}
+                    data-item={item}
+                    className="text-base-content hover:bg-base-200 focus-visible:bg-base-200 flex min-h-7 w-full cursor-default items-center gap-2 rounded-[0.375rem] px-2 py-1 text-left text-sm outline-none max-lg:min-h-11 pointer-coarse:min-h-11"
+                >
+                    {leading}
+                    <span className="min-w-0 flex-1 truncate">{title}</span>
+                    <span className="flex shrink-0 items-center gap-1.5 text-[11px] text-(--muted-foreground) tabular-nums">
+                        {trailing}
+                    </span>
+                </button>
+            </Popover.Close>
+        </li>
+    );
+}
+
+/** A row's repository icon and age. */
+export function CounterAge({ icon, age }: { icon: ReactNode; age: string }) {
+    return (
+        <>
+            {icon}
+            <span className="min-w-7 text-right whitespace-nowrap">{age}</span>
+        </>
+    );
+}
+
+/** A row's figure, such as its spend. */
+export function CounterFigure({ children }: { children: ReactNode }) {
+    return <span className="font-medium text-(--foreground)">{children}</span>;
+}
+
+/** A value not known yet, as nothing has been read. */
+export function CounterDash() {
+    return <span className="font-normal text-(--muted-foreground)">–</span>;
+}
+
+/** A count over a limit, such as builds at work over the build limit: "2/3". */
+export function CounterOfLimit({ count, limit }: { count: ReactNode; limit: number }) {
+    return (
+        <>
+            {count}
+            <span className="font-normal text-(--muted-foreground)">/{limit}</span>
+        </>
+    );
+}
+
+/** A figure that covers only part of what it sums, marked with a plus: amber while some of it is unavailable, muted
+ *  while some is still loading. */
+export function CounterPartial({ figure, unavailable }: { figure: string; unavailable: boolean }) {
+    return (
+        <>
+            {figure}
+            <span className={`font-normal ${unavailable ? 'text-(--you)' : 'text-(--muted-foreground)'}`}>+</span>
+        </>
+    );
+}
+
+/** The build limit as bars, then the count over it: one bar per build it allows, filled for each build at work, and
+ *  extra builds past it after a gap. */
+export function LimitBars({ used, limit }: { used: number; limit: number }) {
+    const bar = (n: number, on: boolean) => (
+        <span key={n} className={`h-1.5 w-3 rounded-full ${on ? 'bg-(--thread)' : 'bg-(--border)'}`} />
+    );
+
+    return (
+        <span className="inline-flex items-center gap-2">
+            <span className="inline-flex items-center gap-[3px]">
+                {Array.from({ length: limit }, (_, n) => bar(n, n < used))}
+                {used > limit && (
+                    <span className="ml-1 inline-flex gap-[3px]">
+                        {Array.from({ length: used - limit }, (_, n) => bar(limit + n, true))}
+                    </span>
+                )}
+            </span>
+            {used}/{limit}
+        </span>
+    );
+}

package/src/board/DataAttributes.ts

@@ -0,0 +1,3 @@
+/** The `data-*` attributes a board composition passes on to its root element, which name what it shows for the
+ *  board's tests and keyboard focus (such as `data-item` or `data-stage`). */
+export type DataAttributes = { [name: `data-${string}`]: string | number | boolean | undefined };

package/src/board/Dependencies.tsx

@@ -0,0 +1,49 @@
+// The Dependencies holding a build, in the item dialog.
+
+import type { ReactNode } from 'react';
+
+/** The Dependencies, one DependencyItem each. */
+export function DependencyList({ children }: { children: ReactNode }) {
+    return <ul className="m-0 grid list-none gap-3 p-0 text-sm">{children}</ul>;
+}
+
+/** A Dependency: who owns it and whether it's met, its need, its latest read and evidence, what the board asks about it,
+ *  and its `action`. */
+export function DependencyItem({
+    id,
+    owner,
+    need,
+    read,
+    evidence,
+    notice,
+    action,
+}: {
+    id: string;
+    owner: ReactNode;
+    need: ReactNode;
+    read: ReactNode;
+    evidence: ReactNode;
+    notice?: ReactNode;
+    action: ReactNode;
+}) {
+    return (
+        <li className="grid gap-1" data-dependency={id}>
+            <span className="font-medium" data-dependency-owner>
+                {owner}
+            </span>
+            <span>{need}</span>
+            <span className="text-xs text-(--muted-foreground)" data-dependency-read>
+                {read}
+            </span>
+            <span className="text-xs text-(--muted-foreground)" data-dependency-evidence>
+                {evidence}
+            </span>
+            {notice && (
+                <p className="m-0 text-xs font-medium text-(--warning-foreground)" data-dependency-notice>
+                    {notice}
+                </p>
+            )}
+            <span>{action}</span>
+        </li>
+    );
+}

package/src/board/Desk.tsx

@@ -0,0 +1,155 @@
+import type { ReactNode } from 'react';
+
+interface DeskSectionProps {
+    title: string;
+    /** How many cards show; with none, `empty` says why in one small line. */
+    count: number;
+    empty?: ReactNode;
+    children?: ReactNode;
+}
+
+/** "Your desk": the items awaiting your action as small cards in one row that scrolls sideways under the page's padding
+ *  to the window's edges. An empty desk is one small line. */
+export function DeskSection({ title, count, empty, children }: DeskSectionProps) {
+    if (!count)
+        return (
+            <section
+                className="desk flex shrink-0 items-baseline gap-2 text-xs text-(--muted-foreground)"
+                aria-labelledby="desk-h"
+            >
+                <h2 id="desk-h" className="m-0 text-[13px] font-medium text-(--foreground)">
+                    {title}
+                </h2>
+                <p className="m-0">{empty}</p>
+            </section>
+        );
+
+    return (
+        <section className="desk grid shrink-0 gap-2" aria-labelledby="desk-h">
+            <h2 id="desk-h" className="m-0 text-[13px] font-medium">
+                {title} <span className="text-(--muted-foreground)">{count}</span>
+            </h2>
+            <div className="-mx-6 flex [scrollbar-width:none] items-start gap-3 overflow-x-auto px-6 py-1 [&::-webkit-scrollbar]:hidden">
+                {children}
+            </div>
+        </section>
+    );
+}
+
+interface DeskCardProps {
+    /** The item's id, as `data-item`. */
+    item: string;
+    /** Whether the item dialog shows this item now. */
+    picked: boolean;
+    onOpen: () => void;
+    /** The first row: where the item comes from, its kind and its age. */
+    source: ReactNode;
+    kind: ReactNode;
+    age: ReactNode;
+    title: ReactNode;
+    /** The title's full text, for its tooltip. */
+    name: string;
+    /** More about the item under its title, such as a work item's fields. */
+    details?: ReactNode;
+    statusIcon: ReactNode;
+    status: string;
+    /** Beside the status: the next step, such as DeskMergeState or DeskHint. */
+    next?: ReactNode;
+    /** The card's actions, in its right corner, the board's button kinds drawn 32px tall there. A click beside them
+     *  opens the item, as anywhere else on the card. */
+    actions: ReactNode;
+}
+
+/**
+ * An item on your desk, opening the item dialog. Every card has the same four rows at the same heights, so they line
+ * up across cards: source, kind and age; the title; the status and next step; and the card's actions. Its summary is a
+ * button too, so the keyboard can open it.
+ */
+export function DeskCard({
+    item,
+    picked,
+    onOpen,
+    source,
+    kind,
+    age,
+    title,
+    name,
+    details,
+    statusIcon,
+    status,
+    next,
+    actions,
+}: DeskCardProps) {
+    return (
+        <div
+            onClick={onOpen}
+            data-item={item}
+            className={`desk-card relative grid w-88 shrink-0 cursor-pointer content-start gap-2 rounded-xl border border-[color-mix(in_srgb,var(--warning)_45%,var(--border))] bg-(--card) py-3 pr-3 pl-4 shadow-[inset_3px_0_0_var(--warning)] hover:bg-(--accent) ${picked ? 'ring-2 ring-(--primary) ring-offset-1 ring-offset-(--background)' : ''}`}
+        >
+            <button
+                type="button"
+                className="grid min-w-0 gap-2 rounded text-left focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-(--primary)"
+            >
+                <span className="desk-meta flex h-6 min-w-0 items-center gap-2 text-[11px]">
+                    {source}
+                    {kind}
+                    <span className="ml-auto shrink-0 text-(--muted-foreground)">{age}</span>
+                </span>
+                <span className="desk-title h-5 truncate text-[13px]/5 font-medium" title={name}>
+                    {title}
+                </span>
+                {details}
+            </button>
+            <span className="flex min-w-0 items-center gap-2">
+                <span className="flex shrink-0 items-center gap-1.5 text-[11px] [&_svg]:size-3">
+                    {statusIcon}
+                    <span className="font-semibold text-(--warning-foreground)">{status}</span>
+                </span>
+                <span className="desk-next flex h-5 min-w-0 flex-1 items-center gap-1.5 text-[11px] text-(--muted-foreground) tabular-nums">
+                    {next}
+                </span>
+            </span>
+            <div
+                className="desk-actions flex h-8 shrink-0 items-center justify-end gap-1.5 [&_[data-kind]:not([data-toggle])]:h-8 [&_[data-kind][data-icon-only]]:w-8!"
+                // The actions keep their clicks from the card; a click on the row's own empty space still opens it.
+                onClick={(event) => {
+                    if (event.target !== event.currentTarget) event.stopPropagation();
+                }}
+            >
+                {actions}
+            </div>
+        </div>
+    );
+}
+
+export type MergeState = 'can merge' | 'checking' | 'blocked' | 'conflicts';
+
+const mergeDots: Record<MergeState, string> = {
+    'can merge': 'bg-(--build)',
+    checking: 'bg-(--warning)',
+    blocked: 'bg-(--muted-foreground)',
+    conflicts: 'bg-(--error)',
+};
+
+/** A desk card's next step while its pull request is open: its merge state, then its checks. */
+export function DeskMergeState({ state, checks }: { state: MergeState; checks: string }) {
+    return (
+        <>
+            <span className={`size-2 shrink-0 rounded-full ${mergeDots[state]}`} />
+            <span className="shrink-0 font-medium text-(--foreground)">{state}</span>
+            <span className="truncate" title={`${state} · ${checks}`}>
+                {' '}
+                · {checks}
+            </span>
+        </>
+    );
+}
+
+/** A desk card's next step as a hint, such as what its status waits for. */
+export function DeskHint({ children }: { children?: string | undefined }) {
+    return (
+        <span className="truncate" title={children}>
+            {children}
+        </span>
+    );
+}