@adecore/ui 0.14.0

package/src/Select.tsx

@@ -0,0 +1,135 @@
+import type { ReactNode, Ref } from 'react';
+import { Select as BaseSelect } from '@base-ui-components/react/select';
+import clsx from 'clsx';
+import { ChevronDown } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { Icon } from './Icon.tsx';
+import { MENU_LABEL, MenuCheck } from './menu/parts.tsx';
+
+export interface SelectItem<T extends string> {
+    value: T;
+    label: string;
+    /* A second line under the label, for what the choice does. */
+    description?: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+
+export interface SelectGroup<T extends string> {
+    label: string;
+    items: SelectItem<T>[];
+}
+
+export interface SelectProps<T extends string> {
+    value: T | null;
+    onValueChange(value: T): void;
+    items: SelectItem<T>[] | SelectGroup<T>[];
+    /* The accessible name of the trigger; the row above it usually carries the visible one. */
+    label: string;
+    /* What the trigger shows while nothing is picked. */
+    placeholder?: string;
+    size?: 'sm' | 'md';
+    variant?: 'outlined' | 'ghost';
+    disabled?: boolean;
+    align?: 'start' | 'end';
+    truncateValue?: boolean;
+    className?: string;
+    ref?: Ref<HTMLButtonElement>;
+}
+
+const isGroup = <T extends string>(entry: SelectItem<T> | SelectGroup<T>): entry is SelectGroup<T> => Array.isArray((entry as SelectGroup<T>).items);
+
+const TRIGGER_SIZE = {
+    sm: 'h-7 gap-1 px-2',
+    md: 'h-8 gap-1.5 px-2'
+} as const;
+
+const TRIGGER_VARIANT = {
+    outlined: 'max-w-56 rounded-lg border border-border bg-surface-raised text-text',
+    ghost: 'rounded-md text-text-muted hover:bg-surface-hover hover:text-text data-[popup-open]:bg-surface-active data-[popup-open]:text-text data-disabled:hover:bg-transparent data-disabled:hover:text-text-muted'
+} as const;
+
+/* The dimmed look `Switch` and `Button` wear when disabled, so a select that cannot open reads as such. */
+const TRIGGER_DISABLED = 'data-disabled:cursor-default data-disabled:opacity-50';
+
+/* A description makes the row two lines high; the box keeps the icon on the label's line. */
+function Row<T extends string>({ item, picked }: { item: SelectItem<T>; picked: boolean }) {
+    return (
+        <BaseSelect.Item className={clsx('menu-item', item.description && 'items-start')} value={item.value} label={item.label} disabled={item.disabled}>
+            <MenuCheck kind="radio" checked={picked} />
+            {item.icon && <span className="flex h-lh shrink-0 items-center">{item.icon}</span>}
+            <span className="flex min-w-0 flex-col">
+                <BaseSelect.ItemText>{item.label}</BaseSelect.ItemText>
+                {item.description && <span className="text-xs text-text-faint">{item.description}</span>}
+            </span>
+        </BaseSelect.Item>
+    );
+}
+
+/* The one select. A Base UI `Select` in the popup style the menus use, so a settings field and a
+   picker in a toolbar read the same. Base UI brings the keyboard along (arrows,
+   Home and End, typeahead, Enter, Escape), which a hand-rolled listbox would have to repeat. */
+export function Select<T extends string>({
+    value,
+    onValueChange,
+    items,
+    label,
+    placeholder,
+    size = 'md',
+    variant = 'outlined',
+    disabled,
+    align = 'start',
+    truncateValue = true,
+    className,
+    ref
+}: SelectProps<T>) {
+    const { t } = useTranslation('ui');
+    const groups = items.length > 0 && isGroup(items[0]!) ? (items as SelectGroup<T>[]) : null;
+    const flat = groups ? groups.flatMap((group) => group.items) : (items as SelectItem<T>[]);
+    const selected = flat.find((item) => item.value === value) ?? null;
+
+    return (
+        <BaseSelect.Root
+            items={flat.map((item) => ({ value: item.value, label: item.label }))}
+            value={value}
+            disabled={disabled}
+            onValueChange={(next) => onValueChange(next as T)}
+        >
+            <BaseSelect.Trigger
+                ref={ref}
+                aria-label={label}
+                className={clsx(
+                    'flex shrink-0 items-center whitespace-nowrap text-xs',
+                    TRIGGER_SIZE[size],
+                    TRIGGER_VARIANT[variant],
+                    TRIGGER_DISABLED,
+                    className
+                )}
+            >
+                {selected?.icon}
+                <BaseSelect.Value className={clsx(truncateValue && 'truncate')}>{() => selected?.label ?? placeholder ?? t('action.select')}</BaseSelect.Value>
+                <BaseSelect.Icon className="ml-auto flex shrink-0 pl-1">
+                    <Icon icon={ChevronDown} size={14} />
+                </BaseSelect.Icon>
+            </BaseSelect.Trigger>
+            <BaseSelect.Portal>
+                <BaseSelect.Positioner className="popup-positioner" side="bottom" align={align} sideOffset={6} alignItemWithTrigger={false}>
+                    <BaseSelect.Popup className="menu-popup">
+                        <BaseSelect.List className="max-h-80 overflow-auto">
+                            {groups
+                                ? groups.map((group) => (
+                                      <BaseSelect.Group key={group.label}>
+                                          <BaseSelect.GroupLabel className={MENU_LABEL}>{group.label}</BaseSelect.GroupLabel>
+                                          {group.items.map((item) => (
+                                              <Row key={item.value} item={item} picked={item.value === value} />
+                                          ))}
+                                      </BaseSelect.Group>
+                                  ))
+                                : flat.map((item) => <Row key={item.value} item={item} picked={item.value === value} />)}
+                        </BaseSelect.List>
+                    </BaseSelect.Popup>
+                </BaseSelect.Positioner>
+            </BaseSelect.Portal>
+        </BaseSelect.Root>
+    );
+}

package/src/Separator.tsx

@@ -0,0 +1,15 @@
+import type { Ref } from 'react';
+import clsx from 'clsx';
+
+export interface SeparatorProps {
+    orientation?: 'vertical' | 'horizontal';
+    className?: string;
+    ref?: Ref<HTMLSpanElement>;
+}
+
+/* A hairline between two groups of controls in a toolbar-like row. It carries no margin of its own.
+   The row's gap puts 8px on either side of it, which is what makes the line read as a divider and
+   not as a group of its own. Between two groups of menu rows it is `Menu.Separator`. */
+export function Separator({ orientation = 'vertical', className, ref }: SeparatorProps) {
+    return <span ref={ref} aria-hidden className={clsx(orientation === 'vertical' ? 'h-4 w-px' : 'h-px w-full', 'shrink-0 bg-border', className)} />;
+}

package/src/ShortcutHints.tsx

@@ -0,0 +1,118 @@
+import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties } from 'react';
+import { createPortal } from 'react-dom';
+import { isApplePlatform } from './platform.ts';
+import { formatShortcut } from './shortcut.ts';
+import { ModifierHold, placeHint, shortcutHintTargets } from './shortcut-hints.ts';
+
+interface PlacedHint {
+    id: number;
+    text: string;
+    style: CSSProperties;
+}
+
+/* Whether a person can see the button now: on screen, not faded out, and not under a dialog or another node. */
+const isSeen = (element: Element, rect: DOMRect): boolean => {
+    if (rect.width === 0 || rect.height === 0 || rect.bottom <= 0 || rect.right <= 0 || rect.top >= window.innerHeight || rect.left >= window.innerWidth) {
+        return false;
+    }
+    if (!element.checkVisibility({ opacityProperty: true, visibilityProperty: true })) {
+        return false;
+    }
+    const hit = document.elementFromPoint((rect.left + rect.right) / 2, (rect.top + rect.bottom) / 2);
+    return hit !== null && element.contains(hit);
+};
+
+const measureHints = (apple: boolean): PlacedHint[] => {
+    const viewport = { width: window.innerWidth, height: window.innerHeight };
+    const hints: PlacedHint[] = [];
+    for (const [element, target] of shortcutHintTargets()) {
+        const rect = element.getBoundingClientRect();
+        if (!isSeen(element, rect)) {
+            continue;
+        }
+        const placement = placeHint(rect, viewport);
+        hints.push({
+            id: target.id,
+            text: formatShortcut(target.shortcut, apple),
+            style: { left: placement.left, right: placement.right, top: placement.top, translate: `${placement.translateX} ${placement.translateY}` }
+        });
+    }
+    return hints;
+};
+
+/*
+ * Every visible button's shortcut, under the button, for as long as the modifier is held on its own.
+ * Mounted once; the listener sits on the window in the capture phase so a terminal that keeps a key to
+ * itself still takes the hints down. An embedded page (`<webview>`) has the keyboard to itself and shows none.
+ */
+export function ShortcutHints() {
+    const [shown, setShown] = useState(false);
+    const [hints, setHints] = useState<PlacedHint[]>([]);
+    const holdRef = useRef<ModifierHold | null>(null);
+
+    useEffect(() => {
+        const hold = new ModifierHold(isApplePlatform(), setShown);
+        holdRef.current = hold;
+        const onKeyDown = (e: KeyboardEvent): void => hold.keyDown(e);
+        const onKeyUp = (e: KeyboardEvent): void => hold.keyUp(e);
+        // A click or a zoom with the modifier down is a gesture, not someone looking for a shortcut.
+        const cancel = (): void => hold.cancel();
+        window.addEventListener('keydown', onKeyDown, true);
+        window.addEventListener('keyup', onKeyUp, true);
+        window.addEventListener('pointerdown', cancel, true);
+        window.addEventListener('wheel', cancel, { capture: true, passive: true });
+        window.addEventListener('blur', cancel);
+        return () => {
+            window.removeEventListener('keydown', onKeyDown, true);
+            window.removeEventListener('keyup', onKeyUp, true);
+            window.removeEventListener('pointerdown', cancel, true);
+            window.removeEventListener('wheel', cancel, true);
+            window.removeEventListener('blur', cancel);
+            hold.cancel();
+        };
+    }, []);
+
+    // Measured before paint and then every frame, so a hint never shows where its button was.
+    useLayoutEffect(() => {
+        if (!shown) {
+            return;
+        }
+        const apple = isApplePlatform();
+        let frame = 0;
+        let last = '';
+        const measure = (): void => {
+            // Focus that moved into a page takes the key-up with it, so the embedder never hears the modifier let go.
+            if (document.activeElement?.tagName === 'WEBVIEW') {
+                holdRef.current?.cancel();
+                return;
+            }
+            const next = measureHints(apple);
+            const signature = JSON.stringify(next);
+            if (signature !== last) {
+                last = signature;
+                setHints(next);
+            }
+            frame = requestAnimationFrame(measure);
+        };
+        measure();
+        return () => cancelAnimationFrame(frame);
+    }, [shown]);
+
+    if (!shown) {
+        return null;
+    }
+    return createPortal(
+        <div aria-hidden className="pointer-events-none fixed inset-0 z-(--z-shortcut-hints)">
+            {hints.map((hint) => (
+                <kbd
+                    key={hint.id}
+                    className="absolute rounded-md bg-text px-1.5 font-sans text-xs/tight font-medium whitespace-nowrap text-surface shadow-float"
+                    style={hint.style}
+                >
+                    {hint.text}
+                </kbd>
+            ))}
+        </div>,
+        document.body
+    );
+}

