@keenmate/web-grid 1.0.0 → 1.0.3

package/README.md

@@ -2,6 +2,22 @@
 
 A feature-rich, framework-agnostic data grid web component built with TypeScript. Sorting, filtering, pagination, inline editing (8 editor types), cell range selection, clipboard support, row toolbar, context menus, frozen columns, column reorder/resize, fill handle, virtual scroll, dark mode, and full CSS variable theming — all in a Shadow DOM encapsulated `<web-grid>` element.
 
+## What's New in v1.0.3
+
+- **`onrowfocus` fixes**: No longer fires during cell range selection (drag/shift+click). Mouse-triggered row focus now defers to click (mouseup) instead of mousedown; keyboard navigation still fires immediately.
+- **Cell selection visual fix**: Focused cell outline no longer persists during cell range drag.
+- **Toolbar fixes**: Tooltip hides when toolbar moves/closes. Selections cleared on toolbar action click. `triggerElement` in `ontoolbarclick` detail stays alive (no longer detached by synchronous re-render).
+- **Z-index layer system**: All z-index values now use CSS custom properties (`--wg-z-header`, `--wg-z-frozen`, etc.). Fixes cell selection bleeding through sticky header and frozen header stacking.
+- **Logging system**: loglevel-based logging with 4 categories (`GRID:INIT`, `GRID:DATA`, `GRID:UI`, `GRID:INTERACTION`). Enable via `window.components['web-grid'].logging.enableLogging()`.
+- **Runtime API**: `window.components['web-grid']` with `version()`, `config`, and `logging` — matching web-multiselect and web-daterangepicker.
+
+### v1.0.2
+
+- **Tooltip positioning in transformed containers**: Fixed tooltips appearing at grid's top-left when ancestor has CSS `transform`. Switched to `position: absolute` with `:host` as positioning context.
+- **HTML tooltips**: New `isTooltipHtml` column option for rich tooltip content.
+- **`ontoolbarclick` detail**: Now includes `event` (MouseEvent) and `triggerElement` (HTMLElement) for anchoring popovers to toolbar buttons inside shadow DOM.
+- **Tooltip show delay**: Reduced default from 400ms to 200ms.
+
 ## Installation
 
 ```bash
@@ -251,7 +267,7 @@ This architecture separates mode detection (the adapter decides *what* action a
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `tooltipShowDelay` | `number` | `400` | Delay in ms before showing tooltip |
+| `tooltipShowDelay` | `number` | `200` | Delay in ms before showing tooltip |
 | `tooltipHideDelay` | `number` | `100` | Delay in ms before hiding tooltip |
 
 ### Summary
@@ -613,7 +629,7 @@ These are **callback properties** set on the grid element, not DOM events. Use t
 | `onroweditstart` | `(detail: { row, rowIndex, field }) => void` | Editing started on a cell |
 | `onroweditcancel` | `(detail: { row, rowIndex, field }) => void` | Edit was cancelled (Escape) |
 | `onvalidationerror` | `(detail: { row, rowIndex, field, error }) => void` | Validation failed on commit |
-| `ontoolbarclick` | `(detail: ToolbarClickDetail<T>) => void` | Toolbar button clicked. Detail: `{ item, rowIndex, row }` |
+| `ontoolbarclick` | `(detail: ToolbarClickDetail<T>) => void` | Toolbar button clicked. Detail: `{ item, rowIndex, row, event, triggerElement }` |
 | `onrowaction` | `(detail: { action, rowIndex, row }) => void` | *Legacy* — use `ontoolbarclick` |
 | `oncontextmenuopen` | `(context: ContextMenuContext<T>) => void` | Cell context menu opened |
 | `onheadercontextmenuopen` | `(context: HeaderMenuContext<T>) => void` | Header context menu opened |
@@ -779,9 +795,18 @@ The manifest follows the [component-variables schema](https://raw.githubusercont
 
 Dark mode is triggered automatically by:
 - OS preference: `@media (prefers-color-scheme: dark)`
-- Attribute: `data-theme="dark"` on ancestor
-- Bootstrap: `data-bs-theme="dark"` on ancestor
-- Class: `.dark` on ancestor (Tailwind CSS)
+- Attribute: `data-theme="dark"` on any ancestor or host element
+- Bootstrap: `data-bs-theme="dark"` on any ancestor or host element
+- Class: `.dark` on any ancestor (Tailwind CSS)
+
+To **force light mode** when the OS is in dark mode, set one of:
+- Attribute: `data-theme="light"` on any ancestor or host element
+- Bootstrap: `data-bs-theme="light"` on any ancestor or host element
+- Class: `.light` on any ancestor (Tailwind CSS)
+
+This is useful when your app manages its own theme (e.g. via a toggle) and needs to override the OS preference. The light mode selectors restore the `--base-*` fallback chain so theme-designer values are respected.
+
+Ancestor detection uses `:host-context()` to cross shadow DOM boundaries (Chrome 88+, Firefox 128+, Safari 15.4+).
 
 ### Dynamic Cell & Row Styling
 
@@ -833,6 +858,25 @@ grid.labels = {
 }
 ```
 
