apex-grid 3.1.0 → 3.3.0

package/docs/media/_tokens.scss

@@ -1,16 +1,13 @@
 // ─────────────────────────────────────────────────────────────────────────
 // Premium default design tokens (`--ag-*`).
-//
 // These land on the `<apex-grid>` host (this file is `@use`d by
 // `grid/_grid.base.scss`, which ships inside every theme). CSS custom
 // properties inherit across shadow boundaries, so every child component
 // (`apex-grid-row`, `apex-grid-cell`, `apex-grid-header`, …) can read them.
-//
 // This is the single rebrand surface: override ~12 values on `apex-grid` and
 // the whole grid re-skins. Values fall back to self-contained literals, so a
 // grid mounted with zero consumer CSS already looks premium; the brand tokens
 // additionally re-tint from the igniteui palette when it is present.
-//
 // No `!important`, no downstream hardcoded numerics — every rule resolves here.
 // ─────────────────────────────────────────────────────────────────────────
 
@@ -20,87 +17,177 @@
     // auto-matches an igniteui host app), and falls back to the self-contained
     // premium blue otherwise. This igniteui hook used to live in the per-theme
     // files; folding it here keeps that integration without named themes.
-    --ag-brand: var(--ig-primary-500, #0d6fd3); // primary blue
-    --ag-brand-strong: var(--ig-primary-700, #0a56b8); // hover / pressed
+    --ag-brand: var(--ig-primary-500, #0d6fd3); /* primary blue */
+    --ag-brand-strong: var(--ig-primary-700, #0a56b8); /* hover / pressed */
 
     // Brand-derived washes are mixed from `--ag-brand` so a one-line rebrand
     // cascades to every tint. With the default brand these resolve to the
     // spec's exact rgba(13, 111, 211, …) values.
-    --ag-brand-soft: color-mix(in srgb, var(--ag-brand) 10%, transparent); // selected row / chip wash
-    --ag-brand-softer: color-mix(in srgb, var(--ag-brand) 7%, transparent); // chip / control wash
-    --ag-brand-line: color-mix(in srgb, var(--ag-brand) 18%, transparent); // chip / search borders
+    --ag-brand-soft: color-mix(in srgb, var(--ag-brand) 10%, transparent); /* selected row / chip wash */
+    --ag-brand-softer: color-mix(in srgb, var(--ag-brand) 7%, transparent); /* chip / control wash */
+    --ag-brand-line: color-mix(in srgb, var(--ag-brand) 18%, transparent); /* chip / search borders */
 
     // ── Neutral chrome ───────────────────────────────────────────────────
     // The grid's chrome (surfaces, gridlines, row hover) is grayscale so the
     // grid reads as a calm, neutral table; `--ag-brand` is reserved for genuine
     // state (selection, focus, checkboxes, active sort) and accents (chips).
-    --ag-hairline: rgba(15, 23, 42, 0.08); // header / structural gridlines
-    --ag-row-hover: color-mix(in srgb, #0f172a 5%, var(--ag-surface)); // neutral hover wash (opaque)
+    --ag-hairline: rgb(15 23 42 / 8%); /* header / structural gridlines */
+    --ag-border: rgb(15 23 42 / 8%); /* row separators — same weight as hairline */
+    --ag-pin-line: rgb(15 23 42 / 18%); /* 1px vertical line at pinned-column edge */
+    --ag-header-separator: rgb(15 23 42 / 12%); /* opt-in per-column header divider (columnSeparator) */
+    --ag-row-hover: color-mix(in srgb, #0f172a 5%, var(--ag-surface)); /* neutral hover wash (opaque) */
 
     // ── Surfaces ─────────────────────────────────────────────────────────
     // These back sticky/pinned regions (header, footer, frozen columns) which
     // paint `background: inherit` to mask content scrolling underneath, so they
     // MUST be opaque — a translucent surface lets the scrolled content bleed
     // through.
-    --ag-surface: #fff; // grid card background
-    --ag-surface-alt: #f9fafb; // alternating row tint (neutral, opaque)
-    --ag-surface-elevated: linear-gradient(180deg, #fbfcfd 0%, #f6f7f8 100%); // header bg (neutral, opaque)
+    // Host card background. Kept as its own token (rather than reusing
+    // `--ag-surface`) so the default can carry the subtle premium light
+    // gradient while sticky surfaces stay flat/opaque. Dark themes override it
+    // with a flat color. The host paints THIS, so dark mode is impossible
+    // without it being a token.
+    --ag-grid-bg: #fff; /* flat white — gradients are dated in modern data grids */
+    --ag-surface: #fff; /* grid card background */
+    --ag-surface-alt: var(--ag-surface); /* no zebra stripes — rely on hover + hairline borders */
+    --ag-surface-elevated: #f8f9fb; /* flat header/toolbar/footer surface */
 
     // ── Text ─────────────────────────────────────────────────────────────
-    --ag-text: #111827; // primary
-    --ag-text-body: #1f2937; // row text
-    --ag-text-muted: #6b7280; // roles, labels
-    --ag-text-subtle: #9ca3af; // placeholder, ellipsis
+    --ag-text: #111827; /* primary */
+    --ag-text-body: #1f2937; /* row text */
+    --ag-text-muted: #6b7280; /* roles, labels */
+    --ag-text-subtle: #9ca3af; /* placeholder, ellipsis */
     --ag-text-on-brand: #fff;
 
-    --ag-border: rgba(15, 23, 42, 0.05); // row separators
-
     // ── State ────────────────────────────────────────────────────────────
-    --ag-good: #10b981; // health > 80, Active
+    --ag-good: #10b981; /* health > 80, Active */
     --ag-good-text: #047857;
-    --ag-good-soft: rgba(16, 185, 129, 0.1);
-    --ag-watch: #f59e0b; // health 65–80, Trial
+    --ag-good-soft: rgb(16 185 129 / 10%);
+    --ag-watch: #f59e0b; /* health 65–80, Trial */
     --ag-watch-text: #b45309;
-    --ag-watch-soft: rgba(245, 158, 11, 0.1);
-    --ag-risk: #ef4444; // health < 65, Churn
+    --ag-watch-soft: rgb(245 158 11 / 10%);
+    --ag-risk: #ef4444; /* health < 65, Churn */
     --ag-risk-text: #b91c1c;
-    --ag-risk-soft: rgba(239, 68, 68, 0.1);
-
-    --ag-gold: #fef3c7; // Enterprise pill bg
+    --ag-risk-soft: rgb(239 68 68 / 10%);
+    --ag-gold: #fef3c7; /* Enterprise pill bg */
     --ag-gold-line: #fde68a;
     --ag-gold-text: #92400e;
-
     --ag-shadow-card:
-        0 16px 38px rgba(15, 23, 42, 0.12),
-        0 0 0 1px rgba(15, 23, 42, 0.06),
-        0 1px 0 rgba(255, 255, 255, 0.9) inset; // soft neutral floating shadow
+        0 16px 38px rgb(15 23 42 / 12%),
+        0 0 0 1px rgb(15 23 42 / 6%),
+        0 1px 0 rgb(255 255 255 / 90%) inset; /* soft neutral floating shadow */
 
     // ── Typography ───────────────────────────────────────────────────────
     --ag-font: 'Inter', -apple-system, blinkmacsystemfont, sans-serif;
-    --ag-fs-cell: 12px;
-    --ag-fs-cell-secondary: 10.5px; // role line, header labels
-    --ag-fs-tiny: 10px; // tags, page ellipsis
+    --ag-fs-cell: 13px;
+    --ag-fs-cell-secondary: 11.5px; /* role line, header labels */
+    --ag-fs-tiny: 10px; /* tags, page ellipsis */
     --ag-fw-regular: 500;
     --ag-fw-semibold: 600;
     --ag-fw-bold: 700;
     --ag-tracking-tight: -0.005em;
-    --ag-tracking-header: 0.05em; // uppercase header labels
+    --ag-tracking-header: 0.05em; /* uppercase header labels */
     --ag-leading: 1.4;
 
     // ── Spacing & sizing ─────────────────────────────────────────────────
     --ag-cell-pad-x: 10px;
-    --ag-row-h: 36px; // dense but readable
-    --ag-header-h: 36px;
+    --ag-row-h: 36px; /* dense but readable */
+    --ag-header-h: 40px; /* taller than rows to accommodate 3-icon header */
     --ag-toolbar-pad: 12px 14px;
     --ag-footer-pad: 10px 14px;
-    --ag-radius: 18px; // outer card
-    --ag-radius-sm: 6px; // chips, page buttons
-    --ag-radius-xs: 4px; // checkboxes, expand button
-    --ag-radius-pill: 20px; // status badges
+    --ag-radius: 8px; /* outer card — tighter matches modern table libraries */
+    --ag-radius-sm: 6px; /* chips, page buttons */
+    --ag-radius-xs: 4px; /* checkboxes, expand button */
+    --ag-radius-pill: 20px; /* status badges */
 
     // ── Motion ───────────────────────────────────────────────────────────
     --ag-ease: cubic-bezier(0.2, 0.8, 0.2, 1);
-    --ag-dur-fast: 120ms; // hover, focus
-    --ag-dur-med: 180ms; // chevron rotate
-    --ag-dur-slow: 240ms; // health bar fill
+    --ag-dur-fast: 120ms; /* hover, focus */
+    --ag-dur-med: 180ms; /* chevron rotate */
+    --ag-dur-slow: 240ms; /* health bar fill */
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Built-in dark theme. Opt in with `<apex-grid theme="dark">`.
+// Only color/surface tokens are flipped to a neutral slate palette; geometry,
+// typography, motion, and the brand hue (which still auto-tints from the
+// igniteui palette when present) are inherited from the light block above.
+// `theme~='dark'` matches a space-separated word so `theme="dark compact"`
+// style stacking keeps working. These tokens inherit across the shadow
+// boundary to every child component, so the whole grid re-skins from here.
+// ─────────────────────────────────────────────────────────────────────────
+:host([theme~='dark']) {
+    // ── Brand ── brighter fallbacks so the accent reads on a dark surface;
+    // still re-tints from the igniteui palette first when it is present.
+    --ag-brand: var(--ig-primary-500, #3b82f6);
+    --ag-brand-strong: var(--ig-primary-400, #60a5fa);
+
+    // ── Surfaces ── flat, opaque slate (sticky regions paint these).
+    --ag-grid-bg: #0f172a; /* host card (flat in dark) */
+    --ag-surface: #0f172a; /* grid body / row bg */
+    --ag-surface-alt: var(--ag-surface); /* no stripes in dark mode either */
+    --ag-surface-elevated: #1e2532; /* header / footer / toolbar — slightly lifted */
+
+    // ── Chrome ── light-on-dark gridlines + a hover wash that mixes toward
+    // white (the light default mixes toward #0f172a, which is invisible here).
+    --ag-hairline: rgb(255 255 255 / 12%); /* structural gridlines */
+    --ag-border: rgb(255 255 255 / 12%); /* row separators — same weight as hairline */
+    --ag-pin-line: rgb(255 255 255 / 28%); /* 1px vertical line at pinned-column edge */
+    --ag-header-separator: rgb(255 255 255 / 18%); /* opt-in per-column header divider (columnSeparator) */
+    --ag-row-hover: color-mix(in srgb, #fff 7%, var(--ag-surface));
+
+    // ── Text ──
+    --ag-text: #f1f5f9; /* primary */
+    --ag-text-body: #e2e8f0; /* row text */
+    --ag-text-muted: #94a3b8; /* roles, labels */
+    --ag-text-subtle: #64748b; /* placeholder, ellipsis */
+
+    // ── State ── brighter text + slightly stronger washes for legibility on
+    // the dark surface.
+    --ag-good-text: #34d399;
+    --ag-good-soft: rgb(16 185 129 / 18%);
+    --ag-watch-text: #fbbf24;
+    --ag-watch-soft: rgb(245 158 11 / 18%);
+    --ag-risk-text: #f87171;
+    --ag-risk-soft: rgb(239 68 68 / 18%);
+    --ag-gold: rgb(245 158 11 / 16%); /* Enterprise pill bg (dark amber wash) */
+    --ag-gold-line: rgb(245 158 11 / 35%);
+    --ag-gold-text: #fcd34d;
+
+    // Drop the light-mode white inset highlight; deepen the drop shadow.
+    --ag-shadow-card:
+        0 16px 38px rgb(0 0 0 / 55%),
+        0 0 0 1px rgb(255 255 255 / 6%),
+        0 1px 0 rgb(255 255 255 / 4%) inset;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Optional brand-tinted chrome. Opt in with `theme="tinted"` (composes with
+// dark as `theme="dark tinted"`).
+// By default the chrome is neutral grayscale and `--ag-brand` only shows on
+// interactive state (selection, focus, active sort). This variant mixes a
+// little brand into the surfaces/gridlines so the grid wears its brand even
+// at rest, a brand-tinted variant. Because every value is `color-mix(... var
+// (--ag-brand) ...)`, it follows whatever brand is in effect (including the
+// igniteui auto-tint) with no per-brand CSS.
+// The light variant mixes into the white neutrals; the dark variant (higher
+// specificity, so it wins under `theme="dark tinted"`) mixes the SAME token
+// set into the slate neutrals. Body row surface stays untinted for legibility.
+// ─────────────────────────────────────────────────────────────────────────
+:host([theme~='tinted']) {
+    --ag-surface-alt: color-mix(in srgb, var(--ag-brand) 4%, #fff); /* zebra */
+    --ag-surface-elevated: color-mix(in srgb, var(--ag-brand) 11%, #fbfcfd); /* header / footer / toolbar */
+    --ag-hairline: color-mix(in srgb, var(--ag-brand) 24%, rgb(15 23 42 / 7%)); /* gridlines */
+    --ag-border: color-mix(in srgb, var(--ag-brand) 12%, transparent); /* row separators */
+    --ag-row-hover: color-mix(in srgb, var(--ag-brand) 9%, var(--ag-surface));
+    --ag-text-muted: color-mix(in srgb, var(--ag-brand) 32%, #6b7280); /* header labels pick up the brand */
+}
+
+:host([theme~='dark'][theme~='tinted']) {
+    --ag-surface-alt: color-mix(in srgb, var(--ag-brand) 10%, #172033);
+    --ag-surface-elevated: color-mix(in srgb, var(--ag-brand) 20%, #1e293b);
+    --ag-hairline: color-mix(in srgb, var(--ag-brand) 30%, rgb(255 255 255 / 12%));
+    --ag-border: color-mix(in srgb, var(--ag-brand) 16%, rgb(255 255 255 / 7%));
+    --ag-row-hover: color-mix(in srgb, var(--ag-brand) 12%, var(--ag-surface));
+    --ag-text-muted: color-mix(in srgb, var(--ag-brand) 28%, #94a3b8);
 }

package/docs/media/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-grid",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Web component data grid following open-wc recommendations",
   "keywords": [
     "lit",

package/docs/media/state-persistence.html

@@ -0,0 +1,189 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>State Persistence (getState / setState) - ApexGrid</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet" />
+    <script src="../apex-grid.min.js"></script>
+    <style>
+      body {
+        max-width: 1000px;
+        margin: 0 auto;
+        font-family: 'Inter', sans-serif;
+        background: #fff;
+        padding: 20px;
+      }
+      h2 {
+        font-size: 22px;
+        font-weight: 700;
+        color: #1a1a2e;
+        margin: 0 0 4px 0;
+        line-height: 1.3;
+      }
+      .subtitle {
+        font-size: 13px;
+        color: #888;
+        margin-bottom: 16px;
+      }
+      .toolbar {
+        display: flex;
+        gap: 8px;
+        margin-bottom: 12px;
+        flex-wrap: wrap;
+      }
+      .toolbar button {
+        padding: 6px 12px;
+        font: inherit;
+        font-size: 13px;
+        border: 1px solid #d0d5dd;
+        background: #fff;
+        border-radius: 4px;
+        cursor: pointer;
+      }
+      .toolbar button:hover {
+        background: #f7f9fc;
+      }
+      .layout {
+        display: grid;
+        grid-template-columns: 1fr 320px;
+        gap: 16px;
+        align-items: start;
+      }
+      apex-grid {
+        min-height: 420px;
+        --ig-size: 2;
+      }
+      .snapshot {
+        margin: 0;
+        padding: 10px 12px;
+        background: #0f172a;
+        color: #cbd5e1;
+        border-radius: 6px;
+        font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+        font-size: 11px;
+        line-height: 1.5;
+        max-height: 460px;
+        overflow: auto;
+        white-space: pre-wrap;
+        word-break: break-word;
+      }
+      .panel-title {
+        font-size: 12px;
+        font-weight: 600;
+        color: #475569;
+        margin: 0 0 6px 0;
+        text-transform: uppercase;
+        letter-spacing: 0.04em;
+      }
+    </style>
+    <script type="module">
+      try {
+        const resp = await fetch('https://cdn.jsdelivr.net/npm/igniteui-webcomponents@5/themes/light/bootstrap.css');
+        const css = await resp.text();
+        const style = document.createElement('style');
+        style.textContent = css.replaceAll(':root', 'apex-grid');
+        document.head.appendChild(style);
+      } catch (e) { /* theme is cosmetic */ }
+    </script>
+  </head>
+  <body>
+    <h2>State Persistence — getState / setState</h2>
+    <p class="subtitle">
+      The grid serializes its restorable view (column layout, sort, filter, pagination, selection, pinned rows, manual order) with <code>getState()</code> and restores it with <code>setState()</code>. The <code>stateChanged</code> event fires after every settled change, so saving to <code>localStorage</code> is a one-liner. Reorder/sort/filter/select, then reload the page — your view is restored.
+    </p>
+    <div class="toolbar">
+      <button id="save">Save view</button>
+      <button id="restore">Restore saved</button>
+      <button id="reset">Reset to default</button>
+    </div>
+    <div class="layout">
+      <apex-grid id="grid"></apex-grid>
+      <div>
+        <p class="panel-title">Live snapshot (getState)</p>
+        <pre class="snapshot" id="snapshot"></pre>
+      </div>
+    </div>
+    <script type="module">
+      const KEY = 'apex-grid:saved-view';
+      const data = [
+        { id: '1',  name: 'Wireless Headphones',    category: 'Audio',        price: 299.00, stock: 14 },
+        { id: '2',  name: 'USB-C Hub',              category: 'Connectivity', price: 49.99,  stock: 28 },
+        { id: '3',  name: 'Mechanical Keyboard',    category: 'Input',        price: 189.00, stock: 5  },
+        { id: '4',  name: 'Ergonomic Mouse',        category: 'Input',        price: 79.95,  stock: 22 },
+        { id: '5',  name: 'Monitor Stand',          category: 'Furniture',    price: 59.99,  stock: 17 },
+        { id: '6',  name: '4K Webcam',              category: 'Video',        price: 149.00, stock: 9  },
+        { id: '7',  name: 'Laptop Sleeve',          category: 'Accessories',  price: 34.99,  stock: 31 },
+        { id: '8',  name: 'Desk Lamp',              category: 'Furniture',    price: 44.50,  stock: 12 },
+        { id: '9',  name: 'True Wireless Earbuds',  category: 'Audio',        price: 249.00, stock: 20 },
+        { id: '10', name: 'Portable Charger',       category: 'Connectivity', price: 39.99,  stock: 45 },
+        { id: '11', name: 'Ultrawide Monitor',      category: 'Video',        price: 649.00, stock: 6  },
+        { id: '12', name: 'Noise-Cancelling Headset', category: 'Audio',      price: 219.00, stock: 11 },
+        { id: '13', name: 'Wireless Charging Pad',  category: 'Connectivity', price: 29.99,  stock: 38 },
+        { id: '14', name: 'LED Desk Light',         category: 'Furniture',    price: 54.99,  stock: 24 },
+        { id: '15', name: 'Laptop Stand',           category: 'Accessories',  price: 49.99,  stock: 18 },
+        { id: '16', name: 'Compact Keyboard',       category: 'Input',        price: 99.00,  stock: 13 },
+        { id: '17', name: 'USB-C Docking Station',  category: 'Connectivity', price: 199.00, stock: 8  },
+        { id: '18', name: 'Trackball Mouse',        category: 'Input',        price: 119.99, stock: 16 },
+        { id: '19', name: 'Monitor Light Bar',      category: 'Furniture',    price: 79.00,  stock: 21 },
+        { id: '20', name: 'Phone Mount for Desk',   category: 'Accessories',  price: 24.99,  stock: 50 },
+      ];
+
+      // A sensible starting view, applied on first load (empty storage). Pins a
+      // row to the top and sorts by price so the snapshot panel is illustrative.
+      const DEFAULT_VIEW = {
+        sort: [{ key: 'price', direction: 'descending' }],
+        rowPinning: { top: [{ index: 0 }], bottom: [] },
+        selection: [{ index: 2 }],
+      };
+
+      const grid = document.getElementById('grid');
+      grid.columns = [
+        { key: 'id',       headerText: 'ID' },
+        { key: 'name',     headerText: 'Name',     sort: true, filter: true },
+        { key: 'category', headerText: 'Category', sort: true, filter: true },
+        { key: 'price',    headerText: 'Price',    sort: true, type: 'number' },
+        { key: 'stock',    headerText: 'Stock',    sort: true, type: 'number' },
+      ];
+      grid.data = data;
+      grid.selection = { enabled: true, mode: 'multiple' };
+      grid.rowPinning = { enabled: true };
+      grid.rowReordering = { enabled: true };
+
+      const snapshotEl = document.getElementById('snapshot');
+      const render = () => {
+        snapshotEl.textContent = JSON.stringify(grid.getState(), null, 2);
+      };
+
+      document.getElementById('save').addEventListener('click', () => {
+        localStorage.setItem(KEY, JSON.stringify(grid.getState()));
+      });
+      document.getElementById('restore').addEventListener('click', () => {
+        const saved = localStorage.getItem(KEY);
+        if (saved) grid.setState(JSON.parse(saved));
+      });
+      document.getElementById('reset').addEventListener('click', () => {
+        localStorage.removeItem(KEY);
+        grid.setState(DEFAULT_VIEW);
+      });
+
+      await customElements.whenDefined('apex-grid');
+      // Apply the saved (or default) view after the grid's first render settles,
+      // so it isn't clobbered by the initial data/columns pipeline.
+      await grid.updateComplete;
+      const saved = localStorage.getItem(KEY);
+      grid.setState(saved ? JSON.parse(saved) : DEFAULT_VIEW);
+      await grid.updateComplete;
+      render();
+
+      // Persistence in one line: save the snapshot whenever state settles. Wired
+      // after the initial view is in place so it captures real user changes.
+      grid.addEventListener('stateChanged', (e) => {
+        localStorage.setItem(KEY, JSON.stringify(e.detail.state));
+        render();
+      });
+    </script>
+  </body>
+</html>