@urbicon-ui/blocks 6.1.4

package/dist/components/Guide/GuideArticle.svelte

@@ -0,0 +1,52 @@
+<script lang="ts">
+  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getGuideContext } from './guide.context';
+  import { getGuidePanelContext } from './guide-panel.context';
+  import { guideArticleVariants } from './guide.variants';
+  import type { GuideArticleProps } from './index';
+
+  let {
+    id,
+    title,
+    children,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: GuideArticleProps = $props();
+
+  const guide = getGuideContext();
+  const panel = getGuidePanelContext();
+
+  // Register with the parent panel's list view. Runs regardless of whether this
+  // article is the active one, so every article shows up in the list. Cleans up
+  // on unmount and re-registers if id/title change.
+  $effect(() => {
+    return panel?.registerArticle(id, title);
+  });
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const slotClasses = $derived(
+    mergeSlotClasses(
+      blocksConfig?.defaults?.GuideArticle?.slotClasses,
+      resolvePresetSlotClasses(blocksConfig?.presets, 'GuideArticle', preset),
+      slotClassesProp
+    )
+  );
+  const styles = $derived(guideArticleVariants());
+
+  const isActive = $derived(guide?.activeArticle === id);
+</script>
+
+{#if isActive}
+  <article
+    class={unstyled
+      ? [slotClasses?.article, className].filter(Boolean).join(' ')
+      : styles.article({ class: [slotClasses?.article, className] })}
+    {...restProps}
+  >
+    {@render children?.()}
+  </article>
+{/if}

package/dist/components/Guide/GuideArticle.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { GuideArticleProps } from './index';
+declare const GuideArticle: import("svelte").Component<GuideArticleProps, {}, "">;
+type GuideArticle = ReturnType<typeof GuideArticle>;
+export default GuideArticle;

package/dist/components/Guide/GuideBeacon.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">
+  import { useBlocksI18n } from '../../i18n';
+  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getGuideContext } from './guide.context';
+  import { guideBeaconVariants } from './guide.variants';
+  import type { GuideBeaconProps } from './index';
+
+  const bt = useBlocksI18n();
+
+  let {
+    tour,
+    onActivate,
+    once = true,
+    size = 'md',
+    label,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: GuideBeaconProps = $props();
+
+  const guide = getGuideContext();
+
+  if (import.meta.env.DEV && !guide) {
+    console.warn(
+      '[Guide] <GuideBeacon> is used without a <GuideProvider> ancestor — it will not render.'
+    );
+  }
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const slotClasses = $derived(
+    mergeSlotClasses(
+      blocksConfig?.defaults?.GuideBeacon?.slotClasses,
+      resolvePresetSlotClasses(blocksConfig?.presets, 'GuideBeacon', preset),
+      slotClassesProp
+    )
+  );
+  const styles = $derived(guideBeaconVariants({ size }));
+
+  // Hide once the tour has been seen (gentle, never nags) and while it is running (the
+  // tour's own scrim takes over). Both reactive: `hasSeen` reads the controller's seen set,
+  // `activeTour` its tour state.
+  const seen = $derived(!!tour && once && !!guide && guide.hasSeen(tour.id));
+  const running = $derived(!!tour && guide?.activeTour?.id === tour.id);
+  const hidden = $derived(seen || running);
+
+  function activate() {
+    if (tour) guide?.startTour(tour);
+    onActivate?.();
+  }
+</script>
+
+{#if guide && !hidden}
+  <button
+    type="button"
+    class={[
+      'guide-beacon',
+      unstyled
+        ? [slotClasses?.beacon, className].filter(Boolean).join(' ')
+        : styles.beacon({ class: [slotClasses?.beacon, className] })
+    ]}
+    aria-label={label ?? bt('guide.startTour', {})}
+    onclick={activate}
+    {...restProps}
+  >
+    <span
+      class={[
+        'guide-beacon-ping',
+        unstyled ? (slotClasses?.ping ?? '') : styles.ping({ class: slotClasses?.ping })
+      ]}
+      aria-hidden="true"
+    ></span>
+    <span
+      class={unstyled ? (slotClasses?.dot ?? '') : styles.dot({ class: slotClasses?.dot })}
+      aria-hidden="true"
+    ></span>
+  </button>
+{/if}
+
+<style>
+  /* Waiting pulse — an expanding, fading ring behind the solid dot. Reduced-motion
+     hides the ring entirely, leaving a calm static dot. */
+  .guide-beacon-ping {
+    animation: guide-beacon-ping 1.6s cubic-bezier(0, 0, 0.2, 1) infinite;
+  }
+
+  @keyframes guide-beacon-ping {
+    0% {
+      transform: scale(1);
+      opacity: 0.7;
+    }
+    75%,
+    100% {
+      transform: scale(2.2);
+      opacity: 0;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .guide-beacon-ping {
+      animation: none;
+      opacity: 0;
+    }
+  }
+</style>

package/dist/components/Guide/GuideBeacon.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { GuideBeaconProps } from './index';
+declare const GuideBeacon: import("svelte").Component<GuideBeaconProps, {}, "">;
+type GuideBeacon = ReturnType<typeof GuideBeacon>;
+export default GuideBeacon;

package/dist/components/Guide/GuideHint.svelte

@@ -0,0 +1,270 @@
+<script lang="ts">
+  import { useBlocksI18n } from '../../i18n';
+  import { CloseIcon } from '../../icons';
+  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import {
+    computePosition,
+    autoUpdate,
+    flip,
+    shift,
+    offset,
+    arrow as floatingArrow
+  } from '../../utils/floating';
+  import { observeTargetResolution } from '../../utils/observe-target';
+  import { getGuideContext } from './guide.context';
+  import { guideHintVariants } from './guide.variants';
+  import type { GuideHintProps } from './index';
+
+  const bt = useBlocksI18n();
+
+  let {
+    for: topicId,
+    seenId: seenIdProp,
+    open = false,
+    trigger = 'mount',
+    once = true,
+    placement = 'bottom',
+    arrow = true,
+    title,
+    children,
+    onDismiss,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: GuideHintProps = $props();
+
+  const guide = getGuideContext();
+
+  if (import.meta.env.DEV && !guide) {
+    console.warn(
+      '[Guide] <GuideHint> is used without a <GuideProvider> ancestor — it will not render.'
+    );
+  }
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const slotClasses = $derived(
+    mergeSlotClasses(
+      blocksConfig?.defaults?.GuideHint?.slotClasses,
+      resolvePresetSlotClasses(blocksConfig?.presets, 'GuideHint', preset),
+      slotClassesProp
+    )
+  );
+  const styles = $derived(guideHintVariants());
+
+  const seenId = $derived(seenIdProp ?? topicId);
+
+  let hintEl = $state<HTMLElement>();
+  let arrowEl = $state<HTMLElement>();
+  let arrowStyle = $state('');
+  let dismissed = $state(false);
+  // Bumped when the anchor (`data-guide` element) appears (lazy render) or vanishes — the
+  // DOM-fallback `querySelector` is not otherwise reactive. The show/hide effect re-resolves.
+  let targetRevision = $state(0);
+
+  // `trigger: 'mount'` shows as soon as it mounts; `'manual'` waits for `open`
+  // (the consumer's on-route / on-condition strategy drives that boolean).
+  const requested = $derived(trigger === 'manual' ? open : true);
+  const alreadySeen = $derived(once && guide ? guide.hasSeen(seenId) : false);
+  // Top-layer discipline (§3.4): step aside while a foreign modal / tour is open.
+  const blocked = $derived((guide?.overlayDepth ?? 0) > 0);
+  const visible = $derived(!!guide && requested && !alreadySeen && !dismissed && !blocked);
+
+  // A manual re-open clears a prior in-session dismiss, so on-route / on-condition hints
+  // can re-surface (the `once` persistence still gates cross-mount reappearance). Also warn
+  // in DEV when `open` is set without `trigger="manual"`, where it is silently ignored.
+  $effect(() => {
+    if (trigger === 'manual') {
+      if (open) dismissed = false;
+    } else if (import.meta.env.DEV && open) {
+      console.warn('[Guide] <GuideHint open> is ignored unless trigger="manual".');
+    }
+  });
+
+  function dismiss() {
+    dismissed = true;
+    if (once) guide?.markSeen(seenId);
+    onDismiss?.();
+  }
+
+  function handleKeydown(e: KeyboardEvent) {
+    // Escape dismisses only while focus is inside the hint (non-modal courtesy).
+    if (e.key === 'Escape' && !e.defaultPrevented) {
+      e.preventDefault();
+      dismiss();
+    }
+  }
+
+  function updatePosition() {
+    const target = guide?.resolveTarget(topicId);
+    if (!target || !hintEl) return;
+    computePosition(target, hintEl, {
+      placement,
+      strategy: 'fixed',
+      middleware: [
+        offset(10),
+        flip(),
+        shift({ padding: 8 }),
+        ...(arrow && arrowEl ? [floatingArrow({ element: arrowEl, padding: 6 })] : [])
+      ]
+    })
+      .then(({ x, y, middlewareData, placement: resolved }) => {
+        if (!hintEl || !Number.isFinite(x) || !Number.isFinite(y)) return;
+        hintEl.style.left = `${x}px`;
+        hintEl.style.top = `${y}px`;
+
+        const arrowData = middlewareData.arrow as { x?: number; y?: number } | undefined;
+        if (arrowData && arrowEl) {
+          const staticSide =
+            { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }[
+              resolved.split('-')[0]
+            ] ?? 'bottom';
+          arrowStyle = `position:absolute;${arrowData.x != null ? `left:${arrowData.x}px;` : ''}${
+            arrowData.y != null ? `top:${arrowData.y}px;` : ''
+          }${staticSide}:-5px;`;
+        }
+      })
+      .catch((err) => console.warn('[GuideHint] computePosition failed', err));
+  }
+
+  // Single exit point (mirrors Tooltip): when visible + target resolvable, show the
+  // popover and attach autoUpdate; otherwise hide and tear down.
+  let cleanup: (() => void) | undefined;
+  $effect(() => {
+    if (!hintEl) return;
+    void targetRevision; // re-resolve when the anchor renders/vanishes (lazy / route swap)
+    const target = visible ? guide?.resolveTarget(topicId) : null;
+
+    if (!target) {
+      cleanup?.();
+      cleanup = undefined;
+      if (hintEl.matches(':popover-open')) {
+        try {
+          hintEl.hidePopover();
+        } catch (err) {
+          console.warn('[GuideHint] hidePopover failed', err);
+        }
+      }
+      return;
+    }
+
+    if (!hintEl.matches(':popover-open')) {
+      try {
+        hintEl.showPopover();
+      } catch (err) {
+        console.warn('[GuideHint] showPopover failed', err);
+      }
+    }
+    cleanup?.();
+    cleanup = autoUpdate(target, hintEl, updatePosition);
+
+    return () => {
+      cleanup?.();
+      cleanup = undefined;
+    };
+  });
+
+  // Lazy / vanishing anchor: while the hint wants to show, watch the DOM so an anchor that
+  // renders *after* the hint mounts gets picked up, and one that is removed hides the hint.
+  // `autoUpdate` (above) only tracks an existing element's box, not its existence.
+  $effect(() => {
+    if (!guide || !visible) return;
+    const controller = guide;
+    const id = topicId;
+    return observeTargetResolution(
+      () => controller.resolveTarget(id),
+      () => targetRevision++
+    );
+  });
+
+  // DEV resilience: a requested hint whose target can't be resolved is a silent
+  // no-op otherwise — warn so a wrong `for` id is noticed (mirrors the engine).
+  $effect(() => {
+    if (import.meta.env.DEV && guide && visible && !guide.resolveTarget(topicId)) {
+      console.warn(
+        `[Guide] <GuideHint for="${topicId}"> cannot anchor — no element with [data-guide="${topicId}"] (or registered target) found.`
+      );
+    }
+  });
+</script>
+
+{#if guide}
+  <div
+    bind:this={hintEl}
+    class={[
+      'guide-hint',
+      unstyled
+        ? [slotClasses?.hint, className].filter(Boolean).join(' ')
+        : styles.hint({ class: [slotClasses?.hint, className] })
+    ]}
+    role="status"
+    aria-live="polite"
+    aria-atomic="true"
+    onkeydown={handleKeydown}
+    {...restProps}
+    popover="manual"
+    style="position:fixed;margin:0;inset:auto;overflow:visible;"
+  >
+    {#if title}
+      <p
+        class={unstyled ? (slotClasses?.title ?? '') : styles.title({ class: slotClasses?.title })}
+      >
+        {title}
+      </p>
+    {/if}
+    <div class={unstyled ? (slotClasses?.body ?? '') : styles.body({ class: slotClasses?.body })}>
+      {@render children?.()}
+    </div>
+    <button
+      type="button"
+      class={unstyled
+        ? (slotClasses?.dismiss ?? '')
+        : styles.dismiss({ class: slotClasses?.dismiss })}
+      onclick={dismiss}
+      aria-label={bt('guide.dismiss', {})}
+    >
+      <CloseIcon class="h-4 w-4" />
+    </button>
+    {#if arrow}
+      <div
+        bind:this={arrowEl}
+        class={unstyled ? (slotClasses?.arrow ?? '') : styles.arrow({ class: slotClasses?.arrow })}
+        style={arrowStyle}
+      ></div>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  /* Entry/exit motion for the native popover. `allow-discrete` lets display/overlay
+     animate so the hint fades out too, not just in. Reduced-motion opts out. */
+  .guide-hint {
+    opacity: 0;
+    transform: translateY(4px);
+    transition:
+      opacity var(--blocks-duration-normal, 200ms) var(--blocks-ease-confident, ease),
+      transform var(--blocks-duration-normal, 200ms) var(--blocks-ease-confident, ease),
+      overlay var(--blocks-duration-normal, 200ms) allow-discrete,
+      display var(--blocks-duration-normal, 200ms) allow-discrete;
+  }
+
+  .guide-hint:popover-open {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  @starting-style {
+    .guide-hint:popover-open {
+      opacity: 0;
+      transform: translateY(4px);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .guide-hint {
+      transition: none;
+    }
+  }
+</style>

package/dist/components/Guide/GuideHint.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { GuideHintProps } from './index';
+declare const GuideHint: import("svelte").Component<GuideHintProps, {}, "">;
+type GuideHint = ReturnType<typeof GuideHint>;
+export default GuideHint;

package/dist/components/Guide/GuideMarker.svelte

@@ -0,0 +1,91 @@
+<script lang="ts">
+  import { useBlocksI18n } from '../../i18n';
+  import { InfoCircleIcon } from '../../icons';
+  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getGuideContext } from './guide.context';
+  import { guideMarkerVariants } from './guide.variants';
+  import type { GuideMarkerProps } from './index';
+
+  const bt = useBlocksI18n();
+
+  let {
+    for: topicId,
+    article,
+    direction,
+    label,
+    size = 'md',
+    children,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: GuideMarkerProps = $props();
+
+  const guide = getGuideContext();
+
+  if (import.meta.env.DEV && !guide) {
+    console.warn(
+      '[Guide] <GuideMarker> is used without a <GuideProvider> ancestor — it renders inert.'
+    );
+  }
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const slotClasses = $derived(
+    mergeSlotClasses(
+      blocksConfig?.defaults?.GuideMarker?.slotClasses,
+      resolvePresetSlotClasses(blocksConfig?.presets, 'GuideMarker', preset),
+      slotClassesProp
+    )
+  );
+  const styles = $derived(guideMarkerVariants({ size }));
+
+  // A Marker is the UI→Guide affordance; it is live unless the resolved direction
+  // is 'to-ui' only. With no `for` there is no topic to gate on (the prop wins).
+  const effectiveDirection = $derived(
+    topicId ? (guide?.resolveDirection(topicId, direction) ?? 'both') : (direction ?? 'both')
+  );
+  const active = $derived(!!guide && effectiveDirection !== 'to-ui');
+
+  // Which article to open: explicit prop > topic meta > the topic id itself.
+  const targetArticle = $derived(
+    article ?? (topicId ? guide?.getTopicMeta(topicId)?.article : undefined) ?? topicId
+  );
+  const topicLabel = $derived(topicId ? guide?.getTopicMeta(topicId)?.label : undefined);
+  const ariaLabel = $derived(
+    label ?? (topicLabel ? bt('guide.infoAbout', { label: topicLabel }) : bt('guide.info', {}))
+  );
+  // Reflects whether *this* marker's article is the one currently shown.
+  const expanded = $derived(
+    !!guide?.panelOpen && targetArticle !== undefined && guide?.activeArticle === targetArticle
+  );
+
+  function activate() {
+    if (!guide || !active) return;
+    guide.openPanel(targetArticle ?? undefined);
+  }
+</script>
+
+{#if active}
+  <button
+    type="button"
+    class={unstyled
+      ? [slotClasses?.marker, className].filter(Boolean).join(' ')
+      : styles.marker({ class: [slotClasses?.marker, className] })}
+    aria-controls={guide?.panelId ?? undefined}
+    aria-expanded={expanded}
+    aria-label={ariaLabel}
+    data-guide-marker
+    onclick={activate}
+    {...restProps}
+  >
+    {#if children}
+      {@render children()}
+    {:else}
+      <InfoCircleIcon
+        class={unstyled ? slotClasses?.icon : styles.icon({ class: slotClasses?.icon })}
+      />
+    {/if}
+  </button>
+{/if}

package/dist/components/Guide/GuideMarker.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { GuideMarkerProps } from './index';
+declare const GuideMarker: import("svelte").Component<GuideMarkerProps, {}, "">;
+type GuideMarker = ReturnType<typeof GuideMarker>;
+export default GuideMarker;

package/dist/components/Guide/GuideMention.svelte

@@ -0,0 +1,108 @@
+<script lang="ts">
+  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getGuideContext } from './guide.context';
+  import { guideMentionVariants } from './guide.variants';
+  import type { GuideMentionProps } from './index';
+
+  let {
+    for: topicId,
+    direction,
+    scroll = true,
+    children,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: GuideMentionProps = $props();
+
+  const guide = getGuideContext();
+
+  if (import.meta.env.DEV && !guide) {
+    console.warn(
+      '[Guide] <GuideMention> is used without a <GuideProvider> ancestor — it renders as plain text.'
+    );
+  }
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const slotClasses = $derived(
+    mergeSlotClasses(
+      blocksConfig?.defaults?.GuideMention?.slotClasses,
+      resolvePresetSlotClasses(blocksConfig?.presets, 'GuideMention', preset),
+      slotClassesProp
+    )
+  );
+  const styles = $derived(guideMentionVariants());
+
+  // A Mention is the Guide→UI affordance; it is interactive unless the resolved
+  // direction is 'to-guide' only (then it degrades to plain inline text).
+  // `resolveDirection` is total (never nullish), so the only live fallback is the
+  // no-provider branch.
+  const effectiveDirection = $derived(
+    guide ? guide.resolveDirection(topicId, direction) : (direction ?? 'both')
+  );
+  const interactive = $derived(!!guide && effectiveDirection !== 'to-guide');
+
+  $effect(() => {
+    if (import.meta.env.DEV && guide && effectiveDirection === 'to-guide') {
+      console.warn(
+        `[Guide] <GuideMention for="${topicId}"> points at a topic whose direction excludes Guide→UI ('to-guide') — it renders as plain text.`
+      );
+    }
+  });
+
+  // Tracks whether this specific mention set the current highlight, so the unmount
+  // teardown only releases a ring it actually owns (not one a sibling mention owns).
+  let owns = false;
+
+  // Hover *and* focus both highlight (keyboard parity, §4.2). Clearing is guarded on the
+  // topic id, so leaving this mention never wipes a *different* topic's highlight (e.g.
+  // when the pointer has already moved on to a mention for another target).
+  function highlight() {
+    owns = true;
+    guide?.highlight(topicId);
+  }
+  function clear() {
+    owns = false;
+    if (guide?.highlightedId === topicId) guide.clearHighlight();
+  }
+  function activate() {
+    owns = true;
+    guide?.highlight(topicId, { scroll });
+  }
+
+  // If this mention unmounts while it still owns the highlight — e.g. its article is
+  // switched away programmatically before mouseleave/blur fire — release the ring so it
+  // doesn't leak onto the (still-mounted) target element.
+  $effect(() => {
+    return () => {
+      if (owns && guide?.highlightedId === topicId) guide.clearHighlight();
+    };
+  });
+</script>
+
+{#if interactive}
+  <button
+    type="button"
+    class={unstyled
+      ? [slotClasses?.mention, className].filter(Boolean).join(' ')
+      : styles.mention({ class: [slotClasses?.mention, className] })}
+    data-guide-mention
+    onmouseenter={highlight}
+    onmouseleave={clear}
+    onfocus={highlight}
+    onblur={clear}
+    onclick={activate}
+    {...restProps}
+  >
+    {@render children?.()}
+  </button>
+{:else}
+  <span
+    class={[slotClasses?.mention, className].filter(Boolean).join(' ') || undefined}
+    {...restProps}
+  >
+    {@render children?.()}
+  </span>
+{/if}

package/dist/components/Guide/GuideMention.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { GuideMentionProps } from './index';
+declare const GuideMention: import("svelte").Component<GuideMentionProps, {}, "">;
+type GuideMention = ReturnType<typeof GuideMention>;
+export default GuideMention;