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

package/dist/components/DataTable/data-table-sort-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-table-sort-manager.js","sources":["../../../src/components/DataTable/data-table-sort-manager.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// same-row-mixed-allow: header chrome corner buttons(refresh/close)跟 row inline actions(drag/trash)不在同 row\nimport * as React from 'react'\nimport { Plus, Trash2, X as XIcon, RotateCcw, GripVertical } from 'lucide-react'\nimport type { ColumnDef, SortingState } from '@tanstack/react-table'\nimport { DndContext, closestCenter, type DragEndEvent } from '@dnd-kit/core'\nimport { SortableContext, useSortable, verticalListSortingStrategy } from '@dnd-kit/sortable'\nimport { CSS } from '@dnd-kit/utilities'\nimport { cn } from '@/lib/utils'\nimport { dragSourceStyle, dragHandleCursorClass } from '@/design-system/lib/drag-visual'\nimport { Button } from '@/design-system/components/Button/button'\nimport { Select, type SelectOption } from '@/design-system/components/Select/select'\nimport { SurfaceHeader, SurfaceBody, COMPACT_HEADER_SLOT } from '@/design-system/patterns/overlay-surface/overlay-surface'\nimport { ButtonDivider } from '@/design-system/components/Button/button-group'\nimport { PopoverTitle, PopoverClose } from '@/design-system/components/Popover/popover'\nimport { ItemInlineActionButton } from '@/design-system/patterns/element-anatomy/item-anatomy'\nimport { getColumnId, getColumnLabel } from './lib/column-meta'\n\n/**\n * DataTableSortManager — Notion-style 多欄排序管理 panel\n *\n * 對齊 ref/進階篩選/sort.png 設計:\n *   Header(title + refresh + close)/ list(field + direction + delete + reorder)/\n *   footer(+ 加排序)。\n *\n * Source-of-truth: TanStack `SortingState`(同 `useReactTable.state.sorting`)。\n * 跟 cell click sort 共享 state — single source-of-truth across cell + panel。\n *\n * Reorder:DnD(useSortable + GripVertical handle,見下方 SortRow)——原 MVP ↑/↓ button 已退役。\n */\n\ninterface SortColumn {\n  id: string\n  label: string\n  enableSorting?: boolean\n}\n\nexport interface DataTableSortManagerProps<TData> extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onReset'> {\n  /** 可排序欄位來源(讀 columnDef.header / id);會自動排除 enableSorting=false */\n  columns: ColumnDef<TData, any>[]\n  /** 當前排序 state(TanStack SortingState) */\n  sorting: SortingState\n  /** 排序變更 callback */\n  onSortingChange: (next: SortingState) => void\n  /** Refresh 按鈕點擊(可選 — 重置或外部 refetch) */\n  onReset?: () => void\n  /** Close 按鈕點擊(若有 — 通常是包在 Popover 外層的 close 行為) */\n  onClose?: () => void\n  className?: string\n}\n\nfunction extractColumns<TData>(columns: ColumnDef<TData, any>[]): SortColumn[] {\n  const out: SortColumn[] = []\n  for (const col of columns) {\n    const id = getColumnId(col)\n    if (!id || id === '__select__') continue\n    if (col.enableSorting === false) continue\n    out.push({ id, label: getColumnLabel(col, id), enableSorting: true })\n  }\n  return out\n}\n\nconst DIRECTION_OPTIONS: SelectOption[] = [\n  { value: 'asc', label: '升冪' },\n  { value: 'desc', label: '降冪' },\n]\n\nfunction DataTableSortManagerInner<TData>({\n  columns,\n  sorting,\n  onSortingChange,\n  onReset,\n  onClose,\n  className,\n  ...props\n}: DataTableSortManagerProps<TData>, ref: React.ForwardedRef<HTMLDivElement>) {\n  const sortableColumns = React.useMemo(() => extractColumns(columns), [columns])\n  const fieldOptions: SelectOption[] = React.useMemo(\n    () => sortableColumns.map((c) => ({ value: c.id, label: c.label })),\n    [sortableColumns]\n  )\n\n  const updateAt = (index: number, patch: Partial<{ id: string; desc: boolean }>) => {\n    const next = sorting.map((s, i) => (i === index ? { ...s, ...patch } : s))\n    onSortingChange(next)\n  }\n  const removeAt = (index: number) => {\n    onSortingChange(sorting.filter((_, i) => i !== index))\n  }\n  const handleDragEnd = (event: DragEndEvent) => {\n    const { active, over } = event\n    if (!over || active.id === over.id) return\n    const oldIndex = sorting.findIndex((s) => s.id === active.id)\n    const newIndex = sorting.findIndex((s) => s.id === over.id)\n    if (oldIndex < 0 || newIndex < 0) return\n    const next = [...sorting]\n    const [moved] = next.splice(oldIndex, 1)\n    next.splice(newIndex, 0, moved)\n    onSortingChange(next)\n  }\n  const addSort = () => {\n    const used = new Set(sorting.map((s) => s.id))\n    const firstUnused = sortableColumns.find((c) => !used.has(c.id))\n    if (!firstUnused) return\n    onSortingChange([...sorting, { id: firstUnused.id, desc: false }])\n  }\n\n  // K11 fix(2026-05-04): viewport-aware scroll chain invariant — 詳 overlay-surface.spec.md\n  // 2026-05-23 Phase A.4 Decision 2: w-[480px] → token `--data-table-sort-panel-width`(SSOT in uiSize.css)\n  return (\n    <div\n      ref={ref}\n      className={cn('flex flex-col h-full min-h-0 w-[var(--data-table-sort-panel-width)]', className)}\n      {...props}\n    >\n      {/* Popover 派輕量 chrome — slot 走 COMPACT_HEADER_SLOT(=21,衍生自 PopoverTitle text-body line-box),header 自然 ~45px */}\n      <SurfaceHeader className={COMPACT_HEADER_SLOT}>\n        <PopoverTitle className=\"flex-1\">排序</PopoverTitle>\n        {onReset && sorting.length > 0 && (\n          <>\n            <Button variant=\"text\" size=\"sm\" iconOnly startIcon={RotateCcw} aria-label=\"重置\" onClick={onReset} />\n            {onClose && <ButtonDivider />}\n          </>\n        )}\n        {onClose && (\n          <PopoverClose asChild>\n            <Button data-dismiss iconOnly dismiss size=\"sm\" startIcon={XIcon} aria-label=\"關閉\" onClick={onClose} />\n          </PopoverClose>\n        )}\n      </SurfaceHeader>\n\n      {/* Body — 條件 list + inline 加排序 CTA(對齊 filter panel canonical Q3+Q6,2026-05-04)\n          無條件時 CTA 直接顯示,不需要 Empty 大區塊 */}\n      <SurfaceBody className=\"flex flex-col gap-[var(--layout-space-tight)]\">\n        {sorting.length > 0 && (\n          <DndContext collisionDetection={closestCenter} onDragEnd={handleDragEnd}>\n            <SortableContext items={sorting.map(s => s.id)} strategy={verticalListSortingStrategy}>\n              {sorting.map((sort, index) => {\n                const usedByOthers = new Set(sorting.filter((_, i) => i !== index).map((s) => s.id))\n                const optionsForRow = fieldOptions.filter((o) => !usedByOthers.has(o.value))\n                return (\n                  <SortRow\n                    key={sort.id}\n                    sort={sort}\n                    optionsForRow={optionsForRow}\n                    onChangeId={(v) => updateAt(index, { id: v })}\n                    onChangeDir={(v) => updateAt(index, { desc: v === 'desc' })}\n                    onRemove={() => removeAt(index)}\n                  />\n                )\n              })}\n            </SortableContext>\n          </DndContext>\n        )}\n\n        {/* B1 加排序 → tertiary,parallel filter「加篩選」(root-level CTA 對等視覺重量) */}\n        <div>\n          <Button\n            variant=\"tertiary\"\n            size=\"sm\"\n            startIcon={Plus}\n            onClick={addSort}\n            disabled={sorting.length >= sortableColumns.length}\n          >\n            加排序\n          </Button>\n        </div>\n      </SurfaceBody>\n    </div>\n  )\n}\n\nexport const DataTableSortManager = React.forwardRef(DataTableSortManagerInner) as <TData>(\n  props: DataTableSortManagerProps<TData> & { ref?: React.ForwardedRef<HTMLDivElement> }\n) => React.ReactElement\n;(DataTableSortManager as { displayName?: string }).displayName = 'DataTableSortManager'\n\n// SortRow:DnD-enabled row。GripVertical 為 drag listener handle(對齊 Notion / Airtable 拖曳 idiom)。\nfunction SortRow({\n  sort, optionsForRow, onChangeId, onChangeDir, onRemove,\n}: {\n  sort: { id: string; desc: boolean }\n  optionsForRow: SelectOption[]\n  onChangeId: (v: string) => void\n  onChangeDir: (v: string) => void\n  onRemove: () => void\n}) {\n  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: sort.id })\n  // 對齊 lib/drag-visual.ts SSOT:source dim 用 `--opacity-disabled` token(不 hardcode 0.5)\n  const style: React.CSSProperties = {\n    transform: CSS.Transform.toString(transform),\n    transition,\n    ...dragSourceStyle(isDragging),\n  }\n  // **#5 fix(2026-05-04)**:row 內水平 gap = gap-2 (8px),layoutSpace 規則 5 緊密相關\n  // SurfaceBody row↔row vertical 仍 tight(12)— 不同 row 不緊密\n  return (\n    <div ref={setNodeRef} style={style} className=\"flex items-center gap-2\">\n      <ItemInlineActionButton\n        icon={GripVertical}\n        size=\"sm\"\n        aria-label=\"拖曳重排\"\n        className={dragHandleCursorClass}\n        {...attributes}\n        {...listeners}\n      />\n      <div className=\"flex-1 min-w-0\">\n        <Select size=\"sm\" aria-label=\"排序欄位\" options={optionsForRow} value={sort.id} onChange={onChangeId} />\n      </div>\n      <div className=\"w-32 shrink-0\">\n        {/* minRows={2} — 升冪/降冪只 2 選項,顯式縮 menu 高度(Q5) */}\n        <Select size=\"sm\" aria-label=\"排序方向\" options={DIRECTION_OPTIONS} value={sort.desc ? 'desc' : 'asc'} onChange={onChangeDir} minRows={2} />\n      </div>\n      {/* Trash 用 text Button(Q4 對齊 filter panel)— form-control row 必 Field 同高 */}\n      <Button variant=\"text\" size=\"sm\" iconOnly startIcon={Trash2} aria-label=\"刪除\" onClick={onRemove} />\n    </div>\n  )\n}\n"],"names":["XIcon"],"mappings":"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"}

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

