apex-grid 2.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +32 -22
  3. package/components/grid.d.ts +69 -40
  4. package/components/grid.js +34 -52
  5. package/components/grid.js.map +1 -1
  6. package/components/header.js +7 -13
  7. package/components/header.js.map +1 -1
  8. package/components/toolbar.js +13 -29
  9. package/components/toolbar.js.map +1 -1
  10. package/controllers/state.d.ts +15 -1
  11. package/controllers/state.js +11 -1
  12. package/controllers/state.js.map +1 -1
  13. package/custom-elements.json +320 -242
  14. package/define.js.map +1 -1
  15. package/docs/assets/hierarchy.js +1 -1
  16. package/docs/assets/highlight.css +9 -2
  17. package/docs/assets/icons.js +1 -1
  18. package/docs/assets/icons.svg +1 -1
  19. package/docs/assets/main.js +4 -4
  20. package/docs/assets/navigation.js +1 -1
  21. package/docs/assets/search.js +1 -1
  22. package/docs/assets/style.css +3 -3
  23. package/docs/classes/ApexGrid.html +115 -93
  24. package/docs/functions/setup.html +11 -17
  25. package/docs/hierarchy.html +1 -1
  26. package/docs/index.html +91 -47
  27. package/docs/interfaces/ApexCellValueChangedEvent.html +5 -5
  28. package/docs/interfaces/ApexCellValueChangingEvent.html +6 -6
  29. package/docs/interfaces/ApexColumnMovedEvent.html +4 -4
  30. package/docs/interfaces/ApexColumnMovingEvent.html +5 -5
  31. package/docs/interfaces/ApexColumnPinnedEvent.html +3 -3
  32. package/docs/interfaces/ApexColumnPinningEvent.html +4 -4
  33. package/docs/interfaces/ApexDetailContext.html +4 -4
  34. package/docs/interfaces/ApexFilteredEvent.html +3 -3
  35. package/docs/interfaces/ApexFilteringEvent.html +3 -3
  36. package/docs/interfaces/ApexGridEventMap.html +21 -16
  37. package/docs/interfaces/ApexHeaderContext.html +3 -3
  38. package/docs/interfaces/ApexPageChangedEvent.html +5 -5
  39. package/docs/interfaces/ApexPageChangingEvent.html +5 -5
  40. package/docs/interfaces/ApexQuickFilterChangedEvent.html +2 -2
  41. package/docs/interfaces/ApexQuickFilterChangingEvent.html +3 -3
  42. package/docs/interfaces/ApexRowEditEndedEvent.html +3 -3
  43. package/docs/interfaces/ApexRowEditStartedEvent.html +2 -2
  44. package/docs/interfaces/ApexRowExpandedEvent.html +4 -4
  45. package/docs/interfaces/ApexRowExpandingEvent.html +5 -5
  46. package/docs/interfaces/ApexRowSelectedEvent.html +4 -4
  47. package/docs/interfaces/ApexRowSelectingEvent.html +5 -5
  48. package/docs/interfaces/ApexTreeRowExpandedEvent.html +4 -4
  49. package/docs/interfaces/ApexTreeRowExpandingEvent.html +5 -5
  50. package/docs/interfaces/BaseApexCellContext.html +6 -6
  51. package/docs/interfaces/BaseApexEditorContext.html +8 -8
  52. package/docs/interfaces/BaseColumnConfiguration.html +34 -15
  53. package/docs/interfaces/BaseColumnSortConfiguration.html +3 -3
  54. package/docs/interfaces/BaseFilterExpression.html +4 -4
  55. package/docs/interfaces/BaseSortExpression.html +3 -3
  56. package/docs/interfaces/CSVExportOptions.html +9 -9
  57. package/docs/interfaces/ColumnFilterConfiguration.html +2 -2
  58. package/docs/interfaces/DataPipelineConfiguration.html +3 -3
  59. package/docs/interfaces/ExportFormat.html +10 -0
  60. package/docs/interfaces/ExportOptions.html +6 -6
  61. package/docs/interfaces/GridEditingConfiguration.html +4 -4
  62. package/docs/interfaces/GridExpansionConfiguration.html +5 -5
  63. package/docs/interfaces/GridSelectionConfiguration.html +4 -4
  64. package/docs/interfaces/GridSortConfiguration.html +3 -3
  65. package/docs/interfaces/GridTreeConfiguration.html +5 -5
  66. package/docs/interfaces/PaginationConfiguration.html +6 -6
  67. package/docs/interfaces/PaginationState.html +5 -5
  68. package/docs/media/LICENSE +80 -0
  69. package/docs/media/_tokens.scss +106 -0
  70. package/docs/media/package.json +14 -12
  71. package/docs/modules.html +1 -1
  72. package/docs/types/ApexCellContext.html +1 -1
  73. package/docs/types/ApexEditorContext.html +1 -1
  74. package/docs/types/BasePropertyType.html +1 -1
  75. package/docs/types/BaseSortComparer.html +1 -1
  76. package/docs/types/ColumnConfiguration.html +1 -1
  77. package/docs/types/ColumnDropPosition.html +1 -1
  78. package/docs/types/ColumnSortConfiguration.html +1 -1
  79. package/docs/types/DataPipelineHook.html +1 -1
  80. package/docs/types/DataPipelineParams.html +4 -4
  81. package/docs/types/DataType.html +18 -1
  82. package/docs/types/ExportSource.html +1 -1
  83. package/docs/types/FilterCriteria.html +1 -1
  84. package/docs/types/FilterExpression.html +1 -1
  85. package/docs/types/Keys.html +1 -1
  86. package/docs/types/PropertyType.html +1 -1
  87. package/docs/types/SortComparer.html +1 -1
  88. package/docs/types/SortExpression.html +1 -1
  89. package/docs/types/SortState.html +1 -1
  90. package/index.d.ts +1 -1
  91. package/index.js.map +1 -1
  92. package/internal/column-types.js +161 -1
  93. package/internal/column-types.js.map +1 -1
  94. package/internal/export.d.ts +12 -4
  95. package/internal/export.js.map +1 -1
  96. package/internal/feature-module.d.ts +27 -0
  97. package/internal/feature-module.js +2 -0
  98. package/internal/feature-module.js.map +1 -0
  99. package/internal/icons.d.ts +7 -0
  100. package/internal/icons.js +11 -0
  101. package/internal/icons.js.map +1 -1
  102. package/internal/index.d.ts +20 -0
  103. package/internal/index.js +6 -0
  104. package/internal/index.js.map +1 -0
  105. package/internal/types.d.ts +54 -5
  106. package/internal/types.js.map +1 -1
  107. package/operations/filter/tree.d.ts +1 -1
  108. package/operations/filter/types.js.map +1 -1
  109. package/operations/sort/types.js.map +1 -1
  110. package/package.json +5 -1
  111. package/setup.d.ts +19 -26
  112. package/setup.js +4 -2
  113. package/setup.js.map +1 -1
  114. package/styles/_checkbox.css.js +3 -0
  115. package/styles/_checkbox.css.js.map +1 -0
  116. package/styles/_tokens.css.js +3 -0
  117. package/styles/_tokens.css.js.map +1 -0
  118. package/styles/body-cell/body-cell.css.js +1 -1
  119. package/styles/body-cell/body-cell.css.js.map +1 -1
  120. package/styles/body-cell/cell-renderers.css.js +3 -0
  121. package/styles/body-cell/cell-renderers.css.js.map +1 -0
  122. package/styles/body-row/body-row.css.js +1 -1
  123. package/styles/body-row/body-row.css.js.map +1 -1
  124. package/styles/filter-row/filter-row.css.js +1 -1
  125. package/styles/filter-row/filter-row.css.js.map +1 -1
  126. package/styles/grid/_grid.base.css.js +1 -1
  127. package/styles/grid/_grid.base.css.js.map +1 -1
  128. package/styles/grid/grid.css.js +3 -0
  129. package/styles/grid/grid.css.js.map +1 -0
  130. package/styles/header-cell/header-cell.css.js +1 -1
  131. package/styles/header-cell/header-cell.css.js.map +1 -1
  132. package/styles/header-row/header-row.base.css.js +1 -1
  133. package/styles/header-row/header-row.base.css.js.map +1 -1
  134. package/styles/paginator/paginator.css.js +1 -1
  135. package/styles/paginator/paginator.css.js.map +1 -1
  136. package/styles/toolbar/toolbar.css.js +1 -1
  137. package/styles/toolbar/toolbar.css.js.map +1 -1
  138. package/docs/interfaces/XLSXExportOptions.html +0 -17
  139. package/docs/media/publish.yml +0 -111
  140. package/internal/theming.d.ts +0 -34
  141. package/internal/theming.js +0 -123
  142. package/internal/theming.js.map +0 -1
  143. package/internal/xlsx.d.ts +0 -22
  144. package/internal/xlsx.js +0 -228
  145. package/internal/xlsx.js.map +0 -1
  146. package/styles/grid/themes/light/grid.bootstrap.css.js +0 -3
  147. package/styles/grid/themes/light/grid.bootstrap.css.js.map +0 -1
  148. package/styles/grid/themes/light/grid.fluent.css.js +0 -3
  149. package/styles/grid/themes/light/grid.fluent.css.js.map +0 -1
  150. package/styles/grid/themes/light/grid.indigo.css.js +0 -3
  151. package/styles/grid/themes/light/grid.indigo.css.js.map +0 -1
  152. package/styles/grid/themes/light/grid.material.css.js +0 -3
  153. package/styles/grid/themes/light/grid.material.css.js.map +0 -1
  154. /package/styles/{grid/themes/light/grid.bootstrap.css.d.ts → _checkbox.css.d.ts} +0 -0
  155. /package/styles/{grid/themes/light/grid.fluent.css.d.ts → _tokens.css.d.ts} +0 -0
  156. /package/styles/{grid/themes/light/grid.indigo.css.d.ts → body-cell/cell-renderers.css.d.ts} +0 -0
  157. /package/styles/grid/{themes/light/grid.material.css.d.ts → grid.css.d.ts} +0 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,51 @@
