@lar-works/design-system 0.2.0 → 0.3.0

package/src/board/PartsList.tsx

@@ -0,0 +1,160 @@
+// An expanded dossier's parts list: each part with what it asks next, its stage track, figures, thread and slices, the
+// done parts folded away; and a part's kind as every surface of the dossier names it.
+
+import { BookOpenIcon, HammerIcon, ListChecksIcon, MessagesSquareIcon, ShapesIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { pickedRow, ROW_OPENS } from './RowStyles';
+
+const KIND_ICON = {
+    grill: MessagesSquareIcon,
+    prototype: ShapesIcon,
+    research: BookOpenIcon,
+    task: ListChecksIcon,
+    decision: MessagesSquareIcon,
+    build: HammerIcon,
+} as const;
+
+/** What a dossier's part is: a decision's method, or a build. */
+export type PartKind = keyof typeof KIND_ICON;
+
+/** A part's method or kind with its icon, in the one place and style every dossier surface shows it. */
+export function PartKindLabel({ kind, children }: { kind: PartKind; children: ReactNode }) {
+    const Icon = KIND_ICON[kind];
+
+    return (
+        <span
+            className="inline-flex shrink-0 items-center gap-1.5 text-[11px] text-(--muted-foreground)"
+            data-part-kind
+        >
+            <Icon className="size-3.5 shrink-0" />
+            {children}
+        </span>
+    );
+}
+
+/** The parts, in two columns where there's room, then `showDone`, the button that unfolds the done ones. */
+export function PartsList({ showDone, children }: { showDone?: ReactNode; children: ReactNode }) {
+    return (
+        <div className="grid gap-1">
+            <ol className="m-0 grid list-none gap-x-4 gap-y-1 p-0 @4xl:grid-cols-2" data-parts-list>
+                {children}
+            </ol>
+            {showDone}
+        </div>
+    );
+}
+
+/** The button under the parts that shows or hides the done ones. */
+export function ShowDoneToggle({
+    open,
+    onToggle,
+    children,
+}: {
+    open: boolean;
+    onToggle: () => void;
+    children: string;
+}) {
+    return (
+        <button
+            type="button"
+            aria-expanded={open}
+            onClick={onToggle}
+            className="justify-self-start rounded px-2 py-1 text-[11px] text-(--muted-foreground) hover:bg-(--accent)"
+        >
+            {children}
+        </button>
+    );
+}
+
+/**
+ * A part: one button opens its item from its `name` and `meta` (kind, repository, track, status), what it asks next
+ * (`action`) sits beside that button, then its `second` line (a RowSecondLine) and any `foot`, its start's message or
+ * error, under that.
+ */
+export function PartRow({
+    id,
+    picked,
+    title,
+    onOpen,
+    name,
+    meta,
+    action,
+    second,
+    foot,
+}: {
+    id: string;
+    picked: boolean;
+    title: string;
+    onOpen: () => void;
+    name: ReactNode;
+    meta: ReactNode;
+    action: ReactNode;
+    second?: ReactNode;
+    foot?: ReactNode;
+}) {
+    return (
+        <li data-part={id} className={`@container rounded-md px-3 py-2 hover:bg-(--accent) ${pickedRow(picked)}`}>
+            <div className="flex items-start gap-x-3">
+                <button
+                    type="button"
+                    data-row-open
+                    onClick={onOpen}
+                    title={title}
+                    className={`grid min-w-0 flex-1 gap-y-1 rounded text-left ${ROW_OPENS}`}
+                >
+                    {name}
+                    <span
+                        className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 pl-5 text-xs text-(--muted-foreground)"
+                        data-part-meta
+                    >
+                        {meta}
+                    </span>
+                </button>
+                <span
+                    data-part-action
+                    className="flex min-h-7 shrink-0 items-center justify-end gap-2 text-xs text-(--muted-foreground)"
+                >
+                    {action}
+                </span>
+            </div>
+            {second}
+            {foot && <span className="block pt-1 pl-5 empty:hidden">{foot}</span>}
+        </li>
+    );
+}
+
+/** A part's stage track in its meta line, at a fixed width so the tracks line up. */
+export function PartTrack({ children }: { children: ReactNode }) {
+    return <span className="w-28 shrink-0">{children}</span>;
+}
+
+/** What a part waits on, beside its action, truncating. */
+export function PartWaits({ children }: { children: string }) {
+    return (
+        <span className="max-w-48 truncate" title={children}>
+            {children}
+        </span>
+    );
+}
+
+/** A part's thread in its second line: its glyph, `name` and `state`; `title` names it in full. */
+export function ThreadLine({
+    glyph,
+    name,
+    state,
+    title,
+}: {
+    glyph: ReactNode;
+    name: string;
+    state: string;
+    title?: string | undefined;
+}) {
+    return (
+        <span className="flex min-w-0 items-center gap-1.5" title={title}>
+            {glyph}
+            <span className="truncate">{name}</span>
+            <span className="shrink-0">· {state}</span>
+        </span>
+    );
+}

package/src/board/ProjectIcon.tsx

@@ -0,0 +1,172 @@
+// A project's icon, in a fixed square. An emoji or monogram chosen in T3 takes the square. Otherwise it holds the
+// toned initial, with the favicon or lucide icon laid over it once that has loaded, so the square keeps its size either
+// way and a missing or broken one leaves the initial. Decorative, as a name sits beside it. An SVG favicon only ever
+// renders through this <img>, which runs none of its scripts.
+
+import { lazy, Suspense, useState, type ComponentProps, type ComponentType } from 'react';
+
+import type { DynamicIcon } from '../icons/dynamic';
+import type { DataAttributes } from './DataAttributes';
+
+/** T3's project icon colours, which tint a lucide icon or a monogram. */
+export type ProjectIconColor =
+    | 'gray'
+    | 'red'
+    | 'orange'
+    | 'amber'
+    | 'yellow'
+    | 'lime'
+    | 'green'
+    | 'emerald'
+    | 'teal'
+    | 'cyan'
+    | 'sky'
+    | 'blue'
+    | 'indigo'
+    | 'violet'
+    | 'purple'
+    | 'fuchsia'
+    | 'pink'
+    | 'rose';
+
+/** What a project's square shows over its initial: a lucide icon by name, an emoji, up to two characters of a
+ *  monogram, or a favicon at `src`. */
+export type ProjectIconSource =
+    | { kind: 'lucide'; name: string; color: ProjectIconColor }
+    | { kind: 'emoji'; emoji: string }
+    | { kind: 'monogram'; text: string; color: ProjectIconColor }
+    | { kind: 'favicon'; src: string };
+
+/** The board's palette of repository colours, which the repositories take in their list order. */
+const REPO_TONES = 8;
+
+const SIZES = {
+    small: { square: 'size-3.5 text-[8px]', emoji: 'text-[10px]', monogram: 'text-[7px]' },
+    row: { square: 'size-4 text-[9px]', emoji: 'text-xs', monogram: 'text-[8px]' },
+    medium: { square: 'size-5 text-[10px]', emoji: 'text-sm', monogram: 'text-[10px]' },
+};
+
+export type ProjectIconSize = keyof typeof SIZES;
+
+/** Whole class names, as Tailwind only finds those. */
+const COLORS: Record<ProjectIconColor, string> = {
+    gray: 'text-gray-500',
+    red: 'text-red-500',
+    orange: 'text-orange-500',
+    amber: 'text-amber-500',
+    yellow: 'text-yellow-500',
+    lime: 'text-lime-500',
+    green: 'text-green-500',
+    emerald: 'text-emerald-500',
+    teal: 'text-teal-500',
+    cyan: 'text-cyan-500',
+    sky: 'text-sky-500',
+    blue: 'text-blue-500',
+    indigo: 'text-indigo-500',
+    violet: 'text-violet-500',
+    purple: 'text-purple-500',
+    fuchsia: 'text-fuchsia-500',
+    pink: 'text-pink-500',
+    rose: 'text-rose-500',
+};
+
+const OVERLAY = 'absolute inset-0 size-full bg-base-100';
+
+/** lucide's name map and its icons are lazy chunks, loaded when first shown. DynamicIcon draws nothing for a name
+ *  lucide lacks or an icon that won't load, and a name map that won't load draws nothing here. */
+const LucideIcon = lazy<ComponentType<ComponentProps<typeof DynamicIcon>>>(() =>
+    import('../icons/dynamic').then(
+        (lucide) => ({ default: lucide.DynamicIcon }),
+        () => ({ default: () => null }),
+    ),
+);
+
+function Favicon({ src }: { src: string }) {
+    const [loaded, setLoaded] = useState(false);
+    const [failed, setFailed] = useState(false);
+
+    if (failed) return null;
+
+    return (
+        <img
+            src={src}
+            alt=""
+            hidden={!loaded}
+            onLoad={() => setLoaded(true)}
+            onError={() => setFailed(true)}
+            className={`${OVERLAY} object-contain`}
+        />
+    );
+}
+
+const graphemes = new Intl.Segmenter();
+const firstGraphemes = (text: string, count: number) => {
+    let shown = '';
+    let length = 0;
+
+    for (const { segment } of graphemes.segment(text)) {
+        shown += segment;
+
+        if (++length === count) break;
+    }
+
+    return shown;
+};
+
+/**
+ * A project's icon in a square of its `size`: `icon`, or its `name`'s initial on the colour of its `place` among the
+ * board's repositories (muted for a project the board doesn't list), with a favicon or lucide icon laid over the
+ * initial once it has loaded.
+ */
+export function ProjectIcon({
+    icon,
+    name,
+    place,
+    size,
+    ...data
+}: {
+    icon?: ProjectIconSource | null | undefined;
+    name: string;
+    place?: number | undefined;
+    size: ProjectIconSize;
+} & DataAttributes) {
+    const { square, emoji, monogram } = SIZES[size];
+    const shared = `${square} relative grid shrink-0 place-items-center overflow-hidden rounded-md font-bold`;
+
+    if (icon?.kind === 'emoji')
+        return (
+            <span {...data} data-project-icon className={shared} aria-hidden="true">
+                <span className={emoji}>{icon.emoji}</span>
+            </span>
+        );
+
+    if (icon?.kind === 'monogram')
+        return (
+            <span {...data} data-project-icon className={`${shared} ${COLORS[icon.color]}`} aria-hidden="true">
+                <span className={`${monogram} leading-none whitespace-nowrap`}>{firstGraphemes(icon.text, 2)}</span>
+            </span>
+        );
+
+    const tone = place === undefined ? 'repo-tone-none' : `repo-tone-${place % REPO_TONES}`;
+
+    return (
+        <span
+            {...data}
+            data-project-icon
+            className={`${tone} ${shared} bg-[var(--k,var(--color-base-600))] text-white`}
+            aria-hidden="true"
+        >
+            {firstGraphemes(name, 1).toUpperCase()}
+            {icon?.kind === 'favicon' && <Favicon key={icon.src} src={icon.src} />}
+            {icon?.kind === 'lucide' && (
+                <Suspense fallback={null}>
+                    <LucideIcon
+                        key={icon.name}
+                        name={icon.name as ComponentProps<typeof DynamicIcon>['name']}
+                        className={`${OVERLAY} ${COLORS[icon.color]}`}
+                    />
+                </Suspense>
+            )}
+        </span>
+    );
+}

package/src/board/PullRequests.tsx

@@ -0,0 +1,106 @@
+// A piece of work's pull requests: a list with each one's checks and readiness, and the short reference rows show.
+
+import { GitPullRequestIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+/** The pull requests in a list, one PullRequestRow each. */
+export function PullRequestList({ children }: { children: ReactNode }) {
+    return <ul className="m-0 grid list-none grid-cols-[minmax(0,1fr)] gap-1 p-0">{children}</ul>;
+}
+
+/** A pull request: its icon and label linking to it in a new tab, then its `checks` and `readiness`. */
+export function PullRequestRow({
+    href,
+    label,
+    checks,
+    readiness,
+}: {
+    href: string;
+    label: string;
+    checks?: ReactNode;
+    readiness?: ReactNode;
+}) {
+    return (
+        <li className="flex flex-wrap items-center gap-x-2 gap-y-1 rounded-lg border border-(--border) bg-(--card) px-3 py-2">
+            <GitPullRequestIcon className="size-4 shrink-0 text-(--st-done)" />
+            <a
+                href={href}
+                target="_blank"
+                rel="noopener"
+                className="min-w-0 flex-1 basis-24 font-medium wrap-anywhere hover:underline"
+            >
+                {label}
+            </a>
+            {checks}
+            {readiness}
+        </li>
+    );
+}
+
+const CHECKS_COLOR = { failed: 'var(--error)', running: 'var(--warning)', passed: 'var(--st-done)' } as const;
+
+/** A pull request's checks as a coloured dot and their state, then any `counts`. */
+export function ChecksState({ state, counts }: { state: keyof typeof CHECKS_COLOR; counts?: string }) {
+    return (
+        <span className="inline-flex shrink-0 items-center gap-1.5 text-xs text-(--muted-foreground)">
+            <span className="size-2 rounded-full" style={{ background: CHECKS_COLOR[state] }} />
+            checks {state}
+            {counts && <span className="tabular-nums">· {counts}</span>}
+        </span>
+    );
+}
+
+/** A pull request as a row names it: its icon and short label, `title` naming it in full. */
+export function PullRequestRef({ label, title }: { label: string; title?: string }) {
+    return (
+        <span title={title} className="inline-flex shrink-0 items-center gap-1">
+            <GitPullRequestIcon className="size-3 shrink-0 text-(--st-done)" />
+            {label}
+        </span>
+    );
+}
+
+/** A pull request's readiness under its row: the `toggle` that shows it, then the `details` while shown. */
+export function PullRequestReadiness({ toggle, details }: { toggle: ReactNode; details?: ReactNode }) {
+    return (
+        <div className="basis-full text-xs text-(--muted-foreground)">
+            {toggle}
+            {details}
+        </div>
+    );
+}
+
+/** What a readiness read says: its `status`, when it was `observed` and what blocks it, a `note`, and `refresh`. */
+export function ReadinessDetails({
+    id,
+    status,
+    observed,
+    blockers = [],
+    note,
+    refresh,
+}: {
+    id: string;
+    status: ReactNode;
+    observed?: ReactNode;
+    blockers?: string[];
+    note: ReactNode;
+    refresh: ReactNode;
+}) {
+    return (
+        <div id={id} role="status" aria-live="polite">
+            <p>{status}</p>
+            {observed && (
+                <>
+                    <p>{observed}</p>
+                    <ul>
+                        {blockers.map((b) => (
+                            <li key={b}>{b}</li>
+                        ))}
+                    </ul>
+                </>
+            )}
+            <p>{note}</p>
+            {refresh}
+        </div>
+    );
+}

package/src/board/RowStyles.ts

@@ -0,0 +1,17 @@
+// What the board's rows share: the rule under a row, the focus ring of a row's own buttons, the action slot, and how
+// the row the item dialog shows is marked; and the warning panel its notes share.
+
+/** The rule under a row, which takes no height, so every row of a type measures the same. */
+export const ROW_RULE = 'shadow-[inset_0_-1px_var(--border)] last:shadow-none';
+/** A row's own buttons draw their focus ring inside the pane that clips them. */
+export const ROW_OPENS = 'focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-(--primary)';
+/** What a row's action slot holds, centred and against its right edge. */
+export const ROW_ACTION =
+    'flex min-w-0 flex-wrap items-center justify-end gap-x-2 gap-y-1 text-right text-xs text-(--muted-foreground)';
+
+/** A row the item dialog shows now: tinted and ringed. */
+export const pickedRow = (picked: boolean) => (picked ? 'bg-(--accent) ring-2 ring-inset ring-(--primary)' : '');
+
+/** The panel a warning about a piece of work sits in, such as why it needs you or is paused. */
+export const WARNING_PANEL =
+    'rounded-xl border border-[color-mix(in_srgb,var(--warning)_35%,transparent)] bg-(--warning-surface) px-3 py-2.5';

package/src/board/Settings.tsx

@@ -0,0 +1,124 @@
+// Lar Factory's settings: the title bar's button that opens them, the sections' sidebar, the column of a page's groups,
+// the short reason a setting can't be changed, and the parts its rows show under and beside their controls.
+
+import { SettingsIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { Button } from '../actions/Button';
+import { SidebarPane } from '../layout/sidebar/SidebarPane';
+import { HelpTip } from '../overlays/HelpTip';
+import { buttonKind } from './ButtonKinds';
+import type { DataAttributes } from './DataAttributes';
+
+/** The title bar's last button, which opens Settings: an icon-only App control named by its `label`, its 20px icon in
+ *  the text colour rather than the muted one, so it holds its own beside the labelled controls. */
+export function OpenSettingsButton({ label, onOpen }: { label: string; onOpen: () => void }) {
+    return (
+        <Button
+            {...buttonKind('control')}
+            iconOnly
+            className="open-settings text-base-content [&_svg]:size-5"
+            aria-label={label}
+            title={label}
+            onClick={onOpen}
+        >
+            <SettingsIcon />
+        </Button>
+    );
+}
+
+/**
+ * Settings' sidebar: the `search` field over the sections' groups (SidebarNavigationGroup), and `empty`, announced,
+ * when a search leaves none. `label` names the navigation.
+ */
+export function SettingsNav({
+    label,
+    search,
+    empty,
+    children,
+    ...data
+}: {
+    label: string;
+    search: ReactNode;
+    empty?: string | undefined;
+    children: ReactNode;
+} & DataAttributes) {
+    return (
+        <div {...data} className="contents">
+            <SidebarPane label={label}>
+                <div className="w-44 shrink-0 md:mb-3 md:w-auto">{search}</div>
+                {empty && (
+                    <p role="status" data-no-match className="text-base-700 m-0 px-2 py-1 text-xs">
+                        {empty}
+                    </p>
+                )}
+                {children}
+            </SidebarPane>
+        </div>
+    );
+}
+
+/**
+ * Why a setting can't be changed, in a short muted line that wraps: the `reason`, a help popover with the whole
+ * `explanation` (`helpLabel` names its button), then the `action` that checks again, such as an InlineLink with `onClick`.
+ */
+export function ReasonNote({
+    reason,
+    explanation,
+    helpLabel,
+    action,
+}: {
+    reason: string;
+    explanation: ReactNode;
+    helpLabel: string;
+    action?: ReactNode;
+}) {
+    return (
+        <span className="inline-flex min-w-0 flex-wrap items-center gap-1 text-xs text-(--muted-foreground)">
+            <span>{reason}</span>
+            <HelpTip label={helpLabel}>{explanation}</HelpTip>
+            {action}
+        </span>
+    );
+}
+
+/** A settings group's note under its panel, such as what the group's last call did: small lines, stacked. `busy` marks
+ *  it as still loading for assistive technology. */
+export function SettingsNote({ busy, children, ...data }: { busy?: boolean; children: ReactNode } & DataAttributes) {
+    return (
+        <div {...data} className="grid gap-2 px-1" aria-busy={busy}>
+            {children}
+        </div>
+    );
+}
+
+/** What a setting row shows under its control, such as an install's progress, in small stacked lines; `breaks` lets a
+ *  long path break anywhere. */
+export function SettingDetails({ breaks = false, children }: { breaks?: boolean; children: ReactNode }) {
+    return <div className={`grid gap-2 text-xs${breaks ? ' [overflow-wrap:anywhere]' : ''}`}>{children}</div>;
+}
+
+/** A setting's control with its error under it, at most 20rem wide. */
+export function SettingControl({ children }: { children: ReactNode }) {
+    return <div className="grid max-w-80 gap-2">{children}</div>;
+}
+
+/** A small list of each Project's value for a setting, the Project left and its value muted right, wrapping. */
+export function ProjectValueList({
+    label,
+    rows,
+}: {
+    label: string;
+    rows: readonly { key: string; name: string; value: string }[];
+}) {
+    return (
+        <ul className="m-0 grid list-none gap-1 p-0 text-xs" aria-label={label}>
+            {rows.map(({ key, name, value }) => (
+                <li key={key} className="flex flex-wrap justify-between gap-x-3">
+                    <span className="[overflow-wrap:anywhere]">{name}</span>{' '}
+                    <span className="[overflow-wrap:anywhere] text-(--muted-foreground)">{value}</span>
+                </li>
+            ))}
+        </ul>
+    );
+}

package/src/board/Slices.tsx

@@ -0,0 +1,103 @@
+// A piece of work's slices: the bar every view of the board draws, and a list with each slice's mark.
+
+import { CheckIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { ambientMotion } from '../foundations/AmbientMotion';
+
+/** Where a slice stands. */
+export type SliceProgress = 'done' | 'active' | 'blocked' | 'unknown' | 'waiting';
+
+const SLICE_COLOR: Record<SliceProgress, string> = {
+    done: 'var(--st-done)',
+    active: 'var(--st-now)',
+    blocked: 'var(--st-review)',
+    unknown: 'var(--muted-foreground)',
+    waiting: 'var(--input)',
+};
+
+/** A 6px segment for each slice, named by its tooltip; waiting segments are faint, and an active one pulses unless
+ *  `still`. */
+export function SliceBar({
+    slices,
+    still = false,
+}: {
+    slices: { name: string; progress: SliceProgress }[];
+    still?: boolean;
+}) {
+    if (!slices.length) return null;
+
+    return (
+        <ol className="m-0 flex list-none gap-[2px] p-0">
+            {slices.map((s, i) => (
+                <li
+                    key={i}
+                    ref={s.progress === 'active' && !still ? ambientMotion : undefined}
+                    title={s.name}
+                    className={`h-1.5 flex-1 rounded-full ${s.progress === 'active' && !still ? 'status-pulse' : ''}`}
+                    style={{ background: s.progress === 'waiting' ? 'var(--soft)' : SLICE_COLOR[s.progress] }}
+                />
+            ))}
+        </ol>
+    );
+}
+
+/** A slice's state as a ring: ticked when done, a question mark when unknown, a dot pulsing unless `still` while
+ *  active. */
+export function SliceMark({ progress, still = false }: { progress: SliceProgress; still?: boolean }) {
+    return (
+        <span
+            className="grid size-4 shrink-0 place-items-center rounded-full border-[1.5px]"
+            style={{
+                borderColor: SLICE_COLOR[progress],
+                background: progress === 'done' ? 'var(--st-done)' : 'transparent',
+            }}
+        >
+            {progress === 'unknown' && <span className="text-[9px] leading-none">?</span>}
+            {progress === 'done' && <CheckIcon className="size-2.5 text-white" strokeWidth={3} />}
+            {progress === 'active' && (
+                <span
+                    ref={still ? undefined : ambientMotion}
+                    className={`${still ? '' : 'status-pulse '}size-1.5 rounded-full bg-(--st-now)`}
+                />
+            )}
+        </span>
+    );
+}
+
+/** The slices of a piece of work, one SliceRow each. */
+export function SliceList({ children }: { children: ReactNode }) {
+    return <ul className="m-0 grid list-none grid-cols-[minmax(0,1fr)] gap-0.5 p-0">{children}</ul>;
+}
+
+/** A slice in SliceList: where its ticket is saved, its mark, number, title (struck through when done) and state. */
+export function SliceRow({
+    source,
+    progress,
+    still = false,
+    number,
+    title,
+}: {
+    source: ReactNode;
+    progress: SliceProgress;
+    still?: boolean;
+    /** The slice's ticket number; a slice with none shows none. */
+    number?: number | undefined;
+    title: string;
+}) {
+    return (
+        <li className="flex items-start gap-2 rounded-md px-2 py-1 text-[13px] hover:bg-(--soft)">
+            {source}
+            <span className="mt-0.5">
+                <SliceMark progress={progress} still={still} />
+            </span>
+            {!!number && <span className="shrink-0 text-(--muted-foreground) tabular-nums">#{number}</span>}
+            <span
+                className={`min-w-0 flex-1 wrap-anywhere ${progress === 'done' ? 'text-(--muted-foreground) line-through' : progress === 'active' ? 'font-medium' : ''}`}
+            >
+                {title}
+            </span>
+            <span className="mt-px shrink-0 text-[11px] text-(--muted-foreground)">{progress}</span>
+        </li>
+    );
+}