@spinjs/components 0.1.0-preview.2 → 0.2.0-alpha.1

package/dist/runtime/actions/scroll-into-view.js

@@ -0,0 +1,36 @@
+// src/runtime/actions/scroll-into-view.ts
+const scrollIntoView = (_node, param) => {
+	let last;
+	const reveal = (next) => {
+		const id = next?.activeId() ?? "";
+		if (id.length === 0) {
+			if (last !== void 0) {
+				for (const list of _node.querySelectorAll("[role=\"group\"]")) list.scrollTop = 0;
+				last = void 0;
+			}
+			return;
+		}
+		if (id === last) return;
+		last = id;
+		if (next?.reveal !== void 0) {
+			next.reveal();
+			return;
+		}
+		const target = document.getElementById(id);
+		if (!(target instanceof HTMLElement)) return;
+		target.scrollIntoView({
+			block: next?.edge ?? "nearest",
+			inline: "nearest"
+		});
+	};
+	reveal(param);
+	return {
+		update: (next) => reveal(next),
+		destroy: () => {
+			last = void 0;
+		}
+	};
+};
+export { scrollIntoView };
+
+//# sourceMappingURL=scroll-into-view.js.map

package/dist/runtime/actions/select-focus.d.ts

@@ -0,0 +1,17 @@
+import { ElementAction } from "./action.js";
+/**
+ * select-focus — move focus into the panel when it opens.
+ *
+ * The `setInitialFocus` behaviour: a keyboard user who opened the panel with
+ * the trigger expects the arrow keys to move the highlight next, and the
+ * trigger's own keys stop applying once the panel is open. The content is
+ * the panel's tab stop, so opening hands it focus (unless focus already
+ * moved inside — a pointer that landed on a row must not be yanked away).
+ *
+ * A reflex, so an action: it runs at attach and again whenever the open flag
+ * moves, and it focuses only the node it is given.
+ */
+export interface SelectFocusParam {
+  readonly open: boolean;
+}
+export declare const selectFocus: ElementAction<SelectFocusParam | undefined>;

package/dist/runtime/actions/select-focus.js

@@ -0,0 +1,16 @@
+import { createAction } from "./action.js";
+// src/runtime/actions/select-focus.ts
+const selectFocus = createAction((node, param) => {
+	if (param === void 0) return;
+	const apply = (current) => {
+		if (!current.open) return;
+		const active = node.getRootNode() instanceof ShadowRoot ? null : document.activeElement;
+		if (active instanceof Node && node.contains(active)) return;
+		node.focus?.();
+	};
+	apply(param);
+	return { update: apply };
+});
+export { selectFocus };
+
+//# sourceMappingURL=select-focus.js.map

package/dist/runtime/actions/select-options.d.ts

@@ -0,0 +1,25 @@
+import { ElementAction } from "./action.js";
+/**
+ * select-options — keep the hidden native select's option list and value in
+ * step with the collection and the selection.
+ *
+ * The recipe cannot template `<option>` children: the element parser drops
+ * `<template>` inside a `<select>`, so the options are built here, from the
+ * rows the bag hands over. The action runs every time the bag re-applies,
+ * which is every collection or selection move, so a rebuild is always against
+ * current values.
+ *
+ * The form's value is the reason this exists: a native select inside the form
+ * posts this component's selection with no custom serialization, and the
+ * form-control action's reset reads it back.
+ */
+export interface SelectOptionsRow {
+  readonly value: string;
+  readonly label: string;
+}
+export interface SelectOptionsParam {
+  readonly rows: readonly SelectOptionsRow[];
+  readonly value: readonly string[];
+  readonly multiple: boolean;
+}
+export declare const selectOptions: ElementAction<SelectOptionsParam | undefined>;

package/dist/runtime/actions/select-options.js

