@framesquared/grid 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Carbone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,640 @@
+import { Panel, PanelConfig } from '@framesquared/ui';
+
+/**
+ * @framesquared/grid – Column types
+ *
+ * Column (base), NumberColumn, DateColumn, BooleanColumn,
+ * CheckColumn, ActionColumn, RowNumbererColumn.
+ */
+interface ColumnConfig {
+    text?: string;
+    dataIndex?: string;
+    width?: number;
+    flex?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    sortable?: boolean;
+    hideable?: boolean;
+    hidden?: boolean;
+    align?: 'left' | 'center' | 'right';
+    renderer?: (value: unknown, metaData: any, record: any, rowIndex: number, colIndex: number) => string;
+    menuDisabled?: boolean;
+    resizable?: boolean;
+    draggable?: boolean;
+    tdCls?: string;
+    xtype?: string;
+    format?: string;
+    trueText?: string;
+    falseText?: string;
+    actions?: ActionConfig[];
+}
+interface ActionConfig {
+    iconCls?: string;
+    tooltip?: string;
+    handler?: (record: any, rowIndex: number) => void;
+}
+declare class Column {
+    readonly text: string;
+    readonly dataIndex: string;
+    readonly width: number;
+    readonly flex: number;
+    readonly minWidth: number;
+    readonly maxWidth: number;
+    readonly sortable: boolean;
+    readonly hidden: boolean;
+    readonly align: string;
+    readonly config: ColumnConfig;
+    private _renderer;
+    constructor(config?: ColumnConfig);
+    getCellValue(record: any): unknown;
+    renderCell(value: unknown, metaData: any, record: any, rowIndex: number, colIndex: number): string;
+    formatValue(value: unknown): string;
+    /** Create the TD content — override in special columns. */
+    renderCellHtml(value: unknown, _metaData: any, record: any, rowIndex: number, colIndex: number): string;
+}
+declare class NumberColumn extends Column {
+    private _format;
+    constructor(config?: ColumnConfig);
+    formatValue(value: unknown): string;
+}
+declare class DateColumn extends Column {
+    private _format;
+    constructor(config?: ColumnConfig);
+    formatValue(value: unknown): string;
+}
+declare class BooleanColumn extends Column {
+    private _trueText;
+    private _falseText;
+    constructor(config?: ColumnConfig);
+    formatValue(value: unknown): string;
+}
+declare class CheckColumn extends Column {
+    constructor(config?: ColumnConfig);
+    renderCellHtml(value: unknown, _metaData: any, _record: any, _rowIndex: number, _colIndex: number): string;
+}
+declare class ActionColumn extends Column {
+    private _actions;
+    constructor(config?: ColumnConfig);
+    get actions(): ActionConfig[];
+    renderCellHtml(_value: unknown, _metaData: any, _record: any, rowIndex: number, _colIndex: number): string;
+}
+declare class RowNumbererColumn extends Column {
+    constructor(config?: ColumnConfig);
+    renderCellHtml(_value: unknown, _metaData: any, _record: any, rowIndex: number, _colIndex: number): string;
+}
+declare function createColumn(config: ColumnConfig): Column;
+
+/**
+ * @framesquared/grid – HeaderContainer
+ *
+ * Renders and manages the <thead> <tr> of column headers.
+ * Applies width, hidden state, and sort indicator classes.
+ */
+
+interface HeaderContainerConfig {
+    columns: Column[];
+}
+declare class HeaderContainer {
+    private columns;
+    private headerRow;
+    private thElements;
+    constructor(config: HeaderContainerConfig);
+    render(): HTMLTableRowElement;
+    getColumns(): Column[];
+    getThElements(): HTMLTableCellElement[];
+    setColumnHidden(index: number, hidden: boolean): void;
+    setSortIndicator(index: number, direction: 'ASC' | 'DESC' | null): void;
+}
+
+/**
+ * @framesquared/grid – GridStore
+ *
+ * Interface that defines the store contract Grid components require.
+ * The real `@framesquared/data` Store satisfies this interface natively.
+ * Custom stores can implement this interface for compatibility.
+ *
+ * @since 0.1.0
+ */
+interface GridRecord {
+    /** Get a field value by name. */
+    get(field: string): unknown;
+    /** Set a field value by name. */
+    set?(field: string, value: unknown): void;
+    /** Get the record's ID. */
+    getId?(): unknown;
+    /** Get all data as a plain object. */
+    getData?(): Record<string, unknown>;
+}
+interface GridStore {
+    /** Return all (filtered) records. */
+    getRange(start?: number, end?: number): GridRecord[];
+    /** Return record at index. */
+    getAt(index: number): GridRecord | undefined;
+    /** Return the count of (filtered) records. */
+    getCount(): number;
+    /** Return total (unfiltered) count. */
+    getTotalCount?(): number;
+    /** Sort by field name and direction. */
+    sort(field: string, direction?: 'ASC' | 'DESC'): void;
+    /** Subscribe to store events. */
+    on(event: string, fn: Function, ...args: any[]): any;
+    /** Iterate all records. */
+    each?(fn: (record: GridRecord, index: number) => boolean | void): void;
+}
+
+/**
+ * @framesquared/grid – GridView
+ *
+ * Renders the grid body using a <table> with <thead> and <tbody>.
+ * Manages row rendering, striping, cell content, and item events.
+ */
+
+interface GridViewConfig {
+    store: GridStore;
+    columns: Column[];
+    emptyText?: string;
+}
+declare class GridView {
+    private store;
+    private columns;
+    private emptyText;
+    private tableEl;
+    private tbodyEl;
+    private theadEl;
+    headerContainer: HeaderContainer;
+    /** Event listeners set by Grid */
+    onItemClick?: (record: GridRecord, rowIndex: number, event: Event) => void;
+    onItemDblClick?: (record: GridRecord, rowIndex: number, event: Event) => void;
+    /** Set by RowSelectionModel so selection classes survive refresh() */
+    isSelected?: (record: GridRecord) => boolean;
+    constructor(config: GridViewConfig);
+    render(): HTMLTableElement;
+    refresh(): void;
+    private renderRows;
+    private createRow;
+    setColumnHidden(index: number, hidden: boolean): void;
+    getTable(): HTMLTableElement | null;
+}
+
+/**
+ * @framesquared/grid – Grid
+ *
+ * The main grid panel.  Extends Panel to display tabular data from
+ * a Store with configurable columns, sorting, column visibility,
+ * row striping, and item events.
+ */
+
+interface GridConfig extends PanelConfig {
+    store?: GridStore;
+    columns?: ColumnConfig[];
+    sortableColumns?: boolean;
+    enableColumnHide?: boolean;
+    enableColumnResize?: boolean;
+    emptyText?: string;
+    scroll?: 'both' | 'horizontal' | 'vertical' | 'none';
+}
+declare class Grid extends Panel {
+    static $className: string;
+    _store: GridStore | null;
+    private _columns;
+    private _gridView;
+    private _sortableColumns;
+    private _sortDirection;
+    private _sortColumnIndex;
+    constructor(config?: GridConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    private setupSortableHeaders;
+    private onHeaderClick;
+    hideColumn(index: number): void;
+    showColumn(index: number): void;
+    private onStoreDataChanged;
+    getStore(): GridStore | null;
+    getColumns(): Column[];
+    getView(): GridView | null;
+}
+
+/**
+ * @framesquared/grid – Grouping feature
+ *
+ * Groups rows by a field value.  Renders group header rows with
+ * expand/collapse behavior.
+ */
+interface GroupingConfig {
+    groupField: string;
+    startCollapsed?: boolean;
+    groupHeaderTpl?: (groupValue: string, records: any[]) => string;
+}
+declare class Grouping {
+    private grid;
+    private groupField;
+    private startCollapsed;
+    private collapsedGroups;
+    private groupHeaderTpl;
+    constructor(config: GroupingConfig);
+    init(grid: any): void;
+    collapse(groupValue: string): void;
+    expand(groupValue: string): void;
+    isCollapsed(groupValue: string): boolean;
+    private rebuildGroupedView;
+    private groupRecords;
+    private setGroupRowsVisible;
+}
+
+/**
+ * @framesquared/grid – Summary feature
+ *
+ * Adds a summary row at the bottom of the grid with aggregate
+ * calculations per column (sum, count, average, min, max, custom).
+ */
+type SummaryType = 'sum' | 'count' | 'average' | 'min' | 'max' | ((records: any[]) => unknown);
+interface SummaryConfig {
+    summaryTypes: Record<string, SummaryType>;
+}
+declare class Summary {
+    private grid;
+    private summaryTypes;
+    constructor(config: SummaryConfig);
+    init(grid: any): void;
+    private renderSummary;
+    protected buildSummaryRow(records: any[], columns: any[]): HTMLTableRowElement;
+    protected calculate(records: any[], field: string, type: SummaryType): unknown;
+}
+
+/**
+ * @framesquared/grid – GroupingSummary feature
+ *
+ * Combines grouping with per-group summary rows.  Each group gets
+ * a header and a summary row at the bottom.
+ */
+
+interface GroupingSummaryConfig {
+    groupField: string;
+    summaryTypes: Record<string, SummaryType>;
+    startCollapsed?: boolean;
+}
+declare class GroupingSummary {
+    private grid;
+    private groupField;
+    private summaryTypes;
+    constructor(config: GroupingSummaryConfig);
+    init(grid: any): void;
+    private rebuild;
+    private groupRecords;
+    private calculate;
+}
+
+/**
+ * @framesquared/grid – RowBody feature
+ *
+ * Adds an expandable body row below each data row with
+ * custom content generated by getAdditionalData.
+ */
+interface RowBodyConfig {
+    getAdditionalData: (data: any, rowIndex: number, record: any) => {
+        rowBody: string;
+        rowBodyCls?: string;
+    };
+}
+declare class RowBody {
+    private grid;
+    private getAdditionalData;
+    constructor(config: RowBodyConfig);
+    init(grid: any): void;
+    private addRowBodies;
+}
+
+/**
+ * @framesquared/grid – CellEditing plugin
+ *
+ * Double-click a cell to start inline editing.  The cell content
+ * is replaced with an input field.  Enter completes; Escape cancels.
+ */
+declare class CellEditing {
+    private grid;
+    private activeEditor;
+    private activeInput;
+    private activeRecord;
+    private activeColumn;
+    private activeCell;
+    private originalValue;
+    init(grid: any): void;
+    private attachCellListeners;
+    private startEdit;
+    completeEdit(): void;
+    cancelEdit(): void;
+    private cleanup;
+}
+
+/**
+ * @framesquared/grid – RowEditing plugin
+ *
+ * Row-level editing: shows input fields for all editable columns
+ * in the selected row.  Update saves all; Cancel reverts.
+ */
+declare class RowEditing {
+    private grid;
+    private activeRowIndex;
+    private editorRow;
+    private inputs;
+    private originalValues;
+    init(grid: any): void;
+    startEdit(rowIndex: number): void;
+    completeEdit(): void;
+    cancelEdit(): void;
+    private teardown;
+}
+
+/**
+ * @framesquared/grid – RowExpander plugin
+ *
+ * Adds an expand button to each row.  Clicking toggles a body
+ * row below with custom content.
+ */
+interface RowExpanderConfig {
+    rowBodyTpl: (record: any) => string;
+    singleExpand?: boolean;
+}
+declare class RowExpander {
+    private grid;
+    private rowBodyTpl;
+    private singleExpand;
+    private expandedRows;
+    constructor(config: RowExpanderConfig);
+    init(grid: any): void;
+    private addExpanders;
+    private toggle;
+    private expandRow;
+    private collapseRow;
+    private collapseAll;
+}
+
+/**
+ * @framesquared/grid – Clipboard plugin
+ *
+ * Copies grid data to the clipboard in TSV (tab-separated) format
+ * for spreadsheet compatibility.
+ */
+declare class GridClipboard {
+    private grid;
+    init(grid: any): void;
+    getGridText(): string;
+    doCopy(): Promise<void>;
+}
+
+/**
+ * @framesquared/grid – DragDrop plugin
+ *
+ * Enables row reordering via drag and drop.  Adds draggable
+ * attributes to rows and provides a moveRow method.
+ */
+declare class GridDragDrop {
+    private grid;
+    init(grid: any): void;
+    private setupDrag;
+    moveRow(fromIndex: number, toIndex: number): void;
+}
+
+/**
+ * @framesquared/grid – RowSelectionModel
+ *
+ * Row-level selection model supporting SINGLE, SIMPLE, and MULTI modes.
+ * Optional checkbox column for visual selection.
+ *
+ * Works with any Grid that implements getStore()/getView() and any Store
+ * that implements the GridStore interface.
+ */
+
+interface RowSelectionModelConfig {
+    mode?: 'SINGLE' | 'SIMPLE' | 'MULTI';
+    checkboxSelect?: boolean;
+}
+interface SelectableGrid {
+    getStore(): GridStore | null;
+    getView(): GridView | null;
+}
+declare class RowSelectionModel {
+    private grid;
+    private mode;
+    private checkboxSelect;
+    private selected;
+    private listeners;
+    constructor(config?: RowSelectionModelConfig);
+    on(event: string, fn: Function): void;
+    private fire;
+    init(grid: SelectableGrid): void;
+    select(record: GridRecord, keepExisting?: boolean): void;
+    deselect(record: GridRecord): void;
+    selectRange(start: GridRecord, end: GridRecord): void;
+    selectAll(): void;
+    deselectAll(): void;
+    getSelection(): GridRecord[];
+    isSelected(record: GridRecord): boolean;
+    getCount(): number;
+    private doSelect;
+    private doDeselect;
+    private updateRowClass;
+    private attachRowListeners;
+    private addCheckboxColumn;
+}
+
+/**
+ * @framesquared/grid – CellSelectionModel
+ *
+ * Selects individual cells.  Supports navigation via arrow keys
+ * and Tab/Shift+Tab.  Selected cell gets x-grid-cell-selected class.
+ */
+
+interface CellPosition {
+    row: number;
+    column: number;
+}
+interface CellSelectableGrid extends SelectableGrid {
+    getColumns(): Column[];
+    el: HTMLElement | null;
+}
+declare class CellSelectionModel {
+    private grid;
+    private position;
+    private listeners;
+    private maxRow;
+    private maxCol;
+    on(event: string, fn: Function): void;
+    private fire;
+    init(grid: CellSelectableGrid): void;
+    getCurrentPosition(): CellPosition | null;
+    private selectCell;
+    private clearSelection;
+    private getCellElement;
+    private attachListeners;
+}
+
+/**
+ * @framesquared/grid – SpreadsheetSelectionModel
+ *
+ * Spreadsheet-like selection: click selects a cell, Shift+click
+ * extends to a range.  Selected cells get x-grid-cell-selected class.
+ */
+interface SelectionRange {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}
+declare class SpreadsheetSelectionModel {
+    private grid;
+    private range;
+    private listeners;
+    on(event: string, fn: Function): void;
+    private fire;
+    init(grid: any): void;
+    getSelectedRange(): SelectionRange | null;
+    private attachListeners;
+    private highlightRange;
+}
+
+/**
+ * @framesquared/grid – Lockable
+ *
+ * Splits a grid into locked (frozen left) and normal (scrollable right)
+ * panels.  Columns with config.locked=true go into the locked panel.
+ * Locked panel does not scroll horizontally.
+ */
+declare class Lockable {
+    private grid;
+    init(grid: any): void;
+    private rebuild;
+    private buildTable;
+}
+
+/**
+ * @framesquared/grid – GridState
+ *
+ * Saves and restores grid column state (widths, hidden, order)
+ * and sort state to localStorage.
+ */
+interface GridStateConfig {
+    stateId: string;
+}
+declare class GridState {
+    private grid;
+    private stateId;
+    constructor(config: GridStateConfig);
+    init(grid: any): void;
+    private get storageKey();
+    save(): void;
+    restore(): void;
+    clear(): void;
+}
+
+/**
+ * @framesquared/grid – TreeStore
+ *
+ * Manages hierarchical data.  Each node has text, children, id,
+ * leaf/expanded state, and optional checked state.  Provides
+ * traversal, path resolution, and mutation helpers.
+ */
+interface TreeNodeConfig {
+    id?: string;
+    text: string;
+    leaf?: boolean;
+    expanded?: boolean;
+    checked?: boolean;
+    children?: TreeNodeConfig[];
+    [key: string]: unknown;
+}
+interface TreeNode {
+    id: string;
+    text: string;
+    leaf: boolean;
+    expanded: boolean;
+    checked: boolean;
+    children: TreeNode[];
+    parent: TreeNode | null;
+    depth: number;
+    data: Record<string, unknown>;
+}
+interface TreeStoreConfig {
+    root: TreeNodeConfig;
+}
+declare class TreeStore {
+    private root;
+    private nodeMap;
+    constructor(config: TreeStoreConfig);
+    private buildMap;
+    getRoot(): TreeNode;
+    getNodeById(id: string): TreeNode | null;
+    /**
+     * Returns visible nodes in display order (respecting expanded state).
+     * If rootVisible is true, the root is included.
+     */
+    getVisibleNodes(rootVisible?: boolean): TreeNode[];
+    appendChild(parent: TreeNode, childCfg: TreeNodeConfig): TreeNode;
+    removeNode(id: string): boolean;
+    private removeFromMap;
+    getPath(node: TreeNode): string;
+    findByPath(path: string): TreeNode | null;
+    /** Expand all ancestors of a node so it becomes visible. */
+    expandToNode(node: TreeNode): void;
+    /** Set expanded=true on all non-leaf nodes. */
+    expandAll(node?: TreeNode): void;
+    /** Set expanded=false on all nodes. */
+    collapseAll(node?: TreeNode): void;
+    /** Cascade checked state to all descendants. */
+    cascadeCheck(node: TreeNode, checked: boolean): void;
+    /** Get all checked nodes. */
+    getChecked(node?: TreeNode): TreeNode[];
+    getRange(): any[];
+    getCount(): number;
+    getAt(i: number): any;
+    get(field: string): unknown;
+    on(_evt: string, _fn: Function): void;
+    sort(): void;
+    isLoading(): boolean;
+    getTotalCount(): number;
+}
+
+/**
+ * @framesquared/grid – TreePanel
+ *
+ * Displays hierarchical data from a TreeStore.  Each node is
+ * rendered with depth-based indentation, expand/collapse icons,
+ * folder/leaf icons, and optional checkboxes with cascade behavior.
+ */
+
+interface TreePanelConfig extends PanelConfig {
+    store?: TreeStore;
+    rootVisible?: boolean;
+    singleExpand?: boolean;
+    useArrows?: boolean;
+    lines?: boolean;
+    animate?: boolean;
+    checkable?: boolean;
+    cascadeCheck?: boolean;
+}
+declare class TreePanel extends Panel {
+    static $className: string;
+    private _treeStore;
+    private _rootVisible;
+    private _singleExpand;
+    private _checkable;
+    private _cascadeCheck;
+    private _treeBody;
+    private _checkedSet;
+    constructor(config?: TreePanelConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    refresh(): void;
+    private renderTree;
+    private createNodeElement;
+    private toggleNode;
+    private expandNode;
+    private collapseNode;
+    expandAll(): void;
+    collapseAll(): void;
+    expandPath(path: string): Promise<void>;
+    getChecked(): TreeNode[];
+    getStore(): TreeStore;
+}
+
+export { ActionColumn, type ActionConfig, BooleanColumn, CellEditing, type CellPosition, CellSelectionModel, CheckColumn, Column, type ColumnConfig, DateColumn, Grid, GridClipboard, type GridConfig, GridDragDrop, type GridRecord, GridState, type GridStateConfig, type GridStore, GridView, type GridViewConfig, Grouping, type GroupingConfig, GroupingSummary, type GroupingSummaryConfig, HeaderContainer, Lockable, NumberColumn, RowBody, type RowBodyConfig, RowEditing, RowExpander, type RowExpanderConfig, RowNumbererColumn, RowSelectionModel, type RowSelectionModelConfig, type SelectableGrid, type SelectionRange, SpreadsheetSelectionModel, Summary, type SummaryConfig, type SummaryType, type TreeNode, type TreeNodeConfig, TreePanel, type TreePanelConfig, TreeStore, type TreeStoreConfig, createColumn };