@cssints/headless 0.7.0 → 0.9.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,63 @@ 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 has no `role=alert`: announcing it when it appears is the host's (`createAlert`).
+
+## 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. A focus trap and a scroll lock are the host's, as for dialog-modal.
+- `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,80 @@ export interface DialogModal {
  * are requests the host may ignore.
  */
 export declare const createDialogModal: (options?: DialogModalOptions) => DialogModal;
+export interface ConfirmOptions {
+  readonly id?: string;
+  /** 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;
+  /** Default `"Confirm"`. */
+  readonly confirmLabel?: string;
+  /** Default `"Cancel"`. */
+  readonly cancelLabel?: string;
+  /** The confirm action destroys something: the host styles it so. */
+  readonly destructive?: boolean;
+}
+/** 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. A focus trap and a scroll lock are
+ * the host's (as for dialog-modal).
+ *
+ * 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 +1455,73 @@ 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;
+  readonly required?: boolean;
+  /**
+   * `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;
+}
+/** 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; absent when neither is. */
+  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;
+}
+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. */
+  readonly describedIds: () => readonly string[];
+  readonly controlProps: FieldControlProps;
+  readonly labelProps: FieldLabelProps;
+  readonly hintProps: FieldMessageProps;
+  readonly errorProps: FieldMessageProps;
+}
+/**
+ * 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 has no
+ * `role=alert`: announcing it is the host's (compose `createAlert`).
+ *
+ * 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,112 @@ const createDialogModal = (options = {}) => {
 		}
 	};
 };
+// src/confirm.ts
+var ConfirmPendingError = class extends Error {
+	name = "ConfirmPendingError";
+	constructor() {
+		super("a confirmation is already pending");
+	}
+};
+/**
+* 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. A focus trap and a scroll lock are
+* the host's (as for dialog-modal).
+*
+* 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);
+		}
+	});
+	createEffect(() => dialog.open(), (isOpen) => {
+		if (isOpen) document.getElementById(cancelId)?.focus();
+	});
+	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 +2825,76 @@ const createFeed = (options = {}) => {
 		}
 	};
 };
+// src/field.ts
+const text = (value) => value === void 0 || value === "" ? void 0 : value;
+/**
+* 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 has no
+* `role=alert`: announcing it is the host's (compose `createAlert`).
+*
+* 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]];
+	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;
+			}
+		}
+	};
+};
 // src/grid.ts
 const GRID_KEYS = /* @__PURE__ */ new Set([
 	"ArrowRight",
@@ -7239,4 +7415,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.7.0",
+  "version": "0.9.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": {