create-wakii-stack 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,392 @@
+// hooks-new.stories.tsx — demo tương tác cho 12 hooks wave mới (PR #65), bỗ
+// tríết lý "docs sống" của kit (khác hooks.stories.tsx: 16 hooks native đầu).
+// MỖI demo là 1 export const story; import trực tiếp từng file (barrel do
+// coordinator thêm lúc commit). Title LỒNG 'Hooks/New Wave' — KHÔNG đè story
+// của hooks.stories.tsx (title 'Theming & Motion/Hooks'). Gom nhóm: lifecycle
+// trio 1 story, fullscreen + title 1 story → 9 stories / 12 hooks.
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useEffect, useRef, useState } from 'react';
+import { useControllableState } from './useControllableState.js';
+import { useEventListener } from './useEventListener.js';
+import { useFullscreen } from './useFullscreen.js';
+import { useInfiniteScroll } from './useInfiniteScroll.js';
+import { useInView } from './useInView.js';
+import { useIsFirstRender } from './useIsFirstRender.js';
+import { useMeasure } from './useMeasure.js';
+import { useMountEffect } from './useMountEffect.js';
+import { useOnlineStatus } from './useOnlineStatus.js';
+import { useScrollProgress } from './useScrollProgress.js';
+import { useTitle } from './useTitle.js';
+import { useUpdateEffect } from './useUpdateEffect.js';
+
+const meta = {
+  title: 'Theming & Motion/Hooks/New Wave',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '12 hooks from the new wave (PR #65): useMountEffect · useUpdateEffect · useIsFirstRender · useControllableState · useEventListener · useScrollProgress · useInView · useInfiniteScroll · useMeasure · useOnlineStatus · useFullscreen · useTitle. 9 interactive demos below — lifecycle trio and the fullscreen/title pair share one story each.',
+      },
+    },
+  },
+} satisfies Meta;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Demo dùng Tailwind token classes (bg-s*/text-ink*/border-line) — cùng ngôn
+// ngữ design system với component stories; mọi nút giữ chuẩn focus-visible ring.
+const demoBox = 'flex flex-col gap-2 text-body text-ink';
+const demoPanel = 'rounded-lg border border-line bg-s2 p-3';
+const demoBtn =
+  'cursor-pointer rounded-lg border border-line bg-s1 px-3 py-1.5 text-label text-ink2 transition-colors hover:border-accent-hi hover:text-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40';
+const demoMono = 'font-mono text-meta text-ink2';
+const demoBadge = (on: boolean) =>
+  `inline-flex w-fit items-center gap-1 rounded-pill border px-2.5 py-1 text-meta font-semibold ${
+    on ? 'border-st-done text-st-done' : 'border-line text-ink3'
+  }`;
+const demoInput =
+  'h-8 rounded-lg border border-line bg-s2 px-3 text-body text-ink placeholder:text-ink4 focus:border-accent-hi focus:outline-none';
+
+/** Mount / update / first-render — bấm để xem hiệu chạy đúng mốc nào. */
+function LifecycleTrioDemo() {
+  const [renders, setRenders] = useState(1);
+  const [dep, setDep] = useState(0);
+  const [log, setLog] = useState<string[]>([]);
+  const isFirst = useIsFirstRender();
+  const push = (line: string) => setLog((l) => [...l.slice(-7), line]);
+
+  useMountEffect(() => push('useMountEffect → ran once on mount'));
+  useUpdateEffect(() => push(`useUpdateEffect → dep = ${dep} (mount was skipped)`), [dep]);
+
+  return (
+    <div className={demoBox}>
+      <div className="flex flex-wrap items-center gap-2">
+        <span className={demoBadge(isFirst)}>first render: {String(isFirst)}</span>
+        <span className={demoMono}>renders: {renders}</span>
+        <button type="button" className={demoBtn} onClick={() => setRenders((r) => r + 1)}>
+          Re-render
+        </button>
+        <button type="button" className={demoBtn} onClick={() => setDep((d) => d + 1)}>
+          Bump update-effect dep
+        </button>
+      </div>
+      <div className={demoPanel}>
+        <ul className="m-0 flex max-h-32 list-none flex-col gap-1 overflow-y-auto p-0">
+          {log.map((line, i) => (
+            <li key={`${i}-${line}`} className={demoMono}>
+              {line}
+            </li>
+          ))}
+        </ul>
+      </div>
+      <div className={demoMono}>
+        Tip: “Re-render” bumps the count but logs nothing — useUpdateEffect only reacts to its deps.
+      </div>
+    </div>
+  );
+}
+
+export const LifecycleTrio: Story = {
+  name: 'Lifecycle trio (useMountEffect · useUpdateEffect · useIsFirstRender)',
+  render: () => <LifecycleTrioDemo />,
+};
+
+/** Controlled/uncontrolled — đổi chế độ sống để thấy quyền sở hữu state chuyển tay. */
+function ControllableStateDemo() {
+  const [mode, setMode] = useState<'uncontrolled' | 'controlled'>('uncontrolled');
+  const [callerValue, setCallerValue] = useState(1);
+  const [changes, setChanges] = useState<string[]>([]);
+  const [value, set] = useControllableState<number>({
+    value: mode === 'controlled' ? callerValue : undefined,
+    defaultValue: 1,
+    onChange: (v) => setChanges((c) => [...c.slice(-4), `onChange → ${v}`]),
+  });
+
+  return (
+    <div className={demoBox}>
+      <div className="flex flex-wrap items-center gap-2">
+        <span className={demoBadge(mode === 'controlled')}>mode: {mode}</span>
+        <span className={demoMono}>value: {value}</span>
+        <button type="button" className={demoBtn} onClick={() => setMode((m) => (m === 'controlled' ? 'uncontrolled' : 'controlled'))}>
+          Switch mode
+        </button>
+        <button type="button" className={demoBtn} onClick={() => set((v) => v + 1)}>
+          Component set +1
+        </button>
+        <button type="button" className={demoBtn} disabled={mode !== 'controlled'} onClick={() => setCallerValue((v) => v + 10)}>
+          Caller set +10
+        </button>
+      </div>
+      <div className={demoPanel}>
+        {changes.length === 0 ? (
+          <span className={demoMono}>onChange not fired yet</span>
+        ) : (
+          changes.map((line, i) => (
+            <div key={`${i}-${line}`} className={demoMono}>
+              {line}
+            </div>
+          ))
+        )}
+      </div>
+      <div className={demoMono}>
+        Controlled mode: “Component set +1” only fires onChange — the value moves when the caller moves it.
+      </div>
+    </div>
+  );
+}
+
+export const ControllableState: Story = {
+  name: 'useControllableState',
+  render: () => <ControllableStateDemo />,
+};
+
+/** Event listener — listener trên window (keydown) + element ref (click). */
+function EventListenerDemo() {
+  const [keyCount, setKeyCount] = useState(0);
+  const [lastKey, setLastKey] = useState('—');
+  const [clickCount, setClickCount] = useState(0);
+  const zoneRef = useRef<HTMLDivElement>(null);
+
+  useEventListener('keydown', (e) => {
+    setKeyCount((c) => c + 1);
+    setLastKey((e as KeyboardEvent).key);
+  });
+  useEventListener('click', () => setClickCount((c) => c + 1), zoneRef);
+
+  return (
+    <div className={demoBox}>
+      <div
+        ref={zoneRef}
+        className="grid h-20 cursor-pointer place-items-center rounded-lg border border-dashed border-line bg-s1 text-label text-ink2 select-none hover:border-accent-hi hover:text-accent"
+      >
+        Click me — this zone listens via an element ref ({clickCount} clicks)
+      </div>
+      <div className={demoMono}>
+        Keydown anywhere in the canvas: {keyCount} keys pressed, last key “{lastKey}”
+      </div>
+    </div>
+  );
+}
+
+export const EventListener: Story = {
+  name: 'useEventListener',
+  render: () => <EventListenerDemo />,
+};
+
+/** Scroll progress — cuộn canvas story, thanh % bám theo tiến độ trang. */
+function ScrollProgressDemo() {
+  const progress = useScrollProgress();
+
+  return (
+    <div className={demoBox}>
+      <div className={demoMono}>Page scroll progress: {Math.round(progress * 100)}%</div>
+      <div className="h-2 w-full overflow-hidden rounded-pill bg-s3">
+        <div className="h-full rounded-pill bg-accent transition-[width] duration-150 ease-out" style={{ width: `${progress * 100}%` }} />
+      </div>
+      <div className="grid h-48 place-items-center rounded-lg border border-dashed border-line text-meta text-ink4">
+        Scroll the story canvas up and down ↑↓
+      </div>
+    </div>
+  );
+}
+
+export const ScrollProgress: Story = {
+  name: 'useScrollProgress',
+  render: () => <ScrollProgressDemo />,
+};
+
+/** In view — hộp đổi màu theo viewport; bật/tắt `once` để xem đảo 2 chiều. */
+function InViewDemo() {
+  const [once, setOnce] = useState(false);
+  const { ref, inView } = useInView<HTMLDivElement>({ once });
+
+  return (
+    <div className={demoBox}>
+      <div className="flex flex-wrap items-center gap-2">
+        <span className={demoBadge(inView)}>inView: {String(inView)}</span>
+        <button type="button" className={demoBtn} onClick={() => setOnce((o) => !o)}>
+          once: {String(once)}
+        </button>
+      </div>
+      <div className="h-40 overflow-y-auto rounded-lg border border-line bg-s1 p-2">
+        <div className="h-32" />
+        <div
+          ref={ref}
+          className={`grid h-16 place-items-center rounded-lg border text-meta transition-colors duration-200 ${
+            inView ? 'border-st-done bg-st-done/10 text-st-done' : 'border-line bg-s3 text-ink3'
+          }`}
+        >
+          {inView ? 'In view' : 'Scroll me into view ↓'}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export const InView: Story = {
+  name: 'useInView',
+  render: () => <InViewDemo />,
+};
+
+/** Infinite scroll — cuộn tới sentinel là list tự dài (loading guard + hasMore). */
+function InfiniteScrollDemo() {
+  const [items, setItems] = useState<number[]>(() => Array.from({ length: 8 }, (_, i) => i + 1));
+  const [loading, setLoading] = useState(false);
+  const [hasMore, setHasMore] = useState(true);
+  const sentinelRef = useInfiniteScroll<HTMLDivElement>({
+    disabled: !hasMore,
+    onLoadMore: async () => {
+      setLoading(true);
+      await new Promise((r) => setTimeout(r, 500));
+      setItems((prev) => [...prev, ...Array.from({ length: 4 }, (_, i) => prev.length + i + 1)]);
+      setLoading(false);
+    },
+  });
+
+  return (
+    <div className={demoBox}>
+      <div className="flex items-center gap-2">
+        <span className={demoBadge(hasMore)}>{items.length} items</span>
+        <button type="button" className={demoBtn} onClick={() => setHasMore((h) => !h)}>
+          {hasMore ? 'Simulate end of data' : 'Re-enable loading'}
+        </button>
+      </div>
+      <div className="flex h-40 list-none flex-col gap-1 overflow-y-auto rounded-lg border border-line bg-s1 p-2">
+        {items.map((n) => (
+          <div key={n} className={`${demoPanel} !py-1.5`}>
+            Item #{n}
+          </div>
+        ))}
+        {loading && <div className={`${demoMono} px-1`}>Loading…</div>}
+        <div ref={sentinelRef} className="h-1" />
+      </div>
+      <div className={demoMono}>Scroll the list to the bottom — the sentinel triggers onLoadMore.</div>
+    </div>
+  );
+}
+
+export const InfiniteScroll: Story = {
+  name: 'useInfiniteScroll',
+  render: () => <InfiniteScrollDemo />,
+};
+
+/** Measure — kéo góc phải-dưới box, kích thước cập nhật realtime qua ResizeObserver. */
+function MeasureDemo() {
+  const [ref, size] = useMeasure<HTMLDivElement>();
+
+  return (
+    <div className={demoBox}>
+      <div
+        ref={ref}
+        className="grid min-h-14 min-w-32 max-w-full resize place-items-center overflow-auto rounded-lg border border-dashed border-line bg-s1 p-3 text-label text-ink2"
+        style={{ height: 72, width: 260 }}
+      >
+        Drag my bottom-right corner ↘
+      </div>
+      <div className={demoMono}>
+        Measured: {Math.round(size.width)} × {Math.round(size.height)}px
+      </div>
+    </div>
+  );
+}
+
+export const Measure: Story = {
+  name: 'useMeasure',
+  render: () => <MeasureDemo />,
+};
+
+/** Online status — badge trạng thái mạng + nút giả lập (stub navigator.onLine, tự khôi phục). */
+function OnlineStatusDemo() {
+  const online = useOnlineStatus();
+  const [stubbed, setStubbed] = useState(false);
+  const originalRef = useRef<boolean | null>(null);
+
+  const simulate = (next: boolean) => {
+    if (originalRef.current === null) originalRef.current = navigator.onLine;
+    Object.defineProperty(navigator, 'onLine', { value: next, configurable: true });
+    setStubbed(true);
+    window.dispatchEvent(new Event(next ? 'online' : 'offline'));
+  };
+  const restore = () => {
+    const orig = originalRef.current;
+    if (orig === null) return;
+    Object.defineProperty(navigator, 'onLine', { value: orig, configurable: true });
+    originalRef.current = null;
+    setStubbed(false);
+    window.dispatchEvent(new Event(orig ? 'online' : 'offline'));
+  };
+  // Rời story → trả navigator.onLine về giá trị thật (đừng để stub dính lại canvas khác)
+  useEffect(() => () => restore(), []);
+
+  return (
+    <div className={demoBox}>
+      <div className="flex flex-wrap items-center gap-2">
+        <span className={demoBadge(online)}>{online ? '● Online' : '○ Offline'}</span>
+        {stubbed && <span className={demoMono}>(simulated)</span>}
+        <button type="button" className={demoBtn} disabled={!online} onClick={() => simulate(false)}>
+          Simulate offline
+        </button>
+        <button type="button" className={demoBtn} disabled={online} onClick={() => simulate(true)}>
+          Simulate online
+        </button>
+        <button type="button" className={demoBtn} disabled={!stubbed} onClick={restore}>
+          Restore real value
+        </button>
+      </div>
+      <div className={demoMono}>Real use case: banner “mất kết nối” — the hook mirrors navigator.onLine via window online/offline events.</div>
+    </div>
+  );
+}
+
+export const OnlineStatus: Story = {
+  name: 'useOnlineStatus',
+  render: () => <OnlineStatusDemo />,
+};
+
+/** Fullscreen + title — 2 hook "document chrome": fullscreen 1 khung & đổi tiêu đề tab. */
+function FullscreenTitleDemo() {
+  const { ref, isFullscreen, toggle } = useFullscreen();
+  const [title, setTitle] = useState('New wave hooks demo');
+  useTitle(title);
+
+  return (
+    <div className={demoBox}>
+      <div
+        ref={ref}
+        className={`grid h-24 place-items-center rounded-lg border text-label transition-colors duration-200 ${
+          isFullscreen ? 'border-accent bg-accent/10 text-accent' : 'border-line bg-s1 text-ink2'
+        }`}
+      >
+        {isFullscreen ? 'Fullscreen — press ESC to exit' : 'Regular frame'}
+      </div>
+      <div className="flex flex-wrap items-center gap-2">
+        <button type="button" className={demoBtn} onClick={toggle}>
+          {isFullscreen ? 'Exit fullscreen' : 'Go fullscreen'}
+        </button>
+        <span className={demoBadge(isFullscreen)}>isFullscreen: {String(isFullscreen)}</span>
+      </div>
+      <div className="h-px bg-line" role="presentation" />
+      <div className="flex flex-wrap items-center gap-2">
+        <label className={demoMono} htmlFor="hooks-new-title-input">
+          document.title
+        </label>
+        <input
+          id="hooks-new-title-input"
+          className={`${demoInput} w-64`}
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+        />
+      </div>
+      <div className={demoMono}>
+        Watch the browser tab while typing — leaving this story restores the previous title (restoreOnUnmount default).
+      </div>
+    </div>
+  );
+}
+
+export const FullscreenTitle: Story = {
+  name: 'useFullscreen + useTitle',
+  render: () => <FullscreenTitleDemo />,
+};

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

@@ -0,0 +1,167 @@
+// hooks.stories.tsx — section 'Hooks' demo tương tác cho bộ 16 hooks native (spec usehooks.com,
+// tham chiếu MIT ui.dev). MỖI demo là 1 export const story; import trực tiếp từng file
+// (barrel src/index.ts do coordinator thêm lúc commit — worker không sửa).
+// Các hook không có demo ở đây (storage/toggle/previous/default/throttle/timeout/clickAway/
+// hover/keyPress/lockBodyScroll) xem test behavior kèm từng file.
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { CSSProperties } from 'react';
+import { useState } from 'react';
+import { useCopyToClipboard } from './useCopyToClipboard.js';
+import { useCountdown } from './useCountdown.js';
+import { useDebounce } from './useDebounce.js';
+import { useMediaQuery } from './useMediaQuery.js';
+import { useWindowSize } from './useWindowSize.js';
+
+const meta = {
+  title: 'Theming & Motion/Hooks',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '16 hooks native: useLocalStorage · useSessionStorage · useToggle · usePrevious · useDefault · useDebounce · useThrottle · useTimeout · useCountdown · useClickAway · useHover · useKeyPress · useMediaQuery · useLockBodyScroll · useWindowSize · useCopyToClipboard. 5 demo tương tác bên dưới — còn lại xem test behavior colocated.',
+      },
+    },
+  },
+} satisfies Meta;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Demo dùng element thuần + inline style — không phụ thuộc theme/provider của Storybook
+const demoBox: CSSProperties = { display: 'grid', gap: 10, maxWidth: 420, fontFamily: 'sans-serif' };
+const demoInput: CSSProperties = {
+  padding: '8px 12px',
+  borderRadius: 8,
+  border: '1px solid #d0d5dd',
+  fontSize: 14,
+};
+const demoButton: CSSProperties = {
+  padding: '6px 14px',
+  borderRadius: 8,
+  border: '1px solid #d0d5dd',
+  background: '#fff',
+  color: '#344054',
+  cursor: 'pointer',
+  fontSize: 14,
+};
+const demoButtonActive: CSSProperties = { ...demoButton, background: '#eef4ff', borderColor: '#84adff' };
+const demoMono: CSSProperties = { fontFamily: 'ui-monospace, monospace', fontSize: 13, color: '#475467' };
+const demoBadge = (on: boolean): CSSProperties => ({
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 6,
+  padding: '4px 12px',
+  borderRadius: 999,
+  border: `1px solid ${on ? '#12b76a' : '#d0d5dd'}`,
+  color: on ? '#067647' : '#667085',
+  fontSize: 13,
+  fontWeight: 600,
+});
+
+/** Debounce input live — gõ liên tục, giá trị "Debounced" chỉ nhảy sau 300ms ngừng gõ. */
+function DebounceDemo() {
+  const [text, setText] = useState('');
+  const debounced = useDebounce(text, 300);
+
+  return (
+    <div style={demoBox}>
+      <input
+        style={demoInput}
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        placeholder="Gõ thử… (debounce 300ms)"
+      />
+      <div style={demoMono}>Trực tiếp: {text || '—'}</div>
+      <div style={demoMono}>Debounced: {debounced || '—'}</div>
+    </div>
+  );
+}
+
+export const Debounce: Story = {
+  name: 'useDebounce',
+  render: () => <DebounceDemo />,
+};
+
+/** Countdown — bấm Start/Stop/Reset, đếm tới 0 tự dừng. */
+function CountdownDemo() {
+  const { seconds, isRunning, start, stop, reset } = useCountdown(10);
+
+  return (
+    <div style={demoBox}>
+      <div style={{ fontSize: 40, fontWeight: 700, fontVariantNumeric: 'tabular-nums' }}>{seconds}s</div>
+      <div style={{ display: 'flex', gap: 8 }}>
+        <button type="button" style={isRunning ? demoButtonActive : demoButton} onClick={start} disabled={isRunning}>
+          Start
+        </button>
+        <button type="button" style={demoButton} onClick={stop} disabled={!isRunning}>
+          Stop
+        </button>
+        <button type="button" style={demoButton} onClick={reset}>
+          Reset
+        </button>
+      </div>
+      <div style={demoMono}>isRunning: {String(isRunning)}</div>
+    </div>
+  );
+}
+
+export const Countdown: Story = {
+  name: 'useCountdown',
+  render: () => <CountdownDemo />,
+};
+
+/** Clipboard copy — bấm copy rồi dán ra đâu đó để kiểm tra. */
+function ClipboardDemo() {
+  const [copiedText, copy] = useCopyToClipboard();
+
+  return (
+    <div style={demoBox}>
+      <button type="button" style={demoButton} onClick={() => void copy('Xin chào từ useCopyToClipboard! 🎉')}>
+        Copy văn bản mẫu
+      </button>
+      <div style={demoMono}>{copiedText ? `Đã copy: ${copiedText}` : 'Chưa copy gì'}</div>
+    </div>
+  );
+}
+
+export const CopyToClipboard: Story = {
+  name: 'useCopyToClipboard',
+  render: () => <ClipboardDemo />,
+};
+
+/** Media query badge — badge sống theo viewport (resize canvas) + color scheme hệ thống. */
+function MediaQueryDemo() {
+  const isDesktop = useMediaQuery('(min-width: 768px)');
+  const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
+
+  return (
+    <div style={{ ...demoBox, gridAutoFlow: 'column', justifyContent: 'start' }}>
+      <span style={demoBadge(isDesktop)}>viewport ≥ 768px: {isDesktop ? 'ĐÚNG' : 'SAI'}</span>
+      <span style={demoBadge(prefersDark)}>prefers dark: {prefersDark ? 'ĐÚNG' : 'SAI'}</span>
+    </div>
+  );
+}
+
+export const MediaQuery: Story = {
+  name: 'useMediaQuery',
+  render: () => <MediaQueryDemo />,
+};
+
+/** Window size — resize cửa sổ/canvas để xem width × height cập nhật realtime. */
+function WindowSizeDemo() {
+  const { width, height } = useWindowSize();
+
+  return (
+    <div style={{ ...demoBox, gridAutoFlow: 'column', justifyContent: 'start' }}>
+      <div style={{ ...demoMono, fontSize: 16, color: '#101828' }}>
+        window: {width} × {height}px
+      </div>
+    </div>
+  );
+}
+
+export const WindowSize: Story = {
+  name: 'useWindowSize',
+  render: () => <WindowSizeDemo />,
+};

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