+## Runtime API
+
+The component registers itself at `window.components['web-grid']` for runtime introspection:
+
+```javascript
+// Check version
+window.components['web-grid'].version()  // "1.0.3"
+
+// Package info
+window.components['web-grid'].config  // { name, version, author, license, repository, homepage }
+
+// Logging (silent by default)
+window.components['web-grid'].logging.enableLogging()         // Enable all at debug level
+window.components['web-grid'].logging.setLogLevel('info')     // Set level: trace|debug|info|warn|error|silent
+window.components['web-grid'].logging.disableLogging()        // Back to silent
+window.components['web-grid'].logging.setCategoryLevel('GRID:UI', 'debug')  // Per-category
+window.components['web-grid'].logging.getCategories()         // ['GRID:INIT', 'GRID:DATA', 'GRID:UI', 'GRID:INTERACTION']
+```
+
 ## Browser Support
 
 - Chrome/Edge 88+

package/ai/callbacks-events.txt

@@ -39,7 +39,8 @@ onvalidationerror
 ontoolbarclick
   Signature: (detail: ToolbarClickDetail<T>) => void
   Fires when a toolbar button is clicked.
-  Detail: { item: NormalizedToolbarItem<T>, rowIndex: number, row: T }
+  Detail: { item: NormalizedToolbarItem<T>, rowIndex: number, row: T, event: MouseEvent, triggerElement: HTMLElement }
+  The triggerElement is the clicked button inside the shadow DOM — usable as a Floating UI anchor for popovers.
 
 onrowaction
   Signature: (detail: { action: string, rowIndex: number, row: T }) => void

package/ai/columns.txt

@@ -301,7 +301,7 @@ tooltipCallback ((value: unknown, row: T) => string | null)
         row.description ? row.description : null
 
     Tooltip show/hide delays are controlled by grid-level properties:
-      tooltipShowDelay (default: 400ms)
+      tooltipShowDelay (default: 200ms)
       tooltipHideDelay (default: 100ms)
 
 

package/ai/selection.txt

@@ -222,8 +222,10 @@ Master/detail pattern:
   }
 
 Behavior:
-  - Click on data cell -> sets focusedRowIndex, fires onrowfocus
-  - Click on row number -> selects row but does NOT change focus
+  - Click on data cell -> fires onrowfocus on mouseup (click), NOT on mousedown
+  - Keyboard navigation (Tab, arrows) -> fires onrowfocus immediately on focus
+  - Click on row number -> selects row but does NOT change focus or fire onrowfocus
+  - Cell range selection (drag/shift+click) -> does NOT fire onrowfocus
   - Click outside grid -> clears focus (focusedRowIndex becomes null)
   - Starting cell range drag -> clears focus
   - Programmatic: grid.focusedRowIndex = 3 (focuses row 3, fires onrowfocus)

package/ai/toolbar-actions.txt

@@ -383,6 +383,8 @@ ontoolbarclick:
           item: NormalizedToolbarItem<T>
           rowIndex: number
           row: T
+          event: MouseEvent              // Original click event
+          triggerElement: HTMLElement     // The clicked button element (usable as Floating UI anchor)
         }
 
     This fires AFTER the item's own onclick handler. For predefined

package/ai/typescript-types.txt

@@ -477,7 +477,7 @@ ADDITIONAL EXPORTED TYPES
   type ColumnOrderState = { field: string, order: number }
   type ColumnResizeDetail = { field: string, oldWidth: string, newWidth: string, allWidths: ColumnWidthState[] }
   type ColumnReorderDetail = { field: string, fromIndex: number, toIndex: number, allOrder: ColumnOrderState[] }
-  type ToolbarClickDetail<T> = { item: NormalizedToolbarItem<T>, rowIndex: number, row: T }
+  type ToolbarClickDetail<T> = { item: NormalizedToolbarItem<T>, rowIndex: number, row: T, event: MouseEvent, triggerElement: HTMLElement }
   type ToolbarTooltip = { description?: string, shortcut?: string }
   type SummaryContext<T> = { items: T[], allItems: T[], totalItems: number, currentPage: number, pageSize: number, metadata: unknown }
   type SummaryContentCallback<T> = (context: SummaryContext<T>) => string

