@keenmate/web-grid 1.0.0-rc04 → 1.0.0-rc06

package/README.md

@@ -71,7 +71,10 @@ npm install @keenmate/web-grid
 | `hoverable` | `boolean` | `false` | Highlight row on hover |
 | `showRowToolbar` | `boolean` | `false` | Show row action toolbar |
 | `rowToolbar` | `Array` | `[]` | Toolbar items configuration |
-| `toolbarTrigger` | `string` | `'hover'` | Toolbar trigger: `'hover'`, `'button'` |
+| `toolbarTrigger` | `string` | `'hover'` | Toolbar trigger: `'hover'`, `'click'`, `'button'` |
+| `toolbarPosition` | `string` | `'auto'` | Toolbar position: `'auto'`, `'left'`, `'right'`, `'top'` |
+| `toolbarAlign` | `string` | `'center'` | Vertical alignment for left/right: `'center'`, `'top'` |
+| `toolbarTopPosition` | `string` | `'center'` | Horizontal position for top: `'start'`, `'center'`, `'end'`, `'cursor'` |
 | `contextMenu` | `Array` | `[]` | Context menu items |
 | `validationTooltipCallback` | `Function` | `undefined` | Custom HTML tooltip for validation errors: `({ field, error, value, row, rowIndex }) => htmlString` |
 
@@ -128,6 +131,11 @@ grid.rowToolbar = [
     onclick: ({ row, rowIndex }) => { /* ... */ }
   }
 ]
