create-wakii-stack 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,94 @@
+// AutoComplete tests — gõ → suggestion lọc, chọn → onSelect + label, Escape,
+// không match, cap 8 suggestions.
+import { cleanup, render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AutoComplete } from './index.js';
+
+const SUGGESTIONS = [
+  { label: 'Học TypeScript', value: 'ts' },
+  { label: 'Học Rust', value: 'rust' },
+  { label: 'Viết test E2E', value: 'e2e' },
+];
+
+afterEach(cleanup);
+
+describe('AutoComplete', () => {
+  it('gõ → suggestions lọc theo label; không khớp không xuất hiện', async () => {
+    const user = userEvent.setup();
+    render(<AutoComplete suggestions={SUGGESTIONS} />);
+    const input = screen.getByRole('combobox', { name: 'Autocomplete' });
+    await user.type(input, 'học');
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+    expect(screen.getByRole('option', { name: 'Học TypeScript' })).toBeInTheDocument();
+    expect(screen.getByRole('option', { name: 'Học Rust' })).toBeInTheDocument();
+    expect(screen.queryByRole('option', { name: 'Viết test E2E' })).toBeNull();
+  });
+
+  it('onChange bắn theo từng keystroke', async () => {
+    const onChange = vi.fn();
+    const user = userEvent.setup();
+    render(<AutoComplete suggestions={SUGGESTIONS} onChange={onChange} />);
+    await user.type(screen.getByRole('combobox', { name: 'Autocomplete' }), 'học');
+    expect(onChange).toHaveBeenLastCalledWith('học');
+  });
+
+  it('chọn suggestion → onSelect(value) + input hiện label + dropdown đóng', async () => {
+    const onSelect = vi.fn();
+    const user = userEvent.setup();
+    render(<AutoComplete suggestions={SUGGESTIONS} onSelect={onSelect} />);
+    const input = screen.getByRole('combobox', { name: 'Autocomplete' });
+    await user.type(input, 'rust');
+    // handler nằm ở <button> trong li — click đúng target
+    await user.click(within(screen.getByRole('option', { name: 'Học Rust' })).getByRole('button'));
+    expect(onSelect).toHaveBeenCalledWith('rust');
+    expect(input).toHaveValue('Học Rust');
+    expect(screen.queryByRole('listbox')).toBeNull();
+  });
+
+  it('không match → không listbox', async () => {
+    const user = userEvent.setup();
+    render(<AutoComplete suggestions={SUGGESTIONS} />);
+    await user.type(screen.getByRole('combobox', { name: 'Autocomplete' }), 'zzz');
+    expect(screen.queryByRole('listbox')).toBeNull();
+  });
+
+  it('Escape đóng dropdown (aria-expanded false)', async () => {
+    const user = userEvent.setup();
+    render(<AutoComplete suggestions={SUGGESTIONS} />);
+    const input = screen.getByRole('combobox', { name: 'Autocomplete' });
+    await user.type(input, 'học');
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+    await user.keyboard('{Escape}');
+    expect(screen.queryByRole('listbox')).toBeNull();
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('tối đa 8 suggestions hiển thị', async () => {
+    const many = Array.from({ length: 12 }, (_, i) => ({ label: `Task ${i}`, value: String(i) }));
+    const user = userEvent.setup();
+    render(<AutoComplete suggestions={many} />);
+    await user.type(screen.getByRole('combobox', { name: 'Autocomplete' }), 'task');
+    expect(screen.getAllByRole('option')).toHaveLength(8);
+  });
+});
+
+describe('AutoComplete — matrix gaps (a11y/props)', () => {
+  it('a11y — role=combobox, aria-expanded đổi khi mở, aria-controls trỏ listbox', async () => {
+    const user = userEvent.setup();
+    render(<AutoComplete suggestions={SUGGESTIONS} />);
+    const input = screen.getByRole('combobox', { name: 'Autocomplete' });
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+    await user.type(input, 'học');
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+    const listId = input.getAttribute('aria-controls');
+    expect(listId).toBeTruthy();
+    expect(screen.getByRole('listbox')).toHaveAttribute('id', listId!);
+  });
+
+  it('placeholder + className passthrough', () => {
+    const { container } = render(<AutoComplete suggestions={SUGGESTIONS} placeholder="Tìm việc…" className="marker" />);
+    expect(screen.getByRole('combobox', { name: 'Autocomplete' })).toHaveAttribute('placeholder', 'Tìm việc…');
+    expect(container.firstElementChild).toHaveClass('marker');
+  });
+});

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

@@ -0,0 +1,54 @@
+// AutoComplete — Select editable standalone: input + suggestion dropdown.
+import { useId, useState } from 'react';
+
+export interface AutoCompleteOption { label: string; value: string }
+
+export interface AutoCompleteProps {
+  value?: string;
+  onChange?: (value: string) => void;
+  onSelect?: (value: string) => void;
+  suggestions?: AutoCompleteOption[];
+  placeholder?: string;
+  className?: string;
+}
+
+export function AutoComplete({ value: valueProp, onChange, onSelect, suggestions = [], placeholder, className }: AutoCompleteProps) {
+  const [internal, setInternal] = useState('');
+  const [open, setOpen] = useState(false);
+  const value = valueProp ?? internal;
+  const listId = useId();
+
+  const matches = value && open
+    ? suggestions.filter((s) => s.label.toLowerCase().includes(value.toLowerCase())).slice(0, 8)
+    : [];
+
+  return (
+    <div className={`relative inline-flex w-full${className ? ` ${className}` : ''}`}>
+      <input
+        aria-label="Autocomplete" role="combobox" aria-expanded={matches.length > 0} aria-controls={listId}
+        value={value} placeholder={placeholder}
+        onChange={(e) => { setInternal(e.target.value); onChange?.(e.target.value); setOpen(true); }}
+        onFocus={() => setOpen(true)}
+        onBlur={() => setTimeout(() => setOpen(false), 150)}
+        onKeyDown={(e) => {
+          if (e.key === 'ArrowDown') { e.preventDefault(); setOpen(true); }
+          if (e.key === 'Escape') setOpen(false);
+        }}
+        className="h-8 w-full rounded-lg border border-line bg-s2 px-3 text-body text-ink placeholder:text-ink4 focus:border-accent-hi focus:outline-none"
+      />
+      {open && matches.length > 0 && (
+        <ul id={listId} role="listbox" className="absolute left-0 top-full z-[var(--z-popover)] m-0 mt-1 w-full origin-top list-none overflow-hidden rounded-xl border border-line bg-s2 shadow-[var(--shadow-pop)] animate-[bp-zoom-in_var(--motion-fast)_var(--ease-enter)]">
+          {matches.map((s) => (
+            <li key={s.value} role="option" aria-selected={value === s.value}>
+              <button type="button"
+                onClick={() => { setInternal(s.label); onSelect?.(s.value); setOpen(false); }}
+                className={`w-full cursor-pointer border-none bg-transparent px-3 py-1.5 text-left text-body text-ink hover:bg-s3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${value === s.value ? 'bg-s3 font-medium' : ''}`}>
+                {s.label}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Avatar } from './index';
+import { Tag } from '../../index.js';
+/** Identity chip — letter initials by default, photo via `src`. */
+const meta = { title: 'Data Display/Avatar', component: Avatar, tags: ['autodocs'] } satisfies Meta<typeof Avatar>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+export const Basic: S = { name: 'Basic — letter', args: { children: 'A' } };
+export const Image: S = { name: 'Image — src + alt', args: { src: 'https://i.pravatar.cc/150?img=1', alt: 'user' } };
+export const Square48: S = { name: 'Square 48', args: { children: 'B', size: 48, shape: 'square' } };
+
+export const Sizes: S = {
+  name: 'Sizes — 24/32/48/64 (circle + square)',
+  render: () => (
+    <div className="flex items-end gap-4">
+      {[24, 32, 48, 64].map((s) => (
+        <Avatar key={`c${s}`} size={s}>
+          {s}
+        </Avatar>
+      ))}
+      {[24, 32, 48, 64].map((s) => (
+        <Avatar key={`s${s}`} size={s} shape="square">
+          {s}
+        </Avatar>
+      ))}
+    </div>
+  ),
+};
+
+export const DarkTheme: S = {
+  name: 'Dark theme',
+  render: () => (
+    <div data-bp-theme="dark" className="flex w-fit gap-3 rounded-xl bg-canvas p-4">
+      <Avatar>VN</Avatar>
+      <Avatar src="https://i.pravatar.cc/150?img=3" alt="user 3" size={48} />
+      <Avatar size={48} shape="square">
+        QT
+      </Avatar>
+    </div>
+  ),
+};
+
+// ── Case-coverage audit 2026-10-18 (antd parity: src error fallback) ──
+
+export const BrokenSrcFallback: S = {
+  name: 'Broken src — falls back to initials on error',
+  render: () => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
+      <Avatar src="https://example.com/missing.jpg" alt="Hai">HB</Avatar>
+      <Avatar src="https://example.com/missing.jpg" alt="Team" shape="square">TM</Avatar>
+      <span className="text-meta text-ink2">← initials replace broken images</span>
+    </div>
+  ),
+};
+
+// ── Real-world usage (2026-10-25): photo avatars in product contexts ──
+
+/** Seeded picsum helper — deterministic real photo per person (same contract as image.stories). */
+function photo(seed: string, w: number, h: number) {
+  return `https://picsum.photos/seed/${seed}/${w}/${h}`;
+}
+
+const COMMENTS = [
+  {
+    seed: 'avatar-mai',
+    name: 'Mai Pham',
+    time: '12 minutes ago',
+    body: 'Deployed the new onboarding flow to staging — take a look when you get a chance.',
+  },
+  {
+    seed: 'avatar-hung',
+    name: 'Hung Bui',
+    time: '34 minutes ago',
+    body: 'Nice. The step indicator feels much snappier with the 160ms transition.',
+  },
+  {
+    seed: 'avatar-lan',
+    name: 'Lan Do',
+    time: '1 hour ago',
+    body: 'Left two small copy suggestions on step 3, everything else LGTM.',
+  },
+];
+
+/** CommentThread — the most common real-world avatar: photo identity next to a message. */
+export const CommentThread: S = {
+  name: 'In a comment thread — 40px photo avatars beside messages',
+  render: () => (
+    <div className="flex w-full max-w-xl flex-col gap-4 rounded-xl border border-line bg-s1 p-5">
+      {COMMENTS.map((c) => (
+        <div key={c.seed} className="flex items-start gap-3">
+          <Avatar src={photo(c.seed, 96, 96)} alt={c.name} size={40} />
+          <div className="min-w-0 flex-1">
+            <div className="flex items-baseline gap-2">
+              <span className="text-body font-medium text-ink">{c.name}</span>
+              <span className="text-meta text-ink3">{c.time}</span>
+            </div>
+            <p className="m-0 mt-0.5 text-body text-ink2">{c.body}</p>
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+const TEAM_MEMBERS = [
+  { seed: 'avatar-mai', name: 'Mai Pham', role: 'Design Lead', status: 'online', dot: 'bg-st-done' },
+  { seed: 'avatar-hung', name: 'Hung Bui', role: 'Frontend Engineer', status: 'online', dot: 'bg-st-done' },
+  { seed: 'avatar-lan', name: 'Lan Do', role: 'QA Engineer', status: 'away', dot: 'bg-st-doing' },
+  { seed: 'avatar-khoa', name: 'Khoa Tran', role: 'Product Manager', status: 'busy', dot: 'bg-st-fail' },
+];
+
+/** TeamPage — member directory rows: photo avatar + name/role + presence tag. */
+export const TeamPage: S = {
+  name: 'Team page — member rows with photo, role, presence',
+  render: () => (
+    <div className="w-full max-w-md rounded-xl border border-line bg-s1 p-2">
+      {TEAM_MEMBERS.map((m) => (
+        <div key={m.name} className="flex items-center gap-3 rounded-lg px-3 py-2.5 transition-colors hover:bg-s3">
+          <Avatar src={photo(m.seed, 96, 96)} alt={m.name} size={40} />
+          <div className="min-w-0 flex-1">
+            <div className="text-body font-medium text-ink">{m.name}</div>
+            <div className="text-meta text-ink3">{m.role}</div>
+          </div>
+          <Tag icon={<span aria-hidden="true" className={`inline-block size-1.5 rounded-pill ${m.dot}`} />}>
+            {m.status}
+          </Tag>
+        </div>
+      ))}
+    </div>
+  ),
+};

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

@@ -0,0 +1,65 @@
+// Avatar tests — chữ cái, size, shape, src.
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Avatar } from './index.js';
+
+afterEach(cleanup);
+
+describe('Avatar', () => {
+  it('mặc định 32 circle + chữ cái', () => {
+    const { container } = render(<Avatar>A</Avatar>);
+    const el = container.firstElementChild as HTMLElement;
+    expect(el.style.width).toBe('32px');
+    expect(el.style.borderRadius).toBe('50%');
+    expect(el).toHaveTextContent('A');
+  });
+
+  it('square + size tuỳ ý', () => {
+    const { container } = render(<Avatar size={48} shape="square">B</Avatar>);
+    expect((container.firstElementChild as HTMLElement).style.width).toBe('48px');
+    expect((container.firstElementChild as HTMLElement).style.borderRadius).toBe('var(--r-2)');
+  });
+
+  it('src → img (src + alt passthrough)', () => {
+    render(<Avatar src="/a.png" alt="me" />);
+    expect(screen.getByRole('img')).toHaveAttribute('src', '/a.png');
+    expect(screen.getByRole('img')).toHaveAttribute('alt', 'me');
+  });
+
+  it('src không alt → alt rỗng (decorative — img rơi vào role presentation, không nhiễu screen reader)', () => {
+    const { container } = render(<Avatar src="/a.png" />);
+    const img = container.querySelector('img');
+    expect(img).toHaveAttribute('alt', '');
+    expect(img).not.toHaveAttribute('role');
+  });
+});
+
+describe('Avatar — branch phụ', () => {
+  it('không children/src → chỉ khung rỗng; className passthrough', () => {
+    const { container } = render(<Avatar className="marker" />);
+    expect(container.firstElementChild).toHaveClass('marker');
+    expect(container.firstElementChild?.textContent).toBe('');
+  });
+
+  it('icon node (ReactNode bất kỳ) render thay chữ', () => {
+    render(<Avatar><span data-testid="ic">★</span></Avatar>);
+    expect(screen.getByTestId('ic')).toBeInTheDocument();
+  });
+});
+
+describe('Avatar — branch phụ (Tier 5 sweep)', () => {
+  it('children chữ fallback span fontSize = size*0.44', () => {
+    render(<Avatar size={40}>VN</Avatar>);
+    const inner = screen.getByText('VN');
+    expect(inner.style.fontSize).toBe('17.6px');
+  });
+
+  // ── Case-coverage audit 2026-10-18 (antd parity: src error → fallback) ──
+
+  it('src load fail → fallback về children initials (antd onError fallback)', () => {
+    render(<Avatar src="https://example.com/broken.jpg" alt="Hai">HB</Avatar>);
+    expect(screen.queryByText('HB')).not.toBeInTheDocument();
+    fireEvent.error(screen.getByRole('img', { name: 'Hai' }));
+    expect(screen.getByText('HB')).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,48 @@
+// Avatar — chữ cái/ảnh (antd: size 32 default, radius 4 (square) / circle, bg fill
+// #f5f5f5? antd avatar default bg colorFillContent = rgba(0,0,0,0.06) — dùng bg-s3;
+// text ink; icon trắng? antd icon = trắng trên bg accent? Default bg gray + icon ink).
+import { useState, type ReactNode } from 'react';
+
+export interface AvatarProps {
+  /** Nội dung hiển thị khi không có src (chữ cái/initials) — fontSize scale theo size. */
+  children?: ReactNode;
+  /** Ảnh src — khi có render <img> (fade-in khi load xong). */
+  src?: string;
+  /** Alt của <img> — nên đặt tên người dùng. */
+  alt?: string;
+  /** Kích thước vuông px (antd default 32). */
+  size?: number;
+  /** circle (mặc định) | square (radius --r-2). */
+  shape?: 'circle' | 'square';
+  className?: string;
+}
+
+export function Avatar({ children, src, alt, size = 32, shape = 'circle', className }: AvatarProps) {
+  const [loaded, setLoaded] = useState(false);
+  // src fail (404/offline) → fallback về children/initials (antd onError fallback)
+  const [failed, setFailed] = useState(false);
+  const style: React.CSSProperties = {
+    width: size,
+    height: size,
+    borderRadius: shape === 'circle' ? '50%' : 'var(--r-2)',
+    lineHeight: `${size}px`,
+  };
+  return (
+    <span
+      className={`inline-flex shrink-0 items-center justify-center overflow-hidden bg-s3 text-body text-ink2${className ? ` ${className}` : ''}`}
+      style={style}
+    >
+      {src && !failed ? (
+        <img
+          src={src}
+          alt={alt ?? ''}
+          onLoad={() => setLoaded(true)}
+          onError={() => setFailed(true)}
+          className={`size-full object-cover transition-opacity duration-200 ${loaded ? 'opacity-100' : 'opacity-0'}`}
+        />
+      ) : (
+        <span style={{ fontSize: size * 0.44 }}>{children}</span>
+      )}
+    </span>
+  );
+}

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

@@ -0,0 +1,113 @@
+// AvatarGroup stories — Data Display. antd Avatar.Group parity (overlap, max →
+// +N pill, name tooltip).
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { AvatarGroup } from './index';
+import { Card } from '../../index.js';
+
+/** Stacked avatars with overflow folded into a +N pill. */
+const meta = {
+  title: 'Data Display/AvatarGroup',
+  component: AvatarGroup,
+  tags: ['autodocs'],
+} satisfies Meta<typeof AvatarGroup>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const TEAM = [
+  { src: 'https://i.pravatar.cc/150?img=1', name: 'An Nguyen' },
+  { src: 'https://i.pravatar.cc/150?img=2', name: 'Binh Tran' },
+  { src: 'https://i.pravatar.cc/150?img=3', name: 'Chi Le' },
+  { src: 'https://i.pravatar.cc/150?img=4', name: 'Duong Pham' },
+  { src: 'https://i.pravatar.cc/150?img=5', name: 'Giang Vo' },
+];
+
+export const Max: Story = {
+  name: 'Max 3 — overflow folds into +N (hover for names)',
+  args: { items: TEAM, max: 3 },
+};
+
+export const Full: Story = {
+  name: 'No max — all 5 avatars',
+  args: { items: TEAM },
+};
+
+export const Fallback: Story = {
+  name: 'No src — initials/fallback',
+  args: {
+    items: [
+      { name: 'An Nguyen' },
+      { name: 'Binh Tran', fallback: 'BT' },
+      { name: 'Chi Le' },
+    ],
+  },
+};
+
+export const Size48: Story = {
+  name: 'Size 48 — larger avatars, overlap ring still even',
+  args: { items: TEAM, max: 4, size: 48 },
+};
+
+export const DarkTheme: Story = {
+  name: 'Dark theme',
+  args: { items: TEAM, max: 3 },
+  render: (args) => (
+    <div data-bp-theme="dark" className="rounded-xl bg-canvas p-4">
+      <AvatarGroup {...args} />
+    </div>
+  ),
+};
+
+// ── Real-world usage (2026-10-25): photo groups in product contexts ──
+
+/** Seeded picsum helper — deterministic real photo per person (same contract as image.stories). */
+function photo(seed: string, w: number, h: number) {
+  return `https://picsum.photos/seed/${seed}/${w}/${h}`;
+}
+
+const ASSIGNEES = [
+  { src: photo('assignee-mai', 96, 96), name: 'Mai Pham' },
+  { src: photo('assignee-hung', 96, 96), name: 'Hung Bui' },
+  { src: photo('assignee-lan', 96, 96), name: 'Lan Do' },
+  { src: photo('assignee-khoa', 96, 96), name: 'Khoa Tran' },
+  { src: photo('assignee-giang', 96, 96), name: 'Giang Vo' },
+];
+
+/** TaskAssignees — ticket header pattern: who is on it, overflow folds into +N. */
+export const TaskAssignees: Story = {
+  name: 'Task assignees — ticket header, photos with +N overflow',
+  args: { items: ASSIGNEES, max: 3, size: 28 },
+  render: (args) => (
+    <div className="w-full max-w-md rounded-xl border border-line bg-s1 p-4">
+      <div className="flex items-center justify-between gap-3">
+        <span className="truncate text-body font-medium text-ink">Migrate design tokens to 0.4.0</span>
+        <span className="shrink-0 font-mono text-meta text-ink3">ORCA-101</span>
+      </div>
+      <div className="mt-3">
+        <AvatarGroup {...args} />
+      </div>
+      <p className="m-0 mt-2 text-meta text-ink3">5 assignees — hover the +N pill to see who is folded in.</p>
+    </div>
+  ),
+};
+
+const ATTENDEES = [
+  { src: photo('attendee-mai', 96, 96), name: 'Mai Pham' },
+  { src: photo('attendee-hung', 96, 96), name: 'Hung Bui' },
+  { src: photo('attendee-lan', 96, 96), name: 'Lan Do' },
+  { src: photo('attendee-khoa', 96, 96), name: 'Khoa Tran' },
+  { src: photo('attendee-giang', 96, 96), name: 'Giang Vo' },
+  { src: photo('attendee-tu', 96, 96), name: 'Tu Nguyen' },
+];
+
+/** MeetingAttendees — who is coming, as an avatar strip under a card title. */
+export const MeetingAttendees: Story = {
+  name: 'Meeting attendees — avatar strip under a card title',
+  args: { items: ATTENDEES, size: 32 },
+  render: (args) => (
+    <Card title="Design review — Thursday 10:00" className="max-w-sm">
+      <AvatarGroup {...args} />
+      <p className="m-0 mt-2 text-meta text-ink3">6 invited · 4 accepted — hover an avatar for the full name.</p>
+    </Card>
+  ),
+};

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

@@ -0,0 +1,71 @@
+// AvatarGroup tests — render đủ/max gộp +N/tooltip tên/fallback ưu tiên/overlap.
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it } from 'vitest';
+import { AvatarGroup } from './index.js';
+
+const TEAM = [
+  { name: 'An Nguyen' },
+  { name: 'Binh Tran', src: 'https://example.com/binh.png' },
+  { name: 'Chi Le', fallback: 'CX' },
+  { name: 'Duong Pham' },
+  { name: 'Giang Vo' },
+];
+
+afterEach(cleanup);
+
+describe('AvatarGroup', () => {
+  it('không max → đủ 5 avatar (initials từ tên)', () => {
+    render(<AvatarGroup items={TEAM} />);
+    expect(screen.getByText('AN')).toBeInTheDocument();
+    expect(screen.getByText('CX')).toBeInTheDocument(); // fallback ưu tiên hơn initials 'CL'
+    expect(screen.getByText('DP')).toBeInTheDocument();
+    expect(screen.getByText('GV')).toBeInTheDocument();
+  });
+
+  it('src → render <img> với src đó', () => {
+    const { container } = render(<AvatarGroup items={[TEAM[1]!]} />);
+    const img = container.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute('src', 'https://example.com/binh.png');
+  });
+
+  it('max=2 → 2 avatar đầu (text + img) + pill "+3"; tên dư không render', () => {
+    const { container } = render(<AvatarGroup items={TEAM} max={2} />);
+    expect(screen.getByText('AN')).toBeInTheDocument();
+    expect(container.querySelector('img')).not.toBeNull(); // Binh qua src
+    expect(screen.queryByText('CX')).toBeNull();
+    expect(screen.queryByText('DP')).toBeNull();
+    expect(screen.queryByText('GV')).toBeNull();
+    expect(screen.getByText('+3')).toBeInTheDocument();
+  });
+
+  it('hover avatar → tooltip tên', async () => {
+    const user = userEvent.setup();
+    render(<AvatarGroup items={TEAM.slice(0, 1)} />);
+    await user.hover(screen.getByText('AN'));
+    expect(screen.getByRole('tooltip')).toHaveTextContent('An Nguyen');
+  });
+
+  it('hover pill +N → tooltip liệt kê tên bị ẩn', async () => {
+    const user = userEvent.setup();
+    render(<AvatarGroup items={TEAM} max={2} />);
+    await user.hover(screen.getByText('+3'));
+    expect(screen.getByRole('tooltip')).toHaveTextContent('Chi Le');
+    expect(screen.getByRole('tooltip')).toHaveTextContent('Duong Pham');
+    expect(screen.getByRole('tooltip')).toHaveTextContent('Giang Vo');
+  });
+
+  it('overlap: avatar không đầu tiên có -ml-2 (wrapper), đầu tiên không', () => {
+    const { container } = render(<AvatarGroup items={TEAM.slice(0, 2)} />);
+    const wrappers = container.querySelectorAll('span');
+    const withOffset = Array.from(wrappers).filter((el) => el.className.includes('-ml-2'));
+    expect(withOffset).toHaveLength(1); // chỉ avatar thứ 2
+  });
+
+  it('size truyền xuống avatar (style width)', () => {
+    const { container } = render(<AvatarGroup items={TEAM.slice(0, 1)} size={48} />);
+    const avatar = container.querySelector('span > span');
+    expect(avatar).toHaveStyle({ width: '48px' });
+  });
+});

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

@@ -0,0 +1,66 @@
+// AvatarGroup — antd Avatar.Group: stack overlap (-ml-2 + ring trắng), max →
+// pill "+N" (tooltip liệt kê tên bị ẩn), tooltip tên khi hover từng avatar.
+// Avatar giữ nguyên — group chỉ wrap. fallback ưu tiên hơn initials suy từ tên.
+import { Avatar } from '../avatar/index';
+import { Tooltip } from '../tooltip/index';
+
+export interface AvatarGroupItem {
+  src?: string;
+  name: string;
+  /** Chữ hiển thị khi không có src (mặc định: initials 2 chữ cái đầu). */
+  fallback?: string;
+}
+
+export interface AvatarGroupProps {
+  /** Danh sách avatar — mỗi item tooltip = name khi hover. */
+  items: AvatarGroupItem[];
+  /** Số avatar hiển thị tối đa — dư gộp thành pill "+N" (tooltip liệt kê tên ẩn). */
+  max?: number;
+  /** Kích thước mỗi avatar px (truyền thẳng Avatar.size). */
+  size?: number;
+  className?: string;
+}
+
+function initials(name: string): string {
+  return name
+    .trim()
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((w) => w.charAt(0).toUpperCase())
+    .join('');
+}
+
+export function AvatarGroup({ items, max, size = 32, className }: AvatarGroupProps) {
+  const visible = max ? items.slice(0, max) : items;
+  const hidden = items.slice(visible.length);
+  const overlapCls = '-ml-2';
+
+  // Pop-in stagger: delay theo vị trí (literal class list — Tailwind quét được;
+  // bước 30ms theo depth contract 24-40ms; vành đai >5 avatar dùng delay cuối —
+  // hiếm, overflow +N đã gộp)
+  const stagger = ['', '[animation-delay:30ms]', '[animation-delay:60ms]', '[animation-delay:90ms]', '[animation-delay:120ms]'];
+
+  return (
+    <div className={`flex items-center${className ? ` ${className}` : ''}`}>
+      {visible.map((item, i) => (
+        <Tooltip key={`${item.name}-${i}`} title={item.name} className={i > 0 ? overlapCls : undefined}>
+          <Avatar
+            src={item.src}
+            alt={item.name}
+            size={size}
+            className={`ring-2 ring-s2 animate-[bp-bounce-in_var(--motion-base)_var(--ease-enter)]${stagger[Math.min(i, stagger.length - 1)]}`}
+          >
+            {item.fallback ?? initials(item.name)}
+          </Avatar>
+        </Tooltip>
+      ))}
+      {hidden.length > 0 && (
+        <Tooltip title={hidden.map((h) => h.name).join(', ')} className={overlapCls}>
+          <Avatar size={size} className="bg-s3 ring-2 ring-s2">
+            +{hidden.length}
+          </Avatar>
+        </Tooltip>
+      )}
+    </div>
+  );
+}