@fungi.computer/caps 0.0.0-stage → 0.0.1

package/dist/components/dropdown-menu.js

@@ -0,0 +1,98 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Menu as BaseMenu } from "@base-ui/react/menu";
+import * as React from "react";
+import { createContext, forwardRef, useContext, useCallback, useImperativeHandle, useRef, } from "react";
+import { cn, resolveClassName } from "../lib/cn.js";
+import { useGlide } from "../lib/glide.js";
+import { useOverlayRoot, useOverlayDismiss } from "./overlay-root.js";
+const MenuContext = createContext(null);
+/** A menu controller with explicit controlled or uncontrolled open state. */
+export function DropdownMenu({ actionsRef: suppliedActionsRef, children, interactionOwner = "local", onOpenChange, ...props }) {
+    const internalActionsRef = useRef(null);
+    const actionsRef = suppliedActionsRef ?? internalActionsRef;
+    useOverlayDismiss(() => actionsRef.current?.close());
+    return (_jsx(MenuContext.Provider, { value: { actionsRef, interactionOwner }, children: _jsx(BaseMenu.Root, { ...props, actionsRef: actionsRef, onOpenChange: (next, details) => {
+                if (interactionOwner === "host" &&
+                    !next &&
+                    details.reason === "escape-key") {
+                    details.cancel();
+                    details.allowPropagation();
+                    return;
+                }
+                onOpenChange?.(next, details);
+            }, children: children }) }));
+}
+/** Access the nearest DropdownMenu close operation. */
+export function useDropdownMenu() {
+    const menu = useMenu();
+    return {
+        /** Close the nearest menu, if it is mounted. */
+        close: () => menu.actionsRef.current?.close(),
+    };
+}
+function useMenu() {
+    const value = useContext(MenuContext);
+    if (!value)
+        throw new Error("DropdownMenu parts must be used inside <DropdownMenu>");
+    return value;
+}
+/** The trigger control for a DropdownMenu. */
+export const DropdownMenuTrigger = forwardRef(function DropdownMenuTrigger({ className, render, type = "button", ...props }, ref) {
+    return (_jsx(BaseMenu.Trigger, { ...props, className: (state) => cn("btn caps-dropdown-trigger", resolveClassName(className, state)), ref: ref, render: render, type: type }));
+});
+/** Shell popover destination, with Base UI container and mount lifetime overrides. */
+export const DropdownMenuPortal = forwardRef(function DropdownMenuPortal({ container, ...props }, ref) {
+    const root = useOverlayRoot("popover");
+    if (container == null && root === null)
+        return null;
+    return _jsx(BaseMenu.Portal, { ...props, container: container ?? root, ref: ref });
+});
+/** Base UI owns placement; a shell's popover root supplies its collision boundary. */
+export const DropdownMenuPositioner = forwardRef(function DropdownMenuPositioner({ collisionBoundary, ...props }, ref) {
+    const root = useOverlayRoot("popover");
+    return (_jsx(BaseMenu.Positioner, { ...props, collisionBoundary: collisionBoundary ?? (root && root !== document.body ? root : undefined), ref: ref }));
+});
+/** The styled popup for caller-composed menu placement and portal ownership. */
+export const DropdownMenuPopup = forwardRef(function DropdownMenuPopup({ className, finalFocus, ...props }, ref) {
+    const { interactionOwner } = useMenu();
+    const popup = useRef(null);
+    useImperativeHandle(ref, () => popup.current);
+    const glide = useGlide(".caps-dropdown-item[data-highlighted]");
+    const attach = useCallback((node) => {
+        popup.current = node;
+        glide(node);
+    }, [glide]);
+    return (_jsx(BaseMenu.Popup, { ...props, className: (state) => cn("caps-dropdown-popup min-w-40 rounded-box border border-base-300 bg-base-100 p-xs shadow-lg outline-none", resolveClassName(className, state)), finalFocus: interactionOwner === "host" ? false : (finalFocus ?? true), ref: attach }));
+});
+/** The positioned content region for a DropdownMenu. */
+export const DropdownMenuContent = forwardRef(function DropdownMenuContent({ align = "end", alignOffset, children, container, keepMounted, side = "bottom", sideOffset = 4, ...props }, ref) {
+    return (_jsx(DropdownMenuPortal, { container: container, keepMounted: keepMounted, children: _jsx(DropdownMenuPositioner, { align: align, alignOffset: alignOffset, side: side, sideOffset: sideOffset, children: _jsx(DropdownMenuPopup, { ...props, ref: ref, children: children }) }) }));
+});
+const itemClasses = "caps-dropdown-item flex w-full items-center gap-sm rounded-field px-md py-sm text-left text-sm outline-none transition-colors hover:bg-base-200 focus-visible:bg-base-200 aria-[current=page]:bg-base-200 aria-[current=page]:font-semibold disabled:cursor-not-allowed disabled:text-base-content/40 data-disabled:cursor-not-allowed data-disabled:text-base-content/40";
+/** An actionable item in a DropdownMenu. */
+export const DropdownMenuItem = forwardRef(function DropdownMenuItem({ className, onClick, onSelect, variant = "default", ...props }, ref) {
+    return (_jsx(BaseMenu.Item, { ...props, className: (state) => cn(itemClasses, variant === "destructive" &&
+            "text-error hover:bg-error hover:text-error-content focus-visible:bg-error focus-visible:text-error-content", resolveClassName(className, state)), onClick: (event) => {
+            onClick?.(event);
+            if (!event.defaultPrevented)
+                onSelect?.(event);
+        }, ref: ref }));
+});
+/** A checkable item in a DropdownMenu. */
+export const DropdownMenuCheckboxItem = forwardRef(function DropdownMenuCheckboxItem({ className, onClick, onSelect, ...props }, ref) {
+    return (_jsx(BaseMenu.CheckboxItem, { ...props, className: (state) => cn(itemClasses, resolveClassName(className, state)), onClick: (event) => {
+            onClick?.(event);
+            if (!event.defaultPrevented)
+                onSelect?.(event);
+        }, ref: ref }));
+});
+/** A visual separator in a DropdownMenu. */
+export const DropdownMenuSeparator = forwardRef(function DropdownMenuSeparator({ className, ...props }, ref) {
+    return (_jsx(BaseMenu.Separator, { ...props, className: (state) => cn("my-xs h-px bg-base-300", resolveClassName(className, state)), ref: ref }));
+});
+/** A named set of related items; pair it with a DropdownMenuLabel. */
+export const DropdownMenuGroup = BaseMenu.Group;
+/** The visible name of a DropdownMenuGroup, announced with its items. */
+export const DropdownMenuLabel = forwardRef(function DropdownMenuLabel({ className, ...props }, ref) {
+    return (_jsx(BaseMenu.GroupLabel, { ...props, className: (state) => cn("px-md pb-xs pt-sm text-xs font-semibold text-base-content/60", resolveClassName(className, state)), ref: ref }));
+});

