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

package/README.md

@@ -27,9 +27,10 @@ npm install @keenmate/web-grid
   ]
   grid.columns = [
     { field: 'id', title: 'ID', width: '60px' },
-    { field: 'name', title: 'Name', sortable: true },
-    { field: 'age', title: 'Age', sortable: true }
+    { field: 'name', title: 'Name' },
+    { field: 'age', title: 'Age' }
   ]
+  grid.sortMode = 'multi'  // Enable multi-column sorting
 </script>
 ```
 
@@ -42,7 +43,7 @@ npm install @keenmate/web-grid
 
 ## Features
 
-- **Sorting** - Click column headers to sort ascending/descending
+- **Sorting** - Single or multi-column sorting with `sortMode` property
 - **Filtering** - Per-column text input filters
 - **Pagination** - Configurable page size with navigation
 - **Inline Editing** - 7 editor types with validation support
@@ -59,18 +60,23 @@ npm install @keenmate/web-grid
 |----------|------|---------|-------------|
 | `items` | `Array` | `[]` | Data array to display |
 | `columns` | `Array<Column>` | `[]` | Column definitions |
-| `sortable` | `boolean` | `false` | Enable column sorting |
+| `sortMode` | `string` | `'none'` | Sort mode: `'none'`, `'single'`, `'multi'` |
 | `filterable` | `boolean` | `false` | Enable column filtering |
 | `pageable` | `boolean` | `false` | Enable pagination |
 | `pageSize` | `number` | `10` | Rows per page |
 | `editable` | `boolean` | `false` | Enable cell editing |
 | `editTrigger` | `string` | `'dblclick'` | Edit trigger: `'click'`, `'dblclick'`, `'navigate'` |
+| `editStartSelection` | `string` | `'mousePosition'` | Cursor position when entering edit: `'mousePosition'`, `'selectAll'`, `'cursorAtStart'`, `'cursorAtEnd'` |
 | `striped` | `boolean` | `false` | Alternate row colors |
 | `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` |
 
 ## Column Definition
 
@@ -83,7 +89,7 @@ npm install @keenmate/web-grid
   maxWidth: '300px',            // Maximum width
   align: 'left',                // 'left', 'center', 'right'
   textOverflow: 'wrap',         // 'wrap' or 'ellipsis'
-  sortable: true,               // Enable sorting
+  sortable: false,              // Disable sorting for this column (when grid has sortMode enabled)
   filterable: true,             // Enable filtering
   editable: true,               // Enable editing
   editor: 'text',               // Editor type
@@ -91,7 +97,8 @@ npm install @keenmate/web-grid
   formatCallback: (value, row) => '',        // Value formatter
   templateCallback: (row, column) => '',     // Custom cell HTML
   cellClassCallback: (value, row) => '',     // Dynamic CSS class
-  beforeCommitCallback: (ctx) => true        // Validation
+  beforeCommitCallback: (ctx) => true,       // Validation
+  validationTooltipCallback: (ctx) => ''     // Custom HTML for validation error tooltip
 }
 ```
 
@@ -124,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

@@ -10,10 +10,11 @@
     { "name": "base-text-color-1", "required": true, "usage": "Primary cell and header text" },
     { "name": "base-text-color-2", "required": false, "usage": "Secondary text, subtitles" },
     { "name": "base-text-color-3", "required": false, "usage": "Placeholder, disabled, empty state text" },
