@ornery/ui-grid-vanilla 0.1.10 → 1.0.1

package/AGENTS.md

@@ -0,0 +1,70 @@
+# @ornery/ui-grid-vanilla — Agent Instructions
+
+The rendering engine. A framework-free custom element (`<ui-grid-element>`) that owns the Shadow DOM, CSS Grid layout, event handling, and the `VanillaGridController` state machine. Angular and React wrappers mount this element — they never render cells themselves.
+
+## Build & Test
+
+```bash
+npm run build --prefix projects/ui-grid-vanilla   # tsup → dist/
+npm test --prefix projects/ui-grid-vanilla        # vitest (138 tests)
+```
+
+Depends on `@ornery/ui-grid-core` — build core first.
+
+## Key Files
+
+| File | Responsibility |
+|------|---------------|
+| `grid-controller.ts` | `VanillaGridController` — all mutable grid state, snapshot emission, column width calculation |
+| `ui-grid-standalone.element.ts` | Custom element class: lifecycle, render orchestration, scroll handling, ResizeObserver |
+| `render.ts` | HTML string builders for header/filter/body cells |
+| `patch.ts` | DOM-diffing fast path: patches existing shadow DOM without full re-render |
+| `events.ts` | All event listeners: click, mousedown (resize drag), dblclick (auto-fit), keydown, scroll, drag-and-drop |
+| `focus.ts` | CellNav focus management, `measureAutoColumnWidth` |
+| `framework-slots.ts` | `FrameworkSlotBridge` — stages slot add/remove deltas, `flush()` dispatches `cellSlotsChanged` |
+| `attribute-bridge.ts` | Parses HTML attributes into `GridOptions` |
+| `templates/index.ts` | Markup fragment helpers (filterRow, bodyVirtual, bodyStatic) |
+| `ui-grid-shell.template.ts` | Full shell template (grid-frame → grid-table → header-strip + filter-strip + body-viewport) |
+
+## Architecture
+
+### Render Paths
+
+1. **`renderFull`** — Full innerHTML swap of the shadow DOM shell. Used on structure changes (column add/remove, virtualization toggle).
+2. **`renderPatch`** — In-place DOM mutation. Header grid-template-columns, filter cells, body rows patched individually. Preserves focus and scroll.
+3. **`renderVirtualBody`** — Scroll-triggered fast path. Only replaces `.grid-virtual-body` innerHTML + calls `frameworkSlots.flush()`.
+4. **`patchCells`** — Data-only update. Iterates existing body cells, updates `.cell-content` innerHTML.
+
+### Column Width (drawnWidth)
+
+Column widths are resolved to **fixed pixel values** by `buildGridTemplateColumns()`, mirroring the old ui-grid's `updateColumnWidths`/`drawnWidth` approach:
+
+- Fixed-px columns: used as-is
+- Percentage columns: resolved against viewport width
+- Flex columns (default `minmax(11rem, 1fr)`): remaining space divided equally, minimum 176px
+- Selection row-header: fixed at configured width, not resizable
+
+The element feeds its measured width to the controller via `setViewportWidth()`. The ResizeObserver keeps it current.
+
+### State Management
+
+`setOptions()` must NOT clobber interactive state. The controller tracks `lastOptions*` values and only applies declarative state when the consumer's value structurally changed. Interactive state that survives `setOptions`: sort, filters, expanded rows, selection, pagination, cell navigation, column widths, column order.
+
+### Framework Slot System
+
+1. Wrapper calls `setFrameworkRenderedSlots({ cells: ['colA', 'colB'] })`
+2. Render emits `<slot name="cell-colA-rowId">` placeholders
+3. `flush()` dispatches `cellSlotsChanged` with `{ added, removed }` deltas
+4. Wrapper listens, creates framework views, appends to light DOM with matching `slot` attribute
+
+## Per-Column Flags
+
+- `enableColumnResizing: false` — no resize handle rendered, column width locked
+- `enableColumnMoving: false` — not draggable, not a valid drop target
+
+## Do NOT
+
+- Skip `frameworkSlots.flush()` after rendering DOM that contains slot placeholders
+- Call `setFrameworkRenderedSlots` on every options update — only on structural column changes
+- Use `innerHTML` on `.grid-body-viewport` — it destroys scroll position; only patch inside `.body-grid`
+- Forget to sync horizontal scroll after a full render (`syncHeaderHorizontalScroll`)

package/README.md

