lily-lark-ui 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,142 @@ Mọi thay đổi đáng chú ý của `lily-lark-ui` được ghi ở đây. Đ
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-11-06
+
+### Added — bộ chọn ngày và bộ chọn kỳ
+
+- `LarkDatePicker` (`YYYY-MM-DD`) và `LarkMonthPicker` (`YYYY-MM`) trong
+  `src/components/date-picker.tsx`: **controlled theo chuỗi**, không cầm engine
+  ngày. Trigger 32px như `LarkSelect`, panel bo 6 viền N200 bóng overlay, lật
+  lên khi hết chỗ phía dưới.
+- Xoá được: hover/focus trigger khi panel đóng hiện nút X, trả `''` qua
+  `onChange` và gọi `onClear`; `required` ẩn nút xoá. Chuỗi rỗng hoặc sai định
+  dạng hiển thị placeholder như chưa chọn.
+- Lịch 42 ô tuần bắt đầu thứ hai (`T2…CN`), ngày ngoài tháng làm mờ, footer
+  "Hôm nay"; `LarkMonthPicker` có lưới 12 tháng và bảng chọn năm 12 ô.
+- Rollover năm: 12→1 và 1→12 đổi cả năm đang xem; chọn năm tự chuyển về bảng
+  tháng; `value` đổi từ ngoài thì view bám theo giá trị mới.
+- Bàn phím: trigger `role=combobox` `aria-haspopup=dialog`, Escape đóng; lưới
+  arrow/Home/End di chuyển focus theo hàng; chọn hoặc gõ tay xong trả focus về
+  trigger. `LarkDatePicker` nhập tay `YYYY/M/D` hoặc `D/M/YYYY` (dấu `/`, `-`,
+  `.`), Enter hoặc blur là commit, sai thì báo lỗi tại chỗ.
+
+### Added — `LarkTable`: header hai tầng, ghim trái, bảng tổng hợp
+
+- `groupedHeader` (`LarkGroupedHeader[]`): hàng 1 là ô nhóm `scope=colgroup`
+  với `colSpan`/`rowSpan: 2`, hàng 2 là cột con; nhóm một cột con vẫn giữ ô
+  nhóm đúng hàng.
+- `pin: 'left'`: cột ghim trái song song `pin: 'right'` đã có (`sticky left-0`,
+  `border-e` phân cách, `z-10` cho body và `z-20` cho head).
+- `rowHeader` trên cột: ô dữ liệu render `th scope=row` thay vì `td`.
+- `caption` + `captionHidden`: caption hiện trên bảng hoặc `sr-only`, đặt
+  accessible name cho `<table>`.
+- `sectionRow(row, index)`: hàng phân mục trong `tbody`, một ô
+  `th scope=colgroup` phủ hết chiều rộng; `sectionRowClassName` đổi class.
+- `showHeader={false}`: bỏ `thead` cho bảng tổng hợp chỉ có `tbody`.
+
+### Added — test
+
+- `tests/date-picker.test.tsx`: 16 test cho hai picker (controlled, xoá,
+  `required`, rollover năm, ngày ngoài tháng, 29/2, gõ tay, focus sau khi chọn).
+- `tests/table.test.tsx`: 6 test mới cho `groupedHeader` (colSpan/rowSpan,
+  scope), `caption`/`captionHidden`, `rowHeader`, `pin: 'left'`,
+  `sectionRow` + `showHeader={false}`.
+
+### Added — bảng prop trong spec sinh tự động
+
+- `scripts/gen-spec-props.mjs` đọc interface thật của 21 file component rồi sinh
+  khối `## Props` (prop riêng, kiểu, bắt buộc, prop HTML kế thừa) cho 18 trang
+  `specs/`. `--check` chạy trong `tests/spec-props.test.ts`.
+- MCP `lui_props`: trả bảng prop của một component theo tên (`switch`,
+  `LarkSwitch`, `tag`, `spinner`…). `serverInfo.version` đọc từ `package.json`.
+
+### Changed — tài liệu, registry, README, skill
+
+- `specs/date-picker.md` (mới) và `specs/table.md` (header hai tầng, ghim trái,
+  section row); `SPEC_MAP` thêm `date-picker`.
+- `registry.json`: thêm `lark-date-picker` và `lark-month-picker` (22 item).
+- `README.md`: thêm hai dòng picker, cập nhật dòng `LarkTable` với prop mới,
+  số component 22.
+- `skill/lark-ui/SKILL.md`: bảng chọn component thêm hai picker kèm ví dụ
+  import; `LarkTable` cập nhật prop mới.
+- `docs/STATUS.md`: số component 22, 21 trang `specs/`, 22 item registry.
+- Showcase: khối "Chọn ngày · Chọn kỳ" (controlled, nút xoá, case `required`,
+  disabled) và bảng tổng hợp dùng `groupedHeader` + `caption` + `sectionRow` +
+  `rowHeader` + cột ghim trái; `lark-ui-components.html` build lại.
+
+### Changed — đồng bộ tài liệu và skill theo trạng thái 0.3.0
+
+- `specs/`: sửa class đã lỗi thời (button viền N300, `text-brand-link` thay
+  `brand-secondary`, `focus-visible:focus-ring` thay `ring-2`, select
+  placeholder `n600`, tag blue `accent-soft`).
+- `README.md`: bảng component theo prop riêng, mục "Prop HTML", mục phát hành,
+  mục xem demo.
+- `INSTALL.md`: bỏ câu "chưa publish", thêm `--version`, ghim bản `0.3.0`.
+- `AGENTS.md`: quy tắc kế thừa prop primitive, quy tắc spec sinh tự động,
+  MCP 5 tool, mock `ResizeObserver`, quy trình phát hành.
+- `skill/lark-ui/SKILL.md`: mục prop HTML + bảng prop phụ (`controlClassName`,
+  `containerClassName`, `triggerClassName`, `toastClassName`), cập nhật
+  `LarkTable`/`LarkRadioGroup`, nhắc `lui_props`.
+
+### Fixed — nền tối cố định, autofocus, khoảng cách
+
+- Toast và tooltip giữ nền tối `#1F2329` ở cả hai theme (`--toast-bg`,
+  `--tooltip-bg` giữ nguyên trong khối dark; trước đây dùng `lark-n900` nên dark
+  mode đảo thành xám nhạt chữ mờ). Mũi tên tooltip ăn theo cùng token.
+- `LarkDialog.Footer` thêm `mt-3` (=12px, cùng nhịp `gap=12` Figma và footer
+  AlertDialog): body không còn dính sát viền divider.
+- Mở `LarkDialog` không còn cướp focus vào ô nhập đầu: chặn autofocus mặc
+  định của Radix, giữ focus trên khung Content (đã `outline-none`).
+- `LarkDatePicker`/`LarkMonthPicker`: bỏ autofocus khi mở panel (ô nhập tay và
+  ô tháng/năm đã chọn); panel lịch trần `max-w-[280px]` căn giữa theo trigger
+  (ô ngày gần vuông, ô nhập không còn dãn full form rộng); khe nhãn thứ–lưới
+  ngày `mt-1` → `mt-2`.
+- Showcase `TableBlock`: nút Xoá demo nay xoá được dòng (state `items`), cờ
+  `LarkSwitch` "Hỏi trước khi xoá", `LarkAlertDialog` xác nhận + toast
+  "Đã xoá phiếu".
+- `LarkDatePicker`/`LarkMonthPicker`: Escape trong panel đóng và trả focus về
+  trigger (chặn lan truyền để dialog cha không đóng theo); rời ô nhập chỉ
+  kiểm hợp lệ, không commit/đóng (bấm ngày khác sau khi gõ vẫn chọn đúng);
+  nút xoá hiện khi focus còn trong cụm trigger nên Tab tới được; `className`
+  gắn lên wrapper ngoài; xoá prop `triggerProps` và tuỳ chọn cột `MonthGrid`
+  không ai dùng.
+- `LarkDialog`: merge ref giữ cleanup của caller (unmount gọi cleanup).
+- `LarkTable`: `thead sticky top-0`, bỏ `sticky top-0` từng `th` nên header
+  hai tầng dính theo khối, không đè nhau khi cuộn.
+- Token: bỏ `--toast-bg`/`--tooltip-bg` trùng trong hai khối dark (kế thừa
+  từ `:root`, giá trị giữ nguyên `#1F2329` ở cả hai theme).
+
+## [0.3.0] — 2026-11-06
+
+### Added — prop HTML trên toàn bộ component
+
+12 component từng chỉ nhận vài prop (Select, Switch, Checkbox, RadioGroup,
+Pagination, Tabs, Dialog, AlertDialog, DropdownMenu, Tooltip, Spinner,
+EmptyState, Table) nay nhận đủ prop HTML của phần tử gốc: `onBlur`, `onFocus`,
+`onKeyDown`, `name`, `form`, `value`, `data-*`, `aria-*`, `style`, `id`, `ref`.
+
+- Interface kế thừa `ComponentPropsWithoutRef<typeof Primitive>` /
+  `HTMLAttributes<...>` thay vì khai báo tay vài prop.
+- Thêm prop phụ để không phá API cũ: `controlClassName` (Switch, Checkbox,
+  Radio.Item), `containerClassName` (Select), `triggerClassName` (Tooltip),
+  `toastClassName`/`viewportClassName` (ToastProvider).
+- `LarkTable` thêm `onRowClick(row, index)`, `rowClassName(row, index)`,
+  `ref` tới `<table>`; `LarkColumn` thêm `className`/`headerClassName`.
+- `LarkRadioGroup` nhận `children` (dùng `LarkRadioGroup.Item` tự bố trí) song
+  song với `options`.
+- `LarkTooltip.content` nhận `ReactNode` (trước là string).
+
+### Fixed
+
+- `LarkEmptyState` và `LarkSpinner` merge `className` qua `cn` nên class riêng
+  override được class kích thước (trước ghi đè mất `size-4`/`size-6`).
+- `AlertDialog.onEscapeKeyDown` do người dùng truyền không còn bị bỏ qua khi
+  `isPending` (giờ chặn trước rồi gọi handler của người dùng).
+- `tests/prop-passthrough.test.tsx` (15 test) + fixture kiểu
+  `tests/fixtures/types-props.tsx` chạy `tsc` để chặn hồi quy.
+- `vitest.setup.ts` mock `ResizeObserver` cho Radix.
+
 ## [0.2.0] — 2026-11-05
 
 ### Changed — đổi tên package sang `lily-lark-ui`

