@lar-works/design-system 0.0.0-stage → 0.1.0

package/src/display/Artwork.tsx

@@ -0,0 +1,140 @@
+import { type HTMLAttributeReferrerPolicy, type ReactNode, useCallback, useEffect, useRef, useState } from 'react';
+
+import { SkeletonLoader } from '../feedback/SkeletonLoader';
+import { tabbable } from '../foundations/KeyboardFocus';
+import { ItemAction, type ItemActionProps } from './ItemAction';
+
+export interface ArtworkProps {
+    alt: string;
+    aspect?: 'square' | 'video' | 'poster' | 'logo';
+    error?: boolean;
+    errorLabel?: string;
+    fallback?: ReactNode;
+    loadingLabel?: string;
+    pendingLabel?: string;
+    editAction?: ItemActionProps;
+    /** Makes the whole image a button, typically to enlarge it; offered only when there is an image to show. */
+    viewAction?: { label: string; onClick: () => void };
+    showLoadingIndicator?: boolean;
+    pending?: boolean;
+    referrerPolicy?: HTMLAttributeReferrerPolicy;
+    sizes?: string;
+    src?: string;
+    srcSet?: string;
+}
+
+export function Artwork({
+    alt,
+    aspect = 'square',
+    error = false,
+    errorLabel,
+    fallback,
+    loadingLabel,
+    pendingLabel,
+    editAction,
+    viewAction,
+    showLoadingIndicator = true,
+    pending = false,
+    referrerPolicy,
+    sizes,
+    src,
+    srcSet,
+}: ArtworkProps) {
+    const [failedSource, setFailedSource] = useState<string>();
+    const [loadedSource, setLoadedSource] = useState<string>();
+    const [slowSource, setSlowSource] = useState<string>();
+    const imageRef = useRef<HTMLImageElement | null>(null);
+    const failed = error || Boolean(src && failedSource === src);
+    const loaded = Boolean(src && !failed && loadedSource === src);
+    const shouldLoad = Boolean(src && !failed);
+    const loading = !loaded && !failed && Boolean(pending || pendingLabel || loadingLabel || shouldLoad);
+    const state = loadingLabel || pendingLabel ? 'loading' : loaded ? 'ready' : loading ? 'loading' : 'placeholder';
+    const showLoading = state === 'loading' && Boolean(loadingLabel || (!pendingLabel && src && slowSource === src));
+    const revealImage = useCallback((image: HTMLImageElement, source: string | undefined) => {
+        if (!source) return;
+
+        const current = () => imageRef.current === image && image.getAttribute('src') === source;
+        const reveal = () => {
+            if (!current()) return;
+
+            setLoadedSource(source);
+        };
+
+        if (typeof image.decode === 'function') {
+            void image.decode().then(reveal, () => {
+                if (current()) setFailedSource(source);
+            });
+        } else reveal();
+    }, []);
+    const attachImage = useCallback(
+        (image: HTMLImageElement | null) => {
+            imageRef.current = image;
+
+            if (image?.complete && image.naturalWidth > 0) revealImage(image, src);
+        },
+        [revealImage, src],
+    );
+
+    useEffect(() => {
+        if (!shouldLoad || loaded) return;
+
+        const timeout = window.setTimeout(() => setSlowSource(src), 150);
+
+        return () => window.clearTimeout(timeout);
+    }, [loaded, shouldLoad, src]);
+
+    return (
+        <div
+            role={pendingLabel ? 'status' : undefined}
+            aria-label={pendingLabel}
+            aria-busy={state === 'loading'}
+            className={`relative overflow-hidden rounded-lg ${aspect === 'logo' ? 'aspect-[3/1]' : aspect === 'poster' ? 'bg-base-200 aspect-[2/3]' : aspect === 'video' ? 'bg-base-200 aspect-video' : 'bg-base-200 aspect-square'}`}
+            data-state={state}
+        >
+            {loading ? (
+                <div className="absolute inset-0">
+                    <SkeletonLoader.Shape presentation={aspect === 'poster' ? 'poster' : 'artwork'} />
+                </div>
+            ) : !loaded ? (
+                <span
+                    role={failed && errorLabel ? 'img' : undefined}
+                    aria-label={failed ? errorLabel : undefined}
+                    aria-hidden={failed && errorLabel ? undefined : true}
+                    className="text-base-400 absolute inset-0 flex items-center justify-center"
+                >
+                    <span className="size-1/3 max-h-16 min-h-4 max-w-16 min-w-4 [&>svg]:size-full">{fallback}</span>
+                </span>
+            ) : null}
+            {(showLoading && showLoadingIndicator) || (editAction && state !== 'loading') ? (
+                <div className="absolute right-2 bottom-2 z-10">
+                    <ItemAction action={editAction} loading={showLoading} loadingLabel={loadingLabel} />
+                </div>
+            ) : null}
+            {shouldLoad ? (
+                <img
+                    alt={alt}
+                    ref={attachImage}
+                    className={`absolute inset-0 size-full ${aspect === 'logo' ? 'object-contain' : 'object-cover'} ${loaded ? 'opacity-100' : 'opacity-0'}`}
+                    decoding="async"
+                    loading="lazy"
+                    referrerPolicy={referrerPolicy}
+                    sizes={sizes}
+                    src={src}
+                    srcSet={srcSet}
+                    onError={() => setFailedSource(src)}
+                    onLoad={(event) => revealImage(event.currentTarget, src)}
+                />
+            ) : null}
+            {viewAction && shouldLoad ? (
+                <button
+                    {...tabbable}
+                    type="button"
+                    aria-label={viewAction.label}
+                    title={viewAction.label}
+                    className="hover:bg-base-900/10 focus-visible:outline-primary absolute inset-0 cursor-zoom-in rounded-lg transition-colors focus-visible:outline-2 focus-visible:-outline-offset-2 motion-reduce:transition-none"
+                    onClick={viewAction.onClick}
+                />
+            ) : null}
+        </div>
+    );
+}

