@parhelia/core 0.3.12827 → 0.3.12831

package/dist/revision.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "0.3.12827";
-export declare const buildDate = "2026-09-03 11:58:26";
+export declare const version = "0.3.12831";
+export declare const buildDate = "2026-09-03 14:25:47";

package/dist/revision.js

@@ -1,3 +1,3 @@
-export const version = "0.3.12827";
-export const buildDate = "2026-09-03 11:58:26";
+export const version = "0.3.12831";
+export const buildDate = "2026-09-03 14:25:47";
 //# sourceMappingURL=revision.js.map

package/dist/tour/sandbox-tour-copy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copy for the sandbox tour. Kept free of React/icon imports so the Playwright
+ * spec can import the exact strings without pulling UI dependencies into the
+ * test runner.
+ */
+export declare const SANDBOX_TOUR_COPY: {
+    readonly "start-tour": {
+        readonly label: "Your page";
+        readonly description: "Everything on the page is editable: click any text and start typing.";
+    };
+    readonly "insert-component": {
+        readonly label: "Add components";
+        readonly description: "Use Add component to place new sections, text, images, and other building blocks on your page.";
+    };
+    readonly "undo-redo": {
+        readonly label: "Undo and redo";
+        readonly description: "Made a change you do not want? Step backward or forward through your recent edits here.";
+    };
+    readonly "content-tree": {
+        readonly label: "Content tree";
+        readonly description: "Open the content tree to browse your site and move quickly between pages.";
+    };
+    readonly "preview-mode": {
+        readonly label: "Preview mode";
+        readonly description: "Switch to preview mode to see the page without editing controls.";
+    };
+    readonly "device-switcher": {
+        readonly label: "Device views";
+        readonly description: "Check how your page looks on desktop, tablet, and mobile screens.";
+    };
+    readonly "agent-prompt": {
+        readonly label: "Your AI agent";
+        readonly description: "Describe what you want in plain language and your agent can write, restyle, or build it for you.";
+    };
+    readonly "agents-button": {
+        readonly label: "Your AI agent";
+        readonly description: "Open the agents panel, then describe what you want in plain language.";
+    };
+    readonly help: {
+        readonly label: "Help";
+        readonly description: "Find guidance and useful resources here whenever you need a hand.";
+    };
+    readonly done: {
+        readonly label: "You are ready";
+        readonly description: "That is everything you need to start exploring. Have fun building in your sandbox!";
+    };
+};
+export type SandboxStepId = keyof typeof SANDBOX_TOUR_COPY;

package/dist/tour/sandbox-tour-copy.js

@@ -0,0 +1,48 @@
+/**
+ * Copy for the sandbox tour. Kept free of React/icon imports so the Playwright
+ * spec can import the exact strings without pulling UI dependencies into the
+ * test runner.
+ */
+export const SANDBOX_TOUR_COPY = {
+    "start-tour": {
+        label: "Your page",
+        description: "Everything on the page is editable: click any text and start typing.",
+    },
+    "insert-component": {
+        label: "Add components",
+        description: "Use Add component to place new sections, text, images, and other building blocks on your page.",
+    },
+    "undo-redo": {
+        label: "Undo and redo",
+        description: "Made a change you do not want? Step backward or forward through your recent edits here.",
+    },
+    "content-tree": {
+        label: "Content tree",
+        description: "Open the content tree to browse your site and move quickly between pages.",
+    },
+    "preview-mode": {
+        label: "Preview mode",
+        description: "Switch to preview mode to see the page without editing controls.",
+    },
+    "device-switcher": {
+        label: "Device views",
+        description: "Check how your page looks on desktop, tablet, and mobile screens.",
+    },
+    "agent-prompt": {
+        label: "Your AI agent",
+        description: "Describe what you want in plain language and your agent can write, restyle, or build it for you.",
+    },
+    "agents-button": {
+        label: "Your AI agent",
+        description: "Open the agents panel, then describe what you want in plain language.",
+    },
+    help: {
+        label: "Help",
+        description: "Find guidance and useful resources here whenever you need a hand.",
+    },
+    done: {
+        label: "You are ready",
+        description: "That is everything you need to start exploring. Have fun building in your sandbox!",
+    },
+};
+//# sourceMappingURL=sandbox-tour-copy.js.map

