@cssints/headless 0.13.0 → 0.14.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, 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.
+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, popover, 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.
 
@@ -220,6 +220,32 @@ 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.
 
+## 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).
+
+```tsx
+const popover = createPopover({ placement: "bottom-start" });
+let trigger!: HTMLButtonElement;
+let content!: HTMLDivElement;
+
+onMount(() => {
+  const teardown = popover.attach(trigger, content);
+  onCleanup(teardown);
+});
+
+<button {...popover.triggerProps} ref={(element) => (trigger = element)}>Filters</button>
+<div {...popover.contentProps} style={popover.contentStyle()} ref={(element) => (content = element)}>
+  …
+</div>;
+```
+
+- **`attach(trigger, content)`** is the whole DOM contract and returns its teardown: it measures and places on open (and on resize, scroll and a `ResizeObserver`), focuses the first focusable element in the content (else the content itself, which is `tabindex="-1"`), returns focus to the trigger on a close it caused, and closes on a `pointerdown` outside both elements. Call it from a `ref`; it creates an effect.
+- **`position(triggerRect, contentRect, viewport)`** is pure: it returns `{ top, left, placement }` for the requested placement, flipped to the other side when the room is not there, and shifted (not flipped) into the viewport horizontally. The rects and the viewport must share a space; `attach` measures in client space and writes page space for `position: absolute`.
+- **Non-modal, deliberately.** The page behind keeps its focus, its clicks and its scroll: no `inert`, no scroll lock, no Tab cycle, no `aria-modal`. That is `createDialogModal`, and `modal` is typed `false` for that reason.
+- **Not a menu.** No roving focus, no arrow keys between items: it is the base for `createMenu` in a popover, and for the filterable menu, which own their own item focus.
+- Absent on purpose: hover open (that is `createTooltipGroup`), submenus and item navigation (the menu), a scroll lock and `inert` (the modal dialog), and a vertical shift when neither side fits (the caller sees the requested placement).
+
 ## Commands
 
 ```sh

package/dist/index.d.mts

@@ -1642,6 +1642,106 @@ export interface Pagination {
  * Target size is the skin's job: 24x24 CSS px at AA, 44x44 at AAA.
  */
 export declare const createPagination: (options: PaginationOptions) => Pagination;
+export type PopoverPlacement = "bottom-start" | "bottom" | "bottom-end" | "top-start" | "top" | "top-end";
+/** A rect in one space, as `getBoundingClientRect` gives it. */
+export interface PopoverRect {
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  readonly height: number;
+}
+export interface PopoverViewport {
+  readonly width: number;
+  readonly height: number;
+}
+export interface PopoverPosition {
+  readonly top: number;
+  readonly left: number;
+  readonly placement: PopoverPlacement;
+}
+/** The last measure, as a style object for the content element. */
+export interface PopoverStyle {
+  readonly position: "absolute";
+  readonly top: string;
+  readonly left: string;
+  /** Custom properties, so the object is assignable to Solid's `style`. */
+  readonly [property: `-${string}`]: string | number | undefined;
+}
+export interface PopoverOptions {
+  /** Base for the generated trigger / content ids. */
+  readonly id?: string | undefined;
+  /** Controlled: the host owns the open state and this is the only thing that changes it. */
+  readonly open?: boolean | undefined;
+  /** Uncontrolled starting state; ignored while `open` is set. */
+  readonly defaultOpen?: boolean | undefined;
+  /** @default "bottom" */
+  readonly placement?: PopoverPlacement | undefined;
+  /** Gap between the trigger and the content, in px. @default 4 */
+  readonly offset?: number | undefined;
+  /**
+   * Only `false`, and it is not read: a popover is the non-modal overlay (the
+   * page behind stays interactive, nothing is made `inert`, no scroll lock).
+   * A modal surface is `createDialogModal`, which owns `aria-modal` and the
+   * focus trap; this option exists only so a host generic over overlays can
+   * pass it and get the truth.
+   */
+  readonly modal?: false;
+  /** A request to change the open state, called when the intent differs. */
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+}
+export interface PopoverTriggerProps {
+  readonly id: string;
+  readonly "aria-haspopup": "dialog";
+  readonly "aria-expanded": "true" | "false";
+  readonly "aria-controls": string;
+  readonly onClick: () => void;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+}
+export interface PopoverContentProps {
+  readonly id: string;
+  readonly role: "dialog";
+  /** Always absent: a popover is not modal. */
+  readonly "aria-modal": undefined;
+  readonly tabindex: -1;
+  readonly hidden: boolean;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+}
+export interface Popover {
+  readonly open: Accessor<boolean>;
+  readonly triggerProps: PopoverTriggerProps;
+  readonly contentProps: PopoverContentProps;
+  /** `style` for the content element. Reads the last measure. */
+  readonly contentStyle: Accessor<PopoverStyle>;
+  /** Pure: the content's offset for these rects, flipped when the room is not there. */
+  readonly position: (triggerRect: PopoverRect, contentRect: PopoverRect, viewport: PopoverViewport) => PopoverPosition;
+  /**
+   * DOM wiring: measure and place on open, focus into the content, return focus
+   * to the trigger on close, close on an outside `pointerdown`. Call it from a
+   * ref (it creates an effect) and call the teardown it returns on cleanup.
+   */
+  readonly attach: (trigger: HTMLElement, content: HTMLElement) => () => void;
+}
+/**
+ * A non-modal popover on Solid 2: 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 it** (APG has
+ * Dialog, which is modal, and no popover), so there is no Quint spec and
+ * `test/popover.browser.test.tsx` is the oracle. Copied from Base UI's Popover
+ * (trigger click toggles, Enter / Space / ArrowDown open, light dismiss on an
+ * outside `pointerdown` that does not steal focus) and React Aria's
+ * `usePopover` (focus into the content on open, back to the trigger on close,
+ * `role="dialog"` with no `aria-modal`, a placement that flips at the viewport
+ * edge).
+ *
+ * Not modal, deliberately: the page behind keeps its focus, its clicks and its
+ * scroll. No `inert`, no scroll lock, no Tab cycle — `createDialogModal` is the
+ * modal one. No roving focus either: this is the base for a menu in a popover
+ * (`createMenu` owns the item focus), not a menu itself.
+ *
+ * Request/commit (map ticket `rt1p`): uncontrolled by default (`defaultOpen`);
+ * pass `open` + `onOpenChange` to own the open state.
+ */
+export declare const createPopover: (options?: PopoverOptions) => Popover;
 /**
  * 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
@@ -2669,7 +2769,7 @@ 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";
+  readonly type?: "text" | "email" | "tel" | "url" | "search" | "password" | undefined;
   /** The HTML token list: the browser's own autofill is the accessible path. */
   readonly autoComplete?: AutoCompleteToken | undefined;
   readonly spellCheck?: boolean | undefined;

package/dist/index.mjs

@@ -3079,6 +3079,164 @@ const createPagination = (options) => {
 		}
 	};
 };
+// src/popover.ts
+const FLIPPED = {
+	"bottom-start": "top-start",
+	bottom: "top",
+	"bottom-end": "top-end",
+	"top-start": "bottom-start",
+	top: "bottom",
+	"top-end": "bottom-end"
+};
+const FOCUSABLE = "a[href], button, input, select, textarea, [tabindex], [contenteditable]";
+const firstFocusable = (root) => Array.from(root.querySelectorAll(FOCUSABLE)).find((element) => element.tabIndex >= 0 && !element.matches(":disabled") && element.getClientRects().length > 0);
+/**
+* A non-modal popover on Solid 2: 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 it** (APG has
+* Dialog, which is modal, and no popover), so there is no Quint spec and
+* `test/popover.browser.test.tsx` is the oracle. Copied from Base UI's Popover
+* (trigger click toggles, Enter / Space / ArrowDown open, light dismiss on an
+* outside `pointerdown` that does not steal focus) and React Aria's
+* `usePopover` (focus into the content on open, back to the trigger on close,
+* `role="dialog"` with no `aria-modal`, a placement that flips at the viewport
+* edge).
+*
+* Not modal, deliberately: the page behind keeps its focus, its clicks and its
+* scroll. No `inert`, no scroll lock, no Tab cycle — `createDialogModal` is the
+* modal one. No roving focus either: this is the base for a menu in a popover
+* (`createMenu` owns the item focus), not a menu itself.
+*
+* Request/commit (map ticket `rt1p`): uncontrolled by default (`defaultOpen`);
+* pass `open` + `onOpenChange` to own the open state.
+*/
+const createPopover = (options = {}) => {
+	const base = options.id ?? createUniqueId();
+	const triggerId = `${base}-trigger`;
+	const contentId = `${base}-content`;
+	const [open, requestOpen] = createControllable({
+		value: () => options.open,
+		initial: options.defaultOpen ?? false,
+		onChange: () => options.onOpenChange
+	});
+	const [measured, setMeasured] = createSignal(void 0);
+	const position = (triggerRect, contentRect, viewport) => {
+		const requested = options.placement ?? "bottom";
+		const gap = options.offset ?? 4;
+		const below = triggerRect.top + triggerRect.height + gap;
+		const above = triggerRect.top - gap - contentRect.height;
+		const fitsBelow = below + contentRect.height <= viewport.height;
+		const fitsAbove = above >= 0;
+		const wantsBelow = requested.startsWith("bottom");
+		const placement = (wantsBelow ? fitsBelow : fitsAbove) || !(wantsBelow ? fitsAbove : fitsBelow) ? requested : FLIPPED[requested];
+		const aligned = placement.endsWith("-start") === true ? triggerRect.left : placement.endsWith("-end") === true ? triggerRect.left + triggerRect.width - contentRect.width : triggerRect.left + (triggerRect.width - contentRect.width) / 2;
+		return {
+			top: placement.startsWith("top") ? above : below,
+			left: Math.max(0, Math.min(aligned, viewport.width - contentRect.width)),
+			placement
+		};
+	};
+	const attach = (trigger, content) => {
+		let restoreFocus = true;
+		let wasOpen = false;
+		const measure = () => {
+			if (!open()) return;
+			const t = trigger.getBoundingClientRect();
+			const c = content.getBoundingClientRect();
+			const at = position({
+				top: t.top,
+				left: t.left,
+				width: t.width,
+				height: t.height
+			}, {
+				top: 0,
+				left: 0,
+				width: c.width,
+				height: c.height
+			}, {
+				width: window.innerWidth,
+				height: window.innerHeight
+			});
+			setMeasured({
+				top: at.top + window.scrollY,
+				left: at.left + window.scrollX,
+				placement: at.placement
+			});
+		};
+		const onPointerDown = (event) => {
+			const target = event.target;
+			if (!(target instanceof Node) || trigger.contains(target) || content.contains(target)) return;
+			restoreFocus = false;
+			requestOpen(false);
+		};
+		createEffect(() => open(), (isOpen) => {
+			if (isOpen) {
+				restoreFocus = true;
+				wasOpen = true;
+				measure();
+				(firstFocusable(content) ?? content).focus();
+			} else if (wasOpen) {
+				wasOpen = false;
+				if (restoreFocus && trigger.isConnected) trigger.focus();
+			}
+		});
+		document.addEventListener("pointerdown", onPointerDown, true);
+		window.addEventListener("resize", measure);
+		window.addEventListener("scroll", measure, true);
+		const observer = new ResizeObserver(measure);
+		observer.observe(trigger);
+		observer.observe(content);
+		return () => {
+			observer.disconnect();
+			document.removeEventListener("pointerdown", onPointerDown, true);
+			window.removeEventListener("resize", measure);
+			window.removeEventListener("scroll", measure, true);
+		};
+	};
+	return {
+		open,
+		triggerProps: {
+			id: triggerId,
+			"aria-haspopup": "dialog",
+			get "aria-expanded"() {
+				return open() ? "true" : "false";
+			},
+			"aria-controls": contentId,
+			onClick: () => requestOpen(!open()),
+			onKeyDown: (event) => {
+				if (event.key === "Enter" || event.key === " " || event.key === "ArrowDown") {
+					event.preventDefault();
+					requestOpen(true);
+				}
+			}
+		},
+		contentProps: {
+			id: contentId,
+			role: "dialog",
+			"aria-modal": void 0,
+			tabindex: -1,
+			get hidden() {
+				return !open();
+			},
+			onKeyDown: (event) => {
+				if (event.key === "Escape" && open()) {
+					event.preventDefault();
+					requestOpen(false);
+				}
+			}
+		},
+		contentStyle: () => {
+			const at = measured();
+			return {
+				position: "absolute",
+				top: `${at?.top ?? 0}px`,
+				left: `${at?.left ?? 0}px`
+			};
+		},
+		position,
+		attach
+	};
+};
 // src/grid.ts
 const GRID_KEYS = /* @__PURE__ */ new Set([
 	"ArrowRight",
@@ -7683,4 +7841,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, 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, 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.13.0",
+  "version": "0.14.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": {