@fungi.computer/caps 0.0.0-stage → 0.0.1

package/dist/components/hold-button.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useRef, } from "react";
+import { cn } from "../lib/cn.js";
+import { canAnimate, motionEasing, readMotion } from "../lib/motion.js";
+import { Button } from "./button.js";
+import { VisuallyHidden } from "./visually-hidden.js";
+const confirmKeys = new Set(["Enter", " "]);
+/**
+ * For an action nothing can undo: press and hold (pointer, Space or Enter)
+ * while a fill rises; let go early and it drops back; hold to the top and the
+ * action runs. Under reduced motion the fill rises in three steps.
+ */
+export const HoldButton = forwardRef(function HoldButton({ children, onConfirm, holdMs = 900, holdHint = "Press and hold to confirm.", className, disabled, loading = false, result, resultLabel, onBlur, onKeyDown, onKeyUp, onPointerDown, onPointerUp, onPointerLeave, onPointerCancel, ...props }, ref) {
+    const fill = useRef(null);
+    const rising = useRef(null);
+    const timer = useRef(null);
+    const confirm = useRef(onConfirm);
+    const hint = useId();
+    useEffect(() => {
+        confirm.current = onConfirm;
+    }, [onConfirm]);
+    useEffect(() => () => {
+        rising.current?.cancel();
+        if (timer.current !== null)
+            clearTimeout(timer.current);
+    }, []);
+    const finish = () => {
+        rising.current = null;
+        timer.current = null;
+        confirm.current();
+        const element = fill.current;
+        if (!element || !canAnimate(element))
+            return;
+        const motion = readMotion(element);
+        element.animate([{ opacity: 1 }, { opacity: 0 }], {
+            duration: motion.normal,
+            easing: motionEasing(motion, motion.easeExit),
+        });
+    };
+    const start = () => {
+        const element = fill.current;
+        if (disabled === true ||
+            loading ||
+            !element ||
+            rising.current ||
+            timer.current)
+            return;
+        if (!canAnimate(element)) {
+            timer.current = setTimeout(finish, holdMs);
+            return;
+        }
+        const motion = readMotion(element);
+        const animation = element.animate([{ transform: "scaleY(0)" }, { transform: "scaleY(1)" }], {
+            duration: holdMs,
+            easing: motion.reduced
+                ? "steps(3, end)"
+                : motionEasing(motion, "cubic-bezier(0.3, 0, 0.7, 1)"),
+        });
+        animation.addEventListener("finish", finish);
+        rising.current = animation;
+    };
+    const release = () => {
+        if (timer.current !== null) {
+            clearTimeout(timer.current);
+            timer.current = null;
+        }
+        const animation = rising.current;
+        const element = fill.current;
+        if (!animation || !element)
+            return;
+        rising.current = null;
+        // Drop back from wherever the fill had reached.
+        const reached = getComputedStyle(element).transform;
+        animation.cancel();
+        const motion = readMotion(element);
+        element.animate([
+            { transform: reached === "none" ? "scaleY(0)" : reached },
+            { transform: "scaleY(0)" },
+        ], { duration: motion.fast, easing: motionEasing(motion, motion.ease) });
+    };
+    return (_jsxs(_Fragment, { children: [_jsxs(Button, { ...props, ref: ref, disabled: disabled, loading: loading, result: result, 
+                // Only the label repeats on the result face; the hold fill owns one ref.
+                resultLabel: resultLabel ?? (result === undefined ? undefined : children), "aria-describedby": hint, className: cn("caps-hold-button", className), onBlur: (event) => {
+                    release();
+                    onBlur?.(event);
+                }, onPointerDown: (event) => {
+                    onPointerDown?.(event);
+                    if (event.button === 0)
+                        start();
+                }, onPointerUp: (event) => {
+                    onPointerUp?.(event);
+                    release();
+                }, onPointerLeave: (event) => {
+                    onPointerLeave?.(event);
+                    release();
+                }, onPointerCancel: (event) => {
+                    onPointerCancel?.(event);
+                    release();
+                }, onKeyDown: (event) => {
+                    onKeyDown?.(event);
+                    if (event.key === "Escape")
+                        release();
+                    if (!confirmKeys.has(event.key))
+                        return;
+                    event.preventDefault();
+                    if (!event.repeat)
+                        start();
+                }, onKeyUp: (event) => {
+                    onKeyUp?.(event);
+                    if (!confirmKeys.has(event.key))
+                        return;
+                    event.preventDefault();
+                    release();
+                }, children: [_jsx("span", { ref: fill, "aria-hidden": "true", className: "caps-hold-fill" }), children] }), _jsx(VisuallyHidden, { id: hint, children: holdHint })] }));
+});