package/src/display/Avatar.tsx

@@ -0,0 +1,7 @@
+import { Avatar as NinnaAvatar, type AvatarProps as NinnaAvatarProps } from '@ninna-ui/primitives';
+
+type AvatarProps = Omit<NinnaAvatarProps, 'color' | 'size' | 'radius'>;
+
+export function Avatar(props: AvatarProps) {
+    return <NinnaAvatar {...props} color="neutral" size="sm" />;
+}

package/src/display/Badge.tsx

@@ -0,0 +1,33 @@
+import { Badge as NinnaBadge, type BadgeProps as NinnaBadgeProps } from '@ninna-ui/primitives';
+import type { CSSProperties } from 'react';
+
+import type { StatusTone } from '../feedback/StatusIndicator';
+
+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;
+};
+
+/** T3 Code's badge: a 6px-radius label on an 8% tint of its tone, in the tone's foreground colour. */
+const toneClasses: Record<NonNullable<BadgeProps['tone']>, string> = {
+    neutral: 'bg-base-200 text-base-800 dark:bg-base-300 dark:text-base-800',
+    accent: 'bg-primary/10 text-primary dark:bg-primary/20 dark:text-[color-mix(in_srgb,var(--color-primary)_55%,white)]',
+    success: 'bg-success/10 text-(--lar-success-text) dark:bg-success/16',
+    warning: 'bg-warning/12 text-(--lar-warning-text) dark:bg-warning/16',
+    danger: 'bg-danger/10 text-(--lar-danger-text) dark:bg-danger/16',
+    info: 'bg-info/10 text-(--lar-info-text) dark:bg-info/16',
+};
+
+export function Badge({ tone = 'neutral', hue, className = '', style, ...props }: BadgeProps) {
+    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}`}
+        />
+    );
+}

package/src/display/BadgeList.tsx

@@ -0,0 +1,25 @@
+import { Badge } from './Badge';
+
+export interface BadgeListItem {
+    id: string;
+    label: string;
+    /** Shown struck through, as a warning, when the item doesn't apply. */
+    struck?: boolean;
+}
+
+export function BadgeList({ items, label }: { items: readonly BadgeListItem[]; label?: string }) {
+    return (
+        <ul aria-label={label} className="flex flex-wrap gap-2">
+            {items.map(({ id, label: text, struck = false }) => (
+                <li key={id} className="max-w-full min-w-0">
+                    <Badge
+                        tone={struck ? 'warning' : 'neutral'}
+                        className="max-w-full wrap-break-word whitespace-normal"
+                    >
+                        {struck ? <del>{text}</del> : text}
+                    </Badge>
+                </li>
+            ))}
+        </ul>
+    );
+}

package/src/display/BrandMark.tsx

@@ -0,0 +1,72 @@
+import type { AnchorHTMLAttributes } from 'react';
+
+import { tabbable } from '../foundations/KeyboardFocus';
+
+// The lar mark on a 100-unit box: the L takes the ink colour, the block is always lar blue.
+const MARK_L = 'M0 0H27.52V72.48H100V100H3a3 3 0 0 1-3-3z';
+const MARK_S =
+    'M50.68 0H91.97a8.03 8.03 0 0 1 8.03 8.03V49.32a8.03 8.03 0 0 1-8.03 8.03H50.68a8.03 8.03 0 0 1-8.03-8.03V8.03a8.03 8.03 0 0 1 8.03-8.03z';
+
+const sizes = { md: 'text-xl', lg: 'text-[1.6rem]' } as const;
+
+/** The Lar lockup: the mark stands in for the L, on the baseline, then "ar", then an optional product name in grey
+ *  after a 0.26em space (lar-brand SPEC.md). */
+export function BrandMark({
+    label,
+    product,
+    size = 'md',
+}: {
+    label: string;
+    product?: string;
+    size?: keyof typeof sizes;
+}) {
+    return (
+        <span
+            role="img"
+            aria-label={label}
+            className={`lar-brand-mark inline-flex shrink-0 items-baseline leading-none ${sizes[size]}`}
+        >
+            <svg aria-hidden viewBox="0 0 100 100" className="mr-[0.07em] size-[0.705em] shrink-0">
+                <path d={MARK_L} fill="currentColor" />
+                <path d={MARK_S} fill="#355292" />
+            </svg>
+            <span aria-hidden className="font-bold tracking-[-0.03em]">
+                ar
+            </span>
+            {product ? (
+                <span
+                    aria-hidden
+                    className="ml-[0.26em] font-medium tracking-[-0.02em] text-[#6b6b73] dark:text-[#8b8b94]"
+                >
+                    {product}
+                </span>
+            ) : null}
+        </span>
+    );
+}
+
+interface BrandLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className' | 'style'> {
+    href: string;
+    label: string;
+    onNavigate: (href: string) => void;
+}
+
+/** The lockup as the link home. */
+export function BrandLink({ href, label, onNavigate, ...props }: BrandLinkProps) {
+    return (
+        <a
+            {...tabbable}
+            {...props}
+            href={href}
+            onClick={(event) => {
+                if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0) return;
+
+                event.preventDefault();
+                onNavigate(href);
+            }}
+            className="focus-visible:outline-primary -mx-1 inline-flex items-center rounded-md px-1 py-1 focus-visible:outline-2"
+        >
+            <BrandMark label={label} />
+        </a>
+    );
+}

package/src/display/ChangeList.tsx

@@ -0,0 +1,41 @@
+import { Code } from '@ninna-ui/primitives';
+
+import { Stack } from '../layout/Flow';
+import { Text } from '../typography/Typography';
+
+export interface ChangeListItem {
+    changes: readonly { from: string; key: string; label: string; to: string }[];
+    key: string;
+    title: string;
+}
+
+/** Before → after values grouped under the item they belong to. */
+export function ChangeList({ items, label }: { items: readonly ChangeListItem[]; label: string }) {
+    return (
+        <Stack as="ul" space="group" aria-label={label}>
+            {items.map((item) => (
+                <li key={item.key} className="min-w-0">
+                    <Stack space="tight">
+                        <Text truncate title={item.title} variant="label">
+                            {item.title}
+                        </Text>
+                        <ul className="space-y-1 pl-4">
+                            {item.changes.map((change) => (
+                                <li key={change.key} className="flex min-w-0 flex-wrap items-baseline gap-x-2">
+                                    <Text as="span" variant="caption" tone="muted">
+                                        {change.label}
+                                    </Text>
+                                    <Code className="text-xs">{change.from}</Code>
+                                    <Text as="span" aria-hidden="true" variant="caption" tone="muted">
+                                        →
+                                    </Text>
+                                    <Code className="text-xs">{change.to}</Code>
+                                </li>
+                            ))}
+                        </ul>
+                    </Stack>
+                </li>
+            ))}
+        </Stack>
+    );
+}

package/src/display/CheckList.tsx

@@ -0,0 +1,27 @@
+import { CheckIcon } from 'lucide-react';
+
+import { Text } from '../typography/Typography';
+
+export interface CheckListItem {
+    key: string;
+    text: string;
+}
+
+/** Short statements of what something does or includes, each with a check mark. */
+export function CheckList({ items, label }: { items: readonly CheckListItem[]; label: string }) {
+    return (
+        <ul aria-label={label} className="space-y-2">
+            {items.map((item) => (
+                <li key={item.key} className="flex min-w-0 items-start gap-2">
+                    <span
+                        aria-hidden="true"
+                        className="text-success mt-0.5 flex size-4 shrink-0 items-center justify-center [&>svg]:size-4"
+                    >
+                        <CheckIcon />
+                    </span>
+                    <Text as="span">{item.text}</Text>
+                </li>
+            ))}
+        </ul>
+    );
+}

package/src/display/CodeBlock.tsx

@@ -0,0 +1,12 @@
+/** Readable examples and configuration values, contained even in narrow drawers. */
+export function CodeBlock({ value, preserveLines = false }: { value: string; preserveLines?: boolean }) {
+    return (
+        <pre
+            className={`border-base-300 bg-base-100/70 text-base-800 min-w-0 rounded-lg border p-4 font-mono text-xs leading-6 ${
+                preserveLines ? 'overflow-x-auto' : 'wrap-anywhere whitespace-pre-wrap'
+            }`}
+        >
+            <code>{value}</code>
+        </pre>
+    );
+}

package/src/display/CopyButton.tsx

@@ -0,0 +1,77 @@
+import { CheckIcon, CopyIcon } from 'lucide-react';
+import { useEffect, useState } from 'react';
+
+import { IconButton } from '../actions/IconButton';
+
+const COPIED_FEEDBACK_MS = 1500;
+
+interface CopyButtonProps {
+    copiedLabel: string;
+    label: string;
+    value: string;
+}
+
+/** The LAN admin also runs over HTTP, where the async clipboard API is unavailable. */
+export function CopyButton({ copiedLabel, label, value }: CopyButtonProps) {
+    const [copiedValue, setCopiedValue] = useState<string | null>(null);
+    const [copying, setCopying] = useState(false);
+    const copied = copiedValue === value;
+
+    useEffect(() => {
+        if (copiedValue === null) return undefined;
+
+        const timer = window.setTimeout(() => setCopiedValue(null), COPIED_FEEDBACK_MS);
+
+        return () => window.clearTimeout(timer);
+    }, [copiedValue]);
+
+    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);
+                }
+            }}
+            tone={copied ? 'success' : 'neutral'}
+        />
+    );
+}
+
+function copySelection(value: string): boolean {
+    if (typeof document.execCommand !== 'function') return false;
+
+    const previousFocus = document.activeElement;
+    const input = document.createElement('textarea');
+
+    input.value = value;
+    input.readOnly = true;
+    input.className = 'fixed -left-full top-0 opacity-0';
+    document.body.append(input);
+    input.focus({ preventScroll: true });
+    input.select();
+
+    try {
+        return document.execCommand('copy');
+    } catch {
+        return false;
+    } finally {
+        input.remove();
+
+        if (previousFocus instanceof HTMLElement) previousFocus.focus();
+    }
+}

package/src/display/DataTable.tsx

@@ -0,0 +1,80 @@
+const cellSpacing = 'px-4 py-2.5 sm:first:pl-5 sm:last:pr-5';
+
+const tones = {
+    default: 'text-base-content',
+    muted: 'text-base-700',
+    warning: 'text-warning',
+} as const;
+
+export interface DataTableCell {
+    id: string;
+    text: string;
+    /** A smaller second line under the text. */
+    detail?: string;
+    /** Shown on hover. */
+    title?: string;
+    tone?: keyof typeof tones;
+}
+
+export interface DataTableRow {
+    id: string;
+    label: string;
+    /** One per column, in column order. */
+    cells: readonly DataTableCell[];
+}
+
+interface DataTableProps {
+    columns: readonly { id: string; label: string }[];
+    /** Names the table for assistive technology. */
+    label: string;
+    /** Heads the first column, which labels each row. */
+    rowHeader: string;
+    rows: readonly DataTableRow[];
+}
+
+/** A compact read-only grid of values: one labelled row per item and one column per subject. */
+export function DataTable({ columns, label, rowHeader, rows }: DataTableProps) {
+    return (
+        <div className="overflow-x-auto">
+            <table aria-label={label} className="w-full text-left text-sm leading-5 tabular-nums">
+                <thead className="text-base-700 text-xs leading-4">
+                    <tr className="border-base-300 border-b">
+                        <th scope="col" className={`${cellSpacing} font-medium`}>
+                            {rowHeader}
+                        </th>
+                        {columns.map((column) => (
+                            <th key={column.id} scope="col" className={`${cellSpacing} font-medium`}>
+                                {column.label}
+                            </th>
+                        ))}
+                    </tr>
+                </thead>
+                <tbody className="divide-base-300 divide-y">
+                    {rows.map((row) => (
+                        <tr key={row.id}>
+                            <th scope="row" className={`${cellSpacing} text-base-content font-normal`}>
+                                {row.label}
+                            </th>
+                            {row.cells.map((cell) => (
+                                <td
+                                    key={cell.id}
+                                    title={cell.title}
+                                    className={`${cellSpacing} text-xs leading-4 ${tones[cell.tone ?? 'default']}`}
+                                >
+                                    {cell.detail ? (
+                                        <>
+                                            <span className="block">{cell.text}</span>
+                                            <span className="text-base-700 mt-0.5 block">{cell.detail}</span>
+                                        </>
+                                    ) : (
+                                        cell.text
+                                    )}
+                                </td>
+                            ))}
+                        </tr>
+                    ))}
+                </tbody>
+            </table>
+        </div>
+    );
+}