@adecore/ui 0.14.0

package/src/ChoiceCards.tsx

@@ -0,0 +1,108 @@
+import { Fragment, useId, type ReactNode, type Ref } from 'react';
+import clsx from 'clsx';
+import type { LucideIcon } from 'lucide-react';
+import { Radio } from '@base-ui-components/react/radio';
+import { RadioGroup } from '@base-ui-components/react/radio-group';
+import { Icon } from './Icon.tsx';
+
+export interface Choice<Value extends string | number> {
+    value: Value;
+    title: string;
+    /* One line under the title that says what picking it means. */
+    description: string;
+    icon?: LucideIcon;
+    disabled?: boolean;
+}
+
+export interface ChoiceCardsProps<Value extends string | number> {
+    value: Value;
+    onValueChange(value: Value): void;
+    choices: readonly Choice<Value>[];
+    /* What the group picks, read by a screen reader since the row has no visible heading of its own. */
+    label: string;
+    /* Side by side at the same width, or one under the other for choices whose descriptions run long. */
+    orientation?: 'horizontal' | 'vertical';
+    /* A set number of columns, filled row by row, for more choices than one row has room for; takes the place of `orientation`. */
+    columns?: number;
+    /* Where the radio stands in a card: after the text, or before the icon and the title. */
+    radio?: 'start' | 'end';
+    /* What the checked choice still asks for, such as a folder or an address, right under its card; only a vertical group without columns has room for it. */
+    detail?: ReactNode;
+    disabled?: boolean;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+
+function ChoiceCard<Value extends string | number>({ choice, radio }: { choice: Choice<Value>; radio: 'start' | 'end' }) {
+    const id = useId();
+    // As tall as the title's line, so the dot centers on it.
+    const dot = (
+        <span className="flex h-(--text-sm--line-height) shrink-0 items-center" aria-hidden>
+            <span className="size-4 rounded-full border border-border-strong group-data-checked:border-5 group-data-checked:border-accent group-data-checked:bg-accent-text" />
+        </span>
+    );
+    return (
+        <Radio.Root
+            value={choice.value}
+            disabled={choice.disabled}
+            aria-labelledby={`${id}-title`}
+            aria-describedby={`${id}-description`}
+            className="group focus-ring flex min-w-0 items-start gap-3 rounded-xl border border-border bg-surface p-3 text-left hover:bg-surface-hover data-checked:border-accent data-disabled:opacity-50 data-disabled:hover:bg-surface"
+        >
+            {radio === 'start' && dot}
+            {choice.icon && (
+                <span className="grid size-8 shrink-0 place-items-center rounded-lg bg-surface-sunken text-text-muted group-data-checked:text-accent">
+                    <Icon icon={choice.icon} size={16} />
+                </span>
+            )}
+            <span className="flex min-w-0 grow flex-col gap-0.5">
+                <span id={`${id}-title`} className="text-sm font-medium text-text">
+                    {choice.title}
+                </span>
+                <span id={`${id}-description`} className="text-xs text-pretty text-text-muted">
+                    {choice.description}
+                </span>
+            </span>
+            {radio === 'end' && dot}
+        </Radio.Root>
+    );
+}
+
+/*
+ * One of a few options, each a card that says what it means, for a choice that deserves more than a
+ * select: the cards stand side by side at the same width, one under the other or in a set number of
+ * columns, and the arrow keys move between them.
+ */
+export function ChoiceCards<Value extends string | number>({
+    value,
+    onValueChange,
+    choices,
+    label,
+    orientation = 'horizontal',
+    columns,
+    radio = 'end',
+    detail,
+    disabled,
+    className,
+    ref
+}: ChoiceCardsProps<Value>) {
+    const vertical = columns === undefined && orientation === 'vertical';
+    return (
+        <RadioGroup
+            ref={ref}
+            value={value}
+            onValueChange={(next) => onValueChange(next as Value)}
+            disabled={disabled}
+            aria-label={label}
+            className={clsx('grid gap-2', columns !== undefined || vertical ? 'grid-flow-row' : 'auto-cols-fr grid-flow-col', className)}
+            style={columns !== undefined ? { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` } : undefined}
+        >
+            {choices.map((choice) => (
+                <Fragment key={choice.value}>
+                    <ChoiceCard choice={choice} radio={radio} />
+                    {vertical && choice.value === value && detail}
+                </Fragment>
+            ))}
+        </RadioGroup>
+    );
+}

package/src/CloseButton.tsx

@@ -0,0 +1,21 @@
+import type { Ref } from 'react';
+import { X } from 'lucide-react';
+import { Dialog } from '@base-ui-components/react/dialog';
+import { IconButton, type IconButtonSize } from './IconButton.tsx';
+import type { Shortcut } from './shortcut.ts';
+
+export type CloseButtonProps = {
+    label: string;
+    kbd?: Shortcut | string;
+    size?: IconButtonSize;
+    className?: string;
+    ref?: Ref<HTMLButtonElement>;
+} & ({ onClick: () => void } | { dialog: true });
+
+/* The close button in the header of every panel and dialog. In a dialog it is that dialog's own close part. */
+export function CloseButton({ label, kbd, size, className, ref, ...closes }: CloseButtonProps) {
+    if ('dialog' in closes) {
+        return <IconButton ref={ref} icon={X} label={label} kbd={kbd} size={size} className={className} render={<Dialog.Close />} />;
+    }
+    return <IconButton ref={ref} icon={X} label={label} kbd={kbd} size={size} className={className} onClick={closes.onClick} />;
+}

package/src/ColorSwatch.tsx

@@ -0,0 +1,41 @@
+import type { ComponentProps } from 'react';
+import clsx from 'clsx';
+import { Check } from 'lucide-react';
+import { useRender } from '@base-ui-components/react/use-render';
+import { Icon } from './Icon.tsx';
+
+/* `focus-ring` for the swatch that is a menu item rather than a button, which the keyboard reaches all the same. */
+const SWATCH = 'focus-ring grid h-6 w-6 place-items-center rounded-full text-accent-text';
+
+/* The ring of the picked color is offset against whatever the swatch stands on. */
+const PICKED_RING = {
+    surface: 'ring-2 ring-accent ring-offset-2 ring-offset-surface',
+    popup: 'ring-2 ring-accent ring-offset-1 ring-offset-surface-raised'
+} as const;
+
+export interface ColorSwatchProps extends ComponentProps<'button'> {
+    /* Any CSS color. Without one the swatch is an outlined circle: "no color", or the button that opens the rest of a palette. */
+    color?: string;
+    picked?: boolean;
+    /* On the surface behind a popup, or inside the popup itself. */
+    on?: keyof typeof PICKED_RING;
+    /* Another element to be the swatch, such as a menu trigger, or `<Menu.Item unstyled />` so the row's padding and highlight stay off it. */
+    render?: useRender.RenderProp;
+}
+
+/*
+ * One color, drawn as the color itself. Its name belongs in a tooltip, so the circle carries a tick
+ * alone when it is picked. Children replace the tick, such as the ellipsis of a "more colors" swatch.
+ */
+export function ColorSwatch({ color, picked = false, on = 'surface', render, className, style, ref, children, ...props }: ColorSwatchProps) {
+    return useRender({
+        render: render ?? <button type="button" />,
+        ref,
+        props: {
+            ...props,
+            className: clsx(SWATCH, color === undefined ? 'border border-border-strong text-text-muted' : picked && PICKED_RING[on], className),
+            style: color === undefined ? style : { ...style, background: color },
+            children: children ?? (picked && <Icon icon={Check} size={12} />)
+        }
+    });
+}

package/src/ColumnResizeHandle.tsx

@@ -0,0 +1,23 @@
+import type { PointerEvent as ReactPointerEvent, Ref } from 'react';
+import clsx from 'clsx';
+import type { ColumnEdge } from './useColumnResize.ts';
+
+export interface ColumnResizeHandleProps {
+    /* The edge the column hangs from, as handed to `useColumnResize`; the handle sits on the other one. */
+    from: ColumnEdge;
+    onPointerDown(event: ReactPointerEvent<HTMLElement>): void;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+
+const PLACEMENT: Record<ColumnEdge, string> = {
+    left: 'inset-y-0 right-0 w-2 cursor-col-resize',
+    right: 'inset-y-0 left-0 w-2 cursor-col-resize',
+    top: 'inset-x-0 bottom-0 h-2 cursor-row-resize',
+    bottom: 'inset-x-0 top-0 h-2 cursor-row-resize'
+};
+
+/* An invisible strip over the free edge of a column, so the column needs `relative` and draws its own border. */
+export function ColumnResizeHandle({ from, onPointerDown, className, ref }: ColumnResizeHandleProps) {
+    return <div ref={ref} className={clsx('absolute z-10', PLACEMENT[from], className)} onPointerDown={onPointerDown} />;
+}

package/src/DisabledReason.tsx

@@ -0,0 +1,23 @@
+import type { ReactElement } from 'react';
+import { Tooltip } from './Tooltip.tsx';
+
+/*
+ * Why a row cannot be picked, in a tooltip beside it rather than in the row itself. A reason is a
+ * sentence, and a sentence in a menu row sets the width of the whole menu. A row with nothing in its
+ * way is handed through untouched, so it carries no tooltip at all.
+ */
+export interface DisabledReasonProps {
+    reason: string | null;
+    children: ReactElement<Record<string, unknown>>;
+}
+
+export function DisabledReason({ reason, children }: DisabledReasonProps) {
+    if (reason === null) {
+        return children;
+    }
+    return (
+        <Tooltip label={reason} side="right">
+            {children}
+        </Tooltip>
+    );
+}

package/src/DockShell.tsx

@@ -0,0 +1,76 @@
+import { useEffect, useRef, useState, type HTMLAttributes, type ReactNode, type Ref } from 'react';
+import clsx from 'clsx';
+import { Surface } from './Surface.tsx';
+
+/* How close to the bottom of the window the pointer has to come before a hidden dock slides back. */
+const REVEAL_ZONE = 120;
+
+export interface DockShellProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+    /* The dock waits below the window's edge until the pointer comes down to it. */
+    autoHide?: boolean;
+    /* Classes for the bar itself, such as letting a dock with many buttons wrap. */
+    barClassName?: string;
+    /* Told whenever the bar slides away or comes back, for what stands on top of it. */
+    onHiddenChange?: (hidden: boolean) => void;
+    ref?: Ref<HTMLDivElement>;
+}
+
+/*
+ * The floating bar at the bottom of a canvas-like view, and the one place that knows how to get out
+ * of the way. With `autoHide` it waits below the edge until the pointer comes down to it, an open
+ * menu keeps it up (it would take its own popup with it), and a keyboard reaches it by tabbing. The
+ * buttons stay in the tab order while it is out of sight, so focus brings it back. Something that
+ * moves with the dock marks itself `data-holds-dock`, so reaching for it does not hide the dock.
+ */
+export function DockShell({ children, autoHide = false, className, barClassName, onHiddenChange, ref, ...rest }: DockShellProps) {
+    const barRef = useRef<HTMLDivElement>(null);
+    const [revealed, setRevealed] = useState(false);
+
+    useEffect(() => {
+        if (!autoHide) {
+            return;
+        }
+        let pointerNear = false;
+        const evaluate = (): void => {
+            const bar = barRef.current;
+            const holds = bar !== null && (bar.querySelector('[data-popup-open]') !== null || bar.querySelector(':focus-visible') !== null);
+            setRevealed(pointerNear || holds);
+        };
+        const onMove = (event: PointerEvent): void => {
+            /* Something that moves with the dock would slide away under the pointer reaching for it,
+               so over one the dock stays as it is. */
+            if (event.target instanceof Element && event.target.closest('[data-holds-dock]') !== null) {
+                return;
+            }
+            pointerNear = window.innerHeight - event.clientY <= REVEAL_ZONE;
+            evaluate();
+        };
+        window.addEventListener('pointermove', onMove);
+        window.addEventListener('focusin', evaluate);
+        return () => {
+            window.removeEventListener('pointermove', onMove);
+            window.removeEventListener('focusin', evaluate);
+            setRevealed(false);
+        };
+    }, [autoHide]);
+
+    const hidden = autoHide && !revealed;
+    useEffect(() => {
+        onHiddenChange?.(hidden);
+    }, [hidden, onHiddenChange]);
+    return (
+        <div ref={ref} {...rest} className={clsx('pointer-events-none absolute inset-x-0 bottom-4 flex justify-center', className)}>
+            <Surface
+                ref={barRef}
+                className={clsx(
+                    'flex items-center gap-2 rounded-xl p-1 transition-[opacity,translate] duration-200',
+                    barClassName,
+                    hidden ? 'pointer-events-none translate-y-6 opacity-0' : 'pointer-events-auto'
+                )}
+            >
+                {children}
+            </Surface>
+        </div>
+    );
+}

package/src/EmptyState.tsx

@@ -0,0 +1,48 @@
+import { cloneElement, isValidElement, type ReactElement, type ReactNode, type Ref } from 'react';
+import type { LucideIcon } from 'lucide-react';
+import clsx from 'clsx';
+import { Icon } from './Icon.tsx';
+import { Spinner } from './Spinner.tsx';
+
+// One size in a panel, a card and a dialog alike, so no caller picks its own.
+const ICON_SIZE = 20;
+
+export interface EmptyStateProps {
+    /* A Lucide icon, or a mark of another kind (a provider's logo) that takes a `size`. */
+    icon?: LucideIcon | ReactElement<{ size?: number }>;
+    /* A `Spinner` in place of the icon, for a state that is still loading. */
+    busy?: boolean;
+    /** @deprecated Turns a Lucide icon; use `busy`, which draws a `Spinner` in its place. */
+    spin?: boolean;
+    /* A heading above the sentence, for a state that is an outcome rather than a list with nothing in it. */
+    title?: ReactNode;
+    /* One sentence. What is missing, and what puts something there. */
+    children: ReactNode;
+    /* The button or the shortcut that fills the space; kept to one. */
+    action?: ReactNode;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+
+/* What a list, a canvas or a thread shows before it holds anything. */
+export function EmptyState({ icon, busy = false, spin = false, title, children, action, className, ref }: EmptyStateProps) {
+    return (
+        <div ref={ref} className={clsx('flex flex-col items-center justify-center gap-2 px-6 py-8 text-center', className)}>
+            {(busy || icon) && (
+                <span className="text-text-faint">
+                    {busy ? (
+                        <Spinner size={ICON_SIZE} />
+                    ) : isValidElement(icon) ? (
+                        cloneElement(icon, { size: ICON_SIZE })
+                    ) : (
+                        icon && <Icon icon={icon} size={ICON_SIZE} className={spin ? 'animate-spin' : undefined} />
+                    )}
+                </span>
+            )}
+            {title && <p className="text-sm font-medium text-text">{title}</p>}
+            <p className="max-w-[280px] text-xs leading-snug text-text-muted">{children}</p>
+            {/* The button is an answer to the sentence, not a third line of it. */}
+            {action && <div className="mt-2">{action}</div>}
+        </div>
+    );
+}

package/src/ErrorBoundary.tsx

@@ -0,0 +1,116 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { Copy, RotateCw, TriangleAlert } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { Button } from './Button.tsx';
+import { ButtonGroup } from './ButtonGroup.tsx';
+import { copyText } from './clipboard.ts';
+import { errorMessageOf, errorReport, shouldReset, type ResetKeys } from './error-boundary.ts';
+import { Icon } from './Icon.tsx';
+import { IconButton } from './IconButton.tsx';
+
+export interface ErrorBoundaryProps {
+    /* What failed, as the first line of the message: "This view failed to render". */
+    label: string;
+    /* What the children draw from; the boundary tries again when one of them changes. */
+    resetKeys?: ResetKeys;
+    /* A small surface, so its message drops the icon and the spacing. */
+    compact?: boolean;
+    /* The last resort has nothing around it to fall back to, so it offers a reload as well. */
+    reload?: boolean;
+    /* The box of the message; by default it covers the positioned parent. */
+    className?: string;
+    children: ReactNode;
+}
+
+interface ErrorBoundaryState {
+    error: unknown;
+    failed: boolean;
+    componentStack: string | null;
+}
+
+const CLEAR: ErrorBoundaryState = { error: null, failed: false, componentStack: null };
+
+interface FallbackProps {
+    label: string;
+    error: unknown;
+    componentStack: string | null;
+    compact: boolean;
+    reload: boolean;
+    className: string;
+    onRetry(): void;
+}
+
+/* A function component, so the words come from the i18next instance the app renders with. */
+function ErrorFallback({ label, error, componentStack, compact, reload, className, onRetry }: FallbackProps) {
+    const { t } = useTranslation('ui');
+    return (
+        <div role="alert" className={clsx('grid place-items-center overflow-auto bg-surface', compact ? 'p-3' : 'p-6', className)}>
+            <div className={clsx('flex max-w-[360px] flex-col items-center text-center', compact ? 'gap-1' : 'gap-2')}>
+                {!compact && <Icon icon={TriangleAlert} size={20} className="text-status-error" />}
+                <p className="text-sm font-medium text-text">{label}</p>
+                <p className="line-clamp-4 text-xs break-words text-text-muted">{errorMessageOf(error)}</p>
+                <div className={clsx('flex items-center gap-2', compact ? 'mt-1' : 'mt-2')}>
+                    <Button variant="secondary" size="sm" onClick={onRetry}>
+                        {t('action.retry')}
+                    </Button>
+                    {reload && (
+                        <Button variant="secondary" size="sm" onClick={() => window.location.reload()}>
+                            <Icon icon={RotateCw} size={14} />
+                            {t('action.reload')}
+                        </Button>
+                    )}
+                    <ButtonGroup>
+                        <IconButton icon={Copy} size="sm" label={t('action.copyError')} onClick={() => copyText(errorReport(label, error, componentStack))} />
+                    </ButtonGroup>
+                </div>
+            </div>
+        </div>
+    );
+}
+
+/*
+ * Keeps a render failure to the subtree it happened in. Without one React unmounts the whole tree,
+ * and whatever lives in it (an embedded page, a running terminal) goes down with it. Key it so it
+ * resets only while it holds an error: `resetKeys` for what the children draw from.
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    state: ErrorBoundaryState = CLEAR;
+
+    static getDerivedStateFromError(error: unknown): Partial<ErrorBoundaryState> {
+        return { error, failed: true };
+    }
+
+    componentDidCatch(error: unknown, info: ErrorInfo): void {
+        console.error(`${this.props.label}:`, error, info.componentStack);
+        this.setState({ componentStack: info.componentStack ?? null });
+    }
+
+    componentDidUpdate(previous: ErrorBoundaryProps): void {
+        if (shouldReset(this.state.failed, previous.resetKeys ?? [], this.props.resetKeys ?? [])) {
+            this.reset();
+        }
+    }
+
+    reset(): void {
+        this.setState(CLEAR);
+    }
+
+    render(): ReactNode {
+        if (!this.state.failed) {
+            return this.props.children;
+        }
+        const { label, compact = false, reload = false, className = 'absolute inset-0' } = this.props;
+        return (
+            <ErrorFallback
+                label={label}
+                error={this.state.error}
+                componentStack={this.state.componentStack}
+                compact={compact}
+                reload={reload}
+                className={className}
+                onRetry={() => this.reset()}
+            />
+        );
+    }
+}

package/src/Field.tsx

@@ -0,0 +1,116 @@
+import { useId, type ReactNode, type Ref } from 'react';
+import clsx from 'clsx';
+import { useRender } from '@base-ui-components/react/use-render';
+import { FieldContext } from './field-context.ts';
+import { SectionLabel } from './SectionLabel.tsx';
+
+const HINT = 'text-xs text-text-muted';
+const ERROR = 'text-xs text-status-error';
+// Beside the control the label reads at the size of what is typed, on the middle of the control's first line however tall it grows.
+const LABEL_BESIDE = 'flex h-8 items-center self-start text-sm text-text-muted';
+
+export type FieldHintProps = useRender.ComponentProps<'p'>;
+
+/* The line under a field that says what goes in it. */
+export function FieldHint({ render, className, ref, ...props }: FieldHintProps) {
+    return useRender({
+        render,
+        ref,
+        defaultTagName: 'p',
+        props: { ...props, className: clsx('mt-1', HINT, className) }
+    });
+}
+
+export type FormErrorProps = useRender.ComponentProps<'p'>;
+
+/* What went wrong in a dialog or a form. An alert, so a screen reader hears it arrive. */
+export function FormError({ render, className, ref, ...props }: FormErrorProps) {
+    return useRender({
+        render,
+        ref,
+        defaultTagName: 'p',
+        props: { role: 'alert', ...props, className: clsx(ERROR, className) }
+    });
+}
+
+/* A group's label names it through `aria-labelledby`; a control's points at the control. */
+function FieldLabel({ id, group, horizontal, children }: { id: string; group: boolean; horizontal: boolean; children: ReactNode }) {
+    if (horizontal) {
+        return group ? (
+            <span id={`${id}-label`} className={LABEL_BESIDE}>
+                {children}
+            </span>
+        ) : (
+            <label htmlFor={`${id}-control`} className={LABEL_BESIDE}>
+                {children}
+            </label>
+        );
+    }
+    return group ? (
+        <SectionLabel id={`${id}-label`}>{children}</SectionLabel>
+    ) : (
+        <SectionLabel render={<label htmlFor={`${id}-control`} />}>{children}</SectionLabel>
+    );
+}
+
+export interface FieldProps {
+    label?: ReactNode;
+    hint?: ReactNode;
+    /* Shown under the control and marks it invalid; null or empty shows nothing. */
+    error?: ReactNode;
+    /*
+     * For what a `<label>` cannot point at: a `Segmented`, a `Select`, cards to choose from, a path
+     * in a box with a button beside it. The label then names a group around it, which the hint and
+     * the error describe.
+     */
+    group?: boolean;
+    /* `horizontal` puts the label in a column of its own beside the control, for a form in a dialog where a stack of fields would scroll. */
+    orientation?: 'vertical' | 'horizontal';
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+    /* The control. An `Input` or a `TextArea` connects to the label and the lines under it by itself, unless the field is a `group`. */
+    children: ReactNode;
+}
+
+/*
+ * A labelled control, or a labelled group, with an optional hint and error under it, stacked 6px apart.
+ * Beside each other the label column is 112px, so the controls of every field in a form line up.
+ */
+export function Field({ label, hint, error, group = false, orientation = 'vertical', className, ref, children }: FieldProps) {
+    const horizontal = orientation === 'horizontal';
+    const id = useId();
+    const hasLabel = label !== undefined;
+    const hasHint = hint !== undefined && hint !== null && hint !== '';
+    const hasError = error !== undefined && error !== null && error !== '';
+    const describedBy = [hasHint ? `${id}-hint` : null, hasError ? `${id}-error` : null].filter((part) => part !== null).join(' ') || undefined;
+    return (
+        <div
+            ref={ref}
+            role={group ? 'group' : undefined}
+            aria-labelledby={group && hasLabel ? `${id}-label` : undefined}
+            aria-describedby={group ? describedBy : undefined}
+            className={clsx(horizontal ? 'grid grid-cols-[112px_minmax(0,1fr)] gap-x-3 gap-y-1.5' : 'flex flex-col gap-1.5', className)}
+        >
+            {hasLabel && (
+                <FieldLabel id={id} group={group} horizontal={horizontal}>
+                    {label}
+                </FieldLabel>
+            )}
+            {/* A group describes itself, so an input inside it stays unconnected rather than taking an id nothing points at. */}
+            <FieldContext value={group ? null : { id: `${id}-control`, describedBy, invalid: hasError }}>
+                {horizontal ? <div className="col-start-2 min-w-0">{children}</div> : children}
+            </FieldContext>
+            {/* The stack already puts 6px above each line, so neither takes the margin a standalone hint has. */}
+            {hasHint && (
+                <p id={`${id}-hint`} className={clsx(HINT, horizontal && 'col-start-2')}>
+                    {hint}
+                </p>
+            )}
+            {hasError && (
+                <p id={`${id}-error`} role="alert" className={clsx(ERROR, 'break-words', horizontal && 'col-start-2')}>
+                    {error}
+                </p>
+            )}
+        </div>
+    );
+}

package/src/FileIcon.tsx

@@ -0,0 +1,27 @@
+import { useInsertionEffect, type Ref } from 'react';
+import clsx from 'clsx';
+import { fileIconFor, mountFileIconSprite } from './file-icon.ts';
+
+export interface FileIconProps {
+    /* Absolute or relative; only the last segment decides which icon this is. */
+    path: string;
+    size?: number;
+    className?: string;
+    ref?: Ref<SVGSVGElement>;
+}
+
+/*
+ * The icon a file gets in a file tree, drawn anywhere else the same file's name shows up. It is the
+ * one place the library steps outside Lucide. The glyphs are Seti's, and so are their colors, because
+ * a TypeScript blue or a Vue green is the mark of the file type, not a theme choice. Decorative like
+ * every other icon here, so the name beside it does the reading.
+ */
+export function FileIcon({ path, size = 16, className, ref }: FileIconProps) {
+    // Before the browser paints, so a `<use>` never points at a symbol that is not in the document yet.
+    useInsertionEffect(mountFileIconSprite, []);
+    return (
+        <svg ref={ref} className={clsx('file-icon', className)} width={size} height={size} viewBox="0 0 16 16" aria-hidden>
+            <use href={`#${fileIconFor(path)}`} />
+        </svg>
+    );
+}

package/src/Icon.tsx

@@ -0,0 +1,22 @@
+import type { Ref } from 'react';
+import type { LucideIcon } from 'lucide-react';
+import clsx from 'clsx';
+
+// The whole client draws at this weight. 2 is Lucide's default, but at 12 and 14 pixels next to
+// text of the same size a hair thinner keeps the glyph from outweighing the words beside it.
+const STROKE_WIDTH = 1.75;
+
+export interface IconProps {
+    icon: LucideIcon;
+    size?: number;
+    className?: string;
+    ref?: Ref<SVGSVGElement>;
+}
+
+/* One Lucide icon, sized in pixels. Icons here are decorative. The name a screen reader reads
+   sits on the button or the label next to it, so the glyph stays hidden. */
+export function Icon({ icon: Glyph, size = 16, className, ref }: IconProps) {
+    // An inline svg sits on the text baseline, which drops a square glyph below the words next to
+    // it; the middle of the box against the middle of the text is what reads as aligned.
+    return <Glyph ref={ref} size={size} strokeWidth={STROKE_WIDTH} className={clsx('align-middle', className)} aria-hidden />;
+}