@lar-works/design-system 0.2.0 → 0.3.0

package/src/board/tokens.css

@@ -0,0 +1,52 @@
+/* The board's role tokens. The board's own roles (--you, --thread, --sub, --build…) name what a colour means on the
+   board: you, a T3 thread, a sub-issue, a build. The others are the role names the board's pages read, each pointed
+   at a design-system token; they are plain variables, not Tailwind colours, so ninna-ui's own primary, secondary and
+   accent hues stay as the theme sets them. The components in ./ use the theme's tokens directly where they can. */
+:root {
+    --radius: var(--radius-lg);
+    --background: var(--color-base-50);
+    --foreground: var(--color-base-content);
+    --card: var(--color-base-100);
+    --primary: var(--color-primary);
+    --secondary: var(--color-zinc-50);
+    --secondary-foreground: var(--foreground);
+    --muted: var(--color-zinc-50);
+    --muted-foreground: var(--color-base-700);
+    --accent: var(--color-base-200);
+    --error: var(--color-danger);
+    --error-foreground: var(--lar-danger-text);
+    --error-surface: color-mix(in srgb, var(--error) 8%, transparent);
+    --destructive-foreground: var(--error-foreground);
+    --border: var(--color-border);
+    --input: var(--color-base-400);
+    --ring: var(--primary);
+    --success: var(--color-success);
+    --success-foreground: var(--lar-success-text);
+    --warning: var(--color-warning);
+    --warning-foreground: var(--lar-warning-text);
+    --warning-surface: color-mix(in srgb, var(--warning) 8%, transparent);
+
+    /* The board's own roles. */
+    --you: var(--warning);
+    --thread: var(--primary);
+    --sub: var(--color-violet-500);
+    --build: var(--success);
+    --danger-text: var(--error-foreground);
+    --soft: color-mix(in srgb, var(--foreground) 7%, transparent);
+
+    /* Each status's colour, which StatusGlyph, the stage track, the slice and part bars draw in. */
+    --st-amber: var(--you);
+    --st-now: var(--thread);
+    --st-review: var(--sub);
+    --st-done: var(--build);
+    --st-idle: color-mix(in srgb, var(--muted-foreground) 70%, transparent);
+
+    @variant dark {
+        --secondary: --alpha(var(--color-white) / 3%);
+        --muted: --alpha(var(--color-white) / 3%);
+        --error-surface: color-mix(in srgb, var(--error) 16%, transparent);
+        --warning-surface: color-mix(in srgb, var(--warning) 16%, transparent);
+
+        --sub: var(--color-violet-400);
+    }
+}

package/src/board.css

@@ -0,0 +1,19 @@
+/* styles.css plus Lar Factory's board (its role tokens, base styles, title bar, loading screen, button kinds, item parts
+   and rows): the import for the board app. It scans every source, so the generic components the board composes are
+   there too. */
+@import './foundations/theme.css';
+@import './board/tokens.css';
+@import './board/base.css';
+@import './board/title-bar.css';
+@import './board/loading-screen.css';
+@import './board/button-kinds.css';
+@import './board/items.css';
+@import './board/rows.css';
+
+@source './';
+
+/* ninna-ui's own @source paths assume npm's flat node_modules and find nothing under pnpm, so its components'
+   classes are scanned from here: next to this package once installed (pnpm's store or npm's tree), and in this
+   package's own node_modules inside the lar-web workspace. */
+@source '../../../@ninna-ui/*/dist/**/*.js';
+@source '../node_modules/@ninna-ui/*/dist/**/*.js';

package/src/collections/CollectionState.tsx

