apex-grid 2.0.0 → 3.0.0

package/README.md

@@ -19,10 +19,10 @@ A Lit-based, framework-agnostic web component data grid. Ships as a single custo
 - **Row selection** — single or multiple, optional checkbox column, full programmatic API.
 - **Row expansion (master-detail)** — opt-in chevron column with a `detailTemplate`.
 - **Tree data (nested rows)** — AG Grid–style `getDataPath` pattern over a flat array.
-- **CSV / XLSX export** — programmatic methods plus an optional toolbar dropdown.
+- **CSV export** — programmatic method plus an optional toolbar dropdown. (Excel/XLSX export is in `apex-grid-enterprise`.)
 - **Toolbar** — opt-in `<apex-grid-toolbar>` with debounced quick filter and export menu.
 - **Templating** — slot-based templates for cells, headers, editors, and detail panels.
-- **Theming** — Bootstrap / Fluent / Indigo / Material themes via `igniteui-webcomponents`, with light and dark variants.
+- **Theming** — styled out-of-the-box; fully customizable through `--ag-*` CSS custom properties (no theme import or build step). Auto-matches an `igniteui-webcomponents` host app when one is present.
 - **Accessibility** — WCAG 2.2 AA semantics (`role="grid"` / `role="treegrid"`, `aria-rowcount`, `aria-colcount`, focus + keyboard navigation).
 - **Provenance-signed npm releases** with OIDC trusted publishing.
 
@@ -34,12 +34,11 @@ A Lit-based, framework-agnostic web component data grid. Ships as a single custo
 
 ```ts
 import { setup } from 'apex-grid';
-import 'igniteui-webcomponents/themes/light/bootstrap.css';
 
-setup({ theme: 'bootstrap' });
+setup();
 ```
 
-That single call registers `<apex-grid>`, calls `configureTheme('bootstrap')`, and adopts a default host stylesheet (`height: 100%; min-height: 240px`). The Ignite UI theme CSS still has to be imported by you — bundlers can't dynamically import CSS portably.
+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.
 
 ### Render the grid
 
@@ -105,18 +104,22 @@ ApexGrid.register();
 
 Without this, `<apex-grid>` is an inert unknown element.
 
-### 3. Load a theme
+### 3. (Optional) Customize the look
 
-The grid's filter dropdowns and sort indicators come from `igniteui-webcomponents`. Both the CSS import **and** the `configureTheme()` call are required:
+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:
 
-```ts
-import { configureTheme } from 'igniteui-webcomponents';
-import 'igniteui-webcomponents/themes/light/bootstrap.css';
-
-configureTheme('bootstrap'); // 'bootstrap' | 'material' | 'fluent' | 'indigo'
+```css
+apex-grid {
+  --ag-brand: #7c3aed;        /* selection, focus, accents */
+  --ag-brand-strong: #6d28d9; /* hover / pressed */
+  --ag-radius: 12px;          /* outer card radius */
+  --ag-row-h: 40px;           /* row height */
+}
 ```
 
-For dark mode, swap `light` → `dark` in the import path. The name passed to `configureTheme()` must match the imported CSS file.
+See [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full token list (brand, surfaces, text, semantic state colors, typography, spacing, motion).
+
+If you embed the grid alongside `igniteui-webcomponents`, the brand tokens automatically re-tint from the igniteui palette (`--ig-primary-500`) — no configuration needed.
 
 ### 4. Size the host
 
@@ -136,7 +139,7 @@ apex-grid {
 
 ### What success looks like
 
-When all four steps are in place you should see:
+With the element registered and the host sized, you should see:
 
 - **Visible borders** between rows and columns.
 - **Sort arrows** (↕) next to each header when `sort: true`.
@@ -148,7 +151,7 @@ When all four steps are in place you should see:
 
 | What you see | Likely cause |
 |---|---|
-| Bare table, no borders, no filter UI | Step 3 — theme CSS not imported or `configureTheme()` not called |
+| Want a different look / brand color | Step 3 — override the `--ag-*` CSS variables |
 | Only ~3 rows visible regardless of data size | Step 4 — no bounded height, **or** consumer CSS sets `display` on `<apex-grid>` (check console for the warning) |
 | `<apex-grid>` blank tag in DOM | Step 2 — element not registered |
 | Columns shown as literal `[object Object]` | `columns=` used as an attribute — must be a **property** (`.columns=${...}` in Lit, `[columns]=` in Angular, `:columns.prop=` in Vue, `el.columns = ...` in vanilla JS) |
@@ -329,7 +332,7 @@ await grid.expandAllTreeRows();
 
 Methods: `toggleTreeRow`, `expandTreeRow`, `collapseTreeRow`, `expandAllTreeRows`, `collapseAllTreeRows`, `isTreeRowExpanded`. Events: `treeRowExpanding` (cancellable), `treeRowExpanded`. When tree mode is active, the host element advertises `role="treegrid"`.
 
-### CSV / XLSX export
+### CSV export
 
 Programmatic:
 
@@ -337,11 +340,11 @@ Programmatic:
 grid.exportToCSV();                                            // downloads data.csv
 grid.exportToCSV({ filename: 'users', source: 'selected' });
 const text = grid.exportToCSV({ filename: '' });               // no download, returns the string
-
-grid.exportToXLSX({ filename: 'users', sheetName: 'Users' });
 ```
 
