Guidebeta

<script lang="ts">
  import { GuideProvider, Guide, GuideController } from '@urbicon-ui/blocks';

  // Create the controller yourself for programmatic access (start tours, open the panel).
  const guide = new GuideController();
</script>

<GuideProvider controller={guide}>
  <!-- Any element becomes a guide target with a data-guide id -->
  <button data-guide="save-button">Save</button>

  <!-- Mount the tour renderer once; it stays invisible until a tour starts -->
  <Guide />
</GuideProvider>

<button onclick={() => guide.startTour(welcomeTour)}>Take the tour</button>

<GuideProvider controller={groupsGuide}>
  <div
    class="border-border-subtle bg-surface-elevated flex w-full max-w-md items-center justify-between gap-3 rounded-2xl border px-4 py-3"
  >
    <span class="text-text-primary text-sm font-semibold">Atlas — Projects</span>
    <Button
      variant="outlined"
      intent="neutral"
      size="sm"
      onclick={() => groupsGuide.openPanel()}
    >
      Open help
    </Button>
  </div>
  <GuidePanel title="Help">
    <GuideArticle id="grp-first-project" title="Create a project" group="Getting started">
      <p>A project collects everything one team ships: tasks, docs, and milestones.</p>
    </GuideArticle>
    <GuideArticle id="grp-invite" title="Invite your team" group="Getting started">
      <p>Invite teammates by email — they join with access to every shared project.</p>
    </GuideArticle>
    <GuideArticle id="grp-plans" title="Plans & pricing" group="Billing">
      <p>The Free plan covers three projects. Pro removes the limit.</p>
    </GuideArticle>
    <GuideArticle id="grp-seats" title="Seats" group="Billing">
      <p>You are billed per occupied seat, prorated monthly.</p>
    </GuideArticle>
    <GuideArticle id="grp-shortcuts" title="Keyboard shortcuts">
      <p>Press <strong>?</strong> anywhere to see the full shortcut map.</p>
    </GuideArticle>
  </GuidePanel>
</GuideProvider>

<GuideProvider controller={searchGuide}>
  <div
    class="border-border-subtle bg-surface-elevated flex w-full max-w-md items-center justify-between gap-3 rounded-2xl border px-4 py-3"
  >
    <span class="text-text-primary text-sm font-semibold">Atlas — Settings</span>
    <Button
      variant="outlined"
      intent="neutral"
      size="sm"
      onclick={() => searchGuide.openPanel()}
    >
      Open help
    </Button>
  </div>
  <GuidePanel title="Help" searchable>
    <GuideArticle id="srch-profile" title="Profile & avatar" group="Account">
      <p>Your name and avatar appear on comments and shared views.</p>
    </GuideArticle>
    <GuideArticle id="srch-security" title="Password & security" group="Account">
      <p>Change your password or add a passkey for phishing-resistant sign-in.</p>
    </GuideArticle>
    <GuideArticle id="srch-notifications" title="Notification preferences" group="Account">
      <p>Choose which events reach you by email, push, or in-app.</p>
    </GuideArticle>
    <GuideArticle id="srch-import" title="Import from CSV" group="Data">
      <p>Upload a CSV and map its columns to project fields.</p>
    </GuideArticle>
    <GuideArticle id="srch-export" title="Export your data" group="Data">
      <p>Download the current view as CSV or JSON at any time.</p>
    </GuideArticle>
    <GuideArticle id="srch-scheduled" title="Scheduled exports" group="Data">
      <p>Deliver a recurring export to email or webhook on a schedule.</p>
    </GuideArticle>
  </GuidePanel>
</GuideProvider>

<GuideProvider controller={refGuide}>
  <div
    class="border-border-subtle bg-surface-elevated flex w-full max-w-md items-center justify-between gap-3 rounded-2xl border px-4 py-3"
  >
    <span class="text-text-primary text-sm font-semibold">Trip to Lisbon — €412.80</span>
    <Button
      variant="outlined"
      intent="neutral"
      size="sm"
      onclick={() => refGuide.openPanel('ref-pot')}
    >
      How is this split?
    </Button>
  </div>
  <GuidePanel title="Help">
    <GuideArticle id="ref-pot" title="The cost pot">
      <p>
        Every expense lands in the trip's shared pot. At the end, the pot is settled with as few
        transfers as possible, based on each expense's
        <GuideRef article="ref-splitting">splitting method</GuideRef>.
      </p>
    </GuideArticle>
    <GuideArticle id="ref-splitting" title="Splitting methods">
      <p>
        Split equally, by shares, or by exact amounts. The method applies per expense and feeds
        the <GuideRef article="ref-pot">cost pot</GuideRef>'s final balance.
      </p>
    </GuideArticle>
  </GuidePanel>
</GuideProvider>

<GuideProvider controller={hintGuide}>
  <div class="flex flex-wrap items-center gap-3">
    <button
      data-guide="ex-export"
      class="border-border-default text-text-secondary rounded-lg border px-3 py-2 text-sm"
    >
      Export
    </button>
    <Button
      variant="outlined"
      intent="neutral"
      size="sm"
      onclick={() => (hintOpen = !hintOpen)}
    >
      {hintOpen ? 'Hide' : 'Show'} hint
    </Button>
  </div>
  <GuideHint
    for="ex-export"
    trigger="manual"
    open={hintOpen}
    once={false}
    title="New: scheduled exports"
    onDismiss={() => (hintOpen = false)}
  >
    You can now export on a recurring schedule from here.
  </GuideHint>
</GuideProvider>

const welcomeTour: GuideTour = {
  id: 'welcome',
  steps: [
    { target: 'save-button', title: 'Save', body: 'Persist your changes here.' },
    { target: 'filter-control', title: 'Filter', body: 'Narrow the list.', interactive: true }
  ],
  // Fired on start (via: 'start') and every next/prev — the step-by-step funnel.
  onStep: ({ index, total, via }) =>
    analytics.track('tour_step', { tour: 'welcome', step: index + 1, total, via }),
  // Fired when the user finishes the whole tour.
  onComplete: () => analytics.track('tour_complete', { tour: 'welcome' }),
  // Fired when the user bails — event.index is where they dropped off.
  onSkip: ({ index }) => analytics.track('tour_skip', { tour: 'welcome', droppedAt: index })
};

<!-- 1. Declarative attribute — framework-agnostic, works on elements you don't render -->
<button data-guide="save-button">Save</button>

<!-- 2. Programmatic attachment — carries metadata (label, article, direction) -->
<button {@attach guide.target('save-button', {
  label: 'Save button',
  article: 'saving',          // which panel article the marker opens
  direction: 'both'           // 'to-guide' | 'to-ui' | 'both' — gates Marker vs Mention
})}>Save</button>

/* Tune globally via the design tokens (defaults shown — override to taste) */
:root {
  --blocks-guide-scrim: oklch(0 0 0 / 0.5);            /* the tour's dimming backdrop */
  --blocks-guide-highlight-ring: var(--color-primary); /* the additive Mention→UI ring */
}

/* Or override per instance */
<GuidePanel slotClasses={{ panel: 'w-[28rem]', header: 'bg-surface-subtle' }} />
<GuideHint slotClasses={{ hint: 'max-w-sm' }} />