@lar-works/design-system 0.2.0 → 0.3.0

package/src/board/SourceIcon.tsx

@@ -0,0 +1,33 @@
+import { LaptopIcon } from 'lucide-react';
+
+import { AzureDevOpsIcon, GitHubIcon } from '../icons/BrandIcons';
+
+/** Where a piece of work's ticket is saved: a GitHub issue, an Azure DevOps work item, or only on this machine. */
+export type ItemSource = 'github' | 'azure' | 'local';
+
+/**
+ * Where an item's ticket is saved, as a small muted mark named by `label`: a bordered square in rows and details, or
+ * with `corner` a tab in a card's top right corner, which lets clicks through to the card.
+ */
+export function SourceIcon({ source, label, corner = false }: { source: ItemSource; label: string; corner?: boolean }) {
+    const shape = corner
+        ? 'absolute right-0 top-0 z-10 size-6 rounded-bl-lg rounded-tr-[inherit] border-b border-l pointer-events-none'
+        : 'size-5 shrink-0 rounded-md border';
+
+    return (
+        <span
+            role="img"
+            aria-label={label}
+            title={label}
+            className={`grid place-items-center border-(--border) bg-(--soft) text-(--muted-foreground) ${shape}`}
+        >
+            {source === 'local' ? (
+                <LaptopIcon className="size-3" strokeWidth={1.75} aria-hidden="true" />
+            ) : source === 'github' ? (
+                <GitHubIcon className="size-3" />
+            ) : (
+                <AzureDevOpsIcon className="size-3" />
+            )}
+        </span>
+    );
+}

package/src/board/StagePane.tsx

@@ -0,0 +1,128 @@
+// A section of Lar Factory's board's work by stage (Queue, Shaping, Ready to build, Build, Concepts and linked work): a
+// titled list that takes the height of its rows, so a section with none stays small and the page scrolls past them all.
+
+import type { ReactNode } from 'react';
+
+/** A stage's section: its status glyph, title and count, anything at the header's `right`, then its rows. */
+export function StagePane({
+    id,
+    title,
+    glyph,
+    count,
+    right,
+    children,
+}: {
+    /** Names the section, as `data-stage`, and its heading's id. */
+    id: string;
+    title: string;
+    glyph?: ReactNode;
+    count: number;
+    right?: ReactNode;
+    children: ReactNode;
+}) {
+    return (
+        <section
+            data-stage={id}
+            aria-labelledby={`${id}-h`}
+            className="min-w-0 overflow-hidden rounded-xl border border-(--border) bg-(--card) shadow-xs"
+        >
+            <header className="flex min-h-10 flex-wrap items-center gap-x-2 gap-y-1 border-b border-(--border) px-3 py-1">
+                {glyph}
+                <h3 id={`${id}-h`} className="m-0 text-[13px] font-medium whitespace-nowrap">
+                    {title} <span className="font-normal text-(--muted-foreground) tabular-nums">{count}</span>
+                </h3>
+                {right && <span className="ml-auto flex max-w-full min-w-0 items-center">{right}</span>}
+            </header>
+            <div className="@container">{children}</div>
+        </section>
+    );
+}
+
+/** The rows of a stage's section. */
+export function StageList({ children }: { children: ReactNode }) {
+    return <ol className="m-0 grid list-none p-0">{children}</ol>;
+}
+
+/** What a section says with no row: that it's loading, that nothing is in it, or that the filters hide every row. */
+export function StagePaneEmpty({ children }: { children: ReactNode }) {
+    return (
+        <p data-pane-empty className="m-0 px-3 py-3 text-[12px] text-(--muted-foreground)">
+            {children}
+        </p>
+    );
+}
+
+/** Builds at work against the build limit, in a section's header: one bar per build the `limit` allows, more when
+ *  they're over it, the bars at work in `color`, then the count in words. */
+export function BuildLimit({
+    building,
+    limit,
+    color,
+    title,
+    children,
+}: {
+    building: number;
+    limit?: number | undefined;
+    color: string;
+    title: string;
+    children: ReactNode;
+}) {
+    return (
+        <span
+            className="build-limit inline-flex items-center gap-1.5 text-[11px] whitespace-nowrap text-(--muted-foreground) tabular-nums"
+            title={title}
+        >
+            {limit !== undefined && (
+                <span className="inline-flex gap-[3px]">
+                    {Array.from({ length: Math.max(limit, building) }, (_, n) => (
+                        <span
+                            key={n}
+                            className="bar h-1.5 w-3 rounded-full"
+                            style={{ background: n < building ? color : 'var(--border)' }}
+                        />
+                    ))}
+                </span>
+            )}
+            {children}
+        </span>
+    );
+}
+
+/** A switch in a section's header with its visible `label` before it, and before that any `hold` that keeps it from
+ *  acting, truncating; `title` says what it would do. */
+export function HeaderSwitch({
+    label,
+    title,
+    hold,
+    control,
+}: {
+    label: string;
+    title: string;
+    hold?: string | undefined;
+    /** The Switch, named by `label` for assistive technology. */
+    control: ReactNode;
+}) {
+    return (
+        <span
+            className="auto-build inline-flex min-w-0 items-center gap-1.5 text-[11px] whitespace-nowrap text-(--muted-foreground)"
+            title={title}
+        >
+            {hold && (
+                <span className="min-w-0 truncate" title={hold} data-auto-build-hold>
+                    {hold}
+                </span>
+            )}
+            <span aria-hidden="true">{label}</span>
+            {control}
+        </span>
+    );
+}
+
+/** The stages' sections, one under another, named by `label`. */
+export function StageSections({ label, children }: { label: string; children: ReactNode }) {
+    return (
+        <section className="stages flex flex-col gap-3" aria-label={label}>
+            {children}
+        </section>
+    );
+}