package/INSTALL.md

@@ -1,13 +1,14 @@
 # Cài đặt lily-lark-ui
 
-## Cài từ npm (sau khi package được publish)
+## Cài từ npm
 
 ```bash
 npx lily-lark-ui init
 ```
 
-Nếu `npx` báo không tìm thấy package, nghĩa là chưa publish lên registry — xem
-mục "Phát hành" bên dưới, hoặc cài từ tarball.
+Package đã publish: `lily-lark-ui@0.3.0` (npm, không scope, `latest`). Nếu
+`npx` báo không tìm thấy, kiểm `npm view lily-lark-ui version`; bản mới có thể
+còn đang qua automated review của npm vài phút.
 
 ## Phát hành (dành cho maintainer)
 
@@ -71,8 +72,9 @@ npx lily-lark-ui init --repo ../app          # cài vào app khác
 npx lily-lark-ui init --dry-run              # xem kế hoạch, không ghi
 npx lily-lark-ui init --no-bootstrap         # không cài Tailwind/sửa vite config
 npx lily-lark-ui init --components button,table
-npx lily-lark-ui check                       # chạy check-lark trên ./src
+npx lily-lark-ui check [<dir>]               # chạy check-lark (mặc định ./src)
 npx lily-lark-ui tokens                      # in bảng token