package/dist/components/icon-button.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from "react";
+import { type ButtonProps } from "./button.js";
+/** Supported IconButton glyph sizes. */
+export type IconButtonIconSize = "xs" | "sm" | "md" | "lg";
+/** Props accepted by IconButton. */
+export type IconButtonProps = {
+    "aria-label": string;
+    active?: boolean;
+    icon: ReactNode;
+    iconSize?: IconButtonIconSize;
+    reveal?: boolean;
+    size?: ButtonProps["size"] | "responsive";
+    tone?: "default" | "destructive";
+} & Omit<ButtonProps, "children" | "size">;
+/** A compact button for an icon control with an accessible name supplied by the caller. */
+export declare const IconButton: import("react").ForwardRefExoticComponent<{
+    "aria-label": string;
+    active?: boolean;
+    icon: ReactNode;
+    iconSize?: IconButtonIconSize;
+    reveal?: boolean;
+    size?: ButtonProps["size"] | "responsive";
+    tone?: "default" | "destructive";
+} & Omit<ButtonProps, "children" | "size"> & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/icon-button.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "./button.js";
+const iconSizeClasses = {
+    xs: "size-3",
+    sm: "size-[var(--stipe-icon-size-sm)]",
+    md: "size-[var(--stipe-icon-size-md)]",
+    lg: "size-[var(--stipe-icon-size-lg)]",
+};
+/** A compact button for an icon control with an accessible name supplied by the caller. */
+export const IconButton = forwardRef(function IconButton({ active = false, icon, iconSize = "xs", className, reveal = false, size = "xs", tone = "default", variant = "ghost", ...props }, ref) {
+    const responsive = size === "responsive";
+    return (_jsx(Button, { ...props, 
+        // A result beat on an icon shows the check alone.
+        resultLabel: props.result === undefined ? undefined : null, ref: ref, size: responsive ? "sm" : size, variant: variant, className: cn("caps-icon-button btn-circle", responsive && "caps-icon-button-responsive md:btn-xs", active && "text-accent", reveal &&
+            "scale-0 transition-transform group-hover:scale-100 focus-visible:scale-100", tone === "destructive" && "hover:text-error", className), children: _jsx("span", { "aria-hidden": "true", className: cn("inline-flex shrink-0 [&>svg]:size-full [&>svg]:[stroke-width:var(--stipe-icon-stroke)]", iconSizeClasses[iconSize]), children: icon }) }));
+});