@@ -0,0 +1,63 @@
+// Tests useClickAway — fireEvent mousedown NGOÀI / TRONG (spec worker B).
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useClickAway } from './useClickAway.js';
+
+function Box({ onClickAway }: { onClickAway: (event: MouseEvent | TouchEvent) => void }) {
+  const ref = useClickAway<HTMLDivElement>(onClickAway);
+  return (
+    <div>
+      <div ref={ref} data-testid="inside" />
+      <div data-testid="outside" />
+    </div>
+  );
+}
+
+afterEach(cleanup);
+
+describe('useClickAway', () => {
+  it('mousedown NGOÀI → gọi handler; TRONG → không gọi', () => {
+    const handler = vi.fn();
+    render(<Box onClickAway={handler} />);
+
+    fireEvent.mouseDown(screen.getByTestId('inside'));
+    expect(handler).not.toHaveBeenCalled();
+
+    fireEvent.mouseDown(screen.getByTestId('outside'));
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler.mock.calls[0][0]).toBeInstanceOf(MouseEvent);
+  });
+
+  it('mousedown trên chính phần tử ref (không phải con) → không gọi', () => {
+    const handler = vi.fn();
+    render(<Box onClickAway={handler} />);
+
+    // 'inside' chính là element mang ref — contains(target) với target === el
+    fireEvent.mouseDown(screen.getByTestId('inside'), { detail: 1 });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('touchstart NGOÀI cũng kích hoạt (mobile)', () => {
+    const handler = vi.fn();
+    render(<Box onClickAway={handler} />);
+
+    fireEvent.touchStart(screen.getByTestId('outside'));
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('unmount gỡ listener — không gọi nữa', () => {
+    const handler = vi.fn();
+    // phần tử "ngoài" đặt ngoài cây render — unmount remove cả cây Box thì nó vẫn còn
+    const outside = document.createElement('div');
+    document.body.appendChild(outside);
+    try {
+      const { unmount } = render(<Box onClickAway={handler} />);
+
+      unmount();
+      fireEvent.mouseDown(outside);
+      expect(handler).not.toHaveBeenCalled();
+    } finally {
+      outside.remove();
+    }
+  });
+});

package/stack-template/app/ui-kit/src/hooks/useClickAway.ts

@@ -0,0 +1,30 @@
+// useClickAway — kích hoạt handler khi mousedown/touchstart RA KHỎI element, pattern usehooks.com/ui.dev.
+// Trả về ref để gắn lên phần tử "bên trong" (dropdown/popover). Handler qua ref → không re-bind listener.
+import { useEffect, useRef } from 'react';
+
+type ClickAwayEvent = MouseEvent | TouchEvent;
+
+export function useClickAway<T extends HTMLElement>(handler: (event: ClickAwayEvent) => void) {
+  const ref = useRef<T | null>(null);
+  const handlerRef = useRef(handler);
+
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    const listener = (event: ClickAwayEvent) => {
+      const el = ref.current;
+      if (!el || el.contains(event.target as Node)) return; // click bên trong → bỏ qua
+      handlerRef.current(event);
+    };
+    document.addEventListener('mousedown', listener);
+    document.addEventListener('touchstart', listener);
+    return () => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    };
+  }, []);
+
+  return ref;
+}