@@ -10,6 +10,12 @@ export interface DataTableProps<TData> extends Omit<React.HTMLAttributes<HTMLDiv
     data: TData[];
     size?: TableSize;
     autoRowHeight?: boolean;
+    /**
+     * 容器高度。預設 '400px'(body 內捲動);'auto' = 自然高度(hug rows);'100%' = fill parent。
+     * L5 分頁(2026-07-06):啟用 `pagination` 且未顯式傳 height 時預設改 'auto' —— 分頁的
+     * 導覽通道是頁碼,再疊 body 內捲動 = 雙重導覽(一頁 20 筆只露 10 筆);對齊 Ant Table
+     * 無預設高度罩、`scroll.y` 顯式選配的慣例。顯式傳 height 照舊尊重(分頁 + 頁內捲動可並用)。
+     */
     height?: string;
     overscan?: number;
     emptyState?: React.ReactNode;
@@ -20,7 +26,7 @@ export interface DataTableProps<TData> extends Omit<React.HTMLAttributes<HTMLDiv
     /**
      * Issue 9 cell error system(2026-05-10)。
      *
-     * Map of `${rowId}:${colId}` → error message(string | string[])。Cell display mode 在 content
+     * Map of `${rowId}:${colId}` → error message(string | string[])。Cell view mode 在 content
      * 下方渲 `text-body text-error` 訊息,gap-1 spacing。Multi-error 用 array → ul / li 分行渲。
      *
      * **使用建議**:
@@ -42,7 +48,8 @@ export interface DataTableProps<TData> extends Omit<React.HTMLAttributes<HTMLDiv
      * Slice D Step 1B(2026-05-10):啟用 spreadsheet-grade interaction overlay。
      * Default false(backward-compat)。Enable 後 hover/editor/selected/range 由
      * `DataTableInteractionLayer` overlay 統一畫,per `.claude/planning/datatable-spreadsheet-rfc.md`。
-     * 漸進切換階段,當前 v1 minimal:hover overlay 1 layer。
+     * 現況:hover ring + selection ring + active editor host 三個 sub-layer
+     * (詳 `data-table-interaction-layer.tsx` 檔頭)。
      */
     experimentalSpreadsheetOverlay?: boolean;
     /**
@@ -58,30 +65,31 @@ export interface DataTableProps<TData> extends Omit<React.HTMLAttributes<HTMLDiv
      * Slice D Step 4(spreadsheet semantics,2026-05-10 user 拍板 + codex Layer B Q2.1 confirm):
      * Excel-like cell selection:click 1=select / click 2=edit / Shift+click=range。
      * Default false opt-in(per codex「DataTable is not a spreadsheet」既有原則 +
-     * data-table.principles.stories.tsx L283-292)。
+     * data-table.principles.stories.tsx「不是試算表」principle story)。
      * Enable 後 inlineEdit cell click 行為:
      *   - Plain click → setSelectedCellId,**不**進 edit mode
      *   - Click on already-selected → enter edit
      *   - Shift+click → extend range from anchor
      *   - Double-click / Enter / F2 / printable(deferred) → enter edit on selected
      *   - Click empty area → clear selection
-     * 視覺:Layer 渲 SelectionRect(solid `--primary` 2px border)+ RangeRect
-     *   (`--primary-subtle` bg fill)— per user「不要 dash 直接實的就好」+ codex Q2.2 token。
+     * 視覺:selection ring 1px `--primary`(layer `CELL_RING_STYLES.selected`);range 視覺
+     *   = cell-bg `--primary-subtle`(`[data-range-cell]` CSS),outer ring 已 2026-05-10 retire
+     *   — per user「不要 dash 直接實的就好」+ codex Q2.2 token。
      */
     spreadsheetMode?: boolean;