@@ -0,0 +1,27 @@
+import { createAction } from "./action.js";
+// src/runtime/actions/select-options.ts
+const selectOptions = createAction((node, param) => {
+	if (param === void 0) return;
+	const select = node;
+	/** The sync, run at mount and again on every param change. */
+	const apply = (current) => {
+		const wanted = current.rows;
+		const existing = [...select.options].map((option) => option.value);
+		if (!(existing.length === wanted.length && existing.every((value, index) => value === wanted[index]?.value))) {
+			select.replaceChildren();
+			for (const row of wanted) {
+				const option = document.createElement("option");
+				option.value = row.value;
+				option.textContent = row.label;
+				select.append(option);
+			}
+		}
+		if (current.multiple) for (const option of [...select.options]) option.selected = current.value.includes(option.value);
+		else select.value = current.value[0] ?? "";
+	};
+	apply(param);
+	return { update: apply };
+});
+export { selectOptions };
+
+//# sourceMappingURL=select-options.js.map

package/dist/runtime/actions/toast-actions.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The toast's own reflexes — the two timers the upstream toast machine runs
+ * as effects, as actions instead, because a timer is never machine state.
+ *
+ * `toast-timer` rides one toast row and owns two clocks:
+ *
+ *   - the dismissal clock, which counts down `remaining` while the row is
+ *     visible and not paused, reports the remainder when it stops early, and
+ *     fires `onTimeout` when it runs out;
+ *   - the remove clock, armed when the row starts dismissing, which fires
+ *     `onRemove` after `removeDelay` — the exit beat that finally takes the
+ *     row out of the queue.
+ *
+ * The pause is where the `syncRemainingTime` lives: it subtracts the
+ * elapsed time from the armed duration and hands it back through
+ * `onPause`, so the number the machine holds is the number the clock
+ * resumes from. A row that never pauses keeps its `remaining` untouched and
+ * the clock never re-arms.
+ *
+ * `toast-row` is the one-row counterpart of the stdlib's observers: it reads
+ * the row's layout height once it is in the document and reports it, which
+ * is the measurement the group machine wants for its stack offsets.
+ */
+import { ElementAction } from "./action.js";
+export interface ToastTimerParam {
+  /** What is left on the dismissal clock, in milliseconds. */
+  readonly remaining: number;
+  /** The row is paused: the clock holds its remainder. */
+  readonly paused: boolean;
+  /** The row is playing its exit. */
+  readonly dismissing: boolean;
+  /** The gap between the exit starting and the row leaving the queue. */
+  readonly removeDelay: number;
+  readonly onTimeout: () => void;
+  readonly onRemove: () => void;
+  /** Fires once when the row reports a clock remainder it stopped at. */
+  readonly onPause: (remaining: number) => void;
+  /** Fires once on the frame after the row attaches — the entry beat. */
+  readonly onReady: () => void;
+}
+export declare const toastTimer: ElementAction<ToastTimerParam>;
+export interface ToastRowParam {
+  /** Fires with the row's layout height, whenever it changes. */
+  readonly onHeight: (height: number) => void;
+}
+/**
+ * The measurement half. A ResizeObserver reports the row's own box, so the
+ * stack's offsets come from a height the element actually has rather than
+ * from a measurement the machine guesses.
+ */
+export declare const toastRow: ElementAction<ToastRowParam>;
+export interface ToastRegionParam {
+  /** The keys that together focus the region, e.g. `["altKey", "KeyT"]`. */
+  readonly hotkey: readonly string[];
+  /** Whether a hidden document pauses the toasts. */
+  readonly pauseOnPageIdle: boolean;
+  readonly onIdleChange: (idle: boolean) => void;
+}
+/**
+ * The region's document reflexes — the `trackHotKeyPress` and
+ * `trackDocumentVisibility` effects. Both are listeners on the document,
+ * which is what an action is for: the element it is attached to is the
+ * region, and the only thing it does with it is focus it.
+ */
+export declare const toastRegion: ElementAction<ToastRegionParam>;