package/dist/components/icon-checkbox.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+import { type CheckboxProps } from "./checkbox.js";
+/** Props accepted by IconCheckbox. The full label names the native input. */
+export type IconCheckboxProps = {
+    label: string;
+    icon: ReactNode;
+    /** A short visible legend; it does not replace the accessible label. */
+    caption?: string;
+    /** Compact instruments show the icon and caption without a tile or lamp. */
+    appearance?: "default" | "compact";
+} & Omit<CheckboxProps, "children" | "indicator">;
+/** An independent icon choice composed from the native Caps Checkbox. */
+export declare const IconCheckbox: import("react").ForwardRefExoticComponent<{
+    label: string;
+    icon: ReactNode;
+    /** A short visible legend; it does not replace the accessible label. */
+    caption?: string;
+    /** Compact instruments show the icon and caption without a tile or lamp. */
+    appearance?: "default" | "compact";
+} & Omit<CheckboxProps, "children" | "indicator"> & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/icon-checkbox.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { cn } from "../lib/cn.js";
+import { Checkbox } from "./checkbox.js";
+import { IconChoiceMark } from "./icon-choice-mark.js";
+/** An independent icon choice composed from the native Caps Checkbox. */
+export const IconCheckbox = forwardRef(function IconCheckbox({ label, icon, caption, appearance, className, ...props }, ref) {
+    return (_jsx("label", { className: "caps-icon-choice", "data-appearance": appearance === "compact" ? appearance : undefined, children: _jsx(Checkbox, { ...props, appearance: appearance ?? "default", "aria-label": label, className: cn("caps-icon-choice-input", className), indicator: _jsx(IconChoiceMark, { icon: icon, caption: caption }), ref: ref }) }));
+});

