clr-lift 21.2.0 → 21.4.0

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.
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  [![Angular](https://img.shields.io/badge/Angular-%3E%3D21.0.0-red.svg)](https://angular.dev)
11
11
  [![Clarity](https://img.shields.io/badge/Clarity-%3E%3D18.0.0-blue.svg)](https://clarity.design)
12
12
 
13
- [📖 Documentation](https://ngx-lift.netlify.app/clr-lift) • [🎮 Live Demo](https://ngx-lift.netlify.app/clr-lift) •
13
+ [📖 Documentation](https://ngx-lift.vercel.app/clr-lift) • [🎮 Live Demo](https://ngx-lift.vercel.app/clr-lift) •
14
14
  [💻 GitHub Repository](https://github.com/wghglory/ngx-lift-workspace)
15
15
 
16
16
  </div>
@@ -19,7 +19,7 @@
19
19
 
20
20
  **clr-lift** supercharges VMware's **Clarity Design System** with battle-tested enterprise primitives. It fills the gaps
21
21
  in standard Clarity by delivering flicker-free datagrid state management, reactive notification systems, async
22
- multi-step wizards, type-safe form controls, zero-config dark mode, and built-in 12+ language localization.
22
+ multi-step wizards, type-safe form controls, zero-config dark mode, and built-in localization.
23
23
 
24
24
  ```html
25
25
  <!-- Enhanced Clarity alert with automatic Error/HttpErrorResponse extraction -->
@@ -31,23 +31,79 @@ multi-step wizards, type-safe form controls, zero-config dark mode, and built-in
31
31
 
32
32
  ---
33
33
 
34
+ This README follows the main branch. Check the
35
+ [release history](https://github.com/wghglory/ngx-lift-workspace/blob/main/CHANGELOG.md) for availability in your
36
+ installed version; source changes under Unreleased are not yet on npm.
37
+
34
38
  ## ⚡ Highlights
35
39
 
36
- - ⚡ **Flicker-Free Datagrids** - `dgState` eliminates search debounce lag and race conditions in server-side datagrids.
40
+ - ⚡ **Flicker-Free Datagrids** - `dgState()` debounces filter changes and suppresses duplicate datagrid states. Pair it
41
+ with `switchMap` to cancel superseded reads.
37
42
  - 🔔 **Reactive Feedback Engine** - Signal-backed `cll-alert`, `AlertService`, and global `ToastService` with action
38
43
  buttons.
39
44
  - 🧙 **Async Timeline Wizard** - `cll-timeline-wizard` with step-level async validation, guard hooks, and reactive
40
45
  progress.
41
- - 📝 **Modern Form Controls** - Native `ControlValueAccessor` components: `cll-file-reader` (drag-and-drop file upload)
42
- & `cll-key-value-inputs`.
46
+ - 📝 **Modern Form Controls** - `cll-file-reader` reads text through `ControlValueAccessor`; `cll-key-value-control`
47
+ edits typed key/value arrays through ngModel, typed Reactive Forms and toSignalForm. `cll-key-value-inputs` edits a
48
+ caller-owned `FormArray`. Neither uploads files to a server.
43
49
  - 🌓 **Zero-Config Theming** - `cll-theme-toggle` seamlessly flips Clarity light/dark themes with instant `localStorage`
44
50
  persistence.
45
- - 🌍 **Built-in 12+ Language Localization** - Zero external dependencies needed; supports English, 简体中文, 繁體中文,
46
- Deutsch, Español, Français, Italiano, 日本語, 한국어, Nederlands, and Português out of the box.
51
+ - 🌍 **Built-in Localization** - Component dictionaries include English, 简体中文, 繁體中文, Deutsch, Español,
52
+ Français, 日本語, 한국어, Nederlands, Português, and Русский out of the box.
47
53
  - 📦 **100% Standalone & Tree-Shakable** - Built for Angular Signals and `OnPush` change detection.
48
54
 
49
55
  ---
50
56
 
57
+ ## Breadcrumb navigation
58
+
59
+ Import `BreadcrumbComponent` and `BreadcrumbItem` from `clr-lift`. Supply a readonly list ordered from root to current
60
+ location. Ancestors with `href` render ordinary links; addressless ancestors emit their original item through
61
+ `(navigate)`. The final item always renders noninteractive current text. An empty list renders no landmark.
62
+
63
+ ```html
64
+ <cll-breadcrumb [items]="items" ariaLabel="Database" />
65
+ ```
66
+
67
+ ```ts
68
+ const items: readonly BreadcrumbItem[] = [
69
+ {id: 'database', label: 'Database', href: '/database'},
70
+ {id: 'servers', label: 'Sql servers', href: '/database/servers'},
71
+ {id: server.id, label: server.name},
72
+ ];
73
+ ```
74
+
75
+ Optional `context` supplies display detail; otherwise descriptions include the ordered display trail and localized
76
+ depth. IDs must be unique, labels nonblank and supplied destinations valid. Relative and http/https/mailto/tel/ftp
77
+ destinations are supported. Duplicate IDs, blank labels, blank navigation names and invalid URLs throw developer
78
+ diagnostics.
79
+
80
+ For SPA routing pass `[linkTemplate]="spaLink"`, with `<ng-template #spaLink let-item>` containing your real RouterLink
81
+ anchor. `BreadcrumbLinkContext` exposes the original item as `$implicit`. Import RouterLink in the host; clr-lift adds
82
+ no router peer. Style the consumer-owned anchor with inherited font size and line height. Use `display: block`,
83
+ `overflow: hidden` and `text-overflow: ellipsis` to keep its clickable bounds inside the available label width, and an
84
+ inset focus outline (`outline-offset: -2px`) so clipping preserves the focus indicator.
85
+
86
+ Set `--cll-breadcrumb-font-size` on an instance or ancestor, including through Angular
87
+ `[style.--cll-breadcrumb-font-size]="'1rem'"`. It sizes the trail; the ancestor popover keeps Clarity's default inline
88
+ typography and line spacing. Both remain responsive to root font size and browser zoom. See the canonical specification
89
+ below for responsive ancestry behavior.
90
+
91
+ `maxVisible` defaults to four actual path items, including root/current and excluding disclosure. Available width and
92
+ current typography can remove recent ancestors. The anchored nonmodal details panel preserves complete ordered ancestry,
93
+ full labels/context and ordinary link behavior without expanding the page. It also appears when truncation alone hides
94
+ text, including on a singleton. Keep supplied arrays immutable and stable between path replacements. Escape and explicit
95
+ close return to the trigger; external path replacement leaves route focus to the host. Measurement runs only in the
96
+ browser; unmeasured rendering uses the count ceiling. SSR/hydration support has not been exercised.
97
+
98
+ For exact bucket/prefix/object state, opt in to `buildObjectPathBreadcrumbs` with `BuildObjectPathBreadcrumbsOptions`
99
+ and `ObjectPathLocation`. It constructs stable IDs, display labels and exact cumulative contexts synchronously;
100
+ `hrefFor` owns destinations and `rootPrefix` excludes higher ancestors. Compose translated application items outside the
101
+ helper. See the [usage and reference guide](../../docs/guides/object-path-breadcrumbs.md) for scope, encoding, unusual
102
+ keys and API-response examples.
103
+
104
+ See the [working demo](https://ngx-lift.vercel.app/clr-lift/components/breadcrumb) and
105
+ [canonical design spec](../../docs/design/clr-lift/breadcrumb-design-spec.md).
106
+
51
107
  ## 🚀 Quick Start (60 Seconds)
52
108
 
53
109
  ### 1. Install
@@ -63,151 +119,200 @@ npm install clr-lift ngx-lift @clr/angular @clr/ui
63
119
  @import '@clr/ui/clr-ui.min.css';
64
120
  ```
65
121
 
66
- ### 3. Use in Your Standalone Component
122
+ ### 3. Enable Clarity animation support
123
+
124
+ Clarity controls such as the datagrid inject Angular's animation builder. Install `@angular/animations` at the same
125
+ version as your app's `@angular/core`, then add its provider to your existing application configuration:
126
+
127
+ ```typescript
128
+ import {ApplicationConfig} from '@angular/core';
129
+ import {provideAnimations} from '@angular/platform-browser/animations';
130
+
131
+ export const appConfig: ApplicationConfig = {
132
+ providers: [provideAnimations()],
133
+ };
134
+ ```
135
+
136
+ Pass `appConfig` to `bootstrapApplication(AppComponent, appConfig)` in `main.ts`. Keep your existing Router/HTTP
137
+ providers. Angular 21 marks this API deprecated, but current Clarity controls still require it; follow Clarity's
138
+ compatibility requirements when upgrading.
139
+
140
+ ### 4. Use in Your Standalone Component
141
+
142
+ Mount one toast container in the application shell. This standalone root example displays a notification when its button
143
+ is clicked; no backend or application service is required.
67
144
 
68
145
  ```typescript
69
- import {Component, inject, signal} from '@angular/core';
70
- import {AlertComponent, ToastService, ThemeToggleComponent} from 'clr-lift';
146
+ import {ChangeDetectionStrategy, Component, inject} from '@angular/core';
147
+ import {AlertComponent, ToastContainerComponent, ToastService, ThemeToggleComponent} from 'clr-lift';
71
148
 
72
149
  @Component({
73
- selector: 'app-dashboard',
74
- imports: [AlertComponent, ThemeToggleComponent],
150
+ selector: 'app-root',
151
+ imports: [AlertComponent, ToastContainerComponent, ThemeToggleComponent],
75
152
  template: `
76
- <header class="flex justify-between p-4">
77
- <h2>Cluster Overview</h2>
153
+ <main cds-layout="vertical gap:md">
78
154
  <cll-theme-toggle />
79
- </header>
80
-
81
- <main class="p-4">
82
- @if (errorMessage()) {
83
- <cll-alert [error]="errorMessage()" [clrAlertClosable]="true" />
84
- }
85
-
86
- <button class="btn btn-primary" (click)="notifySuccess()">Dispatch Notification</button>
155
+ <cll-alert alertType="info" content="Ready to build with clr-lift." />
156
+ <button type="button" class="btn btn-primary" (click)="notifySuccess()">Show notification</button>
87
157
  </main>
158
+ <cll-toast-container />
88
159
  `,
160
+ changeDetection: ChangeDetectionStrategy.OnPush,
89
161
  })
90
- export class DashboardComponent {
91
- private toastService = inject(ToastService);
92
- readonly errorMessage = signal<string | null>(null);
162
+ export class AppComponent {
163
+ private readonly toastService = inject(ToastService);
93
164
 
94
165
  notifySuccess(): void {
95
- this.toastService.success('Cluster backup initiated successfully!');
166
+ this.toastService.success({title: 'Saved', description: 'Your changes were saved.'});
96
167
  }
97
168
  }
98
169
  ```
99
170
 
171
+ For HTTP errors, bind an `Error` or `HttpErrorResponse` to `[error]`; use `content` for a text message. The animation
172
+ setup above also applies to the datagrid example below.
173
+
100
174
  ---
101
175
 
102
176
  ## 🌟 Flagship Features
103
177
 
104
- ### 1. `dgState` — Server-Driven Datagrids without the Headache
178
+ ### 1. `dgState` — Datagrid refresh streams
105
179
 
106
- Clarity's default `(clrDgRefresh)` fires on every filter and pagination tick, causing jarring UI flickers and
107
- out-of-order race conditions. `dgState` manages debouncing, state caching, and cancellation automatically:
180
+ `dgState()` is an RxJS operator, not a resource factory. It delays changed filters by 500 ms and suppresses duplicate
181
+ states by default. The application owns requests, loading/error state, and subscription cleanup.
108
182
 
109
183
  ```typescript
110
- import {Component, inject} from '@angular/core';
111
- import {ClrDatagridStateInterface} from '@clr/angular';
184
+ import {AsyncPipe, JsonPipe} from '@angular/common';
185
+ import {ChangeDetectionStrategy, Component} from '@angular/core';
186
+ import {ClarityModule, ClrDatagridStateInterface} from '@clr/angular';
112
187
  import {dgState} from 'clr-lift';
113
- import {UserService} from './user.service';
188
+ import {BehaviorSubject} from 'rxjs';
114
189
 
115
190
  @Component({
116
- selector: 'app-users-grid',
191
+ selector: 'app-grid-state',
192
+ imports: [AsyncPipe, JsonPipe, ClarityModule],
117
193
  template: `
118
- <clr-datagrid (clrDgRefresh)="usersState.refresh($event)" [clrDgLoading]="usersState.isLoading()">
119
- <clr-dg-column>Name</clr-dg-column>
120
- <clr-dg-column>Email</clr-dg-column>
121
-
122
- <clr-dg-row *clrDgItems="let user of usersState.data()?.items">
123
- <clr-dg-cell>{{ user.name }}</clr-dg-cell>
124
- <clr-dg-cell>{{ user.email }}</clr-dg-cell>
125
- </clr-dg-row>
126
-
127
- <clr-dg-footer>
128
- <clr-dg-pagination [clrDgTotalItems]="usersState.data()?.total ?? 0" />
129
- </clr-dg-footer>
194
+ <clr-datagrid (clrDgRefresh)="refresh$.next($event)">
195
+ <clr-dg-column [clrDgField]="'name'">Name</clr-dg-column>
196
+ <clr-dg-row><clr-dg-cell>Ada</clr-dg-cell></clr-dg-row>
130
197
  </clr-datagrid>
198
+ <pre>{{ state$ | async | json }}</pre>
131
199
  `,
200
+ changeDetection: ChangeDetectionStrategy.OnPush,
132
201
  })
133
- export class UsersGridComponent {
134
- private userService = inject(UserService);
135
-
136
- readonly usersState = dgState((state: ClrDatagridStateInterface) => this.userService.fetchUsers(state), {
137
- debounceTime: 300,
138
- });
202
+ export class GridStateComponent {
203
+ readonly refresh$ = new BehaviorSubject<ClrDatagridStateInterface | null>(null);
204
+ readonly state$ = this.refresh$.pipe(dgState());
139
205
  }
140
206
  ```
141
207
 
142
- ### 2. `cll-timeline-wizard` — Declarative Multi-Step Workflows
208
+ Click the Name column heading to change sorting and display the emitted grid state. For server requests, follow the
209
+ [complete datagrid example](https://ngx-lift.vercel.app/clr-lift/operators/dgState).
143
210
 
144
- Build complex provisioning wizards with per-step asynchronous validation:
211
+ ### 2. `cll-timeline-wizard` — Component-based steps
145
212
 
146
- ```html
147
- <cll-timeline-wizard
148
- [steps]="wizardSteps"
149
- (finish)="onProvisionComplete($event)"
150
- (stepChange)="onStepNavigated($event)"
151
- >
152
- <ng-template cllStepContent="credentials">
153
- <app-credentials-step [form]="credentialsForm" />
154
- </ng-template>
155
-
156
- <ng-template cllStepContent="network">
157
- <app-network-step [form]="networkForm" />
158
- </ng-template>
159
- </cll-timeline-wizard>
160
- ```
213
+ The wizard takes `[timelineSteps]`, an array of `TimelineStep` configurations. Each step renders a component extending
214
+ `TimelineBaseComponent`; its Reactive Forms group owns validity and its `next$` owns optional async advancement.
215
+ `confirmed` precedes the final async action; `finished` follows success. Persisting from both outputs duplicates work.
161
216
 
162
- ### 3. `cll-file-reader` — Native Form-Controlled File Ingestion
217
+ Start with the [complete wizard demo](https://ngx-lift.vercel.app/clr-lift/components/timeline-wizard), including step
218
+ classes, required initial state, form setup and failure recovery. Content templates and `cllStepContent` are not APIs.
163
219
 
164
- No need to mess with native `<input type="file">` change events or manual Base64 reading:
220
+ ### 3. `cll-file-reader` — Read text into a form
165
221
 
166
- ```html
167
- <clr-input-container>
168
- <label>Upload TLS Certificate</label>
169
- <cll-file-reader [formControl]="certFileControl" accept=".pem,.crt" readAs="text" [maxSizeMb]="5" />
170
- </clr-input-container>
222
+ Select a PEM/text file to read its text into the control. `maxSize` is in MiB; `acceptFiles` is a file-chooser hint. Set
223
+ `encoded` for base64 text, with UTF-8 by default or explicit `textEncoding="latin1"` for legacy byte strings. The
224
+ component does not upload files, return DataURLs/ArrayBuffers, or provide drag-and-drop handling.
225
+
226
+ ```typescript
227
+ import {ChangeDetectionStrategy, Component} from '@angular/core';
228
+ import {FormControl, ReactiveFormsModule} from '@angular/forms';
229
+ import {FileReaderComponent} from 'clr-lift';
230
+
231
+ @Component({
232
+ selector: 'app-certificate-import',
233
+ imports: [ReactiveFormsModule, FileReaderComponent],
234
+ template: `
235
+ <label for="certificate-file">Certificate file</label>
236
+ <cll-file-reader controlId="certificate-file" [formControl]="content" acceptFiles=".pem,.crt" [maxSize]="5" />
237
+ <pre>{{ content.value }}</pre>
238
+ `,
239
+ changeDetection: ChangeDetectionStrategy.OnPush,
240
+ })
241
+ export class CertificateImportComponent {
242
+ readonly content = new FormControl('', {nonNullable: true});
243
+ }
171
244
  ```
172
245
 
173
246
  ---
174
247
 
175
248
  ## 🧩 Component & Operator Quick Reference
176
249
 
177
- | Category | Export | Selector / API | Description |
178
- | :----------------- | :----------------------------- | :------------------------- | :---------------------------------------------------------------------------------------- |
179
- | **Datagrid** | `dgState` | Operator / Utility | Flicker-free reactive datagrid state manager with debounce & race-condition cancellation. |
180
- | **Feedback** | `AlertComponent` | `cll-alert` | Intelligent alert container with auto-unwrapping for `Error` and `HttpErrorResponse`. |
181
- | | `AlertContainerComponent` | `cll-alert-container` | Multi-alert reactive stack controlled declaratively by `AlertService`. |
182
- | | `ToastService` | Injectable Service | Global toast dispatcher supporting `success`, `error`, `warning`, `info`. |
183
- | | `ToastContainerComponent` | `cll-toast-container` | Root toast overlay host with positioning and auto-dismiss timing. |
184
- | | `SpinnerComponent` | `cll-spinner` | Center-aligned, sized (`sm`, `md`, `lg`), accessible loading spinner. |
185
- | | `StatusIndicatorComponent` | `cll-status-indicator` | Semantic operational state badges (`success`, `warning`, `error`, `pending`). |
186
- | **Navigation** | `TimelineWizardComponent` | `cll-timeline-wizard` | Multi-step asynchronous wizard with timeline navigation and async step hooks. |
187
- | | `PageContainerComponent` | `cll-page-container` | Standardized header, breadcrumb, action bar, and content responsive shell. |
188
- | **Forms** | `FileReaderComponent` | `cll-file-reader` | `ControlValueAccessor` drag-and-drop file ingestion (Text, DataURL, ArrayBuffer). |
189
- | | `KeyValueInputsComponent` | `cll-key-value-inputs` | Dynamic key-value label/environment variable editor with duplicate key validation. |
190
- | **Theming & i18n** | `ThemeToggleComponent` | `cll-theme-toggle` | Light/dark theme switch with Clarity token synchronization & persistence. |
191
- | | `TranslationService` | Injectable Service | Built-in localization service supporting 12+ enterprise locales without external libs. |
192
- | | `TranslatePipe` | `translate` | Reactive pipe for localized component labels and messages. |
193
- | **Overlays** | `CalloutComponent` | `cll-callout` | Lightweight contextual notice box with subtle borders. |
194
- | | `CertificateSignpostComponent` | `cll-certificate-signpost` | Interactive X.509 certificate inspector showing SAN, expiry, and issuer details. |
195
- | | `TooltipDirective` | `[cllTooltip]` | Dynamic declarative popover tooltip. |
250
+ | Category | Export | Selector / API | Description |
251
+ | :----------------- | :----------------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |
252
+ | **Datagrid** | `dgState` | Operator / Utility | RxJS state operator; debounces filters and optionally suppresses duplicates. |
253
+ | **Feedback** | `AlertComponent` | `cll-alert` | Intelligent alert container with auto-unwrapping for `Error` and `HttpErrorResponse`. |
254
+ | | `AlertContainerComponent` | `cll-alert-container` | Multi-alert reactive stack controlled declaratively by `AlertService`. |
255
+ | | `ToastService` | Injectable Service | Global toast dispatcher supporting `success`, `error`, `warning`, `info`. |
256
+ | | `ToastContainerComponent` | `cll-toast-container` | Root toast overlay host with positioning and auto-dismiss timing. |
257
+ | | `SpinnerComponent` | `cll-spinner` | Center-aligned, sized (`sm`, `md`, `lg`), accessible loading spinner. |
258
+ | | `StatusIndicatorComponent` | `cll-status-indicator` | Semantic operational state badges (`success`, `warning`, `error`, `pending`). |
259
+ | **Navigation** | `TimelineWizardComponent` | `cll-timeline-wizard` | Multi-step asynchronous wizard with timeline navigation and async step hooks. |
260
+ | **Navigation** | `BreadcrumbComponent` | `cll-breadcrumb` | Caller-owned ordinary/SPA links, current-location text and addressless navigation; added in 21.4.0. |
261
+ | | `PageContainerComponent` | `cll-page-container` | Standardized header, breadcrumb, action bar, and content responsive shell. |
262
+ | **Forms** | `FileReaderComponent` | `cll-file-reader` | Text/base64 string CVA with size validation and read cancellation. |
263
+ | | `KeyValueInputsComponent` | `cll-key-value-inputs` | Caller-owned FormArray editor with duplicate key validation; not a CVA. |
264
+ | | `KeyValueControlComponent` | `cll-key-value-control` | Ordered array CVA with text/select/typed editors, custom validation, unique pairs and form integration. |
265
+ | | `DatagridSelectionComponent` | `cll-datagrid-selection` | Native Clarity datagrid CVA preserving stable keys, scoped select-all, availability and loading guards. |
266
+ | | `DatagridSelectionAccessorDirective` | `[cllDatagridSelectionAccessor]` | Host-directive adapter that lets a reusable picker expose its inner selection field to the parent form. |
267
+ | | `DatagridSelectionBindingDirective` | `cll-datagrid-selection[cllDatagridSelectionBinding]` | Binds exactly one inner selection field to the owning accessor host. |
268
+ | **Theming & i18n** | `ThemeToggleComponent` | `cll-theme-toggle` | Light/dark theme switch with Clarity token synchronization & persistence. |
269
+ | | `TranslationService` | Injectable Service | Runtime language selection, dictionary registration and fallback. |
270
+ | | `TranslatePipe` | `translate` | Reactive pipe for localized component labels and messages. |
271
+ | **Overlays** | `CalloutComponent` | `cll-callout` | Lightweight contextual notice box with subtle borders. |
272
+ | | `CertificateSignpostComponent` | `cll-certificate-signpost` | Interactive X.509 certificate inspector showing issuer, validity, and fingerprint details. |
273
+ | | `TooltipDirective` | `[cllTooltip]` | Dynamic declarative popover tooltip. |
274
+ | **Development** | `QueryDevtoolsComponent` | `cll-query-devtools` | Resizable query panel with data/error inspection, row actions and a development-only root provider. |
275
+
276
+ **Available since clr-lift 21.3.0:** the inspector and `clr-lift/devtools` entry point below ship from that release
277
+ onward. Register once in `app.config.ts`:
278
+
279
+ ```typescript
280
+ import {ApplicationConfig} from '@angular/core';
281
+ import {provideQueryDevtools} from 'clr-lift/devtools';
282
+
283
+ export const appConfig: ApplicationConfig = {
284
+ providers: [provideQueryDevtools()],
285
+ };
286
+ ```
287
+
288
+ The development launcher opens a resizable, nonmodal bottom panel. Search/filter/sort/paginate queries, inspect data,
289
+ errors and tags, copy keys, and explicitly refetch one query. Data previews are bounded, expandable and read-only.
290
+ Inspection requires the matching `ngx-lift` 21.4.0 or later; Refetch controls require a client exposing `refetchQuery`.
291
+ Automatic snapshots run only while open and unpaused. `provideQueryClient()` is needed only to customize client
292
+ settings. The package's production condition resolves to a no-op and excludes the inspector implementation.
293
+
294
+ For scoped clients or inline placement, import `QueryDevtoolsComponent` and use
295
+ `<cll-query-devtools [client]="scopedQueryClient" />`. The caller retains client ownership. `launcher="floating"`
296
+ selects the icon launcher. `[enabled]="true"` deliberately enables a direct component import outside development, as in
297
+ the documentation preview; that opt-in bypasses the provider's production exclusion. See the
298
+ [design spec](https://github.com/wghglory/ngx-lift-workspace/blob/main/docs/design/clr-lift/query-devtools-design-spec.md).
196
299
 
197
300
  ---
198
301
 
199
302
  ## 🌍 Built-in Localization
200
303
 
201
- All interactive messages, placeholders, and labels in `clr-lift` are fully localized in:
202
-
203
- | English (`en`) | 简体中文 (`zh-CN`) | 繁體中文 (`zh-TW`) | Deutsch (`de`) |
204
- | :----------------- | :-------------------- | :---------------------------- | :----------------- |
205
- | **Español (`es`)** | **Français (`fr`)** | **Italiano (`it`)** | **日本語 (`ja`)** |
206
- | **한국어 (`ko`)** | **Nederlands (`nl`)** | **Português (`pt`, `pt-BR`)** | **Русский (`ru`)** |
304
+ Library dictionaries cover English, Simplified/Traditional Chinese, German, Spanish, French, Japanese, Korean, Dutch,
305
+ Brazilian Portuguese and Russian, with regional fallback. The libraries and the demo maintain the same eleven language
306
+ dictionaries. Key/placeholder checks establish dictionary completeness; independent native-speaker acceptance remains
307
+ separate. Applications own translations for their content and can register additional dictionaries.
207
308
 
208
309
  Switch language on the fly via `TranslationService`:
209
310
 
210
311
  ```typescript
312
+ // Inside a component/service injection context.
313
+ import {inject} from '@angular/core';
314
+ import {TranslationService} from 'clr-lift';
315
+
211
316
  const translationService = inject(TranslationService);
212
317
 
213
318
  // Change locale at runtime - all clr-lift components react immediately!
@@ -218,16 +323,17 @@ translationService.setLanguage('zh-CN');
218
323
 
219
324
  ## 🧪 Testing
220
325
 
221
- `clr-lift` is built with 100% test focus. When testing components that consume `clr-lift`:
326
+ When testing components that consume `clr-lift`, import the component under test. For example, a standalone alert needs
327
+ no application-specific provider:
222
328
 
223
329
  ```typescript
224
330
  import {TestBed} from '@angular/core/testing';
225
- import {TranslationService} from 'clr-lift';
331
+ import {beforeEach} from 'vitest';
332
+ import {AlertComponent} from 'clr-lift';
226
333
 
227
334
  beforeEach(async () => {
228
335
  await TestBed.configureTestingModule({
229
- imports: [MyComponent],
230
- providers: [TranslationService],
336
+ imports: [AlertComponent],
231
337
  }).compileComponents();
232
338
  });
233
339
  ```
@@ -240,5 +346,9 @@ MIT © [Guanghui Wang](https://github.com/wghglory)
240
346
 
241
347
  ## Lifecycle and production contracts
242
348
 
243
- See [service scoping, clocks, localization and query diagnostics](../../docs/design/priority-1-2-completion.md) for
244
- ownership and loading contracts. [中文说明](../../docs/design/priority-1-2-completion.zh-CN.md).
349
+ See
350
+ [service scoping, clocks, localization and query diagnostics](https://github.com/wghglory/ngx-lift-workspace/blob/main/docs/guides/demo-and-library-integration.md)
351
+ for ownership and loading contracts.
352
+
353
+ See the [key/value usage and design spec](../../docs/design/clr-lift/key-value-inputs-design-spec.md#usage) for selects,
354
+ dependent options, typed values, validation and migration.
@@ -0,0 +1,5 @@
1
+ import {makeEnvironmentProviders} from '@angular/core';
2
+
3
+ export function provideQueryDevtools() {
4
+ return makeEnvironmentProviders([]);
5
+ }
@@ -0,0 +1,57 @@
1
+ import { isPlatformBrowser, DOCUMENT } from '@angular/common';
2
+ import { InjectionToken, makeEnvironmentProviders, provideEnvironmentInitializer, isDevMode, inject, PLATFORM_ID, EnvironmentInjector, ApplicationRef, DestroyRef, afterNextRender, createComponent } from '@angular/core';
3
+ import { QueryDevtoolsComponent } from 'clr-lift';
4
+
5
+ const installation = new InjectionToken('query devtools installation', {
6
+ providedIn: 'root',
7
+ factory: () => ({ installed: false }),
8
+ });
9
+ /**
10
+ * Install one floating query inspector at application root. The package's production condition supplies a no-op.
11
+ * @example
12
+ * ```typescript
13
+ * const appConfig: ApplicationConfig = {providers: [provideQueryDevtools()]};
14
+ * ```
15
+ */
16
+ function provideQueryDevtools() {
17
+ return makeEnvironmentProviders([
18
+ provideEnvironmentInitializer(() => {
19
+ if (!isDevMode() || !isPlatformBrowser(inject(PLATFORM_ID)))
20
+ return;
21
+ const state = inject(installation);
22
+ if (state.installed)
23
+ return;
24
+ state.installed = true;
25
+ const document = inject(DOCUMENT);
26
+ const environmentInjector = inject(EnvironmentInjector);
27
+ const applicationRef = inject(ApplicationRef);
28
+ const destroyRef = inject(DestroyRef);
29
+ let component;
30
+ let host;
31
+ const render = afterNextRender(() => {
32
+ host = document.createElement('cll-query-devtools-root');
33
+ component = createComponent(QueryDevtoolsComponent, { environmentInjector, hostElement: host });
34
+ component.setInput('launcher', 'floating');
35
+ document.body.append(host);
36
+ applicationRef.attachView(component.hostView);
37
+ component.changeDetectorRef.detectChanges();
38
+ }, { injector: environmentInjector });
39
+ destroyRef.onDestroy(() => {
40
+ render.destroy();
41
+ if (component) {
42
+ applicationRef.detachView(component.hostView);
43
+ component.destroy();
44
+ }
45
+ host?.remove();
46
+ state.installed = false;
47
+ });
48
+ }),
49
+ ]);
50
+ }
51
+
52
+ /**
53
+ * Generated bundle index. Do not edit.
54
+ */
55
+
56
+ export { provideQueryDevtools };
57
+ //# sourceMappingURL=clr-lift-devtools-development.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"clr-lift-devtools-development.mjs","sources":["../../../../libs/clr-lift/devtools/development/index.ts","../../../../libs/clr-lift/devtools/development/clr-lift-devtools-development.ts"],"sourcesContent":["import {DOCUMENT, isPlatformBrowser} from '@angular/common';\nimport {\n afterNextRender,\n ApplicationRef,\n createComponent,\n ComponentRef,\n DestroyRef,\n EnvironmentInjector,\n EnvironmentProviders,\n inject,\n InjectionToken,\n isDevMode,\n makeEnvironmentProviders,\n PLATFORM_ID,\n provideEnvironmentInitializer,\n} from '@angular/core';\nimport {QueryDevtoolsComponent} from 'clr-lift';\n\nconst installation = new InjectionToken('query devtools installation', {\n providedIn: 'root',\n factory: () => ({installed: false}),\n});\n\n/**\n * Install one floating query inspector at application root. The package's production condition supplies a no-op.\n * @example\n * ```typescript\n * const appConfig: ApplicationConfig = {providers: [provideQueryDevtools()]};\n * ```\n */\nexport function provideQueryDevtools(): EnvironmentProviders {\n return makeEnvironmentProviders([\n provideEnvironmentInitializer(() => {\n if (!isDevMode() || !isPlatformBrowser(inject(PLATFORM_ID))) return;\n const state = inject(installation);\n if (state.installed) return;\n state.installed = true;\n const document = inject(DOCUMENT);\n const environmentInjector = inject(EnvironmentInjector);\n const applicationRef = inject(ApplicationRef);\n const destroyRef = inject(DestroyRef);\n let component: ComponentRef<QueryDevtoolsComponent> | undefined;\n let host: HTMLElement | undefined;\n const render = afterNextRender(\n () => {\n host = document.createElement('cll-query-devtools-root');\n component = createComponent(QueryDevtoolsComponent, {environmentInjector, hostElement: host});\n component.setInput('launcher', 'floating');\n document.body.append(host);\n applicationRef.attachView(component.hostView);\n component.changeDetectorRef.detectChanges();\n },\n {injector: environmentInjector},\n );\n destroyRef.onDestroy(() => {\n render.destroy();\n if (component) {\n applicationRef.detachView(component.hostView);\n component.destroy();\n }\n host?.remove();\n state.installed = false;\n });\n }),\n ]);\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;;;AAkBA,MAAM,YAAY,GAAG,IAAI,cAAc,CAAC,6BAA6B,EAAE;AACrE,IAAA,UAAU,EAAE,MAAM;IAClB,OAAO,EAAE,OAAO,EAAC,SAAS,EAAE,KAAK,EAAC,CAAC;AACpC,CAAA,CAAC;AAEF;;;;;;AAMG;SACa,oBAAoB,GAAA;AAClC,IAAA,OAAO,wBAAwB,CAAC;QAC9B,6BAA6B,CAAC,MAAK;YACjC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;gBAAE;AAC7D,YAAA,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC;YAClC,IAAI,KAAK,CAAC,SAAS;gBAAE;AACrB,YAAA,KAAK,CAAC,SAAS,GAAG,IAAI;AACtB,YAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;AACjC,YAAA,MAAM,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,CAAC;AACvD,YAAA,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC;AAC7C,YAAA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;AACrC,YAAA,IAAI,SAA2D;AAC/D,YAAA,IAAI,IAA6B;AACjC,YAAA,MAAM,MAAM,GAAG,eAAe,CAC5B,MAAK;AACH,gBAAA,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,yBAAyB,CAAC;AACxD,gBAAA,SAAS,GAAG,eAAe,CAAC,sBAAsB,EAAE,EAAC,mBAAmB,EAAE,WAAW,EAAE,IAAI,EAAC,CAAC;AAC7F,gBAAA,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;AAC1C,gBAAA,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AAC1B,gBAAA,cAAc,CAAC,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC;AAC7C,gBAAA,SAAS,CAAC,iBAAiB,CAAC,aAAa,EAAE;AAC7C,YAAA,CAAC,EACD,EAAC,QAAQ,EAAE,mBAAmB,EAAC,CAChC;AACD,YAAA,UAAU,CAAC,SAAS,CAAC,MAAK;gBACxB,MAAM,CAAC,OAAO,EAAE;gBAChB,IAAI,SAAS,EAAE;AACb,oBAAA,cAAc,CAAC,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC;oBAC7C,SAAS,CAAC,OAAO,EAAE;gBACrB;gBACA,IAAI,EAAE,MAAM,EAAE;AACd,gBAAA,KAAK,CAAC,SAAS,GAAG,KAAK;AACzB,YAAA,CAAC,CAAC;AACJ,QAAA,CAAC,CAAC;AACH,KAAA,CAAC;AACJ;;ACjEA;;AAEG;;"}