@keenmate/web-grid 1.2.0-rc01 → 1.2.0-rc02

package/README.md

@@ -2,6 +2,17 @@
 
 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.2.0-rc02
+
+- **Excel-like commit-on-click-away** — new `shouldCommitOnClickAway` property (defaults to `true`). Clicking a different cell while editing now commits the in-progress value through `beforeCommitCallback` / `validateCallback` instead of silently discarding it. Set to `false` to keep the legacy discard behavior. Companion fix: row focus (`.wg__row--focused`) now applies on the first cell click — previously it only landed on the second.
+- **CSS surface taxonomy aligned with pure-admin's `--base-*` names** — `--wg-surface-1/2/3` renamed to `--wg-main-bg` / `--wg-elevated-bg`, `--wg-surface-floating` → `--wg-dropdown-bg` (`--wg-surface-3` merged into `--wg-hover-bg`). Consumer overrides of the old names need to migrate; see the CHANGELOG mapping table.
+- **Dark mode reworked to respect consumer themes** — the dark-mode override blocks used to set `--wg-*` to hardcoded literals, silently overriding pure-admin / theme-designer values. They now just flip `color-scheme` and let `light-dark()` in `variables.css` do the work. The consumer's `--base-*` chain stays the source of truth.
+- **OS-aware dark mode via `light-dark()` fallbacks** — every hardcoded fallback in `variables.css` is wrapped in `light-dark(<light>, <dark>)`. A consumer who only sets `body { color-scheme: dark }` (no overrides, no framework class) now gets a sensible dark palette automatically.
+- **CSS architecture refactor: `@layer` cascade + canonical file set** — `main.css` now declares `@layer variables, component, overrides;` so consumer rules beat library defaults without `!important`. CSS filenames dropped the underscore prefix (pure-CSS doesn't use SASS-partial convention). New canonical Tier-2 files (`controls.css` / `floating.css` / `states.css` / `animations.css`) match the cross-component pattern.
+- **`--base-active-bg` + `--base-inverse-bg`** — two new cross-component theming hooks. `--base-active-bg` distinguishes pressed from hover; `--base-inverse-bg` covers tooltip and future inverse UI surfaces. Both are optional and additive.
+- **Context menu was leaking through stale `--base-*` names** — was referencing `--base-layer-01` / `--base-stroke-default` / `--base-error-color` (all long-removed in pure-admin). Now uses the canonical names; consumers loading a pure-admin theme finally get themed context menus instead of silent fallbacks.
+- **WCAG contrast e2e suite** — 18 assertions check header / body / hover / focused / selected-row / editing-cell contrast against the 3:1 threshold (WCAG AA for non-text UI). Catches theme regressions invisible to visual smoke tests.
+
 ## What's New in v1.2.0-rc01
 
 - **Tree mode polish**: The column marked `isTree: true` is now read-only by default (editing it conflicts with the toggle); Tab / Shift-Tab in heterogeneous trees skip rows where every cell is read-only, and the next editable cell auto-opens its editor after a Tab commit; `'expand-all'`, `'collapse-all'`, `'expand-tree'`, `'collapse-tree'` are now usable as predefined context-menu items via string shorthand or `{ type: ... }` object form. Tree chevron is a single rotating glyph (120 ms transition) on an inline-flex layout. CSS class `wg__tree-cell-content` renamed to `wg__tree-cell-body`.
@@ -10,14 +21,6 @@ A feature-rich, framework-agnostic data grid web component built with TypeScript
 - **Datepicker no longer closes when you click its own chrome**: previously, clicking the chevrons / month/year header / disabled days appeared as "outside the grid" to two internal listeners and silently tore the picker down. Now both listeners recognize our `document.body`-hosted popovers (datepicker + cell/header context menus) as part of the grid's logical scope. Same fix protects the cell and header context menus from the same class of bug.
 - **Datepicker `outputFormat` is honored from the action pipeline**: a column declaring `editorOptions.outputFormat: 'timestamp'` (or `'date'`) now actually emits a number (or `Date`) instead of an ISO string when commit goes through the modern pipeline executor (`editTrigger='always'` and keyboard-driven select).
 
-## What's New in v1.1.0
-
-- **Tree / hierarchy mode**: Render tree-structured data using ltree-style path strings (`"1.2.3"`, `"/a/b/c"`, `"C:\\Win\\Sys"` — separator auto-detected). Mark one column with `isTree: true` to add depth-based indentation and an expand/collapse chevron. Sort is sibling-aware, filter auto-expands ancestors of matches, pagination operates on visible rows. New props: `treePathMember`, `treeLevelMember`, `treeParentMember`, `treeSeparator`, `treeDataSorted`, `expandedPaths`, `defaultExpandDepth`. Methods: `toggleExpandedPath`, `expandAll`, `collapseAll`, `getRowTreeInfo`. Event: `onexpandedpathschange`.
-- **Custom chevron icons via `treeChevronCallback`**: Receives `{ expanded, hasChildren, row, level, path }`, returns HTML for the chevron's inner content. Result is cached per `(row, expanded, hasChildren)` so the callback fires at most a handful of times per row. Use it for file/folder icons, status indicators, anything per-row. Static fallbacks: `treeExpandedGlyph` / `treeCollapsedGlyph`.
-- **Double-click to expand/collapse**: New `treeDoubleClickBehavior: 'none' | 'toggle'`. When set to `'toggle'`, double-clicking anywhere in the tree column expands/collapses the node — works reliably even when the cell DOM is re-rendered between clicks (uses `MouseEvent.detail`, not the unreliable native `dblclick`).
-- **No more spurious `onrowchange` events**: Entering edit mode and exiting via arrow keys without typing no longer fires phantom "X → X" change events. `commitEdit` now only fires `onrowchange` when the value actually changed (or validation failed).
-- **Pathological filler-cell width fix**: Removed `min-width: max-content` from `.wg__table` — it was redundant with `table-layout: fixed` and triggered intrinsic-size computation that ballooned the filler to hundreds of thousands of pixels in some browsers (Firefox especially) when cells contained absolutely-positioned editors.
-
 ## Installation
 
 ```bash
@@ -930,7 +933,7 @@ web-grid {
 /* Or set base variables for all KeenMate components */
 :root {
   --base-accent-color: #10b981;
-  --base-layer-1: #ffffff;
+  --base-main-bg: #ffffff;
 }
 ```
 
@@ -953,8 +956,10 @@ This means:
 |----------|-------------|
 | `--wg-accent-color` | Primary accent color |
 | `--wg-text-color-1` | Primary text color |
-| `--wg-surface-1` | Background color |
-| `--wg-surface-2` | Alternate row/header background |
+| `--wg-main-bg` | Background color (table body, cells) |
+| `--wg-elevated-bg` | Alternate row/header background |
+| `--wg-hover-bg` | Hover background (rows, buttons) |
+| `--wg-dropdown-bg` | Floating surfaces (toolbar, context menu, dropdowns) |
 | `--wg-border-color` | Border color |
 
 ### Component Variables Manifest

package/ai/fill-handle.txt

@@ -113,7 +113,7 @@ prevents accidental fills from clicks). During the drag:
 
 CSS variables for the fill handle visual:
   --wg-fill-handle-size          Default: 8px
