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 +216 -106
- package/devtools/stub.mjs +5 -0
- package/fesm2022/clr-lift-devtools-development.mjs +57 -0
- package/fesm2022/clr-lift-devtools-development.mjs.map +1 -0
- package/fesm2022/clr-lift.mjs +4890 -702
- package/fesm2022/clr-lift.mjs.map +1 -1
- package/package.json +14 -6
- package/types/clr-lift-devtools-development.d.ts +12 -0
- package/types/clr-lift.d.ts +797 -108
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
[](https://angular.dev)
|
|
11
11
|
[](https://clarity.design)
|
|
12
12
|
|
|
13
|
-
[📖 Documentation](https://ngx-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
|
|
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`
|
|
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** -
|
|
42
|
-
|
|
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
|
|
46
|
-
|
|
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.
|
|
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
|
|
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-
|
|
74
|
-
imports: [AlertComponent, ThemeToggleComponent],
|
|
150
|
+
selector: 'app-root',
|
|
151
|
+
imports: [AlertComponent, ToastContainerComponent, ThemeToggleComponent],
|
|
75
152
|
template: `
|
|
76
|
-
<
|
|
77
|
-
<h2>Cluster Overview</h2>
|
|
153
|
+
<main cds-layout="vertical gap:md">
|
|
78
154
|
<cll-theme-toggle />
|
|
79
|
-
|
|
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
|
|
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('
|
|
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` —
|
|
178
|
+
### 1. `dgState` — Datagrid refresh streams
|
|
105
179
|
|
|
106
|
-
|
|
107
|
-
|
|
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 {
|
|
111
|
-
import {
|
|
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 {
|
|
188
|
+
import {BehaviorSubject} from 'rxjs';
|
|
114
189
|
|
|
115
190
|
@Component({
|
|
116
|
-
selector: 'app-
|
|
191
|
+
selector: 'app-grid-state',
|
|
192
|
+
imports: [AsyncPipe, JsonPipe, ClarityModule],
|
|
117
193
|
template: `
|
|
118
|
-
<clr-datagrid (clrDgRefresh)="
|
|
119
|
-
<clr-dg-column>Name</clr-dg-column>
|
|
120
|
-
<clr-dg-
|
|
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
|
|
134
|
-
|
|
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
|
-
|
|
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
|
-
|
|
211
|
+
### 2. `cll-timeline-wizard` — Component-based steps
|
|
145
212
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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
|
-
|
|
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
|
-
|
|
220
|
+
### 3. `cll-file-reader` — Read text into a form
|
|
165
221
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
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
|
|
178
|
-
| :----------------- |
|
|
179
|
-
| **Datagrid** | `dgState`
|
|
180
|
-
| **Feedback** | `AlertComponent`
|
|
181
|
-
| | `AlertContainerComponent`
|
|
182
|
-
| | `ToastService`
|
|
183
|
-
| | `ToastContainerComponent`
|
|
184
|
-
| | `SpinnerComponent`
|
|
185
|
-
| | `StatusIndicatorComponent`
|
|
186
|
-
| **Navigation** | `TimelineWizardComponent`
|
|
187
|
-
|
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
191
|
-
| | `
|
|
192
|
-
| | `
|
|
193
|
-
|
|
|
194
|
-
| | `
|
|
195
|
-
|
|
|
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
|
-
|
|
202
|
-
|
|
203
|
-
|
|
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
|
|
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 {
|
|
331
|
+
import {beforeEach} from 'vitest';
|
|
332
|
+
import {AlertComponent} from 'clr-lift';
|
|
226
333
|
|
|
227
334
|
beforeEach(async () => {
|
|
228
335
|
await TestBed.configureTestingModule({
|
|
229
|
-
imports: [
|
|
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
|
|
244
|
-
|
|
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,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;;"}
|