+npx lily-lark-ui --version                   # in phiên bản
 npx lily-lark-ui --help
 ```
 
@@ -84,11 +86,11 @@ Yêu cầu: chạy trong repo đã có `package.json` + `react`.
 bash ~/Sites/lark-ui/scripts/install.sh --repo . --apply --bootstrap
 ```
 
-Nếu package chưa publish lên registry, trỏ tới tarball:
+Nếu cần cài từ tarball (bản dev chưa publish, hoặc muốn ghim đúng file):
 
 ```bash
 cd ~/Sites/lark-ui && pnpm pack
-LARK_UI_TARBALL=~/Sites/lark-ui/lily-lark-ui-0.2.0.tgz \
+LARK_UI_TARBALL=~/Sites/lark-ui/lily-lark-ui-0.4.0.tgz \
   bash ~/Sites/lark-ui/scripts/install.sh --repo . --apply --bootstrap
 ```
 
@@ -176,16 +178,15 @@ Tailwind v4 **không tự quét `node_modules`**, nên ngoài `@import` còn ph
 pnpm add lily-lark-ui
 ```
 
-Nếu package chưa publish lên registry, cài từ tarball:
+Package dùng tên không scope, không cần token cho consumer. Import:
 
-```bash
-# trong repo lark-ui
-pnpm pack            # sinh lily-lark-ui-<version>.tgz
-
-# trong repo đích
-pnpm add ./lily-lark-ui-0.2.0.tgz
+```tsx
+import { LarkButton } from 'lily-lark-ui'
 ```
 
