@keenmate/web-grid 1.0.0-rc05 → 1.0.0-rc07

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, ToolbarPosition, GridLabels, RowLockInfo, RowLockingOptions, RowLockChangeDetail } from './types.js';
 /**
  * WebGrid - Core logic class for the data grid
  *
@@ -27,11 +27,23 @@ 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 _toolbarPosition: ToolbarPosition;
+    protected _inlineActionsTitle: string;
     protected _contextMenu: ContextMenuItem<T>[] | undefined;
+    protected _contextMenuXOffset: number;
+    protected _contextMenuYOffset: number;
+    protected _rowShortcuts: RowShortcut<T>[] | undefined;
+    protected _showShortcutsHelp: boolean;
+    protected _shortcutsHelpPosition: 'top-right' | 'top-left';
+    protected _shortcutsHelpContentCallback: (() => string) | undefined;
+    protected _idValueMember: keyof T | undefined;
+    protected _idValueCallback: ((row: T) => unknown) | undefined;
+    protected _rowLocking: RowLockingOptions<T> | undefined;
+    protected _externalLocks: Map<unknown, RowLockInfo>;
+    protected _onrowlockchange: ((detail: RowLockChangeDetail<T>) => void) | undefined;
     protected _onrowchange: ((detail: RowChangeDetail<T>) => void) | undefined;
     protected _onroweditstart: ((detail: {
         row: T;
@@ -72,6 +84,7 @@ export declare class WebGrid<T = unknown> {
     protected _summaryInline: boolean;
     protected _customStylesCallback?: () => string;
     protected _rowClassCallback?: (row: T, rowIndex: number) => string | null;
+    protected _labels: GridLabels;
     protected _virtualScroll: boolean;
     protected _virtualScrollThreshold: number;
     protected _virtualScrollRowHeight: number;
@@ -87,15 +100,17 @@ export declare class WebGrid<T = unknown> {
     protected _focusedCell: FocusedCell;
     protected _isCommittingFromKeyboard: boolean;
     protected _skipNextDropdownAutoEdit: boolean;
+    protected _hoveredRowIndex: number | null;
+    protected _onInteractionChange: ((type: 'hoveredRow' | 'focusedCell' | 'editingCell', detail: {
+        prev: any;
+        current: any;
+    }) => void) | null;
     get items(): T[];
     set items(value: T[]);
     get columns(): Column<T>[];
     set columns(value: Column<T>[]);
     get sortMode(): SortMode;
     set sortMode(value: SortMode);
-    /** @deprecated Use sortMode instead. sortable=true maps to sortMode="multi", sortable=false maps to sortMode="none" */
-    get sortable(): boolean;
-    set sortable(value: boolean);
     get filterable(): boolean;
     set filterable(value: boolean);
     get pageable(): boolean;
@@ -139,20 +154,39 @@ export declare class WebGrid<T = unknown> {
     get editingCell(): EditingCell;
     get isValidating(): boolean;
     get currentCellError(): string | null;
+    get hoveredRowIndex(): number | null;
     get showRowToolbar(): boolean;
     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 toolbarPosition(): ToolbarPosition;
+    set toolbarPosition(value: ToolbarPosition);
+    get inlineActionsTitle(): string;
+    set inlineActionsTitle(value: string);
     get contextMenu(): ContextMenuItem<T>[] | undefined;
     set contextMenu(value: ContextMenuItem<T>[] | undefined);
+    get contextMenuXOffset(): number;
+    set contextMenuXOffset(value: number);
+    get contextMenuYOffset(): number;
+    set contextMenuYOffset(value: number);
+    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;
@@ -179,6 +213,8 @@ export declare class WebGrid<T = unknown> {
     set customStylesCallback(value: (() => string) | undefined);
     get rowClassCallback(): ((row: T, rowIndex: number) => string | null) | undefined;
     set rowClassCallback(value: ((row: T, rowIndex: number) => string | null) | undefined);
+    get labels(): GridLabels;
+    set labels(value: Partial<GridLabels>);
     get virtualScroll(): boolean;
     set virtualScroll(value: boolean);
     get virtualScrollThreshold(): number;
@@ -236,6 +272,14 @@ export declare class WebGrid<T = unknown> {
         rowIndex: number;
         row: T;
     }) => void) | undefined);