package/dist/components/field-guide.d.ts

@@ -0,0 +1,41 @@
+import type { HTMLAttributes, ReactNode } from "react";
+/** A visible keyboard key from a shortcut or instruction. */
+export type KeycapProps = {
+    children: ReactNode;
+} & HTMLAttributes<HTMLElement>;
+/** The shared field-guide treatment for a keyboard key. */
+export declare function Keycap({ children, className, ...props }: KeycapProps): import("react/jsx-runtime").JSX.Element;
+/** Semantic accent pigments for the static status light. */
+export type StatusLedTone = "spore" | "mycelium" | "fruiting";
+/** Props accepted by StatusLed. */
+export type StatusLedProps = {
+    active: boolean;
+    label: string;
+    tone?: StatusLedTone;
+} & Omit<HTMLAttributes<HTMLSpanElement>, "children">;
+/** A static, labelled indicator using the current field-guide pigment tokens. */
+export declare function StatusLed({ active, className, label, tone, ...props }: StatusLedProps): import("react/jsx-runtime").JSX.Element;
+/** Props accepted by CartridgeLabel. */
+export type CartridgeLabelProps = {
+    title: string;
+    subtitle?: string;
+    mark?: ReactNode;
+} & HTMLAttributes<HTMLElement>;
+/** A ruled, token-backed printed label for a physical game cartridge. */
+export declare function CartridgeLabel({ className, mark, subtitle, title, ...props }: CartridgeLabelProps): import("react/jsx-runtime").JSX.Element;
+/** Props accepted by SpecimenLabel. */
+export type SpecimenLabelProps = {
+    plate: string;
+    detail: string;
+    kind: string;
+    number: string;
+    title: ReactNode;
+    summary?: ReactNode;
+    /**
+     * Mark the plate number for a pencil circle and the detail for a pencil
+     * underline. The ruled CSS marks remain until `enhance/sketch` draws them.
+     */
+    sketch?: boolean;
+} & Omit<HTMLAttributes<HTMLElement>, "title">;
+/** A caption, catalogue line, title, and note for a specimen illustration. */
+export declare function SpecimenLabel({ className, detail, kind, number, plate, sketch, summary, title, ...props }: SpecimenLabelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/field-guide.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+/** The shared field-guide treatment for a keyboard key. */
+export function Keycap({ children, className, ...props }) {
+    return (_jsx("kbd", { ...props, className: cn("caps-keycap", className), children: children }));
+}
+/** A static, labelled indicator using the current field-guide pigment tokens. */
+export function StatusLed({ active, className, label, tone = "mycelium", ...props }) {
+    return (_jsxs("span", { ...props, "aria-label": `${label}: ${active ? "on" : "off"}`, className: cn("caps-led", className), "data-active": active, "data-tone": tone, role: "img", children: [_jsx("span", { "aria-hidden": "true", className: "caps-led-bead" }), _jsx("span", { "aria-hidden": "true", children: label })] }));
+}
+/** A ruled, token-backed printed label for a physical game cartridge. */
+export function CartridgeLabel({ className, mark, subtitle, title, ...props }) {
+    return (_jsxs("figure", { ...props, "aria-label": `${title} cartridge label`, className: cn("caps-cartridge-label", className), children: [_jsx("span", { "aria-hidden": "true", className: "caps-cartridge-label-rule" }), mark ? (_jsx("span", { "aria-hidden": "true", className: "caps-cartridge-label-mark", children: mark })) : null, _jsx("span", { className: "caps-cartridge-label-title", children: title }), subtitle ? (_jsx("span", { className: "caps-cartridge-label-subtitle", children: subtitle })) : null, _jsx("span", { "aria-hidden": "true", className: "caps-cartridge-label-rule" })] }));
+}
+/** A caption, catalogue line, title, and note for a specimen illustration. */
+export function SpecimenLabel({ className, detail, kind, number, plate, sketch = false, summary, title, ...props }) {
+    return (_jsxs("aside", { ...props, className: cn("caps-specimen-label", className), children: [_jsxs("p", { className: "caps-specimen-label-caption", children: [_jsx("span", { className: "caps-specimen-label-plate", "data-sketch": sketch ? "circle" : undefined, children: plate }), _jsx("span", { className: "caps-specimen-label-detail", "data-sketch": sketch ? "underline" : undefined, children: detail })] }), _jsxs("span", { className: "caps-specimen-label-meta", children: [kind, " \u00B7 ", number] }), _jsx("div", { className: "caps-specimen-label-title", children: title }), summary ? (_jsx("p", { className: "caps-specimen-label-summary", children: summary })) : null] }));
+}

package/dist/components/field.d.ts

@@ -0,0 +1,164 @@
+import { type FieldsetHTMLAttributes, type FormHTMLAttributes, type HTMLAttributes, type InputHTMLAttributes, type ReactNode } from "react";
+/** An announced error that takes no space when absent and collapses smoothly. */
+export declare function FieldError({ children, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+/** Props accepted by FormFooter. */
+export type FormFooterProps = {
+    /** The submit-time error, announced above the actions. */
+    error?: ReactNode;
+    /** `end` right-aligns actions; `stretch` stacks full-width actions for single-column cards. */
+    layout?: "end" | "stretch";
+    /** Quiet state opposite the actions (role="status"), such as a Status LED reading "Saved". */
+    status?: ReactNode;
+    /** Draws the rule above the footer; short inline forms leave it off. */
+    divider?: boolean;
+} & HTMLAttributes<HTMLElement>;
+/**
+ * A form's stationary action area. Put exactly one primary Button last;
+ * every other action is `ghost` or `outline`.
+ */
+export declare function FormFooter({ children, divider, error, layout, status, ...props }: FormFooterProps): import("react/jsx-runtime").JSX.Element;
+/** Props accepted by Form. */
+export type FormProps = {
+    /** Disables every control while a submission is in flight. */
+    busy?: boolean;
+} & FormHTMLAttributes<HTMLFormElement>;
+/**
+ * A form with Caps' field rhythm. While `busy`, its fieldset disables every
+ * control and the form reports `aria-busy`; validation stays with the caller.
+ */
+export declare const Form: import("react").ForwardRefExoticComponent<{
+    /** Disables every control while a submission is in flight. */
+    busy?: boolean;
+} & FormHTMLAttributes<HTMLFormElement> & import("react").RefAttributes<HTMLFormElement>>;
+/** Props accepted by FormSection. */
+export type FormSectionProps = {
+    title: ReactNode;
+    description?: ReactNode;
+    /** Heading level inside the page outline. */
+    level?: 2 | 3 | 4;
+    children: ReactNode;
+} & Omit<HTMLAttributes<HTMLElement>, "title">;
+/** A titled group of fields; consecutive sections share one quiet rule. */
+export declare const FormSection: import("react").ForwardRefExoticComponent<{
+    title: ReactNode;
+    description?: ReactNode;
+    /** Heading level inside the page outline. */
+    level?: 2 | 3 | 4;
+    children: ReactNode;
+} & Omit<HTMLAttributes<HTMLElement>, "title"> & import("react").RefAttributes<HTMLElement>>;
+/** Props accepted by FieldSet. */
+export type FieldSetProps = {
+    legend: ReactNode;
+    description?: ReactNode;
+    /** The group's announced error, such as "Choose at least one right". */
+    error?: ReactNode;
+    children: ReactNode;
+} & FieldsetHTMLAttributes<HTMLFieldSetElement>;
+/**
+ * A legend-named group of related choices, such as a list of inline
+ * checkbox Fields. `disabled` disables every control inside.
+ */
+export declare const FieldSet: import("react").ForwardRefExoticComponent<{
+    legend: ReactNode;
+    description?: ReactNode;
+    /** The group's announced error, such as "Choose at least one right". */
+    error?: ReactNode;
+    children: ReactNode;
+} & FieldsetHTMLAttributes<HTMLFieldSetElement> & import("react").RefAttributes<HTMLFieldSetElement>>;
+/** Props accepted by Field. */
+export type FieldProps = {
+    children: ReactNode;
+    description?: ReactNode;
+    error?: ReactNode;
+    /**
+     * A decorative marker, such as a Sigil or App icon, before the label. It is
+     * hidden from assistive tech; the label stays the control's name.
+     */
+    icon?: ReactNode;
+    label?: ReactNode;
+    /**
+     * `vertical` stacks label, control and error; `horizontal` puts the control
+     * opposite its copy (settings rows); `inline` puts a checkbox or switch
+     * before its copy.
+     */
+    orientation?: "horizontal" | "inline" | "vertical";
+    /** Marks an optional field in a mostly required form. */
+    optional?: boolean;
+    /**
+     * The child is a read-only readout, such as a Status, not a control: the
+     * label names the row and nothing is wired to the child.
+     */
+    readout?: boolean;
+    required?: boolean;
+} & HTMLAttributes<HTMLDivElement>;
+/** A labelled form-field layout that renders caller-provided control and supporting content. */
+export declare const Field: import("react").ForwardRefExoticComponent<{
+    children: ReactNode;
+    description?: ReactNode;
+    error?: ReactNode;
+    /**
+     * A decorative marker, such as a Sigil or App icon, before the label. It is
+     * hidden from assistive tech; the label stays the control's name.
+     */
+    icon?: ReactNode;
+    label?: ReactNode;
+    /**
+     * `vertical` stacks label, control and error; `horizontal` puts the control
+     * opposite its copy (settings rows); `inline` puts a checkbox or switch
+     * before its copy.
+     */
+    orientation?: "horizontal" | "inline" | "vertical";
+    /** Marks an optional field in a mostly required form. */
+    optional?: boolean;
+    /**
+     * The child is a read-only readout, such as a Status, not a control: the
+     * label names the row and nothing is wired to the child.
+     */
+    readout?: boolean;
+    required?: boolean;
+} & HTMLAttributes<HTMLDivElement> & import("react").RefAttributes<HTMLDivElement>>;
+/** Props accepted by NumberField. */
+export type NumberFieldProps = {
+    /** Controlled value; `null` is empty. */
+    value?: number | null;
+    defaultValue?: number | null;
+    /** Called with each committed value, already clamped to min/max. */
+    onValueChange?: (value: number | null) => void;
+    min?: number;
+    max?: number;
+    /** Arrow keys and the − / + keys move by `step`; Page Up/Down by ten steps. */
+    step?: number;
+    /** A short unit readout after the value, such as "min" or "GB". */
+    unit?: ReactNode;
+    /** Cycle from max back to min (and back) instead of stopping at the ends. */
+    wrap?: boolean;
+    invalid?: boolean;
+    /** Accessible names for the − / + keys. */
+    decrementLabel?: string;
+    incrementLabel?: string;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "max" | "min" | "onChange" | "step" | "type" | "value">;
+/**
+ * A number spinbutton: a native `input type="number"` between − and + keys,
+ * with the value as a mono readout. Field wires its label, description and
+ * error to the input. The `caps-number-field-*` parts are stable so a context
+ * such as a Screen can redraw them; the semantics stay here.
+ */
+export declare const NumberField: import("react").ForwardRefExoticComponent<{
+    /** Controlled value; `null` is empty. */
+    value?: number | null;
+    defaultValue?: number | null;
+    /** Called with each committed value, already clamped to min/max. */
+    onValueChange?: (value: number | null) => void;
+    min?: number;
+    max?: number;
+    /** Arrow keys and the − / + keys move by `step`; Page Up/Down by ten steps. */
+    step?: number;
+    /** A short unit readout after the value, such as "min" or "GB". */
+    unit?: ReactNode;
+    /** Cycle from max back to min (and back) instead of stopping at the ends. */
+    wrap?: boolean;
+    invalid?: boolean;
+    /** Accessible names for the − / + keys. */
+    decrementLabel?: string;
+    incrementLabel?: string;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "onChange" | "type" | "value" | "max" | "min" | "step"> & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/field.js

@@ -0,0 +1,228 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Children, cloneElement, forwardRef, isValidElement, useId, useRef, useState, } from "react";
+import { Minus, Plus } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { Button } from "./button.js";
+import { Label } from "./label.js";
+import { InputGroup, InputGroupAddon } from "./input-group.js";
+import { Collapse } from "./presence.js";
+/** An announced error that takes no space when absent and collapses smoothly. */
+export function FieldError({ children, ...props }) {
+    const [lastError, setLastError] = useState(children);
+    // Retain the closing content so its intrinsic height can animate to zero.
+    if (children && children !== lastError)
+        setLastError(children);
+    return (_jsx(Collapse, { ...props, className: cn("caps-field-error-reveal", props.className), open: Boolean(children), children: _jsx("div", { className: "caps-field-error", role: "alert", "aria-hidden": !children, children: lastError }) }));
+}
+/**
+ * A form's stationary action area. Put exactly one primary Button last;
+ * every other action is `ghost` or `outline`.
+ */
+export function FormFooter({ children, divider = true, error, layout = "end", status, ...props }) {
+    return (_jsxs("footer", { ...props, className: cn("caps-form-footer", props.className), "data-divider": divider, "data-layout": layout, children: [_jsx(FieldError, { children: error }), _jsxs("div", { className: "caps-form-footer-row", children: [status ? (_jsx("div", { className: "caps-form-footer-status", role: "status", children: status })) : null, _jsx("div", { className: "caps-form-footer-actions", children: children })] })] }));
+}
+/**
+ * A form with Caps' field rhythm. While `busy`, its fieldset disables every
+ * control and the form reports `aria-busy`; validation stays with the caller.
+ */
+export const Form = forwardRef(function Form({ busy = false, children, className, ...props }, ref) {
+    return (_jsx("form", { ...props, "aria-busy": busy || undefined, className: cn("caps-form", className), ref: ref, children: _jsx("fieldset", { className: "caps-form-body", disabled: busy, children: children }) }));
+});
+const sectionHeadings = { 2: "h2", 3: "h3", 4: "h4" };
+/** A titled group of fields; consecutive sections share one quiet rule. */
+export const FormSection = forwardRef(function FormSection({ children, className, description, level = 3, title, ...props }, ref) {
+    const id = useId();
+    const Heading = sectionHeadings[level];
+    return (_jsxs("section", { ...props, "aria-labelledby": `${id}-title`, className: cn("caps-form-section", className), ref: ref, children: [_jsxs("header", { className: "caps-form-section-copy", children: [_jsx(Heading, { className: "caps-form-section-title", id: `${id}-title`, children: title }), description ? (_jsx("p", { className: "caps-form-section-description", children: description })) : null] }), _jsx("div", { className: "caps-form-section-fields", children: children })] }));
+});
+/**
+ * A legend-named group of related choices, such as a list of inline
+ * checkbox Fields. `disabled` disables every control inside.
+ */
+export const FieldSet = forwardRef(function FieldSet({ children, className, description, error, legend, ...props }, ref) {
+    const id = useId();
+    const describedBy = [
+        description ? `${id}-description` : props["aria-describedby"],
+        error ? `${id}-error` : null,
+    ]
+        .filter(Boolean)
+        .join(" ") || undefined;
+    return (_jsxs("fieldset", { ...props, "aria-describedby": describedBy, "aria-invalid": error ? true : props["aria-invalid"], className: cn("caps-fieldset", className), ref: ref, children: [_jsx("legend", { className: "caps-fieldset-legend", children: legend }), description ? (_jsx("p", { className: "caps-fieldset-description", id: `${id}-description`, children: description })) : null, _jsx("div", { className: "caps-fieldset-fields", children: children }), error === undefined ? null : (_jsx(FieldError, { id: `${id}-error`, children: error }))] }));
+});
+/** The labelled control inside an InputGroup: its first non-addon element. */
+function groupControl(group) {
+    const controls = [];
+    Children.forEach(group.props.children, (part) => {
+        if (isValidElement(part) &&
+            part.type !== InputGroupAddon)
+            controls.push(part);
+    });
+    return controls[0] ?? null;
+}
+/** A labelled form-field layout that renders caller-provided control and supporting content. */
+export const Field = forwardRef(function Field({ children, className, description, error, icon, label, optional, orientation = "vertical", readout = false, required, ...props }, ref) {
+    const generatedId = useId();
+    const child = isValidElement(children) ? children : null;
+    // An InputGroup is layout: the labelled control is the input inside it.
+    const group = child?.type === InputGroup;
+    const controlElement = group ? groupControl(child) : child;
+    const id = controlElement?.props.id;
+    const controlId = id ?? generatedId;
+    const descriptionId = `${controlId}-description`;
+    const errorId = `${controlId}-error`;
+    // Keep any description the caller already wired to the control.
+    const describedBy = [
+        controlElement?.props["aria-describedby"],
+        description ? descriptionId : null,
+        error ? errorId : null,
+    ]
+        .filter(Boolean)
+        .join(" ") || undefined;
+    const requiredValue = required === true ? true : controlElement?.props.required;
+    const invalidValue = error ? true : controlElement?.props["aria-invalid"];
+    const ariaRequiredValue = required === true ? true : controlElement?.props["aria-required"];
+    const clonedProps = { id: controlId };
+    if (requiredValue !== undefined)
+        clonedProps.required = requiredValue;
+    if (describedBy !== undefined)
+        clonedProps["aria-describedby"] = describedBy;
+    if (invalidValue !== undefined)
+        clonedProps["aria-invalid"] = invalidValue;
+    if (ariaRequiredValue !== undefined)
+        clonedProps["aria-required"] = ariaRequiredValue;
+    const control = child && controlElement && !readout
+        ? group
+            ? cloneElement(child, undefined, Children.map(child.props.children, (part) => part === controlElement
+                ? cloneElement(controlElement, clonedProps)
+                : part))
+            : cloneElement(child, clonedProps)
+        : children;
+    const labelContent = label ? (_jsx(Label, { htmlFor: readout ? undefined : controlId, 
+        // A choice's own label reads as body text; the group's legend carries weight.
+        className: orientation === "inline" ? "font-normal" : undefined, ...(required === undefined ? {} : { required }), ...(optional === undefined ? {} : { optional }), children: label })) : null;
+    const copy = label || description ? (_jsxs("div", { className: "caps-field-copy", children: [labelContent, description ? (_jsx("p", { className: "caps-field-description", id: descriptionId, children: description })) : null] })) : null;
+    const heading = icon ? (_jsxs("div", { className: "caps-field-lead", children: [_jsx("span", { className: "caps-field-icon", "aria-hidden": "true", children: icon }), copy] })) : (copy);
+    return (_jsxs("div", { ...props, className: cn("caps-field", className), "data-orientation": orientation, ref: ref, children: [orientation === "horizontal" ? (_jsxs("div", { className: "caps-field-row", children: [heading, control] })) : orientation === "inline" ? (_jsxs("div", { className: "caps-field-row", children: [control, heading] })) : (_jsxs(_Fragment, { children: [heading, control] })), _jsx(FieldError, { id: errorId, children: error })] }));
+});
+function stepPrecision(step) {
+    const text = String(step);
+    const dot = text.indexOf(".");
+    return dot === -1 ? 0 : text.length - dot - 1;
+}
+/** A 270° encoder arc from 7:30 to 4:30, measured as 100 path units. */
+const DIAL_ARC = "M 9.86 38.14 A 20 20 0 1 1 38.14 38.14";
+/** Pixels of vertical drag per step on the dial. */
+const DIAL_TRAVEL = 6;
+const keySteps = new Map([
+    ["ArrowUp", 1],
+    ["ArrowDown", -1],
+    ["PageUp", 10],
+    ["PageDown", -10],
+]);
+/**
+ * A number spinbutton: a native `input type="number"` between − and + keys,
+ * with the value as a mono readout. Field wires its label, description and
+ * error to the input. The `caps-number-field-*` parts are stable so a context
+ * such as a Screen can redraw them; the semantics stay here.
+ */
+export const NumberField = forwardRef(function NumberField({ className, decrementLabel = "Decrease", defaultValue = null, disabled, incrementLabel = "Increase", invalid, max, min, onBlur, onKeyDown, onValueChange, step = 1, unit, value, wrap = false, ...props }, ref) {
+    const [inner, setInner] = useState(defaultValue);
+    const [draft, setDraft] = useState(null);
+    const current = value === undefined ? inner : value;
+    const precision = stepPrecision(step);
+    const clamp = (next) => {
+        const rounded = Number(next.toFixed(precision));
+        if (min !== undefined && rounded < min)
+            return min;
+        if (max !== undefined && rounded > max)
+            return max;
+        return rounded;
+    };
+    const commit = (next) => {
+        const settled = next === null ? null : clamp(next);
+        setInner(settled);
+        setDraft(null);
+        if (settled !== current)
+            onValueChange?.(settled);
+    };
+    const commitDraft = () => {
+        if (draft === null)
+            return;
+        const parsed = Number(draft);
+        commit(draft.trim() === "" || !Number.isFinite(parsed) ? null : parsed);
+    };
+    const stepBy = (steps) => {
+        const next = (current ?? min ?? 0) + steps * step;
+        if (wrap && min !== undefined && max !== undefined) {
+            if (next > max) {
+                commit(min);
+                return;
+            }
+            if (next < min) {
+                commit(max);
+                return;
+            }
+        }
+        commit(next);
+    };
+    const atMin = min !== undefined && current !== null && current <= min;
+    const atMax = max !== undefined && current !== null && current >= max;
+    const isDisabled = disabled === true;
+    const drag = useRef(null);
+    // The dial is drawn only where a context (a Screen) asks for it, and only
+    // for a bounded value; the input stays the spinbutton either way.
+    const fraction = min !== undefined && max !== undefined && max > min
+        ? ((current ?? min) - min) / (max - min)
+        : null;
+    const onDialDown = (event) => {
+        if (isDisabled)
+            return;
+        event.currentTarget.setPointerCapture(event.pointerId);
+        drag.current = { y: event.clientY, value: current ?? min ?? 0 };
+    };
+    const onDialMove = (event) => {
+        if (!drag.current)
+            return;
+        const steps = Math.trunc((drag.current.y - event.clientY) / DIAL_TRAVEL);
+        const next = clamp(drag.current.value + steps * step);
+        if (next !== current)
+            commit(next);
+    };
+    const endDial = () => {
+        drag.current = null;
+    };
+    return (_jsxs("span", { className: cn("caps-number-field", className), "data-at-max": atMax || undefined, "data-at-min": atMin || undefined, "data-disabled": isDisabled || undefined, "data-wrap": wrap || undefined, children: [fraction === null ? null : (_jsxs("svg", { className: "caps-number-field-dial", viewBox: "0 0 48 48", "aria-hidden": "true", focusable: "false", onPointerDown: onDialDown, onPointerMove: onDialMove, onPointerUp: endDial, onPointerCancel: endDial, children: [_jsx("path", { className: "caps-number-field-dial-track", d: DIAL_ARC, pathLength: 100 }), _jsx("path", { className: "caps-number-field-dial-level", d: DIAL_ARC, pathLength: 100, strokeDasharray: `${String(Math.max(0.5, fraction * 100))} 100` })] })), _jsx(Button, { type: "button", variant: "outline", size: "icon", className: "caps-number-field-decrement", "aria-label": decrementLabel, "aria-controls": props.id, tabIndex: -1, disabled: isDisabled || (atMin && !wrap), onClick: () => {
+                    stepBy(-1);
+                }, children: _jsx(Minus, { "aria-hidden": "true" }) }), _jsxs("span", { className: "caps-number-field-readout", children: [_jsx("input", { ...props, "aria-invalid": invalid
+                            ? true
+                            : props["aria-invalid"] === false
+                                ? undefined
+                                : props["aria-invalid"], className: "input caps-input caps-number-field-input", disabled: disabled, inputMode: props.inputMode ?? (precision > 0 ? "decimal" : "numeric"), max: max, min: min, onBlur: (event) => {
+                            commitDraft();
+                            onBlur?.(event);
+                        }, onChange: (event) => {
+                            setDraft(event.target.value);
+                        }, onKeyDown: (event) => {
+                            onKeyDown?.(event);
+                            if (event.defaultPrevented)
+                                return;
+                            const steps = keySteps.get(event.key);
+                            if (steps !== undefined) {
+                                event.preventDefault();
+                                stepBy(steps);
+                            }
+                            else if (event.key === "Home" && min !== undefined) {
+                                event.preventDefault();
+                                commit(min);
+                            }
+                            else if (event.key === "End" && max !== undefined) {
+                                event.preventDefault();
+                                commit(max);
+                            }
+                            else if (event.key === "Enter") {
+                                commitDraft();
+                            }
+                        }, ref: ref, step: step, type: "number", value: draft ?? (current === null ? "" : String(current)) }), unit ? (_jsx("span", { className: "caps-number-field-unit", "aria-hidden": "true", children: unit })) : null] }), _jsx(Button, { type: "button", variant: "outline", size: "icon", className: "caps-number-field-increment", "aria-label": incrementLabel, "aria-controls": props.id, tabIndex: -1, disabled: isDisabled || (atMax && !wrap), onClick: () => {
+                    stepBy(1);
+                }, children: _jsx(Plus, { "aria-hidden": "true" }) })] }));
+});

package/dist/components/game-feedback.d.ts

@@ -0,0 +1,84 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+/** What happened: an order taken, an order refused, a hit, or something gained. */
+export type FeedbackKind = "confirm" | "deny" | "hit" | "gain";
+/** Props accepted by FeedbackLayer. */
+export type FeedbackLayerProps = HTMLAttributes<HTMLDivElement> & {
+    /** Freeze every mark where it is, e.g. while the game is paused. */
+    paused?: boolean;
+};
+/**
+ * A click-through overlay for game feedback, placed over the world by the
+ * host. Marks inside it are positioned in the layer's own pixels.
+ */
+export declare const FeedbackLayer: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    /** Freeze every mark where it is, e.g. while the game is paused. */
+    paused?: boolean;
+} & import("react").RefAttributes<HTMLDivElement>>;
+/** Props accepted by FeedbackMark. */
+export type FeedbackMarkProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    kind: FeedbackKind;
+    /** Anchor in layer pixels. */
+    x: number;
+    y: number;
+    /** A short note, such as the host's refusal reason. */
+    label?: ReactNode;
+    /** A floating number, drawn signed in outlined pixel numerals. */
+    amount?: number;
+    /** Total life in milliseconds; the host removes the mark when it ends. */
+    life?: number;
+};
+/**
+ * One piece of game feedback at a point: a stepped flash ring, an optional
+ * floating number and an optional note. Reduced motion keeps the ring and
+ * note still and only fades them.
+ */
+export declare const FeedbackMark: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    kind: FeedbackKind;
+    /** Anchor in layer pixels. */
+    x: number;
+    y: number;
+    /** A short note, such as the host's refusal reason. */
+    label?: ReactNode;
+    /** A floating number, drawn signed in outlined pixel numerals. */
+    amount?: number;
+    /** Total life in milliseconds; the host removes the mark when it ends. */
+    life?: number;
+} & import("react").RefAttributes<HTMLDivElement>>;
+/** A generic feedback tone: game-neutral, so any cartridge can author with
+ * it. `bite` is for a creature's bite, not any one game's monster. */
+export type FeedbackWordTone = "impact" | "gun" | "mech" | "wet" | "quiet" | "bite";
+/** Named display sizes for game feedback words. */
+export type FeedbackWordSize = "s" | "m" | "l" | "xl";
+/** A two-phase accent that plays alongside the word: `jaw` claps two wedges
+ * shut once, then eases back open. */
+export type FeedbackWordAccent = "jaw";
+/** Props accepted by FeedbackWordMark. */
+export type FeedbackWordMarkProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Comic lettering, at most 12 characters (e.g. "CRUNCH", "BLAM"). */
+    text: string;
+    /** Anchor in layer pixels; the word sits bottom-centre above this point. */
+    x: number;
+    y: number;
+    tone?: FeedbackWordTone;
+    size?: FeedbackWordSize;
+    accent?: FeedbackWordAccent;
+    /** Total life in milliseconds; the host removes the mark when it ends. */
+    life?: number;
+};
+/**
+ * One comic sound word at a point: punchy lettering that pops in with a
+ * little overshoot, drifts up, and fades. Reduced motion keeps it still at
+ * full strength until the host removes it.
+ */
+export declare const FeedbackWordMark: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Comic lettering, at most 12 characters (e.g. "CRUNCH", "BLAM"). */
+    text: string;
+    /** Anchor in layer pixels; the word sits bottom-centre above this point. */
+    x: number;
+    y: number;
+    tone?: FeedbackWordTone;
+    size?: FeedbackWordSize;
+    accent?: FeedbackWordAccent;
+    /** Total life in milliseconds; the host removes the mark when it ends. */
+    life?: number;
+} & import("react").RefAttributes<HTMLDivElement>>;