package/dist/runtime/actions/toast-actions.js

@@ -0,0 +1,143 @@
+import { createAction } from "./action.js";
+// src/runtime/actions/toast-actions.ts
+/**
+* The toast's own reflexes — the two timers the upstream toast machine runs
+* as effects, as actions instead, because a timer is never machine state.
+*
+* `toast-timer` rides one toast row and owns two clocks:
+*
+*   - the dismissal clock, which counts down `remaining` while the row is
+*     visible and not paused, reports the remainder when it stops early, and
+*     fires `onTimeout` when it runs out;
+*   - the remove clock, armed when the row starts dismissing, which fires
+*     `onRemove` after `removeDelay` — the exit beat that finally takes the
+*     row out of the queue.
+*
+* The pause is where the `syncRemainingTime` lives: it subtracts the
+* elapsed time from the armed duration and hands it back through
+* `onPause`, so the number the machine holds is the number the clock
+* resumes from. A row that never pauses keeps its `remaining` untouched and
+* the clock never re-arms.
+*
+* `toast-row` is the one-row counterpart of the stdlib's observers: it reads
+* the row's layout height once it is in the document and reports it, which
+* is the measurement the group machine wants for its stack offsets.
+*/
+const toastTimer = createAction((_node, param) => {
+	let armed = false;
+	let start = 0;
+	let runFor = 0;
+	let timer;
+	let ready = false;
+	const clearClock = () => {
+		clearTimeout(timer);
+		timer = void 0;
+	};
+	const arm = (ms) => {
+		clearClock();
+		start = Date.now();
+		runFor = ms;
+		armed = true;
+		timer = setTimeout(() => {
+			timer = void 0;
+			armed = false;
+			param?.onTimeout();
+		}, ms);
+	};
+	const stop = () => {
+		const elapsed = Date.now() - start;
+		clearClock();
+		armed = false;
+		if (runFor > elapsed) param?.onPause(runFor - elapsed);
+	};
+	const beat = () => {
+		if (ready) return;
+		ready = true;
+		param?.onReady();
+	};
+	/** The entry beat lands one frame after the row attaches, so the browser
+	* has painted the pre-enter state and the transition has something to
+	* animate from. An environment with no frame clock beats immediately. */
+	const schedule = () => {
+		if (typeof requestAnimationFrame === "function") requestAnimationFrame(beat);
+		else beat();
+	};
+	/** A clock that never elapses — a loading toast, or no limit at all. */
+	const clockable = (ms) => Number.isFinite(ms) && ms > 0;
+	if (param !== void 0) {
+		if (param.paused || !clockable(param.remaining)) armed = false;
+		else arm(param.remaining);
+		schedule();
+	}
+	return {
+		update: (next) => {
+			if (next === void 0) return;
+			if (next.dismissing) {
+				if (armed) stop();
+				clearClock();
+				timer = setTimeout(() => {
+					timer = void 0;
+					next.onRemove();
+				}, next.removeDelay);
+				return;
+			}
+			if (next.paused) {
+				if (armed) stop();
+				return;
+			}
+			if (!clockable(next.remaining)) {
+				clearClock();
+				armed = false;
+				return;
+			}
+			if (!armed || runFor !== next.remaining) arm(next.remaining);
+		},
+		destroy: clearClock
+	};
+});
+/**
+* The measurement half. A ResizeObserver reports the row's own box, so the
+* stack's offsets come from a height the element actually has rather than
+* from a measurement the machine guesses.
+*/
+const toastRow = createAction((node, param) => {
+	if (typeof ResizeObserver !== "function") return;
+	const measure = () => {
+		const height = node.offsetHeight;
+		if (height > 0) param?.onHeight(height);
+	};
+	const observer = new ResizeObserver(measure);
+	observer.observe(node);
+	return { destroy: () => observer.disconnect() };
+});
+/**
+* The region's document reflexes — the `trackHotKeyPress` and
+* `trackDocumentVisibility` effects. Both are listeners on the document,
+* which is what an action is for: the element it is attached to is the
+* region, and the only thing it does with it is focus it.
+*/
+const toastRegion = createAction((node, param) => {
+	const onKeyDown = (event) => {
+		const keys = param?.hotkey ?? [];
+		if (keys.length === 0) return;
+		if (!keys.every((key) => isModifier(key) ? event.getModifierState(key.slice(0, -3)) : event.code === key)) return;
+		event.preventDefault();
+		if (node instanceof HTMLElement) node.focus();
+	};
+	const onVisibility = () => {
+		param?.onIdleChange(document.visibilityState === "hidden");
+	};
+	document.addEventListener("keydown", onKeyDown, { capture: true });
+	if (param?.pauseOnPageIdle !== false) document.addEventListener("visibilitychange", onVisibility);
+	return { destroy: () => {
+		document.removeEventListener("keydown", onKeyDown, { capture: true });
+		document.removeEventListener("visibilitychange", onVisibility);
+	} };
+});
+/** A hotkey entry is a modifier name when it reads as one. */
+function isModifier(key) {
+	return key === "altKey" || key === "ctrlKey" || key === "metaKey" || key === "shiftKey";
+}
+export { toastRegion, toastRow, toastTimer };
+
+//# sourceMappingURL=toast-actions.js.map

