create-wakii-stack 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,118 @@
+// Alert — FILLED (mặc định): nền đặc token --alert-*-filled, chữ trắng, icon trắng, KHÔNG viền.
+// variant="outlined" giữ kiểu cũ (tint bg + border + colored text) cho ai cần.
+// WCAG AA: filled dùng màu đậm đủ contrast với trắng (≥4.5:1 trừ warning ~3.5 large-ok).
+import type { CSSProperties, ReactNode } from 'react';
+import { Icon, type IconName } from '../icons/index.js';
+
+export type AlertType = 'success' | 'info' | 'warning' | 'error';
+export type AlertVariant = 'filled' | 'outlined';
+
+const FILLED: Record<AlertType, { bg: string; icon: IconName }> = {
+  success: { bg: 'var(--alert-success-filled)', icon: 'check' },
+  info: { bg: 'var(--alert-info-filled)', icon: 'info-circle' },
+  warning: { bg: 'var(--alert-warning-filled)', icon: 'exclamation-triangle' },
+  error: { bg: 'var(--alert-error-filled)', icon: 'times' },
+};
+
+const OUTLINED: Record<AlertType, { bg: string; border: string; icon: IconName; iconCls: string }> = {
+  success: { bg: 'var(--alert-success-bg)', border: 'var(--alert-success-border)', icon: 'check', iconCls: 'text-st-done' },
+  info: { bg: 'var(--alert-info-bg)', border: 'var(--alert-info-border)', icon: 'info-circle', iconCls: 'text-accent' },
+  warning: { bg: 'var(--alert-warning-bg)', border: 'var(--alert-warning-border)', icon: 'exclamation-triangle', iconCls: 'text-st-doing' },
+  error: { bg: 'var(--alert-error-bg)', border: 'var(--alert-error-border)', icon: 'times', iconCls: 'text-st-fail' },
+};
+
+/** antd v5-style sub-part slot classes — merge AFTER defaults (consumer appends). */
+export interface AlertClassNames {
+  /** Root container (role=alert). */
+  wrapper?: string;
+  /** Leading status glyph. */
+  icon?: string;
+  /** Primary message line. */
+  message?: string;
+  /** Secondary description line. */
+  description?: string;
+  /** Close × button. */
+  closeButton?: string;
+}
+
+export interface AlertProps {
+  /** Loại trạng thái — quyết định màu nền filled / tint outlined. */
+  type?: AlertType;
+  /** Dòng chính. */
+  message: ReactNode;
+  /** Dòng phụ chi tiết. */
+  description?: ReactNode;
+  /** filled (mặc định) / outlined. */
+  variant?: AlertVariant;
+  /** Hiện nút × đóng. */
+  closable?: boolean;
+  onClose?: () => void;
+  className?: string;
+  style?: CSSProperties;
+  /** Slot classes kiểu antd v5 (SÓNG-3) — merge sau class mặc định. */
+  classNames?: AlertClassNames;
+}
+
+// slot helper — ghép class consumer vào sau mặc định (undefined → rỗng)
+const slot = (c?: string) => (c ? ` ${c}` : '');
+
+export function Alert({
+  type = 'info',
+  message,
+  description,
+  variant = 'filled',
+  closable = false,
+  onClose,
+  className,
+  style,
+  classNames,
+}: AlertProps) {
+  const fill = FILLED[type];
+  const outline = OUTLINED[type];
+  const isFilled = variant === 'filled';
+
+  const containerStyle: CSSProperties = isFilled
+    ? { background: fill.bg }
+    : { background: outline.bg, borderColor: outline.border };
+
+  const iconNode = isFilled ? fill.icon : outline.icon;
+  const iconCls = isFilled ? 'text-white' : outline.iconCls;
+
+  const base = 'flex items-start gap-2 rounded-lg px-3 py-2 text-body';
+  const borderCls = isFilled ? '' : ' border';
+
+  return (
+    <div
+      role="alert"
+      className={`${base} ${borderCls} ${iconCls}${className ? ` ${className}` : ''}${slot(classNames?.wrapper)}`}
+      style={{ ...containerStyle, ...style }}
+    >
+      <span aria-hidden="true" className={`shrink-0 text-label leading-5 ${iconCls}${slot(classNames?.icon)}`}>
+        <Icon name={iconNode} size={14} />
+      </span>
+      <div className="min-w-0 flex-1">
+        <div className={`leading-5 ${isFilled ? 'text-white' : ''}${slot(classNames?.message)}`}
+          style={isFilled ? undefined : { color: 'var(--ink)' }}>
+          {message}
+        </div>
+        {description && (
+          <div className={`mt-1 text-label ${isFilled ? 'text-white/80' : 'text-ink2'}${slot(classNames?.description)}`}>
+            {description}
+          </div>
+        )}
+      </div>
+      {closable && (
+        <button
+          type="button"
+          aria-label="Đóng"
+          className={`shrink-0 cursor-pointer border-none bg-transparent text-base leading-4 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 rounded-1 active:opacity-70${slot(classNames?.closeButton)} ${
+            isFilled ? 'text-white/80 hover:text-white' : 'text-ink3 hover:text-ink'
+          }`}
+          onClick={onClose}
+        >
+          <Icon name="times" size={14} />
+        </button>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,96 @@
+// Parity matrix antd→tokens: docs/parity-matrix.md
+// Anchor stories — scroll the preview page: active dot follows the section in view.
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Anchor, type AnchorLinkItem } from './index';
+
+/** Anchor navigation — jump links synced with scroll position. */
+const meta = { title: 'Navigation/Anchor', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function Section({ id, title }: { id: string; title: string }) {
+  return (
+    <section id={id} className="rounded-xl border border-line bg-s2 p-6">
+      <h3 className="m-0 mb-2 text-h2 font-semibold text-ink">{title}</h3>
+      <p className="m-0 text-body text-ink2">
+        Scroll this preview — the anchor dot on the left turns accent when this section reaches the
+        top of the viewport.
+      </p>
+      <div className="h-64" />
+    </section>
+  );
+}
+
+const BASIC_ITEMS: AnchorLinkItem[] = [
+  { key: 'intro', href: '#anchor-sb-intro', title: 'Introduction' },
+  { key: 'usage', href: '#anchor-sb-usage', title: 'Usage' },
+  { key: 'api', href: '#anchor-sb-api', title: 'API reference' },
+];
+
+export const Basic: Story = {
+  name: 'Basic — scroll-spy + smooth click',
+  render: () => (
+    <div className="flex gap-8">
+      <Anchor items={BASIC_ITEMS} />
+      <div className="flex flex-1 flex-col gap-6">
+        <Section id="anchor-sb-intro" title="Introduction" />
+        <Section id="anchor-sb-usage" title="Usage" />
+        <Section id="anchor-sb-api" title="API reference" />
+      </div>
+    </div>
+  ),
+};
+
+export const WithAffix: Story = {
+  name: 'With affix — anchor stays pinned while scrolling',
+  render: () => (
+    <div className="flex gap-8">
+      <Anchor items={BASIC_ITEMS} affix offsetTop={16} />
+      <div className="flex flex-1 flex-col gap-6">
+        <Section id="anchor-sb-intro" title="Introduction" />
+        <Section id="anchor-sb-usage" title="Usage" />
+        <Section id="anchor-sb-api" title="API reference" />
+      </div>
+    </div>
+  ),
+};
+
+export const Nested: Story = {
+  name: 'Nested — children indent with their own rail',
+  render: () => (
+    <div className="flex gap-8">
+      <Anchor
+        items={[
+          {
+            key: 'guide',
+            href: '#anchor-sb-intro',
+            title: 'Guide',
+            children: [
+              { key: 'install', href: '#anchor-sb-usage', title: 'Installation' },
+              { key: 'advanced', href: '#anchor-sb-api', title: 'Advanced usage' },
+            ],
+          },
+        ]}
+      />
+      <div className="flex flex-1 flex-col gap-6">
+        <Section id="anchor-sb-intro" title="Guide" />
+        <Section id="anchor-sb-usage" title="Installation" />
+        <Section id="anchor-sb-api" title="Advanced usage" />
+      </div>
+    </div>
+  ),
+};
+
+export const CustomOffset: Story = {
+  name: 'Custom offsetTop — activates 96px before the section top',
+  render: () => (
+    <div className="flex gap-8">
+      <Anchor items={BASIC_ITEMS} offsetTop={96} onClick={(_e, link) => console.log('anchor:', link.href)} />
+      <div className="flex flex-1 flex-col gap-6">
+        <Section id="anchor-sb-intro" title="Introduction" />
+        <Section id="anchor-sb-usage" title="Usage" />
+        <Section id="anchor-sb-api" title="API reference" />
+      </div>
+    </div>
+  ),
+};

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

@@ -0,0 +1,191 @@
+// Anchor tests — render items (kể cả nested), scroll-spy active, click scroll mượt
+// (preventDefault + scrollTo smooth), onClick callback, offsetTop threshold,
+// affix sticky, getContainer element. Rect của section stub được để mô phỏng cuộn.
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Anchor, type AnchorLinkItem } from './index.js';
+
+/** Mount 1 section thật vào body với top viewport điều khiển được qua map. */
+function mountSection(id: string, tops: Map<string, number>) {
+  const el = document.createElement('div');
+  el.id = id;
+  document.body.appendChild(el);
+  vi.spyOn(el, 'getBoundingClientRect').mockImplementation(
+    () =>
+      ({
+        top: tops.get(id) ?? 0,
+        bottom: (tops.get(id) ?? 0) + 100,
+        left: 0,
+        right: 100,
+        width: 100,
+        height: 100,
+        x: 0,
+        y: tops.get(id) ?? 0,
+        toJSON: () => ({}),
+      }) as DOMRect,
+  );
+  return el;
+}
+
+function fireScroll(target: Window | HTMLElement = window) {
+  act(() => {
+    target.dispatchEvent(new Event('scroll'));
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  document.body.innerHTML = '';
+  vi.restoreAllMocks();
+});
+
+const ITEMS: AnchorLinkItem[] = [
+  { key: 'intro', href: '#anchor-intro', title: 'Introduction' },
+  { key: 'usage', href: '#anchor-usage', title: 'Usage' },
+  { key: 'api', href: '#anchor-api', title: 'API reference' },
+];
+
+describe('Anchor', () => {
+  it('render items → link đúng title + href trong nav landmark', () => {
+    const tops = new Map<string, number>([['anchor-intro', 400], ['anchor-usage', 800], ['anchor-api', 1200]]);
+    mountSection('anchor-intro', tops);
+    mountSection('anchor-usage', tops);
+    mountSection('anchor-api', tops);
+    const { getByRole, getByText } = render(<Anchor items={ITEMS} />);
+
+    const nav = getByRole('navigation', { name: 'Table of contents' });
+    expect(nav).toBeInTheDocument();
+    for (const item of ITEMS) {
+      const link = getByText(item.title as string);
+      expect(link).toHaveAttribute('href', item.href);
+    }
+    // Chưa section nào chạm offsetTop → không link nào active
+    expect(document.querySelector('[aria-current]')).toBeNull();
+  });
+
+  it('nested children → link con render lồng trong cha', () => {
+    const tops = new Map<string, number>([['anchor-guide', 400], ['anchor-install', 900]]);
+    mountSection('anchor-guide', tops);
+    mountSection('anchor-install', tops);
+    const { getByText } = render(
+      <Anchor
+        items={[
+          {
+            key: 'guide',
+            href: '#anchor-guide',
+            title: 'Guide',
+            children: [{ key: 'install', href: '#anchor-install', title: 'Installation' }],
+          },
+        ]}
+      />,
+    );
+    expect(getByText('Guide')).toHaveAttribute('href', '#anchor-guide');
+    expect(getByText('Installation')).toHaveAttribute('href', '#anchor-install');
+  });
+
+  it('scroll-spy: section chạm offsetTop → aria-current; cuộn tiếp → chuyển link sau', () => {
+    const tops = new Map<string, number>([['anchor-intro', 400], ['anchor-usage', 800], ['anchor-api', 1200]]);
+    mountSection('anchor-intro', tops);
+    mountSection('anchor-usage', tops);
+    mountSection('anchor-api', tops);
+    const { getByText } = render(<Anchor items={ITEMS} />);
+
+    tops.set('anchor-intro', 0); // cuộn tới section 1
+    fireScroll();
+    expect(getByText('Introduction')).toHaveAttribute('aria-current', 'true');
+
+    tops.set('anchor-usage', 0); // cuộn tiếp sang section 2
+    fireScroll();
+    expect(getByText('Introduction')).not.toHaveAttribute('aria-current');
+    expect(getByText('Usage')).toHaveAttribute('aria-current', 'true');
+  });
+
+  it('offsetTop threshold: top 8px chưa active với offsetTop mặc định; đặt offsetTop 10 → active', () => {
+    const tops = new Map<string, number>([['anchor-intro', 8]]);
+    mountSection('anchor-intro', tops);
+    const { getByText, rerender } = render(<Anchor items={ITEMS} />);
+    fireScroll();
+    expect(getByText('Introduction')).not.toHaveAttribute('aria-current');
+
+    rerender(<Anchor items={ITEMS} offsetTop={10} />);
+    expect(getByText('Introduction')).toHaveAttribute('aria-current', 'true');
+  });
+
+  it('click → preventDefault + window.scrollTo smooth tới (rect.top + scrollY - offsetTop)', () => {
+    const tops = new Map<string, number>([['anchor-usage', 200]]);
+    mountSection('anchor-intro', tops);
+    mountSection('anchor-usage', tops);
+    const scrollTo = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+    const { getByText } = render(<Anchor items={ITEMS} offsetTop={10} />);
+
+    let docPrevented: boolean | undefined;
+    document.addEventListener('click', (e) => {
+      docPrevented = e.defaultPrevented;
+    });
+    fireEvent.click(getByText('Usage'));
+
+    expect(docPrevented).toBe(true);
+    expect(scrollTo).toHaveBeenCalledWith({ top: 190, behavior: 'smooth' }); // 200 + 0 - 10
+  });
+
+  it('onClick callback nhận (native event, link {href, title}) trước khi cuộn', () => {
+    const tops = new Map<string, number>([['anchor-intro', 100]]);
+    mountSection('anchor-intro', tops);
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+    const onClick = vi.fn();
+    const { getByText } = render(<Anchor items={ITEMS} onClick={onClick} />);
+
+    fireEvent.click(getByText('Introduction'));
+    expect(onClick).toHaveBeenCalledTimes(1);
+    const [, link] = onClick.mock.calls[0];
+    expect(link.href).toBe('#anchor-intro');
+    expect(link.title).toBe('Introduction');
+  });
+
+  it('affix → wrapper sticky top = offsetTop; không affix → nav là root, không wrapper', () => {
+    const tops = new Map<string, number>([['anchor-intro', 100]]);
+    mountSection('anchor-intro', tops);
+    const { container, rerender } = render(<Anchor items={ITEMS} affix offsetTop={24} className="w-56" />);
+
+    const wrapper = container.firstElementChild as HTMLElement;
+    expect(wrapper.style.position).toBe('sticky');
+    expect(wrapper.style.top).toBe('24px');
+    expect(wrapper).toHaveClass('w-56');
+    expect(wrapper.firstElementChild!.tagName).toBe('NAV');
+
+    rerender(<Anchor items={ITEMS} />);
+    expect(container.firstElementChild!.tagName).toBe('NAV');
+  });
+
+  it('getContainer element → scroll event trên container + scrollTo trên chính container', () => {
+    const tops = new Map<string, number>([['anchor-intro', 300]]);
+    mountSection('anchor-intro', tops);
+    const scrollContainer = document.createElement('div');
+    document.body.appendChild(scrollContainer);
+    const containerScrollTo = vi.fn();
+    (scrollContainer as HTMLElement & { scrollTo: unknown }).scrollTo = containerScrollTo;
+
+    const { getByText } = render(
+      <Anchor items={ITEMS} offsetTop={0} getContainer={() => scrollContainer} />,
+    );
+    // Section top 300 chưa active — element container cũng cập nhật active qua scroll event riêng
+    fireScroll(scrollContainer);
+    expect(getByText('Introduction')).not.toHaveAttribute('aria-current');
+
+    tops.set('anchor-intro', 0);
+    fireScroll(scrollContainer);
+    expect(getByText('Introduction')).toHaveAttribute('aria-current', 'true');
+
+    fireEvent.click(getByText('Introduction'));
+    expect(containerScrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'smooth' });
+  });
+
+  it('section chưa mount (href không khớp id nào) → spy bỏ qua, không vỡ', () => {
+    const tops = new Map<string, number>([['anchor-intro', 0]]);
+    mountSection('anchor-intro', tops);
+    const { getByText } = render(<Anchor items={ITEMS} />);
+    fireScroll();
+    // #anchor-usage/#anchor-api không có section → active rơi về section có thật
+    expect(getByText('Introduction')).toHaveAttribute('aria-current', 'true');
+  });
+});

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

@@ -0,0 +1,144 @@
+// Anchor — in-page navigation kiểu antd: scroll-spy active theo section + click
+// scroll mượt tới section. active xác định bằng scroll + getBoundingClientRect
+// (section cuối cùng có top ≤ offsetTop) qua scroll event của container — không
+// IntersectionObserver (jsdom/test + không deps mới). Vertical rail + ink dot,
+// active accent; a11y: <nav> landmark + aria-current trên link đang active.
+// Depth contract 2026-10-19: selected tint accent/8 + hover tint ink/4
+// (color-mix trên token), dot slide 2px hover, mọi transition ease-smooth 240ms.
+import { useEffect, useMemo, useState, type MouseEvent as ReactMouseEvent, type ReactNode } from 'react';
+
+export interface AnchorLinkItem {
+  key?: string;
+  /** Selector đoạn (`#section-id` — trùng id của section trên trang). */
+  href: string;
+  title: ReactNode;
+  /** Link cấp con (indented, rail riêng — antd nested). */
+  children?: AnchorLinkItem[];
+}
+
+export type AnchorGetContainer = () => HTMLElement | Window;
+
+export interface AnchorProps {
+  items: AnchorLinkItem[];
+  /** Khoảng cách px từ đỉnh viewport để coi section là active (mặc định 0); với affix là khoảng sticky. */
+  offsetTop?: number;
+  /** Callback sau khi click link (e đã preventDefault — component tự cuộn). */
+  onClick?: (e: MouseEvent, link: AnchorLinkItem) => void;
+  /** Ghim anchor khi cuộn (sticky top = offsetTop — bản nhẹ của antd Affix). */
+  affix?: boolean;
+  /** Scroll container chứa các section (mặc định window). */
+  getContainer?: AnchorGetContainer;
+  className?: string;
+}
+
+/** Dẹt hoá cây item (cha trước con) — thứ tự document cho scroll-spy. */
+function flattenItems(items: AnchorLinkItem[]): string[] {
+  const hrefs: string[] = [];
+  const walk = (list: AnchorLinkItem[]) => {
+    for (const item of list) {
+      hrefs.push(item.href);
+      if (item.children) walk(item.children);
+    }
+  };
+  walk(items);
+  return hrefs;
+}
+
+/** Section cuối cùng có đỉnh lên tới (hoặc vượt qua) mép offsetTop → active. */
+function findActiveHref(hrefs: string[], offsetTop: number): string | undefined {
+  let current: string | undefined;
+  for (const href of hrefs) {
+    const el = document.getElementById(href.slice(1));
+    if (!el) continue;
+    if (el.getBoundingClientRect().top <= offsetTop + 1) current = href;
+  }
+  return current;
+}
+
+export function Anchor({
+  items,
+  offsetTop = 0,
+  onClick,
+  affix = false,
+  getContainer,
+  className,
+}: AnchorProps) {
+  const hrefs = useMemo(() => flattenItems(items), [items]);
+  const [active, setActive] = useState<string | undefined>(undefined);
+
+  useEffect(() => {
+    const container = getContainer?.() ?? window;
+    const onScroll = () => setActive(findActiveHref(hrefs, offsetTop));
+    onScroll(); // sync trạng thái ngay khi mount/đổi items
+    container.addEventListener('scroll', onScroll);
+    return () => container.removeEventListener('scroll', onScroll);
+  }, [hrefs, offsetTop, getContainer]);
+
+  const scrollToHref = (href: string) => {
+    const el = document.getElementById(href.slice(1));
+    if (!el) return;
+    const container = getContainer?.();
+    if (container && container !== window) {
+      container.scrollTo({ top: el.offsetTop - offsetTop, behavior: 'smooth' });
+    } else {
+      const top = el.getBoundingClientRect().top + window.scrollY - offsetTop;
+      window.scrollTo({ top, behavior: 'smooth' });
+    }
+  };
+
+  const handleClick = (e: ReactMouseEvent<HTMLAnchorElement>, item: AnchorLinkItem) => {
+    e.preventDefault();
+    onClick?.(e.nativeEvent, item);
+    scrollToHref(item.href);
+  };
+
+  const renderList = (list: AnchorLinkItem[]) => (
+    <ul className="m-0 list-none border-l border-line p-0">
+      {list.map((item) => {
+        const isActive = active === item.href;
+        return (
+          <li key={item.key ?? item.href}>
+            <a
+              href={item.href}
+              onClick={(e) => handleClick(e, item)}
+              aria-current={isActive || undefined}
+              className={`group relative block rounded-lg py-1 pl-4 text-body no-underline outline-none transition-[color,background-color] duration-[240ms] [transition-timing-function:var(--ease-smooth)] focus-visible:ring-2 focus-visible:ring-accent/40 ${
+                isActive
+                  ? 'bg-[color-mix(in_srgb,var(--accent)_8%,transparent)] text-accent'
+                  : 'text-ink2 hover:bg-[color-mix(in_srgb,var(--ink)_4%,transparent)] hover:text-ink'
+              }`}
+            >
+              <span
+                aria-hidden="true"
+                className={`absolute -left-[3px] top-1/2 size-1.5 -translate-y-1/2 rounded-pill transition-[background-color,transform] duration-[240ms] [transition-timing-function:var(--ease-smooth)] group-hover:translate-x-0.5 ${
+                  isActive ? 'bg-accent' : 'bg-ink4'
+                }`}
+              />
+              {item.title}
+            </a>
+            {item.children && item.children.length > 0 && (
+              <div className="pl-4">{renderList(item.children)}</div>
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+
+  const list = renderList(items);
+
+  if (affix) {
+    return (
+      <div style={{ position: 'sticky', top: offsetTop }} className={className}>
+        <nav aria-label="Table of contents" className="w-40 text-body">
+          {list}
+        </nav>
+      </div>
+    );
+  }
+  return (
+    <nav aria-label="Table of contents" className={`w-40 text-body ${className ?? ''}`}>
+      {list}
+    </nav>
+  );
+}

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

@@ -0,0 +1,67 @@
+// AutoComplete stories — input + suggestion dropdown, pick → value.
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { AutoComplete } from './index';
+
+const meta = {
+  title: 'Forms/AutoComplete',
+  component: AutoComplete,
+  tags: ['autodocs'],
+} satisfies Meta;
+export default meta;
+
+type Story = StoryObj;
+
+const TASKS = [
+  { label: 'Learn TypeScript', value: 'ts' },
+  { label: 'Learn Rust', value: 'rust' },
+  { label: 'Write E2E tests', value: 'e2e' },
+  { label: 'Fix nginx gateway', value: 'gateway' },
+  { label: 'Saga compensation demo', value: 'saga' },
+];
+
+/** Basic — type to filter, click a suggestion to pick. */
+export const Basic: Story = {
+  args: { suggestions: TASKS, placeholder: 'Search tasks…' },
+};
+
+/** Controlled — useState demo: typed value + picked value displayed. */
+export const Controlled: Story = {
+  render: () => <AutoCompleteControlledDemo />,
+};
+
+/** Empty — no suggestions → dropdown never opens. */
+export const Empty: Story = {
+  name: 'Empty — no suggestions',
+  args: { suggestions: [], placeholder: 'Nothing to suggest…' },
+};
+
+/** DarkTheme — input + open dropdown on dark canvas. */
+export const DarkTheme: Story = {
+  render: () => (
+    <div data-bp-theme="dark" className="rounded-xl bg-canvas p-4">
+      <div className="grid max-w-[320px] gap-3">
+        <AutoComplete suggestions={TASKS.slice(0, 3)} placeholder="Search tasks…" />
+      </div>
+    </div>
+  ),
+};
+
+function AutoCompleteControlledDemo() {
+  const [value, setValue] = useState('');
+  const [selected, setSelected] = useState('');
+  return (
+    <div className="grid max-w-[320px] gap-3">
+      <AutoComplete
+        suggestions={TASKS}
+        value={value}
+        onChange={setValue}
+        onSelect={setSelected}
+        placeholder="Search tasks…"
+      />
+      <p className="m-0 font-mono text-meta text-ink3">
+        value: <strong className="text-ink">{value || '—'}</strong> · selected: <strong className="text-ink">{selected || '—'}</strong>
+      </p>
+    </div>
+  );
+}