@quadrats/common 0.7.7 → 1.1.0

package/table/index.d.ts

@@ -0,0 +1,4 @@
+export * from './typings';
+export * from './constants';
+export * from './utils';
+export { CreateTableOptions, createTable } from './createTable';

package/table/index.js

@@ -0,0 +1,3 @@
+export { MAX_PINNED_COLUMNS_WIDTH_PERCENTAGE, MIN_COLUMN_WIDTH_PERCENTAGE, MIN_COLUMN_WIDTH_PIXEL, TABLE_BODY_TYPE, TABLE_CELL_TYPE, TABLE_DEFAULT_MAX_COLUMNS, TABLE_DEFAULT_MAX_ROWS, TABLE_HEADER_TYPE, TABLE_MAIN_TYPE, TABLE_ROW_TYPE, TABLE_TITLE_TYPE, TABLE_TYPE, TABLE_TYPES } from './constants.js';
+export { calculateTableMinWidth, columnWidthToCSS, getCellLocation, getTableContainers, tryCrossBoundaryMove, tryExtendSelectionHorizontal, tryMoveToAdjacentRow, tryMoveToNextCell } from './utils.js';
+export { createTable } from './createTable.js';

package/table/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@quadrats/common/table",
+  "sideEffects": false,
+  "main": "./index.cjs.js",
+  "module": "./index.js",
+  "typings": "./index.d.ts"
+}

package/table/typings.d.ts

@@ -0,0 +1,70 @@
+import { Ancestor, Editor, QuadratsElement, Text, Withable, WithElementType } from '@quadrats/core';
+export type TableTypeKey = 'table';
+export type TableTitleTypeKey = 'table_title';
+export type TableMainTypeKey = 'table_main';
+export type TableHeaderTypeKey = 'table_header';
+export type TableBodyTypeKey = 'table_body';
+export type TableRowTypeKey = 'table_row';
+export type TableCellTypeKey = 'table_cell';
+export type TableTypes = Record<TableTypeKey | TableTitleTypeKey | TableMainTypeKey | TableHeaderTypeKey | TableBodyTypeKey | TableRowTypeKey | TableCellTypeKey, string>;
+export type ColumnWidth = {
+    type: 'percentage';
+    value: number;
+} | {
+    type: 'pixel';
+    value: number;
+};
+export interface TableElement extends QuadratsElement, WithElementType {
+    treatAsTitle?: boolean;
+    pinned?: boolean;
+    align?: 'left' | 'center' | 'right';
+    columnWidths?: ColumnWidth[];
+    scrollPosition?: {
+        scrollLeft: number;
+        scrollTop: number;
+    };
+    children: {
+        type: string;
+        treatAsTitle?: boolean;
+        pinned?: boolean;
+        align?: 'left' | 'center' | 'right';
+        children: TableElement['children'] | Text[];
+    }[];
+}
+export interface Table<T extends Editor = Editor> extends Withable {
+    types: TableTypes;
+    createTableElement(rows: number, cols: number): QuadratsElement[];
+    insertTable(editor: T, rows: number, cols: number): void;
+    moveToNextCell(editor: Editor, types: TableTypes): void;
+    moveToRowAbove(editor: Editor, types: TableTypes): void;
+    moveToRowBelow(editor: Editor, types: TableTypes): void;
+    extendSelectionLeft(editor: Editor, types: TableTypes): void;
+    extendSelectionRight(editor: Editor, types: TableTypes): void;
+    extendSelectionUp(editor: Editor, types: TableTypes): void;
+    extendSelectionDown(editor: Editor, types: TableTypes): void;
+    isSelectionInTableMain(editor: T): boolean;
+    isSelectionInTableCell(editor: T): boolean;
+    isSelectionInTableRow(editor: T): boolean;
+    isSelectionInTableHeader(editor: T): boolean;
+    isSelectionInTableBody(editor: T): boolean;
+    isSelectionInTableList(editor: T): boolean;
+}
+export interface CellLocation {
+    cellPath: number[];
+    columnIndex: number;
+    row: Ancestor;
+    rowPath: number[];
+    rowIndex: number;
+    container: Ancestor;
+    containerPath: number[];
+    isHeader: boolean;
+    isBody: boolean;
+}
+export interface TableContainers {
+    tableMain: Ancestor;
+    tableMainPath: number[];
+    tableHeader: TableElement | null;
+    tableBody: TableElement | null;
+    tableHeaderIndex: number;
+    tableBodyIndex: number;
+}

package/table/utils.d.ts

