@keenmate/web-grid 1.0.3 → 1.0.5

package/README.md

@@ -2,21 +2,18 @@
 
 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
+## What's New in v1.0.5
 
-- **`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.
+- **Context menus flip at screen edges**: Both cell and header context menus now correctly flip to the opposite side when opened near a viewport edge (they were clipping before). Switched the root menu to `strategy: 'fixed'` + `position: fixed` so Floating UI's `flip`/`shift` run in viewport coordinates.
+- **Header submenus are viewport-aware**: Header menu submenus (e.g. Column Visibility) now use Floating UI with `placement: 'right-start'` and `flip` fallbacks, replacing the old CSS-only `left: 100%` positioning. A short hide delay lets the cursor cross the gap between parent item and submenu.
+- **Context menu closes on grid-internal scroll**: The menu now subscribes to both the `'window'` and `'container'` scroll sources. Previously, scrolling within the grid didn't close the menu because scroll events aren't composed across shadow DOM.
+- **Context menu offset flips with placement**: `contextMenuXOffset`/`contextMenuYOffset` are now applied via Floating UI's `offset` middleware (`mainAxis` / `alignmentAxis`), so the gap between cursor and menu stays correct even when the menu flips to `*-end` or `top-*`.
+- **Dropdown selected option readable in dark mode**: The selected option in select/combobox/autocomplete dropdowns no longer renders as pale blue against the dark surface. `--wg-accent-color-light` now falls back to a transparent `color-mix` that blends with the underlying surface in either theme.
 
-### v1.0.2
+## What's New in v1.0.4
 
-- **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.
+- **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`.
 
 ## Installation
 
@@ -24,37 +21,220 @@ A feature-rich, framework-agnostic data grid web component built with TypeScript
 npm install @keenmate/web-grid
 ```
 
-## Quick Start
+Or via CDN (no bundler):
 
-### ES Module (recommended)
+```html
+<script type="module" src="https://unpkg.com/@keenmate/web-grid"></script>
+```
+
+## Getting Started
+
+### Step 1 — Import the component
+
+Importing the package registers the `<web-grid>` custom element globally. You only need to import it once anywhere in your app.
+
+```javascript
+import '@keenmate/web-grid'
+```
+
+For vanilla HTML without a bundler:
+
+```html
+<script type="module" src="https://unpkg.com/@keenmate/web-grid"></script>
+```
+
+### Step 2 — Drop the element into your markup
 
 ```html
-<script type="module">
-  import '@keenmate/web-grid'
-</script>
+<web-grid id="grid" style="max-height: 400px"></web-grid>
+```
+
+`max-height` (or `height`) on the host is how you control sizing — see [Height Modes](#height-modes).
+
+### Step 3 — Assign data and columns
+
+The grid reads its configuration from properties on the element, not attributes. Grab a reference and set what you need:
+
+```javascript
+const grid = document.getElementById('grid')
+
+grid.items = [
+  { id: 1, name: 'Alice', age: 28, department: 'Engineering' },
+  { id: 2, name: 'Bob',   age: 34, department: 'Marketing' }
+]
+
+grid.columns = [
+  { field: 'id',         title: 'ID',         width: '60px' },
+  { field: 'name',       title: 'Name',       width: '160px' },
+  { field: 'age',        title: 'Age',        width: '80px', horizontalAlign: 'right' },
+  { field: 'department', title: 'Department', width: '160px' }
+]
+```
 
-<web-grid id="grid"></web-grid>
+That's the minimum — a read-only grid with the headers, rows, and columns you defined.
 
-<script type="module">
-  const grid = document.getElementById('grid')
-  grid.items = [
-    { id: 1, name: 'Alice', age: 28 },
-    { id: 2, name: 'Bob', age: 34 }
-  ]
-  grid.columns = [
-    { field: 'id', title: 'ID', width: '60px' },
-    { field: 'name', title: 'Name' },
-    { field: 'age', title: 'Age' }
-  ]
-  grid.sortMode = 'multi'  // Enable multi-column sorting
-</script>
+### Step 4 — Enable the features you need
+
+Turn on whatever the page calls for. Everything is off by default:
+
+```javascript
+grid.isStriped = true            // alternating row backgrounds
+grid.isHoverable = true          // hover highlight
+grid.isRowNumbersVisible = true  // leftmost # column
+grid.sortMode = 'multi'          // click headers to sort, Ctrl+click to add
+grid.isPageable = true
+grid.pageSize = 25
+grid.isEditable = true
+grid.editTrigger = 'navigate'    // Excel-like: type to edit the focused cell
+```
+
+### Essential Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `items` | `T[]` | Row data — the only required "content" property |
+| `columns` | `Column<T>[]` | Column definitions with at least a `field` each |
+| `isStriped` / `isHoverable` / `isRowNumbersVisible` | `boolean` | Cosmetic toggles |
+| `sortMode` | `'none' \| 'single' \| 'multi'` | Column sort behavior |
+| `isPageable` + `pageSize` | `boolean` + `number` | Pagination |
+| `isEditable` + `editTrigger` | `boolean` + `EditTrigger` | Enable inline editing and how it starts |
+| `isFilterable` | `boolean` | Per-column filter row under the headers |
+| `mode` | `'read-only' \| 'excel' \| 'input-matrix'` | Presets that set several of the above together |
+
+## Common Configurations
+
+Short recipes for common setups. Each sets only what's necessary on top of the Step 3 minimum.
+
+### Sortable grid
+
+```javascript
+grid.sortMode = 'multi'   // or 'single'
+```
+
+### Paginated grid with top + bottom pager
+
+```javascript
+grid.isPageable = true
+grid.pageSize = 25
+grid.paginationPosition = 'top-center|bottom-center'
+```
+
+### Editable grid (Excel-like navigation)
+
+```javascript
+grid.mode = 'excel'   // isEditable + editTrigger='navigate' + cellSelectionMode='click'
+```
+
+Or opt in manually for finer control:
+
+```javascript
+grid.isEditable = true
+grid.editTrigger = 'navigate'
 ```
 
-### UMD (Script Tag)
+### Per-column editors
+
+```javascript
+grid.columns = [
+  { field: 'name',       title: 'Name',  editor: 'text' },
+  { field: 'salary',     title: 'Salary', editor: 'number', editorOptions: { min: 0, step: 1000 } },
+  { field: 'department', title: 'Dept',  editor: 'select',
+    editorOptions: {
+      options: [
+        { value: 'eng', label: 'Engineering' },
+        { value: 'sal', label: 'Sales' }
+      ]
+    }
+  }
+]
+```
+
+### Height modes
+
+The grid's shadow DOM uses `max-height: inherit`, so setting `max-height` on the host controls its internal scroll container:
 
 ```html