package/dist/tour/sandbox-tour-copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-tour-copy.js","sourceRoot":"","sources":["../../src/tour/sandbox-tour-copy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,YAAY,EAAE;QACZ,KAAK,EAAE,WAAW;QAClB,WAAW,EACT,sEAAsE;KACzE;IACD,kBAAkB,EAAE;QAClB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,gGAAgG;KACnG;IACD,WAAW,EAAE;QACX,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,yFAAyF;KAC5F;IACD,cAAc,EAAE;QACd,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,2EAA2E;KAC9E;IACD,cAAc,EAAE;QACd,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,kEAAkE;KACrE;IACD,iBAAiB,EAAE;QACjB,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,mEAAmE;KACtE;IACD,cAAc,EAAE;QACd,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,kGAAkG;KACrG;IACD,eAAe,EAAE;QACf,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,uEAAuE;KAC1E;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM;QACb,WAAW,EACT,mEAAmE;KACtE;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,oFAAoF;KACvF;CACO,CAAC"}

package/dist/tour/sandbox-tour.d.ts

@@ -0,0 +1,3 @@
+import type { Tour } from "../config/types";
+export { SANDBOX_TOUR_COPY } from "./sandbox-tour-copy";
+export declare function createSandboxTour(): Tour;

package/dist/tour/sandbox-tour.js

