@fungi.computer/caps 0.4.0 → 0.6.0

package/README.md

@@ -127,6 +127,13 @@ Caps owns interaction and chooses the semantic destination. A null destination
 waits for the shell root to mount, including during server rendering. Base UI
 menu, Combobox and dialog portals still accept explicit container overrides.
 
+`DialogContent` and the composed `DialogPopup` accept `size="fill"` for a
+full-window frame. It fills the portal's fixed-position containing block (the
+viewport by default), without centring or a maximum width, and retains Caps
+padding, radius and material. Omit `size` or use `size="default"` for the
+existing width-limited frame; `DialogContent` centres it. Focus targets and
+Escape ownership are unchanged.
+
 In body mode, isolate the App root so page controls cannot paint over portaled
 dialogs. Agar's `mountApp` does this. Dialogs and menus rank by portal order;
 tooltips and toasts use their Stipe layers.

package/dist/blocks/status-tray.d.ts

@@ -1,4 +1,4 @@
-import { type HTMLAttributes, type ReactNode } from "react";
+import { type ComponentPropsWithRef, type HTMLAttributes, type ReactNode } from "react";
 import { type StatusGlyph, type StatusMotion, type StatusTone } from "../components/status.js";
 /**
  * One footer readout and the small tray it opens. Semantic data only: the
@@ -43,6 +43,12 @@ export type StatusTrayProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
     leading?: ReactNode;
     /** Trailing controls after the chips (Send, Expand, …). */
     trailing?: ReactNode;
+    /**
+     * Compose a native button trigger, forwarding these attributes, children
+     * and ref. StatusTray still owns disclosure, dismissal and return focus.
+     * Omit to retain the default chip and its theme-owned finish.
+     */
+    renderTrigger?: ((props: ComponentPropsWithRef<"button">) => ReactNode) | undefined;
     /**
      * Structural seat. `housing` sits on the plastic below a screen; `screen`
      * sits inside a Display as flat, screen-native text (the wiki's screen
@@ -59,7 +65,7 @@ export type StatusTrayProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
     hostInset?: number;
 };
 /** A footer row of readout chips; one opens its tray above the row at a time. */