-    /** 已選 row IDs(controlled) */
-    selection?: string[];
-    /** 預設選取(uncontrolled) */
-    defaultSelection?: string[];
-    /** Selection 變更 callback */
-    onSelectionChange?: (next: string[]) => void;
+    /** 已選列(controlled)。傳 string[] = include shorthand;傳 DataTableSelection 支援反向選取(all + excluded) */
+    selection?: string[] | DataTableSelection;
+    /** 預設選取(uncontrolled);同上接受 string[] 或 DataTableSelection */
+    defaultSelection?: string[] | DataTableSelection;
+    /** Selection 變更 callback(emit DataTableSelection union;include / all 兩模型) */
+    onSelectionChange?: (next: DataTableSelection) => void;
     /** 是否啟用 selection / 模式;true 等同 'multi' */
     selectable?: boolean | 'single' | 'multi';
     /** Row 是否可選(disabled rows 只 disable checkbox,row 內容正常 render) */
     isRowSelectable?: (row: TData) => boolean;
     /** 取 row 唯一 ID(selection 用);default `(row, index) => String(index)` */
     getRowId?: (row: TData, index: number) => string;
-    /** Checkbox aria-label fallback;default `'Select row'` */
+    /** Checkbox aria-label fallback;default `'選取此列'` */
     getRowAriaLabel?: (row: TData) => string;
     /** Filter 後 hidden selected rows 是否保留(default false,對齊 Material/AG Grid 共識) */
     preserveSelectionOnFilter?: boolean;