package/src/Skeleton.tsx

@@ -0,0 +1,13 @@
+import type { Ref } from 'react';
+import clsx from 'clsx';
+
+export interface SkeletonProps {
+    /* The width, and a height other than the one line of 16px. */
+    className?: string;
+    ref?: Ref<HTMLSpanElement>;
+}
+
+/* A bar where a value will be, while the answer is still on its way. */
+export function Skeleton({ className, ref }: SkeletonProps) {
+    return <span ref={ref} className={clsx('block h-4 animate-pulse rounded bg-surface-sunken', className)} aria-hidden />;
+}

package/src/SlidingColumn.tsx

@@ -0,0 +1,91 @@
+import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent, type ReactNode, type Ref, type RefObject } from 'react';
+import clsx from 'clsx';
+import { ColumnResizeHandle } from './ColumnResizeHandle.tsx';
+import { mergeRefs } from './merge-refs.ts';
+import { useColumnResize } from './useColumnResize.ts';
+
+// How long the open and close motion takes; the same number as `.sliding-column` in `theme.css`.
+const TRANSITION_MS = 200;
+
+export interface SlidingColumnProps {
+    open: boolean;
+    /* Already clamped by the caller, which knows what has to stay beside it (`clampColumnSize`). */
+    width: number;
+    bounds: { min: number; max(): number };
+    onWidthChange(width: number): void;
+    /*
+     * The width lands without the motion, for a column whose place is being restored as the page
+     * loads; only what a person does afterwards should animate.
+     */
+    instant?: boolean;
+    /*
+     * The column takes the keyboard itself, for a panel with shortcuts of its own. It is focusable
+     * by script alone, so opening something in it hands it the keys without a click first.
+     */
+    body?: {
+        ref: RefObject<HTMLDivElement | null>;
+        onKeyDown(event: ReactKeyboardEvent<HTMLDivElement>): void;
+    };
+    className?: string;
+    /* The outer column, for bounds that measure what is beside it rather than the whole window. */
+    ref?: Ref<HTMLElement>;
+    children?: ReactNode;
+}
+
+/*
+ * A panel that slides in and out along the right edge. The outer column is 0 wide and inert while
+ * closed; the contents sit in an inner column of the stored width, so they do not reflow while it
+ * moves, and they stay mounted until the slide is over, so a close plays out. The left edge is the
+ * drag handle.
+ */
+export function SlidingColumn({ open, width, bounds, onWidthChange, instant = false, body, className, ref, children }: SlidingColumnProps) {
+    /* Closed and done animating. Until then the contents stay mounted, so a close plays out. */
+    const [settled, setSettled] = useState(!open);
+    /* A width that lands without a transition fires no `transitionend`, so the motion it would have
+       ended is over in the same commit that starts it. */
+    if (instant && settled !== !open) {
+        setSettled(!open);
+    }
+    const present = open || !settled;
+    const column = useRef<HTMLElement>(null);
+    const { startResize } = useColumnResize(column, { ...bounds, size: width, from: 'right', onSize: onWidthChange });
+
+    useEffect(() => {
+        if (open || settled) {
+            return;
+        }
+        // Reduced motion and a hidden tab paint no width change, so no `transitionend` arrives.
+        const timer = window.setTimeout(() => setSettled(true), TRANSITION_MS + 50);
+        return () => {
+            window.clearTimeout(timer);
+        };
+    }, [open, settled]);
+
+    return (
+        <aside
+            ref={mergeRefs(column, ref)}
+            inert={!open}
+            data-instant={instant ? '' : undefined}
+            className={clsx('sliding-column flex h-full shrink-0 justify-end overflow-hidden', className)}
+            style={{ width: open ? width : 0 }}
+            onTransitionEnd={(event) => {
+                if (event.propertyName === 'width' && event.target === event.currentTarget) {
+                    setSettled(!open);
+                }
+            }}
+        >
+            {present && (
+                <div
+                    ref={body?.ref}
+                    tabIndex={body ? -1 : undefined}
+                    className="relative flex h-full shrink-0 flex-col border-l border-border bg-surface outline-none"
+                    style={{ width }}
+                    onKeyDown={body?.onKeyDown}
+                >
+                    {open && <ColumnResizeHandle from="right" onPointerDown={startResize} />}
+                    {children}
+                </div>
+            )}
+        </aside>
+    );
+}

