ngx-devextreme-zoneless 2.0.0 → 3.0.0

package/README.md

@@ -2,11 +2,11 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Context7](https://img.shields.io/badge/Context7-Indexed-3B82F6)](https://context7.com/caffeinatedcoder/ngx-devextreme-zoneless)
-[![NPM](https://img.shields.io/badge/NPM-2.0.0-3B82F6)](https://www.npmjs.com/package/ngx-devextreme-zoneless)
+[![NPM](https://img.shields.io/npm/v/ngx-devextreme-zoneless?label=NPM&color=3B82F6)](https://www.npmjs.com/package/ngx-devextreme-zoneless)
 
-<p align="center">
-  <img width="400" height="400" align="center" alt="ngx-devextreme-zoneless-logo" src="package-logo.png" />
-</p>
+> **Independent community project.** DevExtreme is a registered trademark of
+> Developer Express Inc. This library is not affiliated with, endorsed by, or
+> sponsored by Developer Express Inc.
 
 Strongly-typed **signal & zoneless change-detection adapters** for
 [DevExtreme Angular](https://js.devexpress.com/Angular/) components.
@@ -24,16 +24,18 @@ Angular signal  ──effect──▶  widget option / method
 Angular signal  ◀──set────  widget event (optionChanged, selectionChanged, …)
 ```
 
-- **Angular** ≥ 20 (built and verified against Angular 22, zoneless by default)
-- **DevExtreme / devextreme-angular** ≥ 25.1 (built and verified against 26.1)
+- **Angular** ≥ 22.1 < 23 (built and verified against Angular 22.1.3, zoneless by default)
+- **DevExtreme / devextreme-angular** ≥ 26.1 (built and verified against 26.1.4)
 - **TypeScript** 6.0, `strict`, zero `any` in the public surface
 
-> **Why this library exists:** DevExpress officially still requires zone.js —
-> zoneless support for `devextreme-angular` has not been started and has no
-> ETA. Running DevExtreme zoneless is therefore outside the vendor-supported
-> configuration, and this library is the bridge. Its CI (a Playwright suite
-> driving every binding through a real zoneless app on every push) is the
-> compatibility net the vendor does not provide.
+> **Why this library exists:** DevExpress officially still requires zone.js.
+> As of 2026-08-10 DevExpress is *"considering zoneless Angular support for a
+> future release"* (ticket T1328486) — no ETA, and that thread is where an
+> invite to test will be announced if a release is set. Running DevExtreme
+> zoneless is therefore outside the vendor-supported configuration, and this
+> library is the bridge. Its CI (a Playwright suite driving every binding
+> through a real zoneless app on every push) is the compatibility net the
+> vendor does not provide.
 
 Everything is *derived from DevExtreme's own `Properties` declarations* via
 template-literal and conditional types — option names, option value types and
@@ -78,315 +80,62 @@ Or import everything at once with `DX_SIGNAL_DIRECTIVES` (also available per
 family: `DX_VALUE_DIRECTIVES`, `DX_NAVIGATION_DIRECTIVES`,
 `DX_VISIBLE_DIRECTIVES`, `DX_DATA_DIRECTIVES`, `DX_VISUALIZATION_DIRECTIVES`).
 
-Components without a dedicated directive (PivotGrid, Sortable, Menu, …) are
-covered too — see [Composition API](#composition-api): the same engine works
-with **any** option and event of **any** DevExtreme component, fully typed.
-
-## Directive catalog
-
-### Editors — `[(dxValue)]`
-
-Every value editor gets a `[(dxValue)]` two-way model plus `dxValueDebounce`
-(ms, widget → signal direction) and `dxValueEqual` (custom comparer) inputs.
-
-| Component | Model type |
-|---|---|
-| `dx-text-box`, `dx-text-area`, `dx-html-editor` | `string` |
-| `dx-number-box` | `number \| null` |
-| `dx-check-box` | `boolean \| null` |
-| `dx-switch` | `boolean` |
-| `dx-date-box` | `Date \| number \| string \| null` |
-| `dx-date-range-box` | `readonly [start: DxDateValue \| null, end: DxDateValue \| null]` |
-| `dx-calendar` | `DxDateValue \| readonly DxDateValue[] \| null` |
-| `dx-color-box`, `dx-autocomplete` | `string \| null` |
-| `dx-slider` | `number` |
-| `dx-range-slider` | `readonly [start: number, end: number]` |
-| `dx-select-box`, `dx-lookup`, `dx-drop-down-box`, `dx-radio-group` | generic `TValue` — inferred from your signal |
-| `dx-tag-box` | generic `readonly TKey[]` |
-| `dx-filter-builder` | `DxFilterExpression \| null` |
-| `dx-range-selector` | DevExtreme's declared scale range type |
-
-Where DevExtreme declares `value?: any` (SelectBox & friends) the directive is
-**generic** instead, so `[(dxValue)]="status"` with a
-`signal<OrderStatus | null>` is checked end-to-end.
-
-### Selection & data
-
-| Selector | Model |
-|---|---|
-| `dx-data-grid[dxSelectedRowKeys]`, `dx-tree-list[dxSelectedRowKeys]` | `readonly TKey[]` |
-| `dx-list[dxSelectedItemKeys]` | `readonly TKey[]` |
-| `dx-tree-view[dxSelectedNodeKeys]` | `readonly TKey[]` (method-based: `getSelectedNodeKeys` / `selectItem`) |
-| `dx-gantt[dxSelectedRowKey]` | `TKey \| null` |
-| `dx-scheduler[dxCurrentDate]` | `Date \| number \| string` |
-| `dx-scheduler[dxCurrentView]` | DevExtreme's view union |
-| `dx-form[dxFormData]` | generic `TFormData` — emits a fresh shallow copy per field edit |
-
-### Grid state (dx-data-grid and dx-tree-list)
-
-| Selector | Model |
-|---|---|
-| `[dxFocusedRowKey]` | `TKey \| null` (requires `focusedRowEnabled`; `null` clears) |
-| `[dxFilterValue]` | `DxFilterExpression \| null` |
-| `[dxPageIndex]`, `[dxPageSize]` | `number` (method-based — paging lives under the nested `paging` option) |
-| `[dxGridState]` | `DxGridState \| null \| undefined` — the full layout state (`state()` / `stateStoring`) |
-
-`[(dxGridState)]` is the layout-persistence story: bind it to a signal you
-persist wherever you like. `undefined` pulls the current state on attach,
-a saved state object restores the layout, `null` resets to defaults. Widget →
-signal reads are debounced (`dxGridStateDebounce`, default 100 ms).
-
-### Navigation & overlays
-
-| Selector | Model |
-|---|---|
-| `dx-tabs`, `dx-tab-panel`, `dx-accordion`, `dx-gallery` + `[dxSelectedIndex]` | `number` |
-| `dx-drawer[dxOpened]` | `boolean` |
-| `dx-popup`, `dx-popover`, `dx-tooltip`, `dx-toast`, `dx-load-panel`, `dx-action-sheet` + `[dxVisible]` | `boolean` |
-
-`[(dxVisible)]` tracks *every* way an overlay can close (shading click, escape,
-close button, API) — the classic zoneless pain point.
-
-### Visualization
-
-| Selector | Model |
-|---|---|
-| `dx-chart[dxSelectedPoints]`, `dx-pie-chart[dxSelectedPoints]` | `readonly DxChartSelectedPoint[]` |
-
-Chart selection is method-based; selected points are exposed as serializable
-`{ seriesName, argument, value }` descriptors that can be stored and restored.
-DevExtreme charts do not select points on click by themselves (their demos
-wire `onPointClick: e => e.target.select()` manually), so these directives
-toggle the clicked point's selection by default — opt out with
-`[dxPointClickToggle]="false"` if you want to handle `onPointClick` yourself.
-
-## Composition API
-
-The directives are sugar. The same engine is available as injection-context
-functions and covers **every option and event of every DevExtreme component**,
-fully typed:
-
-```ts
-import {
-  bindDxOption, dxOptionSignal, dxEventSignal, injectDxInstance,
-} from 'ngx-devextreme-zoneless';
-
-@Component({ /* ... */ })
-export class MyComponent {
-  // On the same element (inside a directive):
-  private readonly textBox = inject(DxTextBoxComponent, { self: true });
-
-  // Two-way signal for any option — names & types from DevExtreme Properties:
-  readonly placeholder = dxOptionSignal(this.textBox, 'placeholder');
-  readonly mode = dxOptionSignal(this.textBox, 'mode', { initialValue: 'search' });
-
-  // Latest payload of any widget event:
-  readonly focusOut = dxEventSignal(this.textBox, 'focusOut');
-
-  // Works with view children too (pass the viewChild signal itself):
-  private readonly grid = viewChild(DxDataGridComponent<Order, number>);
-  readonly filter = dxOptionSignal(this.grid, 'filterValue');
-
-  // Bind an existing signal to an option:
-  readonly keys = signal<number[] | undefined>([]);
-  constructor() {
-    bindDxOption(this.grid, 'selectedRowKeys', this.keys);
-  }
-
-  // The raw widget instance as a signal (undefined until created):
-  readonly widget = injectDxInstance(DxTextBoxComponent);
-
-  // Same, but for a view child — resets to undefined while the widget is
-  // gone and follows re-creation:
-  readonly gridWidget = dxInstanceSignal(this.grid);
-}
-```
-
-### Widget re-creation
-
-Composition-API bindings on a **getter host reference** (a `viewChild(...)`
-signal) survive widget re-creation: when an `@if`, a tab panel or re-created
-popup content destroys the widget and later creates a new one, the binding
-re-attaches automatically and the initial synchronization runs again — a
-signal holding state therefore **restores it into the new widget**. The
-attribute directives don't need any of this; they die and are re-created with
-their element.
-
-`onDxWidgetReady` is the underlying primitive: it fires once per widget
-instance, and its callback may return a cleanup that runs when the widget
-goes away.
-
-### Components without a dedicated directive
-
-The coverage model is simple: **a directive exists wherever a widget has
-genuine user-mutable two-way state** (value, selection, visibility, index,
-current date/view, form data, chart points). Every other component — and any
-component DevExtreme ships in the future — is still fully supported through
-the composition API, because `dxOptionSignal`, `dxEventSignal` and
-`bindDxOption` are not written against a component list: their option names,
-option value types and event payloads are computed from the `Properties`
-declaration of whatever host component you hand them. Support doesn't
-cliff-edge at the directive catalog; it just gets one notch less sugary.
-
-A few real-world cases:
-
-```ts
-// PivotGrid — no two-way options (its mutable state lives in the
-// PivotGridDataSource), but every event and option is reachable, typed:
-private readonly pivot = inject(DxPivotGridComponent, { self: true });
-readonly cellClick = dxEventSignal(this.pivot, 'cellClick');
-readonly contextMenu = dxEventSignal(this.pivot, 'contextMenuPreparing');
-```
-
-```ts
-// Scheduler beyond [(dxCurrentDate)] / [(dxCurrentView)] — appointment
-// lifecycle as signals:
-private readonly scheduler = inject(DxSchedulerComponent, { self: true });
-readonly appointmentAdded = dxEventSignal(this.scheduler, 'appointmentAdded');
-```
-
-```ts
-// Sortable (e.g. a Kanban board built from dx-sortable + lists) — purely
-// event-driven, so state stays in your signals and events drive mutations:
-private readonly sortable = viewChild(DxSortableComponent);
-readonly reorder = dxEventSignal(this.sortable, 'reorder');
-constructor() {
-  effect(() => {
-    const e = this.reorder();
-    if (e) this.cards.update((cards) => moveItem(cards, e.fromIndex, e.toIndex));
-  });
-}
-```
-
-```ts
-// Any option of any widget, two-way — e.g. Menu, ButtonGroup, Toolbar, ...:
-readonly disabled = dxOptionSignal(this.menu, 'disabled');
-```
-
-For state that is neither an option nor a single event (method-based APIs),
-implement a `DxBindingAdapter` and pass it to `bindDxState` — that is exactly
-how the chart-selection and tree-view directives are built. And if you want
-template sugar for a component we don't cover, a custom directive is ~10
-lines by extending `DxValueDirectiveBase`, `DxVisibleDirectiveBase`, etc.
-
-## Data loading (signals → DataSource)
-
-Two-way state is one half of the zoneless problem; the other half is data
-loading — DevExtreme components load through `DataSource`/stores, which know
-nothing about signals.
-
-**Array data in a signal** — `dxArrayStoreSource` wraps a
-`Signal<readonly T[]>` in a `DataSource` that reloads whenever the signal
-changes:
-
-```ts
-readonly orders = signal<readonly Order[]>([]);
-readonly ordersSource = dxArrayStoreSource(this.orders, { key: 'id' });
-// <dx-data-grid [dataSource]="ordersSource" />
-```
-
-**Remote data with signal-driven filters** — `dxReloadOn` triggers a reload
-whenever dependency signals change, so external filter state needs no
-hand-written `refresh()` plumbing:
-
-```ts
-readonly search = signal('');
-
-// e.g. a DevExtreme.AspNet.Data endpoint:
-readonly source = new DataSource({
-  store: createStore({ loadUrl: '/api/orders', key: 'id' }),
-});
-
-constructor() {
-  dxReloadOn(this.source, [this.search]);
-}
-```
-
-The target can also be a callback (`dxReloadOn(() => this.grid()?.refresh(), [deps])`)
-for anything that is not a `DataSource`.
-
-**Recipe: full remote loading state as signals.** Pair a `CustomStore` with
-signals for loading/error state — the store reads filters `untracked`, and
-`dxReloadOn` drives reloads:
-
-```ts
-readonly search = signal('');
-readonly isLoading = signal(false);
-readonly loadError = signal<unknown>(undefined);
-
-readonly source = new DataSource<Order, number>({
-  store: new CustomStore<Order, number>({
-    key: 'id',
-    loadMode: 'raw',
-    load: async () => {
-      this.isLoading.set(true);
-      try {
-        const query = untracked(this.search);
-        return await fetchOrders(query);
-      } catch (error) {
-        this.loadError.set(error);
-        throw error;
-      } finally {
-        this.isLoading.set(false);
-      }
-    },
-  }),
-});
-
-constructor() {
-  dxReloadOn(this.source, [this.search]);
-}
-```
-
-This intentionally ships as a recipe rather than API: the shape will be
-extracted from real consumer screens before it hardens into code.
-
-## Semantics
-
-- **Initial sync** (`initialSync`, default `'auto'`): the signal's value is
-  pushed into the widget on attach; if it is `undefined`, the widget's current
-  value is pulled into the signal instead.
-- **`undefined` vs `null`**: `undefined` means *absent* — a signal holding
-  `undefined` is never pushed into the widget (that is what makes `'auto'`
-  initial sync and late-created widgets work). To *clear* an option through a
-  binding, use `null`: `status.set(null)` clears a select box,
-  `status.set(undefined)` does nothing. This mirrors DevExtreme's own
-  conventions — its clearable editors write `null`, not `undefined`.
-- **Debounced typing**: DevExtreme text editors update their `value` option on
-  *blur* by default. Pair `[(dxValue)]` + `dxValueDebounce` with
-  `valueChangeEvent="input"` on the editor to get live per-keystroke updates:
-
-  ```html
-  <dx-text-box [(dxValue)]="search" [dxValueDebounce]="300" valueChangeEvent="input" />
-  ```
-
-  Without it, the binding appears to only fire on blur — that is the widget's
-  event timing, not the binding's.
-- **Echo suppression**: updates only propagate when the value *structurally*
-  changed (`Date`-aware, deep for arrays/plain objects). Override per binding
-  via `equal` / `dxValueEqual`.
-- **Debounce** applies to the widget → signal direction only, so typing into a
-  `dx-text-box` doesn't storm your `computed()` graph.
-- **Teardown** is automatic via `DestroyRef` — event handlers are detached and
-  effects destroyed when the directive/component dies.
-- **Re-attach**: with a getter host reference the binding follows widget
-  re-creation (see [Widget re-creation](#widget-re-creation)); per-widget
-  resources are disposed on each detach.
-- **Zoneless**: no `NgZone`, no `markForCheck` — signal writes are the change
-  notification.
+## Choosing your binding style
+
+Three ways to put a value on a DevExtreme editor — the classic one, and the
+two this package opens up:
+
+| | A: zone.js + Reactive Forms | B: `[(dxValue)]` | C: `[formField]` + `[dxFieldState]` |
+|---|---|---|---|
+| Change detection | zone.js (opt-in since v21) | zoneless, native | zoneless, native |
+| Vendor support | ✅ the supported config | outside support — netted by this repo's CI | same net |
+| Error display | hand-rolled per field/rule | DIY | the widget's own UI, zero template markup |
+| Schema-driven readonly/hidden/disabled | manual | — | yes, all three |
+| Value type safety | typed forms | end-to-end compile error | restored via `[dxFieldState]` |
+| Boilerplate per field | ~5–8 template lines | ~1 line | ~2 lines, flat |
+
+Use **B** for state outside a form (filters, toolbars, settings), **C** for
+forms, and **A** only where zone.js is staying anyway. Full code for all
+three, the trade-offs, and the two rules that keep them honest:
+**[Choosing your binding style](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/binding-styles.md)**.
+The smoke app renders them side by side (`npm run smoke` →
+http://localhost:4299/compare) — including the classic syntax's measured
+zoneless behaviour: field state arrives (Angular's reactive directives mark
+for check on their own); the widget state a CVA never carries is what stays
+invisible, and is what the rest of this package covers.
+
+## What is covered
+
+Two-way directives exist wherever a widget has genuine user-mutable state —
+`[(dxValue)]` on every editor, selection and grid state on the data widgets,
+`[(dxVisible)]`/`[(dxOpened)]`/`[(dxSelectedIndex)]` on overlays and
+navigation, chart point selection — each typed to the widget's real value
+type. The
+**[directive catalog](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/directives.md)**
+is the authoritative table. Components without a dedicated directive
+(PivotGrid, Sortable, Menu, …) are fully covered by the
+**[composition API](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/composition-api.md)**:
+`dxOptionSignal`, `dxEventSignal` and `bindDxOption` work with **any** option
+and event of **any** DevExtreme component, fully typed.
+
+For data, `dxArrayStoreSource` puts a signal-held array behind a `DataSource`,
+and `dxRemoteStore` wraps a server load function in `resource()` vocabulary —
+loading/error signals, cancellation, signal-driven dependencies — speaking the
+complete DevExtreme.AspNet.Data loadOptions wire protocol through your own
+`fetch`:
+**[data loading and remote data](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/remote-data.md)**.
 
 ## Entry points & tree-shaking
 
-The package ships per-family secondary entry points:
-
 ```
 ngx-devextreme-zoneless            → everything (re-exports the below)
-ngx-devextreme-zoneless/core       → engine, types, bases, data-source helpers
+ngx-devextreme-zoneless/core       → engine, types, bases, data-source/remote helpers
 ngx-devextreme-zoneless/editors    → [(dxValue)] directives
 ngx-devextreme-zoneless/navigation → [(dxSelectedIndex)], [(dxOpened)], …
 ngx-devextreme-zoneless/overlays   → [(dxVisible)] directives
 ngx-devextreme-zoneless/data       → grid/form/scheduler/tree directives
 ngx-devextreme-zoneless/visualization → chart selection, range selector
+ngx-devextreme-zoneless/forms      → [dxFieldState] (Signal Forms; NOT re-exported by the main entry)
 ```
 
 Importing from the main entry is fine: bundlers drop the families you don't
@@ -395,39 +144,29 @@ directive is asserted to contain no Gantt, Scheduler, HtmlEditor, chart or
 grid modules). Import from a family entry point when you want the split to be
 explicit.
 
-## Type helpers
-
-All building blocks are exported, e.g.:
-
-```ts
-DxHostOptionName<DxTextBoxComponent>          // 'value' | 'placeholder' | 'mode' | ...
-DxHostOptionValue<DxTextBoxComponent, 'mode'> // 'email' | 'password' | ... | undefined
-DxHostEventName<DxDataGridComponent>          // 'rowClick' | 'selectionChanged' | ...
-DxHostEventArg<DxTextBoxComponent, 'valueChanged'>
-DxHostValue<DxCheckBoxComponent>              // boolean | null
-```
-
-## Development
+## Documentation
 
-```bash
-npm run build               # ng-packagr build → dist/ (all entry points)
-npm run typecheck:examples  # strict-template check of examples/ + type contract tests
-npm run verify              # both
-npm run smoke               # runtime smoke test app on http://localhost:4299
-npm run e2e                 # Playwright suite against the smoke app
-npm run probe               # bundle tree-shaking probe (requires a prior build)
-```
-
-The smoke app ([smoke/src/smoke.component.ts](smoke/src/smoke.component.ts))
-boots with `provideZonelessChangeDetection()` — zone.js is not even installed
-in this workspace — and exercises text box, select box, check box, slider,
-tabs, grid selection/paging/focus, signal-driven data loading, popup
-visibility, chart point selection, the composition API and widget
-re-creation in a real browser. The Playwright suite
-([e2e/smoke.spec.ts](e2e/smoke.spec.ts)) asserts both directions of every
-binding against the `data-testid` readouts and runs in CI on every push.
-
-See [examples/order-dashboard.component.ts](examples/order-dashboard.component.ts)
-for a complete signal-driven dashboard and
-[examples/type-tests.ts](examples/type-tests.ts) for the compile-time contract
-tests.
+| Page | What it covers |
+|---|---|
+| **[Choosing your binding style](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/binding-styles.md)** | The same form three ways — classic zone.js, `[(dxValue)]`, Signal Forms — with syntax, boilerplate and capability compared |
+| **[Directive catalog](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/directives.md)** | Every two-way directive with its model type: editors, selection, grid state, navigation, overlays, visualization |
+| **[Signal Forms](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/signal-forms.md)** | `[dxFieldState]`: what crosses the vendor CVA, what the directive adds, why the field is named twice, debounce ownership |
+| **[Composition API](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/composition-api.md)** | `dxOptionSignal`/`dxEventSignal`/`bindDxOption` for any component, widget re-creation, custom adapters |
+| **[Data loading & remote data](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/remote-data.md)** | `dxArrayStoreSource`, `dxReloadOn`, and the `dxRemoteStore` contract: cancellation, error/retry, paging, `byKey`, `langParams` |
+| **[Binding semantics & type helpers](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/semantics.md)** | The engine contract: `undefined` vs `null`, initial sync, echo suppression, debounce, teardown, the exported type helpers |
+
+Working on the package itself:
+[development](https://github.com/CaffeinatedCoder/ngx-devextreme-zoneless/blob/main/docs/development.md)
+— builds, the smoke app's four screens, the e2e suite and the tree-shaking
+probe.
+
+## Verified, not assumed
+
+Running DevExtreme zoneless is outside the vendor-supported configuration, so
+the claim this package makes is exactly as strong as its suite: a Playwright
+run drives every binding family through a real zoneless app — both directions,
+widget re-creation, slow and failing endpoints against a wire-protocol stub —
+on every push. The compile-time surface has its own contract tests
+([examples/type-tests.ts](examples/type-tests.ts)): option names, event names
+and value types are pinned so a vendor rename fails the build instead of
+shipping.