feat: guided tour component

apps/www/src/components/demo/demo.tsx

@@ -58,6 +58,7 @@ import {
 import ChipInputDemo from '../inputfield-chip-demo';
 import LinearMenuDemo from '../linear-dropdown-demo';
 import PopoverColorPicker from '../popover-color-picker';
+import TourDemo from '../tour-demo';
 import DemoPlayground from './demo-playground';
 import DemoPreview from './demo-preview';
 import { DemoProps } from './types';
@@ -90,6 +91,7 @@ export default function Demo(props: DemoProps) {
       DataTableSelectionDemo,
       LinearMenuDemo,
       PopoverColorPicker,
+      TourDemo,
       Info,
       X,
       Home,

apps/www/src/components/playground/index.ts

@@ -55,3 +55,4 @@ export * from './text-examples';
 export * from './toast-examples';
 export * from './toggle-examples';
 export * from './tooltip-examples';
+export * from './tour-examples';

apps/www/src/components/playground/tour-examples.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import { BellIcon, GearIcon, HomeIcon } from '@radix-ui/react-icons';
+import {
+  Button,
+  Flex,
+  IconButton,
+  Text,
+  Tour,
+  type TourActions,
+  type TourStep
+} from '@raystack/apsara';
+import { useRef } from 'react';
+import PlaygroundLayout from './playground-layout';
+
+const steps: TourStep[] = [
+  {
+    id: 'welcome',
+    title: 'Welcome',
+    content: 'A centered, detached step to open the tour.'
+  },
+  {
+    id: 'home',
+    target: '[data-pg-tour="home"]',
+    title: 'Home',
+    content: 'Anchored to the home button, popover below.',
+    side: 'bottom'
+  },
+  {
+    id: 'settings',
+    target: '[data-pg-tour="settings"]',
+    title: 'Settings',
+    content: 'Anchored below with a pill spotlight.',
+    side: 'bottom',
+    spotlightRadius: 999,
+    spotlightPadding: 6
+  },
+  {
+    id: 'alerts',
+    target: '[data-pg-tour="alerts"]',
+    title: 'Alerts',
+    content: 'Last step — Finish closes the tour.',
+    side: 'left'
+  }
+];
+
+export function TourExamples() {
+  const actionsRef = useRef<TourActions>(null);
+
+  return (
+    <PlaygroundLayout title='Tour'>
+      <Flex direction='column' gap={7}>
+        <Flex gap={3} align='center'>
+          <IconButton data-pg-tour='home' size={4} aria-label='Home'>
+            <HomeIcon />
+          </IconButton>
+          <IconButton data-pg-tour='settings' size={4} aria-label='Settings'>
+            <GearIcon />
+          </IconButton>
+          <IconButton data-pg-tour='alerts' size={4} aria-label='Alerts'>
+            <BellIcon />
+          </IconButton>
+        </Flex>
+
+        <Flex direction='column' gap={3} align='start'>
+          <Text>Default card, four steps:</Text>
+          <Button onClick={() => actionsRef.current?.start()}>
+            Start tour
+          </Button>
+        </Flex>
+
+        <Tour steps={steps} actionsRef={actionsRef} />
+      </Flex>
+    </PlaygroundLayout>
+  );
+}

apps/www/src/components/tour-demo.tsx

@@ -0,0 +1,95 @@
+'use client';
+
+import { BarChartIcon, BellIcon, RocketIcon } from '@radix-ui/react-icons';
+import {
+  Button,
+  Flex,
+  IconButton,
+  Search,
+  Text,
+  Tour,
+  type TourActions,
+  type TourStep
+} from '@raystack/apsara';
+import { useRef } from 'react';
+
+const panel: React.CSSProperties = {
+  padding: 'var(--rs-space-5)',
+  border: '1px solid var(--rs-color-border-base-primary)',
+  borderRadius: 'var(--rs-radius-3)',
+  backgroundColor: 'var(--rs-color-background-base-primary)'
+};
+
+const steps: TourStep[] = [
+  {
+    id: 'welcome',
+    title: 'Welcome aboard',
+    content:
+      'A quick tour of the workspace. Use Next to move on, or press Escape to leave any time.'
+  },
+  {
+    id: 'search',
+    target: '[data-tour="search"]',
+    title: 'Search anything',
+    content: 'Jump to any resource from here. Try typing while the tour runs.',
+    side: 'bottom',
+    spotlightClicks: true
+  },
+  {
+    id: 'analytics',
+    target: '[data-tour="analytics"]',
+    title: 'Track usage',
+    content: 'Analytics break down usage across your whole workspace.',
+    side: 'bottom'
+  },
+  {
+    id: 'notifications',
+    target: '[data-tour="notifications"]',
+    title: 'Stay in the loop',
+    content: 'Unread alerts land on the bell. That is the whole tour!',
+    side: 'left',
+    spotlightRadius: 999,
+    spotlightPadding: 6
+  }
+];
+
+export default function TourDemo() {
+  const actionsRef = useRef<TourActions>(null);
+
+  return (
+    <Flex direction='column' gap={5} style={{ width: '100%', maxWidth: 640 }}>
+      <Flex justify='between' align='center' gap={3} style={panel}>
+        <div data-tour='search' style={{ flex: 1, maxWidth: 280 }}>
+          <Search size='small' placeholder='Search…' />
+        </div>
+        <Flex gap={2} align='center'>
+          <IconButton data-tour='analytics' size={4} aria-label='Analytics'>
+            <BarChartIcon />
+          </IconButton>
+          <IconButton
+            data-tour='notifications'
+            size={4}
+            aria-label='Notifications'
+          >
+            <BellIcon />
+          </IconButton>
+        </Flex>
+      </Flex>
+
+      <Flex direction='column' gap={3} align='start' style={panel}>
+        <Text size='regular' weight='medium'>
+          Guided tour
+        </Text>
+        <Text size='small' variant='secondary'>
+          Four steps: a centered welcome, then the search box, analytics, and
+          notifications — each anchored and spotlighted.
+        </Text>
+        <Button onClick={() => actionsRef.current?.start()}>
+          <RocketIcon /> Start tour
+        </Button>
+      </Flex>
+
+      <Tour steps={steps} actionsRef={actionsRef} />
+    </Flex>
+  );
+}

apps/www/src/content/docs/components/tour/demo.ts

@@ -0,0 +1,6 @@
+'use client';
+
+export const preview = {
+  type: 'code',
+  code: `<TourDemo />`
+};