@@ -0,0 +1,68 @@
+import { Editor } from '@quadrats/core';
+import { CellLocation, ColumnWidth, TableContainers, TableTypes } from './typings';
+/**
+ * 將 ColumnWidth 轉換為 CSS 可用的字串
+ * @param width - 行寬定義（column width）
+ * @returns CSS 寬度字串（例如 "30%" 或 "200px"）
+ */
+export declare function columnWidthToCSS(width: ColumnWidth): string;
+/**
+ * 計算 table 的總寬度（用於設定 min-width 以支援 overflow）
+ * 此函數會將所有 columnWidths 的百分比和 pixel 值加總：
+ * - percentage: 保留為百分比
+ * - pixel: 直接累加
+ *
+ * @param columnWidths - 行寬陣列（column widths）
+ * @returns 總寬度的 CSS 字串（例如 "calc(50% + 400px)" 或 "100%" 或 "800px"）
+ */
+export declare function calculateTableMinWidth(columnWidths: ColumnWidth[]): string;
+/**
+ * 獲取 cell 的位置資訊
+ * @param editor - Slate editor
+ * @param types - Table types
+ * @param at - 可選的位置，預設使用 editor.selection
+ * @returns cell 的位置資訊，如果找不到則返回 null
+ */
+export declare function getCellLocation(editor: Editor, types: TableTypes, at?: any): CellLocation | null;
+/**
+ * 獲取 table main 和相關容器資訊
+ * @param editor - Slate editor
+ * @param types - Table types
+ * @param containerPath - 當前容器的路徑
+ * @returns table 容器資訊，如果找不到則返回 null
+ */
+export declare function getTableContainers(editor: Editor, types: TableTypes, containerPath: number[]): TableContainers | null;
+/**
+ * 嘗試移動到相鄰列的相同行
+ * @param location - 當前 cell 位置資訊
+ * @param direction - 移動方向（'up' 或 'down'）
+ * @param selectFn - 選擇函數（用於 move 或 extend 模式）
+ * @returns 是否成功移動
+ */
+export declare function tryMoveToAdjacentRow(location: CellLocation, direction: 'up' | 'down', selectFn: (cellPath: number[], position: 'start' | 'end') => void): boolean;
+/**
+ * 嘗試跨容器移動（header <-> body）
+ * @param containers - Table 容器資訊
+ * @param location - 當前 cell 位置資訊
+ * @param direction - 移動方向（'up' 或 'down'）
+ * @param selectFn - 選擇函數（用於 move 或 extend 模式）
+ * @param targetColumn - 目標行索引，預設為保持當前行，設為 0 可強制移動到第一行
+ * @returns 是否成功移動
+ */
+export declare function tryCrossBoundaryMove(containers: TableContainers, location: CellLocation, direction: 'up' | 'down', selectFn: (cellPath: number[], position: 'start' | 'end') => void, targetColumn?: number): boolean;
+/**
+ * 嘗試移動到下一個 cell
+ * @param location - 當前 cell 位置資訊
+ * @param selectFn - 選擇函數
+ * @returns 是否成功移動
+ */
+export declare function tryMoveToNextCell(location: CellLocation, selectFn: (cellPath: number[], position: 'start' | 'end') => void): boolean;
+/**
+ * 嘗試在水平方向擴展選擇（左右移動）
+ * @param editor - Slate editor
+ * @param location - 當前 cell 位置資訊
+ * @param direction - 移動方向（'left' 或 'right'）
+ * @param anchor - 選擇的起點
+ * @returns 是否成功擴展
+ */
+export declare function tryExtendSelectionHorizontal(editor: Editor, location: CellLocation, direction: 'left' | 'right', anchor: any): boolean;

package/table/utils.js

