@cssints/headless 0.12.0 → 0.13.0

package/README.md

@@ -154,6 +154,41 @@ const field = createField({
 - **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`.
 
+## Text input and textarea
+
+`createTextInput` and `createTextArea` are `createField` plus the props a host forgets. **There is no APG pattern for text editing** — an `<input>` already is the pattern — so there is no Quint spec: `test/textbox.browser.test.tsx` asserts the attribute objects and the element behaviour.
+
+```tsx
+const email = createTextInput({ type: "email", autoComplete: "email", inputMode: "email", required: true });
+<label {...email.labelProps}>Email</label>
+<input {...email.controlProps} />
+```
+
+- Everything the field documents holds: ids, hint then error in `aria-describedby`, `aria-invalid` only when invalid, `role="alert"` on a shown error.
+- The extra props: `type`, `autoComplete` (the HTML token list — the browser's autofill is the accessible path), `spellCheck`, `autoCapitalize`, `inputMode`, `maxLength`, `readOnly`, `disabled`, `required`, `name`, `dir`, `placeholder`, `onValueChange` (one callback for `input`).
+- **`maxLength` is the browser's.** The primitive emits the attribute and reports the value it is given; it does not truncate in JS, because that breaks paste and IME.
+- **`disabled` vs `readOnly`.** Disabled is out of the tab order and not submitted; readOnly is focusable, selectable and submitted. A field the user must read before signing is readOnly, not disabled.
+- `createTextArea` adds `rows`, `wrap` and `resize` (`resize` is a style, since CSS has no attribute for it; `none` is what a layout that owns its own height wants).
+
+## Pagination
+
+`createPagination` is a navigation landmark over a page list. **No APG pattern exists**; the requirements are TetraLogical's (accessible-components-library v1.0.0), and `test/pagination.browser.test.tsx` is the oracle.
+
+```tsx
+const pages = createPagination({ page: 3, pageCount: 12, hrefFor: (page) => `/issues?page=${page}` });
+<nav {...pages.navProps}>
+  <ul {...pages.listProps}>{/* items() with gaps, linkProps(page) */}</ul>
+</nav>
+<p {...pages.statusProps}>{pages.status()}</p>;
+```
+
+- **One current page**, marked `aria-current="page"` on the item and its link; the current page is not a link target.
+- **The ends stay in place** and carry `aria-disabled` at the boundary instead of disappearing: a control that vanishes moves every other control under the pointer.
+- **One gap per elided run**, `siblings` (default 1) either side of the current page and `boundaries` (default 1) at each end.
+- **The count is announced once**, in a `role="status"` line ("Page 3 of 12"), not in every link. Pass `labels.status` to translate it.
+- **`hrefFor` is what makes it work without JS**: with it every page is a real link; without it they are buttons and the host owns navigation.
+- **Target size is the skin's job**: 24x24 CSS px at AA, 44x44 at AAA.
+
 ## 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).

package/dist/index.d.mts

@@ -1557,6 +1557,91 @@ export interface Field {
  * Options are read when an attribute is read: pass getters, never destructure.
  */
 export declare const createField: (options?: FieldOptions) => Field;
+export interface PaginationLabels {
+  /** The navigation landmark's name; defaults to "Pagination". */
+  readonly nav?: string | undefined;
+  readonly previous?: string | undefined;
+  readonly next?: string | undefined;
+  /** The prefix of a page link's name; defaults to "Page". */
+  readonly page?: string | undefined;
+  /** The gap between page runs; defaults to "More pages". */
+  readonly gap?: string | undefined;
+  /** The live count; defaults to `Page <page> of <count>`. */
+  readonly status?: ((page: number, count: number) => string) | undefined;
+}
+export interface PaginationOptions {
+  /** The current page, 1-based. */
+  readonly page: number;
+  readonly pageCount: number;
+  /** Pages shown on each side of the current one; defaults to 1. */
+  readonly siblings?: number;
+  /** Pages always shown at each end; defaults to 1. */
+  readonly boundaries?: number;
+  /** Where a page link points, when the host renders anchors; without it, buttons. */
+  readonly hrefFor?: ((page: number) => string) | undefined;
+  readonly disabled?: boolean;
+  readonly labels?: PaginationLabels | undefined;
+  readonly onPageChange?: ((page: number) => void) | undefined;
+}
+/** One entry of the page list: a page, or the run of pages the list elides. */
+export type PaginationItem = {
+  readonly kind: "page";
+  readonly page: number;
+  readonly current: boolean;
+} | {
+  readonly kind: "gap";
+  readonly key: string;
+};
+export interface PaginationNavProps {
+  readonly "aria-label": string;
+}
+export interface PaginationListProps {
+  readonly role: "list";
+}
+export interface PaginationItemProps {
+  readonly role: "listitem";
+  readonly "aria-current": "page" | undefined;
+}
+export interface PaginationLinkProps {
+  readonly href: string | undefined;
+  readonly "aria-current": "page" | undefined;
+  readonly "aria-disabled": "true" | undefined;
+  readonly "aria-label": string;
+  readonly rel: "prev" | "next" | undefined;
+  readonly onClick: (event: {
+    preventDefault: () => void;
+  }) => void;
+}
+export interface PaginationStatusProps {
+  readonly role: "status";
+  readonly "aria-live": "polite";
+  readonly "aria-atomic": "true";
+}
+export interface Pagination {
+  /** The page list with the elided runs, recomputed when an option changes. */
+  readonly items: () => readonly PaginationItem[];
+  readonly current: () => number;
+  readonly navProps: PaginationNavProps;
+  readonly listProps: PaginationListProps;
+  readonly itemProps: (page: number) => PaginationItemProps;
+  readonly linkProps: (page: number) => PaginationLinkProps;
+  readonly previousProps: PaginationLinkProps;
+  readonly nextProps: PaginationLinkProps;
+  /** The count, announced once here rather than in every link. */
+  readonly status: () => string;
+  readonly statusProps: PaginationStatusProps;
+}
+/**
+ * Pagination: a navigation landmark over a page list, the current page marked
+ * `aria-current=page` and never a link. No APG pattern exists for it; the
+ * requirements are TetraLogical's (accessible-components-library, v1.0.0):
+ * exactly one current page, ends kept in place and disabled rather than
+ * removed, the count announced once, and a host-supplied `href` for every link
+ * so the control works without JS.
+ *
+ * Target size is the skin's job: 24x24 CSS px at AA, 44x44 at AAA.
+ */
+export declare const createPagination: (options: PaginationOptions) => Pagination;
 /**
  * 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
@@ -2581,6 +2666,86 @@ export interface Switch {
  * pass `value` + `onValueChange` to own the state.
  */
 export declare const createSwitch: (options?: SwitchOptions) => Switch;
+/** The HTML `autocomplete` tokens worth naming; the attribute also takes an arbitrary token. */
+export type AutoCompleteToken = "off" | "on" | "name" | "given-name" | "family-name" | "username" | "email" | "tel" | "url" | "organization" | "street-address" | "postal-code" | "current-password" | "new-password" | "one-time-code" | "nickname";
+export interface TextInputOptions extends FieldOptions {
+  readonly type?: "text" | "email" | "tel" | "url" | "search" | "password";
+  /** The HTML token list: the browser's own autofill is the accessible path. */
+  readonly autoComplete?: AutoCompleteToken | undefined;
+  readonly spellCheck?: boolean | undefined;
+  readonly autoCapitalize?: "none" | "sentences" | "words" | "characters" | undefined;
+  readonly inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
+  readonly maxLength?: number | undefined;
+  readonly readOnly?: boolean | undefined;
+  readonly disabled?: boolean | undefined;
+  readonly name?: string | undefined;
+  readonly dir?: "ltr" | "rtl" | "auto" | undefined;
+  readonly placeholder?: string | undefined;
+  /** Change and input both land here; the host decides what a keystroke means. */
+  readonly onValueChange?: ((value: string) => void) | undefined;
+}
+export interface TextAreaOptions extends TextInputOptions {
+  readonly rows?: number | undefined;
+  readonly wrap?: "soft" | "hard" | "off" | undefined;
+  readonly resize?: "none" | "vertical" | "horizontal" | "both" | undefined;
+}
+export interface TextControlProps {
+  readonly id: string;
+  readonly "aria-describedby": string | undefined;
+  readonly "aria-invalid": "true" | undefined;
+  readonly "aria-required": "true" | undefined;
+  readonly required: true | undefined;
+  readonly type: TextInputOptions["type"];
+  readonly autoComplete: AutoCompleteToken | undefined;
+  readonly spellcheck: "true" | "false" | undefined;
+  readonly autocapitalize: TextInputOptions["autoCapitalize"];
+  readonly inputmode: TextInputOptions["inputMode"];
+  readonly maxlength: number | undefined;
+  readonly readOnly: true | undefined;
+  readonly disabled: true | undefined;
+  readonly name: string | undefined;
+  readonly dir: "ltr" | "rtl" | "auto" | undefined;
+  readonly placeholder: string | undefined;
+  readonly onInput: (event: {
+    currentTarget: {
+      value: string;
+    };
+  }) => void;
+}
+export interface TextAreaControlProps extends TextControlProps {
+  readonly rows: number | undefined;
+  readonly wrap: TextAreaOptions["wrap"];
+  readonly style: {
+    readonly resize: "none" | "vertical" | "horizontal" | "both";
+  } | undefined;
+}
+/** The field and the control, one object: every prop the element needs. */
+export interface TextInput extends Field {
+  readonly controlProps: TextControlProps;
+}
+export interface TextArea extends Field {
+  readonly controlProps: TextAreaControlProps;
+}
+/**
+ * A text input with the field contract attached: label, hint, error (announced),
+ * `aria-describedby` and `aria-invalid` come from `createField`; this adds the
+ * props a host forgets — autofill tokens, spellcheck, inputmode, maxlength, the
+ * disabled/readOnly pair. Platform: native (`input` is its own APG-equivalent;
+ * no primitive re-implements text editing, which is why there is no key
+ * handling here).
+ *
+ * Both `required` and `aria-required` are emitted: the native attribute is what
+ * the browser enforces, the ARIA one is what a custom widget reading the same
+ * props needs. A host that validates itself passes `noValidate` on the form
+ * rather than dropping the attribute.
+ */
+export declare const createTextInput: (options?: TextInputOptions) => TextInput;
+/**
+ * The same contract for a textarea, plus rows, wrap and resize. `resize` is a
+ * style because CSS has no attribute for it; `none` is the value a layout that
+ * owns its own height wants.
+ */
+export declare const createTextArea: (options?: TextAreaOptions) => TextArea;
 export type TabsOrientation = "horizontal" | "vertical";
 export type TabsActivation = "automatic" | "manual";
 /**

package/dist/index.mjs

@@ -1048,7 +1048,7 @@ const RATE_PERCENTS = [
 const SURFACE_SEEK_SECONDS = 5;
 const SEEK_STEP_SECONDS = 1;
 const SEEK_PAGE_SECONDS = 15;
-const clamp$2 = (value, max) => value < 0 ? 0 : value > max ? max : value;
+const clamp$3 = (value, max) => value < 0 ? 0 : value > max ? max : value;
 const mss = (seconds) => `${Math.floor(seconds / 60)}:${String(Math.floor(seconds) % 60).padStart(2, "0")}`;
 /**
 * APG media player primitive on Solid 2: playback state + attribute objects.
@@ -1085,7 +1085,7 @@ const createPlayer = (options) => {
 	const isActive = () => stage() === "playing" || stage() === "buffering";
 	const canPlay = () => stage() === "ready" || stage() === "paused" || stage() === "ended" || stage() === "buffering";
 	const moveTo = (seconds) => {
-		setPosition(clamp$2(seconds, duration()));
+		setPosition(clamp$3(seconds, duration()));
 	};
 	const play = () => {
 		if (!canPlay()) return;
@@ -1106,14 +1106,14 @@ const createPlayer = (options) => {
 	};
 	const commit = (seconds) => {
 		if (!known()) return;
-		const target = clamp$2(seconds, duration());
+		const target = clamp$3(seconds, duration());
 		if (stage() === "ended") setStage("paused");
 		moveTo(target);
 		options.onSeek?.(target);
 		options.adapter.seek(target);
 	};
 	const setVolume = (value) => {
-		requestVolume(clamp$2(value, 100));
+		requestVolume(clamp$3(value, 100));
 	};
 	const toggleMute = () => {
 		requestMuted(!muted());
@@ -2971,6 +2971,114 @@ const createField = (options = {}) => {
 		}
 	};
 };
+// src/pagination.ts
+const clamp$2 = (value, min, max) => Math.min(Math.max(value, min), max);
+/**
+* Pagination: a navigation landmark over a page list, the current page marked
+* `aria-current=page` and never a link. No APG pattern exists for it; the
+* requirements are TetraLogical's (accessible-components-library, v1.0.0):
+* exactly one current page, ends kept in place and disabled rather than
+* removed, the count announced once, and a host-supplied `href` for every link
+* so the control works without JS.
+*
+* Target size is the skin's job: 24x24 CSS px at AA, 44x44 at AAA.
+*/
+const createPagination = (options) => {
+	const current = () => clamp$2(options.page, 1, Math.max(options.pageCount, 1));
+	const label = (name, fallback) => options.labels?.[name] ?? fallback;
+	const navigate = (page) => {
+		if (options.disabled === true || page === current()) return;
+		if (page < 1 || page > options.pageCount) return;
+		options.onPageChange?.(page);
+	};
+	const pages = () => {
+		const count = options.pageCount;
+		const page = current();
+		const siblings = Math.max(options.siblings ?? 1, 0);
+		const boundaries = Math.max(options.boundaries ?? 1, 0);
+		const first = Math.min(boundaries, count);
+		const last = Math.max(count - boundaries + 1, 1);
+		const from = Math.max(page - siblings, first + 1);
+		const to = Math.min(page + siblings, last - 1);
+		const items = [];
+		for (let index = 1; index <= count; index++) {
+			if (index <= first || index >= last || index >= from && index <= to) {
+				items.push({
+					kind: "page",
+					page: index,
+					current: index === page
+				});
+				continue;
+			}
+			if (items.at(-1)?.kind !== "gap") items.push({
+				kind: "gap",
+				key: `gap-${index}`
+			});
+		}
+		return items;
+	};
+	const linkProps = (page) => ({
+		get href() {
+			return options.hrefFor?.(page);
+		},
+		get "aria-current"() {
+			return page === current() ? "page" : void 0;
+		},
+		get "aria-disabled"() {
+			const outside = page < 1 || page > options.pageCount;
+			return options.disabled === true || outside ? "true" : void 0;
+		},
+		get "aria-label"() {
+			return `${label("page", "Page")} ${page}`;
+		},
+		get rel() {},
+		onClick: (event) => {
+			event.preventDefault();
+			navigate(page);
+		}
+	});
+	const endProps = (page, name, rel) => ({
+		get href() {
+			return options.hrefFor?.(page);
+		},
+		get "aria-current"() {},
+		get "aria-disabled"() {
+			const outside = page < 1 || page > options.pageCount;
+			return options.disabled === true || outside ? "true" : void 0;
+		},
+		"aria-label": name,
+		get rel() {
+			return rel;
+		},
+		onClick: (event) => {
+			event.preventDefault();
+			navigate(page);
+		}
+	});
+	return {
+		items: pages,
+		current,
+		navProps: { get "aria-label"() {
+			return label("nav", "Pagination");
+		} },
+		listProps: { role: "list" },
+		itemProps: (page) => ({
+			role: "listitem",
+			get "aria-current"() {
+				return page === current() ? "page" : void 0;
+			}
+		}),
+		linkProps,
+		previousProps: endProps(current() - 1, label("previous", "Previous page"), "prev"),
+		nextProps: endProps(current() + 1, label("next", "Next page"), "next"),
+		status: () => options.labels?.status?.(current(), options.pageCount) ?? `Page ${current()} of ${options.pageCount}`,
+		statusProps: {
+			role: "status",
+			"aria-live": "polite",
+			"aria-atomic": "true"
+		}
+	};
+};
 // src/grid.ts
 const GRID_KEYS = /* @__PURE__ */ new Set([
 	"ArrowRight",
@@ -5525,6 +5633,90 @@ const createSwitch = (options = {}) => {
 		}
 	};
 };
+// src/textbox.ts
+const control = (field, options) => ({
+	...field.controlProps,
+	get type() {
+		return options.type ?? "text";
+	},
+	get autoComplete() {
+		return options.autoComplete;
+	},
+	get spellcheck() {
+		if (options.spellCheck === void 0) return;
+		return options.spellCheck ? "true" : "false";
+	},
+	get autocapitalize() {
+		return options.autoCapitalize;
+	},
+	get inputmode() {
+		return options.inputMode;
+	},
+	get maxlength() {
+		return options.maxLength;
+	},
+	get readOnly() {
+		return options.readOnly === true ? true : void 0;
+	},
+	get disabled() {
+		return options.disabled === true ? true : void 0;
+	},
+	get name() {
+		return options.name;
+	},
+	get dir() {
+		return options.dir;
+	},
+	get placeholder() {
+		return options.placeholder;
+	},
+	onInput: (event) => {
+		options.onValueChange?.(event.currentTarget.value);
+	}
+});
+/**
+* A text input with the field contract attached: label, hint, error (announced),
+* `aria-describedby` and `aria-invalid` come from `createField`; this adds the
+* props a host forgets — autofill tokens, spellcheck, inputmode, maxlength, the
+* disabled/readOnly pair. Platform: native (`input` is its own APG-equivalent;
+* no primitive re-implements text editing, which is why there is no key
+* handling here).
+*
+* Both `required` and `aria-required` are emitted: the native attribute is what
+* the browser enforces, the ARIA one is what a custom widget reading the same
+* props needs. A host that validates itself passes `noValidate` on the form
+* rather than dropping the attribute.
+*/
+const createTextInput = (options = {}) => {
+	const field = createField(options);
+	return {
+		...field,
+		controlProps: control(field, options)
+	};
+};
+/**
+* The same contract for a textarea, plus rows, wrap and resize. `resize` is a
+* style because CSS has no attribute for it; `none` is the value a layout that
+* owns its own height wants.
+*/
+const createTextArea = (options = {}) => {
+	const field = createField(options);
+	return {
+		...field,
+		controlProps: {
+			...control(field, options),
+			get rows() {
+				return options.rows;
+			},
+			get wrap() {
+				return options.wrap;
+			},
+			get style() {
+				return options.resize === void 0 ? void 0 : { resize: options.resize };
+			}
+		}
+	};
+};
 // src/tabs.ts
 /**
 * APG Tabs (https://www.w3.org/WAI/ARIA/apg/patterns/tabs/): state plus prop
@@ -7491,4 +7683,4 @@ const createRearrangeableListbox = (options) => {
 		})
 	};
 };
-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 };
+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, createPagination, createPlayer, createRadioGroup, createRearrangeableListbox, createResizablePanels, createSlider, createSliderMultiThumb, createSpinbutton, createSwitch, createTabs, createTextArea, createTextInput, 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.12.0",
+  "version": "0.13.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": {