create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,182 @@
+// Watermark — overlay chữ lặp phủ lên nội dung (antd-like) dùng SVG data-URI làm
+// backgroundImage tile repeat (KHÔNG deps mới; canvas.toDataURL không chạy được trong
+// jsdom nên chọn nhánh SVG data-URI). Overlay pointer-events-none + aria-hidden —
+// nội dung children vẫn bấm/select bình thường.
+// Màu mặc định resolve token --ink3 qua getComputedStyle (fallback = giá trị --ink3
+// light cho môi trường không cascade token, vd jsdom). Đổi theme (data-bp-theme) →
+// re-bake tile qua MutationObserver. Font-family mặc định 'sans-serif' — SVG data-URI
+// không đọc được CSS var, consumer override qua prop font khi cần đúng stack.
+import { useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+
+export interface WatermarkFont {
+  /** Cỡ chữ tile (px). Mặc định 16. */
+  fontSize?: number;
+  /** Độ đậm. Mặc định 'normal'. */
+  fontWeight?: 'normal' | 'bold' | number;
+  /** Font family (mặc định 'sans-serif' — xem ghi chú đầu file). */
+  fontFamily?: string;
+  /** Kiểu chữ. Mặc định 'normal'. */
+  fontStyle?: 'normal' | 'italic' | 'oblique';
+}
+
+export interface WatermarkProps {
+  /** Nội dung được phủ watermark. */
+  children: ReactNode;
+  /** Chữ watermark — 1 dòng hoặc mảng nhiều dòng. */
+  content: string | string[];
+  /** Khoảng hở giữa các tile [ngang, dọc] (px). Mặc định [100, 100] (antd). */
+  gap?: [number, number];
+  /** Độ lệch lưới tile so với gốc [ngang, dọc] (px). Mặc định gap/2 (antd). */
+  offset?: [number, number];
+  /** Tọa độ đặt overlay (số → px) — kèm width/height để thu overlay lại. */
+  left?: number | string;
+  /** Tọa độ đặt overlay (số → px) — kèm width/height để thu overlay lại. */
+  top?: number | string;
+  /** Chiều rộng overlay (px khi số) — chỉ có ý nghĩa khi truyền left/top. */
+  width?: number | string;
+  /** Chiều cao overlay (px khi số) — chỉ có ý nghĩa khi truyền left/top. */
+  height?: number | string;
+  /** z-index overlay (antd mặc định 9 — dưới thang --z-* overlay). */
+  zIndex?: number;
+  /** Góc nghiêng chữ (độ). Mặc định -22 (antd). */
+  rotate?: number;
+  /** Độ mờ overlay 0–1. Mặc định 1 (mức mờ nằm ở màu token --ink3). */
+  opacity?: number;
+  /** Kiểu chữ tile — xem WatermarkFont. */
+  font?: WatermarkFont;
+  /** Màu chữ tile — override token (resolve --ink3 từ scope consumer khi không truyền). */
+  fontColor?: string;
+  className?: string;
+  /** Style dán lên container bao children. */
+  style?: CSSProperties;
+}
+
+/** Escape nội dung text đưa vào SVG (data-URI không được vỡ markup). */
+function escapeXml(s: string): string {
+  return s
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+/** Ước lượng độ rộng dòng — CJK đếm 1em, ký tự còn lại ~0.6em (không dùng canvas:
+ * jsdom không có getContext('2d'), méo vài px không thấy vì gap mặc định 100px). */
+function estimateTextWidth(text: string, fontSize: number): number {
+  const units = Array.from(text).reduce((w, ch) => w + (ch.charCodeAt(0) > 0x2e7f ? 1 : 0.6), 0);
+  return Math.ceil(units * fontSize);
+}
+
+/** Dựng tile SVG xoay sẵn + encode data-URI — tile repeat thẳng, chữ xoay trong tile (kiểu antd). */
+function buildTileUrl(opts: {
+  lines: string[];
+  gap: [number, number];
+  rotate: number;
+  fontSize: number;
+  fontWeight: WatermarkFont['fontWeight'];
+  fontFamily: string;
+  fontStyle: WatermarkFont['fontStyle'];
+  color: string;
+}): string {
+  const { lines, gap, rotate, fontSize, fontWeight, fontFamily, fontStyle, color } = opts;
+  const lineHeight = Math.ceil(fontSize * 1.2);
+  const blockW = Math.max(...lines.map((l) => estimateTextWidth(l, fontSize)));
+  const blockH = lines.length * lineHeight;
+  const rad = (Math.abs(rotate) * Math.PI) / 180;
+  // Tile đủ lớn để chữ xoay quanh tâm không tràn mép (bounding box xoay + gap)
+  const tileW = Math.ceil(blockW * Math.cos(rad) + blockH * Math.sin(rad)) + gap[0];
+  const tileH = Math.ceil(blockW * Math.sin(rad) + blockH * Math.cos(rad)) + gap[1];
+  const cx = tileW / 2;
+  const cy = tileH / 2;
+  const textTags = lines
+    .map((line, i) => {
+      const y = cy - ((lines.length - 1) / 2) * lineHeight + i * lineHeight;
+      return `<text x="${cx}" y="${y}" fill="${escapeXml(color)}" font-family="${escapeXml(fontFamily)}" font-size="${fontSize}" font-weight="${fontWeight}" font-style="${fontStyle}" text-anchor="middle" dominant-baseline="middle">${escapeXml(line)}</text>`;
+    })
+    .join('');
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${tileW}" height="${tileH}" viewBox="0 0 ${tileW} ${tileH}"><g transform="rotate(${rotate} ${cx} ${cy})">${textTags}</g></svg>`;
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+
+export function Watermark({
+  children,
+  content,
+  gap = [100, 100],
+  offset,
+  left,
+  top,
+  width,
+  height,
+  zIndex = 9,
+  rotate = -22,
+  opacity = 1,
+  font,
+  fontColor,
+  className,
+  style,
+}: WatermarkProps) {
+  const rootRef = useRef<HTMLSpanElement>(null);
+  // Màu tile bake sẵn vào SVG — resolve token --ink3 trong scope consumer; fallback
+  // là giá trị --ink3 light (môi trường không cascade token, vd jsdom).
+  const [tileColor, setTileColor] = useState('rgba(0, 0, 0, 0.45)');
+
+  useEffect(() => {
+    if (fontColor) return; // consumer override — khỏi resolve token
+    const sync = () => {
+      const el = rootRef.current;
+      if (!el) return;
+      const v = getComputedStyle(el).getPropertyValue('--ink3').trim();
+      if (v) setTileColor(v); // đổi theme data-bp-theme → re-bake tile màu mới
+    };
+    sync();
+    const mo = new MutationObserver(sync);
+    mo.observe(document.documentElement, { attributes: true, attributeFilter: ['data-bp-theme'] });
+    return () => mo.disconnect();
+  }, [fontColor]);
+
+  const lines = useMemo(() => (Array.isArray(content) ? content : [content]), [content]);
+
+  const tileUrl = useMemo(
+    () =>
+      buildTileUrl({
+        lines,
+        gap,
+        rotate,
+        fontSize: font?.fontSize ?? 16,
+        fontWeight: font?.fontWeight ?? 'normal',
+        fontFamily: font?.fontFamily ?? 'sans-serif',
+        fontStyle: font?.fontStyle ?? 'normal',
+        color: fontColor ?? tileColor,
+      }),
+    [lines, gap, rotate, font, fontColor, tileColor],
+  );
+
+  // Overlay mặc định phủ kín container (inset-0); truyền left/top (và width/height)
+  // → neo góc riêng kiểu antd (watermark vùng chọn thay vì toàn khối).
+  const positioned = left !== undefined || top !== undefined;
+  const overlayStyle: CSSProperties = {
+    zIndex,
+    opacity,
+    backgroundImage: `url("${tileUrl}")`,
+    backgroundRepeat: 'repeat',
+    backgroundPosition: offset ? `${offset[0]}px ${offset[1]}px` : `${gap[0] / 2}px ${gap[1] / 2}px`,
+  };
+  if (positioned) {
+    overlayStyle.left = left;
+    overlayStyle.top = top;
+    if (width !== undefined) overlayStyle.width = width;
+    if (height !== undefined) overlayStyle.height = height;
+  }
+
+  return (
+    <span ref={rootRef} className={`relative block${className ? ` ${className}` : ''}`} style={style}>
+      {children}
+      <span
+        aria-hidden="true"
+        className={`pointer-events-none absolute overflow-hidden${positioned ? '' : ' inset-0'}`}
+        style={overlayStyle}
+      />
+    </span>
+  );
+}

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

@@ -0,0 +1,96 @@
+// Watermark stories — basic text, multi-line, media block, custom style.
+// Parity matrix antd→tokens: docs/parity-matrix.md
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Watermark } from './index';
+
+/** Repeated watermark overlay for page branding. */
+const meta = {
+  title: 'Data Display/Watermark',
+  component: Watermark,
+  tags: ['autodocs'],
+} satisfies Meta<typeof Watermark>;
+export default meta;
+
+// StoryObj không generic (pattern Popconfirm) — meta có component, story render-only.
+type Story = StoryObj;
+
+export const Basic: Story = {
+  name: 'Basic text — full-area tile, default -22° ink3',
+  render: () => (
+    <Watermark content="CONFIDENTIAL" className="p-6">
+      <div className="rounded-xl border border-line bg-s1 p-6 text-body text-ink2">
+        Draft contract v2 — internal use only. The overlay is pointer-events-none,
+        so this text stays selectable and copyable.
+      </div>
+    </Watermark>
+  ),
+};
+
+export const MultiLine: Story = {
+  name: 'Multi-line content — array of lines, tighter gap',
+  render: () => (
+    <Watermark content={['wakii', 'demo workspace']} gap={[60, 60]} className="p-6">
+      <div className="rounded-xl border border-line bg-s1 p-6 text-body text-ink2">
+        Two-line watermark (antd content prop accepts an array of lines).
+      </div>
+    </Watermark>
+  ),
+};
+
+export const MediaBlock: Story = {
+  name: 'Media block — protect preview imagery (corner-anchored overlay)',
+  render: () => (
+    <Watermark
+      content="© wakii studio"
+      gap={[48, 48]}
+      opacity={0.75}
+      className="w-fit"
+    >
+      <div className="grid h-44 w-72 place-items-center rounded-xl bg-s3 text-ink3">
+        product-photograph.png
+      </div>
+    </Watermark>
+  ),
+};
+
+export const CustomStyle: Story = {
+  name: 'Custom style — rotate, opacity, font, color, z-index',
+  render: () => (
+    <Watermark
+      content="DRAFT"
+      rotate={-45}
+      opacity={0.6}
+      zIndex={20}
+      font={{ fontSize: 24, fontWeight: 'bold' }}
+      className="p-6"
+    >
+      <div className="rounded-xl border border-line bg-s1 p-6 text-body text-ink2">
+        Steeper angle + bold 24px tile for heavy drafts.
+      </div>
+    </Watermark>
+  ),
+};
+
+export const CornerAnchored: Story = {
+  name: 'Corner anchored — left/top/width/height instead of full area',
+  render: () => (
+    <Watermark content="SAMPLE" left={16} top={16} width={180} height={80} className="p-6">
+      <div className="h-40 rounded-xl border border-line bg-s1 p-6 text-body text-ink2">
+        Overlay pinned at (16, 16) sized 180×80 — the rest of the block stays clean.
+      </div>
+    </Watermark>
+  ),
+};
+
+export const DarkTheme: Story = {
+  name: 'DarkTheme — tile re-bakes to dark --ink3',
+  render: () => (
+    <div data-bp-theme="dark" className="p-4">
+      <Watermark content="INTERNAL" className="p-6">
+        <div className="rounded-xl border border-line bg-s1 p-6 text-body text-ink2">
+          Tile color resolves --ink3 inside the dark scope.
+        </div>
+      </Watermark>
+    </div>
+  ),
+};

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

@@ -0,0 +1,120 @@
+// Watermark tests — render children, data-URI tile trong style, content đổi → URL
+// đổi, pointer-events-none, custom rotate/opacity/zIndex/left-top reflect trong DOM.
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { useState } from 'react';
+import { Watermark } from './index.js';
+
+afterEach(cleanup);
+
+/** Lấy data-URI tile từ overlay (span aria-hidden duy nhất trong container). */
+const overlayOf = (c: HTMLElement) => c.querySelector('span[aria-hidden]') as HTMLElement;
+const tileUrlOf = (c: HTMLElement) => overlayOf(c).style.backgroundImage;
+
+describe('Watermark', () => {
+  it('render children bình thường (overlay không chặn nội dung)', () => {
+    render(
+      <Watermark content="CONFIDENTIAL">
+        <p>Body content</p>
+      </Watermark>,
+    );
+    expect(screen.getByText('Body content')).toBeInTheDocument();
+    expect(screen.getByText('Body content').parentElement).toHaveClass('relative'); // container bao
+  });
+
+  it('overlay có data:image/svg+xml data-URI trong backgroundImage + repeat', () => {
+    const { container } = render(
+      <Watermark content="INTERNAL">
+        <div>doc</div>
+      </Watermark>,
+    );
+    const url = tileUrlOf(container);
+    expect(url).toContain('data:image/svg+xml;charset=utf-8,');
+    expect(url).toContain('INTERNAL'); // chữ nằm trong SVG tile
+    expect(overlayOf(container).style.backgroundRepeat).toBe('repeat');
+  });
+
+  it('content đổi → data-URI đổi (re-bake tile)', () => {
+    const { rerender, container } = render(
+      <Watermark content="DRAFT v1">
+        <div>doc</div>
+      </Watermark>,
+    );
+    const before = tileUrlOf(container);
+    rerender(
+      <Watermark content="DRAFT v2">
+        <div>doc</div>
+      </Watermark>,
+    );
+    const after = tileUrlOf(container);
+    expect(before).not.toBe(after);
+    expect(after).toContain('DRAFT%20v2');
+  });
+
+  it('overlay pointer-events-none + aria-hidden (children vẫn tương tác được)', () => {
+    const { container } = render(
+      <Watermark content="w">
+        <button>Click</button>
+      </Watermark>,
+    );
+    const overlay = overlayOf(container);
+    expect(overlay.className).toContain('pointer-events-none');
+    expect(overlay).toHaveAttribute('aria-hidden', 'true');
+    // overlay KHÔNG bọc children — children là sibling, bấm/select bình thường
+    expect(overlay.contains(screen.getByRole('button', { name: 'Click' }))).toBe(false);
+  });
+
+  it('custom rotate/opacity/zIndex reflect: rotate vào SVG transform, opacity/z-index vào style', () => {
+    const { container } = render(
+      <Watermark content="x" rotate={-45} opacity={0.5} zIndex={42}>
+        <div>doc</div>
+      </Watermark>,
+    );
+    const overlay = overlayOf(container);
+    expect(overlay.style.opacity).toBe('0.5');
+    expect(overlay.style.zIndex).toBe('42');
+    expect(decodeURIComponent(tileUrlOf(container))).toContain('rotate(-45');
+  });
+
+  it('left/top/width/height → overlay neo góc riêng (không inset-0)', () => {
+    const { container } = render(
+      <Watermark content="x" left={20} top="10px" width={200} height={100}>
+        <div>doc</div>
+      </Watermark>,
+    );
+    const overlay = overlayOf(container);
+    expect(overlay.style.left).toBe('20px');
+    expect(overlay.style.top).toBe('10px');
+    expect(overlay.style.width).toBe('200px');
+    expect(overlay.style.height).toBe('100px');
+    expect(overlay.className).not.toContain('inset-0');
+  });
+
+  it('multi-line content (mảng) → cả 2 dòng trong tile; fontColor override vào fill', () => {
+    const { container } = render(
+      <Watermark content={['Line A', 'Line B']} fontColor="#123456">
+        <div>doc</div>
+      </Watermark>,
+    );
+    const svg = decodeURIComponent(tileUrlOf(container));
+    expect(svg).toContain('Line A');
+    expect(svg).toContain('Line B');
+    expect(svg).toContain('fill="#123456"');
+  });
+
+  it('đổi content runtime qua state → tile re-bake (useMemo deps chạy đúng)', () => {
+    function Demo() {
+      const [c, setC] = useState('A');
+      return (
+        <Watermark content={c}>
+          <button onClick={() => setC('B')}>Flip</button>
+        </Watermark>
+      );
+    }
+    const { container } = render(<Demo />);
+    const before = tileUrlOf(container);
+    fireEvent.click(screen.getByRole('button', { name: 'Flip' }));
+    expect(tileUrlOf(container)).not.toBe(before);
+    expect(decodeURIComponent(tileUrlOf(container))).toContain('>B<');
+  });
+});

package/stack-template/app/ui-kit/src/utils/array.test.ts

@@ -0,0 +1,88 @@
+// Tests array — chunk (đều/lẻ/edge), groupBy (đa nhóm/giữ thứ tự), flattenTree
+// + findTreeNode (cây 3 tầng, không thấy → null).
+import { describe, expect, it } from 'vitest';
+import { chunk, findTreeNode, flattenTree, groupBy } from './array.js';
+
+describe('chunk', () => {
+  it('chia đều + khối cuối ngắn hơn', () => {
+    expect(chunk([1, 2, 3, 4, 5], 2)).toEqual([[1, 2], [3, 4], [5]]);
+    expect(chunk([1, 2, 3, 4], 2)).toEqual([
+      [1, 2],
+      [3, 4],
+    ]);
+  });
+
+  it('edge: mảng rỗng · size > length · size không hợp lệ throw', () => {
+    expect(chunk([], 3)).toEqual([]);
+    expect(chunk([1, 2], 10)).toEqual([[1, 2]]);
+    expect(() => chunk([1], 0)).toThrow(RangeError);
+    expect(() => chunk([1], -2)).toThrow(RangeError);
+  });
+
+  it('không mutate input', () => {
+    const src = [1, 2, 3];
+    chunk(src, 2);
+    expect(src).toEqual([1, 2, 3]);
+  });
+});
+
+describe('groupBy', () => {
+  it('nhóm theo keyFn, giữ thứ tự xuất hiện đầu', () => {
+    const tasks = [
+      { id: 1, status: 'todo' },
+      { id: 2, status: 'doing' },
+      { id: 3, status: 'todo' },
+    ];
+    expect(groupBy(tasks, (t) => t.status)).toEqual({
+      todo: [tasks[0], tasks[2]],
+      doing: [tasks[1]],
+    });
+  });
+
+  it('mảng rỗng → object rỗng; khoá number vẫn hoạt động', () => {
+    expect(groupBy([], (x: never) => x)).toEqual({});
+    expect(groupBy([1, 2, 3], (n) => n % 2)).toEqual({ 1: [1, 3], 0: [2] });
+  });
+});
+
+interface Node {
+  name: string;
+  children?: Node[];
+}
+const TREE: Node[] = [
+  {
+    name: 'a',
+    children: [
+      { name: 'a1', children: [{ name: 'a1x' }] },
+      { name: 'a2' },
+    ],
+  },
+  { name: 'b' },
+];
+
+describe('flattenTree', () => {
+  it('DFS pre-order + depth đúng (gốc 0)', () => {
+    expect(flattenTree(TREE).map((f) => [f.node.name, f.depth])).toEqual([
+      ['a', 0],
+      ['a1', 1],
+      ['a1x', 2],
+      ['a2', 1],
+      ['b', 0],
+    ]);
+  });
+
+  it('cây rỗng → []', () => {
+    expect(flattenTree([])).toEqual([]);
+  });
+});
+
+describe('findTreeNode', () => {
+  it('thấy node tầng sâu (DFS pre-order trả node đầu tiên thoả)', () => {
+    expect(findTreeNode(TREE, (n) => n.name === 'a1x')?.name).toBe('a1x');
+    expect(findTreeNode(TREE, (n) => n.name.startsWith('a'))?.name).toBe('a');
+  });
+
+  it('không thấy → null', () => {
+    expect(findTreeNode(TREE, (n) => n.name === 'zzz')).toBeNull();
+  });
+});

package/stack-template/app/ui-kit/src/utils/array.ts

@@ -0,0 +1,51 @@
+// array — helper mảng + cây (0 deps, strict): chunk · groupBy · flattenTree ·
+// findTreeNode. Không mutate input; generic giữ typecaller.
+
+export interface FlatTreeNode<T> {
+  /** Node hiện tại (không clone — tham chiếu gốc). */
+  node: T;
+  /** Độ sâu: gốc = 0. */
+  depth: number;
+}
+
+/** Chia mảng thành các khối `size` phần tử (khối cuối có thể ngắn hơn).
+ * size <= 0 → throw RangeError (lỗi gọi sai phải lộ sớm). */
+export function chunk<T>(items: readonly T[], size: number): T[][] {
+  if (!Number.isInteger(size) || size <= 0) throw new RangeError(`chunk: size phải là số nguyên dương, nhận ${size}`);
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+
+/** Nhóm theo khoá sinh từ `keyFn` — thứ tự nhóm theo lần xuất hiện đầu. */
+export function groupBy<T, K extends string | number>(items: readonly T[], keyFn: (item: T) => K): Record<K, T[]> {
+  const out = {} as Record<K, T[]>;
+  for (const item of items) {
+    const key = keyFn(item);
+    (out[key] ??= []).push(item);
+  }
+  return out;
+}
+
+/** Phẳng cây (DFS pre-order) thành danh sách kèm depth — gốc depth 0.
+ * Node có `children` rỗng/undefined thì không sinh con. */
+export function flattenTree<T extends { children?: readonly T[] }>(nodes: readonly T[], depth = 0): Array<FlatTreeNode<T>> {
+  const out: Array<FlatTreeNode<T>> = [];
+  for (const node of nodes) {
+    out.push({ node, depth });
+    if (node.children?.length) out.push(...flattenTree(node.children, depth + 1));
+  }
+  return out;
+}
+
+/** Tìm node đầu tiên thoả `predicate` — DFS pre-order; không thấy → null. */
+export function findTreeNode<T extends { children?: readonly T[] }>(nodes: readonly T[], predicate: (node: T) => boolean): T | null {
+  for (const node of nodes) {
+    if (predicate(node)) return node;
+    if (node.children?.length) {
+      const hit = findTreeNode(node.children, predicate);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,69 @@
+// Tests dom — getScrollParent (tìm ancestor cuộn được/null), getFocusableElements
+// (đúng selector + thứ tự DOM + bỏ disabled/tabindex -1), cx (bỏ falsy).
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { cx, getFocusableElements, getScrollParent } from './dom.js';
+
+afterEach(cleanup);
+
+describe('getScrollParent', () => {
+  it('tìm ancestor có overflow-y auto/scroll gần nhất', () => {
+    const { container } = render(
+      <div style={{ overflowY: 'auto' }} data-testid="scroller">
+        <div style={{ overflowY: 'visible' }}>
+          <span data-testid="leaf">x</span>
+        </div>
+      </div>,
+    );
+    const leaf = container.querySelector('[data-testid="leaf"]') as HTMLElement;
+    const scroller = container.querySelector('[data-testid="scroller"]') as HTMLElement;
+    expect(getScrollParent(leaf)).toBe(scroller);
+  });
+
+  it('không có ancestor cuộn được → null', () => {
+    const { container } = render(
+      <div>
+        <span data-testid="leaf2">x</span>
+      </div>,
+    );
+    const leaf = container.querySelector('[data-testid="leaf2"]') as HTMLElement;
+    // body trong jsdom không set overflow — đi hết → null
+    expect(getScrollParent(leaf)).toBeNull();
+  });
+});
+
+describe('getFocusableElements', () => {
+  it('thu theo thứ tự DOM, bỏ disabled + tabindex=-1', () => {
+    const { container } = render(
+      <div>
+        <button data-name="btn">b</button>
+        <a href="#x" data-name="link">
+          l
+        </a>
+        <button disabled data-name="disabled">
+          d
+        </button>
+        <div tabIndex={-1} data-name="neg">
+          n
+        </div>
+        <div tabIndex={0} data-name="tab0">
+          t
+        </div>
+      </div>,
+    );
+    const got = getFocusableElements(container as HTMLElement).map((el) => el.getAttribute('data-name'));
+    expect(got).toEqual(['btn', 'link', 'tab0']);
+  });
+
+  it('container rỗng → []', () => {
+    const { container } = render(<div />);
+    expect(getFocusableElements(container as HTMLElement)).toEqual([]);
+  });
+});
+
+describe('cx', () => {
+  it('nối class thật, bỏ false/null/undefined', () => {
+    expect(cx('a', false && 'b', undefined, 'c', null)).toBe('a c');
+    expect(cx()).toBe('');
+  });
+});

package/stack-template/app/ui-kit/src/utils/dom.ts

@@ -0,0 +1,38 @@
+// dom — helper DOM dùng chung (0 deps): scroll parent · focusable · className.
+// ⚠️ getFocusableElements dùng CÙNG selector chuẩn WAI-ARIA với
+// src/hooks/useFocusTrap.ts (file đó ngoài scope sửa — bản này copy selector,
+// comment dẫn nguồn; lead có thể hợp nhất sau qua re-export).
+
+/** Focusable selector chuẩn WAI-ARIA — nhất quán với hooks/useFocusTrap.ts. */
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+
+/** Tìm ancestor cuộn được theo trục dọc (overflow-y auto/scroll) — đi từ
+ * parentElement lên; không thấy → null (caller fallback window/document). */
+export function getScrollParent(element: HTMLElement): HTMLElement | null {
+  let current = element.parentElement;
+  while (current) {
+    const style = window.getComputedStyle(current);
+    const overflowY = style.overflowY;
+    if (overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') return current;
+    current = current.parentElement;
+  }
+  return null;
+}
+
+/** Danh sách phần tử nhận focus trong container (thứ tự DOM) — selector chuẩn
+ * WAI-ARIA, khớp useFocusTrap. */
+export function getFocusableElements(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR));
+}
+
+/** Nối className có điều kiện — bỏ falsy: cx('a', cond && 'b', null) → "a b". */
+export function cx(...classes: Array<string | false | null | undefined>): string {
+  return classes.filter(Boolean).join(' ');
+}