@qijenchen/design-system 0.1.0-beta.10

package/dist/components/DataTable/filter-operators.d.ts

@@ -0,0 +1,116 @@
+/**
+ * filter-operators.ts — Advanced Filter Operator Registry SSOT
+ *
+ * Single source of truth for all filter operator definitions.
+ * 51 ops × 9 columnTypes × 12 ValueShapes.
+ *
+ * **禁止**:component 內 hardcode op 字串。一律走 `OPERATOR_REGISTRY[columnType]`。
+ *
+ * 設計路線:ClickUp baseline + 合理擴充(string +2, url 獨立 +4, date +2)。
+ * 詳細 spec:`./advanced-filter-operators.draft.md`
+ */
+import type { ColumnType } from './column-types';
+/**
+ * Filter value 該用什麼 picker — panel 只認 ValueShape,不認 op。
+ * 新增 op 只需 map 到既有 shape。
+ */
+export type ValueShape = 'none' | 'text' | 'number' | 'date_single' | 'date_range' | 'date_relative' | 'datetime_single' | 'datetime_range' | 'select_single' | 'select_multi' | 'person_single' | 'person_multi';
+export interface OperatorSpec {
+    /** Internal key, snake_case, immutable for FilterTree serialization */
+    op: string;
+    /** UI label in zh-TW(暫硬編,留 i18n hook) */
+    label: string;
+    /** Reference label for English / future i18n key */
+    labelEn: string;
+    /**
+     * Value picker shape.
+     * date_* shapes auto-promote to datetime_* when includeTime=true(via `getValueShape`).
+     */
+    valueShape: ValueShape;
+}
+export declare const DATE_RELATIVE_GROUPS: readonly [{
+    readonly key: "past";
+    readonly label: "過去";
+}, {
+    readonly key: "current";
+    readonly label: "目前";
+}, {
+    readonly key: "future";
+    readonly label: "未來";
+}];
+export declare const DATE_RELATIVE_OPTIONS: readonly [{
+    readonly value: "past_30_days";
+    readonly label: "過去 30 天";
+    readonly group: "past";
+}, {
+    readonly value: "past_7_days";
+    readonly label: "過去 7 天";
+    readonly group: "past";
+}, {
+    readonly value: "last_month";
+    readonly label: "上月";
+    readonly group: "past";
+}, {
+    readonly value: "last_week";
+    readonly label: "上週";
+    readonly group: "past";
+}, {
+    readonly value: "yesterday";
+    readonly label: "昨天";
+    readonly group: "past";
+}, {
+    readonly value: "today";
+    readonly label: "今天";
+    readonly group: "current";
+}, {
+    readonly value: "this_week";
+    readonly label: "本週";
+    readonly group: "current";
+}, {
+    readonly value: "this_month";
+    readonly label: "本月";
+    readonly group: "current";
+}, {
+    readonly value: "tomorrow";
+    readonly label: "明天";
+    readonly group: "future";
+}, {
+    readonly value: "next_week";
+    readonly label: "下週";
+    readonly group: "future";
+}, {
+    readonly value: "next_month";
+    readonly label: "下月";
+    readonly group: "future";
+}, {
+    readonly value: "next_7_days";
+    readonly label: "未來 7 天";
+    readonly group: "future";
+}, {
+    readonly value: "next_30_days";
+    readonly label: "未來 30 天";
+    readonly group: "future";
+}];
+/**
+ * SSOT canonical — 全部 51 ops, 9 columnTypes 對照表.
+ *
+ * **禁止繞過**:component 內勿 hardcode op 字串(M17 Rule-of-3 + Phase 5 Q3=c TypeScript-enforce 派)。
+ * `currency` 共用 `number` op set,渲染依 `column.meta.precision/prefix` 格式化。
+ */
+export declare const OPERATOR_REGISTRY: Record<ColumnType, OperatorSpec[]>;
+/** Default operator per columnType — 開新 condition 時的 op preset */
+export declare const DEFAULT_OPERATOR: Record<ColumnType, string>;
+/**
+ * Resolve ValueShape for a given op + columnType + includeTime flag.
+ *
+ * `date_single` / `date_range` shapes auto-promote to `datetime_single` /
+ * `datetime_range` when columnType=`date` && includeTime=true. All other
+ * shapes pass-through unchanged.
+ *
+ * `date_relative` stays as-is(relative 本質 day-level,e.g. `today` =
+ * 從今天 00:00 到 23:59:59,跟 includeTime 無關)。
+ */
+export declare function getValueShape(op: OperatorSpec, columnType: ColumnType, includeTime?: boolean): ValueShape;
+/** Get OperatorSpec by columnType + op key. Returns null if not found. */
+export declare function getOperatorSpec(columnType: ColumnType, op: string): OperatorSpec | null;
+//# sourceMappingURL=filter-operators.d.ts.map

package/dist/components/DataTable/filter-operators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-operators.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/filter-operators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAIhD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,MAAM,GACN,QAAQ,GACR,aAAa,GACb,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,eAAe,GACf,cAAc,CAAA;AAIlB,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAA;IACV,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,UAAU,EAAE,UAAU,CAAA;CACvB;AAOD,eAAO,MAAM,oBAAoB;;;;;;;;;EAIvB,CAAA;AAEV,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBxB,CAAA;AAkFV;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,UAAU,EAAE,YAAY,EAAE,CAchE,CAAA;AAED,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAYvD,CAAA;AAID;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,UAAU,EACtB,WAAW,CAAC,EAAE,OAAO,GACpB,UAAU,CAMZ;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAEvF"}

package/dist/components/DataTable/filter-tree.d.ts