+Nếu cần ghim đúng file build (bản dev chưa publish, hoặc kiểm tra tarball), cài
+bằng `pnpm add ./lily-lark-ui-0.4.0.tgz` sau khi `pnpm pack` trong repo này.
+
 Dùng component:
 
 ```tsx

package/README.md

@@ -1,7 +1,15 @@
 # lily-lark-ui
 
-Thu vien component React theo phong cach Lark (Universe Design), dung kieu shadcn:
-copy-paste component Tailwind v4 + Radix headless. Hien co 20 component.
+Thư viện component React theo phong cách Lark (Universe Design) cho React 19 +
+Tailwind v4. 22 component, nền Radix headless, phát hành trên npm.
+
+```bash
+npx lily-lark-ui init        # cài vào app hiện tại (tự cài Tailwind v4)
+```
+
+Phiên bản hiện tại: `0.4.0`. Mọi component nhận đủ prop HTML của phần tử gốc
+(`onBlur`, `onFocus`, `onKeyDown`, `name`, `form`, `value`, `data-*`, `aria-*`,
+`style`, `id`, `ref`) — xem mục [Prop HTML](#prop-html).
 
 ## Cài đặt
 
@@ -44,61 +52,117 @@ lớn hơn 0.
 
 ## Cai vao repo moi
 
-Mot lenh (6 buoc + kiem Tailwind v4, copy --components neu co, check-lark report):
+Mot lenh (6 buoc + kiem Tailwind v4, copy `--components` neu co, check-lark report):
+
+```bash
+npx lily-lark-ui init                      # app hien tai
+npx lily-lark-ui init --repo ../app        # app khac
+npx lily-lark-ui init --dry-run            # chi in ke hoach
+npx lily-lark-ui init --no-bootstrap       # khong dung Tailwind/vite config
+npx lily-lark-ui init --components button,table
+```
+
+Hoac goi thang script trong source checkout:
 
 ```bash
 scripts/install.sh --repo <path> --apply [--components button,text-field]
 ```
 
 - Khong truyen `--apply` thi dry-run: chi in ke hoach, khong sua file.
-- `--skip-install`: bo qua buoc `pnpm add` (dung cho test offline).
+- `--skip-install`: bo qua buoc cai package (dung cho test offline).
 - `--components <list>`: chi copy component can (ten cach nhau boi dau phay,
   vd `button,text-field`); kem `src/lib/utils.ts` + `src/styles/lark-tokens.css`
   neu chua co. Ten sai thi bao loi + liet ke ten hop le.
 - Idempotent: chay lai khong them trung import/block MCP.
 
+## Phát hành (maintainer)
+
+```bash
+pnpm release:dry   # build + test + check-lark + publint + pack + import(), khong publish
+pnpm release       # publish thật, rồi cài lại từ registry để xác nhận
+```
+
+Package là `lily-lark-ui` (không scope). Publish cần token npm có quyền ghi
+package; nếu tài khoản bật 2FA thì `npm publish` trả `EOTP`, cần Automation
+token. Bản mới đi qua automated review của npm (vài phút) trước khi thành
+`latest`.
+
 ## Component
 
-| Component | Import | Props chinh | So do |
-|---|---|---|---|
-| LarkButton | `import { LarkButton } from 'lily-lark-ui'` | `variant` (primary/secondary/danger/ghost/text), `size` (xs/sm/md/lg), `isIconOnly`, `fullWidth`, `isPending`, `asChild` | 32px mac dinh (h-8), 40px nut chinh form (h-10), 28/24 nho; mobile 36/48px |
-| LarkTextField (+inputClass) | `import { LarkTextField } from 'lily-lark-ui'` | `label`, `error`, `description`, `isRequired`, `isInvalid` | Cao 42 mobile / 36 PC (`md:min-h-9`), chu 16 mobile / 14 PC |
-| LarkDropdownMenu | `import { LarkDropdownMenu } from 'lily-lark-ui'` | `trigger`, `align` (start/center/end); `Item` (`value`, `onSelect?`, `danger?`, `disabled?`, `checked?`) | Popover toi thieu 200 rong, bo goc 8, bong overlay; item 32px, dropdown vien #DEE0E3 qua token; dong menu (Escape/chon/click ngoai) tra focus ve trigger, click lai dong menu |
-| LarkTabs | `import { LarkTabs } from 'lily-lark-ui'` | `defaultValue`/`value`/`onValueChange`, `LarkTabs.List/Tab/Panel` | Tab cao 34, gach duoi tab kich hoat |
-| LarkTooltip (+LarkTooltipProvider) | `import { LarkTooltip, LarkTooltipProvider } from 'lily-lark-ui'` | `content`, `side` (top/right/bottom/left); Provider `delayDuration` (=300), `skipDelayDuration?` | delay 300ms, lech 6, overlay 300ms ease-out; render doc lap van mo (fallback), trong Provider dung chung |
-| LarkTextArea | `import { LarkTextArea } from 'lily-lark-ui'` | `label`, `error`, `isRequired` (ke thua moi prop `textarea`) | toi thieu 72px (~3 dong), chu 16 mobile / 14 PC |
-| LarkSelect | `import { LarkSelect } from 'lily-lark-ui'` | `options`, `value`/`onValueChange`, `placeholder`, `disabled`, `isInvalid` | trigger 32px (`h-8`) bo 6 (`rounded-lg`), item 32px, dropdown bo 6 vien `#DEE0E3` qua token |
-| LarkCheckbox | `import { LarkCheckbox } from 'lily-lark-ui'` | `label`, `checked` (true/false/'indeterminate'), `onCheckedChange` | khung 16px (`size-4`) bo 4, dau `size-3` trang |
-| LarkRadioGroup | `import { LarkRadioGroup } from 'lily-lark-ui'` | `label?`, `options`, `value`/`onValueChange` | khung 16px tron, cham chon vien brand 5px |
-| LarkSwitch | `import { LarkSwitch } from 'lily-lark-ui'` | `label?`, `checked`/`onCheckedChange` | ranh 36x20 (`h-5 w-9`), num 16px trang |
-| LarkDialog | `import { LarkDialog } from 'lily-lark-ui'` | `open`/`onOpenChange`, `Content` (`title`, `description?`), `Footer` | bo 8 (`rounded-xl`), dem 20 mobile / 24 PC, toi da `max-w-md` |
-| LarkAlertDialog | `import { LarkAlertDialog } from 'lily-lark-ui'` | `title`, `confirmLabel`, `cancelLabel` (=`Huy`), `onConfirm`, `isPending` | khung nhu dialog; pending chan Escape + disable nut huy |
-| LarkToast (+Provider/useLarkToast) | `import { LarkToastProvider, useLarkToast } from 'lily-lark-ui'` | `toast({ title, description?, variant? })` (default/success/danger) | nen `n900`, bo 8 / pill mobile, hien 4s, quet phai de tat |
-| LarkSpinner / LarkEmptyState | `import { LarkSpinner, LarkEmptyState } from 'lily-lark-ui'` | Spinner `size` (sm/md), `label` bat buoc; EmptyState `icon`, `title`, `description?`, `action?` | spinner 16/24px xoay `n500`; empty can giua, icon 24px, dem doc 40px |
-| LarkTable (+Wrapper/Footer/TruncatedCell) | `import { LarkTable, LarkTableWrapper, LarkPagination } from 'lily-lark-ui'` | `columns`, `rows`, `rowKey`, `isLoading?`, `emptyState?`; cot `pin: 'right'`; caller tu boc `<LarkTable.Footer>` quanh `<LarkPagination>` | head 48 (`h-12`), body 47 (`h-[47px]`), divider `n200/n300`, ghim `z-10/z-20`, skeleton `animate-pulse` |
-| LarkPagination (+pageWindow) | `import { LarkPagination } from 'lily-lark-ui'` | `page`, `total`, `pageSize`, `onPageChange`, `pageSizes?` (mac dinh `[50, 100, 200]`), `onPageSizeChange?`, `isLoading?` | nut 28 (`size-7`), active 28x28 bo 6 (rounded-lg = --radius-lg 6px), footer `py-2 px-3`, pageWindow toi da 7 |
-| LarkTag | `import { LarkTag } from 'lily-lark-ui'` | `color` (blue/gray/success/danger/warning), `size` (md/sm) | cao 24 md (`h-6`) / 16 sm (`h-4`), bo 4 (`rounded-sm`) |
-| LarkBadge | `import { LarkBadge } from 'lily-lark-ui'` | `count?`, `max` (=`99`), `dot?` | cao 14 (`h-[14px]`), cham `size-2`, pill do `rounded-full` |
-| LarkAvatar (+getInitials) | `import { LarkAvatar } from 'lily-lark-ui'` | `name?`, `src?`, `team?`, `size` (sm/md/lg) | 20 sm (`size-5`) / 32 md (`size-8`) / 36 lg (`size-9`), team tron 36px (alias size lg) |
-
-## Nguon so do
-
-Moi so do trong thu vien lay tu `~/Sites/lily-projects/lark-design-guide`:
-uu tien mau noi bo `patterns/`, sau do so do goc Figma `figma/`
-(buttons, list, navigation, action-menu, feedback).
-Chi tiet xem `docs/specs/2026-11-05-lark-ui.md`.
-
-## Vi du
+Tất cả component nhận đủ prop HTML của phần tử gốc; bảng dưới chỉ liệt kê prop
+riêng của thư viện.
+
+| Component | Props riêng | Số đo |
+|---|---|---|
+| `LarkButton` | `variant` (primary, secondary, secondaryBlue, ghost, text, primaryError, secondaryError), `size` (xs/sm/md/lg), `isIconOnly`, `fullWidth`, `isPending`, `asChild` | 32px mặc định (`h-8`), 40px nút chính form (`h-10`), 28/24 nhỏ; mobile 36/48px |
+| `LarkTextField` (+ `inputClass`) | `label`, `error`, `description`, `isRequired`, `isInvalid` | 42px mobile / 36px PC (`md:min-h-9`), chữ 16/14 |
+| `LarkTextArea` | `label`, `error`, `isRequired` | tối thiểu 72px (~3 dòng) |
+| `LarkDropdownMenu` | `trigger`, `align` (start/center/end); `Item` (`value`, `onSelect`, `danger`, `disabled`, `checked`); `Separator` | popover min 200 rộng, bo 8, bóng overlay; item 32px; đóng menu trả focus về trigger |
+| `LarkTabs` | `defaultValue`/`value`/`onValueChange`; `LarkTabs.List/Tab/Panel` | tab cao 34, gạch dưới 3px |
+| `LarkTooltip` (+ `LarkTooltipProvider`) | `content` (`ReactNode`), `side`, `delayDuration`, `triggerClassName`; Provider `delayDuration` (=300), `skipDelayDuration` | delay 300ms, lệch 6px, overlay 300ms |
+| `LarkSelect` | `options`, `value`/`onValueChange`, `onOpenChange`, `placeholder`, `disabled`, `isInvalid`, `ariaLabel`, `containerClassName` | trigger 32px bo 6, item 32px, dropdown bo 6 |
+| `LarkDatePicker` | `label`, `value` (`YYYY-MM-DD`), `onChange`, `onClear`, `error`, `isInvalid`, `required`, `placeholder`, `disabled`, `describedBy`, `containerClassName` | trigger 32px như Select, panel bo 6, lịch 42 ô tuần bắt đầu T2, ô ngày 32px |
+| `LarkMonthPicker` (+ `formatMonthValue`) | `label`, `value` (`YYYY-MM`), `onChange`, `onClear`, `error`, `isInvalid`, `required`, `placeholder`, `disabled`, `describedBy`, `containerClassName` | trigger 32px, lưới tháng 3 cột, bảng năm 12 ô |
+| `LarkCheckbox` | `label`, `checked` (`true`/`false`/`'indeterminate'`), `onCheckedChange`, `controlClassName` | khung 16px bo 4, dấu 12px trắng |
+| `LarkRadioGroup` | `label`, `options` **hoặc** `children` (`LarkRadioGroup.Item`), `value`/`onValueChange` | khung 16px tròn, chấm viền brand 5px |
+| `LarkSwitch` | `label`, `checked`/`onCheckedChange`, `controlClassName` | rãnh 36×20, núm 16px |
+| `LarkDialog` | `open`/`onOpenChange`; `Content` (`title`, `description`), `Footer` | bo 8, đệm 20/24, tối đa `max-w-md` |
+| `LarkAlertDialog` | `title`, `confirmLabel`, `cancelLabel` (=`Hủy`), `onConfirm`, `isPending` | như dialog; pending chặn Escape, disable nút huỷ |
+| `LarkToastProvider` + `useLarkToast` | `toast({ title, description, variant })`; Provider `duration` (=4000), `toastClassName`, `viewportClassName` | nền `n900`, bo 8 / pill mobile, 4s, quét phải để tắt |
+| `LarkSpinner` / `LarkEmptyState` | Spinner `size` (sm/md), `label` bắt buộc; EmptyState `icon`, `title`, `description`, `action` | spinner 16/24px; empty căn giữa, icon 24px |
+| `LarkTable` (+ `Wrapper`/`Footer`/`TruncatedCell`) | `columns`, `rows`, `rowKey`, `isLoading`, `emptyState`, `onRowClick`, `rowClassName`, `ref`; cột có `pin: 'right' \| 'left'`, `rowHeader`, `className`, `headerClassName`; bảng có `groupedHeader`, `caption`, `captionHidden`, `sectionRow`, `sectionRowClassName`, `showHeader` | head 48, body 47, divider `n200/n300`, ghim `z-10/z-20` |
+| `LarkPagination` (+ `pageWindow`) | `page`, `total`, `pageSize`, `onPageChange`, `pageSizes` (=`[50,100,200]`), `onPageSizeChange`, `isLoading` | nút 28, active 28×28 bo 6, footer `py-2 px-3` |
+| `LarkTag` | `color` (blue/gray/success/danger/warning), `size` (md/sm) | 24 md / 16 sm, bo 4 |
+| `LarkBadge` | `count`, `max` (=99), `dot` | cao 14, chấm 8px |
+| `LarkAvatar` (+ `getInitials`) | `name`, `src`, `team`, `size` (sm/md/lg) | 20/32/36px, tròn |
+
+### Prop HTML
+
+Mọi component kế thừa prop HTML của phần tử gốc, nên gắn được logic React
+thoải mái:
+
+```tsx
+<LarkSwitch
+  label="Nhắc lịch hẹn"
+  name="notify"
+  checked={on}
+  onCheckedChange={setOn}
+  onBlur={trackBlur}
+  data-testid="notify-switch"
+  aria-describedby="notify-hint"
+/>
+
+<LarkTable
+  ref={tableRef}
+  columns={cols}
+  rows={rows}
+  rowKey={(r) => r.id}
+  onRowClick={(row, i) => open(row)}
+  rowClassName={(row) => (row.urgent ? 'bg-lark-danger/5' : undefined)}
+/>
+```
+
+`name`/`form`/`value` của `LarkSwitch` và `LarkCheckbox` vào hidden input của
+Radix nên `FormData` trong `<form>` thu được giá trị thật.
+
+## Nguồn số đo
+
+Số đo lấy từ style guide chính thức của Lark (MCP `lark-design`:
+`design-language/*`, `components/*`) — đây là nguồn quyết định. File Figma
+(`~/Sites/lily-projects/lark-design-guide/figma/`) chỉ để đối chiếu; lệch thì
+theo style guide và ghi rõ chỗ lệch trong spec. Chi tiết:
+`docs/specs/2026-11-05-lark-ui.md` và `specs/*.md`.
+
+## Ví dụ
 
 ```tsx
 import { LarkButton, LarkTextField } from 'lily-lark-ui'
-import 'lily-lark-ui/styles.css'
 
 export function LoginForm() {
   return (
     <form>
-      <LarkTextField label="So dien thoai" placeholder="Nhap so dien thoai" isRequired />
-      <LarkButton type="submit">Dang nhap</LarkButton>
+      <LarkTextField label="Số điện thoại" placeholder="Nhập số điện thoại" isRequired />
+      <LarkButton type="submit">Đăng nhập</LarkButton>
     </form>
   )
 }
@@ -119,6 +183,18 @@ export function RecordsTable({ columns, rows, page, total, pageSize, onPageChang
 }
 ```
 
