create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,377 @@
+// Transition — họ enter/exit kiểu MUI (motion-effects W8, 0 deps) — 11 loại:
+//   Fade (opacity) · Zoom (scale .96) · Collapse (grid 0fr↔1fr, orientation
+//   vertical|horizontal) · Slide (4 hướng) · Grow (scale từ gốc origin) · Flip
+//   (rotateY 3D) · Rotate (đơn trục) · Blur (filter+opacity) · Bounce (overshoot)
+//   · ScaleSoft (scale nhẹ) · Stagger (children delay nối tiếp) · Crossfade
+//   (swap 2 children opacity).
+// API thống nhất: `in?` · `duration?` · `delay?` · `easing?` (mặc định token
+// --ease-smooth — depth contract 2026-10-19: 200-280ms, vào mềm dừng không giật)
+// · `unmountOnExit?` + prop riêng: Slide.direction · Grow.origin ·
+// Collapse.orientation · Stagger.staggerMs · Crossfade.active.
+// Keyframe bằng token (styles/tailwind.css, khối motion). Exit của loại mới =
+// REVERSE của enter (animationDirection) — không đúc keyframe out. Class giữ
+// LITERAL (Tailwind quét được — cấm nội suy chuỗi class). prefers-reduced-motion
+// tự tắt nhờ block global (end-event vẫn fire tức thì nên exit-machine vẫn đúng).
+// unmountOnExit (mặc định true): exit chạy XONG mới unmount (state machine kiểu
+// Modal); false → giữ DOM ẩn bằng opacity-0/invisible.
+// ── Chọn loại nào khi nào ────────────────────────────────────────────────
+//   Fade: mặc định an toàn         · Zoom: card/dialog pop
+//   Collapse dọc: FAQ/accordion    · Collapse ngang: sidebar/mở cột
+//   Slide: drawer/panel theo mép   · Grow: menu/popover mọc từ trigger
+//   Flip: đổi mặt thẻ/lượt xem     · Rotate: icon/badge quay vào
+//   Blur: hero/ảnh focus-in        · Bounce: điểm thưởng/success pop
+//   ScaleSoft: hover-inRegion nhẹ  · Stagger: list/grid mount nối tiếp
+//   Crossfade: swap 2 trạng thái cùng chỗ (tab ảnh, 2 mode xem)
+import { useEffect, useState,
+  type AnimationEvent,
+  type CSSProperties,
+  type ReactNode,
+  type TransitionEvent } from 'react';
+
+export interface TransitionProps {
+  /** Hiện (enter) / ẩn (exit) — bỏ qua mặc định là hiện. */
+  in?: boolean;
+  /** Exit xong unmount khỏi DOM (mặc định true); false → giữ DOM ở trạng thái ẩn. */
+  unmountOnExit?: boolean;
+  /** Override thời lượng ms — mặc định token `--motion-base` (240ms). */
+  duration?: number;
+  /** Trễ ms trước khi animation chạy (fill backwards — element ẩn trong lúc trễ). */
+  delay?: number;
+  /** Timing function — mặc định token `var(--ease-smooth)` (depth contract). */
+  easing?: string;
+  className?: string;
+  children: ReactNode;
+}
+
+/** State machine chung: mở → mount; đóng → chờ animation/transition end mới unmount. */
+function useExitMachine(show: boolean) {
+  const [mounted, setMounted] = useState(show);
+  useEffect(() => {
+    if (show) setMounted(true);
+  }, [show]);
+  const closing = mounted && !show;
+  // Chỉ nhận end-event từ chính wrapper (con bắn animationEnd bubble lên không tính)
+  const handleEnd = (e: AnimationEvent<HTMLDivElement> | TransitionEvent<HTMLDivElement>) => {
+    if (e.target === e.currentTarget) setMounted(false);
+  };
+  return { mounted, closing, handleEnd };
+}
+
+function baseCls(show: boolean, unmountOnExit: boolean, extra: string, className?: string) {
+  // giữ ẩn sau exit khi giữ DOM (animation không fill — cần class hold)
+  const hold = !show && !unmountOnExit ? ' opacity-0' : '';
+  return `${extra}${hold}${className ? ` ${className}` : ''}`;
+}
+
+/** Style animation dùng chung — duration/delay/easing/reverse (exit = reverse enter). */
+function animStyle(opts: {
+  duration?: number;
+  delay?: number;
+  easing?: string;
+  closing?: boolean;
+}): CSSProperties {
+  return {
+    ...(opts.duration ? { animationDuration: `${opts.duration}ms` } : null),
+    ...(opts.delay
+      ? { animationDelay: `${opts.delay}ms`, animationFillMode: 'both' as const }
+      : null),
+    ...(opts.easing ? { animationTimingFunction: opts.easing } : null),
+    ...(opts.closing ? { animationDirection: 'reverse' as const } : null),
+  };
+}
+
+/** Fade — mờ dần/vào mờ dần (bp-fade-in / bp-fade-out). */
+export function Fade({ in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: TransitionProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={animStyle({ duration, delay, easing, closing })}
+      className={baseCls(
+        show,
+        unmountOnExit,
+        show
+          ? 'animate-[bp-fade-in_var(--motion-base)_var(--ease-smooth)]'
+          : 'animate-[bp-fade-out_var(--motion-fast)_var(--ease-smooth)]',
+        className,
+      )}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Zoom — phóng từ 96% (bp-zoom-in / bp-zoom-out). */
+export function Zoom({ in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: TransitionProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={animStyle({ duration, delay, easing, closing })}
+      className={baseCls(
+        show,
+        unmountOnExit,
+        show
+          ? 'animate-[bp-zoom-in_var(--motion-base)_var(--ease-smooth)]'
+          : 'animate-[bp-zoom-out_var(--motion-fast)_var(--ease-smooth)]',
+        className,
+      )}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Collapse — thu/mở theo chiều (grid 0fr↔1fr, KHÔNG keyframe height):
+ * padding/border phải đặt trong `children`, KHÔNG trên wrapper — tầng
+ * `overflow-hidden` phải clip SẠCH, nếu viền/padding nằm tầng ngoài sẽ giật.
+ * `orientation="horizontal"` → thu/mở NGANG (grid-template-columns — sidebar,
+ * mở cột chi tiết); children cần bọc nội dung không-wrap nếu muốn giữ độ rộng.
+ */
+export interface CollapseProps extends TransitionProps {
+  /** Chiều thu/mở — vertical (mặc định, FAQ) | horizontal (sidebar/cột). */
+  orientation?: 'vertical' | 'horizontal';
+}
+
+export function Collapse({ in: show = true, unmountOnExit = true, duration, delay, easing, orientation = 'vertical', className, children }: CollapseProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  const horizontal = orientation === 'horizontal';
+  const dim: CSSProperties = horizontal
+    ? { gridTemplateColumns: show ? '1fr' : '0fr' }
+    : { gridTemplateRows: show ? '1fr' : '0fr' };
+  return (
+    <div
+      style={{
+        ...dim,
+        transitionTimingFunction: easing ?? 'var(--ease-smooth)',
+        ...(duration ? { transitionDuration: `${duration}ms` } : null),
+        ...(delay ? { transitionDelay: `${delay}ms` } : null),
+      }}
+      className={`grid ${horizontal ? 'transition-[grid-template-columns]' : 'transition-[grid-template-rows]'} duration-[var(--motion-base)]${!show && !unmountOnExit ? ' invisible' : ''}${className ? ` ${className}` : ''}`}
+      onTransitionEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      <div className={horizontal ? 'h-full min-w-0 overflow-hidden' : 'min-h-0 overflow-hidden'}>{children}</div>
+    </div>
+  );
+}
+
+/** Slide — trôi vào từ 1 cạnh (direction: up mặc định / down / left / right).
+ * Exit = reverse của enter. up tái dùng bp-slide-up-in; left/right có sẵn. */
+export interface SlideProps extends TransitionProps {
+  /** Cạnh element trôi vào từ. */
+  direction?: 'up' | 'down' | 'left' | 'right';
+}
+
+const SLIDE_CLS: Record<NonNullable<SlideProps['direction']>, string> = {
+  up: 'animate-[bp-slide-up-in_var(--motion-base)_var(--ease-smooth)]',
+  down: 'animate-[bp-slide-in-down_var(--motion-base)_var(--ease-smooth)]',
+  left: 'animate-[bp-slide-in-left_var(--motion-base)_var(--ease-smooth)]',
+  right: 'animate-[bp-slide-in-right_var(--motion-base)_var(--ease-smooth)]',
+};
+
+export function Slide({ direction = 'up', in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: SlideProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={animStyle({ duration, delay, easing, closing })}
+      className={baseCls(show, unmountOnExit, SLIDE_CLS[direction], className)}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Grow — scale 0.85→1 TỪ GỐC `origin` (CSS transform-origin — 'bottom left' cho
+ * menu mọc từ trigger, 'top right' cho popover góc…). Exit = reverse (co về gốc). */
+export interface GrowProps extends TransitionProps {
+  /** transform-origin — 'bottom left' (mặc định) | 'top right' | bất kỳ giá trị CSS. */
+  origin?: string;
+}
+
+export function Grow({ origin = 'bottom left', in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: GrowProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={{ transformOrigin: origin, ...animStyle({ duration, delay, easing, closing }) }}
+      className={baseCls(show, unmountOnExit, 'animate-[bp-grow-in_var(--motion-base)_var(--ease-smooth)]', className)}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Flip — xoay 3D quanh trục Y (perspective 800px, rotateY 70°→0). Exit = reverse. */
+export function Flip({ in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: TransitionProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={animStyle({ duration, delay, easing, closing })}
+      className={baseCls(show, unmountOnExit, 'animate-[bp-flip_var(--motion-base)_var(--ease-smooth)]', className)}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Rotate — quay đơn trục -90°→0 kèm scale nhẹ (flip-clock/settle). Exit = reverse. */
+export function Rotate({ in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: TransitionProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={animStyle({ duration, delay, easing, closing })}
+      className={baseCls(show, unmountOnExit, 'animate-[bp-rotate-in_var(--motion-base)_var(--ease-smooth)]', className)}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Blur — focus-in từ mờ 8px (ảnh hero, khung ảnh lớn). Ngoại lệ duy nhất animate
+ * `filter` (bản chất của loại — vẫn GPU-composited). Exit = reverse. */
+export function Blur({ in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: TransitionProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={animStyle({ duration, delay, easing, closing })}
+      className={baseCls(show, unmountOnExit, 'animate-[bp-blur-in_var(--motion-base)_var(--ease-smooth)]', className)}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Bounce — pop overshoot (scale .6→1.05→.97→1) — điểm thưởng/success pop.
+ * Exit = reverse (co về). */
+export function Bounce({ in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: TransitionProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={animStyle({ duration, delay, easing, closing })}
+      className={baseCls(show, unmountOnExit, 'animate-[bp-bounce-in_var(--motion-base)_var(--ease-smooth)]', className)}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** ScaleSoft — scale 0.98→1 cực nhẹ (khởi hiện vùng nội dung, không gây chú ý). */
+export function ScaleSoft({ in: show = true, unmountOnExit = true, duration, delay, easing, className, children }: TransitionProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  return (
+    <div
+      style={animStyle({ duration, delay, easing, closing })}
+      className={baseCls(show, unmountOnExit, 'animate-[bp-soft-in_var(--motion-base)_var(--ease-smooth)]', className)}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Stagger — children hiện nối tiếp (delay cộng dồn `staggerMs`/mục, mặc định 30 —
+ * depth contract 24-40ms). Mỗi con bọc 1 tầng animate bp-slide-up-in fill both;
+ * exit = container fade-out rồi mới unmount (end-event từ chính container). */
+export interface StaggerProps extends TransitionProps {
+  /** Trễ nối tiếp giữa 2 mục (ms) — mặc định 30 (depth contract 24-40). */
+  staggerMs?: number;
+}
+
+export function Stagger({ staggerMs = 30, in: show = true, unmountOnExit = true, duration, delay = 0, easing, className, children }: StaggerProps) {
+  const { mounted, closing, handleEnd } = useExitMachine(show);
+  if (!mounted) return null;
+  const items = Array.isArray(children) ? children : [children];
+  const ease = easing ?? 'var(--ease-smooth)';
+  return (
+    <div
+      style={animStyle({ duration, easing })}
+      className={baseCls(
+        show,
+        unmountOnExit,
+        closing ? 'animate-[bp-fade-out_var(--motion-fast)_var(--ease-smooth)]' : '',
+        className,
+      )}
+      onAnimationEnd={(e) => {
+        if (closing) handleEnd(e);
+      }}
+    >
+      {items.map((child, i) => (
+        <div key={i} style={{ animation: `bp-slide-up-in ${duration ?? 240}ms ${ease} ${delay + i * staggerMs}ms both` }}>
+          {child}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/** Crossfade — swap 2 children CÙNG chỗ (grid chồng cell): `active` 0|1, mục
+ * không active opacity-0 + pointer-events-none. Không machine (cả 2 luôn mounted —
+ * transition-opacity ease-smooth). Container cao theo child CAO HƠN (không nhảy layout). */
+export interface CrossfadeProps {
+  /** Chỉ mục hiện: 0 | 1. */
+  active?: 0 | 1;
+  /** Thời lượng crossfade ms — mặc định token `--motion-base` (240ms). */
+  duration?: number;
+  /** Timing function — mặc định token `var(--ease-smooth)`. */
+  easing?: string;
+  className?: string;
+  /** Đúng 2 node — [mục 0, mục 1]. */
+  children: ReactNode;
+}
+
+export function Crossfade({ active = 0, duration, easing, className, children }: CrossfadeProps) {
+  const items = (Array.isArray(children) ? children : [children]).slice(0, 2);
+  return (
+    <div className={`relative grid${className ? ` ${className}` : ''}`}>
+      {items.map((child, i) => (
+        <div
+          key={i}
+          aria-hidden={active !== i || undefined}
+          style={{
+            ...(duration ? { transitionDuration: `${duration}ms` } : null),
+            ...(easing ? { transitionTimingFunction: easing } : null),
+          }}
+          className={`col-start-1 row-start-1 transition-opacity ${active === i ? 'opacity-100' : 'pointer-events-none opacity-0'}`}
+        >
+          {child}
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,254 @@
+// Transition stories — Fade/Zoom/Collapse toggles + a Reveal combo (scroll
+// reveal expands a collapsible) + MATRIX 11 loại (depth contract 2026-10-19:
+// mọi loại ease-smooth 200-280ms, exit = reverse enter). Toggle buttons drive
+// `in` like a real consumer.
+import { useState, type ComponentType, type ReactNode } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from '../button/index.js';
+import { Reveal } from '../reveal/index.js';
+import {
+  Blur,
+  Bounce,
+  Collapse,
+  Crossfade,
+  Fade,
+  Flip,
+  Grow,
+  Rotate,
+  ScaleSoft,
+  Slide,
+  Stagger,
+  Zoom,
+  type TransitionProps,
+} from './index';
+
+// Meta WITHOUT `component` — children + in are required/CSF-hostile props;
+// render-only stories (image.stories pattern).
+const meta = {
+  title: 'Theming & Motion/Transition',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: [
+          '**11 loại × khi-nào-dùng** (depth contract — mọi loại easing `--ease-smooth` 200-280ms, exit = reverse enter):',
+          '| Loại | Khi nào dùng |',
+          '|---|---|',
+          '| Fade | mặc định an toàn — text/hint hiện gọn |',
+          '| Zoom | card/dialog pop giữa màn |',
+          '| Collapse (vertical) | FAQ/accordion mở rộng chiều dọc |',
+          '| Collapse (horizontal) | sidebar/mở cột chi tiết |',
+          '| Slide | drawer/panel trôi từ mép (4 hướng) |',
+          '| Grow | menu/popover MỌC từ trigger (origin) |',
+          '| Flip | đổi mặt thẻ/lượt xem 3D |',
+          '| Rotate | icon/badge quay vào chỗ |',
+          '| Blur | hero/ảnh focus-in từ mờ |',
+          '| Bounce | điểm thưởng/success pop overshoot |',
+          '| ScaleSoft | vùng nội dung hiện cực nhẹ |',
+          '| Stagger | list/grid mount nối tiếp 24-40ms |',
+          '| Crossfade | swap 2 trạng thái cùng chỗ |',
+        ].join('\n'),
+      },
+    },
+  },
+} satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Fade — opacity in/out, unmounts after the exit animation. */
+export const FadeStory: Story = {
+  name: 'Fade — opacity enter/exit',
+  render: () => <ToggleDemo Comp={Fade} label="Fade" />,
+};
+
+/** Zoom — scale 96%→100% pop, modal-card feel. */
+export const ZoomStory: Story = {
+  name: 'Zoom — scale pop',
+  render: () => <ToggleDemo Comp={Zoom} label="Zoom" />,
+};
+
+/** Collapse — height 0fr↔1fr (grid rows), FAQ-section pattern. */
+export const CollapseStory: Story = {
+  name: 'Collapse — height 0fr↔1fr',
+  render: () => <CollapseDemo />,
+};
+
+/** WithReveal — Reveal scrolls the card in, Collapse expands details on click. */
+export const WithReveal: Story = {
+  name: 'With Reveal — scroll-in card with collapsible details',
+  render: () => <RevealComboDemo />,
+};
+
+/** KeepMounted — unmountOnExit=false: exit plays, DOM stays (opacity-0 hold). */
+export const KeepMounted: Story = {
+  name: 'Keep mounted — unmountOnExit=false',
+  render: () => <ToggleDemo Comp={Fade} label="Fade" unmountOnExit={false} />,
+};
+
+/** Matrix — lưới 11 loại transition (depth contract 2026-10-19): bấm nút từng ô
+ * để xem enter/exit (exit = reverse enter); bảng "loại × khi-nào-dùng" ở docs
+ * component trên. Mọi ô easing --ease-smooth 240ms. */
+export const Matrix: Story = {
+  name: 'Matrix — 11 loại (ease-smooth, exit = reverse)',
+  render: () => <MatrixDemo />,
+};
+
+type GenericComp = ComponentType<Record<string, unknown>>;
+
+const MATRIX: [string, GenericComp, Record<string, unknown>][] = [
+  ['Fade', Fade as unknown as GenericComp, {}],
+  ['Zoom', Zoom as unknown as GenericComp, {}],
+  ['Slide up', Slide as unknown as GenericComp, { direction: 'up' }],
+  ['Slide left', Slide as unknown as GenericComp, { direction: 'left' }],
+  ['Grow', Grow as unknown as GenericComp, { origin: 'bottom left' }],
+  ['Flip', Flip as unknown as GenericComp, {}],
+  ['Rotate', Rotate as unknown as GenericComp, {}],
+  ['Blur', Blur as unknown as GenericComp, {}],
+  ['Bounce', Bounce as unknown as GenericComp, {}],
+  ['ScaleSoft', ScaleSoft as unknown as GenericComp, {}],
+];
+
+function MatrixCell({ label, Comp, props }: { label: string; Comp: GenericComp; props: Record<string, unknown> }) {
+  const [show, setShow] = useState(true);
+  return (
+    <div className="flex min-h-28 flex-col items-start gap-2">
+      <Button size="small" onClick={() => setShow((s) => !s)}>
+        {show ? 'Ẩn' : 'Hiện'} — {label}
+      </Button>
+      <Comp in={show} {...props}>
+        <div className="rounded-xl border border-line bg-s1 p-3 text-meta text-ink2 shadow-[var(--ele-1)]">
+          {label}
+        </div>
+      </Comp>
+    </div>
+  );
+}
+
+function CollapseHorizontalCell() {
+  const [open, setOpen] = useState(true);
+  return (
+    <div className="flex min-h-28 flex-col items-start gap-2">
+      <Button size="small" onClick={() => setOpen((o) => !o)}>
+        Collapse ngang
+      </Button>
+      <Collapse in={open} orientation="horizontal" unmountOnExit={false}>
+        <div className="whitespace-nowrap rounded-xl border border-line bg-s1 p-3 text-meta text-ink2 shadow-[var(--ele-1)]">
+          Cột 0fr↔1fr
+        </div>
+      </Collapse>
+    </div>
+  );
+}
+
+function StaggerCell() {
+  const [run, setRun] = useState(0);
+  return (
+    <div className="flex min-h-28 flex-col items-start gap-2">
+      <Button size="small" onClick={() => setRun((r) => r + 1)}>
+        Stagger replay
+      </Button>
+      <Stagger key={run} in staggerMs={30}>
+        <div className="rounded-lg border border-line bg-s1 px-3 py-1 text-meta text-ink2">Mục 1</div>
+        <div className="rounded-lg border border-line bg-s1 px-3 py-1 text-meta text-ink2">Mục 2</div>
+        <div className="rounded-lg border border-line bg-s1 px-3 py-1 text-meta text-ink2">Mục 3</div>
+      </Stagger>
+    </div>
+  );
+}
+
+function CrossfadeCell() {
+  const [face, setFace] = useState<0 | 1>(0);
+  return (
+    <div className="flex min-h-28 flex-col items-start gap-2">
+      <Button size="small" onClick={() => setFace((f) => (f === 0 ? 1 : 0))}>
+        Crossfade swap
+      </Button>
+      <Crossfade active={face} className="w-40">
+        <div className="rounded-xl border border-line bg-s1 p-3 text-meta text-ink2 shadow-[var(--ele-1)]">Mặt A</div>
+        <div className="rounded-xl border border-line bg-s1 p-3 text-meta text-ink2 shadow-[var(--ele-1)]">Mặt B</div>
+      </Crossfade>
+    </div>
+  );
+}
+
+function MatrixDemo() {
+  return (
+    <div className="grid max-w-4xl grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+      {MATRIX.map(([label, Comp, props]) => (
+        <MatrixCell key={label} label={label} Comp={Comp} props={props} />
+      ))}
+      <CollapseHorizontalCell />
+      <StaggerCell />
+      <CrossfadeCell />
+    </div>
+  );
+}
+
+function Panel({ children }: { children: ReactNode }) {
+  return <div className="w-fit rounded-xl border border-line bg-s1 p-4 text-body text-ink2">{children}</div>;
+}
+
+function ToggleDemo({ Comp, label, unmountOnExit }: { Comp: (props: TransitionProps) => ReactNode; label: string; unmountOnExit?: boolean }) {
+  const [show, setShow] = useState(true);
+  return (
+    <div className="flex max-w-md flex-col gap-4">
+      <Button onClick={() => setShow((s) => !s)}>{show ? 'Hide' : 'Show'} ({label})</Button>
+      <Comp in={show} unmountOnExit={unmountOnExit}>
+        <Panel>
+          {label} transition — exit plays to the end before unmount (motion-base, tokens only).
+        </Panel>
+      </Comp>
+    </div>
+  );
+}
+
+function CollapseDemo() {
+  const [open, setOpen] = useState(true);
+  return (
+    <div className="max-w-md rounded-xl border border-line bg-s1">
+      <button
+        type="button"
+        aria-expanded={open}
+        onClick={() => setOpen((o) => !o)}
+        className="flex w-full cursor-pointer items-center justify-between border-none bg-transparent px-4 py-3 text-left text-body font-medium text-ink hover:bg-s2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+      >
+        What changes when I collapse this?
+        <span className="font-mono text-meta text-ink3">{open ? '−' : '+'}</span>
+      </button>
+      {/* padding nằm SẶC trong tầng clip — không đặt lên wrapper Collapse */}
+      <Collapse in={open}>
+        <p className="m-0 px-4 pb-4 text-body text-ink2">
+          Grid rows animate 0fr↔1fr so the height eases without measuring — padding lives inside the
+          clipped tier, never on the wrapper.
+        </p>
+      </Collapse>
+    </div>
+  );
+}
+
+function RevealComboDemo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="flex max-w-md flex-col gap-6">
+      <Reveal direction="up">
+        <div className="rounded-xl border border-line bg-s1 p-4">
+          <div className="text-body font-medium text-ink">Scroll-revealed card</div>
+          <p className="m-0 mt-1 text-meta text-ink3">
+            Reveal brought this card in; the button below drives a Collapse.
+          </p>
+          <div className="mt-3">
+            <Button size="small" onClick={() => setOpen((o) => !o)}>
+              {open ? 'Hide details' : 'Show details'}
+            </Button>
+          </div>
+          <Collapse in={open}>
+            <p className="m-0 pt-3 text-body text-ink2">
+              Two motion primitives stacked: Reveal owns the scroll entrance, Collapse owns the expand
+              state — each unmount/exit cleans up after itself.
+            </p>
+          </Collapse>
+        </div>
+      </Reveal>
+    </div>
+  );
+}