@@ -113,8 +121,8 @@ export interface DataTableProps<TData> extends Omit<React.HTMLAttributes<HTMLDiv
      *
      * **v2(2026-05-05)修正**:
      * - Virtualizer × transform:被拖 row 略過 `measureElement`(透過 SortableRowCtx 廣播 active id),避免 transform 干擾測量
-     * - 3-panel mirror sync:每 region 都呼叫 `useSortable({id})`(同 SortableContext 共用 state),mirror 自然取得相同 transform
-     * - Cross-parent drop:nested 全 row 進 SortableContext.items,自訂 collisionDetection 過濾出「同 parent siblings」;cross-parent over → 不觸發,handle cursor `not-allowed`
+     * - 3-panel mirror sync:primary region 呼叫 `useDraggable` + `useDroppable`;mirror region 只 `useDroppable`(v15.4 split),isDragging 由 `useDndContext` active.id 同步 → 三 region 視覺一致
+     * - Cross-parent drop:nested 全 row 各自 `useDroppable`,自訂 collisionDetection 過濾出「同 parent siblings」;cross-parent over → 不觸發,handle cursor `not-allowed`
      *
      * 詳 `data-table.spec.md`「L4 Row drag」段。
      */
@@ -160,7 +168,50 @@ export interface DataTableProps<TData> extends Omit<React.HTMLAttributes<HTMLDiv
      * @param position 'before' | 'after'
      */
     onColumnReorder?: (sourceId: string, targetId: string, position: 'before' | 'after') => void;