+
+// Positioning
+grid.toolbarPosition = 'left'     // Prefer left side (falls back if no space)
+grid.toolbarAlign = 'top'         // Align to top of row (for left/right position)
+grid.toolbarTopPosition = 'cursor' // Position at cursor (for top position)
 ```
 
 ## Context Menu

package/component-variables.manifest.json

@@ -14,6 +14,7 @@
     { "name": "base-main-bg", "required": true, "usage": "Table background, cell background, inputs" },
     { "name": "base-elevated-bg", "required": true, "usage": "Header background, striped rows, pagination buttons" },
     { "name": "base-hover-bg", "required": false, "usage": "Hover states, sorted header, active buttons" },
+    { "name": "base-disabled-bg", "required": false, "usage": "Readonly/disabled cell backgrounds" },
     { "name": "base-dropdown-bg", "required": false, "usage": "Toolbar, context menu, floating surfaces" },
     { "name": "base-border-color", "required": true, "usage": "Table, cell, header, toolbar borders" },
     { "name": "base-input-bg", "required": false, "usage": "Filter input, editor backgrounds" },

package/dist/grid.d.ts

@@ -1,4 +1,4 @@
-import type { Column, CellValidationState, RowToolbarConfig, ContextMenuItem, RowChangeDetail, ToolbarClickDetail, RowActionClickDetail, ContextMenuContext, EditTrigger, EditStartSelection, EditingCell, FocusedCell, SortMode, SortState, DataRequestDetail, DataRequestTrigger, BeforeCommitResult, GridMode, ToggleVisibility, PaginationLabelsCallback, SummaryContentCallback, ValidationTooltipContext } from './types.js';
+import type { Column, CellValidationState, RowToolbarConfig, ContextMenuItem, RowShortcut, RowChangeDetail, ToolbarClickDetail, RowActionClickDetail, ContextMenuContext, EditTrigger, EditStartSelection, EditingCell, FocusedCell, SortMode, SortState, DataRequestDetail, DataRequestTrigger, BeforeCommitResult, GridMode, ToggleVisibility, PaginationLabelsCallback, SummaryContentCallback, ValidationTooltipContext } from './types.js';
 /**
  * WebGrid - Core logic class for the data grid
  *
@@ -27,10 +27,15 @@ export declare class WebGrid<T = unknown> {
     protected _invalidCells: CellValidationState[];
     protected _showRowToolbar: boolean;
     protected _rowToolbar: RowToolbarConfig<T>[];
-    protected _toolbarAlign: 'center' | 'top';
-    protected _toolbarTopPosition: 'start' | 'center' | 'end' | 'cursor';
+    protected _toolbarVerticalAlign: 'top' | 'center' | 'bottom';
+    protected _toolbarHorizontalAlign: 'start' | 'center' | 'end' | 'cursor';
     protected _toolbarTrigger: 'hover' | 'click' | 'button';
+    protected _toolbarPosition: 'auto' | 'left' | 'right' | 'top';
     protected _contextMenu: ContextMenuItem<T>[] | undefined;
+    protected _rowShortcuts: RowShortcut<T>[] | undefined;
+    protected _showShortcutsHelp: boolean;
+    protected _shortcutsHelpPosition: 'top-right' | 'top-left';
+    protected _shortcutsHelpContentCallback: (() => string) | undefined;
     protected _onrowchange: ((detail: RowChangeDetail<T>) => void) | undefined;
     protected _onroweditstart: ((detail: {
         row: T;
@@ -142,14 +147,28 @@ export declare class WebGrid<T = unknown> {
     set showRowToolbar(value: boolean);
     get rowToolbar(): RowToolbarConfig<T>[];
     set rowToolbar(value: RowToolbarConfig<T>[]);
-    get toolbarAlign(): 'center' | 'top';
-    set toolbarAlign(value: 'center' | 'top');
+    get toolbarVerticalAlign(): 'top' | 'center' | 'bottom';
+    set toolbarVerticalAlign(value: 'top' | 'center' | 'bottom');
+    get toolbarHorizontalAlign(): 'start' | 'center' | 'end' | 'cursor';
+    set toolbarHorizontalAlign(value: 'start' | 'center' | 'end' | 'cursor');
+    get toolbarAlign(): 'top' | 'center' | 'bottom';
+    set toolbarAlign(value: 'top' | 'center' | 'bottom');
     get toolbarTopPosition(): 'start' | 'center' | 'end' | 'cursor';
     set toolbarTopPosition(value: 'start' | 'center' | 'end' | 'cursor');
     get toolbarTrigger(): 'hover' | 'click' | 'button';
     set toolbarTrigger(value: 'hover' | 'click' | 'button');
+    get toolbarPosition(): 'auto' | 'left' | 'right' | 'top';
+    set toolbarPosition(value: 'auto' | 'left' | 'right' | 'top');
     get contextMenu(): ContextMenuItem<T>[] | undefined;
     set contextMenu(value: ContextMenuItem<T>[] | undefined);
+    get rowShortcuts(): RowShortcut<T>[] | undefined;
+    set rowShortcuts(value: RowShortcut<T>[] | undefined);
+    get showShortcutsHelp(): boolean;
+    set showShortcutsHelp(value: boolean);
+    get shortcutsHelpPosition(): 'top-right' | 'top-left';
+    set shortcutsHelpPosition(value: 'top-right' | 'top-left');
+    get shortcutsHelpContentCallback(): (() => string) | undefined;
+    set shortcutsHelpContentCallback(value: (() => string) | undefined);
     get sort(): SortState[];
     set sort(value: SortState[]);
     get currentPage(): number;

package/dist/modules/toolbar/index.d.ts

@@ -14,8 +14,10 @@ export type ConnectorState = {
 export declare function normalizeToolbarItems<T>(config: RowToolbarConfig<T>[]): NormalizedToolbarItem<T>[];
 /**
  * Render toolbar HTML for a specific row
+ * @param reverseRows - If true, reverse row order so Row 1 ends up at top visually
+ *                      (CSS column-reverse makes last HTML row appear at top)
  */
-export declare function renderToolbarHTML<T>(items: NormalizedToolbarItem<T>[], row: T, rowIndex: number): string;
+export declare function renderToolbarHTML<T>(items: NormalizedToolbarItem<T>[], row: T, rowIndex: number, reverseRows?: boolean): string;
 /**
  * Open toolbar for a specific row
  */
@@ -47,6 +49,7 @@ export declare function getConnectorState(): ConnectorState;
 /**
  * Update connector path after row has moved
  * Call this after a moveUp/moveDown action to draw the bracket-shaped connector
+ * The connector is clipped at grid container boundaries
  */
 export declare function updateConnector<T>(ctx: GridContext<T>, displayItems: T[]): void;
 /**

package/dist/types.d.ts

@@ -177,12 +177,34 @@ export type ContextMenuItem<T> = {
     id: string;
     label: string | ((context: ContextMenuContext<T>) => string);
     icon?: string | ((context: ContextMenuContext<T>) => string);
+    shortcut?: string;
     disabled?: boolean | ((context: ContextMenuContext<T>) => boolean);
     visible?: boolean | ((context: ContextMenuContext<T>) => boolean);
     danger?: boolean;
     dividerBefore?: boolean;
     onclick?: (context: ContextMenuContext<T>) => void | Promise<void>;
 };
+export type ShortcutContext<T> = {
+    row: T;
+    rowIndex: number;
+    colIndex: number;
+    column: Column<T>;
+    cellValue: unknown;
+};
+export type RowShortcut<T> = {
+    key: string;
+    id: string;
+    label: string;
+    action: (ctx: ShortcutContext<T>) => void | Promise<void>;
+    disabled?: boolean | ((ctx: ShortcutContext<T>) => boolean);
+};
+export type ParsedKeyCombo = {
+    key: string;
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    meta: boolean;
+};
 export type QuickGridProps<T> = {
     items: T[];
     columns: Column<T>[];
@@ -221,13 +243,20 @@ export type QuickGridProps<T> = {
     invalidCells?: CellValidationState[];
     showRowToolbar?: boolean;
     rowToolbar?: RowToolbarConfig<T>[];
-    toolbarAlign?: 'center' | 'top';
-    toolbarTopPosition?: 'start' | 'center' | 'end' | 'cursor';
+    toolbarVerticalAlign?: 'top' | 'center' | 'bottom';
+    toolbarHorizontalAlign?: 'start' | 'center' | 'end' | 'cursor';
     toolbarTrigger?: 'hover' | 'click' | 'button';
+    toolbarPosition?: 'auto' | 'left' | 'right' | 'top';
     showRowActions?: boolean;
     rowActions?: RowToolbarConfig<T>[];
+    toolbarAlign?: 'top' | 'center' | 'bottom';
+    toolbarTopPosition?: 'start' | 'center' | 'end' | 'cursor';
     contextMenu?: ContextMenuItem<T>[];
     oncontextmenuopen?: (context: ContextMenuContext<T>) => void;
+    rowShortcuts?: RowShortcut<T>[];
+    showShortcutsHelp?: boolean;
+    shortcutsHelpPosition?: 'top-right' | 'top-left';
+    shortcutsHelpContentCallback?: () => string;
     virtualScroll?: boolean;
     virtualScrollThreshold?: number;
     virtualScrollRowHeight?: number;

package/dist/web-component.d.ts

@@ -1,5 +1,5 @@
 import { WebGrid } from './grid.js';
-import type { Column, CellValidationState, RowToolbarConfig, ContextMenuItem, RowChangeDetail, ToolbarClickDetail, RowActionClickDetail, ContextMenuContext, EditTrigger, EditStartSelection, EditorOption, EditorOptions, GridMode, ToggleVisibility, DataRequestDetail, SortState, SortMode, PaginationLabelsCallback, SummaryContentCallback, ValidationTooltipContext } from './types.js';
+import type { Column, CellValidationState, RowToolbarConfig, ContextMenuItem, RowShortcut, RowChangeDetail, ToolbarClickDetail, RowActionClickDetail, ContextMenuContext, EditTrigger, EditStartSelection, EditorOption, EditorOptions, GridMode, ToggleVisibility, DataRequestDetail, SortState, SortMode, PaginationLabelsCallback, SummaryContentCallback, ValidationTooltipContext } from './types.js';
 import type { GridContext } from './modules/types.js';
 /**
  * GridElement - Custom HTML Element for WebGrid
@@ -103,14 +103,28 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     set showRowToolbar(value: boolean);
     get rowToolbar(): RowToolbarConfig<T>[];
     set rowToolbar(value: RowToolbarConfig<T>[]);
-    get toolbarAlign(): 'center' | 'top';
-    set toolbarAlign(value: 'center' | 'top');
+    get toolbarVerticalAlign(): 'top' | 'center' | 'bottom';
+    set toolbarVerticalAlign(value: 'top' | 'center' | 'bottom');
+    get toolbarHorizontalAlign(): 'start' | 'center' | 'end' | 'cursor';
+    set toolbarHorizontalAlign(value: 'start' | 'center' | 'end' | 'cursor');
+    get toolbarAlign(): 'top' | 'center' | 'bottom';
+    set toolbarAlign(value: 'top' | 'center' | 'bottom');
     get toolbarTopPosition(): 'start' | 'center' | 'end' | 'cursor';
     set toolbarTopPosition(value: 'start' | 'center' | 'end' | 'cursor');
     get toolbarTrigger(): 'hover' | 'click' | 'button';
     set toolbarTrigger(value: 'hover' | 'click' | 'button');
+    get toolbarPosition(): 'auto' | 'left' | 'right' | 'top';
+    set toolbarPosition(value: 'auto' | 'left' | 'right' | 'top');
     get contextMenu(): ContextMenuItem<T>[] | undefined;
     set contextMenu(value: ContextMenuItem<T>[] | undefined);
+    get rowShortcuts(): RowShortcut<T>[] | undefined;
+    set rowShortcuts(value: RowShortcut<T>[] | undefined);
+    get showShortcutsHelp(): boolean;
+    set showShortcutsHelp(value: boolean);
+    get shortcutsHelpPosition(): 'top-right' | 'top-left';
+    set shortcutsHelpPosition(value: 'top-right' | 'top-left');
+    get shortcutsHelpContentCallback(): (() => string) | undefined;
+    set shortcutsHelpContentCallback(value: (() => string) | undefined);
     get showRowActions(): boolean;
     set showRowActions(value: boolean);
     get rowActions(): RowToolbarConfig<T>[];
@@ -199,6 +213,15 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     discardAllDrafts(): void;
     isCellInvalid(rowIndex: number, field: string): boolean;
     getCellValidationError(rowIndex: number, field: string): string | null;
+    /**
+     * Programmatically focus a cell. Updates state and focuses the DOM element.
+     * State is updated immediately so pending renders use the correct position.
+     */
+    focusCell(rowIndex: number, colIndex: number): void;
+    /**
+     * Programmatically start editing a cell.
+     */
+    startEditing(rowIndex: number, colIndex: number): void;
     escapeHtml(text: string): string;
     getCurrentEditingColumn(): Column<T> | null;
     getCurrentEditorOptions(): EditorOptions;
@@ -230,6 +253,10 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
      * Handle infinite scroll - trigger load more when near bottom
      */
     private handleInfiniteScroll;
+    /**
+     * Render the shortcuts help icon and overlay
+     */
+    private renderShortcutsHelpIcon;
     private render;
     /**
      * Render the SVG connector arrow for toolbar row tracking