@keenmate/web-grid 1.0.1 → 1.0.4

package/README.md

@@ -2,6 +2,25 @@
 
 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.4
+
+- **Dirty cell/row indicator**: New `isDirtyIndicatorVisible` property (default: `true`). Edited cells show a subtle orange tint + corner triangle; row numbers get an orange left border. Themable via `--wg-dirty-*` variables. Public methods: `isCellDirty()`, `isRowDirty()`.
+- **Dropdown positioning fix**: Fixed dropdown editors appearing offset in shadow DOM by switching from `position: fixed` to `position: absolute`.
+
+### 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.
+
+### 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 +270,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 +632,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 |
@@ -842,6 +861,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/basic-setup.txt

@@ -89,6 +89,7 @@ page-size               pageSize                number     10        Rows per pa
 is-editable             isEditable              boolean    false     Enable cell editing
 edit-trigger            editTrigger             string     'dblclick' How editing starts (see below)
 is-row-numbers-visible  isRowNumbersVisible     boolean    false     Show row number column
+                        isDirtyIndicatorVisible boolean    true      Show dirty indicator on edited cells
 mode                    mode                    string     (none)    Grid mode (see below)
 is-scrollable           isScrollable            boolean    false     Enable scroll container
 freeze-columns          freezeColumns           number     0         Freeze first N columns

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/editing.txt

@@ -427,6 +427,27 @@ Draft behavior:
   - The onrowchange callback includes both row (original) and draftRow (with
     changes) so the consumer can compare.
 
+Dirty indicator:
+  grid.isDirtyIndicatorVisible (boolean, default: true)
+    When enabled, edited cells show a subtle orange background tint and a small
+    corner triangle. Row numbers show an orange left border when any cell in
+    the row has been modified.
+
+  grid.isCellDirty(rowIndex, field)  -- Returns true if the cell's draft value
+                                        differs from the original.
+  grid.isRowDirty(rowIndex)          -- Returns true if any cell in the row
+                                        has been modified (draft exists).
+
+  CSS variables for theming:
+    --wg-dirty-indicator-color       (default: #ed8b00)
+    --wg-dirty-indicator-size        (default: 6px)
+    --wg-dirty-cell-bg               (default: rgba(237, 139, 0, 0.08))
+    --wg-dirty-row-number-border-color (default: #ed8b00)
+
+  CSS classes applied:
+    .wg__cell--dirty                 -- on dirty data cells
+    .wg__row-number--dirty           -- on row number cells of dirty rows
+
 
 EVENTS (CALLBACKS)
 ------------------

package/ai/public-methods.txt

@@ -53,6 +53,12 @@ discardAllDrafts(): void
   Discard all draft changes across all rows. Reverts every edited cell
   to its original value.
 
+isCellDirty(rowIndex: number, field: string): boolean
+  Check if a specific cell has been modified (draft value differs from original).
+
+isRowDirty(rowIndex: number): boolean
+  Check if any cell in a row has been modified (draft exists for that row).
+
 
 ----------------------------------------------------------------------
 VALIDATION

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/styling-theming.txt

@@ -115,6 +115,9 @@ All four methods apply the same dark palette overrides:
   --wg-hover-bg: #3a3a3a
   --wg-danger-color: #f87c86
   --wg-danger-bg-light: #442726
+  --wg-dirty-indicator-color: #ffa940
+  --wg-dirty-cell-bg: rgba(255, 169, 64, 0.12)
+  --wg-dirty-row-number-border-color: #ffa940
 
 The attribute can be on the <web-grid> element itself or any ancestor:
 

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/grid.d.ts

@@ -28,6 +28,7 @@ export declare class WebGrid<T = unknown> {
     protected _isStickyRowNumbers: boolean;
     protected _freezeColumns: number;
     protected _invalidCells: CellValidationState[];
+    protected _isDirtyIndicatorVisible: boolean;
     protected _isRowToolbarVisible: boolean;
     protected _rowToolbar: RowToolbarConfig<T>[];
     protected _toolbarVerticalAlign: 'top' | 'center' | 'bottom';
@@ -200,6 +201,8 @@ export declare class WebGrid<T = unknown> {
     set isCheckboxAlwaysEditable(value: boolean);
     get isRowNumbersVisible(): boolean;
     set isRowNumbersVisible(value: boolean);
+    get isDirtyIndicatorVisible(): boolean;
+    set isDirtyIndicatorVisible(value: boolean);
     get isStickyRowNumbers(): boolean;
     set isStickyRowNumbers(value: boolean);
     get freezeColumns(): number;
@@ -544,6 +547,14 @@ export declare class WebGrid<T = unknown> {
     protected requestUpdate(): void;
     getRowDraft(rowIndex: number): T | undefined;
     hasRowDraft(rowIndex: number): boolean;
+    /**
+     * Check if a specific cell has been modified (draft value differs from original)
+     */
+    isCellDirty(rowIndex: number, field: string): boolean;
+    /**
+     * Check if any cell in a row has been modified
+     */
+    isRowDirty(rowIndex: number): boolean;
     discardRowDraft(rowIndex: number): void;
     /**
      * Discard draft value for a single cell (field)

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/types.d.ts

@@ -305,6 +305,7 @@ export type QuickGridProps<T> = {
     isStriped?: boolean;
     isHoverable?: boolean;
     isRowNumbersVisible?: boolean;
+    isDirtyIndicatorVisible?: boolean;
     isStickyRowNumbers?: boolean;
     freezeColumns?: number;
     class?: string;

package/dist/web-component.d.ts

@@ -113,6 +113,10 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     set isCheckboxAlwaysEditable(value: boolean);
     get isRowNumbersVisible(): boolean;
     set isRowNumbersVisible(value: boolean);
+    get isDirtyIndicatorVisible(): boolean;
+    set isDirtyIndicatorVisible(value: boolean);
+    isCellDirty(rowIndex: number, field: string): boolean;
+    isRowDirty(rowIndex: number): boolean;
     get isStickyRowNumbers(): boolean;
     set isStickyRowNumbers(value: boolean);
     get freezeColumns(): number;
@@ -367,6 +371,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).