@@ -0,0 +1,66 @@
+/**
+ * filter-tree.ts — FilterTree types + helpers + evaluator
+ *
+ * 抽自 data-table-filter-panel.tsx 為了 file-size budget(panel 拆分)。
+ * 純資料結構 + pure functions,無 UI dep。
+ *
+ * 詳:./advanced-filter.draft.md
+ */
+export type Conjunction = 'and' | 'or';
+export interface FilterCondition {
+    kind: 'cond';
+    /** 唯一 row id(stable across renders) */
+    id: string;
+    /** 對應 column id;空字串 = 尚未選 field(operator/value picker disabled) */
+    field: string;
+    /** OperatorSpec.op key — 對齊 OPERATOR_REGISTRY */
+    op: string;
+    /** 依 ValueShape 解讀的值 */
+    value: unknown;
+}
+export interface FilterGroup {
+    kind: 'group';
+    id: string;
+    /** group 內 children 共用的 join(全 AND 或全 OR;不允許混) */
+    conjunction: Conjunction;
+    /** ⚠️ 型別鎖死:children 只能 condition,不可再 nested group(1-level cap) */
+    children: FilterCondition[];
+}
+export type FilterTreeFlat = {
+    mode: 'flat';
+    conjunction: Conjunction;
+    children: FilterCondition[];
+};
+export type FilterTreeNested = {
+    mode: 'nested';
+    conjunction: Conjunction;
+    children: FilterGroup[];
+};
+export type FilterTree = FilterTreeFlat | FilterTreeNested;
+/** Empty FilterTree — consumer 用來 init useState */
+export declare function createEmptyFilterTree(mode: 'flat'): FilterTreeFlat;
+export declare function createEmptyFilterTree(mode: 'nested'): FilterTreeNested;
+/** 是否有任何 active filter — DataTable trigger button checked state 用 */
+export declare function isFilterTreeActive(tree: FilterTree): boolean;
+/** Compare two FilterTrees structurally — 忽略內部 row id(refresh-detect 不該被內部 id 干擾)*/
+export declare function isFilterTreeEqual(a: FilterTree, b: FilterTree): boolean;
+/**
+ * 整棵 FilterTree 對 row 求 boolean。
+ * 配合 useReactTable `globalFilterFn`:
+ *
+ *   const tree = useState<FilterTree>(createEmptyFilterTree('flat'))
+ *   useReactTable({
+ *     state: { globalFilter: tree },
+ *     onGlobalFilterChange: setTree,
+ *     globalFilterFn: (row, _, t: FilterTree) => evaluateTree(t, row.original),
+ *     getFilteredRowModel: getFilteredRowModel(),
+ *   })
+ */
+export declare function evaluateTree(tree: FilterTree, row: any): boolean;
+/**
+ * @deprecated v0.x — old per-column filterFn integration。
+ * 新版用 `evaluateTree` 配 TanStack `globalFilter`。
+ * 保留為了過渡期 backward-compat,新 consumer 不要用。
+ */
+export declare function dataTableFilterMatch(cellValue: unknown, filterValue: unknown): boolean;
+//# sourceMappingURL=filter-tree.d.ts.map

package/dist/components/DataTable/filter-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-tree.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/filter-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoCH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,IAAI,CAAA;AAEtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAA;IACV,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAA;IACV,wBAAwB;IACxB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,EAAE,EAAE,MAAM,CAAA;IACV,kDAAkD;IAClD,WAAW,EAAE,WAAW,CAAA;IACxB,kEAAkE;IAClE,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,QAAQ,CAAA;IACd,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,WAAW,EAAE,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,gBAAgB,CAAA;AAI1D,mDAAmD;AACnD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAA;AACnE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,gBAAgB,CAAA;AAMvE,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAK5D;AAsBD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAUvE;AAeD;;;;;;;;;;;GAWG;AAEH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAgBhE;AAgID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAMtF"}

package/dist/components/DataTable/lib/column-meta.d.ts

@@ -0,0 +1,49 @@
+/**
+ * column-meta — TanStack ColumnDef typed accessor helpers.
+ *
+ * **Scope:Internal-only — DataTable 自用,非 public API**(本檔不 re-export 出
+ * `data-table-filter-panel.tsx` / `data-table.tsx`,consumer 透過 panel / sort-manager
+ * 間接使用)。M21 (a) classification:lib/ folder 慣例 = internal helper。
+ *
+ * 為什麼存在:`ColumnDef<T, V>` 是 discriminated union(AccessorKey / AccessorFn /
+ * Display / Group),每個 variant 有不同欄位,直接 `col.id` 在型別上不安全。
+ * 既有 consumer 用 `(col as any).id` cast,3+ 處 hard-code = M17 違反。
+ * 抽成 typed helper 統一型別 narrowing,消除 `any` cast。
+ *
+ * Why not annotate each `as any`:DRY + single SSOT for column field access。
+ * 任一 helper 行為變更(e.g. 加 fallback 邏輯)只需改一處。
+ *
+ * 對齊 mindset #2 「優先消費既有」+ M17「同 hard-code 在 3+ consumer 必抽」。
+ */
+import type { ColumnDef, ColumnMeta, RowData } from '@tanstack/react-table';
+/**
+ * 取 column 的 stable identifier。
+ *
+ * 解析順序對齊 TanStack 內部行為:
+ * 1. `col.id`(顯式設定優先)
+ * 2. `col.accessorKey`(string version,fallback for accessor columns)
+ *
+ * 都無 → return undefined(display column 無 accessorKey 且未設 id)。
+ */
+export declare function getColumnId<T extends RowData>(col: ColumnDef<T, unknown>): string | undefined;
+/**
+ * 取 column 的 header 定義(可為 string / React node / function — TanStack 規約)。
+ *
+ * 注意:本 helper 不執行 header function。consumer 若需 rendered string,
+ * 自行 narrow + call,或用 TanStack `flexRender` API。
+ */
+export declare function getColumnHeader<T extends RowData>(col: ColumnDef<T, unknown>): ColumnDef<T, unknown>['header'];
+/**
+ * 取 column 的 meta(本 DS 的 ColumnMeta 已 extend 加上 type / align / wrap 等)。
+ */
+export declare function getColumnMeta<T extends RowData>(col: ColumnDef<T, unknown>): ColumnMeta<T, unknown> | undefined;
+/**
+ * 從 header 定義抽 plain string label(filter / sort UI 顯示用)。
+ *
+ * 處理 3 種 header 形式:
+ * - string → 直接 return
+ * - function → 不執行(避過 React render context),fallback id
+ * - undefined / 其他 → fallback id
+ */
+export declare function getColumnLabel<T extends RowData>(col: ColumnDef<T, unknown>, fallbackId?: string): string;
+//# sourceMappingURL=column-meta.d.ts.map

