create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,85 @@
+// useFieldArray — mảng động trong useForm (antd Form.List / RHF useFieldArray parity,
+// docs/parity-matrix.md Gap P0 "Form.List giá trị cao"). Path get/set dạng
+// `name.index.key`: get qua `fields[i]`, set qua `update(i, patch)`; input đặt
+// name qua `nameAt(i, key)` → focus-first-invalid của form.handleSubmit tự hoạt
+// động (querySelector `[name="emails.0.email"]`).
+// Sau MỖI op cấu trúc (append/remove/move/swap/update): nếu form ĐANG có errors,
+// rebuild toàn bộ errors từ snapshot values MỚI qua schema — lỗi tự dồn path đúng
+// khi row giữa bị xoá/dời (index dịch). Form sạch (chưa submit) không bị hiện
+// lỗi sớm. Mode 'onChange' của form vẫn validate riêng như cũ (vô hại với path con).
+// Lưu ý: 1 op mỗi event — op đọc `form.values` từ render hiện tại (hook thuần,
+// closure-based như useForm; gọi 2 op liên tiếp trong 1 handler → op sau thấy
+// state cũ, hãy gộp thành 1 op hoặc tách 2 event).
+import { collectErrors, type FormInstance } from './useForm.js';
+
+export interface FieldArrayHelpers<R extends object> {
+  /** Snapshot các row hiện tại — render `.map()`. */
+  fields: R[];
+  /** Số row hiện tại. */
+  count: number;
+  /** Push 1 row — giá trị mặc định do consumer cung cấp (antd Form.List add). */
+  append: (row: R) => void;
+  /** Xoá row theo index — errors dồn về path đúng sau khi index dịch. */
+  remove: (index: number) => void;
+  /** Chuyển row `from` tới vị trí `to` (insert-at, RHF semantics). */
+  move: (from: number, to: number) => void;
+  /** Đổi chỗ 2 row. */
+  swap: (a: number, b: number) => void;
+  /** Thay nội dung row i (shallow-merge patch) — set từng ô `name.i.key`. */
+  update: (index: number, patch: Partial<R>) => void;
+  /** name attribute cho input `key` của row i — khớp focus-first-invalid của form. */
+  nameAt: (index: number, key: keyof R & string) => string;
+}
+
+// R (kiểu row) truyền tường minh ở call site: useFieldArray<Form, 'emails', EmailRow>(...)
+// — TS check generic default eagerly nên không infer-conditional được cho constraint object.
+export function useFieldArray<F extends object, K extends keyof F & string, R extends object>(
+  form: FormInstance<F>,
+  name: K,
+): FieldArrayHelpers<R> {
+  const rows = ((form.values[name] as unknown) ?? []) as R[];
+  type Row = R;
+
+  /** Ghi mảng mới vào form + remap errors (khi đã có) từ snapshot mới. */
+  function apply(nextRows: Row[]) {
+    form.setValue(name, nextRows as F[K]);
+    if (Object.keys(form.errors).length > 0) {
+      const snapshot = { ...form.values, [name]: nextRows } as F;
+      const result = form.schema.safeParse(snapshot);
+      form.setErrors(result.success ? {} : collectErrors(result));
+    }
+  }
+
+  function append(row: Row) {
+    apply([...rows, row]);
+  }
+
+  function remove(index: number) {
+    if (index < 0 || index >= rows.length) return;
+    apply(rows.filter((_, i) => i !== index));
+  }
+
+  function move(from: number, to: number) {
+    if (from === to || from < 0 || to < 0 || from >= rows.length || to >= rows.length) return;
+    const next = [...rows];
+    const [item] = next.splice(from, 1);
+    next.splice(to, 0, item!);
+    apply(next);
+  }
+
+  function swap(a: number, b: number) {
+    if (a === b || a < 0 || b < 0 || a >= rows.length || b >= rows.length) return;
+    const next = [...rows];
+    [next[a], next[b]] = [next[b]!, next[a]!];
+    apply(next);
+  }
+
+  function update(index: number, patch: Partial<Row>) {
+    if (index < 0 || index >= rows.length) return;
+    apply(rows.map((r, i) => (i === index ? { ...r, ...patch } : r)));
+  }
+
+  const nameAt = (index: number, key: keyof Row & string) => `${name}.${index}.${key}`;
+
+  return { fields: rows, count: rows.length, append, remove, move, swap, update, nameAt };
+}

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

