@synopackageland/ui 0.20.3 → 0.20.4

package/dist/grid-core/renderer/layout.d.ts

@@ -0,0 +1,129 @@
+import { CoordinateManager } from '../coordinate';
+import { CombinedSelection } from '../selection';
+import { IGridTheme } from '../theme';
+import { IActiveCellBound, ICellItem, IColumnFreezeState, IColumnResizeState, IDragState, IGridColumn, ILinearRow, IMouseState, IRectangle, IRowControlItem, IScrollState } from '../types';
+export interface IVisibleRegion {
+    startRowIndex: number;
+    stopRowIndex: number;
+    startColumnIndex: number;
+    stopColumnIndex: number;
+}
+/** Rows and columns that intersect the viewport (one extra row below for partial rows). */
+export declare const getVisibleRegion: (coordInstance: CoordinateManager, scrollState: Pick<IScrollState, "scrollTop" | "scrollLeft">) => IVisibleRegion;
+/** What the host's `drawCell` gets: the cell rect (in canvas px) and its state. */
+export interface ICellDrawContext extends IRectangle {
+    theme: IGridTheme;
+    /** Data row index. */
+    rowIndex: number;
+    columnIndex: number;
+    isActive: boolean;
+}
+export type IGridIconKind = 'drag' | 'expand' | 'add' | 'primary' | 'description' | 'column';
+export interface IIconDrawContext {
+    kind: IGridIconKind;
+    x: number;
+    y: number;
+    size: number;
+    theme: IGridTheme;
+    /** For `column` and `description` icons. */
+    column?: IGridColumn;
+}
+export interface IGridRenderProps {
+    coordInstance: CoordinateManager;
+    scrollState: IScrollState;
+    visibleRegion: IVisibleRegion;
+    theme: IGridTheme;
+    columns: IGridColumn[];
+    /** Canvas height in CSS px (container height plus any footer). */
+    height: number;
+    mouseState: IMouseState;
+    selection: CombinedSelection;
+    isSelecting: boolean;
+    isEditing: boolean;
+    /** Selecting, dragging, resizing or freezing: hides hover tints. */
+    isInteracting: boolean;
+    activeCell: ICellItem | null;
+    activeCellBound: IActiveCellBound | null;
+    rowControls: IRowControlItem[];
+    rowControlPaddingX?: number;
+    /** Show the row number until the row is hovered or checked. */
+    rowIndexVisible?: boolean;
+    highlightedRowIndex?: number | null;
+    dragState: IDragState;
+    columnResizeState: IColumnResizeState;
+    hoveredColumnResizeIndex: number;
+    columnFreezeState: IColumnFreezeState;
+    isColumnResizable?: boolean;
+    isColumnHeaderMenuVisible?: boolean;
+    isColumnAppendEnable?: boolean;
+    isMultiSelectionEnable?: boolean;
+    isFilling?: boolean;
+    isFillEnabled?: boolean;
+    getLinearRow?: (index: number) => ILinearRow;
+    real2RowIndex?: (index: number) => number;
+    drawCell: (ctx: CanvasRenderingContext2D, cell: ICellDrawContext) => void;
+    drawIcon?: (ctx: CanvasRenderingContext2D, icon: IIconDrawContext) => void;
+    /** Change to force the cached cell content to redraw (data changed). */
+    forceRenderFlag?: unknown;
+}
+interface IResolvedProps extends IGridRenderProps {
+    getLinearRow: (index: number) => ILinearRow;
+    real2RowIndex: (index: number) => number;
+    shouldRerender?: boolean;
+}
+interface ICellProps extends ICellDrawContext {
+    fill: string;
+}
+interface IRowHeaderProps extends IRectangle {
+    displayIndex: string;
+    isHover: boolean;
+    isChecked: boolean;
+}
+interface IAppendRowProps extends IRectangle {
+    isHover: boolean;
+}
+type IRenderRegion = 'freeze' | 'other';
+/** Cell and row-header draw lists for the frozen or the scrolling region. */
+export declare const calcCells: (p: IResolvedProps, region: IRenderRegion) => {
+    cellPropList: ICellProps[];
+    rowHeaderPropList: IRowHeaderProps[];
+    appendRowList: IAppendRowProps[];
+};
+export declare const drawRowHeader: (ctx: CanvasRenderingContext2D, props: IRowHeaderProps, p: IResolvedProps) => void;
+/** Backgrounds and grid lines on the main canvas; cell content on the cache canvas when `shouldRerender`. */
+export declare const drawCells: (mainCtx: CanvasRenderingContext2D, cacheCtx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+/** The active cell: cell background, a 1 px neutral ring with radius 2 (Teable style), and its content on top. */
+export declare const drawActiveCell: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+/** While dragging the fill handle: a tinted box over the target rows only, above or below the range. */
+export declare const drawFillPreview: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+/** A 5 px square (7 px with its stroke) on the range's bottom-right corner; hidden while editing or selecting. */
+export declare const drawFillHandler: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+export declare const drawColumnHeader: (ctx: CanvasRenderingContext2D, props: IRectangle & {
+    column: IGridColumn;
+    fill?: string;
+    hasMenu?: boolean;
+}, p: IResolvedProps) => void;
+/** The corner above the row headers, with the select-all checkbox. */
+export declare const drawGridHeader: (ctx: CanvasRenderingContext2D, props: IRectangle & {
+    isChecked: boolean;
+}, p: IResolvedProps) => void;
+export declare const drawColumnHeaders: (ctx: CanvasRenderingContext2D, p: IResolvedProps, region: IRenderRegion) => void;
+export declare const drawAppendColumn: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+/** The bar on the column edge being hovered or resized. */
+export declare const drawColumnResizeHandler: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+/** Ghost of the dragged column following the pointer, and a 2 px drop line. */
+export declare const drawColumnDraggingRegion: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+/** Ghost band of the dragged row and a 2 px drop line. */
+export declare const drawRowDraggingRegion: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+export declare const drawColumnFreezeHandler: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+/** Line after the frozen columns; a soft shadow once the body scrolls under it. */
+export declare const drawFreezeRegionDivider: (ctx: CanvasRenderingContext2D, p: IResolvedProps) => void;
+/** Whether cached cell content must be redrawn. */
+export declare const computeShouldRerender: (current: IGridRenderProps, last?: IGridRenderProps) => boolean;
+/**
+ * Paints one frame. `mainCanvas` is the visible canvas; `cacheCanvas` is an
+ * offscreen canvas that keeps cell content between frames. Pass the previous
+ * frame's props as `lastProps` so unchanged content is not redrawn.
+ */
+export declare const drawGrid: (mainCanvas: HTMLCanvasElement, cacheCanvas: HTMLCanvasElement, props: IGridRenderProps, lastProps?: IGridRenderProps, pixelRatio?: number) => void;
+export {};

package/dist/grid-core/selection-controller.d.ts

@@ -0,0 +1,62 @@
+import { CombinedSelection } from './selection';
+import { RowControlType, SelectableType, ICellItem, ILinearRow, IMouseState, IPosition, IRange } from './types';
+/** Modifier keys of a pointer event. Pass the platform's command key as `metaKey` (Cmd on macOS, Ctrl elsewhere). */
+export interface IPointerModifiers {
+    shiftKey: boolean;
+    metaKey: boolean;
+}
+export interface ISelectionControllerOptions {
+    /** Data row count, for the corner checkbox. */
+    getPureRowCount: () => number;
+    selectable?: SelectableType;
+    isMultiSelectionEnable?: boolean;
+    /** With `selectable: Row`, whether clicking a cell toggles its row. */
+    isRowClickSelectionEnabled?: boolean;
+    getLinearRow?: (index: number) => ILinearRow;
+    /** Called once per change of the selection or the active cell. */
+    onChange?: (state: {
+        selection: CombinedSelection;
+        activeCell: ICellItem | null;
+    }) => void;
+    onRowControlClick?: (rowIndex: number, type: RowControlType, checked: boolean) => void;
+    /** Rows selected in one go (Shift or the corner checkbox), so the host can load ids it has not fetched. */
+    onRowRangeSelected?: (ranges: IRange[]) => void;
+}
+/**
+ * Pointer rules for the selection, as a plain state holder (Teable's
+ * `useSelection` without React). Selection starts on pointerdown on a cell;
+ * header, checkbox and corner selection happen on click.
+ *
+ * - Shift+click on a cell keeps the anchor and moves the head; Cmd+click is a plain click.
+ * - Column header: click selects, Shift extends from the first selected column, Cmd toggles.
+ * - Row checkbox: toggles; Shift selects the run from the last toggled row.
+ * - Corner checkbox: selects all rows; a second click clears.
+ */
+export declare class SelectionController {
+    selection: CombinedSelection;
+    activeCell: ICellItem | null;
+    isSelecting: boolean;
+    private prevSelectedRowIndex;
+    private readonly options;
+    constructor(options: ISelectionControllerOptions);
+    private get selectable();
+    private get isMultiSelectionEnable();
+    private getLinearRow;
+    /** Replaces the selection and/or the active cell; notifies once if either changed. */
+    update(next: {
+        selection?: CombinedSelection;
+        activeCell?: ICellItem | null;
+    }): void;
+    /** Clears selection, active cell and the drag-select state (click outside the grid). */
+    reset(): void;
+    onSelectionStart(event: IPointerModifiers, mouseState: IMouseState): void;
+    /** Moves the head to the cell under the pointer while drag-selecting. Positions above or left of the grid clamp to 0. */
+    onSelectionChange(mouseState: Pick<IMouseState, 'rowIndex' | 'columnIndex'>): void;
+    onSelectionEnd(): void;
+    onSelectionClick(event: IPointerModifiers, mouseState: IMouseState): void;
+    /**
+     * Right click: keeps the selection when the pointer is inside it, otherwise
+     * selects the cell or column under the pointer; then calls `callback`.
+     */
+    onSelectionContextMenu(mouseState: IMouseState, callback: (selection: CombinedSelection, position: IPosition) => void): void;
+}

package/dist/grid-core/selection.d.ts

@@ -0,0 +1,35 @@
+import { SelectionRegionType, IRange } from './types';
+/**
+ * One selection of a single kind. Immutable: every change returns a new object,
+ * so a host can hold it in a `shallowRef` and compare by identity.
+ *
+ * - Cells: `ranges = [anchor, head]`, each `[column, row]`, one rectangle.
+ * - Rows / Columns: `ranges` is a list of `[from, to]` index runs.
+ *
+ * Select-all is a Cells selection from `[0, 0]` to the last cell; the corner
+ * checkbox is a Rows selection of every row.
+ */
+export declare class CombinedSelection {
+    readonly type: SelectionRegionType;
+    readonly ranges: IRange[];
+    constructor(type?: SelectionRegionType, ranges?: IRange[]);
+    get isColumnSelection(): boolean;
+    get isRowSelection(): boolean;
+    get isCellSelection(): boolean;
+    get isNoneSelection(): boolean;
+    reset(): CombinedSelection;
+    set(type: SelectionRegionType, ranges: IRange[]): CombinedSelection;
+    setRanges(ranges: IRange[]): CombinedSelection;
+    private isOverlap;
+    /** Adds a run (rows/columns, merged with any it overlaps) or moves the head (cells). */
+    expand(range: IRange): CombinedSelection;
+    /** Toggles a run (rows/columns; empty result clears) or moves the head (cells). */
+    merge(range: IRange): CombinedSelection;
+    flatten(): number[];
+    /** Runs merged and sorted, or the cell rectangle as `[topLeft, bottomRight]`. */
+    serialize(): IRange[];
+    /** For cells, whether `[column, row]` is inside the rectangle; for rows/columns, whether the run is inside. */
+    includes(range?: IRange): boolean;
+    equals(comparisonRanges: IRange[]): boolean;
+}
+export declare const emptySelection: CombinedSelection;

package/dist/grid-core/theme.d.ts

@@ -0,0 +1,81 @@
+export interface IGridTheme {
+    staticWhite: string;
+    staticBlack: string;
+    iconFgCommon: string;
+    iconBgSelected: string;
+    iconFgSelected: string;
+    iconSizeXS: number;
+    iconSizeSM: number;
+    iconSizeMD: number;
+    iconSizeLG: number;
+    fontSizeXXS: number;
+    fontSizeXS: number;
+    fontSizeSM: number;
+    fontSizeMD: number;
+    fontSizeLG: number;
+    fontFamily: string;
+    cellBg: string;
+    cellBgHovered: string;
+    cellBgSelected: string;
+    cellBgLoading: string;
+    cellLineColor: string;
+    /** The active cell's ring: 1 px, neutral (Teable style). */
+    cellLineColorActived: string;
+    cellTextColor: string;
+    cellTextColorHighlight: string;
+    cellOptionBg: string;
+    cellOptionBgHighlight: string;
+    cellOptionTextColor: string;
+    groupHeaderBgPrimary: string;
+    groupHeaderBgSecondary: string;
+    groupHeaderBgTertiary: string;
+    columnHeaderBg: string;
+    columnHeaderBgHovered: string;
+    columnHeaderBgSelected: string;
+    columnHeaderNameColor: string;
+    columnResizeHandlerBg: string;
+    columnDraggingPlaceholderBg: string;
+    rowHeaderTextColor: string;
+    appendRowBg: string;
+    appendRowBgHovered: string;
+    avatarBg: string;
+    avatarTextColor: string;
+    scrollBarBg: string;
+    interactionLineColorCommon: string;
+    interactionLineColorHighlight: string;
+    /** 'light' or 'dark'; renderers that cache by theme include it in the key. */
+    themeKey: string;
+}
+export type IGridThemeColorKey = {
+    [K in keyof IGridTheme]: IGridTheme[K] extends string ? K : never;
+}[keyof IGridTheme];
+/** Teable's light theme values. */
+export declare const teableGridTheme: IGridTheme;
+/**
+ * Which UI library token feeds each theme colour. Task 08 owns the token
+ * values; this only names them. The active-cell ring uses the text colour for a
+ * 1 px neutral ring, as in Teable.
+ */
+export declare const GRID_THEME_TOKENS: Record<Exclude<IGridThemeColorKey, 'themeKey' | 'fontFamily'>, string>;
+export declare const GRID_FONT_TOKENS: {
+    readonly fontFamily: "--ui-font-sans";
+    readonly fontSizeSM: "--ui-font-size";
+    readonly fontSizeXS: "--ui-font-size-sm";
+};
+/** Looks up a CSS custom property, returning an empty string or undefined when it is not set. */
+export type IGridTokenSource = (token: string) => string | undefined;
+/**
+ * Builds the theme from token values. Colours come back as the source resolved
+ * them; missing tokens keep Teable's value.
+ */
+export declare const createGridTheme: (source: IGridTokenSource, overrides?: Partial<IGridTheme>) => IGridTheme;
+/**
+ * Token source that reads computed tokens on `el` and resolves each colour to
+ * an `rgb()`/`rgba()` string through a hidden probe, so canvas never sees
+ * `var()` or `color-mix()`. Call `dispose` when done; re-read on theme change.
+ */
+export declare const cssTokenSource: (el: Element) => IGridTokenSource & {
+    dispose: () => void;
+};
+/** Theme from the tokens in effect on `el` (light or dark, by whatever the page sets). */
+export declare const readGridTheme: (el: Element, overrides?: Partial<IGridTheme>) => IGridTheme;

package/dist/grid-core/types.d.ts

@@ -0,0 +1,178 @@
+export interface IPosition {
+    x: number;
+    y: number;
+}
+export interface IRectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A pointer position with the row and column under it. Row -1 is the column header, column -1 the row header, column -2 the append column; -Infinity is above or left of the grid. */
+export interface IRegionPosition extends IPosition {
+    rowIndex: number;
+    columnIndex: number;
+}
+export interface IScrollState {
+    scrollTop: number;
+    scrollLeft: number;
+    isScrolling: boolean;
+}
+export declare enum SelectionRegionType {
+    Rows = "Rows",
+    Columns = "Columns",
+    Cells = "Cells",
+    None = "None"
+}
+export declare enum RegionType {
+    Cell = "Cell",
+    ActiveCell = "ActiveCell",
+    AppendRow = "AppendRow",
+    AppendColumn = "AppendColumn",
+    ColumnHeader = "ColumnHeader",
+    ColumnHeaderMenu = "ColumnHeaderMenu",
+    ColumnPrimaryIcon = "ColumnPrimaryIcon",
+    ColumnDescription = "ColumnDescription",
+    ColumnResizeHandler = "ColumnResizeHandler",
+    ColumnFreezeHandler = "ColumnFreezeHandler",
+    RowHeaderDragHandler = "RowHeaderDragHandler",
+    RowHeaderExpandHandler = "RowHeaderExpandHandler",
+    RowHeaderCheckbox = "RowHeaderCheckbox",
+    RowGroupControl = "RowGroupControl",
+    RowGroupHeader = "RowGroupHeader",
+    RowHeader = "RowHeader",
+    AllCheckbox = "AllCheckbox",
+    FillHandler = "FillHandler",
+    Blank = "Blank",
+    None = "None"
+}
+/** A cell as `[columnIndex, rowIndex]`, or a run of rows or columns as `[start, end]`. Cell selections hold `[anchor, head]`. */
+export type ICellRange = [colIndex: number, rowIndex: number];
+export type IColumnRange = [colStartIndex: number, colEndIndex: number];
+export type IRowRange = [rowStartIndex: number, rowEndIndex: number];
+export type IRange = ICellRange | IColumnRange | IRowRange;
+export type ICellItem = [colIndex: number, rowIndex: number];
+export interface IMouseState extends IRegionPosition {
+    type: RegionType;
+    isOutOfBounds: boolean;
+}
+export interface IGridColumn {
+    id?: string;
+    name: string;
+    width?: number;
+    hasMenu?: boolean;
+    readonly?: boolean;
+    isPrimary?: boolean;
+    description?: string;
+    /** Space for a type icon before the name; the host draws it through `drawColumnIcon`. */
+    hasIcon?: boolean;
+}
+export interface IColumnResizeState {
+    columnIndex: number;
+    width: number;
+    x: number;
+}
+export interface IColumnFreezeState {
+    sourceIndex: number;
+    targetIndex: number;
+    isFreezing: boolean;
+}
+export declare enum DragRegionType {
+    Rows = "Rows",
+    Columns = "Columns",
+    None = "None"
+}
+export interface IDragState {
+    type: DragRegionType;
+    /** Pointer distance from the dragged item's leading edge, so the ghost keeps its grip point. */
+    delta: number;
+    ranges: IRange[];
+    isDragging: boolean;
+}
+export type IScrollDirection = -1 | 0 | 1;
+export declare enum MouseButtonType {
+    Left = 0,
+    Center = 1,
+    Right = 2
+}
+export declare enum RowControlType {
+    Spacer = "Spacer",
+    Drag = "Drag",
+    Expand = "Expand",
+    Checkbox = "Checkbox"
+}
+export interface IRowControlItem {
+    type: RowControlType;
+}
+export declare enum DraggableType {
+    All = "all",
+    None = "none",
+    Column = "column",
+    Row = "row"
+}
+export declare enum SelectableType {
+    All = "all",
+    None = "none",
+    Column = "column",
+    Row = "row",
+    Cell = "cell"
+}
+/** Size of the active cell, which can grow downward past its row for long text. */
+export interface IActiveCellBound {
+    rowIndex: number;
+    columnIndex: number;
+    width: number;
+    height: number;
+}
+export declare enum LinearRowType {
+    Group = 0,
+    Row = 1,
+    Append = 2
+}
+/** A visual row. `realIndex` is the data row index; group headers and the append row have their own types. */
+export type ILinearRow = {
+    type: LinearRowType.Row;
+    displayIndex: number;
+    realIndex: number;
+} | {
+    type: LinearRowType.Group;
+    id: string;
+    value: unknown;
+    depth: number;
+    realIndex: number;
+    isCollapsed: boolean;
+} | {
+    type: LinearRowType.Append;
+    value: unknown;
+    realIndex: number;
+};
+/** Plain grid without groups: the visual row is the data row. */
+export declare const identityLinearRow: (index: number) => ILinearRow;
+export declare const identityRowIndex: (index: number) => number;
+export declare enum ItemType {
+    Row = "Row",
+    Column = "Column"
+}
+export type IIndicesMap = Record<number, number>;
+export interface ICellMetaData {
+    size: number;
+    offset: number;
+}
+export type ICellMetaDataMap = Record<number, ICellMetaData>;
+export interface ICoordinate {
+    rowCount: number;
+    /** Data rows only, without group headers or the append row. */
+    pureRowCount: number;
+    columnCount: number;
+    containerWidth: number;
+    containerHeight: number;
+    rowHeight: number;
+    columnWidth: number;
+    rowHeightMap?: IIndicesMap;
+    columnWidthMap?: IIndicesMap;
+    /** Column header height. */
+    rowInitSize?: number;
+    /** Row header width. */
+    columnInitSize?: number;
+    freezeColumnCount?: number;
+}