create-wakii-stack 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,45 @@
+// Flex — wrapper bố cục nhẹ kiểu antd v5: <Flex vertical gap justify align wrap>.
+// Gap dùng thang Space của thư viện (small 8 / middle 16 / large 24 | number px)
+// để nhất quán nội bộ; justify/align nhận giá trị CSS thô.
+import type { ReactNode } from 'react';
+
+export type FlexGap = 'small' | 'middle' | 'large' | number;
+export type FlexJustify = 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+export type FlexAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+
+export interface FlexProps {
+  /** Xếp dọc (flex-col) thay vì ngang (mặc định ngang). */
+  vertical?: boolean;
+  /** Khoảng cách giữa item: thang Space hoặc px tuỳ ý (mặc định small = 8). */
+  gap?: FlexGap;
+  /** Phân bố item (justify-content). */
+  justify?: FlexJustify;
+  /** Căn item (align-items). */
+  align?: FlexAlign;
+  /** Cho item xuống hàng khi tràn. */
+  wrap?: boolean;
+  children: ReactNode;
+  className?: string;
+}
+
+const GAP: Record<Exclude<FlexGap, number>, number> = { small: 8, middle: 16, large: 24 };
+
+export function Flex({
+  vertical = false,
+  gap = 'small',
+  justify,
+  align,
+  wrap = false,
+  children,
+  className,
+}: FlexProps) {
+  const gapPx = typeof gap === 'number' ? gap : GAP[gap];
+  return (
+    <div
+      className={`flex${vertical ? ' flex-col' : ' flex-row'}${wrap ? ' flex-wrap' : ''}${className ? ` ${className}` : ''}`}
+      style={{ gap: gapPx, justifyContent: justify, alignItems: align }}
+    >
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,82 @@
+// FloatButton stories — single FAB, Group (hover/click), BackTop on a tall page.
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Icon } from '../icons/index';
+import { FloatButton, FloatButtonBackTop, FloatButtonGroup } from './index';
+
+/** Floating action button — antd FloatButton lite, fixed bottom-right. */
+const meta = { title: 'Navigation/FloatButton', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Basic — single button with tooltip (hover for the title bubble). */
+export const Basic: Story = {
+  render: () => (
+    <div className="relative h-24 overflow-hidden rounded-xl border border-line bg-canvas">
+      <FloatButton icon={<Icon name="pencil" size={16} />} tooltip="Soạn thảo" />
+    </div>
+  ),
+};
+
+/** Group — hover the trigger to fan out quick actions. */
+export const Group: Story = {
+  render: () => (
+    <div className="relative h-40 overflow-hidden rounded-xl border border-line bg-canvas">
+      <FloatButtonGroup ariaLabel="Thao tác nhanh">
+        <FloatButton icon={<Icon name="pencil" size={16} />} tooltip="Soạn thảo" />
+        <FloatButton icon={<Icon name="upload" size={16} />} tooltip="Tải lên" />
+        <FloatButton icon={<Icon name="download" size={16} />} tooltip="Tải xuống" />
+      </FloatButtonGroup>
+    </div>
+  ),
+};
+
+/** GroupClick — trigger=click keeps the cluster open until toggled. */
+export const GroupClick: Story = {
+  name: 'Group — click trigger',
+  render: () => (
+    <div className="relative h-40 overflow-hidden rounded-xl border border-line bg-canvas">
+      <FloatButtonGroup trigger="click" ariaLabel="Thao tác nhanh">
+        <FloatButton icon={<Icon name="file" size={16} />} tooltip="Tạo file" />
+        <FloatButton icon={<Icon name="folder" size={16} />} tooltip="Tạo thư mục" />
+      </FloatButtonGroup>
+    </div>
+  ),
+};
+
+/** BackTop — scroll the page (button below): the pill appears past 400px, click returns to top. */
+export const BackTop: Story = {
+  render: () => (
+    <div>
+      <p className="text-label text-ink3">Scroll the page (or click the button) — the pill appears past 400px.</p>
+      <div className="my-3">
+        <button
+          type="button"
+          onClick={() => window.scrollTo({ top: 800, behavior: 'smooth' })}
+          className="cursor-pointer rounded-lg border border-line bg-s2 px-3 py-1.5 text-body text-ink hover:bg-s3"
+        >
+          Scroll down ↓
+        </button>
+      </div>
+      <div className="flex flex-col gap-2">
+        {Array.from({ length: 25 }, (_, i) => (
+          <div key={i} className="rounded-lg border border-line bg-s2 p-3 text-body text-ink2">
+            Filler block {i + 1}
+          </div>
+        ))}
+      </div>
+      <FloatButtonBackTop visibilityHeight={400} />
+    </div>
+  ),
+};
+
+/** DarkTheme — buttons follow tokens on dark canvas (open via hover). */
+export const DarkTheme: Story = {
+  render: () => (
+    <div data-bp-theme="dark" className="relative h-40 overflow-hidden rounded-xl bg-canvas">
+      <FloatButton icon={<Icon name="pencil" size={16} />} tooltip="Soạn thảo" />
+      <FloatButtonGroup icon={<Icon name="plus" size={20} />} ariaLabel="Thao tác nhanh">
+        <FloatButton icon={<Icon name="upload" size={16} />} tooltip="Tải lên" />
+      </FloatButtonGroup>
+    </div>
+  ),
+};

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

@@ -0,0 +1,107 @@
+// FloatButton tests — render + onClick, Group hover/click trigger, controlled open,
+// BackTop threshold + scrollTo top.
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { FloatButton, FloatButtonBackTop, FloatButtonGroup } from './index.js';
+import { Icon } from '../icons/index.js';
+
+afterEach(cleanup);
+
+describe('FloatButton', () => {
+  it('render nút với aria-label từ tooltip + click gọi onClick', async () => {
+    const onClick = vi.fn();
+    const user = userEvent.setup();
+    render(<FloatButton icon={<Icon name="plus" size={16} />} tooltip="Thêm mới" onClick={onClick} />);
+    await user.click(screen.getByRole('button', { name: 'Thêm mới' }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('shape square → rounded-lg; circle (mặc định) → rounded-pill', () => {
+    const { rerender } = render(<FloatButton icon="+" tooltip="b" shape="square" />);
+    expect(screen.getByRole('button', { name: 'b' }).className).toContain('rounded-lg');
+    rerender(<FloatButton icon="+" tooltip="c" />);
+    expect(screen.getByRole('button', { name: 'c' }).className).toContain('rounded-pill');
+  });
+});
+
+describe('FloatButtonGroup', () => {
+  it('trigger hover (mặc định): mouseEnter → mở cụm + aria-expanded; mouseLeave → đóng', () => {
+    render(
+      <FloatButtonGroup>
+        <FloatButton icon={<Icon name="pencil" size={16} />} tooltip="Soạn" />
+      </FloatButtonGroup>,
+    );
+    const trigger = screen.getByRole('button', { name: 'Thao tác nhanh' });
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    fireEvent.mouseEnter(trigger.closest('div')!);
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    fireEvent.mouseLeave(trigger.closest('div')!);
+    expect(screen.queryByRole('menu')).toBeNull();
+  });
+
+  it('trigger click: click mở; click lần nữa đóng', async () => {
+    const user = userEvent.setup();
+    render(
+      <FloatButtonGroup trigger="click">
+        <FloatButton icon={<Icon name="pencil" size={16} />} tooltip="Soạn" />
+      </FloatButtonGroup>,
+    );
+    const trigger = screen.getByRole('button', { name: 'Thao tác nhanh' });
+    await user.click(trigger);
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    await user.click(trigger);
+    expect(screen.queryByRole('menu')).toBeNull();
+  });
+
+  it('controlled open → cụm hiện theo prop, không cần trigger', () => {
+    render(
+      <FloatButtonGroup open>
+        <FloatButton icon={<Icon name="pencil" size={16} />} tooltip="Soạn" />
+        <FloatButton icon={<Icon name="upload" size={16} />} tooltip="Tải lên" />
+      </FloatButtonGroup>,
+    );
+    expect(screen.getAllByRole('button', { name: 'Soạn' })).toHaveLength(1);
+    expect(screen.getAllByRole('button', { name: 'Tải lên' })).toHaveLength(1);
+  });
+
+  it('onOpenChange báo trạng thái khi hover mở (trigger hover)', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <FloatButtonGroup onOpenChange={onOpenChange}>
+        <FloatButton icon="+" tooltip="x" />
+      </FloatButtonGroup>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'Thao tác nhanh' }).closest('div')!);
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+});
+
+describe('FloatButtonBackTop', () => {
+  it('scrollY dưới ngưỡng → ẩn; vượt ngưỡng → hiện + click → scrollTo top', async () => {
+    let y = 0;
+    vi.spyOn(window, 'scrollY', 'get').mockImplementation(() => y);
+    const scrollTo = vi.fn();
+    vi.spyOn(window, 'scrollTo').mockImplementation(scrollTo);
+    render(<FloatButtonBackTop visibilityHeight={100} />);
+    expect(screen.queryByRole('button', { name: 'Về đầu trang' })).toBeNull();
+    y = 150;
+    fireEvent.scroll(window);
+    const btn = screen.getByRole('button', { name: 'Về đầu trang' });
+    await userEvent.setup().click(btn);
+    await waitFor(() => expect(scrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'smooth' }));
+  });
+
+  it('visibilityHeight tuỳ chỉnh — dưới ngưỡng mới vẫn ẩn', () => {
+    const y = 300;
+    vi.spyOn(window, 'scrollY', 'get').mockImplementation(() => y);
+    render(<FloatButtonBackTop visibilityHeight={500} />);
+    fireEvent.scroll(window);
+    expect(screen.queryByRole('button', { name: 'Về đầu trang' })).toBeNull();
+  });
+
+  it('gắn được qua FloatButton.BackTop (sub-component antd style)', () => {
+    expect((FloatButton as unknown as { BackTop: unknown }).BackTop).toBe(FloatButtonBackTop);
+  });
+});

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

@@ -0,0 +1,124 @@
+// FloatButton — nút nổi góc màn hình (antd FloatButton lite) + Group mở cụm
+// (trigger hover/click) + BackTop tích hợp (hiện sau ngưỡng cuộn, về đầu trang).
+// Depth contract 2026-10-19 (Geist): hover nhấc 1px + viền đậm mực 20% + ele-3
+// chồng shadow-pop, press chìm 1px nén bóng (ele-1), icon slide 2px, wash sheen,
+// stagger cụm 40ms ease-smooth — không scale lòe loẹt.
+import { useEffect, useState, type ReactNode } from 'react';
+import { Icon } from '../icons/index.js';
+
+export interface FloatButtonProps {
+  /** Icon từ bộ primeicons (<Icon name size>). */
+  icon: ReactNode;
+  onClick?: () => void;
+  /** circle (mặc định) | square — bo góc pill hay rounded-lg. */
+  shape?: 'circle' | 'square';
+  /** Nhãn accessible + tooltip khi hover. */
+  tooltip?: string;
+  className?: string;
+}
+
+export function FloatButton({ icon, onClick, shape = 'circle', tooltip, className }: FloatButtonProps) {
+  const radius = shape === 'square' ? 'rounded-lg' : 'rounded-pill';
+  return (
+    <button
+      type="button"
+      title={tooltip}
+      aria-label={tooltip}
+      aria-haspopup={undefined}
+      onClick={onClick}
+      className={`group grid size-10 cursor-pointer place-items-center border border-line bg-s1 text-ink2 [background-image:var(--wash)] shadow-[var(--shadow-pop)] transition-[color,background-color,border-color,box-shadow,transform] duration-[240ms] [transition-timing-function:var(--ease-smooth)] hover:-translate-y-px hover:bg-s2 hover:text-accent hover:border-[color-mix(in_srgb,var(--ink)_20%,transparent)] hover:shadow-[var(--shadow-pop),var(--ele-3)] active:translate-y-px active:shadow-[var(--ele-1)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${radius}${className ? ` ${className}` : ''}`}
+    >
+      <span className="grid place-items-center transition-transform duration-[240ms] [transition-timing-function:var(--ease-smooth)] group-hover:translate-x-0.5">
+        {icon}
+      </span>
+    </button>
+  );
+}
+
+export interface FloatButtonGroupProps {
+  /** hover (mặc định) | click — cách mở cụm nút. */
+  trigger?: 'hover' | 'click';
+  /** Icon nút kích hoạt (mặc định: dấu +). */
+  icon?: ReactNode;
+  /** Controlled mở/đóng; không truyền → uncontrolled. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** aria-label nút kích hoạt. */
+  ariaLabel?: string;
+  children: ReactNode;
+  className?: string;
+}
+
+export function FloatButtonGroup({ trigger = 'hover', icon, open, onOpenChange, ariaLabel = 'Thao tác nhanh', children, className }: FloatButtonGroupProps) {
+  const [inner, setInner] = useState(false);
+  const isOpen = open ?? inner;
+  function setOpen(next: boolean) {
+    if (open === undefined) setInner(next);
+    onOpenChange?.(next);
+  }
+  const items = Array.isArray(children) ? children : [children];
+  return (
+    <div
+      className={`fixed bottom-6 right-6 z-[var(--z-toast)] flex flex-col items-center gap-2${className ? ` ${className}` : ''}`}
+      onMouseEnter={trigger === 'hover' ? () => setOpen(true) : undefined}
+      onMouseLeave={trigger === 'hover' ? () => setOpen(false) : undefined}
+    >
+      {isOpen && (
+        <div role="menu" className="flex flex-col items-center gap-2 animate-[bp-zoom-in_var(--motion-base)_var(--ease-smooth)]">
+          {items.map((child, i) => (
+            <div key={i} role="none" style={{ animation: `bp-slide-up-in 240ms var(--ease-smooth) ${(items.length - 1 - i) * 40}ms both` }}>
+              {child}
+            </div>
+          ))}
+        </div>
+      )}
+      <button
+        type="button"
+        aria-label={ariaLabel}
+        aria-expanded={isOpen}
+        aria-haspopup="menu"
+        onClick={trigger === 'click' ? () => setOpen(!isOpen) : undefined}
+        className="grid size-12 cursor-pointer place-items-center rounded-pill border-none bg-accent text-xl text-white shadow-[var(--shadow-pop)] transition-[box-shadow,transform] duration-[240ms] [transition-timing-function:var(--ease-smooth)] hover:shadow-[var(--shadow-pop),var(--ele-3)] active:translate-y-px active:shadow-[var(--ele-1)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 [&>svg]:text-white"
+      >
+        <span className={`transition-transform duration-200 ${isOpen ? 'rotate-45' : ''}`}>{icon ?? <Icon name="plus" size={20} />}</span>
+      </button>
+    </div>
+  );
+}
+
+export interface FloatButtonBackTopProps {
+  /** Ngưỡng scrollY (px) trước khi hiện — mặc định 400. */
+  visibilityHeight?: number;
+  tooltip?: string;
+  className?: string;
+}
+
+/** BackTop — FloatButton về đầu trang, hiện khi scrollY > visibilityHeight. */
+export function FloatButtonBackTop({ visibilityHeight = 400, tooltip = 'Về đầu trang', className }: FloatButtonBackTopProps) {
+  const [visible, setVisible] = useState(false);
+  useEffect(() => {
+    const fn = () => setVisible(window.scrollY > visibilityHeight);
+    window.addEventListener('scroll', fn, { passive: true });
+    return () => window.removeEventListener('scroll', fn);
+  }, [visibilityHeight]);
+  return (
+    <div className={`fixed bottom-6 right-6 z-[var(--z-toast)]${className ? ` ${className}` : ''}`}>
+      {visible && (
+        <button
+          type="button"
+          aria-label={tooltip}
+          title={tooltip}
+          onClick={() => window.scrollTo({ top: 0, behavior: 'smooth' })}
+          className="group grid size-10 animate-[bp-fade-in_var(--motion-base)_var(--ease-smooth)] cursor-pointer place-items-center rounded-pill border border-line bg-s1 text-ink2 [background-image:var(--wash)] shadow-[var(--shadow-pop)] transition-[color,background-color,border-color,box-shadow,transform] duration-[240ms] [transition-timing-function:var(--ease-smooth)] hover:-translate-y-px hover:bg-s2 hover:text-accent hover:border-[color-mix(in_srgb,var(--ink)_20%,transparent)] hover:shadow-[var(--shadow-pop),var(--ele-3)] active:translate-y-px active:shadow-[var(--ele-1)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+        >
+          <span className="grid place-items-center transition-transform duration-[240ms] [transition-timing-function:var(--ease-smooth)] group-hover:-translate-y-0.5">
+            <Icon name="chevron-up" size={16} />
+          </span>
+        </button>
+      )}
+    </div>
+  );
+}
+
+/** Sub-component: <FloatButton.BackTop /> (antd style). */
+(FloatButton as unknown as { BackTop: typeof FloatButtonBackTop }).BackTop = FloatButtonBackTop;

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

@@ -0,0 +1,78 @@
+// Galleria stories — real photography via picsum.photos (seeded URLs: stable
+// across loads, no auth, plain-CORS <img> safe) — same pattern as image.stories.
+// Scroll-snap swipe + dot indicators; every photo carries a descriptive caption.
+// Tests stay offline (galleria.test.tsx uses local paths — network-free).
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Galleria, type GalleriaImage } from './index';
+
+// Meta WITH component — every story carries args (component has a required
+// `images` prop, so render-only stories here would fail CSF typecheck).
+const meta = { title: 'Data Display/Galleria', component: Galleria, tags: ['autodocs'] } satisfies Meta<typeof Galleria>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+/** Seeded picsum URL — deterministic real photo per seed name. */
+function photo(seed: string, w: number, h: number) {
+  return `https://picsum.photos/seed/${seed}/${w}/${h}`;
+}
+
+const TRIP: GalleriaImage[] = [
+  {
+    src: photo('orca-ridge', 1280, 720),
+    alt: 'Mountain ridge above the tree line (picsum seed: orca-ridge)',
+    caption: 'Day 1 — ridge trail, thin air and a clear sky',
+  },
+  {
+    src: photo('orca-bay', 1280, 720),
+    alt: 'Bay at sunset with boats at anchor (picsum seed: orca-bay)',
+    caption: 'Day 2 — the bay calms down at golden hour',
+  },
+  {
+    src: photo('orca-dune', 1280, 720),
+    alt: 'Sand dunes with wind-carved ripples (picsum seed: orca-dune)',
+    caption: 'Day 3 — dunes reshape themselves overnight',
+  },
+  {
+    src: photo('orca-lake', 1280, 720),
+    alt: 'Alpine lake reflecting the valley walls (picsum seed: orca-lake)',
+    caption: 'Day 4 — still water, best photo stop of the trip',
+  },
+];
+
+/** Basic — 4 real photos, swipe/scroll or click the dots; each has a caption. */
+export const Basic: S = {
+  name: 'Basic — real photos with trip captions',
+  args: { images: TRIP, className: 'max-w-2xl' },
+};
+
+/** WithoutCaptions — same set, no caption paragraph (cleaner media strip). */
+export const WithoutCaptions: S = {
+  name: 'Without captions — media strip only',
+  args: { images: TRIP.map(({ src, alt }) => ({ src, alt })), className: 'max-w-2xl' },
+};
+
+/** SingleImage — one photo, one dot (single indicator). */
+export const SingleImage: S = {
+  name: 'Single — one photo (single dot indicator)',
+  args: {
+    images: [
+      {
+        src: photo('orca-meadow', 1280, 720),
+        alt: 'Wildflower meadow under a wide sky (picsum seed: orca-meadow)',
+        caption: 'A single slide — one dot, no swipe needed',
+      },
+    ],
+    className: 'max-w-2xl',
+  },
+};
+
+/** DarkTheme — real photos on the dark canvas (tokens cascade). */
+export const DarkTheme: S = {
+  name: 'Dark theme',
+  args: { images: TRIP.slice(0, 3), className: 'max-w-2xl' },
+  render: (args) => (
+    <div data-bp-theme="dark" className="rounded-xl bg-canvas p-4">
+      <Galleria {...args} />
+    </div>
+  ),
+};

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

@@ -0,0 +1,67 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Galleria } from './index.js';
+afterEach(cleanup);
+
+const IMAGES = [
+  { src: '/a.png', alt: 'a' },
+  { src: '/b.png', alt: 'b', caption: 'Caption B' },
+];
+
+describe('Galleria', () => {
+  it('renders images + captions + dots', () => {
+    render(<Galleria images={IMAGES} />);
+    expect(screen.getByAltText('a')).toBeInTheDocument();
+    expect(screen.getByAltText('b')).toBeInTheDocument();
+    expect(screen.getByText('Caption B')).toBeInTheDocument();
+    expect(screen.getAllByRole('button', { name: /Ảnh/ }).length).toBe(2);
+  });
+
+  it('ảnh không caption → không p trống; caption chỉ ở đúng ảnh', () => {
+    render(<Galleria images={IMAGES} />);
+    expect(screen.queryByText('Caption A')).toBeNull();
+    // caption là <p> — chỉ 1 caption cho 2 ảnh
+    expect(document.querySelectorAll('p').length).toBe(1);
+  });
+
+  it('dot đầu active ngay (aria-current); dot còn lại không', () => {
+    render(<Galleria images={IMAGES} />);
+    const dots = screen.getAllByRole('button', { name: /Ảnh/ });
+    expect(dots[0]).toHaveAttribute('aria-current', 'true');
+    expect(dots[1]).not.toHaveAttribute('aria-current');
+  });
+
+  it('click dot → aria-current chuyển + scrollTo tới đúng vị trí track', async () => {
+    const user = userEvent.setup();
+    // jsdom không có Element.scrollTo — stub thủ công (browser thật có sẵn)
+    const scrollTo = vi.fn();
+    const proto = HTMLElement.prototype as unknown as { scrollTo?: unknown };
+    const hadScrollTo = 'scrollTo' in proto;
+    const original = proto.scrollTo;
+    Object.defineProperty(proto, 'scrollTo', { configurable: true, value: scrollTo });
+    try {
+      render(<Galleria images={IMAGES} />);
+      const dots = screen.getAllByRole('button', { name: /Ảnh/ });
+      await user.click(dots[1]!);
+      expect(dots[1]).toHaveAttribute('aria-current', 'true');
+      expect(dots[0]).not.toHaveAttribute('aria-current');
+      expect(scrollTo).toHaveBeenCalledWith({ left: expect.any(Number), behavior: 'smooth' });
+    } finally {
+      if (hadScrollTo) (proto as { scrollTo: unknown }).scrollTo = original;
+      else delete (proto as { scrollTo?: unknown }).scrollTo;
+    }
+  });
+
+  it('className passthrough lên container', () => {
+    const { container } = render(<Galleria images={IMAGES} className="marker" />);
+    expect(container.firstElementChild).toHaveClass('marker');
+  });
+
+  it('1 ảnh → 1 dot, active ngay', () => {
+    render(<Galleria images={[IMAGES[0]!]} />);
+    const dots = screen.getAllByRole('button', { name: /Ảnh/ });
+    expect(dots).toHaveLength(1);
+    expect(dots[0]).toHaveAttribute('aria-current', 'true');
+  });
+});

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

@@ -0,0 +1,47 @@
+// Galleria — gallery CSS scroll-snap lite (hướng A — đủ gallery cơ bản, 0 deps).
+// Indicator click scroll qua trackRef (trước đây document.querySelector('.snap-x')
+// — query toàn document, trúng nhầm track galleria khác khi 2 gallery cùng trang).
+import { useRef, useState } from 'react';
+
+export interface GalleriaImage {
+  /** Đường dẫn ảnh (bắt buộc). */
+  src: string;
+  /** Alt bắt buộc a11y. */
+  alt: string;
+  /** Chú thích dưới ảnh (text-body, căn giữa). */
+  caption?: string;
+}
+
+export interface GalleriaProps {
+  /** Ảnh gallery — scroll-snap ngang, indicator dưới click nhảy tới. */
+  images: GalleriaImage[];
+  className?: string;
+}
+
+export function Galleria({ images, className }: GalleriaProps) {
+  const [active, setActive] = useState(0);
+  const trackRef = useRef<HTMLDivElement>(null);
+  return (
+    <div className={`overflow-hidden rounded-xl${className ? ` ${className}` : ''}`}>
+      <div ref={trackRef} className="flex overflow-x-auto snap-x snap-mandatory scroll-smooth"
+        onScroll={(e) => {
+          const idx = Math.round(e.currentTarget.scrollLeft / e.currentTarget.clientWidth);
+          setActive(idx);
+        }}>
+        {images.map((img, i) => (
+          <div key={i} className="w-full shrink-0 snap-center">
+            <img src={img.src} alt={img.alt} className="aspect-video w-full object-cover" />
+            {img.caption && <p className="p-2 text-center text-body text-ink2">{img.caption}</p>}
+          </div>
+        ))}
+      </div>
+      <div className="flex justify-center gap-1.5 py-2">
+        {images.map((_, i) => (
+          <button key={i} type="button" aria-label={`Ảnh ${i + 1}`} aria-current={i === active ? 'true' : undefined}
+            onClick={() => { const track = trackRef.current; if (track) track.scrollTo({ left: i * track.clientWidth, behavior: 'smooth' }); setActive(i); }}
+            className={`size-2 cursor-pointer rounded-pill border-none outline-none focus-visible:ring-2 focus-visible:ring-accent/40 transition-colors duration-200 ease-[var(--ease-smooth)] ${i === active ? 'bg-accent' : 'bg-line hover:bg-ink3'}`} />
+        ))}
+      </div>
+    </div>
+  );
+}