@@ -0,0 +1,210 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowLeft, ArrowRight, Check } from "lucide-react";
+import { elementState, isElementVisible } from "./tour-utils";
+import { SANDBOX_TOUR_COPY } from "./sandbox-tour-copy";
+export { SANDBOX_TOUR_COPY } from "./sandbox-tour-copy";
+const SELECTORS = {
+    "start-tour": '[data-testid="pageEditoriframe"]',
+    "insert-component": '[data-testid="insert-component-button"]',
+    "undo-redo": 'div:has(> [data-testid="toolbar-undo-button"])',
+    "content-tree": '[data-testid="content-tree-toggle-button"]',
+    "preview-mode": '[data-testid="preview-mode-button"]',
+    "device-switcher": '[data-testid="viewport-mode-switcher-button"]',
+    "agent-prompt": '[data-testid="agent-terminal-prompt"]',
+    "agents-button": '[data-testid="agents-panel-button"]',
+    help: '[data-testid="help-button"]',
+};
+/**
+ * The editor chrome the tour waits for before it treats an absent optional
+ * control as "not part of this layout". The toolbar and its siblings mount in
+ * the same React commit, so once these two exist the rest has settled. Waiting
+ * on every step selector instead would stall the first bubble for the full
+ * timeout whenever one control is legitimately missing (mobile, closed agents
+ * panel).
+ */
+const REQUIRED_CHROME_SELECTORS = [
+    SELECTORS["start-tour"],
+    '[data-testid="genericToolbar"]',
+];
+const SETTLE_TIMEOUT_MS = 3000;
+export function createSandboxTour() {
+    let settled = false;
+    let settlePromise;
+    let settleGeneration = 0;
+    const resetSettleState = () => {
+        settled = false;
+        settlePromise = undefined;
+        settleGeneration += 1;
+    };
+    return {
+        dismissOnEscape: true,
+        pointer: "caret",
+        getSteps: (params) => {
+            const selectorShouldBeSkipped = (selector) => {
+                const state = elementState(selector);
+                return state === "hidden" || (settled && state === "absent");
+            };
+            const definitions = [
+                {
+                    id: "start-tour",
+                    focusElement: SELECTORS["start-tour"],
+                    bubblePosition: "right",
+                    bubbleVerticalAnchor: "center",
+                },
+                {
+                    id: "insert-component",
+                    focusElement: SELECTORS["insert-component"],
+                    bubblePosition: "bottom",
+                    skipIf: () => selectorShouldBeSkipped(SELECTORS["insert-component"]),
+                },
+                {
+                    id: "undo-redo",
+                    focusElement: SELECTORS["undo-redo"],
+                    bubblePosition: "bottom",
+                    skipIf: () => selectorShouldBeSkipped(SELECTORS["undo-redo"]),
+                },
+                {
+                    id: "content-tree",
+                    focusElement: SELECTORS["content-tree"],
+                    bubblePosition: "bottom",
+                    skipIf: () => selectorShouldBeSkipped(SELECTORS["content-tree"]),
+                },
+                {
+                    id: "preview-mode",
+                    focusElement: SELECTORS["preview-mode"],
+                    bubblePosition: "bottom",
+                    skipIf: () => selectorShouldBeSkipped(SELECTORS["preview-mode"]),
+                },
+                {
+                    id: "device-switcher",
+                    focusElement: SELECTORS["device-switcher"],
+                    bubblePosition: "bottom",
+                    skipIf: () => selectorShouldBeSkipped(SELECTORS["device-switcher"]),
+                },
+                {
+                    id: "agent-prompt",
+                    focusElement: SELECTORS["agent-prompt"],
+                    bubblePosition: "left",
+                    skipIf: () => selectorShouldBeSkipped(SELECTORS["agent-prompt"]),
+                },
+                {
+                    id: "agents-button",
+                    focusElement: SELECTORS["agents-button"],
+                    bubblePosition: "bottom",
+                    skipIf: () => isElementVisible(SELECTORS["agent-prompt"]) ||
+                        selectorShouldBeSkipped(SELECTORS["agents-button"]),
+                },
+                {
+                    id: "help",
+                    focusElement: SELECTORS.help,
+                    bubblePosition: "bottom",
+                    skipIf: () => selectorShouldBeSkipped(SELECTORS.help),
+                },
+                { id: "done" },
+            ];
+            const startSettlePass = () => {
+                if (!settlePromise) {
+                    const generation = settleGeneration;
+                    // Defer one microtask: Tour's wait helper reads the current step, which
+                    // is initialized immediately after getSteps returns.
+                    settlePromise = Promise.resolve()
+                        .then(() => Promise.all(REQUIRED_CHROME_SELECTORS.map((selector) => params.waitForElement(selector, SETTLE_TIMEOUT_MS))))
+                        .then(() => {
+                        if (generation === settleGeneration)
+                            settled = true;
+                    }, () => {
+                        if (generation === settleGeneration)
+                            settled = true;
+                    });
+                }
+                return settlePromise;
+            };
+            void startSettlePass();
+            const stopTour = () => {
+                resetSettleState();
+                params.stopTour();
+            };
+            const isSkipped = (definition) => definition.skipIf?.(params.editContext.configuration) ?? false;
+            // Numbering only counts steps whose target is on screen right now (plus
+            // the element-less closing step). Before the chrome has settled, absent
+            // targets are deliberately not skipped, but counting them would make
+            // "n of N" shrink once they are confirmed missing.
+            const isCounted = (definition) => !isSkipped(definition) &&
+                (!definition.focusElement ||
+                    elementState(definition.focusElement) === "visible");
+            const visibleDefinitions = definitions.filter(isCounted);
+            const findPreviousVisible = (index) => {
+                for (let previous = index - 1; previous >= 0; previous -= 1) {
+                    const candidate = definitions[previous];
+                    if (candidate && !isSkipped(candidate))
+                        return candidate.id;
+                }
+                return undefined;
+            };
+            const steps = {};
+            definitions.forEach((definition, index) => {
+                const copy = SANDBOX_TOUR_COPY[definition.id];
+                const visibleIndex = visibleDefinitions.findIndex((candidate) => candidate.id === definition.id);
+                const nextId = definitions[index + 1]?.id ?? "done";
+                const previousId = findPreviousVisible(index);
+                const isDone = definition.id === "done";
+                steps[definition.id] = {
+                    title: copy.label,
+                    progress: {
+                        index: visibleIndex + 1,
+                        total: visibleDefinitions.length,
+                    },
+                    description: copy.description,
+                    focusElement: definition.focusElement,
+                    bubblePosition: definition.bubblePosition,
+                    bubbleVerticalAnchor: definition.bubbleVerticalAnchor,
+                    skipIf: definition.skipIf,
+                    nextStep: nextId,
+                    ...(definition.id === "start-tour"
+                        ? {
+                            prepareAction: async () => {
+                                // Every fresh run passes through here (only a URL-restored
+                                // run skips it), so this also clears state left behind when
+                                // the engine's own close button or Escape ended the last run
+                                // without going through the wrapped stopTour.
+                                resetSettleState();
+                                await startSettlePass();
+                            },
+                        }
+                        : {}),
+                    buttons: [
+                        ...(previousId
+                            ? [
+                                {
+                                    label: (_jsxs(_Fragment, { children: [_jsx(ArrowLeft, { strokeWidth: 1, className: "inline h-4 w-4" }), "Back"] })),
+                                    onClick: () => params.nextStep(previousId),
+                                    className: "button button-secondary mt-2",
+                                    variant: "secondary",
+                                },
+                            ]
+                            : []),
+                        {
+                            label: isDone ? (_jsxs(_Fragment, { children: [_jsx(Check, { strokeWidth: 1, className: "inline h-4 w-4" }), " Finish"] })) : (_jsxs(_Fragment, { children: [_jsx(ArrowRight, { strokeWidth: 1, className: "inline h-4 w-4" }), " Next"] })),
+                            onClick: () => (isDone ? stopTour() : params.nextStep(nextId)),
+                            className: "button button-primary mt-2",
+                            variant: "primary",
+                        },
+                    ],
+                };
+            });
+            steps.error = {
+                title: "Oh no...",
+                description: "Something went wrong.",
+                nextStep: "done",
+                buttons: [
+                    {
+                        label: (_jsxs(_Fragment, { children: [_jsx(Check, { strokeWidth: 1, className: "inline h-4 w-4" }), " Close"] })),
+                        onClick: stopTour,
+                    },
+                ],
+            };
+            return steps;
+        },
+    };
+}
+//# sourceMappingURL=sandbox-tour.js.map

