@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

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

@@ -0,0 +1,181 @@
+import * as React from 'react';
+import { type ColumnDef, type TableOptions } from '@tanstack/react-table';
+import { type VariantProps } from 'class-variance-authority';
+declare const dataTableVariants: (props?: ({
+    bordered?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type TableSize = 'sm' | 'md' | 'lg';
+export interface DataTableProps<TData> extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>, VariantProps<typeof dataTableVariants> {
+    columns: ColumnDef<TData, any>[];
+    data: TData[];
+    size?: TableSize;
+    autoRowHeight?: boolean;
+    height?: string;
+    overscan?: number;
+    emptyState?: React.ReactNode;
+    enableHover?: boolean;
+    estimateRowHeight?: number;
+    tableOptions?: Partial<Omit<TableOptions<TData>, 'data' | 'columns' | 'getCoreRowModel'>>;
+    rowActions?: (row: TData) => React.ReactNode;
+    /**
+     * Issue 9 cell error system(2026-05-10)。
+     *
+     * Map of `${rowId}:${colId}` → error message(string | string[])。Cell display mode 在 content
+     * 下方渲 `text-body text-error` 訊息,gap-1 spacing。Multi-error 用 array → ul / li 分行渲。
+     *
+     * **使用建議**:
+     *   - 搭配 `autoRowHeight` prop:cell error 訊息 wrap → row 自動拉高吸收。fixed 高 row 模式
+     *     error 訊息會被裁切(consumer 應 set autoRowHeight=true 給有 error 的 use case)。
+     *   - Edit cell 自動 clear 自己的 error(展開 portal Field 時消失,新值 commit 由 consumer
+     *     onCellCommit 驗證後決定 set / clear)。
+     *   - aria-describedby:cell wrapper 接 error message id,AT 讀 cell 內容後讀 error。
+     *
+     * 對齊 AG Grid `cellClassRules='ag-cell-error'` + Material X-DataGrid `errorMessage` cell prop +
+     * Airtable record validation idiom。
+     */
+    cellErrors?: Record<string, string | string[]>;
+    pinnedLeftColumns?: string[];
+    pinnedRightColumns?: string[];
+    /** Inline edit 視覺模式：body cell 間加垂直分隔線，select 類欄位顯示指示器 */
+    inlineEdit?: boolean;
+    /**
+     * 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。
+     */
+    experimentalSpreadsheetOverlay?: boolean;
+    /**
+     * Slice D Step 3.2(2026-05-10):啟用 ActiveEditorController portal Field。
+     * Default false(backward-compat)。
+     * Enable 後 active edit cell 不 render Field inline,改 portal 進 overlay layer
+     * (per RFC Contract 8 「one geometry, two paint owners」)。
+     * 當前 scaffold:prop 已收,functional portal logic Step 3.3 實作。
+     * Per codex Q-7 string-first canary:string cell first,picker types 漸進。
+     */
+    experimentalActiveEditorController?: boolean;
+    /**
+     * 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)。
+     * 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。
+     */
+    spreadsheetMode?: boolean;
+    /** 已選 row IDs(controlled) */
+    selection?: string[];
+    /** 預設選取(uncontrolled) */
+    defaultSelection?: string[];
+    /** Selection 變更 callback */
+    onSelectionChange?: (next: string[]) => 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'` */
+    getRowAriaLabel?: (row: TData) => string;
+    /** Filter 後 hidden selected rows 是否保留(default false,對齊 Material/AG Grid 共識) */
+    preserveSelectionOnFilter?: boolean;
+    /** 欄位顯隱(controlled),Record<columnId, boolean>;true / undefined = 顯示 */
+    columnVisibility?: Record<string, boolean>;
+    /** 預設顯隱(uncontrolled) */
+    defaultColumnVisibility?: Record<string, boolean>;
+    /** 顯隱變更 callback */
+    onColumnVisibilityChange?: (next: Record<string, boolean>) => void;
+    /** 啟用多欄排序(shift+click 加 secondary;單擊仍 replace);default true,對齊 AG Grid / Material */
+    enableMultiSort?: boolean;
+    /** Cell ⌄ menu「Filter by this」點擊,emit columnId 讓 consumer 開 global filter panel + prefill。
+     *  對齊 ClickUp / Airtable / Notion 派 — filter 永遠 global,不 per-cell inline。 */
+    onColumnFilterTrigger?: (columnId: string) => void;
+    /**
+     * Cell value commit callback。User 編完(blur/Enter/select-option)→ 觸發本 callback。
+     * Consumer 自管 data update + persistence。
+     * 啟用條件:該 column `meta.editable` 為 true 或 fn 回傳 true。詳 `column-types.ts`。
+     */
+    onCellCommit?: (rowId: string, columnId: string, value: unknown) => void;
+    /**
+     * 啟用 row drag reorder。為 true 時,row 最左出 GripVertical handle(hover-revealed),
+     * 拖曳改 default order via `onRowReorder` callback。
+     *
+     * Sort × Drag 互斥:`sorting.length > 0` 時 drag handle 視覺 disabled + Tooltip
+     * 「排序中無法拖曳,清除排序後可重排」。對齊 Notion / Airtable 共識。
+     *
+     * **必填 `getRowId`**:enableRowDrag 為 true 時 consumer 必傳 `getRowId`,用穩定 row identity 作 dnd source / target id。否則 dnd 用 row.index 會在 reorder 後錯位(runtime 不會 throw,但 reorder 行為不正確)。
+     *
+     * **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`
+     *
+     * 詳 `data-table.spec.md`「L4 Row drag」段。
+     */
+    enableRowDrag?: boolean;
+    /**
+     * Row reorder callback。User 拖曳完成觸發。
+     * @param sourceId 拖曳的 row id
+     * @param targetId 放下的目標 row id
+     * @param position 'before' | 'after' — 放在 target 前 OR 後
+     */
+    onRowReorder?: (sourceId: string, targetId: string, position: 'before' | 'after') => void;
+    /**
+     * 啟用全表 column resize(2026-05-06 v11):
+     * - `true`: 所有 data columns 全 fixed width,header 右邊出現 resize handle(hover 顯色 +
+     *   cursor:col-resize),user 拖拉調整 column width。System columns(checkbox / drag handle /
+     *   row actions)永遠 fixed,不在 resize 集合。
+     * - `false`(default): 所有 data columns 全 flex-grow:1 均分剩餘寬度。
+     *
+     * **二選一 canonical**(對齊 Notion / Airtable / Linear product UI 共識)— 不支援 per-column
+     * mixed,簡單明確。Min width 預設 80px,consumer 透過 `columnDef.minSize` override。
+     */
+    enableColumnResize?: boolean;
+    /**
+     * Column resize callback。User 拖完一輪觸發(commit-on-pointerup,非 live)。Consumer 收到
+     * 自管 width persistence(localStorage / URL / API)— DS 不持久化(對齊「DS 不包全域 provider」原則)。
+     * @param columnId 被 resize 的 column id
+     * @param width 最終 width(px)
+     */
+    onColumnResize?: (columnId: string, width: number) => void;
+    /**
+     * 啟用全表 column reorder(2026-05-06 v11):
+     * - `true`: 所有 data column header 可拖曳重排,DragOverlay portal 顯示 ghost
+     * - `false`(default): 不啟用
+     *
+     * 使用 `columnDef.meta.locked = true` 標示鎖定欄(無 grab cursor、不啟動 drag、被拖過不顯
+     * drop indicator)。對齊 Notion / Linear locked column canonical。
+     */
+    enableColumnReorder?: boolean;
+    /**
+     * Column reorder callback。
+     * @param sourceId source column id
+     * @param targetId target column id
+     * @param position 'before' | 'after'
+     */
+    onColumnReorder?: (sourceId: string, targetId: string, position: 'before' | 'after') => void;
+}
+export declare const MIN_COLUMN_WIDTH = 80;
+export declare const DataTable: <TData>(props: DataTableProps<TData> & {
+    ref?: React.ForwardedRef<HTMLDivElement>;
+}) => React.ReactElement;
+export declare const dataTableMeta: {
+    readonly component: "DataTable";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "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"];
+        readonly ring: readonly [];
+    };
+};
+export { dataTableVariants };
+//# sourceMappingURL=data-table.d.ts.map

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

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