Onboarding Flow

<script lang="ts">
  import {
    Guide,
    GuideArticle,
    GuideBeacon,
    GuideController,
    GuideHint,
    GuideMarker,
    GuideMention,
    GuidePanel,
    GuideProvider
  } from '@urbicon-ui/blocks';
  import type { GuideTour } from '@urbicon-ui/blocks';

  const guide = new GuideController();
  let hintOpen = $state(false);

  const onboardingTour: GuideTour = {
    id: 'onboarding',
    // once: false — here, on the beacon and on the hint — keeps the docs demo
    // repeatable. Drop all three in your app: the default (true) shows each
    // once per user, remembered through the controller's storage adapter.
    once: false,
    steps: [
      {
        target: 'projects',
        title: 'Create your first project',
        body: 'Everything starts with a project: your space for tasks, files, and docs.'
      },
      {
        target: 'team',
        title: 'Invite your team',
        body: 'Bring teammates in so they can collaborate from day one.'
      },
      {
        // interactive keeps the spotlit tile clickable during this step
        target: 'api',
        title: 'Generate an API key',
        body: 'Automate anything once you are set up.',
        interactive: true
      }
    ],
    // Stand-ins for your analytics calls — the demo pipes the same events into
    // the log beside the workspace.
    onStep: (e) =>
      analytics.track('onboard_step', { step: e.index + 1, total: e.total, via: e.via }),
    onComplete: () => {
      analytics.track('onboard_complete');
      hintOpen = true; // reveal the "new feature" hint once onboarding is done
    },
    onSkip: (e) => analytics.track('onboard_skip', { droppedAt: e.index + 1 })
  };
</script>

<GuideProvider controller={guide}>
  <!-- Your app shell — the provider wraps it once, near the root. -->
  <header>
    <span>Acme Workspace</span>
    <!-- the ⓘ: opens the help panel at the matching article -->
    <GuideMarker for="projects" />
    <!-- the opt-in tour entry; hides itself once the tour is seen -->
    <GuideBeacon tour={onboardingTour} once={false} />
  </header>

  <!-- data-guide marks each target once; tour steps, the marker, the mentions
       and the hint all resolve to it -->
  <button data-guide="projects">New project</button>
  <button data-guide="team">Invite team</button>
  <button data-guide="api">API keys</button>

  <!-- non-modal help: the workspace stays usable behind the open panel -->
  <GuidePanel title="Workspace help">
    <GuideArticle id="projects" title="Projects & workspace">
      <p>
        A <GuideMention for="projects">project</GuideMention> groups your tasks, files, and
        docs. Start there, then add people from
        <GuideMention for="team">team settings</GuideMention>.
      </p>
      <p>
        Prefer automation? Generate an
        <GuideMention for="api">API key</GuideMention> and drive everything from the API.
      </p>
    </GuideArticle>
  </GuidePanel>

  <!-- waits for onComplete to raise hintOpen -->
  <GuideHint
    for="api"
    trigger="manual"
    open={hintOpen}
    once={false}
    title="New: API keys"
    onDismiss={() => (hintOpen = false)}
  >
    You can now generate scoped API keys for automation.
  </GuideHint>

  <!-- the tour renderer: mount once; renders nothing until a tour starts -->
  <Guide />
</GuideProvider>