@@ -0,0 +1,67 @@
+// useFocusTrap — khoá focus trong container (modal/drawer, batch ⑫ worker C):
+// - kích hoạt: capture document.activeElement (trigger) → focus phần tử focusable đầu
+// - Tab/Shift+Tab: vòng trong container (querySelector focusable chuẩn WAI-ARIA)
+// - kết thúc (active=false): TRẢ FOCUS về trigger đã capture
+// Không dep ngoài. active nên = open && mounted (mounted=false do exit animation
+// chưa xong vẫn trả focus sớm — đúng thời điểm dialog "đóng" về mặt tương tác).
+import { useEffect, type RefObject } from 'react';
+
+/** Focusable selector chuẩn: input, button, select, textarea, a[href], tabIndex>=0. */
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+
+export function getFocusableElements(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR));
+}
+
+export function useFocusTrap(ref: RefObject<HTMLElement | null>, active: boolean): void {
+  useEffect(() => {
+    if (!active) return;
+    const container = ref.current;
+    if (!container) return;
+
+    const previous = document.activeElement as HTMLElement | null;
+
+    // Mở → focus phần tử đầu (không có focusable → focus chính container)
+    const items = getFocusableElements(container);
+    (items[0] ?? container).focus();
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+      const focusable = getFocusableElements(container);
+      if (focusable.length === 0) {
+        // Dialog không focusable nào bên trong (vd image preview chỉ có img) —
+        // giữ focus trên container, KHÔNG cho Tab thoát ra ngoài (WAI-ARIA modal).
+        e.preventDefault();
+        container.focus();
+        return;
+      }
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      const current = document.activeElement;
+      const inside = current instanceof Node && container.contains(current);
+      if (e.shiftKey) {
+        // Shift+Tab ở phần tử đầu (hoặc focus đang ở ngoài) → vòng về cuối
+        if (current === first || !inside) {
+          e.preventDefault();
+          last.focus();
+        }
+      } else if (current === last || !inside) {
+        // Tab ở phần tử cuối (hoặc ngoài) → vòng về đầu
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      previous?.focus?.(); // đóng → trả focus về trigger
+    };
+  }, [active, ref]);
+}

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

