create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,113 @@
+// Drawer — panel trượt từ phải (antd: width 378, mask, ESC/mask = onClose).
+// Motion identity (CSS thuần): slide-in khi mở, slide-out khi đóng — closing state
+// machine: open=false → animation chạy XONG (onAnimationEnd) mới unmount.
+// A11y (batch ⑫ worker C): focus trap (Tab/Shift+Tab vòng trong panel), mở →
+// focus phần tử đầu (nút ×), đóng → trả focus về trigger (capture activeElement).
+import { useEffect, useId, useRef, useState, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import { useFocusTrap } from '../../hooks/useFocusTrap.js';
+import { Icon } from '../icons/index.js';
+
+/** antd v5-style sub-part slot classes — merge AFTER defaults (consumer appends). */
+export interface DrawerClassNames {
+  /** Sliding panel (aside). */
+  wrapper?: string;
+  /** Fullscreen dim overlay. */
+  mask?: string;
+  /** Title bar. */
+  header?: string;
+  /** Scrollable body. */
+  body?: string;
+  /** Footer action row. */
+  footer?: string;
+}
+
+export interface DrawerProps {
+  /** Mở/đóng (đóng có exit animation trước khi unmount). */
+  open: boolean;
+  /** Tiêu đề header (string → làm aria-label dialog). */
+  title?: ReactNode;
+  /** px — mặc định 378 (antd). */
+  width?: number;
+  onClose?: () => void;
+  /** Hàng nút cuối panel. */
+  footer?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+  /** Slot classes kiểu antd v5 (SÓNG-3) — merge sau class mặc định. */
+  classNames?: DrawerClassNames;
+}
+
+// slot helper — ghép class consumer vào sau mặc định (undefined → rỗng)
+const slot = (c?: string) => (c ? ` ${c}` : '');
+
+export function Drawer({ open, title, width = 378, onClose, footer, children, className, classNames }: DrawerProps) {
+  // A11y: dialog name qua labelledby — ăn cả title ReactNode, không chỉ string.
+  const titleId = useId();
+  const [mounted, setMounted] = useState(open);
+  const closing = mounted && !open;
+  const panelRef = useRef<HTMLElement>(null);
+
+  // active = open && mounted: mở → focus đầu; bắt đầu closing → trả focus trigger
+  useFocusTrap(panelRef, open && mounted);
+
+  useEffect(() => {
+    if (open) setMounted(true);
+  }, [open]);
+
+  // ESC chỉ khi open
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose?.();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [open, onClose]);
+
+  // Scroll lock giữ tới mounted=false (exit animation XONG)
+  useEffect(() => {
+    if (!mounted) return;
+    document.body.style.overflow = 'hidden';
+    return () => { document.body.style.overflow = ''; };
+  }, [mounted]);
+
+  if (!mounted) return null;
+
+  return createPortal(
+    <div
+      className={`fixed inset-0 z-[var(--z-modal)] bg-[var(--mask)] ${closing ? 'animate-[bp-fade-out_var(--motion-fast)_var(--ease-exit)]' : 'animate-[bp-fade-in_var(--motion-base)_var(--ease-enter)]'}${slot(classNames?.mask)}`}
+      onClick={() => onClose?.()}
+      data-testid="drawer-overlay"
+    >
+      <aside
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        tabIndex={-1}
+        aria-labelledby={titleId}
+        className={`absolute inset-y-0 right-0 flex flex-col bg-s2 shadow-[var(--shadow-pop)] ${closing ? 'animate-[bp-slide-out-right_var(--motion-fast)_var(--ease-exit)]' : 'animate-[bp-slide-in-right_var(--motion-base)_var(--ease-enter)]'}${className ? ` ${className}` : ''}${slot(classNames?.wrapper)}`}
+        style={{ width }}
+        onAnimationEnd={(e) => {
+          if (closing && e.target === e.currentTarget) setMounted(false);
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <header className={`flex items-center justify-between border-b border-line2 px-6 py-4${slot(classNames?.header)}`}>
+          <div id={titleId} className="text-h2 font-semibold text-ink">{title}</div>
+          <button
+            type="button"
+            aria-label="Đóng"
+            className="cursor-pointer rounded-1 border-none bg-transparent text-base leading-4 text-ink3 hover:text-ink focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 active:opacity-70"
+            onClick={() => onClose?.()}
+          >
+            <Icon name="times" size={14} />
+          </button>
+        </header>
+        <div className={`flex-1 overflow-auto p-6 text-body text-ink2${slot(classNames?.body)}`}>{children}</div>
+        {footer && <footer className={`flex justify-end gap-2 border-t border-line2 p-4${slot(classNames?.footer)}`}>{footer}</footer>}
+      </aside>
+    </div>,
+    document.body,
+  );
+}

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

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from 'react';
+import { Dropdown, type DropdownItem } from './index';
+import { Button } from '../button/index';
+
+/** Button-triggered action menu with role=menu keyboard nav. */
+const meta = { title: 'Navigation/Dropdown', component: Dropdown, tags: ['autodocs'] } satisfies Meta<typeof Dropdown>;
+export default meta;
+type S = StoryObj<typeof meta>;
+type R = StoryObj;
+
+const items: DropdownItem[] = [
+  { key: 'edit', label: 'Edit' },
+  { key: 'duplicate', label: 'Duplicate' },
+  { key: '---', label: '' },
+  { key: 'archive', label: 'Archive', disabled: true },
+  { key: 'delete', label: 'Delete', danger: true },
+];
+
+function Demo() {
+  const [msg, setMsg] = useState('');
+  return (
+    <div>
+      <Dropdown trigger={<Button>Action ▾</Button>} onItemClick={(k) => setMsg(k)} items={items} />
+      {msg && <p className="mt-2 text-label text-ink2">Selected: {msg}</p>}
+    </div>
+  );
+}
+
+export const Basic: S = {
+  name: 'Basic — divider + disabled + danger items',
+  args: { trigger: <button>Menu</button>, items: [{ key: 'a', label: 'A' }] },
+  render: () => <Demo />,
+};
+
+export const Minimal: S = {
+  name: 'Minimal — single item, min-width menu',
+  args: { trigger: <button>Menu</button>, items: [{ key: 'a', label: 'A' }] },
+  render: () => (
+    <Dropdown trigger={<Button>Only one action ▾</Button>} items={[{ key: 'only', label: 'The only action' }]} />
+  ),
+};
+
+export const WithKeyboardNav: R = {
+  name: 'WithKeyboardNav — ArrowDown opens + focuses first, ESC returns focus',
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <span className="text-label text-ink2">Focus the trigger, press ArrowDown / Enter / Space</span>
+      <Dropdown trigger={<Button>Keyboard menu ▾</Button>} items={items} />
+    </div>
+  ),
+};
+
+export const DarkTheme: R = {
+  name: 'DarkTheme — menu bg-s2 + shadow-pop dark',
+  render: () => (
+    <div data-bp-theme="dark" className="p-4">
+      <Dropdown trigger={<Button>Action ▾ (dark)</Button>} items={items} />
+    </div>
+  ),
+};

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

@@ -0,0 +1,101 @@
+// Dropdown tests — toggle/item click/ESC/outside/danger/disabled
+// (+ keyboard a11y batch ⑫: role menu/menuitem, arrow keys, focus-first khi mở keyboard).
+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 { Dropdown } from './index.js';
+
+const ITEMS = [
+  { key: 'edit', label: 'Sửa' },
+  { key: '---', label: '' },
+  { key: 'delete', label: 'Xoá', danger: true },
+  { key: 'lock', label: 'Khoá', disabled: true },
+];
+
+afterEach(cleanup);
+
+describe('Dropdown', () => {
+  it('mặc định ẩn; click trigger mở menu items', async () => {
+    const user = userEvent.setup();
+    render(<Dropdown trigger={<button>Menu</button>} items={ITEMS} />);
+    expect(screen.queryByText('Sửa')).toBeNull();
+    await user.click(screen.getByRole('button', { name: 'Menu' }));
+    expect(screen.getByText('Sửa')).toBeInTheDocument();
+    expect(screen.getByText('Xoá')).toHaveClass('text-st-fail');
+  });
+
+  it('item click → onItemClick(key) + đóng; disabled không gọi', async () => {
+    const onItemClick = vi.fn();
+    const user = userEvent.setup();
+    render(<Dropdown trigger={<button>Menu</button>} items={ITEMS} onItemClick={onItemClick} />);
+    await user.click(screen.getByRole('button', { name: 'Menu' }));
+    await user.click(screen.getByText('Sửa'));
+    expect(onItemClick).toHaveBeenCalledWith('edit');
+    await user.click(screen.getByRole('button', { name: 'Menu' }));
+    await user.click(screen.getByText('Khoá'));
+    expect(onItemClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('ESC đóng', async () => {
+    const user = userEvent.setup();
+    render(<Dropdown trigger={<button>Menu</button>} items={ITEMS} />);
+    await user.click(screen.getByRole('button', { name: 'Menu' }));
+    await user.keyboard('{Escape}');
+    expect(screen.queryByText('Sửa')).toBeNull();
+  });
+});
+
+describe('Dropdown — branch phụ (Tier 5 sweep)', () => {
+  it('divider "---" → li border; item disabled → class cursor-not-allowed', async () => {
+    const user = userEvent.setup();
+    render(<Dropdown trigger={<button>Menu</button>} items={ITEMS} />);
+    await user.click(screen.getByRole('button', { name: 'Menu' }));
+    expect(document.querySelector('.my-1.border-t')).not.toBeNull();
+    expect(screen.getByText('Khoá').className).toContain('cursor-not-allowed');
+  });
+});
+
+describe('Dropdown — keyboard a11y (batch ⑫ worker C)', () => {
+  it('role=menu + role=menuitem; item disabled có aria-disabled', async () => {
+    const user = userEvent.setup();
+    render(<Dropdown trigger={<button>Menu</button>} items={ITEMS} />);
+    await user.click(screen.getByRole('button', { name: 'Menu' }));
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    expect(screen.getByRole('menuitem', { name: 'Sửa' })).toBeInTheDocument();
+    expect(screen.getByRole('menuitem', { name: 'Khoá' })).toHaveAttribute('aria-disabled', 'true');
+  });
+
+  it('ArrowDown mở menu + focus item ĐẦU; ArrowDown/Up đi giữa item (bỏ disabled)', async () => {
+    render(<Dropdown trigger={<button>Menu</button>} items={ITEMS} />);
+    const trigger = screen.getByRole('button', { name: 'Menu' });
+    fireEvent.keyDown(trigger, { key: 'ArrowDown' });
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    expect(screen.getByRole('menuitem', { name: 'Sửa' })).toHaveFocus();
+    fireEvent.keyDown(screen.getByRole('menu'), { key: 'ArrowDown' }); // Sửa → Xoá (divider + Khoá disabled bị bỏ)
+    expect(screen.getByRole('menuitem', { name: 'Xoá' })).toHaveFocus();
+    fireEvent.keyDown(screen.getByRole('menu'), { key: 'ArrowUp' });
+    expect(screen.getByRole('menuitem', { name: 'Sửa' })).toHaveFocus();
+  });
+
+  it('End/Home → item cuối/đầu focusable', async () => {
+    const user = userEvent.setup();
+    render(<Dropdown trigger={<button>Menu</button>} items={ITEMS} />);
+    await user.click(screen.getByRole('button', { name: 'Menu' }));
+    fireEvent.keyDown(screen.getByRole('menu'), { key: 'End' });
+    expect(screen.getByRole('menuitem', { name: 'Xoá' })).toHaveFocus();
+    fireEvent.keyDown(screen.getByRole('menu'), { key: 'Home' });
+    expect(screen.getByRole('menuitem', { name: 'Sửa' })).toHaveFocus();
+  });
+
+  it('mở bằng Enter (keyboard click) → focus item đầu; ESC → đóng + TRẢ FOCUS về trigger', async () => {
+    const user = userEvent.setup();
+    render(<Dropdown trigger={<button>Menu</button>} items={ITEMS} />);
+    const trigger = screen.getByRole('button', { name: 'Menu' });
+    trigger.focus();
+    await user.keyboard('{Enter}');
+    expect(screen.getByRole('menuitem', { name: 'Sửa' })).toHaveFocus();
+    await user.keyboard('{Escape}');
+    expect(screen.queryByRole('menu')).toBeNull();
+    expect(trigger).toHaveFocus();
+  });
+});

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

@@ -0,0 +1,162 @@
+// Dropdown — trigger + menu overlay (style matrix 2026-10-18: menu rounded-xl,
+// shadow var(--shadow-pop); item hover bg-s3, danger = đỏ; divider giữa nhóm key '---').
+// Đóng: click item / ESC / click ngoài (document listener).
+// A11y (batch ⑫ worker C): role=menu/menuitem, ArrowUp/Down/Home/End đi giữa
+// item, mở bằng keyboard (Enter/Space/ArrowDown) → focus item đầu, ESC → đóng
+// + trả focus về trigger.
+import {
+  cloneElement,
+  isValidElement,
+  useEffect,
+  useRef,
+  useState,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+export interface DropdownItem {
+  key: string;
+  label: ReactNode;
+  danger?: boolean;
+  disabled?: boolean;
+}
+
+export interface DropdownProps {
+  /** Trigger element (click để mở). */
+  trigger: ReactNode;
+  /** Item menu — key '---' render divider. */
+  items: DropdownItem[];
+  /** Callback khi click item (không gọi với item disabled). */
+  onItemClick?: (key: string) => void;
+  className?: string;
+}
+
+export function Dropdown({ trigger, items, onItemClick, className }: DropdownProps) {
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLSpanElement>(null);
+  const menuRef = useRef<HTMLUListElement>(null);
+  // Mở bằng keyboard (Enter/Space/ArrowDown) → focus item đầu sau khi mở
+  const focusFirstOnOpen = useRef(false);
+
+  const itemButtons = () =>
+    Array.from(
+      menuRef.current?.querySelectorAll<HTMLButtonElement>('button[role="menuitem"]:not([disabled])') ?? [],
+    );
+
+  useEffect(() => {
+    if (!open) return;
+    if (focusFirstOnOpen.current) {
+      focusFirstOnOpen.current = false;
+      itemButtons()[0]?.focus();
+    }
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onDoc = (e: MouseEvent) => {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        setOpen(false);
+        // trả focus về trigger (phần tử focusable đầu trong root)
+        rootRef.current
+          ?.querySelector<HTMLElement>('button:not([disabled]), [tabindex]:not([tabindex="-1"])')
+          ?.focus();
+      }
+    };
+    document.addEventListener('mousedown', onDoc);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDoc);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  // Trigger mở bằng keyboard: ArrowDown mở + focus item đầu với MỌI trigger;
+  // Enter/Space với native button → click sự kiện detail=0 (keyboard) → flag trước.
+  const onTriggerKey = (e: ReactKeyboardEvent<HTMLSpanElement>) => {
+    if (open) return;
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      focusFirstOnOpen.current = true;
+      setOpen(true);
+    }
+  };
+  const onTriggerClick = (e: React.MouseEvent) => {
+    // click sinh từ bàn phím (Enter/Space trên native button) có detail = 0
+    if (e.detail === 0) focusFirstOnOpen.current = true;
+    setOpen((o) => !o);
+  };
+
+  // Menu keyboard: ArrowUp/Down vòng tròn, Home/End đầu/cuối (bỏ item disabled)
+  const onMenuKey = (e: ReactKeyboardEvent<HTMLUListElement>) => {
+    const buttons = itemButtons();
+    if (buttons.length === 0) return;
+    const idx = buttons.indexOf(document.activeElement as HTMLButtonElement);
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      buttons[(idx + 1) % buttons.length].focus();
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      buttons[(idx - 1 + buttons.length) % buttons.length].focus();
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      buttons[0].focus();
+    } else if (e.key === 'End') {
+      e.preventDefault();
+      buttons[buttons.length - 1].focus();
+    }
+  };
+
+  // Trigger được wire aria (cloneElement — pattern Popconfirm): SR biết menu đang
+  // mở + trigger mở loại gì; children không phải element → giữ nguyên.
+  const triggerEl = isValidElement(trigger)
+    ? cloneElement(trigger as ReactElement<Record<string, unknown>>, {
+        'aria-haspopup': 'menu',
+        'aria-expanded': open,
+      })
+    : trigger;
+
+  return (
+    <span ref={rootRef} className={`relative inline-flex${className ? ` ${className}` : ''}`}>
+      <span onClick={onTriggerClick} onKeyDown={onTriggerKey} className="inline-flex">
+        {triggerEl}
+      </span>
+      {open && (
+        <ul
+          ref={menuRef}
+          role="menu"
+          onKeyDown={onMenuKey}
+          className="absolute right-0 z-[var(--z-dropdown)] mt-1 min-w-[120px] origin-top-right list-none rounded-xl border border-line bg-s2 p-1 shadow-[var(--shadow-pop)] animate-[bp-zoom-in_var(--motion-fast)_var(--ease-enter)]"
+        >
+          {items.map((item) =>
+            item.key === '---' ? (
+              <li key={item.key} className="my-1 border-t border-line2" />
+            ) : (
+              <li key={item.key}>
+                <button
+                  type="button"
+                  role="menuitem"
+                  aria-disabled={item.disabled || undefined}
+                  disabled={item.disabled}
+                  onClick={() => {
+                    if (item.disabled) return;
+                    onItemClick?.(item.key);
+                    setOpen(false);
+                  }}
+                  className={`w-full cursor-pointer rounded-lg border-none bg-transparent px-3 py-1.5 text-left text-body transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${
+                    item.danger ? 'text-st-fail hover:bg-st-fail/12 active:bg-st-fail/12' : 'text-ink hover:bg-s3 active:bg-s3'
+                  } ${item.disabled ? 'cursor-not-allowed text-ink3' : ''}`}
+                >
+                  {item.label}
+                </button>
+              </li>
+            ),
+          )}
+        </ul>
+      )}
+    </span>
+  );
+}

package/stack-template/app/ui-kit/src/ui/editor/EditorInner.tsx

@@ -0,0 +1,93 @@
+// EditorInner — thân thật Tiptap v3 (static import — chỉ được load qua React.lazy
+// ở index.tsx sau khi consumer có @tiptap/*). Toolbar: B/I/S + H2/H3 + list +
+// undo/redo; active state theo editor.isActive; placeholder DIY qua editor.isEmpty
+// (StarterKit v3 KHÔNG kèm Placeholder — không thêm dep mới).
+import { useState } from 'react';
+import { EditorContent, useEditor, type Editor } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+import { Icon } from '../icons/index.js';
+import type { EditorProps } from './index.js';
+
+interface TBtn {
+  key: string;
+  label: string;
+  title: string;
+  cls?: string;
+  icon?: 'arrow-left' | 'arrow-right';
+  run: (editor: Editor) => void;
+  active?: (editor: Editor) => boolean;
+}
+
+const TOOLS: TBtn[] = [
+  { key: 'bold', label: 'B', title: 'Đậm', cls: 'font-bold', run: (ed) => void ed.chain().focus().toggleBold().run(), active: (ed) => ed.isActive('bold') },
+  { key: 'italic', label: 'I', title: 'Nghiêng', cls: 'italic', run: (ed) => void ed.chain().focus().toggleItalic().run(), active: (ed) => ed.isActive('italic') },
+  { key: 'strike', label: 'S', title: 'Gạch ngang', cls: 'line-through', run: (ed) => void ed.chain().focus().toggleStrike().run(), active: (ed) => ed.isActive('strike') },
+  { key: 'h2', label: 'H2', title: 'Tiêu đề 2', cls: 'font-semibold', run: (ed) => void ed.chain().focus().toggleHeading({ level: 2 }).run(), active: (ed) => ed.isActive('heading', { level: 2 }) },
+  { key: 'h3', label: 'H3', title: 'Tiêu đề 3', cls: 'font-semibold', run: (ed) => void ed.chain().focus().toggleHeading({ level: 3 }).run(), active: (ed) => ed.isActive('heading', { level: 3 }) },
+  { key: 'bullet', label: '••', title: 'Danh sách chấm', run: (ed) => void ed.chain().focus().toggleBulletList().run(), active: (ed) => ed.isActive('bulletList') },
+  { key: 'ordered', label: '1.', title: 'Danh sách số', cls: 'text-[11px]', run: (ed) => void ed.chain().focus().toggleOrderedList().run(), active: (ed) => ed.isActive('orderedList') },
+  { key: 'undo', label: '', title: 'Hoàn tác', icon: 'arrow-left', run: (ed) => void ed.chain().focus().undo().run() },
+  { key: 'redo', label: '', title: 'Làm lại', icon: 'arrow-right', run: (ed) => void ed.chain().focus().redo().run() },
+];
+
+export function EditorInner({ content = '', onChange, placeholder, className, editorRef }: EditorProps) {
+  const [empty, setEmpty] = useState(!content);
+
+  const editor = useEditor({
+    extensions: [StarterKit],
+    content,
+    // active state (B/I/S…) cần re-render theo selection/transaction — v3 mặc định off
+    shouldRerenderOnTransaction: true,
+    onCreate: ({ editor: ed }) => {
+      editorRef?.(ed);
+      setEmpty(ed.isEmpty);
+    },
+    onUpdate: ({ editor: ed }) => {
+      setEmpty(ed.isEmpty);
+      onChange?.(ed.getHTML());
+    },
+    onSelectionUpdate: ({ editor: ed }) => setEmpty(ed.isEmpty),
+  });
+
+  return (
+    <div
+      className={`overflow-hidden rounded-lg border border-line bg-s2 transition-colors focus-within:border-accent-hi${
+        className ? ` ${className}` : ''
+      }`}
+    >
+      {/* Toolbar sticky trên content */}
+      <div className="sticky top-0 z-10 flex flex-wrap items-center gap-0.5 border-b border-line bg-s1 px-1 py-1">
+        {TOOLS.map((t) => {
+          const active = editor ? Boolean(t.active?.(editor)) : false;
+          return (
+            <button
+              key={t.key}
+              type="button"
+              aria-label={t.title}
+              aria-pressed={active ? 'true' : 'false'}
+              title={t.title}
+              disabled={!editor}
+              onClick={() => editor && t.run(editor)}
+              className={`grid size-7 cursor-pointer place-items-center rounded-lg border-none bg-transparent text-body text-ink2 transition-colors hover:bg-s3 hover:text-ink disabled:cursor-default disabled:opacity-50 ${
+                active ? 'bg-s3 text-ink' : ''
+              }`}
+            >
+              {t.icon ? <Icon name={t.icon} size={14} /> : <span className={t.cls}>{t.label}</span>}
+            </button>
+          );
+        })}
+      </div>
+      <div className="relative">
+        {placeholder && empty && (
+          <span aria-hidden="true" className="pointer-events-none absolute left-3 top-3 select-none text-body text-ink4">
+            {placeholder}
+          </span>
+        )}
+        <EditorContent
+          editor={editor}
+          className="[&_.ProseMirror]:min-h-[120px] [&_.ProseMirror]:p-3 [&_.ProseMirror]:text-body [&_.ProseMirror]:text-ink [&_.ProseMirror]:outline-none"
+        />
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,37 @@
+// Editor stories — Basic (toolbar + sample content) / Controlled (realtime HTML) /
+// Placeholder. Tiptap v3 — jsdom-friendly via commands, direct typing in browser.
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Editor } from './index';
+
+/** Rich-text editor (Tiptap) — toolbar + HTML output, subpath `@wakii/ui-kit/editor`. */
+const meta = { title: 'Forms/Editor', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+export const Basic: S = {
+  name: 'Basic — toolbar + sample content',
+  render: () => <Editor content="<p>Sample <strong>content</strong> — try the toolbar above.</p>" placeholder="Start writing…" />,
+};
+
+function ControlledDemo() {
+  const [html, setHtml] = useState('<p>Type to see the HTML…</p>');
+  return (
+    <div className="flex w-[560px] flex-col gap-3">
+      <Editor content={html} onChange={setHtml} placeholder="Write a note…" />
+      <pre className="m-0 max-h-32 overflow-auto rounded-lg border border-line bg-s1 p-3 text-meta text-ink2">
+        {html}
+      </pre>
+    </div>
+  );
+}
+
+export const Controlled: S = {
+  name: 'Controlled — realtime HTML output (useState)',
+  render: () => <ControlledDemo />,
+};
+
+export const Placeholder: S = {
+  name: 'Placeholder — shown when empty',
+  render: () => <Editor placeholder="Enter the task description…" className="max-w-[420px]" />,
+};

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

@@ -0,0 +1,84 @@
+// Editor tests — jsdom + Tiptap v3 thật: .ProseMirror tồn tại, typing → onChange
+// HTML, toolbar toggleBold → active state, placeholder lúc trống, undo, imperative
+// editor qua editorRef. Type qua editorRef (PM handleBeforeInput trong jsdom
+// không đáng tin — commands là API chính thức).
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Editor as TiptapEditor } from '@tiptap/react';
+import { Editor } from './index.js';
+
+afterEach(cleanup);
+
+const pm = () => {
+  const el = document.querySelector('.ProseMirror');
+  if (!el) throw new Error('.ProseMirror chưa mount');
+  return el as HTMLElement;
+};
+
+const waitForMounted = () => waitFor(() => expect(document.querySelector('.ProseMirror')).toBeInTheDocument());
+
+describe('Editor — render', () => {
+  it('render → .ProseMirror tồn tại + contentEditable + content khởi tạo', async () => {
+    render(<Editor content="<p>Xin chào</p>" />);
+    await waitForMounted();
+    expect(pm()).toHaveAttribute('contenteditable', 'true');
+    expect(pm()).toHaveTextContent('Xin chào');
+  });
+
+  it('trống + placeholder → bubble placeholder hiện', async () => {
+    render(<Editor placeholder="Viết gì đó…" />);
+    await waitForMounted();
+    expect(screen.getByText('Viết gì đó…')).toBeInTheDocument();
+  });
+});
+
+describe('Editor — onChange + commands', () => {
+  it('insertContent (commands API) → onChange nhận HTML chứa text', async () => {
+    // jsdom: userEvent.type vào ProseMirror không cập nhật PM state (thiếu
+    // elementFromPoint) — giả lập qua editor instance như spec cho phép
+    const onChange = vi.fn();
+    let editor: TiptapEditor | null = null;
+    render(<Editor onChange={onChange} editorRef={(ed) => (editor = ed as TiptapEditor)} />);
+    await waitForMounted();
+    editor!.commands.insertContent('abc');
+    await vi.waitFor(() => {
+      expect(onChange).toHaveBeenCalled();
+    });
+    expect(String(onChange.mock.calls.at(-1)?.[0])).toContain('abc');
+  });
+
+  it('toolbar toggleBold sau selectAll → onChange wrap <strong>', async () => {
+    const onChange = vi.fn();
+    let editor: TiptapEditor | null = null;
+    render(<Editor content="<p>hello</p>" onChange={onChange} editorRef={(ed) => (editor = ed as TiptapEditor)} />);
+    await waitForMounted();
+    editor!.commands.selectAll();
+    const boldBtn = screen.getByRole('button', { name: 'Đậm' });
+    expect(boldBtn).toHaveAttribute('aria-pressed', 'false');
+    fireEvent.click(boldBtn);
+    expect(editor!.isActive('bold')).toBe(true);
+    expect(boldBtn).toHaveAttribute('aria-pressed', 'true');
+    expect(boldBtn).toHaveClass('bg-s3');
+    expect(editor!.getHTML()).toContain('<strong>hello</strong>');
+    expect(onChange).toHaveBeenCalled();
+  });
+
+  it('toggleHeading H2 → isActive heading level 2', async () => {
+    let editor: TiptapEditor | null = null;
+    render(<Editor content="<p>tiêu đề</p>" editorRef={(ed) => (editor = ed as TiptapEditor)} />);
+    await waitForMounted();
+    fireEvent.click(screen.getByRole('button', { name: 'Tiêu đề 2' }));
+    expect(editor!.isActive('heading', { level: 2 })).toBe(true);
+    expect(editor!.getHTML()).toContain('<h2>');
+  });
+
+  it('undo → trả về nội dung trước đó', async () => {
+    let editor: TiptapEditor | null = null;
+    render(<Editor content="<p>gốc</p>" editorRef={(ed) => (editor = ed as TiptapEditor)} />);
+    await waitForMounted();
+    fireEvent.click(screen.getByRole('button', { name: 'Tiêu đề 2' }));
+    expect(editor!.getHTML()).toContain('<h2>');
+    fireEvent.click(screen.getByRole('button', { name: 'Hoàn tác' }));
+    expect(editor!.getHTML()).not.toContain('<h2>');
+  });
+});