@urbicon-ui/blocks 6.1.4

package/dist/utils/floating.js

@@ -0,0 +1,291 @@
+// ─── Types ───────────────────────────────────────────────────────────────────
+// ─── Geometry Helpers ────────────────────────────────────────────────────────
+function getSide(placement) {
+    return placement.split('-')[0];
+}
+function getAlignment(placement) {
+    return placement.split('-')[1];
+}
+function getOppositeSide(side) {
+    return { top: 'bottom', bottom: 'top', left: 'right', right: 'left' }[side];
+}
+function getSideAxis(side) {
+    return side === 'top' || side === 'bottom' ? 'y' : 'x';
+}
+function getBaseCoords(ref, floating, placement) {
+    const side = getSide(placement);
+    const alignment = getAlignment(placement);
+    const centerX = ref.left + ref.width / 2 - floating.width / 2;
+    const centerY = ref.top + ref.height / 2 - floating.height / 2;
+    let x;
+    let y;
+    switch (side) {
+        case 'top':
+            x = centerX;
+            y = ref.top - floating.height;
+            break;
+        case 'bottom':
+            x = centerX;
+            y = ref.bottom;
+            break;
+        case 'left':
+            x = ref.left - floating.width;
+            y = centerY;
+            break;
+        case 'right':
+            x = ref.right;
+            y = centerY;
+            break;
+    }
+    if (alignment) {
+        const isVertical = side === 'top' || side === 'bottom';
+        if (isVertical) {
+            x = alignment === 'start' ? ref.left : ref.right - floating.width;
+        }
+        else {
+            y = alignment === 'start' ? ref.top : ref.bottom - floating.height;
+        }
+    }
+    return { x, y };
+}
+function viewportToLocal(floating, x, y, strategy) {
+    if (strategy === 'fixed')
+        return { x, y };
+    const offsetParent = floating.offsetParent;
+    if (!offsetParent)
+        return { x, y };
+    const parentRect = offsetParent.getBoundingClientRect();
+    return {
+        x: x - parentRect.left + offsetParent.scrollLeft,
+        y: y - parentRect.top + offsetParent.scrollTop
+    };
+}
+function detectOverflow(state, padding = 0) {
+    const vh = window.visualViewport?.height ?? window.innerHeight;
+    const vw = window.visualViewport?.width ?? window.innerWidth;
+    return {
+        top: padding - state.y,
+        bottom: state.y + state.rects.floating.height - vh + padding,
+        left: padding - state.x,
+        right: state.x + state.rects.floating.width - vw + padding
+    };
+}
+// ─── computePosition ─────────────────────────────────────────────────────────
+export function computePosition(reference, floating, options = {}) {
+    const { placement: initialPlacement = 'bottom', strategy = 'absolute', middleware = [] } = options;
+    let placement = initialPlacement;
+    let refRect = reference.getBoundingClientRect();
+    const floatingSize = { width: floating.offsetWidth, height: floating.offsetHeight };
+    let { x, y } = getBaseCoords(refRect, floatingSize, placement);
+    const middlewareData = {};
+    let resetCount = 0;
+    for (let i = 0; i < middleware.length; i++) {
+        const mw = middleware[i];
+        const state = {
+            x,
+            y,
+            placement,
+            initialPlacement,
+            rects: { reference: refRect, floating: floatingSize },
+            elements: { reference, floating },
+            middlewareData,
+            strategy
+        };
+        const result = mw.fn(state);
+        if (result.x != null)
+            x = result.x;
+        if (result.y != null)
+            y = result.y;
+        if (result.data)
+            middlewareData[mw.name] = result.data;
+        if (result.reset && resetCount < 10) {
+            resetCount++;
+            if (typeof result.reset === 'object' && result.reset.placement) {
+                placement = result.reset.placement;
+            }
+            refRect = reference.getBoundingClientRect();
+            floatingSize.width = floating.offsetWidth;
+            floatingSize.height = floating.offsetHeight;
+            ({ x, y } = getBaseCoords(refRect, floatingSize, placement));
+            i = -1;
+        }
+    }
+    const local = viewportToLocal(floating, x, y, strategy);
+    return Promise.resolve({
+        x: local.x,
+        y: local.y,
+        placement,
+        strategy,
+        middlewareData
+    });
+}
+// ─── Middleware: offset ───────────────────────────────────────────────────────
+export function offset(value) {
+    return {
+        name: 'offset',
+        fn(state) {
+            const mainAxis = typeof value === 'number' ? value : (value.mainAxis ?? 0);
+            const crossAxis = typeof value === 'number' ? 0 : (value.crossAxis ?? 0);
+            const side = getSide(state.placement);
+            const axis = getSideAxis(side);
+            const dx = axis === 'y' ? crossAxis : side === 'left' ? -mainAxis : mainAxis;
+            const dy = axis === 'y' ? (side === 'top' ? -mainAxis : mainAxis) : crossAxis;
+            return { x: state.x + dx, y: state.y + dy, data: { x: dx, y: dy } };
+        }
+    };
+}
+// ─── Middleware: flip ─────────────────────────────────────────────────────────
+export function flip(options) {
+    const padding = options?.padding ?? 0;
+    return {
+        name: 'flip',
+        fn(state) {
+            const flipData = state.middlewareData.flip;
+            if (flipData?.flipped)
+                return {};
+            const overflow = detectOverflow(state, padding);
+            const side = getSide(state.placement);
+            const alignment = getAlignment(state.placement);
+            const axis = getSideAxis(side);
+            const mainOverflow = axis === 'y'
+                ? side === 'top'
+                    ? overflow.top
+                    : overflow.bottom
+                : side === 'left'
+                    ? overflow.left
+                    : overflow.right;
+            if (mainOverflow > 0) {
+                const ref = state.rects.reference;
+                const vh = window.visualViewport?.height ?? window.innerHeight;
+                const vw = window.visualViewport?.width ?? window.innerWidth;
+                const spaceOnSide = axis === 'y'
+                    ? side === 'bottom'
+                        ? vh - ref.top - ref.height
+                        : ref.top
+                    : side === 'right'
+                        ? vw - ref.left - ref.width
+                        : ref.left;
+                const spaceOnOpposite = axis === 'y'
+                    ? side === 'bottom'
+                        ? ref.top
+                        : vh - ref.top - ref.height
+                    : side === 'right'
+                        ? ref.left
+                        : vw - ref.left - ref.width;
+                if (spaceOnOpposite > spaceOnSide) {
+                    const opposite = getOppositeSide(side);
+                    const newPlacement = alignment ? `${opposite}-${alignment}` : opposite;
+                    return { data: { flipped: true }, reset: { placement: newPlacement } };
+                }
+            }
+            return {};
+        }
+    };
+}
+// ─── Middleware: shift ────────────────────────────────────────────────────────
+export function shift(options) {
+    const padding = options?.padding ?? 0;
+    return {
+        name: 'shift',
+        fn(state) {
+            const overflow = detectOverflow(state, padding);
+            const axis = getSideAxis(getSide(state.placement));
+            let { x, y } = state;
+            if (axis === 'y') {
+                if (overflow.left > 0)
+                    x += overflow.left;
+                else if (overflow.right > 0)
+                    x -= overflow.right;
+            }
+            else {
+                if (overflow.top > 0)
+                    y += overflow.top;
+                else if (overflow.bottom > 0)
+                    y -= overflow.bottom;
+            }
+            return { x, y, data: { x: x - state.x, y: y - state.y } };
+        }
+    };
+}
+// ─── Middleware: arrow ────────────────────────────────────────────────────────
+export function arrow(options) {
+    return {
+        name: 'arrow',
+        fn(state) {
+            const { element: arrowEl, padding = 0 } = options;
+            const side = getSide(state.placement);
+            const isVertical = side === 'top' || side === 'bottom';
+            const arrowLen = isVertical ? arrowEl.offsetWidth : arrowEl.offsetHeight;
+            const refCenter = isVertical
+                ? state.rects.reference.left + state.rects.reference.width / 2
+                : state.rects.reference.top + state.rects.reference.height / 2;
+            const floatingStart = isVertical ? state.x : state.y;
+            const floatingLen = isVertical ? state.rects.floating.width : state.rects.floating.height;
+            const center = refCenter - floatingStart;
+            const min = padding;
+            const max = floatingLen - arrowLen - padding;
+            const arrowPos = Math.max(min, Math.min(center - arrowLen / 2, max));
+            return {
+                data: {
+                    x: isVertical ? arrowPos : undefined,
+                    y: isVertical ? undefined : arrowPos
+                }
+            };
+        }
+    };
+}
+// ─── Middleware: size ─────────────────────────────────────────────────────────
+export function size(options) {
+    return {
+        name: 'size',
+        fn(state) {
+            const overflow = detectOverflow(state);
+            const availableWidth = state.rects.floating.width - Math.max(0, overflow.left) - Math.max(0, overflow.right);
+            const availableHeight = state.rects.floating.height - Math.max(0, overflow.top) - Math.max(0, overflow.bottom);
+            options.apply({ ...state, availableWidth, availableHeight });
+            const newW = state.elements.floating.offsetWidth;
+            const newH = state.elements.floating.offsetHeight;
+            if (newW !== state.rects.floating.width || newH !== state.rects.floating.height) {
+                return { reset: true };
+            }
+            return {};
+        }
+    };
+}
+// ─── autoUpdate ──────────────────────────────────────────────────────────────
+export function autoUpdate(reference, floating, callback) {
+    const cleanups = [];
+    if (typeof ResizeObserver !== 'undefined') {
+        const ro = new ResizeObserver(() => callback());
+        ro.observe(reference);
+        ro.observe(floating);
+        cleanups.push(() => ro.disconnect());
+    }
+    function getScrollAncestors(el) {
+        const ancestors = [];
+        let current = el.parentElement;
+        while (current) {
+            const { overflow, overflowX, overflowY } = getComputedStyle(current);
+            if (/auto|scroll|overlay|hidden/.test(overflow + overflowX + overflowY)) {
+                ancestors.push(current);
+            }
+            current = current.parentElement;
+        }
+        ancestors.push(window);
+        return ancestors;
+    }
+    const scrollAncestors = new Set([
+        ...getScrollAncestors(reference),
+        ...getScrollAncestors(floating)
+    ]);
+    for (const ancestor of scrollAncestors) {
+        ancestor.addEventListener('scroll', callback, { passive: true });
+        cleanups.push(() => ancestor.removeEventListener('scroll', callback));
+    }
+    window.addEventListener('resize', callback);
+    cleanups.push(() => window.removeEventListener('resize', callback));
+    return () => {
+        for (const fn of cleanups)
+            fn();
+    };
+}