package/dist/tour/sandbox-tour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-tour.js","sourceRoot":"","sources":["../../src/tour/sandbox-tour.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAsB,MAAM,qBAAqB,CAAC;AAE5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,SAAS,GAAG;IAChB,YAAY,EAAE,kCAAkC;IAChD,kBAAkB,EAAE,yCAAyC;IAC7D,WAAW,EAAE,gDAAgD;IAC7D,cAAc,EAAE,4CAA4C;IAC5D,cAAc,EAAE,qCAAqC;IACrD,iBAAiB,EAAE,+CAA+C;IAClE,cAAc,EAAE,uCAAuC;IACvD,eAAe,EAAE,qCAAqC;IACtD,IAAI,EAAE,6BAA6B;CAC3B,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,yBAAyB,GAAG;IAChC,SAAS,CAAC,YAAY,CAAC;IACvB,gCAAgC;CACxB,CAAC;AACX,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAU/B,MAAM,UAAU,iBAAiB;IAC/B,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,aAAwC,CAAC;IAC7C,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,MAAM,gBAAgB,GAAG,GAAG,EAAE;QAC5B,OAAO,GAAG,KAAK,CAAC;QAChB,aAAa,GAAG,SAAS,CAAC;QAC1B,gBAAgB,IAAI,CAAC,CAAC;IACxB,CAAC,CAAC;IAEF,OAAO;QACL,eAAe,EAAE,IAAI;QACrB,OAAO,EAAE,OAAO;QAChB,QAAQ,EAAE,CAAC,MAAgC,EAAE,EAAE;YAC7C,MAAM,uBAAuB,GAAG,CAAC,QAAgB,EAAE,EAAE;gBACnD,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACrC,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,OAAO,IAAI,KAAK,KAAK,QAAQ,CAAC,CAAC;YAC/D,CAAC,CAAC;YAEF,MAAM,WAAW,GAAqB;gBACpC;oBACE,EAAE,EAAE,YAAY;oBAChB,YAAY,EAAE,SAAS,CAAC,YAAY,CAAC;oBACrC,cAAc,EAAE,OAAO;oBACvB,oBAAoB,EAAE,QAAQ;iBAC/B;gBACD;oBACE,EAAE,EAAE,kBAAkB;oBACtB,YAAY,EAAE,SAAS,CAAC,kBAAkB,CAAC;oBAC3C,cAAc,EAAE,QAAQ;oBACxB,MAAM,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;iBACrE;gBACD;oBACE,EAAE,EAAE,WAAW;oBACf,YAAY,EAAE,SAAS,CAAC,WAAW,CAAC;oBACpC,cAAc,EAAE,QAAQ;oBACxB,MAAM,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;iBAC9D;gBACD;oBACE,EAAE,EAAE,cAAc;oBAClB,YAAY,EAAE,SAAS,CAAC,cAAc,CAAC;oBACvC,cAAc,EAAE,QAAQ;oBACxB,MAAM,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;iBACjE;gBACD;oBACE,EAAE,EAAE,cAAc;oBAClB,YAAY,EAAE,SAAS,CAAC,cAAc,CAAC;oBACvC,cAAc,EAAE,QAAQ;oBACxB,MAAM,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;iBACjE;gBACD;oBACE,EAAE,EAAE,iBAAiB;oBACrB,YAAY,EAAE,SAAS,CAAC,iBAAiB,CAAC;oBAC1C,cAAc,EAAE,QAAQ;oBACxB,MAAM,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;iBACpE;gBACD;oBACE,EAAE,EAAE,cAAc;oBAClB,YAAY,EAAE,SAAS,CAAC,cAAc,CAAC;oBACvC,cAAc,EAAE,MAAM;oBACtB,MAAM,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;iBACjE;gBACD;oBACE,EAAE,EAAE,eAAe;oBACnB,YAAY,EAAE,SAAS,CAAC,eAAe,CAAC;oBACxC,cAAc,EAAE,QAAQ;oBACxB,MAAM,EAAE,GAAG,EAAE,CACX,gBAAgB,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;wBAC3C,uBAAuB,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;iBACtD;gBACD;oBACE,EAAE,EAAE,MAAM;oBACV,YAAY,EAAE,SAAS,CAAC,IAAI;oBAC5B,cAAc,EAAE,QAAQ;oBACxB,MAAM,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,SAAS,CAAC,IAAI,CAAC;iBACtD;gBACD,EAAE,EAAE,EAAE,MAAM,EAAE;aACf,CAAC;YAEF,MAAM,eAAe,GAAG,GAAG,EAAE;gBAC3B,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnB,MAAM,UAAU,GAAG,gBAAgB,CAAC;oBACpC,wEAAwE;oBACxE,qDAAqD;oBACrD,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE;yBAC9B,IAAI,CAAC,GAAG,EAAE,CACT,OAAO,CAAC,GAAG,CACT,yBAAyB,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CACzC,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CACnD,CACF,CACF;yBACA,IAAI,CACH,GAAG,EAAE;wBACH,IAAI,UAAU,KAAK,gBAAgB;4BAAE,OAAO,GAAG,IAAI,CAAC;oBACtD,CAAC,EACD,GAAG,EAAE;wBACH,IAAI,UAAU,KAAK,gBAAgB;4BAAE,OAAO,GAAG,IAAI,CAAC;oBACtD,CAAC,CACF,CAAC;gBACN,CAAC;gBACD,OAAO,aAAa,CAAC;YACvB,CAAC,CAAC;YAEF,KAAK,eAAe,EAAE,CAAC;YAEvB,MAAM,QAAQ,GAAG,GAAG,EAAE;gBACpB,gBAAgB,EAAE,CAAC;gBACnB,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,CAAC,CAAC;YAEF,MAAM,SAAS,GAAG,CAAC,UAA0B,EAAE,EAAE,CAC/C,UAAU,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC;YAEjE,wEAAwE;YACxE,wEAAwE;YACxE,qEAAqE;YACrE,mDAAmD;YACnD,MAAM,SAAS,GAAG,CAAC,UAA0B,EAAE,EAAE,CAC/C,CAAC,SAAS,CAAC,UAAU,CAAC;gBACtB,CAAC,CAAC,UAAU,CAAC,YAAY;oBACvB,YAAY,CAAC,UAAU,CAAC,YAAY,CAAC,KAAK,SAAS,CAAC,CAAC;YAEzD,MAAM,kBAAkB,GAAG,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAEzD,MAAM,mBAAmB,GAAG,CAAC,KAAa,EAAE,EAAE;gBAC5C,KAAK,IAAI,QAAQ,GAAG,KAAK,GAAG,CAAC,EAAE,QAAQ,IAAI,CAAC,EAAE,QAAQ,IAAI,CAAC,EAAE,CAAC;oBAC5D,MAAM,SAAS,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;oBACxC,IAAI,SAAS,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;wBAAE,OAAO,SAAS,CAAC,EAAE,CAAC;gBAC9D,CAAC;gBACD,OAAO,SAAS,CAAC;YACnB,CAAC,CAAC;YAEF,MAAM,KAAK,GAA6B,EAAE,CAAC;YAC3C,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE;gBACxC,MAAM,IAAI,GAAG,iBAAiB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;gBAC9C,MAAM,YAAY,GAAG,kBAAkB,CAAC,SAAS,CAC/C,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,UAAU,CAAC,EAAE,CAC9C,CAAC;gBACF,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,MAAM,CAAC;gBACpD,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;gBAC9C,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,KAAK,MAAM,CAAC;gBAExC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG;oBACrB,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,QAAQ,EAAE;wBACR,KAAK,EAAE,YAAY,GAAG,CAAC;wBACvB,KAAK,EAAE,kBAAkB,CAAC,MAAM;qBACjC;oBACD,WAAW,EAAE,IAAI,CAAC,WAAW;oBAC7B,YAAY,EAAE,UAAU,CAAC,YAAY;oBACrC,cAAc,EAAE,UAAU,CAAC,cAAc;oBACzC,oBAAoB,EAAE,UAAU,CAAC,oBAAoB;oBACrD,MAAM,EAAE,UAAU,CAAC,MAAM;oBACzB,QAAQ,EAAE,MAAM;oBAChB,GAAG,CAAC,UAAU,CAAC,EAAE,KAAK,YAAY;wBAChC,CAAC,CAAC;4BACE,aAAa,EAAE,KAAK,IAAI,EAAE;gCACxB,2DAA2D;gCAC3D,4DAA4D;gCAC5D,6DAA6D;gCAC7D,8CAA8C;gCAC9C,gBAAgB,EAAE,CAAC;gCACnB,MAAM,eAAe,EAAE,CAAC;4BAC1B,CAAC;yBACF;wBACH,CAAC,CAAC,EAAE,CAAC;oBACP,OAAO,EAAE;wBACP,GAAG,CAAC,UAAU;4BACZ,CAAC,CAAC;gCACE;oCACE,KAAK,EAAE,CACL,8BACE,KAAC,SAAS,IAAC,WAAW,EAAE,CAAC,EAAE,SAAS,EAAC,gBAAgB,GAAG,YAEvD,CACJ;oCACD,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;oCAC1C,SAAS,EAAE,8BAA8B;oCACzC,OAAO,EAAE,WAAoB;iCAC9B;6BACF;4BACH,CAAC,CAAC,EAAE,CAAC;wBACP;4BACE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CACd,8BACE,KAAC,KAAK,IAAC,WAAW,EAAE,CAAC,EAAE,SAAS,EAAC,gBAAgB,GAAG,eACnD,CACJ,CAAC,CAAC,CAAC,CACF,8BACE,KAAC,UAAU,IAAC,WAAW,EAAE,CAAC,EAAE,SAAS,EAAC,gBAAgB,GAAG,aACxD,CACJ;4BACD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;4BAC9D,SAAS,EAAE,4BAA4B;4BACvC,OAAO,EAAE,SAAkB;yBAC5B;qBACF;iBACF,CAAC;YACJ,CAAC,CAAC,CAAC;YAEH,KAAK,CAAC,KAAK,GAAG;gBACZ,KAAK,EAAE,UAAU;gBACjB,WAAW,EAAE,uBAAuB;gBACpC,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE;oBACP;wBACE,KAAK,EAAE,CACL,8BACE,KAAC,KAAK,IAAC,WAAW,EAAE,CAAC,EAAE,SAAS,EAAC,gBAAgB,GAAG,cACnD,CACJ;wBACD,OAAO,EAAE,QAAQ;qBAClB;iBACF;aACF,CAAC;YAEF,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tour/tour-utils.d.ts

