create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/ui-kit/src/ui/tour/index.tsx

@@ -0,0 +1,210 @@
+// Tour — guided spotlight tour (antd Tour lite, P1): mask khoét lỗ quanh target
+// (getBoundingClientRect + padding, vẽ SVG path fill-rule evenodd), panel step
+// (title/description + prev/next/finish). Không target → panel căn giữa màn
+// hình (bước intro/outro). ESC / click mask = đóng; scroll/resize tự re-measure.
+// A11y (pattern Modal): role=dialog + useFocusTrap — mở → focus panel, Tab vòng
+// trong, đóng → trả focus về trigger. Motion: bp-fade-in mask + bp-zoom-in panel.
+// Depth contract 2026-10-19: panel nổi bậc L3 — hairline border + ele-3 (inset
+// highlight) chồng shadow-pop + wash sheen + easing --ease-smooth.
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import { createPortal } from 'react-dom';
+import { Button } from '../button/index.js';
+import { Icon } from '../icons/index.js';
+import { useFocusTrap } from '../../hooks/useFocusTrap.js';
+
+/** 1 bước tour — bỏ `target` → panel căn giữa (giới thiệu/kết thúc kiểu antd). */
+export interface TourStep {
+  /** Element cần spotlight: CSS selector | element | ref. */
+  target?: string | HTMLElement | RefObject<HTMLElement | null>;
+  title?: ReactNode;
+  description?: ReactNode;
+}
+
+export interface TourProps {
+  /** Danh sách bước (thứ tự hiển thị). */
+  steps: TourStep[];
+  /** Mở/tắt tour. */
+  open: boolean;
+  /** Đóng (ESC, click mask, nút ×, nút Finish bước cuối). */
+  onClose: () => void;
+  /** Bước hiện tại (controlled). Bỏ → tour tự quản internal. */
+  current?: number;
+  /** Gọi khi prev/next đổi bước (dùng cùng `current` controlled). */
+  onCurrentChange?: (index: number) => void;
+  className?: string;
+}
+
+/** Đệm quanh element được spotlight. */
+const SPOTLIGHT_PAD = 8;
+/** Góc bo lỗ spotlight (khớp radius token controls). */
+const SPOTLIGHT_RADIUS = 8;
+/** Bề rộng panel — hằng số để clamp ngang không cần đo. */
+const PANEL_WIDTH = 320;
+/** Ước lượng cao panel cho heuristic trên/dưới. */
+const PANEL_EST_HEIGHT = 220;
+const GAP = 12;
+
+type Rect = { top: number; left: number; width: number; height: number; bottom: number };
+
+function resolveTarget(target: TourStep['target']): HTMLElement | null {
+  if (!target) return null;
+  if (typeof target === 'string') return document.querySelector<HTMLElement>(target);
+  if (target instanceof HTMLElement) return target;
+  return target.current;
+}
+
+/** Lỗ khoét: rect target + padding, clamp >= 0 (jsdom/element 0×0 vẫn vẽ được). */
+function holeRect(rect: Rect): Rect {
+  const top = Math.max(0, rect.top - SPOTLIGHT_PAD);
+  const height = Math.max(0, rect.height + SPOTLIGHT_PAD * 2);
+  return {
+    left: Math.max(0, rect.left - SPOTLIGHT_PAD),
+    top,
+    width: Math.max(0, rect.width + SPOTLIGHT_PAD * 2),
+    height,
+    bottom: top + height,
+  };
+}
+
+/** SVG path: chữ nhật full + lỗ bo góc (evenodd → lỗ trong suốt). */
+function maskPath(view: { w: number; h: number }, hole: Rect | null): string {
+  let d = `M0 0 H${view.w} V${view.h} H0 Z`;
+  if (hole && hole.width > 0 && hole.height > 0) {
+    const r = Math.min(SPOTLIGHT_RADIUS, hole.width / 2, hole.height / 2);
+    const { left: x, top: y, width: w, height: h } = hole;
+    d += ` M${x + r} ${y} h${w - 2 * r} a${r} ${r} 0 0 1 ${r} ${r} v${h - 2 * r}`
+      + ` a${r} ${r} 0 0 1 -${r} ${r} h${-(w - 2 * r)} a${r} ${r} 0 0 1 -${r} -${r}`
+      + ` v${-(h - 2 * r)} a${r} ${r} 0 0 1 ${r} -${r} Z`;
+  }
+  return d;
+}
+
+export function Tour({ steps, open, onClose, current, onCurrentChange, className }: TourProps) {
+  const [inner, setInner] = useState(0);
+  const [view, setView] = useState({ w: 0, h: 0 });
+  const [rect, setRect] = useState<Rect | null>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  const index = Math.max(0, Math.min(current ?? inner, steps.length - 1));
+
+  // Mở lại tour → internal current về 0 (controlled `current` do consumer quyết)
+  useEffect(() => {
+    if (open) setInner(0);
+  }, [open]);
+
+  // ESC đóng (chỉ khi open — như Modal)
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [open, onClose]);
+
+  useFocusTrap(panelRef, open);
+
+  // Kích thước viewport + rect target — re-measure khi scroll (capture bắt cả
+  // scroll container trong trang) / resize trong lúc tour mở.
+  useLayoutEffect(() => {
+    if (!open) return;
+    const measure = () => {
+      setView({ w: window.innerWidth, h: window.innerHeight });
+      const el = resolveTarget(steps[index]?.target);
+      setRect(el ? el.getBoundingClientRect() : null);
+    };
+    measure();
+    document.addEventListener('scroll', measure, true);
+    window.addEventListener('resize', measure);
+    return () => {
+      document.removeEventListener('scroll', measure, true);
+      window.removeEventListener('resize', measure);
+    };
+  }, [open, index, steps]);
+
+  if (!open || steps.length === 0) return null;
+
+  const go = (next: number) => {
+    const clamped = Math.max(0, Math.min(next, steps.length - 1));
+    if (current === undefined) setInner(clamped);
+    onCurrentChange?.(clamped);
+  };
+
+  // Panel: ưu tiên dưới target, thiếu chỗ → trên, hẹp cả 2 → dính mép trên.
+  let panelStyle: CSSProperties;
+  if (rect) {
+    const cx = rect.left + rect.width / 2;
+    const left = Math.max(8, Math.min(cx - PANEL_WIDTH / 2, view.w - PANEL_WIDTH - 8));
+    panelStyle =
+      rect.bottom + GAP + PANEL_EST_HEIGHT < view.h
+        ? { left, top: rect.bottom + GAP }
+        : { left, bottom: Math.max(8, view.h - rect.top + GAP) };
+  } else {
+    panelStyle = { left: '50%', top: '50%', transform: 'translate(-50%, -50%)' };
+  }
+
+  const step = steps[index];
+  const isLast = index === steps.length - 1;
+  const slot = className ? ` ${className}` : '';
+
+  return createPortal(
+    <div
+      data-testid="tour-overlay"
+      onClick={onClose}
+      className={`fixed inset-0 z-[var(--z-modal)] animate-[bp-fade-in_var(--motion-base)_var(--ease-smooth)]${slot}`}
+    >
+      <svg
+        data-testid="tour-spotlight"
+        width={view.w}
+        height={view.h}
+        className="pointer-events-none absolute inset-0"
+        aria-hidden="true"
+      >
+        <path d={maskPath(view, rect ? holeRect(rect) : null)} fill="var(--mask)" fillRule="evenodd" />
+      </svg>
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={typeof step?.title === 'string' ? step.title : 'Product tour'}
+        tabIndex={-1}
+        style={panelStyle}
+        onClick={(e) => e.stopPropagation()}
+        className="absolute w-[320px] rounded-xl border border-line bg-s2 p-4 shadow-[var(--shadow-pop),var(--ele-3)] [background-image:var(--wash)] outline-none animate-[bp-zoom-in_var(--motion-base)_var(--ease-smooth)]"
+      >
+        <div className="mb-1 flex items-start justify-between gap-2">
+          <span className="pt-0.5 font-mono text-meta text-ink3">
+            {index + 1} / {steps.length}
+          </span>
+          <button
+            type="button"
+            aria-label="Close tour"
+            className="cursor-pointer rounded-1 border-none bg-transparent p-1 text-base leading-3 text-ink3 hover:text-ink focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+            onClick={onClose}
+          >
+            <Icon name="times" size={14} />
+          </button>
+        </div>
+        {step?.title && <div className="text-h3 font-semibold text-ink">{step.title}</div>}
+        {step?.description && <div className="mt-1 text-body text-ink2">{step.description}</div>}
+        <div className="mt-4 flex items-center gap-2">
+          <Button disabled={index === 0} onClick={() => go(index - 1)}>
+            Prev
+          </Button>
+          <Button type="primary" onClick={() => (isLast ? onClose() : go(index + 1))}>
+            {isLast ? 'Finish' : 'Next'}
+          </Button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/stack-template/app/ui-kit/src/ui/tour/tour.stories.tsx

@@ -0,0 +1,153 @@
+// Tour stories — spotlight mask + step panel over a mock settings page.
+// Steps target real DOM nodes by selector (#tour-*), so the spotlight lands
+// with true rects in the browser. Open via the Start button per story.
+import { useState, type ReactNode } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from '../button/index.js';
+import { Switch } from '../switch/index.js';
+import { Tour } from './index';
+
+const meta = { title: 'Feedback/Tour', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Mock page the tour walks through — targets are the ids on these rows. */
+function SettingsCard() {
+  const [dark, setDark] = useState(false);
+  return (
+    <div className="w-[360px] rounded-xl border border-line bg-s1 p-5">
+      <h3 className="m-0 text-h3 font-semibold text-ink">Workspace settings</h3>
+      <div id="tour-profile" className="mt-4 flex items-center justify-between rounded-lg bg-s2 px-3 py-2.5">
+        <div>
+          <div className="text-body font-medium text-ink">Display name</div>
+          <div className="text-meta text-ink3">Shown on tasks and comments</div>
+        </div>
+      </div>
+      <div id="tour-appearance" className="mt-3 flex items-center justify-between rounded-lg bg-s2 px-3 py-2.5">
+        <div>
+          <div className="text-body font-medium text-ink">Dark mode</div>
+          <div className="text-meta text-ink3">Tokens cascade automatically</div>
+        </div>
+        <Switch checked={dark} onChange={setDark} aria-label="Dark mode" />
+      </div>
+      <div className="mt-4 flex justify-end">
+        <Button type="primary" size="small" id="tour-save">
+          Save changes
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+const SETTINGS_STEPS = [
+  {
+    target: '#tour-profile',
+    title: 'Your identity',
+    description: 'Set the display name teammates see on tasks and comments.',
+  },
+  {
+    target: '#tour-appearance',
+    title: 'Pick a theme',
+    description: 'Dark mode recolors the whole workspace — no per-component work needed.',
+  },
+  {
+    target: '#tour-save',
+    title: 'Save when done',
+    description: 'Changes apply after you save. Click anywhere on the dimmed area to end the tour.',
+  },
+];
+
+/** Basic — 3-step guided tour over a mock settings page. */
+export const Basic: Story = {
+  name: 'Basic — spotlight steps over a settings page',
+  render: () => <BasicTourDemo />,
+};
+
+/** Controlled — current + onCurrentChange owned by the consumer. */
+export const Controlled: Story = {
+  name: 'Controlled — current state owned by the app',
+  render: () => <ControlledTourDemo />,
+};
+
+/** CenteredIntro — steps without a target render a centered panel (intro/outro). */
+export const CenteredIntro: Story = {
+  name: 'Centered — targetless intro/outro steps',
+  render: () => <CenteredTourDemo />,
+};
+
+/** DarkTheme — tour panel + spotlight on the dark canvas. */
+export const DarkTheme: Story = {
+  name: 'Dark theme',
+  render: () => <DarkTourDemo />,
+};
+
+function TourFrame({ children, open, onStart }: { children: ReactNode; open: boolean; onStart: () => void }) {
+  return (
+    <div className="flex flex-col items-start gap-4">
+      <div className="flex items-center gap-3">
+        <Button type="primary" onClick={onStart} disabled={open}>
+          Start tour
+        </Button>
+        <span className="text-meta text-ink3">ESC or click the dimmed area exits; Prev/Next walk the steps.</span>
+      </div>
+      <SettingsCard />
+      {children}
+    </div>
+  );
+}
+
+function BasicTourDemo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <TourFrame open={open} onStart={() => setOpen(true)}>
+      <Tour steps={SETTINGS_STEPS} open={open} onClose={() => setOpen(false)} />
+    </TourFrame>
+  );
+}
+
+function ControlledTourDemo() {
+  const [open, setOpen] = useState(false);
+  const [current, setCurrent] = useState(0);
+  return (
+    <TourFrame open={open} onStart={() => { setCurrent(0); setOpen(true); }}>
+      <div className="font-mono text-meta text-ink3">
+        current: <strong className="text-ink">{current}</strong>
+      </div>
+      <Tour
+        steps={SETTINGS_STEPS}
+        open={open}
+        current={current}
+        onCurrentChange={setCurrent}
+        onClose={() => setOpen(false)}
+      />
+    </TourFrame>
+  );
+}
+
+function CenteredTourDemo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <TourFrame open={open} onStart={() => setOpen(true)}>
+      <Tour
+        steps={[
+          { title: 'Welcome to the workspace', description: 'A 2-stop quick look — centered panels bookend a targeted step.' },
+          ...SETTINGS_STEPS.slice(0, 1),
+          { title: "You're all set", description: 'Replay any time from the Start button above.' },
+        ]}
+        open={open}
+        onClose={() => setOpen(false)}
+      />
+    </TourFrame>
+  );
+}
+
+function DarkTourDemo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <div data-bp-theme="dark" className="rounded-xl bg-canvas p-4">
+      <TourFrame open={open} onStart={() => setOpen(true)}>
+        <Tour steps={SETTINGS_STEPS} open={open} onClose={() => setOpen(false)} />
+      </TourFrame>
+    </div>
+  );
+}