@@ -0,0 +1,192 @@
+// useForm tests — behavior thật: form render với Input ui-kit (invalid = !!errors[field]),
+// submit thiếu → errors + focus field đầu, sửa đúng → onSubmit(parsed), mode onBlur/
+// onChange, reset, schema transformers (trim/min), isValid/touched/setValue, schema non-object.
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { useForm } from './useForm.js';
+import { Input } from '../ui/input/index.js';
+
+afterEach(cleanup);
+
+const schema = z.object({
+  email: z.string().min(1, 'Email bắt buộc').email('Email không hợp lệ'),
+  password: z.string().min(8, 'Mật khẩu tối thiểu 8 ký tự'),
+});
+
+type LoginFormValues = z.infer<typeof schema>;
+type FormHandle = ReturnType<typeof useForm<LoginFormValues>>;
+
+function LoginForm({
+  onSubmit,
+  mode = 'onSubmit',
+}: {
+  onSubmit?: (data: LoginFormValues) => void;
+  mode?: 'onSubmit' | 'onBlur' | 'onChange';
+}) {
+  const form = useForm({ schema, initialValues: { email: '', password: '' }, mode });
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit ?? vi.fn())}>
+      <Input
+        name="email"
+        placeholder="Email"
+        value={form.values.email}
+        invalid={!!form.errors.email}
+        onChange={form.handleChange('email')}
+        onBlur={form.handleBlur('email')}
+      />
+      {form.errors.email && <p className="text-meta text-st-fail">{form.errors.email}</p>}
+      <Input
+        name="password"
+        type="password"
+        placeholder="Mật khẩu"
+        value={form.values.password}
+        invalid={!!form.errors.password}
+        onChange={form.handleChange('password')}
+        onBlur={form.handleBlur('password')}
+      />
+      {form.errors.password && <p className="text-meta text-st-fail">{form.errors.password}</p>}
+      <button type="submit">Đăng nhập</button>
+      <button type="button" onClick={() => form.reset()}>
+        Reset
+      </button>
+    </form>
+  );
+}
+
+const VALID = { email: 'alice@demo.local', password: 'demo-password' };
+
+describe('useForm — onSubmit mode', () => {
+  it('submit thiếu → errors từng field + input mang class invalid + focus field đầu', async () => {
+    const onSubmit = vi.fn();
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={onSubmit} />);
+    await user.click(screen.getByRole('button', { name: 'Đăng nhập' }));
+    expect(screen.getByText('Email bắt buộc')).toHaveClass('text-st-fail', 'text-meta');
+    expect(screen.getByText('Mật khẩu tối thiểu 8 ký tự')).toBeInTheDocument();
+    expect(screen.getByPlaceholderText('Email')).toHaveClass('border-st-fail');
+    expect(screen.getByPlaceholderText('Mật khẩu')).toHaveClass('border-st-fail');
+    // focus rơi vào field đầu theo thứ tự issues (email)
+    expect(document.activeElement).toBe(screen.getByPlaceholderText('Email'));
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('sửa đúng → onSubmit nhận parsed data + errors sạch', async () => {
+    const onSubmit = vi.fn();
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={onSubmit} />);
+    await user.type(screen.getByPlaceholderText('Email'), VALID.email);
+    await user.type(screen.getByPlaceholderText('Mật khẩu'), VALID.password);
+    await user.click(screen.getByRole('button', { name: 'Đăng nhập' }));
+    expect(onSubmit).toHaveBeenCalledWith(VALID);
+    expect(screen.queryByText(/bắt buộc/)).toBeNull();
+  });
+
+  it('schema transformers (trim/min) — min chạy sau trim, onSubmit nhận giá trị đã trim', async () => {
+    const onSubmit = vi.fn();
+    const trimSchema = z.object({ name: z.string().trim().min(3, 'Tên tối thiểu 3 ký tự') });
+    function TrimForm() {
+      const form = useForm({ schema: trimSchema, initialValues: { name: '' } });
+      return (
+        <form onSubmit={form.handleSubmit(onSubmit)}>
+          <Input name="name" value={form.values.name} onChange={form.handleChange('name')} />
+          {form.errors.name && <p>{form.errors.name}</p>}
+          <button type="submit">Gửi</button>
+        </form>
+      );
+    }
+    const user = userEvent.setup();
+    render(<TrimForm />);
+    await user.type(screen.getByRole('textbox'), 'ab');
+    await user.click(screen.getByRole('button', { name: 'Gửi' }));
+    // 'ab' sau trim vẫn 2 ký tự → min(3) fail
+    expect(screen.getByText('Tên tối thiểu 3 ký tự')).toBeInTheDocument();
+    await user.type(screen.getByRole('textbox'), 'cd');
+    await user.click(screen.getByRole('button', { name: 'Gửi' }));
+    expect(onSubmit).toHaveBeenCalledWith({ name: 'abcd' });
+  });
+
+  it('reset xoá sạch — values về initial, errors biến mất, input hết invalid', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm />);
+    await user.click(screen.getByRole('button', { name: 'Đăng nhập' }));
+    expect(screen.getByPlaceholderText('Email')).toHaveClass('border-st-fail');
+    await user.type(screen.getByPlaceholderText('Email'), 'x@y.z');
+    await user.click(screen.getByRole('button', { name: 'Reset' }));
+    expect(screen.getByPlaceholderText('Email')).toHaveValue('');
+    expect(screen.getByPlaceholderText('Email')).not.toHaveClass('border-st-fail');
+    expect(screen.queryByText(/bắt buộc/)).toBeNull();
+  });
+
+  it('isValid phản ánh đúng schema + setValue trực tiếp + touched qua blur', () => {
+    let formRef: FormHandle | null = null;
+    function Probe() {
+      const form = useForm({ schema, initialValues: { email: '', password: '' } });
+      formRef = form;
+      return (
+        <>
+          <Input value={form.values.email} onChange={form.handleChange('email')} onBlur={form.handleBlur('email')} />
+          <button type="button" onClick={() => form.setValue('password', VALID.password)}>
+            set
+          </button>
+        </>
+      );
+    }
+    render(<Probe />);
+    expect(formRef!.isValid).toBe(false);
+    expect(formRef!.touched.email).toBeUndefined();
+    fireEvent.blur(screen.getByRole('textbox'));
+    expect(formRef!.touched.email).toBe(true);
+    fireEvent.click(screen.getByRole('button', { name: 'set' }));
+    expect(formRef!.values.password).toBe(VALID.password);
+  });
+});
+
+describe('useForm — mode onBlur / onChange', () => {
+  it('mode onBlur: rời input sai → lỗi field đó hiện KHÔNG cần submit; field khác sạch', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm mode="onBlur" />);
+    await user.type(screen.getByPlaceholderText('Email'), 'khong-hop-le');
+    fireEvent.blur(screen.getByPlaceholderText('Email'));
+    expect(screen.getByText('Email không hợp lệ')).toBeInTheDocument();
+    expect(screen.queryByText(/Mật khẩu/)).toBeNull();
+  });
+
+  it('mode onChange: gõ sai hiện lỗi, sửa đúng tự xoá', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm mode="onChange" />);
+    await user.type(screen.getByPlaceholderText('Email'), 'khong-hop-le');
+    expect(screen.getByText('Email không hợp lệ')).toBeInTheDocument();
+    await user.clear(screen.getByPlaceholderText('Email'));
+    await user.type(screen.getByPlaceholderText('Email'), VALID.email);
+    expect(screen.queryByText('Email không hợp lệ')).toBeNull();
+  });
+
+  it('mode onSubmit mặc định: gõ sai KHÔNG hiện lỗi tới khi submit', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm />);
+    await user.type(screen.getByPlaceholderText('Email'), 'khong-hop-le');
+    expect(screen.queryByText('Email không hợp lệ')).toBeNull();
+  });
+});
+
+describe('useForm — schema non-object (root path)', () => {
+  it('issue path rỗng → key "root" map đúng message', async () => {
+    const onSubmit = vi.fn();
+    function Probe() {
+      const form = useForm({ schema: z.string().min(5, 'Tối thiểu 5 ký tự'), initialValues: 'ab' });
+      return (
+        <form onSubmit={form.handleSubmit(onSubmit)}>
+          {form.errors.root && <p>{form.errors.root}</p>}
+          <button type="submit">Gửi</button>
+        </form>
+      );
+    }
+    const user = userEvent.setup();
+    render(<Probe />);
+    await user.click(screen.getByRole('button', { name: 'Gửi' }));
+    expect(screen.getByText('Tối thiểu 5 ký tự')).toBeInTheDocument();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,119 @@
+// useForm — native form state + zod validation (peer-dep: consumer tự cài zod
+// khi dùng hook này — ui-kit chỉ khai báo peer). API tối giản kiểu RHF:
+// values/errors/touched + setValue/handleChange/handleBlur/handleSubmit/reset/isValid.
+// errors: Record<path, message> map từ safeParse issues — path join '.', giữ
+// issue ĐẦU TIÊN mỗi field. handleSubmit: sai → set errors + focus field đầu
+// (querySelector [name=...]); đúng → onSubmit(parsed — schema transformers đã chạy).
+// mode: 'onSubmit' (mặc định) | 'onBlur' (validate từng field khi rời input)
+// | 'onChange' (validate từng field khi gõ — lỗi tự xoá khi sửa đúng).
+import { useMemo, useState } from 'react';
+import type { ChangeEvent, FormEvent } from 'react';
+import type { ZodType } from 'zod';
+
+export type FormValidationMode = 'onSubmit' | 'onBlur' | 'onChange';
+
+export interface UseFormOptions<T> {
+  schema: ZodType<T>;
+  initialValues?: Partial<T>;
+  mode?: FormValidationMode;
+}
+
+export type FormErrors = Record<string, string>;
+
+type SafeResult<T> = ReturnType<ZodType<T>['safeParse']>;
+
+/** safeParse issues → FormErrors: path join '.', 1 message/field (issue đầu). */
+export function collectErrors<T>(result: Extract<SafeResult<T>, { success: false }>): FormErrors {
+  const next: FormErrors = {};
+  for (const issue of result.error.issues) {
+    const key = issue.path.join('.') || 'root';
+    if (!(key in next)) next[key] = issue.message;
+  }
+  return next;
+}
+
+export function useForm<T>({ schema, initialValues, mode = 'onSubmit' }: UseFormOptions<T>) {
+  /* Shallow-copy chỉ khi object (tránh spread primitive → biến thành {0:..,1:..}). */
+  const cloneInit = (v?: Partial<T>): T => {
+    const base = (v ?? initialValues) as T | undefined;
+    if (base === undefined) return {} as T;
+    return typeof base === 'object' && base !== null ? ({ ...base } as T) : base;
+  };
+
+  const [values, setValues] = useState<T>(() => cloneInit());
+  const [errors, setErrors] = useState<FormErrors>({});
+  const [touched, setTouched] = useState<Record<string, boolean>>({});
+
+  const isValid = useMemo(() => schema.safeParse(values).success, [schema, values]);
+
+  /** Validate 1 field trên snapshot values cụ thể — merge: xoá lỗi cũ field, thêm nếu vẫn sai. */
+  const validateFieldWith = (field: string, vals: T) => {
+    const result = schema.safeParse(vals);
+    const all = result.success ? {} : collectErrors<T>(result);
+    setErrors((prev) => {
+      const rest = { ...prev };
+      delete rest[field];
+      return all[field] !== undefined ? { ...rest, [field]: all[field] } : rest;
+    });
+  };
+
+  const setValue = <K extends keyof T & string>(field: K, value: T[K]) => {
+    const next = { ...values, [field]: value };
+    setValues(next);
+    if (mode === 'onChange') validateFieldWith(field, next);
+  };
+
+  /** Handler cho onChange của input — bind field, đọc e.target.value. */
+  const handleChange = <K extends keyof T & string>(field: K) => {
+    return (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => {
+      setValue(field, e.target.value as T[K]);
+    };
+  };
+
+  /** Handler cho onBlur — đánh touched + validate field theo mode onBlur. */
+  const handleBlur = <K extends keyof T & string>(field: K) => {
+    return () => {
+      setTouched((prev) => ({ ...prev, [field]: true }));
+      if (mode === 'onBlur') validateFieldWith(field, values);
+    };
+  };
+
+  /** Submit — sai: set errors + đánh touched toàn bộ + focus field đầu; đúng: onValid(parsed). */
+  const handleSubmit = (onValid: (data: T) => void | Promise<void>) => {
+    return (e?: FormEvent) => {
+      e?.preventDefault();
+      const result = schema.safeParse(values);
+      if (result.success) {
+        setErrors({});
+        void onValid(result.data);
+        return;
+      }
+      setErrors(collectErrors<T>(result));
+      setTouched((prev) => {
+        const all = { ...prev };
+        for (const key of Object.keys(values as Record<string, unknown>)) all[key] = true;
+        return all;
+      });
+      const first = result.error.issues[0];
+      const firstPath = first?.path.join('.') ?? '';
+      if (firstPath) document.querySelector<HTMLElement>(`[name="${firstPath}"]`)?.focus();
+    };
+  };
+
+  /** Reset về initialValues (hoặc next truyền vào) + xoá errors/touched. */
+  const reset = (next?: Partial<T>) => {
+    setValues(cloneInit(next));
+    setErrors({});
+    setTouched({});
+  };
+
+  return {
+    values, errors, touched, setValue, handleChange, handleBlur, handleSubmit, reset, isValid,
+    // Expose cho hook companion (useFieldArray — Form.List): schema để tự safeParse
+    // snapshot mới, setErrors để rebuild errors khi index mảng dịch. Không đổi API cũ.
+    schema, setErrors,
+  };
+}
+
+/** Kiểu instance trả về từ useForm — dùng khi hook companion cần nhận form qua param. */
+export type FormInstance<T> = ReturnType<typeof useForm<T>>;

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

@@ -0,0 +1,71 @@
+// Tests useFullscreen — jsdom KHÔNG có Fullscreen API: group fallback no-op
+// (không crash); group mock API: enter gọi requestFullscreen đúng element,
+// fullscreenchange sync state + onChange, exit gọi exitFullscreen.
+import { act, cleanup, renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useFullscreen } from './useFullscreen.js';
+
+function mockFullscreenApi() {
+  const el = document.createElement('div');
+  el.requestFullscreen = vi.fn().mockResolvedValue(undefined);
+  Object.defineProperty(document, 'fullscreenElement', { value: el, configurable: true });
+  document.exitFullscreen = vi.fn().mockResolvedValue(undefined);
+  return el;
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  // dọn property mock (defineProperty configurable)
+  delete (document as unknown as Record<string, unknown>).fullscreenElement;
+  delete (document as unknown as Record<string, unknown>).exitFullscreen;
+});
+
+describe('useFullscreen — fallback (jsdom không có API)', () => {
+  it('enter/exit không crash, không throw; isFullscreen khởi tạo theo document', () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useFullscreen({ onChange }));
+    expect(result.current.isFullscreen).toBe(false);
+    expect(() => {
+      result.current.enter();
+      result.current.exit();
+      result.current.toggle();
+    }).not.toThrow();
+    expect(onChange).not.toHaveBeenCalled(); // không có event → không bắn
+  });
+});
+
+describe('useFullscreen — mock Fullscreen API', () => {
+  it('enter → requestFullscreen trên ref element; event fullscreenchange sync state + onChange', () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useFullscreen({ onChange }));
+    const host = document.createElement('div');
+    result.current.ref.current = host;
+    host.requestFullscreen = vi.fn().mockResolvedValue(undefined);
+
+    act(() => result.current.enter());
+    expect(host.requestFullscreen).toHaveBeenCalledTimes(1);
+
+    // browser xử lý xong → bắn fullscreenchange với fullscreenElement đã đặt
+    mockFullscreenApi();
+    act(() => {
+      document.dispatchEvent(new Event('fullscreenchange'));
+    });
+    expect(result.current.isFullscreen).toBe(true);
+    expect(onChange).toHaveBeenLastCalledWith(true);
+  });
+
+  it('exit → exitFullscreen; toggle theo state hiện tại', async () => {
+    const el = mockFullscreenApi();
+    const { result } = renderHook(() => useFullscreen({ target: { current: el } }));
+    // state sync qua event fullscreenchange — bắn event giả lập browser xác nhận
+    act(() => {
+      document.dispatchEvent(new Event('fullscreenchange'));
+    });
+    expect(result.current.isFullscreen).toBe(true);
+
+    act(() => result.current.toggle());
+    expect(document.exitFullscreen).toHaveBeenCalledTimes(1);
+    await Promise.resolve();
+  });
+});

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