package/dist/components/DataTable/lib/column-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-meta.d.ts","sourceRoot":"","sources":["../../../../src/components/DataTable/lib/column-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAE3E;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAC3C,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,GACzB,MAAM,GAAG,SAAS,CASpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,EAC/C,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,GACzB,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,CAEjC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,EAC7C,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,GACzB,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,SAAS,CAEpC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC9C,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,EAC1B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAIR"}

package/dist/components/DateGrid/date-grid.d.ts

@@ -0,0 +1,61 @@
+import * as React from 'react';
+import { DayPicker } from 'react-day-picker';
+import 'react-day-picker/style.css';
+/**
+ * DateGrid — DayPicker 包裝,用本 DS token 覆寫預設視覺。
+ *
+ * ── 視覺對照(ref/datepicker.png,2026-04-21 rewrite)──
+ *
+ * | 區塊 | 規格 |
+ * |------|------|
+ * | Outer padding | `p-3`(12px 四邊對稱) |
+ * | Nav + Month caption row | h-field-xs(24px)單行,chevron(xs)分居左右 / 月份置中垂直對齊 |
+ * | Nav → Weekday gap | 12px(mt-3) |
+ * | Weekday | text-body(14px)text-fg-secondary(neutral-8) |
+ * | Cell gap(水平 + 垂直)| 4px(gap-1) |
+ * | Day cell size | h-field-md w-field-height-md(32×32 md / 36×36 lg) |
+ * | Day button | rounded-full 填滿 cell |
+ *
+ * ── 五種 cell state canonical ──
+ *
+ * | State | 視覺 | Token |
+ * |-------|------|-------|
+ * | today | 文字下方藍色底線 | underline decoration-primary decoration-2 underline-offset-4 |
+ * | disabled | 灰底圓圈 + disabled 字色(跟 Button disabled 一致) | [&>button]:bg-disabled [&>button]:text-fg-disabled rounded-full |
+ * | outside(非本月) | text-fg-muted(neutral-7) | [&>button]:text-fg-muted |
+ * | selected / range 端點 | 藍底白字圓 | [&>button]:bg-primary [&>button]:text-on-emphasis rounded-full |
+ * | range middle | 灰底矩形 track(neutral-3),**高度 = button 高度**(28×28 @ md) | before pseudo: `inset-y-0.5 inset-x-0` |
+ * | range start/end 半圓 track | 左/右半圓 + selected 圓疊在上,**圓半徑 = button 半徑** | before pseudo: `rounded-l/r-full` 加 `left-0.5` / `right-0.5` |
+ * | hover(未選中) | 藍圈 outline | hover:ring-1 hover:ring-primary |
+ *
+ * ── Range track 高度 canonical(2026-05-02 Q8 修正,M8 4 家對照)──
+ * Ant Design([picker source](https://github.com/ant-design/ant-design/blob/master/components/date-picker/style/panel.ts))/ Material X DateRangePicker([mui-x source](https://github.com/mui/mui-x/tree/master/packages/x-date-pickers-pro/src/DateRangeCalendar))/ Apple Calendar `@benchmark-unverified`(closed-source)/ Google Calendar `@benchmark-unverified`(closed-source)共識:
+ * **range track 高度 = button 高度**(不是 cell 高度)— track 跟 selected 圓緊貼,
+ * 不留 2px「fat」邊距(舊版 cell-level bg 在 button 上下留 2px 空白看起來「胖」)。
+ * 實作:bg 走 `before:` pseudo 走 `inset-y-0.5`(top/bottom 2px 內縮),`inset-x-0`
+ * 維持完整 cell 寬度 → 相鄰 cell 的 pseudo 在 cell 邊界相接 = 橫向連貫。
+ *
+ * ── 為什麼 neutral-3 不 neutral-2(AR 新版 canonical)──
+ * neutral-2 在 light mode 太淡(OKLCH L≈0.97),range track 跟 white bg 幾乎無對比。
+ * neutral-3(L≈0.94-0.95)在 Google / Ant / Apple DateRange track 視覺明顯,維持「可見 track」。
+ *
+ * ── 為什麼 nav 放頂部 + 年月垂直置中(不 separate 兩行)──
+ * ref/datepicker.png:chevron prev / 月份 / chevron next 同一行,24px 高(xs field height)。
+ * 省垂直空間,使用者視線不需上下跳。世界級(Google Calendar / Apple / iOS 日期輸入)皆此佈局。
+ */
+export type DateGridProps = React.ComponentProps<typeof DayPicker>;
+declare const DateGrid: React.ForwardRefExoticComponent<import("react-day-picker").DayPickerProps & React.RefAttributes<HTMLDivElement>>;
+export declare const dateGridMeta: {
+    readonly component: "DateGrid";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["bg-disabled", "bg-neutral-hover", "bg-primary", "bg-primary-hover", "bg-transparent"];
+        readonly fg: readonly ["text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"];
+        readonly ring: readonly ["ring-primary", "ring-ring"];
+    };
+};
+export { DateGrid };
+//# sourceMappingURL=date-grid.d.ts.map

package/dist/components/DateGrid/date-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-grid.d.ts","sourceRoot":"","sources":["../../../src/components/DateGrid/date-grid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,4BAA4B,CAAA;AAKnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,MAAM,MAAM,aAAa,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,SAAS,CAAC,CAAA;AAGlE,QAAA,MAAM,QAAQ,kHAkIZ,CAAA;AAKF,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/DateGrid/date-grid.js

