@spinjs/components 0.0.0-stage → 0.1.0-preview.1

package/dist/tour/tour.presentation.js

@@ -0,0 +1,272 @@
+import { tour as tour$1 } from "./tour.machine.js";
+import { ariaHidden, defineComponent } from "@spinjs/runtime";
+// src/tour/tour.presentation.ts
+const runningState = (state) => state === "resolving" || state === "scrolling" || state === "active";
+/** The lookup's budget: two seconds, then the target counts as missing. */
+const RESOLVE_BUDGET_MS = 2e3;
+/** The settle wait after a scroll, before the spotlight activates. */
+const SCROLL_SETTLE_MS = 150;
+/** The target's box, padded: the spotlight's own geometry. */
+const measure = (el, padding) => {
+	const rect = el.getBoundingClientRect();
+	return {
+		x: rect.left - padding,
+		y: rect.top - padding,
+		w: rect.width + padding * 2,
+		h: rect.height + padding * 2
+	};
+};
+const resolveAndScroll = (send, target, spotlightPadding) => {
+	const deadline = Date.now() + RESOLVE_BUDGET_MS;
+	if (target === "") {
+		const w = typeof window === "undefined" ? 0 : window.innerWidth;
+		const h = typeof window === "undefined" ? 0 : window.innerHeight;
+		const cardW = Math.min(320, w * .9);
+		const cardH = 160;
+		send({
+			type: "SPOTLIGHT.SET",
+			x: (w - cardW) / 2,
+			y: (h - cardH) / 2,
+			w: cardW,
+			h: cardH
+		});
+		send({ type: "TARGET.RESOLVED" });
+		send({ type: "SCROLL.END" });
+		return;
+	}
+	const attempt = () => {
+		const el = typeof document === "undefined" ? null : document.querySelector(target);
+		if (el instanceof HTMLElement) {
+			const geo = measure(el, spotlightPadding);
+			send({
+				type: "SPOTLIGHT.SET",
+				x: geo.x,
+				y: geo.y,
+				w: geo.w,
+				h: geo.h
+			});
+			send({ type: "TARGET.RESOLVED" });
+			el.scrollIntoView({
+				behavior: "smooth",
+				block: "center"
+			});
+			setTimeout(() => {
+				const settled = measure(el, spotlightPadding);
+				send({
+					type: "SPOTLIGHT.SET",
+					x: settled.x,
+					y: settled.y,
+					w: settled.w,
+					h: settled.h
+				});
+				send({ type: "SCROLL.END" });
+			}, SCROLL_SETTLE_MS);
+			return;
+		}
+		if (Date.now() >= deadline) {
+			send({ type: "TARGET.NOT_FOUND" });
+			return;
+		}
+		setTimeout(attempt, 50);
+	};
+	attempt();
+};
+const def = {
+	name: "tour",
+	machine: (args, authored) => tour$1(args, authored),
+	start: "inactive",
+	settled: ({ event, after, props, send }) => {
+		if (event.type !== "START" && event.type !== "STEP.NEXT" && event.type !== "STEP.PREV" && event.type !== "STEP.SET") return;
+		if (after.state !== "resolving") return;
+		const context = after.context;
+		const step = context.steps[context.step] ?? null;
+		if (step === null) return;
+		const padding = context.spotlightPadding;
+		resolveAndScroll(send, step.target, padding);
+	},
+	parts: {
+		root: { attrs: (scope) => ({ "data-state": runningState(scope.state) ? "running" : "closed" }) },
+		backdrop: { attrs: (scope) => ({
+			...ariaHidden(true),
+			"data-state": runningState(scope.state) ? "open" : "closed"
+		}) },
+		spotlight: { attrs: (scope) => {
+			const geo = scope.context.spotlight;
+			const ctx = scope.context;
+			const step = ctx.steps[ctx.step] ?? null;
+			const dialog = step !== null && step.target === "";
+			const open = runningState(scope.state) && !dialog;
+			return {
+				...ariaHidden(true),
+				"data-state": open ? "open" : "closed",
+				hidden: !open,
+				style: {
+					left: `${geo.x}px`,
+					top: `${geo.y}px`,
+					width: `${geo.w}px`,
+					height: `${geo.h}px`
+				}
+			};
+		} },
+		positioner: { attrs: (scope) => {
+			const geo = scope.context.spotlight;
+			return {
+				"data-state": scope.state === "active" ? "active" : runningState(scope.state) ? "running" : "closed",
+				style: {
+					left: `${geo.x}px`,
+					top: `calc(${geo.y}px + ${geo.h}px + 0.5rem)`
+				},
+				"use:dismissable": {
+					onOutside: () => scope.send({ type: "DISMISS" }),
+					onEscape: () => scope.send({ type: "DISMISS" })
+				}
+			};
+		} },
+		content: { attrs: (scope) => {
+			const ctx = scope.context;
+			const step = ctx.steps[ctx.step] ?? null;
+			return {
+				role: "dialog",
+				"aria-label": step === null ? ctx.label : step.title,
+				"data-state": scope.state === "active" ? "open" : "closed",
+				hidden: !runningState(scope.state)
+			};
+		} },
+		title: { attrs: (_scope) => ({}) },
+		description: { attrs: (_scope) => ({}) },
+		progressText: {
+			id: "progress",
+			attrs: (scope) => {
+				const ctx = scope.context;
+				return { text: `${ctx.step + 1} of ${ctx.steps.length}` };
+			}
+		},
+		startTrigger: {
+			id: "start",
+			attrs: (scope) => ({
+				"aria-label": "Start tour",
+				onClick: () => scope.send({ type: "START" })
+			})
+		},
+		prevTrigger: {
+			id: "prev",
+			attrs: (scope) => ({
+				"aria-label": "Previous step",
+				hidden: scope.context.step <= 0,
+				onClick: () => scope.send({ type: "STEP.PREV" })
+			})
+		},
+		nextTrigger: {
+			id: "next",
+			attrs: (scope) => ({
+				"aria-label": "Next step",
+				onClick: () => scope.send({ type: "STEP.NEXT" })
+			})
+		},
+		dismissTrigger: {
+			id: "dismiss",
+			attrs: (scope) => ({
+				"aria-label": "End tour",
+				onClick: () => scope.send({ type: "DISMISS" })
+			})
+		},
+		skipTrigger: {
+			id: "skip",
+			attrs: (scope) => ({
+				"aria-label": "Skip tour",
+				onClick: () => scope.send({ type: "SKIP" })
+			})
+		}
+	},
+	commands: {
+		start: { event: () => ({ type: "START" }) },
+		next: { event: () => ({ type: "STEP.NEXT" }) },
+		prev: { event: () => ({ type: "STEP.PREV" }) },
+		dismiss: { event: () => ({ type: "DISMISS" }) },
+		skip: { event: () => ({ type: "SKIP" }) },
+		setStep: { event: ([step]) => ({
+			type: "STEP.SET",
+			step
+		}) },
+		notifyTargetResolved: { event: () => ({ type: "TARGET.RESOLVED" }) },
+		notifyTargetNotFound: { event: () => ({ type: "TARGET.NOT_FOUND" }) },
+		notifyScrollEnd: { event: () => ({ type: "SCROLL.END" }) }
+	},
+	readers: {
+		step: { read: (context) => context.step },
+		steps: { read: (context) => context.steps },
+		running: { read: (_context, state) => runningState(state) },
+		active: { read: (_context, state) => state === "active" },
+		state: { read: (_context, state) => state }
+	},
+	methods: { getTextRows: { call: (context) => {
+		const ctx = context;
+		const step = ctx.steps[ctx.step] ?? null;
+		const holders = {
+			title: step === null ? ctx.label : step.title,
+			description: step === null ? "" : step.description,
+			progress: `${ctx.step + 1} of ${ctx.steps.length}`
+		};
+		return [{
+			key: "step",
+			get title() {
+				return holders.title;
+			},
+			get description() {
+				return holders.description;
+			},
+			get progress() {
+				return holders.progress;
+			}
+		}];
+	} } },
+	events: {
+		start: {
+			prop: "onStart",
+			watch: () => [],
+			detail: () => ({ step: -1 }),
+			select: (event, _before, after, states) => {
+				if (states === void 0 || runningState(states.was) || !runningState(states.is)) return null;
+				return { step: after.step };
+			}
+		},
+		"step-change": {
+			prop: "onStepChange",
+			watch: () => [],
+			detail: () => ({ step: -1 }),
+			select: (event, before, after) => {
+				if (after.step === before.step || after.step < 0) return null;
+				return {
+					step: after.step,
+					stepId: after.steps[after.step]?.id ?? ""
+				};
+			}
+		},
+		dismiss: {
+			prop: "onDismiss",
+			watch: () => [],
+			detail: () => ({ reason: "dismiss" }),
+			select: (event, before, after, states) => {
+				if (states === void 0 || !runningState(states.was) || runningState(states.is)) return null;
+				return {
+					reason: event.type === "SKIP" ? "skip" : event.type === "TARGET.NOT_FOUND" ? "not-found" : states.was === "active" && before.step === after.steps.length - 1 && event.type === "DISMISS" ? "complete" : "dismiss",
+					step: before.step
+				};
+			}
+		},
+		complete: {
+			prop: "onComplete",
+			watch: () => [],
+			detail: () => ({}),
+			select: (event, before, after, states) => {
+				if (event.type !== "DISMISS" || states?.was !== "active") return null;
+				if (before.step !== after.steps.length - 1) return null;
+				return {};
+			}
+		}
+	}
+};
+const tour = defineComponent(def);
+export { def, tour };
+
+//# sourceMappingURL=tour.presentation.js.map

