@c9up/nebula 0.1.0

package/src/organisms/Questionnaire.ts

@@ -0,0 +1,322 @@
+/**
+ * Questionnaire — a survey, one question per step.
+ *
+ * Composed rather than reimplemented: `RadioGroup`, `Checkbox`, `Input`,
+ * `Textarea`, `Progress` and `Button` already exist, so this file is the state
+ * machine over them — which question is showing, what has been answered, and
+ * whether the reader may move on.
+ *
+ * Three decisions worth stating, because each has an obvious wrong answer:
+ *
+ * **The step counter is announced.** A visual progress bar tells a sighted
+ * reader they are on question 3 of 8. `aria-live="polite"` on the counter is
+ * what tells everyone else, and without it the survey is a series of
+ * unexplained page changes.
+ *
+ * **Answers survive going back.** Moving to the previous question and forward
+ * again keeps what was typed. The alternative — clearing on navigation —
+ * punishes the reader for checking what they said a moment ago.
+ *
+ * **A required question blocks Next, and says why.** Disabling the button
+ * silently is the common version, and it leaves the reader clicking a dead
+ * control with no explanation. The message appears only after an attempt, so
+ * the survey does not open by telling you that you have done nothing wrong yet.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import { Button } from "../atoms/Button.js";
+import { Checkbox } from "../atoms/Checkbox.js";
+import { Input } from "../atoms/Input.js";
+import { Progress } from "../atoms/Progress.js";
+import { Textarea } from "../atoms/Textarea.js";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read } from "../lib/props.js";
+import { RadioGroup } from "../molecules/RadioGroup.js";
+
+export interface QuestionOption {
+	value: string;
+	label: Child;
+	description?: Child;
+}
+
+interface BaseQuestion {
+	/** Stable key. The answer is filed under it. */
+	id: string;
+	prompt: Child;
+	description?: Child;
+	/** Blocks Next until answered. */
+	required?: boolean;
+}
+
+export interface SingleChoiceQuestion extends BaseQuestion {
+	type: "single";
+	options: readonly QuestionOption[];
+}
+
+export interface MultipleChoiceQuestion extends BaseQuestion {
+	type: "multiple";
+	options: readonly QuestionOption[];
+}
+
+export interface FreeformQuestion extends BaseQuestion {
+	type: "text";
+	placeholder?: string;
+	/** Renders a textarea instead of a single-line input. */
+	multiline?: boolean;
+}
+
+export type Question =
+	| SingleChoiceQuestion
+	| MultipleChoiceQuestion
+	| FreeformQuestion;
+
+/** One answer: a value for single/text, a set for multiple. */
+export type Answer = string | readonly string[];
+export type Answers = Readonly<Record<string, Answer>>;
+
+export interface QuestionnaireProps {
+	questions: readonly Question[];
+	onComplete: (answers: Answers) => void;
+	onAnswerChange?: (id: string, answer: Answer) => void;
+	/** Allow skipping questions that are not required. Default `true`. */
+	skippable?: boolean;
+	showProgress?: boolean;
+	backLabel?: string;
+	nextLabel?: string;
+	skipLabel?: string;
+	submitLabel?: string;
+	class?: Reactive<string>;
+}
+
+function isSingle(question: Question): question is SingleChoiceQuestion {
+	return question.type === "single";
+}
+
+function isMultiple(question: Question): question is MultipleChoiceQuestion {
+	return question.type === "multiple";
+}
+
+/** Narrow an answer to the set form, for a multiple-choice question. */
+function asSet(answer: Answer | undefined): readonly string[] {
+	if (answer === undefined) return [];
+	return typeof answer === "string" ? [answer] : answer;
+}
+
+/** Narrow an answer to the single form. */
+function asValue(answer: Answer | undefined): string {
+	if (answer === undefined) return "";
+	return typeof answer === "string" ? answer : (answer[0] ?? "");
+}
+
+/** Has this question been answered at all? */
+export function isAnswered(
+	question: Question,
+	answer: Answer | undefined,
+): boolean {
+	if (answer === undefined) return false;
+	if (isMultiple(question)) return asSet(answer).length > 0;
+	return asValue(answer).trim() !== "";
+}
+
+export const Questionnaire = component<QuestionnaireProps>((props) => {
+	const total = props.questions.length;
+	const step = signal(0);
+	const answers = signal<Answers>({});
+	/** Set only after a blocked Next, so the survey does not open scolding. */
+	const attempted = signal(false);
+	const counterId = uid("questionnaire-counter");
+
+	const current = (): Question | undefined => props.questions[step()];
+
+	function answerOf(question: Question): Answer | undefined {
+		return answers()[question.id];
+	}
+
+	function record(question: Question, answer: Answer): void {
+		answers({ ...answers(), [question.id]: answer });
+		attempted(false);
+		props.onAnswerChange?.(question.id, answer);
+	}
+
+	function toggleChoice(question: Question, value: string): void {
+		const chosen = asSet(answerOf(question));
+		record(
+			question,
+			chosen.includes(value)
+				? chosen.filter((entry) => entry !== value)
+				: [...chosen, value],
+		);
+	}
+
+	function canAdvance(): boolean {
+		const question = current();
+		if (question === undefined) return false;
+		if (question.required !== true) return true;
+		return isAnswered(question, answerOf(question));
+	}
+
+	function advance(): void {
+		if (!canAdvance()) {
+			attempted(true);
+			return;
+		}
+		attempted(false);
+		if (step() < total - 1) step(step() + 1);
+		else props.onComplete(answers());
+	}
+
+	function goBack(): void {
+		attempted(false);
+		if (step() > 0) step(step() - 1);
+	}
+
+	function skip(): void {
+		attempted(false);
+		if (step() < total - 1) step(step() + 1);
+		else props.onComplete(answers());
+	}
+
+	const isLast = (): boolean => step() === total - 1;
+
+	return html`<section
+		data-slot="questionnaire"
+		aria-describedby="${counterId}"
+		class="${() => cn("flex w-full max-w-xl flex-col gap-6", read(props.class))}"
+	>
+		${
+			props.showProgress === false
+				? null
+				: html`<div class="flex flex-col gap-2">
+					${Progress({
+						value: () => step() + 1,
+						max: total,
+						label: "Questionnaire progress",
+					})}
+					<p
+						id="${counterId}"
+						aria-live="polite"
+						class="text-muted-foreground text-xs tabular-nums"
+					>${() => `Question ${step() + 1} of ${total}`}</p>
+				</div>`
+		}
+
+		${() => renderQuestion()}
+
+		<div class="flex items-center justify-between gap-2">
+			${Button({
+				variant: "ghost",
+				disabled: () => step() === 0,
+				onClick: goBack,
+				children: props.backLabel ?? "Back",
+			})}
+			<div class="flex items-center gap-2">
+				${() =>
+					props.skippable === false || current()?.required === true
+						? null
+						: Button({
+								variant: "ghost",
+								onClick: skip,
+								children: props.skipLabel ?? "Skip",
+							})}
+				${Button({
+					onClick: advance,
+					children: () =>
+						isLast()
+							? (props.submitLabel ?? "Submit")
+							: (props.nextLabel ?? "Next"),
+				})}
+			</div>
+		</div>
+	</section>`;
+
+	function renderQuestion(): Child {
+		const question = current();
+		if (question === undefined) return null;
+
+		const blocked = attempted() && !canAdvance();
+		const errorId = `${question.id}-required`;
+
+		return html`<div data-slot="questionnaire-question" class="flex flex-col gap-3">
+			<div class="flex flex-col gap-1">
+				<h2 class="text-lg font-medium">
+					${question.prompt}${
+						question.required === true
+							? html`<span aria-hidden="true" class="text-destructive"> *</span>`
+							: null
+					}
+				</h2>
+				${
+					question.description === undefined
+						? null
+						: html`<p class="text-muted-foreground text-sm">${question.description}</p>`
+				}
+			</div>
+			${renderControl(question, errorId, blocked)}
+			<p
+				id="${errorId}"
+				role="alert"
+				class="text-destructive text-sm empty:hidden"
+			>${blocked ? "This question needs an answer before you can continue." : ""}</p>
+		</div>`;
+	}
+
+	function renderControl(
+		question: Question,
+		errorId: string,
+		blocked: boolean,
+	): Child {
+		if (isSingle(question)) {
+			return RadioGroup({
+				name: question.id,
+				options: question.options.map((option) => ({
+					value: option.value,
+					label: option.label,
+					description: option.description,
+				})),
+				value: () => asValue(answerOf(question)),
+				onValueChange: (value) => record(question, value),
+			});
+		}
+
+		if (isMultiple(question)) {
+			return html`<div role="group" class="grid gap-3">
+				${question.options.map((option) => {
+					const id = uid("questionnaire-choice");
+					return html`<div class="flex items-start gap-3">
+						${Checkbox({
+							id,
+							name: question.id,
+							value: option.value,
+							checked: () => asSet(answerOf(question)).includes(option.value),
+							onCheckedChange: () => toggleChoice(question, option.value),
+						})}
+						<div class="grid gap-1 leading-none">
+							<label for="${id}" class="text-sm leading-none font-medium select-none"
+								>${option.label}</label
+							>
+							${
+								option.description === undefined
+									? null
+									: html`<p class="text-muted-foreground text-sm">${option.description}</p>`
+							}
+						</div>
+					</div>`;
+				})}
+			</div>`;
+		}
+
+		const shared = {
+			name: question.id,
+			placeholder: question.placeholder,
+			invalid: blocked,
+			describedBy: errorId,
+			value: () => asValue(answerOf(question)),
+			onInput: (value: string) => record(question, value),
+		};
+		return question.multiline === true
+			? Textarea({ ...shared, rows: 4 })
+			: Input(shared);
+	}
+});

