@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

package/dist/components/DataTable/column-types.d.ts

@@ -22,7 +22,7 @@ declare module '@tanstack/react-table' {
         wrap?: boolean;
         /**
          * Max visible lines before ellipsis(2026-05-14 I9 per codex verdict + user 拍板)。
-         * Only effective when `autoRowHeight + wrap=true`。Display 用 `line-clamp-N`,edit textarea
+         * Only effective when `autoRowHeight + wrap=true`。view 用 `line-clamp-N`,edit textarea
          * 高度 match clamp。對齊 Notion 「Truncate」row toggle / AG Grid `cellClassRules` 上限 row height。
          * Default = undefined(無 clamp,完整 wrap)。
          */
@@ -79,10 +79,16 @@ declare module '@tanstack/react-table' {
         precision?: number;
         locale?: string;
         /** Select/multiSelect options — maps value to display label */
-        options?: Array<{
-            value: string;
-            label: string;
-        }>;
+        /** select/multiSelect 選項:消費 Select 的 SelectOption 完整 schema(M30 wrapper-extends-primitive;
+         *  2026-07-08 原 {value,label} 窄型別讓 icon/description/iconClassName 傳不進 = 假 SSOT)*/
+        options?: Array<import('../Select/select').SelectOption>;
+        /** select cell 的 trigger/display 自訂渲染(轉發 Select.selectedItemRenderer;status 彩色 icon 場景)*/
+        selectedItemRenderer?: (opt: import('../Select/select').SelectOption) => React.ReactNode;
+        /** select cell 顯示模式(轉發 Select.display;cell-registry SelectCell 消費 `meta?.display`)。
+         *  default `'plain'` 純文字;`'tag'` opt-in 內容導向 Tag 視覺(status / category 彩色標籤,
+         *  搭配 options 的 `tagVariant`)。2026-07-14 deep-audit 補型別:runtime 一直消費此欄位
+         *  (cell-registry.tsx SelectCell displayMode),但 ColumnMeta 漏宣告 → typed consumer 傳不進(假 SSOT)。 */
+        display?: 'plain' | 'tag';
         /** Date: Intl.DateTimeFormat options */
         formatOptions?: Intl.DateTimeFormatOptions;
         /**
@@ -113,22 +119,6 @@ declare module '@tanstack/react-table' {
          * Esc cancel / blur or Enter commit。Commit 觸發 `onCellCommit`。
          */
         editable?: boolean | ((row: TData) => boolean);
-        /**
-         * Inline disabled state(2026-05-13 Stream C Cluster B Q3 ship,per codex Q3 verdict):
-         * cell 不可操作 state(orthogonal to editable readonly)。
-         * - `true`:cell 永遠 disabled
-         * - `false` / undef(default):cell normal
-         * - `(row) => boolean`:per-row 動態(e.g. row.archived 或 row.locked 才 disabled)
-         *
-         * 視覺(per `color.spec.md` `--bg-disabled` component-state token):
-         * - TD 外殼:`bg-disabled` + `cursor-not-allowed` + 抑制 hover ring
-         * - Cell content(Field family):`mode='disabled'` → 各 Field type 內部走具體 disabled token
-         * - edit entry 抑制:disabled cell 點擊不進 edit(對齊 `editable && !disabled` invariant)
-         *
-         * 跟 `editable=false` 區分:editable=false = readonly(可看不可編);disabled = 不可操作 state。
-         * 對齊 MUI X `isCellEditable` + cellClassName / AG Grid `cellClassRules` / Notion locked properties。
-         */
-        disabled?: boolean | ((row: TData) => boolean);
         /**
          * Locked column — column reorder 不可拖,Notion 「primary column」 pattern。
          * 對齊 SKU / ID 等不可移欄位。

package/dist/components/DataTable/column-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"column-types.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/column-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AASpD,eAAO,MAAM,WAAW,+HAYd,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAIrD,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;CAInC;AAED,qCAAqC;AACrC,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAYnE,CAAA;AAID,OAAO,QAAQ,uBAAuB,CAAC;IACrC,UAAU,UAAU,CAAC,KAAK,SAAS,OAAO,EAAE,MAAM;QAChD;;;;;WAKG;QACH,IAAI,CAAC,EAAE,UAAU,CAAA;QACjB,kDAAkD;QAClD,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;QACnC,sEAAsE;QACtE,IAAI,CAAC,EAAE,OAAO,CAAA;QACd;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB;;;;;;;;;;;;;;;WAeG;QACH,KAAK,CAAC,EAAE,MAAM,CAAA;QACd;;;WAGG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB;;WAEG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB;;;;;;;;;;;WAWG;QACH,SAAS,CAAC,EAAE,OAAO,CAAA;QACnB;;;;;WAKG;QACH,UAAU,CAAC,EAAE,OAAO,CAAA;QACpB,yCAAyC;QACzC,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,+DAA+D;QAC/D,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;QACjD,wCAAwC;QACxC,aAAa,CAAC,EAAE,IAAI,CAAC,qBAAqB,CAAA;QAC1C;;;;;;;;;WASG;QACH,WAAW,CAAC,EAAE,OAAO,CAAA;QACrB,2CAA2C;QAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB;;;;;;;;;;;;;WAaG;QACH,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC,CAAA;QAC9C;;;;;;;;;;;;;;WAcG;QACH,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC,CAAA;QAC9C;;;WAGG;QACH,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,6FAA6F;QAC7F,MAAM,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAC3E;CACF"}
+{"version":3,"file":"column-types.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/column-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AASpD,eAAO,MAAM,WAAW,+HAYd,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAIrD,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;CAInC;AAED,qCAAqC;AACrC,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAYnE,CAAA;AAID,OAAO,QAAQ,uBAAuB,CAAC;IACrC,UAAU,UAAU,CAAC,KAAK,SAAS,OAAO,EAAE,MAAM;QAChD;;;;;WAKG;QACH,IAAI,CAAC,EAAE,UAAU,CAAA;QACjB,kDAAkD;QAClD,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;QACnC,sEAAsE;QACtE,IAAI,CAAC,EAAE,OAAO,CAAA;QACd;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB;;;;;;;;;;;;;;;WAeG;QACH,KAAK,CAAC,EAAE,MAAM,CAAA;QACd;;;WAGG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB;;WAEG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB;;;;;;;;;;;WAWG;QACH,SAAS,CAAC,EAAE,OAAO,CAAA;QACnB;;;;;WAKG;QACH,UAAU,CAAC,EAAE,OAAO,CAAA;QACpB,yCAAyC;QACzC,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,+DAA+D;QAC/D;0FACkF;QAClF,OAAO,CAAC,EAAE,KAAK,CAAC,OAAO,kBAAkB,EAAE,YAAY,CAAC,CAAA;QACxD,0FAA0F;QAC1F,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,kBAAkB,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAA;QACxF;;;wGAGgG;QAChG,OAAO,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;QACzB,wCAAwC;QACxC,aAAa,CAAC,EAAE,IAAI,CAAC,qBAAqB,CAAA;QAC1C;;;;;;;;;WASG;QACH,WAAW,CAAC,EAAE,OAAO,CAAA;QACrB,2CAA2C;QAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB;;;;;;;;;;;;;WAaG;QACH,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC,CAAA;QAI9C;;;WAGG;QACH,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,6FAA6F;QAC7F,MAAM,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAC3E;CACF"}

package/dist/components/DataTable/column-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"column-types.js","sources":["../../../src/components/DataTable/column-types.ts"],"sourcesContent":["import type { RowData } from '@tanstack/react-table'\n\n// ── Column Types ─────────────────────────────────────────────────────────────\n\n// ── Column Types ─────────────────────────────────────────────────────────────\n//\n// 命名原則:描述**資料型別**本身,不是視覺變體。命名要避開撞 Button `variant` 值。\n// `string` / `url` 是世界級 DS(Atlassian / Notion / Ant Table)的資料型別用語,\n// 跟 Button 的視覺變體 `text` / `link` 在 consumer 心智不會混淆。\nexport const columnTypes = [\n  'string',      // 前身為 'text',因撞 Button variant=\"text\"(文字樣式按鈕)改名\n  'number',\n  'currency',\n  'date',\n  'time',        // Phase C(2026-05-05):time-only column,渲 `<TimePicker>`\n  'select',\n  'multiSelect',\n  'person',\n  'multiPerson',\n  'boolean',\n  'url',         // 前身為 'link',因撞 Button variant=\"link\"(連結樣式按鈕)改名\n] as const\n\nexport type ColumnType = (typeof columnTypes)[number]\n\n// ── Column Type Config ───────────────────────────────────────────────────────\n\nexport interface ColumnTypeConfig {\n  /** Default horizontal alignment */\n  align: 'left' | 'right' | 'center'\n  // L3: sortingFn\n  // L4: filterVariant, filterFn\n  // L5: cellRenderer, cellEditor\n}\n\n/** Default config per column type */\nexport const columnTypeDefaults: Record<ColumnType, ColumnTypeConfig> = {\n  string:      { align: 'left' },\n  number:      { align: 'right' },\n  currency:    { align: 'right' },\n  date:        { align: 'left' },\n  time:        { align: 'left' },\n  select:      { align: 'left' },\n  multiSelect: { align: 'left' },\n  person:      { align: 'left' },\n  multiPerson: { align: 'left' },\n  boolean:     { align: 'left' },\n  url:         { align: 'left' },\n}\n\n// ── Extend TanStack Table ColumnMeta ─────────────────────────────────────────\n\ndeclare module '@tanstack/react-table' {\n  interface ColumnMeta<TData extends RowData, TValue> {\n    /**\n     * Column data type — determines default alignment, rendering, sorting, filtering.\n     *\n     * **Filterable column 必須設此 prop**(filter UI 只列有 `type` 的 column,\n     * 對齊 Notion / Airtable / Linear:每 property 強制有 type)。\n     */\n    type?: ColumnType\n    /** Override default alignment from column type */\n    align?: 'left' | 'right' | 'center'\n    /** Allow text wrapping (only effective when autoRowHeight is true) */\n    wrap?: boolean\n    /**\n     * Max visible lines before ellipsis(2026-05-14 I9 per codex verdict + user 拍板)。\n     * Only effective when `autoRowHeight + wrap=true`。Display 用 `line-clamp-N`,edit textarea\n     * 高度 match clamp。對齊 Notion 「Truncate」row toggle / AG Grid `cellClassRules` 上限 row height。\n     * Default = undefined(無 clamp,完整 wrap)。\n     */\n    maxLines?: number\n    /**\n     * Column 寬度(px)— DS canonical 命名(2026-05-06 v14.3)。\n     *\n     * **為何不用 TanStack 的 `size`** — DS 內 `size` 既定意為元件 density string\n     * `'sm' | 'md' | 'lg'`(Field / Button / Input 等 49+ 處 use case)。Column 寬\n     * 是 px 數字,跟 density 概念衝突 → 走 DS-internal 命名 `width`/`minWidth`/`maxWidth`\n     * (對齊 CSS 原生 + AG Grid 的命名共識)。\n     *\n     * 內部 pre-process 會把 `meta.width` copy 到 TanStack 的 root `size`,確保 column\n     * resize feature(`enableColumnResize=true` 拖拉 + columnSizing state)正常運作。\n     *\n     * - **No resize mode**(default): `width` = column 寬度 reserve(cell ≥ width,\n     *   flex 可 grow,**不可 shrink** 低於 width)。對齊 user 預期「我設多寬就多寬」。\n     * - **Resize mode**(`enableColumnResize=true`):`width` = 初始寬度,user 可拖拉\n     *   到 `minWidth` 為止。\n     */\n    width?: number\n    /**\n     * Column 最小寬度(px)— resize 模式下的拖拉下限。No resize 模式不使用(`width` 即下限)。\n     * Default(resize mode 沒明示時)= 80px(`MIN_COLUMN_WIDTH`)。\n     */\n    minWidth?: number\n    /**\n     * Column 最大寬度(px)— resize 模式下的拖拉上限。預設無上限。\n     */\n    maxWidth?: number\n    /**\n     * Column 是否可被 user 拖拉 resize(opt-out per col)。Default `true`(when `enableColumnResize` 也 true)。\n     *\n     * Set `false` 表「此 col 寬度由內容決定不允許 resize」(2026-05-10 加,per user\n     * 「操作列這種內容決定寬度的欄位應該不允許 resize」)。對齊 AG Grid `colDef.resizable` /\n     * Material X-DataGrid 同 API。\n     *\n     * System cols(__select__ / __drag__ / __actions__)自動 false(內部 hard-code,\n     * consumer 不需設)— 永遠固定寬。\n     *\n     * 典型 use case:custom 圖示欄、status indicator 欄、密度太緊不該 user 動的欄。\n     */\n    resizable?: boolean\n    /**\n     * Explicit opt-out from filter UI(預設 accessor column 有 type 即 filterable)。\n     *\n     * 用於:有 `type` 但不想在 filter UI 出現的 accessor column\n     * (例如:internal sorting key、composite display 用的 hidden column)。\n     */\n    filterable?: boolean\n    /** Number/currency formatting options */\n    prefix?: string\n    suffix?: string\n    precision?: number\n    locale?: string\n    /** Select/multiSelect options — maps value to display label */\n    options?: Array<{ value: string; label: string }>\n    /** Date: Intl.DateTimeFormat options */\n    formatOptions?: Intl.DateTimeFormatOptions\n    /**\n     * Date: 是否含時間部分(datetime mode)。對齊 Notion idiom — 不另設 datetime column type。\n     *\n     * - `false`(default):cell 顯示與 filter 比對僅日期(day-level 精度)\n     * - `true`:cell 渲 date+time;filter 比對走 ms 精度(避開 Airtable 著名地雷)\n     *\n     * 在 advanced filter 中,`date` columnType 配 `includeTime=true` 時,\n     * `date_*` ValueShape 自動 promote 到 `datetime_*`,渲 `<DatePicker showTime>` /\n     * `<DatePickerRange showTime>`(詳 `filter-operators.ts` `getValueShape`)。\n     */\n    includeTime?: boolean\n    /** Link: 自訂顯示文字（不設則自動從 URL 提取 hostname） */\n    linkLabel?: string\n    /**\n     * Inline edit:column 是否可編輯。\n     * - `true`:可編\n     * - `false`(default):唯讀\n     * - `(row) => boolean`:per-row 動態決定(e.g. row.status !== 'archived' 才能編)\n     *\n     * 互動 per type(對齊 Notion / Airtable):\n     * - string / number / currency:click cell → inline `<Input>` autoFocus + selected\n     * - date / select / multiSelect / person / multiPerson:click cell → 進 edit mode 的 Field control(用戶按 trigger 開 picker)\n     * - boolean:不分 read/edit mode,直接 `<Checkbox>` 點即 toggle + commit\n     * - url:read = 連結;**hover cell** 右側出 Pencil 按鈕,click 才進 `<Input>` edit mode(保留 click 連結語意)\n     *\n     * Esc cancel / blur or Enter commit。Commit 觸發 `onCellCommit`。\n     */\n    editable?: boolean | ((row: TData) => boolean)\n    /**\n     * Inline disabled state(2026-05-13 Stream C Cluster B Q3 ship,per codex Q3 verdict):\n     * cell 不可操作 state(orthogonal to editable readonly)。\n     * - `true`:cell 永遠 disabled\n     * - `false` / undef(default):cell normal\n     * - `(row) => boolean`:per-row 動態(e.g. row.archived 或 row.locked 才 disabled)\n     *\n     * 視覺(per `color.spec.md` `--bg-disabled` component-state token):\n     * - TD 外殼:`bg-disabled` + `cursor-not-allowed` + 抑制 hover ring\n     * - Cell content(Field family):`mode='disabled'` → 各 Field type 內部走具體 disabled token\n     * - edit entry 抑制:disabled cell 點擊不進 edit(對齊 `editable && !disabled` invariant)\n     *\n     * 跟 `editable=false` 區分:editable=false = readonly(可看不可編);disabled = 不可操作 state。\n     * 對齊 MUI X `isCellEditable` + cellClassName / AG Grid `cellClassRules` / Notion locked properties。\n     */\n    disabled?: boolean | ((row: TData) => boolean)\n    /**\n     * Locked column — column reorder 不可拖,Notion 「primary column」 pattern。\n     * 對齊 SKU / ID 等不可移欄位。\n     */\n    locked?: boolean\n    /** Person/multiPerson edit mode: people pool for picker(2026-05-05 v4 type-augmentation)。 */\n    people?: Array<{ name: string; avatarUrl?: string; description?: string }>\n  }\n}\n"],"names":[],"mappings":"AAoCO,MAAM,qBAA2D;AAAA,EACtE,QAAa,EAAE,OAAO,OAAA;AAAA,EACtB,QAAa,EAAE,OAAO,QAAA;AAAA,EACtB,UAAa,EAAE,OAAO,QAAA;AAAA,EACtB,MAAa,EAAE,OAAO,OAAA;AAAA,EACtB,MAAa,EAAE,OAAO,OAAA;AAAA,EACtB,QAAa,EAAE,OAAO,OAAA;AAAA,EACtB,aAAa,EAAE,OAAO,OAAA;AAAA,EACtB,QAAa,EAAE,OAAO,OAAA;AAAA,EACtB,aAAa,EAAE,OAAO,OAAA;AAAA,EACtB,SAAa,EAAE,OAAO,OAAA;AAAA,EACtB,KAAa,EAAE,OAAO,OAAA;AACxB;"}
+{"version":3,"file":"column-types.js","sources":["../../../src/components/DataTable/column-types.ts"],"sourcesContent":["import type { RowData } from '@tanstack/react-table'\n\n// ── Column Types ─────────────────────────────────────────────────────────────\n\n// ── Column Types ─────────────────────────────────────────────────────────────\n//\n// 命名原則:描述**資料型別**本身,不是視覺變體。命名要避開撞 Button `variant` 值。\n// `string` / `url` 是世界級 DS(Atlassian / Notion / Ant Table)的資料型別用語,\n// 跟 Button 的視覺變體 `text` / `link` 在 consumer 心智不會混淆。\nexport const columnTypes = [\n  'string',      // 前身為 'text',因撞 Button variant=\"text\"(文字樣式按鈕)改名\n  'number',\n  'currency',\n  'date',\n  'time',        // Phase C(2026-05-05):time-only column,渲 `<TimePicker>`\n  'select',\n  'multiSelect',\n  'person',\n  'multiPerson',\n  'boolean',\n  'url',         // 前身為 'link',因撞 Button variant=\"link\"(連結樣式按鈕)改名\n] as const\n\nexport type ColumnType = (typeof columnTypes)[number]\n\n// ── Column Type Config ───────────────────────────────────────────────────────\n\nexport interface ColumnTypeConfig {\n  /** Default horizontal alignment */\n  align: 'left' | 'right' | 'center'\n  // L3: sortingFn\n  // L4: filterVariant, filterFn\n  // L5: cellRenderer, cellEditor\n}\n\n/** Default config per column type */\nexport const columnTypeDefaults: Record<ColumnType, ColumnTypeConfig> = {\n  string:      { align: 'left' },\n  number:      { align: 'right' },\n  currency:    { align: 'right' },\n  date:        { align: 'left' },\n  time:        { align: 'left' },\n  select:      { align: 'left' },\n  multiSelect: { align: 'left' },\n  person:      { align: 'left' },\n  multiPerson: { align: 'left' },\n  boolean:     { align: 'left' },\n  url:         { align: 'left' },\n}\n\n// ── Extend TanStack Table ColumnMeta ─────────────────────────────────────────\n\ndeclare module '@tanstack/react-table' {\n  interface ColumnMeta<TData extends RowData, TValue> {\n    /**\n     * Column data type — determines default alignment, rendering, sorting, filtering.\n     *\n     * **Filterable column 必須設此 prop**(filter UI 只列有 `type` 的 column,\n     * 對齊 Notion / Airtable / Linear:每 property 強制有 type)。\n     */\n    type?: ColumnType\n    /** Override default alignment from column type */\n    align?: 'left' | 'right' | 'center'\n    /** Allow text wrapping (only effective when autoRowHeight is true) */\n    wrap?: boolean\n    /**\n     * Max visible lines before ellipsis(2026-05-14 I9 per codex verdict + user 拍板)。\n     * Only effective when `autoRowHeight + wrap=true`。view 用 `line-clamp-N`,edit textarea\n     * 高度 match clamp。對齊 Notion 「Truncate」row toggle / AG Grid `cellClassRules` 上限 row height。\n     * Default = undefined(無 clamp,完整 wrap)。\n     */\n    maxLines?: number\n    /**\n     * Column 寬度(px)— DS canonical 命名(2026-05-06 v14.3)。\n     *\n     * **為何不用 TanStack 的 `size`** — DS 內 `size` 既定意為元件 density string\n     * `'sm' | 'md' | 'lg'`(Field / Button / Input 等 49+ 處 use case)。Column 寬\n     * 是 px 數字,跟 density 概念衝突 → 走 DS-internal 命名 `width`/`minWidth`/`maxWidth`\n     * (對齊 CSS 原生 + AG Grid 的命名共識)。\n     *\n     * 內部 pre-process 會把 `meta.width` copy 到 TanStack 的 root `size`,確保 column\n     * resize feature(`enableColumnResize=true` 拖拉 + columnSizing state)正常運作。\n     *\n     * - **No resize mode**(default): `width` = column 寬度 reserve(cell ≥ width,\n     *   flex 可 grow,**不可 shrink** 低於 width)。對齊 user 預期「我設多寬就多寬」。\n     * - **Resize mode**(`enableColumnResize=true`):`width` = 初始寬度,user 可拖拉\n     *   到 `minWidth` 為止。\n     */\n    width?: number\n    /**\n     * Column 最小寬度(px)— resize 模式下的拖拉下限。No resize 模式不使用(`width` 即下限)。\n     * Default(resize mode 沒明示時)= 80px(`MIN_COLUMN_WIDTH`)。\n     */\n    minWidth?: number\n    /**\n     * Column 最大寬度(px)— resize 模式下的拖拉上限。預設無上限。\n     */\n    maxWidth?: number\n    /**\n     * Column 是否可被 user 拖拉 resize(opt-out per col)。Default `true`(when `enableColumnResize` 也 true)。\n     *\n     * Set `false` 表「此 col 寬度由內容決定不允許 resize」(2026-05-10 加,per user\n     * 「操作列這種內容決定寬度的欄位應該不允許 resize」)。對齊 AG Grid `colDef.resizable` /\n     * Material X-DataGrid 同 API。\n     *\n     * System cols(__select__ / __drag__ / __actions__)自動 false(內部 hard-code,\n     * consumer 不需設)— 永遠固定寬。\n     *\n     * 典型 use case:custom 圖示欄、status indicator 欄、密度太緊不該 user 動的欄。\n     */\n    resizable?: boolean\n    /**\n     * Explicit opt-out from filter UI(預設 accessor column 有 type 即 filterable)。\n     *\n     * 用於:有 `type` 但不想在 filter UI 出現的 accessor column\n     * (例如:internal sorting key、composite display 用的 hidden column)。\n     */\n    filterable?: boolean\n    /** Number/currency formatting options */\n    prefix?: string\n    suffix?: string\n    precision?: number\n    locale?: string\n    /** Select/multiSelect options — maps value to display label */\n    /** select/multiSelect 選項:消費 Select 的 SelectOption 完整 schema(M30 wrapper-extends-primitive;\n     *  2026-07-08 原 {value,label} 窄型別讓 icon/description/iconClassName 傳不進 = 假 SSOT)*/\n    options?: Array<import('../Select/select').SelectOption>\n    /** select cell 的 trigger/display 自訂渲染(轉發 Select.selectedItemRenderer;status 彩色 icon 場景)*/\n    selectedItemRenderer?: (opt: import('../Select/select').SelectOption) => React.ReactNode\n    /** select cell 顯示模式(轉發 Select.display;cell-registry SelectCell 消費 `meta?.display`)。\n     *  default `'plain'` 純文字;`'tag'` opt-in 內容導向 Tag 視覺(status / category 彩色標籤,\n     *  搭配 options 的 `tagVariant`)。2026-07-14 deep-audit 補型別:runtime 一直消費此欄位\n     *  (cell-registry.tsx SelectCell displayMode),但 ColumnMeta 漏宣告 → typed consumer 傳不進(假 SSOT)。 */\n    display?: 'plain' | 'tag'\n    /** Date: Intl.DateTimeFormat options */\n    formatOptions?: Intl.DateTimeFormatOptions\n    /**\n     * Date: 是否含時間部分(datetime mode)。對齊 Notion idiom — 不另設 datetime column type。\n     *\n     * - `false`(default):cell 顯示與 filter 比對僅日期(day-level 精度)\n     * - `true`:cell 渲 date+time;filter 比對走 ms 精度(避開 Airtable 著名地雷)\n     *\n     * 在 advanced filter 中,`date` columnType 配 `includeTime=true` 時,\n     * `date_*` ValueShape 自動 promote 到 `datetime_*`,渲 `<DatePicker showTime>` /\n     * `<DatePickerRange showTime>`(詳 `filter-operators.ts` `getValueShape`)。\n     */\n    includeTime?: boolean\n    /** Link: 自訂顯示文字（不設則自動從 URL 提取 hostname） */\n    linkLabel?: string\n    /**\n     * Inline edit:column 是否可編輯。\n     * - `true`:可編\n     * - `false`(default):唯讀\n     * - `(row) => boolean`:per-row 動態決定(e.g. row.status !== 'archived' 才能編)\n     *\n     * 互動 per type(對齊 Notion / Airtable):\n     * - string / number / currency:click cell → inline `<Input>` autoFocus + selected\n     * - date / select / multiSelect / person / multiPerson:click cell → 進 edit mode 的 Field control(用戶按 trigger 開 picker)\n     * - boolean:不分 read/edit mode,直接 `<Checkbox>` 點即 toggle + commit\n     * - url:read = 連結;**hover cell** 右側出 Pencil 按鈕,click 才進 `<Input>` edit mode(保留 click 連結語意)\n     *\n     * Esc cancel / blur or Enter commit。Commit 觸發 `onCellCommit`。\n     */\n    editable?: boolean | ((row: TData) => boolean)\n    // 2026-07-16 round16:cell `disabled` 已廢除。世界級 grid(MUI X isCellEditable / AG Grid editable /\n    //   Handsontable readOnly)皆無 disabled cell 態 — 鎖定用 `editable:(row)=>false`(可看不可編、不灰化),\n    //   非 disabled 灰化態。原 `disabled?: boolean | ((row)=>boolean)` + bg-disabled TD 灰化全移除(全庫 0 消費)。\n    /**\n     * Locked column — column reorder 不可拖,Notion 「primary column」 pattern。\n     * 對齊 SKU / ID 等不可移欄位。\n     */\n    locked?: boolean\n    /** Person/multiPerson edit mode: people pool for picker(2026-05-05 v4 type-augmentation)。 */\n    people?: Array<{ name: string; avatarUrl?: string; description?: string }>\n  }\n}\n"],"names":[],"mappings":"AAoCO,MAAM,qBAA2D;AAAA,EACtE,QAAa,EAAE,OAAO,OAAA;AAAA,EACtB,QAAa,EAAE,OAAO,QAAA;AAAA,EACtB,UAAa,EAAE,OAAO,QAAA;AAAA,EACtB,MAAa,EAAE,OAAO,OAAA;AAAA,EACtB,MAAa,EAAE,OAAO,OAAA;AAAA,EACtB,QAAa,EAAE,OAAO,OAAA;AAAA,EACtB,aAAa,EAAE,OAAO,OAAA;AAAA,EACtB,QAAa,EAAE,OAAO,OAAA;AAAA,EACtB,aAAa,EAAE,OAAO,OAAA;AAAA,EACtB,SAAa,EAAE,OAAO,OAAA;AAAA,EACtB,KAAa,EAAE,OAAO,OAAA;AACxB;"}

package/dist/components/DataTable/data-table-column-visibility-panel.d.ts

@@ -9,7 +9,7 @@
  *   - Locked 欄位(`lockedIds`)— 顯 Lock icon,不可 toggle / 不可 drag
  *   - 可選 search filter(`searchable`,跨欄位 label match)
  *   - 可選 column drag reorder(`onColumnOrderChange` 傳 → 啟 DnD)
- *   - 可選 reset 按鈕(`onReset`,header 區 RotateCcw)
+ *   - 可選 reset 按鈕(`resettable: boolean` opt-in,header 區 RotateCcw;點擊 `onVisibilityChange({})` 還原全顯示,無獨立 onReset prop)
  *   - Bidirectional bulk toggle(footer button:全可見 → 全部隱藏 / 任一隱藏 → 顯示全部)
  *
  * **Why 抽 primitive**(per Issue 3 Rule-of-3):RoadmapAllInOne + WithBulkActions + 未來 product
@@ -20,13 +20,14 @@
  * **對齊**:Linear column-visibility-panel pattern / Material X-DataGrid `<GridColumnsPanel>`
  * / Airtable Field-config drawer。
  */
+import * as React from 'react';
 interface ColumnVisibilityPanelColumn {
     /** Column id(stable identifier;對齊 DataTable column.id / accessorKey)*/
     id: string;
     /** Column header label(human-readable)*/
     label: string;
 }
-export interface DataTableColumnVisibilityPanelProps {
+export interface DataTableColumnVisibilityPanelProps extends React.HTMLAttributes<HTMLDivElement> {
     /** 全部可 toggle 欄位(consumer 已過濾掉 system cols 如 __select__)*/
     columns: ColumnVisibilityPanelColumn[];
     /** 受控 visibility map(`true` / undefined = visible / `false` = hidden)*/
@@ -44,6 +45,6 @@ export interface DataTableColumnVisibilityPanelProps {
     /** 是否顯 reset button(任一欄隱藏才顯,onClick 清空 visibility map)*/
     resettable?: boolean;
 }
-export declare function DataTableColumnVisibilityPanel({ columns, visibility, onVisibilityChange, columnOrder, onColumnOrderChange, lockedIds, searchable, resettable, }: DataTableColumnVisibilityPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare const DataTableColumnVisibilityPanel: React.ForwardRefExoticComponent<DataTableColumnVisibilityPanelProps & React.RefAttributes<HTMLDivElement>>;
 export {};
 //# sourceMappingURL=data-table-column-visibility-panel.d.ts.map

package/dist/components/DataTable/data-table-column-visibility-panel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-table-column-visibility-panel.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/data-table-column-visibility-panel.tsx"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAgBH,UAAU,2BAA2B;IACnC,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAA;IACV,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,mCAAmC;IAClD,2DAA2D;IAC3D,OAAO,EAAE,2BAA2B,EAAE,CAAA;IACtC,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,6BAA6B;IAC7B,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAC3D,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IAC9C,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,yDAAyD;IACzD,UAAU,CAAC,EAAE,OAAO,CAAA;CAGrB;AAED,wBAAgB,8BAA8B,CAAC,EAC7C,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,SAAc,EACd,UAAkB,EAClB,UAAkB,GACnB,EAAE,mCAAmC,2CAmIrC"}
+{"version":3,"file":"data-table-column-visibility-panel.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/data-table-column-visibility-panel.tsx"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAa9B,UAAU,2BAA2B;IACnC,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAA;IACV,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,mCAAoC,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC/F,2DAA2D;IAC3D,OAAO,EAAE,2BAA2B,EAAE,CAAA;IACtC,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,6BAA6B;IAC7B,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAC3D,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IAC9C,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,yDAAyD;IACzD,UAAU,CAAC,EAAE,OAAO,CAAA;CAGrB;AAED,eAAO,MAAM,8BAA8B,4GA4JzC,CAAA"}

package/dist/components/DataTable/data-table-column-visibility-panel.js

@@ -0,0 +1,193 @@
+import { jsxs, jsx, Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { RotateCcw, X, Search, Lock, GripVertical, Eye, EyeOff } from "lucide-react";
+import { Button } from "../Button/button.js";
+import { ButtonDivider } from "../Button/button-group.js";
+import { Input } from "../Input/input.js";
+import { PopoverHeader, PopoverTitle, PopoverClose, PopoverBody, PopoverFooter } from "../Popover/popover.js";
+import { ItemPrefix, ItemInlineActionButton, ItemLabel, ROW_PADDING_BY_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
+import { cn } from "../../lib/utils.js";
+import { DndContext, closestCenter } from "@dnd-kit/core";
+import { SortableContext, verticalListSortingStrategy, useSortable } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { dragSourceStyle } from "../../lib/drag-visual.js";
+const DataTableColumnVisibilityPanel = React.forwardRef(({
+  columns,
+  visibility,
+  onVisibilityChange,
+  columnOrder,
+  onColumnOrderChange,
+  lockedIds = [],
+  searchable = false,
+  resettable = false,
+  className,
+  ...props
+}, ref) => {
+  const [search, setSearch] = React.useState("");
+  const lockedSet = React.useMemo(() => new Set(lockedIds), [lockedIds]);
+  const dndEnabled = !!(columnOrder && onColumnOrderChange);
+  const orderedIds = React.useMemo(() => {
+    if (columnOrder && columnOrder.length > 0) {
+      const colSet = new Set(columns.map((c) => c.id));
+      return columnOrder.filter((id) => colSet.has(id));
+    }
+    return columns.map((c) => c.id);
+  }, [columnOrder, columns]);
+  const filteredEntries = React.useMemo(() => {
+    return orderedIds.map((id) => columns.find((c) => c.id === id)).filter((c) => c != null).filter((c) => search ? c.label.toLowerCase().includes(search.toLowerCase()) : true);
+  }, [orderedIds, columns, search]);
+  const togglableIds = columns.map((c) => c.id).filter((id) => !lockedSet.has(id));
+  const allVisible = togglableIds.every((id) => visibility[id] !== false);
+  const anyHidden = togglableIds.some((id) => visibility[id] === false);
+  const handleToggle = (id) => {
+    const visible = visibility[id] !== false;
+    onVisibilityChange({ ...visibility, [id]: !visible });
+  };
+  const handleReset = () => onVisibilityChange({});
+  const handleBulkToggle = () => {
+    if (allVisible) {
+      const next = {};
+      togglableIds.forEach((id) => {
+        next[id] = false;
+      });
+      onVisibilityChange(next);
+    } else {
+      onVisibilityChange({});
+    }
+  };
+  const handleDragEnd = (e) => {
+    if (!dndEnabled) return;
+    const { active, over } = e;
+    if (!over || active.id === over.id) return;
+    const oldIdx = columnOrder.indexOf(active.id);
+    const newIdx = columnOrder.indexOf(over.id);
+    if (oldIdx < 0 || newIdx < 0) return;
+    if (lockedSet.has(columnOrder[oldIdx]) || lockedSet.has(columnOrder[newIdx])) return;
+    const next = [...columnOrder];
+    const [m] = next.splice(oldIdx, 1);
+    next.splice(newIdx, 0, m);
+    onColumnOrderChange(next);
+  };
+  return (
+    // 決策16 定案(2026-07-18,SSOT consistency 稽核後):對齊 sibling FilterPanel/SortManager 的
+    //   overlay-surface canonical shape —— root `<div flex flex-col h-full min-h-0>`(M25 viewport-aware
+    //   scroll chain)+ viewport-adaptive `PopoverBody`(取代原 fixed `ScrollArea max-h-72`)。三個
+    //   DataTable state-panel 收斂成同一形狀,body 隨視窗高度自適應(高螢幕多欄不再硬卡 288px)。
+    //   寬度仍由 consumer 的 `<PopoverContent w-72>` 提供(panel root w-full 撐滿)。
+    /* @__PURE__ */ jsxs("div", { ref, className: cn("flex flex-col h-full min-h-0 w-full", className), ...props, children: [
+      /* @__PURE__ */ jsx(PopoverHeader, { hideClose: true, children: /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1 w-full min-w-0", children: [
+        /* @__PURE__ */ jsx(PopoverTitle, { className: "flex-1", children: "欄位顯示" }),
+        resettable && anyHidden && /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(
+            Button,
+            {
+              variant: "text",
+              size: "sm",
+              iconOnly: true,
+              startIcon: RotateCcw,
+              "aria-label": "恢復預設",
+              onClick: handleReset
+            }
+          ),
+          /* @__PURE__ */ jsx(ButtonDivider, {})
+        ] }),
+        /* @__PURE__ */ jsx(PopoverClose, { asChild: true, children: /* @__PURE__ */ jsx(Button, { "data-dismiss": true, iconOnly: true, dismiss: true, size: "sm", startIcon: X, "aria-label": "關閉" }) })
+      ] }) }),
+      searchable && /* @__PURE__ */ jsx("div", { className: "shrink-0 px-[var(--layout-space-loose)] pt-[var(--layout-space-tight)]", children: /* @__PURE__ */ jsx(
+        Input,
+        {
+          size: "md",
+          placeholder: "搜尋欄位…",
+          "aria-label": "搜尋欄位",
+          value: search,
+          onChange: (e) => setSearch(e.target.value),
+          startIcon: Search
+        }
+      ) }),
+      /* @__PURE__ */ jsx(PopoverBody, { className: "!px-0 !py-0", children: /* @__PURE__ */ jsx("div", { className: "py-2 flex flex-col", style: { "--item-prefix-slot": "16px" }, children: dndEnabled ? /* @__PURE__ */ jsx(DndContext, { collisionDetection: closestCenter, onDragEnd: handleDragEnd, children: /* @__PURE__ */ jsx(
+        SortableContext,
+        {
+          items: filteredEntries.map((e) => e.id).filter((id) => !lockedSet.has(id)),
+          strategy: verticalListSortingStrategy,
+          children: filteredEntries.map(({ id, label }) => /* @__PURE__ */ jsx(
+            VisibilityRow,
+            {
+              id,
+              label,
+              visible: visibility[id] !== false,
+              locked: lockedSet.has(id),
+              draggable: true,
+              onToggle: () => handleToggle(id)
+            },
+            id
+          ))
+        }
+      ) }) : filteredEntries.map(({ id, label }) => /* @__PURE__ */ jsx(
+        VisibilityRow,
+        {
+          id,
+          label,
+          visible: visibility[id] !== false,
+          locked: lockedSet.has(id),
+          draggable: false,
+          onToggle: () => handleToggle(id)
+        },
+        id
+      )) }) }),
+      /* @__PURE__ */ jsx(PopoverFooter, { className: "justify-start", children: /* @__PURE__ */ jsx(Button, { variant: "tertiary", size: "sm", onClick: handleBulkToggle, children: allVisible ? "全部隱藏" : "顯示全部" }) })
+    ] })
+  );
+});
+DataTableColumnVisibilityPanel.displayName = "DataTableColumnVisibilityPanel";
+function VisibilityRow({
+  id,
+  label,
+  visible,
+  locked,
+  draggable,
+  onToggle
+}) {
+  const sortable = useSortable({ id, disabled: locked || !draggable });
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = sortable;
+  const style = draggable ? { transform: CSS.Transform.toString(transform), transition, ...dragSourceStyle(isDragging) } : {};
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: draggable ? setNodeRef : void 0,
+      style,
+      className: cn(
+        "flex items-start gap-2 w-full px-[var(--layout-space-loose)]",
+        ROW_PADDING_BY_SIZE.md
+      ),
+      children: [
+        /* @__PURE__ */ jsx(ItemPrefix, { children: locked ? /* @__PURE__ */ jsx(Lock, { size: 16, className: "text-fg-muted", "aria-hidden": true }) : draggable ? /* @__PURE__ */ jsx(
+          ItemInlineActionButton,
+          {
+            icon: GripVertical,
+            size: "md",
+            "aria-label": "拖曳重排",
+            className: "cursor-grab active:cursor-grabbing",
+            ...attributes,
+            ...listeners
+          }
+        ) : null }),
+        /* @__PURE__ */ jsx(ItemLabel, { className: locked ? "text-fg-disabled" : void 0, children: label }),
+        /* @__PURE__ */ jsx(
+          ItemInlineActionButton,
+          {
+            icon: visible ? Eye : EyeOff,
+            size: "md",
+            "aria-label": visible ? "隱藏此欄" : "顯示此欄",
+            disabled: locked,
+            onClick: onToggle,
+            className: locked ? "cursor-not-allowed text-fg-disabled" : ""
+          }
+        )
+      ]
+    }
+  );
+}
+export {
+  DataTableColumnVisibilityPanel
+};
+//# sourceMappingURL=data-table-column-visibility-panel.js.map