package/src/Spinner.tsx

@@ -0,0 +1,32 @@
+import type { ComponentProps, CSSProperties } from 'react';
+import clsx from 'clsx';
+
+const DOTS = [0, 1, 2];
+
+export interface SpinnerProps extends Omit<ComponentProps<'span'>, 'children'> {
+    /* In pixels, on the steps of an icon: 12, 14, 16 or 20. */
+    size?: number;
+    /* What runs, read by a screen reader. Left out where the words beside it already say so, which hides the spinner as an icon is hidden. */
+    label?: string;
+}
+
+/* Work in progress: three dots that leap over each other in the color of the text around them. With reduced motion they stand still. */
+export function Spinner({ size = 16, label, className, style, ref, ...props }: SpinnerProps) {
+    return (
+        <span
+            ref={ref}
+            role={label === undefined ? undefined : 'img'}
+            aria-label={label}
+            aria-hidden={label === undefined ? true : undefined}
+            {...props}
+            className={clsx('spinner', className)}
+            style={{ ...style, '--spinner-size': `${size}px` } as CSSProperties}
+        >
+            {DOTS.map((dot) => (
+                <span key={dot} className="spinner-hop" style={{ '--spinner-step': dot } as CSSProperties}>
+                    <span className="spinner-dot" />
+                </span>
+            ))}
+        </span>
+    );
+}

