@fungi.computer/caps 0.0.0-stage → 0.0.1

package/dist/enhance/cigarette-card.js

@@ -0,0 +1,33 @@
+/** Only the pressed-button card turns over; a preview card is a link. */
+const CARD = "button.caps-cigarette-card";
+/** Show one face of a server-rendered CigaretteCard. */
+export function setCigaretteCardFlipped(card, flipped) {
+    card.setAttribute("aria-pressed", String(flipped));
+    card.dataset.flipped = String(flipped);
+    card
+        .querySelector(".caps-cigarette-card-front")
+        ?.setAttribute("aria-hidden", String(flipped));
+    card
+        .querySelector(".caps-cigarette-card-back")
+        ?.setAttribute("aria-hidden", String(!flipped));
+}
+function onClick(event) {
+    // A hydrated CigaretteCard handles its own click and marks it prevented.
+    if (event.defaultPrevented || !(event.target instanceof Element))
+        return;
+    const card = event.target.closest(CARD);
+    if (!card)
+        return;
+    setCigaretteCardFlipped(card, card.getAttribute("aria-pressed") !== "true");
+}
+/**
+ * Flip server-rendered CigaretteCards on click, tap, Enter or Space. The card
+ * is a native button, so the keyboard reaches it as a click; this only
+ * toggles the pressed state. Returns a cleanup that removes the listener.
+ */
+export function enhanceCigaretteCards(root = document) {
+    root.addEventListener("click", onClick);
+    return () => {
+        root.removeEventListener("click", onClick);
+    };
+}

package/dist/enhance/sketch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The opt-in pencil layer for server-rendered field-guide pages.
+ *
+ * Markup contract, all plain attributes so any host can use it without React:
+ * - `data-sketch-root` marks a positioned host; its overlay is drawn inside it.
+ * - `data-sketch="circle" | "underline"` marks inline text to annotate.
+ * - `data-sketch-leader-x` / `data-sketch-leader-y` (fractions of the target
+ *   box) on a note draw a leader from the note to the `data-sketch-target`
+ *   inside the same `data-sketch-item`. The layout decides whether leaders
+ *   apply by setting `--caps-sketch-leader: on` on the note.
+ *
+ * Strokes use `currentColor`, so a theme switch recolors them without a
+ * redraw. The host receives `data-sketch-drawn` once annotations exist, which
+ * lets Caps hide the static CSS fallbacks they replace.
+ */
+export declare function sketch(root?: ParentNode): () => void;

package/dist/enhance/sketch.js

