@urbicon-ui/blocks 6.1.4

package/dist/utils/guide.svelte.js

@@ -0,0 +1,488 @@
+import { untrack } from 'svelte';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { overlayStack } from './overlay-stack.svelte';
+/**
+ * Guide system — the headless engine. The full design lives in docs/GUIDE.md.
+ *
+ * @module
+ */
+const BROWSER = typeof window !== 'undefined';
+const SEEN_STORAGE_KEY = 'urbicon_guide_seen_v1';
+/**
+ * The default {@link GuideStorageAdapter}: localStorage-backed, SSR-safe, and
+ * resilient to private-mode / quota failures (mirrors `persistent-state`).
+ */
+export function createLocalStorageAdapter(key = SEEN_STORAGE_KEY) {
+    return {
+        load() {
+            if (!BROWSER)
+                return [];
+            try {
+                const raw = window.localStorage.getItem(key);
+                if (!raw)
+                    return [];
+                const parsed = JSON.parse(raw);
+                return Array.isArray(parsed)
+                    ? parsed.filter((x) => typeof x === 'string')
+                    : [];
+            }
+            catch {
+                return [];
+            }
+        },
+        save(ids) {
+            if (!BROWSER)
+                return;
+            try {
+                window.localStorage.setItem(key, JSON.stringify(ids));
+            }
+            catch {
+                /* private mode / quota exceeded — persistence is best-effort */
+            }
+        }
+    };
+}
+let tourIdCounter = 0;
+/** Opaque id for overlay-stack registration. Never SSR-rendered, so no hydration risk. */
+function nextOverlayId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return `guide-tour-${++tourIdCounter}`;
+}
+/**
+ * Escape a value for a `[data-guide="…"]` selector. Only ever called inside a
+ * `typeof document` guard, where `CSS.escape` exists; the string fallback is a
+ * belt-and-suspenders path for exotic DOM-less-but-CSS-less environments.
+ */
+function escapeAttr(value) {
+    if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function')
+        return CSS.escape(value);
+    return value.replace(/["\\]/g, '\\$&');
+}
+const HIGHLIGHT_ATTR = 'data-guide-highlight';
+/**
+ * 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 class GuideController {
+    /** Live DOM targets, keyed by `data-guide` id. Reactive so resolution updates. */
+    #targets = new SvelteMap();
+    /** Persisted "seen" ids. */
+    #seen;
+    #storage;
+    #overlayStack;
+    #dev;
+    // ── Tour state ──────────────────────────────────────────
+    #activeTour = $state(null);
+    #stepIndex = $state(0);
+    // $state so the `paused` getter stays reactive even if the id is ever rotated
+    // independently of #activeTour (today they always change in lockstep).
+    #tourOverlayId = $state(null);
+    #tourUnregister = null;
+    // ── Highlight (shared by tour steps + Mention→UI, Direction B) ──
+    #highlightedId = $state(null);
+    // ── Panel state (UI in Phase 3) ─────────────────────────
+    #panelOpen = $state(false);
+    #activeArticle = $state(null);
+    // Live GuidePanel DOM id, published by the mounted panel so a GuideMarker can
+    // wire `aria-controls` (Direction A). `null` until a panel mounts (e.g. SSR).
+    #panelId = $state(null);
+    constructor(options = {}) {
+        this.#storage = options.storage ?? createLocalStorageAdapter();
+        this.#overlayStack = options.overlayStack ?? overlayStack;
+        this.#dev = options.dev ?? import.meta.env.DEV;
+        this.#seen = new SvelteSet(this.#storage.load());
+    }
+    // ─── Target registry ──────────────────────────────────────────────────────
+    /**
+     * Register a DOM element under a `data-guide` id. Returns an unregister function —
+     * use it as the cleanup of the `target()` attachment.
+     */
+    registerTarget(id, element, meta = {}) {
+        const existing = untrack(() => this.#targets.get(id));
+        if (existing && existing.element !== element && this.#dev) {
+            console.warn(`[Guide] duplicate target id "${id}" — the previously registered element is being overwritten.`);
+        }
+        this.#targets.set(id, { element, meta });
+        return () => this.unregisterTarget(id, element);
+    }
+    /** Remove a target. No-op if `element` is not the currently registered one. */
+    unregisterTarget(id, element) {
+        const current = untrack(() => this.#targets.get(id));
+        if (current && current.element === element) {
+            this.#targets.delete(id);
+            // Clear via the element directly: once removed from the registry it is no longer
+            // resolvable (a purely programmatic target carries no data-guide attribute), so
+            // clearHighlight()/resolveTarget() could not reach it to drop the attribute.
+            if (untrack(() => this.#highlightedId) === id) {
+                element.removeAttribute(HIGHLIGHT_ATTR);
+                this.#highlightedId = null;
+            }
+        }
+    }
+    /**
+     * 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, meta) {
+        return (element) => this.registerTarget(id, element, meta);
+    }
+    /**
+     * 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) {
+        const registered = this.#targets.get(id);
+        if (registered)
+            return registered.element;
+        if (typeof document !== 'undefined') {
+            return document.querySelector(`[data-guide="${escapeAttr(id)}"]`);
+        }
+        return null;
+    }
+    /** Metadata for a registered target, if any. */
+    getTopicMeta(id) {
+        return this.#targets.get(id)?.meta;
+    }
+    /**
+     * 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, override) {
+        return override ?? this.#targets.get(id)?.meta.direction ?? 'both';
+    }
+    // ─── Tour state machine ───────────────────────────────────────────────────
+    get activeTour() {
+        return this.#activeTour;
+    }
+    get isTourActive() {
+        return this.#activeTour !== null;
+    }
+    get stepIndex() {
+        return this.#stepIndex;
+    }
+    get currentStep() {
+        return this.#activeTour?.steps[this.#stepIndex] ?? null;
+    }
+    get stepCount() {
+        return this.#activeTour?.steps.length ?? 0;
+    }
+    get isFirstStep() {
+        return this.#stepIndex === 0;
+    }
+    get isLastStep() {
+        return this.#activeTour ? this.#stepIndex === this.#activeTour.steps.length - 1 : false;
+    }
+    /**
+     * `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() {
+        if (!this.#activeTour || this.#tourOverlayId === null)
+            return false;
+        return !this.#overlayStack.isTop(this.#tourOverlayId);
+    }
+    /**
+     * 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() {
+        return this.#overlayStack.depth;
+    }
+    /**
+     * Start a tour. Returns `false` (and does nothing) when the tour was already seen
+     * (and `once !== false`) or has no steps.
+     */
+    startTour(tour) {
+        if (tour.once !== false && this.hasSeen(tour.id))
+            return false;
+        if (tour.steps.length === 0) {
+            if (this.#dev)
+                console.warn(`[Guide] tour "${tour.id}" has no steps — not started.`);
+            return false;
+        }
+        // Tear down any tour already running so its overlay-stack entry never leaks.
+        this.#teardownTour();
+        this.#activeTour = tour;
+        this.#stepIndex = 0;
+        this.#tourOverlayId = nextOverlayId();
+        this.#tourUnregister = this.#overlayStack.register(this.#tourOverlayId, () => this.skip());
+        this.#applyStepHighlight();
+        this.#emitStep('start');
+        return true;
+    }
+    /** Advance to the next step, or finish the tour if on the last step. */
+    next() {
+        if (!this.#activeTour)
+            return;
+        if (this.isLastStep) {
+            this.finish();
+            return;
+        }
+        this.#stepIndex += 1;
+        this.#applyStepHighlight();
+        this.#emitStep('next');
+    }
+    /** Go back one step. No-op on the first step. */
+    prev() {
+        if (!this.#activeTour || this.isFirstStep)
+            return;
+        this.#stepIndex -= 1;
+        this.#applyStepHighlight();
+        this.#emitStep('prev');
+    }
+    /** Dismiss the tour without completing it — marks it seen, fires `onSkip`. */
+    skip() {
+        const tour = this.#activeTour;
+        if (!tour)
+            return;
+        const event = this.#endEvent(tour);
+        this.#endTour();
+        this.#emit(tour.onSkip, event);
+    }
+    /** Complete the tour — marks it seen, fires `onComplete`. */
+    finish() {
+        const tour = this.#activeTour;
+        if (!tour)
+            return;
+        const event = this.#endEvent(tour);
+        this.#endTour();
+        this.#emit(tour.onComplete, event);
+    }
+    /**
+     * 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() {
+        if (this.#activeTour)
+            this.#teardownTour();
+    }
+    /**
+     * 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() {
+        if (this.#activeTour)
+            this.#applyStepHighlight();
+    }
+    #endTour() {
+        const tour = this.#activeTour;
+        this.#teardownTour();
+        // Both skip and finish mark the tour seen — "helpful, not intrusive": never nag.
+        // (The skip/complete distinction itself lives in skip()/finish(), which fire the
+        // matching analytics callback around this shared teardown.)
+        if (tour && tour.once !== false)
+            this.markSeen(tour.id);
+    }
+    /** Reset all tour state and release the overlay-stack registration. No persistence. */
+    #teardownTour() {
+        this.clearHighlight();
+        this.#tourUnregister?.();
+        this.#tourUnregister = null;
+        this.#tourOverlayId = null;
+        this.#activeTour = null;
+        this.#stepIndex = 0;
+    }
+    // ─── Analytics hooks (onStep / onComplete / onSkip) ───────────────────────
+    /** Snapshot of the end-of-tour state for an `onComplete`/`onSkip` payload. */
+    #endEvent(tour) {
+        return { tour, index: this.#stepIndex, step: this.currentStep, total: tour.steps.length };
+    }
+    /** Fire the active tour's `onStep` for the current step (after highlight is applied). */
+    #emitStep(via) {
+        const tour = this.#activeTour;
+        const step = this.currentStep;
+        if (!tour || !step)
+            return;
+        this.#emit(tour.onStep, { tour, index: this.#stepIndex, step, total: tour.steps.length, via });
+    }
+    /**
+     * Invoke a consumer-supplied tour callback, swallowing throws (DEV-warned) so analytics
+     * code can never corrupt tour state or leak the overlay-stack entry. Mirrors the
+     * best-effort posture of the localStorage adapter.
+     */
+    #emit(fn, event) {
+        if (!fn)
+            return;
+        try {
+            fn(event);
+        }
+        catch (err) {
+            if (this.#dev)
+                console.warn('[Guide] a tour analytics callback threw:', err);
+        }
+    }
+    #applyStepHighlight() {
+        const step = this.currentStep;
+        if (!step)
+            return;
+        if (!step.target) {
+            this.clearHighlight();
+            return;
+        }
+        if (this.resolveTarget(step.target)) {
+            // Scroll the step target into view before the bubble anchors to it (§6.1/6.2).
+            // Unlike Direction-B hover (which never scrolls), a tour drives the viewport —
+            // the scroll is reduced-motion-aware inside `highlight`.
+            this.highlight(step.target, { scroll: true });
+        }
+        else {
+            this.clearHighlight();
+            if (this.#dev) {
+                console.warn(`[Guide] tour "${this.#activeTour?.id}" step ${this.#stepIndex}: target "${step.target}" not found in DOM.`);
+            }
+        }
+    }
+    // ─── Highlight (Direction B + tour steps) ─────────────────────────────────
+    get highlightedId() {
+        return this.#highlightedId;
+    }
+    /**
+     * 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, options) {
+        const el = this.resolveTarget(id);
+        if (!el) {
+            if (this.#dev)
+                console.warn(`[Guide] highlight target "${id}" not found in DOM.`);
+            return;
+        }
+        if (this.#highlightedId && this.#highlightedId !== id) {
+            this.resolveTarget(this.#highlightedId)?.removeAttribute(HIGHLIGHT_ATTR);
+        }
+        this.#highlightedId = id;
+        el.setAttribute(HIGHLIGHT_ATTR, '');
+        if (options?.scroll)
+            this.#scrollIntoView(el);
+    }
+    /** Scroll an element into view, reduced-motion-aware. DOM-guarded for SSR/tests. */
+    #scrollIntoView(el) {
+        if (typeof el.scrollIntoView !== 'function')
+            return;
+        el.scrollIntoView({
+            block: 'nearest',
+            inline: 'nearest',
+            behavior: this.#prefersReducedMotion() ? 'auto' : 'smooth'
+        });
+    }
+    /** One-shot reduced-motion read. SSR/test-safe (no `matchMedia` → not reduced). */
+    #prefersReducedMotion() {
+        if (!BROWSER || typeof window.matchMedia !== 'function')
+            return false;
+        try {
+            return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Clear the current highlight. */
+    clearHighlight() {
+        if (this.#highlightedId) {
+            this.resolveTarget(this.#highlightedId)?.removeAttribute(HIGHLIGHT_ATTR);
+        }
+        this.#highlightedId = null;
+    }
+    // ─── Panel state (UI in Phase 3) ──────────────────────────────────────────
+    get panelOpen() {
+        return this.#panelOpen;
+    }
+    get activeArticle() {
+        return this.#activeArticle;
+    }
+    /** Open the help panel, optionally jumping to a specific article (Direction A). */
+    openPanel(article) {
+        this.#panelOpen = true;
+        if (article !== undefined)
+            this.#activeArticle = article;
+    }
+    /** Close the help panel. */
+    closePanel() {
+        this.#panelOpen = false;
+    }
+    /** Set the active article without changing the panel's open state. */
+    setArticle(article) {
+        this.#activeArticle = article;
+    }
+    /** Live `GuidePanel` DOM id, or `null` when no panel is mounted. */
+    get panelId() {
+        return this.#panelId;
+    }
+    /**
+     * 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) {
+        this.#panelId = id;
+        return () => {
+            if (untrack(() => this.#panelId) === id)
+                this.#panelId = null;
+        };
+    }
+    // ─── Persistence ──────────────────────────────────────────────────────────
+    /** Whether an id (tour, hint, …) has been seen. */
+    hasSeen(id) {
+        return this.#seen.has(id);
+    }
+    /** Mark an id as seen and persist. */
+    markSeen(id) {
+        if (this.#seen.has(id))
+            return;
+        this.#seen.add(id);
+        this.#storage.save([...this.#seen]);
+    }
+    /** Forget one id, or all of them when called without an argument. */
+    resetSeen(id) {
+        if (id === undefined)
+            this.#seen.clear();
+        else
+            this.#seen.delete(id);
+        this.#storage.save([...this.#seen]);
+    }
+    /** Snapshot of all seen ids. */
+    get seenIds() {
+        return [...this.#seen];
+    }
+}

package/dist/utils/id.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generates a unique ID, optionally with a prefix.
+ *
+ * Inside Svelte components prefer `$props.id()` (Svelte 5) — it is
+ * deterministic across SSR and the client, so it avoids hydration
+ * mismatches. This helper exists for non-component code (tests, build
+ * tools) and uses `crypto.randomUUID()` when available, falling back
+ * to `Math.random()` only on legacy runtimes.
+ *
+ * @param prefix - An optional prefix for the ID.
+ * @returns A unique string ID.
+ */
+export declare function id(prefix?: string): string;

package/dist/utils/id.js

@@ -0,0 +1,18 @@
+/**
+ * Generates a unique ID, optionally with a prefix.
+ *
+ * Inside Svelte components prefer `$props.id()` (Svelte 5) — it is
+ * deterministic across SSR and the client, so it avoids hydration
+ * mismatches. This helper exists for non-component code (tests, build
+ * tools) and uses `crypto.randomUUID()` when available, falling back
+ * to `Math.random()` only on legacy runtimes.
+ *
+ * @param prefix - An optional prefix for the ID.
+ * @returns A unique string ID.
+ */
+export function id(prefix = 'blocks-') {
+    const random = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+        ? crypto.randomUUID().replace(/-/g, '').slice(0, 7)
+        : Math.random().toString(36).substring(2, 9);
+    return `${prefix}${random}`;
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,16 @@
+export * from './date';
+export * from './draggable';
+export * from './figma-token-export';
+export { arrow, autoUpdate, type ComputePositionReturn, computePosition, flip, type Middleware, offset, type Placement, type Strategy, shift, size } from './floating';
+export { createLocalStorageAdapter, GuideController, type GuideControllerOptions, type GuideDirection, type GuideEndEvent, type GuideOverlayStackLike, type GuideStep, type GuideStepEvent, type GuideStorageAdapter, type GuideTopicMeta, type GuideTour } from './guide.svelte';
+export * from './id';
+export { observeTargetResolution } from './observe-target';
+export { createOptionalContext } from './optional-context';
+export { overlayStack } from './overlay-stack.svelte';
+export { type EasingFn, getOverlayMotion, OVERLAY_MOTION_DEFAULTS, type OverlayMotion, type OverlayMotionOverride } from './overlay-tokens';
+export * from './persistent-state.svelte';
+export { getTierContext, type InteractiveTier, setTierContext, type TierContext } from './tier-context';
+export * from './types';
+export { type FloatingListboxOptions, useFloatingListbox } from './use-floating-listbox.svelte';
+export { computeFormFieldAria, type UseFormFieldInputs, type UseFormFieldReturn, useFormField } from './use-form-field.svelte';
+export { cx, type TVProps, tv, type VariantProps } from './variants';

package/dist/utils/index.js

@@ -0,0 +1,16 @@
+export * from './date';
+export * from './draggable';
+export * from './figma-token-export';
+export { arrow, autoUpdate, computePosition, flip, offset, shift, size } from './floating';
+export { createLocalStorageAdapter, GuideController } from './guide.svelte';
+export * from './id';
+export { observeTargetResolution } from './observe-target';
+export { createOptionalContext } from './optional-context';
+export { overlayStack } from './overlay-stack.svelte';
+export { getOverlayMotion, OVERLAY_MOTION_DEFAULTS } from './overlay-tokens';
+export * from './persistent-state.svelte';
+export { getTierContext, setTierContext } from './tier-context';
+export * from './types';
+export { useFloatingListbox } from './use-floating-listbox.svelte';
+export { computeFormFieldAria, useFormField } from './use-form-field.svelte';
+export { cx, tv } from './variants';

package/dist/utils/observe-target.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Watch the DOM for a target element's *resolution* changing — appearing (a lazily
+ * rendered `data-guide` element) or disappearing (removed, or swapped out by a route
+ * change). `onChange(next)` fires whenever `resolve()` returns a different element than
+ * the previous call, coalesced to at most one resolve per animation frame so a burst of
+ * unrelated mutations (e.g. a live table re-rendering rows) stays cheap.
+ *
+ * This complements {@link autoUpdate}, which only tracks the *position and size* of an
+ * element that already exists — it cannot notice one that is not in the DOM yet, nor one
+ * that has been removed. The Guide surfaces (tour bubble + hint) use this to re-anchor a
+ * step whose target renders after the surface, and to fall back gracefully when a target
+ * vanishes mid-flight.
+ *
+ * SSR / no-`MutationObserver` safe: returns a no-op disconnect when there is no DOM.
+ *
+ * @param resolve Returns the current target element (or `null` when unresolved).
+ * @param onChange Called with the new element each time resolution flips.
+ * @returns A disconnect function — call it on cleanup.
+ */
+export declare function observeTargetResolution(resolve: () => HTMLElement | null, onChange: (next: HTMLElement | null) => void): () => void;

package/dist/utils/observe-target.js

@@ -0,0 +1,60 @@
+/**
+ * Watch the DOM for a target element's *resolution* changing — appearing (a lazily
+ * rendered `data-guide` element) or disappearing (removed, or swapped out by a route
+ * change). `onChange(next)` fires whenever `resolve()` returns a different element than
+ * the previous call, coalesced to at most one resolve per animation frame so a burst of
+ * unrelated mutations (e.g. a live table re-rendering rows) stays cheap.
+ *
+ * This complements {@link autoUpdate}, which only tracks the *position and size* of an
+ * element that already exists — it cannot notice one that is not in the DOM yet, nor one
+ * that has been removed. The Guide surfaces (tour bubble + hint) use this to re-anchor a
+ * step whose target renders after the surface, and to fall back gracefully when a target
+ * vanishes mid-flight.
+ *
+ * SSR / no-`MutationObserver` safe: returns a no-op disconnect when there is no DOM.
+ *
+ * @param resolve Returns the current target element (or `null` when unresolved).
+ * @param onChange Called with the new element each time resolution flips.
+ * @returns A disconnect function — call it on cleanup.
+ */
+export function observeTargetResolution(resolve, onChange) {
+    if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') {
+        return () => { };
+    }
+    let current = resolve();
+    let frame = 0;
+    const check = () => {
+        frame = 0;
+        const next = resolve();
+        if (next !== current) {
+            current = next;
+            onChange(next);
+        }
+    };
+    // Coalesce a burst of mutations into a single resolve on the next frame.
+    const schedule = () => {
+        if (frame || typeof requestAnimationFrame !== 'function') {
+            if (!frame)
+                check();
+            return;
+        }
+        frame = requestAnimationFrame(check);
+    };
+    const observer = new MutationObserver(schedule);
+    observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        // The DOM-fallback resolves via `[data-guide="…"]`, so a flipped attribute can change
+        // resolution just like an added/removed node — watch it too (and only it, to stay cheap).
+        attributeFilter: ['data-guide']
+    });
+    return () => {
+        observer.disconnect();
+        if (frame && typeof cancelAnimationFrame === 'function')
+            cancelAnimationFrame(frame);
+        // Reset so a mutation record that slipped through before disconnect (and would call
+        // schedule() once more) takes the coalesce early-return instead of queuing a stray frame.
+        frame = 0;
+    };
+}

package/dist/utils/optional-context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Optional context helper.
+ *
+ * Svelte's built-in `createContext<T>()` getter throws `missing_context`
+ * when no parent component set the value. That is correct for compound
+ * components (Tab, Accordion, …) where the sub-components must live
+ * inside the parent. For *optional* contexts (e.g. BlocksProvider,
+ * ButtonGroup wrapping individual Buttons, IconProvider) we want the
+ * getter to silently return `undefined` instead.
+ *
+ * This helper provides the same `[get, set]` shape as `createContext`
+ * but with a `() => T | undefined` getter that uses `hasContext` to
+ * differentiate between "no provider" (return undefined) and "provider
+ * deliberately set the value to undefined" (return undefined too —
+ * the consumer can't tell the difference, which is fine for opt-in
+ * APIs).
+ */
+export declare function createOptionalContext<T>(): readonly [
+    () => T | undefined,
+    (value: T | undefined) => T | undefined
+];