{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"settings-form","type":"registry:component","title":"Settings form","description":"A settings page that saves the way people expect: switches save themselves, text edits gather into one bar that rises with \"2 unsaved changes\".","author":"Hairline UI","dependencies":[],"registryDependencies":["https://hairlineui.com/r/text-morph.json?as=dependency","https://hairlineui.com/r/number-roll.json?as=dependency","https://hairlineui.com/r/status-button.json?as=dependency"],"files":[{"path":"registry/settings-form.tsx","type":"registry:component","content":"// Hairline UI · settings-form · MIT License\n// Copyright (c) 2026 Hairline UI · https://hairlineui.com/license#components\n\n\"use client\";\n\nimport * as React from \"react\";\nimport { NumberRoll } from \"./number-roll\";\nimport { StatusButton, type ActionStatus } from \"./status-button\";\nimport { TextMorph } from \"./text-morph\";\n\n/* ─────────────────────────────────────────────────────────\n * SETTINGS FORM: a settings page that saves the way people\n * expect it to\n *\n * switch toggles and choices save the moment they change:\n * the thumb is thrown across, \"Saving\" opens beside\n * the label, a check draws and fades. If the server\n * says no, the thumb is thrown back with a shake\n * and the reason opens under the field\n * edit text edits wait for you: a dot swells beside each\n * changed label and one bar rises at the foot of\n * the form, \"2 unsaved changes\", rolling as you go\n * check a field with an async check (is this address\n * free?) asks a moment after you stop typing:\n * \"Checking\", then \"Available\" or why not\n * save Save (or ⌘S) sends just what changed; the bar says\n * Saving, then Saved, and folds away. Errors your\n * server sends per field open under those fields\n * and focus goes to the first\n * reset the edits blur back to what's saved\n *\n * Fields are plain objects; onSave gets only the changed values\n * and returns what was stored.\n * ───────────────────────────────────────────────────────── */\n\nexport type SettingsValue = string | boolean;\nexport type SettingsValues = Record;\n\ntype Base = { name: string; label: string; description?: string };\n\nexport type SettingsField =\n | (Base & { type: \"toggle\" })\n | (Base & { type: \"choice\"; options: { value: string; label: string }[] })\n | (Base & {\n type: \"text\" | \"textarea\";\n placeholder?: string;\n /** Shown inside the field before the value, e.g. \"relay.app/\". */\n prefix?: string;\n /** Textarea height in lines. */\n rows?: number;\n maxLength?: number;\n inputMode?: React.HTMLAttributes[\"inputMode\"];\n autoComplete?: string;\n /** Return a message to refuse the value before it's sent. */\n validate?: (value: string, values: SettingsValues) => string | null | undefined | void;\n /** Asked a moment after typing stops: return null when the value is fine, or why it isn't. */\n check?: (value: string, options: { signal: AbortSignal }) => Promise;\n /** What a passed check says. */\n checkPassed?: string;\n });\n\nexport interface SettingsSection {\n title: string;\n description?: string;\n fields: SettingsField[];\n}\n\n/** Throw this from onSave to put messages under particular fields. */\nexport class SettingsFormError extends Error {\n fields: Record;\n constructor(message: string, fields: Record = {}) {\n super(message);\n this.name = \"SettingsFormError\";\n this.fields = fields;\n }\n}\n\nexport interface SettingsFormProps extends Omit, \"defaultValue\" | \"onChange\"> {\n sections: SettingsSection[];\n /** Saved values, controlled. */\n value?: SettingsValues;\n defaultValue?: SettingsValues;\n /** The saved values after every successful save. */\n onValueChange?: (values: SettingsValues) => void;\n /** Saves the changed values. Return what was stored (or nothing); throw to keep the edits and say why. */\n onSave: (patch: SettingsValues, values: SettingsValues) => Promise | SettingsValues | void;\n /** Toggles and choices save the moment they change. */\n autosave?: boolean;\n /** Ask before leaving the page with unsaved edits. */\n warnOnLeave?: boolean;\n}\n\ntype Check = { state: \"checking\" | \"ok\" | \"no\"; message: string };\ntype TextField = Extract;\n\nconst EASE = \"cubic-bezier(0.16,1,0.3,1)\";\nconst THROW = \"cubic-bezier(0.34,1.36,0.64,1)\";\nconst FOCUS = \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40\";\nconst EMPTY: SettingsValues = {};\nconst SHAKE = [{ transform: \"none\" }, { transform: \"translateX(-4px)\" }, { transform: \"translateX(4px)\" }, { transform: \"translateX(-2px)\" }, { transform: \"none\" }];\n\nconst reducedQuery = \"(prefers-reduced-motion: reduce)\";\nconst subscribeReduced = (onChange: () => void) => {\n const query = window.matchMedia(reducedQuery);\n query.addEventListener(\"change\", onChange);\n return () => query.removeEventListener(\"change\", onChange);\n};\nconst useReducedMotion = () =>\n React.useSyncExternalStore(subscribeReduced, () => window.matchMedia(reducedQuery).matches, () => false);\n\nconst without = (o: Record, keys: string[]) => Object.fromEntries(Object.entries(o).filter(([k]) => !keys.includes(k))) as Record;\nconst message = (e: unknown, fallback: string) => (e instanceof Error && e.message ? e.message : fallback);\n\nfunction DrawnCheck({ drawn, reduced, className = \"size-3.5\" }: { drawn: boolean; reduced: boolean; className?: string }) {\n return (\n \n \n \n );\n}\n\nfunction Spinner({ on }: { on: boolean }) {\n return ;\n}\n\n/** Text that changes by lifting the old line out through a blur and the new one in (sentences don't morph letter by letter). */\nfunction Line({ text, className = \"\", reduced }: { text: string; className?: string; reduced: boolean }) {\n const [shown, setShown] = React.useState(text);\n const [leaving, setLeaving] = React.useState<{ key: number; text: string }[]>([]);\n const key = React.useRef(0);\n const ref = React.useRef(null);\n if (text !== shown) {\n if (!reduced && shown) setLeaving((l) => [...l, { key: ++key.current, text: shown }]);\n setShown(text);\n }\n React.useLayoutEffect(() => {\n if (reduced || !ref.current || !leaving.length) return;\n ref.current.animate([{ opacity: 0, transform: \"translateY(4px)\", filter: \"blur(3px)\" }, { opacity: 1, transform: \"none\", filter: \"blur(0px)\" }], { duration: 320, delay: 60, easing: EASE, fill: \"backwards\" });\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [shown]);\n return (\n \n \n {shown}\n \n {leaving.map((l) => (\n setLeaving((all) => all.filter((x) => x.key !== l.key))} />\n ))}\n \n );\n}\n\nfunction LeavingLine({ text, onDone }: { text: string; onDone: () => void }) {\n const ref = React.useRef(null);\n React.useLayoutEffect(() => {\n const a = ref.current?.animate([{ opacity: 1, filter: \"blur(0px)\" }, { opacity: 0, transform: \"translateY(-4px)\", filter: \"blur(3px)\" }], { duration: 200, easing: EASE, fill: \"forwards\" });\n if (a) a.onfinish = onDone;\n return () => a?.cancel();\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, []);\n return (\n \n {text}\n \n );\n}\n\n/** A block that opens and closes by height, keeping its last children while it closes. */\nfunction Fold({ open, reduced, children }: { open: boolean; reduced: boolean; children: React.ReactNode }) {\n const kept = React.useRef(children);\n if (open) kept.current = children;\n return (\n
\n
{open ? children : kept.current}
\n
\n );\n}\n\n/** \"Saving\" → \"Saved\" beside a label that saved itself; it fades once it's said it. */\nfunction SavedMark({ status, reduced }: { status: ActionStatus; reduced: boolean }) {\n const open = status !== \"idle\";\n const [label, setLabel] = React.useState(\"Saving\");\n const next = status === \"pending\" ? \"Saving\" : status === \"success\" ? \"Saved\" : status === \"error\" ? \"Not saved\" : label;\n if (next !== label) setLabel(next);\n return (\n \n \n \n \n \n \n \n \n \n \n \n {label}\n \n \n \n );\n}\n\nfunction Label({ field, htmlFor, dirty, status, reduced, id }: { field: SettingsField; htmlFor?: string; dirty: boolean; status: ActionStatus; reduced: boolean; id: string }) {\n const Tag = htmlFor ? \"label\" : \"span\";\n return (\n \n \n {field.label}\n {/* A dot that swells in beside a label whose value has changed but isn't saved. */}\n \n \n \n {field.description && (\n \n {field.description}\n \n )}\n \n );\n}\n\nfunction Switch({ on, onToggle, labelledBy, describedBy, shake, reduced }: { on: boolean; onToggle: () => void; labelledBy: string; describedBy?: string; shake: number; reduced: boolean }) {\n const ref = React.useRef(null);\n React.useEffect(() => {\n if (shake && !reduced) ref.current?.animate(SHAKE, { duration: 380, easing: \"ease-out\" });\n }, [shake, reduced]);\n return (\n \n \n \n );\n}\n\nfunction Choice({ field, value, onChange, labelledBy, shake, reduced }: { field: Extract; value: string; onChange: (v: string) => void; labelledBy: string; shake: number; reduced: boolean }) {\n const wrap = React.useRef(null);\n const refs = React.useRef<(HTMLButtonElement | null)[]>([]);\n const [thumb, setThumb] = React.useState({ left: 0, width: 0, ready: false });\n const index = Math.max(0, field.options.findIndex((o) => o.value === value));\n\n React.useLayoutEffect(() => {\n const measure = () => {\n const b = refs.current[index];\n if (!b) return;\n setThumb((t) => (t.left === b.offsetLeft && t.width === b.offsetWidth && t.ready ? t : { left: b.offsetLeft, width: b.offsetWidth, ready: t.width > 0 }));\n };\n measure();\n const observer = new ResizeObserver(measure);\n if (wrap.current) observer.observe(wrap.current);\n return () => observer.disconnect();\n }, [index]);\n\n React.useEffect(() => {\n if (shake && !reduced) wrap.current?.animate(SHAKE, { duration: 380, easing: \"ease-out\" });\n }, [shake, reduced]);\n\n return (\n
\n \n {field.options.map((o, i) => {\n const on = i === index;\n return (\n {\n refs.current[i] = el;\n }}\n type=\"button\"\n role=\"radio\"\n aria-checked={on}\n tabIndex={on ? 0 : -1}\n onClick={() => onChange(o.value)}\n onKeyDown={(e) => {\n const step = e.key === \"ArrowRight\" || e.key === \"ArrowDown\" ? 1 : e.key === \"ArrowLeft\" || e.key === \"ArrowUp\" ? -1 : 0;\n if (!step) return;\n e.preventDefault();\n const next = (i + step + field.options.length) % field.options.length;\n onChange(field.options[next].value);\n refs.current[next]?.focus();\n }}\n className={`relative h-7 cursor-pointer rounded-full px-3 text-[12px] font-medium transition-colors duration-300 ${FOCUS} ${on ? \"text-foreground\" : \"text-muted-foreground hover:text-foreground\"}`}\n >\n {o.label}\n \n );\n })}\n
\n );\n}\n\nfunction TextInput({\n field,\n id,\n value,\n error,\n check,\n onChange,\n reduced,\n register,\n}: {\n field: TextField;\n id: string;\n value: string;\n error?: string;\n check?: Check;\n onChange: (v: string) => void;\n reduced: boolean;\n register: (name: string, el: HTMLInputElement | HTMLTextAreaElement | null) => void;\n}) {\n const ring = error || check?.state === \"no\" ? \"shadow-[inset_0_0_0_1px_color-mix(in_oklab,var(--color-red-500)_45%,transparent)]\" : \"shadow-[inset_0_0_0_1px_var(--border)] focus-within:shadow-[inset_0_0_0_1px_var(--ring)]\";\n const common = {\n id,\n name: field.name,\n value,\n placeholder: field.placeholder,\n maxLength: field.maxLength,\n \"aria-invalid\": Boolean(error || check?.state === \"no\") || undefined,\n \"aria-describedby\": `${id}-desc ${id}-note`,\n onChange: (e: React.ChangeEvent) => onChange(e.target.value),\n };\n const text = \"bg-transparent text-[16px] text-foreground outline-none placeholder:text-muted-foreground/70 [@media(pointer:fine)]:text-[13.5px]\";\n return (\n
\n {field.type === \"textarea\" ? (\n