-`source` can be `'view'` (default — post-filter/post-sort), `'page'`, `'selected'`, or `'all'`. Per-column opt-out: `{ key: 'secret', exportable: false }`. XLSX preserves native cell types for numbers, booleans, and `Date` values.
+`source` can be `'view'` (default — post-filter/post-sort), `'page'`, `'selected'`, or `'all'`. Per-column opt-out: `{ key: 'secret', exportable: false }`.
+
+> **XLSX (Excel) export** moved to [`apex-grid-enterprise`](https://www.npmjs.com/package/apex-grid-enterprise) in v3. `<apex-grid-enterprise>` adds `grid.exportToXLSX(...)` and an "Export XLSX" entry to this same toolbar menu. CSV stays free.
 
 Toolbar dropdown:
 
@@ -349,7 +352,7 @@ Toolbar dropdown:
 <apex-grid show-export></apex-grid>
 ```
 
-Renders a download icon in the toolbar's trailing actions area; the menu has "Export CSV" and "Export XLSX" entries. Toolbar `exportFilename` overrides the default `data` filename. Attribute: `show-export`.
+Renders a download icon in the toolbar's trailing actions area; the menu has an "Export CSV" entry (the enterprise grid adds "Export XLSX"). Toolbar `exportFilename` overrides the default `data` filename. Attribute: `show-export`.
 
 ### Toolbar
 
@@ -370,7 +373,7 @@ Search input has a `debounce` attribute (default `200`ms).
 
 ### Theming
 
-Built-in themes: `bootstrap`, `material`, `fluent`, `indigo` — each with `light` and `dark` variants. Switch at runtime via `configureTheme(name)`.
+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. When `igniteui-webcomponents` is present, the brand tokens auto-tint from its palette.
 
 Style with CSS parts on the grid, paginator, and toolbar:
 
@@ -446,7 +449,7 @@ toggleTreeRow(row); expandTreeRow(row); collapseTreeRow(row)
 expandAllTreeRows(); collapseAllTreeRows(); isTreeRowExpanded(row)
 
 exportToCSV(options?): string
-exportToXLSX(options?): Uint8Array
+exportAs(formatId, options?): void   // toolbar dispatch; 'csv' (community), 'xlsx' (enterprise)
 ```
 
 ### Events
@@ -523,4 +526,4 @@ Any push whose head commit does not start with `release:` is a no-op for the wor
 
 ## License
 
-See [LICENSE.md](LICENSE.md).
+See [LICENSE](LICENSE).

package/components/grid.d.ts

@@ -3,7 +3,7 @@ import { nothing } from 'lit';
 import { DataOperationsController } from '../controllers/data-operation.js';
 import { GridDOMController } from '../controllers/dom.js';
 import { StateController } from '../controllers/state.js';
-import { type CSVExportOptions, type XLSXExportOptions } from '../internal/export.js';
+import { type CSVExportOptions, type ExportFormat, type ExportOptions } from '../internal/export.js';
 import { EventEmitterBase } from '../internal/mixins/event-emitter.js';
 import type { ColumnConfiguration, DataPipelineConfiguration, GridEditingConfiguration, GridExpansionConfiguration, GridSelectionConfiguration, GridSortConfiguration, GridTreeConfiguration, Keys, PaginationConfiguration, PaginationState, PinPosition } from '../internal/types.js';
 import type { FilterExpression } from '../operations/filter/types.js';
@@ -558,7 +558,7 @@ export interface ApexGridEventMap<T extends object> {
  *
  */
 export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGridEventMap<T>> {
-    static get tagName(): "apex-grid";
+    static get tagName(): string;
     static styles: import("lit").CSSResult;
     /**
      * Registers `<apex-grid>` and its internal dependencies with the custom-element
@@ -574,6 +574,14 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     protected stateController: StateController<T>;
     protected DOM: GridDOMController<T>;
     protected dataController: DataOperationsController<T>;
+    /**
+     * Builds the grid's {@link StateController}. This is the single construction
+     * site for `stateController` — overriding it (rather than re-declaring the
+     * field) is the supported seam for derived grids to inject optional
+     * {@link GridFeatureModule}s while preserving field-initializer ordering.
+     * The community grid registers no extra modules.
+     */
+    protected createStateController(): StateController<T>;
     protected stateProvider: ContextProvider<{
         __context__: StateController<any>;
     }, this>;
@@ -664,9 +672,9 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      *
      * @remarks
      * When `true`, the toolbar shows a download button on the trailing side;
-     * clicking it opens a menu with "Export CSV" and "Export XLSX" entries
-     * that call {@link ApexGrid.exportToCSV} and {@link ApexGrid.exportToXLSX}
-     * respectively. Both methods remain callable programmatically regardless
+     * clicking it opens a menu with one entry per {@link ApexGrid.exportFormats}
+     * (CSV in the community grid) that calls {@link ApexGrid.exportAs}.
+     * {@link ApexGrid.exportToCSV} remains callable programmatically regardless
      * of this flag.
      *
      * @attr show-export
@@ -921,7 +929,6 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     protected pipeline(): Promise<void>;
     protected paginationChanged(): void;
     protected quickFilterChanged(): void;
-    constructor();
     protected updated(): void;
     protected firstUpdated(): void;
     /**
@@ -1102,24 +1109,22 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      */
     exportToCSV(options?: CSVExportOptions<T>): string;
     /**
-     * Exports the current grid contents as an `.xlsx` workbook and (in a browser
-     * context) triggers a download.
+     * The export formats offered in the toolbar's export menu, in order.
      *
      * @remarks
-     * Produces a single-sheet workbook with a bold header row. Numbers, booleans
-     * and `Date` values keep their native cell type in Excel; everything else is
-     * written as inline strings. Sharing the same `source` / `columns` /
-     * `formatter` options as {@link ApexGrid.exportToCSV}, plus an optional
-     * `sheetName`. Pass `filename: ''` to skip the download and only receive
-     * the bytes back.
-     *
-     * @example
-     * ```ts
-     * grid.exportToXLSX();
-     * grid.exportToXLSX({ filename: 'users', sheetName: 'Users' });
-     * ```
+     * The community grid offers CSV only. This is the seam derived grids use to
+     * contribute more formats: `@apexcharts/grid-enterprise` overrides it to add
+     * `'xlsx'`. The toolbar renders one menu item per entry and dispatches the
+     * chosen id to {@link ApexGrid.exportAs}.
+     */
+    get exportFormats(): ReadonlyArray<ExportFormat>;
+    /**
+     * Exports the grid in the given format (one of {@link ApexGrid.exportFormats}).
+     * Called by the toolbar's export menu. The community grid handles `'csv'`;
+     * derived grids override to handle additional formats, delegating to `super`
+     * for the ones they don't add.
      */
-    exportToXLSX(options?: XLSXExportOptions<T>): Uint8Array;
+    exportAs(formatId: string, options?: ExportOptions<T>): void;
     /**
      * Moves a column relative to another column.
      *
@@ -1168,6 +1173,5 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
 }
 declare global {
     interface HTMLElementTagNameMap {
-        [ApexGrid.tagName]: ApexGrid<object>;
     }
 }

package/components/grid.js

@@ -12,18 +12,13 @@ import { DataOperationsController } from '../controllers/data-operation.js';
 import { GridDOMController } from '../controllers/dom.js';
 import { gridStateContext, StateController } from '../controllers/state.js';
 import { DEFAULT_COLUMN_CONFIG, PIPELINE } from '../internal/constants.js';
-import { buildCSV, downloadBlob, getColumnLabel, resolveExportColumns, resolveExportRows, resolveExportValue, } from '../internal/export.js';
+import { buildCSV, downloadBlob, } from '../internal/export.js';
 import { EventEmitterBase } from '../internal/mixins/event-emitter.js';
 import { registerComponent } from '../internal/register.js';
 import { GRID_TAG } from '../internal/tags.js';
-import { addThemingController } from '../internal/theming.js';
 import { asArray, autoGenerateColumns, getDisplayColumns, getFilterOperandsFor, } from '../internal/utils.js';
 import { watch } from '../internal/watch.js';
-import { buildXLSX } from '../internal/xlsx.js';
-import { styles as bootstrap } from '../styles/grid/themes/light/grid.bootstrap.css.js';
-import { styles as fluent } from '../styles/grid/themes/light/grid.fluent.css.js';
-import { styles as indigo } from '../styles/grid/themes/light/grid.indigo.css.js';
-import { styles as material } from '../styles/grid/themes/light/grid.material.css.js';
+import { styles as gridStyles } from '../styles/grid/grid.css.js';
 import ApexGridCell from './cell.js';
 import ApexFilterRow from './filter-row.js';
 import ApexGridHeaderRow from './header-row.js';
@@ -32,13 +27,38 @@ import ApexGridRow from './row.js';
 import ApexGridToolbar from './toolbar.js';
 import ApexVirtualizer from './virtualizer.js';
 export class ApexGrid extends EventEmitterBase {
+    constructor() {
+        super(...arguments);
+        this.stateController = this.createStateController();
+        this.DOM = new GridDOMController(this, this.stateController);
+        this.dataController = new DataOperationsController(this);
+        this.stateProvider = new ContextProvider(this, {
+            context: gridStateContext,
+            initialValue: this.stateController,
+        });
+        this.dataState = [];
+        this.columns = [];
+        this.data = [];
+        this.autoGenerate = false;
+        this.sortConfiguration = {
+            multiple: true,
+            triState: true,
+        };
+        this.quickFilter = '';
+        this.showQuickFilter = false;
+        this.showExport = false;
+        this.columnReordering = false;
+    }
     static get tagName() {
         return GRID_TAG;
     }
-    static { this.styles = bootstrap; }
+    static { this.styles = gridStyles; }
     static register() {
         registerComponent(ApexGrid, ApexVirtualizer, ApexGridRow, ApexGridHeaderRow, ApexFilterRow, ApexGridPaginator, ApexGridToolbar);
     }
+    createStateController() {
+        return new StateController(this);
+    }
     get selectedRows() {
         return this.stateController.selection.selectedRows();
     }
@@ -205,32 +225,6 @@ export class ApexGrid extends EventEmitterBase {
             this.pipeline();
         }
     }
-    constructor() {
-        super();
-        this.stateController = new StateController(this);
-        this.DOM = new GridDOMController(this, this.stateController);
-        this.dataController = new DataOperationsController(this);
-        this.stateProvider = new ContextProvider(this, {
-            context: gridStateContext,
-            initialValue: this.stateController,
-        });
-        this.dataState = [];
-        this.columns = [];
-        this.data = [];
-        this.autoGenerate = false;
-        this.sortConfiguration = {
-            multiple: true,
-            triState: true,
-        };
-        this.quickFilter = '';
-        this.showQuickFilter = false;
-        this.showExport = false;
-        this.columnReordering = false;
-        addThemingController(this, {
-            light: { bootstrap, material, fluent, indigo },
-            dark: { bootstrap, material, fluent, indigo },
-        });
-    }
     updated() {
         this.setAttribute('role', this.stateController.tree.enabled ? 'treegrid' : 'grid');
         const hasFilter = this.columns.some((column) => column.filter);
@@ -384,25 +378,13 @@ export class ApexGrid extends EventEmitterBase {
         }
         return csv;
     }
-    exportToXLSX(options = {}) {
-        const columns = resolveExportColumns(this, options);
-        const rows = resolveExportRows(this, options.source);
-        const includeHeader = options.includeHeader ?? true;
-        const sheet = {
-            name: options.sheetName ?? 'Sheet1',
-            headers: includeHeader ? columns.map((column) => getColumnLabel(column)) : [],
-            rows: rows.map((row) => columns.map((column) => resolveExportValue(column, row, options))),
-        };
-        const bytes = buildXLSX(sheet);
-        const filename = options.filename;
-        const mime = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
-        if (filename) {
-            downloadBlob(`${filename}.xlsx`, bytes, mime);
-        }
-        else if (filename === undefined) {
-            downloadBlob('data.xlsx', bytes, mime);
+    get exportFormats() {
+        return [{ id: 'csv', label: 'Export CSV' }];
+    }
+    exportAs(formatId, options = {}) {
+        if (formatId === 'csv') {
+            this.exportToCSV(options);
         }
-        return bytes;
     }
     async moveColumn(fromKey, toKey, position = 'before') {
         if (fromKey === toKey)