create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,234 @@
+// Kanban tests — controlled board: mọi move đều qua onCardMove (consumer sở hữu
+// state). dataTransfer stub giữ payload giữa dragStart → drop (jsdom không có
+// DragEvent thật). Mouse drop test trên slot DropZone (cha của [data-drag-id]).
+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 { KanbanBoard, type KanbanColumnData } from './index.js';
+
+afterEach(cleanup);
+
+/** Live region không role=status (trùng Badge) — query qua aria-live. */
+const liveRegion = () => document.querySelector('[aria-live="polite"]') as HTMLElement;
+
+function makeDt() {
+  const store = new Map<string, string>();
+  return {
+    types: [...store.keys()],
+    setData: (t: string, v: string) => store.set(t, v),
+    getData: (t: string) => store.get(t) ?? '',
+    effectAllowed: 'all',
+    dropEffect: 'all',
+  };
+}
+
+const COLS: KanbanColumnData[] = [
+  {
+    key: 'a',
+    title: 'Todo',
+    cards: [
+      { key: 't1', title: 'Task 1' },
+      { key: 't2', title: 'Task 2' },
+    ],
+  },
+  { key: 'b', title: 'Doing', cards: [{ key: 't3', title: 'Task 3' }] },
+];
+
+/** fire dragStart trên card → drop vào slot CHỨA card target (chèn trước target). */
+function dragTo(targetKey: string, ontoTitle: string) {
+  const dt = makeDt();
+  const card = document.querySelector(`[data-drag-id="${targetKey}"]`) as HTMLElement;
+  fireEvent.dragStart(card, { dataTransfer: dt });
+  const onto = screen.getByText(ontoTitle).closest('[data-drag-id]') as HTMLElement;
+  fireEvent.drop(onto.parentElement as HTMLElement, { dataTransfer: dt });
+}
+
+/** fire dragStart trên card → drop vào vùng trống cột (append). */
+function dragToColumn(targetKey: string, colTitle: string) {
+  const dt = makeDt();
+  const card = document.querySelector(`[data-drag-id="${targetKey}"]`) as HTMLElement;
+  fireEvent.dragStart(card, { dataTransfer: dt });
+  fireEvent.drop(screen.getByRole('group', { name: colTitle }), { dataTransfer: dt });
+}
+
+describe('KanbanBoard render', () => {
+  it('render cột + card + count badge', () => {
+    render(<KanbanBoard columns={COLS} />);
+    expect(screen.getByText('Todo')).toBeInTheDocument();
+    expect(screen.getByText('Doing')).toBeInTheDocument();
+    expect(screen.getByText('Task 1')).toBeInTheDocument();
+    expect(screen.getByText('Task 3')).toBeInTheDocument();
+    expect(screen.getByText('2')).toBeInTheDocument(); // badge cột Todo
+    expect(screen.getByText('1')).toBeInTheDocument(); // badge cột Doing
+  });
+
+  it('wipLimit hiển thị n/limit trên badge', () => {
+    render(
+      <KanbanBoard
+        columns={[{ key: 'a', title: 'Todo', wipLimit: 3, cards: COLS[0].cards }]}
+      />,
+    );
+    expect(screen.getByText('2/3')).toBeInTheDocument();
+  });
+
+  it('cột rỗng → EmptyState "Kéo thẻ vào đây"', () => {
+    render(<KanbanBoard columns={[{ key: 'a', title: 'Todo', cards: [] }]} />);
+    expect(screen.getByText('Kéo thẻ vào đây')).toBeInTheDocument();
+  });
+
+  it('renderCard slot — custom content, vẫn bọc Draggable + drop zone', () => {
+    render(
+      <KanbanBoard
+        columns={COLS}
+        renderCard={(c) => <div data-testid={`custom-${c.key}`}>custom {c.title}</div>}
+      />,
+    );
+    expect(screen.getByTestId('custom-t1')).toHaveTextContent('custom Task 1');
+    expect(screen.getByTestId('custom-t1').closest('[data-drag-id="t1"]')).not.toBeNull();
+  });
+});
+
+describe('KanbanBoard move (mouse DnD)', () => {
+  it('cross-column: drop vào slot cột khác → onCardMove(key, from, to, toIndex)', () => {
+    const onCardMove = vi.fn();
+    render(<KanbanBoard columns={COLS} onCardMove={onCardMove} />);
+    dragTo('t1', 'Task 3'); // chèn trước Task 3 → index 0 cột Doing
+    expect(onCardMove).toHaveBeenCalledWith('t1', 'a', 'b', 0);
+  });
+
+  it('reorder trong cột: drop t1 vào slot t3 → toIndex sau remove', () => {
+    const onCardMove = vi.fn();
+    render(
+      <KanbanBoard
+        columns={[
+          {
+            key: 'a',
+            title: 'Todo',
+            cards: [
+              { key: 't1', title: 'Task 1' },
+              { key: 't2', title: 'Task 2' },
+              { key: 't3', title: 'Task 3' },
+            ],
+          },
+        ]}
+        onCardMove={onCardMove}
+      />,
+    );
+    dragTo('t1', 'Task 3'); // insertIdx 2 > fromIdx 0 → toIndex 1
+    expect(onCardMove).toHaveBeenCalledWith('t1', 'a', 'a', 1);
+  });
+
+  it('append: drop vào vùng trống cột → toIndex = length', () => {
+    const onCardMove = vi.fn();
+    render(<KanbanBoard columns={COLS} onCardMove={onCardMove} />);
+    dragToColumn('t1', 'Doing'); // Doing có 1 card → toIndex 1
+    expect(onCardMove).toHaveBeenCalledWith('t1', 'a', 'b', 1);
+  });
+
+  it('drop đúng slot cũ → no-op, không bắn onCardMove', () => {
+    const onCardMove = vi.fn();
+    render(<KanbanBoard columns={COLS} onCardMove={onCardMove} />);
+    dragTo('t1', 'Task 1'); // chính nó
+    dragTo('t1', 'Task 2'); // slot kế tiếp = cùng vị trí sau remove
+    expect(onCardMove).not.toHaveBeenCalled();
+  });
+
+  it('WIP đạt limit: từ chối drop từ cột khác + aria-live báo từ chối', () => {
+    const onCardMove = vi.fn();
+    render(
+      <KanbanBoard
+        columns={[
+          { key: 'a', title: 'Todo', cards: COLS[0].cards },
+          { key: 'b', title: 'Doing', wipLimit: 1, cards: COLS[1].cards }, // đầy
+        ]}
+        onCardMove={onCardMove}
+      />
+    );
+    dragTo('t1', 'Task 3');
+    expect(onCardMove).not.toHaveBeenCalled();
+    expect(liveRegion()).toHaveTextContent('giới hạn WIP (1/1)');
+  });
+
+  it('WIP đầy vẫn cho reorder TRONG cột (count không đổi)', () => {
+    const onCardMove = vi.fn();
+    render(
+      <KanbanBoard
+        columns={[
+          {
+            key: 'a',
+            title: 'Todo',
+            wipLimit: 3,
+            cards: [
+              { key: 't1', title: 'Task 1' },
+              { key: 't2', title: 'Task 2' },
+              { key: 't3', title: 'Task 3' },
+            ],
+          },
+        ]}
+        onCardMove={onCardMove}
+      />,
+    );
+    dragTo('t1', 'Task 3');
+    expect(onCardMove).toHaveBeenCalledWith('t1', 'a', 'a', 1);
+  });
+
+  it('move thành công → aria-live "Đã chuyển … tới cột …, vị trí …"', () => {
+    render(<KanbanBoard columns={COLS} onCardMove={vi.fn()} />);
+    dragTo('t1', 'Task 3');
+    expect(liveRegion()).toHaveTextContent('Đã chuyển "Task 1" tới cột "Doing", vị trí 1.');
+  });
+});
+
+describe('KanbanBoard keyboard', () => {
+  it('Space nhặt → ArrowRight đổi cột → Enter thả → onCardMove + aria-live', async () => {
+    const user = userEvent.setup();
+    const onCardMove = vi.fn();
+    render(<KanbanBoard columns={COLS} onCardMove={onCardMove} />);
+    await user.tab(); // card đầu (t1)
+    await user.keyboard('{Space}');
+    expect(screen.getByRole('button', { name: 'Task 1', pressed: true })).toBeInTheDocument();
+    await user.keyboard('{ArrowRight}'); // sang cột Doing
+    await user.keyboard('{Enter}');
+    expect(onCardMove).toHaveBeenCalledWith('t1', 'a', 'b', 0);
+    expect(liveRegion()).toHaveTextContent('Đã chuyển "Task 1" tới cột "Doing", vị trí 1.');
+    expect(screen.getByRole('button', { name: 'Task 1', pressed: false })).toBeInTheDocument();
+  });
+
+  it('Space → ArrowDown đổi vị trí trong cột → Enter', async () => {
+    const user = userEvent.setup();
+    const onCardMove = vi.fn();
+    render(
+      <KanbanBoard
+        columns={[
+          {
+            key: 'a',
+            title: 'Todo',
+            cards: [
+              { key: 't1', title: 'Task 1' },
+              { key: 't2', title: 'Task 2' },
+              { key: 't3', title: 'Task 3' },
+            ],
+          },
+        ]}
+        onCardMove={onCardMove}
+      />,
+    );
+    await user.tab();
+    await user.keyboard('{Space}');
+    await user.keyboard('{ArrowDown}{ArrowDown}{ArrowDown}'); // index 3 = append cuối
+    await user.keyboard('{Enter}');
+    expect(onCardMove).toHaveBeenCalledWith('t1', 'a', 'a', 2);
+  });
+
+  it('Esc hủy — Enter sau đó không bắn onCardMove', async () => {
+    const user = userEvent.setup();
+    const onCardMove = vi.fn();
+    render(<KanbanBoard columns={COLS} onCardMove={onCardMove} />);
+    await user.tab();
+    await user.keyboard('{Space}');
+    await user.keyboard('{Escape}');
+    expect(screen.getByRole('button', { name: 'Task 1', pressed: false })).toBeInTheDocument();
+    await user.keyboard('{Enter}');
+    expect(onCardMove).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,58 @@
+// Knob — dial value (antd lite): circular indicator + drag.
+// A11y (batch ⑫ worker C): role=slider + Arrow keys (±1, clamp min/max) —
+// trước đây chỉ drag chuột, keyboard không với tới.
+import { useCallback, useRef, type KeyboardEvent } from 'react';
+
+export interface KnobProps {
+  value?: number;
+  onChange?: (v: number) => void;
+  min?: number;
+  max?: number;
+  size?: number;
+  /** aria-label cho role=slider (mặc định 'Điều khiển giá trị'). */
+  ariaLabel?: string;
+  className?: string;
+}
+
+export function Knob({ value = 0, onChange, min = 0, max = 100, size = 96, ariaLabel = 'Điều khiển giá trị', className }: KnobProps) {
+  const ref = useRef<SVGSVGElement>(null);
+  const r = size / 2 - 8;
+  const c = size / 2;
+  const circumference = 2 * Math.PI * r;
+  const arc = (270 / 360) * circumference;
+
+  const onDrag = useCallback((clientX: number, clientY: number) => {
+    const rect = ref.current?.getBoundingClientRect();
+    if (!rect) return;
+    const cx = rect.left + rect.width / 2, cy = rect.top + rect.height / 2;
+    let deg = (Math.atan2(clientY - cy, clientX - cx) * 180) / Math.PI + 90;
+    if (deg > 135) deg -= 360;
+    const pct = Math.min(100, Math.max(0, ((deg + 135) / 270) * 100));
+    onChange?.(Math.round(min + (pct / 100) * (max - min)));
+  }, [min, max, onChange]);
+
+  const onKeyDown = (e: KeyboardEvent<SVGSVGElement>) => {
+    const step = e.key === 'ArrowUp' || e.key === 'ArrowRight' ? 1 : e.key === 'ArrowDown' || e.key === 'ArrowLeft' ? -1 : 0;
+    if (!step) return;
+    e.preventDefault();
+    onChange?.(Math.min(max, Math.max(min, value + step)));
+  };
+
+  return (
+    <svg ref={ref} width={size} height={size} viewBox={`0 0 ${size} ${size}`}
+      role="slider" aria-label={ariaLabel} aria-valuemin={min} aria-valuemax={max} aria-valuenow={value} tabIndex={0}
+      onKeyDown={onKeyDown}
+      className={`cursor-grab active:cursor-grabbing${className ? ` ${className}` : ''}`}
+      onMouseDown={(e) => { const move = (me: MouseEvent) => onDrag(me.clientX, me.clientY); const up = () => { window.removeEventListener('mousemove', move); window.removeEventListener('mouseup', up); }; window.addEventListener('mousemove', move); window.addEventListener('mouseup', up); onDrag(e.clientX, e.clientY); }}>
+      <circle cx={c} cy={c} r={r} fill="none" stroke="var(--line2)" strokeWidth="6"
+        strokeDasharray={`${arc} ${circumference}`} strokeLinecap="round"
+        transform={`rotate(135 ${c} ${c})`} />
+      <circle cx={c} cy={c} r={r} fill="none" stroke="var(--accent)" strokeWidth="6"
+        strokeDasharray={`${(pct(value) / 100) * arc} ${circumference}`} strokeLinecap="round"
+        transform={`rotate(135 ${c} ${c})`} />
+      <text x={c} y={c + 6} textAnchor="middle" fill="var(--ink)" fontSize={size * 0.18} fontWeight="600">{value}</text>
+    </svg>
+  );
+}
+
+function pct(v: number) { return v; }

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

@@ -0,0 +1,49 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Knob } from './index';
+
+const meta = { title: 'Forms/Knob', component: Knob, tags: ['autodocs'] } satisfies Meta<typeof Knob>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+/** Basic — dial at 40/100; drag the ring or focus + arrow keys (±1). */
+export const Basic: S = { args: { value: 40, ariaLabel: 'Volume' } };
+
+/** MinMax — dial over a [20, 80] window (range maps to the 270° arc). */
+export const MinMax: S = { name: 'Min/Max — 270° arc over [20, 80]', args: { value: 50, min: 20, max: 80, ariaLabel: 'Threshold' } };
+
+/** Sizes — 64 / 96 (default) / 128 px. */
+export const Sizes: S = {
+  name: 'Sizes — 64 / 96 / 128',
+  render: () => (
+    <div className="flex items-center gap-6">
+      <Knob value={30} size={64} ariaLabel="Small knob" />
+      <Knob value={60} ariaLabel="Middle knob" />
+      <Knob value={90} size={128} ariaLabel="Large knob" />
+    </div>
+  ),
+};
+
+/** Controlled — drag / arrow keys → value shown below. */
+export const Controlled: S = {
+  render: () => <KnobControlledDemo />,
+};
+
+/** DarkTheme — ring + label on dark canvas. */
+export const DarkTheme: S = {
+  render: () => (
+    <div data-bp-theme="dark" className="w-fit rounded-xl bg-canvas p-4">
+      <Knob value={75} ariaLabel="Dark knob" />
+    </div>
+  ),
+};
+
+function KnobControlledDemo() {
+  const [v, setV] = useState(40);
+  return (
+    <div className="grid max-w-[160px] gap-2 justify-items-center">
+      <Knob value={v} onChange={setV} ariaLabel="Controlled knob" />
+      <p className="m-0 font-mono text-meta text-ink3">value: <strong className="text-ink">{v}</strong></p>
+    </div>
+  );
+}

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

@@ -0,0 +1,42 @@
+// Knob tests — role=slider aria + keyboard ±1 clamp (drag cần mousemove trên window,
+// jsdom không layout — chỉ assert listener gắn được qua mousedown không crash).
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Knob } from './index.js';
+
+afterEach(cleanup);
+
+describe('Knob', () => {
+  it('role=slider + aria valuemin/max/now + label', () => {
+    render(<Knob value={40} min={0} max={100} ariaLabel="Volume" />);
+    const knob = screen.getByRole('slider', { name: 'Volume' });
+    expect(knob).toHaveAttribute('aria-valuemin', '0');
+    expect(knob).toHaveAttribute('aria-valuemax', '100');
+    expect(knob).toHaveAttribute('aria-valuenow', '40');
+  });
+
+  it('ArrowUp → onChange(value+1); ArrowDown → value-1', async () => {
+    const onChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Knob value={40} onChange={onChange} ariaLabel="K" />);
+    const knob = screen.getByRole('slider', { name: 'K' });
+    await user.type(knob, '{ArrowUp}');
+    expect(onChange).toHaveBeenLastCalledWith(41);
+    await user.type(knob, '{ArrowDown}');
+    expect(onChange).toHaveBeenLastCalledWith(39);
+  });
+
+  it('clamp tại max: ArrowUp trên value=max → onChange(max)', async () => {
+    const onChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Knob value={100} max={100} onChange={onChange} ariaLabel="C" />);
+    await user.type(screen.getByRole('slider', { name: 'C' }), '{ArrowUp}');
+    expect(onChange).toHaveBeenCalledWith(100);
+  });
+
+  it('default aria-label tiếng Việt khi không truyền', () => {
+    render(<Knob value={10} />);
+    expect(screen.getByRole('slider', { name: 'Điều khiển giá trị' })).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,145 @@
+// Layout — composition shell kiểu antd: Layout/Header/Content/Footer/Sider.
+// Root <section> flex-col (nested Layout tự thành cột trong hàng khi hasSider);
+// hasSider: prop THẮNG, thiếu → dò Layout.Sider con trực tiếp (sync lúc render,
+// không nhảy layout sau mount — Sider bọc trong Fragment thì truyền hasSider thủ công).
+// Sider: zone flex-none, width mirror controlled `collapsed` (đồng bộ collapse
+// CỦA <Sidebar> đặt trong children qua onToggle của nó — Sidebar tự giữ trigger
+// pill + width 200↔80, Sider chỉ theo kèm nên không double trigger); cấp
+// SiderContext cho con cháu (useSiderCollapsed) để label/menu tự co.
+// a11y landmark EXPLICIT vì zone nằm trong <section> (implicit role bị scope
+// mất): Header role="banner" · Content <main> · Footer role="contentinfo";
+// Sider là div zone thuần — landmark complementary do <Sidebar> trong children
+// đảm nhiệm (tránh nested <aside> trùng landmark).
+// Sticky header z-10 theo idiom Table (sticky in-flow, không thuộc overlay scale
+// --z-*); motion: Sider transition width 200ms ease-out (đồng bộ Sidebar).
+// Tokens-only: root bg-canvas (colorBgLayout antd), zones bg-s1 — không hex.
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  type FunctionComponent,
+  type ReactNode,
+} from 'react';
+
+export interface LayoutProps {
+  /** Ép hàng ngang (Sider trái + khối nội dung phải). Thiếu → tự dò Layout.Sider con trực tiếp. */
+  hasSider?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+export interface LayoutHeaderProps {
+  /** Bám đỉnh viewport khi cuộn (sticky top-0). */
+  sticky?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+export interface LayoutContentProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+export interface LayoutFooterProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+export interface LayoutSiderProps {
+  /** Bề ngang zone khi KHÔNG collapsed (mặc định 200 — khớp Sidebar). */
+  width?: number | string;
+  /** Controlled: true → thu về collapsedWidth. Đồng bộ với Sidebar qua onToggle của nó. */
+  collapsed?: boolean;
+  /** Bề ngang khi collapsed (mặc định 80 — khớp Sidebar icon-only). */
+  collapsedWidth?: number | string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const SiderContext = createContext<{ collapsed: boolean }>({ collapsed: false });
+
+/** collapsed hiện tại của Layout.Sider bao ngoài (false nếu không trong Sider). */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useSiderCollapsed(): boolean {
+  return useContext(SiderContext).collapsed;
+}
+
+function LayoutSider({
+  width = 200,
+  collapsed = false,
+  collapsedWidth = 80,
+  className,
+  children,
+}: LayoutSiderProps) {
+  return (
+    <SiderContext.Provider value={{ collapsed }}>
+      <div
+        style={{ width: collapsed ? collapsedWidth : width }}
+        className={`flex-none overflow-hidden bg-s1 transition-[width] duration-200 ease-out${className ? ` ${className}` : ''}`}
+      >
+        {children}
+      </div>
+    </SiderContext.Provider>
+  );
+}
+
+function LayoutHeader({ sticky = false, className, children }: LayoutHeaderProps) {
+  return (
+    <header
+      role="banner"
+      className={`flex h-16 flex-none items-center gap-3 border-b border-line bg-s1 px-4${sticky ? ' sticky top-0 z-10' : ''}${className ? ` ${className}` : ''}`}
+    >
+      {children}
+    </header>
+  );
+}
+
+function LayoutContent({ className, children }: LayoutContentProps) {
+  return (
+    <main
+      role="main"
+      className={`flex min-h-0 flex-auto flex-col${className ? ` ${className}` : ''}`}
+    >
+      {children}
+    </main>
+  );
+}
+
+function LayoutFooter({ className, children }: LayoutFooterProps) {
+  return (
+    <footer
+      role="contentinfo"
+      className={`flex flex-none items-center justify-center border-t border-line bg-s1 px-4 py-5 text-center text-meta text-ink3${className ? ` ${className}` : ''}`}
+    >
+      {children}
+    </footer>
+  );
+}
+
+export interface LayoutComponent extends FunctionComponent<LayoutProps> {
+  Header: FunctionComponent<LayoutHeaderProps>;
+  Content: FunctionComponent<LayoutContentProps>;
+  Footer: FunctionComponent<LayoutFooterProps>;
+  Sider: FunctionComponent<LayoutSiderProps>;
+}
+
+export const Layout = (({ hasSider, className, children }: LayoutProps) => {
+  // Auto-detect Sider con TRỰC TIẾP (đồng bộ lúc render); prop hasSider thắng.
+  const detectSider = Children.toArray(children).some(
+    (child) => isValidElement(child) && child.type === LayoutSider,
+  );
+  const row = hasSider ?? detectSider;
+  return (
+    <section
+      className={`flex min-h-0 flex-auto bg-canvas ${row ? 'flex-row' : 'flex-col'}${className ? ` ${className}` : ''}`}
+    >
+      {children}
+    </section>
+  );
+}) as LayoutComponent;
+
+Layout.Header = LayoutHeader;
+Layout.Content = LayoutContent;
+Layout.Footer = LayoutFooter;
+Layout.Sider = LayoutSider;