@@ -0,0 +1,243 @@
+import { Editor, Element, Transforms } from '@quadrats/core';
+
+/**
+ * 將 ColumnWidth 轉換為 CSS 可用的字串
+ * @param width - 行寬定義（column width）
+ * @returns CSS 寬度字串（例如 "30%" 或 "200px"）
+ */
+function columnWidthToCSS(width) {
+    if (width.type === 'percentage') {
+        return `${width.value.toFixed(1)}%`;
+    }
+    return `${width.value}px`;
+}
+/**
+ * 計算 table 的總寬度（用於設定 min-width 以支援 overflow）
+ * 此函數會將所有 columnWidths 的百分比和 pixel 值加總：
+ * - percentage: 保留為百分比
+ * - pixel: 直接累加
+ *
+ * @param columnWidths - 行寬陣列（column widths）
+ * @returns 總寬度的 CSS 字串（例如 "calc(50% + 400px)" 或 "100%" 或 "800px"）
+ */
+function calculateTableMinWidth(columnWidths) {
+    if (columnWidths.length === 0) {
+        return '100%';
+    }
+    let totalPercentage = 0;
+    let totalPixels = 0;
+    columnWidths.forEach((width) => {
+        if (width.type === 'percentage') {
+            totalPercentage += width.value;
+        }
+        else {
+            totalPixels += width.value;
+        }
+    });
+    // 只有 percentage，沒有 pixel
+    if (totalPixels === 0) {
+        return `${totalPercentage.toFixed(1)}%`;
+    }
+    // 只有 pixel，沒有 percentage
+    if (totalPercentage === 0) {
+        return `${totalPixels}px`;
+    }
+    // 有 percentage 也有 pixel
+    // 使用 calc() 來結合兩者
+    return `calc(${totalPercentage.toFixed(1)}% + ${totalPixels}px)`;
+}
+/**
+ * 獲取 cell 的位置資訊
+ * @param editor - Slate editor
+ * @param types - Table types
+ * @param at - 可選的位置，預設使用 editor.selection
+ * @returns cell 的位置資訊，如果找不到則返回 null
+ */
+function getCellLocation(editor, types, at) {
+    const cellEntry = Editor.above(editor, {
+        at,
+        match: (n) => Element.isElement(n) && n.type === types.table_cell,
+    });
+    if (!cellEntry)
+        return null;
+    const [, cellPath] = cellEntry;
+    const columnIndex = cellPath[cellPath.length - 1];
+    const rowEntry = Editor.above(editor, {
+        at: cellPath,
+        match: (n) => Element.isElement(n) && n.type === types.table_row,
+    });
+    if (!rowEntry)
+        return null;
+    const [row, rowPath] = rowEntry;
+    const rowIndex = rowPath[rowPath.length - 1];
+    const containerEntry = Editor.above(editor, {
+        at: rowPath,
+        match: (n) => Element.isElement(n) && [types.table_header, types.table_body].includes(n.type),
+    });
+    if (!containerEntry)
+        return null;
+    const [container, containerPath] = containerEntry;
+    return {
+        cellPath,
+        columnIndex,
+        row,
+        rowPath,
+        rowIndex,
+        container,
+        containerPath,
+        isHeader: Element.isElement(container) && container.type === types.table_header,
+        isBody: Element.isElement(container) && container.type === types.table_body,
+    };
+}
+/**
+ * 獲取 table main 和相關容器資訊
+ * @param editor - Slate editor
+ * @param types - Table types
+ * @param containerPath - 當前容器的路徑
+ * @returns table 容器資訊，如果找不到則返回 null
+ */
+function getTableContainers(editor, types, containerPath) {
+    const tableMainEntry = Editor.above(editor, {
+        at: containerPath,
+        match: (n) => Element.isElement(n) && n.type === types.table_main,
+    });
+    if (!tableMainEntry)
+        return null;
+    const [tableMain, tableMainPath] = tableMainEntry;
+    const tableHeader = tableMain.children.find((child) => Element.isElement(child) && child.type === types.table_header);
+    const tableBody = tableMain.children.find((child) => Element.isElement(child) && child.type === types.table_body);
+    const tableHeaderIndex = tableHeader ? tableMain.children.findIndex((child) => child === tableHeader) : -1;
+    const tableBodyIndex = tableBody ? tableMain.children.findIndex((child) => child === tableBody) : -1;
+    return {
+        tableMain,
+        tableMainPath,
+        tableHeader,
+        tableBody,
+        tableHeaderIndex,
+        tableBodyIndex,
+    };
+}
+/**
+ * 嘗試移動到相鄰列的相同行
+ * @param location - 當前 cell 位置資訊
+ * @param direction - 移動方向（'up' 或 'down'）
+ * @param selectFn - 選擇函數（用於 move 或 extend 模式）
+ * @returns 是否成功移動
+ */
+function tryMoveToAdjacentRow(location, direction, selectFn) {
+    const { container, containerPath, rowIndex, columnIndex } = location;
+    const targetRowIndex = direction === 'up' ? rowIndex - 1 : rowIndex + 1;
+    // 嘗試在當前容器中移動
+    if (targetRowIndex >= 0 && targetRowIndex < container.children.length) {
+        const targetRow = container.children[targetRowIndex];
+        if (Element.isElement(targetRow)) {
+            const targetColumnIndex = Math.min(columnIndex, targetRow.children.length - 1);
+            const targetCellPath = [...containerPath, targetRowIndex, targetColumnIndex];
+            selectFn(targetCellPath, direction === 'up' ? 'start' : 'end');
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * 嘗試跨容器移動（header <-> body）
+ * @param containers - Table 容器資訊
+ * @param location - 當前 cell 位置資訊
+ * @param direction - 移動方向（'up' 或 'down'）
+ * @param selectFn - 選擇函數（用於 move 或 extend 模式）
+ * @param targetColumn - 目標行索引，預設為保持當前行，設為 0 可強制移動到第一行
+ * @returns 是否成功移動
+ */
+function tryCrossBoundaryMove(containers, location, direction, selectFn, targetColumn) {
+    const { columnIndex, isHeader, isBody } = location;
+    const { tableMainPath, tableHeader, tableBody, tableHeaderIndex, tableBodyIndex } = containers;
+    // 從 body 向上移動到 header
+    if (direction === 'up' && isBody && tableHeader && Element.isElement(tableHeader)) {
+        const lastRowIndex = tableHeader.children.length - 1;
+        const lastRow = tableHeader.children[lastRowIndex];
+        if (Element.isElement(lastRow)) {
+            const targetColumnIndex = targetColumn !== undefined ? targetColumn : Math.min(columnIndex, lastRow.children.length - 1);
+            const targetCellPath = [...tableMainPath, tableHeaderIndex, lastRowIndex, targetColumnIndex];
+            selectFn(targetCellPath, 'start');
+            return true;
+        }
+    }
+    // 從 header 向下移動到 body
+    if (direction === 'down' && isHeader && tableBody && Element.isElement(tableBody)) {
+        const firstRow = tableBody.children[0];
+        if (Element.isElement(firstRow)) {
+            const targetColumnIndex = targetColumn !== undefined ? targetColumn : Math.min(columnIndex, firstRow.children.length - 1);
+            const targetCellPath = [...tableMainPath, tableBodyIndex, 0, targetColumnIndex];
+            // Tab 導航時使用 'start'，上下鍵導航時使用 'end'
+            const position = targetColumn === 0 ? 'start' : 'end';
+            selectFn(targetCellPath, position);
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * 嘗試移動到下一個 cell
+ * @param location - 當前 cell 位置資訊
+ * @param selectFn - 選擇函數
+ * @returns 是否成功移動
+ */
+function tryMoveToNextCell(location, selectFn) {
+    const { cellPath, row, rowPath, container, containerPath, rowIndex } = location;
+    const currentColumnIndex = cellPath[cellPath.length - 1];
+    const nextColumnIndex = currentColumnIndex + 1;
+    if (nextColumnIndex < row.children.length) {
+        const targetCellPath = [...rowPath, nextColumnIndex];
+        selectFn(targetCellPath, 'start');
+        return true;
+    }
+    const nextRowIndex = rowIndex + 1;
+    if (nextRowIndex < container.children.length) {
+        const nextRow = container.children[nextRowIndex];
+        if (Element.isElement(nextRow) && nextRow.children.length > 0) {
+            const targetCellPath = [...containerPath, nextRowIndex, 0];
+            selectFn(targetCellPath, 'start');
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * 嘗試在水平方向擴展選擇（左右移動）
+ * @param editor - Slate editor
+ * @param location - 當前 cell 位置資訊
+ * @param direction - 移動方向（'left' 或 'right'）
+ * @param anchor - 選擇的起點
+ * @returns 是否成功擴展
+ */
+function tryExtendSelectionHorizontal(editor, location, direction, anchor) {
+    var _a;
+    const { cellPath, columnIndex, row, rowPath } = location;
+    const focus = (_a = editor.selection) === null || _a === void 0 ? void 0 : _a.focus;
+    if (!focus)
+        return false;
+    const isLeftDirection = direction === 'left';
+    const isAtBoundary = isLeftDirection ? columnIndex === 0 : columnIndex >= row.children.length - 1;
+    // 如果已經在邊界，嘗試擴展到該 cell 的開頭或結尾
+    if (isAtBoundary) {
+        const boundaryPoint = isLeftDirection ? Editor.start(editor, cellPath) : Editor.end(editor, cellPath);
+        // 只有當 focus 還沒到邊界時才移動
+        const shouldMove = isLeftDirection
+            ? focus.offset > boundaryPoint.offset || focus.path.length !== boundaryPoint.path.length
+            : focus.offset < boundaryPoint.offset || focus.path.length !== boundaryPoint.path.length;
+        if (shouldMove) {
+            Transforms.select(editor, { anchor, focus: boundaryPoint });
+        }
+        return true;
+    }
+    // 找到目標 cell
+    const targetColumnIndex = isLeftDirection ? columnIndex - 1 : columnIndex + 1;
+    const targetCellPath = [...rowPath, targetColumnIndex];
+    // 根據方向選擇目標點（左邊用 end，右邊用 start）
+    const targetPoint = isLeftDirection ? Editor.end(editor, targetCellPath) : Editor.start(editor, targetCellPath);
+    // 保持 anchor 不變，移動 focus
+    Transforms.select(editor, { anchor, focus: targetPoint });
+    return true;
+}
+
+export { calculateTableMinWidth, columnWidthToCSS, getCellLocation, getTableContainers, tryCrossBoundaryMove, tryExtendSelectionHorizontal, tryMoveToAdjacentRow, tryMoveToNextCell };