create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/app/ui-kit/.storybook/manager.ts

@@ -0,0 +1,138 @@
+// Manager UI theme — "Đồng bộ ui-kit": chrome Storybook map 1:1 tokens
+// styles/tokens.css (antd-look light) + themes/dark.css — Storybook mặc đúng
+// áo của design system nó documenting. Nguồn giá trị ghi cạnh mỗi key; đổi
+// token ở tokens.css/dark.css = đổi ở đây cùng commit.
+// Chi tiết selector-spezifisch (sidebar item/search/scrollbar) ở manager-head.html.
+// Dark đồng bộ toolbar toggle: nghe GLOBALS_UPDATED (addon-themes) — bấm dark
+// trên toolbar là cả manager (sidebar/toolbar) theo canvas (2026-10-23).
+import { addons } from 'storybook/manager-api';
+import { create } from 'storybook/theming';
+import { GLOBALS_UPDATED } from 'storybook/internal/core-events';
+
+// Font stacks — mirror --f / --m (tokens.css)
+const FONT_BASE =
+  '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif';
+const FONT_MONO =
+  '"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace';
+
+// Brand — Mark chữ W (khối accent bo r-1) + wordmark ghép trong 1 SVG
+// (brandImage thay brandTitle trong sidebar header). Mực wordmark + accent
+// mark theo palette để đọc được trên cả 2 nền sidebar.
+function brandImage(ink: string, accent: string): string {
+  return `data:image/svg+xml,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="128" height="24" viewBox="0 0 128 24"><rect width="24" height="24" rx="6" fill="${accent}"/><path d="M5.5 8l2.6 8L10.7 10.4 13.3 16l2.6-8" stroke="#fff" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" fill="none"/><text x="32" y="16.5" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif" font-size="14" font-weight="600" fill="${ink}">Wakii UI Kit</text></svg>`,
+  )}`;
+}
+
+// 2 palette — giá trị mirror tokens.css (light) / themes/dark.css (dark).
+const PALETTES = {
+  light: {
+    base: 'light' as const,
+    // Accent — --accent / --accent-hi
+    colorPrimary: '#1677ff',
+    colorSecondary: '#4096ff',
+    // Nền khung — --c-canvas (sidebar) / --c-s2 (content)
+    appBg: '#f5f5f5',
+    appContentBg: '#ffffff',
+    // Viền — --line (cool-tint hairline)
+    appBorderColor: '#e2e5ea',
+    // Toolbar — khối --c-s1, chữ --ink2
+    barBg: '#ffffff',
+    barTextColor: 'rgba(0, 0, 0, 0.65)',
+    barSelectedColor: '#1677ff',
+    barHoverColor: '#4096ff',
+    // Mực — 4 mức antd colorText
+    textColor: 'rgba(0, 0, 0, 0.88)',
+    textInverseColor: '#ffffff',
+    textMutedColor: 'rgba(0, 0, 0, 0.45)',
+    // Inputs (search box...) — nền --c-s3
+    inputBg: '#fafafa',
+    inputBorder: '#e2e5ea',
+    inputTextColor: 'rgba(0, 0, 0, 0.88)',
+    // Buttons — mirror Button default (nền s2 viền line)
+    buttonBg: '#ffffff',
+    buttonBorder: '#e2e5ea',
+    brandImage: brandImage('rgba(0,0,0,0.88)', '#1677ff'),
+  },
+  dark: {
+    base: 'dark' as const,
+    colorPrimary: '#5e6ad2', // --accent
+    colorSecondary: '#828fff', // --accent-hi
+    appBg: '#010102', // --c-canvas
+    appContentBg: '#141516', // --c-s2
+    appBorderColor: '#23252a', // --line
+    barBg: '#0f1011', // --c-s1
+    barTextColor: '#d0d6e0', // --ink2
+    barSelectedColor: '#828fff', // --accent-hi (đọc được trên nền tối)
+    barHoverColor: '#5e6ad2', // --accent
+    textColor: '#f7f8f8', // --ink
+    textInverseColor: '#010102',
+    textMutedColor: '#8a8f98', // --ink3
+    inputBg: '#18191a', // --c-s3
+    inputBorder: '#23252a',
+    inputTextColor: '#f7f8f8',
+    buttonBg: '#141516', // --c-s2
+    buttonBorder: '#23252a',
+    brandImage: brandImage('#f7f8f8', '#5e6ad2'),
+  },
+};
+
+function applyManagerTheme(globals?: Record<string, unknown>): void {
+  const theme = (globals?.theme as string | undefined) === 'dark' ? 'dark' : 'light';
+  // Attr trên body manager để manager-head.html chỉnh iframe/overlay theo
+  // (manager scope không có tokens var nên CSS ở đó dùng hex kèm comment nguồn).
+  if (typeof document !== 'undefined' && document.body) {
+    document.body.setAttribute('data-bp-theme', theme);
+  }
+  addons.setConfig({
+    theme: create({
+      ...PALETTES[theme],
+      brandTitle: 'Wakii UI Kit',
+      brandUrl: 'https://storybook-static-khaki-two.vercel.app',
+      appBorderRadius: 8, // --r-2
+      fontBase: FONT_BASE,
+      fontCode: FONT_MONO,
+    }),
+  });
+}
+
+// Boot: theme có thể nằm sẵn trong URL (?globals=theme:dark) — manager không
+// nhận lại event cho giá trị initial nên tự đọc query string.
+{
+  const q = new URLSearchParams(window.location.search).get('globals') ?? '';
+  applyManagerTheme(/(^|,)theme:dark(,|$)/.test(q) ? { theme: 'dark' } : undefined);
+}
+// Toggle runtime trên toolbar.
+addons.getChannel().on(GLOBALS_UPDATED, ({ globals }: { globals?: Record<string, unknown> }) => {
+  applyManagerTheme(globals);
+});
+
+// Ẩn teaser SB "Learn what's new" ở đáy sidebar — class là emotion-hash
+// (đổi mỗi build) nên match theo nội dung; MutationObserver phòng render
+// muộn sau boot. (SB strip <script> inline khỏi manager-head nên phải ở đây.)
+function hideVersionTeaser(): void {
+  const els = document.querySelectorAll<HTMLElement>('nav div, aside div, #root div');
+  for (const el of els) {
+    const text = (el.textContent ?? '').trim();
+    if (text.includes("Learn what's new") && text.length < 120) {
+      el.style.display = 'none';
+    }
+  }
+}
+if (typeof document !== 'undefined') {
+  hideVersionTeaser();
+  if (document.body) {
+    new MutationObserver(hideVersionTeaser).observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+  } else {
+    document.addEventListener('DOMContentLoaded', () => {
+      hideVersionTeaser();
+      new MutationObserver(hideVersionTeaser).observe(document.body, {
+        childList: true,
+        subtree: true,
+      });
+    });
+  }
+}

package/stack-template/app/ui-kit/.storybook/preview-head.html

@@ -0,0 +1,57 @@
+<style>
+  /* Canvas padding chuẩn — mọi story cách mép preview 24px, đồng nhất các nhóm. */
+  #storybook-root {
+    padding: 24px;
+  }
+
+  /* addon-docs tự set nền trắng (.sbdocs/.sbdocs-wrapper/.sb-wrapper) — ở dark
+     mode chúng đè lên body tối làm docs canvas trắng chói. Trả về token canvas
+     (dark.css override sẵn --c-canvas). Story mode không đụng các class này. */
+  body[data-bp-theme='dark'] .sb-wrapper,
+  body[data-bp-theme='dark'] .sbdocs,
+  body[data-bp-theme='dark'] .sbdocs-wrapper,
+  body[data-bp-theme='dark'] .sb-previewBlock {
+    background: var(--c-canvas);
+  }
+
+  /* Prose docs — addon-docs ép màu light #2e3438 lên MỌI tag trần trong
+     .sbdocs-content qua :where(p, li, h1-h5, th, td...):not(.sb-unstyled *)
+     (phep :where giữ specificity 0, trừ vùng render component). Phủ lại theo
+     ĐÚNG pattern đó khi dark — heading → --ink, thân/table → --ink2. Selector
+     có prefix body[...] nên đặc hiệu hơn rule addon, và :not(...) không đụng
+     component trong autodocs (tự màu qua utility kit). */
+  body[data-bp-theme='dark'] .sbdocs-content :where(h1, h2, h3, h4, h5, h6):not(.sb-anchor, .sb-unstyled, .sb-unstyled :is(h1, h2, h3, h4, h5, h6)) {
+    color: var(--ink);
+  }
+  body[data-bp-theme='dark'] .sbdocs-content :where(p, li, dt, dd, figcaption, blockquote):not(.sb-unstyled, .sb-unstyled *) {
+    color: var(--ink2);
+  }
+  body[data-bp-theme='dark'] .sbdocs-content :where(table th, table td):not(.sb-unstyled, .sb-unstyled *) {
+    color: var(--ink2);
+  }
+  /* .sbdocs-title (h1.sb-unstyled) bị emotion css riêng ép màu, :not() ở trên
+     loại nó ra — override trực tiếp. */
+  body[data-bp-theme='dark'] .sbdocs-title {
+    color: var(--ink);
+  }
+  /* ArgsTable header (autodocs) — span cột bị docblock ép đen mờ
+     rgba(46,52,56,.75) trên canvas tối. */
+  body[data-bp-theme='dark'] .sb-argstableBlock-head span {
+    color: var(--ink2);
+  }
+  /* Kicker section trang Introduction — --accent dark #5e6ad2 trên s1 hụt
+     ngưỡng AA 4.5 một chút (4.44, label 12px); dark nâng lên --accent-hi
+     (cùng vai trò manager barSelected). */
+  body[data-bp-theme='dark'] .bp-kicker {
+    color: var(--accent-hi);
+  }
+
+  /* Code inline addon-docs: chip nền trắng-sáng chữ đen — giữa canvas tối
+     thành khối chói lấn chữ. Trả về mono surface: nền s3 + mực ink2 + viền
+     line (khối pre giữ nguyên — addon đã render syntax dark sẵn). */
+  body[data-bp-theme='dark'] .sbdocs :not(pre) > code {
+    background: var(--c-s3);
+    color: var(--ink2);
+    border: 1px solid var(--line);
+  }
+</style>

package/stack-template/app/ui-kit/.storybook/preview.ts

@@ -0,0 +1,62 @@
+// Preview render primitives ĐÚNG ngữ cảnh design system: tokens (antd-look light
+// default) + base css + tailwind utilities (@tailwindcss/vite — main.ts).
+// Dark theme qua toolbar toggle (addon-themes — đặt `data-bp-theme="dark"` lên
+// <html>, đúng rule AGENTS.md; tokens.css tự import themes/dark.css nên không
+// cần import thêm ở đây). Canvas padding chuẩn 24px qua preview-head.html.
+import type { Preview } from '@storybook/react-vite';
+import { withThemeByDataAttribute } from '@storybook/addon-themes';
+import { addons } from 'storybook/internal/preview-api';
+import { GLOBALS_UPDATED, SET_GLOBALS } from 'storybook/internal/core-events';
+import './tailwind-preview.css';
+import '../src/styles/tokens.css';
+import '../src/styles/base.css';
+
+// Trang docs MDX thuần (Introduction, Intro/Showcase) không render story nào
+// → decorator withThemeByDataAttribute không chạy → body mất data-bp-theme,
+// canvas kẹt light dù toolbar đang dark (bug thấy 2026-10-23). Sync attr trực
+// tiếp theo globals trên channel: SET_GLOBALS lúc iframe boot (initial globals
+// từ URL ?globals=theme:dark), GLOBALS_UPDATED khi user bấm toggle toolbar.
+type GlobalsPayload = { globals?: Record<string, unknown> };
+const syncBodyTheme = ({ globals }: GlobalsPayload): void => {
+  const theme = (globals?.theme as string | undefined) ?? 'light';
+  document.body.setAttribute('data-bp-theme', theme);
+};
+const channel = addons.getChannel();
+channel.on(SET_GLOBALS, syncBodyTheme);
+channel.on(GLOBALS_UPDATED, syncBodyTheme);
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    a11y: {
+      // Iframe standalone là 1 trang không main/h1/landmark — 3 rule PAGE-SCAFFOLD
+      // (axe: landmark-one-main, page-has-heading-one, region) đánh vào khung xem,
+      // không phải component (audit 3D 21:58 xác nhận). Component vẫn bị audit
+      // đầy đủ các rule còn lại (contrast, aria, name...).
+      rules: [
+        { id: 'landmark-one-main', enabled: false },
+        { id: 'page-has-heading-one', enabled: false },
+        { id: 'region', enabled: false },
+      ],
+    },
+  },
+  decorators: [
+    withThemeByDataAttribute<Preview>({
+      themes: { light: '', dark: 'dark' },
+      defaultTheme: 'light',
+      attributeName: 'data-bp-theme',
+      // 'body' thay vì 'html' mặc định: tokens.css khai light trong `:root` (line
+      // 13) SAU khi @import dark.css (line 11) — cùng specificity 0-1-0, rule sau
+      // thắng ⇒ trên <html> light đè dark. <body> không match :root → dark thắng,
+      // var cascade xuống toàn canvas (đúng rule AGENTS: html HOẶC node bao).
+      parentSelector: 'body',
+    }),
+  ],
+};
+
+export default preview;

package/stack-template/app/ui-kit/.storybook/tailwind-preview.css

@@ -0,0 +1,3 @@
+/* Storybook-only tailwind entry — storybook chạy Vite riêng nên tự @import
+ * (không dùng qua app). @theme inline định nghĩa ở ui-kit/styles/tailwind.css. */
+@import '../src/styles/tailwind.css';

package/stack-template/app/ui-kit/.storybook/test-runner.config.ts

@@ -0,0 +1,20 @@
+// Cấu hình test-runner (mop-up round 2, worker V1 2026-10-18).
+//
+// Flaky đã mổ xẻ: chạy full sweep với default workers (~số CPU) làm nghẽn dev
+// server Vite on-demand → một số iframe load không kịp đủ module graph → helper
+// `__test` của runner chưa register (`__test is not defined` / TDZ `'blue'`).
+// Fix chứng minh: --maxWorkers=2 → 620/620 pass ổn định.
+//
+// Ràng buộc: TestRunnerConfig của test-runner 0.26 KHÔNG có maxWorkers/retry —
+// maxWorkers chỉ đặt qua CLI, đã cố định trong package.json:
+//   "test-storybook": "test-storybook --maxWorkers=2"
+// Ai cần worker khác: `pnpm exec test-storybook --maxWorkers=<n>` (ghi đè script).
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
+  // Giảm ồn log runner (chỉ hiện warn/error khi có sự cố) — sweep 620 story
+  // in hàng nghìn dòng a11y-warn gây rối output CI.
+  logLevel: 'warn',
+};
+
+export default config;

package/stack-template/app/ui-kit/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog — @wakii/ui-kit
+
+Format theo [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); đánh số hướng SemVer.
+ui-kit **consumed qua source** (ADR-0009) nên "release" = điểm merge PR vào `main`;
+mục `[Unreleased]` gom các batch giữa 2 lần merge.
+
+## [0.5.0] — 2026-10-24 (BREAKING — barrel chính sạch彻底 peer imports)
+
+### Breaking
+
+- **`Carousel` rời barrel chính** → `import { Carousel } from '@wakii/ui-kit/carousel'`. Component phụ thuộc `swiper/react` (peer) — nằm trong barrel phá nguyên tắc 0-deps: consumer KHÔNG cài swiper fail vite build (`"Swiper" is not exported` — bắt từ gate create-wakii-app end-to-end). Không consumer nào trong monorepo import từ barrel (đã grep).
+
+### Fixed (chuỗi hotfix 0.4.1→0.5.0 — tất cả bắt từ gate scaffold thật + install + vite build)
+
+- 0.4.1: npm exports trỏ TS source → consumer vite không resolve package entry; publish script rewrite exports sang dist (6 entry)
+- 0.4.2/0.4.3: dynamic peer imports (chart.js/auto, @fullcalendar/*) qua biến specifier — rollup consumer không phân tích
+- 0.4.4: EditorInner entry riêng + tsup splitting:false — @tiptap/starter-kit không lọt index bundle qua shared chunk
+- 0.5.0: Carousel dời subpath — swiper/react không lọt barrel (này)
+
+## [0.4.4] — 2026-10-24 (hotfix 4 — index bundle sạch peer static imports)
+
+### Fixed
+
+- **`@tiptap/starter-kit` static import lọt vào index bundle qua shared chunk** — consumer không cài tiptap vẫn fail build dù không dùng Editor. tsup `splitting: false` (mỗi entry self-contained) + **EditorInner thành entry riêng** (`dist/editorInner.js`) — wrapper `React.lazy` import qua biến specifier (esbuild inline dynamic import khi không splitting; type giữ qua `import type`). Sau fix: `grep tiptap dist/index.js` chỉ còn fallback message string. Chuỗi hotfix 0.4.1→0.4.4 đều bắt từ gate end-to-end create-wakii-app (scaffold thật + install + vite build).
+
+## [0.4.3] — 2026-10-24 (hotfix 3 — dynamic peer import qua biến specifier)
+
+### Fixed
+
+- `/* @vite-ignore */` bị esbuild strip khỏi dist (comment) — consumer build vẫn fail. Dynamic peer imports (chart.js/auto, @fullcalendar/*) chuyển sang **biến specifier** (`const FC_CORE = '@fullcalendar/core'; import(FC_CORE)`) — rollup/vite của consumer không thể phân tích tĩnh, giữ nguyên runtime import + fallback khi peer thiếu.
+
+## [0.4.2] — 2026-10-24 (hotfix 2 — consumer vite build với dynamic peer imports)
+
+### Fixed
+
+- **Consumer Vite production build fail: `Rollup failed to resolve import "@fullcalendar/daygrid"`** — rollup phân tích cả dynamic import peer trong dist chunk dù consumer không cài peer đó. Dynamic imports peer (chart `chart.js/auto`, schedule `@fullcalendar/*`) thêm `/* @vite-ignore */` — bundler bỏ phân tích, runtime import bình thường (fallback sẵn khi peer thiếu). Bắt khi gate create-wakii-app: scaffold thật + install + `vite build` end-to-end.
+
+## [0.4.1] — 2026-10-24 (hotfix publish — exports dist cho npm consumers)
+
+### Fixed
+
+- **npm exports trỏ TS source → consumers ngoài monorepo không build được** — repo exports `./src/index.ts` (ADR-0009 đúng cho monorepo) nhưng Vite/webpack consumers qua npm KHÔNG resolve được package entry `.ts` (`Failed to resolve entry for package` — bắt được khi gate create-wakii-app scaffold thật install + build). Publish script giờ rewrite exports sang **dist** (6 entry js/cjs/d.ts kể cả experience3d — tsup thêm entry) + main/module/types; styles giữ src (css thuần, có trong tarball). Repo không đổi (monorepo vẫn consumed-qua-source).
+
+## [0.4.0] — 2026-10-24 (depth & motion wave — dark toàn diện + hooks mở trọn barrel)
+
+> 23 commits (PR #55–#67 squash + trực tiếp): depth/elevation tokens, cinematic experience template, 12 hooks + 3 utils mở trọn barrel, Storybook manager 2 palette, landing ×2 motion showcase, sweep glyph→Icon SVG, app FE dark+motion pass, chart probe dark-live, Introduction redesign. Suite tại HEAD: **163 files / 1290 tests PASS** · **683 story exports / 142 file stories** (đếm tĩnh).
+
+### Added
+
+- **Depth & elevation tokens (coordinator)** — elevation 3 tầng `--ele-1..3` (shadow + inset highlight viền trên — component dùng theo trạng thái rest/hover/active, overlay giữ `--shadow-pop`) · surface wash `--wash` (kết hợp utilities `bg-s1/s2`) · depth contract `--ease-smooth`/`--motion-smooth` cho state-change. (`95ab014`, `55017c6`)
+- **Experience cinematic template (workers V2, D)** — nhóm mới `templates/experience/`: `ChapterShell` lib + hero/chapters "chaptershell" (glass-nav contract sf3, design contract typography/palette/mood engine sf1) — chapter-shell test 77 assertions, sf3 **44 tests**. (`3ac8044`, `46f6807`)
+- **Hooks wave ×12 + 3 utils + ScrollPage — MỞ TRỌN BARREL (PR #65)** — lifecycle/observers/controllable: `useMountEffect` · `useUpdateEffect` · `useIsFirstRender` · `useControllableState` · `useEventListener` · `useScrollProgress` · `useInView` · `useInfiniteScroll` · `useMeasure` · `useOnlineStatus` · `useFullscreen` · `useTitle` + utils `format` (`formatCurrency`/`formatBytes`/`formatRelativeTime`/`formatNumber`), `array` (`chunk`/`groupBy`/`flattenTree`/`findTreeNode`), `dom` (`getScrollParent`/`getFocusableElements`/`cx`) + `ScrollPage` section-snap; gỡ nợ barrel treo từ `267a273` — hooks suite **110 tests / 30 files**. (`1476eaf`)
+- **Team-OS domain (worker V1)** — `PingFeed` (+`relTime`) · `StagePipeline` · `DebtBoard` · `TeamDashboard` · `InboxThread` — 29 tests. (`e22db92`)
+- **Motion depth cluster (worker W8)** — transition family mở rộng 11 types, barrel dedupe (`Collapse`→`CollapseTransition` precedent) — 102 tests. (`2032bc1`)
+- **Depth pass forms + data display (workers W6, D)** — 19 form + 7 data component polish theo depth contract (`ease-smooth`, elevation tier) — suite 1244 tại thời điểm đợt. (`f666fbe`)
+- **Storybook manager chrome 2 palette (PR #57, #60)** — manager UI đồng bộ ngôn ngữ ui-kit (light antd / dark direction-B, brand + head html), trang showcase `Intro/Showcase` "Why Wakii UI Kit" (hero Reveal + stats CountUp + live demo + why-grid + footer CTA). (`ab2ac81`, `04cf002`)
+- **Landing + Parallax Landing motion showcase (PR #62, #63)** — `landing.stories` motion hero + dọn prose dark contrast; `parallax-landing` depth-trio hero + parallax lab. (`dcdc4f8`, `3254185`)
+- **Hooks demo stories ×9 (PR #67)** — `hooks-new.stories` (Theming & Motion/Hooks/New Wave): demo tương tác thật cho cả 12 hook mới (log timeline, controlled/uncontrolled toggle, scroll/in-view/infinite labs, online stub tự khôi phục, fullscreen + title). (`e4d2229`)
+- **Chart probe dark-live (PR #66)** — pattern `useChartColors` (span ẩn + `getComputedStyle` đọc token trong theme scope, fallback hex như dashboard template) + `MutationObserver` trên `<html data-bp-theme>` → chart re-resolve màu NGAY khi dark toggle, không F5; áp `admin` Dashboard. (`f6469cd`)
+- **Input.Search attached-button + InputNumber antd-fidelity redo (worker W6)**. (`c456866`)
+
+### Fixed
+
+- **Chart 2-shape bug (PR #67)** — `<Chart>` ép rebuild config theo shape flat (`config.labels`) trong khi consumer (admin Dashboard) truyền shape native chart.js v4 (`data:{labels,datasets}` lồng) → chart RỖNG im lặng (canvas 0 pixel, 0 lỗi console — chỉ bắt được bằng browser verify thật). Fix: component resolve cả 2 shape (`labels ?? data.labels`), type thêm nested optional + test nested mới; admin Dashboard chuẩn hoá về flat theo type. (`e4d2229`)
+- **Dark docs text chìm (PR #61, #62)** — heading h1-h4 + inline code + note `ink2` trong docs/preview; dọn hết prose contrast sót (`preview-head` + `intro.docs`). (`a5f3414`, `dcdc4f8`)
+- **Dark tokens polish (PR #60)** — `--ink4` `#5c626b` (mirror antd dark colorTextQuaternary, cùng họ `--ink3` `#8a8f98`) · `--bg-disabled` 4% đồng tỉ lệ light · alert tints dark chuyển alpha tint màu trạng thái (bg 12% / border 37%, error base = `--st-fail` dark `#f06a6a` — đồng bộ 100% 4 type) · shadow dark đậm ×1.6 · `color-scheme: light` default + `color-scheme: dark` scoped `[data-bp-theme="dark"]` (native controls ăn theo theme). (`04cf002`)
+- **Sweep glyph ký tự → Icon SVG (PR #59, #60)** — đợt 1: 9 components (alert/drawer/input/input-search/table…); đợt 2: steps tick ✓, select marker ✓, upload-core/dropzone 4 SVG tự vẽ → Icon file/check/times/upload + **icon set 50→52** (`filter-fill`/`filter-slash`) + rounded chuẩn controls + focus-visible sót. (`ec7e1dc`, `04cf002`)
+- **Table first-column sticky + Calendar responsive 375 (worker W6, PR #55)**. (`85cc797`)
+- **Repo debts (PR #56)** — barrel `index.ts` export module chưa commit treo typecheck/test/build-storybook (gỡ export, mở khoá bằng `262e512`) · theme tokens dark · xoá `go-svc/ci.compose.override.yml` redundant · docs drift (CI disabled note, ADR-0009 index, ink3 templates, known-issue standalone). (`267a273`)
+
+### Changed
+
+- **Templates ink3→ink2 (PR #64)** — dark audit M#3: body mô tả chính (auth subtitle ×4, crud/settings emptyMessage, settings danger-zone caption) `text-ink3` → `text-ink2`; meta phụ giữ ink3. (`1ab7585`)
+- **App FE dark + motion pass (PR #66)** — shell · tasks · activity · admin: nội dung chính ink2, nav link rest + CTA "Đăng nhập" nâng contrast (hover→ink), page subtitles admin ink2; chart admin probe dark-live. (`f6469cd`)
+- **Introduction docs redesign ×2 vòng (PR #58, #67)** — #58 hero + stats + card layout; #67 đem ngang tầm showcase: wash hero + Reveal stagger, kicker accent + `Title level={2}` thay markdown trần, card hover-lift, demo bọc `Card`, CTA cuối dẫn Showcase. (`5490c8c`, `e4d2229`)
+
+## [0.3.0] — 2026-10-19 (story VU-53 UI redesign — OCD parity wave)
+
+> ~110 commits: 30+ component mới (Timesheet/Kanban/3D/Parallax-họ/Layout/TreeTable...), 6+1 templates, motion-max, a11y pass, app-fit 4 apps Wakii, storybook 131 titles/641 stories, eslint 0/0, 1111+ tests. Chi tiết mục dưới.
+
+### Added
+
+- **Motion system (worker W8)** — 2 đợt chuyển động 0-deps, chỉ animate `transform`/`opacity`: `Transition` family — `Fade`/`Zoom`/`CollapseTransition` (grid-rows 0fr↔1fr, 3 tầng grid > min-h-0 > children — không padding-leak) + `Backdrop` scrim `--scrim-4`; `unmountOnExit` mặc định, state machine kiểu Modal (exit chạy xong mới unmount, guard `e.target`), barrel đổi `Collapse`→`CollapseTransition` · `Parallax` (scroll-linked translateY + rAF-throttle, tự tắt reduced-motion) · `Reveal` (IntersectionObserver, `direction`/`delay`/`once`) · `CountUp` (rAF ease-out, `decimals`/`format`, animate tiếp từ số đang hiển thị) — **36 tests (13 + 23) + 20 stories (7 + 13)**. (`157cfc2`, `47e1f55`)
+- **Navigation & data display (workers V2, W9, D, W7)** — `OrgChart` cây tổ chức connector thuần CSS (dept/person node, collapse, `role=tree/treeitem`) · `MegaMenu` bar + panel dropdown multi-column (group = cột, hover/click, ESC trả focus trigger) · `SlideMenu` trượt ngang giữa các cấp (`translateX`, back bar, trang ẩn `inert`) · `Layout` composite antd (Header/Content/Footer/Sider + `useSiderCollapsed`) · `TreeTable` cây dạng bảng (`role="treegrid"`, expander + indent, selection, expand animate grid-rows) · DragDrop primitives + `KanbanBoard` polish edge-cases (native HTML5 DnD — không touch, peer-dep dnd-kit nếu cần) — **66 tests (8 + 14 + 19 + 25) + 29 stories**. (`7e3d0ec`, `b73d2e6`, `1782a5d`, `a8e6fd1`)
+- **Mobile batch (worker V1)** — 4 component layout hẹp: `BottomNavigation` (fixed-bottom MUI-style, `hideOnScroll`) · `FloatButton` + `Group` (nút nổi + BackTop tích hợp) · `Fieldset` (legend lợn viền, toggleable) · `DeferredContent` (IntersectionObserver render-lazy) — **26 tests + 16 stories**. (`70f1f36`)
+- **Forms & field arrays (workers W6, V2)** — `useFieldArray` companion `useForm` (antd Form.List parity): `fields`/`count`, `append`/`remove`/`move` (insert-at)/`swap`/`update`, `nameAt` giữ focus-first-invalid, errors rebuilt từ snapshot — lỗi đi theo ROW · `Checkbox` tri-state (`null` = indeterminate, `aria-checked="mixed"`) · `InputNumber` stepper flush container (chỉ góc ngoài bo, `active:opacity` thay scale) — **16 tests mới (12 + 4) + 3 stories + demo**. (`8c5f716`, `e94b3e4`, `4b85830`)
+- **antd/MUI parity + Table advanced (worker W6)** — Gap P0: `Input.Search` composite · `Link` (underline modes, disabled bỏ href) · `Affix` (sticky thuần, onChange đo trên scroll container thật) · `Table` `expandable` · Gap P1: `QRCode` SVG (vendored qrcode-generator v1.4.4 MIT, UTF-8, không deps runtime) + `icon` excavate mode R10 (khung nền punch-out giữa đồng bộ bgColor — matrix giữ nguyên, scanner bù qua EC; có icon không truyền level tự nâng H) · Table advanced: `scroll={{ y }}` fixed header + filter row sticky, `summary` tfoot dính đáy (data trang hiện tại), sorting 3-state + `aria-sort` — **56 tests (28 + 12 + 16) + 29 stories (19 + 4 + 6)**. (`31f5d05`, `8c5f716`)
+- **Templates showcase (workers W6, W7, V2, D)** — 6 trang template trong `src/templates/`: Auth (sign-in/up split-hero useForm) · CRUD Table (toolbar search/filter + table đầy đủ + Drawer form zod focus-first-invalid + Popconfirm + toasts) · Dashboard admin · Kanban project · Landing (parallax) · Settings (tabs + theme live) — **9 story exports**. (`69e7e42`, `417f089`, `3a55922`, `31f5d05`)
+- **Storybook & docs infra (worker W8 + lead)** — trang Introduction docs + toolbar dark-mode `@storybook/addon-themes` (đặt `data-bp-theme` trên body preview) + manager brand + canvas padding 24px · taxonomy stories chuẩn hoá 7 nhóm naming EN + autodocs order · recipes motion (Fade/Zoom/Collapse/Backdrop + parity docs) — 0 component code. (`8d8dad1`, `38943c4`, `26bfceb`, `2017ac6`)
+- **App-fit apps (workers D, V2)** — `admin` dashboard layout ui-kit (Grid/Card giữ stat-intent — 7 tests) · `activity` ActivityPage migrate `StatTile`/`Card`/`Statistic`. (`d6db790`, `324b491`)
+- **Accordion (worker D)** — nhóm panel mở-một kiểu PrimeReact/MUI: mặc định single-open (mở item mới **tự đóng** item đang mở), `multiple` → hành vi Collapse (nhiều mở cùng lúc); controlled `activeKey` (`string` khi single / `string[]` khi multiple) + `onChange` payload theo mode, `defaultActiveKey` uncontrolled; `items` dùng lại shape `CollapseItem` (key/label/children/disabled per-item); visual/motion kế thừa Collapse (`rounded-xl border-line bg-s2`, chevron xoay 180, animate grid-rows 0fr↔1fr) ; a11y `aria-expanded` + `aria-controls` trên header, panel `role="region"` labelledby — 9 tests + 6 stories. (`03e8ad2`)
+- **Timesheet (worker W7)** — grid log giờ theo tuần (chấm công/approval): hàng = task/dự án (`rows`: `label` + `meta` + `values` đúng 7 phần tử T2→CN, `null` = ô trống), cột = 7 ngày **luôn bắt đầu Thứ 2** (vi T2 / en Mon, khác Calendar theo firstDayOfWeek), cell = giờ — `editable` → InputNumber compact clamp 0–24 step 0.5, bắn `onCellChange(rowKey, dayIndex, value|null)`; footer tổng cột + grand total `font-medium` + `tabular-nums`; nav prev/next bắn `onWeekChange(weekStart)` + grid remount replay `bp-fade-in`; locale `vi`/`en` (nhãn tuần `19–25 Th10 2026` / `Oct 19–25, 2026`, aria ô `Thứ 2 20/10 · Task A`); cột T7/CN nền `bg-s3/60` nhẹ; `loading` skeleton; `classNames` slots (`wrapper`/`header`/`row`/`cell`/`footer`) — 9 tests + 7 stories. (`dd740e5`)
+- **Alert** — variant `filled` mặc định: nền đặc màu type, chữ/icon trắng, WCAG AA; `variant="outlined"` giữ look cũ. (`ab76cfe`)
+- **InputNumber** — restyle PrimeReact stepper: SVG chevron, hover/active, keyboard ↑↓. (`ab76cfe`)
+- **Pagination** — antd redesign: item vuông 32px outline `border-line`, active `bg-accent` chữ trắng `font-medium`, SVG chevron, ellipsis `···` jump ±5, disabled `text-ink3` không viền. (`ab76cfe`)
+- **Carousel** — nút nav custom hoạt động thật trên swiper v14, prop `height`, `onSlideChange` dùng `realIndex` (loop-safe); stories 2→8. (`292b1a3`)
+- **Calendar** — đồng bộ ngôn ngữ nút Pagination: ngày thường outline, selected accent đặc, today ring accent, adjacent disabled. (`292b1a3`)
+- **Hooks native ×16** theo spec usehooks.com: `useDebounce`, `useThrottle`, `useToggle`, `useLocalStorage`, `useSessionStorage`, `useMediaQuery`, `useWindowSize`, `useHover`, `useClickAway`, `useKeyPress`, `useTimeout`, `useCountdown`, `useCopyToClipboard`, `usePrevious`, `useDefault`, `useLockBodyScroll` — 60 behavior tests. (`4baf52b`)
+- **Menu** đa cấp antd parity (vertical/horizontal, submenu không giới hạn cấp, auto-open nhánh chứa selectedKey, animate grid-rows, role `menu`/`menuitem`) + **Sidebar** collapsible 200↔80px icon-only qua `MenuCompactContext` — 24 tests + 7 stories. (`11bb127`)
+- **useForm** native + peer-dep **zod ^4**: `values/errors/touched`, mode `onSubmit|onBlur|onChange`, submit sai → focus field đầu — 9 tests. (`375baae`)
+- **Upload + UploadDropzone** — drag-drop, beforeUpload guard, danh sách file remove — 14 tests + 5 stories. (`55288b1`)
+- **Field** — wrapper label + control + error/hint với id `aria-describedby` suy từ `htmlFor`. (`5615a9b`)
+- **Subpath exports** component nặng (tách CSS khỏi barrel chính): `@wakii/ui-kit/carousel`, `./chart`, `./schedule`, `./editor`. (`5615a9b`, `463cef4`)
+- **Z-index scale tokens**: `--z-dropdown < --z-popover < --z-modal < --z-toast < --z-tooltip`. (`5615a9b`)
+- **Icon** — 48 icon path data gốc primeicons 7.0.0 (`size`/`className`/`aria-hidden`), refactor chevron 5 component dùng bộ chung. (`463cef4`)
+- **List** (antd pattern: loading Skeleton + empty EmptyState + pagination client), **AvatarGroup** (stack overlap + max "+N"), **TreeSelect** (searchable, chọn leaf, trigger hiện đường dẫn) — 28 tests. (`530a4a1`)
+- **DatePicker** range + showTime, **TimePicker** mới (stepper Giờ/Phút + "Bây giờ"), locale `vi`/`en` cho họ date — 25 tests. (`f4d1883`)
+- **Alert** — nền `filled` tokenize `--alert-error/warning/info/success-filled` (shade 700 antd theo type, look không đổi). (`1a086a8`)
+- **Tokens scrim/mask** — thang `--scrim-1..4` theme-independent phủ media (bullet indicator/nav button/backdrop) + `--mask` mới cho overlay drawer/modal (BlockUI chuyển `var(--mask)` + z-token, chữ trắng; dark đậm hơn 0.6); thêm `--fs-h3` 15px. (`1a086a8`)
+- **ContextMenu** — keyboard nav ArrowUp/Down/Home/End (bỏ qua item disabled), `role="menuitem"` + `aria-disabled`, focus ring, menu `w-max` chống tràn viewport. (`1a086a8`)
+- **Tooltip/Popconfirm** — wire aria lên trigger qua `cloneElement`: Tooltip `aria-describedby` khi mở, Popconfirm `aria-haspopup="dialog"` + `aria-expanded`; bubble Popconfirm `role="dialog"` + shadow `--shadow-pop`. (`1a086a8`)
+- **Tree/Steps/TabMenu/Menubar/Timeline** — a11y pass: Tree role `treeitem`/`group` + Icon chevron thay ký tự `▸`; Steps `aria-current="step"`, TabMenu `aria-current="page"`; Menubar focus ring + z-token, submenu item nhận `onClick`; Timeline label `text-label`. (`1a086a8`)
+- **Dropdown** — đồng bộ menu family: `rounded-xl`, z-token `--z-dropdown`, focus ring accent, active state. (`1a086a8`)
+- **DatePicker** — polish: placeholder range `text-ink4`→`text-ink` (contrast), panel `min-w-[300px]`, nút footer Today/OK to hơn. (`1a086a8`)
+- **Schedule** — skin FullCalendar qua CSS vars: nút toolbar Button-like (bg-s2/border-line, active accent, focus ring), frame border/radius/today-bg ăn token (dark tự theo); prop `height` mặc định 650 — khung không nhảy giữa tháng 5/6 hàng. (`1a086a8`)
+- **Select** — Icon check accent khi selected (single) + menu `min-h-[104px]` chống nhảy panel. (`1a086a8`)
+- **CascadeSelect** — panel căn giữa trigger (`w-max` + translate), width theo content thay vì full-width. (`1a086a8`)
+- **Table** — zebra dịu hơn: `bg-s3` → `bg-s3/40`. (`1a086a8`)
+- **A11y/focus-ring sweep** — Pagination, Inplace (Icon times), PanelMenu, Segmented, ToggleButton thêm focus ring + radius `rounded-lg`; Tabs inactive `opacity-65`; Typography Title H1 weight 700; JSDoc props + stories/test mở rộng ~40 component; xoá test debug rác `pick-list/__d4.test.tsx`. (`1a086a8`)
+- **Grid (Row/Col), Flex, Anchor** — layout + nav batch: `Row`/`Col` 24-col kiểu antd (`gutter` `[ngang, dọc]` qua negative-margin + col padding, span mobile-first `xs→xl` resolve matchMedia, wrap tự động) · `Flex` 1 trục (`gap` thang `small|middle|large|px`, `vertical`, justify/align) · `Anchor` in-page TOC scroll-spy (`items` nested, `affix` sticky, `offsetTop`, `getContainer`, `aria-current`) — 35 tests + stories EN. (`4fd4323`)
+- **Popover, Watermark** — overlay batch: `Popover` panel neo trigger nội dung tự do (`title` divider + `content` ReactNode, `trigger` hover/click/focus, controlled `open`/`onOpenChange`, ESC + click-outside qua `useClickAway`, `role="dialog"` + trigger `aria-expanded`) · `Watermark` overlay tile SVG data-URI lặp (`rotate` −22° mặc định, `gap`/`offset`, màu resolve token `--ink3` + re-bake khi đổi theme, overlay `pointer-events-none` children vẫn bấm được) — 18 tests + stories EN. (`291ce0d`)
+
+### Fixed
+
+- **Tooltip token dark contrast (worker V2)** — `--tooltip-bg` dark-surface + chữ `--ink` (thay nền/độ tương phản cũ vi phạm AA). (`4a480c1`)
+- **Radius sweep (worker W7)** — `rounded-3` legacy → `rounded-xl` đồng bộ 9 files qua 4 apps (chuẩn hoá theo quy ước radius control/card). (`1d42d3f`)
+- **Scrollbar** — thumb mặc định `#5b5b5b` clash thiết kế (user báo): custom 8px pill `var(--line2)` track transparent (dark tự theo nhờ dark.css override `--line2` — 0 hex), `scrollbar-width: thin` + ⚠️ macOS overlay scrollbar → chuyển thành thin persistent: hành vi chấp nhận có chủ đích (nhất quán cross-app). (`8013033`)
+- **InputNumber stepper** — nút lập flush container: radius CHỈ góc ngoài (up `rounded-tr-lg`, down `rounded-br-lg`; góc trong = 0, container `overflow-hidden` clip theo `rounded-lg`), active `opacity-70` thay `scale-95` (scale co nút làm hở viền) — kèm 4 stories demo `useFieldArray` cho Field. (`e94b3e4`)
+- **Dark theme không ăn**: `@import "./themes/dark.css"` đứng sau rule thường bị drop theo spec CSS — chuyển lên đầu `tokens.css`. (`ab76cfe`)
+- **Carousel nút prev/next chết** trên swiper v14 (init trong render → refs null lúc `onBeforeInit`) — test click-đổi-realIndex chặn regression. (`292b1a3`)
+- **17 story file 0-export** bị Storybook indexer drop: 12 file dựng dở viết lại story matrix + 5 component menu-family tạo stories mới — index **51 → 79 titles, 190 stories**. (`6f4c9a0`)
+- stories Pagination sai type meta/args sau merge main (TS2322/TS2353). (`a55b2fe`)
+- **useFocusTrap** — dialog không có element focusable nào (vd image preview chỉ có img): giữ focus trên container thay vì cho Tab thoát ra ngoài (WAI-ARIA modal). (`1a086a8`)
+
+### Đồng bộ consumer (cùng đợt)
+
+- `remote-tasks`: selector test Skeleton/aria-busy cập nhật theo DOM mới sau migration ui-kit (PR #44). (`c056e92`, `3197ef1`)

package/stack-template/app/ui-kit/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wakii-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/stack-template/app/ui-kit/MIGRATION.md

@@ -0,0 +1,84 @@
+# Migration — @wakii/ui-kit
+
+Các breaking/behavior change giữa 2 lần merge, và cách giữ hành vi cũ khi cần.
+Xem [CHANGELOG.md](./CHANGELOG.md) cho danh sách đầy đủ.
+
+## 1. Alert — `filled` là mặc định (2026-10-18)
+
+`Alert` giờ render **nền đặc màu type + chữ trắng, không viền** (WCAG AA với màu đậm đã chọn).
+Look cũ (tint bg + viền + chữ màu) không mất — chuyển sang `variant="outlined"`.
+
+```tsx
+// TRƯỚC (look cũ trở thành mặc định)
+<Alert type="error" message="Gán thất bại" />
+
+// SAU — mặc định filled (nền đặc, chữ trắng)
+<Alert type="error" message="Gán thất bại" />
+
+// GIỮ look cũ
+<Alert type="error" message="Gán thất bại" variant="outlined" />
+```
+
+**Ảnh hưởng**: `remotes/tasks` + `remotes/activity` đang hiển thị banner lỗi/thành công —
+đã verify test xanh sau đổi; UI banner chuyển sang filled là chủ đích design (khối lượng
+chữ trắng nổi hơn trên mọi surface). API props khác (`message/description/closable/onClose`)
+giữ nguyên.
+
+## 2. Pagination — antd look (viền + radius + icon)
+
+Item đổi khối class — nếu consumer có CSS/selector bám class cũ cần đối chiếu:
+
+| Trạng thái | Trước | Sau |
+|---|---|---|
+| Item thường | `rounded-2 border border-transparent` | `rounded-lg border border-line bg-transparent` |
+| Active | `rounded-[4px] border-none bg-accent` | `rounded-lg border-none bg-accent text-white font-medium` (hover giữ accent) |
+| Prev/Next | ký tự `‹ ›` | SVG chevron (`<Icon name="chevron-left/right" size={14}/>`), disabled = `text-ink3 cursor-not-allowed` không viền |
+| Ellipsis | `•••` | `···` (middot) — **text content đổi**, selector theo text phải sửa |
+
+API props, `pageList` logic, `aria-label`/`aria-current` **giữ nguyên**.
+
+## 3. Imports nặng — chuyển subpath
+
+CSS của component nặng đã **tách khỏi barrel chính** để barrel không kéo CSS/Swiper khi
+chỉ dùng primitive. Consumer đang import carousel/chart/schedule/editor từ barrel cần chuyển:
+
+```tsx
+// TRƯỚC — kéo cả swiper CSS qua barrel
+import { Carousel } from '@wakii/ui-kit';
+
+// SAU — subpath (component + CSS gói cùng nhau)
+import { Carousel } from '@wakii/ui-kit/carousel';
+import { Chart } from '@wakii/ui-kit/chart';
+import { Schedule } from '@wakii/ui-kit/schedule';
+import { Editor } from '@wakii/ui-kit/editor';
+```
+
+Yêu cầu đi kèm: `swiper` là **peer-dep của subpath carousel** — consumer tự cài
+(`pnpm add swiper`) đúng pattern `zod` với `useForm`. Shell/remotes đã chuyển hết;
+story file demo tự import `'swiper/css'` để canvas Storybook có style.
+
+## 4. Z-index — dùng scale token, không hardcode
+
+Sistema tầng mới (thấp → cao): `--z-dropdown:1000 < --z-popover:1030 < --z-modal:1050
+< --z-toast:1070 < --z-tooltip:1090`.
+
+```tsx
+// TRƯỚC — số cứng, dễ xung đột tầng
+<div className="absolute z-50">…</div>
+
+// SAU — token theo tier
+<div className="absolute z-[var(--z-dropdown)]">…</div>
+```
+
+Nếu app consumer **override** thứ tự tầng (vd modal dưới toast), override biến ở scope
+của mình — `:root { --z-toast: 1040; }` — thay vì sửa `z-*` rải rác trong component.
+
+## 5. useForm — zod là peer-dep
+
+`useForm` yêu cầu `zod ^4` do consumer khai báo (`pnpm add zod`). ui-kit chỉ đặt
+`peerDependencies` — không bundle schema engine vào barrel.
+
+```bash
+# consumer (shell/remotes) cần có zod trước khi dùng useForm
+pnpm add zod@^4
+```