@eocrm/design-system 0.6.24 → 0.8.0

package/dist/components/Tour/Tour.js

@@ -0,0 +1,400 @@
+'use client';
+import { Button } from "../Button/Button.js";
+import { Cluster } from "../Cluster/Cluster.js";
+import { CircularProgress } from "../CircularProgress/CircularProgress.js";
+import { Stack } from "../Stack/Stack.js";
+import { useTranslation } from "../../i18n/useTranslation.js";
+import { TOUR_CURRENT_TARGET } from "../_internal/overlay/tourHold.js";
+import { overlayStack, useFloatingSurface } from "../_internal/overlay/useOverlayStack.js";
+import { useFocusTrap } from "../_internal/overlay/useFocusTrap.js";
+import { mergeRefs, sanitizeId } from "../_internal/refs.js";
+import { useControllableState } from "../_internal/useControllableState.js";
+import { Spotlight } from "./Spotlight.js";
+import { useTourTarget } from "./useTourTarget.js";
+import Tour_module_default from "./Tour.module.js";
+import { forwardRef, useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import clsx from "clsx";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
+import { arrow, autoUpdate, flip, offset, shift, useFloating } from "@floating-ui/react-dom";
+// src/components/Tour/Tour.tsx
+/**
+* Activates a click-to-continue target. DropdownMenu's trigger toggles on
+* pointerdown, so a bare click() wouldn't activate it; replay the full
+* primary-pointer sequence a real click produces.
+*/
+function activate(el) {
+	const init = {
+		bubbles: true,
+		cancelable: true,
+		button: 0
+	};
+	const Ptr = typeof window.PointerEvent === "function" ? window.PointerEvent : MouseEvent;
+	const ptr = {
+		...init,
+		isPrimary: true,
+		pointerType: "mouse"
+	};
+	el.dispatchEvent(new Ptr("pointerdown", ptr));
+	el.dispatchEvent(new MouseEvent("mousedown", init));
+	el.dispatchEvent(new Ptr("pointerup", ptr));
+	el.dispatchEvent(new MouseEvent("mouseup", init));
+	el.dispatchEvent(new MouseEvent("click", init));
+}
+/** Gap in px between target and card (room for the arrow). */
+var CARD_OFFSET = 12;
+/** Viewport edge padding for shift(); mirrored by `--tour-card-viewport-gap` in Tour.tokens.scss. */
+var CARD_VIEWPORT_PADDING = 8;
+/** Arrow keys inside these keep their native meaning (caret, option list). */
+var EDITABLE = "input, textarea, select, [contenteditable]:not([contenteditable=\"false\"])";
+/**
+* Guided tour that spotlights each step's `data-tour` target and anchors a card with Skip / Back / Next to it.
+* @see docs/components/Tour.md
+*/
+var Tour = forwardRef(function Tour(props, ref) {
+	const { open } = props;
+	const [present, setPresent] = useState(open);
+	const [session, setSession] = useState(0);
+	const [prevOpen, setPrevOpen] = useState(open);
+	if (open !== prevOpen) {
+		setPrevOpen(open);
+		if (open) {
+			setPresent(true);
+			setSession((s) => s + 1);
+		}
+	}
+	const onExited = useCallback(() => setPresent(false), []);
+	if (!present) return null;
+	return /* @__PURE__ */ jsx(TourSession, {
+		...props,
+		ref,
+		closing: !open,
+		onExited
+	}, session);
+});
+var TourSession = forwardRef(function TourSession({ steps, open: _open, onOpenChange, onFinish, step: stepProp, onStepChange, defaultStep = 0, modal = true, targetTimeout = 5e3, onTargetMissing, doneLabel, closing, onExited, onKeyDown, className, style, ...rest }, forwardedRef) {
+	const t = useTranslation();
+	const [index, setIndex] = useControllableState({
+		value: stepProp,
+		defaultValue: defaultStep,
+		onChange: onStepChange
+	});
+	const current = steps[index];
+	const total = steps.length;
+	const isLast = index === total - 1;
+	const uid = sanitizeId(useId());
+	const titleId = `tour-title-${uid}`;
+	const bodyId = `tour-body-${uid}`;
+	const hintId = `tour-hint-${uid}`;
+	const cardRef = useRef(null);
+	const arrowRef = useRef(null);
+	const { element, status } = useTourTarget(current?.target, targetTimeout, () => {
+		if (!current) return;
+		if (process.env.NODE_ENV !== "production") console.warn(`[Tour] target "${current.target}" not found after ${targetTimeout}ms; showing step ${index + 1} centered.`);
+		onTargetMissing?.(current, index);
+	});
+	const found = status === "found" ? element : null;
+	const waiting = status === "waiting";
+	const centered = !found;
+	const [waitingText, setWaitingText] = useState("");
+	useEffect(() => {
+		setWaitingText(waiting && !closing ? t("tour.waiting") : "");
+	}, [
+		waiting,
+		closing,
+		t
+	]);
+	const finishedRef = useRef(false);
+	const finish = (reason) => {
+		if (closing || finishedRef.current) return;
+		finishedRef.current = true;
+		onOpenChange(false);
+		onFinish?.(reason);
+	};
+	const goNext = () => isLast ? finish("completed") : setIndex(index + 1);
+	const goBack = () => {
+		if (index > 0) setIndex(index - 1);
+	};
+	const goNextRef = useRef(goNext);
+	goNextRef.current = goNext;
+	const finishRef = useRef(finish);
+	finishRef.current = finish;
+	const restoreRef = useRef(null);
+	useLayoutEffect(() => {
+		restoreRef.current = document.activeElement;
+	}, []);
+	useLayoutEffect(() => {
+		if (closing) return;
+		queueMicrotask(() => cardRef.current?.focus({ preventScroll: true }));
+	}, [index, closing]);
+	useEffect(() => {
+		if (!closing) return;
+		const active = document.activeElement;
+		if (active && active !== document.body && !cardRef.current?.contains(active)) return;
+		const el = restoreRef.current;
+		if (el?.isConnected) el.focus({ preventScroll: true });
+	}, [closing]);
+	useFocusTrap(cardRef, modal && !closing, modal && current?.interactive ? found : null);
+	const floatingId = useFloatingSurface(!closing && !!current);
+	const hasCurrent = !!current;
+	useEffect(() => {
+		if (closing || !hasCurrent) return;
+		const onDocKeyDown = (e) => {
+			if (e.key !== "Escape" || !overlayStack.isTopFloating(floatingId)) return;
+			if (!modal && !cardRef.current?.contains(document.activeElement)) return;
+			e.preventDefault();
+			overlayStack.consumeEscape(e);
+			finishRef.current("skipped");
+		};
+		document.addEventListener("keydown", onDocKeyDown, true);
+		return () => document.removeEventListener("keydown", onDocKeyDown, true);
+	}, [
+		closing,
+		floatingId,
+		hasCurrent,
+		modal
+	]);
+	const side = current?.side ?? "bottom";
+	const align = current?.align ?? "center";
+	const placement = align === "center" ? side : `${side}-${align}`;
+	const { refs, floatingStyles, placement: resolvedPlacement, middlewareData, isPositioned } = useFloating({
+		open: !!found,
+		placement,
+		strategy: "fixed",
+		transform: false,
+		middleware: [
+			offset(CARD_OFFSET),
+			flip(),
+			shift({ padding: CARD_VIEWPORT_PADDING }),
+			arrow({ element: arrowRef })
+		],
+		whileElementsMounted: autoUpdate,
+		elements: { reference: found }
+	});
+	const resolvedSide = resolvedPlacement.split("-")[0];
+	const staticSide = {
+		top: "bottom",
+		bottom: "top",
+		left: "right",
+		right: "left"
+	}[resolvedSide];
+	const [glide, setGlide] = useState(false);
+	useEffect(() => {
+		if (glide || !(centered || isPositioned)) return;
+		const id = requestAnimationFrame(() => setGlide(true));
+		return () => cancelAnimationFrame(id);
+	}, [
+		glide,
+		centered,
+		isPositioned
+	]);
+	useEffect(() => {
+		if (!found) return;
+		const r = found.getBoundingClientRect();
+		if (r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth) return;
+		const reduce = window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches;
+		found.scrollIntoView?.({
+			block: "center",
+			inline: "nearest",
+			behavior: reduce ? "auto" : "smooth"
+		});
+	}, [found]);
+	const advanceOn = current?.advanceOn;
+	const interactive = current?.interactive;
+	const clickToContinue = advanceOn === "click" && (!modal || !!interactive) && !!found;
+	const advance = () => clickToContinue && current?.next !== "skip" && found && !found.matches(":disabled") ? activate(found) : goNext();
+	useEffect(() => {
+		if (advanceOn !== "click") return;
+		if (modal && !interactive) {
+			if (process.env.NODE_ENV !== "production") console.warn("[Tour] advanceOn=\"click\" needs interactive: true in modal mode — ignored.");
+			return;
+		}
+		if (!found) return;
+		const onClick = () => {
+			setTimeout(() => goNextRef.current(), 0);
+		};
+		found.addEventListener("click", onClick);
+		return () => found.removeEventListener("click", onClick);
+	}, [
+		advanceOn,
+		interactive,
+		found,
+		modal
+	]);
+	useEffect(() => {
+		if (!(modal && interactive && found) || closing) return;
+		found.setAttribute("data-tour-active-target", "");
+		return () => found.removeAttribute("data-tour-active-target");
+	}, [
+		modal,
+		interactive,
+		found,
+		closing
+	]);
+	useEffect(() => {
+		if (!(modal && !interactive && found) || closing) return;
+		found.setAttribute("data-tour-inert", "");
+		return () => found.removeAttribute("data-tour-inert");
+	}, [
+		modal,
+		interactive,
+		found,
+		closing
+	]);
+	useEffect(() => {
+		if (!found || closing) return;
+		found.setAttribute(TOUR_CURRENT_TARGET, "");
+		return () => found.removeAttribute(TOUR_CURRENT_TARGET);
+	}, [found, closing]);
+	useEffect(() => {
+		if (!closing) return;
+		const el = cardRef.current;
+		const onEnd = (e) => {
+			if (e.target === el) onExited();
+		};
+		el?.addEventListener("transitionend", onEnd);
+		const timer = setTimeout(onExited, 300);
+		return () => {
+			el?.removeEventListener("transitionend", onEnd);
+			clearTimeout(timer);
+		};
+	}, [closing, onExited]);
+	const onCardKeyDown = (e) => {
+		onKeyDown?.(e);
+		if (e.defaultPrevented) return;
+		if (e.key !== "ArrowRight" && e.key !== "ArrowLeft") return;
+		if (e.target.closest(EDITABLE)) return;
+		e.preventDefault();
+		if (e.key === "ArrowLeft") goBack();
+		else if (!isLast) advance();
+	};
+	useEffect(() => {
+		if (current) return;
+		if (process.env.NODE_ENV !== "production") console.warn(`[Tour] no step at index ${index} (steps: ${total}).`);
+	}, [index, total]);
+	if (!current) return null;
+	const state = closing ? "closed" : "open";
+	const cardStyle = centered ? {
+		position: "fixed",
+		top: "50%",
+		left: "50%",
+		translate: "-50% -50%"
+	} : {
+		...floatingStyles,
+		translate: "0 0"
+	};
+	const arrowXY = middlewareData.arrow;
+	return createPortal(/* @__PURE__ */ jsxs("div", {
+		"data-tour-portal-root": "",
+		children: [modal && /* @__PURE__ */ jsx(Spotlight, {
+			target: found,
+			padding: current.spotlightPadding ?? 8,
+			interactive: !!current.interactive && !!found,
+			state,
+			glide
+		}), /* @__PURE__ */ jsxs("div", {
+			...rest,
+			ref: mergeRefs(cardRef, refs.setFloating, forwardedRef),
+			role: "dialog",
+			"aria-modal": modal,
+			"aria-labelledby": titleId,
+			"aria-describedby": [current.body != null && bodyId, clickToContinue && hintId].filter(Boolean).join(" ") || void 0,
+			tabIndex: -1,
+			"data-state": state,
+			"data-side": centered ? void 0 : resolvedSide,
+			"data-centered": centered ? "" : void 0,
+			"data-waiting": waiting ? "" : void 0,
+			"data-glide": glide ? "" : void 0,
+			className: clsx(Tour_module_default.card, className),
+			style: {
+				...style,
+				...cardStyle
+			},
+			onKeyDown: onCardKeyDown,
+			children: [
+				!centered && /* @__PURE__ */ jsx("span", {
+					ref: arrowRef,
+					"aria-hidden": "true",
+					className: Tour_module_default.arrow,
+					style: {
+						left: typeof arrowXY?.x === "number" ? `${arrowXY.x}px` : void 0,
+						top: typeof arrowXY?.y === "number" ? `${arrowXY.y}px` : void 0,
+						[staticSide]: "calc(var(--tour-arrow-size) / -2)"
+					}
+				}),
+				/* @__PURE__ */ jsxs(Stack, {
+					gap: "md",
+					children: [
+						/* @__PURE__ */ jsxs(Stack, {
+							gap: "xs",
+							className: Tour_module_default.content,
+							children: [
+								/* @__PURE__ */ jsx("span", {
+									className: Tour_module_default.progress,
+									children: t("tour.progress", {
+										current: index + 1,
+										total
+									})
+								}),
+								/* @__PURE__ */ jsx("h2", {
+									id: titleId,
+									className: Tour_module_default.title,
+									children: current.title
+								}),
+								current.body != null && /* @__PURE__ */ jsx("div", {
+									id: bodyId,
+									className: Tour_module_default.body,
+									children: current.body
+								})
+							]
+						}, index),
+						clickToContinue && /* @__PURE__ */ jsx("span", {
+							id: hintId,
+							className: Tour_module_default.hint,
+							children: t("tour.clickHint")
+						}),
+						waiting && /* @__PURE__ */ jsxs(Cluster, {
+							gap: "sm",
+							align: "center",
+							"aria-hidden": "true",
+							children: [/* @__PURE__ */ jsx(CircularProgress, { size: "sm" }), /* @__PURE__ */ jsx("span", {
+								className: Tour_module_default.waiting,
+								children: t("tour.waiting")
+							})]
+						}),
+						/* @__PURE__ */ jsxs(Cluster, {
+							justify: isLast ? "end" : "between",
+							gap: "sm",
+							children: [!isLast && /* @__PURE__ */ jsx(Button, {
+								variant: "ghost",
+								size: "sm",
+								onClick: () => finish("skipped"),
+								children: t("tour.skip")
+							}), /* @__PURE__ */ jsxs(Cluster, {
+								gap: "sm",
+								children: [index > 0 && /* @__PURE__ */ jsx(Button, {
+									variant: "secondary",
+									size: "sm",
+									onClick: goBack,
+									children: t("tour.back")
+								}), /* @__PURE__ */ jsx(Button, {
+									variant: clickToContinue ? "secondary" : void 0,
+									size: "sm",
+									onClick: advance,
+									children: isLast ? doneLabel || t("tour.done") : t("tour.next")
+								})]
+							})]
+						})
+					]
+				}),
+				/* @__PURE__ */ jsx("span", {
+					role: "status",
+					"aria-live": "polite",
+					className: Tour_module_default.srOnly,
+					children: waitingText
+				})
+			]
+		})]
+	}), document.body);
+});
+export { Tour };

package/dist/components/Tour/Tour.module.js

@@ -0,0 +1,28 @@
+import "./Tour.css";
+// src/components/Tour/Tour.module.scss
+var spotlight = "Tour__spotlight__Tcezd";
+var blocker = "Tour__blocker__3esuX";
+var card = "Tour__card__wExUW";
+var content = "Tour__content__FOy83";
+var progress = "Tour__progress__4fQaG";
+var hint = "Tour__hint__Pv9hF";
+var waiting = "Tour__waiting__b8y91";
+var title = "Tour__title__qdy_J";
+var body = "Tour__body__lca9v";
+var arrow = "Tour__arrow__xH3mm";
+var srOnly = "Tour__srOnly__gGEdj";
+var Tour_module_default = {
+	spotlight,
+	"attention-wave": "Tour__attention-wave__BMUZu",
+	blocker,
+	card,
+	content,
+	progress,
+	hint,
+	waiting,
+	title,
+	body,
+	arrow,
+	srOnly
+};
+export { arrow, blocker, body, card, content, Tour_module_default as default, hint, progress, spotlight, srOnly, title, waiting };

package/dist/components/Tour/index.d.ts

@@ -0,0 +1,2 @@
+export { Tour } from './Tour.js';
+export type { TourProps, TourStep, TourSide, TourAlign, TourFinishReason } from './Tour.js';

package/dist/components/Tour/useTourTarget.d.ts

@@ -0,0 +1,18 @@
+/** Where a step's target stands. `missing` = timed out; the card falls back to centered. */
+export type TourTargetStatus = 'none' | 'waiting' | 'found' | 'missing';
+export interface TourTargetState {
+    element: HTMLElement | null;
+    status: TourTargetStatus;
+}
+/**
+ * First RENDERED element whose `data-tour` equals `id` (exact match — no CSS
+ * escaping needed). `display:none` / `hidden` matches count as absent.
+ */
+export declare function findTourTarget(id: string): HTMLElement | null;
+/**
+ * Resolves a step's `data-tour` target and keeps it resolved: waits (via a
+ * MutationObserver on `body`) for a target that hasn't mounted or is hidden,
+ * falls back to `missing` after `timeout` ms (`Infinity` = wait forever), and
+ * re-attaches if the node is replaced mid-step (the timeout restarts).
+ */
+export declare function useTourTarget(target: string | undefined, timeout: number, onMissing: () => void): TourTargetState;

package/dist/components/Tour/useTourTarget.js

@@ -0,0 +1,101 @@
+'use client';
+import { useLayoutEffect, useRef, useState } from "react";
+// src/components/Tour/useTourTarget.ts
+var NONE = {
+	element: null,
+	status: "none"
+};
+var WAITING = {
+	element: null,
+	status: "waiting"
+};
+var MISSING = {
+	element: null,
+	status: "missing"
+};
+var warnedDuplicates = /* @__PURE__ */ new Set();
+function isRendered(el) {
+	return el.isConnected && el.getClientRects().length > 0;
+}
+/**
+* First RENDERED element whose `data-tour` equals `id` (exact match — no CSS
+* escaping needed). `display:none` / `hidden` matches count as absent.
+*/
+function findTourTarget(id) {
+	const matches = Array.from(document.querySelectorAll("[data-tour]")).filter((el) => el.dataset.tour === id && isRendered(el));
+	if (matches.length > 1 && process.env.NODE_ENV !== "production" && !warnedDuplicates.has(id)) {
+		warnedDuplicates.add(id);
+		console.warn(`[Tour] ${matches.length} elements match data-tour="${id}"; using the first.`);
+	}
+	return matches[0] ?? null;
+}
+/**
+* Resolves a step's `data-tour` target and keeps it resolved: waits (via a
+* MutationObserver on `body`) for a target that hasn't mounted or is hidden,
+* falls back to `missing` after `timeout` ms (`Infinity` = wait forever), and
+* re-attaches if the node is replaced mid-step (the timeout restarts).
+*/
+function useTourTarget(target, timeout, onMissing) {
+	const [state, setState] = useState(NONE);
+	const onMissingRef = useRef(onMissing);
+	onMissingRef.current = onMissing;
+	useLayoutEffect(() => {
+		if (!target) {
+			setState(NONE);
+			return;
+		}
+		let current;
+		let timer;
+		let timedOut = false;
+		const check = () => {
+			const el = findTourTarget(target);
+			if (el === current) return;
+			current = el;
+			if (el) {
+				clearTimeout(timer);
+				timer = void 0;
+				timedOut = false;
+				setState({
+					element: el,
+					status: "found"
+				});
+				return;
+			}
+			if (timedOut) {
+				setState(MISSING);
+				return;
+			}
+			setState(WAITING);
+			if (Number.isFinite(timeout)) timer = setTimeout(() => {
+				timedOut = true;
+				setState(MISSING);
+				onMissingRef.current();
+			}, timeout);
+		};
+		check();
+		const observer = new MutationObserver((records) => {
+			if (records.every((r) => {
+				const node = r.target;
+				return (node.nodeType === Node.TEXT_NODE ? node.parentElement : node)?.closest?.("[data-tour-portal-root]");
+			})) return;
+			check();
+		});
+		observer.observe(document.body, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: [
+				"data-tour",
+				"class",
+				"style",
+				"hidden"
+			]
+		});
+		return () => {
+			observer.disconnect();
+			clearTimeout(timer);
+		};
+	}, [target, timeout]);
+	return state;
+}
+export { findTourTarget, useTourTarget };