1
+ # Changelog — apex-grid
2
+
3
+ All notable changes to the `apex-grid` (community) package are documented here.
4
+ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
5
+ and the format is based on [Keep a Changelog](https://keepachangelog.com/).
6
+
7
+ ## [3.0.1] — unreleased
8
+
9
+ Documentation-only patch (no runtime or API changes).
10
+
11
+ ### Documentation
12
+ - Documented the `--ag-grid-shadow` theming hook and the flat-by-default grid
13
+ edge (1px hairline ring; opt back into the elevated card with
14
+ `--ag-grid-shadow: var(--ag-shadow-card)`, or remove it with `none`).
15
+ - Added `@cssprop` JSDoc for the public `--ag-*` design tokens (incl.
16
+ `--ag-grid-shadow`) and a `@csspart` entry on the grid root, so the generated
17
+ Custom Elements Manifest / API reference list the theming surface.
18
+ - Completed the class `@fires` list — added the row- and tree-expansion events
19
+ (`rowExpanding`, `rowExpanded`, `treeRowExpanding`, `treeRowExpanded`) and
20
+ attached the missing `rowSelecting` event description.
21
+ - Corrected the stale "getting started" block in the `ApexGrid` JSDoc: theming
22
+ is via `--ag-*` CSS custom properties (no `configureTheme()` / theme-CSS
23
+ import required).
24
+ - Fixed an incorrect package name (`@apexcharts/grid-enterprise` →
25
+ `apex-grid-enterprise`) in export JSDoc.
26
+
27
+ ## [3.0.0] — 2026-06-09
28
+
29
+ ### Changed
30
+ - **BREAKING: Excel (XLSX) export removed from core.** It now lives in
31
+ [`apex-grid-enterprise`](https://www.npmjs.com/package/apex-grid-enterprise).
32
+ Core keeps **CSV export** (`exportToCSV`). The toolbar export menu is now
33
+ driven by a generic seam — `exportFormats` getter + `exportAs(formatId, opts)`
34
+ — so derived grids can add formats. Migrate `grid.exportToXLSX(...)` calls by
35
+ switching to `<apex-grid-enterprise>` (see its README).
36
+ - **Theming is now CSS-variable based.** The grid styles itself out of the box
37
+ through `--ag-*` custom properties — no theme import or `configureTheme()`
38
+ call is required. When `igniteui-webcomponents` is present, brand tokens
39
+ auto-tint from its palette.
40
+ - **Neutral restyle**: grayscale chrome with brand color reserved for state and
41
+ accents.
42
+ - **Flat grid edge by default.** The host no longer paints a heavy floating-card
43
+ shadow; it shows a flat 1px hairline edge. Restore the prior look with
44
+ `--ag-grid-shadow: var(--ag-shadow-card)`.
45
+
46
+ ### Project
47
+ - Repository converted to an npm-workspaces monorepo; this package publishes
48
+ from `packages/core`.
49
+
50
+ [3.0.1]: https://github.com/apexcharts/apex-grid/releases
51
+ [3.0.0]: https://github.com/apexcharts/apex-grid/releases
package/README.md CHANGED
@@ -19,10 +19,10 @@ A Lit-based, framework-agnostic web component data grid. Ships as a single custo
19
19
  - **Row selection** — single or multiple, optional checkbox column, full programmatic API.
20
20
  - **Row expansion (master-detail)** — opt-in chevron column with a `detailTemplate`.
21
21
  - **Tree data (nested rows)** — AG Grid–style `getDataPath` pattern over a flat array.
22
- - **CSV / XLSX export** — programmatic methods plus an optional toolbar dropdown.
22
+ - **CSV export** — programmatic method plus an optional toolbar dropdown. (Excel/XLSX export is in `apex-grid-enterprise`.)
23
23
  - **Toolbar** — opt-in `<apex-grid-toolbar>` with debounced quick filter and export menu.
24
24
  - **Templating** — slot-based templates for cells, headers, editors, and detail panels.
25
- - **Theming** — Bootstrap / Fluent / Indigo / Material themes via `igniteui-webcomponents`, with light and dark variants.
25
+ - **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.
26
26
  - **Accessibility** — WCAG 2.2 AA semantics (`role="grid"` / `role="treegrid"`, `aria-rowcount`, `aria-colcount`, focus + keyboard navigation).
27
27
  - **Provenance-signed npm releases** with OIDC trusted publishing.
28
28
 
@@ -34,12 +34,11 @@ A Lit-based, framework-agnostic web component data grid. Ships as a single custo
34
34
 
35
35
  ```ts
36
36
  import { setup } from 'apex-grid';
37
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
38
37
 
39
- setup({ theme: 'bootstrap' });
38
+ setup();
40
39
  ```
41
40
 
42
- 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.
41
+ 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.
43
42
 
44
43
  ### Render the grid
45
44
 
@@ -105,18 +104,29 @@ ApexGrid.register();
105
104
 
106
105
  Without this, `<apex-grid>` is an inert unknown element.
107
106
 
108
- ### 3. Load a theme
107
+ ### 3. (Optional) Customize the look
109
108
 
110
- The grid's filter dropdowns and sort indicators come from `igniteui-webcomponents`. Both the CSS import **and** the `configureTheme()` call are required:
109
+ 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:
111
110
 
112
- ```ts
113
- import { configureTheme } from 'igniteui-webcomponents';
114
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
111
+ ```css
112
+ apex-grid {
113
+ --ag-brand: #7c3aed; /* selection, focus, accents */
114
+ --ag-brand-strong: #6d28d9; /* hover / pressed */
115
+ --ag-radius: 12px; /* outer card radius */
116
+ --ag-row-h: 40px; /* row height */
117
+ }
118
+ ```
115
119
 
116
- configureTheme('bootstrap'); // 'bootstrap' | 'material' | 'fluent' | 'indigo'
120
+ See [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full token list (brand, surfaces, text, semantic state colors, typography, spacing, motion).
121
+
122
+ **Grid edge / shadow.** By default the grid shows a flat 1px hairline edge (no drop shadow). Control it with the `--ag-grid-shadow` hook — this is an opt-in override, not one of the `_tokens.scss` defaults:
123
+
124
+ ```css
125
+ apex-grid { --ag-grid-shadow: var(--ag-shadow-card); } /* elevated floating-card look */
126
+ apex-grid { --ag-grid-shadow: none; } /* remove the edge entirely */
117
127
  ```
118
128
 
119
- For dark mode, swap `light` → `dark` in the import path. The name passed to `configureTheme()` must match the imported CSS file.
129
+ If you embed the grid alongside `igniteui-webcomponents`, the brand tokens automatically re-tint from the igniteui palette (`--ig-primary-500`) — no configuration needed.
120
130
 
121
131
  ### 4. Size the host
122
132
 
@@ -136,7 +146,7 @@ apex-grid {
136
146
 
137
147
  ### What success looks like
138
148
 
139
- When all four steps are in place you should see:
149
+ With the element registered and the host sized, you should see:
140
150
 
141
151
  - **Visible borders** between rows and columns.
142
152
  - **Sort arrows** (↕) next to each header when `sort: true`.
@@ -148,7 +158,7 @@ When all four steps are in place you should see:
148
158
 
149
159
  | What you see | Likely cause |
150
160
  |---|---|
151
- | Bare table, no borders, no filter UI | Step 3 — theme CSS not imported or `configureTheme()` not called |
161
+ | Want a different look / brand color | Step 3 — override the `--ag-*` CSS variables |
152
162
  | 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) |
153
163
  | `<apex-grid>` blank tag in DOM | Step 2 — element not registered |
154
164
  | 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 +339,7 @@ await grid.expandAllTreeRows();
329
339
 
330
340
  Methods: `toggleTreeRow`, `expandTreeRow`, `collapseTreeRow`, `expandAllTreeRows`, `collapseAllTreeRows`, `isTreeRowExpanded`. Events: `treeRowExpanding` (cancellable), `treeRowExpanded`. When tree mode is active, the host element advertises `role="treegrid"`.
331
341
 
332
- ### CSV / XLSX export
342
+ ### CSV export
333
343
 
334
344
  Programmatic:
335
345
 
@@ -337,11 +347,11 @@ Programmatic:
337
347
  grid.exportToCSV(); // downloads data.csv
338
348
  grid.exportToCSV({ filename: 'users', source: 'selected' });
339
349
  const text = grid.exportToCSV({ filename: '' }); // no download, returns the string
340
-
341
- grid.exportToXLSX({ filename: 'users', sheetName: 'Users' });
342
350
  ```
343
351
 
344
- `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.
352
+ `source` can be `'view'` (default — post-filter/post-sort), `'page'`, `'selected'`, or `'all'`. Per-column opt-out: `{ key: 'secret', exportable: false }`.
353
+
354
+ > **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.
345
355
 
346
356
  Toolbar dropdown:
347
357
 
@@ -349,7 +359,7 @@ Toolbar dropdown:
349
359
  <apex-grid show-export></apex-grid>
350
360
  ```
351
361
 
352
- 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`.
362
+ 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`.
353
363
 
354
364
  ### Toolbar
355
365
 
@@ -370,7 +380,7 @@ Search input has a `debounce` attribute (default `200`ms).
370
380
 
371
381
  ### Theming
372
382
 
373
- Built-in themes: `bootstrap`, `material`, `fluent`, `indigo` — each with `light` and `dark` variants. Switch at runtime via `configureTheme(name)`.
383
+ 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.
374
384
 
375
385
  Style with CSS parts on the grid, paginator, and toolbar:
376
386
 
@@ -446,7 +456,7 @@ toggleTreeRow(row); expandTreeRow(row); collapseTreeRow(row)
446
456
  expandAllTreeRows(); collapseAllTreeRows(); isTreeRowExpanded(row)
447
457
 
448
458
  exportToCSV(options?): string
449
- exportToXLSX(options?): Uint8Array
459
+ exportAs(formatId, options?): void // toolbar dispatch; 'csv' (community), 'xlsx' (enterprise)
450
460
  ```
451
461
 
452
462
  ### Events
@@ -523,4 +533,4 @@ Any push whose head commit does not start with `release:` is a no-op for the wor
523
533
 
524
534
  ## License
525
535
 
526
- See [LICENSE.md](LICENSE.md).
536
+ See [LICENSE](LICENSE).
@@ -3,7 +3,7 @@ import { nothing } from 'lit';
3
3
  import { DataOperationsController } from '../controllers/data-operation.js';
4
4
  import { GridDOMController } from '../controllers/dom.js';
5
5
  import { StateController } from '../controllers/state.js';
6
- import { type CSVExportOptions, type XLSXExportOptions } from '../internal/export.js';
6
+ import { type CSVExportOptions, type ExportFormat, type ExportOptions } from '../internal/export.js';
7
7
  import { EventEmitterBase } from '../internal/mixins/event-emitter.js';
8
8
  import type { ColumnConfiguration, DataPipelineConfiguration, GridEditingConfiguration, GridExpansionConfiguration, GridSelectionConfiguration, GridSortConfiguration, GridTreeConfiguration, Keys, PaginationConfiguration, PaginationState, PinPosition } from '../internal/types.js';
9
9
  import type { FilterExpression } from '../operations/filter/types.js';
@@ -463,16 +463,6 @@ export interface ApexGridEventMap<T extends object> {
463
463
  * @event
464
464
  */
465
465
  rowEditEnded: CustomEvent<ApexRowEditEndedEvent>;
466
- /**
467
- * Emitted before the row selection set changes.
468
- *
469
- * @remarks
470
- * Cancellable — calling `preventDefault()` aborts the selection change.
471
- * Fires for every selection-mutating call (toggle, range select, select-all,
472
- * programmatic `selectedRows = ...`).
473
- *
474
- * @event
475
- */
476
466
  /**
477
467
  * Emitted before the tree-row expansion set changes.
478
468
  *
@@ -507,6 +497,16 @@ export interface ApexGridEventMap<T extends object> {
507
497
  * @event
508
498
  */
509
499
  rowExpanded: CustomEvent<ApexRowExpandedEvent<T>>;
500
+ /**
501
+ * Emitted before the row selection set changes.
502
+ *
503
+ * @remarks
504
+ * Cancellable — calling `preventDefault()` aborts the selection change.
505
+ * Fires for every selection-mutating call (toggle, range select, select-all,
506
+ * programmatic `selectedRows = ...`).
507
+ *
508
+ * @event
509
+ */
510
510
  rowSelecting: CustomEvent<ApexRowSelectingEvent<T>>;
511
511
  /**
512
512
  * Emitted after a row-selection change has been applied.
@@ -522,18 +522,18 @@ export interface ApexGridEventMap<T extends object> {
522
522
  * the ability to template cells and headers and column hiding.
523
523
  *
524
524
  * @remarks
525
- * A working, styled grid requires four setup steps:
525
+ * A working, styled grid requires three things:
526
526
  * 1. Register the element: `import 'apex-grid/define'` (or `ApexGrid.register()`).
527
- * 2. Configure an Ignite UI theme + import the matching CSS, e.g.
528
- * `import { configureTheme } from 'igniteui-webcomponents';`
529
- * `import 'igniteui-webcomponents/themes/light/bootstrap.css';`
530
- * `configureTheme('bootstrap');`
531
- * 3. Give the host element a bounded height, e.g. `apex-grid { height: 480px }` —
527
+ * 2. Give the host element a bounded height, e.g. `apex-grid { height: 480px }` —
532
528
  * the virtualizer collapses without one.
533
- * 4. Do NOT set `display` on the host — the component declares `:host { display: grid }`
529
+ * 3. Do NOT set `display` on the host — the component declares `:host { display: grid }`
534
530
  * internally and any override breaks the track layout.
535
531
  *
536
- * See the README "Getting Started" section for the full example.
532
+ * The grid is styled out of the box through `--ag-*` CSS custom properties —
533
+ * there is no theme to import and no `configureTheme()` call. Override `--ag-*`
534
+ * tokens on the host (or any ancestor) to rebrand; when `igniteui-webcomponents`
535
+ * is present, the brand tokens auto-tint from its palette. See the README
536
+ * "Getting Started" and "Theming" sections for the full example and token list.
537
537
  *
538
538
  * @element apex-grid
539
539
  *
@@ -555,10 +555,35 @@ export interface ApexGridEventMap<T extends object> {
555
555
  * @fires rowEditEnded - Emitted when a row leaves edit mode (row mode only).
556
556
  * @fires rowSelecting - Cancellable. Emitted before a selection-set change is applied.
557
557
  * @fires rowSelected - Emitted after a selection-set change has been applied.
558
+ * @fires rowExpanding - Cancellable. Emitted before the row-expansion set changes (master-detail).
559
+ * @fires rowExpanded - Emitted after a row-expansion change has been applied.
560
+ * @fires treeRowExpanding - Cancellable. Emitted before a tree-row expansion change (tree mode).
561
+ * @fires treeRowExpanded - Emitted after a tree-row expansion change has been applied.
558
562
  *
563
+ * @csspart live-region - Visually-hidden ARIA live region used for screen-reader announcements.
564
+ *
565
+ * @cssprop [--ag-brand] - Brand color for selection, focus rings, and accents. Auto-tints from `--ig-primary-500` when igniteui is present.
566
+ * @cssprop [--ag-brand-strong] - Brand color for hover / pressed states.
567
+ * @cssprop [--ag-grid-shadow] - Grid edge/shadow override. Default is a flat 1px hairline edge; set to `var(--ag-shadow-card)` for the elevated card look, or `none` to remove it.
568
+ * @cssprop [--ag-surface] - Grid card background (must be opaque).
569
+ * @cssprop [--ag-surface-alt] - Alternating row tint.
570
+ * @cssprop [--ag-surface-elevated] - Header background.
571
+ * @cssprop [--ag-hairline] - Header / structural gridline color.
572
+ * @cssprop [--ag-border] - Row separator color.
573
+ * @cssprop [--ag-text] - Primary text color.
574
+ * @cssprop [--ag-text-body] - Row text color.
575
+ * @cssprop [--ag-text-muted] - Muted text (roles, labels).
576
+ * @cssprop [--ag-row-hover] - Row hover wash.
577
+ * @cssprop [--ag-row-h] - Row height.
578
+ * @cssprop [--ag-header-h] - Header height.
579
+ * @cssprop [--ag-radius] - Outer card corner radius.
580
+ * @cssprop [--ag-font] - Grid font family.
581
+ * @cssprop [--ag-fs-cell] - Cell font size.
582
+ *
583
+ * @see {@link https://github.com/apexcharts/apex-grid/blob/main/packages/core/src/styles/_tokens.scss | _tokens.scss} for the complete `--ag-*` token list.
559
584
  */
560
585
  export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGridEventMap<T>> {
561
- static get tagName(): "apex-grid";
586
+ static get tagName(): string;
562
587
  static styles: import("lit").CSSResult;
563
588
  /**
564
589
  * Registers `<apex-grid>` and its internal dependencies with the custom-element
@@ -574,6 +599,14 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
574
599
  protected stateController: StateController<T>;
575
600
  protected DOM: GridDOMController<T>;
576
601
  protected dataController: DataOperationsController<T>;
602
+ /**
603
+ * Builds the grid's {@link StateController}. This is the single construction
604
+ * site for `stateController` — overriding it (rather than re-declaring the
605
+ * field) is the supported seam for derived grids to inject optional
606
+ * {@link GridFeatureModule}s while preserving field-initializer ordering.
607
+ * The community grid registers no extra modules.
608
+ */
609
+ protected createStateController(): StateController<T>;
577
610
  protected stateProvider: ContextProvider<{
578
611
  __context__: StateController<any>;
579
612
  }, this>;
@@ -664,9 +697,9 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
664
697
  *
665
698
  * @remarks
666
699
  * When `true`, the toolbar shows a download button on the trailing side;
667
- * clicking it opens a menu with "Export CSV" and "Export XLSX" entries
668
- * that call {@link ApexGrid.exportToCSV} and {@link ApexGrid.exportToXLSX}
669
- * respectively. Both methods remain callable programmatically regardless
700
+ * clicking it opens a menu with one entry per {@link ApexGrid.exportFormats}
701
+ * (CSV in the community grid) that calls {@link ApexGrid.exportAs}.
702
+ * {@link ApexGrid.exportToCSV} remains callable programmatically regardless
670
703
  * of this flag.
671
704
  *
672
705
  * @attr show-export
@@ -921,7 +954,6 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
921
954
  protected pipeline(): Promise<void>;
922
955
  protected paginationChanged(): void;
923
956
  protected quickFilterChanged(): void;
924
- constructor();
925
957
  protected updated(): void;
926
958
  protected firstUpdated(): void;
927
959
  /**
@@ -1102,24 +1134,22 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
1102
1134
  */
1103
1135
  exportToCSV(options?: CSVExportOptions<T>): string;
1104
1136
  /**
1105
- * Exports the current grid contents as an `.xlsx` workbook and (in a browser
1106
- * context) triggers a download.
1137
+ * The export formats offered in the toolbar's export menu, in order.
1107
1138
  *
1108
1139
  * @remarks
1109
- * Produces a single-sheet workbook with a bold header row. Numbers, booleans
1110
- * and `Date` values keep their native cell type in Excel; everything else is
1111
- * written as inline strings. Sharing the same `source` / `columns` /
1112
- * `formatter` options as {@link ApexGrid.exportToCSV}, plus an optional
1113
- * `sheetName`. Pass `filename: ''` to skip the download and only receive
1114
- * the bytes back.
1115
- *
1116
- * @example
1117
- * ```ts
1118
- * grid.exportToXLSX();
1119
- * grid.exportToXLSX({ filename: 'users', sheetName: 'Users' });
1120
- * ```
1140
+ * The community grid offers CSV only. This is the seam derived grids use to
1141
+ * contribute more formats: `@apexcharts/grid-enterprise` overrides it to add
1142
+ * `'xlsx'`. The toolbar renders one menu item per entry and dispatches the
1143
+ * chosen id to {@link ApexGrid.exportAs}.
1144
+ */
1145
+ get exportFormats(): ReadonlyArray<ExportFormat>;
1146
+ /**
1147
+ * Exports the grid in the given format (one of {@link ApexGrid.exportFormats}).
1148
+ * Called by the toolbar's export menu. The community grid handles `'csv'`;
1149
+ * derived grids override to handle additional formats, delegating to `super`
1150
+ * for the ones they don't add.
1121
1151
  */
1122
- exportToXLSX(options?: XLSXExportOptions<T>): Uint8Array;
1152
+ exportAs(formatId: string, options?: ExportOptions<T>): void;
1123
1153
  /**
1124
1154
  * Moves a column relative to another column.
1125
1155
  *
@@ -1168,6 +1198,5 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
1168
1198
  }
1169
1199
  declare global {
1170
1200
  interface HTMLElementTagNameMap {
1171
- [ApexGrid.tagName]: ApexGrid<object>;
1172
1201
  }
1173
1202
  }
@@ -12,18 +12,13 @@ import { DataOperationsController } from '../controllers/data-operation.js';
12
12
  import { GridDOMController } from '../controllers/dom.js';
13
13
  import { gridStateContext, StateController } from '../controllers/state.js';
14
14
  import { DEFAULT_COLUMN_CONFIG, PIPELINE } from '../internal/constants.js';
15
- import { buildCSV, downloadBlob, getColumnLabel, resolveExportColumns, resolveExportRows, resolveExportValue, } from '../internal/export.js';
15
+ import { buildCSV, downloadBlob, } from '../internal/export.js';
16
16
  import { EventEmitterBase } from '../internal/mixins/event-emitter.js';
17
17
  import { registerComponent } from '../internal/register.js';
18
18
  import { GRID_TAG } from '../internal/tags.js';
19
- import { addThemingController } from '../internal/theming.js';
20
19
  import { asArray, autoGenerateColumns, getDisplayColumns, getFilterOperandsFor, } from '../internal/utils.js';
21
20
  import { watch } from '../internal/watch.js';
22
- import { buildXLSX } from '../internal/xlsx.js';
23
- import { styles as bootstrap } from '../styles/grid/themes/light/grid.bootstrap.css.js';
24
- import { styles as fluent } from '../styles/grid/themes/light/grid.fluent.css.js';
25
- import { styles as indigo } from '../styles/grid/themes/light/grid.indigo.css.js';
26
- import { styles as material } from '../styles/grid/themes/light/grid.material.css.js';
21
+ import { styles as gridStyles } from '../styles/grid/grid.css.js';
27
22
  import ApexGridCell from './cell.js';
28
23
  import ApexFilterRow from './filter-row.js';
29
24
  import ApexGridHeaderRow from './header-row.js';
@@ -32,13 +27,38 @@ import ApexGridRow from './row.js';
32
27
  import ApexGridToolbar from './toolbar.js';
33
28
  import ApexVirtualizer from './virtualizer.js';
34
29
  export class ApexGrid extends EventEmitterBase {
30
+ constructor() {
31
+ super(...arguments);
32
+ this.stateController = this.createStateController();
33
+ this.DOM = new GridDOMController(this, this.stateController);
34
+ this.dataController = new DataOperationsController(this);
35
+ this.stateProvider = new ContextProvider(this, {
36
+ context: gridStateContext,
37
+ initialValue: this.stateController,
38
+ });
39
+ this.dataState = [];
40
+ this.columns = [];
41
+ this.data = [];
42
+ this.autoGenerate = false;
43
+ this.sortConfiguration = {
44
+ multiple: true,
45
+ triState: true,
46
+ };
47
+ this.quickFilter = '';
48
+ this.showQuickFilter = false;
49
+ this.showExport = false;
50
+ this.columnReordering = false;
51
+ }
35
52
  static get tagName() {
36
53
  return GRID_TAG;
37
54
  }
38
- static { this.styles = bootstrap; }
55
+ static { this.styles = gridStyles; }
39
56
  static register() {
40
57
  registerComponent(ApexGrid, ApexVirtualizer, ApexGridRow, ApexGridHeaderRow, ApexFilterRow, ApexGridPaginator, ApexGridToolbar);
41
58
  }
59
+ createStateController() {
60
+ return new StateController(this);
61
+ }
42
62
  get selectedRows() {
43
63
  return this.stateController.selection.selectedRows();
44
64
  }
@@ -205,32 +225,6 @@ export class ApexGrid extends EventEmitterBase {
205
225
  this.pipeline();
206
226
  }
207
227
  }
208
- constructor() {
209
- super();
210
- this.stateController = new StateController(this);
211
- this.DOM = new GridDOMController(this, this.stateController);
212
- this.dataController = new DataOperationsController(this);
213
- this.stateProvider = new ContextProvider(this, {
214
- context: gridStateContext,
215
- initialValue: this.stateController,
216
- });
217
- this.dataState = [];
218
- this.columns = [];
219
- this.data = [];
220
- this.autoGenerate = false;
221
- this.sortConfiguration = {
222
- multiple: true,
223
- triState: true,
224
- };
225
- this.quickFilter = '';
226
- this.showQuickFilter = false;
227
- this.showExport = false;
228
- this.columnReordering = false;
229
- addThemingController(this, {
230
- light: { bootstrap, material, fluent, indigo },
231
- dark: { bootstrap, material, fluent, indigo },
232
- });
233
- }
234
228
  updated() {
235
229
  this.setAttribute('role', this.stateController.tree.enabled ? 'treegrid' : 'grid');
236
230
  const hasFilter = this.columns.some((column) => column.filter);
@@ -384,25 +378,13 @@ export class ApexGrid extends EventEmitterBase {
384
378
  }
385
379
  return csv;
386
380
  }
387
- exportToXLSX(options = {}) {
388
- const columns = resolveExportColumns(this, options);
389
- const rows = resolveExportRows(this, options.source);
390
- const includeHeader = options.includeHeader ?? true;
391
- const sheet = {
392
- name: options.sheetName ?? 'Sheet1',
393
- headers: includeHeader ? columns.map((column) => getColumnLabel(column)) : [],
394
- rows: rows.map((row) => columns.map((column) => resolveExportValue(column, row, options))),
395
- };
396
- const bytes = buildXLSX(sheet);
397
- const filename = options.filename;
398
- const mime = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
399
- if (filename) {
400
- downloadBlob(`${filename}.xlsx`, bytes, mime);
401
- }
402
- else if (filename === undefined) {
403
- downloadBlob('data.xlsx', bytes, mime);
381
+ get exportFormats() {
382
+ return [{ id: 'csv', label: 'Export CSV' }];
383
+ }
384
+ exportAs(formatId, options = {}) {
385
+ if (formatId === 'csv') {
386
+ this.exportToCSV(options);
404
387
  }
405
- return bytes;
406
388
  }
407
389
  async moveColumn(fromKey, toKey, position = 'before') {
408
390
  if (fromKey === toKey)