@@ -0,0 +1,68 @@
+// useFullscreen — toàn màn hình cho 1 element (Fullscreen API, pattern
+// usehooks.com): ref (hoặc `target` option) + isFullscreen theo event
+// `fullscreenchange` của document + enter/exit/toggle. Fallback an toàn: môi
+// trường thiếu API (jsdom/SSR/browser chặn) → enter/exit no-op, state vẫn
+// phản ánh document.fullscreenElement thật — không crash, không promise reject
+// lơ lửng (catch nuốt lỗi trình duyệt từ chối không có user gesture).
+import { useCallback, useEffect, useRef, useState, type RefObject } from 'react';
+
+export interface UseFullscreenOptions {
+  /** Element cố định cần fullscreen — không truyền thì gắn `ref` trả về. */
+  target?: RefObject<HTMLElement | null>;
+  /** Bắn mỗi lần trạng thái đổi (theo event fullscreenchange). */
+  onChange?: (isFullscreen: boolean) => void;
+}
+
+export interface UseFullscreenReturn {
+  /** Gắn lên element muốn fullscreen (bỏ qua nếu đã dùng `target`). */
+  ref: RefObject<HTMLDivElement | null>;
+  /** true khi element đang fullscreen (đọc document.fullscreenElement). */
+  isFullscreen: boolean;
+  enter: () => void;
+  exit: () => void;
+  toggle: () => void;
+}
+
+/** Toàn màn hình cho element — state sync qua fullscreenchange (kể cả ESC). */
+export function useFullscreen(options: UseFullscreenOptions = {}): UseFullscreenReturn {
+  const { target, onChange } = options;
+  const ref = useRef<HTMLDivElement>(null);
+  const [isFullscreen, setIsFullscreen] = useState(
+    () => typeof document !== 'undefined' && document.fullscreenElement != null,
+  );
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const sync = () => {
+      const active = document.fullscreenElement != null;
+      setIsFullscreen(active);
+      onChangeRef.current?.(active);
+    };
+    document.addEventListener('fullscreenchange', sync);
+    return () => document.removeEventListener('fullscreenchange', sync);
+  }, []);
+
+  const resolveEl = () => target?.current ?? ref.current;
+
+  // Fallback: API không tồn tại (jsdom/SSR) → no-op; promise reject (browser
+  // yêu cầu user gesture) → catch nuốt, state chờ fullscreenchange quyết định.
+  const enter = useCallback(() => {
+    const el = resolveEl() ?? document.documentElement;
+    const request = (el as HTMLElement & { requestFullscreen?: () => Promise<void> }).requestFullscreen?.bind(el);
+    request?.().catch(() => {});
+  }, [target]);
+
+  const exit = useCallback(() => {
+    const exitFn = (document as Document & { exitFullscreen?: () => Promise<void> }).exitFullscreen?.bind(document);
+    exitFn?.().catch(() => {});
+  }, []);
+
+  const toggle = useCallback(() => {
+    if (isFullscreen) exit();
+    else enter();
+  }, [isFullscreen, enter, exit]);
+
+  return { ref, isFullscreen, enter, exit, toggle };
+}

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