+    get idValueMember(): keyof T | undefined;
+    set idValueMember(value: keyof T | undefined);
+    get idValueCallback(): ((row: T) => unknown) | undefined;
+    set idValueCallback(value: ((row: T) => unknown) | undefined);
+    get rowLocking(): RowLockingOptions<T> | undefined;
+    set rowLocking(value: RowLockingOptions<T> | undefined);
+    get onrowlockchange(): ((detail: RowLockChangeDetail<T>) => void) | undefined;
+    set onrowlockchange(value: ((detail: RowLockChangeDetail<T>) => void) | undefined);
     get isNavigateMode(): boolean;
     get filteredItems(): T[];
     get sortedItems(): T[];
@@ -327,5 +371,57 @@ export declare class WebGrid<T = unknown> {
      * NOTE: Does NOT call requestUpdate() - GridElement handles DOM updates surgically
      */
     clearFocusedCell(): void;
+    /**
+     * Set the hovered row index (for toolbar/shortcuts)
+     * NOTE: Does NOT call requestUpdate() - GridElement handles UI updates
+     */
+    setHoveredRow(rowIndex: number | null): void;
+    /**
+     * Get the unique ID for a row using configured idValueMember/idValueCallback
+     */
+    getRowId(row: T): unknown | undefined;
+    /**
+     * Find a row by its ID
+     */
+    findRowById(id: unknown): {
+        row: T;
+        index: number;
+    } | null;
+    /**
+     * Get lock info for a row (combines all sources: external, callback, property)
+     */
+    getRowLockInfo(rowOrId: T | unknown): RowLockInfo | null;
+    /**
+     * Check if a row is locked
+     */
+    isRowLocked(rowOrId: T | unknown): boolean;
+    /**
+     * Lock a row by ID (external lock for WebSocket scenarios)
+     */
+    lockRowById(id: unknown, lockerInfo?: Partial<RowLockInfo>): boolean;
+    /**
+     * Unlock a row by ID
+     */
+    unlockRowById(id: unknown): boolean;
+    /**
+     * Get all external locks (for debugging/inspection)
+     */
+    getExternalLocks(): Map<unknown, RowLockInfo>;
+    /**
+     * Clear all external locks
+     */
+    clearExternalLocks(): void;
+    /**
+     * Update a row's data by ID (partial update, preserves other fields)
+     */
+    updateRowById(id: unknown, newData: Partial<T>): boolean;
+    /**
+     * Replace entire row by ID
+     */
+    replaceRowById(id: unknown, newRow: T): boolean;
+    /**
+     * Check if a cell can be edited (respects lock state)
+     */
+    canEditCell(rowIndex: number, field: string): boolean;
 }
 export default WebGrid;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { GridElement } from './web-component.js';
 export { WebGrid } from './grid.js';
-export type { EditorType, EditTrigger, OptionsLoadTrigger, DateOutputFormat, EditorOption, EditorOptions, CustomEditorContext, CellValidationState, ValidationResult, BeforeCommitContext, BeforeCommitResult, Column, CellRenderCallback, RowChangeDetail, PredefinedToolbarItemType, RowToolbarItem, RowToolbarConfig, NormalizedToolbarItem, ToolbarClickDetail, RowActionType, RowActionClickDetail, ContextMenuContext, ContextMenuItem, QuickGridProps, SortState, DataRequestDetail, DataRequestTrigger, EditingCell, FocusedCell, SortDirection, ToolbarRowGroup, PopupPosition, ConnectorArrowDir } from './types.js';
+export type { EditorType, EditTrigger, OptionsLoadTrigger, DateOutputFormat, EditorOption, EditorOptions, CustomEditorContext, CellValidationState, ValidationResult, BeforeCommitContext, BeforeCommitResult, Column, CellRenderCallback, RowChangeDetail, PredefinedToolbarItemType, ToolbarPosition, ToolbarTooltip, RowToolbarItem, RowToolbarConfig, NormalizedToolbarItem, ToolbarClickDetail, RowActionType, RowActionClickDetail, ContextMenuContext, ContextMenuItem, QuickGridProps, SortState, DataRequestDetail, DataRequestTrigger, GridLabels, RowLockInfo, RowLockingOptions, RowLockChangeDetail, LockedRowEditBehavior, EditingCell, FocusedCell, SortDirection, ToolbarRowGroup, PopupPosition, ConnectorArrowDir } from './types.js';
 export { GridElement as default } from './web-component.js';

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