@@ -0,0 +1,26 @@
+/** Resolve duplicate selectors to the mounted instance the user can actually see. */
+export declare function resolveTourElement(selector: string, root?: Document | Element): Element | null;
+export declare function isElementVisible(selector: string): boolean;
+export declare function elementState(selector: string): "absent" | "hidden" | "visible";
+export type CaretSide = "top" | "bottom" | "left" | "right";
+export type CaretPlacement = {
+    left: number;
+    top: number;
+    /** Which bubble edge carries the caret; null when the bubble overlaps the target. */
+    caretSide: CaretSide | null;
+    /** Caret centre along that edge, in px from the bubble's left/top edge. */
+    caretOffset: number;
+};
+/**
+ * Places a bubble of a known size next to a target and keeps it inside the
+ * viewport. The caret is positioned independently of the bubble's clamped
+ * position so it keeps pointing at the target's centre.
+ */
+export declare function placeCaretBubble(position: string, target: DOMRect, bubble: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, margin?: number): CaretPlacement;
+export declare function useTourEscape(enabled: boolean, onEscape: () => void): void;

package/dist/tour/tour-utils.js

@@ -0,0 +1,138 @@
+import { useEffect, useRef } from "react";
+function hasArea(rect) {
+    return rect.width > 0 && rect.height > 0;
+}
+function rectsIntersect(a, b) {
+    return (a.right > b.left && a.left < b.right && a.bottom > b.top && a.top < b.bottom);
+}
+function isClippingOverflow(value) {
+    return value === "hidden" || value === "auto" || value === "scroll";
+}
+function isTourElementVisible(element) {
+    const visibilityElement = element;
+    if (typeof visibilityElement.checkVisibility === "function") {
+        if (!visibilityElement.checkVisibility({
+            checkOpacity: true,
+            checkVisibilityCSS: true,
+        })) {
+            return false;
+        }
+    }
+    else {
+        const styles = window.getComputedStyle(element);
+        if (styles.display === "none" ||
+            styles.visibility === "hidden" ||
+            styles.opacity === "0") {
+            return false;
+        }
+    }
+    const rect = element.getBoundingClientRect();
+    if (!hasArea(rect))
+        return false;
+    let ancestor = element.parentElement;
+    while (ancestor) {
+        const styles = window.getComputedStyle(ancestor);
+        if (isClippingOverflow(styles.overflow) ||
+            isClippingOverflow(styles.overflowX) ||
+            isClippingOverflow(styles.overflowY)) {
+            const ancestorRect = ancestor.getBoundingClientRect();
+            if (!hasArea(ancestorRect) || !rectsIntersect(rect, ancestorRect)) {
+                return false;
+            }
+        }
+        ancestor = ancestor.parentElement;
+    }
+    return true;
+}
+/** Resolve duplicate selectors to the mounted instance the user can actually see. */
+export function resolveTourElement(selector, root = document) {
+    const matches = Array.from(root.querySelectorAll(selector));
+    return matches.find(isTourElementVisible) ?? matches[0] ?? null;
+}
+export function isElementVisible(selector) {
+    const element = resolveTourElement(selector);
+    return element !== null && isTourElementVisible(element);
+}
+export function elementState(selector) {
+    const matches = document.querySelectorAll(selector);
+    if (matches.length === 0)
+        return "absent";
+    return Array.from(matches).some(isTourElementVisible) ? "visible" : "hidden";
+}
+const CARET_GAP = 14;
+const CARET_EDGE_INSET = 24;
+/**
+ * Places a bubble of a known size next to a target and keeps it inside the
+ * viewport. The caret is positioned independently of the bubble's clamped
+ * position so it keeps pointing at the target's centre.
+ */
+export function placeCaretBubble(position, target, bubble, viewport, margin = 12) {
+    const clamp = (value, min, max) => Math.min(Math.max(value, min), Math.max(min, max));
+    const targetCenterX = target.left + target.width / 2;
+    const targetCenterY = target.top + target.height / 2;
+    const maxLeft = viewport.width - bubble.width - margin;
+    const maxTop = viewport.height - bubble.height - margin;
+    let left;
+    let top;
+    let caretSide;
+    switch (position) {
+        case "top":
+        case "top-left":
+        case "top-right":
+            left = clamp(targetCenterX - bubble.width / 2, margin, maxLeft);
+            top = clamp(target.top - CARET_GAP - bubble.height, margin, maxTop);
+            caretSide = "bottom";
+            break;
+        case "left":
+            left = clamp(target.left - CARET_GAP - bubble.width, margin, maxLeft);
+            top = clamp(targetCenterY - bubble.height / 2, margin, maxTop);
+            caretSide = "right";
+            break;
+        case "right":
+            left = clamp(target.left + target.width + CARET_GAP, margin, maxLeft);
+            top = clamp(targetCenterY - bubble.height / 2, margin, maxTop);
+            caretSide = "left";
+            break;
+        default:
+            // "bottom" and "bottom-right"
+            left = clamp(targetCenterX - bubble.width / 2, margin, maxLeft);
+            top = clamp(target.top + target.height + CARET_GAP, margin, maxTop);
+            caretSide = "top";
+            break;
+    }
+    const overlapsTarget = left < target.left + target.width &&
+        left + bubble.width > target.left &&
+        top < target.top + target.height &&
+        top + bubble.height > target.top;
+    const horizontal = caretSide === "top" || caretSide === "bottom";
+    const caretOffset = horizontal
+        ? clamp(targetCenterX - left, CARET_EDGE_INSET, bubble.width - CARET_EDGE_INSET)
+        : clamp(targetCenterY - top, CARET_EDGE_INSET, bubble.height - CARET_EDGE_INSET);
+    return {
+        left,
+        top,
+        caretSide: overlapsTarget ? null : caretSide,
+        caretOffset,
+    };
+}
+export function useTourEscape(enabled, onEscape) {
+    // Callers pass a fresh callback every render; keep the listener stable and
+    // read the latest callback through a ref instead of re-subscribing.
+    const onEscapeRef = useRef(onEscape);
+    onEscapeRef.current = onEscape;
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const handleKeyDown = (event) => {
+            if (event.key !== "Escape")
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            event.stopImmediatePropagation();
+            onEscapeRef.current();
+        };
+        window.addEventListener("keydown", handleKeyDown, true);
+        return () => window.removeEventListener("keydown", handleKeyDown, true);
+    }, [enabled]);
+}
+//# sourceMappingURL=tour-utils.js.map

package/dist/tour/tour-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-utils.js","sourceRoot":"","sources":["../../src/tour/tour-utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parhelia/core",
-  "version": "0.3.12827",
+  "version": "0.3.12831",
   "publishConfig": {
     "access": "public"
   },