@@ -13,9 +13,14 @@ const variants = {
     compact: { layout: 'max-w-64 px-3 py-6', icon: '[&>svg]:size-6', space: 'related' },
     /** A quiet empty state with the same surface as dashboard content. */
     panel: { layout: 'max-w-md px-4 py-5', icon: '[&>svg]:size-6', space: 'related' },
+    /** A first run's welcome in an app's empty main area: its `icon` (such as the brand mark) in its own colours over a
+     *  section-sized title. */
+    welcome: { layout: 'max-w-xl px-6 py-16', icon: '', space: 'group' },
 } as const;
 
 interface CollectionStateProps {
+    /** The action in place of `actionLabel` and `onAction`, for a caller whose button has its own look or markers. */
+    action?: ReactNode;
     actionLabel?: string;
     description: string;
     icon?: ReactNode;
@@ -25,6 +30,7 @@ interface CollectionStateProps {
 }
 
 export function CollectionState({
+    action,
     actionLabel,
     description,
     icon,
@@ -39,12 +45,18 @@ export function CollectionState({
             space={variants[variant].space}
             className={`mx-auto text-center ${variants[variant].layout}`}
         >
-            {icon ? <span className={`text-base-500 ${variants[variant].icon}`}>{icon}</span> : null}
+            {icon ? (
+                variant === 'welcome' ? (
+                    icon
+                ) : (
+                    <span className={`text-base-500 ${variants[variant].icon}`}>{icon}</span>
+                )
+            ) : null}
             <Stack space="tight">
                 {compact ? (
                     <Text variant="label">{title}</Text>
                 ) : (
-                    <Heading as="h2" variant="subsection">
+                    <Heading as="h2" variant={variant === 'welcome' ? 'section' : 'subsection'}>
                         {title}
                     </Heading>
                 )}
@@ -52,11 +64,12 @@ export function CollectionState({
                     {description}
                 </Text>
             </Stack>
-            {actionLabel && onAction ? (
-                <Button type="button" onClick={onAction} variant="secondary">
-                    {actionLabel}
-                </Button>
-            ) : null}
+            {action ??
+                (actionLabel && onAction ? (
+                    <Button type="button" onClick={onAction} variant="secondary">
+                        {actionLabel}
+                    </Button>
+                ) : null)}
         </Stack>
     );
 

package/src/display/Avatar.tsx

@@ -1,7 +1,10 @@
 import { Avatar as NinnaAvatar, type AvatarProps as NinnaAvatarProps } from '@ninna-ui/primitives';
 
-type AvatarProps = Omit<NinnaAvatarProps, 'color' | 'size' | 'radius'>;
+type AvatarProps = Omit<NinnaAvatarProps, 'color' | 'size' | 'radius'> & {
+    /** The 24px avatar beside a name in a dense list, such as a comment's author. */
+    compact?: boolean;
+};
 
-export function Avatar(props: AvatarProps) {
-    return <NinnaAvatar {...props} color="neutral" size="sm" />;
+export function Avatar({ compact = false, ...props }: AvatarProps) {
+    return <NinnaAvatar {...props} color="neutral" size={compact ? 'xs' : 'sm'} />;
 }

package/src/display/Badge.tsx

@@ -2,11 +2,17 @@ import { Badge as NinnaBadge, type BadgeProps as NinnaBadgeProps } from '@ninna-
 import type { CSSProperties } from 'react';
 
 import type { StatusTone } from '../feedback/StatusIndicator';
+import { tint } from './LabelTint';
 
 export type BadgeProps = Omit<NinnaBadgeProps, 'color' | 'size' | 'variant'> & {
     tone?: StatusTone | 'accent';
     /** A lar-brand app hue that colours the badge in place of its tone. */
     hue?: number;
+    /** A tracker label's own colour, such as GitHub's, as a soft tint readable in both modes; anything but a colour
+     *  keeps the tone. */
+    labelColor?: string | undefined;
+    /** Dims the text to the muted colour, for an entry that is listed but switched off. */
+    muted?: boolean;
 };
 
 /** T3 Code's badge: a 6px-radius label on an 8% tint of its tone, in the tone's foreground colour. */
@@ -19,15 +25,31 @@ const toneClasses: Record<NonNullable<BadgeProps['tone']>, string> = {
     info: 'bg-info/10 text-(--lar-info-text) dark:bg-info/16',
 };
 
-export function Badge({ tone = 'neutral', hue, className = '', style, ...props }: BadgeProps) {
+export function Badge({
+    tone = 'neutral',
+    hue,
+    labelColor,
+    muted = false,
+    className = '',
+    style,
+    ...props
+}: BadgeProps) {
+    const labelTint = tint(labelColor);
+
     return (
         <NinnaBadge
             {...props}
             color={tone === 'accent' ? 'primary' : tone}
             size="sm"
             variant="soft"
-            style={hue === undefined ? style : ({ ...style, '--lar-kind-hue': hue } as CSSProperties)}
-            className={`h-5 gap-1 rounded-sm px-1.5 text-xs font-medium [&>svg]:size-3 [&>svg]:shrink-0 ${hue === undefined ? toneClasses[tone] : 'kind-badge!'} ${className}`}
+            style={
+                hue !== undefined
+                    ? ({ ...style, '--lar-kind-hue': hue } as CSSProperties)
+                    : labelTint
+                      ? { ...style, ...labelTint }
+                      : style
+            }
+            className={`h-5 gap-1 rounded-sm px-1.5 text-xs font-medium [&>svg]:size-3 [&>svg]:shrink-0 ${hue === undefined ? toneClasses[tone] : 'kind-badge!'} ${muted ? 'text-(--muted-foreground)' : ''} ${className}`}
         />
     );
 }

package/src/display/Comment.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+
+import { Avatar } from './Avatar';
+
+/** The comments, newest first, one Comment each, such as a ticket's. */
+export function CommentList({ children }: { children: ReactNode }) {
+    return <ol className="m-0 grid list-none grid-cols-[minmax(0,1fr)] gap-3 p-0">{children}</ol>;
+}
+
+/** A comment: its author's avatar beside a card with their name and `time` over the comment. */
+export function Comment({ author, time, children }: { author: string; time: ReactNode; children: ReactNode }) {
+    return (
+        <li className="flex gap-3">
+            <Avatar name={author} compact />
+            <div className="border-border bg-base-100 min-w-0 flex-1 rounded-lg border">
+                <div className="border-border flex items-center gap-2 border-b px-3 py-1.5 text-xs">
+                    <span className="font-medium" data-comment-author>
+                        {author}
+                    </span>
+                    <span className="text-base-700">{time}</span>
+                </div>
+                <div className="px-3 py-2">{children}</div>
+            </div>
+        </li>
+    );
+}

package/src/display/CopyButton.tsx

@@ -1,6 +1,7 @@
 import { CheckIcon, CopyIcon } from 'lucide-react';
 import { useEffect, useState } from 'react';
 
+import { Button } from '../actions/Button';
 import { IconButton } from '../actions/IconButton';
 
 const COPIED_FEEDBACK_MS = 1500;
@@ -9,10 +10,25 @@ interface CopyButtonProps {
     copiedLabel: string;
     label: string;
     value: string;
+    /** `icon` is a copy icon that turns into a tick; `text` is a compact button that reads `copyText`, then
+     *  `copiedLabel`, as a dense tool's Copy beside a command. */
+    presentation?: 'icon' | 'text';
+    /** The text presentation's word before a copy, such as "Copy"; `label` stays its accessible name. */
+    copyText?: string;
+    /** Called after each copy, such as to announce it in a live region. */
+    onCopied?: () => void;
 }
 
-/** The LAN admin also runs over HTTP, where the async clipboard API is unavailable. */
-export function CopyButton({ copiedLabel, label, value }: CopyButtonProps) {
+/** Copies `value`. The LAN admin also runs over HTTP, where the async clipboard API is unavailable, so it falls back
+ *  to a selected textarea. */
+export function CopyButton({
+    copiedLabel,
+    label,
+    value,
+    presentation = 'icon',
+    copyText = label,
+    onCopied,
+}: CopyButtonProps) {
     const [copiedValue, setCopiedValue] = useState<string | null>(null);
     const [copying, setCopying] = useState(false);
     const copied = copiedValue === value;
@@ -25,28 +41,42 @@ export function CopyButton({ copiedLabel, label, value }: CopyButtonProps) {
         return () => window.clearTimeout(timer);
     }, [copiedValue]);
 
+    const copy = async () => {
+        setCopying(true);
+
+        let done = false;
+
+        try {
+            if (navigator.clipboard) {
+                await navigator.clipboard.writeText(value);
+                done = true;
+            } else {
+                done = copySelection(value);
+            }
+        } catch {
+            done = copySelection(value);
+        } finally {
+            setCopiedValue(done ? value : null);
+            setCopying(false);
+        }
+
+        if (done) onCopied?.();
+    };
+
+    if (presentation === 'text')
+        return (
+            <Button variant="secondary" compact aria-label={label} onClick={() => void copy()}>
+                {copied ? copiedLabel : copyText}
+            </Button>
+        );
+
     return (
         <IconButton
             icon={copied ? <CheckIcon /> : <CopyIcon />}
             aria-label={copied ? copiedLabel : label}
             title={copied ? copiedLabel : label}
             loading={copying}
-            onClick={async () => {
-                setCopying(true);
-
-                try {
-                    if (navigator.clipboard) {
-                        await navigator.clipboard.writeText(value);
-                        setCopiedValue(value);
-                    } else {
-                        setCopiedValue(copySelection(value) ? value : null);
-                    }
-                } catch {
-                    setCopiedValue(copySelection(value) ? value : null);
-                } finally {
-                    setCopying(false);
-                }
-            }}
+            onClick={copy}
             tone={copied ? 'success' : 'neutral'}
         />
     );

package/src/display/Diagram.tsx

@@ -0,0 +1,59 @@
+import { useEffect, useId, useRef, useState } from 'react';
+
+interface DiagramProps {
+    /** The diagram's text, such as a Mermaid flowchart. */
+    source: string;
+    /** Draws `source` as an SVG document's markup; `id` is unique to this diagram. A rejection shows `failedLabel`. */
+    draw: (source: string, id: string) => Promise<string>;
+    /** The drawing's accessible name. */
+    label: string;
+    /** Shown in place of the drawing when `draw` fails. */
+    failedLabel: string;
+    /** The disclosure that shows the source under the drawing. */
+    sourceLabel: string;
+}
+
+/** A drawn diagram in a bordered figure, with its source under it in a disclosure. The SVG comes from `draw`, so the
+ *  design system needs no diagram library; a drawing too wide for its figure scrolls inside it. */
+export function Diagram({ source, draw, label, failedLabel, sourceLabel }: DiagramProps) {
+    const id = useId().replace(/[^a-zA-Z0-9]/g, '');
+    const host = useRef<HTMLDivElement>(null);
+    // The source the diagram failed on, so a new source draws afresh.
+    const [failed, setFailed] = useState<string | null>(null);
+
+    useEffect(() => {
+        const drawn = new AbortController();
+
+        draw(source, id).then(
+            (svg) => {
+                if (!drawn.signal.aborted && host.current) host.current.innerHTML = svg;
+            },
+            () => {
+                if (!drawn.signal.aborted) setFailed(source);
+            },
+        );
+
+        return () => drawn.abort();
+    }, [draw, id, source]);
+
+    return (
+        <figure className="m-0 grid min-w-0 gap-2 rounded-lg border p-3" data-map-diagram>
+            {failed === source ? (
+                <p role="status" className="text-base-700 m-0 text-xs">
+                    {failedLabel}
+                </p>
+            ) : (
+                <div
+                    ref={host}
+                    className="overflow-auto [&_svg]:mx-auto [&_svg]:h-auto [&_svg]:max-w-full"
+                    role="img"
+                    aria-label={label}
+                />
+            )}
+            <details className="text-base-700 text-xs">
+                <summary className="cursor-pointer">{sourceLabel}</summary>
+                <pre className="overflow-auto pt-2 whitespace-pre-wrap">{source}</pre>
+            </details>
+        </figure>
+    );
+}

package/src/display/InsetPanel.tsx

@@ -7,17 +7,20 @@ interface InsetPanelProps {
     children: ReactNode;
     onClick?: () => void;
     presentation?: 'default' | 'settings';
+    /** Under a `settings` panel's rows, on the muted surface: the group's own action, such as an add button. */
+    footer?: ReactNode;
 }
 
 /**
  * A neutral surface that groups related content without adding message or status meaning.
  * Use Alert for current status, InfoBox for optional guidance, and NoticeCard for a decision item.
  */
-export function InsetPanel({ children, onClick, presentation = 'default' }: InsetPanelProps) {
+export function InsetPanel({ children, onClick, presentation = 'default', footer }: InsetPanelProps) {
     if (presentation === 'settings') {
         return (
             <div className="divide-base-300 border-base-300 bg-base-100 divide-y overflow-hidden rounded-lg border shadow-xs/5">
                 {children}
+                {footer && <div className="rounded-b-xl bg-(--muted) px-4 py-2">{footer}</div>}
             </div>
         );
     }

package/src/display/LabelChip.tsx

@@ -0,0 +1,73 @@
+import { LockIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { Badge } from './Badge';
+
+type DataAttributes = { [key: `data-${string}`]: string | undefined };
+
+interface LabelChipProps extends DataAttributes {
+    /** The label's name, truncating, which its tooltip gives whole. */
+    label: string;
+    /** The label's own colour, such as a tracker's, as Badge's `labelColor`; none keeps the neutral badge. */
+    color?: string | undefined;
+    /** Follows the name, faded, such as "new" for a label still to be created. */
+    note?: ReactNode;
+    /** A lock before the name, for a label that can't be edited here; `lockedLabel` says why. */
+    locked?: boolean;
+    lockedLabel?: string;
+    /** A × after the name, for a chip inside a control that removes it, such as an active filter's. */
+    removable?: boolean;
+    /** Its own × button, which `removeLabel` names, that removes the label. */
+    onRemove?: () => void;
+    removeLabel?: string;
+    disabled?: boolean;
+}
+
+/** A label as a chip in its own colour, such as a tracker's: its name truncating, then any note, and a lock or a × that
+ *  removes it. */
+export function LabelChip({
+    label,
+    color,
+    note,
+    locked = false,
+    lockedLabel,
+    removable = false,
+    onRemove,
+    removeLabel,
+    disabled = false,
+    ...data
+}: LabelChipProps) {
+    return (
+        <Badge
+            data-label-chip=""
+            {...data}
+            title={locked ? lockedLabel : undefined}
+            className="max-w-full min-w-0"
+            labelColor={color}
+        >
+            {locked && <LockIcon aria-label={lockedLabel} />}
+            <span className="max-w-52 truncate" title={label}>
+                {label}
+            </span>
+            {note && (
+                <>
+                    {' '}
+                    <span className="opacity-70">{note}</span>
+                </>
+            )}
+            {onRemove ? (
+                <button
+                    type="button"
+                    className="cursor-pointer bg-transparent p-0"
+                    aria-label={removeLabel}
+                    disabled={disabled}
+                    onClick={onRemove}
+                >
+                    ×
+                </button>
+            ) : (
+                removable && <span aria-hidden="true">×</span>
+            )}
+        </Badge>
+    );
+}

package/src/display/LabelTint.ts

@@ -0,0 +1,72 @@
+// A tracker's label colour (GitHub's, say) as a chip's style. A label's colour says nothing about what it sits on, so the text starts from a
+// mix with the foreground and moves towards the foreground, in each mode, until it reaches the contrast a chip's name needs.
+
+type Rgb = readonly [number, number, number];
+type Mode = 'light' | 'dark';
+
+/** WCAG AA for text this small. */
+export const CONTRAST_FLOOR = 4.5;
+
+/** The palette's foreground, and the surface a chip's text contrasts least with: the accent a hovered or picked row fills with. */
+export const PALETTE: Record<Mode, { foreground: string; surface: string }> = {
+    light: { foreground: '#27272a', surface: '#f4f4f5' },
+    dark: { foreground: '#f5f5f5', surface: '#161616' },
+};
+
+const FILL = 0.16;
+const TEXT_SHARE = 0.55;
+
+const rgbOf = (hex: string): Rgb | null => {
+    const digits = /^#?([0-9a-f]{6})$/i.exec(hex)?.[1];
+
+    return digits ? ([0, 2, 4].map((at) => parseInt(digits.slice(at, at + 2), 16)) as unknown as Rgb) : null;
+};
+const mixed = (a: Rgb, b: Rgb, share: number): Rgb =>
+    a.map((part, at) => part * share + b[at]! * (1 - share)) as unknown as Rgb;
+const hexOf = (color: Rgb) => `#${color.map((part) => Math.round(part).toString(16).padStart(2, '0')).join('')}`;
+
+const luminance = (color: Rgb): number => {
+    const [r, g, b] = color.map((part) => {
+        const linear = part / 255;
+
+        return linear <= 0.03928 ? linear / 12.92 : ((linear + 0.055) / 1.055) ** 2.4;
+    }) as unknown as Rgb;
+
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+/** The WCAG contrast ratio of two colours. */
+export function contrastRatio(a: string, b: string): number {
+    const [lighter, darker] = [luminance(rgbOf(a)!), luminance(rgbOf(b)!)].sort((x, y) => y - x) as [number, number];
+
+    return (lighter + 0.05) / (darker + 0.05);
+}
+
+/** A chip's fill in `mode`, as tint's `color-mix` paints it over the palette's surface. */
+export const chipFill = (color: string, mode: Mode): string =>
+    hexOf(mixed(rgbOf(color)!, rgbOf(PALETTE[mode].surface)!, FILL));
+
+/** A chip's text in `mode`: as much of the label's colour as the contrast floor allows. The foreground alone always clears it. */
+export function chipText(color: string, mode: Mode): string {
+    const label = rgbOf(color)!;
+    const foreground = rgbOf(PALETTE[mode].foreground)!;
+    const fill = chipFill(color, mode);
+
+    for (let share = TEXT_SHARE; share > 0; share -= 0.05) {
+        const text = hexOf(mixed(label, foreground, share));
+
+        if (contrastRatio(text, fill) >= CONTRAST_FLOOR) return text;
+    }
+
+    return PALETTE[mode].foreground;
+}
+
+/** A soft tint of a tracker's label colour with its name readable in both modes; none, or one that isn't a colour, keeps the Badge's neutral style. */
+export const tint = (color: string | undefined) =>
+    color && rgbOf(color)
+        ? {
+              backgroundColor: `color-mix(in srgb, ${color} ${FILL * 100}%, transparent)`,
+              color: `light-dark(${chipText(color, 'light')}, ${chipText(color, 'dark')})`,
+              boxShadow: `inset 0 0 0 1px color-mix(in srgb, ${color} 40%, transparent)`,
+          }
+        : undefined;

package/src/display/Person.tsx

@@ -0,0 +1,11 @@
+import { Avatar } from './Avatar';
+
+/** A person: their avatar and name, the name wrapping. */
+export function Person({ name }: { name: string }) {
+    return (
+        <span className="inline-flex max-w-full min-w-0 items-center gap-1.5">
+            <Avatar name={name} compact />
+            <span className="min-w-0 wrap-anywhere">{name}</span>
+        </span>
+    );
+}

package/src/display/RadioChoice.tsx

@@ -2,21 +2,30 @@ import type { ReactNode } from 'react';
 
 import { tabbable } from '../foundations/KeyboardFocus';
 
+type DataAttributes = { [key: `data-${string}`]: string | undefined };
+
+/** One choice of a group of radios, a row of an InsetPanel's `settings` panel: the radio and its content, which can
+ *  shrink so a long title in it truncates, then any `trailing` content. Data attributes, such as the value it names,
+ *  go on the row. */
 export function RadioChoice({
     name,
     checked,
     onChange,
     children,
     trailing,
+    ...data
 }: {
     name: string;
     checked: boolean;
     onChange: () => void;
     children: ReactNode;
     trailing?: ReactNode;
-}) {
+} & DataAttributes) {
     return (
-        <div className="hover:bg-base-100 has-checked:bg-primary/10 has-focus-visible:ring-primary flex min-w-0 items-center gap-3 transition-colors has-focus-visible:ring-2 has-focus-visible:ring-inset has-disabled:opacity-60">
+        <div
+            {...data}
+            className="hover:bg-base-100 has-checked:bg-primary/10 has-focus-visible:ring-primary flex min-w-0 items-center gap-3 transition-colors has-focus-visible:ring-2 has-focus-visible:ring-inset has-disabled:opacity-60"
+        >
             <label className="flex min-w-0 flex-1 cursor-pointer items-center gap-3 px-4 py-3 has-disabled:cursor-default">
                 <input
                     {...tabbable}