apex-grid 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -4,6 +4,344 @@ All notable changes to the `apex-grid` (community) package are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 and the format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [3.6.0] - 2026-10-21
+
+A quality release built from a full code-quality audit, plus `--ag-*` tokens
+that reach the grid from any ancestor (shadow roots included). No exported
+symbol was removed or renamed. A few documented contracts now hold where they
+did not: `sorted`, `filtered`, `pageChanged` and `quickFilterChanged` fire after
+the pipeline run they caused, and a row move on a sorted grid clears the sort.
+See Changed for what apps may notice.
+
+### Added
+- **`--ag-*` tokens set on any ancestor now reach the grid**, including the
+  shadow host of a web component the grid renders in, however deep. Set a
+  theme once on your own host element and every grid inside follows it. See
+  "Changed" for how the defaults moved to make this work.
+- **Dark-mode inputs `--ag-dark-*`** (`--ag-dark-surface`, `--ag-dark-text`,
+  `--ag-dark-hairline`, `--ag-dark-shadow-card`, …) for every colour
+  `theme="dark"` changes. Dark grids read these instead of the light inputs,
+  so a light palette set on a shared ancestor never puts a white surface under
+  the dark theme's light text. Sizing, typography, motion, the brand and the
+  base state colours stay shared by both modes.
+- **`apex-grid/tokens.css`**: the token defaults as a plain stylesheet, for
+  server rendering or for apps that opt out of the adopted sheet.
+- **`setup({ tokenStyles: false })`** skips adopting the token defaults into
+  the document.
+- **`applyEdits()` entries can name their row by record**: `{ row, column,
+  value }` alongside the positional `{ rowIndex, column, value }`. A record
+  reaches rows on other pages, pinned rows and rows under a collapsed tree
+  parent, so `grid.selectedRows.map((row) => ({ row, column, value }))` now
+  edits the whole selection; with `rowIndex` such rows were skipped. Events
+  and validators for those rows see `rowIndex` -1.
+- **`ApexGrid.ownsEvent(event)`** tells whether an event came from this grid
+  or from a grid nested in one of its master-detail panels. The grid uses it
+  so cells of a nested grid no longer drive the outer one (clicks, Space
+  selection, Ctrl+Z, pointer drags).
+- `CSVExportOptions.escapeFormulas` (default `true`), see the change below.
+- Locale keys `toolPanel.valueColumn` and `toolPanel.columnLabelColumn` for the
+  enterprise tool panel, in English and Spanish.
+- Locale key `chart.mapCategoryNone` (English "None", Spanish "Ninguna") for
+  the enterprise chart panel's Category select.
+- Locale key `setFilter.more` for the enterprise set filter's list cap, in
+  English and Spanish.
+- `expansion.exportParts` lists parts inside your `detailTemplate` content
+  for the row to re-export, so `apex-grid::part(name)` can style them.
+- Locale key `pivot.columnsTruncated` for the enterprise pivot column cap, in
+  English and Spanish.
+- `rowMoving` and `rowMoved` carry `position` (`'before'` or `'after'`) and
+  `toIndex`, the view index the row lands at, next to `from`, `to` and
+  `data`.
+
+### Changed
+- **Token defaults moved from the grid host to the document root.** The grid
+  used to declare every `--ag-*` default on its own host, and a declaration on
+  an element always beats an inherited value, so tokens set on an ancestor
+  never reached it (only `--ig-primary-500` did, through the brand fallback).
+  The defaults now sit on `:where(:root)`, adopted into the document through
+  `adoptedStyleSheets` when the first grid connects (no `<style>` element, so
+  no CSP nonce), and the grid resolves them into private copies on its host.
+  Reading tokens keeps working: `var(--ag-surface)` resolves to the default
+  anywhere on the page, and `apex-grid { --ag-grid-shadow:
+  var(--ag-shadow-card); }` still gives the card shadow. Changes to look for:
+  - `var(--ag-brand)` and `var(--ag-brand-strong)` have no root default, so an
+    Ignite UI palette set on any ancestor keeps tinting the grid. Page CSS
+    reading them needs its own fallback.
+  - Derived tokens (`--ag-brand-soft`, `--ag-brand-softer`, `--ag-brand-line`,
+    `--ag-row-hover`, `--ag-surface-alt`) are mixed on the grid host so they
+    follow a brand set lower down. They still accept an override but have no
+    root default to read.
+  - A value set on an element above a dark grid (`--ag-surface`, …) no longer
+    applies to it; set `--ag-dark-surface` and the other `--ag-dark-*` inputs.
+    A value set on the dark grid element itself is now ignored the same way.
+    On a dark grid, use `--ag-grid-shadow: var(--ag-dark-shadow-card)` for the
+    card shadow recipe.
+  - `theme="tinted"` mixes the brand into the surface, gridline and
+    muted-text values in effect (yours, if you set them) instead of replacing
+    them. Its row separators stay the brand alone, so a tinted grid ignores
+    `--ag-border` and `--ag-dark-border`, including on the grid element itself.
+    The default tinted look is unchanged.
+- **CSV export neutralises spreadsheet formulas.** A text cell or header that
+  starts with `=`, `+`, `-`, `@`, a tab or a carriage return is written with a
+  leading apostrophe, so a spreadsheet opening the file shows it as text
+  instead of running it. Numbers are untouched, and so is text that is a plain
+  signed decimal such as `-5` or `+1.5`. Other text with a leading sign gains
+  the apostrophe too: a lone `-`, a phone number such as `+44 20 7946 0958`,
+  `-1,234.50`, or formatter output such as `-$5.00`. Pass
+  `exportToCSV({ escapeFormulas: false })` for the old output.
+- **An open editor stays on the record it was opened for** when the data,
+  sort, filter or page changes while editing; before, it could jump to another
+  row and Enter wrote into the wrong record. The edit is cancelled when its
+  record leaves the view (removed, filtered out or replaced by a copy).
+  `editingCell`, `editingRow` and the `rowIndex` of the edit events are -1 when
+  the edited record is in a pinned row or on another page.
+- **Row mode edits the staged row.** Cells of the row in edit show their staged
+  values, validators receive the staged row as `ctx.data` (a copy of the
+  record with the staged values applied), and a row commit re-validates the
+  row's other editable cells. A checkbox click, or any `cellTemplate` calling
+  `ctx.commit`, joins the row edit instead of writing straight to the record,
+  so `cancelEdit()` rolls it back.
+- **After tabbing into the grid body, the first arrow, Home or Page Up key
+  activates the first cell** instead of moving past it (ArrowDown lands on
+  row 0). Page Up and Page Down move by the rows that fit in the body instead
+  of a fixed 10.
+- **Tree data under a filter shows the ancestors of a match as their own
+  rows** (selectable and exportable, not matching the filter themselves)
+  instead of blank placeholders, and matches under a non-matching parent are
+  no longer hidden.
+- **Replacing `grid.data` prunes tree and detail expansion** of rows that left
+  the data, so `getState()` no longer lists rows that are gone.
+- **Exports write booleans as the checkbox shows them**: true only for
+  `true`, so strings such as `'false'` or `'yes'` and the number 1 export as
+  false. **Currency and progress columns export as numbers**, like number and
+  rating columns; text that is not a number exports as an empty cell.
+- **Replacing `grid.data` with new records clears the undo history** (and
+  fires `historyChanged`). Undo used to replay onto the old, detached records:
+  nothing changed on screen, yet `cellValueChanged` fired for a row the grid no
+  longer held. New data that keeps the edited records, such as an appended
+  row, keeps its history, and so do in-place edits. A subclass that keeps
+  records outside `data` (a row model that drops collapsed rows and restores
+  the same objects) overrides the protected `historyRecords()` to keep their
+  history too.
+- **`cellValueChanged` from undo or redo reports `rowIndex` -1 when the
+  record is pinned or on another page**, instead of the index it had when
+  edited (which could name a different row). Listeners that read `rowIndex`
+  from a replayed change should identify the row by the event's `data`.
+- `applyEdits()` skips an entry whose `rowIndex` is negative or fractional,
+  as it already skipped one past the end of the page. 3.5.0 counted a negative
+  index from the end of the page and rounded a fraction down.
+- **`sortExpressions` and `filterExpressions` replace the current sort or filter
+  instead of merging into it**, as documented and as `setState` already did;
+  `[]`, `null` or `undefined` clears it. Apps that assigned one expression at a
+  time to build up a multi-column sort or filter should assign the full list (or
+  call `sort()` / `filter()`, which still add). The assigned list applies at the
+  next update, against the columns as they are then, so a template may bind it
+  before `columns`; reading it back before that returns what was assigned. Sort
+  entries for an unknown column or with an unknown direction are dropped with a
+  console warning (an omitted direction still sorts ascending).
+- **`currency`, `rating` and `progress` columns filter as numbers**, as their
+  type docs already said. The filter panel offers the number conditions (Equals,
+  Greater than, Less than and so on) and reads the typed value as a number, and
+  `getSchema()` lists the number operands for these columns. A saved state or
+  `filter()` call that names a text condition such as `contains` on one of them
+  is now dropped with a console warning; in 3.5.0 those conditions threw inside
+  the pipeline and filtered nothing. Feature modules read the rule through
+  `StateController.isNumericColumn(column)`.
+- Feature modules can reveal a cell, read the inline direction of an arrow key
+  under RTL and read the scroll insets through the grid's navigation
+  controller (`revealCell`, `towardsInlineEnd`, `scrollInsets`), so the
+  enterprise range selection follows core navigation instead of a copy.
+- **Cell templates run again after each data pipeline run.** A column
+  `cellTemplate` is called for every visible row, body and pinned, after each
+  pipeline run (sort, filter, quick filter, edit, tree toggle), so a template
+  that reads other fields of its row stays current. Keep templates light;
+  plain and typed cells are not re-rendered by this.
+- Start-pinned columns freeze after the leading checkbox, expansion, reorder
+  grip and row-number columns instead of at the grid edge. The grid sets
+  `--apex-chrome-offset-row-number`, `--apex-chrome-offset-reorder`,
+  `--apex-chrome-offset-selection` and `--apex-chrome-offset-expansion` on the
+  host and no longer writes `--scrollbar-offset` inline (the stylesheet
+  default stays).
+- A decoration-only change (range selection, formula reference highlight)
+  updates cell attributes without re-rendering cell content. For feature
+  modules, `bumpDecoration` now only re-applies `CellDecorator` attributes;
+  request a pipeline run when content must change.
+- Feature modules can attach a command to a cell edit and its undo step, and
+  read the header's sortable rule through `SortController.isSortable`.
+- Pressing on interactive content in a `headerTemplate` (an input, select,
+  textarea, button, link or editable element) no longer starts a column drag.
+- When a `columnMoving` listener cancels a live swap, the event is raised once
+  per target crossing instead of on every pointer move.
+- The filter panel's `filtering` event carries a proposed copy of the
+  expression for panel edits, and the change is applied only after the event
+  is not cancelled. Escape pressed outside the panel is no longer swallowed.
+- Switching an applied Empty or Not empty filter to a condition that needs a
+  value removes the filter (with a cancellable remove) until a value is typed.
+- `getState()` and `setState()` copy array filter terms, and feature modules
+  can register a filter operand by name (`registerFilterOperand` on
+  `apex-grid/internal`) so a saved filter that uses it restores.
+- **`sorted`, `filtered`, `pageChanged` and `quickFilterChanged` fire after
+  the pipeline run they caused.** With an asynchronous
+  `dataPipelineConfiguration` hook, listeners now read the new rows and
+  totals. With synchronous hooks they still fire in the same task, after the
+  re-render of the new rows. The server-side and infinite row models fetch
+  outside the pipeline, so with them these events can still fire before the
+  new block arrives.
+- `setQuickFilter` (and the toolbar search box) fires `pageChanged` and
+  announces the page when it moves the grid back to the first page. Setting
+  the `quickFilter` property or calling `setState` stays silent.
+- Every part a row renders can be styled with `apex-grid::part()`:
+  selection, expansion, detail panel, row number and reorder parts, and the
+  parts of rows a module renders. Before, only `cell` was reachable, so
+  existing `::part()` rules for these names now take effect.
+- **Moving a row on a sorted grid clears the sort** and keeps the moved order,
+  so the sort indicator goes away on the first move and `getState` never
+  reports a sort and a row order together. Before, an `applyToData` move was
+  undone by the re-sort.
+- A move that leaves the row where it is (`moveRow(0, 1, 'before')`, for
+  example) returns `false` and fires no `rowMoving` or `rowMoved`.
+- Escape after keyboard grab steps restores the original order (and
+  `grid.data` with `applyToData`, and any sort) and fires `rowMoved` for the
+  way back, so a persisted order stays in sync.
+
+### Fixed
+- **`setup()` host sizing reaches grids inside a shadow root.** The
+  `min-height: 240px` default was adopted into the page only, which never
+  styles an element inside a shadow root. Each grid now adopts it into the
+  root it connects in, and for its own tag name, so `<apex-grid-enterprise>`
+  gets it too.
+- **ArrowDown and ArrowUp in the toolbar's export menu move focus again.** The
+  menu looked up the focused item through `document.activeElement`, which is
+  the grid's host because the menu lives in the grid's shadow root, so focus
+  never moved past the first item.
+- **Text filter conditions no longer throw on a cell that is not a string.**
+  Contains, Starts with, Equals and the rest read `null` and `undefined` as
+  empty text and match numbers, dates and other values on their text. In 3.5.0
+  one such cell (an optional field left empty, a Date in a date column) made
+  the filter apply nothing and stopped later sorts until it was removed.
+- `OperandKeys` offers the text operand names for a field whose type is not
+  number, string or boolean (a `Date`, for example), matching what the grid
+  applies, instead of accepting the value type itself as a condition. A
+  nullable or optional field keeps the names of its type (`number | null`
+  still takes the number names only), and a field typed `unknown`, such as
+  every field of a `Record<string, unknown>` row, keeps every operand name.
+- **Number range conditions no longer match an empty cell.** Greater than, Less
+  than and their or equal forms read `null`, and an empty string from CSV or
+  JSON data, as 0, so Less than 20 included rows with no value. Empty now
+  matches those cells instead.
+- **OR filter criteria are evaluated per column.** An OR on one column no longer
+  cancels the OR conditions of other columns, so `(city is Paris OR Oslo) AND
+  (id is 3 OR 99)` keeps the matching rows instead of none, and a column left
+  with only OR conditions (after removing its first chip) filters again instead
+  of keeping every row.
+- A filter entry without `caseSensitive` (from `setState`, `filter()` or an AI
+  patch) keeps the column's `filter.caseSensitive` instead of turning case
+  sensitivity off.
+- Removing a filter that is not applied, such as typing `-` or `.` first into a
+  number filter, or clearing a column that has no filter, no longer fires
+  `filtering` and `filtered` or announces that the filter was cleared.
+- When the filter changes (a condition or term is added, edited or removed, or
+  the filter is cleared), the grid scrolls back to its first row. The reset
+  targeted an element that does not scroll, so a deep scroll offset was clamped
+  to the end of the shorter result and the first matches sat above the fold.
+  Reapplying the same filter, such as `setState(getState())` or assigning an
+  equal `filterExpressions` list on every render, keeps the scroll position.
+- **A batch of edits made inside another undoes as one step.** A
+  `cellValueChanged` listener that calls `applyEdits()` during a row commit,
+  a bulk edit or a paste no longer splits it, so one undo reverts all of it.
+- Undoing or redoing a large batch reads the view once instead of once per
+  cell.
+- `applyEdits()` shows the invalid state of its cells when every edit in the
+  batch is rejected by a validator, without waiting for another render.
+- `pattern()` validators with a global (`g`) or sticky (`y`) RegExp give the
+  same result every time; repeated valid values no longer alternate between
+  passing and failing.
+- Editing a pinned row edits the pinned record; a checkbox or double-click in
+  a pinned row used to act on a body row. In row mode a cancelled
+  `cellValueChanging` aborts the whole row before anything is written.
+- Keyboard navigation keeps its position per grid: an arrow key in one grid no
+  longer continues from a cell clicked in another, and removing a grid no
+  longer resets the others. The active cell follows filters, sorting, paging,
+  data changes and hidden columns, so the body always keeps one tab stop.
+- Ctrl+End and Ctrl+Home on large grids render the target rows and keep focus
+  on the target cell, and keyboard moves no longer leave the active cell
+  hidden behind the sticky header, pinned rows or pinned columns. Full-width
+  rows from feature modules (group headers, total rows) take keyboard focus.
+- Tree data with `defaultExpanded` keeps a parent the user collapsed when
+  `grid.data` is reassigned. Two rows with the same path are both shown, and
+  `treeRowExpanding` and `treeRowExpanded` list parents that exist only as a
+  path segment.
+- Exported dates stored as `'YYYY-MM-DD'` strings carry the calendar day the
+  grid shows; west of UTC they were written one day early. An invalid `Date`
+  exports as an empty cell instead of throwing (CSV) or writing a value the
+  spreadsheet app reports as corrupt (XLSX).
+- Exporting with source `'selected'` writes rows in the order the grid shows
+  them, followed by selected rows the view hides.
+- Date and currency cells reuse their `Intl` formatters, so re-renders and
+  large exports no longer build one per cell; a malformed locale, currency or
+  date format falls back to a default instead of failing every cell.
+- Sparkline cells no longer show a misleading 0% delta when the series starts
+  at zero, and never print -0%.
+- A `cellTemplate` that reads other fields of its row updates after an inline
+  edit, `applyEdits`, paste, fill or a data change, in body and pinned rows.
+- The tree data chevron and `aria-expanded` follow every expand and collapse,
+  including `expandTreeRow` and `collapseTreeRow`.
+- Range selection highlights stay on the selected positions after a sort,
+  filter or expand moves rows.
+- With the row-number gutter, reorder grip, selection or expansion column
+  shown, a horizontal scroll no longer stacks those cells or a start-pinned
+  column on top of each other, in LTR and RTL.
+- Column group headers sit over their member columns when the reorder grip or
+  the row-number gutter is shown, and the group row's cells over pinned and
+  leading columns stay frozen on horizontal scroll.
+- Pinned columns inside a CSS-scaled container no longer overlap on
+  horizontal scroll.
+- A header drag toward later columns (rightward, or leftward with
+  `dir="rtl"`) keeps following the pointer after the first swap and always
+  ends on release, including a release outside the header or a lost release.
+- Column autosize no longer throws when group header, total or loading rows
+  are rendered.
+- With `dir="rtl"` the column resize guide is drawn on the dragged edge.
+- The filter panel: a cancelled change really leaves the filter unchanged, a
+  condition picked on a fresh panel is reported and announced as an add, the
+  filter icon of the open column closes it with a mouse, the panel stays under
+  its column on scroll, resize and keyboard column switches, and it no longer
+  runs off screen when the root font size is not 16px.
+- `setState(getState())` keeps the scroll position when the filter holds an
+  array term, and the filter panel chip lists such a term's values.
+- With an asynchronous pipeline hook, a slower earlier run no longer
+  overwrites the rows of a newer quick filter, filter or sort, and a run
+  replaced before it finishes no longer holds back the newer one's calls and
+  events.
+- A `quickFilterChanging` listener that assigns `grid.quickFilter` (to trim
+  the input, for example) keeps its value, and `quickFilterChanged` reports
+  it. A substitute equal to the current filter changes nothing and
+  `setQuickFilter` returns `false`.
+- Changing `grid.tree` after the first render (turning tree mode on or off,
+  or changing `getDataPath` or `defaultExpanded`) rebuilds the rows.
+- `grid.data` set to `null` or `undefined` (a framework prop that is still
+  loading) shows an empty grid and reads back as `[]`, instead of throwing
+  and keeping the previous rows.
+- `moveColumn` no longer fires `columnMoving` for a move that changes nothing.
+- Shift+click and Ctrl or Cmd+click beside the checkbox in the selection cell
+  do the same range or additive selection as on the checkbox itself.
+- When a `rowSelecting` listener cancels the change, the row and select-all
+  checkboxes show the real selection state instead of staying checked.
+- Moving a row while a column filter or the quick filter is active keeps every
+  hidden row in its place, in the manual order and in `grid.data` with
+  `applyToData`. Before, hidden rows were pushed to the end.
+- Replacing `grid.data` carries the manual row order and row pins onto the
+  new rows (by `rowId` when set, otherwise rows that left the data are
+  dropped). New rows can be move targets, a reload no longer disables
+  reordering and header sorting, and the pinned band no longer shows a stale
+  copy of a reloaded row.
+- A row drag ends when the pointer is released or cancelled anywhere on the
+  page, or when a move arrives with no button held, and a grid removed
+  mid-drag drops its ghost.
+- With `rowPinning.enabled` set to `false`, `pinnedRows` and the aria row
+  counts no longer report pinned rows and those rows get their reorder grip
+  back. The pins are kept for when pinning is turned back on.
+
 ## [3.5.0] - 2026-09-12
 
 A feature and accessibility release. No exported symbol was removed or renamed.

