@cssints/headless 0.14.0 → 0.15.0

package/README.md

@@ -220,6 +220,56 @@ const remove = async () => {
 - **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.
 
+## Toast and status
+
+Two live regions for the two sizes of feedback: `createStatus` is one `role=status` message whose text the host replaces ("Link copied", "Saved"); `createToast` is a queue of toasts, each with its own live region, a timeout, a ceiling and a countdown that pauses. Neither touches the DOM: like every primitive here they return state and attribute objects. **There is no APG pattern for either** (APG's Alert, `createAlert`, is imperative and assertive), so there is no Quint spec and `test/toast.browser.test.tsx` is the oracle. The behaviour is copied from Base UI's Toast and React Aria's Toast (a landmark, F6 into it, at least 5 s, timers paused on hover or focus, the announced text handed in rather than read from the DOM).
+
+```tsx
+const toast = createToast();
+const status = createStatus();
+
+const copy = async () => {
+  await navigator.clipboard.writeText(url);
+  status.show("Link copied");
+};
+
+const upload = async () => {
+  try {
+    await send(file);
+    toast.show({ title: "Uploaded", description: file.name, tone: "success" });
+  } catch {
+    toast.show({
+      title: "Upload failed",
+      description: "Try again from the file row",
+      tone: "error",
+    });
+  }
+};
+
+<p {...status.statusProps}>{status.message()}</p>;
+
+<div {...toast.regionProps} tabindex={-1}>
+  <For each={toast.toasts()}>
+    {(item) => (
+      <div {...toast.toastProps(item.id)}>
+        <p>{item.title}</p>
+        <p>{item.description}</p>
+        <button type="button" onClick={() => toast.dismiss(item.id)}>
+          Dismiss
+        </button>
+      </div>
+    )}
+  </For>
+</div>;
+```
+
+- **A status replaces, it does not stack.** `show(text)` writes the one region and `clear()` empties it; a second message before the first is read replaces it. A status is never for errors: an error is `createAlert` (`role=alert`, assertive), and a titled message with a timeout is a toast.
+- **Toast roles.** `toastProps(id).role` is `"alert"` for `tone: "error"` and `"status"` otherwise, so an error interrupts and the rest wait. The container is `role="region"` with `aria-label` ("Notifications" unless `labels.region`), and each toast is `aria-atomic`, so its title and description are announced as one — the toast's own text is the announcement, a close button's label included, so keep a toast to its title and description. The role sits on the toast rather than on one container per tone: the container is the `region` landmark, so it cannot also be the live region, and a role per toast needs no second region from the host.
+- **Timers.** `timeout` defaults to 5000 ms, the five seconds Base UI and React Aria call the minimum for reading a message; shorter values are for tests. One timer per toast, cleared by `dismiss`/`dismissAll` and all of them on dispose.
+- **Pause.** Hovering a toast pauses its countdown and leaving resumes it with the time it had left (the deadline is kept, not restarted); focus always pauses, because a reader who tabbed into the toast must not lose it. `pauseOnHover: false` leaves focus as the only pause.
+- **The ceiling.** `max` (default 3) keeps the newest: a `show` past it drops the oldest. `onDismiss(id)` fires for every toast that leaves, whichever way — a timeout, a dismiss, `dismissAll` or the ceiling.
+- **F6.** Base UI and React Aria enter the toast region with F6 and return with F6: the region is the target, so give it `tabindex="-1"` and focus it from the host's F6 handler, remembering the element to restore. The primitive binds no keys: global hotkeys are a separate piece (bean cssints-h0d5).
+
 ## Popover
 
 `createPopover` is the non-modal overlay: an anchored surface a trigger opens, dismissed by a click on the trigger, an outside `pointerdown` or Escape, with focus moving into it and back to the trigger. **There is no APG pattern for a popover** (APG has Dialog, which is modal), so there is no Quint spec and `test/popover.browser.test.tsx` is the oracle. It is copied from Base UI's Popover (the trigger click toggle, Enter / Space / ArrowDown, light dismiss on an outside `pointerdown` that does not steal focus) and React Aria's `usePopover` (focus in on open, back on close, `role="dialog"` without `aria-modal`, a placement that flips at the viewport edge).

package/dist/index.d.mts

@@ -2712,6 +2712,37 @@ export interface Spinbutton {
  * APG text.
  */
 export declare const createSpinbutton: (options?: SpinbuttonOptions) => Spinbutton;
+export interface StatusOptions {
+  /** Rendered on `statusProps`; generated when absent. */
+  readonly id?: string | undefined;
+}
+/** Spread onto the `role=status` live region. Render it once, always. */
+export interface StatusProps {
+  readonly id: string;
+  readonly role: "status";
+  readonly "aria-live": "polite";
+  readonly "aria-atomic": "true";
+}
+export interface Status {
+  /** The text currently shown, or `undefined` before the first `show`. */
+  readonly message: Accessor<string | undefined>;
+  /** Writes the message, replacing the previous one; nothing is queued. */
+  readonly show: (text: string) => void;
+  readonly clear: () => void;
+  readonly statusProps: StatusProps;
+}
+/**
+ * APG Alert's polite sibling: one `role=status` live region whose text the host
+ * replaces ("Link copied", "Saved"). It is not a queue: a second message shows
+ * in place of the first, so a burst reads as the last state, not as N alerts.
+ * The region is rendered once and stays mounted, which is what makes a change
+ * of its text announced.
+ *
+ * A status is never for errors: an error that needs attention now is
+ * `createAlert` (`role=alert`, assertive), and a message with a title, a
+ * description and a timeout is `createToast`.
+ */
+export declare const createStatus: (options?: StatusOptions) => Status;
 export interface SwitchOptions {
   /** Controlled: the host owns the state and this is the only thing that changes it. */
   readonly value?: boolean | undefined;
@@ -3037,6 +3068,74 @@ export interface Timeline {
  * reactive.
  */
 export declare const createTimeline: (options?: TimelineOptions) => Timeline;
+/** A toast's urgency; `error` is the only tone that announces assertively. */
+export type ToastTone = "info" | "success" | "error";
+export interface ToastOptions {
+  /** Auto-dismiss delay in ms, default 5000. A number; `0` dismisses on the next tick. */
+  readonly timeout?: number | undefined;
+  /** Visible toasts kept, default 3; a new one past the ceiling drops the oldest. */
+  readonly max?: number | undefined;
+  /** Pauses the countdown while a pointer is over a toast, default true. Focus always pauses. */
+  readonly pauseOnHover?: boolean | undefined;
+  /** The region's accessible name; `region` defaults to `"Notifications"`. */
+  readonly labels?: {
+    readonly region?: string | undefined;
+  } | undefined;
+  /** Called with the id whenever a toast leaves, for whatever reason. */
+  readonly onDismiss?: ((id: string) => void) | undefined;
+}
+/** What `show` takes; `tone` defaults to `"info"`. */
+export interface ToastInput {
+  readonly title: string;
+  readonly description?: string | undefined;
+  readonly tone?: ToastTone | undefined;
+}
+/** A toast in the queue, oldest first in `toasts()`. */
+export interface ToastItem {
+  readonly id: string;
+  readonly title: string;
+  readonly description: string | undefined;
+  readonly tone: ToastTone;
+}
+/** Spread onto the container that holds every toast and the F6 target. */
+export interface ToastRegionProps {
+  readonly role: "region";
+  readonly "aria-label": string;
+}
+/**
+ * Spread onto one toast. `role` is `alert` for the `error` tone and `status`
+ * otherwise; both pause the countdown while hovered or focused.
+ */
+export interface ToastItemProps {
+  readonly role: "alert" | "status";
+  readonly "aria-atomic": "true";
+  readonly onMouseEnter: () => void;
+  readonly onMouseLeave: () => void;
+  readonly onFocusIn: () => void;
+  readonly onFocusOut: () => void;
+}
+export interface Toast {
+  /** Oldest first. */
+  readonly toasts: Accessor<readonly ToastItem[]>;
+  /** Queues a toast and returns its id. */
+  readonly show: (input: ToastInput) => string;
+  readonly dismiss: (id: string) => void;
+  readonly dismissAll: () => void;
+  readonly regionProps: ToastRegionProps;
+  readonly toastProps: (id: string) => ToastItemProps;
+}
+/**
+ * A toast queue: one timeout per toast, a ceiling that drops the oldest, and a
+ * countdown that pauses on hover and focus and resumes from where it stopped.
+ * A toast announces itself through its own live region (`role=status`, or
+ * `role=alert` for `error`), so the host renders one element per toast inside
+ * `regionProps`. No DOM access here: the host renders, the primitive decides.
+ *
+ * The timeout is a floor of practice, not of code: the default is 5000 ms
+ * because both Base UI and React Aria agree on at least five seconds to read a
+ * message; shorter values exist for tests and are the host's judgement.
+ */
+export declare const createToast: (options?: ToastOptions) => Toast;
 /**
  * APG Toolbar on Solid 2: state plus attribute objects, no elements, no
  * styling. A faithful transcription of `specs/apg/toolbar.qnt`.

package/dist/index.mjs

@@ -4982,7 +4982,7 @@ const createRadioGroup = (options) => {
 };
 // src/resizable-panels.ts
 const DEFAULT_MIN = 10;
-const DEFAULT_MAX = 80;
+const DEFAULT_MAX$1 = 80;
 const DEFAULT_STEP = 10;
 const FULL = 100;
 const clamp = (value, low, high) => Math.min(high, Math.max(low, value));
@@ -5052,7 +5052,7 @@ const createResizablePanels = (options) => {
 	const minOf = (index) => panes()[index]?.min ?? DEFAULT_MIN;
 	/** The smallest committed size (a collapsible pane may sit at collapsedSize). */
 	const lowOf = (index) => panes()[index]?.collapsible === true ? collapsedSize(index) : minOf(index);
-	const highOf = (index) => panes()[index]?.max ?? DEFAULT_MAX;
+	const highOf = (index) => panes()[index]?.max ?? DEFAULT_MAX$1;
 	/** Clamp every pane, then push the residual into the panes in order. */
 	const fit = (raw) => {
 		const next = panes().map((_, index) => clamp(round2(raw[index] ?? FULL / Math.max(count(), 1)), lowOf(index), highOf(index)));
@@ -5702,6 +5702,37 @@ const createSpinbutton = (options = {}) => {
 		}
 	};
 };
+// src/status.ts
+/**
+* APG Alert's polite sibling: one `role=status` live region whose text the host
+* replaces ("Link copied", "Saved"). It is not a queue: a second message shows
+* in place of the first, so a burst reads as the last state, not as N alerts.
+* The region is rendered once and stays mounted, which is what makes a change
+* of its text announced.
+*
+* A status is never for errors: an error that needs attention now is
+* `createAlert` (`role=alert`, assertive), and a message with a title, a
+* description and a timeout is `createToast`.
+*/
+const createStatus = (options = {}) => {
+	const id = options.id ?? createUniqueId();
+	const [message, setMessage] = createSignal();
+	return {
+		message,
+		show: (text) => {
+			setMessage(text);
+		},
+		clear: () => {
+			setMessage(void 0);
+		},
+		statusProps: {
+			id,
+			role: "status",
+			"aria-live": "polite",
+			"aria-atomic": "true"
+		}
+	};
+};
 // src/switch.ts
 /**
 * APG Switch (https://www.w3.org/WAI/ARIA/apg/patterns/switch/): a binary on/off
@@ -6248,6 +6279,143 @@ const createTimeline = (options = {}) => {
 		}
 	};
 };
+// src/toast.ts
+const DEFAULT_TIMEOUT_MS = 5e3;
+const DEFAULT_MAX = 3;
+const DEFAULT_REGION_LABEL = "Notifications";
+/**
+* A toast queue: one timeout per toast, a ceiling that drops the oldest, and a
+* countdown that pauses on hover and focus and resumes from where it stopped.
+* A toast announces itself through its own live region (`role=status`, or
+* `role=alert` for `error`), so the host renders one element per toast inside
+* `regionProps`. No DOM access here: the host renders, the primitive decides.
+*
+* The timeout is a floor of practice, not of code: the default is 5000 ms
+* because both Base UI and React Aria agree on at least five seconds to read a
+* message; shorter values exist for tests and are the host's judgement.
+*/
+const createToast = (options = {}) => {
+	const [version, setVersion] = createSignal(0);
+	let items = [];
+	const timers = /* @__PURE__ */ new Map();
+	const toasts = () => {
+		version();
+		return items;
+	};
+	const commit = (next) => {
+		items = [...next];
+		setVersion((count) => count + 1);
+	};
+	const clear = (id) => {
+		const countdown = timers.get(id);
+		if (countdown === void 0) return;
+		if (countdown.handle !== void 0) clearTimeout(countdown.handle);
+		timers.delete(id);
+	};
+	const dismiss = (id) => {
+		if (!items.some((item) => item.id === id)) return;
+		clear(id);
+		commit(items.filter((item) => item.id !== id));
+		options.onDismiss?.(id);
+	};
+	const dismissAll = () => {
+		const ids = items.map((item) => item.id);
+		if (ids.length === 0) return;
+		for (const id of ids) clear(id);
+		commit([]);
+		for (const id of ids) options.onDismiss?.(id);
+	};
+	const arm = (id, countdown) => {
+		countdown.handle = setTimeout(() => dismiss(id), countdown.remaining);
+	};
+	const pause = (id) => {
+		const countdown = timers.get(id);
+		if (countdown === void 0 || countdown.handle === void 0) return;
+		clearTimeout(countdown.handle);
+		countdown.handle = void 0;
+		countdown.remaining = Math.max(0, countdown.deadline - Date.now());
+	};
+	const paused = (countdown) => countdown.focused || countdown.hovered && (options.pauseOnHover ?? true);
+	const resume = (id) => {
+		const countdown = timers.get(id);
+		if (countdown === void 0 || countdown.handle !== void 0 || paused(countdown)) return;
+		countdown.deadline = Date.now() + countdown.remaining;
+		arm(id, countdown);
+	};
+	const sync = (id, countdown) => {
+		if (paused(countdown)) pause(id);
+		else resume(id);
+	};
+	const show = (input) => {
+		const item = {
+			id: createUniqueId(),
+			title: input.title,
+			description: input.description,
+			tone: input.tone ?? "info"
+		};
+		const limit = Math.max(1, options.max ?? DEFAULT_MAX);
+		const next = [...items, item];
+		const dropped = [];
+		while (next.length > limit) {
+			const oldest = next.shift();
+			if (oldest !== void 0) dropped.push(oldest.id);
+		}
+		commit(next);
+		for (const id of dropped) {
+			clear(id);
+			options.onDismiss?.(id);
+		}
+		const duration = Math.max(0, options.timeout ?? DEFAULT_TIMEOUT_MS);
+		const countdown = {
+			handle: void 0,
+			deadline: Date.now() + duration,
+			remaining: duration,
+			hovered: false,
+			focused: false
+		};
+		timers.set(item.id, countdown);
+		arm(item.id, countdown);
+		return item.id;
+	};
+	const hover = (id, next) => {
+		const countdown = timers.get(id);
+		if (countdown === void 0) return;
+		countdown.hovered = next;
+		sync(id, countdown);
+	};
+	const focus = (id, next) => {
+		const countdown = timers.get(id);
+		if (countdown === void 0) return;
+		countdown.focused = next;
+		sync(id, countdown);
+	};
+	if (getOwner() !== null) onCleanup(() => {
+		for (const countdown of timers.values()) if (countdown.handle !== void 0) clearTimeout(countdown.handle);
+		timers.clear();
+	});
+	return {
+		toasts,
+		show,
+		dismiss,
+		dismissAll,
+		regionProps: {
+			role: "region",
+			get "aria-label"() {
+				return options.labels?.region ?? DEFAULT_REGION_LABEL;
+			}
+		},
+		toastProps: (id) => ({
+			get role() {
+				return items.find((item) => item.id === id)?.tone === "error" ? "alert" : "status";
+			},
+			"aria-atomic": "true",
+			onMouseEnter: () => hover(id, true),
+			onMouseLeave: () => hover(id, false),
+			onFocusIn: () => focus(id, true),
+			onFocusOut: () => focus(id, false)
+		})
+	};
+};
 // src/toolbar.ts
 const AXIS = (o) => o === "horizontal" ? "inline" : "block";
 const delta = (axis, key) => {
@@ -7841,4 +8009,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, createPagination, createPlayer, createPopover, 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 };
+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, createPopover, createRadioGroup, createRearrangeableListbox, createResizablePanels, createSlider, createSliderMultiThumb, createSpinbutton, createStatus, createSwitch, createTabs, createTextArea, createTextInput, createTimeline, createToast, 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.14.0",
+  "version": "0.15.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": {