@@ -0,0 +1,168 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { DayPicker } from "react-day-picker";
+import { ChevronRight, ChevronLeft } from "lucide-react";
+/* empty css                                                */
+import { cn } from "../../lib/utils.js";
+import { Button } from "../Button/button.js";
+const DateGrid = React.forwardRef(function DateGrid2({
+  className,
+  classNames,
+  showOutsideDays = true,
+  ...props
+}, _ref) {
+  return /* @__PURE__ */ jsx(
+    DayPicker,
+    {
+      showOutsideDays,
+      navLayout: "around",
+      className: cn("p-3", className),
+      classNames: {
+        months: "flex flex-col sm:flex-row gap-4",
+        // Month:relative 讓 prev/next 按鈕 absolute 定位到 month 右上/左上(navLayout="around")
+        month: "flex flex-col relative",
+        // Month caption:單行置中 h-field-xs,prev/next 按鈕 absolute 從兩側貼齊
+        month_caption: "flex items-center justify-center h-field-xs mb-3",
+        caption_label: "text-body font-medium",
+        // ── Prev/Next button(canonical 2026-05-03 v6,user audit fix)──
+        // RDP 把這 className apply 到 <Button> 本身(不是 wrapper),所以用 className 直接套
+        // 定位類(absolute top/left/right-0)。muted 色透過 Button override 內部加,不用 [&>button] 黑魔法。
+        button_previous: "absolute top-0 left-0 z-[1]",
+        button_next: "absolute top-0 right-0 z-[1]",
+        // ── Grid layout(canonical 2026-05-03 v7,純 table-native)──
+        // RDP v9 month_grid = <table>。v6 試 grid 在 tr 上但 break border-spacing(grid 蓋掉
+        // table-row layout)。乾淨修:**純 table layout** + `border-spacing-1`(4px H+V,table-native)。
+        // 所有 cells 自動同寬同高(td 的 w/h-field-sm),無 grid hack。
+        month_grid: "border-separate border-spacing-1",
+        weekdays: "",
+        // thead default
+        weekday: cn(
+          // text-foreground + font-medium 對齊 DS 一致設計語言(2026-05-03 user audit):
+          // weekday 列標跟 caption「April 2026」同視覺權重(都屬 calendar header 區),
+          // 不弱化(撤銷 v3 fg-secondary 的 mistake)。對齊 icon-only Button 預設 neutral-9 一致。
+          "text-foreground text-body font-medium",
+          "h-7 align-middle text-center"
+        ),
+        week: "",
+        // tr default
+        // Cell **就是** button 容器(28×28 @ md / 32×32 @ lg),`relative` 讓 before pseudo 定位
+        // ── h-field-sm 對齊 user spec(28×28 @ md)— v3 用 h-field-md (32×32) 是錯的
+        day: cn(
+          "h-field-sm w-[var(--field-height-sm)] p-0 text-center relative"
+        ),
+        day_button: cn(
+          // absolute inset-0 = 完全填滿 cell(naked button,無 inset 4px 空隙)
+          // z-[1] 讓 button 疊在 range track `before:` pseudo 之上
+          "absolute inset-0 z-[1] flex items-center justify-center",
+          "font-normal text-body rounded-full transition-colors",
+          // Hover 藍圈 1.5px(對齊 Apple HIG / Ant `@benchmark-unverified` visual ring measurement)— ring 在 button 之上 + 透明 bg 不擋 range track
+          "hover:ring-[1.5px] hover:ring-primary hover:bg-transparent",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        ),
+        // today:藍色 underline bar 貼近數字
+        today: cn(
+          "[&>button]:after:content-['']",
+          "[&>button]:after:absolute",
+          "[&>button]:after:bottom-[5px] [&>button]:after:left-1/2 [&>button]:after:-translate-x-1/2",
+          "[&>button]:after:w-[40%] [&>button]:after:h-[1.5px] [&>button]:after:rounded-full",
+          "[&>button]:after:bg-primary",
+          // today + selected:bar 切 on-emphasis(白)
+          "[&[data-selected=true]>button]:after:bg-on-emphasis"
+        ),
+        outside: "[&>button]:text-fg-muted",
+        // Selected(single 或 range 端點):button 藍底白字圓
+        selected: cn(
+          "[&>button]:bg-primary [&>button]:text-on-emphasis",
+          "[&>button]:hover:bg-primary-hover [&>button]:hover:ring-0"
+        ),
+        disabled: cn(
+          "[&>button]:bg-disabled [&>button]:text-fg-disabled [&>button]:cursor-not-allowed",
+          "[&>button]:hover:ring-0 [&>button]:hover:bg-disabled"
+        ),
+        // ── Range track(canonical 2026-05-03 v6,Ant stadium pattern)──
+        // v5 用 pseudo 矩形蓋全 cell 修「白色破圖」,但新副作用:button 圓比矩形小,4 個
+        // corner triangle 區域 pseudo grey 凸出圓外(user 2026-05-03 抓到「凸出去」)。
+        // 對齊 Ant 實證(`cell-range-start::before { border-radius: 9999px 0 0 9999px }`):
+        // rangeStart pseudo 加 `rounded-l-full` → pseudo 變「左半圓 + 右矩形」stadium
+        // 左半圓 EXACTLY OVERLAY button 圓的左半圓(同 center,同 radius 14)→ 邊界無縫
+        // 右側矩形 bridge 2px to middle → 跟 middle pseudo 連續
+        // Cell 的 top-left + bottom-left corner triangle:pseudo 不蓋 + button 不蓋 →
+        // popover white 顯露(乾淨 breathing,跟 outside-of-range cells 一致視覺)
+        range_start: cn(
+          "before:content-[''] before:absolute before:inset-y-0",
+          "before:left-0 before:-right-[2px]",
+          "before:bg-neutral-selected before:pointer-events-none",
+          "before:rounded-l-full"
+          // ← stadium 左半圓 matches button 圓的左半弧
+        ),
+        range_end: cn(
+          "before:content-[''] before:absolute before:inset-y-0",
+          "before:-left-[2px] before:right-0",
+          "before:bg-neutral-selected before:pointer-events-none",
+          "before:rounded-r-full"
+          // ← 鏡像
+        ),
+        range_middle: cn(
+          "before:content-[''] before:absolute before:inset-y-0 before:-inset-x-[2px]",
+          "before:bg-neutral-selected before:pointer-events-none",
+          // button 透明顯露 track,但 hover ring 仍顯示
+          "[&>button]:!bg-transparent [&>button]:!text-foreground"
+        ),
+        hidden: "invisible",
+        ...classNames
+      },
+      components: {
+        // ── Prev/Next nav(canonical 2026-05-03 v9,DS 一致設計語言)──
+        // User 2026-05-03 audit:「icon-only Button icon 都用 neutral-9,只有 dismiss 用 45%」
+        // → chevron 不是 dismiss,**走 Button 預設 text-foreground**(neutral-9 85%),
+        // 不開新 tier 自打嘴(撤銷 v6-v8 用 fg-muted override 的 mistake)。
+        // RDP v9 `PreviousMonthButton / NextMonthButton` override(node_modules/react-day-picker/dist/esm/components/Nav.js)
+        // ⚠️ children: _ 必丟棄(RDP 把 <Chevron> 當 children 傳 → 跟 Button startIcon 重疊變 double chevron)
+        PreviousMonthButton: ({ className: className2, children: _children, ...props2 }) => /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: "text",
+            size: "xs",
+            iconOnly: true,
+            startIcon: ChevronLeft,
+            "aria-label": "上一個月",
+            className: className2,
+            ...props2
+          }
+        ),
+        NextMonthButton: ({ className: className2, children: _children, ...props2 }) => /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: "text",
+            size: "xs",
+            iconOnly: true,
+            startIcon: ChevronRight,
+            "aria-label": "下一個月",
+            className: className2,
+            ...props2
+          }
+        )
+      },
+      ...props
+    }
+  );
+});
+DateGrid.displayName = "DateGrid";
+const dateGridMeta = {
+  component: "DateGrid",
+  family: null,
+  // non-family composite / overlay / layout
+  variants: {},
+  sizes: {},
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-disabled", "bg-neutral-hover", "bg-primary", "bg-primary-hover", "bg-transparent"],
+    fg: ["text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"],
+    ring: ["ring-primary", "ring-ring"]
+  }
+};
+export {
+  DateGrid,
+  dateGridMeta
+};
+//# sourceMappingURL=date-grid.js.map