package/src/board/StageRow.tsx

@@ -0,0 +1,320 @@
+// The board's one work row (board/rows.css), in Queue, Shaping, Ready to build, Build and Concepts and linked work: a
+// first line in columns that line up down the whole board, one button that opens the item's details with the row's
+// action beside it, and under it a second line on the same columns.
+
+import { ChevronDownIcon, ChevronRightIcon } from 'lucide-react';
+import type { MouseEvent, ReactNode } from 'react';
+
+import { Badge } from '../display/Badge';
+import { Loading } from '../feedback/Loading';
+import { pickedRow, ROW_ACTION, ROW_OPENS, ROW_RULE } from './RowStyles';
+
+/** A stage row: `item` names it as `data-item`, and `picked` marks the item the dialog shows. */
+export function StageRowItem({ item, picked, children }: { item: string; picked: boolean; children: ReactNode }) {
+    return (
+        <li data-item={item} className={`@container py-2 ${ROW_RULE} hover:bg-(--accent) ${pickedRow(picked)}`}>
+            {children}
+        </li>
+    );
+}
+
+/** A row's first line: its cells, then its side. */
+export function RowFirst({ children }: { children: ReactNode }) {
+    return <div className="row-first">{children}</div>;
+}
+
+/** A row's first line's cells as the one button that opens its item. */
+export function RowOpen({ onOpen, children }: { onOpen: () => void; children: ReactNode }) {
+    return (
+        <button type="button" data-row-open data-meta onClick={onOpen} className={`row-cols ${ROW_OPENS}`}>
+            {children}
+        </button>
+    );
+}
+
+/** A row's first line's cells, when its title opens the item and the rest of the line does something else. */
+export function RowCells({ children }: { children: ReactNode }) {
+    return <div className="row-cols">{children}</div>;
+}
+
+/** The first cell: the item's status glyph. */
+export function RowGlyph({ children }: { children: ReactNode }) {
+    return (
+        <span className="grid size-6 place-items-center" data-glyph>
+            {children}
+        </span>
+    );
+}
+
+/** The first cell of a Queue row: its place in the Queue. */
+export function QueuePlace({ children }: { children: ReactNode }) {
+    return <span className="queue-n text-center font-medium tabular-nums">{children}</span>;
+}
+
+/** Where the item's ticket is saved and its repository, in the source cell. */
+export function RowIdentity({ children }: { children: ReactNode }) {
+    return (
+        <span data-row-identity className="flex min-w-0 items-center gap-1.5 text-[11px] text-(--muted-foreground)">
+            {children}
+        </span>
+    );
+}
+
+/** The kind cell. */
+export function RowKindCell({ children }: { children: ReactNode }) {
+    return (
+        <span className="flex min-w-0 items-center" data-kind>
+            {children}
+        </span>
+    );
+}
+
+/** The title cell: the RowTitle and what it is part of. */
+export function RowTitleCell({ children }: { children: ReactNode }) {
+    return (
+        <span className="flex min-w-0 items-center gap-2" data-title-cell>
+            {children}
+        </span>
+    );
+}
+
+/** The row's title, truncating; `name` gives it whole. */
+export function RowTitle({ name, children }: { name: string; children: ReactNode }) {
+    return (
+        <span className="min-w-0 truncate text-sm leading-7 font-medium text-(--foreground)" title={name} data-title>
+            {children}
+        </span>
+    );
+}
+
+/** After the title: which concept or parent the row's work belongs to, giving its room up first. */
+export function RowPartOf({ children }: { children: string }) {
+    return (
+        <span
+            data-concept
+            title={children}
+            className="max-w-44 min-w-16 shrink-[100] truncate rounded bg-(--muted) px-1.5 text-(--muted-foreground)"
+        >
+            {children}
+        </span>
+    );
+}
+
+/** The state cell, which `clips` what overflows it unless what it holds keeps its own width. */
+export function RowStateCell({ clips = true, children }: { clips?: boolean; children: ReactNode }) {
+    return (
+        <span className={`flex min-w-0 items-center gap-1.5${clips ? ' overflow-hidden' : ''}`} data-col="state">
+            {children}
+        </span>
+    );
+}
+
+/** The row's state in words; `title` says more. */
+export function RowState({ title, children }: { title?: string; children: ReactNode }) {
+    return (
+        <span className="max-w-full shrink-0 truncate" title={title} data-state>
+            {children}
+        </span>
+    );
+}
+
+/** A Queue row's state: how long it has waited. */
+export function QueueAge({ children }: { children: ReactNode }) {
+    return (
+        <span className="queue-age shrink-0 tabular-nums" data-state>
+            {children}
+        </span>
+    );
+}
+
+/** The row's action slot, at its right. With `passEmpty`, clicks on its controls stay there, and a click beside them
+ *  reaches the row. */
+export function RowSide({ passEmpty = false, children }: { passEmpty?: boolean; children: ReactNode }) {
+    if (!passEmpty)
+        return (
+            <span data-col="side" className={`row-side ${ROW_ACTION}`}>
+                {children}
+            </span>
+        );
+
+    return (
+        <span data-col="side" className="row-side">
+            <span
+                className={ROW_ACTION}
+                onClick={(event) => {
+                    if (event.target !== event.currentTarget) event.stopPropagation();
+                }}
+            >
+                {children}
+            </span>
+        </span>
+    );
+}
+
+/** Where to act on an item that waits on you, in its action slot. */
+export function OnYourDesk({ children }: { children: ReactNode }) {
+    return <span className="text-(--warning-foreground)">{children}</span>;
+}
+
+/** A row's second line: `bar` and `count` on the left, `children` in its text slot, then its pull requests and
+ *  figures. A click on it beside its controls goes to `onClick`. */
+export function RowSecondLine({
+    bar,
+    count,
+    prs,
+    figures,
+    onClick,
+    children,
+}: {
+    bar?: ReactNode;
+    /** A RowCount or RowSliceToggle; with none, its cell stays empty. */
+    count?: ReactNode;
+    /** The pull requests, as PullRequestRefs. */
+    prs?: ReactNode;
+    figures?: ReactNode;
+    onClick?: ((event: MouseEvent<HTMLElement>) => void) | undefined;
+    children?: ReactNode;
+}) {
+    return (
+        <div data-progress onClick={onClick} className={`row-second ${onClick ? 'cursor-pointer' : ''}`}>
+            <span data-col="bar" className="min-w-0">
+                {bar}
+            </span>
+            {count || <span data-col="count" />}
+            <span data-col="next" className="flex min-w-0 items-center gap-3">
+                {children}
+            </span>
+            <span data-col="pr" className="flex min-w-0 gap-2 overflow-hidden tabular-nums">
+                {prs}
+            </span>
+            <span data-col="figures">{figures}</span>
+        </div>
+    );
+}
+
+/** The second line's count, such as `2/5 parts`. */
+export function RowCount({ title, children }: { title?: string; children: ReactNode }) {
+    return (
+        <span data-col="count" className="tabular-nums" title={title}>
+            {children}
+        </span>
+    );
+}
+
+/** The second line's slice count as a button that unfolds the row's slices under it. */
+export function RowSliceToggle({
+    open,
+    label,
+    onToggle,
+    children,
+}: {
+    open: boolean;
+    /** Names the button, as what it does now. */
+    label: string;
+    onToggle: () => void;
+    children: ReactNode;
+}) {
+    return (
+        <button
+            type="button"
+            aria-expanded={open}
+            aria-label={label}
+            onClick={onToggle}
+            data-col="count"
+            className={`flex h-4 items-center gap-1 justify-self-start rounded tabular-nums hover:text-(--foreground) ${ROW_OPENS}`}
+        >
+            {children}
+            {open ? <ChevronDownIcon className="size-3" /> : <ChevronRightIcon className="size-3" />}
+        </button>
+    );
+}
+
+/** Why the row is blocked, as a danger badge in its second line that truncates. */
+export function RowBlocked({ children }: { children: string }) {
+    return (
+        <Badge tone="danger" className="min-w-0" title={children} data-blocked>
+            <span className="truncate">{children}</span>
+        </Badge>
+    );
+}
+
+const SLICE_TONE = { blocked: 'text-(--st-review)', active: 'text-(--st-now)' } as const;
+
+/** The second line's word on the row's slices: its first blocked or active slice, `more` after it, and anything `after`
+ *  that (such as that every slice is implemented); `title` lists them all. */
+export function RowSliceNote({
+    title,
+    first,
+    more,
+    after,
+}: {
+    title?: string | undefined;
+    first?: { word: string; tone: keyof typeof SLICE_TONE; title: string } | undefined;
+    more?: string | undefined;
+    after?: string | undefined;
+}) {
+    return (
+        <span data-note className="min-w-0 truncate" title={title}>
+            {first && (
+                <>
+                    <span className={`font-medium ${SLICE_TONE[first.tone]}`}>{first.word}</span>{' '}
+                    <span className="text-(--foreground)">{first.title}</span>
+                    {more}
+                </>
+            )}
+            {after && <span>{after}</span>}
+        </span>
+    );
+}
+
+/** Under a row: Start's message or error and what Auto-build says of it, taking no room when empty. */
+export function RowFoot({ children }: { children: ReactNode }) {
+    return <div className="pt-1 pr-3 pl-12 empty:hidden">{children}</div>;
+}
+
+/** Under a row: its unfolded slices. */
+export function RowSlices({ children }: { children: ReactNode }) {
+    return (
+        <div className="pt-1 pr-3 pl-10" data-slices>
+            {children}
+        </div>
+    );
+}
+
+/** The agent figures on one line, at the row's right: `text`, ending in a + when `partial`, or `incomplete` when there
+ *  are no figures to show; while `updating`, a spinner named by it leads them. A row that stops animating keeps its
+ *  spinner `still`. */
+export function UsageFigures({
+    title,
+    text,
+    updating,
+    still = false,
+    partial,
+    incomplete,
+}: {
+    title: string;
+    text?: string | null | undefined;
+    updating?: string | undefined;
+    still?: boolean;
+    /** Screen-reader words for the +. */
+    partial?: string | undefined;
+    /** The words in place of figures for an incomplete total with none to show. */
+    incomplete?: string | undefined;
+}) {
+    return (
+        <span
+            className="flex min-w-0 items-center justify-end gap-1 text-(--muted-foreground) tabular-nums"
+            title={title}
+        >
+            {updating && <Loading presentation="inline" title={updating} still={still} />}
+            {text && <span className="truncate">{text}</span>}
+            {text
+                ? partial && (
+                      <span className="-ml-1 shrink-0" data-partial>
+                          +<span className="sr-only"> {partial}</span>
+                      </span>
+                  )
+                : incomplete && <span className="shrink-0">{incomplete}</span>}
+        </span>
+    );
+}