package/dist/components/icon-choice-mark.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react";
+/** The decorative face shared by icon choices; its native input names it. */
+export declare function IconChoiceMark({ icon, caption, }: {
+    icon: ReactNode;
+    caption?: string | undefined;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/icon-choice-mark.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The decorative face shared by icon choices; its native input names it. */
+export function IconChoiceMark({ icon, caption, }) {
+    return (_jsxs("span", { className: "caps-icon-choice-mark", "aria-hidden": "true", children: [_jsx("span", { className: "caps-icon-choice-art", children: icon }), caption ? (_jsx("span", { className: "caps-icon-choice-caption", children: caption })) : null, _jsx("span", { className: "caps-icon-choice-lamp" })] }));
+}

package/dist/components/icon-lamp.d.ts

@@ -0,0 +1,42 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+/** Props accepted by IconLamp. */
+export type IconLampProps = {
+    /** The full name read with the state, such as "Read files". */
+    label: string;
+    icon: ReactNode;
+    /** A short visible legend; it does not replace the accessible label. */
+    caption?: string;
+    /** Lit: the icon in colour with the ink lamp. Off: the grey silhouette. */
+    on: boolean;
+    /** How the state reads aloud, as [on, off]. */
+    stateLabels?: readonly [string, string];
+} & Omit<HTMLAttributes<HTMLElement>, "children">;
+/**
+ * A read-only icon state: an icon key's face with no input, for rights or
+ * settings shown but not changed here. It reads as "Label: state".
+ */
+export declare const IconLamp: import("react").ForwardRefExoticComponent<{
+    /** The full name read with the state, such as "Read files". */
+    label: string;
+    icon: ReactNode;
+    /** A short visible legend; it does not replace the accessible label. */
+    caption?: string;
+    /** Lit: the icon in colour with the ink lamp. Off: the grey silhouette. */
+    on: boolean;
+    /** How the state reads aloud, as [on, off]. */
+    stateLabels?: readonly [string, string];
+} & Omit<HTMLAttributes<HTMLElement>, "children"> & import("react").RefAttributes<HTMLElement>>;
+/** One lamp in an IconLamps row. */
+export type IconLampItem = Omit<IconLampProps, "stateLabels"> & {
+    id: string;
+};
+/** Props accepted by IconLamps. */
+export type IconLampsProps = {
+    items: readonly IconLampItem[];
+    stateLabels?: readonly [string, string];
+} & Omit<HTMLAttributes<HTMLUListElement>, "children">;
+/** A named row of read-only icon lamps; name it with `aria-label(ledby)`. */
+export declare const IconLamps: import("react").ForwardRefExoticComponent<{
+    items: readonly IconLampItem[];
+    stateLabels?: readonly [string, string];
+} & Omit<HTMLAttributes<HTMLUListElement>, "children"> & import("react").RefAttributes<HTMLUListElement>>;

package/dist/components/icon-lamp.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { cn } from "../lib/cn.js";
+import { IconChoiceMark } from "./icon-choice-mark.js";
+/**
+ * A read-only icon state: an icon key's face with no input, for rights or
+ * settings shown but not changed here. It reads as "Label: state".
+ */
+export const IconLamp = forwardRef(function IconLamp({ label, icon, caption, on, stateLabels = ["on", "off"], className, ...props }, ref) {
+    return (_jsxs("span", { ...props, className: cn("caps-icon-lamp", className), "data-on": on, ref: ref, children: [_jsx(IconChoiceMark, { icon: icon, caption: caption }), _jsxs("span", { className: "sr-only", children: [label, ": ", on ? stateLabels[0] : stateLabels[1]] })] }));
+});
+/** A named row of read-only icon lamps; name it with `aria-label(ledby)`. */
+export const IconLamps = forwardRef(function IconLamps({ items, stateLabels, className, ...props }, ref) {
+    return (_jsx("ul", { ...props, className: cn("caps-icon-lamps", className), ref: ref, children: items.map(({ id, ...item }) => (_jsx("li", { children: _jsx(IconLamp, { ...item, ...(stateLabels === undefined ? {} : { stateLabels }) }) }, id))) }));
+});

package/dist/components/icon-radio.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+import { type RadioGroupItemProps } from "./radio-group.js";
+/** Props accepted by IconRadio. Use it inside the existing RadioGroup. */
+export type IconRadioProps = {
+    label: string;
+    icon: ReactNode;
+    /** A short visible legend; it does not replace the accessible label. */
+    caption?: string;
+} & Omit<RadioGroupItemProps, "children" | "indicator">;
+/** One icon choice in a native, mutually exclusive Caps RadioGroup. */
+export declare const IconRadio: import("react").ForwardRefExoticComponent<{
+    label: string;
+    icon: ReactNode;
+    /** A short visible legend; it does not replace the accessible label. */
+    caption?: string;
+} & Omit<RadioGroupItemProps, "children" | "indicator"> & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/icon-radio.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { cn } from "../lib/cn.js";
+import { RadioGroupItem } from "./radio-group.js";
+import { IconChoiceMark } from "./icon-choice-mark.js";
+/** One icon choice in a native, mutually exclusive Caps RadioGroup. */
+export const IconRadio = forwardRef(function IconRadio({ label, icon, caption, className, ...props }, ref) {
+    return (_jsx("label", { className: "caps-icon-choice", children: _jsx(RadioGroupItem, { ...props, "aria-label": label, className: cn("caps-icon-choice-input", className), indicator: _jsx(IconChoiceMark, { icon: icon, caption: caption }), ref: ref }) }));
+});

package/dist/components/inline-code.d.ts

@@ -0,0 +1,3 @@
+import { type HTMLAttributes } from "react";
+/** A subdued inline code value for identifiers and other technical labels. */
+export declare const InlineCode: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & import("react").RefAttributes<HTMLElement>>;

package/dist/components/inline-code.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { cn } from "../lib/cn.js";
+/** A subdued inline code value for identifiers and other technical labels. */
+export const InlineCode = forwardRef(function InlineCode({ className, ...props }, ref) {
+    return (_jsx("code", { ...props, className: cn("caps-inline-code", className), ref: ref }));
+});

package/dist/components/input-group.d.ts

@@ -0,0 +1,9 @@
+import { type HTMLAttributes } from "react";
+/** Props accepted by InputGroup. */
+export type InputGroupProps = HTMLAttributes<HTMLDivElement>;
+/** Join a control with caller-owned prefixes, suffixes, or actions. */
+export declare const InputGroup: import("react").ForwardRefExoticComponent<InputGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+/** Props accepted by InputGroupAddon. */
+export type InputGroupAddonProps = HTMLAttributes<HTMLDivElement>;
+/** An addon region for an InputGroup. */
+export declare const InputGroupAddon: import("react").ForwardRefExoticComponent<InputGroupAddonProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/input-group.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, cloneElement, forwardRef, isValidElement, } from "react";
+import { cn } from "../lib/cn.js";
+/** Join a control with caller-owned prefixes, suffixes, or actions. */
+export const InputGroup = forwardRef(function InputGroup({ children, className, ...props }, ref) {
+    return (_jsx("div", { ...props, className: cn("caps-input-group join flex w-full items-stretch [&>*]:join-item [&>*:first-child]:rounded-e-none [&>*:last-child]:rounded-s-none [&>*:not(:first-child):not(:last-child)]:rounded-none [&>.btn]:shrink-0 [&>.input]:min-w-0 [&>.input]:flex-1 [&>.select]:min-w-0 [&>.select]:flex-1", className), ref: ref, children: Children.map(children, (child) => isValidElement(child)
+            ? cloneElement(child, {
+                className: cn("join-item caps-input-group-control", child.props.className),
+            })
+            : child) }));
+});
+/** An addon region for an InputGroup. */
+export const InputGroupAddon = forwardRef(function InputGroupAddon({ className, ...props }, ref) {
+    return (_jsx("div", { ...props, className: cn("join-item flex items-center border border-base-300 bg-base-200 px-md text-sm text-base-content", className), ref: ref }));
+});

package/dist/components/input.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode, type InputHTMLAttributes } from "react";
+/** Props accepted by Input. */
+export type InputProps = {
+    invalid?: boolean;
+} & InputHTMLAttributes<HTMLInputElement>;
+/** A styled native text input that preserves caller-owned value and event behavior. */
+export declare const Input: import("react").ForwardRefExoticComponent<{
+    invalid?: boolean;
+} & InputHTMLAttributes<HTMLInputElement> & import("react").RefAttributes<HTMLInputElement>>;
+/** A native search input with an optional decorative leading icon. */
+export declare const SearchInput: import("react").ForwardRefExoticComponent<{
+    invalid?: boolean;
+} & InputHTMLAttributes<HTMLInputElement> & {
+    leading?: ReactNode;
+} & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/input.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { cn } from "../lib/cn.js";
+/** A styled native text input that preserves caller-owned value and event behavior. */
+export const Input = forwardRef(function Input({ className, invalid, ...props }, ref) {
+    return (_jsx("input", { ...props, "aria-invalid": invalid
+            ? true
+            : props["aria-invalid"] === false
+                ? undefined
+                : props["aria-invalid"], className: cn("input caps-input w-full", className), ref: ref }));
+});
+/** A native search input with an optional decorative leading icon. */
+export const SearchInput = forwardRef(function SearchInput({ leading, className, ...props }, ref) {
+    return (_jsxs("span", { className: "caps-search-input", "data-leading": leading ? "true" : undefined, children: [leading ? (_jsx("span", { className: "caps-search-leading", "aria-hidden": "true", children: leading })) : null, _jsx(Input, { ...props, type: "search", className: className, ref: ref })] }));
+});