package/dist/components/DateGrid/date-grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-grid.js","sources":["../../../src/components/DateGrid/date-grid.tsx"],"sourcesContent":["// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.\n// M22 retrofit DONE 2026-05-03 v11(real source URLs added inline at lines 38 + 111)\nimport * as React from 'react'\nimport { DayPicker } from 'react-day-picker'\nimport { ChevronLeft, ChevronRight } from 'lucide-react'\nimport 'react-day-picker/style.css'\n\nimport { cn } from '@/lib/utils'\nimport { Button } from '@/design-system/components/Button/button'\n\n/**\n * DateGrid — DayPicker 包裝,用本 DS token 覆寫預設視覺。\n *\n * ── 視覺對照(ref/datepicker.png,2026-04-21 rewrite)──\n *\n * | 區塊 | 規格 |\n * |------|------|\n * | Outer padding | `p-3`(12px 四邊對稱) |\n * | Nav + Month caption row | h-field-xs(24px)單行,chevron(xs)分居左右 / 月份置中垂直對齊 |\n * | Nav → Weekday gap | 12px(mt-3) |\n * | Weekday | text-body(14px)text-fg-secondary(neutral-8) |\n * | Cell gap(水平 + 垂直)| 4px(gap-1) |\n * | Day cell size | h-field-md w-field-height-md(32×32 md / 36×36 lg) |\n * | Day button | rounded-full 填滿 cell |\n *\n * ── 五種 cell state canonical ──\n *\n * | State | 視覺 | Token |\n * |-------|------|-------|\n * | today | 文字下方藍色底線 | underline decoration-primary decoration-2 underline-offset-4 |\n * | disabled | 灰底圓圈 + disabled 字色(跟 Button disabled 一致) | [&>button]:bg-disabled [&>button]:text-fg-disabled rounded-full |\n * | outside(非本月) | text-fg-muted(neutral-7) | [&>button]:text-fg-muted |\n * | selected / range 端點 | 藍底白字圓 | [&>button]:bg-primary [&>button]:text-on-emphasis rounded-full |\n * | range middle | 灰底矩形 track(neutral-3),**高度 = button 高度**(28×28 @ md) | before pseudo: `inset-y-0.5 inset-x-0` |\n * | range start/end 半圓 track | 左/右半圓 + selected 圓疊在上,**圓半徑 = button 半徑** | before pseudo: `rounded-l/r-full` 加 `left-0.5` / `right-0.5` |\n * | hover(未選中) | 藍圈 outline | hover:ring-1 hover:ring-primary |\n *\n * ── Range track 高度 canonical(2026-05-02 Q8 修正,M8 4 家對照)──\n * Ant Design([picker source](https://github.com/ant-design/ant-design/blob/master/components/date-picker/style/panel.ts))/ Material X DateRangePicker([mui-x source](https://github.com/mui/mui-x/tree/master/packages/x-date-pickers-pro/src/DateRangeCalendar))/ Apple Calendar `@benchmark-unverified`(closed-source)/ Google Calendar `@benchmark-unverified`(closed-source)共識:\n * **range track 高度 = button 高度**(不是 cell 高度)— track 跟 selected 圓緊貼,\n * 不留 2px「fat」邊距(舊版 cell-level bg 在 button 上下留 2px 空白看起來「胖」)。\n * 實作:bg 走 `before:` pseudo 走 `inset-y-0.5`(top/bottom 2px 內縮),`inset-x-0`\n * 維持完整 cell 寬度 → 相鄰 cell 的 pseudo 在 cell 邊界相接 = 橫向連貫。\n *\n * ── 為什麼 neutral-3 不 neutral-2(AR 新版 canonical)──\n * neutral-2 在 light mode 太淡(OKLCH L≈0.97),range track 跟 white bg 幾乎無對比。\n * neutral-3(L≈0.94-0.95)在 Google / Ant / Apple DateRange track 視覺明顯,維持「可見 track」。\n *\n * ── 為什麼 nav 放頂部 + 年月垂直置中(不 separate 兩行)──\n * ref/datepicker.png:chevron prev / 月份 / chevron next 同一行,24px 高(xs field height)。\n * 省垂直空間,使用者視線不需上下跳。世界級(Google Calendar / Apple / iOS 日期輸入)皆此佈局。\n */\n\nexport type DateGridProps = React.ComponentProps<typeof DayPicker>\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGrid(\n  {\n    className,\n    classNames,\n    showOutsideDays = true,\n    ...props\n  },\n  _ref,\n) {\n  // Note: react-day-picker v9 DayPicker 未對外 forward ref 到單一 DOM 節點(內部有多 div),\n  // 故 ref 簽名保留但不附著(符合 DS 統一 forwardRef 慣例;真要取 DOM 用 wrapper 包)。\n  return (\n    <DayPicker\n      showOutsideDays={showOutsideDays}\n      // navLayout=\"around\" = 每個 month caption 兩側渲染 prev / next 按鈕(inline row)\n      // 取代先前 absolute 定位覆蓋整個 months 容器導致箭頭垂直置中於中段的 bug\n      navLayout=\"around\"\n      // p-3 = 12px 四邊對稱(canonical 不可動)\n      className={cn('p-3', className)}\n      classNames={{\n        months: 'flex flex-col sm:flex-row gap-4',\n        // Month:relative 讓 prev/next 按鈕 absolute 定位到 month 右上/左上(navLayout=\"around\")\n        month: 'flex flex-col relative',\n        // Month caption:單行置中 h-field-xs,prev/next 按鈕 absolute 從兩側貼齊\n        month_caption: 'flex items-center justify-center h-field-xs mb-3',\n        caption_label: 'text-body font-medium',\n        // ── Prev/Next button(canonical 2026-05-03 v6,user audit fix)──\n        // RDP 把這 className apply 到 <Button> 本身(不是 wrapper),所以用 className 直接套\n        // 定位類(absolute top/left/right-0)。muted 色透過 Button override 內部加,不用 [&>button] 黑魔法。\n        button_previous: 'absolute top-0 left-0 z-[1]',\n        button_next: 'absolute top-0 right-0 z-[1]',\n        // ── Grid layout(canonical 2026-05-03 v7,純 table-native)──\n        // RDP v9 month_grid = <table>。v6 試 grid 在 tr 上但 break border-spacing(grid 蓋掉\n        // table-row layout)。乾淨修:**純 table layout** + `border-spacing-1`(4px H+V,table-native)。\n        // 所有 cells 自動同寬同高(td 的 w/h-field-sm),無 grid hack。\n        month_grid: 'border-separate border-spacing-1',\n        weekdays: '',  // thead default\n        weekday: cn(\n          // text-foreground + font-medium 對齊 DS 一致設計語言(2026-05-03 user audit):\n          // weekday 列標跟 caption「April 2026」同視覺權重(都屬 calendar header 區),\n          // 不弱化(撤銷 v3 fg-secondary 的 mistake)。對齊 icon-only Button 預設 neutral-9 一致。\n          'text-foreground text-body font-medium',\n          'h-7 align-middle text-center',\n        ),\n        week: '',  // tr default\n        // Cell **就是** button 容器(28×28 @ md / 32×32 @ lg),`relative` 讓 before pseudo 定位\n        // ── h-field-sm 對齊 user spec(28×28 @ md)— v3 用 h-field-md (32×32) 是錯的\n        day: cn(\n          'h-field-sm w-[var(--field-height-sm)] p-0 text-center relative',\n        ),\n        day_button: cn(\n          // absolute inset-0 = 完全填滿 cell(naked button,無 inset 4px 空隙)\n          // z-[1] 讓 button 疊在 range track `before:` pseudo 之上\n          'absolute inset-0 z-[1] flex items-center justify-center',\n          'font-normal text-body rounded-full transition-colors',\n          // Hover 藍圈 1.5px(對齊 Apple HIG / Ant `@benchmark-unverified` visual ring measurement)— ring 在 button 之上 + 透明 bg 不擋 range track\n          'hover:ring-[1.5px] hover:ring-primary hover:bg-transparent',\n          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',\n        ),\n        // today:藍色 underline bar 貼近數字\n        today: cn(\n          \"[&>button]:after:content-['']\",\n          '[&>button]:after:absolute',\n          '[&>button]:after:bottom-[5px] [&>button]:after:left-1/2 [&>button]:after:-translate-x-1/2',\n          '[&>button]:after:w-[40%] [&>button]:after:h-[1.5px] [&>button]:after:rounded-full',\n          '[&>button]:after:bg-primary',\n          // today + selected:bar 切 on-emphasis(白)\n          '[&[data-selected=true]>button]:after:bg-on-emphasis',\n        ),\n        outside: '[&>button]:text-fg-muted',\n        // Selected(single 或 range 端點):button 藍底白字圓\n        selected: cn(\n          '[&>button]:bg-primary [&>button]:text-on-emphasis',\n          '[&>button]:hover:bg-primary-hover [&>button]:hover:ring-0',\n        ),\n        disabled: cn(\n          '[&>button]:bg-disabled [&>button]:text-fg-disabled [&>button]:cursor-not-allowed',\n          '[&>button]:hover:ring-0 [&>button]:hover:bg-disabled',\n        ),\n        // ── Range track(canonical 2026-05-03 v6,Ant stadium pattern)──\n        // v5 用 pseudo 矩形蓋全 cell 修「白色破圖」,但新副作用:button 圓比矩形小,4 個\n        // corner triangle 區域 pseudo grey 凸出圓外(user 2026-05-03 抓到「凸出去」)。\n        // 對齊 Ant 實證(`cell-range-start::before { border-radius: 9999px 0 0 9999px }`):\n        // rangeStart pseudo 加 `rounded-l-full` → pseudo 變「左半圓 + 右矩形」stadium\n        // 左半圓 EXACTLY OVERLAY button 圓的左半圓(同 center,同 radius 14)→ 邊界無縫\n        // 右側矩形 bridge 2px to middle → 跟 middle pseudo 連續\n        // Cell 的 top-left + bottom-left corner triangle:pseudo 不蓋 + button 不蓋 →\n        // popover white 顯露(乾淨 breathing,跟 outside-of-range cells 一致視覺)\n        range_start: cn(\n          \"before:content-[''] before:absolute before:inset-y-0\",\n          'before:left-0 before:-right-[2px]',\n          'before:bg-neutral-selected before:pointer-events-none',\n          'before:rounded-l-full',  // ← stadium 左半圓 matches button 圓的左半弧\n        ),\n        range_end: cn(\n          \"before:content-[''] before:absolute before:inset-y-0\",\n          'before:-left-[2px] before:right-0',\n          'before:bg-neutral-selected before:pointer-events-none',\n          'before:rounded-r-full',  // ← 鏡像\n        ),\n        range_middle: cn(\n          \"before:content-[''] before:absolute before:inset-y-0 before:-inset-x-[2px]\",\n          'before:bg-neutral-selected before:pointer-events-none',\n          // button 透明顯露 track,但 hover ring 仍顯示\n          '[&>button]:!bg-transparent [&>button]:!text-foreground',\n        ),\n        hidden: 'invisible',\n        ...classNames,\n      }}\n      components={{\n        // ── Prev/Next nav(canonical 2026-05-03 v9,DS 一致設計語言)──\n        // User 2026-05-03 audit:「icon-only Button icon 都用 neutral-9,只有 dismiss 用 45%」\n        // → chevron 不是 dismiss,**走 Button 預設 text-foreground**(neutral-9 85%),\n        // 不開新 tier 自打嘴(撤銷 v6-v8 用 fg-muted override 的 mistake)。\n        // RDP v9 `PreviousMonthButton / NextMonthButton` override(node_modules/react-day-picker/dist/esm/components/Nav.js)\n        // ⚠️ children: _ 必丟棄(RDP 把 <Chevron> 當 children 傳 → 跟 Button startIcon 重疊變 double chevron)\n        PreviousMonthButton: ({ className, children: _children, ...props }) => (\n          <Button variant=\"text\" size=\"xs\" iconOnly startIcon={ChevronLeft}\n            aria-label=\"上一個月\"\n            className={className} {...props} />\n        ),\n        NextMonthButton: ({ className, children: _children, ...props }) => (\n          <Button variant=\"text\" size=\"xs\" iconOnly startIcon={ChevronRight}\n            aria-label=\"下一個月\"\n            className={className} {...props} />\n        ),\n      }}\n      {...props}\n    />\n  )\n})\nDateGrid.displayName = 'DateGrid'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const dateGridMeta = {\n  component: 'DateGrid',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-disabled', 'bg-neutral-hover', 'bg-primary', 'bg-primary-hover', 'bg-transparent'],\n    fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],\n    ring: ['ring-primary', 'ring-ring'],\n  },\n} as const\n\nexport { DateGrid }\n"],"names":["DateGrid","className","props"],"mappings":";;;;;;;AAwDA,MAAM,WAAW,MAAM,WAA0C,SAASA,UACxE;AAAA,EACE;AAAA,EACA;AAAA,EACA,kBAAkB;AAAA,EAClB,GAAG;AACL,GACA,MACA;AAGA,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC;AAAA,MAGA,WAAU;AAAA,MAEV,WAAW,GAAG,OAAO,SAAS;AAAA,MAC9B,YAAY;AAAA,QACV,QAAQ;AAAA;AAAA,QAER,OAAO;AAAA;AAAA,QAEP,eAAe;AAAA,QACf,eAAe;AAAA;AAAA;AAAA;AAAA,QAIf,iBAAiB;AAAA,QACjB,aAAa;AAAA;AAAA;AAAA;AAAA;AAAA,QAKb,YAAY;AAAA,QACZ,UAAU;AAAA;AAAA,QACV,SAAS;AAAA;AAAA;AAAA;AAAA,UAIP;AAAA,UACA;AAAA,QAAA;AAAA,QAEF,MAAM;AAAA;AAAA;AAAA;AAAA,QAGN,KAAK;AAAA,UACH;AAAA,QAAA;AAAA,QAEF,YAAY;AAAA;AAAA;AAAA,UAGV;AAAA,UACA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,QAAA;AAAA;AAAA,QAGF,OAAO;AAAA,UACL;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA,QAAA;AAAA,QAEF,SAAS;AAAA;AAAA,QAET,UAAU;AAAA,UACR;AAAA,UACA;AAAA,QAAA;AAAA,QAEF,UAAU;AAAA,UACR;AAAA,UACA;AAAA,QAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAWF,aAAa;AAAA,UACX;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA;AAAA,QAAA;AAAA,QAEF,WAAW;AAAA,UACT;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA;AAAA,QAAA;AAAA,QAEF,cAAc;AAAA,UACZ;AAAA,UACA;AAAA;AAAA,UAEA;AAAA,QAAA;AAAA,QAEF,QAAQ;AAAA,QACR,GAAG;AAAA,MAAA;AAAA,MAEL,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAOV,qBAAqB,CAAC,EAAE,WAAAC,YAAW,UAAU,WAAW,GAAGC,OAAAA,MACzD;AAAA,UAAC;AAAA,UAAA;AAAA,YAAO,SAAQ;AAAA,YAAO,MAAK;AAAA,YAAK,UAAQ;AAAA,YAAC,WAAW;AAAA,YACnD,cAAW;AAAA,YACX,WAAWD;AAAAA,YAAY,GAAGC;AAAAA,UAAA;AAAA,QAAA;AAAA,QAE9B,iBAAiB,CAAC,EAAE,WAAAD,YAAW,UAAU,WAAW,GAAGC,OAAAA,MACrD;AAAA,UAAC;AAAA,UAAA;AAAA,YAAO,SAAQ;AAAA,YAAO,MAAK;AAAA,YAAK,UAAQ;AAAA,YAAC,WAAW;AAAA,YACnD,cAAW;AAAA,YACX,WAAWD;AAAAA,YAAY,GAAGC;AAAAA,UAAA;AAAA,QAAA;AAAA,MAAO;AAAA,MAGtC,GAAG;AAAA,IAAA;AAAA,EAAA;AAGV,CAAC;AACD,SAAS,cAAc;AAIhB,MAAM,eAAe;AAAA,EAC1B,WAAW;AAAA,EACX,QAAQ;AAAA;AAAA,EACR,UAAU,CAAA;AAAA,EAGV,OAAO,CAAA;AAAA,EAGP,QAAQ,CAAC,WAAW,SAAS,UAAU,iBAAiB,UAAU;AAAA,EAClE,QAAQ;AAAA,IACN,IAAI,CAAC,eAAe,oBAAoB,cAAc,oBAAoB,gBAAgB;AAAA,IAC1F,IAAI,CAAC,oBAAoB,iBAAiB,qBAAqB,iBAAiB;AAAA,IAChF,MAAM,CAAC,gBAAgB,WAAW;AAAA,EAAA;AAEtC;"}

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