package/src/organisms/Select.ts

@@ -0,0 +1,286 @@
+/**
+ * Select — choose one option from a list.
+ *
+ * A custom listbox, not a styled `<select>`. This is the one place nebula
+ * gives up native behaviour, and the reason is that a `<select>` popup is
+ * drawn by the operating system: its font, its colours and its checkmarks
+ * cannot be styled at all, and options cannot contain anything but text. A
+ * design system that can style every control except this one is not a design
+ * system.
+ *
+ * What that costs is everything the native control was doing for free, and it
+ * all has to be put back:
+ *
+ * - `role="combobox"` on the trigger, `role="listbox"` on the panel,
+ *   `role="option"` with `aria-selected` on each entry.
+ * - `aria-activedescendant` rather than moving DOM focus — the listbox pattern
+ *   keeps focus on the trigger and *names* the highlighted option, which is
+ *   what lets a screen reader announce it without the focus ring jumping.
+ * - Type-ahead, arrows, Home/End, Enter and Escape.
+ * - A hidden input, so the control still posts with a plain HTML form.
+ *
+ * The panel is sized to the trigger and capped at the space available below
+ * it, so a hundred-option list scrolls rather than running off the screen.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { CheckIcon, ChevronDownIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { type Reactive, read, readOr } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { focusSilently } from "../primitives/focusable.js";
+
+export interface SelectOption {
+	value: string;
+	label: string;
+	disabled?: boolean;
+	/** Groups consecutive options under a heading. */
+	group?: string;
+}
+
+export interface SelectProps {
+	options: readonly SelectOption[];
+	name?: string;
+	value?: Reactive<string | undefined>;
+	defaultValue?: string;
+	placeholder?: string;
+	disabled?: Reactive<boolean>;
+	invalid?: Reactive<boolean>;
+	required?: boolean;
+	class?: Reactive<string>;
+	contentClass?: Reactive<string>;
+	onValueChange?: (value: string) => void;
+}
+
+export const selectTriggerClasses =
+	"border-input dark:bg-input/30 dark:hover:bg-input/50 flex h-9 w-fit min-w-0 items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-[placeholder]:text-muted-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";
+
+export const Select = component<SelectProps>((props) => {
+	const triggerId = uid("select-trigger");
+	const listId = uid("select-list");
+	const optionIds = new Map<string, string>();
+	for (const option of props.options)
+		optionIds.set(option.value, uid("select-option"));
+
+	const open = signal(false);
+	const selection = controllable<string | undefined>({
+		value: props.value,
+		initial: props.defaultValue,
+		onChange: (next) => {
+			if (next !== undefined) props.onValueChange?.(next);
+		},
+	});
+	/** The option the keyboard is on. Distinct from the selected one. */
+	const active = signal<string | undefined>(undefined);
+
+	const enabled = (): readonly SelectOption[] =>
+		props.options.filter((option) => option.disabled !== true);
+
+	function labelFor(value: string | undefined): string | undefined {
+		return props.options.find((option) => option.value === value)?.label;
+	}
+
+	function choose(value: string): void {
+		selection.set(value);
+		active(value);
+		open(false);
+		focusSilently(document.getElementById(triggerId));
+	}
+
+	function moveActive(delta: number): void {
+		const list = enabled();
+		if (list.length === 0) return;
+		const from = list.findIndex((option) => option.value === active());
+		const next = from === -1 ? (delta > 0 ? 0 : list.length - 1) : from + delta;
+		const clamped = Math.min(Math.max(next, 0), list.length - 1);
+		const target = list[clamped];
+		if (target !== undefined) active(target.value);
+	}
+
+	/**
+	 * Type-ahead over the option *data*, not over elements.
+	 *
+	 * The shared primitive walks DOM nodes, which works for menus where focus
+	 * moves. Here focus stays on the trigger and only `aria-activedescendant`
+	 * moves, so the search runs over the options array instead.
+	 */
+	let buffer = "";
+	let bufferTimer: ReturnType<typeof setTimeout> | undefined;
+
+	function seekByText(character: string): void {
+		buffer += character.toLowerCase();
+		if (bufferTimer !== undefined) clearTimeout(bufferTimer);
+		bufferTimer = setTimeout(() => {
+			buffer = "";
+		}, 1000);
+
+		const list = enabled();
+		const from = list.findIndex((option) => option.value === active());
+		for (let i = 1; i <= list.length; i += 1) {
+			const option = list[(Math.max(from, 0) + i) % list.length];
+			if (option === undefined) continue;
+			if (option.label.toLowerCase().startsWith(buffer)) {
+				active(option.value);
+				return;
+			}
+		}
+	}
+
+	function onTriggerKeyDown(event: KeyboardEvent): void {
+		if (readOr(props.disabled, false)) return;
+
+		if (!open()) {
+			if (
+				event.key === "ArrowDown" ||
+				event.key === "Enter" ||
+				event.key === " "
+			) {
+				event.preventDefault();
+				active(selection.current() ?? enabled()[0]?.value);
+				open(true);
+			}
+			return;
+		}
+
+		if (event.key === "ArrowDown") {
+			event.preventDefault();
+			moveActive(1);
+		} else if (event.key === "ArrowUp") {
+			event.preventDefault();
+			moveActive(-1);
+		} else if (event.key === "Home") {
+			event.preventDefault();
+			active(enabled()[0]?.value);
+		} else if (event.key === "End") {
+			event.preventDefault();
+			active(enabled()[enabled().length - 1]?.value);
+		} else if (event.key === "Enter" || event.key === " ") {
+			event.preventDefault();
+			const current = active();
+			if (current !== undefined) choose(current);
+		} else if (event.key.length === 1 && !event.metaKey && !event.ctrlKey) {
+			seekByText(event.key);
+		}
+	}
+
+	floatingSurface({
+		anchor: () => document.getElementById(triggerId),
+		open: () => open(),
+		onClose: () => open(false),
+		placement: "bottom-start",
+		offset: 4,
+		matchWidth: true,
+		// Focus never enters the panel — the listbox pattern keeps it on the
+		// trigger — so nothing here traps or moves it.
+		content: renderList,
+		onOpened: scrollActiveIntoView,
+	});
+
+	function renderList(): ReturnType<typeof html> {
+		let lastGroup: string | undefined;
+
+		return html`<div
+			data-slot="select-content"
+			id="${listId}"
+			role="listbox"
+			aria-labelledby="${triggerId}"
+			class="${cn(
+				"bg-popover text-popover-foreground z-50 max-h-(--nebula-available-height) min-w-(--nebula-anchor-width) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md",
+				zoomInOut,
+				read(props.contentClass),
+			)}"
+		>
+			${props.options.map((option) => {
+				const heading =
+					option.group !== undefined && option.group !== lastGroup
+						? html`<div class="text-muted-foreground px-2 py-1.5 text-xs">${option.group}</div>`
+						: null;
+				lastGroup = option.group;
+				return [heading, renderOption(option)];
+			})}
+		</div>`;
+	}
+
+	function renderOption(option: SelectOption): Child {
+		const chosen = (): boolean => selection.current() === option.value;
+		return html`<div
+			role="option"
+			id="${optionIds.get(option.value)}"
+			data-slot="select-item"
+			data-value="${option.value}"
+			aria-selected="${() => (chosen() ? "true" : "false")}"
+			data-active="${() => (active() === option.value ? "" : undefined)}"
+			data-disabled="${option.disabled === true ? "" : undefined}"
+			class="relative flex w-full cursor-default select-none items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-none data-[active]:bg-accent data-[active]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50"
+			@click="${() => {
+				if (option.disabled !== true) choose(option.value);
+			}}"
+			@pointerenter="${() => {
+				if (option.disabled !== true) active(option.value);
+			}}"
+		>
+			<span class="flex-1 truncate">${option.label}</span>
+			<span class="absolute right-2 flex size-3.5 items-center justify-center">
+				${() => (chosen() ? CheckIcon({ class: "size-4" }) : null)}
+			</span>
+		</div>`;
+	}
+
+	/**
+	 * Bring the highlighted option into view when the panel opens.
+	 *
+	 * Opening a two-hundred-option select on the one already chosen and showing
+	 * the top of the list is the standard failure of a custom select.
+	 */
+	function scrollActiveIntoView(panel: HTMLElement): void {
+		const current = active() ?? selection.current();
+		if (current === undefined) return;
+		const id = optionIds.get(current);
+		if (id === undefined) return;
+		panel
+			.querySelector(`#${CSS.escape(id)}`)
+			?.scrollIntoView({ block: "nearest" });
+	}
+
+	return html`<div data-slot="select" class="${() => cn("inline-flex", read(props.class))}">
+		<button
+			type="button"
+			data-slot="select-trigger"
+			id="${triggerId}"
+			role="combobox"
+			aria-haspopup="listbox"
+			aria-expanded="${() => (open() ? "true" : "false")}"
+			aria-controls="${() => (open() ? listId : undefined)}"
+			aria-activedescendant="${() => {
+				const current = active();
+				return open() && current !== undefined
+					? optionIds.get(current)
+					: undefined;
+			}}"
+			aria-invalid="${() => (read(props.invalid) === true ? "true" : undefined)}"
+			aria-required="${props.required === true ? "true" : undefined}"
+			data-placeholder="${() => (selection.current() === undefined ? "" : undefined)}"
+			?disabled="${() => readOr(props.disabled, false)}"
+			class="${() => cn(selectTriggerClasses, read(props.class))}"
+			@click="${() => {
+				active(selection.current() ?? enabled()[0]?.value);
+				open(!open());
+			}}"
+			@keydown="${onTriggerKeyDown}"
+		>
+			<span class="truncate"
+				>${() => labelFor(selection.current()) ?? props.placeholder ?? "Select…"}</span
+			>
+			${ChevronDownIcon({ class: "size-4 opacity-50" })}
+		</button>
+		<input
+			type="hidden"
+			name="${props.name}"
+			.value="${() => selection.current() ?? ""}"
+		/>
+	</div>`;
+});