@cssints/headless 0.9.0 → 0.11.0

package/README.md

@@ -150,7 +150,9 @@ const field = createField({
 - **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`).
+- **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
 
@@ -177,7 +179,10 @@ const remove = async () => {
 
 - `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.
+- **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

package/dist/index.d.mts

@@ -1295,19 +1295,22 @@ export interface DialogModal {
  */
 export declare const createDialogModal: (options?: DialogModalOptions) => DialogModal;
 export interface ConfirmOptions {
-  readonly id?: string;
+  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;
-  /** Default `"Confirm"`. */
-  readonly confirmLabel?: string;
-  /** Default `"Cancel"`. */
-  readonly cancelLabel?: 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;
+  readonly destructive?: boolean | undefined;
 }
 /** The request being shown (or shown last), with the defaults applied. */
 export interface ConfirmView {
@@ -1359,8 +1362,19 @@ export declare class ConfirmPendingError extends Error {
  * 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).
+ * 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
@@ -1457,8 +1471,8 @@ export interface Feed {
 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;
+  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,
@@ -1470,11 +1484,19 @@ export interface FieldOptions {
   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; absent when neither is. */
+  /** 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`). */
@@ -1490,18 +1512,25 @@ 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. */
+  /**
+   * 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: FieldMessageProps;
+  readonly errorProps: FieldErrorProps;
 }
 /**
  * The ARIA contract of a form field: a label, a control, a hint and an error.
@@ -1516,8 +1545,14 @@ export interface Field {
  * 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`).
+ * 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.
  */

package/dist/index.mjs

@@ -2591,6 +2591,21 @@ var ConfirmPendingError = class extends Error {
 		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/).
@@ -2600,8 +2615,19 @@ var ConfirmPendingError = class extends Error {
 * 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).
+* 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
@@ -2633,8 +2659,44 @@ const createConfirm = (options = {}) => {
 			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) document.getElementById(cancelId)?.focus();
+		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);
@@ -2827,6 +2889,7 @@ 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
@@ -2840,8 +2903,14 @@ const text = (value) => value === void 0 || value === "" ? void 0 : value;
 * 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`).
+* 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.
 */
@@ -2855,7 +2924,11 @@ const createField = (options = {}) => {
 	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]];
+	const describedIds = () => [
+		...hint() === void 0 ? [] : [hintId],
+		...error() === void 0 ? [] : [errorId],
+		...external(options.describedby)
+	];
 	return {
 		invalid,
 		hint,
@@ -2891,6 +2964,9 @@ const createField = (options = {}) => {
 			id: errorId,
 			get hidden() {
 				return error() === void 0;
+			},
+			get role() {
+				return error() === void 0 ? void 0 : "alert";
 			}
 		}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssints/headless",
-  "version": "0.9.0",
+  "version": "0.11.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": {