package/LICENSE.md

@@ -0,0 +1,125 @@
+## 📄 License Options for ApexGrid
+
+ApexGrid is offered under a **dual-license model** to support individuals, startups, and commercial products of all sizes.
+
+One license key works across every Apex product, so a customer of one does not buy a second for another.
+
+---
+
+### 🔓 Community License (Free)
+
+For individuals, non-profits, educators, and small businesses whose **annual revenue, operating budget, funding, or equivalent financial resources are less than $2 million USD**.
+
+✅ What's allowed:
+
+- Personal, educational, or non-profit use
+- Commercial use by small orgs (under $2M in annual revenue, budget or funding)
+- Modifications, and redistribution of the library itself (with attribution)
+
+🚫 Not allowed:
+
+- Use by companies or entities at or above $2M in annual revenue, budget or funding
+- Use in competing data grid or charting products
+- Sublicensing under different terms
+- Embedding in a product or platform used by other people, which needs the OEM License below whatever your size
+
+➡ By using ApexGrid under this license, you confirm that **you qualify as a Small Organization**.
+
+---
+
+### 💼 Commercial License (Paid)
+
+The Commercial License applies to all paid SKUs (Pro, Premium and OEM).
+
+The **Community License** is available at no cost **only** to organizations whose **annual revenue, operating budget, funding, or equivalent financial resources are under $2M USD**.
+If you, your parent company, affiliates, or any entity under common control reach $2M USD or more on any of those measures, you must purchase one of our paid licenses.
+
+Pro and Premium are priced per developer, and priced on the features you use rather than on your size.
+
+✅ What's included:
+
+- Use in internal tools and commercial applications
+- Modifications and app-level distribution
+- 12-month subscription with updates & support
+
+🚫 Not allowed:
+
+- Redistribution in toolkits, SDKs, or platforms
+- Use by unlicensed developers
+- Competing data grid or charting products
+
+---
+
+### 🎚 What each plan includes for ApexGrid
+
+- **Free, at Community and above:** ApexGrid itself.
+- **Premium and above:** the ApexGrid Enterprise add-on, a separate package (`apex-grid-enterprise`) covering Row Grouping, Aggregations, Pivoting, the Server-Side Row Model, Advanced Filter Builder, Range Selection, Integrated Charts, Formula Engine, AI Toolkit and Companion Elements.
+
+For the full comparison see [https://apexcharts.com/pricing](https://apexcharts.com/pricing).
+
+---
+
+### 🏛 Non-Profit Tiers
+
+Non-Profits are treated like commercial entities:
+
+- Annual operating budget **less than $2 million USD**
+- _Eligible for Community licenses_
+
+or
+
+- Annual operating budget **greater than $2 million USD**
+- _Commercial license with possible discounts for Community, Pro, Premium and OEM products_
+
+---
+
+### 🔄 OEM / Redistribution License (Paid)
+
+Required if you are **embedding ApexGrid into a product or platform used by other people**, such as:
+
+- No-code dashboards
+- Developer platforms
+- Embedded BI tools
+- SDKs
+
+✅ What's included:
+
+- Redistribution rights for **one application or product**
+- **Unlimited developer seats** on that application, with no separate per-developer license to buy
+- **Every licensed feature**, at the highest tier
+- 12-month subscription with updates & support
+
+Your end users need no license of their own. A second application needs a second OEM license. White-label, resale, and affiliate arrangements are quoted separately.
+
+✅ OEM **not required** if your app simply renders static grids and users **cannot** configure or interact with them.
+
+---
+
+### ⏳ When a subscription ends
+
+Your license key expires, and **licensed features render with a trial watermark**. You no longer receive updates, new features, or technical support. Work built only from free features is unaffected, and your existing deployment keeps running.
+
+For OEM licenses, continued redistribution requires an active subscription.
+
+---
+
+### ⚠️ License Acceptance
+
+By installing ApexGrid (e.g., via `npm install apex-grid`), you are agreeing to the applicable license based on your usage:
+
+- Community License (if under $2M in annual revenue, budget or funding)
+- Commercial License (if at or above $2M in annual revenue, budget or funding)
+- OEM License (if redistributing to third-party users)
+
+---
+
+### 🛠 Need a License or Have Questions?
+
+📧 Contact us at [sales@apexcharts.com](mailto:sales@apexcharts.com)
+📚 Read full license agreements here: [https://apexcharts.com/license](https://apexcharts.com/license)
+
+---
+
+Copyright © 2026 ApexCharts. All rights reserved.
+
+Thank you for supporting ApexGrid! Your licensing keeps the Community License available to individuals and small teams.

package/README.md

@@ -45,7 +45,7 @@ import { setup } from 'apex-grid';
 setup();
 ```
 
-That single call registers `<apex-grid>` and adopts a default host stylesheet (`height: 100%; min-height: 240px`). The grid is styled out-of-the-box; no theme CSS import is required.
+That single call registers `<apex-grid>` and adopts a default host stylesheet (`height: 100%; min-height: 240px`), also inside any shadow root a grid connects in. The grid is styled out-of-the-box; no theme CSS import is required.
 
 ### Render the grid
 
@@ -111,7 +111,7 @@ Without this, `<apex-grid>` is an inert unknown element.
 
 ### 3. (Optional) Customize the look
 
-The grid is styled out-of-the-box; there is no theme to import. Customize it by overriding the `--ag-*` CSS custom properties on `apex-grid` (or any ancestor); a one-line brand override cascades to every tint:
+The grid is styled out-of-the-box; there is no theme to import. Customize it by overriding the `--ag-*` CSS custom properties on `apex-grid` or on any ancestor: `:root`, a dashboard panel, or the shadow host of a web component the grid renders in (custom properties inherit through shadow boundaries, however deep). A one-line brand override cascades to every tint:
 
 ```css
 apex-grid {
@@ -122,16 +122,40 @@ apex-grid {
 }
 ```
 
-See [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full token list (brand, surfaces, text, semantic state colors, typography, spacing, motion).
+See [`src/styles/_token-values.scss`](src/styles/_token-values.scss) for the full token list and defaults (surfaces, text, semantic state colors, typography, spacing, motion).
+
+**Where the defaults live.** The first grid to connect adopts the token defaults into its document, on `:where(:root)`, through `adoptedStyleSheets` (no `<style>` element, so no CSP nonce). Zero specificity means any value you set wins, and `var(--ag-*)` reads in your own CSS resolve to the defaults. If you manage your own CSS, opt out with `setup({ tokenStyles: false })` and import the same defaults as a file (also the way to get them into server-rendered HTML):
+
+```ts
+import 'apex-grid/tokens.css';
+```
+
+The grid renders the same without the sheet; it carries the defaults as fallbacks. Three groups have no root default, so page CSS reading them needs its own fallback:
+
+- `--ag-brand` and `--ag-brand-strong`, so an Ignite UI palette set on any ancestor keeps tinting the grid (see below).
+- The derived washes `--ag-brand-soft`, `--ag-brand-softer`, `--ag-brand-line`, `--ag-row-hover` and `--ag-surface-alt`. The grid mixes them from the brand and surface in effect, so they follow a brand set on an ancestor. Set them only to override the mix.
+
+**Dark mode.** `theme="dark"` reads its own colour inputs, `--ag-dark-*` (`--ag-dark-surface`, `--ag-dark-text`, `--ag-dark-hairline`, `--ag-dark-shadow-card`, and so on), so a light palette set on a shared ancestor never puts a white surface under the dark theme's light text. Sizing, typography, motion, the brand and the base state colours are shared by both modes. To theme both from one place, set both palettes:
+
+```css
+.dashboard {
+  --ag-brand: #7c3aed;
+  --ag-surface: #fdfcff;
+  --ag-dark-surface: #140f24;
+}
+```
+
+`theme="tinted"` mixes a little brand into the surface, gridline and muted-text values in effect, including any you set. Its row separators are the brand alone, so a tinted grid ignores `--ag-border` and `--ag-dark-border`.
 
 **Grid edge / shadow.** By default the grid shows a flat 1px hairline edge (no drop shadow). Control it with the `--ag-grid-shadow` hook, an opt-in override that is not one of the `_tokens.scss` defaults:
 
 ```css
-apex-grid { --ag-grid-shadow: var(--ag-shadow-card); } /* elevated floating-card look */
-apex-grid { --ag-grid-shadow: none; }                  /* remove the edge entirely */
+apex-grid { --ag-grid-shadow: var(--ag-shadow-card); }                     /* elevated floating-card look */
+apex-grid[theme~='dark'] { --ag-grid-shadow: var(--ag-dark-shadow-card); } /* the same, for dark grids */
+apex-grid { --ag-grid-shadow: none; }                                      /* remove the edge entirely */
 ```
 
-If you embed the grid in an Ignite UI app, the brand tokens automatically re-tint from its palette: they read `--ig-primary-500` with the grid's own default as the fallback. That is a plain CSS variable lookup, so the grid neither depends on nor bundles Ignite UI.
+If you embed the grid in an Ignite UI app, the brand tokens automatically re-tint from its palette, wherever it is declared: they read `--ig-primary-500` with the grid's own default as the fallback. That is a plain CSS variable lookup, so the grid neither depends on nor bundles Ignite UI.
 
 ### 4. Size the host
 
@@ -334,6 +358,14 @@ re-renders. The returned tally splits `applied` from `unchanged`, `invalid`,
 one. Edits naming a row out of range or a column the user could not edit either
 are skipped rather than throwing.
 
+`rowIndex` is view-relative, so it reaches the current page only. To edit rows
+anywhere (other pages, pinned rows, rows under a collapsed tree parent), name
+the record itself with `row`:
+
+```ts
+grid.applyEdits(grid.selectedRows.map((row) => ({ row, column: 'discount', value: 0 })));
+```
+
 ### Keyboard navigation and accessibility
 
 The grid body is a single tab stop: Tab enters the grid, and the active cell
@@ -416,7 +448,7 @@ grid.unpinRow(data[0]);
 grid.pinnedRows;                    // { top: T[], bottom: T[] }
 ```
 
-Pinned rows render in sticky top / bottom bands outside the virtualizer and are lifted out of the scrollable set (no duplication). Selection and styling work by row reference. Events: `rowPinning` (cancellable), `rowPinned`.
+Pinned rows render in sticky top / bottom bands outside the virtualizer and are lifted out of the scrollable set (no duplication). Selection and styling work by row reference. Replacing `grid.data` carries the pins onto the new rows (by `rowId` when set, else a pin whose row left the data is dropped). While `rowPinning.enabled` is false the pinned rows return to the body and `pinnedRows` reports none, but the pins are kept (`getState` still saves them) and re-enabling brings them back. Events: `rowPinning` (cancellable), `rowPinned`.
 
 ### Row drag-reorder
 
@@ -426,7 +458,7 @@ grid.rowReordering = { enabled: true };   // add applyToData: true to splice gri
 grid.moveRow(0, 4, 'after');
 ```
 
-By default (`rowReordering.handle`, boolean, default `true`) a six-dot grip handle shows at the start of every reorderable row, and dragging lifts a full-row floating ghost that follows the cursor. Both interaction modes are supported: **handle mode** (only the grip starts a drag, so the rest of the row stays free for selection and editing) and **whole-row mode** (set `handle: false` to drag from anywhere on the row, excluding interactive sub-parts like inputs and buttons). Or use the keyboard: focus a row, **Space** to grab, **Arrow** keys to move, **Space / Enter** to drop, **Esc** to cancel. The grid holds a manual order that is mutually exclusive with sorting (applying a sort clears it). By default the app persists the order via the `rowMoved` event; set `applyToData: true` to splice `grid.data` directly. Events: `rowMoving` (cancellable), `rowMoved { from, to, data }`.
+By default (`rowReordering.handle`, boolean, default `true`) a six-dot grip handle shows at the start of every reorderable row, and dragging lifts a full-row floating ghost that follows the cursor. Both interaction modes are supported: **handle mode** (only the grip starts a drag, so the rest of the row stays free for selection and editing) and **whole-row mode** (set `handle: false` to drag from anywhere on the row, excluding interactive sub-parts like inputs and buttons). Or use the keyboard: focus a row, **Space** to grab, **Arrow** keys to move, **Space / Enter** to drop, **Esc** to cancel. The grid holds a manual order that is mutually exclusive with sorting (applying a sort clears it, and a move clears the sort). Rows hidden by a filter keep their place when a visible row moves, and the order follows `grid.data` when it is replaced (by `rowId` when set). By default the app persists the order via the `rowMoved` event; set `applyToData: true` to splice `grid.data` directly. Events: `rowMoving` (cancellable), `rowMoved { from, to, position, toIndex, data }`, where `toIndex` is the view index the row lands at.
 
 ### Row expansion (master-detail)
 
@@ -514,7 +546,7 @@ Search input has a `debounce` attribute (default `200`ms).
 
 ### Theming
 
-The grid styles itself through `--ag-*` CSS custom properties; override them on `apex-grid` (or any ancestor) to rebrand; see [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full list. Where an Ignite UI palette is present, the brand tokens auto-tint from `--ig-primary-500`.
+The grid styles itself through `--ag-*` CSS custom properties; override them on `apex-grid` or any ancestor (shadow hosts included) to rebrand, and use `--ag-dark-*` for dark grids. See [Customize the look](#3-optional-customize-the-look) and [`src/styles/_token-values.scss`](src/styles/_token-values.scss) for the full list. Where an Ignite UI palette is present, the brand tokens auto-tint from `--ig-primary-500`.
 
 Style with CSS parts on the grid, paginator, and toolbar:
 
@@ -523,6 +555,28 @@ apex-grid::part(paginator) { background: var(--surface-2); }
 apex-grid-toolbar::part(search-input) { font-family: var(--font-mono); }
 ```
 
+Body rows re-export these parts, so `apex-grid::part(name)` reaches them:
+
+| Part | What |
+|---|---|
+| `cell` | A data cell |
+| `selection-cell`, `selection-checkbox` | Selection column cell and its checkbox |
+| `expansion-cell`, `expansion-toggle`, `expansion-chevron` | Expansion column cell, its button and the chevron icon |
+| `detail-panel` | Expanded detail panel container |
+| `row-number-cell`, `row-number` | Row-number gutter cell and its label (`coordinateHints`) |
+| `reorder-handle-cell`, `reorder-handle`, `reorder-grip` | Row-reorder grip cell, handle and icon (handle mode) |
+| `group-row` | Default container of a row a feature module renders full width |
+
+Parts used inside your own `detailTemplate` content are re-exported when you list them in `expansion.exportParts`:
+
+```js
+grid.expansion = {
+  enabled: true,
+  exportParts: ['order-summary'],
+  detailTemplate: ({ data }) => html`<div part="order-summary">${data.total}</div>`,
+};
+```
+
 ### Right-to-left
 
 Set `dir="rtl"` on the grid or any ancestor and the whole grid mirrors — no
@@ -688,7 +742,7 @@ All events bubble and are composed across shadow boundaries. Names ending in `-i
 | `historyChanged` | no | `{ canUndo, canRedo }` |
 | `rowSelecting` / `rowSelected` | yes / no | `{ added, removed }` |
 | `rowPinning` / `rowPinned` | yes / no | `{ row, position }` |
-| `rowMoving` / `rowMoved` | yes / no | `{ from, to, data }` |
+| `rowMoving` / `rowMoved` | yes / no | `{ from, to, position, toIndex, data }` |
 | `rowExpanding` / `rowExpanded` | yes / no | row context |
 | `treeRowExpanding` / `treeRowExpanded` | yes / no | row context |
 | `stateChanged` | no | `{ state }` (debounced; only while listened) |