package/dist/runtime/aria.d.ts

@@ -0,0 +1,231 @@
+/**
+ * The ARIA vocabulary: the attribute sets a part states.
+ *
+ * The attributes of a part belong to the pattern the part plays — a
+ * disclosure trigger, a list surface, a slider thumb, an option row — and
+ * not to the component that renders it. Stating a pattern once is what
+ * makes a change to it reach every part that plays it.
+ *
+ * A primitive states the attributes it owns and nothing else, so a part
+ * spreads it beside the attributes it owns itself.
+ *
+ * Two rules govern the shape of a primitive, and both are the framework's
+ * own conventions:
+ *
+ * - A member left out of the options is not in the fragment at all. A
+ *   member passed as `undefined` is in the fragment with no value, which
+ *   the framework drops when it writes the attribute. The difference is the
+ *   difference between a part that does not carry the attribute and a
+ *   part that carries it with nothing to say.
+ * - A value is the value the part already states. The corpus spells a
+ *   state either as the boolean or as the string the attribute reads in
+ *   the DOM, and both render the same attribute text, so the type admits
+ *   both and a part keeps the one it used.
+ *
+ * The single-attribute helpers are named after the attribute they own —
+ * `ariaDisabled` is `aria-disabled` — so a reader of a part's bag sees
+ * where the attribute came from. The composites are named after the role
+ * they play: a `disclosureTrigger` opens a region, a `listSurface` holds
+ * rows, a `sliderThumb` rides a range, an `optionRow` sits in a set, a
+ * `comboboxInput` completes what is typed into it.
+ */
+import { PartView } from "./component/define.js";
+/** The values an ARIA attribute may carry. */
+export type AriaValue = string | number | boolean | undefined;
+/** The attribute fragment a pattern contributes to a part's bag. */
+export type AriaFragment = Record<string, AriaValue>;
+/**
+ * A state an ARIA attribute states.
+ *
+ * The corpus spells a state either as the boolean or as the string the
+ * attribute reads in the DOM. Both render the same attribute text, so the
+ * type admits both.
+ */
+export type AriaState = boolean | "true" | "false";
+/** The popups a trigger can announce. */
+export type AriaHasPopup = "menu" | "dialog" | "listbox" | "tree" | "grid";
+/** How a combobox completes what is typed into it. */
+export type AriaAutocomplete = "none" | "inline" | "list" | "both";
+/** The direction a region reads in. */
+export type AriaOrientation = "horizontal" | "vertical";
+/** How eagerly a region is announced. */
+export type AriaLive = "off" | "polite" | "assertive";
+/** Where a part stands within a set. */
+export type AriaCurrent = "page" | "step" | "location" | "date" | "time" | boolean;
+/** A part of the scope, named for a relation that points at more than one. */
+export interface AriaPartRef {
+  /** The part the relation points at. */
+  readonly part: string;
+  /** The slot the relation points at, when the part is a slot. */
+  readonly slot?: unknown;
+}
+/**
+ * The element an ARIA relation points at.
+ *
+ * A relation names the part of the scope it points to and the scope mints
+ * the id; a relation that points at an element the scope does not own
+ * names the id itself; a relation that points at several elements names
+ * them as parts, and the ids are joined by a space.
+ */
+export type AriaTarget = {
+  readonly part: string;
+  readonly slot?: unknown;
+} | {
+  readonly id: string;
+} | {
+  readonly parts: readonly AriaPartRef[];
+};
+/**
+ * A part the user cannot act on.
+ *
+ * The state is stated rather than implied: the part is still in the page,
+ * and a reader has to hear that it is unavailable.
+ */
+export declare function ariaDisabled(state: AriaState | undefined): AriaFragment;
+/** A part that is not in the page for a reader. */
+export declare function ariaHidden(state: AriaState | undefined): AriaFragment;
+/** A part whose value is not valid. */
+export declare function ariaInvalid(state: AriaState | undefined): AriaFragment;
+/** A toggle that is held down. */
+export declare function ariaPressed(state: AriaState | undefined): AriaFragment;
+/** A part that is still working. */
+export declare function ariaBusy(state: AriaState | undefined): AriaFragment;
+/** Where a part stands within a set. */
+export declare function ariaCurrent(place: AriaCurrent | undefined): AriaFragment;
+/** The direction a region reads in. */
+export declare function ariaOrientation(dir: AriaOrientation | undefined): AriaFragment;
+/** The name a part gives itself beyond its role. */
+export declare function ariaRoleDescription(text: string | undefined): AriaFragment;
+/** A description of a part that no element owns. */
+export declare function ariaDescription(text: string | undefined): AriaFragment;
+/** How a combobox completes what is typed into it. */
+export declare function ariaAutocomplete(mode: AriaAutocomplete | undefined): AriaFragment;
+/**
+ * A prop's truth, as an ARIA state.
+ *
+ * The corpus states a boolean prop as its own truth: a prop that is absent
+ * or false says nothing, so the attribute is not written at all, and a
+ * prop that is true states the state.
+ */
+export declare function ariaFlag(value: unknown): boolean | undefined;
+/**
+ * A prop's value, as an ARIA state.
+ *
+ * A boolean prop is the state it is: a prop that is false states "false",
+ * and a prop that is absent states nothing at all.
+ */
+export declare function ariaState(value: unknown): AriaState | undefined;
+/** Whether a part must be filled in. */
+export declare function ariaRequired(state: AriaState | undefined): AriaFragment;
+/** Whether a part refuses edits. */
+export declare function ariaReadOnly(state: AriaState | undefined): AriaFragment;
+/** The element that describes a part. */
+export declare function ariaDescribedBy<C extends object>(scope: PartView<unknown, C>, target: AriaTarget | undefined): AriaFragment;
+/** The element that names a part. */
+export declare function ariaLabelledBy<C extends object>(scope: PartView<unknown, C>, target: AriaTarget | undefined): AriaFragment;
+/** The region a part controls. */
+export declare function ariaControls<C extends object>(scope: PartView<unknown, C>, target: AriaTarget | undefined): AriaFragment;
+/** The elements a part owns. */
+export declare function ariaOwns<C extends object>(scope: PartView<unknown, C>, target: AriaTarget | undefined): AriaFragment;
+/**
+ * A region that announces itself.
+ *
+ * The region says how loudly it speaks, whether it speaks as a whole, and
+ * which of its changes are worth speaking of.
+ */
+export declare function liveRegion(init: {
+  /** How eagerly the region is announced. */
+  readonly live?: AriaLive | undefined;
+  /** Whether the region is announced as a whole. */
+  readonly atomic?: AriaState | undefined;
+  /** Which of the region's changes are announced. */
+  readonly relevant?: string | undefined;
+}): AriaFragment;
+/**
+ * A control that opens a region.
+ *
+ * The trigger says whether the region is open, what kind of popup it
+ * opens, and which region that is. A trigger that opens no region states
+ * no `aria-controls`, and a part that is not a trigger at all states
+ * neither.
+ */
+export declare function disclosureTrigger<C extends object>(scope: PartView<unknown, C>, init: {
+  /** Whether the region the trigger opens is open. */
+  readonly expanded?: AriaState | undefined;
+  /** The kind of popup the trigger opens. */
+  readonly hasPopup?: AriaHasPopup | undefined;
+  /** The region the trigger opens. */
+  readonly controls?: AriaTarget | undefined;
+}): AriaFragment;
+/**
+ * A surface that holds rows.
+ *
+ * The surface says what names it, which row is the active descendant, and
+ * the selection states it carries.
+ */
+export declare function listSurface<C extends object>(scope: PartView<unknown, C>, init: {
+  /** The element that names the surface. */
+  readonly labelledBy?: AriaTarget | undefined;
+  /** The row the surface is on. */
+  readonly activeDescendant?: AriaTarget | undefined;
+  /** Whether more than one row may be chosen. */
+  readonly multiSelectable?: AriaState | undefined;
+  /** Whether the surface must be filled in. */
+  readonly required?: AriaState | undefined;
+  /** Whether the surface refuses edits. */
+  readonly readOnly?: AriaState | undefined;
+}): AriaFragment;
+/**
+ * A field that completes what is typed into it.
+ *
+ * The field says how it completes, which region it controls, whether that
+ * region is open, and which row it is on.
+ */
+export declare function comboboxInput<C extends object>(scope: PartView<unknown, C>, init: {
+  /** How the field completes what is typed into it. */
+  readonly autocomplete?: AriaAutocomplete | undefined;
+  /** The region the field controls. */
+  readonly controls?: AriaTarget | undefined;
+  /** Whether the region the field controls is open. */
+  readonly expanded?: AriaState | undefined;
+  /** The row the field is on. */
+  readonly activeDescendant?: AriaTarget | undefined;
+}): AriaFragment;
+/**
+ * A handle that rides a range.
+ *
+ * The thumb says the range it rides and where it sits in it; `text` is
+ * what a reader hears, which the number alone does not say.
+ */
+export declare function sliderThumb(init: {
+  /** The lowest value of the range. */
+  readonly min?: string | number | undefined;
+  /** The highest value of the range. */
+  readonly max?: string | number | undefined;
+  /** The value the thumb sits at. */
+  readonly now?: string | number | undefined;
+  /** The value a reader hears. */
+  readonly text?: string | undefined;
+}): AriaFragment;
+/**
+ * A row inside a set.
+ *
+ * A row is either selected or checked, never both: `selected` says the
+ * row is the chosen one, `checked` says the row carries a state of its
+ * own. `posInSet` and `setSize` place the row in the set it belongs to,
+ * and `level` places it in the hierarchy it belongs to.
+ */
+export declare function optionRow(init: {
+  /** Whether the row is the chosen one. */
+  readonly selected?: AriaState | undefined;
+  /** The state the row carries. */
+  readonly checked?: AriaState | undefined;
+  /** The row's place in the set. */
+  readonly posInSet?: string | number | undefined;
+  /** The size of the set the row belongs to. */
+  readonly setSize?: string | number | undefined;
+  /** The row's depth in the hierarchy. */
+  readonly level?: number | undefined;
+  /** Whether the row is unavailable to the user. */
+  readonly disabled?: AriaState | undefined;
+}): AriaFragment;