@cssints/headless 0.8.0 → 0.10.0

package/README.md

@@ -65,7 +65,7 @@ A primitive that has a seam honours an optional `prefs` entry (a `Partial<Prefs>
 - **menu / menubar** — `typeaheadDelayMs` (the typeahead buffer timeout).
 - **tooltip** — `tooltipShowDelayMs` / `tooltipHideDelayMs`, exposed as `showDelayMs()` / `hideDelayMs()` for the host to wire its `setTimeout` from (the spec keeps timers as events).
 
-Everything else **ignores** prefs: accordion, alert, alertdialog, breadcrumb, button, carousel, checkbox, checkbox-group, combobox, dialog-modal, disclosure, feed, grid, link, listbox, meter, player, radio, resizable-panels, slider, slider-multithumb, spinbutton, switch, tabs, timeline, toolbar, treegrid, treeview, windowsplitter — they expose no timing / motion / live-region / camera seam. `listbox` / `treeview` / `timeline` typeahead timeouts are host-driven via their reset methods, so they take no delay here either.
+Everything else **ignores** prefs: accordion, alert, alertdialog, breadcrumb, button, carousel, checkbox, checkbox-group, combobox, confirm, dialog-modal, disclosure, feed, field, grid, link, listbox, meter, player, radio, resizable-panels, slider, slider-multithumb, spinbutton, switch, tabs, timeline, toolbar, treegrid, treeview, windowsplitter — they expose no timing / motion / live-region / camera seam. `listbox` / `treeview` / `timeline` typeahead timeouts are host-driven via their reset methods, so they take no delay here either.
 
 `motionDurationMs` is **not consumed**: canvas tweens are tick-driven, not millisecond-driven, and the look layer owns durations. It stays in `Prefs` only so a host's preference record fits the type.
 
@@ -123,6 +123,68 @@ Controlled is `sizes` + `onSizesChange` (the request), like every other primitiv
 
 Left to the host: pane bounds in pixels (percent only), nested groups, and F6 (with three panes a Tab is enough). Not modelled: react-resizable-panels' collapse-on-drag threshold (a pane collapses on Enter or a host write, never by dragging through MIN) and restoring a pane that was mounted already collapsed (it returns to its own `min`).
 
+## Form field
+
+`createField` is the ARIA contract of a form field: a label, a control, a hint and an error. **There is no APG pattern for it**, so there is no Quint spec and no ported scenarios: the contract is WAI-ARIA (`aria-describedby`, `aria-invalid`, `aria-required`) and HTML (`label[for]`, `required`), and where those are silent the majority of Base UI Field, react-aria TextField and ariakit FormControl. `test/field.browser.test.tsx` is its oracle (plain assertions on the attribute objects; no DOM is needed, the file name is only what `vite.config.ts` includes).
+
+```tsx
+const field = createField({
+  required: true,
+  hint: "At least 8 characters",
+  get invalid() {
+    return touched() && password().length < 8;
+  },
+  get error() {
+    return "Too short";
+  },
+});
+
+<label {...field.labelProps}>Password</label>
+<input type="password" {...field.controlProps} />
+<p {...field.hintProps}>{field.hint()}</p>
+<p {...field.errorProps}>{field.error()}</p>;
+```
+
+- **Ids** are `<id>-control`, `-label`, `-hint`, `-error` from `id` (or a unique one); `labelProps.for` is the control's id.
+- **Render the hint and the error elements always.** They carry `hidden` while absent, and `aria-describedby` lists only the ones that are shown, hint first: a reference never points at a hidden or missing id.
+- **The error does not replace the hint.** Both are listed, hint then error, as Base UI, react-aria and ariakit do: the hint is what tells the user how to fix the error.
+- **`aria-invalid` only when invalid.** An error message makes the field invalid; `invalid: "message"` is both the flag and the message (an `error` wins over it); `invalid: true` without a message marks the control and shows no error; `invalid: false` wins over everything, so a host can keep the message ready and pass `touched() && failed()`.
+- **`required`** sets both `required` and `aria-required` (a native control needs the first, a custom widget the second); use `novalidate` on the form if the browser's own bubbles are not wanted.
+- **The error announces itself.** `errorProps.role` is `"alert"` while the error is shown and `undefined` while it is hidden, so spreading `errorProps` is all the host does (no hand-written `role={field.error() === undefined ? undefined : "alert"}`); an element that is hidden announces nothing, and one that appears is announced. The hint stays a plain element: `hintProps` has no `role`.
+- **One refusal that belongs to two controls.** `describedby` is an id, or a list of ids, of an element the host owns, appended to `aria-describedby` after the field's own hint and error ids (`password-hint password-error form-error`) and dropped when empty. Give a form-level error ("The passwords do not match") one element with its own id and `role`, and pass that id to both fields: each control then names the same message, and it is announced once, not once per field. The field cannot see whether that element is shown, so pass the id only while it is (a getter: `get describedby() { return mismatch() ? "form-error" : undefined; }`); `describedIds()` includes it.
+- **Getters that return `undefined` typecheck.** `id`, `required`, `invalid`, `hint`, `error` and `describedby` are all `T | undefined`, so a getter over an optional prop (`get required() { return props.required; }`) compiles under `exactOptionalPropertyTypes`.
+
+## Confirm
+
+`createConfirm` is a promise-based confirmation over `createDialogModal({ role: "alertdialog" })`. Like the field it is not checked against a spec (the dialog is; `test/confirm.browser.test.tsx` covers the promise around it, in Chromium).
+
+```tsx
+const confirm = createConfirm();
+
+const remove = async () => {
+  if (await confirm.confirm({ title: "Delete post?", description: "This cannot be undone.", confirmLabel: "Delete", destructive: true })) {
+    await deletePost();
+  }
+};
+
+<button {...confirm.triggerProps} onClick={remove}>Delete</button>
+<div {...confirm.backdropProps} />
+<div {...confirm.dialogProps}>
+  <h2 {...confirm.titleProps}>{confirm.request()?.title}</h2>
+  <p {...confirm.descriptionProps}>{confirm.request()?.description}</p>
+  <button {...confirm.cancelProps}>{confirm.request()?.cancelLabel}</button>
+  <button {...confirm.confirmProps}>{confirm.request()?.confirmLabel}</button>
+</div>;
+```
+
+- `confirm(request)` resolves `true` on the confirm button, `false` on cancel, Escape or a click on the backdrop. `onOpenChange` fires when it opens and when it settles.
+- **One request at a time.** A second `confirm()` while one is pending **rejects** with `ConfirmPendingError` and leaves the first alone; it is not queued (a double click on "Delete" would ask twice, and a queued question can outlive the screen that asked it). A pending request is answered `false` when the owner is disposed.
+- **Focus.** The cancel button takes focus on open (the least destructive action); on settle focus returns to the element that had it when `confirm()` was called, before the promise resolves, so the caller may move it on.
+- **The dialog shell, while it is open.** Tab and Shift+Tab cycle among the dialog's tabbable elements (from the last to the first and back; a focus that escaped is pulled in on the next Tab; with nothing tabbable the dialog itself keeps it). `overflow: hidden` is set on `document.documentElement` and the inline value it had is restored on close, on dispose and on every way the request settles; add `scrollbar-gutter: stable` to the page if the vanished scrollbar must not shift the layout (the lock does not pad for it). Escape is read from the **document**, in the capture phase, so it answers `false` wherever the focus is, and it stops there: the elements around the dialog (a dialog the confirm sits in) do not see it. The backdrop click is `backdropProps`, as before; keep the backdrop and the dialog siblings, or a click inside the dialog reaches the backdrop. Making the rest of the page `inert` or `aria-hidden` is still the host's.
+- **Nesting.** Confirms from different `createConfirm` calls may be open together (a "discard changes?" over a "delete?" that opened it): the one opened last gets Escape and Tab, the one under it waits, and the scroll lock is counted, so the first takes it and the last to close restores it. One `createConfirm` is still one request at a time. A `createDialogModal` that is open under a confirm knows nothing of this stack.
+- **Labels are the host's.** The defaults, `"Confirm"` and `"Cancel"`, stay English. An app that translates passes `confirmLabel` and `cancelLabel` (and the `title`) with each request, `confirm({ title: t("unsaved"), confirmLabel: t("discard"), cancelLabel: t("keep") })`; a label left out, or `undefined`, falls back to the English default. Nothing in the options needed to change for this: `ConfirmRequest` already carried both labels.
+- `aria-labelledby` is the title and `aria-describedby` **always** the description (an alertdialog needs one), so render `descriptionProps` always: it is `hidden` when the request has no description. `triggerProps` are dialog-modal's trigger attributes without the handlers; the click that calls `confirm()` is the host's. `request()` keeps the last request after it settles, so a closing animation does not flash empty.
+
 ## Commands
 
 ```sh

package/dist/index.d.mts

@@ -1294,6 +1294,94 @@ export interface DialogModal {
  * are requests the host may ignore.
  */
 export declare const createDialogModal: (options?: DialogModalOptions) => DialogModal;
+export interface ConfirmOptions {
+  readonly id?: string | undefined;
+  /** Called with `true` when a request opens the dialog and `false` when it settles. */
+  readonly onOpenChange?: (open: boolean) => void;
+}
+export interface ConfirmRequest {
+  readonly title: string;
+  readonly description?: string | undefined;
+  /**
+   * Default `"Confirm"`. The defaults are English and stay so: a host that
+   * translates passes both labels (and the title) with every request.
+   */
+  readonly confirmLabel?: string | undefined;
+  /** Default `"Cancel"`; see `confirmLabel`. */
+  readonly cancelLabel?: string | undefined;
+  /** The confirm action destroys something: the host styles it so. */
+  readonly destructive?: boolean | undefined;
+}
+/** The request being shown (or shown last), with the defaults applied. */
+export interface ConfirmView {
+  readonly title: string;
+  readonly description: string | undefined;
+  readonly confirmLabel: string;
+  readonly cancelLabel: string;
+  readonly destructive: boolean;
+}
+/** The attributes of dialog-modal's trigger; the click that calls `confirm()` is the host's. */
+export type ConfirmTriggerProps = Omit<DialogTriggerProps, "onClick" | "onKeyDown">;
+export interface ConfirmTextProps {
+  readonly id: string;
+  readonly hidden?: boolean;
+}
+export interface ConfirmButtonProps {
+  readonly id: string;
+  readonly type: "button";
+  readonly onClick: () => void;
+}
+export interface Confirm {
+  /**
+   * Opens the dialog and resolves with the answer: `true` on confirm, `false`
+   * on cancel, Escape or a backdrop click. A request made while one is pending
+   * rejects with `ConfirmPendingError` and leaves the pending one alone.
+   */
+  readonly confirm: (request: ConfirmRequest) => Promise<boolean>;
+  readonly open: Accessor<boolean>;
+  readonly request: Accessor<ConfirmView | undefined>;
+  readonly triggerProps: ConfirmTriggerProps;
+  readonly dialogProps: DialogContentProps;
+  readonly backdropProps: DialogBackdropProps;
+  readonly titleProps: ConfirmTextProps;
+  /** Render this element always: `aria-describedby` points at it. Hidden when there is no description. */
+  readonly descriptionProps: ConfirmTextProps;
+  readonly cancelProps: ConfirmButtonProps;
+  readonly confirmProps: ConfirmButtonProps;
+}
+export declare class ConfirmPendingError extends Error {
+  readonly name = "ConfirmPendingError";
+  constructor();
+}
+/**
+ * A promise-based confirmation over `createDialogModal({ role: "alertdialog" })`
+ * (APG Alert Dialog: https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/).
+ * Not checked against a Quint spec: the dialog is, the promise around it is
+ * covered by `test/confirm.browser.test.tsx`.
+ *
+ * Focus: the cancel button, the least destructive action, takes focus when the
+ * dialog opens; when the request settles, focus goes back to the element that
+ * had it when `confirm()` was called, before the promise resolves, so the
+ * caller's continuation may move it again.
+ *
+ * The shell, while open: Tab and Shift+Tab cycle inside the dialog (and pull
+ * focus back in if it escaped), `overflow: hidden` on the document element, and
+ * Escape is read from the document in the capture phase, so it answers `false`
+ * wherever focus is. The backdrop click is `backdropProps`; keep the backdrop
+ * and the dialog siblings, or a click in the dialog reaches the backdrop. Hiding
+ * the rest of the page (`inert`) stays the host's.
+ *
+ * Nesting: confirms from different `createConfirm` calls may be open together;
+ * only the last one opened gets Escape and Tab (and Escape does not reach a
+ * dialog it sits in), and the scroll lock is counted: the first takes it, the
+ * last to close restores what `overflow` was. One confirm still has one request.
+ *
+ * One request at a time: a second `confirm()` while one is pending is rejected,
+ * not queued. Queued, a double click on "Delete" would ask twice and a stale
+ * question could outlive the screen that asked it. A pending request is
+ * answered `false` when the owner is disposed.
+ */
+export declare const createConfirm: (options?: ConfirmOptions) => Confirm;
 /**
  * Options are read lazily (getters); pass a component's `props`.
  */
@@ -1381,6 +1469,94 @@ export interface Feed {
  * request; `loadStart` / `loadFail` are adapter lifecycle events.
  */
 export declare const createFeed: (options?: FeedOptions) => Feed;
+export interface FieldOptions {
+  /** Base of every id the field makes (`<id>-control`, `-label`, `-hint`, `-error`). */
+  readonly id?: string | undefined;
+  readonly required?: boolean | undefined;
+  /**
+   * `true` marks the control invalid; a string does too and is the error message
+   * (unless `error` is set). `false` forces valid: an `error` is then not shown,
+   * so a host can pass `touched() && failed()` and keep the message ready.
+   * Left out, the field is invalid exactly when it has an error message.
+   */
+  readonly invalid?: boolean | string | undefined;
+  /** Help text; absent (or empty) means the hint element is hidden and not referenced. */
+  readonly hint?: string | undefined;
+  /** The error message; absent (or empty) means no error element. */
+  readonly error?: string | undefined;
+  /**
+   * Ids of elements the host owns, appended to `aria-describedby` after the
+   * field's own hint and error: a form-level error that belongs to several
+   * controls ("the passwords do not match" names both). One id or a list;
+   * empty strings are dropped, and the attribute is absent when nothing is left.
+   * The host keeps that element rendered, and decides whether it is hidden.
+   */
+  readonly describedby?: string | readonly string[] | undefined;
+}
+/** Spread onto the form control (`input`, `textarea`, `select`, or a custom widget). */
+export interface FieldControlProps {
+  readonly id: string;
+  /** The ids of the hint and the error that are shown, hint first, then the host's `describedby`; absent when there are none. */
+  readonly "aria-describedby": string | undefined;
+  readonly "aria-invalid": "true" | undefined;
+  /** For a control that is not native (a native one has `required`). */
+  readonly "aria-required": "true" | undefined;
+  readonly required: true | undefined;
+}
+export interface FieldLabelProps {
+  readonly id: string;
+  readonly for: string;
+}
+/** Spread onto the hint and the error element; render both, always. */
+export interface FieldMessageProps {
+  readonly id: string;
+  readonly hidden: boolean;
+}
+/** The error element also announces itself: `role="alert"` while it is shown. */
+export interface FieldErrorProps extends FieldMessageProps {
+  readonly role: "alert" | undefined;
+}
+export interface Field {
+  readonly invalid: () => boolean;
+  /** The hint, or `undefined` when there is none. */
+  readonly hint: () => string | undefined;
+  /** The error shown: `undefined` unless the field is invalid and has a message. */
+  readonly error: () => string | undefined;
+  /**
+   * The ids `aria-describedby` lists now: hint, then error (never an id that is
+   * hidden), then the host's `describedby`.
+   */
+  readonly describedIds: () => readonly string[];
+  readonly controlProps: FieldControlProps;
+  readonly labelProps: FieldLabelProps;
+  readonly hintProps: FieldMessageProps;
+  readonly errorProps: FieldErrorProps;
+}
+/**
+ * The ARIA contract of a form field: a label, a control, a hint and an error.
+ * There is no APG pattern for it (APG has no "form field"; the nearest is the
+ * label and description rules of the accessible name computation), so the
+ * contract comes from WAI-ARIA 1.2 (`aria-describedby`, `aria-invalid`,
+ * `aria-required`) and HTML (`label[for]`, `required`), and from the
+ * majority of Base UI Field, react-aria TextField and ariakit FormControl,
+ * which list the description and the error message together. It is not checked
+ * against a Quint spec; `test/field.browser.test.tsx` is its oracle.
+ *
+ * Decisions: the error does not replace the hint, both are listed, hint first
+ * (the hint is what tells the user how to fix the error); an error implies
+ * invalid and `invalid: false` overrides it; a hidden message is never
+ * referenced, so `aria-describedby` has no dangling id. The error element is
+ * `role="alert"` only while it is shown (a hidden element announces nothing, and
+ * one that appears is announced); the hint is never an alert.
+ *
+ * `describedby` lists host-owned ids after the field's own: one refusal that
+ * belongs to two controls is one form-level element (with its own `role`), named
+ * by both. The field cannot know whether that element is shown: the host
+ * passes the id only while it is.
+ *
+ * Options are read when an attribute is read: pass getters, never destructure.
+ */
+export declare const createField: (options?: FieldOptions) => Field;
 /**
  * APG grid primitive on Solid 2: roving focus, 2-D navigation, edit mode, a
  * cell/row/column selection rectangle and sortable column headers. State plus

package/dist/index.mjs

@@ -2584,6 +2584,174 @@ const createDialogModal = (options = {}) => {
 		}
 	};
 };
+// src/confirm.ts
+var ConfirmPendingError = class extends Error {
+	name = "ConfirmPendingError";
+	constructor() {
+		super("a confirmation is already pending");
+	}
+};
+const openDialogs = [];
+let scrollLocks = 0;
+let scrollBefore = "";
+const lockScroll = () => {
+	const root = document.documentElement;
+	if (scrollLocks++ === 0) {
+		scrollBefore = root.style.overflow;
+		root.style.overflow = "hidden";
+	}
+	return () => {
+		if (--scrollLocks === 0) root.style.overflow = scrollBefore;
+	};
+};
+const TABBABLE = "a[href], button, input, select, textarea, [tabindex], [contenteditable]";
+const tabbables = (root) => Array.from(root.querySelectorAll(TABBABLE)).filter((element) => element.tabIndex >= 0 && !element.matches(":disabled") && element.getClientRects().length > 0);
+/**
+* A promise-based confirmation over `createDialogModal({ role: "alertdialog" })`
+* (APG Alert Dialog: https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/).
+* Not checked against a Quint spec: the dialog is, the promise around it is
+* covered by `test/confirm.browser.test.tsx`.
+*
+* Focus: the cancel button, the least destructive action, takes focus when the
+* dialog opens; when the request settles, focus goes back to the element that
+* had it when `confirm()` was called, before the promise resolves, so the
+* caller's continuation may move it again.
+*
+* The shell, while open: Tab and Shift+Tab cycle inside the dialog (and pull
+* focus back in if it escaped), `overflow: hidden` on the document element, and
+* Escape is read from the document in the capture phase, so it answers `false`
+* wherever focus is. The backdrop click is `backdropProps`; keep the backdrop
+* and the dialog siblings, or a click in the dialog reaches the backdrop. Hiding
+* the rest of the page (`inert`) stays the host's.
+*
+* Nesting: confirms from different `createConfirm` calls may be open together;
+* only the last one opened gets Escape and Tab (and Escape does not reach a
+* dialog it sits in), and the scroll lock is counted: the first takes it, the
+* last to close restores what `overflow` was. One confirm still has one request.
+*
+* One request at a time: a second `confirm()` while one is pending is rejected,
+* not queued. Queued, a double click on "Delete" would ask twice and a stale
+* question could outlive the screen that asked it. A pending request is
+* answered `false` when the owner is disposed.
+*/
+const createConfirm = (options = {}) => {
+	const base = options.id ?? createUniqueId();
+	const titleId = `${base}-title`;
+	const descriptionId = `${base}-description`;
+	const cancelId = `${base}-cancel`;
+	const [request, setRequest] = createSignal(void 0);
+	let pending;
+	const settle = (answer) => {
+		const current = pending;
+		if (current === void 0) return;
+		pending = void 0;
+		dialog.close();
+		current.invoker?.focus();
+		current.resolve(answer);
+	};
+	const dialog = createDialogModal({
+		id: base,
+		role: "alertdialog",
+		labelledby: titleId,
+		describedby: descriptionId,
+		onOpenChange: (open) => {
+			if (!open) settle(false);
+			options.onOpenChange?.(open);
+		}
+	});
+	const self = Symbol(base);
+	const onDocumentKeyDown = (event) => {
+		if (openDialogs.at(-1) !== self) return;
+		if (event.key === "Escape") {
+			event.preventDefault();
+			event.stopPropagation();
+			settle(false);
+			return;
+		}
+		const root = document.getElementById(dialog.dialogProps.id);
+		if (event.key !== "Tab" || root === null) return;
+		const items = tabbables(root);
+		const first = items[0];
+		const last = items.at(-1);
+		const active = document.activeElement;
+		const inside = root.contains(active);
+		if (first === void 0 || last === void 0) {
+			event.preventDefault();
+			root.focus();
+		} else if (event.shiftKey && (!inside || active === first || active === root)) {
+			event.preventDefault();
+			last.focus();
+		} else if (!event.shiftKey && (!inside || active === last)) {
+			event.preventDefault();
+			first.focus();
+		}
+	};
+	createEffect(() => dialog.open(), (isOpen) => {
+		if (!isOpen) return;
+		document.getElementById(cancelId)?.focus();
+		const unlock = lockScroll();
+		openDialogs.push(self);
+		document.addEventListener("keydown", onDocumentKeyDown, true);
+		return () => {
+			document.removeEventListener("keydown", onDocumentKeyDown, true);
+			openDialogs.splice(openDialogs.indexOf(self), 1);
+			unlock();
+		};
+	});
+	onCleanup(() => {
+		pending?.resolve(false);
+		pending = void 0;
+	});
+	const confirm = (next) => {
+		if (pending !== void 0) return Promise.reject(new ConfirmPendingError());
+		return new Promise((resolve) => {
+			pending = {
+				resolve,
+				invoker: document.activeElement instanceof HTMLElement ? document.activeElement : null
+			};
+			setRequest({
+				title: next.title,
+				description: next.description,
+				confirmLabel: next.confirmLabel ?? "Confirm",
+				cancelLabel: next.cancelLabel ?? "Cancel",
+				destructive: next.destructive === true
+			});
+			dialog.openDialog();
+		});
+	};
+	return {
+		confirm,
+		open: dialog.open,
+		request,
+		triggerProps: {
+			id: dialog.triggerProps.id,
+			"aria-haspopup": "dialog",
+			get "aria-expanded"() {
+				return dialog.triggerProps["aria-expanded"];
+			},
+			"aria-controls": dialog.triggerProps["aria-controls"]
+		},
+		dialogProps: dialog.dialogProps,
+		backdropProps: dialog.backdropProps,
+		titleProps: { id: titleId },
+		descriptionProps: {
+			id: descriptionId,
+			get hidden() {
+				return request()?.description === void 0;
+			}
+		},
+		cancelProps: {
+			id: cancelId,
+			type: "button",
+			onClick: () => settle(false)
+		},
+		confirmProps: {
+			id: `${base}-confirm`,
+			type: "button",
+			onClick: () => settle(true)
+		}
+	};
+};
 // src/feed.ts
 /**
 * APG Feed (https://www.w3.org/WAI/ARIA/apg/patterns/feed/): state plus prop
@@ -2719,6 +2887,90 @@ const createFeed = (options = {}) => {
 		}
 	};
 };
+// src/field.ts
+const text = (value) => value === void 0 || value === "" ? void 0 : value;
+const external = (value) => (value === void 0 ? [] : typeof value === "string" ? [value] : value).filter((id) => id !== "");
+/**
+* The ARIA contract of a form field: a label, a control, a hint and an error.
+* There is no APG pattern for it (APG has no "form field"; the nearest is the
+* label and description rules of the accessible name computation), so the
+* contract comes from WAI-ARIA 1.2 (`aria-describedby`, `aria-invalid`,
+* `aria-required`) and HTML (`label[for]`, `required`), and from the
+* majority of Base UI Field, react-aria TextField and ariakit FormControl,
+* which list the description and the error message together. It is not checked
+* against a Quint spec; `test/field.browser.test.tsx` is its oracle.
+*
+* Decisions: the error does not replace the hint, both are listed, hint first
+* (the hint is what tells the user how to fix the error); an error implies
+* invalid and `invalid: false` overrides it; a hidden message is never
+* referenced, so `aria-describedby` has no dangling id. The error element is
+* `role="alert"` only while it is shown (a hidden element announces nothing, and
+* one that appears is announced); the hint is never an alert.
+*
+* `describedby` lists host-owned ids after the field's own: one refusal that
+* belongs to two controls is one form-level element (with its own `role`), named
+* by both. The field cannot know whether that element is shown: the host
+* passes the id only while it is.
+*
+* Options are read when an attribute is read: pass getters, never destructure.
+*/
+const createField = (options = {}) => {
+	const base = options.id ?? createUniqueId();
+	const controlId = `${base}-control`;
+	const labelId = `${base}-label`;
+	const hintId = `${base}-hint`;
+	const errorId = `${base}-error`;
+	const hint = () => text(options.hint);
+	const message = () => text(options.error) ?? (typeof options.invalid === "string" ? text(options.invalid) : void 0);
+	const invalid = () => options.invalid === false ? false : options.invalid === true || message() !== void 0;
+	const error = () => invalid() ? message() : void 0;
+	const describedIds = () => [
+		...hint() === void 0 ? [] : [hintId],
+		...error() === void 0 ? [] : [errorId],
+		...external(options.describedby)
+	];
+	return {
+		invalid,
+		hint,
+		error,
+		describedIds,
+		controlProps: {
+			id: controlId,
+			get "aria-describedby"() {
+				const ids = describedIds();
+				return ids.length === 0 ? void 0 : ids.join(" ");
+			},
+			get "aria-invalid"() {
+				return invalid() ? "true" : void 0;
+			},
+			get "aria-required"() {
+				return options.required === true ? "true" : void 0;
+			},
+			get required() {
+				return options.required === true ? true : void 0;
+			}
+		},
+		labelProps: {
+			id: labelId,
+			for: controlId
+		},
+		hintProps: {
+			id: hintId,
+			get hidden() {
+				return hint() === void 0;
+			}
+		},
+		errorProps: {
+			id: errorId,
+			get hidden() {
+				return error() === void 0;
+			},
+			get role() {
+				return error() === void 0 ? void 0 : "alert";
+			}
+		}
+	};
+};
 // src/grid.ts
 const GRID_KEYS = /* @__PURE__ */ new Set([
 	"ArrowRight",
@@ -7239,4 +7491,4 @@ const createRearrangeableListbox = (options) => {
 		})
 	};
 };
-export { DEFAULT_PREFS, DRAG_PX, GRID, NO_POS, SNAP_PX, TONE, TREEVIEW_NODES, TWEEN_TICKS, WORLD_BOUND, YES_POS, ZMAX, ZMIN, ZONE, cellPart, createAccordion, createAlert, createAlertDialog, createBreadcrumb, createButton, createCanvas, createCarousel, createCheckbox, createCheckboxGroup, createCombobox, createDialogModal, createDisclosure, createFeed, createGrid, createLink, createListbox, createMenu, createMenubar, createMeter, createPlayer, createRadioGroup, createRearrangeableListbox, createResizablePanels, createSlider, createSliderMultiThumb, createSpinbutton, createSwitch, createTabs, createTimeline, createToolbar, createTooltipGroup, createTreegrid, createTreeview, createWindowSplitter, gridCandidates, headerPart, packSelection, packSort, rowPart, treegridCellPart, treegridFocusTargetPart, treegridRowPart, withPrefs };
+export { ConfirmPendingError, DEFAULT_PREFS, DRAG_PX, GRID, NO_POS, SNAP_PX, TONE, TREEVIEW_NODES, TWEEN_TICKS, WORLD_BOUND, YES_POS, ZMAX, ZMIN, ZONE, cellPart, createAccordion, createAlert, createAlertDialog, createBreadcrumb, createButton, createCanvas, createCarousel, createCheckbox, createCheckboxGroup, createCombobox, createConfirm, createDialogModal, createDisclosure, createFeed, createField, createGrid, createLink, createListbox, createMenu, createMenubar, createMeter, createPlayer, createRadioGroup, createRearrangeableListbox, createResizablePanels, createSlider, createSliderMultiThumb, createSpinbutton, createSwitch, createTabs, createTimeline, createToolbar, createTooltipGroup, createTreegrid, createTreeview, createWindowSplitter, gridCandidates, headerPart, packSelection, packSort, rowPart, treegridCellPart, treegridFocusTargetPart, treegridRowPart, withPrefs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssints/headless",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Headless APG widgets on Solid 2: state plus attribute objects, no elements, no styling, each conformance-checked against its Quint spec",
   "license": "MIT",
   "repository": {