-    { "name": "base-text-on-accent", "required": false, "usage": "Text on accent backgrounds" },
-    { "name": "base-surface-1", "required": true, "usage": "Table background, cell background, inputs" },
-    { "name": "base-surface-2", "required": true, "usage": "Header background, striped rows, pagination buttons" },
-    { "name": "base-surface-3", "required": false, "usage": "Hover states, sorted header, active buttons" },
+    { "name": "base-text-color-on-accent", "required": false, "usage": "Text on accent backgrounds" },
+    { "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, EditingCell, FocusedCell, SortState, DataRequestDetail, DataRequestTrigger, BeforeCommitResult, GridMode, ToggleVisibility, PaginationLabelsCallback, SummaryContentCallback } from './types.js';
+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';
 /**
  * WebGrid - Core logic class for the data grid
  *
@@ -8,7 +8,7 @@ import type { Column, CellValidationState, RowToolbarConfig, ContextMenuItem, Ro
 export declare class WebGrid<T = unknown> {
     protected _items: T[];
     protected _columns: Column<T>[];
-    protected _sortable: boolean;
+    protected _sortMode: SortMode;
     protected _filterable: boolean;
     protected _pageable: boolean;
     protected _pageSize: number;
@@ -17,6 +17,7 @@ export declare class WebGrid<T = unknown> {
     protected _hoverable: boolean;
     protected _editable: boolean;
     protected _editTrigger: EditTrigger;
+    protected _editStartSelection: EditStartSelection;
     protected _mode: GridMode;
     protected _dropdownToggleVisibility: ToggleVisibility;
     protected _dropdownShowOnFocus: boolean;
@@ -29,6 +30,7 @@ export declare class WebGrid<T = unknown> {
     protected _toolbarAlign: 'center' | 'top';
     protected _toolbarTopPosition: 'start' | 'center' | 'end' | 'cursor';
     protected _toolbarTrigger: 'hover' | 'click' | 'button';
+    protected _toolbarPosition: 'auto' | 'left' | 'right' | 'top';
     protected _contextMenu: ContextMenuItem<T>[] | undefined;
     protected _onrowchange: ((detail: RowChangeDetail<T>) => void) | undefined;
     protected _onroweditstart: ((detail: {
@@ -47,6 +49,7 @@ export declare class WebGrid<T = unknown> {
         field: string;
         error: string;
     }) => void) | undefined;
+    protected _validationTooltipCallback: ((context: ValidationTooltipContext<T>) => string | null) | undefined;
     protected _ontoolbarclick: ((detail: ToolbarClickDetail<T>) => void) | undefined;
     protected _onrowaction: ((detail: RowActionClickDetail<T>) => void) | undefined;
     protected _oncontextmenuopen: ((context: ContextMenuContext<T>) => void) | undefined;
@@ -88,6 +91,9 @@ export declare class WebGrid<T = unknown> {
     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;
@@ -106,6 +112,8 @@ export declare class WebGrid<T = unknown> {
     set editable(value: boolean);
     get editTrigger(): EditTrigger;
     set editTrigger(value: EditTrigger);
+    get editStartSelection(): EditStartSelection;
+    set editStartSelection(value: EditStartSelection);
     get mode(): GridMode;
     set mode(value: GridMode);
     get dropdownToggleVisibility(): ToggleVisibility;
@@ -141,6 +149,8 @@ export declare class WebGrid<T = unknown> {
     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 sort(): SortState[];
@@ -210,6 +220,8 @@ export declare class WebGrid<T = unknown> {
         field: string;
         error: string;
     }) => void) | undefined);
+    get validationTooltipCallback(): ((context: ValidationTooltipContext<T>) => string | null) | undefined;
+    set validationTooltipCallback(value: ((context: ValidationTooltipContext<T>) => string | null) | undefined);
     get ontoolbarclick(): ((detail: ToolbarClickDetail<T>) => void) | undefined;
     set ontoolbarclick(value: ((detail: ToolbarClickDetail<T>) => void) | undefined);
     set onrowaction(value: ((detail: RowActionClickDetail<T>) => void) | undefined);

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

@@ -47,6 +47,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/modules/tooltip/tooltip.d.ts

@@ -2,7 +2,7 @@ import type { GridContext } from '../types.js';
 /**
  * Show tooltip for an element
  */
-export declare function showTooltip<T>(ctx: GridContext<T>, anchor: HTMLElement, text: string, delay?: number): void;
+export declare function showTooltip<T>(ctx: GridContext<T>, anchor: HTMLElement, text: string, delay?: number, isHtml?: boolean): void;
 /**
  * Hide tooltip
  */
@@ -10,4 +10,4 @@ export declare function hideTooltip<T>(ctx: GridContext<T>, delay?: number): voi
 /**
  * Create and position tooltip element
  */
-export declare function createTooltip<T>(ctx: GridContext<T>, anchor: HTMLElement, text: string): void;
+export declare function createTooltip<T>(ctx: GridContext<T>, anchor: HTMLElement, content: string, isHtml?: boolean): void;

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export type GridMode = "read-only" | "excel" | "input-matrix";
 export type ToggleVisibility = "always" | "on-focus";
 export type OptionsLoadTrigger = "immediate" | "oneditstart" | "ondropdownopen";
 export type DateOutputFormat = "date" | "iso" | "timestamp";
-export type EditStartSelection = "selectAll" | "cursorAtStart" | "cursorAtEnd";
+export type EditStartSelection = "mousePosition" | "selectAll" | "cursorAtStart" | "cursorAtEnd";
 export type EditorOption = {
     value: string | number | boolean;
     label: string;
@@ -118,6 +118,14 @@ export type Column<T> = {
     tooltipCallback?: (value: unknown, row: T) => string | null;
     beforeCopyCallback?: (value: unknown, row: T) => string;
     beforePasteCallback?: (value: string, row: T) => unknown;
+    validationTooltipCallback?: (context: ValidationTooltipContext<T>) => string | null;
+};
+export type ValidationTooltipContext<T> = {
+    field: string;
+    error: string;
+    value: unknown;
+    row: T;
+    rowIndex: number;
 };
 export type RowChangeDetail<T> = {
     row: T;
@@ -178,6 +186,7 @@ export type ContextMenuItem<T> = {
 export type QuickGridProps<T> = {
     items: T[];
     columns: Column<T>[];
+    /** @deprecated Use sortMode instead */
     sortable?: boolean;
     filterable?: boolean;
     pageable?: boolean;
@@ -190,6 +199,7 @@ export type QuickGridProps<T> = {
     customStylesCallback?: () => string;
     rowClassCallback?: (row: T, rowIndex: number) => string | null;
     sort?: SortState[];
+    sortMode?: SortMode;
     currentPage?: number;
     totalItems?: number;
     showPagination?: boolean | 'auto';
@@ -202,6 +212,7 @@ export type QuickGridProps<T> = {
     summaryInline?: boolean;
     editable?: boolean;
     editTrigger?: EditTrigger;
+    editStartSelection?: EditStartSelection;
     mode?: GridMode;
     dropdownToggleVisibility?: ToggleVisibility;
     dropdownShowOnFocus?: boolean;
@@ -213,6 +224,7 @@ export type QuickGridProps<T> = {
     toolbarAlign?: 'center' | 'top';
     toolbarTopPosition?: 'start' | 'center' | 'end' | 'cursor';
     toolbarTrigger?: 'hover' | 'click' | 'button';
+    toolbarPosition?: 'auto' | 'left' | 'right' | 'top';
     showRowActions?: boolean;
     rowActions?: RowToolbarConfig<T>[];
     contextMenu?: ContextMenuItem<T>[];
@@ -241,6 +253,7 @@ export type QuickGridProps<T> = {
         field: string;
         error: string;
     }) => void;
+    validationTooltipCallback?: (context: ValidationTooltipContext<T>) => string | null;
     ontoolbarclick?: (detail: ToolbarClickDetail<T>) => void;
     onrowaction?: (detail: RowActionClickDetail<T>) => void;
     ondatarequest?: (detail: DataRequestDetail) => void;
@@ -260,6 +273,7 @@ export type FocusedCell = {
     colIndex: number;
 } | null;
 export type SortDirection = "asc" | "desc";
+export type SortMode = "none" | "single" | "multi";
 export type ToolbarRowGroup<T> = {
     rowNum: number;
     groups: {

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, EditorOption, EditorOptions, GridMode, ToggleVisibility, DataRequestDetail, SortState, PaginationLabelsCallback, SummaryContentCallback } from './types.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 { GridContext } from './modules/types.js';
 /**
  * GridElement - Custom HTML Element for WebGrid
@@ -83,6 +83,8 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     set editable(value: boolean);
     get editTrigger(): EditTrigger;
     set editTrigger(value: EditTrigger);
+    get editStartSelection(): EditStartSelection;
+    set editStartSelection(value: EditStartSelection);
     get mode(): GridMode;
     set mode(value: GridMode);
     get dropdownToggleVisibility(): ToggleVisibility;
@@ -107,6 +109,8 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     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 showRowActions(): boolean;
@@ -130,6 +134,8 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
         field: string;
         error: string;
     }) => void) | undefined);
+    get validationTooltipCallback(): ((context: ValidationTooltipContext<T>) => string | null) | undefined;
+    set validationTooltipCallback(value: ((context: ValidationTooltipContext<T>) => string | null) | undefined);
     set ontoolbarclick(value: ((detail: ToolbarClickDetail<T>) => void) | undefined);
     set onrowaction(value: ((detail: RowActionClickDetail<T>) => void) | undefined);
     set oncontextmenuopen(value: ((context: ContextMenuContext<T>) => void) | undefined);
@@ -145,6 +151,8 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     }) => void) | undefined);
     get sort(): SortState[];
     set sort(value: SortState[]);
+    get sortMode(): SortMode;
+    set sortMode(value: SortMode);
     get currentPage(): number;
     set currentPage(value: number);
     get totalItems(): number | null;