-  --wg-fill-handle-bg            Default: var(--wg-surface-1)
+  --wg-fill-handle-bg            Default: var(--wg-main-bg)
   --wg-fill-handle-border-color  Default: var(--wg-accent-color)
   --wg-fill-handle-border-width  Default: 2px
   --wg-fill-range-bg             Default: color-mix(accent 15%, transparent)

package/ai/frozen-columns.txt

@@ -74,7 +74,7 @@ color against the opaque frozen column base color instead of transparent:
 
   .wg__row--selected > .wg__cell--frozen {
     background: color-mix(in srgb, var(--wg-accent-color) 15%,
-      var(--wg-frozen-column-bg, var(--wg-surface-1))) !important;
+      var(--wg-frozen-column-bg, var(--wg-main-bg))) !important;
   }
 
 
@@ -105,7 +105,7 @@ The shadow only appears when the wg--scrolled-horizontal class is present
 on the container (set when scrollLeft > 0).
 
 Other frozen column CSS variables:
-  --wg-frozen-column-bg       Default: var(--wg-surface-1)
+  --wg-frozen-column-bg       Default: var(--wg-main-bg)
   --wg-frozen-header-bg       Default: color-mix(in srgb, accent 8%, header-bg)
   --wg-frozen-column-border   Default: 2px solid var(--wg-border-color)
   --wg-cell-splitter-color    Border color for frozen column separator

package/ai/row-locking.txt

@@ -148,7 +148,7 @@ Locked rows receive the following visual treatment:
   - Lock icon has cursor: help and full opacity (overrides row opacity)
 
 CSS variables:
-  --wg-row-locked-bg       Default: var(--base-disabled-bg, var(--wg-surface-2))
+  --wg-row-locked-bg       Default: var(--base-disabled-bg, var(--wg-elevated-bg))
   --wg-row-locked-opacity  Default: 0.7
 
 

package/ai/styling-theming.txt