package/src/board/StageTrack.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode } from 'react';
+
+const PAST = 'color-mix(in srgb, var(--foreground) 28%, transparent)';
+
+/**
+ * A piece of work's place on the board's active stages: one segment per stage, the past ones filled, and the current
+ * one half-filled in `color` under `glyph` (its status glyph), faint and ringed dashed while it `waiting`s. Complete
+ * work shows `glyph` alone, a tick, in place of the track.
+ */
+export function StageTrack({
+    stages,
+    at,
+    color,
+    glyph,
+    title,
+    waiting = false,
+    complete = false,
+}: {
+    /** The stages' names, in order. */
+    stages: readonly string[];
+    /** The current stage's index. */
+    at: number;
+    color: string;
+    glyph: ReactNode;
+    title: string;
+    waiting?: boolean;
+    complete?: boolean;
+}) {
+    if (complete)
+        return (
+            <span className="flex h-5 items-center" title={title}>
+                {glyph}
+            </span>
+        );
+
+    return (
+        <ol className="m-0 grid list-none grid-cols-5 gap-px p-0" title={title}>
+            {stages.map((name, n) => (
+                <li key={name} className="relative flex h-5 items-center justify-center">
+                    <span
+                        className={`absolute inset-x-0 h-1.5 ${n === 0 ? 'rounded-l-full' : ''} ${n === stages.length - 1 ? 'rounded-r-full' : ''}`}
+                        style={{ background: n < at ? PAST : 'var(--soft)' }}
+                    />
+                    {n === at && (
+                        <>
+                            <span
+                                className={`absolute right-1/2 left-0 h-1.5 ${n === 0 ? 'rounded-l-full' : ''}`}
+                                style={{ background: color, opacity: waiting ? 0.35 : 1 }}
+                            />
+                            <span
+                                className={`relative grid size-5 place-items-center rounded-full bg-(--card) ${waiting ? 'border border-dashed border-(--muted-foreground)' : ''}`}
+                            >
+                                {glyph}
+                            </span>
+                        </>
+                    )}
+                </li>
+            ))}
+        </ol>
+    );
+}

