create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/app/ui-kit/src/ui/team/stage-pipeline/index.tsx

@@ -0,0 +1,60 @@
+// StagePipeline — pipeline các stage của đội: mũi tên nối + state màu token
+// (pending=ink3 · running=accent pulse · gated=st-doing + gate icon · done=st-done)
+// + aria-current="step" cho stage đang chạy. Depth: ele-1 panel + ease-smooth.
+import { Icon } from '../../icons/index.js';
+
+export type StageState = 'pending' | 'running' | 'gated' | 'done';
+
+export interface PipelineStage {
+  key: string;
+  label: string;
+  state: StageState;
+}
+
+export interface StagePipelineProps {
+  stages: PipelineStage[];
+  /** Hướng ngang (mặc định) hay dọc. */
+  direction?: 'horizontal' | 'vertical';
+  className?: string;
+}
+
+const STATE_CLS: Record<StageState, { chip: string; icon: string; iconCls: string }> = {
+  pending: { chip: 'border-line bg-s1 text-ink3', icon: 'clock', iconCls: 'text-ink3' },
+  running: { chip: 'border-accent bg-accent/10 text-accent', icon: 'refresh', iconCls: 'text-accent animate-[bp-pulse-soft_1.6s_ease-in-out_infinite]' },
+  gated: { chip: 'border-st-doing bg-st-doing/10 text-st-doing', icon: 'exclamation-triangle', iconCls: 'text-st-doing' },
+  done: { chip: 'border-st-done bg-st-done/10 text-st-done', icon: 'check', iconCls: 'text-st-done' },
+};
+
+export function StagePipeline({ stages, direction = 'horizontal', className }: StagePipelineProps) {
+  const vertical = direction === 'vertical';
+  return (
+    <ol
+      aria-label="Team pipeline"
+      className={`m-0 flex list-none p-0 ${vertical ? 'flex-col gap-2' : 'flex-wrap items-center gap-2'}${
+        className ? ` ${className}` : ''
+      }`}
+    >
+      {stages.map((s, i) => {
+        const meta = STATE_CLS[s.state];
+        const isCurrent = s.state === 'running' || s.state === 'gated';
+        return (
+          <li key={s.key} className="flex items-center gap-2" aria-current={isCurrent ? 'step' : undefined}>
+            <span
+              className={`inline-flex items-center gap-2 rounded-pill border px-3 py-1.5 text-label font-semibold shadow-[var(--ele-1)] transition-[box-shadow] duration-[240ms] ease-[var(--ease-smooth)] hover:shadow-[var(--ele-2)] ${meta.chip}`}
+            >
+              <span aria-hidden="true" className="font-mono text-[10px] opacity-70">
+                {String(i + 1).padStart(2, '0')}
+              </span>
+              {s.label}
+              <Icon aria-hidden={true} name={meta.icon as never} size={12} className={meta.iconCls} />
+              {s.state === 'gated' && <span className="sr-only">(gate — chờ duyệt)</span>}
+            </span>
+            {!vertical && i < stages.length - 1 && (
+              <Icon aria-hidden={true} name="arrow-right" size={12} className="shrink-0 text-ink3" />
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/stack-template/app/ui-kit/src/ui/team/stage-pipeline/stage-pipeline.stories.tsx

@@ -0,0 +1,68 @@
+// StagePipeline stories — team pipeline với gate + aria-current step.
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { StagePipeline } from './index';
+
+/** Pipeline stages nối mũi tên, state màu token. */
+const meta = { title: 'Domain/StagePipeline', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+/** Basic — full pipeline với running + gated giữa đường. */
+export const Basic: S = {
+  render: () => (
+    <StagePipeline
+      stages={[
+        { key: 'baseline', label: 'Baseline', state: 'done' },
+        { key: 'depth', label: 'Depth pass', state: 'running' },
+        { key: 'review', label: 'Gate review', state: 'gated' },
+        { key: 'ship', label: 'Ship', state: 'pending' },
+      ]}
+    />
+  ),
+};
+
+/** AllDone — mọi stage done (không aria-current). */
+export const AllDone: S = {
+  name: 'All done — pipeline hoàn tất',
+  render: () => (
+    <StagePipeline
+      stages={[
+        { key: 'brief', label: 'Brief', state: 'done' },
+        { key: 'code', label: 'Code', state: 'done' },
+        { key: 'verify', label: 'Verify', state: 'done' },
+      ]}
+    />
+  ),
+};
+
+/** Vertical — direction="vertical" cho sidebar hẹp. */
+export const Vertical: S = {
+  name: 'Vertical — sidebar layout',
+  render: () => (
+    <StagePipeline
+      direction="vertical"
+      stages={[
+        { key: 'baseline', label: 'Baseline', state: 'done' },
+        { key: 'apply', label: 'Áp depth', state: 'running' },
+        { key: 'gate', label: 'Gate', state: 'gated' },
+        { key: 'after', label: 'After-shot', state: 'pending' },
+      ]}
+    />
+  ),
+};
+
+/** DarkTheme — chip màu token trên dark canvas. */
+export const DarkTheme: S = {
+  name: 'Dark theme',
+  render: () => (
+    <div data-bp-theme="dark" className="p-3">
+      <StagePipeline
+        stages={[
+          { key: 'sweep', label: 'Sweep', state: 'done' },
+          { key: 'fix', label: 'Fix', state: 'running' },
+          { key: 'gate', label: 'Gate', state: 'pending' },
+        ]}
+      />
+    </div>
+  ),
+};

package/stack-template/app/ui-kit/src/ui/team/stage-pipeline/stage-pipeline.test.tsx

@@ -0,0 +1,50 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { StagePipeline } from './index.js';
+
+afterEach(cleanup);
+
+const STAGES = [
+  { key: 'baseline', label: 'Baseline', state: 'done' as const },
+  { key: 'apply', label: 'Áp depth', state: 'running' as const },
+  { key: 'review', label: 'Review', state: 'gated' as const },
+  { key: 'ship', label: 'Ship', state: 'pending' as const },
+];
+
+describe('StagePipeline', () => {
+  it('render đủ stages theo thứ tự + số thứ tự mono', () => {
+    render(<StagePipeline stages={STAGES} />);
+    expect(screen.getByText('Baseline')).toBeInTheDocument();
+    expect(screen.getByText('Áp depth')).toBeInTheDocument();
+    expect(screen.getByText('Ship')).toBeInTheDocument();
+    expect(screen.getByText('01')).toBeInTheDocument();
+    expect(screen.getByText('04')).toBeInTheDocument();
+  });
+
+  it('running/gated → aria-current="step"; pending/done không', () => {
+    render(<StagePipeline stages={STAGES} />);
+    expect(screen.getByText('Áp depth').closest('li')).toHaveAttribute('aria-current', 'step');
+    expect(screen.getByText('Review').closest('li')).toHaveAttribute('aria-current', 'step');
+    expect(screen.getByText('Baseline').closest('li')).not.toHaveAttribute('aria-current');
+  });
+
+  it('state màu token: done chip st-done, gated chip st-doing', () => {
+    render(<StagePipeline stages={STAGES} />);
+    expect(screen.getByText('Baseline').closest('span')).toHaveClass('text-st-done');
+    expect(screen.getByText('Review').closest('span')).toHaveClass('text-st-doing');
+  });
+
+  it('mũi tên nối = stages-1 (ngang); dọc không có mũi tên ngang', () => {
+    const { container, rerender } = render(<StagePipeline stages={STAGES} />);
+    const arrows = container.querySelectorAll('[aria-label="Team pipeline"] svg');
+    // mỗi stage 1 icon + (stages-1) arrow → tổng = stages*2 - 1
+    expect(arrows.length).toBe(STAGES.length * 2 - 1);
+    rerender(<StagePipeline stages={STAGES} direction="vertical" />);
+    expect(container.querySelectorAll('ol svg').length).toBe(STAGES.length);
+  });
+
+  it('gated stage có mô tả gate cho screen reader', () => {
+    render(<StagePipeline stages={STAGES} />);
+    expect(screen.getByText('(gate — chờ duyệt)')).toHaveClass('sr-only');
+  });
+});

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

@@ -0,0 +1,103 @@
+// TeamDashboard — layout compose sẵn (Team-OS): header Statistic band
+// (agents-busy · tests-green · debts-open) + PingFeed + StagePipeline 2 cột
+// responsive (feed trái rộng, pipeline + debt phải; <lg xếp dọc).
+// Depth: các panel con tự mang ele-1/wash — dashboard chỉ lo grid + gap chuẩn.
+import type { ReactNode } from 'react';
+import { Icon } from '../../icons/index.js';
+import { DebtBoard, type DebtItem } from '../debt-board/index';
+import { PingFeed, type PingEvent } from '../ping-feed/index';
+import { StagePipeline, type PipelineStage } from '../stage-pipeline/index';
+import { Statistic } from '../../statistic/index';
+
+export interface TeamStats {
+  /** Agent đang bận task. */
+  agentsBusy: number;
+  /** Tổng agents trong team (mốc để tính busy ratio). */
+  agentsTotal: number;
+  /** % test suite xanh (0–100). */
+  testsGreen: number;
+  /** Số debt đang mở. */
+  debtsOpen: number;
+}
+
+export interface TeamDashboardProps {
+  stats: TeamStats;
+  events: PingEvent[];
+  stages: PipelineStage[];
+  debts: DebtItem[];
+  /** Chiều sâu queue phân công (R0.1) — truyền để DebtBoard hiện cột Queue. */
+  queueDepth?: number;
+  /** Node phụ chú thêm dưới band (vd ghi chú chu kỳ). */
+  footnote?: ReactNode;
+  className?: string;
+}
+
+export function TeamDashboard({ stats, events, stages, debts, queueDepth, footnote, className }: TeamDashboardProps) {
+  // R0.1 "KHÔNG NGHỈ" thành feature: agent idle MÀ còn debts mở → đỏ + pulse + alert.
+  const idle = Math.max(0, stats.agentsTotal - stats.agentsBusy);
+  const idleAlert = idle > 0 && stats.debtsOpen > 0;
+  return (
+    <div className={`flex flex-col gap-6${className ? ` ${className}` : ''}`}>
+      {/* Statistic band — 3 KPI (R11: số to tabular, label uppercase) */}
+      <section
+        aria-label="Team stats"
+        className="grid grid-cols-1 gap-4 rounded-xl border border-line bg-s1 p-5 shadow-[var(--ele-1)] [background-image:var(--wash)] sm:grid-cols-3 transition-[box-shadow] duration-[240ms] ease-[var(--ease-smooth)] hover:shadow-[var(--ele-2)]"
+      >
+        <Statistic
+          title={
+            <span className="inline-flex items-center gap-1.5 text-[11px] font-bold tracking-[2.64px] text-ink3 uppercase">
+              Agents busy
+              {idleAlert && (
+                <span
+                  aria-hidden="true"
+                  className="size-1.5 animate-[bp-pulse-soft_1.6s_ease-in-out_infinite] rounded-pill bg-st-fail"
+                />
+              )}
+            </span>
+          }
+          value={
+            <span className="inline-flex items-center gap-2 tabular-nums">
+              {stats.agentsBusy}
+              {idleAlert && <Icon aria-hidden={true} name="exclamation-triangle" size={14} />}
+            </span>
+          }
+          suffix={`/${stats.agentsTotal}`}
+          valueStyle={{ color: idleAlert ? 'var(--st-fail)' : 'var(--ink)' }}
+        />
+        <Statistic
+          title={<span className="text-[11px] font-bold tracking-[2.64px] text-ink3 uppercase">Tests green</span>}
+          value={<span className="tabular-nums">{stats.testsGreen}</span>}
+          suffix="%"
+          valueStyle={{ color: stats.testsGreen >= 90 ? 'var(--st-done)' : 'var(--st-doing)' }}
+        />
+        <Statistic
+          title={<span className="text-[11px] font-bold tracking-[2.64px] text-ink3 uppercase">Debts open</span>}
+          value={<span className="tabular-nums">{stats.debtsOpen}</span>}
+          valueStyle={{ color: stats.debtsOpen === 0 ? 'var(--st-done)' : 'var(--st-doing)' }}
+        />
+        {idleAlert && (
+          <p
+            role="status"
+            className="m-0 flex items-center gap-2 rounded-lg bg-st-fail/10 px-3 py-1.5 text-label font-semibold text-st-fail sm:col-span-3"
+          >
+            <Icon aria-hidden={true} name="exclamation-triangle" size={12} />
+            {idle} agent idle while {stats.debtsOpen} debts open — phân công lại theo R0.1.
+          </p>
+        )}
+        {footnote && <p className="m-0 self-end text-meta text-ink3 sm:col-span-3">{footnote}</p>}
+      </section>
+
+      {/* 2 cột responsive: feed trái (rộng) · pipeline + debt phải */}
+      <div className="grid items-start gap-6 lg:grid-cols-[1.4fr_1fr]">
+        <PingFeed events={events} title="Team ping" />
+        <div className="flex flex-col gap-6">
+          <section aria-label="Stage pipeline" className="rounded-xl border border-line bg-s1 p-4 shadow-[var(--ele-1)] [background-image:var(--wash)] transition-[box-shadow] duration-[240ms] ease-[var(--ease-smooth)] hover:shadow-[var(--ele-2)]">
+            <h2 className="m-0 mb-3 text-[12px] font-bold uppercase tracking-[2.4px] text-ink">Pipeline</h2>
+            <StagePipeline stages={stages} direction="vertical" />
+          </section>
+          <DebtBoard debts={debts} queueDepth={queueDepth} agentsIdle={idle} />
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,72 @@
+// TeamDashboard stories — layout compose Team-OS (stats band + feed + pipeline + debt).
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { TeamDashboard } from './index';
+
+const meta = { title: 'Domain/TeamDashboard', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+const NOW = Date.now();
+const at = (min: number) => new Date(NOW - min * 60000);
+
+/** Basic — dashboard đầy đủ + R0.1 idle-alert (2 agent idle trong khi 2 debts mở). */
+export const Basic: S = {
+  render: () => (
+    <TeamDashboard
+      stats={{ agentsBusy: 5, agentsTotal: 7, testsGreen: 96, debtsOpen: 2 }}
+      queueDepth={0}
+      events={[
+        { at: at(2), actor: 'V1', kind: 'report', text: 'Depth baseline 14 grid chụp xong.' },
+        { at: at(18), actor: 'V2', kind: 'start', text: 'Depth wave 2 — 6 component.' },
+        { at: at(41), actor: 'W6', kind: 'milestone', text: 'Team-OS 5 comp gate 23/23.' },
+        { at: at(52), actor: 'D', kind: 'idle-alert', text: 'Idle 20 phút — cần phân công.' },
+        { at: at(70), actor: 'W8', kind: 'blocked', text: 'Chart legend color theo token — chờ probe.' },
+      ]}
+      stages={[
+        { key: 'baseline', label: 'Baseline', state: 'done' },
+        { key: 'depth', label: 'Depth pass', state: 'running' },
+        { key: 'after', label: 'After-shot', state: 'pending' },
+      ]}
+      debts={[
+        { item: 'Descriptions dd min-w-0', owner: 'd', status: 'open' },
+        { item: 'Landing spark fill TS', owner: 'v2', status: 'fixed' },
+      ]}
+      footnote="Chu kỳ ACK 30s · standup mỗi 30 phút — RULES R4/R8."
+    />
+  ),
+};
+
+/** AllClear — mọi chỉ xanh: debts 0, tests 100, không blocked event. */
+export const AllClear: S = {
+  name: 'All clear — KPI xanh toàn bộ',
+  render: () => (
+    <TeamDashboard
+      stats={{ agentsBusy: 2, agentsTotal: 7, testsGreen: 100, debtsOpen: 0 }}
+      events={[{ at: at(4), actor: 'D', kind: 'milestone', text: 'Gate pass — không debt mở.' }]}
+      stages={[
+        { key: 'depth', label: 'Depth pass', state: 'done' },
+        { key: 'gate', label: 'Gate', state: 'done' },
+      ]}
+      debts={[]}
+    />
+  ),
+};
+
+/** DarkTheme — toàn bộ cascade token trên dark canvas. */
+export const DarkTheme: S = {
+  name: 'Dark theme',
+  render: () => (
+    <div data-bp-theme="dark" className="p-3">
+      <TeamDashboard
+        stats={{ agentsBusy: 6, agentsTotal: 7, testsGreen: 88, debtsOpen: 4 }}
+        events={[{ at: at(6), actor: 'V2', kind: 'start', text: 'Depth wave 2 — night mode.' }]}
+        stages={[
+          { key: 'wave1', label: 'Wave 1', state: 'done' },
+          { key: 'wave2', label: 'Wave 2', state: 'running' },
+          { key: 'gate', label: 'Gate', state: 'pending' },
+        ]}
+        debts={[{ item: 'Contrast sweep sót tooltip', owner: 'w8', status: 'open' }]}
+      />
+    </div>
+  ),
+};

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

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { TeamDashboard } from './index.js';
+
+afterEach(cleanup);
+
+const PROPS = {
+  stats: { agentsBusy: 5, agentsTotal: 7, testsGreen: 96, debtsOpen: 3 },
+  events: [{ at: new Date(Date.now() - 60000), actor: 'V1', kind: 'milestone' as const, text: 'gate cross' }],
+  stages: [
+    { key: 'a', label: 'Baseline', state: 'done' as const },
+    { key: 'b', label: 'Depth', state: 'running' as const },
+  ],
+  debts: [{ item: 'hex cứng', owner: 'v1', status: 'open' as const }],
+};
+
+describe('TeamDashboard', () => {
+  it('band 3 Statistic: agents-busy · tests-green · debts-open đúng số', () => {
+    render(<TeamDashboard {...PROPS} />);
+    expect(screen.getByText('5')).toBeInTheDocument();
+    expect(screen.getByText('/7')).toBeInTheDocument();
+    expect(screen.getAllByText('96').length).toBeGreaterThan(0);
+    expect(screen.getByText('3')).toBeInTheDocument();
+    expect(screen.getByText('Agents busy')).toBeInTheDocument();
+    expect(screen.getByText('Debts open')).toBeInTheDocument();
+  });
+
+  it('màu KPI theo ngưỡng: tests ≥90 → st-done; debts >0 → st-doing', () => {
+    render(<TeamDashboard {...PROPS} />);
+    const green = (screen.getByText('96').closest('span[style]') || screen.getByText('96')) as HTMLElement;
+    expect(green.style.color).toContain('--st-done');
+    const debts = screen.getByText('3').parentElement as HTMLElement;
+    expect(debts.style.color).toContain('--st-doing');
+  });
+
+  it('compose PingFeed + StagePipeline + DebtBoard trong 1 layout', () => {
+    render(<TeamDashboard {...PROPS} />);
+    expect(screen.getByText('Team ping')).toBeInTheDocument();
+    expect(screen.getByText('Pipeline')).toBeInTheDocument();
+    expect(screen.getByText('Debt board — R10')).toBeInTheDocument();
+    expect(screen.getByText('gate cross')).toBeInTheDocument();
+    expect(screen.getByText('Depth')).toBeInTheDocument();
+    expect(screen.getByText('hex cứng')).toBeInTheDocument();
+  });
+
+  it('footnote render khi truyền', () => {
+    render(<TeamDashboard {...PROPS} footnote="Chu kỳ ACK 30s — standup mỗi 30 phút." />);
+    expect(screen.getByText('Chu kỳ ACK 30s — standup mỗi 30 phút.')).toBeInTheDocument();
+  });
+});
+
+describe('TeamDashboard — R0.1 idle-alert', () => {
+  it('idle>0 + debts>0 → số agents busy đỏ + Alert "idle while debts open"', () => {
+    render(<TeamDashboard {...PROPS} />);
+    const busy = screen.getByText('5').parentElement as HTMLElement;
+    expect(busy.style.color).toContain('--st-fail');
+    expect(screen.getByText(/agent idle while/)).toBeInTheDocument();
+  });
+
+  it('debts=0 → không alert dù có idle', () => {
+    render(
+      <TeamDashboard
+        stats={{ agentsBusy: 2, agentsTotal: 7, testsGreen: 100, debtsOpen: 0 }}
+        events={[]}
+        stages={[]}
+        debts={[]}
+      />,
+    );
+    expect(screen.queryByRole('status')).toBeNull();
+    expect(screen.getByText('2').style.color).not.toContain('--st-fail');
+  });
+});

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

@@ -0,0 +1,143 @@
+// TimePicker (batch ⑧ worker C) — input giờ HH:mm + dropdown panel: stepper
+// tăng/giảm từng trường (Giờ/Phút) + nút nhanh "Bây giờ". Value nhận Date|string
+// ('HH:mm'); onChange luôn phát Date — GIỮ phần ngày khi input là Date, ngày
+// 1970-01-01 khi input là string (time thuần). Panel portal giống DatePicker.
+// Design: trigger theo pattern Input (border-line, focus accent, rounded-lg h-8),
+// panel bg-s2 border shadow-pop, nút nhanh active bg-accent text-white.
+import { useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Icon } from '../icons/index.js';
+import { useDateLocale, type DateLocaleInput } from '../date-picker/locale.js';
+
+export interface TimeParts {
+  h: number;
+  m: number;
+}
+
+export interface TimeSpinnerProps {
+  value: TimeParts;
+  onChange: (t: TimeParts) => void;
+  /** 'vi' | 'en' | DateLocale — thắng DateLocaleProvider context; default vi. */
+  locale?: DateLocaleInput;
+}
+
+const pad = (n: number) => n.toString().padStart(2, '0');
+
+const STEP_BTN =
+  'grid size-5 cursor-pointer place-items-center rounded-1 border border-line bg-transparent text-meta text-ink3 transition-colors duration-200 ease-[var(--ease-smooth)] hover:border-ink/20 hover:text-accent';
+
+/** Nhóm stepper Giờ/Phút dùng chung cho TimePicker panel + cột showTime của DatePicker. */
+export function TimeSpinner({ value, onChange, locale }: TimeSpinnerProps) {
+  const loc = useDateLocale(locale);
+  const set = (part: 'h' | 'm', delta: number) => {
+    if (part === 'h') onChange({ ...value, h: (value.h + delta + 24) % 24 });
+    else onChange({ ...value, m: (value.m + delta + 60) % 60 });
+  };
+  const row = (part: 'h' | 'm', label: string, val: number) => (
+    <div className="flex items-center justify-between gap-3">
+      <span className="text-meta text-ink3">{label}</span>
+      <span className="flex items-center gap-1.5">
+        <button type="button" aria-label={`${loc.decrease} ${label.toLowerCase()}`} className={STEP_BTN}
+          onClick={() => set(part, -1)}><Icon name="minus" size={12} /></button>
+        {/* Counter pulse khi đổi giá trị (depth contract — remount theo key, slide-up mềm) */}
+        <span
+          key={val}
+          aria-label={label}
+          className="min-w-[2.5rem] text-center text-body font-medium text-ink tabular-nums animate-[bp-slide-up-in_200ms_var(--ease-smooth)]"
+        >
+          {pad(val)}
+        </span>
+        <button type="button" aria-label={`${loc.increase} ${label.toLowerCase()}`} className={STEP_BTN}
+          onClick={() => set(part, 1)}><Icon name="plus" size={12} /></button>
+      </span>
+    </div>
+  );
+  return (
+    <div className="grid gap-2">
+      {row('h', loc.hour, value.h)}
+      {row('m', loc.minute, value.m)}
+    </div>
+  );
+}
+
+export interface TimePickerProps {
+  /** Date (giữ phần ngày khi phát onChange) hoặc string 'HH:mm'. */
+  value?: Date | string;
+  onChange?: (time: Date) => void;
+  placeholder?: string;
+  disabled?: boolean;
+  locale?: DateLocaleInput;
+  /** Mốc "bây giờ" — inject được để test deterministic. */
+  now?: Date;
+  className?: string;
+}
+
+function parseValue(value: Date | string | undefined): TimeParts {
+  if (value instanceof Date) return { h: value.getHours(), m: value.getMinutes() };
+  const match = /^(\d{1,2}):(\d{2})$/.exec(value ?? '');
+  return match ? { h: Number(match[1]), m: Number(match[2]) } : { h: 0, m: 0 };
+}
+
+export function TimePicker({
+  value,
+  onChange,
+  placeholder = 'HH:mm',
+  disabled = false,
+  locale,
+  now = new Date(),
+  className,
+}: TimePickerProps) {
+  const loc = useDateLocale(locale);
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLSpanElement>(null);
+  const parts = parseValue(value);
+
+  // emit — giữ hành vi date-part của value gốc cho stepper + nút Now
+  const emit = (t: TimeParts): Date => {
+    if (value instanceof Date) return new Date(value.getFullYear(), value.getMonth(), value.getDate(), t.h, t.m);
+    return new Date(1970, 0, 1, t.h, t.m);
+  };
+
+  const ariaLabel = value !== undefined ? `${loc.timeValuePrefix} ${pad(parts.h)}:${pad(parts.m)}` : loc.timeTriggerLabel;
+
+  return (
+    <span ref={ref} className={`relative inline-flex${className ? ` ${className}` : ''}`}>
+      <button
+        type="button"
+        aria-label={ariaLabel}
+        aria-expanded={open}
+        disabled={disabled}
+        onClick={() => setOpen((o) => !o)}
+        className={`inline-flex h-8 w-full min-w-[100px] cursor-pointer items-center gap-2 rounded-lg border bg-s3 px-3 text-body shadow-[var(--ele-1)] transition-[background-color,border-color,box-shadow] duration-200 ease-[var(--ease-smooth)] hover:shadow-[var(--ele-2)] focus-visible:ring-[3px] focus-visible:ring-accent/40 focus-visible:outline-none ${
+          open ? 'border-accent-hi' : 'border-line hover:border-ink/20'
+        } ${disabled ? 'cursor-not-allowed bg-s3 text-ink4 shadow-none' : 'text-ink'}`}
+      >
+        <span className={value !== undefined ? 'tabular-nums' : 'text-ink4'}>{value !== undefined ? `${pad(parts.h)}:${pad(parts.m)}` : placeholder}</span>
+        <span aria-hidden="true" className="ml-auto text-ink3"><Icon name="clock" size={14} /></span>
+      </button>
+      {open && createPortal(
+        <div className="fixed inset-0 z-[var(--z-popover)]" onClick={() => setOpen(false)}>
+          <div
+            className="absolute w-[180px] animate-[bp-zoom-in_var(--motion-base)_var(--ease-enter)] rounded-xl border border-line bg-s2 bg-[image:var(--wash)] p-3 shadow-[var(--shadow-pop),var(--ele-3)]"
+            style={{ left: ref.current?.getBoundingClientRect().left ?? 0, top: (ref.current?.getBoundingClientRect().bottom ?? 0) + 4 }}
+            onClick={(e) => e.stopPropagation()}
+          >
+            <TimeSpinner value={parts} onChange={(t) => onChange?.(emit(t))} locale={locale} />
+            <button
+              type="button"
+              onClick={() => {
+                // "Bây giờ" = thời điểm đầy đủ (ngày + giờ của now) — không bám date-part của value
+                onChange?.(new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours(), now.getMinutes()));
+                setOpen(false);
+              }}
+              className="mt-3 w-full cursor-pointer rounded-lg bg-accent px-2 py-1.5 text-label font-medium text-white transition-[opacity,transform] duration-200 ease-[var(--ease-smooth)] hover:opacity-90 active:translate-y-px"
+            >
+              {loc.now}
+            </button>
+          </div>
+        </div>,
+        document.body,
+      )}
+    </span>
+  );
+}

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

@@ -0,0 +1,90 @@
+// time-picker.stories.tsx — Forms/TimePicker (batch ⑧ worker C): input HH:mm +
+// dropdown stepper tăng/giảm từng trường + nút nhanh "Bây giờ".
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { TimePicker } from './index.js';
+
+const meta = {
+  title: 'Forms/TimePicker',
+  component: TimePicker,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Value nhận Date (onChange giữ nguyên phần ngày) hoặc string "HH:mm" (phát ngày thuần 01/01/1970). Panel: stepper ± từng trường Giờ/Phút (wrap 24h/60p) + nút nhanh Bây giờ. Locale qua prop hoặc DateLocaleProvider.',
+      },
+    },
+  },
+} satisfies Meta<typeof TimePicker>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+function CoBanDemo() {
+  const [t, setT] = useState<Date | undefined>();
+  return (
+    <div className="grid w-[260px] gap-3">
+      <TimePicker onChange={setT} />
+      <p className="text-meta text-ink3">
+        {t ? `Đã chọn: ${t.getHours().toString().padStart(2, '0')}:${t.getMinutes().toString().padStart(2, '0')}` : 'Mở panel → ± từng trường hoặc Bây giờ'}
+      </p>
+    </div>
+  );
+}
+
+export const Basic: Story = {
+  name: 'Basic',
+  render: () => <CoBanDemo />,
+};
+
+export const WithDateValue: Story = {
+  name: 'With Date value — date part preserved',
+  render: () => <TimePicker value={new Date(2026, 9, 18, 8, 30)} />,
+};
+
+/** StringValue — value as "HH:mm": trigger shows the time; a pick emits a pure
+ * epoch-day Date (1970-01-01 + time) — pair with DatePicker, not standalone. */
+export const StringValue: Story = {
+  name: 'String value "08:30" — emits epoch-day Date',
+  render: () => (
+    <div className="grid w-[260px] gap-3">
+      <TimePicker value="08:30" />
+      <p className="text-meta text-ink3">String value → trigger renders HH:mm without a Date object.</p>
+    </div>
+  ),
+};
+
+export const LocaleEN: Story = {
+  name: 'Locale EN',
+  render: () => <TimePicker locale="en" />,
+};
+
+/** Disabled — trigger locked. */
+export const Disabled: Story = {
+  args: { disabled: true, value: '08:30' },
+};
+
+/** Controlled — string value 'HH:mm' demo. */
+export const Controlled: Story = {
+  render: () => <TimePickerControlledDemo />,
+};
+
+export const DarkTheme: Story = {
+  name: 'Dark theme',
+  render: () => (
+    <div data-bp-theme="dark" className="rounded-xl bg-canvas p-4">
+      <TimePicker />
+    </div>
+  ),
+};
+
+function TimePickerControlledDemo() {
+  const [t, setT] = useState<string>('09:00');
+  return (
+    <div className="grid w-[260px] gap-3">
+      <TimePicker value={t} onChange={(d) => setT(`${d.getHours().toString().padStart(2, '0')}:${d.getMinutes().toString().padStart(2, '0')}`)} />
+      <p className="m-0 font-mono text-meta text-ink3">value: <strong className="text-ink">{t}</strong></p>
+    </div>
+  );
+}