create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,62 @@
+// Radio + Radio.Group — tròn 16px, checked = dot accent; Group options layout
+// horizontal mặc định (antd RadioGroup).
+// A11y (sweep 2026-10-18): Group bắn chung `name` (useId) cho input radio →
+// ←↑/→↑ di chuyển giữa options như native (roving selection); group nhận
+// aria-label passthrough (role=radiogroup cần accessible name).
+import { useId, type ReactNode } from 'react';
+
+export interface RadioProps {
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  /** name chung của group — Group tự sinh; truyền tay chỉ dùng khi Radio đơn lẻ. */
+  name?: string;
+  children?: ReactNode;
+  className?: string;
+}
+
+export function Radio({ checked = false, onChange, disabled = false, name, children, className }: RadioProps) {
+  return (
+    <label className={`inline-flex cursor-pointer items-center gap-2 text-body text-ink${disabled ? ' cursor-not-allowed text-ink3' : ''}${className ? ` ${className}` : ''}`}>
+      <input
+        type="radio"
+        name={name}
+        checked={checked}
+        disabled={disabled}
+        onChange={(e) => onChange?.(e.target.checked)}
+        className="peer size-4 cursor-pointer appearance-none rounded-pill border border-line bg-s2 shadow-[var(--ele-1)] transition-[border-color,border-width,box-shadow,transform] duration-200 ease-[var(--ease-smooth)] hover:border-ink/20 checked:border-[5px] checked:border-accent checked:scale-[1.1] checked:shadow-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:outline-none disabled:cursor-not-allowed disabled:bg-s3 disabled:shadow-none"
+      />
+      {children}
+    </label>
+  );
+}
+
+export interface RadioGroupProps {
+  value?: string;
+  onChange?: (value: string) => void;
+  options: Array<{ label: ReactNode; value: string; disabled?: boolean }>;
+  disabled?: boolean;
+  /** Accessible name cho role="radiogroup". */
+  'aria-label'?: string;
+  className?: string;
+}
+
+export function RadioGroup({ value, onChange, options, disabled = false, className, ...rest }: RadioGroupProps) {
+  // Tên chung cho cả nhóm input — bật điều hướng arrow-key native giữa options.
+  const name = useId();
+  return (
+    <div role="radiogroup" className={`flex flex-wrap items-center gap-4${className ? ` ${className}` : ''}`} {...rest}>
+      {options.map((option) => (
+        <Radio
+          key={option.value}
+          name={name}
+          checked={value === option.value}
+          disabled={disabled || option.disabled}
+          onChange={(checked) => checked && onChange?.(option.value)}
+        >
+          {option.label}
+        </Radio>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,94 @@
+// Radio stories — Radio (single) + RadioGroup (options list).
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Radio, RadioGroup } from './index';
+
+const meta = { title: 'Forms/Radio', component: RadioGroup, tags: ['autodocs'] } satisfies Meta<typeof RadioGroup>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+/** Basic — group with 2 options. */
+export const Basic: S = {
+  args: {
+    value: 'a',
+    onChange: () => {},
+    options: [
+      { label: 'Option A', value: 'a' },
+      { label: 'Option B', value: 'b' },
+    ],
+  },
+};
+
+/** Single — standalone Radio without a group. */
+export const Single: S = {
+  args: { options: [] },
+  render: () => <Radio checked onChange={() => {}}>Standalone radio</Radio>,
+};
+
+/** WithDisabled — one option locked (per-option disabled). */
+export const WithDisabled: S = {
+  name: 'With disabled option',
+  args: {
+    value: 'a',
+    onChange: () => {},
+    options: [
+      { label: 'Available', value: 'a' },
+      { label: 'Unavailable', value: 'b', disabled: true },
+    ],
+  },
+};
+
+/** GroupDisabled — whole group locked (antd RadioGroup disabled). */
+export const GroupDisabled: S = {
+  name: 'Group disabled — all options locked',
+  args: {
+    value: 'a',
+    disabled: true,
+    onChange: () => {},
+    options: [
+      { label: 'Option A', value: 'a' },
+      { label: 'Option B', value: 'b' },
+    ],
+  },
+};
+
+/** Controlled — useState demo: pick shows the selected value. */
+export const Controlled: S = {
+  args: { options: [] },
+  render: () => <RadioGroupControlledDemo />,
+};
+
+/** DarkTheme — group on dark canvas. */
+export const DarkTheme: S = {
+  args: { options: [] },
+  render: () => (
+    <div data-bp-theme="dark" className="w-[280px] rounded-xl bg-canvas p-4">
+      <RadioGroup
+        value="a"
+        onChange={() => {}}
+        options={[
+          { label: 'Option A', value: 'a' },
+          { label: 'Option B', value: 'b' },
+        ]}
+      />
+    </div>
+  ),
+};
+
+function RadioGroupControlledDemo() {
+  const [v, setV] = useState('fe');
+  return (
+    <div className="grid max-w-[320px] gap-3">
+      <RadioGroup
+        value={v}
+        onChange={setV}
+        options={[
+          { label: 'Frontend', value: 'fe' },
+          { label: 'Backend', value: 'be' },
+          { label: 'DevOps', value: 'ops' },
+        ]}
+      />
+      <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/radio/radio.test.tsx

@@ -0,0 +1,83 @@
+// Radio/Group tests — chọn 1 trong nhóm, disabled per-option.
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Radio, RadioGroup } from './index.js';
+
+afterEach(cleanup);
+
+describe('RadioGroup', () => {
+  it('value hiện tại checked; chọn option khác → onChange(value)', async () => {
+    const onChange = vi.fn();
+    render(
+      <RadioGroup
+        value="a"
+        onChange={onChange}
+        options={[
+          { label: 'A', value: 'a' },
+          { label: 'B', value: 'b' },
+        ]}
+      />,
+    );
+    expect(screen.getByRole('radiogroup')).toBeInTheDocument();
+    await userEvent.setup().click(screen.getByText('B'));
+    expect(onChange).toHaveBeenCalledWith('b');
+  });
+
+  it('option disabled → không chọn được', async () => {
+    const onChange = vi.fn();
+    render(
+      <RadioGroup
+        value="a"
+        onChange={onChange}
+        options={[
+          { label: 'A', value: 'a' },
+          { label: 'Khoá', value: 'k', disabled: true },
+        ]}
+      />,
+    );
+    await userEvent.setup().click(screen.getByText('Khoá'));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('Radio đơn — onChange(checked)', async () => {
+    const onChange = vi.fn();
+    render(<Radio checked={false} onChange={onChange}>r</Radio>);
+    await userEvent.setup().click(screen.getByText('r'));
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+});
+
+describe('Radio — branch phụ (Tier 5 sweep)', () => {
+  it('disabled → label class ink3 + không tick được', async () => {
+    const onChange = vi.fn();
+    render(<Radio disabled onChange={onChange}>r</Radio>);
+    expect(screen.getByText('r')).toHaveClass('cursor-not-allowed');
+    await userEvent.setup().click(screen.getByRole('radio'));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+// ── Coverage audit additions ─────────────────────────────────────────────────────
+describe('RadioGroup — group-level disabled (coverage audit)', () => {
+  it('disabled group → mọi radio khoá, click không gọi onChange', async () => {
+    const onChange = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <RadioGroup
+        value="a"
+        disabled
+        onChange={onChange}
+        options={[
+          { label: 'Free', value: 'a' },
+          { label: 'Pro', value: 'b' },
+        ]}
+      />,
+    );
+    const inputs = screen.getAllByRole('radio');
+    expect(inputs).toHaveLength(2);
+    for (const input of inputs) expect(input).toBeDisabled();
+    await user.click(screen.getByText('Pro'));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,36 @@
+// Rating — stars + hover preview + readonly (antd look).
+import { useState } from 'react';
+
+export interface RatingProps {
+  value?: number;
+  onChange?: (v: number) => void;
+  max?: number;
+  disabled?: boolean;
+  readOnly?: boolean;
+  className?: string;
+}
+
+export function Rating({ value = 0, onChange, max = 5, disabled, readOnly, className }: RatingProps) {
+  const [hover, setHover] = useState<number | null>(null);
+  const display = hover ?? value;
+  return (
+    <div className={`inline-flex gap-0.5${className ? ` ${className}` : ''}`} role="radiogroup" aria-label="Đánh giá">
+      {Array.from({ length: max }, (_, i) => i + 1).map((star) => (
+        <button
+          key={star}
+          type="button"
+          disabled={disabled || readOnly}
+          aria-label={`${star} sao`}
+          onMouseEnter={() => !disabled && !readOnly && setHover(star)}
+          onMouseLeave={() => setHover(null)}
+          onClick={() => !disabled && !readOnly && onChange?.(star)}
+          className={`cursor-pointer border-none bg-transparent p-0 text-lg leading-none transition-colors ${
+            star <= display ? 'text-st-doing' : 'text-line'
+          } ${disabled || readOnly ? 'cursor-default' : ''}`}
+        >
+          ★
+        </button>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,42 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Rating } from './index';
+const meta = { title: 'Forms/Rating', component: Rating, tags: ['autodocs'] } satisfies Meta<typeof Rating>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+/** Basic — 5 stars, click to rate (hover previews). */
+export const MacDinh: S = { name: 'Basic — click to rate' };
+
+/** CustomMax — 10-star scale (antd Rate count). */
+export const CustomMax: S = { name: 'Custom max — 10 stars', args: { value: 6, max: 10 } };
+
+/** ReadOnly — stars render but clicks are locked (display-only score). */
+export const ReadOnly: S = { args: { value: 3, readOnly: true } };
+
+/** Disabled — locked + dimmed (antd Rate disabled). */
+export const Disabled: S = { args: { value: 2, disabled: true } };
+
+/** Controlled — hover preview + picked value shown below. */
+export const Controlled: S = {
+  render: () => <RatingControlledDemo />,
+};
+
+/** DarkTheme — stars on dark canvas. */
+export const DarkTheme: S = {
+  render: () => (
+    <div data-bp-theme="dark" className="w-fit rounded-xl bg-canvas p-4">
+      <Rating value={4} />
+    </div>
+  ),
+};
+
+function RatingControlledDemo() {
+  const [v, setV] = useState(0);
+  return (
+    <div className="grid max-w-[240px] gap-2">
+      <Rating value={v} onChange={setV} />
+      <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/rating/rating.test.tsx

@@ -0,0 +1,45 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Rating } from './index.js';
+afterEach(cleanup);
+describe('Rating', () => {
+  it('max stars render; click → onChange', async () => {
+    const onChange = vi.fn();
+    render(<Rating onChange={onChange} />);
+    await userEvent.setup().click(screen.getByRole('button', { name: '3 sao' }));
+    expect(onChange).toHaveBeenCalledWith(3);
+  });
+  it('readonly → không click được', async () => {
+    const onChange = vi.fn();
+    render(<Rating readOnly onChange={onChange} />);
+    await userEvent.setup().click(screen.getByRole('button', { name: '1 sao' }));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+// ── Coverage audit additions ─────────────────────────────────────────────────────
+describe('Rating — coverage audit', () => {
+  it('disabled → không click được', async () => {
+    const onChange = vi.fn();
+    render(<Rating disabled onChange={onChange} />);
+    const star = screen.getByRole('button', { name: '4 sao' });
+    expect(star).toBeDisabled();
+    await userEvent.setup().click(star);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('max=10 → 10 sao; value 6 → 6 sao filled (class text-st-doing)', () => {
+    render(<Rating value={6} max={10} />);
+    const stars = screen.getAllByRole('button');
+    expect(stars).toHaveLength(10);
+    expect(stars[5].className).toContain('text-st-doing');
+    expect(stars[6].className).not.toContain('text-st-doing');
+  });
+
+  it('radiogroup aria + mỗi sao là button aria-label "N sao"', () => {
+    render(<Rating value={3} />);
+    expect(screen.getByRole('radiogroup', { name: 'Đánh giá' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: '3 sao' })).toHaveAttribute('aria-label', '3 sao');
+  });
+});

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

@@ -0,0 +1,72 @@
+// Result — trang kết quả (antd): icon lớn màu status + title + subTitle + extra.
+// Icon status = Icon SVG bộ chung (style sweep 2026-10-23 — bỏ glyph ký tự text);
+// success giữ SVG check-draw vẽ tay (motion waves); 404/500 là CHỮ SỐ cố ý, không glyph.
+import type { ReactNode } from 'react';
+import { Icon, type IconName } from '../icons/index.js';
+
+export type ResultStatus = 'success' | 'error' | 'info' | 'warning' | '404' | '500';
+
+const CONFIG: Record<string, { icon: IconName | '404' | '500'; color: string; defaultTitle: string }> = {
+  success: { icon: 'check', color: 'var(--st-done)', defaultTitle: 'Thành công' },
+  error: { icon: 'times', color: 'var(--st-fail)', defaultTitle: 'Có lỗi xảy ra' },
+  info: { icon: 'info-circle', color: 'var(--accent)', defaultTitle: 'Thông tin' },
+  warning: { icon: 'exclamation-triangle', color: 'var(--st-doing)', defaultTitle: 'Cảnh báo' },
+  '404': { icon: '404', color: 'var(--ink)', defaultTitle: 'Không tìm thấy trang' },
+  '500': { icon: '500', color: 'var(--ink)', defaultTitle: 'Lỗi máy chủ' },
+};
+
+export interface ResultProps {
+  /** Trạng thái — icon + màu + title mặc định theo status. */
+  status?: ResultStatus;
+  /** Tiêu đề (bỏ qua → dùng defaultTitle theo status). */
+  title?: ReactNode;
+  /** Dòng phụ dưới tiêu đề. */
+  subTitle?: ReactNode;
+  /** Nút actions (vd Quay lại trang chủ). */
+  extra?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+}
+
+export function Result({ status = 'info', title, subTitle, extra, children, className }: ResultProps) {
+  const cfg = CONFIG[status];
+  return (
+    <div className={`flex flex-col items-center gap-2 py-8 text-center animate-[bp-slide-up-in_var(--motion-slow)_var(--ease-enter)]${className ? ` ${className}` : ''}`}>
+      {status === 'success' ? (
+        // Success — check vẽ tay (bp-check-draw): circle + tick stroke pathLength=1,
+        // offset 1→0 chạy đúng mọi độ dài path. reduced-motion → hiện tức thì.
+        <svg aria-hidden="true" data-testid="result-check" viewBox="0 0 52 52" className="size-14 text-st-done">
+          <circle
+            cx="26" cy="26" r="23" fill="none" stroke="currentColor" strokeWidth="2.5" opacity="0.45"
+            pathLength={1} strokeDasharray={1}
+            style={{ animation: 'bp-check-draw 320ms var(--ease-enter) both' }}
+          />
+          <path
+            d="M16 27l7.5 7.5L37 20" fill="none" stroke="currentColor" strokeWidth="3.5"
+            strokeLinecap="round" strokeLinejoin="round"
+            pathLength={1} strokeDasharray={1}
+            style={{ animation: 'bp-check-draw 420ms 200ms var(--ease-enter) both' }}
+          />
+        </svg>
+      ) : (
+        <div
+          aria-hidden="true"
+          data-testid="result-icon"
+          className={status === 'error' ? 'text-st-fail' : status === 'warning' ? 'text-st-doing' : 'text-ink'}
+          style={status === 'error' || status === 'info' || status === 'warning' ? { color: cfg.color } : undefined}
+        >
+          {cfg.icon === '404' || cfg.icon === '500' ? (
+            <span className="text-5xl font-bold">{cfg.icon}</span>
+          ) : (
+            // 40px — tương đương khối glyph text-5xl cũ (SVG stroke mảnh hơn font nên giữ gần khung)
+            <Icon name={cfg.icon} size={40} />
+          )}
+        </div>
+      )}
+      <div className="text-h2 font-semibold text-ink">{title ?? cfg.defaultTitle}</div>
+      {subTitle && <div className="text-body text-ink2">{subTitle}</div>}
+      {children}
+      {extra && <div className="mt-2 flex gap-2">{extra}</div>}
+    </div>
+  );
+}

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

@@ -0,0 +1,82 @@
+// Parity matrix antd→tokens: docs/parity-matrix.md
+// Result stories — success/error/404 (icon per status; no custom icon prop).
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Result } from './index';
+import { Button } from '../button/index';
+
+/** Full-area status page — icon + title + actions per status. */
+const meta = { title: 'Feedback/Result', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Success: Story = {
+  name: 'Success — with extra actions',
+  render: () => (
+    <Result
+      status="success"
+      title="Task created"
+      subTitle="Task FE-42 is now in the sprint 12 backlog."
+      extra={<Button type="primary">View task</Button>}
+    />
+  ),
+};
+
+export const Error: Story = {
+  name: 'Error — assignee failure',
+  render: () => (
+    <Result
+      status="error"
+      title="Assignment failed"
+      subTitle="fail@demo.local did not receive the task — event went to the DLQ."
+      extra={<Button>Retry</Button>}
+    />
+  ),
+};
+
+export const NotFound: Story = {
+  name: '404 — page not found',
+  render: () => (
+    <Result
+      status="404"
+      title="404"
+      subTitle="The page you are looking for does not exist or was deleted."
+      extra={<Button type="primary">Back to home</Button>}
+    />
+  ),
+};
+
+export const ServerError: Story = {
+  name: '500 — server error',
+  render: () => (
+    <Result
+      status="500"
+      title="500"
+      subTitle="node-svc is not responding — on-call has been paged."
+      extra={<Button>Retry</Button>}
+    />
+  ),
+};
+
+export const WarningInfo: Story = {
+  name: 'Warning + Info — secondary statuses',
+  render: () => (
+    <div className="flex gap-8">
+      <Result status="warning" title="Due soon" subTitle="3 tasks due within 24h." />
+      <Result status="info" title="Scheduled maintenance" subTitle="Today 22:00–23:00." />
+    </div>
+  ),
+};
+
+export const DarkTheme: Story = {
+  name: 'DarkTheme — dark ink + status colors',
+  render: () => (
+    <div data-bp-theme="dark" className="p-4">
+      <Result
+        status="success"
+        title="Task created"
+        subTitle="Task FE-42 is now in the sprint 12 backlog (dark scope)."
+        extra={<Button type="primary">View task</Button>}
+      />
+    </div>
+  ),
+};

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

@@ -0,0 +1,57 @@
+// Result tests — 6 status (icon/màu/defaultTitle), override title/subTitle/extra, children, className.
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Result } from './index.js';
+
+afterEach(cleanup);
+
+describe('Result', () => {
+  it('success → check-draw svg + title mặc định (motion waves: stroke vẽ tay)', () => {
+    render(<Result status="success" />);
+    expect(screen.getByText('Thành công')).toBeInTheDocument();
+    const check = document.querySelector('[data-testid="result-check"]');
+    expect(check).not.toBeNull();
+    expect(check).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('title/subTitle/extra override + children', () => {
+    render(
+      <Result status="404" title="404" subTitle="Trang không tồn tại" extra={<button>Về chủ</button>}>
+        <p>detail</p>
+      </Result>,
+    );
+    expect(screen.getAllByText('404').length).toBeGreaterThanOrEqual(1); // icon + title đều "404"
+    expect(screen.getByText('Trang không tồn tại')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Về chủ' })).toBeInTheDocument();
+    expect(screen.getByText('detail')).toBeInTheDocument();
+  });
+
+  it.each([
+    ['success', 'Thành công', 'text-st-done'],
+    ['error', 'Có lỗi xảy ra', 'text-st-fail'],
+    ['info', 'Thông tin', 'text-ink'],
+    ['warning', 'Cảnh báo', 'text-st-doing'],
+    ['404', 'Không tìm thấy trang', 'text-ink'],
+    ['500', 'Lỗi máy chủ', 'text-ink'],
+  ] as const)('status %s → defaultTitle + màu icon đúng', (status, defaultTitle, colorCls) => {
+    render(<Result status={status} />);
+    expect(screen.getByText(defaultTitle)).toBeInTheDocument();
+    if (status === 'success') {
+      // success dùng check-draw svg (motion waves) — màu nằm trên svg
+      expect(document.querySelector('[data-testid="result-check"]')).toHaveClass('text-st-done');
+    } else {
+      // style sweep: icon = SVG bộ chung trong wrapper testid (404/500 giữ chữ số text)
+      expect(document.querySelector('[data-testid="result-icon"]')?.className).toContain(colorCls);
+    }
+  });
+
+  it('icon là aria-hidden (decorative)', () => {
+    render(<Result status="error" />);
+    expect(document.querySelector('[data-testid="result-icon"]')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('className passthrough', () => {
+    render(<Result status="info" className="pt-4" />);
+    expect(document.querySelector('.pt-4.text-center')).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,83 @@
+// Reveal — hiện dần khi vào viewport (motion-effects W8, 0 deps):
+// IntersectionObserver thêm class animate CÓ SẴN — direction=up dùng
+// bp-slide-up-in, các hướng khác bp-fade-in + transition transform riêng
+// (KHÔNG tạo keyframe mới). once (mặc định) chỉ reveal lần đầu; once=false →
+// ẩn lại khi rời viewport. Delay dùng animation-delay + fill backwards nên
+// element vẫn ẩn trong lúc trễ. prefers-reduced-motion tự tắt nhờ block global.
+import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+
+export type RevealDirection = 'up' | 'down' | 'left' | 'right';
+
+export interface RevealProps {
+  /** Cạnh element trôi vào từ: up = từ dưới (slide-up-in) · down/left/right = fade + transition. */
+  direction?: RevealDirection;
+  /** Trễ ms trước khi animate (animation/transition delay). */
+  delay?: number;
+  /** Chỉ reveal lần đầu (mặc định true); false → ẩn lại khi rời viewport. */
+  once?: boolean;
+  /** RootMargin IntersectionObserver (vd '0px 0px -80px 0px' — trigger muộn hơn). */
+  rootMargin?: string;
+  className?: string;
+  children: ReactNode;
+}
+
+/** Offset ẩn ban đầu theo hướng (up đi bằng keyframe nên chỉ cần opacity). */
+const HIDDEN_OFFSET: Record<RevealDirection, string> = {
+  up: 'none',
+  down: 'translateY(-12px)',
+  left: 'translateX(-12px)',
+  right: 'translateX(12px)',
+};
+
+export function Reveal({ direction = 'up', delay = 0, once = true, rootMargin, className, children }: RevealProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [shown, setShown] = useState(false);
+
+  useEffect(() => {
+    const el = ref.current;
+    // Không IO (SSR/môi trường lạ) → hiện luôn, không kẹt trạng thái ẩn
+    if (!el || typeof IntersectionObserver === 'undefined') {
+      setShown(true);
+      return;
+    }
+    const io = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setShown(true);
+            if (once) io.disconnect();
+          } else if (!once) {
+            setShown(false);
+          }
+        }
+      },
+      { rootMargin: rootMargin ?? undefined },
+    );
+    io.observe(el);
+    return () => io.disconnect();
+  }, [once, rootMargin]);
+
+  const delayCss = `${delay}ms`;
+  // fill `backwards`: trong khoảng delay element giữ keyframe "from" (opacity 0)
+  const anim = shown
+    ? direction === 'up'
+      ? 'animate-[bp-slide-up-in_var(--motion-base)_var(--ease-enter)_backwards]'
+      : 'animate-[bp-fade-in_var(--motion-fast)_var(--ease-enter)_backwards]'
+    : '';
+  const style: CSSProperties = shown
+    ? {
+        animationDelay: delayCss,
+        transform: 'none',
+        // down/left/right: opacity do keyframe, offset do transition transform
+        transition: direction === 'up' ? undefined : `transform var(--motion-base) var(--ease-enter) ${delayCss}`,
+      }
+    : { transform: HIDDEN_OFFSET[direction] };
+
+  // ẩn = opacity-0; hiện = gỡ opacity-0 (sau animation computed opacity = 1)
+  const cls = `${shown ? anim : 'opacity-0'}${className ? ` ${className}` : ''}`;
+  return (
+    <div ref={ref} style={style} className={cls}>
+      {children}
+    </div>
+  );
+}