+    /**
+     * L5 分頁(2026-07-06):`true` 或 config 物件啟用——內部接 TanStack `getPaginationRowModel`,
+     * 表格下方渲染分頁列(消費 `<Pagination>` 獨立元件,間距 tight、頁碼靠右)。
+     * 啟用時虛擬滾動自動關閉(TanStack 官方:互斥替代策略)。v1 = client-side only。
+     * 詳 data-table.spec.md「L5:分頁」段。
+     */
+    pagination?: boolean | DataTablePaginationOptions;
+}
+/** L5 分頁 config(頁碼 1-based 對外,對齊 Pagination / Ant;詳 data-table.spec.md「L5:分頁」段) */
+export interface DataTablePaginationOptions {
+    /** 每頁筆數(預設 20) */
+    pageSize?: number;
+    /** 每頁筆數選項;傳了才渲染「每頁 N 筆」Select(消費既有 Select size="sm") */
+    pageSizeOptions?: number[];
+    /** 左側「共 N 筆」文字(opt-in,= Ant showTotal 邏輯;數源 = filter 後全集 getPrePaginationRowModel,非 selection all-mode 的 server-side 全集數 M — 那是 consumer 自持) */
+    showTotal?: boolean;
+    /** 當前頁(1-based,controlled;不傳 = uncontrolled) */
+    page?: number;
+    /** uncontrolled 初始頁(1-based,預設 1) */
+    defaultPage?: number;
+    onPageChange?: (page: number) => void;
+    onPageSizeChange?: (pageSize: number) => void;
 }
+/**
+ * L2 選取模型(discriminated union,2026-06-22 對齊 MUI X DataGrid v8
+ * rowSelectionModel { type: include | exclude, ids } + AG Grid selectAll + toggledNodes)。
+ *
+ * - mode==='include' (ids):只選 ids 列(預設;= 載入/可見列逐一選取)。
+ * - mode==='all' (excluded):全資料集(filter 後)選取,扣掉 excluded —— 反向選取(inverted)。
+ *   解決「全選 10k 筆只載 50 筆 → 無法列舉其餘 ID」:all 模式「選取 = 全集 − excluded」,
+ *   任何 toggle 都只是 excluded 的 add/remove,對任意順序封閉、O(1)、不需列舉未載入 ID。
+ *
+ * 計數(consumer):mode==='all' ? M − excluded.length : ids.length(M = consumer 自持的
+ * server-side / filter 後全集筆數;2026-07-13 D1 拍板:DataTable 不收 totalCount prop — DS 內部
+ * 零消費 no-op 已移除,計數本來就全由 consumer 端算)。
+ * 進入 all 模式:consumer 在「選取全部 M」hint 點擊時 setSelection({ mode: 'all', excluded: [] })。
+ */
+export type DataTableSelection = {
+    mode: 'include';
+    ids: string[];
+} | {
+    mode: 'all';
+    excluded: string[];
+};
 export declare const MIN_COLUMN_WIDTH = 80;
 export declare const DataTable: <TData>(props: DataTableProps<TData> & {
     ref?: React.ForwardedRef<HTMLDivElement>;
@@ -170,7 +221,7 @@ export declare const dataTableMeta: {
     readonly family: null;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default", "hover", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly ["bg-muted", "bg-neutral-hover", "bg-surface"];
         readonly fg: readonly ["text-fg-muted", "text-fg-secondary", "text-foreground"];

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

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