package/dist/utils/guide.svelte.d.ts

@@ -0,0 +1,264 @@
+import type { Attachment } from 'svelte/attachments';
+import type { Placement } from './floating';
+/** Which link directions a topic supports (D3/§4). `both` when omitted. */
+export type GuideDirection = 'to-guide' | 'to-ui' | 'both';
+/** Metadata attached to a registered target via `target(id, meta)`. */
+export interface GuideTopicMeta {
+    /** Human-readable label, e.g. "Save button". */
+    label?: string;
+    /** Article id this topic links to (Direction A: Marker → Panel). */
+    article?: string;
+    /** Enabled link directions. @default 'both' */
+    direction?: GuideDirection;
+}
+/** A single step of a guided tour. */
+export interface GuideStep {
+    /** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
+    target?: string;
+    /** Step heading. */
+    title?: string;
+    /** Step body text. */
+    body?: string;
+    /** Preferred bubble placement relative to the target (Phase 6). */
+    placement?: Placement;
+    /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
+    interactive?: boolean;
+    /**
+     * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
+     * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
+     * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
+     * `controller.next()` once the user performed the real action (usually combined with
+     * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
+     * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
+     * @default 'user'
+     */
+    advance?: 'user' | 'action';
+}
+/**
+ * Payload for {@link GuideTour.onStep} — fired when a step becomes the active one.
+ */
+export interface GuideStepEvent {
+    /** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
+    tour: GuideTour;
+    /** Zero-based index of the now-active step. */
+    index: number;
+    /** The now-active step. */
+    step: GuideStep;
+    /** Total number of steps in the tour. */
+    total: number;
+    /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
+    via: 'start' | 'next' | 'prev';
+}
+/**
+ * Payload for {@link GuideTour.onComplete} and {@link GuideTour.onSkip} — a snapshot of
+ * where the tour ended (e.g. the step a user skipped from, for drop-off analytics).
+ */
+export interface GuideEndEvent {
+    /** The tour that ended. */
+    tour: GuideTour;
+    /** Index of the step that was active when the tour ended. */
+    index: number;
+    /** The step active at the end (`null` only for an empty tour, which never starts). */
+    step: GuideStep | null;
+    /** Total number of steps in the tour. */
+    total: number;
+}
+/** A guided tour definition. */
+export interface GuideTour {
+    /** Unique id — used for "seen" persistence. */
+    id: string;
+    /** Ordered steps. */
+    steps: GuideStep[];
+    /** Skip automatically once completed/dismissed. @default true */
+    once?: boolean;
+    /**
+     * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
+     * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
+     * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
+     */
+    onStep?: (event: GuideStepEvent) => void;
+    /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
+    onComplete?: (event: GuideEndEvent) => void;
+    /**
+     * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
+     * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
+     * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
+     */
+    onSkip?: (event: GuideEndEvent) => void;
+}
+/**
+ * Persistence boundary for "seen" ids. The default is localStorage-backed, but a
+ * consumer can inject a server-state adapter. Kept deliberately tiny.
+ */
+export interface GuideStorageAdapter {
+    /** Returns the persisted set of seen/completed ids. */
+    load(): string[];
+    /** Persists the full set of seen/completed ids. */
+    save(ids: string[]): void;
+}
+/** Minimal slice of the overlay stack the controller depends on (injectable for tests). */
+export interface GuideOverlayStackLike {
+    register(id: string, close: () => void): () => void;
+    isTop(id: string): boolean;
+    /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
+    readonly depth: number;
+}
+/** Options for {@link GuideController}; every dependency is injectable for testing. */
+export interface GuideControllerOptions {
+    /** Persistence adapter. @default localStorage-backed adapter */
+    storage?: GuideStorageAdapter;
+    /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
+    overlayStack?: GuideOverlayStackLike;
+    /** Force DEV-mode warnings on/off. @default `import.meta.env.DEV` */
+    dev?: boolean;
+}
+/**
+ * The default {@link GuideStorageAdapter}: localStorage-backed, SSR-safe, and
+ * resilient to private-mode / quota failures (mirrors `persistent-state`).
+ */
+export declare function createLocalStorageAdapter(key?: string): GuideStorageAdapter;
+/**
+ * Headless engine for the Guide system — the UI-free state machine behind every
+ * Guide surface (Panel, Marker, Mention, Hint, Tour).
+ *
+ * One instance per `GuideProvider` (Phase 2) — *not* a singleton, so multiple scopes
+ * can coexist and tests get a fresh instance. Modeled on `OverlayStack` (class with
+ * `$state` + `untrack`).
+ *
+ * Responsibilities:
+ * - **Target registry** — maps `data-guide` ids to live DOM elements, fed by the
+ *   `target()` attachment and resolved with a `[data-guide="…"]` DOM fallback.
+ * - **Tour state machine** — `startTour` / `next` / `prev` / `skip` / `finish`.
+ * - **Highlight** — `highlight` / `clearHighlight`, shared by tour steps and the
+ *   bidirectional Mention→UI link (Direction B). Toggles a `data-guide-highlight`
+ *   attribute; the additive ring itself is pure CSS (token-driven, D5).
+ * - **Panel state** — `openPanel` / `closePanel` (the UI lands in Phase 3).
+ * - **Persistence** — `hasSeen` / `markSeen` via an injectable {@link GuideStorageAdapter}.
+ * - **Analytics hooks** — fires the active tour's `onStep` / `onComplete` / `onSkip`
+ *   callbacks (the actual business value of a tour) defensively, so a throwing
+ *   consumer callback can never corrupt tour state or leak the overlay entry.
+ * - **overlay-stack integration** — a running tour registers itself so it pauses
+ *   when a foreign modal (Dialog/Drawer) stacks on top.
+ *
+ * @stability beta
+ */
+export declare class GuideController {
+    #private;
+    constructor(options?: GuideControllerOptions);
+    /**
+     * Register a DOM element under a `data-guide` id. Returns an unregister function —
+     * use it as the cleanup of the `target()` attachment.
+     */
+    registerTarget(id: string, element: HTMLElement, meta?: GuideTopicMeta): () => void;
+    /** Remove a target. No-op if `element` is not the currently registered one. */
+    unregisterTarget(id: string, element: HTMLElement): void;
+    /**
+     * Svelte attachment that registers the host element as a guide target.
+     *
+     * @example
+     * ```svelte
+     * <button {@attach guide.target('save', { label: 'Save', article: 'saving' })}>Save</button>
+     * ```
+     */
+    target(id: string, meta?: GuideTopicMeta): Attachment;
+    /**
+     * Resolve a `data-guide` id to its element: the programmatic registry first, then
+     * a `[data-guide="…"]` DOM lookup as fallback. Returns `null` if unresolved.
+     */
+    resolveTarget(id: string): HTMLElement | null;
+    /** Metadata for a registered target, if any. */
+    getTopicMeta(id: string): GuideTopicMeta | undefined;
+    /**
+     * Effective link direction for a topic (§4.3). A surface-level `override` wins
+     * over the topic's registered `direction`, which in turn defaults to `'both'`.
+     * Surfaces derive their gating from this: a `GuideMarker` (UI→Guide) is live when
+     * the result is not `'to-ui'`; a `GuideMention` (Guide→UI) when it is not `'to-guide'`.
+     */
+    resolveDirection(id: string, override?: GuideDirection): GuideDirection;
+    get activeTour(): GuideTour | null;
+    get isTourActive(): boolean;
+    get stepIndex(): number;
+    get currentStep(): GuideStep | null;
+    get stepCount(): number;
+    get isFirstStep(): boolean;
+    get isLastStep(): boolean;
+    /**
+     * `true` when a foreign overlay (Dialog/Drawer) sits above the running tour — the
+     * UI should hide/dim while paused. Derives from `overlayStack.isTop`, so it reacts
+     * automatically as foreign overlays open and close.
+     */
+    get paused(): boolean;
+    /**
+     * Number of modal overlays currently stacked (Dialog/Drawer/Sidebar + an active
+     * guided tour). Non-modal surfaces — notably `GuideHint` — hide while this is `> 0`,
+     * the top-layer discipline from §3.4. Reactive via the injected overlay stack.
+     */
+    get overlayDepth(): number;
+    /**
+     * Start a tour. Returns `false` (and does nothing) when the tour was already seen
+     * (and `once !== false`) or has no steps.
+     */
+    startTour(tour: GuideTour): boolean;
+    /** Advance to the next step, or finish the tour if on the last step. */
+    next(): void;
+    /** Go back one step. No-op on the first step. */
+    prev(): void;
+    /** Dismiss the tour without completing it — marks it seen, fires `onSkip`. */
+    skip(): void;
+    /** Complete the tour — marks it seen, fires `onComplete`. */
+    finish(): void;
+    /**
+     * Tear a running tour down **without** marking it seen — for programmatic teardown such as
+     * the `Guide` renderer unmounting mid-tour, a route change, or logout. Unlike `skip`/`finish`
+     * (user-driven, "never nag" → seen), a stopped tour can surface again. Releases the
+     * overlay-stack entry and clears the highlight ring; no-op if no tour is active.
+     */
+    stopTour(): void;
+    /**
+     * Re-apply the current step's highlight + scroll — for a surface that detected its
+     * target resolving *after* the step began (a lazily rendered `data-guide` element) or
+     * vanishing mid-step (removed / swapped by a route change). On step change the engine
+     * highlights once; if the element wasn't in the DOM yet the ring couldn't land, so the
+     * surface calls this once it observes the target appear (or disappear → ring clears).
+     * No-op when no tour is active.
+     */
+    reapplyStepHighlight(): void;
+    get highlightedId(): string | null;
+    /**
+     * Highlight a target by id — toggles a `data-guide-highlight` attribute the CSS
+     * ring hooks into (additive `outline`, never a scrim — D5). No-op + DEV warning
+     * if the target is unresolved.
+     *
+     * @param options.scroll Scroll the target into view (Direction B click — D5).
+     *   Honors `prefers-reduced-motion` (instant jump instead of smooth scroll).
+     */
+    highlight(id: string, options?: {
+        scroll?: boolean;
+    }): void;
+    /** Clear the current highlight. */
+    clearHighlight(): void;
+    get panelOpen(): boolean;
+    get activeArticle(): string | null;
+    /** Open the help panel, optionally jumping to a specific article (Direction A). */
+    openPanel(article?: string): void;
+    /** Close the help panel. */
+    closePanel(): void;
+    /** Set the active article without changing the panel's open state. */
+    setArticle(article: string | null): void;
+    /** Live `GuidePanel` DOM id, or `null` when no panel is mounted. */
+    get panelId(): string | null;
+    /**
+     * Publish the mounted `GuidePanel`'s DOM id so `GuideMarker`s can target it via
+     * `aria-controls`. Returns a cleanup that releases it. One panel per provider is
+     * the norm; the most recent registration wins.
+     */
+    registerPanel(id: string): () => void;
+    /** Whether an id (tour, hint, …) has been seen. */
+    hasSeen(id: string): boolean;
+    /** Mark an id as seen and persist. */
+    markSeen(id: string): void;
+    /** Forget one id, or all of them when called without an argument. */
+    resetSeen(id?: string): void;
+    /** Snapshot of all seen ids. */
+    get seenIds(): string[];
+}