@urbicon-ui/blocks 6.1.4

package/dist/components/Guide/guide.variants.js

@@ -0,0 +1,204 @@
+import { tv } from '../../utils/variants';
+/**
+ * Styling for the non-modal `GuidePanel` (D1). Mirrors the `Drawer` look
+ * (surface-overlay, hairline border, lg shadow) but sits at `--z-sidebar`
+ * (1350) and slides in without a backdrop, so the app stays interactive
+ * behind it — required for the Mention→UI link (Direction B).
+ */
+export const guidePanelVariants = tv({
+    slots: {
+        panel: [
+            'fixed top-0 bottom-0 z-[var(--z-sidebar)] flex max-w-[100dvw] flex-col',
+            'bg-surface-overlay border-border-hairline shadow-[var(--blocks-shadow-lg)]',
+            'overflow-hidden'
+        ],
+        header: ['flex items-center gap-2 px-5 py-4', 'border-b border-border-hairline flex-shrink-0'],
+        backButton: [
+            'inline-flex items-center gap-1 -ml-1 rounded-md px-1.5 py-1',
+            'text-sm text-text-secondary hover:text-text-primary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-primary/50'
+        ],
+        title: ['flex-1 text-base font-semibold text-text-primary truncate'],
+        closeButton: [
+            'inline-flex items-center justify-center rounded-md p-1',
+            'text-text-secondary hover:bg-surface-hover hover:text-text-primary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-primary/50'
+        ],
+        body: ['flex-1 overflow-y-auto overscroll-contain px-5 py-4'],
+        list: ['flex flex-col gap-1'],
+        listItem: [
+            'flex w-full items-center gap-2 rounded-lg px-3 py-2.5 text-left text-sm transition-colors',
+            'text-text-secondary hover:bg-surface-hover hover:text-text-primary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-primary/50'
+        ],
+        footer: [
+            'flex items-center justify-end gap-3 px-5 py-3',
+            'border-t border-border-hairline flex-shrink-0'
+        ]
+    },
+    variants: {
+        placement: {
+            left: { panel: 'left-0 border-r rounded-r-xl' },
+            right: { panel: 'right-0 border-l rounded-l-xl' }
+        },
+        size: {
+            sm: { panel: 'w-72' },
+            md: { panel: 'w-96' },
+            lg: { panel: 'w-[32rem]' }
+        }
+    },
+    defaultVariants: {
+        placement: 'right',
+        size: 'md'
+    }
+});
+/**
+ * Styling for a `GuideArticle` body. Light prose defaults; consumers style
+ * their own content via the article snippet and `slotClasses`.
+ */
+export const guideArticleVariants = tv({
+    slots: {
+        article: [
+            'text-sm leading-relaxed text-text-secondary',
+            '[&_:where(p)]:my-2 [&_:where(p)]:first:mt-0'
+        ]
+    }
+});
+/**
+ * Styling for `GuideMarker` (Direction A, UI → Guide). A discreet, round "ⓘ"
+ * icon button — intentionally low-key (tertiary text, primary on
+ * hover/focus) so it reads as an affordance, not a status `Badge`.
+ */
+export const guideMarkerVariants = tv({
+    slots: {
+        marker: [
+            'inline-flex shrink-0 items-center justify-center align-middle rounded-full',
+            'text-text-tertiary transition-colors duration-[var(--blocks-duration-fast)]',
+            'hover:text-primary focus-visible:text-primary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-primary/50',
+            'cursor-help'
+        ],
+        icon: ['']
+    },
+    variants: {
+        size: {
+            sm: { icon: 'h-4 w-4' },
+            md: { icon: 'h-[1.15em] max-h-5 min-h-4 w-[1.15em] max-w-5 min-w-4' }
+        }
+    },
+    defaultVariants: {
+        size: 'md'
+    }
+});
+/**
+ * Styling for `GuideMention` (Direction B, Guide → UI). An inline, link-like
+ * reference inside article prose: primary text with a dotted underline that
+ * goes solid on hover/focus. Resets the native button box so it flows with the
+ * surrounding text and wraps naturally.
+ */
+export const guideMentionVariants = tv({
+    slots: {
+        mention: [
+            'm-0 inline cursor-pointer border-0 bg-transparent p-0 text-left font-medium text-primary',
+            'underline decoration-dotted decoration-1 underline-offset-2',
+            'transition-[text-decoration-color] duration-[var(--blocks-duration-fast)]',
+            'hover:decoration-solid focus-visible:decoration-solid',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-primary/50 focus-visible:rounded-[0.2em]'
+        ]
+    }
+});
+/**
+ * Styling for `GuideHint` — a small, non-blocking bubble anchored to a
+ * `data-guide` element via `floating.ts`, rendered in the native popover
+ * top-layer. `overflow-visible` keeps the arrow (which sits half outside the
+ * box) from being clipped by the UA `[popover]` default. Position + inset are
+ * set inline in the component, as for `Tooltip`.
+ */
+export const guideHintVariants = tv({
+    slots: {
+        hint: [
+            'z-[var(--z-popover)] m-0 max-w-xs overflow-visible',
+            'rounded-xl border border-border-hairline bg-surface-overlay py-3 pl-4 pr-9',
+            'text-sm text-text-secondary shadow-[var(--blocks-shadow-lg)]'
+        ],
+        title: ['mb-1 text-sm font-semibold text-text-primary'],
+        body: ['leading-relaxed [&_:where(p)]:my-1 [&_:where(p)]:first:mt-0 [&_:where(p)]:last:mb-0'],
+        dismiss: [
+            'absolute right-2 top-2 inline-flex items-center justify-center rounded-md p-1',
+            'text-text-tertiary transition-colors hover:bg-surface-hover hover:text-text-primary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-primary/50'
+        ],
+        // Rotated square in the bubble colour, tucked half behind the bubble (the
+        // component sets the static-side offset inline) for a seamless pointer.
+        // Borderless like Tooltip's arrow — a bordered tip would leak its inner edges
+        // over the bubble background and need per-placement border sides.
+        arrow: ['absolute h-2.5 w-2.5 rotate-45 bg-surface-overlay']
+    }
+});
+/**
+ * Styling for the guided `Guide` tour (Phase 6) — the one *subtractive* Guide
+ * surface (full-scrim spotlight, D5). The `scrim` SVG and `bubble` live inside a
+ * single native-popover container (top-layer), so both clear every app stacking
+ * context; the container's z is `--z-guide` (1550) as a non-top-layer fallback.
+ * The `bubble` mirrors `GuideHint` (surface-overlay, hairline border, lg shadow)
+ * but is a focusable `role="dialog"` with a step footer. Position + inset are set
+ * inline in the component, as for `GuideHint`/`Tooltip`.
+ */
+export const guideTourVariants = tv({
+    slots: {
+        // Full-viewport popover wrapper; the component overrides the UA `[popover]`
+        // box to inset:0 and sets `pointer-events:none` so only the painted scrim
+        // surround + the bubble capture clicks (the cut-out hole stays click-through).
+        container: ['z-[var(--z-guide)]'],
+        // The SVG that paints the dim around the spotlight hole. `fill` is the
+        // tunable `--blocks-guide-scrim` token; the hole is an even-odd cut-out.
+        scrim: ['fixed inset-0 h-full w-full'],
+        bubble: [
+            'z-[var(--z-guide)] m-0 w-[min(22rem,calc(100vw-2rem))] max-w-[calc(100vw-2rem)] overflow-visible',
+            'rounded-xl border border-border-hairline bg-surface-overlay p-4',
+            'text-sm text-text-secondary shadow-[var(--blocks-shadow-lg)]',
+            'focus-visible:outline-none'
+        ],
+        // Rotated square in the bubble colour (borderless, like GuideHint/Tooltip).
+        arrow: ['absolute h-2.5 w-2.5 rotate-45 bg-surface-overlay'],
+        title: ['mb-1 text-sm font-semibold text-text-primary'],
+        body: ['leading-relaxed [&_:where(p)]:my-1 [&_:where(p)]:first:mt-0 [&_:where(p)]:last:mb-0'],
+        progress: ['mt-3 flex items-center gap-2'],
+        dots: ['flex items-center gap-1.5'],
+        dot: ['h-1.5 w-1.5 rounded-full bg-border-strong/50 transition-all'],
+        // Layered additively on the active dot (the component toggles it per step).
+        dotActive: ['w-4 bg-primary'],
+        stepText: ['text-xs text-text-tertiary tabular-nums'],
+        footer: ['mt-4 flex items-center gap-2'],
+        // Pushes the prev/next pair to the trailing edge, skip to the leading edge.
+        spacer: ['flex-1']
+    }
+});
+/**
+ * Styling for `GuideBeacon` (Phase 6.3) — a waiting, pulsing hotspot that opens
+ * an opt-in tour. A real `<button>` wrapping an animated `ping` ring and a solid
+ * `dot`; the consumer positions it (inline, or absolutely over a feature corner).
+ * The pulse is pure CSS and halts under `prefers-reduced-motion` (static dot).
+ */
+export const guideBeaconVariants = tv({
+    slots: {
+        beacon: [
+            'relative inline-flex items-center justify-center rounded-full align-middle',
+            'cursor-pointer',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-primary/50'
+        ],
+        // Expanding/fading ring behind the dot (animation lives in the component <style>).
+        ping: ['absolute inline-flex h-full w-full rounded-full bg-primary/70'],
+        // Solid center dot.
+        dot: ['relative inline-flex rounded-full bg-primary']
+    },
+    variants: {
+        size: {
+            sm: { beacon: 'h-2.5 w-2.5', dot: 'h-2.5 w-2.5' },
+            md: { beacon: 'h-3.5 w-3.5', dot: 'h-3.5 w-3.5' }
+        }
+    },
+    defaultVariants: {
+        size: 'md'
+    }
+});

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

