@kermodes/grid 0.0.0-stage → 0.3.13-dev.68.g32b767a

package/dist/GridModel.d.ts

@@ -0,0 +1,96 @@
+import type { IColumnHeaderGroup } from './ColumnHeaderGroup';
+import { type ModelIndex } from './GridMetrics';
+import { type GridColor, type GridTheme, type NullableGridColor } from './GridTheme';
+/**
+ * Model for a Grid
+ * All of these methods should return very quickly, as they will be called many times in the render cycle.
+ * If data needs to be loaded asynchronously, return something immediately, then redraw the grid when it arrives.
+ */
+declare abstract class GridModel {
+    /** Count of rows in the grid */
+    abstract get rowCount(): number;
+    /** Count of columns in the grid */
+    abstract get columnCount(): number;
+    /** Count of rows that are frozen (or 'floating') at the top */
+    get floatingTopRowCount(): number;
+    /** Count of rows that are frozen at the bottom */
+    get floatingBottomRowCount(): number;
+    /** Count of columns that are frozen (or 'floating') at the left */
+    get floatingLeftColumnCount(): number;
+    /** Count of columns that are frozen (or 'floating') at the right */
+    get floatingRightColumnCount(): number;
+    /**
+     * How many columns header levels are in the grid
+     * Used for column grouping where columns at depth 0 are the base columns
+     *
+     * A grid with 1-level grouping would have a columnHeaderDepth of 2
+     * and column headers at depths 0 and 1
+     */
+    get columnHeaderMaxDepth(): number;
+    /**
+     * Get the text for the specified cell
+     * @param column Column to get the text for
+     * @param row Row to get the text for
+     * @returns Text for the specified cell
+     */
+    abstract textForCell(column: ModelIndex, row: ModelIndex): string;
+    /**
+     * Get the character to replace text when truncated for a specific cell.
+     * Leave undefined to show text truncated with ellipsis
+     * @param column Column to get the truncation character for
+     * @param row Row to get the truncation character for
+     * @returns Truncation character for the specified cell
+     */
+    truncationCharForCell(column: ModelIndex, row: ModelIndex): string | undefined;
+    /**
+     * Get the text alignment for the specified cell
+     * @param column Column to get the alignment for
+     * @param row Row to get the alignment for
+     * @returns Text alignment for the specified cell
+     */
+    textAlignForCell(column: ModelIndex, row: ModelIndex): CanvasTextAlign;
+    /**
+     * Get the color for the text in the specified cell
+     * @param column Column to get the color for
+     * @param row Row to get the color for
+     * @param theme Theme applied to the grid
+     * @returns Color for the text in the cell
+     */
+    colorForCell(column: ModelIndex, row: ModelIndex, theme: GridTheme): GridColor;
+    /**
+     * Get the background color for the cell
+     * @param column Column to get the background color for
+     * @param row Row to get the background color for
+     * @param theme Theme applied to the grid
+     * @returns Background color for the cell
+     */
+    backgroundColorForCell(column: ModelIndex, row: ModelIndex, theme: GridTheme): NullableGridColor;
+    /**
+     * Text for the column header
+     * @param column Column to get the header for
+     * @param depth Depth to get the header text for. 0 is base columns
+     * @returns Text to put in the column header
+     */
+    abstract textForColumnHeader(column: ModelIndex, depth?: number): string | undefined;
+    /** Color for column header
+     * @param column Column to get the color for
+     * @param depth Header depth to get the color for
+     * @returns Color for the header at the depth or null
+     */
+    colorForColumnHeader(column: ModelIndex, depth?: number): string | null;
+    /**
+     * Text for the row header
+     * @param row Row to get the header for
+     * @returns Text to put in the row header
+     */
+    textForRowHeader(row: ModelIndex): string;
+    /**
+     * Text for the row footer
+     * @param row Row to get the footer for
+     * @returns Text to put in the row footer
+     */
+    textForRowFooter(row: ModelIndex): string;
+    getColumnHeaderGroup(modelIndex: ModelIndex, depth: number): IColumnHeaderGroup | undefined;
+    getColumnHeaderParentGroup(modelIndex: ModelIndex, depth: number): IColumnHeaderGroup | undefined;
+}
+export default GridModel;

