clr-lift 21.3.0 → 21.5.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 +99 -43
- package/fesm2022/clr-lift.mjs +3469 -624
- package/fesm2022/clr-lift.mjs.map +1 -1
- package/package.json +3 -4
- package/types/clr-lift.d.ts +672 -104
package/README.md
CHANGED
|
@@ -10,16 +10,16 @@
|
|
|
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>
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
20
|
-
**clr-lift** supercharges
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
**clr-lift** supercharges the **Clarity Design System** with battle-tested enterprise primitives. It fills the gaps in
|
|
21
|
+
standard Clarity by delivering flicker-free datagrid state management, reactive notification systems, async multi-step
|
|
22
|
+
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 -->
|
|
@@ -43,16 +43,67 @@ installed version; source changes under Unreleased are not yet on npm.
|
|
|
43
43
|
buttons.
|
|
44
44
|
- 🧙 **Async Timeline Wizard** - `cll-timeline-wizard` with step-level async validation, guard hooks, and reactive
|
|
45
45
|
progress.
|
|
46
|
-
- 📝 **Modern Form Controls** - `cll-file-reader` reads text through `ControlValueAccessor`; `cll-key-value-
|
|
47
|
-
edits
|
|
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.
|
|
48
49
|
- 🌓 **Zero-Config Theming** - `cll-theme-toggle` seamlessly flips Clarity light/dark themes with instant `localStorage`
|
|
49
50
|
persistence.
|
|
50
|
-
- 🌍 **Built-in Localization** - Component dictionaries include English, 简体中文, 繁體中文, Deutsch, Español,
|
|
51
|
-
|
|
51
|
+
- 🌍 **Built-in Localization** - Component dictionaries include English, 简体中文, 繁體中文, Deutsch, Español,
|
|
52
|
+
Français, 日本語, 한국어, Nederlands, Português, and Русский out of the box.
|
|
52
53
|
- 📦 **100% Standalone & Tree-Shakable** - Built for Angular Signals and `OnPush` change detection.
|
|
53
54
|
|
|
54
55
|
---
|
|
55
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. The repository's `docs/guides/object-path-breadcrumbs.md` covers scope, encoding, unusual keys and API-response
|
|
102
|
+
examples.
|
|
103
|
+
|
|
104
|
+
See the [working demo](https://ngx-lift.vercel.app/clr-lift/components/breadcrumb) and the canonical design spec at
|
|
105
|
+
`docs/design/clr-lift/breadcrumb-design-spec.md` in the repository.
|
|
106
|
+
|
|
56
107
|
## 🚀 Quick Start (60 Seconds)
|
|
57
108
|
|
|
58
109
|
### 1. Install
|
|
@@ -155,7 +206,7 @@ export class GridStateComponent {
|
|
|
155
206
|
```
|
|
156
207
|
|
|
157
208
|
Click the Name column heading to change sorting and display the emitted grid state. For server requests, follow the
|
|
158
|
-
[complete datagrid example](https://ngx-lift.
|
|
209
|
+
[complete datagrid example](https://ngx-lift.vercel.app/clr-lift/operators/dgState).
|
|
159
210
|
|
|
160
211
|
### 2. `cll-timeline-wizard` — Component-based steps
|
|
161
212
|
|
|
@@ -163,7 +214,7 @@ The wizard takes `[timelineSteps]`, an array of `TimelineStep` configurations. E
|
|
|
163
214
|
`TimelineBaseComponent`; its Reactive Forms group owns validity and its `next$` owns optional async advancement.
|
|
164
215
|
`confirmed` precedes the final async action; `finished` follows success. Persisting from both outputs duplicates work.
|
|
165
216
|
|
|
166
|
-
Start with the [complete wizard demo](https://ngx-lift.
|
|
217
|
+
Start with the [complete wizard demo](https://ngx-lift.vercel.app/clr-lift/components/timeline-wizard), including step
|
|
167
218
|
classes, required initial state, form setup and failure recovery. Content templates and `cllStepContent` are not APIs.
|
|
168
219
|
|
|
169
220
|
### 3. `cll-file-reader` — Read text into a form
|
|
@@ -196,29 +247,32 @@ export class CertificateImportComponent {
|
|
|
196
247
|
|
|
197
248
|
## 🧩 Component & Operator Quick Reference
|
|
198
249
|
|
|
199
|
-
| Category | Export | Selector / API | Description
|
|
200
|
-
| :----------------- | :----------------------------- | :------------------------- |
|
|
201
|
-
| **Datagrid** | `dgState` | Operator / Utility | RxJS state operator; debounces filters and optionally suppresses duplicates.
|
|
202
|
-
| **Feedback** | `AlertComponent` | `cll-alert` | Intelligent alert container with auto-unwrapping for `Error` and `HttpErrorResponse`.
|
|
203
|
-
| | `AlertContainerComponent` | `cll-alert-container` | Multi-alert reactive stack controlled declaratively by `AlertService`.
|
|
204
|
-
| | `ToastService` | Injectable Service | Global toast dispatcher supporting `success`, `error`, `warning`, `info`.
|
|
205
|
-
| | `ToastContainerComponent` | `cll-toast-container` | Root toast overlay host with positioning and auto-dismiss timing.
|
|
206
|
-
| | `SpinnerComponent` | `cll-spinner` | Center-aligned, sized (`sm`, `md`, `lg`), accessible loading spinner.
|
|
207
|
-
| | `StatusIndicatorComponent` | `cll-status-indicator` | Semantic operational state badges (`success`, `warning`, `error`, `pending`).
|
|
208
|
-
| **Navigation** | `TimelineWizardComponent` | `cll-timeline-wizard` | Multi-step asynchronous wizard with timeline navigation and async step hooks.
|
|
209
|
-
|
|
|
210
|
-
|
|
|
211
|
-
|
|
|
212
|
-
|
|
|
213
|
-
| | `
|
|
214
|
-
| | `
|
|
215
|
-
| **
|
|
216
|
-
| | `
|
|
217
|
-
| | `
|
|
218
|
-
| **
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
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
|
+
| **Theming & i18n** | `ThemeToggleComponent` | `cll-theme-toggle` | Light/dark theme switch with Clarity token synchronization & persistence. |
|
|
267
|
+
| | `TranslationService` | Injectable Service | Runtime language selection, dictionary registration and fallback. |
|
|
268
|
+
| | `TranslatePipe` | `translate` | Reactive pipe for localized component labels and messages. |
|
|
269
|
+
| **Overlays** | `CalloutComponent` | `cll-callout` | Lightweight contextual notice box with subtle borders. |
|
|
270
|
+
| | `CertificateSignpostComponent` | `cll-certificate-signpost` | Interactive X.509 certificate inspector showing issuer, validity, and fingerprint details. |
|
|
271
|
+
| | `TooltipDirective` | `[cllTooltip]` | Dynamic declarative popover tooltip. |
|
|
272
|
+
| **Development** | `QueryDevtoolsComponent` | `cll-query-devtools` | Resizable query panel with data/error inspection, row actions and a development-only root provider. |
|
|
273
|
+
|
|
274
|
+
**Available since clr-lift 21.3.0:** the inspector and `clr-lift/devtools` entry point below ship from that release
|
|
275
|
+
onward. Register once in `app.config.ts`:
|
|
222
276
|
|
|
223
277
|
```typescript
|
|
224
278
|
import {ApplicationConfig} from '@angular/core';
|
|
@@ -230,10 +284,10 @@ export const appConfig: ApplicationConfig = {
|
|
|
230
284
|
```
|
|
231
285
|
|
|
232
286
|
The development launcher opens a resizable, nonmodal bottom panel. Search/filter/sort/paginate queries, inspect data,
|
|
233
|
-
errors and tags, copy keys, and explicitly refetch one query. Data previews are bounded, expandable and read-only.
|
|
234
|
-
ngx-lift 21.
|
|
235
|
-
run only while open and unpaused. `provideQueryClient()` is needed only to customize client
|
|
236
|
-
production condition resolves to a no-op and excludes the inspector implementation.
|
|
287
|
+
errors and tags, copy keys, and explicitly refetch one query. Data previews are bounded, expandable and read-only.
|
|
288
|
+
Inspection requires the matching `ngx-lift` 21.4.0 or later; Refetch controls require a client exposing `refetchQuery`.
|
|
289
|
+
Automatic snapshots run only while open and unpaused. `provideQueryClient()` is needed only to customize client
|
|
290
|
+
settings. The package's production condition resolves to a no-op and excludes the inspector implementation.
|
|
237
291
|
|
|
238
292
|
For scoped clients or inline placement, import `QueryDevtoolsComponent` and use
|
|
239
293
|
`<cll-query-devtools [client]="scopedQueryClient" />`. The caller retains client ownership. `launcher="floating"`
|
|
@@ -245,11 +299,10 @@ the documentation preview; that opt-in bypasses the provider's production exclus
|
|
|
245
299
|
|
|
246
300
|
## 🌍 Built-in Localization
|
|
247
301
|
|
|
248
|
-
Library dictionaries cover English, Simplified/Traditional Chinese, German, Spanish, French,
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
dictionaries.
|
|
302
|
+
Library dictionaries cover English, Simplified/Traditional Chinese, German, Spanish, French, Japanese, Korean, Dutch,
|
|
303
|
+
Brazilian Portuguese and Russian, with regional fallback. The libraries and the demo maintain the same eleven language
|
|
304
|
+
dictionaries. Key/placeholder checks establish dictionary completeness; independent native-speaker acceptance remains
|
|
305
|
+
separate. Applications own translations for their content and can register additional dictionaries.
|
|
253
306
|
|
|
254
307
|
Switch language on the fly via `TranslationService`:
|
|
255
308
|
|
|
@@ -287,10 +340,13 @@ beforeEach(async () => {
|
|
|
287
340
|
|
|
288
341
|
## 📄 License
|
|
289
342
|
|
|
290
|
-
MIT ©
|
|
343
|
+
MIT © Project maintainers
|
|
291
344
|
|
|
292
345
|
## Lifecycle and production contracts
|
|
293
346
|
|
|
294
347
|
See
|
|
295
348
|
[service scoping, clocks, localization and query diagnostics](https://github.com/wghglory/ngx-lift-workspace/blob/main/docs/guides/demo-and-library-integration.md)
|
|
296
349
|
for ownership and loading contracts.
|
|
350
|
+
|
|
351
|
+
The `Usage` section of `docs/design/clr-lift/key-value-inputs-design-spec.md` in the repository covers selects,
|
|
352
|
+
dependent options, typed values, validation and migration.
|