@@ -9,7 +9,7 @@ Each --wg-* variable falls back to a --base-* variable, then to a hardcoded defa
 
   :host {
     --wg-accent-color: var(--base-accent-color, #0078d4);
-    --wg-surface-1: var(--base-main-bg, #ffffff);
+    --wg-main-bg: var(--base-main-bg, #ffffff);
     --wg-font-size-base: calc(var(--base-font-size-sm, 1.4) * var(--wg-rem));
   }
 
@@ -23,7 +23,7 @@ Example -- theme all KeenMate components at once:
 
   :root {
     --base-accent-color: #10b981;
-    --base-layer-1: #ffffff;
+    --base-main-bg: #ffffff;
     --base-font-family: 'Inter', sans-serif;
   }
 
@@ -54,16 +54,17 @@ Colors:
                              Falls back to: --base-text-color-1, default: #242424
   --wg-text-color-2          Secondary text (row numbers, labels)
   --wg-text-color-3          Muted text (placeholders, empty states)
-  --wg-surface-1             Main background (table body, cells)
+  --wg-main-bg               Main background (table body, cells)
                              Falls back to: --base-main-bg, default: #ffffff
-  --wg-surface-2             Elevated background (headers, striped rows)
+  --wg-elevated-bg           Elevated background (headers, striped rows)
                              Falls back to: --base-elevated-bg, default: #f5f5f5
-  --wg-surface-3             Hover background (row hover, button hover)
+  --wg-hover-bg              Hover background (row hover, button hover)
+                             Falls back to: --base-hover-bg, default: color-mix derived
   --wg-border-color          All borders (table, cells, header separators)
                              Falls back to: --base-border-color, default: #e0e0e0
 
 Header:
-  --wg-header-bg             Header row background (defaults to --wg-surface-2)
+  --wg-header-bg             Header row background (defaults to --wg-elevated-bg)
   --wg-header-bg-hover       Sortable header on hover
   --wg-header-color          Header text color
   --wg-header-border         Bottom border below header (2px solid)
@@ -71,8 +72,8 @@ Header:
   --wg-header-font-weight    Header text weight (semibold)
 
 Rows:
-  --wg-row-bg-hover          Row hover when isHoverable=true (defaults to --wg-surface-3)
-  --wg-row-bg-even           Striped even rows when isStriped=true (defaults to --wg-surface-2)
+  --wg-row-bg-hover          Row hover when isHoverable=true (defaults to --wg-hover-bg)
+  --wg-row-bg-even           Striped even rows when isStriped=true (defaults to --wg-elevated-bg)
   --wg-row-border            Border between rows
 
 Typography:
@@ -104,15 +105,15 @@ Dark mode activates automatically. No configuration needed. Detection methods:
 
 All four methods apply the same dark palette overrides:
 
-  --wg-surface-1: #1f1f1f
-  --wg-surface-2: #2b2b2b
-  --wg-surface-3: #333333
+  --wg-main-bg: #1f1f1f
+  --wg-elevated-bg: #2b2b2b
+  --wg-hover-bg: #3a3a3a
   --wg-text-color-1: #e0e0e0
   --wg-text-color-2: #c0c0c0
   --wg-text-color-3: #a0a0a0
   --wg-border-color: #3d3d3d
   --wg-input-bg: #1f1f1f
-  --wg-hover-bg: #3a3a3a
+  --wg-active-bg: #4a4a4a
   --wg-danger-color: #f87c86
   --wg-danger-bg-light: #442726
   --wg-dirty-indicator-color: #ffa940

package/component-variables.manifest.json

@@ -13,10 +13,12 @@
     { "name": "base-text-color-on-accent", "required": false, "usage": "Text color on accent-colored backgrounds" },
     { "name": "base-text-inverted", "required": false, "usage": "Text on dark backgrounds (selected row numbers)" },
     { "name": "base-main-bg", "required": true, "usage": "Table body background, cell backgrounds, input fields" },
-    { "name": "base-elevated-bg", "required": true, "usage": "Header row, striped even rows, pagination bar" },
-    { "name": "base-hover-bg", "required": false, "usage": "Row hover, sorted column header, button hover states" },
+    { "name": "base-elevated-bg", "required": true, "usage": "Header row, striped even rows, pagination bar; also secondary fallback for base-dropdown-bg" },
+    { "name": "base-hover-bg", "required": false, "usage": "Row hover, sorted column header, button hover background (primary lookup; falls back to text/main color-mix)" },
+    { "name": "base-active-bg", "required": false, "usage": "Pressed/active button background, selected option background (primary lookup; falls back to text/main color-mix)" },
     { "name": "base-disabled-bg", "required": false, "usage": "Read-only and disabled cell backgrounds, locked row backgrounds" },
-    { "name": "base-dropdown-bg", "required": false, "usage": "Floating toolbar, context menu, dropdown panels" },
+    { "name": "base-dropdown-bg", "required": false, "usage": "Floating toolbar, context menu, dropdown panels (primary lookup; chains through base-elevated-bg)" },
+    { "name": "base-inverse-bg", "required": false, "usage": "Secondary fallback for tooltip background (inverse-colored surface — dark in light mode, light in dark mode)" },
     { "name": "base-border-color", "required": true, "usage": "Table border, cell borders, header separators" },
     { "name": "base-input-bg", "required": false, "usage": "Filter input fields, editor text inputs" },
     { "name": "base-input-color", "required": false, "usage": "Text color in filter and editor inputs" },
@@ -54,10 +56,9 @@
     { "name": "wg-text-color-3", "category": "text", "usage": "Placeholder text, disabled text, empty state message, date trigger" },
     { "name": "wg-text-on-accent", "category": "text", "usage": "Text on accent backgrounds (Go button, active pagination)" },
 
-    { "name": "wg-surface-1", "category": "surface", "usage": "Table body, cell backgrounds, filter input background" },
-    { "name": "wg-surface-2", "category": "surface", "usage": "Header row, striped even rows, read-only cells, shortcut key badges" },
-    { "name": "wg-surface-3", "category": "surface", "usage": "Row hover background, sorted header, pagination button hover" },
-    { "name": "wg-surface-floating", "category": "surface", "usage": "Floating toolbar background, context menu, dropdown panels" },
+    { "name": "wg-main-bg", "category": "surface", "usage": "Table body, cell backgrounds, filter input background" },
+    { "name": "wg-elevated-bg", "category": "surface", "usage": "Header row, striped even rows, read-only cells, shortcut key badges" },
+    { "name": "wg-dropdown-bg", "category": "surface", "usage": "Floating toolbar background, context menu, dropdown panels" },
 
     { "name": "wg-border-color", "category": "border", "usage": "Table border, cell borders, header bottom, toolbar dividers" },
     { "name": "wg-border-color-hover", "category": "border", "usage": "Pagination button border on hover" },

package/dist/grid.d.ts

@@ -32,6 +32,7 @@ export declare class WebGrid<T = unknown> {
     protected _isRowEditable: boolean | ((row: T) => boolean) | undefined;
     protected _editTrigger: EditTrigger;
     protected _editStartSelection: EditStartSelection;
+    protected _shouldCommitOnClickAway: boolean;
     protected _mode: GridMode;
     protected _dropdownToggleVisibility: ToggleVisibility;
     protected _shouldShowDropdownOnFocus: boolean;
@@ -221,6 +222,8 @@ export declare class WebGrid<T = unknown> {
     set editTrigger(value: EditTrigger);
     get editStartSelection(): EditStartSelection;
     set editStartSelection(value: EditStartSelection);
+    get shouldCommitOnClickAway(): boolean;
+    set shouldCommitOnClickAway(value: boolean);
     get mode(): GridMode;
     set mode(value: GridMode);
     get dropdownToggleVisibility(): ToggleVisibility;

package/dist/types.d.ts

@@ -339,6 +339,7 @@ export type QuickGridProps<T> = {
     isRowEditable?: boolean | ((row: T) => boolean);
     editTrigger?: EditTrigger;
     editStartSelection?: EditStartSelection;
+    shouldCommitOnClickAway?: boolean;
     mode?: GridMode;
     dropdownToggleVisibility?: ToggleVisibility;
     shouldShowDropdownOnFocus?: boolean;

package/dist/web-component.d.ts

@@ -110,6 +110,8 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     set editTrigger(value: EditTrigger);
     get editStartSelection(): EditStartSelection;
     set editStartSelection(value: EditStartSelection);
+    get shouldCommitOnClickAway(): boolean;
+    set shouldCommitOnClickAway(value: boolean);
     get mode(): GridMode;
     set mode(value: GridMode);
     get dropdownToggleVisibility(): ToggleVisibility;
@@ -452,6 +454,14 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
      * Clear all selections (cell range, row, column) and their visual borders
      */
     private clearAllSelections;
+    /**
+     * Called from cell-transition click handlers in place of grid.cancelEdit().
+     * Reads the in-progress editor value and commits it (Excel-like) when
+     * shouldCommitOnClickAway is true; falls back to cancel when false or when
+     * the editor DOM can't be read. Must be called BEFORE renderCell wipes
+     * the editor element.
+     */
+    private commitOrCancelEditOnTransition;
     /**
      * Surgically update row focus visual (add/remove wg__row--focused class)
      * Avoids full re-render to preserve cell focus