package/dist/tour/tour.state.d.ts

@@ -0,0 +1,43 @@
+export type TourState = "inactive" | "resolving" | "scrolling" | "active";
+export interface TourStepRecord {
+  readonly id: string;
+  readonly target: string;
+  readonly title: string;
+  readonly description: string;
+}
+/** The spotlight's box, in the viewport's coordinates. */
+export interface TourSpotlight {
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+export interface TourContext {
+  steps: readonly TourStepRecord[];
+  /** -1 when the tour is not running. */
+  step: number;
+  /** Where the last transition came from; the overlay's entry. */
+  previousStep: number;
+  /** The resolved target's box, padded: the spotlight's own geometry. */
+  spotlight: TourSpotlight;
+  disabled: boolean;
+  spotlightPadding: number;
+  label: string;
+}
+/** The tour's arguments: the values the host may set. */
+export interface TourArgs {
+  /** JSON text, one entry per step. */
+  readonly steps?: string;
+  readonly step?: number;
+  readonly disabled?: boolean;
+  readonly spotlightPadding?: number;
+  readonly label?: string;
+}
+/** The step collection off any transport: well-shaped entries only. The
+ * scope grammar coerces `= []` to `["[]"]`, so JSON text parses too. */
+export declare function stepsOf(raw: unknown): TourStepRecord[];
+/** The machine's context from its arguments. */
+export declare function initial(args: TourArgs, authored?: (name: string) => boolean): Pick<TourContext, "steps" | "step" | "previousStep" | "spotlight" | "disabled" | "spotlightPadding" | "label">;
+export declare function stepOf(raw: unknown, count: number): number;
+export declare const bailStep: (ctx: TourContext) => Partial<TourContext>;
+//# sourceMappingURL=tour.state.d.ts.map

package/dist/tour/tour.state.js

@@ -0,0 +1,60 @@
+import { defaultTwin, isRecord } from "@spinjs/runtime";
+// src/tour/tour.state.ts
+const parseJsonList = (raw) => {
+	if (typeof raw !== "string" || raw.length === 0) return [];
+	try {
+		const parsed = JSON.parse(raw);
+		return Array.isArray(parsed) ? parsed : [];
+	} catch {
+		return [];
+	}
+};
+/** The step collection off any transport: well-shaped entries only. The
+* scope grammar coerces `= []` to `["[]"]`, so JSON text parses too. */
+function stepsOf(raw) {
+	const list = Array.isArray(raw) ? raw : parseJsonList(raw);
+	const steps = [];
+	for (const entry of list) {
+		if (!isRecord(entry)) continue;
+		const id = entry["id"];
+		if (typeof id !== "string") continue;
+		const target = entry["target"];
+		const title = entry["title"];
+		const description = entry["description"];
+		steps.push({
+			id,
+			target: typeof target === "string" ? target : "",
+			title: typeof title === "string" ? title : "",
+			description: typeof description === "string" ? description : ""
+		});
+	}
+	return steps;
+}
+/** The machine's context from its arguments. */
+function initial(args, authored = () => true) {
+	const steps = stepsOf(args.steps);
+	return {
+		steps,
+		step: authored("step") || authored(defaultTwin("step")) ? stepOf(args.step, steps.length) : -1,
+		previousStep: -1,
+		spotlight: {
+			x: 0,
+			y: 0,
+			w: 0,
+			h: 0
+		},
+		disabled: args.disabled ?? false,
+		spotlightPadding: args.spotlightPadding ?? 8,
+		label: args.label ?? ""
+	};
+}
+function stepOf(raw, count) {
+	return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 && raw < count ? raw : -1;
+}
+const bailStep = (ctx) => ({
+	previousStep: ctx.step,
+	step: -1
+});
+export { bailStep, initial, stepOf, stepsOf };
+
+//# sourceMappingURL=tour.state.js.map

package/dist/tour/tour.transitions.d.ts

@@ -0,0 +1,16 @@
+import { TourContext } from "./tour.state.js";
+import { TourEvents } from "./tour.events.js";
+import { AssignFor, GuardFor } from "@spinjs/runtime/fsm";
+type TourAssign<K extends keyof TourEvents = keyof TourEvents> = AssignFor<TourContext, TourEvents, K>;
+export declare const setSpotlight: TourAssign<"SPOTLIGHT.SET">;
+export declare const setStep: TourAssign<"STEP.SET">;
+export declare const startTour: TourAssign<"START">;
+export declare const nextStep: TourAssign<"STEP.NEXT">;
+export declare const prevStep: TourAssign<"STEP.PREV">;
+export declare const bail: (ctx: TourContext) => Partial<TourContext>;
+export declare const hasSteps: GuardFor<TourContext, TourEvents>;
+export declare const validStep: GuardFor<TourContext, TourEvents>;
+export declare const hasNext: GuardFor<TourContext, TourEvents>;
+export declare const hasPrev: GuardFor<TourContext, TourEvents>;
+export {};
+//# sourceMappingURL=tour.transitions.d.ts.map

package/dist/tour/tour.transitions.js

@@ -0,0 +1,32 @@
+import { bailStep, stepOf } from "./tour.state.js";
+// src/tour/tour.transitions.ts
+const setSpotlight = (_ctx, event) => ({ spotlight: {
+	x: event.x,
+	y: event.y,
+	w: event.w,
+	h: event.h
+} });
+const setStep = (ctx, event) => ({
+	previousStep: ctx.step,
+	step: stepOf(event.step, ctx.steps.length)
+});
+const startTour = () => ({
+	previousStep: -1,
+	step: 0
+});
+const nextStep = (ctx) => ({
+	previousStep: ctx.step,
+	step: ctx.step + 1
+});
+const prevStep = (ctx) => ({
+	previousStep: ctx.step,
+	step: ctx.step - 1
+});
+const bail = (ctx) => bailStep(ctx);
+const hasSteps = (ctx) => ctx.steps.length > 0;
+const validStep = (ctx, event) => event.type === "STEP.SET" && event.step >= 0 && event.step < ctx.steps.length;
+const hasNext = (ctx) => ctx.step + 1 < ctx.steps.length;
+const hasPrev = (ctx) => ctx.step > 0;
+export { bail, hasNext, hasPrev, hasSteps, nextStep, prevStep, setSpotlight, setStep, startTour, validStep };
+
+//# sourceMappingURL=tour.transitions.js.map

package/dist/tree-view/examples/basic.html

@@ -0,0 +1,47 @@
+<script lang="ts">
+import { treeView } from "../tree-view.presentation.js";
+
+const machine = treeView({
+  nodes:
+    '[{"value": "packages", "label": "packages", "children": [{"value": "packages/components", "label": "components", "children": [{"value": "packages/combobox", "label": "combobox"}, {"value": "packages/select", "label": "select"}]}, {"value": "packages/runtime", "label": "runtime"}]}, {"value": "packages/preset", "label": "preset"}, {"value": "readme", "label": "README.md"}]',
+  expandedValue: ["packages", "packages/components"],
+});
+</script>
+<div class="mx-auto w-full max-w-sm" {...machine.getRootProps()}>
+  <span class="mb-4 block text-md font-semibold text-text"
+    {...machine.getLabelProps()}>Project Files</span>
+  <div
+    class="stack-xs rounded-lg border border-solid border-border bg-surface-raised p-3"
+    {...machine.getTreeProps()}>
+    <template for={machine.getVisibleRows()} as={row} key={row.node.value}>
+      <div class="relative" {...machine.getItemProps(row)}>
+        <span class="pointer-events-none absolute inset-y-0 w-[1px] bg-border"
+          aria-hidden="true" {...machine.getRailProps(row)}></span>
+        <button
+          class={["bare relative flex min-h-0 items-center gap-2 rounded-lg border-0 px-3 py-2 text-left text-sm font-medium transition-colors duration-fast ease-standard hover:bg-surface", { "bg-surface-sunken": machine.getItemState(row).selected, "bg-transparent": !machine.getItemState(row).selected }]}
+          {...machine.getBranchControlProps(row)}
+        >
+          <span
+            class={["h-4 w-4 shrink-0 items-center justify-center text-text-muted transition-transform duration-fast ease-standard", { "inline-flex": machine.isBranch(row), "hidden": !machine.isBranch(row), "rotate-90": machine.getItemState(row).expanded }]}
+            {...machine.getBranchIndicatorProps(row)}>
+            <span class="i-lucide-chevron-right text-xs"
+              aria-hidden="true"></span>
+          </span>
+          <span
+            show={machine.isBranch(row) && !machine.getItemState(row).expanded}
+            class="i-lucide-folder shrink-0 text-sm text-primary"
+            aria-hidden="true" {...machine.getItemIconProps(row)}></span>
+          <span
+            show={machine.isBranch(row) && machine.getItemState(row).expanded}
+            class="i-lucide-folder-open shrink-0 text-sm text-primary"
+            aria-hidden="true" {...machine.getItemIconProps(row)}></span>
+          <span show={!machine.isBranch(row)}
+            class="i-lucide-file shrink-0 text-sm text-text-muted" aria-hidden="true"
+            {...machine.getItemIconProps(row)}></span>
+          <span class="min-w-0 flex-1 truncate"
+            {...machine.getBranchTextProps(row)}>{row.node.label}</span>
+        </button>
+      </div>
+    </template>
+  </div>
+</div>

package/dist/tree-view/examples/loading.html

@@ -0,0 +1,57 @@
+<script lang="ts">
+import { treeView } from "../tree-view.presentation.js";
+
+const machine = treeView({
+  nodes:
+    '[{"value": "packages", "label": "packages"}, {"value": "packages/preset", "label": "preset", "children": []}, {"value": "readme", "label": "README.md", "children": []}]',
+  expandedValue: [],
+  loadChildren: "",
+});
+</script>
+<!-- Lazy roots declare no children: expanding one calls the host's
+  `loadChildren(value)` property (a function returning nodes) and shows
+  the loading marker until LOAD_DONE. In this page the loader below is
+  wired by the viewer; in your own code set the property yourself:
+
+    tree.loadChildren = async (value) => fetchChildren(value);
+-->
+<div class="mx-auto w-full max-w-sm" {...machine.getRootProps()}>
+  <span class="mb-4 block text-md font-semibold text-text"
+    {...machine.getLabelProps()}>Project Files</span>
+  <div
+    class="stack-xs rounded-lg border border-solid border-border bg-surface-raised p-3"
+    {...machine.getTreeProps()}>
+    <template for={machine.getVisibleRows()} as={row} key={row.node.value}>
+      <div class="relative" {...machine.getItemProps(row)}>
+        <span class="pointer-events-none absolute inset-y-0 w-[1px] bg-border"
+          aria-hidden="true" {...machine.getRailProps(row)}></span>
+        <button
+          class={["bare relative flex min-h-0 items-center gap-2 rounded-lg border-0 px-3 py-2 text-left text-sm font-medium transition-colors duration-fast ease-standard hover:bg-surface", { "bg-surface-sunken": machine.getItemState(row).selected, "bg-transparent": !machine.getItemState(row).selected }]}
+          {...machine.getBranchControlProps(row)}
+        >
+          <span
+            class={["h-4 w-4 shrink-0 items-center justify-center text-text-muted transition-transform duration-fast ease-standard", { "inline-flex": machine.isBranch(row), "hidden": !machine.isBranch(row), "rotate-90": machine.getItemState(row).expanded }]}
+            {...machine.getBranchIndicatorProps(row)}>
+            <span class="i-lucide-chevron-right text-xs"
+              aria-hidden="true"></span>
+          </span>
+          <span
+            show={machine.isBranch(row) && !machine.getItemState(row).expanded}
+            class="i-lucide-folder shrink-0 text-sm text-primary"
+            aria-hidden="true" {...machine.getItemIconProps(row)}></span>
+          <span
+            show={machine.isBranch(row) && machine.getItemState(row).expanded}
+            class="i-lucide-folder-open shrink-0 text-sm text-primary"
+            aria-hidden="true" {...machine.getItemIconProps(row)}></span>
+          <span show={!machine.isBranch(row)}
+            class="i-lucide-file shrink-0 text-sm text-text-muted" aria-hidden="true"
+            {...machine.getItemIconProps(row)}></span>
+          <span class="min-w-0 flex-1 truncate"
+            {...machine.getBranchTextProps(row)}>{row.node.label}</span>
+          <span class="ms-auto shrink-0 text-text-muted"
+            {...machine.getLoadingProps(row)}><span class="i-lucide-loader-circle animate-spin text-sm" aria-hidden="true"></span></span>
+        </button>
+      </div>
+    </template>
+  </div>
+</div>

package/dist/tree-view/tree-view.events.d.ts

@@ -0,0 +1,67 @@
+import { TreeNodeShape } from "./tree-view.state.js";
+import { EventUnion } from "@spinjs/runtime/fsm";
+export interface TreeEvents {
+  "EXPANDED.SET": {
+    value?: string[];
+    expandedValue?: string[];
+  };
+  "EXPANDED.CLEAR": {};
+  "BRANCH.EXPAND": {
+    value: string[];
+  };
+  "BRANCH.COLLAPSE": {
+    value: string[];
+  };
+  "BRANCH.TOGGLE": {
+    value: string;
+  };
+  "SELECTED.SET": {
+    value?: string[];
+    selectedValue?: string[];
+  };
+  "SELECTED.CLEAR": {};
+  "NODE.SELECT": {
+    value: string;
+  };
+  "NODE.DESELECT": {
+    value: string;
+  };
+  "CHECKED.TOGGLE": {
+    value: string;
+  };
+  "CHECKED.SET": {
+    value?: string[];
+    checkedValue?: string[];
+  };
+  "CHECKED.CLEAR": {};
+  "NODE.FOCUS": {
+    value: string | null;
+  };
+  "NODE.CLICK": {
+    value: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+  };
+  "BRANCH_NODE.CLICK": {
+    value: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+  };
+  "NODE.RENAME": {
+    value: string;
+  };
+  "RENAME.SUBMIT": {
+    value: string;
+    label: string;
+  };
+  "RENAME.CANCEL": {};
+  "NODE.LOAD_START": {
+    value: string;
+  };
+  "NODE.LOAD_DONE": {
+    value: string;
+    children?: readonly TreeNodeShape[];
+  };
+}
+export type TreeEvent = EventUnion<TreeEvents>;
+//# sourceMappingURL=tree-view.events.d.ts.map

package/dist/tree-view/tree-view.events.js

@@ -0,0 +1 @@
+export {};

package/dist/tree-view/tree-view.machine.d.ts

@@ -0,0 +1,6 @@
+import { TreeArgs, TreeContext, TreeState, nodesOf } from "./tree-view.state.js";
+import { TreeEvents } from "./tree-view.events.js";
+import { Machine } from "@spinjs/runtime/fsm";
+export declare function treeView(args?: TreeArgs, authored?: (name: string) => boolean): Machine<TreeContext, TreeEvents, TreeState>;
+export { nodesOf };
+//# sourceMappingURL=tree-view.machine.d.ts.map