package/dist/components/DataTable/data-table-column-visibility-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-table-column-visibility-panel.js","sources":["../../../src/components/DataTable/data-table-column-visibility-panel.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/**\n * DataTableColumnVisibilityPanel — Issue 3 primitive(2026-05-10)。\n *\n * 從 WithBulkActions story L868+(149 lines)+ RoadmapAllInOne(L1796+,53 lines)抽出 SSOT\n * primitive。Roadmap demo 跟 WithBulkActions 都用此 panel 開啟「欄位顯示」popover。\n *\n * **Feature SSOT**(對齊 Linear / Airtable / Notion / Material X-DataGrid 的 columnVisibility panel idiom):\n *   - 列出所有 togglable 欄位 + Eye / EyeOff 切換\n *   - Locked 欄位(`lockedIds`)— 顯 Lock icon,不可 toggle / 不可 drag\n *   - 可選 search filter(`searchable`,跨欄位 label match)\n *   - 可選 column drag reorder(`onColumnOrderChange` 傳 → 啟 DnD)\n *   - 可選 reset 按鈕(`resettable: boolean` opt-in,header 區 RotateCcw;點擊 `onVisibilityChange({})` 還原全顯示,無獨立 onReset prop)\n *   - Bidirectional bulk toggle(footer button:全可見 → 全部隱藏 / 任一隱藏 → 顯示全部)\n *\n * **Why 抽 primitive**(per Issue 3 Rule-of-3):RoadmapAllInOne + WithBulkActions + 未來 product\n * UI 至少 3 處消費同 panel。重複 hand-craft → 設計語言 drift(已抓到:Roadmap 版無 search /\n * 無 drag / 無 reset,WithBulkActions 版有,語意不一致)。Primitive 把所有 feature 集中,\n * consumer opt-in via props 確保 SSOT。\n *\n * **對齊**:Linear column-visibility-panel pattern / Material X-DataGrid `<GridColumnsPanel>`\n * / Airtable Field-config drawer。\n */\n\nimport * as React from 'react'\nimport { Eye, EyeOff, Lock, GripVertical, Search, RotateCcw, X as XIcon } from 'lucide-react'\nimport { Button } from '@/design-system/components/Button/button'\nimport { ButtonDivider } from '@/design-system/components/Button/button-group'\nimport { Input } from '@/design-system/components/Input/input'\nimport { PopoverHeader, PopoverBody, PopoverFooter, PopoverTitle, PopoverClose } from '@/design-system/components/Popover/popover'\nimport { ItemPrefix, ItemLabel, ItemInlineActionButton, ROW_PADDING_BY_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'\nimport { cn } from '@/lib/utils'\nimport { DndContext, closestCenter, type DragEndEvent } from '@dnd-kit/core'\nimport { SortableContext, useSortable, verticalListSortingStrategy } from '@dnd-kit/sortable'\nimport { CSS } from '@dnd-kit/utilities'\nimport { dragSourceStyle } from '@/design-system/lib/drag-visual'\n\ninterface ColumnVisibilityPanelColumn {\n  /** Column id(stable identifier;對齊 DataTable column.id / accessorKey)*/\n  id: string\n  /** Column header label(human-readable)*/\n  label: string\n}\n\nexport interface DataTableColumnVisibilityPanelProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** 全部可 toggle 欄位(consumer 已過濾掉 system cols 如 __select__)*/\n  columns: ColumnVisibilityPanelColumn[]\n  /** 受控 visibility map(`true` / undefined = visible / `false` = hidden)*/\n  visibility: Record<string, boolean>\n  /** Visibility 變更 callback */\n  onVisibilityChange: (next: Record<string, boolean>) => void\n  /** 受控 column order(若提供啟 DnD reorder) */\n  columnOrder?: string[]\n  /** Order 變更 callback;若提供 → 啟用 drag handle / DnD reorder */\n  onColumnOrderChange?: (next: string[]) => void\n  /** Locked column ids(顯 Lock icon,不可 toggle / 不可 drag)*/\n  lockedIds?: string[]\n  /** 是否啟搜尋 input(預設 false)*/\n  searchable?: boolean\n  /** 是否顯 reset button(任一欄隱藏才顯,onClick 清空 visibility map)*/\n  resettable?: boolean\n  // Issue 3 post-codex audit(2026-05-10):`onClose` prop retired — Radix `PopoverClose asChild`\n  // 已自帶 popover dismiss,沒 concrete consumer 需 callback。Future 若需要再加。\n}\n\nexport const DataTableColumnVisibilityPanel = React.forwardRef<HTMLDivElement, DataTableColumnVisibilityPanelProps>(({\n  columns,\n  visibility,\n  onVisibilityChange,\n  columnOrder,\n  onColumnOrderChange,\n  lockedIds = [],\n  searchable = false,\n  resettable = false,\n  className,\n  ...props\n}, ref) => {\n  const [search, setSearch] = React.useState('')\n  const lockedSet = React.useMemo(() => new Set(lockedIds), [lockedIds])\n  const dndEnabled = !!(columnOrder && onColumnOrderChange)\n\n  // 計算 visible order:用 columnOrder 排,fallback columns 順序。\n  const orderedIds = React.useMemo(() => {\n    if (columnOrder && columnOrder.length > 0) {\n      const colSet = new Set(columns.map((c) => c.id))\n      return columnOrder.filter((id) => colSet.has(id))\n    }\n    return columns.map((c) => c.id)\n  }, [columnOrder, columns])\n\n  const filteredEntries = React.useMemo(() => {\n    return orderedIds\n      .map((id) => columns.find((c) => c.id === id))\n      .filter((c): c is ColumnVisibilityPanelColumn => c != null)\n      .filter((c) => (search ? c.label.toLowerCase().includes(search.toLowerCase()) : true))\n  }, [orderedIds, columns, search])\n\n  const togglableIds = columns.map((c) => c.id).filter((id) => !lockedSet.has(id))\n  const allVisible = togglableIds.every((id) => visibility[id] !== false)\n  const anyHidden = togglableIds.some((id) => visibility[id] === false)\n\n  const handleToggle = (id: string) => {\n    const visible = visibility[id] !== false\n    onVisibilityChange({ ...visibility, [id]: !visible })\n  }\n\n  const handleReset = () => onVisibilityChange({})\n\n  const handleBulkToggle = () => {\n    if (allVisible) {\n      const next: Record<string, boolean> = {}\n      togglableIds.forEach((id) => { next[id] = false })\n      onVisibilityChange(next)\n    } else {\n      onVisibilityChange({})\n    }\n  }\n\n  const handleDragEnd = (e: DragEndEvent) => {\n    if (!dndEnabled) return\n    const { active, over } = e\n    if (!over || active.id === over.id) return\n    const oldIdx = columnOrder!.indexOf(active.id as string)\n    const newIdx = columnOrder!.indexOf(over.id as string)\n    if (oldIdx < 0 || newIdx < 0) return\n    // Locked id 不可被 reorder 動到\n    if (lockedSet.has(columnOrder![oldIdx]) || lockedSet.has(columnOrder![newIdx])) return\n    const next = [...columnOrder!]\n    const [m] = next.splice(oldIdx, 1)\n    next.splice(newIdx, 0, m)\n    onColumnOrderChange!(next)\n  }\n\n  // 2026-07-18 決策16 錯誤史(明記以免再犯):原本這個 panel 是 Fragment + fixed `ScrollArea max-h-72`,\n  //   與 sibling FilterPanel/SortManager(root-div + viewport-aware SurfaceBody)不一致。我給過**兩個都錯**\n  //   的辯護理由 —— (1)「PopoverHeader 用 -mx 負邊距、包 root 會破壞」= 錯(SurfaceHeader 用正 px-loose+border-b,\n  //   無 -mx);(2)「sibling 自刻 header 不用 primitive」= 錯(三 panel 皆消費 SurfaceHeader/PopoverHeader primitive)。\n  //   真正差異只是 body/scroll 策略。multi-agent SSOT consistency 稽核定案:**是 drift,該統一**(fixed 288px cap\n  //   在高螢幕多欄下劣於 sibling 的 viewport-adaptive;且是唯一不能當 template 複製的 panel)。故下方已改成 canonical shape。\n  return (\n    // 決策16 定案(2026-07-18,SSOT consistency 稽核後):對齊 sibling FilterPanel/SortManager 的\n    //   overlay-surface canonical shape —— root `<div flex flex-col h-full min-h-0>`(M25 viewport-aware\n    //   scroll chain)+ viewport-adaptive `PopoverBody`(取代原 fixed `ScrollArea max-h-72`)。三個\n    //   DataTable state-panel 收斂成同一形狀,body 隨視窗高度自適應(高螢幕多欄不再硬卡 288px)。\n    //   寬度仍由 consumer 的 `<PopoverContent w-72>` 提供(panel root w-full 撐滿)。\n    <div ref={ref} className={cn('flex flex-col h-full min-h-0 w-full', className)} {...props}>\n      <PopoverHeader hideClose>\n        <div className=\"flex items-center gap-1 w-full min-w-0\">\n          <PopoverTitle className=\"flex-1\">欄位顯示</PopoverTitle>\n          {resettable && anyHidden && (\n            <>\n              <Button\n                variant=\"text\" size=\"sm\" iconOnly startIcon={RotateCcw}\n                aria-label=\"恢復預設\"\n                onClick={handleReset}\n              />\n              <ButtonDivider />\n            </>\n          )}\n          <PopoverClose asChild>\n            <Button data-dismiss iconOnly dismiss size=\"sm\" startIcon={XIcon} aria-label=\"關閉\" />\n          </PopoverClose>\n        </div>\n      </PopoverHeader>\n      {searchable && (\n        <div className=\"shrink-0 px-[var(--layout-space-loose)] pt-[var(--layout-space-tight)]\">\n          <Input\n            size=\"md\"\n            placeholder=\"搜尋欄位…\"\n            aria-label=\"搜尋欄位\"\n            value={search}\n            onChange={(e) => setSearch(e.target.value)}\n            startIcon={Search}\n          />\n        </div>\n      )}\n      {/* viewport-adaptive body(List-as-region idiom:PopoverBody !px-0 !py-0 撤 chrome padding,\n          內層 py-2 給垂直呼吸、row 自帶 px-loose 水平 padding)。取代原 fixed ScrollArea max-h-72。 */}\n      <PopoverBody className=\"!px-0 !py-0\">\n        <div className=\"py-2 flex flex-col\" style={{ '--item-prefix-slot': '16px' } as React.CSSProperties}>\n          {dndEnabled ? (\n            <DndContext collisionDetection={closestCenter} onDragEnd={handleDragEnd}>\n              <SortableContext\n                items={filteredEntries.map((e) => e.id).filter((id) => !lockedSet.has(id))}\n                strategy={verticalListSortingStrategy}\n              >\n                {filteredEntries.map(({ id, label }) => (\n                  <VisibilityRow\n                    key={id}\n                    id={id}\n                    label={label}\n                    visible={visibility[id] !== false}\n                    locked={lockedSet.has(id)}\n                    draggable\n                    onToggle={() => handleToggle(id)}\n                  />\n                ))}\n              </SortableContext>\n            </DndContext>\n          ) : (\n            filteredEntries.map(({ id, label }) => (\n              <VisibilityRow\n                key={id}\n                id={id}\n                label={label}\n                visible={visibility[id] !== false}\n                locked={lockedSet.has(id)}\n                draggable={false}\n                onToggle={() => handleToggle(id)}\n              />\n            ))\n          )}\n        </div>\n      </PopoverBody>\n      <PopoverFooter className=\"justify-start\">\n        <Button variant=\"tertiary\" size=\"sm\" onClick={handleBulkToggle}>\n          {allVisible ? '全部隱藏' : '顯示全部'}\n        </Button>\n      </PopoverFooter>\n    </div>\n  )\n})\nDataTableColumnVisibilityPanel.displayName = 'DataTableColumnVisibilityPanel'\n\n// VisibilityRow:single column row。Draggable mode → GripVertical handle / static mode → 無 handle。\nfunction VisibilityRow({\n  id, label, visible, locked, draggable, onToggle,\n}: {\n  id: string\n  label: string\n  visible: boolean\n  locked: boolean\n  draggable: boolean\n  onToggle: () => void\n}) {\n  // Conditional hooks 不行 — 永遠呼 useSortable,只是 disabled 時 listeners no-op\n  const sortable = useSortable({ id, disabled: locked || !draggable })\n  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = sortable\n  const style: React.CSSProperties = draggable\n    ? { transform: CSS.Transform.toString(transform), transition, ...dragSourceStyle(isDragging) }\n    : {}\n  return (\n    <div\n      ref={draggable ? setNodeRef : undefined}\n      style={style}\n      className={cn(\n        'flex items-start gap-2 w-full px-[var(--layout-space-loose)]',\n        ROW_PADDING_BY_SIZE.md,\n      )}\n    >\n      <ItemPrefix>\n        {/* 2026-05-18 改 per user「做完」approval:14 → 16 對齊 uiSize.spec.md Icon Tier */}\n        {locked ? (\n          <Lock size={16} className=\"text-fg-muted\" aria-hidden />\n        ) : draggable ? (\n          <ItemInlineActionButton\n            icon={GripVertical}\n            size=\"md\"\n            aria-label=\"拖曳重排\"\n            className=\"cursor-grab active:cursor-grabbing\"\n            {...attributes}\n            {...listeners}\n          />\n        ) : null}\n      </ItemPrefix>\n      <ItemLabel className={locked ? 'text-fg-disabled' : undefined}>{label}</ItemLabel>\n      <ItemInlineActionButton\n        icon={visible ? Eye : EyeOff}\n        size=\"md\"\n        aria-label={visible ? '隱藏此欄' : '顯示此欄'}\n        disabled={locked}\n        onClick={onToggle}\n        className={locked ? 'cursor-not-allowed text-fg-disabled' : ''}\n      />\n    </div>\n  )\n}\n"],"names":["XIcon"],"mappings":"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"}

package/dist/components/DataTable/data-table-filter-group.d.ts

@@ -0,0 +1,51 @@
+import { type SelectOption } from '../../components/Select/select';
+import type { ColumnType } from './column-types';
+import type { Conjunction, FilterCondition, FilterGroup } from './filter-tree';
+import type { DataTableFilterPanelLabels } from './data-table-filter-labels';
+export interface FilterColumn {
+    id: string;
+    label: string;
+    type: ColumnType;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** People pool for person/multiPerson filter picker(對齊 cell-registry meta.people SSOT)*/
+    people?: Array<{
+        name: string;
+        avatarUrl?: string;
+        description?: string;
+    }>;
+    includeTime?: boolean;
+}
+export declare function getDefaultOperator(type?: ColumnType): string;
+export declare const datePrecisionOf: (col: FilterColumn | undefined) => "day" | "ms" | undefined;
+export declare function FilterRow({ index, condition, conjunction, filterableColumns, fieldOptions, onChangeConjunction, onChangeField, onChangeOp, onChangeValue, onRemove, labels, }: {
+    index: number;
+    condition: FilterCondition;
+    conjunction: Conjunction;
+    filterableColumns: FilterColumn[];
+    fieldOptions: SelectOption[];
+    onChangeConjunction: (c: Conjunction) => void;
+    onChangeField: (v: string) => void;
+    onChangeOp: (v: string) => void;
+    onChangeValue: (v: unknown) => void;
+    onRemove: () => void;
+    labels: DataTableFilterPanelLabels;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function GroupBlock({ index, group, rootConjunction, filterableColumns, fieldOptions, onChangeRootConjunction, onChangeGroupConjunction, onChangeCondition, onRemoveCondition, onAddCondition, onRemoveGroup, canAddCondition, labels, }: {
+    index: number;
+    group: FilterGroup;
+    rootConjunction: Conjunction;
+    filterableColumns: FilterColumn[];
+    fieldOptions: SelectOption[];
+    onChangeRootConjunction: (c: Conjunction) => void;
+    onChangeGroupConjunction: (c: Conjunction) => void;
+    onChangeCondition: (condId: string, patch: Partial<FilterCondition>) => void;
+    onRemoveCondition: (condId: string) => void;
+    onAddCondition: () => void;
+    onRemoveGroup: () => void;
+    canAddCondition: boolean;
+    labels: DataTableFilterPanelLabels;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=data-table-filter-group.d.ts.map

package/dist/components/DataTable/data-table-filter-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-table-filter-group.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/data-table-filter-group.tsx"],"names":[],"mappings":"AAiBA,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,0CAA0C,CAAA;AAEpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAQhD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE9E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAA;AAI5E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,UAAU,CAAA;IAChB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACjD,yFAAyF;IACzF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1E,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAUD,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAE5D;AAID,eAAO,MAAM,eAAe,GAAI,KAAK,YAAY,GAAG,SAAS,KAAG,KAAK,GAAG,IAAI,GAAG,SACV,CAAA;AA6CrE,wBAAgB,SAAS,CAAC,EACxB,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAC9D,mBAAmB,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAChF,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,eAAe,CAAA;IAC1B,WAAW,EAAE,WAAW,CAAA;IACxB,iBAAiB,EAAE,YAAY,EAAE,CAAA;IACjC,YAAY,EAAE,YAAY,EAAE,CAAA;IAC5B,mBAAmB,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;IAC7C,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,aAAa,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IACnC,QAAQ,EAAE,MAAM,IAAI,CAAA;IACpB,MAAM,EAAE,0BAA0B,CAAA;CACnC,2CAiEA;AAID,wBAAgB,UAAU,CAAC,EACzB,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAC9D,uBAAuB,EAAE,wBAAwB,EACjD,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EACnE,eAAe,EAAE,MAAM,GACxB,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,WAAW,CAAA;IAClB,eAAe,EAAE,WAAW,CAAA;IAC5B,iBAAiB,EAAE,YAAY,EAAE,CAAA;IACjC,YAAY,EAAE,YAAY,EAAE,CAAA;IAC5B,uBAAuB,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;IACjD,wBAAwB,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;IAClD,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,CAAA;IAC5E,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3C,cAAc,EAAE,MAAM,IAAI,CAAA;IAC1B,aAAa,EAAE,MAAM,IAAI,CAAA;IACzB,eAAe,EAAE,OAAO,CAAA;IACxB,MAAM,EAAE,0BAA0B,CAAA;CACnC,2CAyCA"}

package/dist/components/DataTable/data-table-filter-group.js

@@ -0,0 +1,159 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import { Trash2, Plus } from "lucide-react";
+import { Button } from "../Button/button.js";
+import { Select } from "../Select/select.js";
+import { FieldControlGroup } from "../FieldControlGroup/field-control-group.js";
+import { DEFAULT_OPERATOR, getOperatorSpec, getValueShape, OPERATOR_REGISTRY } from "./filter-operators.js";
+import { FilterValuePicker } from "./data-table-filter-value-picker.js";
+function getOperatorOptions(type, operatorLabels) {
+  const registry = type && OPERATOR_REGISTRY[type] ? OPERATOR_REGISTRY[type] : OPERATOR_REGISTRY.string;
+  return registry.map((op) => ({ value: op.op, label: operatorLabels[op.op] ?? op.label }));
+}
+function getDefaultOperator(type) {
+  return type && DEFAULT_OPERATOR[type] || DEFAULT_OPERATOR.string;
+}
+const datePrecisionOf = (col) => (col == null ? void 0 : col.type) === "date" ? col.includeTime ? "ms" : "day" : void 0;
+function ConjunctionLabel({
+  index,
+  conjunction,
+  onChange,
+  labels
+}) {
+  if (index === 0) {
+    return /* @__PURE__ */ jsx("div", { className: "w-20 shrink-0 text-body text-fg-secondary px-[var(--field-px)] self-center", children: labels.where });
+  }
+  if (index >= 2) {
+    const label = conjunction === "and" ? labels.and : labels.or;
+    return /* @__PURE__ */ jsx("div", { className: "w-20 shrink-0 text-body text-fg-secondary px-[var(--field-px)] self-center", children: label });
+  }
+  return /* @__PURE__ */ jsx("div", { className: "w-20 shrink-0", children: /* @__PURE__ */ jsx(
+    Select,
+    {
+      size: "sm",
+      options: [
+        { value: "and", label: labels.and },
+        { value: "or", label: labels.or }
+      ],
+      value: conjunction,
+      onChange: (v) => onChange(v),
+      minRows: 2,
+      "aria-label": labels.conjunctionAriaLabel
+    }
+  ) });
+}
+function FilterRow({
+  index,
+  condition,
+  conjunction,
+  filterableColumns,
+  fieldOptions,
+  onChangeConjunction,
+  onChangeField,
+  onChangeOp,
+  onChangeValue,
+  onRemove,
+  labels
+}) {
+  const colInfo = filterableColumns.find((c) => c.id === condition.field);
+  const operatorOptions = getOperatorOptions(colInfo == null ? void 0 : colInfo.type, labels.operatorLabels);
+  const hasField = !!condition.field;
+  const opSpec = colInfo ? getOperatorSpec(colInfo.type, condition.op) : null;
+  const valueShape = colInfo && opSpec ? getValueShape(opSpec, colInfo.type, colInfo.includeTime) : null;
+  const hasValueCell = valueShape !== "none";
+  return /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+    /* @__PURE__ */ jsx(ConjunctionLabel, { index, conjunction, onChange: onChangeConjunction, labels }),
+    /* @__PURE__ */ jsxs(FieldControlGroup, { block: true, className: "flex-1 min-w-0", children: [
+      /* @__PURE__ */ jsx(
+        Select,
+        {
+          className: "!w-[var(--data-table-filter-field-width)] flex-shrink-0 [&_.text-fg-muted]:!text-fg-secondary",
+          size: "sm",
+          options: fieldOptions,
+          value: condition.field,
+          onChange: onChangeField,
+          placeholder: labels.fieldPlaceholder,
+          "aria-label": labels.fieldAriaLabel
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        Select,
+        {
+          className: hasValueCell ? "!w-[var(--data-table-filter-op-width)] flex-shrink-0" : "!flex-1 !min-w-0",
+          size: "sm",
+          options: operatorOptions,
+          value: condition.op,
+          onChange: onChangeOp,
+          disabled: !hasField,
+          placeholder: labels.operatorPlaceholder,
+          "aria-label": labels.operatorAriaLabel
+        }
+      ),
+      hasValueCell && /* @__PURE__ */ jsx(
+        FilterValuePicker,
+        {
+          shape: valueShape,
+          value: condition.value,
+          onChange: onChangeValue,
+          colInfo,
+          disabled: !hasField,
+          ariaLabel: labels.filterValueAriaLabel(colInfo == null ? void 0 : colInfo.label),
+          labels,
+          className: "!flex-1 !min-w-0"
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsx(Button, { variant: "text", size: "sm", iconOnly: true, startIcon: Trash2, "aria-label": labels.deleteCondition, onClick: onRemove })
+  ] });
+}
+function GroupBlock({
+  index,
+  group,
+  rootConjunction,
+  filterableColumns,
+  fieldOptions,
+  onChangeRootConjunction,
+  onChangeGroupConjunction,
+  onChangeCondition,
+  onRemoveCondition,
+  onAddCondition,
+  onRemoveGroup,
+  canAddCondition,
+  labels
+}) {
+  return /* @__PURE__ */ jsxs("div", { className: "flex items-start gap-2", children: [
+    /* @__PURE__ */ jsx("div", { className: "pt-2", children: /* @__PURE__ */ jsx(ConjunctionLabel, { index, conjunction: rootConjunction, onChange: onChangeRootConjunction, labels }) }),
+    /* @__PURE__ */ jsxs("div", { className: "flex-1 min-w-0 rounded-md bg-muted p-2 flex flex-col gap-2", children: [
+      group.children.map((cond, cIdx) => /* @__PURE__ */ jsx(
+        FilterRow,
+        {
+          index: cIdx,
+          condition: cond,
+          conjunction: group.conjunction,
+          filterableColumns,
+          fieldOptions,
+          onChangeConjunction: onChangeGroupConjunction,
+          onChangeField: (v) => {
+            const newCol = filterableColumns.find((c) => c.id === v);
+            onChangeCondition(cond.id, { field: v, op: getDefaultOperator(newCol == null ? void 0 : newCol.type), value: "", datePrecision: datePrecisionOf(newCol) });
+          },
+          onChangeOp: (v) => onChangeCondition(cond.id, { op: v, value: "" }),
+          onChangeValue: (v) => onChangeCondition(cond.id, { value: v }),
+          onRemove: () => onRemoveCondition(cond.id),
+          labels
+        },
+        cond.id
+      )),
+      /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between", children: [
+        /* @__PURE__ */ jsx(Button, { variant: "text", size: "sm", startIcon: Plus, onClick: onAddCondition, disabled: !canAddCondition, children: labels.addNestedFilter }),
+        group.children.length === 0 && /* @__PURE__ */ jsx(Button, { variant: "text", size: "sm", startIcon: Trash2, danger: true, onClick: onRemoveGroup, children: labels.removeEmptyGroup })
+      ] })
+    ] })
+  ] });
+}
+export {
+  FilterRow,
+  GroupBlock,
+  datePrecisionOf,
+  getDefaultOperator
+};
+//# sourceMappingURL=data-table-filter-group.js.map