@seekalfred/primitives 0.5.1 → 0.7.1

package/dist/onboarding-checklist/index.d.ts

@@ -0,0 +1,2 @@
+import { OnboardingChecklist, OnboardingChecklistProps, OnboardingStep } from "./onboarding-checklist.js";
+export { OnboardingChecklist, type OnboardingChecklistProps, type OnboardingStep };

package/dist/onboarding-checklist/index.js

@@ -0,0 +1,2 @@
+import { OnboardingChecklist } from "./onboarding-checklist.js";
+export { OnboardingChecklist };

package/dist/onboarding-checklist/onboarding-checklist.d.ts

@@ -0,0 +1,55 @@
+//#region src/onboarding-checklist/onboarding-checklist.d.ts
+/**
+ * OnboardingChecklist: a getting-started card for a new account or workspace,
+ * for a short, one-time setup of three to eight loosely ordered steps. (Use a
+ * Stepper when the order is strict and steps map to screens.)
+ *
+ * The progress ring and the count follow every check: the ring fills on the
+ * morph spring, the count rolls its digits, and at 100% a tick draws in the
+ * ring while the title morphs to `doneTitle`. A checked step fills its circle
+ * from the centre, draws its tick and strikes its title through; 720ms later it
+ * folds into a "N completed" row that opens again, and the next unfinished step
+ * opens and takes focus if the finished one had it. A step with an `actionLabel`
+ * runs `onAction`: resolving checks the step, throwing an Error keeps it open
+ * and shows the message. The body can be hidden and shown again.
+ *
+ * Rows and panels open and close their height on a spring that never
+ * overshoots, closing a little quicker. Nothing animates on first render, and
+ * reduced motion removes the height animation and keeps short fades.
+ *
+ * Built on plain buttons and the shared swap and rolling-number helpers; the
+ * action is the library's ActionButton, whose arrow becomes a spinner and then
+ * a tick that draws itself. Keyboard: Up and Down walk the step titles,
+ * Home and End jump to the first and last, Enter or Space expands a step,
+ * toggles its checkbox or runs its action.
+ */
+export interface OnboardingStep {
+  id: string;
+  title: string;
+  description?: string;
+  /** Label of the button that does the step. Without it, the step is checked off by hand. */
+  actionLabel?: string;
+  /** Runs the step. Resolve to check it off; throw an Error to keep it open and show the error's message. */
+  onAction?: () => void | Promise<void>;
+}
+export interface OnboardingChecklistProps {
+  /** Card title while steps remain. */
+  title: string;
+  /** Title once every step is done. @default "You’re all set" */
+  doneTitle?: string;
+  /** Steps in order. */
+  steps: OnboardingStep[];
+  /** Step ids that start completed. */
+  defaultCompleted?: string[];
+  /** Called with the completed ids, in step order, whenever they change. */
+  onCompletedChange?: (completed: string[]) => void;
+  /** Starts with the body collapsed. @default false */
+  defaultHidden?: boolean;
+  /** Called when the Hide or Show button is used. */
+  onHiddenChange?: (hidden: boolean) => void;
+  /** Extra classes for the card. Merged last. */
+  className?: string;
+}
+export declare const OnboardingChecklist: import("react").ForwardRefExoticComponent<OnboardingChecklistProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+//# sourceMappingURL=onboarding-checklist.d.ts.map

package/dist/onboarding-checklist/onboarding-checklist.js