@@ -3,7 +3,7 @@ import type { GridContext } from '../types.js';
 /**
  * Open context menu at position
  */
-export declare function openContextMenu<T>(ctx: GridContext<T>, x: number, y: number, items: ContextMenuItem<T>[], menuContext: ContextMenuContext<T>, onItemClick: (itemId: string) => void, onClose: () => void): HTMLElement | null;
+export declare function openContextMenu<T>(ctx: GridContext<T>, x: number, y: number, xOffset: number, yOffset: number, items: ContextMenuItem<T>[], menuContext: ContextMenuContext<T>, onItemClick: (itemId: string) => void, onClose: () => void): HTMLElement | null;
 /**
  * Close context menu and cleanup
  */

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

@@ -1,2 +1,2 @@
-export { commitCurrentEditor, handleCheckboxChange, toggleCheckboxAndMove, handleEditorBlur, moveFocusAfterCommit, focusCellAfterCancel } from './lifecycle.js';
+export { commitCurrentEditor, handleCheckboxChange, toggleCheckboxAndMove, handleEditorBlur, moveFocusAfterCommit, focusCellAfterCancel, restoreCellToDisplayMode } from './lifecycle.js';
 export { renderCellEditor, renderTextEditor, renderNumberEditor, renderCheckboxEditor, renderSelectEditor, renderComboboxEditor, renderAutocompleteEditor } from './renderers.js';

package/dist/modules/editing/lifecycle.d.ts

@@ -1,4 +1,9 @@
 import type { GridContext } from '../types.js';
+/**
+ * Surgically restore a cell from editing mode to display mode.
+ * Uses centralized renderCell() to ensure all states are correct.
+ */
+export declare function restoreCellToDisplayMode<T>(ctx: GridContext<T>, rowIndex: number, colIndex: number): void;
 /**
  * Commit the value from the current editor
  */

package/dist/modules/navigation/focus.d.ts