@@ -0,0 +1,196 @@
+# @ornery/ui-grid-vanilla
+
+A vanilla Web Components wrapper for `@ornery/ui-grid-core`. Renders a high-performance data grid as a custom element with no framework dependency.
+
+## Architecture
+
+The grid is built as a composition of autonomous custom elements, each following the `@ornery/web-components` pattern:
+
+```
+<ui-grid-element>                  ← main grid element (shadow DOM)
+  ├── ui-grid-shell.html           ← declarative grid layout template
+  ├── ui-grid-empty.html           ← empty/no-options state template
+  │
+  ├── <ui-grid-header-cell>        ← column header (sort, group, pin, resize)
+  ├── <ui-grid-filter-cell>        ← column filter input (shadow DOM + .html template)
+  ├── <ui-grid-body-cell>          ← data cell (class-managed, perf-optimized)
+  ├── <ui-grid-group-row>          ← grouping disclosure row (shadow DOM + .html template)
+  ├── <ui-grid-pagination>         ← pagination controls (shadow DOM + .html template)
+  └── <ui-grid-template>           ← declarative reusable template factory
+```
+
+### Component Pattern
+
+Components follow the standard `@ornery/web-components` lifecycle:
+
+```js
+import template from './my-component.html';
+
+class MyComponent extends HTMLElement {
+  // 1. Attach shadow DOM in constructor
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  // 2. Declare instance properties as template context
+  myProp = 'default';
+
+  // 3. Render in connectedCallback
+  connectedCallback() {
+    this.myProp = this.getAttribute('data-my-prop') ?? 'default';
+    template(this).connect(); // auto-renders into shadowRoot
+  }
+}
+```
+
+The `.html` template uses ES6 template literal syntax:
+```html
+<div class="my-class">${this.myProp}</div>
+```
+
+Templates are compiled at build time by `@ornery/web-components/vite` (or `/webpack`, `/esbuild`, `/rollup`).
+
+### Performance Strategy
+
+- **Hot-path components** (`ui-grid-body-cell`, `ui-grid-header-cell`) skip `template().connect()` entirely — the parent pre-renders innerHTML as a string, and the component only manages CSS classes via `attributeChangedCallback`. This avoids DOM construction overhead per cell.
+- **Low-frequency components** (`ui-grid-filter-cell`, `ui-grid-group-row`, `ui-grid-pagination`) use full `template(this).connect()` with shadow DOM for encapsulation and declarative rendering.
+
+### Template Bindings
+
+Cell and row slot templates support dual binding syntax:
+
+| Syntax | Example | Description |
+|--------|---------|-------------|
+| `{{ }}` | `{{value}}` | Mustache-style, original grid syntax |
+| `${ }` | `${this.value}` | ES6 template literal, `@ornery/web-components` native |
+
+Both resolve against the same context: `{ $implicit, value, valueText, row, column, rowIndex }`.
+
+## Installation
+
+```bash
+npm install @ornery/ui-grid-vanilla @ornery/ui-grid-core
+```
+
+## Usage
+
+### Imperative (JavaScript)
+
+```js
+import { mountVanillaUiGrid } from '@ornery/ui-grid-vanilla';
+
+const grid = await mountVanillaUiGrid(document.getElementById('grid'), {
+  id: 'my-grid',
+  columnDefs: [
+    { name: 'name', field: 'name', displayName: 'Name' },
+    { name: 'age', field: 'age', displayName: 'Age', align: 'end' },
+  ],
+  data: [
+    { name: 'Alice', age: 30 },
+    { name: 'Bob', age: 25 },
+  ],
+  enableSorting: true,
+  enableFiltering: true,
+});
+```
+
+### Declarative (HTML attributes)
+
+```html
+<ui-grid-element
+  grid-id="my-grid"
+  enable-sorting
+  enable-filtering
+  column-defs='[{"name":"name","field":"name"},{"name":"age","field":"age","align":"end"}]'
+  data='[{"name":"Alice","age":30},{"name":"Bob","age":25}]'>
+</ui-grid-element>
+```
+
+### Custom Cell Templates (slots)
+
+```html
+<ui-grid-element id="grid">
+  <!-- Mustache syntax -->
+  <template slot="cell-name">
+    <strong>{{value}}</strong>
+  </template>
+
+  <!-- ES6 syntax -->
+  <template slot="cell-age">
+    <span style="color: ${this.value > 30 ? 'red' : 'green'}">${this.value}</span>
+  </template>
+</ui-grid-element>
+```
+
+### Declarative Reusable Templates
+
+Define reusable components from HTML alone with `<template is="ui-grid-template">`:
+
+```html
+<!-- Define a badge component -->
+<template is="ui-grid-template" name="ui-status-badge" status="unknown">
+  <style>
+    :host { display: inline-block; }
+    .badge { padding: 2px 8px; border-radius: 4px; }
+    .badge-active { background: #d1fae5; color: #065f46; }
+    .badge-inactive { background: #fee2e2; color: #991b1b; }
+  </style>
+  <span class="badge badge-${this.status}">${this.status}</span>
+</template>
+
+<!-- Use it in a grid cell slot -->
+<ui-grid-element>
+  <template slot="cell-status">
+    <ui-status-badge status="{{value}}"></ui-status-badge>
+  </template>
+</ui-grid-element>
+```
+
+## Bundler Setup
+
+### Vite
+
+```js
+import { defineConfig } from 'vite';
+import webComponents from '@ornery/web-components/vite';
+
+export default defineConfig({
+  plugins: [webComponents()]
+});
+```
+
+### Webpack 5
+
+```js
+import webComponents from '@ornery/web-components/webpack';
+
+export default {
+  plugins: [webComponents()]
+};
+```
+
+### tsup (esbuild)
+
+```ts
+import { defineConfig } from 'tsup';
+import webComponents from '@ornery/web-components/esbuild';
+
+export default defineConfig({
+  esbuildPlugins: [webComponents()],
+});
+```
+
+## API
+
+### `mountVanillaUiGrid(target, options, rustModule?, tagName?)`
+Mount a grid into a target element. Returns the grid element.
+
+### `defineStandaloneUiGridElement(tagName?)`
+Register the `<ui-grid-element>` custom element (and all sub-components).
+
+### `UIGridTemplate`
+Exported class for the `<template is="ui-grid-template">` element. Auto-registered when the grid is defined.
+
+### Grid Element Properties
+See `VanillaUiGridElement` type — all `GridOptions` fields are available as both HTML attributes and JS properties.

package/demo/main.ts

@@ -24,7 +24,6 @@ const options: GridOptions = {
   title: 'UI Grid Vanilla Demo',
   emptyMessage: 'No rows match the current filters.',
   rowHeight: 48,
-  viewportHeight: 620,
   enableSorting: true,
   enableFiltering: true,
   enableGrouping: true,