package/src/board/StartControls.tsx

@@ -0,0 +1,77 @@
+// What sits around a piece of work's Start (board/items.css): the group that holds it, the tag that takes its place once
+// a thread started, and the line under it with Start's message or error.
+
+import type { ReactNode, Ref } from 'react';
+
+import { Badge } from '../display/Badge';
+import type { DataAttributes } from './DataAttributes';
+
+/** Start and what goes with it, at the right of its row, wrapping. */
+export function StartGroup({ children }: { children: ReactNode }) {
+    return <span className="start-group">{children}</span>;
+}
+
+/** A sentence on a line of its own in StartGroup, such as "Run finished.". */
+export function StartNote({ children }: { children: ReactNode }) {
+    return <span className="basis-full">{children}</span>;
+}
+
+/** The tag that takes Start's place: Started, or May have started while it's `unsure`. It takes focus back from a closed
+ *  message, so it is focusable from script. */
+export function StartTag({
+    unsure = false,
+    title,
+    children,
+    ...data
+}: {
+    unsure?: boolean;
+    title: string;
+    children: ReactNode;
+} & DataAttributes) {
+    return (
+        <Badge
+            {...data}
+            tone={unsure ? 'warning' : 'success'}
+            className={unsure ? 'started-tag unsure' : 'started-tag'}
+            tabIndex={-1}
+            title={title}
+        >
+            {children}
+        </Badge>
+    );
+}
+
+/** The small line under Start: its message or error, or what Auto-build says of the item. */
+export function StartLine({
+    ref,
+    tabIndex,
+    children,
+    ...data
+}: {
+    ref?: Ref<HTMLParagraphElement>;
+    tabIndex?: number;
+    children: ReactNode;
+} & DataAttributes) {
+    return (
+        <p {...data} ref={ref} tabIndex={tabIndex} className="start">
+            {children}
+        </p>
+    );
+}
+
+/** An action's error in the danger text colour, on its own line after the controls beside it. */
+export function ActionError({
+    ref,
+    role,
+    children,
+}: {
+    ref?: Ref<HTMLSpanElement>;
+    role?: 'alert';
+    children: ReactNode;
+}) {
+    return (
+        <span ref={ref} role={role} className="action-error">
+            {children}
+        </span>
+    );
+}

package/src/board/StatusColors.ts

@@ -0,0 +1,28 @@
+// The board's statuses and the colour each is drawn in (board/tokens.css's --st-* colours).
+
+/** A piece of work's status on the board. */
+export type BoardStatus =
+    | 'List'
+    | 'Queued'
+    | 'Shaping'
+    | 'Needs you'
+    | 'Ready'
+    | 'In progress'
+    | 'Review'
+    | 'Verify'
+    | 'Ready to merge'
+    | 'Done';
+
+/** Each status's colour, as a CSS colour value. */
+export const statusColor: Record<BoardStatus, string> = {
+    List: 'var(--st-idle)',
+    Queued: 'var(--st-idle)',
+    Shaping: 'var(--st-now)',
+    'Needs you': 'var(--st-amber)',
+    Ready: 'var(--st-now)',
+    'In progress': 'var(--st-now)',
+    Review: 'var(--st-review)',
+    Verify: 'var(--st-amber)',
+    'Ready to merge': 'var(--st-done)',
+    Done: 'var(--st-done)',
+};