@@ -0,0 +1,130 @@
+import roughImport from "roughjs";
+function resolveRough(entry) {
+    return "svg" in entry ? entry : entry.default;
+}
+const rough = resolveRough(roughImport);
+const SVG = "http://www.w3.org/2000/svg";
+/**
+ * The opt-in pencil layer for server-rendered field-guide pages.
+ *
+ * Markup contract, all plain attributes so any host can use it without React:
+ * - `data-sketch-root` marks a positioned host; its overlay is drawn inside it.
+ * - `data-sketch="circle" | "underline"` marks inline text to annotate.
+ * - `data-sketch-leader-x` / `data-sketch-leader-y` (fractions of the target
+ *   box) on a note draw a leader from the note to the `data-sketch-target`
+ *   inside the same `data-sketch-item`. The layout decides whether leaders
+ *   apply by setting `--caps-sketch-leader: on` on the note.
+ *
+ * Strokes use `currentColor`, so a theme switch recolors them without a
+ * redraw. The host receives `data-sketch-drawn` once annotations exist, which
+ * lets Caps hide the static CSS fallbacks they replace.
+ */
+export function sketch(root = document) {
+    const hosts = Array.from(root.querySelectorAll("[data-sketch-root]"));
+    const draw = () => {
+        for (const [index, host] of hosts.entries())
+            drawHost(host, index);
+    };
+    draw();
+    // Older engines and jsdom lack ResizeObserver; they draw once.
+    const observer = "ResizeObserver" in globalThis ? new ResizeObserver(draw) : undefined;
+    for (const host of hosts)
+        observer?.observe(host);
+    // Web fonts move annotated text once they load; jsdom has no font set.
+    if ("fonts" in document)
+        void document.fonts.ready.then(draw);
+    return () => {
+        observer?.disconnect();
+        for (const host of hosts) {
+            host.querySelector(":scope > .caps-sketch-overlay")?.remove();
+            delete host.dataset.sketchDrawn;
+        }
+    };
+}
+function drawHost(host, index) {
+    host.querySelector(":scope > .caps-sketch-overlay")?.remove();
+    const bounds = host.getBoundingClientRect();
+    if (!bounds.width || !bounds.height)
+        return;
+    const overlay = document.createElementNS(SVG, "svg");
+    overlay.setAttribute("viewBox", `0 0 ${String(bounds.width)} ${String(bounds.height)}`);
+    overlay.setAttribute("aria-hidden", "true");
+    overlay.setAttribute("focusable", "false");
+    overlay.classList.add("caps-sketch-overlay");
+    const generator = rough.svg(overlay);
+    for (const [markIndex, mark] of host
+        .querySelectorAll("[data-sketch]")
+        .entries()) {
+        const annotation = drawMark(generator, bounds, mark, {
+            roughness: 1.1,
+            stroke: "currentColor",
+            strokeWidth: 1.3,
+            seed: 2601 + index * 10 + markIndex,
+        });
+        if (annotation)
+            overlay.append(annotation);
+    }
+    for (const [noteIndex, note] of host
+        .querySelectorAll("[data-sketch-leader-x]")
+        .entries()) {
+        const leader = drawLeader(generator, bounds, note, {
+            roughness: 1.2,
+            stroke: "currentColor",
+            strokeWidth: 1.2,
+            seed: 3101 + index * 10 + noteIndex,
+        });
+        if (leader)
+            overlay.append(leader);
+    }
+    host.append(overlay);
+    host.dataset.sketchDrawn = "";
+}
+function drawMark(generator, host, mark, options) {
+    const box = mark.getBoundingClientRect();
+    if (!box.width || !box.height)
+        return undefined;
+    const x = box.left - host.left;
+    const y = box.top - host.top;
+    switch (mark.dataset.sketch) {
+        case "circle":
+            return generator.ellipse(x + box.width / 2, y + box.height / 2, box.width + 9, box.height + 7, options);
+        case "underline":
+            return generator.line(x, y + box.height + 3, x + box.width, y + box.height + 3, options);
+        default:
+            return undefined;
+    }
+}
+function drawLeader(generator, host, note, options) {
+    if (getComputedStyle(note).getPropertyValue("--caps-sketch-leader").trim() !==
+        "on")
+        return undefined;
+    const target = note
+        .closest("[data-sketch-item]")
+        ?.querySelector("[data-sketch-target]");
+    const fx = Number(note.dataset.sketchLeaderX);
+    const fy = Number(note.dataset.sketchLeaderY);
+    if (!target || !Number.isFinite(fx) || !Number.isFinite(fy))
+        return undefined;
+    const targetBox = target.getBoundingClientRect();
+    const noteBox = note.getBoundingClientRect();
+    const endX = targetBox.left - host.left + targetBox.width * fx;
+    const endY = targetBox.top - host.top + targetBox.height * fy;
+    const startX = Math.min(Math.max(endX, noteBox.left - host.left + 18), noteBox.right - host.left - 18);
+    const startY = noteBox.top - host.top - 8;
+    const length = Math.hypot(endX - startX, endY - startY);
+    if (length < 12)
+        return undefined;
+    const group = document.createElementNS(SVG, "g");
+    const bend = Math.min(16, length / 10);
+    group.append(generator.curve([
+        [startX, startY],
+        [(startX + endX) / 2 + bend, (startY + endY) / 2],
+        [endX, endY],
+    ], options));
+    const angle = Math.atan2(endY - startY, endX - startX);
+    for (const side of [-1, 1]) {
+        const wing = angle + Math.PI + side * 0.45;
+        group.append(generator.line(endX, endY, endX + Math.cos(wing) * 11, endY + Math.sin(wing) * 11, options));
+    }
+    return group;
+}

package/dist/form-error.d.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** First readable TanStack string error or Standard Schema issue. */
+export declare function fieldError(meta: {
+    errors: readonly unknown[];
+}): string | undefined;
+/** Effect's maintained Standard Schema adapter, including nested issue paths. */
+export declare const effectValidator: typeof Schema.toStandardSchemaV1;

package/dist/form-error.js