package/dist/logger.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Logging configuration using loglevel with categorized loggers
+ *
+ * Categories:
+ * - GRID:INIT: Component initialization and configuration
+ * - GRID:DATA: Data loading, sorting, filtering, pagination
+ * - GRID:UI: UI updates, rendering, scroll, resize operations
+ * - GRID:INTERACTION: User interactions, clicks, selections, keyboard events
+ *
+ * Usage:
+ * - By default, all logging is disabled (silent mode) for production
+ * - Enable logging in browser console:
+ *   ```javascript
+ *   // Enable all logging at debug level
+ *   window.components['web-grid'].logging.enableLogging();
+ *
+ *   // Or set a specific log level for all categories
+ *   window.components['web-grid'].logging.setLogLevel('info');
+ *
+ *   // Or enable/disable specific categories
+ *   window.components['web-grid'].logging.disableLogging();  // First disable all
+ *   window.components['web-grid'].logging.setCategoryLevel('GRID:UI', 'debug');
+ *   window.components['web-grid'].logging.setCategoryLevel('GRID:DATA', 'info');
+ *   ```
+ */
+import log from './vendor/loglevel/index.js';
+export declare const initLogger: any;
+export declare const dataLogger: any;
+export declare const uiLogger: any;
+export declare const interactionLogger: any;
+export default log;
+/**
+ * List of all logging categories for introspection
+ */
+export declare const LOGGING_CATEGORIES: string[];
+/**
+ * Enable all logging (set to debug level)
+ */
+export declare function enableLogging(): void;
+/**
+ * Disable all logging (set to silent level)
+ */
+export declare function disableLogging(): void;
+/**
+ * Set log level for all loggers
+ * @param level Log level to set ('trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent')
+ */
+export declare function setLogLevel(level: string): void;
+/**
+ * Set log level for a specific category
+ * @param category Category logger to configure (e.g., 'GRID:UI')
+ * @param level Log level to set ('trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent')
+ */
+export declare function setCategoryLevel(category: string, level: string): void;

package/dist/modules/actions/adapter.d.ts

@@ -73,6 +73,10 @@ export declare class ActionPipelineAdapter<T = unknown> {
      * Note: This checks the original context, not the Object.create'd executor context
      */
     isDatepickerOpen(): boolean;
+    /**
+     * Clear all selections (row, cell range, column) through the pipeline
+     */
+    clearSelection(): void;
 }
 /**
  * Create an action pipeline adapter for a grid context

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

@@ -33,7 +33,7 @@ export declare function renderToolbarHTML<T>(items: NormalizedToolbarItem<T>[],
 /**
  * Open toolbar for a specific row
  */
-export declare function openToolbar<T>(ctx: GridContext<T>, rowElement: HTMLElement, rowIndex: number, items: NormalizedToolbarItem<T>[], row: T, onItemClick: (item: NormalizedToolbarItem<T>) => void, cursorX?: number): void;
+export declare function openToolbar<T>(ctx: GridContext<T>, rowElement: HTMLElement, rowIndex: number, items: NormalizedToolbarItem<T>[], row: T, onItemClick: (item: NormalizedToolbarItem<T>, event: MouseEvent, triggerElement: HTMLElement) => void, cursorX?: number): void;
 /**
  * Close the active toolbar
  */

package/dist/types.d.ts

@@ -125,6 +125,7 @@ export type Column<T> = {
     isEditButtonVisible?: boolean;
     tooltipMember?: string;
     tooltipCallback?: (value: unknown, row: T) => string | null;
+    isTooltipHtml?: boolean;
     beforeCopyCallback?: (value: unknown, row: T) => string;
     beforePasteCallback?: (value: string, row: T) => unknown;
     validationTooltipCallback?: (context: ValidationTooltipContext<T>) => string | null;
@@ -196,6 +197,8 @@ export type ToolbarClickDetail<T> = {
     item: NormalizedToolbarItem<T>;
     rowIndex: number;
     row: T;
+    event: MouseEvent;
+    triggerElement: HTMLElement;
 };
 export type RowActionType = PredefinedToolbarItemType;
 export type RowActionClickDetail<T> = {

package/dist/web-component.d.ts

@@ -367,6 +367,8 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
      * Handle keydown in editor inputs
      */
     private handleEditorKeyDown;
+    /** Tracks whether a mouse button is currently pressed on the table (mousedown→mouseup) */
+    private _isMouseDown;
     private attachEventListeners;
     /**
      * Scroll to a row position programmatically (keyboard navigation).