package/dist/GridMouseHandler.d.ts

@@ -0,0 +1,29 @@
+import { type EventHandlerResult } from './EventHandlerResult';
+import type Grid from './Grid';
+import { type GridPoint } from './GridUtils';
+/**
+ * Some events we listen to are a native mouse event, and others are wrapped with React's SyntheticEvent.
+ * The GridMouseHandler shouldn't care though - the properties it accesses should be common on both types of events.
+ */
+export type GridMouseEvent = MouseEvent | React.MouseEvent;
+export type GridWheelEvent = WheelEvent | React.WheelEvent;
+export type GridMouseHandlerFunctionName = 'onDown' | 'onMove' | 'onDrag' | 'onLeave' | 'onClick' | 'onContextMenu' | 'onDoubleClick' | 'onUp' | 'onWheel';
+/**
+ * Define a region in the grid that interacts with the mouse on a grid.
+ * Return true from any of the events to indicate they're consumed, and stopPropagation/preventDefault will be called.
+ */
+export declare class GridMouseHandler {
+    order: number;
+    constructor(order?: number);
+    cursor: string | null;
+    onDown(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+    onMove(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+    onDrag(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+    onLeave(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+    onClick(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+    onContextMenu(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+    onDoubleClick(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+    onUp(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+    onWheel(gridPoint: GridPoint, grid: Grid, event: GridMouseEvent): EventHandlerResult;
+}
+export default GridMouseHandler;

package/dist/GridRange.d.ts

@@ -0,0 +1,268 @@
+export type GridRangeIndex = number | null;
+export type RequiredGridRangeIndex = number;
+type LeftIndex = GridRangeIndex;
+type RightIndex = GridRangeIndex;
+type TopIndex = GridRangeIndex;
+type BottomIndex = GridRangeIndex;
+export type GridCell = {
+    column: RequiredGridRangeIndex;
+    row: RequiredGridRangeIndex;
+};
+export interface BoundedGridRange extends GridRange {
+    startColumn: RequiredGridRangeIndex;
+    startRow: RequiredGridRangeIndex;
+    endColumn: RequiredGridRangeIndex;
+    endRow: RequiredGridRangeIndex;
+}
+export declare enum SELECTION_DIRECTION {
+    DOWN = "DOWN",
+    UP = "UP",
+    LEFT = "LEFT",
+    RIGHT = "RIGHT"
+}
+export declare class GridRange {
+    startColumn: GridRangeIndex;
+    startRow: GridRangeIndex;
+    endColumn: GridRangeIndex;
+    endRow: GridRangeIndex;
+    static SELECTION_DIRECTION: typeof SELECTION_DIRECTION;
+    /**
+     * Returns a normalized array of indexes ensuring left <= right and top <= bottom
+     * @param startColumn Start column index
+     * @param startRow Start row index
+     * @param endColumn End column index
+     * @param endRow End row index
+     * @returns Array containing normalized indexes [left, top, right, bottom]
+     */
+    static normalize(startColumn: GridRangeIndex, startRow: GridRangeIndex, endColumn: GridRangeIndex, endRow: GridRangeIndex): [LeftIndex, TopIndex, RightIndex, BottomIndex];
+    /**
+     * Makes a GridRange ensuring startColumn <= endColumn, startRow <= endRow
+     * @param startColumn Start column index
+     * @param startRow Start row index
+     * @param endColumn End column index
+     * @param endRow End row index
+     * @returns Normalized GridRange
+     */
+    static makeNormalized(startColumn: GridRangeIndex, startRow: GridRangeIndex, endColumn: GridRangeIndex, endRow: GridRangeIndex): GridRange;
+    /**
+     * Creates a GridRange representing a single cell
+     * @param column Column index
+     * @param row Row index
+     * @returns GridRange representing the cell
+     */
+    static makeCell(column: GridRangeIndex, row: GridRangeIndex): GridRange;
+    /**
+     * Creates a GridRange representing an infinite length column
+     * @param column Column index
+     * @returns GridRange representing the column
+     */
+    static makeColumn(column: GridRangeIndex): GridRange;
+    /**
+     * Creates a GridRange representing an infinite length row
+     * @param row Row index
+     * @returns GridRange representing the row
+     */
+    static makeRow(row: GridRangeIndex): GridRange;
+    /**
+     * Returns the minimum value between 2 range indexes or null if at least 1 is null
+     * @param index1 First grid range index
+     * @param index2 Second grid range index
+     * @returns Minimum index or null if either index is null
+     */
+    static minOrNull(index1: GridRangeIndex, index2: GridRangeIndex): number | null;
+    /**
+     * Returns the maximum value between 2 range indexes or null if at least 1 is null
+     * @param index1 First grid range index
+     * @param index2 Second grid range index
+     * @returns Maximum index or null if either index is null
+     */
+    static maxOrNull(index1: GridRangeIndex, index2: GridRangeIndex): number | null;
+    /**
+     * Consolidate the passed in ranges to the minimum set, merging overlapping ranges.
+     * @param ranges The ranges to consolidate
+     * @returns Consolidated ranges
+     */
+    static consolidate(ranges: readonly GridRange[]): GridRange[];
+    /**
+     * Checks if the 1-D ranges between 2 index pairs overlap or are continuous.
+     * For example ranges [0, 1] and [2, 3] are continuous and will return true.
+     * [0, 1] and [1, 3] overlap and return true.
+     * [0, 1] and [3, 4] do not overlap and have a gap so this will return false.
+     * @param start1 Start of 1st range
+     * @param end1 End of 1st range
+     * @param start2 Start of 2nd range
+     * @param end2 End of 2nd range
+     * @returns True if the ranges overlap or touch, else false
+     */
+    static isAxisRangeTouching(start1: GridRangeIndex, end1: GridRangeIndex, start2: GridRangeIndex, end2: GridRangeIndex): boolean;
+    /**
+     * Checks if 2 arrays of ranges are the same ranges
+     * @param ranges1 First array of ranges
+     * @param ranges2 Second array of ranges
+     * @returns True if the arrays contain the same ranges in the same order
+     */
+    static rangeArraysEqual(ranges1: readonly GridRange[], ranges2: readonly GridRange[]): boolean;
+    /**
+     * Get the intersection (overlapping area) of two ranges
+     * @param range One range to check for the intersection
+     * @param otherRange The other range to check for the intersection
+     * @returns Intersection of the two ranges. If they do not intersect, returns `null`.
+     */
+    static intersection(range: GridRange, otherRange: GridRange): GridRange | null;
+    /**
+     * Subtracts 1 range from another
+     * @param range The range to be subtracted from
+     * @param subtractRange The range to subtract from within this range
+     * @returns The ranges needed to represent the remaining
+     */
+    static subtractFromRange(range: GridRange, subtractRange: GridRange): GridRange[];
+    /**
+     * Subtract a range from multiple ranges
+     * @param ranges The ranges to be subtracted from
+     * @param subtractRange The range to subtract from within these ranges
+     * @returns The ranges needed to represent the remaining
+     */
+    static subtractFromRanges(ranges: readonly GridRange[], subtractRange: GridRange): GridRange[];
+    /**
+     * Subtract multiple ranges from multiple ranges
+     * @param ranges The ranges to be subtracted from
+     * @param subtractRanges The ranges to subtract from within these ranges
+     * @returns The ranges needed to represent the remaining
+     */
+    static subtractRangesFromRanges(ranges: readonly GridRange[], subtractRanges: readonly GridRange[]): GridRange[];
+    /**
+     * Test if a given range is bounded (all values are non-null)
+     * @param range The range to test
+     * @returns True if this range is bounded, false otherwise
+     */
+    static isBounded(range: GridRange): range is BoundedGridRange;
+    /**
+     * Converts any GridRange passed in that is a full row or column selection to be bound
+     * to the `columnCount` and `rowCount` passed in
+     *
+     * @param range The range to get the bounded range of
+     * @param columnCount The number of columns
+     * @param rowCount The number of rows
+     * @returns The passed in GridRange with any null values filled in
+     */
+    static boundedRange(range: GridRange, columnCount: number, rowCount: number): BoundedGridRange;
+    /**
+     * Converts the GridRanges passed in to be bound to the `columnCount` and `rowCount` passed in
+     *
+     * @param ranges The ranges to get the bounded ranges of
+     * @param columnCount The number of columns
+     * @param rowCount The number of rows
+     * @returns The passed in GridRange with any null values filled in
+     */
+    static boundedRanges(ranges: readonly GridRange[], columnCount: number, rowCount: number): BoundedGridRange[];
+    /**
+     * Offsets a GridRange by the specified amount in the x and y directions
+     *
+     * @param range The range to offset
+     * @param columnOffset The number of columns to offset
+     * @param rowOffset The number of rows to offset
+     * @returns The new grid range offset from the original
+     */
+    static offset(range: GridRange, columnOffset: number, rowOffset: number): GridRange;
+    /**
+     * Get the next cell given the selected ranges and the current cell
+     * @param ranges The selected bounded ranges within the grid
+     * @param column The cursor column, or null if none focused
+     * @param row The cursor row, or null if none focused
+     * @param direction The direction in which to select next
+     * @returns The next cell to focus, or null if there should be no more focus
+     */
+    static nextCell(ranges: readonly GridRange[], column?: GridRangeIndex, row?: GridRangeIndex, direction?: SELECTION_DIRECTION): GridCell | null;
+    /**
+     * Count the number of cells in the provided grid ranges
+     * @param ranges The ranges to count the rows of
+     * @returns The number of cells in the ranges, or `NaN` if any of the ranges were unbounded
+     */
+    static cellCount(ranges: readonly GridRange[]): number;
+    /**
+     * Count the number of rows in the provided grid ranges
+     * @param ranges The ranges to count the rows of
+     * @returns The number of rows in the ranges, or `NaN` if any of the ranges were unbounded
+     */
+    static rowCount(ranges: readonly GridRange[]): number;
+    /**
+     * Count the number of columns in the provided grid ranges
+     * @param ranges The ranges to count the columns of
+     * @returns The number of columns in the ranges, or `NaN` if any of the ranges were unbounded
+     */
+    static columnCount(ranges: readonly GridRange[]): number;
+    /**
+     * Check if the provided ranges contain the provided cell
+     * @param ranges The ranges to check
+     * @param column The column index
+     * @param row The row index
+     * @returns True if the cell is within the provided ranges, false otherwise.
+     */
+    static containsCell(ranges: readonly GridRange[], column: GridRangeIndex, row: GridRangeIndex): boolean;
+    /**
+     * Iterate through each cell in the provided ranges
+     * @param ranges The ranges to iterate through
+     * @param callback The callback to execute. `index` is the index within that range
+     * @param direction The direction to iterate in
+     */
+    static forEachCell(ranges: readonly GridRange[], callback: (column: number, row: number, index: number) => void, direction?: SELECTION_DIRECTION): void;
+    constructor(startColumn: GridRangeIndex, startRow: GridRangeIndex, endColumn: GridRangeIndex, endRow: GridRangeIndex);
+    /**
+     * Checks if the provided range is equivalent to this range (same start and end column/row indexes)
+     * @param other Grid range to check against
+     * @returns True if the ranges cover the same area
+     */
+    equals(other: GridRange): boolean;
+    /**
+     * Checks if this GridRange contains another range
+     * @param other The range to check
+     * @returns True if this GridRange completely contains `other`
+     * */
+    contains(other: GridRange): boolean;
+    /**
+     * Check if the provided cell is in this range
+     * @param column The column to check
+     * @param row The row to check
+     * @returns True if this cell is within this range
+     */
+    containsCell(column: GridRangeIndex, row: GridRangeIndex): boolean;
+    /**
+     * Check if the provided range touches (or overlaps) this GridRange
+     * Effectively checks if the 2 ranges could be represented by 1 continuous range
+     * @param other The range to check
+     * @returns True if this GridRange touches `other`
+     * */
+    touches(other: GridRange): boolean;
+    /**
+     * Subtracts a range from this range
+     * @param other The range to deselect from within this range
+     * @returns The ranges needed to represent the remaining
+     */
+    subtract(other: GridRange): GridRange[];
+    /**
+     * Get the first cell in this range. Throws if this range is unbounded.
+     *
+     * @param direction The direction to get the starting cell in. Defaults to DOWN
+     * @returns The first cell in this range in the direction specified
+     */
+    startCell(direction?: SELECTION_DIRECTION): GridCell;
+    /**
+     * Get the next cell in the direction specified. Throws if this range is unbounded.
+     * If already at the bounds of the range in that direction, wrap to the next column or row
+     * If at the end of the entire range, return null
+     * If outside of the range, returns the next cell closest within this range.
+     *
+     * @param column The cursor column
+     * @param row The cursor row
+     * @param direction The direction to go in
+     * @returns The next cell in the direction specified, or `null` if at the end of the range
+     */
+    nextCell(column: GridRangeIndex, row: GridRangeIndex, direction: SELECTION_DIRECTION): GridCell | null;
+    /**
+     * Iterate through each cell in the range
+     * @param callback Callback to execute. `index` is the index within this range
+     * @param direction The direction to iterate in
+     */
+    forEach(callback: (column: number, row: number, index: number) => void, direction?: SELECTION_DIRECTION): void;
+}
+export default GridRange;

package/dist/GridRenderer.d.ts

@@ -0,0 +1,159 @@
+import { type GridColorWay, type NullableGridColor } from './GridTheme';
+import { type Coordinate, type VisibleIndex } from './GridMetrics';
+import { type BoundedAxisRange } from './GridAxisRange';
+import { type GridRenderState } from './GridRendererTypes';
+import TextCellRenderer from './TextCellRenderer';
+/**
+ * A GridRenderer handles rendering the different parts of the grid
+ * This default rendering just renders a basic grid. Extend this class and implement
+ * your own methods to customize drawing of the grid (eg. Draw icons or special features)
+ */
+export declare class GridRenderer {
+    static DEFAULT_EDGE_RADIUS: number;
+    protected textCellRenderer: TextCellRenderer;
+    /**
+     * Truncate a string to the specified length and add ellipses if necessary
+     * @param str The string to truncate
+     * @param len The length to truncate the string to. If longer than the actual string, just returns the string
+     * @returns The truncated string
+     */
+    static truncate(str: string, len: number): string;
+    /**
+     * Uses binary search to truncate a string to fit in the provided width
+     * @param context The drawing context to measure the text in
+     * @param str The string to get the maximum length it can draw
+     * @param width The width to truncate it to
+     * @param start The low boundary to start the search
+     * @param end The high boundary to start the search
+     * @param truncationChar This char will be repeated as the display string if the string is truncated instead of just adding an ellipsis
+     * @returns The truncated string
+     */
+    static binaryTruncateToWidth(context: CanvasRenderingContext2D, str: string, width: number, start?: number, end?: number, truncationChar?: string): string;
+    /**
+     * The most characters of a string that can be drawn within a width, based on
+     * the estimated width of the narrowest character. `truncateToWidth` never
+     * reads past this many characters.
+     * @param width The width to truncate within
+     * @param fontWidthLower The estimated width of the narrowest character
+     * @returns The maximum number of characters that can fit
+     */
+    static getMaxTruncatedLength(width: number, fontWidthLower?: number): number;
+    /**
+     * Truncate a string (if necessary) to fit in the specified width.
+     * First uses the estimated font width to calculate a lower/upper bound
+     * Then uses binary search within those bounds to find the exact max length
+     * @param context The drawing context
+     * @param str The string to calculate max length for
+     * @param width The width to truncate within
+     * @param fontWidth The estimated width of each character
+     * @param truncationChar This char will be repeated as the display string if the string is truncated instead of just adding an ellipsis
+     * @returns The truncated string that fits within the width provided
+     */
+    static truncateToWidth(context: CanvasRenderingContext2D, str: string, width: number, fontWidthLower?: number, fontWidthUpper?: number, truncationChar?: string): string;
+    /** Split a space separated list of row background colors, cached for the last value */
+    static getCachedBackgroundColors: import("memoize-one").MemoizedFn<(backgroundColors: GridColorWay) => string[]>;
+    /**
+     * Draw the grid canvas with the state provided
+     * @param state The state of the grid
+     */
+    drawCanvas(state: GridRenderState): void;
+    configureContext(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawBackground(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawGrid(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawFloatingRows(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawFloatingColumns(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawFloatingBorders(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawGridBackground(context: CanvasRenderingContext2D, state: GridRenderState, drawHover?: boolean): void;
+    drawRowStripes(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawRowStripesForRows(context: CanvasRenderingContext2D, state: GridRenderState, rows: readonly VisibleIndex[], rowBackgroundColors: GridColorWay, minX?: number, maxX?: number): void;
+    drawMouseColumnHover(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawMouseRowHover(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawFloatingMouseRowHover(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    /** Tints the whole row of the cursor cell, so a clicked cell's row stands out */
+    drawCursorRow(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawMouseRowHoverForRow(context: CanvasRenderingContext2D, state: GridRenderState, row: VisibleIndex): void;
+    drawGridLines(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawGridLinesForItems(context: CanvasRenderingContext2D, state: GridRenderState, columns: readonly VisibleIndex[], rows: readonly VisibleIndex[], columnColor: NullableGridColor, rowColor: NullableGridColor): void;
+    drawGridLinesForColumns(context: CanvasRenderingContext2D, state: GridRenderState, columns: readonly VisibleIndex[]): void;
+    drawGridLinesForRows(context: CanvasRenderingContext2D, state: GridRenderState, rows: readonly VisibleIndex[]): void;
+    drawCellBackgrounds(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawCellBackgroundsForItems(context: CanvasRenderingContext2D, state: GridRenderState, columns: readonly VisibleIndex[], rows: readonly VisibleIndex[]): void;
+    drawCellBackground(context: CanvasRenderingContext2D, state: GridRenderState, column: VisibleIndex, row: VisibleIndex): void;
+    drawCellContents(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawColumnCellContents(context: CanvasRenderingContext2D, state: GridRenderState, column: VisibleIndex): void;
+    drawCellContent(context: CanvasRenderingContext2D, state: GridRenderState, column: VisibleIndex, row: VisibleIndex): void;
+    drawHeaders(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    /**
+     * The row between the headers and the cells that holds the filter inputs: a header-coloured
+     * band divided like the columns below it, so each input reads as a cell of the grid.
+     */
+    drawFilterBar(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawFooters(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawColumnHeaders(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawColumnHeadersForRange(context: CanvasRenderingContext2D, state: GridRenderState, range: BoundedAxisRange, bounds: {
+        minX: number;
+        maxX: number;
+    }): void;
+    drawColumnHeadersAtDepth(context: CanvasRenderingContext2D, state: GridRenderState, range: BoundedAxisRange, bounds: {
+        minX: number;
+        maxX: number;
+    }, depth: number): void;
+    /**
+     * Draws the column header for the given visible index
+     * @param context Canvas context
+     * @param state Grid render state
+     * @param index Visible index of the column header to draw
+     * @param bounds The horizontal bounds the header can be drawn in
+     */
+    drawColumnHeaderAtIndex(context: CanvasRenderingContext2D, state: GridRenderState, index: VisibleIndex, bounds: {
+        minX: number;
+        maxX: number;
+    }): void;
+    drawColumnHeader(context: CanvasRenderingContext2D, state: GridRenderState, columnText: string, columnX: Coordinate, columnWidth: number, style?: {
+        backgroundColor?: string;
+        textColor?: string;
+        separatorColor?: string;
+        textInsetRight?: number;
+    }, bounds?: {
+        minX?: number;
+        maxX?: number;
+    }): void;
+    drawRowHeaders(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawRowHeader(context: CanvasRenderingContext2D, state: GridRenderState, row: VisibleIndex, rowY: Coordinate, rowHeight: number): void;
+    drawRowFooters(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawSelectedRanges(context: CanvasRenderingContext2D, state: GridRenderState, viewport?: {
+        left?: VisibleIndex;
+        top?: VisibleIndex;
+        right?: VisibleIndex;
+        bottom?: VisibleIndex;
+        minX?: Coordinate;
+        minY?: Coordinate;
+        maxX?: Coordinate;
+        maxY?: Coordinate;
+    }): void;
+    drawActiveCell(context: CanvasRenderingContext2D, state: GridRenderState, column: VisibleIndex, row: VisibleIndex): void;
+    /**
+     * Draws an outline around the in-flight ctrl+click / ctrl+shift+click drag
+     * rectangle. Uses `selection.cursor` (mouse-down anchor) and
+     * `selection.selectionEnd` (current drag position) for the bounds. For row
+     * selection themes only the top and bottom horizontal strokes are drawn
+     * (row-boundary preview); for column selection only left/right; for cell
+     * selection all four sides.
+     */
+    drawGestureDragOutline(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    /**
+     * Draws a rounded rectangle using the current state of the canvas.
+     *
+     * @param context The canvas context
+     * @param x coordinate of the left side
+     * @param y coordinate of the top side
+     * @param w width of the rectangle
+     * @param h height of the rectangle
+     * @param r corner radius of the rectangle
+     */
+    drawRoundedRect(context: CanvasRenderingContext2D, x: Coordinate, y: Coordinate, w: number, h: number, r?: number): void;
+    drawDraggingColumn(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    drawScrollBars(context: CanvasRenderingContext2D, state: GridRenderState): void;
+    getCachedHeaderWidth: (context: CanvasRenderingContext2D, text: string) => number;
+}
+export default GridRenderer;

package/dist/GridRendererTypes.d.ts

@@ -0,0 +1,25 @@
+import { type Coordinate } from './GridMetrics';
+import type GridMetrics from './GridMetrics';
+import type GridModel from './GridModel';
+import { type GridTheme } from './GridTheme';
+import { type GridSeparator } from './mouse-handlers/GridSeparatorMouseHandler';
+import { type DraggingColumn } from './mouse-handlers/GridColumnMoveMouseHandler';
+import type { GestureMode, Selection } from './Selection';
+export declare const DEFAULT_FONT_WIDTH = 10;
+export type GridRenderState = {
+    width: number;
+    height: number;
+    context: CanvasRenderingContext2D;
+    theme: GridTheme;
+    model: GridModel;
+    metrics: GridMetrics;
+    mouseX: Coordinate | null;
+    mouseY: Coordinate | null;
+    selection: Selection;
+    draggingColumn: DraggingColumn | null;
+    draggingColumnSeparator: GridSeparator | null;
+    isDraggingHorizontalScrollBar: boolean;
+    isDraggingVerticalScrollBar: boolean;
+    isDragging: boolean;
+    gestureMode: GestureMode | null;
+};

package/dist/GridSelectionUtils.d.ts

@@ -0,0 +1,97 @@
+import GridRange, { type GridRangeIndex, type SELECTION_DIRECTION } from './GridRange';
+import type { CommitGestureOptions, GestureExtendOptions, GestureMode, Selection } from './Selection';
+/**
+ * Maps modifier-key state on a mouse event to the appropriate `GestureMode`.
+ * The four modifier combinations partition the gesture space:
+ * - shift + ctrl/meta → `maximize`
+ * - shift alone       → `extend`
+ * - ctrl/meta alone   → `add`
+ * - no modifiers      → `replace`
+ */
+export declare function gestureModeFromModifiers(modifiers: {
+    isShiftKey: boolean;
+    isModifierKey: boolean;
+}): GestureMode;
+/**
+ * Shape describing how a mouse gesture should mutate the selection's ranges.
+ * Consumed by each `Selection` implementation's `withGestureExtend` to install
+ * the transient overlay.
+ */
+export type GestureExtendResult = {
+    /** The new range list to install as the transient overlay. */
+    newRanges: readonly GridRange[];
+    /**
+     * True when the caller should drop any previously-committed selection state
+     * (relevant to `KeyedSelection.selectedKeys`; ignored by `RangedSelection`).
+     */
+    isReplacing: boolean;
+    /**
+     * True when the caller should trim to the last committed range before
+     * installing the new ranges. Applies to `extend` mode.
+     */
+    trimBefore: boolean;
+    /**
+     * True when the caller should reset the gesture anchor to `cursor` after
+     * installing. False preserves the existing anchor.
+     */
+    resetAnchor: boolean;
+};
+/**
+ * Compute the geometry for a mouse gesture. Given the current active ranges,
+ * gesture anchor, cursor position, and mode, returns the new overlay ranges
+ * plus the flags describing how the caller should install them.
+ *
+ * This is the shared arithmetic used by both `RangedSelection` and
+ * `KeyedSelection` for their `withGestureExtend` implementations.
+ */
+export declare function computeGestureExtend(activeRanges: readonly GridRange[], anchor: {
+    row: GridRangeIndex;
+    column: GridRangeIndex;
+} | null, cursor: {
+    row: GridRangeIndex;
+    column: GridRangeIndex;
+}, opts: GestureExtendOptions): GestureExtendResult;
+/**
+ * Returns the next cursor cell in `direction` walking through `ranges`.
+ * Falls back to walking the full grid when the ranges are empty or contain
+ * exactly one cell — matches Tab/Enter behavior for single-cell selections.
+ * Shared by `RangedSelection` and `KeyedSelection` implementations of
+ * `getNextCursorInDirection`.
+ */
+export declare function nextCursorInRanges(ranges: readonly GridRange[], current: {
+    row: GridRangeIndex;
+    column: GridRangeIndex;
+}, direction: SELECTION_DIRECTION, bounds: {
+    columnCount: number;
+    rowCount: number;
+}): {
+    row: GridRangeIndex;
+    column: GridRangeIndex;
+} | null;
+/**
+ * Returns the first cell of `ranges` bounded to `[columnCount, rowCount]`.
+ * Shared by `RangedSelection` and `KeyedSelection` implementations of
+ * `getCursorLandingCell`.
+ */
+export declare function cursorLandingCellForRanges(ranges: readonly GridRange[], bounds: {
+    columnCount: number;
+    rowCount: number;
+}): {
+    row: GridRangeIndex;
+    column: GridRangeIndex;
+} | null;
+/**
+ * Returns `settled` with the post-commit cursor placed. Uses `opts.cursor`
+ * as the target; substitutes `landing` when the target falls outside a
+ * non-empty settled selection; preserves the target when settled is empty
+ * (matches Escape's "cursor survives clear" semantics).
+ *
+ * Callers pass `landing` precomputed from the pre-commit selection so this
+ * helper doesn't need to reach back into the caller's overlay state.
+ * Returns `settled` unchanged when the cursor is already correct so
+ * mouseUp no-ops preserve reference equality.
+ */
+export declare function withCommittedCursor<S extends Selection>(settled: S, landing: {
+    row: GridRangeIndex;
+    column: GridRangeIndex;
+} | null, opts: CommitGestureOptions): S;