@@ -0,0 +1,14 @@
+import { Option, Schema } from "effect";
+const readStringError = Schema.decodeUnknownOption(Schema.String);
+const readIssueError = Schema.decodeUnknownOption(Schema.Struct({ message: Schema.String }));
+/** First readable TanStack string error or Standard Schema issue. */
+export function fieldError(meta) {
+    for (const error of meta.errors) {
+        const message = Option.getOrUndefined(Option.orElse(Option.map(readIssueError(error), (issue) => issue.message), () => readStringError(error)));
+        if (message !== undefined && message.length > 0)
+            return message;
+    }
+    return undefined;
+}
+/** Effect's maintained Standard Schema adapter, including nested issue paths. */
+export const effectValidator = Schema.toStandardSchemaV1;

package/dist/form-fields.d.ts

@@ -0,0 +1,15 @@
+import type { FormValues } from "./form-schema.js";
+import type { SchemaFormModel } from "./schema-form.js";
+/** Props accepted by FormFields. */
+export type FormFieldsProps<V extends FormValues> = {
+    model: SchemaFormModel<V>;
+    /** 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. */
+    disabled?: boolean;
+};
+/**
+ * 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)[];

package/dist/form-fields.js

@@ -0,0 +1,250 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useField, useSelector, } from "@tanstack/react-form";
+import { Option, Schema } from "effect";
+import { Eye, EyeOff } from "lucide-react";
+import { useRef, useState } from "react";
+import { Button } from "./components/button.js";
+import { UploadQueue } from "./blocks/upload-queue.js";
+import { Checkbox } from "./components/checkbox.js";
+import { Combobox, ComboboxTrigger } from "./components/combobox.js";
+import { Field, FieldSet, FormSection, NumberField, } from "./components/field.js";
+import { IconCheckbox } from "./components/icon-checkbox.js";
+import { IconRadio } from "./components/icon-radio.js";
+import { Input } from "./components/input.js";
+import { InputGroup, InputGroupAddon } from "./components/input-group.js";
+import { RadioGroup, RadioGroupCard, RadioGroupItem, } from "./components/radio-group.js";
+import { Select } from "./components/select.js";
+import { Switch } from "./components/switch.js";
+import { Textarea } from "./components/textarea.js";
+import { VisuallyHidden } from "./components/visually-hidden.js";
+import { fieldError } from "./form-error.js";
+// TanStack hands field values back untyped; each control reads its own kind.
+const readText = Schema.decodeUnknownOption(Schema.String);
+const readFlag = Schema.decodeUnknownOption(Schema.Boolean);
+const readAmount = Schema.decodeUnknownOption(Schema.NullOr(Schema.Finite));
+const readTexts = Schema.decodeUnknownOption(Schema.Array(Schema.String));
+const filesSchema = Schema.Array(Schema.instanceOf(File));
+const readFiles = Schema.decodeUnknownOption(filesSchema);
+const inputSchema = Schema.Union([
+    Schema.String,
+    Schema.Finite,
+    Schema.Boolean,
+    Schema.Null,
+    Schema.Undefined,
+    Schema.Array(Schema.String),
+    filesSchema,
+]);
+const readInput = Schema.decodeUnknownOption(inputSchema);
+const text = (field) => Option.getOrElse(readText(field.state.value), () => "");
+const flag = (field) => Option.getOrElse(readFlag(field.state.value), () => false);
+const amount = (field) => Option.getOrElse(readAmount(field.state.value), () => null);
+const texts = (field) => Option.getOrElse(readTexts(field.state.value), () => []);
+const files = (field) => Option.getOrElse(readFiles(field.state.value), () => []);
+const input = (field) => Option.getOrElse(readInput(field.state.value), () => null);
+function SecretInput({ field, spec, locked, ...control }) {
+    const [shown, setShown] = useState(false);
+    return (_jsxs(InputGroup, { children: [_jsx(Input, { ...control, name: spec.name, disabled: locked, type: shown ? "text" : "password", autoComplete: "off", spellCheck: false, className: "caps-field-secret", placeholder: spec.placeholder, readOnly: spec.readOnly, value: text(field), onBlur: field.handleBlur, onChange: (event) => {
+                    field.handleChange(event.currentTarget.value);
+                } }), _jsx(Button, { type: "button", variant: "outline", size: "icon", "aria-label": shown ? "Hide" : "Show", "aria-pressed": shown, disabled: locked, onClick: () => {
+                    setShown((current) => !current);
+                }, children: shown ? _jsx(EyeOff, { "aria-hidden": "true" }) : _jsx(Eye, { "aria-hidden": "true" }) })] }));
+}
+const inputTypes = { text: "text", email: "email", url: "url", tel: "tel" };
+/** The picker supplies File objects; queue rows use only their metadata. */
+function FileInput({ spec, field, locked, ...control }) {
+    const selected = files(field);
+    const disabled = locked || spec.readOnly === true;
+    const picker = useRef(null);
+    return (_jsxs("div", { className: "flex flex-col gap-sm", children: [_jsx(VisuallyHidden, { asChild: true, children: _jsx("input", { ...control, ref: picker, type: "file", tabIndex: -1, required: control.required === true && selected.length === 0, name: spec.name, accept: spec.accept, multiple: spec.multiple, disabled: disabled, onBlur: field.handleBlur, onChange: (event) => {
+                        field.handleChange(Array.from(event.currentTarget.files ?? []));
+                        // The queue owns the selection display, including resets and removal.
+                        // Clear the native picker so choosing the same file fires another change.
+                        event.currentTarget.value = "";
+                    } }) }), _jsx(Button, { type: "button", variant: "outline", "aria-label": `Choose files for ${spec.label}`, "aria-describedby": control["aria-describedby"], "aria-invalid": control["aria-invalid"], disabled: disabled, onBlur: field.handleBlur, onClick: () => {
+                    picker.current?.click();
+                }, children: "Choose files" }), _jsx(UploadQueue, { items: selected.map((file, index) => ({
+                    id: String(index),
+                    name: file.name,
+                    preview: { kind: "file" },
+                    progress: 0,
+                    progressLabel: `${String(file.size)} bytes`,
+                    statusLabel: "Selected",
+                    actions: disabled
+                        ? {}
+                        : {
+                            remove: {
+                                label: "Remove",
+                                accessibleLabel: `Remove ${file.name}`,
+                            },
+                        },
+                })), onRemove: (id) => {
+                    field.handleChange(selected.filter((_, index) => String(index) !== id));
+                }, onCancel: () => undefined, onRetry: () => undefined })] }));
+}
+/** One control, wired by the Field around it (Field clones these props in). */
+function SpecControl({ spec, field, locked, ...control }) {
+    const setText = (value) => {
+        field.handleChange(value);
+    };
+    const shared = {
+        ...control,
+        name: spec.name,
+        disabled: locked,
+        onBlur: field.handleBlur,
+    };
+    switch (spec.kind) {
+        case "text":
+        case "email":
+        case "url":
+        case "tel":
+            return (_jsx(Input, { ...shared, type: inputTypes[spec.kind], inputMode: spec.kind === "text" ? undefined : spec.kind, autoComplete: spec.autoComplete, placeholder: spec.placeholder, maxLength: spec.maxLength, readOnly: spec.readOnly, value: text(field), onChange: (event) => {
+                    setText(event.currentTarget.value);
+                } }));
+        case "textarea":
+            return (_jsx(Textarea, { ...shared, rows: spec.rows ?? 3, placeholder: spec.placeholder, maxLength: spec.maxLength, readOnly: spec.readOnly, value: text(field), onChange: (event) => {
+                    setText(event.currentTarget.value);
+                } }));
+        case "secret":
+            return (_jsx(SecretInput, { ...control, field: field, spec: spec, locked: locked }));
+        case "money":
+            return (_jsxs(InputGroup, { children: [_jsx(InputGroupAddon, { className: "caps-field-currency", children: spec.currency ?? "USD" }), _jsx(Input, { ...shared, inputMode: "decimal", autoComplete: "off", className: "caps-field-amount", placeholder: spec.placeholder ?? "0.00", readOnly: spec.readOnly, value: text(field), onChange: (event) => {
+                            setText(event.currentTarget.value);
+                        } })] }));
+        case "date":
+            return (_jsx(Input, { ...shared, type: "date", readOnly: spec.readOnly, value: text(field), onChange: (event) => {
+                    setText(event.currentTarget.value);
+                } }));
+        case "number":
+            return (_jsx(NumberField, { ...shared, ...(spec.min === undefined ? {} : { min: spec.min }), ...(spec.max === undefined ? {} : { max: spec.max }), ...(spec.step === undefined ? {} : { step: spec.step }), ...(spec.unit === undefined ? {} : { unit: spec.unit }), ...(spec.wrap === undefined ? {} : { wrap: spec.wrap }), disabled: locked || spec.readOnly === true, decrementLabel: `Decrease ${spec.label}`, incrementLabel: `Increase ${spec.label}`, value: amount(field), onValueChange: (value) => {
+                    field.handleChange(value);
+                } }));
+        case "select":
+            return (_jsxs(Select, { ...shared, value: text(field), onChange: (event) => {
+                    setText(event.currentTarget.value);
+                }, children: [spec.placeholder === undefined ? null : (_jsx("option", { value: "", disabled: true, children: spec.placeholder })), spec.options.map((option) => (_jsx("option", { value: option.value, disabled: option.disabled, children: option.label }, option.value)))] }));
+        case "combobox":
+            return (_jsx(Combobox, { id: control.id ?? spec.name, "aria-describedby": control["aria-describedby"], "aria-invalid": control["aria-invalid"], "aria-required": control["aria-required"], items: spec.options, getKey: (option) => option.value, getLabel: (option) => option.label, isDisabled: (option) => option.disabled || locked || spec.readOnly === true, value: text(field), ...(spec.placeholder === undefined
+                    ? {}
+                    : { placeholder: spec.placeholder }), trigger: _jsx(ComboboxTrigger, { name: spec.name, disabled: locked || spec.readOnly === true, onBlur: field.handleBlur, children: spec.options.find((option) => option.value === text(field))
+                        ?.label ??
+                        spec.placeholder ??
+                        "Choose…" }), inputProps: {
+                    "aria-label": `Search ${spec.label}`,
+                    disabled: locked || spec.readOnly === true,
+                }, onValueChange: (value) => {
+                    setText(value ?? "");
+                    field.handleBlur();
+                } }));
+        case "file":
+            return (_jsx(FileInput, { ...control, spec: spec, field: field, locked: locked }));
+        case "checkbox":
+            return (_jsx(Checkbox, { ...shared, disabled: locked || spec.readOnly === true, checked: flag(field), onChange: (event) => {
+                    field.handleChange(event.currentTarget.checked);
+                } }));
+        case "switch":
+            return (_jsx(Switch, { ...shared, disabled: locked || spec.readOnly === true, checked: flag(field), onCheckedChange: (checked) => {
+                    field.handleChange(checked);
+                } }));
+        case "radio":
+        case "icon-radio":
+        case "checkboxes":
+        case "icon-checkboxes":
+            return null;
+    }
+}
+const groupKinds = new Set([
+    "radio",
+    "icon-radio",
+    "checkboxes",
+    "icon-checkboxes",
+]);
+/** Choice groups: a legend names the group; each option names its input. */
+function SpecGroup({ spec, field, locked, error, }) {
+    const disabled = locked || spec.readOnly === true;
+    const legend = spec.label;
+    if (spec.kind === "checkboxes" || spec.kind === "icon-checkboxes") {
+        const selected = texts(field);
+        const toggle = (value, on) => {
+            field.handleChange(on
+                ? [...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
+                        ? {}
+                        : { 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);
+                    } }, option.value))) })) : (spec.options.map((option) => (_jsx(Field, { label: option.label, description: option.description, orientation: "inline", children: _jsx(Checkbox, { name: spec.name, value: option.value, disabled: option.disabled, checked: selected.includes(option.value), onBlur: field.handleBlur, onChange: (event) => {
+                        toggle(option.value, event.currentTarget.checked);
+                    } }) }, 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) => {
+                field.handleChange(next);
+                field.handleBlur();
+            }, 
+            // Icon keys and choice cards sit in a wrapping row.
+            orientation: spec.kind === "icon-radio" || cards ? "horizontal" : "vertical", children: spec.options.map((option) => spec.kind === "icon-radio" ? (_jsx(IconRadio, { value: option.value, label: option.label, ...(option.caption === undefined
+                    ? {}
+                    : { caption: option.caption }), icon: option.icon, disabled: option.disabled }, option.value)) : cards ? (_jsx(RadioGroupCard, { value: option.value, title: option.label, description: option.description, meta: option.meta, disabled: option.disabled }, option.value)) : (_jsx(Field, { label: option.label, orientation: "inline", children: _jsx(RadioGroupItem, { value: option.value, disabled: option.disabled }) }, option.value))) }) }));
+}
+/** The `render` bailout: the caller's control with the built-in wiring. */
+function RenderedControl({ spec, field, locked, error, render, ...control }) {
+    return render({
+        name: spec.name,
+        label: spec.label,
+        help: spec.help,
+        value: input(field),
+        onChange: (value) => {
+            field.handleChange(value);
+        },
+        onBlur: field.handleBlur,
+        error,
+        disabled: locked,
+        // Field clones the id and descriptions in, so its label names the control.
+        id: control.id ?? spec.name,
+        "aria-describedby": control["aria-describedby"],
+        "aria-invalid": error !== undefined,
+    });
+}
+function SchemaField({ form, spec, locked, }) {
+    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"
+            ? "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 })) }));
+}
+const readValues = Schema.decodeUnknownOption(Schema.Record(Schema.String, inputSchema));
+function Visible({ form, spec, locked, }) {
+    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 });
+}
+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 }));
+}
+/**
+ * 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, }) {
+    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 model.description.sections.map((section) => (_jsx(SectionFields, { form: form, section: section, locked: disabled }, section.id ?? "")));
+}

package/dist/form-schema.d.ts

@@ -0,0 +1,166 @@
+import type { StandardSchemaV1 } from "@tanstack/react-form";
+import { Schema } from "effect";
+import type { ReactNode } from "react";
+import * as z from "zod";
+/**
+ * The raw input one field holds: text, a number (or empty), a flag, or a set
+ * of chosen values or files. The schema turns it into the domain value at submit.
+ */
+export type FieldInput = string | number | boolean | null | undefined | readonly string[] | readonly File[];
+/** The raw values a schema form holds: one entry per field name. */
+export type FormValues = Readonly<Record<string, FieldInput>>;
+/** Every control a schema field can render as. */
+export type FieldKind = "text" | "email" | "url" | "tel" | "textarea" | "secret" | "money" | "date" | "number" | "select" | "combobox" | "file" | "radio" | "icon-radio" | "checkbox" | "switch" | "checkboxes" | "icon-checkboxes";
+/** One choice's presentation, keyed by its value in `options`. */
+export type OptionAnnotation = {
+    readonly label?: string;
+    /** A sentence under the label; radio options with one render as cards. */
+    readonly description?: string;
+    /** A short readout on a radio card's trailing edge, such as a price. */
+    readonly meta?: string;
+    /** A Sigil or App icon: choices with icons render as icon keys. */
+    readonly icon?: ReactNode;
+    /** The short legend on an icon key; `label` stays the accessible name. */
+    readonly caption?: string;
+    readonly disabled?: boolean;
+};
+/** What a `render` annotation receives: the same wiring every built-in kind gets. */
+export type FieldRenderProps<T extends FieldInput = FieldInput> = {
+    readonly name: string;
+    readonly label: string;
+    readonly help: ReactNode;
+    readonly value: T;
+    /** Set the field's raw value; validation runs as it would for a built-in kind. */
+    onChange(value: T): void;
+    /** Mark the field visited, so its error shows. */
+    readonly onBlur: () => void;
+    /** The visible error, after the person leaves the field or submits. */
+    readonly error: string | undefined;
+    readonly disabled: boolean;
+    /** Put these on the control so the Field's label, help and error name it. */
+    readonly id: string;
+    readonly "aria-describedby": string | undefined;
+    readonly "aria-invalid": boolean;
+};
+/** Presentation for one schema field. The schema stays the single source. */
+export type FieldAnnotation<T extends FieldInput = FieldInput> = {
+    /** The visible label and accessible name; defaults to the humanized key. */
+    readonly label?: string;
+    readonly help?: string;
+    /** Overrides the kind inferred from the schema type. */
+    readonly kind?: FieldKind;
+    readonly placeholder?: string;
+    /** The `sections` key this field sits in; unsectioned fields come first. */
+    readonly section?: string;
+    /** Sort position within its section; fields keep schema order otherwise. */
+    readonly order?: number;
+    /** `row` puts the control opposite its label (a settings row). */
+    readonly layout?: "stacked" | "row";
+    readonly required?: boolean;
+    /** Marks an optional field in a mostly required form. */
+    readonly optional?: boolean;
+    /** A decorative Sigil or App icon before the label. */
+    readonly icon?: ReactNode;
+    /** Labels, help and icons for literal choices, keyed by value. */
+    readonly options?: Readonly<Record<string, string | OptionAnnotation>>;
+    readonly currency?: string;
+    readonly unit?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly wrap?: boolean;
+    readonly rows?: number;
+    readonly maxLength?: number;
+    readonly autoComplete?: string;
+    /** Native file-picker filter; the schema owns file-type validation. */
+    readonly accept?: string;
+    readonly multiple?: boolean;
+    /** Per-file byte limit, enforced by the field's schema check. */
+    readonly maxBytes?: number;
+    readonly readOnly?: boolean;
+    /** Show the field only while this holds for the current raw values. */
+    when?(values: FormValues): boolean;
+    /**
+     * The bailout: draw this field's control yourself. Caps still owns the
+     * label, help, error, layout, validation and save bar.
+     */
+    render?(field: FieldRenderProps<T>): ReactNode;
+};
+/** A titled group of fields, declared on the struct. */
+export type SectionAnnotation = {
+    readonly title: string;
+    readonly description?: string;
+};
+/** Holds a field annotation inside schema annotations (Effect or Zod). */
+export declare class FieldMeta {
+    readonly annotation: FieldAnnotation;
+    constructor(annotation: FieldAnnotation);
+}
+/** Holds the section list inside a struct's annotations. */
+export declare class SectionsMeta {
+    readonly sections: Readonly<Record<string, SectionAnnotation>>;
+    constructor(sections: Readonly<Record<string, SectionAnnotation>>);
+}
+declare const formKey = "caps/form";
+/** Schema annotations for one field: Effect `.annotate()` or Zod `.meta()`. */
+export type FieldAnnotations = Record<`caps/form:${number}`, FieldMeta> & {
+    title?: string;
+    description?: string;
+};
+/** Schema annotations for a struct's sections. */
+export type SectionAnnotations = {
+    readonly [formKey]: SectionsMeta;
+};
+/**
+ * Annotate a schema field for forms. Works with Effect
+ * (`Schema.String.annotate(field({ … }))`) and Zod (`z.string().meta(field({ … }))`).
+ * `label` and `help` also become the schema's `title` and `description`.
+ */
+export declare function field<T extends FieldInput = FieldInput>(annotation: FieldAnnotation<T>): FieldAnnotations;
+/** Annotate a struct with its sections, in display order. */
+export declare function sections(list: Readonly<Record<string, SectionAnnotation>>): SectionAnnotations;
+/** A key or token: masked, never autofilled, with a reveal key. */
+export declare const Secret: Schema.brand<Schema.String, "Secret">;
+/** One choice, resolved for rendering. */
+export type ResolvedOption = {
+    readonly value: string;
+    readonly label: string;
+    readonly description: string | undefined;
+    readonly meta: string | undefined;
+    readonly icon: ReactNode;
+    readonly caption: string | undefined;
+    readonly disabled: boolean;
+};
+/** One field, resolved from the schema for rendering. */
+export type ResolvedField = Omit<FieldAnnotation, "options" | "kind" | "help"> & {
+    readonly help: string | undefined;
+    readonly name: string;
+    readonly label: string;
+    readonly kind: FieldKind;
+    readonly options: readonly ResolvedOption[];
+    readonly optionalInSchema: boolean;
+    readonly index: number;
+};
+/** A section and its fields, in display order. */
+export type ResolvedSection = {
+    readonly id: string | null;
+    readonly title: string | undefined;
+    readonly description: string | undefined;
+    readonly fields: readonly ResolvedField[];
+};
+/** Everything a form needs from its schema. */
+export type FormDescription = {
+    readonly sections: readonly ResolvedSection[];
+    readonly fields: readonly ResolvedField[];
+    readonly defaults: FormValues;
+};
+/** Read a form's fields, sections and empty defaults from its schema. */
+export declare function describeSchema(schema: Schema.Top | z.ZodType): FormDescription;
+/**
+ * A form schema: an Effect `Schema.Struct` (the house path) or a Zod object.
+ * `V` is the raw input the controls hold; `Out` is what the submit receives.
+ */
+export type FormSchema<V extends FormValues = FormValues, Out = unknown> = Schema.Codec<Out, V> | z.ZodType<Out, V>;
+/** The schema as a Standard Schema validator for TanStack Form. */
+export declare function standardSchema<V extends FormValues, Out>(schema: FormSchema<V, Out>): StandardSchemaV1<V, Out>;
+export {};