@@ -12,15 +12,21 @@ export declare function focusCellElement<T>(ctx: GridContext<T>, rowIndex: numbe
 export declare function scrollToRowPosition<T>(ctx: GridContext<T>, rowIndex: number): void;
 /**
  * Update focus visual state surgically (without full re-render)
- * This directly manipulates CSS classes on existing DOM elements
+ * Uses centralized renderCell() to ensure all states are correct
  */
 export declare function updateFocusVisual<T>(ctx: GridContext<T>, oldFocus: FocusedCell | null, newFocus: FocusedCell | null): void;
 /**
  * Surgically remove the editing visual (blue border) from current editing cell.
- * Call this BEFORE cancelEdit() to ensure the DOM class is removed immediately,
- * rather than waiting for the async re-render.
+ * Call this BEFORE cancelEdit() to ensure the DOM class is removed immediately.
+ * NOTE: This just removes the class - full cell restoration happens via renderCell()
+ * after cancelEdit() clears the state.
  */
 export declare function clearEditingVisual<T>(ctx: GridContext<T>): void;
+/**
+ * Fully restore an editing cell to display mode.
+ * Must be called AFTER cancelEdit() so the cell renders in display mode.
+ */
+export declare function restoreEditingCellToDisplayMode<T>(ctx: GridContext<T>, rowIndex: number, colIndex: number): void;
 /**
  * Handle cell focus event
  */
@@ -31,6 +37,7 @@ export declare function handleCellFocus<T>(ctx: GridContext<T>, rowIndex: number
 export declare function moveFocus<T>(ctx: GridContext<T>, newRowIndex: number, newColIndex: number): void;
 /**
  * Try to start editing a cell (checks if editable first)
+ * Uses centralized renderCell() for surgical DOM update
  */
 export declare function tryStartEdit<T>(ctx: GridContext<T>, rowIndex: number, colIndex: number, options?: {
     initialSearchQuery?: string;

package/dist/modules/rendering/cell.d.ts

@@ -0,0 +1,19 @@
+import type { GridContext } from '../types.js';
+export type RenderCellOptions = {
+    /** Focus the editor after rendering (for edit mode) */
+    focusEditor?: boolean;
+    /** Cursor position for text inputs */
+    cursorPosition?: number;
+    /** Initial search query (type-to-start) */
+    initialSearchQuery?: string;
+};
+/**
+ * Surgically update a single cell's DOM based on current grid state.
+ * This is the single source of truth for cell appearance.
+ *
+ * Handles:
+ * - All CSS classes (focused, editing, editable, invalid, etc.)
+ * - Cell content (editor vs display mode)
+ * - Editor focus and cursor positioning
+ */
+export declare function renderCell<T>(ctx: GridContext<T>, rowIndex: number, colIndex: number, options?: RenderCellOptions): void;

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

@@ -1,3 +1,5 @@
 export { getContainerClasses, renderHeaderRow, renderDataRows, renderDataRowsVirtual, renderPagination, renderSummary } from './table.js';
 export type { VirtualScrollParams } from './table.js';
 export { renderCellDisplay } from './display.js';
+export { renderCell } from './cell.js';
+export type { RenderCellOptions } from './cell.js';

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

@@ -12,10 +12,18 @@ export type ConnectorState = {
  * Convert toolbar config (strings or objects) to normalized items
  */
 export declare function normalizeToolbarItems<T>(config: RowToolbarConfig<T>[]): NormalizedToolbarItem<T>[];
+/**
+ * Build rich tooltip HTML for a toolbar item
+ * @param item - The toolbar item
+ * @param shortcutKey - Optional keyboard shortcut from rowShortcuts
+ */
+export declare function buildToolbarTooltipHtml<T>(item: NormalizedToolbarItem<T>, shortcutKey?: string): string;
 /**
  * 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
  */
@@ -53,4 +61,4 @@ export declare function updateConnector<T>(ctx: GridContext<T>, displayItems: T[
 /**
  * Render the toolbar trigger button HTML
  */
-export declare function renderTriggerButton(rowIndex: number, isActive: boolean): string;
+export declare function renderTriggerButton(rowIndex: number, isActive: boolean, title?: string): string;

package/dist/types.d.ts

@@ -38,6 +38,8 @@ export type EditorOptions<T = unknown> = {
     onselect?: (option: EditorOption, row: T) => void;
     allowEmpty?: boolean;
     emptyLabel?: string;
+    noOptionsText?: string;
+    searchingText?: string;
     maxLength?: number;
     placeholder?: string;
     pattern?: string;
@@ -138,6 +140,11 @@ export type RowChangeDetail<T> = {
     validationError?: string | null;
 };
 export type PredefinedToolbarItemType = 'add' | 'delete' | 'duplicate' | 'moveUp' | 'moveDown';
+export type ToolbarPosition = 'auto' | 'left' | 'right' | 'top' | 'inline';
+export type ToolbarTooltip = {
+    description?: string;
+    shortcut?: string;
+};
 export type RowToolbarItem<T> = {
     id: string;
     icon: string;
@@ -148,13 +155,19 @@ export type RowToolbarItem<T> = {
     type?: PredefinedToolbarItemType;
     danger?: boolean;
     disabled?: boolean | ((row: T, rowIndex: number) => boolean);
+    hidden?: boolean | ((row: T, rowIndex: number) => boolean);
+    tooltip?: ToolbarTooltip;
+    tooltipCallback?: (row: T, rowIndex: number) => string;
     onclick?: (detail: {
         row: T;
         rowIndex: number;
     }) => void | Promise<void>;
 };
 export type RowToolbarConfig<T> = PredefinedToolbarItemType | RowToolbarItem<T>;
-export type NormalizedToolbarItem<T> = Required<Pick<RowToolbarItem<T>, 'id' | 'icon' | 'title' | 'row' | 'group'>> & Omit<RowToolbarItem<T>, 'id' | 'icon' | 'title' | 'row' | 'group'>;
+export type NormalizedToolbarItem<T> = Required<Pick<RowToolbarItem<T>, 'id' | 'icon' | 'title' | 'row' | 'group'>> & Omit<RowToolbarItem<T>, 'id' | 'icon' | 'title' | 'row' | 'group'> & {
+    tooltip?: ToolbarTooltip;
+    tooltipCallback?: (row: T, rowIndex: number) => string;
+};
 export type ToolbarClickDetail<T> = {
     item: NormalizedToolbarItem<T>;
     rowIndex: number;
@@ -177,17 +190,37 @@ 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>[];
-    /** @deprecated Use sortMode instead */
-    sortable?: boolean;
     filterable?: boolean;
     pageable?: boolean;
     pageSize?: number;
@@ -221,14 +254,23 @@ 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';
+    toolbarPosition?: ToolbarPosition;
+    inlineActionsTitle?: string;
     showRowActions?: boolean;
     rowActions?: RowToolbarConfig<T>[];
+    toolbarAlign?: 'top' | 'center' | 'bottom';
+    toolbarTopPosition?: 'start' | 'center' | 'end' | 'cursor';
     contextMenu?: ContextMenuItem<T>[];
+    contextMenuXOffset?: number;
+    contextMenuYOffset?: number;
     oncontextmenuopen?: (context: ContextMenuContext<T>) => void;
+    rowShortcuts?: RowShortcut<T>[];
+    showShortcutsHelp?: boolean;
+    shortcutsHelpPosition?: 'top-right' | 'top-left';
+    shortcutsHelpContentCallback?: () => string;
     virtualScroll?: boolean;
     virtualScrollThreshold?: number;
     virtualScrollRowHeight?: number;
@@ -314,6 +356,20 @@ export type PaginationLabelsContext = {
     pageSize: number;
 };
 export type PaginationLabelsCallback = (context: PaginationLabelsContext) => Partial<PaginationLabels>;
+export type GridLabels = {
+    rowActions: string;
+    inlineActionsHeader: string;
+    keyboardShortcuts: string;
+    paginationFirst: string;
+    paginationPrevious: string;
+    paginationNext: string;
+    paginationLast: string;
+    paginationPageInfo: string;
+    paginationItemCount: string;
+    paginationPerPage: string;
+    dropdownNoOptions: string;
+    dropdownSearching: string;
+};
 export type SummaryContext<T> = {
     items: T[];
     allItems: T[];
@@ -323,3 +379,27 @@ export type SummaryContext<T> = {
     metadata: unknown;
 };
 export type SummaryContentCallback<T> = (context: SummaryContext<T>) => string;
+export type RowLockInfo = {
+    isLocked: boolean;
+    lockedBy?: string;
+    lockedAt?: Date | string;
+    reason?: string;
+    [key: string]: unknown;
+};
+export type LockedRowEditBehavior = 'block' | 'allow' | 'callback';
+export type RowLockingOptions<T> = {
+    lockedMember?: keyof T;
+    lockInfoMember?: keyof T;
+    isLockedCallback?: (row: T, rowIndex: number) => boolean;
+    getLockInfoCallback?: (row: T, rowIndex: number) => RowLockInfo | null;
+    lockedEditBehavior?: LockedRowEditBehavior;
+    canEditLockedCallback?: (row: T, lockInfo: RowLockInfo) => boolean;
+    lockTooltipCallback?: (lockInfo: RowLockInfo, row: T) => string | null;
+};
+export type RowLockChangeDetail<T> = {
+    rowId: unknown;
+    row: T | null;
+    rowIndex: number;
+    lockInfo: RowLockInfo | null;
+    source: 'property' | 'callback' | 'external';
+};

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, ToolbarPosition, GridLabels, RowLockInfo, RowLockingOptions, RowLockChangeDetail } from './types.js';
 import type { GridContext } from './modules/types.js';
 /**
  * GridElement - Custom HTML Element for WebGrid
@@ -31,6 +31,8 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     private toolbarMoveInProgress;
     private toolbarHideTimeout;
     private toolbarHovered;
+    private toolbarShortcutHandler;
+    private inlineShortcutHandler;
     dropdownOpen: boolean;
     dropdownOptions: EditorOption[];
     highlightedIndex: number;
@@ -38,6 +40,7 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     isUserFiltering: boolean;
     justSelected: boolean;
     isOpeningDropdown: boolean;
+    private isProgrammaticScroll;
     searchDebounceTimer: ReturnType<typeof setTimeout> | null;
     searchAbortController: AbortController | null;
     isSearching: boolean;
@@ -65,8 +68,6 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     set items(value: T[]);
     get columns(): Column<T>[];
     set columns(value: Column<T>[]);
-    get sortable(): boolean;
-    set sortable(value: boolean);
     get filterable(): boolean;
     set filterable(value: boolean);
     get pageable(): boolean;
@@ -103,16 +104,34 @@ 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 toolbarPosition(): ToolbarPosition;
+    set toolbarPosition(value: ToolbarPosition);
+    get inlineActionsTitle(): string;
+    set inlineActionsTitle(value: string);
     get contextMenu(): ContextMenuItem<T>[] | undefined;
     set contextMenu(value: ContextMenuItem<T>[] | undefined);
+    get contextMenuXOffset(): number;
+    set contextMenuXOffset(value: number);
+    get contextMenuYOffset(): number;
+    set contextMenuYOffset(value: number);
+    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>[];
@@ -173,10 +192,20 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     set customStylesCallback(value: (() => string) | undefined);
     get rowClassCallback(): ((row: T, rowIndex: number) => string | null) | undefined;
     set rowClassCallback(value: ((row: T, rowIndex: number) => string | null) | undefined);
+    get labels(): GridLabels;
+    set labels(value: Partial<GridLabels>);
     get summaryMetadata(): unknown;
     set summaryMetadata(value: unknown);
     get summaryInline(): boolean;
     set summaryInline(value: boolean);
+    get idValueMember(): keyof T | undefined;
+    set idValueMember(value: keyof T | undefined);
+    get idValueCallback(): ((row: T) => unknown) | undefined;
+    set idValueCallback(value: ((row: T) => unknown) | undefined);
+    get rowLocking(): RowLockingOptions<T> | undefined;
+    set rowLocking(value: RowLockingOptions<T> | undefined);
+    get onrowlockchange(): ((detail: RowLockChangeDetail<T>) => void) | undefined;
+    set onrowlockchange(value: ((detail: RowLockChangeDetail<T>) => void) | undefined);
     get virtualScroll(): boolean;
     set virtualScroll(value: boolean);
     get virtualScrollThreshold(): number;
@@ -201,6 +230,30 @@ 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;
+    getRowId(row: T): unknown | undefined;
+    findRowById(id: unknown): {
+        row: T;
+        index: number;
+    } | null;
+    isRowLocked(rowOrId: T | unknown): boolean;
+    getRowLockInfo(rowOrId: T | unknown): RowLockInfo | null;
+    lockRowById(id: unknown, lockerInfo?: Partial<RowLockInfo>): boolean;
+    unlockRowById(id: unknown): boolean;
+    getExternalLocks(): Map<unknown, RowLockInfo>;
+    clearExternalLocks(): void;
+    updateRowById(id: unknown, newData: Partial<T>): boolean;
+    replaceRowById(id: unknown, newRow: T): boolean;
+    canEditCell(rowIndex: number, field: string): boolean;
+    /**
+     * 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.
+     * Uses surgical DOM update instead of full re-render.
+     */
+    startEditing(rowIndex: number, colIndex: number): void;
     escapeHtml(text: string): string;
     getCurrentEditingColumn(): Column<T> | null;
     getCurrentEditorOptions(): EditorOptions;
@@ -219,6 +272,12 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
      */
     private handleEditorKeyDown;
     private attachEventListeners;
+    /**
+     * Scroll to a row position programmatically (keyboard navigation).
+     * Pre-renders the target row range ONCE, then scrolls. Flag prevents
+     * the scroll event from redundantly calling handleVirtualScroll.
+     */
+    private scrollToRowProgrammatically;
     /**
      * Handle virtual scroll - recalculate visible range and re-render if changed
      */
@@ -232,6 +291,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
@@ -265,6 +328,25 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
      * Handle context menu (right-click) on cells
      */
     private handleContextMenu;
+    /**
+     * Setup document-level keyboard shortcut listener for toolbar row
+     * Allows shortcuts to work on hovered row without cell focus
+     */
+    private setupToolbarShortcuts;
+    /**
+     * Setup keyboard shortcuts for inline toolbar mode
+     * Uses hoveredRowIndex to determine which row to act on
+     */
+    private setupInlineShortcuts;
+    /**
+     * Remove inline shortcuts listener
+     */
+    private removeInlineShortcuts;
+    /**
+     * Setup rich tooltips for toolbar buttons
+     * Shows title, description, and keyboard shortcut on hover
+     */
+    private setupToolbarTooltips;
     /**
      * Show toolbar for a specific row
      */
@@ -277,6 +359,10 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
      * Handle toolbar item click
      */
     private handleToolbarItemClick;
+    /**
+     * Handle inline action button click (toolbarPosition="inline")
+     */
+    private handleInlineActionClick;
     /**
      * Handle paste event in navigate mode
      */