@@ -0,0 +1,119 @@
+import * as React from 'react';
+import type { FieldMode, FieldVariant } from '../../components/Field/field-types';
+import { type TimeStep } from '../../components/TimePicker/time-columns';
+export interface DateFormatOptions {
+    /** Intl.DateTimeFormat options（預設 { year: 'numeric', month: '2-digit', day: '2-digit' }） */
+    formatOptions?: Intl.DateTimeFormatOptions;
+    /** locale（預設 'en-US'） */
+    locale?: string;
+}
+/**
+ * Default format:**YYYY/MM/DD**(對齊 Ant Design 順序,year-first ISO-like)。
+ * 棄 `en-US` `MM/DD/YYYY`(month-first 美式)— 美式順序在 international DS 反直覺
+ * (跟 ISO date 視覺對不上,跟 sort 順序也對不上)。Ant / Material X / Apple HIG
+ * 一致 year-first。Consumer 想自訂可傳 `formatOptions` + `locale`。
+ */
+declare function formatDate(value: string | number | Date, options?: DateFormatOptions): string;
+export interface DatePickerProps extends DateFormatOptions, Omit<React.HTMLAttributes<HTMLDivElement>, 'value' | 'onChange' | 'placeholder' | 'defaultValue'> {
+    mode?: FieldMode;
+    /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
+    variant?: FieldVariant;
+    error?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    /** ISO date(YYYY-MM-DD)或 ISO datetime(YYYY-MM-DDTHH:MM:SS,當 showTime=true) */
+    value?: string | null;
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    className?: string;
+    disabled?: boolean;
+    /** 允許清空已選值 */
+    clearable?: boolean;
+    /** 啟用時間欄位(時 / 分 [/ 秒]),Ant idiom — value 變 ISO datetime */
+    showTime?: boolean;
+    /** showTime 時是否顯示秒 */
+    showSeconds?: boolean;
+    /** showTime 分鐘步進(會議常用 15) */
+    minuteStep?: TimeStep;
+    /** showTime 秒鐘步進 */
+    secondStep?: TimeStep;
+    /**
+     * 是否需 OK 確認才提交,預設 showTime=true 時為 true(對齊 Ant DatePicker showTime)
+     * — datetime picker user 習慣編完才 commit,避免 calendar 點到就關。
+     */
+    needConfirm?: boolean;
+    /**
+     * Display 是否渲 Calendar icon + Field naked wrapper(D-path opt-in,2026-05-08)
+     * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 span,backward compat)。
+     * 設 true 時 display 走 fieldWrapperStyles(naked variant)+ ItemSuffix CalendarIcon,
+     * 與 edit 同 DOM 結構,消除 Layer-B padding mismatch。
+     */
+    showDisplayEndIcon?: boolean;
+    /** Initial open state(uncontrolled)— DataTable cell-as-input 1-step open canonical */
+    defaultOpen?: boolean;
+    /** open state 變更 callback。DataTable cell-as-input 用:open=false → cell exit edit */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Issue 10 typed input(2026-05-10):trigger 內渲 real `<input>` 接 user 鍵盤輸入,
+     * 同時保持 Calendar icon trigger 開啟 calendar 選擇(對齊 Material X DatePicker / Ant
+     * DatePicker / Notion typed-date idiom)。
+     *
+     * 預設 false(backward-compat)— trigger 仍是 `<div role="combobox">` + `<span>` 文字。
+     *
+     * Behavior(opt-in `typeable=true`):
+     *   - `<input>` 取代 `<span>` displayValue,user 可直接打字
+     *   - Partial input(打到一半,如 "2025-")allow,**不**即時驗證
+     *   - `Enter` / `Blur` → `parseDateInput` 解析 → 合法 commit `onChange`;不合法 set
+     *     aria-invalid + keep draft visible(user 可繼續修)
+     *   - `Esc` → reset draft 回 committed value
+     *   - IME composition 期間不觸發驗證(中日韓輸入法 onCompositionStart/End 攔截)
+     *   - Calendar pick → 同步 input draft + commit(走原 path)
+     *   - Calendar icon 仍 click 開 popover(Material/Ant idiom)
+     *
+     * **v1 limits**:
+     *   - format detection ISO YYYY-MM-DD / YYYY/MM/DD / Date.parse fallback(`parseDateInput`)
+     *   - US `MM/DD/YYYY` vs EU `DD/MM/YYYY` ambiguous → fallback native parser
+     *   - 未支援 locale-aware format prop(v2 加 `dateFormat?: string`)
+     *
+     * 對齊 Material X-DatePicker `format` prop / Ant DatePicker `format` array / Notion typed-input。
+     */
+    typeable?: boolean;
+}
+export interface DatePickerRangeProps extends DateFormatOptions, Omit<React.HTMLAttributes<HTMLDivElement>, 'value' | 'onChange' | 'placeholder' | 'defaultValue'> {
+    mode?: FieldMode;
+    /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
+    variant?: FieldVariant;
+    error?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    /** 區間值:[start ISO, end ISO]。任一 null 代表尚未選。 */
+    value?: [string | null, string | null] | null;
+    onChange?: (value: [string | null, string | null]) => void;
+    /** Placeholder:[start placeholder, end placeholder] */
+    placeholder?: [string, string];
+    className?: string;
+    disabled?: boolean;
+    clearable?: boolean;
+    /** 啟用時間欄位 — value 兩端皆變 ISO datetime */
+    showTime?: boolean;
+    showSeconds?: boolean;
+    minuteStep?: TimeStep;
+    secondStep?: TimeStep;
+    needConfirm?: boolean;
+}
+declare const DatePickerRange: React.ForwardRefExoticComponent<DatePickerRangeProps & React.RefAttributes<HTMLDivElement>>;
+declare const DatePickerWithRange: React.ForwardRefExoticComponent<DatePickerProps & React.RefAttributes<HTMLDivElement>> & {
+    Range: React.ForwardRefExoticComponent<DatePickerRangeProps & React.RefAttributes<HTMLDivElement>>;
+};
+export declare const datePickerMeta: {
+    readonly component: "DatePicker";
+    readonly family: 4;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly [];
+        readonly fg: readonly ["text-fg-disabled", "text-fg-muted"];
+        readonly ring: readonly [];
+    };
+};
+export { DatePickerWithRange as DatePicker, DatePickerRange, formatDate, };
+//# sourceMappingURL=date-picker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"date-picker.d.ts","sourceRoot":"","sources":["../../../src/components/DatePicker/date-picker.tsx"],"names":[],"mappings":"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"}