-## Phat trien
+## Xem component
+
+Mở `lark-ui-components.html` ở root repo bằng trình duyệt — một file tự chứa,
+có nút chuyển sáng/tối, responsive 320–1600px.
+
+## Phát triển
 
-Xem [AGENTS.md](./AGENTS.md) truoc khi sua code.
+Xem [AGENTS.md](./AGENTS.md) trước khi sửa code.
+
+```bash
+pnpm test              # 254 test (vitest + jsdom)
+pnpm test:visual       # 9 test layout thật (Playwright)
+pnpm check:lark        # cấm hex, dark:, emoji-icon trong src/
+pnpm showcase:build    # build lại lark-ui-components.html
+```

package/dist/components/alert-dialog.d.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
-export interface LarkAlertDialogProps {
+import * as AlertDialogPrimitive from '@radix-ui/react-alert-dialog';
+export interface LarkAlertDialogProps extends Omit<React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>, 'title' | 'children' | 'className'> {
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
     title: string;

package/dist/components/alert-dialog.js

@@ -4,8 +4,13 @@ import * as React from 'react';
 import * as AlertDialogPrimitive from '@radix-ui/react-alert-dialog';
 import { cn } from '../lib/utils.js';
 import { LarkButton } from './button.js';
-function LarkAlertDialogBase({ open, onOpenChange, title, description, confirmLabel, cancelLabel = 'Hủy', onConfirm, isPending, children, className, }, ref) {
-    return (_jsx(AlertDialogPrimitive.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(AlertDialogPrimitive.Portal, { children: [_jsx(AlertDialogPrimitive.Overlay, { className: "fixed inset-0 bg-[var(--overlay-mask)] data-[state=open]:anim-overlay-in data-[state=closed]:anim-overlay-out" }), _jsxs(AlertDialogPrimitive.Content, { ref: ref, ...(description ? {} : { 'aria-describedby': undefined }), onEscapeKeyDown: isPending ? (event) => event.preventDefault() : undefined, className: cn('fixed left-1/2 top-1/2 w-[calc(100vw-2.5rem)] -translate-x-1/2 -translate-y-1/2 rounded-xl bg-brand-primary p-5 shadow-[var(--shadow-overlay)] outline-none data-[state=open]:anim-overlay-in data-[state=closed]:anim-overlay-out md:w-full md:max-w-md md:p-6', className), children: [_jsx(AlertDialogPrimitive.Title, { className: "text-base font-medium text-lark-n900 md:text-[17px]", children: title }), description ? (_jsx(AlertDialogPrimitive.Description, { className: "mt-3 text-sm text-lark-n600", children: description })) : null, children ? _jsx("div", { className: "mt-3", children: children }) : null, _jsxs("div", { className: "mt-3 flex justify-end gap-3 border-t border-[color-mix(in_srgb,var(--color-lark-n900)_15%,transparent)] px-5 py-4 md:px-6 -mx-5 -mb-5 md:-mx-6 md:-mb-6", children: [_jsx(AlertDialogPrimitive.Cancel, { asChild: true, children: _jsx(LarkButton, { type: "button", disabled: isPending, children: cancelLabel }) }), _jsx(AlertDialogPrimitive.Action, { asChild: true, children: _jsx(LarkButton, { type: "button", variant: "primary", isPending: isPending, onClick: onConfirm, children: confirmLabel }) })] })] })] }) }));
+function LarkAlertDialogBase({ open, onOpenChange, title, description, confirmLabel, cancelLabel = 'Hủy', onConfirm, isPending, children, className, onEscapeKeyDown, ...props }, ref) {
+    return (_jsx(AlertDialogPrimitive.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(AlertDialogPrimitive.Portal, { children: [_jsx(AlertDialogPrimitive.Overlay, { className: "fixed inset-0 bg-[var(--overlay-mask)] data-[state=open]:anim-overlay-in data-[state=closed]:anim-overlay-out" }), _jsxs(AlertDialogPrimitive.Content, { ref: ref, ...(description ? {} : { 'aria-describedby': undefined }), onEscapeKeyDown: isPending
+                        ? (event) => {
+                            event.preventDefault();
+                            onEscapeKeyDown?.(event);
+                        }
+                        : onEscapeKeyDown, className: cn('fixed left-1/2 top-1/2 w-[calc(100vw-2.5rem)] -translate-x-1/2 -translate-y-1/2 rounded-xl bg-brand-primary p-5 shadow-[var(--shadow-overlay)] outline-none data-[state=open]:anim-overlay-in data-[state=closed]:anim-overlay-out md:w-full md:max-w-md md:p-6', className), ...props, children: [_jsx(AlertDialogPrimitive.Title, { className: "text-base font-medium text-lark-n900 md:text-[17px]", children: title }), description ? (_jsx(AlertDialogPrimitive.Description, { className: "mt-3 text-sm text-lark-n600", children: description })) : null, children ? _jsx("div", { className: "mt-3", children: children }) : null, _jsxs("div", { className: "mt-3 flex justify-end gap-3 border-t border-[color-mix(in_srgb,var(--color-lark-n900)_15%,transparent)] px-5 py-4 md:px-6 -mx-5 -mb-5 md:-mx-6 md:-mb-6", children: [_jsx(AlertDialogPrimitive.Cancel, { asChild: true, children: _jsx(LarkButton, { type: "button", disabled: isPending, children: cancelLabel }) }), _jsx(AlertDialogPrimitive.Action, { asChild: true, children: _jsx(LarkButton, { type: "button", variant: "primary", isPending: isPending, onClick: onConfirm, children: confirmLabel }) })] })] })] }) }));
 }
 const LarkAlertDialogInner = React.forwardRef(LarkAlertDialogBase);
 LarkAlertDialogInner.displayName = 'LarkAlertDialog';

package/dist/components/checkbox.d.ts

@@ -1,10 +1,12 @@
 import * as React from 'react';
-export interface LarkCheckboxProps {
-    label: string;
+import * as Checkbox from '@radix-ui/react-checkbox';
+export interface LarkCheckboxProps extends Omit<React.ComponentPropsWithoutRef<typeof Checkbox.Root>, 'checked' | 'onCheckedChange' | 'disabled' | 'className'> {
+    label?: string;
     checked?: boolean | 'indeterminate';
     onCheckedChange?: (checked: boolean | 'indeterminate') => void;
     disabled?: boolean;
     className?: string;
+    controlClassName?: string;
 }
 declare const LarkCheckboxInner: React.ForwardRefExoticComponent<LarkCheckboxProps & React.RefAttributes<HTMLButtonElement>>;
 export { LarkCheckboxInner as LarkCheckbox };

package/dist/components/checkbox.js

@@ -5,10 +5,14 @@ import * as Checkbox from '@radix-ui/react-checkbox';
 import * as Label from '@radix-ui/react-label';
 import { Check, Minus } from 'lucide-react';
 import { cn } from '../lib/utils.js';
-function LarkCheckboxBase({ label, checked, onCheckedChange, disabled, className }, ref) {
+function LarkCheckboxBase({ label, checked, onCheckedChange, disabled, className, controlClassName, id, ...props }, ref) {
     const autoId = React.useId();
+    const checkboxId = id ?? autoId;
     const indeterminate = checked === 'indeterminate';
-    return (_jsxs("div", { className: cn('flex items-center gap-2', className), children: [_jsx(Checkbox.Root, { ref: ref, id: autoId, checked: checked, onCheckedChange: onCheckedChange, disabled: disabled, className: "size-4 shrink-0 rounded-[4px] border border-lark-n500 bg-brand-primary focus-visible:focus-ring transition-colors duration-fast ease-base data-[state=checked]:border-brand-secondary data-[state=checked]:bg-brand-secondary data-[state=indeterminate]:border-brand-secondary data-[state=indeterminate]:bg-brand-secondary disabled:cursor-not-allowed disabled:opacity-50", children: _jsx(Checkbox.Indicator, { className: "flex items-center justify-center", children: indeterminate ? (_jsx(Minus, { className: "size-3 text-white", "aria-hidden": "true" })) : (_jsx(Check, { className: "size-3 text-white", "aria-hidden": "true" })) }) }), _jsx(Label.Root, { htmlFor: autoId, className: "text-sm text-lark-n900", children: label })] }));
+    const root = (_jsx(Checkbox.Root, { ref: ref, id: checkboxId, checked: checked, onCheckedChange: onCheckedChange, disabled: disabled, className: cn('size-4 shrink-0 rounded-[4px] border border-lark-n500 bg-brand-primary focus-visible:focus-ring transition-colors duration-fast ease-base data-[state=checked]:border-brand-secondary data-[state=checked]:bg-brand-secondary data-[state=indeterminate]:border-brand-secondary data-[state=indeterminate]:bg-brand-secondary disabled:cursor-not-allowed disabled:opacity-50', controlClassName), ...props, children: _jsx(Checkbox.Indicator, { className: "flex items-center justify-center", children: indeterminate ? (_jsx(Minus, { className: "size-3 text-white", "aria-hidden": "true" })) : (_jsx(Check, { className: "size-3 text-white", "aria-hidden": "true" })) }) }));
+    if (!label)
+        return _jsx("div", { className: className, children: root });
+    return (_jsxs("div", { className: cn('flex items-center gap-2', className), children: [root, _jsx(Label.Root, { htmlFor: checkboxId, className: "text-sm text-lark-n900", children: label })] }));
 }
 const LarkCheckboxInner = React.forwardRef(LarkCheckboxBase);
 LarkCheckboxInner.displayName = 'LarkCheckbox';

package/dist/components/date-picker.d.ts

@@ -0,0 +1,49 @@
+import * as React from 'react';
+/** Nhãn tháng: `2026-10` → `Tháng 10/2026`; chuỗi lạ giữ nguyên. */
+export declare function formatMonthValue(value: string): string;
+export interface LarkMonthPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | 'children' | 'className'> {
+    /** Nhãn hiển thị phía trên trigger. */
+    label: string;
+    /** Kỳ dạng `YYYY-MM`; chuỗi rỗng hoặc sai định nghĩa là chưa chọn. */
+    value: string;
+    /** Nhận chuỗi `YYYY-MM` vừa chọn; nút xoá nhận `''`. */
+    onChange: (value: string) => void;
+    /** Báo lỗi dưới trigger; có lỗi thì trigger viền đỏ. */
+    error?: string;
+    /** Viền đỏ không kèm chữ (khi caller tự báo lỗi ngoài). */
+    isInvalid?: boolean;
+    /** true thì ẩn nút xoá — không cho bỏ trống; mặc định false cho phép xoá trả `''`. */
+    required?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    /** id đặt lên trigger để label form trỏ htmlFor. */
+    id?: string;
+    className?: string;
+    /** Class cho wrapper ngoài (nhãn + trigger + lỗi). */
+    containerClassName?: string;
+    /** aria-describedby thêm vào trigger (mô tả ngoài như hint). */
+    describedBy?: string;
+    /** Callback gọi cùng `onChange` khi người dùng xoá giá trị. */
+    onClear?: () => void;
+}
+export declare function LarkMonthPicker({ label, value, onChange, error, isInvalid, required, placeholder, disabled, id, className, containerClassName, describedBy, onClear: onClearProp, ...props }: LarkMonthPickerProps): React.JSX.Element;
+export interface LarkDatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | 'children' | 'className'> {
+    /** Nhãn hiển thị phía trên trigger. */
+    label: string;
+    /** Ngày dạng `YYYY-MM-DD`; chuỗi rỗng hoặc sai là chưa chọn. */
+    value: string;
+    /** Nhận `YYYY-MM-DD`; nút xoá nhận `''`. */
+    onChange: (value: string) => void;
+    error?: string;
+    isInvalid?: boolean;
+    /** true thì ẩn nút xoá; mặc định false cho phép xoá trả `''`. */
+    required?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    id?: string;
+    className?: string;
+    containerClassName?: string;
+    describedBy?: string;
+    onClear?: () => void;
+}
+export declare function LarkDatePicker({ label, value, onChange, error, isInvalid, required, placeholder, disabled, id, className, containerClassName, describedBy, onClear: onClearProp, ...props }: LarkDatePickerProps): React.JSX.Element;