package/src/Stepper.tsx

@@ -0,0 +1,67 @@
+import type { Ref } from 'react';
+import clsx from 'clsx';
+import { Minus, Plus } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { ButtonGroup } from './ButtonGroup.tsx';
+import { formatFixed } from './format/number.ts';
+import { IconButton } from './IconButton.tsx';
+
+export interface StepperProps {
+    value: number;
+    onValueChange(value: number): void;
+    min: number;
+    max: number;
+    step: number;
+    /* Places after the separator, always shown: `1,0`, `1,5`. Defaults to the places `step` is written with. */
+    decimals?: number;
+    /* Printed right after the number, such as `px` or `%`. */
+    unit?: string;
+    label: string;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+
+const placesOf = (step: number): number => String(step).split('.')[1]?.length ?? 0;
+
+/* A number between minus and plus, in one sunken group so the three read as a single control. */
+export function Stepper({ value, onValueChange, min, max, step, decimals = placesOf(step), unit, label, className, ref }: StepperProps) {
+    const { t } = useTranslation('ui');
+    const reading = (amount: number) => (
+        <>
+            {formatFixed(amount, decimals)}
+            {unit && <span className="text-text-muted">{unit}</span>}
+        </>
+    );
+    const nudge = (direction: -1 | 1): void => {
+        const next = Math.round((value + direction * step) * 100) / 100;
+        onValueChange(Math.min(max, Math.max(min, next)));
+    };
+    return (
+        <ButtonGroup ref={ref} className={clsx('shrink-0 rounded-lg bg-surface-sunken p-0.5', className)} role="group" aria-label={label}>
+            <IconButton
+                icon={Minus}
+                size="sm"
+                label={t('controls.stepper.smallerFor', { label })}
+                tooltip={t('controls.stepper.smaller')}
+                disabled={value <= min}
+                onClick={() => nudge(-1)}
+            />
+            {/* The ends sit invisible in the same cell, so the widest of them sets the width and a step never moves the buttons. */}
+            <span className="grid min-w-10 px-1 text-center text-xs text-text tabular-nums">
+                <span className="invisible col-start-1 row-start-1">{reading(min)}</span>
+                <span className="invisible col-start-1 row-start-1">{reading(max)}</span>
+                <span className="col-start-1 row-start-1" aria-live="polite">
+                    {reading(value)}
+                </span>
+            </span>
+            <IconButton
+                icon={Plus}
+                size="sm"
+                label={t('controls.stepper.largerFor', { label })}
+                tooltip={t('controls.stepper.larger')}
+                disabled={value >= max}
+                onClick={() => nudge(1)}
+            />
+        </ButtonGroup>
+    );
+}

package/src/Surface.tsx

@@ -0,0 +1,20 @@
+import clsx from 'clsx';
+import { useRender } from '@base-ui-components/react/use-render';
+
+const FLOAT = 'border border-border bg-[color-mix(in_srgb,var(--surface-raised)_88%,transparent)] shadow-float backdrop-blur-[14px]';
+
+export type SurfaceProps = useRender.ComponentProps<'div'>;
+
+/*
+ * The glass card that floats over the content under it: a dock, a banner, a toast, a find bar, a
+ * chip over a scrolling thread. It brings the ground, the border and the shadow; the caller brings
+ * the shape (radius, padding, height) and the position.
+ */
+export function Surface({ render, className, ref, ...props }: SurfaceProps) {
+    return useRender({
+        render,
+        ref,
+        defaultTagName: 'div',
+        props: { ...props, className: clsx(FLOAT, className) }
+    });
+}

package/src/Switch.tsx

@@ -0,0 +1,32 @@
+import type { Ref } from 'react';
+import clsx from 'clsx';
+import { Switch as BaseSwitch } from '@base-ui-components/react/switch';
+
+export interface SwitchProps {
+    checked: boolean;
+    onCheckedChange(checked: boolean): void;
+    /* The accessible name; the row it sits in usually carries the visible one. */
+    label: string;
+    disabled?: boolean;
+    className?: string;
+    ref?: Ref<HTMLButtonElement>;
+}
+
+/* On or off, as a switch rather than a checkbox: a setting that takes effect the moment it flips. */
+export function Switch({ checked, onCheckedChange, label, disabled, className, ref }: SwitchProps) {
+    return (
+        <BaseSwitch.Root
+            ref={ref}
+            checked={checked}
+            onCheckedChange={(next) => onCheckedChange(next)}
+            aria-label={label}
+            disabled={disabled}
+            className={clsx(
+                'relative h-5 w-9 shrink-0 rounded-full bg-border-strong p-0.5 transition-colors data-checked:bg-accent data-disabled:opacity-50',
+                className
+            )}
+        >
+            <BaseSwitch.Thumb className="block h-4 w-4 rounded-full bg-surface-raised shadow-raised transition-transform data-checked:translate-x-4" />
+        </BaseSwitch.Root>
+    );
+}

package/src/TextMenu.tsx

@@ -0,0 +1,59 @@
+import { useRef, useState, type ComponentProps, type KeyboardEvent as ReactKeyboardEvent, type ReactNode } from 'react';
+import { Copy, Scan } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { copyText } from './clipboard.ts';
+import { Icon } from './Icon.tsx';
+import { Kbd } from './Kbd.tsx';
+import { mergeRefs } from './merge-refs.ts';
+import { ContextMenuRoot, ContextMenuTrigger, MenuItem, MenuPopup, MenuSeparator } from './menu/parts.tsx';
+import { isApplePlatform } from './platform.ts';
+import { selectAllWithin, selectionWithin } from './selection.ts';
+import { EDIT_SHORTCUTS, matchesShortcut } from './shortcut.ts';
+
+export type TextMenuProps = ComponentProps<'div'> & {
+    /* What the surface itself can be asked, under a line of their own: `ContextMenu.Item`s. */
+    items?: ReactNode;
+};
+
+/*
+ * A block of text and the menu that belongs to it: Copy for what is selected inside it, Select all
+ * for the whole of it, on Cmd+A as well. Anywhere text can be selected a right-click has to offer
+ * to copy it, and an app that draws every menu itself offers nothing at all without one of these.
+ */
+export function TextMenu({ children, items, ref, ...rest }: TextMenuProps) {
+    const { t } = useTranslation('ui');
+    const host = useRef<HTMLDivElement>(null);
+    // Read when the menu opens: a selection made after that is not the one the click was about.
+    const [selection, setSelection] = useState('');
+
+    const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>): void => {
+        if (!matchesShortcut(EDIT_SHORTCUTS.selectAll, event, isApplePlatform())) {
+            return;
+        }
+        event.preventDefault();
+        selectAllWithin(host.current);
+    };
+
+    return (
+        <ContextMenuRoot onOpenChange={(open) => setSelection(open ? selectionWithin(host.current) : '')}>
+            <ContextMenuTrigger {...rest} ref={mergeRefs(host, ref)} onKeyDown={onKeyDown}>
+                {children}
+            </ContextMenuTrigger>
+            <MenuPopup>
+                <MenuItem disabled={selection === ''} onClick={() => copyText(selection)}>
+                    <Icon icon={Copy} size={14} /> {t('action.copy')} <Kbd shortcut={EDIT_SHORTCUTS.copy} />
+                </MenuItem>
+                <MenuSeparator />
+                <MenuItem onClick={() => selectAllWithin(host.current)}>
+                    <Icon icon={Scan} size={14} /> {t('action.selectAll')} <Kbd shortcut={EDIT_SHORTCUTS.selectAll} />
+                </MenuItem>
+                {items !== undefined && (
+                    <>
+                        <MenuSeparator />
+                        {items}
+                    </>
+                )}
+            </MenuPopup>
+        </ContextMenuRoot>
+    );
+}