-<script src="https://unpkg.com/@keenmate/web-grid"></script>
-<web-grid id="grid"></web-grid>
+<!-- Container: grid caps at 400px, scrolls internally -->
+<web-grid style="max-height: 400px"></web-grid>
+
+<!-- Full height: grid expands with content, page handles scrolling -->
+<web-grid style="height: 100%"></web-grid>
+```
+
+For full-height mode, also set `tableBorderOnly = true` so the grid doesn't capture wheel events:
+
+```javascript
+grid.tableBorderOnly = true
+```
+
+### Header context menu with column hide + visibility submenu
+
+```javascript
+grid.headerContextMenu = [
+  'sortAsc', 'sortDesc', 'clearSort',
+  { dividerBefore: true },
+  'hideColumn',         // hide the right-clicked column
+  'columnVisibility'    // submenu with a toggle per column
+]
+```
+
+### Hide a column programmatically
+
+```javascript
+grid.columns.find(c => c.field === 'email').isHidden = true
+grid.columns = [...grid.columns]   // reassign to trigger re-render
+```
+
+### Row toolbar
+
+```javascript
+grid.isRowToolbarVisible = true
+grid.rowToolbar = ['add', 'delete', 'duplicate', 'moveUp', 'moveDown']
+```
+
+### Master/detail — react to row focus
+
+```javascript
+grid.onrowfocus = ({ row, rowIndex }) => {
+  showDetailsFor(row)
+}
+```
+
+### Validate a cell before commit
+
+```javascript
+grid.columns = [{
+  field: 'email',
+  title: 'Email',
+  editor: 'text',
+  beforeCommitCallback: ({ value }) => {
+    if (!/^[^@]+@[^@]+$/.test(String(value))) {
+      return { valid: false, message: 'Invalid email address' }
+    }
+    return { valid: true }
+  }
+}]
+```
+
+### TypeScript
+
+Full type definitions ship with the package. Import types from the root:
+
+```typescript
+import '@keenmate/web-grid'
+import type { Column, RowChangeDetail } from '@keenmate/web-grid'
+
+interface Employee {
+  id: number
+  name: string
+  salary: number
+}
+
+const columns: Column<Employee>[] = [
+  { field: 'id',     title: 'ID',     width: '60px' },
+  { field: 'name',   title: 'Name',   width: '200px' },
+  { field: 'salary', title: 'Salary', editor: 'number' }
+]
 ```
 
 ## Features

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/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/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/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/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;