package/stack-template/app/ui-kit/src/ui/tour/tour.test.tsx

@@ -0,0 +1,131 @@
+// Tour tests — panel render + điều hướng prev/next/finish + ESC/mask đóng +
+// spotlight đo theo getBoundingClientRect + focus trap (pattern Modal tests).
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useState } from 'react';
+import { Tour } from './index.js';
+
+afterEach(cleanup);
+
+const STEPS = [
+  { title: 'Welcome', description: 'Intro step, no target' },
+  { title: 'Profile', description: 'Your profile lives here', target: '#demo-card' },
+  { title: 'Done', description: 'Last step' },
+];
+
+describe('Tour', () => {
+  it('open + step không target → panel căn giữa, render title/description + counter', () => {
+    render(<Tour steps={STEPS} open onClose={() => {}} />);
+    expect(screen.getByText('Welcome')).toBeInTheDocument();
+    expect(screen.getByText('Intro step, no target')).toBeInTheDocument();
+    expect(screen.getByText('1 / 3')).toBeInTheDocument();
+    expect(screen.getByRole('dialog')).toHaveAttribute('aria-modal', 'true');
+  });
+
+  it('closed → không render gì', () => {
+    render(<Tour steps={STEPS} open={false} onClose={() => {}} />);
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(document.querySelector('[data-testid="tour-overlay"]')).toBeNull();
+  });
+
+  it('uncontrolled: Prev disabled bước đầu; Next đổi step; bước cuối → Finish', async () => {
+    const user = userEvent.setup();
+    render(<Tour steps={STEPS} open onClose={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Prev' })).toBeDisabled();
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+    expect(screen.getByText('Your profile lives here')).toBeInTheDocument();
+    expect(screen.getByText('2 / 3')).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Prev' }));
+    expect(screen.getByText('1 / 3')).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+    expect(screen.getByRole('button', { name: 'Finish' })).toBeInTheDocument();
+  });
+
+  it('Finish ở bước cuối → onClose', async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    render(<Tour steps={STEPS} open current={2} onClose={onClose} />);
+    await user.click(screen.getByRole('button', { name: 'Finish' }));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('ESC → onClose', async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    render(<Tour steps={STEPS} open onClose={onClose} />);
+    await user.keyboard('{Escape}');
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('click mask → onClose; click panel không đóng', async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    render(<Tour steps={STEPS} open onClose={onClose} />);
+    await user.click(screen.getByTestId('tour-spotlight'));
+    expect(onClose).toHaveBeenCalledTimes(1);
+    await user.click(screen.getByRole('dialog'));
+    expect(onClose).toHaveBeenCalledTimes(1); // vẫn 1 — panel stopPropagation
+  });
+
+  it('controlled: current + onCurrentChange — Next báo index kế (không tự internal)', async () => {
+    const user = userEvent.setup();
+    const onCurrentChange = vi.fn();
+    render(<Tour steps={STEPS} open current={0} onCurrentChange={onCurrentChange} onClose={() => {}} />);
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+    expect(onCurrentChange).toHaveBeenCalledWith(1);
+    expect(screen.getByText('1 / 3')).toBeInTheDocument(); // controlled — không tự nhảy
+  });
+
+  it('target selector → spotlight khoét lỗ theo rect + padding (8px)', () => {
+    const spy = vi
+      .spyOn(Element.prototype, 'getBoundingClientRect')
+      .mockReturnValue({ top: 100, left: 100, width: 200, height: 80, x: 100, y: 100, right: 300, bottom: 180, toJSON: () => ({}) } as DOMRect);
+    try {
+      render(
+        <div id="demo-card" style={{ position: 'absolute', top: 100, left: 100, width: 200, height: 80 }} />,
+      );
+      render(<Tour steps={STEPS} open current={1} onClose={() => {}} />);
+      const path = document.querySelector('[data-testid="tour-spotlight"] path');
+      expect(path).not.toBeNull();
+      // lỗ = rect + pad 8 → góc bo bắt đầu (92+8, 92) = (100, 92); w/h rời ràng = 200/80
+      expect(path?.getAttribute('d')).toContain('M100 92 h200');
+      expect(path?.getAttribute('d')).toContain('v80'); // h = 80 + 16 − 2×r(8)
+      expect(path?.getAttribute('fill')).toBe('var(--mask)');
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('focus trap: mở → focus panel, Tab vòng trong, ESC đóng trả focus về trigger', async () => {
+    const user = userEvent.setup();
+    function Harness() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <button type="button" onClick={() => setOpen(true)}>Start tour</button>
+          <Tour steps={STEPS} open={open} onClose={() => setOpen(false)} />
+        </>
+      );
+    }
+    render(<Harness />);
+    const trigger = screen.getByRole('button', { name: 'Start tour' });
+    await user.click(trigger);
+    const dialog = screen.getByRole('dialog');
+    // panel có focusable (×, Prev, Next) → trap focus phần tử đầu tiên TRONG panel
+    expect(dialog).toContainElement(document.activeElement as HTMLElement);
+    await user.tab();
+    expect(dialog).toContainElement(document.activeElement as HTMLElement); // không thoát khỏi panel
+    await user.keyboard('{Escape}');
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(trigger).toHaveFocus();
+  });
+
+  it('fireEvent click overlay (không qua panel) → onClose', () => {
+    const onClose = vi.fn();
+    render(<Tour steps={STEPS} open onClose={onClose} />);
+    fireEvent.click(screen.getByTestId('tour-overlay'));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});