package/dist/components/item-grid.d.ts

@@ -0,0 +1,110 @@
+import { type ButtonHTMLAttributes, type HTMLAttributes, type ReactNode } from "react";
+/** One item placed on the grid. Coordinates are cells from the top left. */
+export type ItemGridItem = {
+    id: string;
+    /** Accessible name, e.g. "Axe" or "Bread". */
+    label: string;
+    x: number;
+    y: number;
+    /** Footprint width in cells after rotation. Defaults to 1. */
+    w?: number;
+    /** Footprint height in cells after rotation. Defaults to 1. */
+    h?: number;
+    /** Decorative art: a sprite, an image or an SVG. */
+    icon?: ReactNode;
+    /** Stack count, drawn in pixel numerals when above 1. */
+    quantity?: number;
+    selected?: boolean;
+};
+/** A drop preview: where the held item would land, and whether it may. */
+export type ItemGridGhost = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    legal: boolean;
+    /** Why an illegal drop is refused, in the host's words. */
+    reason?: string;
+};
+/** A grid cell, with the item covering it if any. */
+export type ItemGridCell = {
+    x: number;
+    y: number;
+    item: ItemGridItem | null;
+};
+/** Cell sizes: pockets, a backpack and a big chest view. */
+export type ItemGridCellSize = "sm" | "md" | "lg";
+/** Props accepted by ItemGrid. */
+export type ItemGridProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Accessible name of the container, e.g. "Backpack". */
+    label: string;
+    columns: number;
+    rows: number;
+    items: readonly ItemGridItem[];
+    ghost?: ItemGridGhost | null;
+    cellSize?: ItemGridCellSize;
+    /** Controlled keyboard cursor. Omit to let the grid keep its own. */
+    activeCell?: {
+        x: number;
+        y: number;
+    };
+    /** The keyboard cursor moved to another cell. */
+    onActiveCellChange?: (cell: ItemGridCell) => void;
+    /** Click, Enter or Space on a cell. The host decides pick up, drop or use. */
+    onCellActivate?: (cell: ItemGridCell) => void;
+    /** Pointer over a cell, or `null` on leaving the grid; for drag ghosts. */
+    onCellHover?: (cell: ItemGridCell | null) => void;
+};
+/**
+ * A Diablo-style item grid. Cells carry the keyboard and pointer interface;
+ * items and the drop ghost are drawn above them from the host's facts. The
+ * grid never moves, merges or validates items: it shows what the host says.
+ */
+export declare const ItemGrid: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Accessible name of the container, e.g. "Backpack". */
+    label: string;
+    columns: number;
+    rows: number;
+    items: readonly ItemGridItem[];
+    ghost?: ItemGridGhost | null;
+    cellSize?: ItemGridCellSize;
+    /** Controlled keyboard cursor. Omit to let the grid keep its own. */
+    activeCell?: {
+        x: number;
+        y: number;
+    };
+    /** The keyboard cursor moved to another cell. */
+    onActiveCellChange?: (cell: ItemGridCell) => void;
+    /** Click, Enter or Space on a cell. The host decides pick up, drop or use. */
+    onCellActivate?: (cell: ItemGridCell) => void;
+    /** Pointer over a cell, or `null` on leaving the grid; for drag ghosts. */
+    onCellHover?: (cell: ItemGridCell | null) => void;
+} & import("react").RefAttributes<HTMLDivElement>>;
+/** How a slot answers the item being held over it. */
+export type ItemSlotState = "idle" | "legal" | "illegal";
+/** Props accepted by ItemSlot. */
+export type ItemSlotProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    /** Slot name, e.g. "Head" or "Main hand". */
+    label: string;
+    /** The equipped item, if any. */
+    item?: {
+        label: string;
+        icon?: ReactNode;
+    } | null;
+    /** Faint outline art shown while the slot is empty. */
+    placeholder?: ReactNode;
+    state?: ItemSlotState;
+};
+/** One equipment slot for a paper doll: a pocket, its item and its name. */
+export declare const ItemSlot: import("react").ForwardRefExoticComponent<Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    /** Slot name, e.g. "Head" or "Main hand". */
+    label: string;
+    /** The equipped item, if any. */
+    item?: {
+        label: string;
+        icon?: ReactNode;
+    } | null;
+    /** Faint outline art shown while the slot is empty. */
+    placeholder?: ReactNode;
+    state?: ItemSlotState;
+} & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/item-grid.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId, useState, } from "react";
+import { cn } from "../lib/cn.js";
+import { PixelNumber } from "./pixel-number.js";
+const MAX_CELLS = 32;
+function footprint(item) {
+    return { w: item.w ?? 1, h: item.h ?? 1 };
+}
+/** Throw on geometry the grid cannot draw; the host's data is wrong. */
+function checkGrid(columns, rows, items) {
+    for (const [name, value] of [
+        ["columns", columns],
+        ["rows", rows],
+    ])
+        if (!Number.isInteger(value) || value < 1 || value > MAX_CELLS)
+            throw new RangeError(`ItemGrid ${name} must be an integer from 1 to ${String(MAX_CELLS)}`);
+    const occupant = new Map();
+    for (const item of items) {
+        const { w, h } = footprint(item);
+        if (![item.x, item.y, w, h].every(Number.isInteger) ||
+            item.x < 0 ||
+            item.y < 0 ||
+            w < 1 ||
+            h < 1 ||
+            item.x + w > columns ||
+            item.y + h > rows)
+            throw new RangeError(`ItemGrid item ${item.id} does not fit a ${String(columns)}×${String(rows)} grid`);
+        for (let y = item.y; y < item.y + h; y++)
+            for (let x = item.x; x < item.x + w; x++)
+                occupant.set(`${String(x)},${String(y)}`, item);
+    }
+    return occupant;
+}
+/** The cell a navigation key moves to, clamped to the grid. */
+function keyMove(key, { x, y }, columns, rows) {
+    switch (key) {
+        case "ArrowLeft":
+            return [Math.max(0, x - 1), y];
+        case "ArrowRight":
+            return [Math.min(columns - 1, x + 1), y];
+        case "ArrowUp":
+            return [x, Math.max(0, y - 1)];
+        case "ArrowDown":
+            return [x, Math.min(rows - 1, y + 1)];
+        case "Home":
+            return [0, y];
+        case "End":
+            return [columns - 1, y];
+        default:
+            return null;
+    }
+}
+function area(x, y, w, h) {
+    return {
+        gridColumn: `${String(x + 1)} / span ${String(w)}`,
+        gridRow: `${String(y + 1)} / span ${String(h)}`,
+    };
+}
+function tracks(style, columns, rows) {
+    return {
+        ...style,
+        "--caps-item-grid-columns": columns,
+        "--caps-item-grid-rows": rows,
+    };
+}
+function cellName(cell, ghost) {
+    const where = `column ${String(cell.x + 1)}, row ${String(cell.y + 1)}`;
+    const inGhost = ghost &&
+        cell.x >= ghost.x &&
+        cell.x < ghost.x + ghost.w &&
+        cell.y >= ghost.y &&
+        cell.y < ghost.y + ghost.h;
+    const drop = inGhost
+        ? ghost.legal
+            ? ", drop here"
+            : `, cannot drop${ghost.reason ? `: ${ghost.reason}` : ""}`
+        : "";
+    if (!cell.item)
+        return `Empty, ${where}${drop}`;
+    const count = cell.item.quantity !== undefined && cell.item.quantity > 1
+        ? ` ×${String(cell.item.quantity)}`
+        : "";
+    return `${cell.item.label}${count}, ${where}${drop}`;
+}
+/**
+ * A Diablo-style item grid. Cells carry the keyboard and pointer interface;
+ * items and the drop ghost are drawn above them from the host's facts. The
+ * grid never moves, merges or validates items: it shows what the host says.
+ */
+export const ItemGrid = forwardRef(function ItemGrid({ label, columns, rows, items, ghost = null, cellSize = "md", activeCell, onActiveCellChange, onCellActivate, onCellHover, className, style, ...props }, ref) {
+    const occupant = checkGrid(columns, rows, items);
+    const [ownCell, setOwnCell] = useState({ x: 0, y: 0 });
+    const current = activeCell ?? ownCell;
+    const reasonId = useId();
+    const cellAt = (x, y) => ({
+        x,
+        y,
+        item: occupant.get(`${String(x)},${String(y)}`) ?? null,
+    });
+    const focusCell = (grid, x, y) => {
+        const next = cellAt(x, y);
+        if (activeCell === undefined)
+            setOwnCell({ x, y });
+        onActiveCellChange?.(next);
+        grid
+            .querySelector(`[data-cell="${String(x)},${String(y)}"]`)
+            ?.focus({ preventScroll: true });
+    };
+    const onKeyDown = (event) => {
+        const move = keyMove(event.key, current, columns, rows);
+        if (move) {
+            event.preventDefault();
+            focusCell(event.currentTarget, move[0], move[1]);
+        }
+        else if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            onCellActivate?.(cellAt(current.x, current.y));
+        }
+    };
+    const refused = ghost && !ghost.legal && ghost.reason ? ghost.reason : null;
+    return (_jsxs("div", { ...props, ref: ref, className: cn("caps-item-grid", className), "data-cell-size": cellSize, style: tracks(style, columns, rows), children: [_jsxs("div", { className: "caps-item-grid-board", children: [_jsx("div", { role: "grid", "aria-label": label, "aria-rowcount": rows, "aria-colcount": columns, "aria-describedby": refused ? reasonId : undefined, className: "caps-item-grid-cells", onKeyDown: onKeyDown, onPointerLeave: () => onCellHover?.(null), children: Array.from({ length: rows }, (_, y) => (_jsx("div", { role: "row", className: "caps-item-grid-row", children: Array.from({ length: columns }, (_, x) => {
+                                const cell = cellAt(x, y);
+                                const active = current.x === x && current.y === y;
+                                return (_jsx("div", { role: "gridcell", tabIndex: active ? 0 : -1, "aria-label": cellName(cell, ghost), "aria-selected": cell.item?.selected ?? false, "data-cell": `${String(x)},${String(y)}`, "data-occupied": cell.item !== null, className: "caps-item-grid-cell", onClick: (event) => {
+                                        focusCell(event.currentTarget.closest("[role=grid]") ?? event.currentTarget, x, y);
+                                        onCellActivate?.(cell);
+                                    }, onPointerEnter: () => onCellHover?.(cell) }, x));
+                            }) }, y))) }), _jsxs("div", { className: "caps-item-grid-items", "aria-hidden": "true", children: [items.map((item) => {
+                                const { w, h } = footprint(item);
+                                return (_jsxs("div", { className: "caps-item", "data-selected": item.selected ?? false, style: area(item.x, item.y, w, h), children: [_jsx("span", { className: "caps-item-icon", children: item.icon }), item.quantity !== undefined && item.quantity > 1 ? (_jsx(PixelNumber, { className: "caps-item-count", value: item.quantity, size: "sm" })) : null] }, item.id));
+                            }), ghost ? (_jsx("div", { className: "caps-item-ghost", "data-legal": ghost.legal, style: area(ghost.x, ghost.y, ghost.w, ghost.h) })) : null] })] }), refused ? (_jsx("p", { id: reasonId, className: "caps-item-grid-reason", role: "status", children: refused })) : null] }));
+});
+/** One equipment slot for a paper doll: a pocket, its item and its name. */
+export const ItemSlot = forwardRef(function ItemSlot({ label, item = null, placeholder, state = "idle", className, type = "button", ...props }, ref) {
+    return (_jsxs("button", { ...props, ref: ref, type: type, className: cn("caps-item-slot", className), "data-state": state, "data-filled": item !== null, "aria-label": props["aria-label"] ?? `${label}: ${item?.label ?? "empty"}`, children: [_jsx("span", { className: "caps-item-slot-pocket", "aria-hidden": "true", children: item ? (_jsx("span", { className: "caps-item-icon", children: item.icon })) : (_jsx("span", { className: "caps-item-slot-placeholder", children: placeholder })) }), _jsx("span", { className: "caps-item-slot-label", "aria-hidden": "true", children: label })] }));
+});