@@ -0,0 +1,409 @@
+import type { Snippet } from 'svelte';
+import type { GuideController, GuideDirection, GuideStorageAdapter, GuideTour, Placement } from '../../utils';
+import type { GuideBeaconVariants, GuideMarkerVariants, GuidePanelVariants } from './guide.variants';
+/**
+ * @description Root provider for the Guide help system. Instantiates a `GuideController`
+ * and shares it via context with all Guide surfaces (Panel, Marker, Mention, Hint, Tour).
+ * Place once near the app root. The context is optional — a surface used without a provider
+ * renders inert rather than throwing.
+ * @tag overlay
+ * @tag feedback
+ * @related GuidePanel
+ * @related GuideMarker
+ * @stability beta
+ * @standalone
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { GuideProvider, GuideController } from '@urbicon-ui/blocks';
+ *   const guide = new GuideController();
+ * </script>
+ *
+ * <GuideProvider controller={guide}>
+ *   <App />
+ * </GuideProvider>
+ *
+ * <button onclick={() => guide.startTour(welcomeTour)}>Take the tour</button>
+ * ```
+ */
+export interface GuideProviderProps {
+    /** Persistence adapter for "seen" state (tours/hints). @default localStorage-backed adapter */
+    storage?: GuideStorageAdapter;
+    /**
+     * Supply a pre-created `GuideController` for programmatic access from outside the provider
+     * (start tours, open the panel, query `hasSeen`). When omitted, the provider creates one
+     * internally and shares it via context. When supplied, `storage` is ignored.
+     */
+    controller?: GuideController;
+    /** App subtree wired to the Guide context. */
+    children: Snippet;
+}
+/**
+ * @description Non-modal help panel for the Guide system. Slides in (default from the right)
+ * without a backdrop or focus trap, so the app stays interactive behind it — this is what lets
+ * a `GuideMention` highlight a UI element while the panel is open (D1). Visibility is driven by
+ * the controller (`openPanel`/`closePanel`), not a local prop. Place `GuideArticle` children
+ * inside: the panel shows a list of them, or the active article's content with a back button.
+ * @tag overlay
+ * @tag navigation
+ * @related GuideProvider
+ * @related GuideArticle
+ * @related GuideMarker
+ * @stability beta
+ * @standalone
+ *
+ * @example
+ * ```svelte
+ * <GuidePanel title="Help">
+ *   <GuideArticle id="saving" title="Saving your work">
+ *     <p>Use the Save button to persist your changes.</p>
+ *   </GuideArticle>
+ * </GuidePanel>
+ * ```
+ */
+export interface GuidePanelProps {
+    /**
+     * Stable DOM id for the panel root. `GuideMarker`s reference it via `aria-controls`.
+     * @default auto-generated (`guide-panel-<id>`)
+     */
+    id?: string;
+    /** Side the panel docks to. @default 'right' */
+    placement?: GuidePanelVariants['placement'];
+    /** Panel width. @default 'md' */
+    size?: GuidePanelVariants['size'];
+    /** Heading shown when no article is open. @default i18n `guide.openHelp` */
+    title?: string;
+    /** Close the panel when Escape is pressed. @default true */
+    closeOnEscape?: boolean;
+    /** Optional footer content. */
+    footer?: Snippet;
+    /** `GuideArticle` children and any custom content. */
+    children?: Snippet;
+    /** Additional classes on the panel root. */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<'panel' | 'header' | 'backButton' | 'title' | 'closeButton' | 'body' | 'list' | 'listItem' | 'footer', string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ GuidePanel: {...} }}>`. */
+    preset?: string;
+}
+/**
+ * @description A single help article inside a `GuidePanel`. Registers itself in the panel's
+ * list (by `title`) and renders its content only when it is the active article
+ * (`controller.activeArticle === id`). Use `GuideMention` inside to link back to UI elements.
+ * @tag display
+ * @related GuidePanel
+ * @related GuideMention
+ * @stability beta
+ * @standalone
+ *
+ * @example
+ * ```svelte
+ * <GuideArticle id="seats" title="Seats & billing">
+ *   <p>Each <GuideMention for="seat-count">seat</GuideMention> is one team member.</p>
+ * </GuideArticle>
+ * ```
+ */
+export interface GuideArticleProps {
+    /** Unique article id — referenced by `GuideMarker` and `openPanel(id)`. */
+    id: string;
+    /** Title shown in the panel list and header. */
+    title: string;
+    /** Article body. */
+    children?: Snippet;
+    /** Additional classes on the article root. */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<'article', string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ GuideArticle: {...} }}>`. */
+    preset?: string;
+}
+/**
+ * @description Direction A of the bidirectional link (UI → Guide): a discreet "ⓘ" trigger
+ * that sits on a UI element and opens the `GuidePanel` at the matching article. A real
+ * `<button>` with `aria-controls`/`aria-expanded` — deliberately *not* a status `Badge`
+ * (which is a non-interactive label, not a trigger). Renders inert without a `GuideProvider`,
+ * or when the topic's direction excludes UI→Guide (`'to-ui'`).
+ * @tag action
+ * @tag feedback
+ * @related GuidePanel
+ * @related GuideMention
+ * @related GuideProvider
+ * @stability beta
+ * @standalone
+ *
+ * @example
+ * ```svelte
+ * <h3>Billing <GuideMarker for="billing" article="billing-help" /></h3>
+ * ```
+ */
+export interface GuideMarkerProps {
+    /**
+     * `data-guide` topic id this marker explains. Resolves the article (from topic meta) and
+     * the link direction. Optional (unlike `GuideMention.for`) because `article` can stand
+     * alone — supply one of the two. With neither, the marker opens the panel index.
+     */
+    for?: string;
+    /** Article to open in the panel. Overrides the topic meta's `article`; falls back to `for`. */
+    article?: string;
+    /**
+     * Override the topic's link direction. The marker is live unless this resolves to `'to-ui'`.
+     * @default the topic's `direction`, or `'both'`
+     */
+    direction?: GuideDirection;
+    /**
+     * Accessible label for the icon button.
+     * @default i18n `guide.infoAbout` (with the topic's label) or `guide.info`
+     */
+    label?: string;
+    /** Icon size. @default 'md' */
+    size?: GuideMarkerVariants['size'];
+    /** Custom trigger content, replacing the default "ⓘ" icon. */
+    children?: Snippet;
+    /** Additional classes on the marker button. */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<'marker' | 'icon', string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ GuideMarker: {...} }}>`. */
+    preset?: string;
+}
+/**
+ * @description Direction B of the bidirectional link (Guide → UI): an inline reference inside a
+ * `GuideArticle` that highlights the matching UI element on hover *and* focus (keyboard parity).
+ * Additive `outline` ring, no scrim, no layout shift (D5); clicking also scrolls the element into
+ * view (reduced-motion-aware). A real `<button>`; degrades to plain inline text without a
+ * `GuideProvider` or when the topic's direction excludes Guide→UI (`'to-guide'`).
+ * @tag navigation
+ * @related GuideArticle
+ * @related GuideMarker
+ * @related GuidePanel
+ * @stability beta
+ * @standalone
+ *
+ * @example
+ * ```svelte
+ * <p>Click the <GuideMention for="save-button">Save button</GuideMention> to persist.</p>
+ * ```
+ */
+export interface GuideMentionProps {
+    /**
+     * `data-guide` id of the UI element to highlight. Required (unlike `GuideMarker.for`):
+     * a mention with no target has nothing to highlight.
+     */
+    for: string;
+    /**
+     * Override the topic's link direction. The mention is interactive unless this resolves to
+     * `'to-guide'`.
+     * @default the topic's `direction`, or `'both'`
+     */
+    direction?: GuideDirection;
+    /** Scroll the target into view on click (reduced-motion-aware). @default true */
+    scroll?: boolean;
+    /** The mention text. */
+    children?: Snippet;
+    /** Additional classes on the mention. */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<'mention', string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ GuideMention: {...} }}>`. */
+    preset?: string;
+}
+/**
+ * @description A contextual, non-blocking hint anchored to a `data-guide` element via
+ * `floating.ts` (flip/shift/arrow), rendered in the native popover top-layer. Waits at the
+ * right element rather than interrupting: shows on mount (or when `open` for `trigger="manual"`),
+ * persists "seen" so it appears once (`once`), and steps aside while a foreign modal or guided
+ * tour is open. Dismissable; announces itself via `aria-live`. Renders inert without a provider.
+ * @tag overlay
+ * @tag feedback
+ * @related GuideProvider
+ * @related GuideMarker
+ * @related GuidePanel
+ * @stability beta
+ * @standalone
+ *
+ * @example
+ * ```svelte
+ * <button data-guide="export">Export</button>
+ *
+ * <GuideHint for="export" title="New: scheduled exports">
+ *   You can now export on a schedule from here.
+ * </GuideHint>
+ * ```
+ */
+export interface GuideHintProps {
+    /** `data-guide` id of the element to anchor to. Required — a hint with no anchor has nothing to point at. */
+    for: string;
+    /**
+     * Persistence key for the "seen once" state, decoupled from the anchor (this is *not* a DOM id —
+     * the popover gets none). Override only to track two hints on one element independently, or to keep
+     * a stable key across a renamed anchor.
+     * @default the `for` id
+     */
+    seenId?: string;
+    /**
+     * Manual visibility for `trigger="manual"` (the on-route / on-condition strategy). Ignored for
+     * `trigger="mount"`. Re-raising it to `true` after a dismiss re-surfaces the hint (subject to `once`).
+     * @default false
+     */
+    open?: boolean;
+    /**
+     * When the hint may appear: `'mount'` shows it as soon as it mounts; `'manual'` waits for
+     * `open` to become `true` (the consumer's route/condition logic).
+     * @default 'mount'
+     */
+    trigger?: 'mount' | 'manual';
+    /**
+     * When dismissed, persist a "seen" flag (via the controller's StorageAdapter) so the hint
+     * does not reappear on later mounts. Mirrors the tour's "mark seen on end" rule — a hint
+     * shown but never dismissed may show again. Set `false` to always show.
+     * @default true
+     */
+    once?: boolean;
+    /** Preferred placement relative to the target. @default 'bottom' */
+    placement?: Placement;
+    /** Render the pointer arrow. @default true */
+    arrow?: boolean;
+    /** Optional bold heading above the body. */
+    title?: string;
+    /** Hint body. */
+    children?: Snippet;
+    /** Called when the hint is dismissed (close button or Escape). */
+    onDismiss?: () => void;
+    /** Additional classes on the hint root. */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<'hint' | 'title' | 'body' | 'dismiss' | 'arrow', string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ GuideHint: {...} }}>`. */
+    preset?: string;
+}
+/**
+ * @description The guided-tour renderer — the deliberately opt-in, intrusive Guide surface
+ * (§6, low priority). Renders the active tour the controller drives (`startTour`/`next`/`prev`/
+ * `skip`/`finish`): a spotlight that dims everything but a cut-out hole over the current step's
+ * target (the one *subtractive* Guide treatment, D5) plus an anchored bubble with the step
+ * title, body, dot progress, and Back / Next / Skip controls. Mount once inside `GuideProvider`;
+ * it renders nothing until a tour starts. Top-layer (native popover), so it clears app stacking
+ * contexts; it steps aside (pauses) when a foreign modal stacks above it. A step with no `target`
+ * renders centered over a full scrim. Renders inert without a `GuideProvider`.
+ * @tag overlay
+ * @tag feedback
+ * @related GuideProvider
+ * @related GuideBeacon
+ * @related GuideHint
+ * @stability beta
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { GuideProvider, Guide, GuideController } from '@urbicon-ui/blocks';
+ *   const guide = new GuideController();
+ *   const tour = {
+ *     id: 'welcome',
+ *     steps: [
+ *       { target: 'save-button', title: 'Save', body: 'Persist your changes here.' },
+ *       { target: 'filter-control', title: 'Filter', body: 'Narrow the list.', interactive: true }
+ *     ]
+ *   };
+ * </script>
+ *
+ * <GuideProvider controller={guide}>
+ *   <Guide />
+ *   <button onclick={() => guide.startTour(tour)}>Take the tour</button>
+ * </GuideProvider>
+ * ```
+ */
+export interface GuideProps {
+    /**
+     * Padding in px between the step target and the spotlight hole edge. Also frames the
+     * additive highlight ring the engine paints on the target. @default 8
+     */
+    padding?: number;
+    /**
+     * Spotlight hole corner radius in px. When omitted, it follows the target's own
+     * border-radius (plus `padding`), clamped to the hole size. Set a number to force it.
+     */
+    radius?: number;
+    /** Render the bubble's pointer arrow on anchored steps. @default true */
+    arrow?: boolean;
+    /** Preferred bubble placement when a step omits its own `placement`. @default 'bottom' */
+    placement?: Placement;
+    /** Additional classes on the bubble. */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<'container' | 'scrim' | 'bubble' | 'arrow' | 'title' | 'body' | 'progress' | 'dots' | 'dot' | 'dotActive' | 'stepText' | 'footer' | 'spacer' | 'skip' | 'prev' | 'next', string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ Guide: {...} }}>`. */
+    preset?: string;
+}
+/**
+ * @description A waiting, pulsing hotspot that invites the user into an opt-in guided tour (§6.3)
+ * — the gentlest tour entry point, the opposite of an auto-starting tour. A real `<button>` the
+ * consumer positions (inline, or absolutely over a feature corner); on activation it starts the
+ * given `tour` and/or calls `onActivate`. Hides itself once that tour has been seen. The pulse
+ * halts under `prefers-reduced-motion` (static dot). Renders inert without a `GuideProvider`.
+ * @tag feedback
+ * @tag action
+ * @related Guide
+ * @related GuideProvider
+ * @related GuideHint
+ * @stability beta
+ * @standalone
+ *
+ * @example
+ * ```svelte
+ * <span class="relative">
+ *   New feature
+ *   <GuideBeacon class="absolute -right-3 -top-1" {tour} />
+ * </span>
+ * ```
+ */
+export interface GuideBeaconProps {
+    /**
+     * The tour to start when the beacon is activated. When set, the beacon also hides itself once
+     * the tour has been seen (subject to `once`). Omit to drive everything from `onActivate`.
+     */
+    tour?: GuideTour;
+    /** Called on activation (click / Enter / Space), after `tour` is started when both are set. */
+    onActivate?: () => void;
+    /**
+     * Hide the beacon once its `tour` has been seen (and while that tour is running). Needs `tour`.
+     * @default true
+     */
+    once?: boolean;
+    /** Visual size of the hotspot. @default 'md' */
+    size?: GuideBeaconVariants['size'];
+    /**
+     * Accessible label for the button.
+     * @default i18n `guide.startTour`
+     */
+    label?: string;
+    /** Additional classes on the beacon button (use for absolute positioning over a target). */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<'beacon' | 'ping' | 'dot', string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ GuideBeacon: {...} }}>`. */
+    preset?: string;
+}
+export { default as Guide } from './Guide.svelte';
+export { default as GuideArticle } from './GuideArticle.svelte';
+export { default as GuideBeacon } from './GuideBeacon.svelte';
+export { default as GuideHint } from './GuideHint.svelte';
+export { default as GuideMarker } from './GuideMarker.svelte';
+export { default as GuideMention } from './GuideMention.svelte';
+export { default as GuidePanel } from './GuidePanel.svelte';
+export { default as GuideProvider } from './GuideProvider.svelte';
+export { type GuideArticleVariants, type GuideBeaconVariants, type GuideHintVariants, type GuideMarkerVariants, type GuideMentionVariants, type GuidePanelVariants, type GuideTourVariants, guideArticleVariants, guideBeaconVariants, guideHintVariants, guideMarkerVariants, guideMentionVariants, guidePanelVariants, guideTourVariants } from './guide.variants';

package/dist/components/Guide/index.js

@@ -0,0 +1,12 @@
+export { default as Guide } from './Guide.svelte';
+export { default as GuideArticle } from './GuideArticle.svelte';
+export { default as GuideBeacon } from './GuideBeacon.svelte';
+export { default as GuideHint } from './GuideHint.svelte';
+export { default as GuideMarker } from './GuideMarker.svelte';
+export { default as GuideMention } from './GuideMention.svelte';
+export { default as GuidePanel } from './GuidePanel.svelte';
+export { default as GuideProvider } from './GuideProvider.svelte';
+export { guideArticleVariants, guideBeaconVariants, guideHintVariants, guideMarkerVariants, guideMentionVariants, guidePanelVariants, guideTourVariants } from './guide.variants';
+// Note: getGuideContext/setGuideContext are intentionally NOT re-exported here.
+// They are an internal wiring seam — surfaces import them directly from
+// './guide.context' (mirrors Tab/Icon, which keep their context helpers private).