package/src/Tile.tsx

@@ -0,0 +1,49 @@
+import type { ComponentProps, ReactNode } from 'react';
+import clsx from 'clsx';
+import { Kbd } from './Kbd.tsx';
+import type { Shortcut } from './shortcut.ts';
+
+export interface TileProps extends Omit<ComponentProps<'button'>, 'title'> {
+    icon: ReactNode;
+    title: string;
+    /* One short line under the title: where it acts, or why it waits. */
+    description?: ReactNode;
+    shortcut?: Shortcut;
+    /* The one tile a screen leads with. */
+    primary?: boolean;
+    /* `sm` for a narrow column like the sidebar. */
+    size?: 'md' | 'sm';
+}
+
+/*
+ * One thing to start with, as a card that is a button: a start screen and the empty places of an app
+ * use it, so a place to begin looks the same wherever it is offered.
+ */
+export function Tile({ icon, title, description, shortcut, primary = false, size = 'md', className, type = 'button', ...rest }: TileProps) {
+    return (
+        <button
+            type={type}
+            className={clsx(
+                'flex min-w-0 items-center border bg-surface text-left hover:bg-surface-hover disabled:opacity-50 disabled:hover:bg-surface',
+                size === 'md' ? 'gap-3 rounded-xl p-3' : 'gap-2 rounded-lg px-2 py-1.5',
+                primary ? 'border-accent' : 'border-border',
+                className
+            )}
+            {...rest}
+        >
+            <span
+                className={clsx(
+                    'grid size-8 shrink-0 place-items-center rounded-lg',
+                    primary ? 'bg-accent text-accent-text' : 'bg-surface-sunken text-text-muted'
+                )}
+            >
+                {icon}
+            </span>
+            <span className="flex min-w-0 grow flex-col">
+                <span className="truncate text-sm font-medium text-text">{title}</span>
+                {description && <span className="truncate text-xs text-text-muted">{description}</span>}
+            </span>
+            {shortcut && <Kbd shortcut={shortcut} variant="inline" className="shrink-0" />}
+        </button>
+    );
+}