@@ -0,0 +1,577 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mergeRefs } from "../lib/merge-refs.js";
+import { ActionButton } from "../action-button/action-button.js";
+import { SwapText } from "../lib/swap-text.js";
+import { RollingNumber } from "../lib/field-message.js";
+import { forwardRef, useEffect, useId, useMemo, useReducer, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/onboarding-checklist/onboarding-checklist.tsx
+/** How long a checked step stays in place, struck through, before it folds into the completed row. */
+const SETTLE_MS = 720;
+const ordered = (ids, steps) => steps.map((step) => step.id).filter((id) => ids.includes(id));
+const without = (ids, id) => ids.filter((item) => item !== id);
+const omit = (errors, id) => Object.fromEntries(Object.entries(errors).filter(([key]) => key !== id));
+const titleOf = (steps, id) => steps.find((step) => step.id === id)?.title ?? "Step";
+function init({ steps, completed, hidden }) {
+	const done = ordered(completed, steps);
+	return {
+		done,
+		settled: done,
+		expanded: steps.find((step) => !done.includes(step.id))?.id ?? null,
+		errors: {},
+		groupOpen: false,
+		hidden,
+		message: ""
+	};
+}
+function reducer(state, action) {
+	switch (action.type) {
+		case "check": {
+			if (state.done.includes(action.id)) return state;
+			const done = ordered([...state.done, action.id], action.steps);
+			const total = action.steps.length;
+			return {
+				...state,
+				done,
+				errors: omit(state.errors, action.id),
+				message: done.length === total ? `All ${total} steps done.` : `${titleOf(action.steps, action.id)} done. ${done.length} of ${total} complete.`
+			};
+		}
+		case "uncheck": {
+			if (!state.done.includes(action.id)) return state;
+			const done = without(state.done, action.id);
+			return {
+				...state,
+				done,
+				settled: without(state.settled, action.id),
+				expanded: state.expanded ?? action.id,
+				message: `${titleOf(action.steps, action.id)} marked as not done. ${done.length} of ${action.steps.length} complete.`
+			};
+		}
+		case "settle": {
+			if (!state.done.includes(action.id) || state.settled.includes(action.id)) return state;
+			let expanded = state.expanded;
+			if (expanded === action.id) {
+				const order = action.steps.map((step) => step.id);
+				const start = order.indexOf(action.id);
+				expanded = order.map((_, offset) => order[(start + offset + 1) % order.length]).find((id) => !state.done.includes(id)) ?? null;
+			}
+			return {
+				...state,
+				settled: ordered([...state.settled, action.id], action.steps),
+				expanded
+			};
+		}
+		case "expand": return {
+			...state,
+			expanded: state.expanded === action.id ? null : action.id
+		};
+		case "start": return {
+			...state,
+			errors: omit(state.errors, action.id)
+		};
+		case "fail": return {
+			...state,
+			errors: {
+				...state.errors,
+				[action.id]: action.message
+			},
+			message: action.message
+		};
+		case "group": return {
+			...state,
+			groupOpen: !state.groupOpen
+		};
+		case "hide": return {
+			...state,
+			hidden: !state.hidden
+		};
+	}
+}
+const Chevron = () => /* @__PURE__ */ jsx("svg", {
+	width: 16,
+	height: 16,
+	viewBox: "0 0 24 24",
+	fill: "none",
+	stroke: "currentColor",
+	strokeWidth: 1.75,
+	strokeLinecap: "round",
+	strokeLinejoin: "round",
+	"aria-hidden": "true",
+	children: /* @__PURE__ */ jsx("path", { d: "m18 15-6-6-6 6" })
+});
+/**
+* A box that opens and closes its height (a grid track going between 0fr and 1fr).
+* Closed, it is visibility: hidden once folded, so it leaves the tab order.
+*/
+function Collapse({ show, children }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-shown": show || void 0,
+		className: "checklist-collapse",
+		children: /* @__PURE__ */ jsx("div", { children })
+	});
+}
+/** Every label the slot can show sits invisibly underneath, so a swap never changes the slot's size. */
+function SwapLabel({ text, options }) {
+	return /* @__PURE__ */ jsxs("span", {
+		className: "checklist-swap",
+		"aria-hidden": "true",
+		children: [options.map((option, index) => /* @__PURE__ */ jsx("span", {
+			className: "checklist-swap-sizer",
+			children: option
+		}, index)), /* @__PURE__ */ jsx(SwapText, {
+			swapKey: text,
+			motion: "rise",
+			className: "checklist-swap-item",
+			children: text
+		})]
+	});
+}
+/** The ring's stroke fills on a spring as steps are checked; once every step is done a tick draws in its center. */
+function ProgressRing({ done, total }) {
+	const ratio = total ? done / total : 0;
+	const complete = total > 0 && done === total;
+	return /* @__PURE__ */ jsxs("span", {
+		className: "checklist-ring",
+		role: "progressbar",
+		"aria-label": "Setup progress",
+		"aria-valuemin": 0,
+		"aria-valuemax": total,
+		"aria-valuenow": done,
+		"aria-valuetext": `${done} of ${total} steps done`,
+		children: [/* @__PURE__ */ jsxs("svg", {
+			viewBox: "0 0 40 40",
+			fill: "none",
+			"aria-hidden": "true",
+			children: [/* @__PURE__ */ jsx("circle", {
+				className: "checklist-ring-track",
+				cx: "20",
+				cy: "20",
+				r: "17",
+				strokeWidth: 3
+			}), /* @__PURE__ */ jsx("g", {
+				transform: "rotate(-90 20 20)",
+				children: /* @__PURE__ */ jsx("circle", {
+					className: "checklist-ring-fill",
+					cx: "20",
+					cy: "20",
+					r: "17",
+					strokeWidth: 3,
+					strokeLinecap: "round",
+					pathLength: 1,
+					"data-started": ratio > 0 ? "" : void 0,
+					style: { "--ratio": ratio }
+				})
+			})]
+		}), /* @__PURE__ */ jsx("span", {
+			className: "checklist-ring-tick",
+			"aria-hidden": "true",
+			children: /* @__PURE__ */ jsx(SwapText, {
+				swapKey: complete ? "tick" : "",
+				motion: "glyph",
+				className: "grid place-items-center",
+				children: complete ? /* @__PURE__ */ jsx("svg", {
+					viewBox: "0 0 40 40",
+					fill: "none",
+					children: /* @__PURE__ */ jsx("path", {
+						className: "checklist-draw",
+						pathLength: 1,
+						d: "M13.5 20.5 18 25l8.5-9.5",
+						stroke: "currentColor",
+						strokeWidth: 2.25,
+						strokeLinecap: "round",
+						strokeLinejoin: "round"
+					})
+				}) : null
+			})
+		})]
+	});
+}
+/** The fill grows from the center while the tick draws from its short stroke; unchecking retracts both quickly. */
+function CheckButton({ checked, labelledBy, onToggle }) {
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		role: "checkbox",
+		"aria-checked": checked,
+		"aria-labelledby": labelledBy,
+		className: "checklist-check",
+		"data-check": "",
+		onClick: onToggle,
+		children: /* @__PURE__ */ jsxs("span", {
+			className: "checklist-check-visual",
+			"aria-hidden": "true",
+			children: [/* @__PURE__ */ jsx("span", { className: "checklist-check-fill" }), /* @__PURE__ */ jsx("svg", {
+				className: "checklist-check-mark",
+				viewBox: "0 0 22 22",
+				fill: "none",
+				children: /* @__PURE__ */ jsx("path", {
+					pathLength: 1,
+					d: "M6.75 11.25 9.75 14.25 15.25 8.25",
+					stroke: "currentColor",
+					strokeWidth: 1.75,
+					strokeLinecap: "round",
+					strokeLinejoin: "round"
+				})
+			})]
+		})
+	});
+}
+function StepItem({ step, baseId, done, settled, expanded, error, onToggle, onExpand, onRun }) {
+	const titleId = `${baseId}-${step.id}-title`;
+	const panelId = `${baseId}-${step.id}-panel`;
+	const [lastError, setLastError] = useState(error);
+	if (error && error !== lastError) setLastError(error);
+	return /* @__PURE__ */ jsx("li", {
+		"data-step": step.id,
+		"data-done": done || void 0,
+		"data-current": expanded || void 0,
+		"data-open": settled ? void 0 : "",
+		children: /* @__PURE__ */ jsx(Collapse, {
+			show: !settled,
+			children: /* @__PURE__ */ jsxs("div", {
+				className: "checklist-step-inner",
+				children: [/* @__PURE__ */ jsx(CheckButton, {
+					checked: done,
+					labelledBy: titleId,
+					onToggle
+				}), /* @__PURE__ */ jsxs("div", {
+					className: "checklist-step-main",
+					children: [/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "checklist-step-title",
+						"data-title": "",
+						"aria-expanded": expanded,
+						"aria-controls": panelId,
+						onClick: onExpand,
+						children: /* @__PURE__ */ jsx("span", {
+							id: titleId,
+							className: "checklist-title-text",
+							children: step.title
+						})
+					}), /* @__PURE__ */ jsx(Collapse, {
+						show: expanded,
+						children: /* @__PURE__ */ jsxs("div", {
+							id: panelId,
+							role: "region",
+							"aria-labelledby": titleId,
+							className: "checklist-panel-inner",
+							children: [
+								step.description ? /* @__PURE__ */ jsx("p", {
+									className: "checklist-description",
+									children: step.description
+								}) : null,
+								/* @__PURE__ */ jsx(Collapse, {
+									show: Boolean(error),
+									children: /* @__PURE__ */ jsx("p", {
+										role: "alert",
+										className: "checklist-error",
+										children: lastError
+									})
+								}),
+								step.actionLabel ? /* @__PURE__ */ jsx(ActionButton, {
+									variant: "primary",
+									size: "sm",
+									className: "mt-3",
+									"data-primary": "",
+									pendingLabel: step.actionLabel,
+									successLabel: step.actionLabel,
+									onAction: onRun,
+									children: step.actionLabel
+								}) : null
+							]
+						})
+					})]
+				})]
+			})
+		})
+	});
+}
+const OnboardingChecklist = forwardRef(function OnboardingChecklist({ title, doneTitle = "You’re all set", steps, defaultCompleted = [], onCompletedChange, defaultHidden = false, onHiddenChange, className }, ref) {
+	const baseId = useId();
+	const [state, dispatch] = useReducer(reducer, {
+		steps,
+		completed: defaultCompleted,
+		hidden: defaultHidden
+	}, init);
+	const root = useRef(null);
+	const refs = useMemo(() => mergeRefs(ref, root), [ref]);
+	const timers = useRef(/* @__PURE__ */ new Map());
+	const focusRequest = useRef(null);
+	const reportCompleted = useRef(onCompletedChange);
+	const reported = useRef(state.done);
+	useEffect(() => {
+		reportCompleted.current = onCompletedChange;
+	});
+	useEffect(() => {
+		if (reported.current === state.done) return;
+		reported.current = state.done;
+		reportCompleted.current?.(state.done);
+	}, [state.done]);
+	useEffect(() => {
+		const pending = timers.current;
+		return () => pending.forEach(clearTimeout);
+	}, []);
+	useEffect(() => {
+		const request = focusRequest.current;
+		const node = root.current;
+		if (!request || !node) return;
+		focusRequest.current = null;
+		let target;
+		if (request === "next") {
+			const next = state.expanded ? node.querySelector(`[data-step="${state.expanded}"][data-open]`) : null;
+			target = next?.querySelector("[data-primary]") ?? next?.querySelector("[data-title]") ?? node.querySelector("[data-group-toggle]");
+		} else target = node.querySelector(`[data-step="${request.id}"][data-open] [data-check]`);
+		target?.focus({ preventScroll: true });
+	});
+	function check(id) {
+		dispatch({
+			type: "check",
+			id,
+			steps
+		});
+		if (timers.current.has(id)) return;
+		timers.current.set(id, setTimeout(() => {
+			timers.current.delete(id);
+			if (root.current?.querySelector(`[data-step="${id}"]`)?.contains(document.activeElement)) focusRequest.current = "next";
+			dispatch({
+				type: "settle",
+				id,
+				steps
+			});
+		}, SETTLE_MS));
+	}
+	function uncheck(id, fromGroup) {
+		clearTimeout(timers.current.get(id));
+		timers.current.delete(id);
+		if (fromGroup) focusRequest.current = { id };
+		dispatch({
+			type: "uncheck",
+			id,
+			steps
+		});
+	}
+	async function run(step) {
+		if (!step.onAction || state.done.includes(step.id)) return;
+		dispatch({
+			type: "start",
+			id: step.id,
+			steps
+		});
+		try {
+			await step.onAction();
+		} catch (error) {
+			dispatch({
+				type: "fail",
+				id: step.id,
+				message: error instanceof Error && error.message ? error.message : "That didn’t work. Try again."
+			});
+			throw error;
+		}
+		check(step.id);
+	}
+	function toggleHidden() {
+		dispatch({ type: "hide" });
+		onHiddenChange?.(!state.hidden);
+	}
+	/** Up and Down walk the step titles, Home and End jump to the first and last. */
+	function navigate(event) {
+		const target = event.target;
+		if (!target.matches("[data-title]") || ![
+			"ArrowDown",
+			"ArrowUp",
+			"Home",
+			"End"
+		].includes(event.key)) return;
+		const titles = Array.from(event.currentTarget.querySelectorAll("li[data-open] [data-title]"));
+		const index = titles.indexOf(target);
+		const next = event.key === "Home" ? 0 : event.key === "End" ? titles.length - 1 : (index + (event.key === "ArrowDown" ? 1 : -1) + titles.length) % titles.length;
+		event.preventDefault();
+		titles[next]?.focus();
+	}
+	const total = steps.length;
+	const doneCount = state.done.length;
+	const allDone = total > 0 && doneCount === total;
+	const completed = steps.filter((step) => state.settled.includes(step.id));
+	const titleId = `${baseId}-title`;
+	const bodyId = `${baseId}-body`;
+	const groupId = `${baseId}-completed`;
+	return /* @__PURE__ */ jsxs("section", {
+		ref: refs,
+		"aria-labelledby": titleId,
+		"data-slot": "onboarding-checklist",
+		"data-complete": allDone || void 0,
+		"data-hidden": state.hidden || void 0,
+		className: cn("checklist box-border font-sans", className),
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "checklist-header",
+				children: [
+					/* @__PURE__ */ jsx(ProgressRing, {
+						done: doneCount,
+						total
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "checklist-heading",
+						children: [/* @__PURE__ */ jsxs("h3", {
+							id: titleId,
+							className: "checklist-title",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "sr-only",
+								children: allDone ? doneTitle : title
+							}), /* @__PURE__ */ jsx(SwapLabel, {
+								text: allDone ? doneTitle : title,
+								options: [title, doneTitle]
+							})]
+						}), /* @__PURE__ */ jsxs("p", {
+							className: "checklist-count",
+							children: [/* @__PURE__ */ jsxs("span", {
+								className: "sr-only",
+								children: [
+									doneCount,
+									" of ",
+									total,
+									" done"
+								]
+							}), /* @__PURE__ */ jsxs("span", {
+								className: "checklist-count-visual",
+								"aria-hidden": "true",
+								children: [
+									/* @__PURE__ */ jsx(RollingNumber, { word: String(doneCount) }),
+									"\xA0of ",
+									total,
+									" done"
+								]
+							})]
+						})]
+					}),
+					/* @__PURE__ */ jsxs("button", {
+						type: "button",
+						className: "checklist-hide",
+						"aria-expanded": !state.hidden,
+						"aria-controls": bodyId,
+						onClick: toggleHidden,
+						children: [
+							/* @__PURE__ */ jsx("span", {
+								className: "checklist-hide-label",
+								children: /* @__PURE__ */ jsx(SwapLabel, {
+									text: state.hidden ? "Show" : "Hide",
+									options: ["Hide", "Show"]
+								})
+							}),
+							/* @__PURE__ */ jsxs("span", {
+								className: "sr-only",
+								children: [state.hidden ? "Show" : "Hide", " checklist"]
+							}),
+							/* @__PURE__ */ jsx("span", {
+								className: "checklist-chevron",
+								"aria-hidden": "true",
+								"data-flipped": state.hidden || void 0,
+								children: /* @__PURE__ */ jsx(Chevron, {})
+							})
+						]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				id: bodyId,
+				"data-shown": state.hidden ? void 0 : "",
+				className: "checklist-collapse",
+				children: /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsxs("div", {
+					className: "checklist-body-inner",
+					children: [/* @__PURE__ */ jsx("ul", {
+						className: "checklist-list",
+						"aria-label": "Steps to do",
+						"aria-hidden": completed.length === total ? true : void 0,
+						onKeyDown: navigate,
+						children: steps.map((step) => /* @__PURE__ */ jsx(StepItem, {
+							step,
+							baseId,
+							done: state.done.includes(step.id),
+							settled: state.settled.includes(step.id),
+							expanded: state.expanded === step.id,
+							error: state.errors[step.id],
+							onToggle: () => state.done.includes(step.id) ? uncheck(step.id, false) : check(step.id),
+							onExpand: () => dispatch({
+								type: "expand",
+								id: step.id,
+								steps
+							}),
+							onRun: () => run(step)
+						}, step.id))
+					}), /* @__PURE__ */ jsxs(Collapse, {
+						show: completed.length > 0,
+						children: [/* @__PURE__ */ jsxs("button", {
+							type: "button",
+							className: "checklist-group-toggle",
+							"data-group-toggle": "",
+							"aria-expanded": state.groupOpen,
+							"aria-controls": groupId,
+							onClick: () => dispatch({ type: "group" }),
+							children: [
+								/* @__PURE__ */ jsxs("span", {
+									className: "sr-only",
+									children: [completed.length, " completed"]
+								}),
+								/* @__PURE__ */ jsxs("span", {
+									className: "checklist-count-visual",
+									"aria-hidden": "true",
+									children: [/* @__PURE__ */ jsx(RollingNumber, { word: String(completed.length) }), "\xA0completed"]
+								}),
+								/* @__PURE__ */ jsx("span", {
+									className: "checklist-chevron",
+									"aria-hidden": "true",
+									"data-flipped": state.groupOpen ? void 0 : "",
+									children: /* @__PURE__ */ jsx(Chevron, {})
+								})
+							]
+						}), /* @__PURE__ */ jsx(Collapse, {
+							show: state.groupOpen,
+							children: /* @__PURE__ */ jsx("div", {
+								id: groupId,
+								children: /* @__PURE__ */ jsx("ul", {
+									className: "checklist-list",
+									"aria-label": "Completed steps",
+									children: steps.map((step) => {
+										const doneId = `${baseId}-${step.id}-done`;
+										return /* @__PURE__ */ jsx("li", {
+											"data-completed-step": step.id,
+											"data-done": "",
+											children: /* @__PURE__ */ jsx(Collapse, {
+												show: state.settled.includes(step.id),
+												children: /* @__PURE__ */ jsxs("div", {
+													className: "checklist-step-inner",
+													children: [/* @__PURE__ */ jsx(CheckButton, {
+														checked: true,
+														labelledBy: doneId,
+														onToggle: () => uncheck(step.id, true)
+													}), /* @__PURE__ */ jsx("span", {
+														className: "checklist-done-title",
+														children: /* @__PURE__ */ jsx("span", {
+															id: doneId,
+															className: "checklist-title-text",
+															children: step.title
+														})
+													})]
+												})
+											})
+										}, step.id);
+									})
+								})
+							})
+						})]
+					})]
+				}) })
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "sr-only",
+				role: "status",
+				children: state.message
+			})
+		]
+	});
+});
+//#endregion
+export { OnboardingChecklist };
+
+//# sourceMappingURL=onboarding-checklist.js.map