package/stack-template/app/ui-kit/src/hooks/useControllableState.test.ts

@@ -0,0 +1,36 @@
+// Tests useControllableState — uncontrolled tự do, controlled theo props, cả hai đều bắn onChange.
+import { act, cleanup, renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useControllableState } from './useControllableState.js';
+
+afterEach(cleanup);
+
+describe('useControllableState', () => {
+  it('uncontrolled: defaultValue khởi tạo, set nội bộ cập nhật + bắn onChange', () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useControllableState<number>({ defaultValue: 10, onChange }));
+    expect(result.current[0]).toBe(10);
+    act(() => result.current[1](20));
+    expect(result.current[0]).toBe(20);
+    expect(onChange).toHaveBeenCalledWith(20);
+  });
+
+  it('controlled: value từ props thắng, set KHÔNG đổi state nội bộ — chỉ bắn onChange', () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(({ v }) => useControllableState<number>({ value: v, onChange }), {
+      initialProps: { v: 1 },
+    });
+    act(() => result.current[1](99));
+    expect(result.current[0]).toBe(1); // vẫn theo props — caller quyết định
+    expect(onChange).toHaveBeenCalledWith(99);
+    rerender({ v: 99 }); // caller áp dụng → UI đổi
+    expect(result.current[0]).toBe(99);
+  });
+
+  it('updater dạng hàm nhận prev đúng (uncontrolled)', () => {
+    const { result } = renderHook(() => useControllableState<number>({ defaultValue: 5 }));
+    act(() => result.current[1]((p) => p + 1));
+    act(() => result.current[1]((p) => p * 2));
+    expect(result.current[0]).toBe(12);
+  });
+});