@@ -0,0 +1,30 @@
+// Tests useHover — mouseenter/mouseleave đổi trạng thái (spec worker B).
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { useHover } from './useHover.js';
+
+function HoverArea() {
+  const [ref, hovered] = useHover<HTMLDivElement>();
+  return (
+    <div ref={ref} data-testid="area">
+      {hovered ? 'hovering' : 'idle'}
+    </div>
+  );
+}
+
+afterEach(cleanup);
+
+describe('useHover', () => {
+  it('mouseenter → true, mouseleave → false', () => {
+    render(<HoverArea />);
+    const area = screen.getByTestId('area');
+
+    expect(area).toHaveTextContent('idle');
+
+    fireEvent.mouseEnter(area);
+    expect(area).toHaveTextContent('hovering');
+
+    fireEvent.mouseLeave(area);
+    expect(area).toHaveTextContent('idle');
+  });
+});

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

@@ -0,0 +1,23 @@
+// useHover — trạng thái hover của 1 element, pattern usehooks.com/ui.dev.
+// Trả về [ref, hovered] — gắn ref lên phần tử cần theo dõi.
+import { useEffect, useRef, useState } from 'react';
+
+export function useHover<T extends HTMLElement = HTMLElement>() {
+  const ref = useRef<T | null>(null);
+  const [hovered, setHovered] = useState(false);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    const onMouseEnter = () => setHovered(true);
+    const onMouseLeave = () => setHovered(false);
+    el.addEventListener('mouseenter', onMouseEnter);
+    el.addEventListener('mouseleave', onMouseLeave);
+    return () => {
+      el.removeEventListener('mouseenter', onMouseEnter);
+      el.removeEventListener('mouseleave', onMouseLeave);
+    };
+  }, []);
+
+  return [ref, hovered] as const;
+}