create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,278 @@
+// Chart stories — full case matrix: Line 1/2 datasets, single/grouped Bar, Pie,
+// Doughnut, Radar, Mixed bar+line, Colors custom, Height, Options passthrough +
+// Fallback/EmptyData (edges). Verify standard: canvas alpha > 5% for every story
+// with data (EmptyData is intentionally blank, Fallback has no canvas).
+import { useMemo, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from '../button/index';
+import { UiKitProvider } from '../../provider/index.js';
+import { Chart, useChartTheme } from './index';
+import type { ChartConfig } from './index';
+
+const meta = { title: 'Data Display/Chart', component: Chart, tags: ['autodocs'] } satisfies Meta<typeof Chart>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+// ui-kit palette (light tokens) — explicit demo colors, not runtime tokens.
+const ACCENT = '#5e6ad2';
+const ACCENT_HI = '#828fff';
+const DOING = '#f2c94c';
+const DONE = '#3fb950';
+const FAIL = '#f06a6a';
+const INK3 = '#8a8f98';
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'];
+
+/** Single Bar — 1 dataset, default height 260. */
+export const Bar: S = {
+  args: {
+    config: {
+      type: 'bar',
+      labels: MONTHS,
+      datasets: [{ label: 'Revenue', data: [12, 19, 3, 15, 9, 17], backgroundColor: ACCENT }],
+    },
+  },
+};
+
+/** Grouped Bar — 3 colored datasets comparing 3 years on shared labels. */
+export const BarGrouped: S = {
+  name: 'Bar — grouped 3 datasets',
+  args: {
+    config: {
+      type: 'bar',
+      labels: MONTHS,
+      datasets: [
+        { label: '2024', data: [12, 19, 3, 15, 9, 17], backgroundColor: ACCENT },
+        { label: '2025', data: [8, 14, 11, 18, 13, 20], backgroundColor: DONE },
+        { label: '2026', data: [15, 9, 16, 12, 19, 14], backgroundColor: DOING },
+      ],
+    },
+  },
+};
+
+/** Single Line — 1 dataset with a soft area fill via semi-transparent backgroundColor. */
+export const Line: S = {
+  args: {
+    config: {
+      type: 'line',
+      labels: MONTHS,
+      datasets: [{ label: 'Growth', data: [5, 9, 7, 12, 14, 11], borderColor: ACCENT, backgroundColor: 'rgba(94,106,210,0.15)' }],
+    },
+  },
+};
+
+/** Two-series Line — compare 2 series on one axis (distinct borders, no fill). */
+export const LineTwoDatasets: S = {
+  name: 'Line — 2 datasets compared',
+  args: {
+    config: {
+      type: 'line',
+      labels: MONTHS,
+      datasets: [
+        { label: 'Node-svc', data: [30, 42, 38, 55, 49, 60], borderColor: ACCENT },
+        { label: 'Go-svc', data: [20, 25, 33, 28, 44, 51], borderColor: DONE },
+      ],
+    },
+  },
+};
+
+/** Pie — backgroundColor is an ARRAY, one color per slice (same length as labels). */
+export const Pie: S = {
+  args: {
+    config: {
+      type: 'pie',
+      labels: ['Todo', 'In progress', 'Done', 'Failed'],
+      datasets: [{ label: 'Tasks', data: [8, 5, 11, 2], backgroundColor: [INK3, DOING, DONE, FAIL] }],
+    },
+  },
+};
+
+/** Doughnut — same as Pie with a center hole (chart.js default cutout). */
+export const Doughnut: S = {
+  args: {
+    config: {
+      type: 'doughnut',
+      labels: ['API', 'UI', 'E2E', 'Docs'],
+      datasets: [{ label: 'Cost', data: [40, 25, 20, 15], backgroundColor: [ACCENT, ACCENT_HI, DOING, INK3] }],
+    },
+  },
+};
+
+/** Radar — 2 multi-axis datasets (0.4 fill) + height 320 so the polygon breathes. */
+export const Radar: S = {
+  args: {
+    config: {
+      type: 'radar',
+      labels: ['BE', 'FE', 'E2E', 'Docs', 'DevOps'],
+      datasets: [
+        { label: 'Team A', data: [8, 9, 6, 4, 5], borderColor: ACCENT, backgroundColor: 'rgba(94,106,210,0.4)' },
+        { label: 'Team B', data: [5, 6, 8, 7, 6], borderColor: DONE, backgroundColor: 'rgba(63,185,80,0.4)' },
+      ],
+    },
+  },
+  render: (args) => <Chart {...args} height={320} />,
+};
+
+/** Mixed — bar + line on SHARED labels (per-dataset type override, chart.js v4). */
+export const Mixed: S = {
+  name: 'Mixed — bar + line on one axis',
+  args: {
+    config: {
+      type: 'bar',
+      labels: MONTHS,
+      datasets: [
+        { label: 'Tasks created', data: [12, 19, 3, 15, 9, 17], backgroundColor: ACCENT },
+        { label: 'Tasks deleted', data: [4, 3, 5, 2, 6, 3], backgroundColor: FAIL },
+        { type: 'line', label: 'End-of-period stock', data: [10, 22, 18, 28, 24, 35], borderColor: DOING },
+      ],
+    },
+  },
+};
+
+/** Colors custom — hand-set backgroundColor/borderColor via ChartDataset. */
+export const ColorsCustom: S = {
+  name: 'Colors — custom backgroundColor/borderColor',
+  args: {
+    config: {
+      type: 'bar',
+      labels: ['P0', 'P1', 'P2'],
+      datasets: [
+        {
+          label: 'Incidents',
+          data: [3, 7, 12],
+          backgroundColor: [FAIL, DOING, DONE],
+          borderColor: '#1f2328',
+          borderWidth: 2,
+        },
+      ],
+    },
+  },
+};
+
+/** Height — the `height` prop (px) controls the container height: 160 vs 400. */
+export const Height: S = {
+  name: 'Height — 160 vs 400',
+  args: { config: { type: 'bar', labels: [], datasets: [] } },
+  render: () => (
+    <div className="flex flex-wrap items-start gap-6">
+      <div className="w-[320px]">
+        <p className="m-0 mb-2 font-mono text-meta text-ink3">height=160</p>
+        <Chart
+          config={{ type: 'bar', labels: MONTHS, datasets: [{ label: 'Short', data: [5, 9, 7, 12, 14, 11], backgroundColor: ACCENT_HI }] }}
+          height={160}
+        />
+      </div>
+      <div className="w-[320px]">
+        <p className="m-0 mb-2 font-mono text-meta text-ink3">height=400</p>
+        <Chart
+          config={{ type: 'bar', labels: MONTHS, datasets: [{ label: 'Tall', data: [5, 9, 7, 12, 14, 11], backgroundColor: ACCENT }] }}
+          height={400}
+        />
+      </div>
+    </div>
+  ),
+};
+
+/** Options passthrough — config.options goes straight to chart.js: bottom legend + y beginAtZero. */
+export const OptionsPassthrough: S = {
+  name: 'Options — legend bottom + y beginAtZero',
+  args: {
+    config: {
+      type: 'bar',
+      labels: MONTHS,
+      datasets: [{ label: 'Orders', data: [0, 4, 9, 3, 12, 8], backgroundColor: DONE }],
+      options: {
+        plugins: { legend: { position: 'bottom' } },
+        scales: { y: { beginAtZero: true } },
+      },
+    },
+  },
+};
+
+/** Fallback — chart.js NOT installed / import error → fallback replaces the canvas.
+ * Walks the component's REAL failed path: unknown type + dataset → chart.js throws
+ * during controller lookup → `failed` → fallback renders (a dataset is needed to
+ * reach the controller lookup — unknown type alone is not enough). */
+export const Fallback: S = {
+  args: {
+    config: {
+      type: 'bogus',
+      labels: ['a'],
+      datasets: [{ label: 'x', data: [1] }],
+    } as unknown as ChartConfig,
+    fallback: (
+      <p className="m-0 grid place-items-center rounded-lg border border-dashed border-line p-6 text-meta text-ink3">
+        chart.js not installed / init error — this is the component's real fallback
+      </p>
+    ),
+  },
+};
+
+/** EmptyData — empty labels/datasets: canvas still mounts (a valid chart with no
+ * data yet); blank is CORRECT behavior — not a rendering bug. */
+export const EmptyData: S = {
+  args: { config: { type: 'line', labels: [], datasets: [] } },
+};
+
+/** DarkTheme — chart on a dark canvas (chart.js default grey legend/ticks stay legible).
+ * Dataset colors are the explicit demo palette — kept for both themes. */
+export const DarkTheme: S = {
+  name: 'Dark theme — doughnut on dark canvas',
+  args: {
+    config: {
+      type: 'doughnut',
+      labels: ['Todo', 'In progress', 'Done', 'Failed'],
+      datasets: [{ label: 'Tasks', data: [8, 5, 11, 2], backgroundColor: [INK3, DOING, DONE, FAIL] }],
+    },
+  },
+  render: (args) => (
+    <div data-bp-theme="dark" className="w-[420px] rounded-xl bg-canvas p-4">
+      <Chart {...args} height={280} />
+    </div>
+  ),
+};
+
+/** DarkToggleLive — useChartTheme resolves token colors inside the UiKitProvider
+ * scope; toggling re-resolves → config JSON changes → Chart re-inits with the new
+ * palette WITHOUT remount (F2: dark-toggle live, 0 extra props on Chart). */
+export const DarkToggleLive: S = {
+  // render demo tự quản config qua useChartTheme — args chỉ để thỏa config required
+  args: { config: { type: 'line', labels: [], datasets: [] } },
+  render: () => <ChartThemeDemo />,
+};
+
+const THEME_VARS = { accent: '--accent', done: '--st-done' } as const;
+const THEME_FALLBACK = { accent: '#1677ff', done: '#52c41a' };
+
+function ChartThemeDemo() {
+  const [dark, setDark] = useState(false);
+  const { ref, colors } = useChartTheme(THEME_VARS, THEME_FALLBACK);
+  const config = useMemo<ChartConfig>(
+    () => ({
+      type: 'line',
+      labels: MONTHS,
+      datasets: [
+        { label: 'Accent', data: [12, 19, 3, 15, 9, 17], borderColor: colors.accent, backgroundColor: colors.accent, borderWidth: 2 },
+        { label: 'Done', data: [7, 11, 5, 13, 8, 14], borderColor: colors.done, backgroundColor: colors.done, borderWidth: 2 },
+      ],
+      options: { responsive: true, maintainAspectRatio: false },
+    }),
+    [colors],
+  );
+  return (
+    <UiKitProvider theme={dark ? 'dark' : 'light'}>
+      {/* Probe token trong đúng scope theme — attr đổi trên wrapper provider nằm trong subtree body */}
+      <span ref={ref} aria-hidden="true" className="hidden" />
+      <div className="grid w-full max-w-2xl gap-3 rounded-xl bg-canvas p-4">
+        <Button className="w-fit" onClick={() => setDark((d) => !d)}>
+          {dark ? 'Switch to light' : 'Switch to dark'} (live)
+        </Button>
+        <Chart config={config} height={240} />
+        <p className="m-0 font-mono text-meta text-ink3">
+          resolved: accent <strong className="text-ink">{colors.accent}</strong> · done{' '}
+          <strong className="text-ink">{colors.done}</strong>
+        </p>
+      </div>
+    </UiKitProvider>
+  );
+}

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

@@ -0,0 +1,103 @@
+// Chart peer-dep — jsdom không có canvas 2D → test fallback + interop resolve + config
+// passthrough (mock Chart class bắt shape config thay vì đo pixel).
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Chart } from './index.js';
+afterEach(cleanup);
+
+const CONFIG = { type: 'bar' as const, labels: ['T1', 'T2'], datasets: [{ label: 'd', data: [1, 2] }] };
+
+describe('Chart', () => {
+  it('không fallback → render canvas', () => {
+    const { container } = render(<Chart config={{ type: 'bar', labels: [], datasets: [] }} />);
+    expect(container.querySelector('canvas')).toBeInTheDocument();
+  });
+
+  it('fallback CHỈ hiện khi import chart.js fail — truyền fallback không chặn canvas', async () => {
+    vi.doMock('chart.js/auto', () => Promise.reject(new Error('no chart.js')));
+    const { Chart: ChartMocked } = await import('./index.js');
+    render(<ChartMocked config={{ type: 'bar', labels: [], datasets: [] }} fallback={<p>No chart</p>} />);
+    await vi.waitFor(() => {
+      expect(screen.getByText('No chart')).toBeInTheDocument();
+    });
+    vi.doUnmock('chart.js/auto');
+  });
+
+  it('interop ESM thuần: named Chart export → resolve mod.Chart', async () => {
+    const ChartStub = vi.fn(() => ({ destroy: vi.fn() }));
+    vi.doMock('chart.js/auto', () =>
+      Promise.resolve({ Chart: ChartStub, default: ChartStub, __esModule: true }));
+    const { Chart: ChartMocked } = await import('./index.js');
+    render(<ChartMocked config={CONFIG} />);
+    await vi.waitFor(() => expect(ChartStub).toHaveBeenCalled());
+    vi.doUnmock('chart.js/auto');
+  });
+
+  it('interop default-only (một số bundler): mod.default là Chart class → vẫn vẽ', async () => {
+    const ChartStub = vi.fn(() => ({ destroy: vi.fn() }));
+    vi.doMock('chart.js/auto', () => Promise.resolve({ default: ChartStub, __esModule: true }));
+    const { Chart: ChartMocked } = await import('./index.js');
+    render(<ChartMocked config={CONFIG} />);
+    await vi.waitFor(() => expect(ChartStub).toHaveBeenCalled());
+    vi.doUnmock('chart.js/auto');
+  });
+
+  it('config wrap ĐÚNG shape chart.js v4: { type, data: { labels, datasets } } — gốc của bug "canvas mounted alpha=0"', async () => {
+    const ChartStub = vi.fn(() => ({ destroy: vi.fn() }));
+    vi.doMock('chart.js/auto', () => Promise.resolve({ Chart: ChartStub, __esModule: true }));
+    const { Chart: ChartMocked } = await import('./index.js');
+    render(<ChartMocked config={CONFIG} />);
+    await vi.waitFor(() => expect(ChartStub).toHaveBeenCalled());
+    // vi.fn() zero-param → mock.calls tuple rỗng về type; cast để đọc arg truyền vào
+    const cfg = (ChartStub.mock.calls[0] as unknown[] | undefined)?.[1];
+    expect(cfg).toMatchObject({ type: 'bar', data: { labels: ['T1', 'T2'], datasets: [{ label: 'd', data: [1, 2] }] } });
+    // labels/datasets KHÔNG còn nằm top-level (shape sai cũ)
+    expect(cfg).not.toHaveProperty('labels');
+    vi.doUnmock('chart.js/auto');
+  });
+
+  it('config native nested (data lồng) vẫn vẽ dữ liệu — app/admin pass-through', async () => {
+    const ChartStub = vi.fn(() => ({ destroy: vi.fn() }));
+    vi.doMock('chart.js/auto', () => Promise.resolve({ Chart: ChartStub, __esModule: true }));
+    const { Chart: ChartMocked } = await import('./index.js');
+    const NESTED = {
+      type: 'line' as const,
+      data: { labels: ['T2', 'T3'], datasets: [{ label: 'n', data: [3, 4] }] },
+    };
+    render(<ChartMocked config={NESTED} />);
+    await vi.waitFor(() => expect(ChartStub).toHaveBeenCalled());
+    const cfg = (ChartStub.mock.calls[0] as unknown[] | undefined)?.[1];
+    // nested vẫn resolve đủ → chart.js nhận labels/datasets trong `data` (không rỗng câm lặng)
+    expect(cfg).toMatchObject({ type: 'line', data: { labels: ['T2', 'T3'], datasets: [{ label: 'n', data: [3, 4] }] } });
+    vi.doUnmock('chart.js/auto');
+  });
+
+  it('Chart class không resolve được (module rỗng) → fallback, KHÔNG để canvas trắng câm lặng', async () => {
+    vi.doMock('chart.js/auto', () => Promise.resolve({}));
+    const { Chart: ChartMocked } = await import('./index.js');
+    render(<ChartMocked config={CONFIG} fallback={<p>Chart lỗi</p>} />);
+    await vi.waitFor(() => expect(screen.getByText('Chart lỗi')).toBeInTheDocument());
+    expect(screen.queryByRole('img')).toBeNull();
+    vi.doUnmock('chart.js/auto');
+  });
+
+  it('unmount → destroy() chart instance (không leak canvas)', async () => {
+    const destroy = vi.fn();
+    const ChartStub = vi.fn(() => ({ destroy }));
+    vi.doMock('chart.js/auto', () => Promise.resolve({ Chart: ChartStub, __esModule: true }));
+    const { Chart: ChartMocked } = await import('./index.js');
+    const { unmount } = render(<ChartMocked config={CONFIG} />);
+    await vi.waitFor(() => expect(ChartStub).toHaveBeenCalled());
+    unmount();
+    expect(destroy).toHaveBeenCalledTimes(1);
+    vi.doUnmock('chart.js/auto');
+  });
+
+  it('height prop → inline style container; className passthrough', () => {
+    const { container } = render(<Chart config={{ type: 'bar', labels: [], datasets: [] }} height={180} className="marker" />);
+    const wrapper = container.firstElementChild as HTMLElement;
+    expect(wrapper.style.height).toBe('180px');
+    expect(wrapper).toHaveClass('marker');
+    expect(wrapper.querySelector('canvas')).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,172 @@
+// Chart — PEER-DEP pattern: chart.js lazy import (consumer tự cài — pnpm add chart.js).
+// Fix 2026-10-18 (user "docs empty"): (1) fallback giờ chỉ hiện khi import THẤT BẠI
+// (trước đây cứ truyền prop fallback là không bao giờ render canvas); (2) config so
+// theo JSON (useMemo) — hết destroy/re-create loop mỗi re-render của docs; (3) canvas
+// nằm trong container có height chuẩn (default 260px) — chart.js responsive khỏi init 0×0.
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode, type RefObject } from 'react';
+
+export interface ChartDataset {
+  label: string;
+  data: number[];
+  /** Màu nền dataset (bar/area) hoặc từng slice (pie/doughnut — truyền mảng cùng độ dài labels). */
+  backgroundColor?: string | string[];
+  /** Màu viền dataset. */
+  borderColor?: string | string[];
+  /** Độ dày viền (px) — demo Colors custom. */
+  borderWidth?: number;
+  /** Override type PER-DATASET cho mixed chart (vd bar + line cùng trục — chart.js v4). */
+  type?: 'bar' | 'line';
+  /** Passthrough tuỳ chọn chart.js v4 khác (tension, fill, pointRadius…) —
+   * surface options quá rộng để liệt kê hết; đánh đổi: typo không bắt tại type. */
+  [key: string]: unknown;
+}
+
+export interface ChartConfig {
+  type: 'bar' | 'line' | 'pie' | 'doughnut' | 'radar';
+  /** Shape FLAT (chuẩn kit — khuyến nghị): labels/datasets top-level. */
+  labels?: string[];
+  datasets?: ChartDataset[];
+  /** Shape NATIVE chart.js v4 (nested) — Chart chấp nhận CẢ HAI (fix 2026-10-24:
+   * app/admin truyền native rồi mà component chỉ đọc flat → chart rỗng câm lặng).
+   * Resolve: flat trước, rơi về `data.*` khi flat thiếu. */
+  data?: {
+    labels?: string[];
+    datasets?: ChartDataset[];
+  };
+  options?: Record<string, unknown>;
+}
+
+export interface ChartProps {
+  config: ChartConfig;
+  /** Chiều cao container (px) — mặc định 260. */
+  height?: number;
+  className?: string;
+  /** Hiện khi chart.js chưa cài/import lỗi (chỉ lúc đó mới dùng). */
+  fallback?: ReactNode;
+}
+
+/**
+ * Đọc export từ module/lazy-namespace MỘT CÁCH AN TOÀN: vitest mock namespace THẮ
+ * Error khi truy cập export không định nghĩa ("No X export is defined on the mock")
+ * thay vì trả undefined — probe bọc try/catch để chain resolve không vỡ trong test,
+ * còn trên bundler thật (ESM không có export) chỉ là undefined tự nhiên.
+ */
+function safeGet(obj: unknown, key: string): unknown {
+  try {
+    return (obj as Record<string, unknown>)?.[key];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * useChartTheme — resolve token màu cho chart canvas theo scope theme bao ngoài
+ * (gắn `ref` vào 1 probe span trong đúng scope) + TỰ re-resolve khi theme đổi
+ * (attr data-bp-theme/class/style trên <html> hoặc subtree body — MutationObserver,
+ * cover cả wrapper div của UiKitProvider). Chart tự re-init khi config JSON đổi →
+ * combo này cho dark-toggle LIVE mà KHÔNG cần prop mới trên Chart (F2 2026-10-18).
+ * jsdom/unit test không áp CSS → trả `fallback` cho tới khi token có giá trị thật.
+ * Truyền `vars`/`fallback` là const ngoài component (deps theo identity).
+ */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useChartTheme<T extends Record<string, string>>(
+  vars: T,
+  fallback: { [K in keyof T]: string },
+): { ref: RefObject<HTMLSpanElement | null>; colors: { [K in keyof T]: string } } {
+  const ref = useRef<HTMLSpanElement>(null);
+  const [colors, setColors] = useState(fallback);
+  const colorsRef = useRef(colors);
+  colorsRef.current = colors;
+  useLayoutEffect(() => {
+    const resolve = () => {
+      const el = ref.current;
+      if (!el) return;
+      const cs = getComputedStyle(el);
+      let next: { [K in keyof T]: string } | null = null;
+      for (const key of Object.keys(vars) as (keyof T & string)[]) {
+        const value = cs.getPropertyValue(vars[key]).trim();
+        if (value && value !== colorsRef.current[key]) {
+          next ??= { ...colorsRef.current };
+          next[key] = value;
+        }
+      }
+      if (next) setColors(next);
+    };
+    resolve();
+    if (typeof MutationObserver === 'undefined') return undefined;
+    const filter = ['data-bp-theme', 'class', 'style'];
+    const mo = new MutationObserver(resolve);
+    mo.observe(document.documentElement, { attributes: true, attributeFilter: filter });
+    mo.observe(document.body, { attributes: true, attributeFilter: filter, subtree: true });
+    return () => mo.disconnect();
+  }, [vars, fallback]);
+  return { ref, colors };
+}
+
+export function Chart({ config, height = 260, className, fallback }: ChartProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const chartRef = useRef<unknown>(null);
+  const [failed, setFailed] = useState(false);
+
+  // JSON-stable: tránh re-create chart khi parent re-render với object config mới-chứa-nội-dung-cũ
+  const stableConfig = useMemo(() => config, [JSON.stringify(config)]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    if (failed) return;
+    let cancelled = false;
+    let chart: unknown = null;
+    (async () => {
+      try {
+        // Peer-dep lazy (consumer tự cài chart.js) — import qua cast thủ công.
+        const CHARTJS_AUTO = 'chart.js/auto';
+        // specifier qua BIẾN: bundler consumer không phân tích được dynamic import
+        // peer khi build production (comment @vite-ignore bị esbuild strip khỏi dist)
+        const mod = (await import(CHARTJS_AUTO)) as unknown;
+        // Robust interop: ESM thuần có named Chart; một số bundler/interop chỉ trả
+        // default. Resolve theo thứ tự — không khớp cái nào → throw (hiện fallback
+        // thay vì canvas trắng câm lặng).
+        const dflt = safeGet(mod, 'default');
+        const Ctor = safeGet(mod, 'Chart') ?? safeGet(dflt, 'Chart') ?? dflt;
+        if (cancelled || !canvasRef.current) return;
+        if (typeof Ctor !== 'function') {
+          throw new Error('chart.js/auto: không resolve được Chart class');
+        }
+        // Shape chart.js v4: { type, data: { labels, datasets }, options } — NHẤT QUÁN
+        // wrap `data`. (Bug "canvas mounted mà alpha=0": labels/datasets truyền
+        // top-level → chart init/resize OK nhưng data rỗng → không vẽ, 0 lỗi console.)
+        // Fix 2026-10-24 (admin Dashboard chart trống): consumer có thể truyền FLAT
+        // (chuẩn kit) lẫn NESTED (native chart.js) — resolve cả 2, flat ưu tiên.
+        const src = stableConfig as {
+          labels?: string[];
+          datasets?: ChartDataset[];
+          data?: { labels?: string[]; datasets?: ChartDataset[] };
+        };
+        const labels = src.labels ?? src.data?.labels;
+        const datasets = src.datasets ?? src.data?.datasets;
+        chart = new (Ctor as new (...args: unknown[]) => unknown)(canvasRef.current, {
+          type: stableConfig.type,
+          data: { labels, datasets },
+          options: { responsive: true, maintainAspectRatio: false, ...(stableConfig.options ?? {}) },
+        });
+        chartRef.current = chart;
+      } catch (err) {
+        console.warn('[ui-kit] chart.js import/init lỗi:', err);
+        if (!cancelled) setFailed(true);
+      }
+    })();
+    return () => {
+      cancelled = true;
+      if (chart) (chart as { destroy(): void }).destroy();
+      if (chartRef.current === chart) chartRef.current = null;
+    };
+  }, [stableConfig, failed]);
+
+  if (failed && fallback !== undefined) return <>{fallback}</>;
+  if (failed) return <div style={{ height }} className={`grid place-items-center rounded-lg border border-dashed border-line text-label text-ink3${className ? ` ${className}` : ''}`}>chart.js chưa cài — pnpm add chart.js</div>;
+
+  return (
+    <div style={{ height, position: 'relative' }} className={className}>
+      <canvas ref={canvasRef} style={{ maxWidth: '100%' }} />
+    </div>
+  );
+}

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

@@ -0,0 +1,67 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Checkbox } from './index';
+const meta = { title: 'Forms/Checkbox', component: Checkbox, tags: ['autodocs'] } satisfies Meta<typeof Checkbox>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+/** Basic — unchecked. */
+export const Basic: S = { args: { children: 'Remember me' } };
+
+/** Group — multi-pick column of checkboxes (antd Checkbox.Group pattern, consumer-side). */
+export const Group: S = {
+  name: 'Group — multi-pick (consumer-side state)',
+  render: () => <CheckboxGroupDemo />,
+};
+
+/** Checked — pressed state. */
+export const Checked: S = { args: { checked: true, children: 'Selected' } };
+
+/** Disabled — locked, dimmed. */
+export const Disabled: S = { args: { disabled: true, children: 'Cannot check' } };
+
+/** Controlled — useState demo: click label flips checked. */
+export const Controlled: S = {
+  render: () => <CheckboxControlledDemo />,
+};
+
+/** DarkTheme — both states on dark canvas. */
+export const DarkTheme: S = {
+  render: () => (
+    <div data-bp-theme="dark" className="grid w-[280px] gap-3 rounded-xl bg-canvas p-4">
+      <Checkbox>Remember me</Checkbox>
+      <Checkbox checked>Selected</Checkbox>
+      <Checkbox disabled>Cannot check</Checkbox>
+    </div>
+  ),
+};
+
+const STACKS = ['React', 'TypeScript', 'Rust'];
+
+function CheckboxGroupDemo() {
+  const [picked, setPicked] = useState<string[]>(['React']);
+  const toggle = (name: string) =>
+    setPicked((prev) => (prev.includes(name) ? prev.filter((n) => n !== name) : [...prev, name]));
+  return (
+    <div className="grid max-w-[320px] gap-3">
+      <div role="group" aria-label="Stacks" className="grid gap-2">
+        {STACKS.map((name) => (
+          <Checkbox key={name} checked={picked.includes(name)} onChange={() => toggle(name)}>
+            {name}
+          </Checkbox>
+        ))}
+      </div>
+      <p className="m-0 font-mono text-meta text-ink3">picked: <strong className="text-ink">{JSON.stringify(picked)}</strong></p>
+    </div>
+  );
+}
+
+function CheckboxControlledDemo() {
+  const [on, setOn] = useState(false);
+  return (
+    <div className="grid max-w-[320px] gap-3">
+      <Checkbox checked={on} onChange={setOn}>Enable autosave</Checkbox>
+      <p className="m-0 font-mono text-meta text-ink3">checked: <strong className="text-ink">{String(on)}</strong></p>
+    </div>
+  );
+}