-export declare function StatusTray({ items, openId, onOpenChange, leading, trailing, placement, align, hostInset, className, ...props }: StatusTrayProps): import("react/jsx-runtime").JSX.Element;
+export declare function StatusTray({ items, openId, onOpenChange, leading, trailing, renderTrigger, placement, align, hostInset, className, ...props }: StatusTrayProps): import("react/jsx-runtime").JSX.Element;
 /** A group of tray rows. Precede it with a DataListHeading to label it. */
 export declare function StatusTrayList({ children, className, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
 /**

package/dist/blocks/status-tray.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { X } from "lucide-react";
 import { Fragment, useEffect, useId, useRef, } from "react";
 import { IconButton } from "../components/icon-button.js";
@@ -6,7 +6,7 @@ import { Popover, PopoverAnchor } from "../components/popover.js";
 import { Status, } from "../components/status.js";
 import { cn } from "../lib/cn.js";
 /** A footer row of readout chips; one opens its tray above the row at a time. */
-export function StatusTray({ items, openId, onOpenChange, leading, trailing, placement = "housing", align = "end", hostInset, className, ...props }) {
+export function StatusTray({ items, openId, onOpenChange, leading, trailing, renderTrigger, placement = "housing", align = "end", hostInset, className, ...props }) {
     const scope = useId();
     const root = useRef(null);
     const panel = useRef(null);
@@ -50,14 +50,30 @@ export function StatusTray({ items, openId, onOpenChange, leading, trailing, pla
             document.removeEventListener("pointerdown", onPointer);
         };
     }, [activeId, onOpenChange]);
-    return (_jsxs(PopoverAnchor, { ...props, ref: root, className: cn("caps-status-tray", className), "data-placement": placement, "data-align": align, children: [open ? (_jsxs(Popover, { open: true, ref: panel, tabIndex: -1, side: "top", id: `${scope}-${open.id}`, role: "dialog", "aria-labelledby": `${scope}-title`, className: "caps-status-tray-panel", "data-status-tray-panel": open.id, children: [_jsxs("div", { className: "caps-status-tray-head", children: [open.tone ? (_jsx(Status, { size: "compact", tone: open.tone, glyph: open.glyph ?? "dot" })) : null, _jsx("span", { id: `${scope}-title`, className: "caps-status-tray-title", children: open.title ?? open.label }), open.actions, _jsx(IconButton, { "aria-label": "Close tray", icon: _jsx(X, { "aria-hidden": "true" }), onClick: close })] }), _jsx("div", { className: "caps-status-tray-body", children: open.content })] })) : null, placement === "host" ? null : (_jsxs("div", { className: "caps-status-tray-row", children: [leading, _jsx("div", { className: "caps-status-tray-chips", children: items.map((item) => (_jsxs(Fragment, { children: [_jsxs("button", { ref: (node) => {
-                                        if (node)
-                                            triggers.current.set(item.id, node);
-                                        else
-                                            triggers.current.delete(item.id);
-                                    }, type: "button", className: "caps-status-tray-chip", "aria-expanded": activeId === item.id, "aria-controls": activeId === item.id ? `${scope}-${item.id}` : undefined, "aria-label": item.accessibleLabel, disabled: item.disabled, title: item.disabled ? item.accessibleLabel : undefined, "aria-haspopup": "dialog", "data-status-tray-chip": item.id, onClick: () => {
-                                        onOpenChange(openId === item.id ? null : item.id);
-                                    }, children: [item.tone ? (_jsx(Status, { size: "compact", glyph: item.glyph ?? "dot", motion: item.motion ?? "none", tone: item.tone })) : null, _jsx("span", { className: "caps-status-tray-label", children: item.label }), item.count !== undefined && item.count > 0 ? (_jsx("span", { className: "caps-status-tray-count", children: item.count })) : null] }), item.after] }, item.id))) }), trailing] }))] }));
+    return (_jsxs(PopoverAnchor, { ...props, ref: root, className: cn("caps-status-tray", className), "data-placement": placement, "data-align": align, children: [open ? (_jsxs(Popover, { open: true, ref: panel, tabIndex: -1, side: "top", id: `${scope}-${open.id}`, role: "dialog", "aria-labelledby": `${scope}-title`, className: "caps-status-tray-panel", "data-status-tray-panel": open.id, children: [_jsxs("div", { className: "caps-status-tray-head", children: [open.tone ? (_jsx(Status, { size: "compact", tone: open.tone, glyph: open.glyph ?? "dot" })) : null, _jsx("span", { id: `${scope}-title`, className: "caps-status-tray-title", children: open.title ?? open.label }), open.actions, _jsx(IconButton, { "aria-label": "Close tray", icon: _jsx(X, { "aria-hidden": "true" }), onClick: close })] }), _jsx("div", { className: "caps-status-tray-body", children: open.content })] })) : null, placement === "host" ? null : (_jsxs("div", { className: "caps-status-tray-row", children: [leading, _jsx("div", { className: "caps-status-tray-chips", children: items.map((item) => {
+                            const trigger = {
+                                ref: (node) => {
+                                    if (node)
+                                        triggers.current.set(item.id, node);
+                                    else
+                                        triggers.current.delete(item.id);
+                                },
+                                type: "button",
+                                className: renderTrigger ? undefined : "caps-status-tray-chip",
+                                "aria-expanded": activeId === item.id,
+                                "aria-controls": activeId === item.id ? `${scope}-${item.id}` : undefined,
+                                "aria-label": item.accessibleLabel,
+                                disabled: item.disabled,
+                                title: item.disabled ? item.accessibleLabel : undefined,
+                                "aria-haspopup": "dialog",
+                                "data-status-tray-chip": item.id,
+                                onClick: () => {
+                                    onOpenChange(openId === item.id ? null : item.id);
+                                },
+                                children: (_jsxs(_Fragment, { children: [item.tone ? (_jsx(Status, { size: "compact", glyph: item.glyph ?? "dot", motion: item.motion ?? "none", tone: item.tone })) : null, _jsx("span", { className: "caps-status-tray-label", children: item.label }), item.count !== undefined && item.count > 0 ? (_jsx("span", { className: "caps-status-tray-count", children: item.count })) : null] })),
+                            };
+                            return (_jsxs(Fragment, { children: [renderTrigger ? (renderTrigger(trigger)) : (_jsx("button", { ...trigger })), item.after] }, item.id));
+                        }) }), trailing] }))] }));
 }
 /** A group of tray rows. Precede it with a DataListHeading to label it. */
 export function StatusTrayList({ children, className, ...props }) {

package/dist/components/dialog.d.ts

@@ -18,10 +18,15 @@ export declare const DialogTrigger: import("react").ForwardRefExoticComponent<Om
 export declare const DialogPortal: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react/dialog").DialogPortalProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 /** The styled backdrop for a composed Dialog. */
 export declare const DialogBackdrop: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react/dialog").DialogBackdropProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+/** Props accepted by DialogPopup. */
+export type DialogPopupProps = BaseDialog.Popup.Props & {
+    /** Fill the portal's positioning context instead of using the default width. */
+    size?: "default" | "fill";
+};
 /** The styled popup with Base UI composition and caller-controlled focus targets. */
-export declare const DialogPopup: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react/dialog").DialogPopupProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const DialogPopup: import("react").ForwardRefExoticComponent<Omit<DialogPopupProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 /** Props accepted by DialogContent. */
-export type DialogContentProps = BaseDialog.Popup.Props & Pick<BaseDialog.Portal.Props, "container" | "keepMounted">;
+export type DialogContentProps = DialogPopupProps & Pick<BaseDialog.Portal.Props, "container" | "keepMounted">;
 /**
  * The default portal, backdrop and popup composition for a Dialog.
  * Keeps child state across closes. Like Base UI, only full modal mode has a backdrop.

package/dist/components/dialog.js

@@ -39,17 +39,20 @@ export const DialogBackdrop = forwardRef(function DialogBackdrop({ className, ..
     return (_jsx(BaseDialog.Backdrop, { ...props, ref: ref, className: (state) => cn("caps-dialog-backdrop fixed inset-0 bg-black/40", resolveClassName(className, state)) }));
 });
 /** The styled popup with Base UI composition and caller-controlled focus targets. */
-export const DialogPopup = forwardRef(function DialogPopup({ className, finalFocus, ...props }, ref) {
+export const DialogPopup = forwardRef(function DialogPopup({ className, finalFocus, size = "default", ...props }, ref) {
     const dialog = useDialogContext();
-    return (_jsx(BaseDialog.Popup, { ...props, className: (state) => cn("caps-dialog-popup max-h-screen w-11/12 max-w-(--container-lg) overflow-y-auto overscroll-contain rounded-box bg-base-100 p-lg text-base-content shadow-xl", resolveClassName(className, state)), finalFocus: dialog.interactionOwner === "host" ? false : (finalFocus ?? true), ref: ref }));
+    return (_jsx(BaseDialog.Popup, { ...props, "data-size": size, className: (state) => cn("caps-dialog-popup overflow-y-auto overscroll-contain rounded-box bg-base-100 p-lg text-base-content shadow-xl", size === "fill"
+            ? "fixed inset-0 h-full w-full max-w-none"
+            : "max-h-screen w-11/12 max-w-(--container-lg)", resolveClassName(className, state)), finalFocus: dialog.interactionOwner === "host" ? false : (finalFocus ?? true), ref: ref }));
 });
 /**
  * The default portal, backdrop and popup composition for a Dialog.
  * Keeps child state across closes. Like Base UI, only full modal mode has a backdrop.
  */
-export const DialogContent = forwardRef(function DialogContent({ container, keepMounted = true, className, ...props }, ref) {
+export const DialogContent = forwardRef(function DialogContent({ container, keepMounted = true, className, size = "default", ...props }, ref) {
     const { modal } = useDialogContext();
-    return (_jsxs(DialogPortal, { container: container, keepMounted: keepMounted, children: [modal === true ? _jsx(DialogBackdrop, {}) : null, _jsx(DialogPopup, { ...props, className: (state) => cn("fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2", resolveClassName(className, state)), ref: ref })] }));
+    return (_jsxs(DialogPortal, { container: container, keepMounted: keepMounted, children: [modal === true ? _jsx(DialogBackdrop, {}) : null, _jsx(DialogPopup, { ...props, size: size, className: (state) => cn(size === "default" &&
+                    "fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2", resolveClassName(className, state)), ref: ref })] }));
 });
 /** A footer layout for caller-provided Dialog actions. */
 export function DialogFooter({ className, ...props }) {

package/dist/components/dropdown-menu.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } 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";
@@ -79,12 +79,12 @@ export const DropdownMenuItem = forwardRef(function DropdownMenuItem({ className
         }, 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) => {
+export const DropdownMenuCheckboxItem = forwardRef(function DropdownMenuCheckboxItem({ children, className, onClick, onSelect, ...props }, ref) {
+    return (_jsxs(BaseMenu.CheckboxItem, { ...props, className: (state) => cn(itemClasses, resolveClassName(className, state)), onClick: (event) => {
             onClick?.(event);
             if (!event.defaultPrevented)
                 onSelect?.(event);
-        }, ref: ref }));
+        }, ref: ref, children: [_jsx("span", { className: "min-w-0 flex-1", children: children }), _jsx(BaseMenu.CheckboxItemIndicator, { "aria-hidden": "true", className: "shrink-0", children: "\u2713" })] }));
 });
 /** A visual separator in a DropdownMenu. */
 export const DropdownMenuSeparator = forwardRef(function DropdownMenuSeparator({ className, ...props }, ref) {

package/dist/components/field.d.ts

@@ -21,6 +21,8 @@ export declare function FormFooter({ children, divider, error, layout, status, .
 export type FormProps = {
     /** Disables every control while a submission is in flight. */
     busy?: boolean;
+    /** Opt-in label/control grid; the default field rhythm is unchanged. */
+    layout?: "columns" | undefined;
 } & FormHTMLAttributes<HTMLFormElement>;
 /**
  * A form with Caps' field rhythm. While `busy`, its fieldset disables every
@@ -29,11 +31,15 @@ export type FormProps = {
 export declare const Form: import("react").ForwardRefExoticComponent<{
     /** Disables every control while a submission is in flight. */
     busy?: boolean;
+    /** Opt-in label/control grid; the default field rhythm is unchanged. */
+    layout?: "columns" | undefined;
 } & FormHTMLAttributes<HTMLFormElement> & import("react").RefAttributes<HTMLFormElement>>;
 /** Props accepted by FormSection. */
 export type FormSectionProps = {
     title: ReactNode;
     description?: ReactNode;
+    /** Opt-in label/control grid when used without a Form parent. */
+    layout?: "columns" | undefined;
     /** Heading level inside the page outline. */
     level?: 2 | 3 | 4;
     children: ReactNode;
@@ -42,6 +48,8 @@ export type FormSectionProps = {
 export declare const FormSection: import("react").ForwardRefExoticComponent<{
     title: ReactNode;
     description?: ReactNode;
+    /** Opt-in label/control grid when used without a Form parent. */
+    layout?: "columns" | undefined;
     /** Heading level inside the page outline. */
     level?: 2 | 3 | 4;
     children: ReactNode;
@@ -49,7 +57,11 @@ export declare const FormSection: import("react").ForwardRefExoticComponent<{
 /** Props accepted by FieldSet. */
 export type FieldSetProps = {
     legend: ReactNode;
+    /** Full legend on hover when a columns form clips it to one line. */
+    legendTitle?: string;
     description?: ReactNode;
+    /** Opt-in label/control grid when used without a Form parent. */
+    layout?: "columns" | undefined;
     /** The group's announced error, such as "Choose at least one right". */
     error?: ReactNode;
     children: ReactNode;
@@ -60,7 +72,11 @@ export type FieldSetProps = {
  */
 export declare const FieldSet: import("react").ForwardRefExoticComponent<{
     legend: ReactNode;
+    /** Full legend on hover when a columns form clips it to one line. */
+    legendTitle?: string;
     description?: ReactNode;
+    /** Opt-in label/control grid when used without a Form parent. */
+    layout?: "columns" | undefined;
     /** The group's announced error, such as "Choose at least one right". */
     error?: ReactNode;
     children: ReactNode;
@@ -76,6 +92,8 @@ export type FieldProps = {
      */
     icon?: ReactNode;
     label?: ReactNode;
+    /** Full label on hover when a columns form clips it to one line. */
+    labelTitle?: string;
     /**
      * `vertical` stacks label, control and error; `horizontal` puts the control
      * opposite its copy (settings rows); `inline` puts a checkbox or switch
@@ -102,6 +120,8 @@ export declare const Field: import("react").ForwardRefExoticComponent<{
      */
     icon?: ReactNode;
     label?: ReactNode;
+    /** Full label on hover when a columns form clips it to one line. */
+    labelTitle?: string;
     /**
      * `vertical` stacks label, control and error; `horizontal` puts the control
      * opposite its copy (settings rows); `inline` puts a checkbox or switch

package/dist/components/field.js

@@ -25,21 +25,21 @@ export function FormFooter({ children, divider = true, error, layout = "end", st
  * 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 }) }));
+export const Form = forwardRef(function Form({ busy = false, children, className, layout, ...props }, ref) {
+    return (_jsx("form", { ...props, "aria-busy": busy || undefined, className: cn("caps-form", className), "data-layout": layout, 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) {
+export const FormSection = forwardRef(function FormSection({ children, className, description, layout, 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 })] }));
+    return (_jsxs("section", { ...props, "aria-labelledby": `${id}-title`, className: cn("caps-form-section", className), "data-layout": layout, 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) {
+export const FieldSet = forwardRef(function FieldSet({ children, className, description, error, layout, legend, legendTitle, ...props }, ref) {
     const id = useId();
     const describedBy = [
         description ? `${id}-description` : props["aria-describedby"],
@@ -47,7 +47,7 @@ export const FieldSet = forwardRef(function FieldSet({ children, className, desc
     ]
         .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 }))] }));
+    return (_jsxs("fieldset", { ...props, "aria-describedby": describedBy, "aria-invalid": error ? true : props["aria-invalid"], className: cn("caps-fieldset", className), "data-layout": layout, ref: ref, children: [_jsx("legend", { className: "caps-fieldset-legend", title: legendTitle, 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) {
@@ -60,7 +60,7 @@ function groupControl(group) {
     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) {
+export const Field = forwardRef(function Field({ children, className, description, error, icon, label, labelTitle, 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.
@@ -97,7 +97,7 @@ export const Field = forwardRef(function Field({ children, className, descriptio
                 : part))
             : cloneElement(child, clonedProps)
         : children;
-    const labelContent = label ? (_jsx(Label, { htmlFor: readout ? undefined : controlId, 
+    const labelContent = label ? (_jsx(Label, { htmlFor: readout ? undefined : controlId, title: labelTitle, 
         // 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;

package/dist/form-fields.d.ts

@@ -3,6 +3,8 @@ import type { SchemaFormModel } from "./schema-form.js";
 /** Props accepted by FormFields. */
 export type FormFieldsProps<V extends FormValues> = {
     model: SchemaFormModel<V>;
+    /** Opt-in label/control grid for generated sections and groups. */
+    layout?: "columns" | undefined;
     /** Render only these fields, in this order, without section headings. */
     names?: readonly (keyof V & string)[];
     /** Disable every field, such as while an uncertain request is retried. */
@@ -12,4 +14,4 @@ export type FormFieldsProps<V extends FormValues> = {
  * Render a schema form's fields from its schema: every section in order, or
  * only `names` (for placing fields in Screen cells or custom layouts).
  */
-export declare function FormFields<V extends FormValues>({ model, names, disabled, }: FormFieldsProps<V>): (import("react/jsx-runtime").JSX.Element | null)[];
+export declare function FormFields<V extends FormValues>({ model, names, disabled, layout, }: FormFieldsProps<V>): (import("react/jsx-runtime").JSX.Element | null)[];

package/dist/form-fields.js

@@ -159,7 +159,7 @@ const groupKinds = new Set([
     "icon-checkboxes",
 ]);
 /** Choice groups: a legend names the group; each option names its input. */
-function SpecGroup({ spec, field, locked, error, }) {
+function SpecGroup({ spec, field, locked, error, layout, }) {
     const disabled = locked || spec.readOnly === true;
     const legend = spec.label;
     if (spec.kind === "checkboxes" || spec.kind === "icon-checkboxes") {
@@ -169,7 +169,7 @@ function SpecGroup({ spec, field, locked, error, }) {
                 ? [...selected, value]
                 : selected.filter((current) => current !== value));
         };
-        return (_jsx(FieldSet, { legend: legend, description: spec.help, disabled: disabled, error: error ?? null, children: spec.kind === "icon-checkboxes" ? (_jsx("div", { className: "caps-field-icon-choices", children: spec.options.map((option) => (_jsx(IconCheckbox, { name: spec.name, value: option.value, label: option.label, ...(option.caption === undefined
+        return (_jsx(FieldSet, { legend: legend, layout: layout, ...(layout === "columns" ? { legendTitle: legend } : {}), description: spec.help, disabled: disabled, error: error ?? null, children: spec.kind === "icon-checkboxes" ? (_jsx("div", { className: "caps-field-icon-choices", children: spec.options.map((option) => (_jsx(IconCheckbox, { name: spec.name, value: option.value, label: option.label, ...(option.caption === undefined
                         ? {}
                         : { caption: option.caption }), icon: option.icon, disabled: option.disabled, checked: selected.includes(option.value), onBlur: field.handleBlur, onChange: (event) => {
                         toggle(option.value, event.currentTarget.checked);
@@ -178,7 +178,7 @@ function SpecGroup({ spec, field, locked, error, }) {
                     } }) }, option.value)))) }));
     }
     const cards = spec.options.some((option) => option.description !== undefined || option.meta !== undefined);
-    return (_jsx(FieldSet, { legend: legend, description: spec.help, disabled: disabled, error: error ?? null, children: _jsx(RadioGroup, { name: spec.name, "aria-label": legend, value: text(field), onValueChange: (next) => {
+    return (_jsx(FieldSet, { legend: legend, layout: layout, ...(layout === "columns" ? { legendTitle: legend } : {}), description: spec.help, disabled: disabled, error: error ?? null, children: _jsx(RadioGroup, { name: spec.name, "aria-label": legend, value: text(field), onValueChange: (next) => {
                 field.handleChange(next);
                 field.handleBlur();
             }, 
@@ -206,45 +206,52 @@ function RenderedControl({ spec, field, locked, error, render, ...control }) {
         "aria-invalid": error !== undefined,
     });
 }
-function SchemaField({ form, spec, locked, }) {
+function SchemaField({ form, spec, locked, layout, }) {
     const field = useField({ form, name: spec.name });
     const submitted = useSelector(form.store, (state) => state.submissionAttempts > 0);
     const error = field.state.meta.isBlurred || submitted
         ? fieldError(field.state.meta)
         : undefined;
     if (spec.render === undefined && groupKinds.has(spec.kind))
-        return (_jsx(SpecGroup, { spec: spec, field: field, locked: locked, error: error }));
-    const orientation = spec.kind === "checkbox"
-        ? "inline"
-        : (spec.layout ?? (spec.kind === "switch" ? "row" : "stacked")) === "row"
+        return (_jsx(SpecGroup, { spec: spec, field: field, locked: locked, error: error, layout: layout }));
+    // A columns form chooses one rhythm; per-field layout hints only govern
+    // the unchanged default presentation.
+    const orientation = layout === "columns"
+        ? spec.kind === "switch" || spec.kind === "checkbox"
             ? "horizontal"
-            : "vertical";
-    return (_jsx(Field, { label: spec.label, description: spec.help, icon: spec.icon, orientation: orientation, error: error, ...(spec.required === undefined ? {} : { required: spec.required }), ...(spec.optional === undefined ? {} : { optional: spec.optional }), children: spec.render === undefined ? (_jsx(SpecControl, { spec: spec, field: field, locked: locked })) : (_jsx(RenderedControl, { spec: spec, field: field, locked: locked, error: error, render: spec.render })) }));
+            : "vertical"
+        : spec.kind === "checkbox"
+            ? "inline"
+            : (spec.layout ?? (spec.kind === "switch" ? "row" : "stacked")) ===
+                "row"
+                ? "horizontal"
+                : "vertical";
+    return (_jsx(Field, { label: spec.label, ...(layout === "columns" ? { labelTitle: spec.label } : {}), description: spec.help, icon: spec.icon, orientation: orientation, error: error, ...(spec.required === undefined ? {} : { required: spec.required }), ...(spec.optional === undefined ? {} : { optional: spec.optional }), children: spec.render === undefined ? (_jsx(SpecControl, { spec: spec, field: field, locked: locked })) : (_jsx(RenderedControl, { spec: spec, field: field, locked: locked, error: error, render: spec.render })) }));
 }
 const readValues = Schema.decodeUnknownOption(Schema.Record(Schema.String, inputSchema));
-function Visible({ form, spec, locked, }) {
+function Visible({ form, spec, locked, layout, }) {
     const when = spec.when;
     const shown = useSelector(form.store, (state) => when === undefined
         ? true
         : when(Option.getOrElse(readValues(state.values), () => ({}))));
     if (!shown)
         return null;
-    return _jsx(SchemaField, { form: form, spec: spec, locked: locked });
+    return (_jsx(SchemaField, { form: form, spec: spec, locked: locked, layout: layout }));
 }
-function SectionFields({ form, section, locked, }) {
-    const fields = section.fields.map((spec) => (_jsx(Visible, { form: form, spec: spec, locked: locked }, spec.name)));
-    return section.title === undefined ? (fields) : (_jsx(FormSection, { title: section.title, description: section.description, children: fields }));
+function SectionFields({ form, section, locked, layout, }) {
+    const fields = section.fields.map((spec) => (_jsx(Visible, { form: form, spec: spec, locked: locked, layout: layout }, spec.name)));
+    return section.title === undefined ? (fields) : (_jsx(FormSection, { title: section.title, description: section.description, layout: layout, children: fields }));
 }
 /**
  * Render a schema form's fields from its schema: every section in order, or
  * only `names` (for placing fields in Screen cells or custom layouts).
  */
-export function FormFields({ model, names, disabled = false, }) {
+export function FormFields({ model, names, disabled = false, layout, }) {
     const form = model.form;
     if (names !== undefined)
         return names.map((name) => {
             const spec = model.description.fields.find((field) => field.name === name);
-            return spec === undefined ? null : (_jsx(Visible, { form: form, spec: spec, locked: disabled }, name));
+            return spec === undefined ? null : (_jsx(Visible, { form: form, spec: spec, locked: disabled, layout: layout }, name));
         });
-    return model.description.sections.map((section) => (_jsx(SectionFields, { form: form, section: section, locked: disabled }, section.id ?? "")));
+    return model.description.sections.map((section) => (_jsx(SectionFields, { form: form, section: section, locked: disabled, layout: layout }, section.id ?? "")));
 }

package/dist/lib/format-money.d.ts

@@ -1,2 +1,8 @@
-/** Format USD with cents, preserving sub-cent precision without displaying non-zero amounts as zero. */
-export declare function formatMoney(amount: number): string;
+/**
+ * Format USD to cents, marking non-zero sub-cent amounts rather than rounding
+ * them to zero. Callers needing the supported five-decimal precision opt in
+ * with `precision: "exact"`.
+ */
+export declare function formatMoney(amount: number, options?: Readonly<{
+    precision: "exact";
+}>): string;

package/dist/lib/format-money.js

@@ -4,19 +4,22 @@ const regularUsd = new Intl.NumberFormat("en-US", {
     minimumFractionDigits: 2,
     maximumFractionDigits: 2,
 });
-const subcentUsd = new Intl.NumberFormat("en-US", {
+const exactUsd = new Intl.NumberFormat("en-US", {
     style: "currency",
     currency: "USD",
     minimumFractionDigits: 2,
     maximumFractionDigits: 5,
 });
-/** Format USD with cents, preserving sub-cent precision without displaying non-zero amounts as zero. */
-export function formatMoney(amount) {
+/**
+ * Format USD to cents, marking non-zero sub-cent amounts rather than rounding
+ * them to zero. Callers needing the supported five-decimal precision opt in
+ * with `precision: "exact"`.
+ */
+export function formatMoney(amount, options) {
     if (!Number.isFinite(amount))
         throw new RangeError("Money amount must be finite");
-    if (amount !== 0 && Math.abs(amount) < 0.00001)
+    const subcent = amount !== 0 && Math.abs(amount) < 0.01;
+    if (subcent && (options?.precision !== "exact" || Math.abs(amount) < 0.00001))
         return amount < 0 ? ">-$0.01" : "<$0.01";
-    return amount !== 0 && Math.abs(amount) < 0.01
-        ? subcentUsd.format(amount)
-        : regularUsd.format(amount);
+    return subcent ? exactUsd.format(amount) : regularUsd.format(amount);
 }

package/dist/schema-form.d.ts

@@ -33,6 +33,10 @@ export type SchemaFormOptions<V extends FormValues, Out> = {
     defaultValues: V;
     /** Receives the parsed value, never the raw input. */
     onSubmit: (value: Out, raw: V) => Promise<SubmitResult<V> | undefined> | Promise<void> | SubmitResult<V> | undefined;
+    /** Called only after a saved result, with the new raw-value baseline. */
+    onSaved?: ((values: V) => void) | undefined;
+    /** Safe message for a thrown submit; the cause is logged, never shown. */
+    failure?: string | undefined;
 };
 /** The schema as TanStack validates it: raw values in, any output. */
 export type Validator<V> = StandardSchemaV1<V, unknown>;
@@ -75,6 +79,9 @@ export type SchemaFormPresentation = {
     submitLabel?: ReactNode;
     /** Show a Discard action while there are unsaved changes. */
     discardLabel?: ReactNode;
+    /** A secondary exit action, shown even when clean; never submits or discards. */
+    onCancel?: () => void;
+    cancelLabel?: ReactNode;
     /** Keep the primary action available on a clean form (create forms). */
     allowClean?: boolean;
     /** Replaces the SaveBar, such as a footer with a retry key; `null` drops it. */
@@ -90,6 +97,8 @@ export type SchemaFormPresentation = {
 /** Props accepted by SchemaForm: a model from useSchemaForm, or its options. */
 export type SchemaFormProps<V extends FormValues, Out> = SchemaFormPresentation & ({
     model: SchemaFormModel<V>;
+    onSaved?: never;
+    failure?: never;
 } | SchemaFormOptions<V, Out>);
 /**
  * A whole form from its schema: fields, sections, validation, busy state and
@@ -104,6 +113,9 @@ export type SaveBarProps<V extends FormValues> = {
     label: ReactNode;
     /** Show a Discard action while there are unsaved changes. */
     discardLabel?: ReactNode;
+    /** A secondary exit action that never submits or resets the form. */
+    onCancel?: (() => void) | undefined;
+    cancelLabel?: ReactNode;
     /**
      * Keep the primary action available on a clean form (create forms that may
      * submit their defaults). By default a clean form has nothing to save.
@@ -117,4 +129,4 @@ export type SaveBarProps<V extends FormValues> = {
  * The form's action row: the refused-submit error, a quiet "Unsaved changes"
  * or "Saved" readout, an optional Discard, and the one primary submit.
  */
-export declare function SaveBar<V extends FormValues>({ model, label, discardLabel, allowClean, dirtyLabel, buttonProps, ...props }: SaveBarProps<V>): import("react/jsx-runtime").JSX.Element;
+export declare function SaveBar<V extends FormValues>({ model, label, discardLabel, onCancel, cancelLabel, allowClean, dirtyLabel, buttonProps, ...props }: SaveBarProps<V>): import("react/jsx-runtime").JSX.Element;

package/dist/schema-form.js

@@ -1,12 +1,24 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { evaluate, useForm, useSelector, } from "@tanstack/react-form";
-import { useMemo, useState } from "react";
+import { useMemo, useRef, useState } from "react";
 import { Button } from "./components/button.js";
 import { Form, FormFooter, } from "./components/field.js";
 import { Status } from "./components/status.js";
 import { FormFields } from "./form-fields.js";
 import { describeSchema, standardSchema, } from "./form-schema.js";
 const serverKey = "onServer";
+/** Keep the user's place when a submitted form reveals validation errors. */
+function focusFirstInvalid(form) {
+    const invalid = form?.querySelector('[aria-invalid="true"]');
+    if (invalid?.matches("input, select, textarea, button, [tabindex]")) {
+        invalid.focus();
+    }
+    else {
+        invalid
+            ?.querySelector("input, select, textarea, button")
+            ?.focus();
+    }
+}
 function hasServerError(field) {
     return field.state.meta.errorMap.onServer !== undefined;
 }
@@ -61,9 +73,17 @@ export function useSchemaForm(options) {
                 setError(parsed.issues[0]?.message ?? "Check the form and try again.");
                 return;
             }
-            const result = (await options.onSubmit(parsed.value, value)) ?? {
-                kind: "saved",
-            };
+            let result;
+            try {
+                result = (await options.onSubmit(parsed.value, value)) ?? {
+                    kind: "saved",
+                };
+            }
+            catch (cause) {
+                console.error("SchemaForm submit failed", cause);
+                setError(options.failure ?? "Couldn't save changes. Try again.");
+                return;
+            }
             if (result.kind === "refused") {
                 setError(result.error ?? null);
                 const wide = formApi;
@@ -76,6 +96,7 @@ export function useSchemaForm(options) {
             setSavedBaseline(baseline);
             formApi.reset(baseline);
             setSaved(result.message ?? "Saved");
+            options.onSaved?.(baseline);
         },
     });
     return {
@@ -98,16 +119,28 @@ export function useSchemaFormStatus(model) {
     const canSubmit = useSelector(model.form.store, (state) => state.canSubmit);
     return { dirty, submitting, canSubmit };
 }
-function BoundSchemaForm({ model, submitLabel = "Save changes", discardLabel, allowClean, footer, children, disabled = false, ...props }) {
+function BoundSchemaForm({ model, submitLabel = "Save changes", discardLabel, onCancel, cancelLabel, allowClean, layout, footer, children, disabled = false, ...props }) {
     const { submitting } = useSchemaFormStatus(model);
-    return (_jsxs(Form, { ...props, busy: submitting, noValidate: true, onSubmit: (event) => {
+    const formRef = useRef(null);
+    return (_jsxs(Form, { ...props, ref: formRef, layout: layout, busy: submitting, noValidate: true, onSubmit: (event) => {
             event.preventDefault();
             if (!model.form.state.isSubmitting)
-                void model.submit();
-        }, children: [children ?? _jsx(FormFields, { model: model, disabled: disabled }), footer !== undefined ? (footer) : (_jsx(SaveBar, { model: model, label: submitLabel, ...(discardLabel === undefined ? {} : { discardLabel }), ...(allowClean === undefined ? {} : { allowClean }) }))] }));
+                void model.submit().then(() => {
+                    // React commits field errors after TanStack completes validation.
+                    setTimeout(() => {
+                        focusFirstInvalid(formRef.current);
+                    }, 0);
+                });
+        }, children: [children ?? (_jsx(FormFields, { model: model, disabled: disabled, layout: layout })), footer !== undefined ? (footer) : (_jsx(SaveBar, { model: model, label: submitLabel, discardLabel: onCancel === undefined ? discardLabel : undefined, onCancel: onCancel, cancelLabel: cancelLabel, allowClean: allowClean ?? onCancel !== undefined, divider: onCancel === undefined }))] }));
 }
-function OwnedSchemaForm({ schema, defaultValues, onSubmit, ...props }) {
-    const model = useSchemaForm({ schema, defaultValues, onSubmit });
+function OwnedSchemaForm({ schema, defaultValues, onSubmit, onSaved, failure, ...props }) {
+    const model = useSchemaForm({
+        schema,
+        defaultValues,
+        onSubmit,
+        onSaved,
+        failure,
+    });
     return _jsx(BoundSchemaForm, { ...props, model: model });
 }
 /**
@@ -122,8 +155,8 @@ export function SchemaForm(props) {
  * The form's action row: the refused-submit error, a quiet "Unsaved changes"
  * or "Saved" readout, an optional Discard, and the one primary submit.
  */
-export function SaveBar({ model, label, discardLabel, allowClean = false, dirtyLabel = "Unsaved changes", buttonProps, ...props }) {
-    const { dirty, submitting, canSubmit } = useSchemaFormStatus(model);
+export function SaveBar({ model, label, discardLabel, onCancel, cancelLabel = "Cancel", allowClean = false, dirtyLabel = "Unsaved changes", buttonProps, ...props }) {
+    const { dirty, submitting } = useSchemaFormStatus(model);
     const status = submitting ? null : model.saved && !dirty ? (_jsx(Status, { tone: "success", size: "compact", label: model.saved })) : dirty ? (_jsx(Status, { tone: "neutral", size: "compact", label: dirtyLabel })) : null;
-    return (_jsxs(FormFooter, { ...props, error: model.error, status: status, children: [discardLabel && dirty ? (_jsx(Button, { type: "button", variant: "ghost", disabled: submitting, onClick: model.discard, children: discardLabel })) : null, _jsx(Button, { ...buttonProps, type: "submit", loading: submitting, disabled: submitting || !canSubmit || (!dirty && !allowClean), children: label })] }));
+    return (_jsxs(FormFooter, { ...props, error: model.error, status: status, children: [onCancel ? (_jsx(Button, { type: "button", variant: "ghost", disabled: submitting, onClick: onCancel, children: cancelLabel })) : discardLabel && dirty ? (_jsx(Button, { type: "button", variant: "ghost", disabled: submitting, onClick: model.discard, children: discardLabel })) : null, _jsx(Button, { ...buttonProps, type: "submit", loading: submitting, disabled: submitting || (!dirty && !allowClean), title: !dirty && !allowClean ? "No changes to save" : undefined, children: label })] }));
 }