clr-lift 21.3.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>
@@ -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-inputs`
47
- edits a caller-owned `FormArray`. Neither uploads files to a server.
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, Français,
51
- 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.
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. 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
+
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.netlify.app/clr-lift/operators/dgState).
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.netlify.app/clr-lift/components/timeline-wizard), including step
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,34 @@ 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
- | | `PageContainerComponent` | `cll-page-container` | Standardized header, breadcrumb, action bar, and content responsive shell. |
210
- | **Forms** | `FileReaderComponent` | `cll-file-reader` | Text/base64 string CVA with size validation and read cancellation. |
211
- | | `KeyValueInputsComponent` | `cll-key-value-inputs` | Caller-owned FormArray editor with duplicate key validation; not a CVA. |
212
- | **Theming & i18n** | `ThemeToggleComponent` | `cll-theme-toggle` | Light/dark theme switch with Clarity token synchronization & persistence. |
213
- | | `TranslationService` | Injectable Service | Runtime language selection, dictionary registration and fallback. |
214
- | | `TranslatePipe` | `translate` | Reactive pipe for localized component labels and messages. |
215
- | **Overlays** | `CalloutComponent` | `cll-callout` | Lightweight contextual notice box with subtle borders. |
216
- | | `CertificateSignpostComponent` | `cll-certificate-signpost` | Interactive X.509 certificate inspector showing SAN, expiry, and issuer details. |
217
- | | `TooltipDirective` | `[cllTooltip]` | Dynamic declarative popover tooltip. |
218
- | **Development** | `QueryDevtoolsComponent` | `cll-query-devtools` | Resizable query panel with data/error inspection, row actions and a development-only root provider. |
219
-
220
- **Unreleased on main:** the inspector and `clr-lift/devtools` entry point below are not in clr-lift 21.2.0. Use a
221
- release containing them before copying this setup. Register once in `app.config.ts`:
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`:
222
278
 
223
279
  ```typescript
224
280
  import {ApplicationConfig} from '@angular/core';
@@ -230,10 +286,10 @@ export const appConfig: ApplicationConfig = {
230
286
  ```
231
287
 
232
288
  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. With
234
- ngx-lift 21.3, inspection is available; Refetch controls require a client exposing `refetchQuery`. Automatic snapshots
235
- run only while open and unpaused. `provideQueryClient()` is needed only to customize client settings. The package's
236
- production condition resolves to a no-op and excludes the inspector implementation.
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.
237
293
 
238
294
  For scoped clients or inline placement, import `QueryDevtoolsComponent` and use
239
295
  `<cll-query-devtools [client]="scopedQueryClient" />`. The caller retains client ownership. `launcher="floating"`
@@ -245,11 +301,10 @@ the documentation preview; that opt-in bypasses the provider's production exclus
245
301
 
246
302
  ## 🌍 Built-in Localization
247
303
 
248
- Library dictionaries cover English, Simplified/Traditional Chinese, German, Spanish, French, Italian, Japanese, Korean,
249
- Dutch, Portuguese and Russian, with regional fallback. The demo maintains eleven language dictionaries; its locale
250
- inventory differs from the library dictionaries. Key/placeholder checks establish dictionary completeness; independent
251
- native-speaker acceptance remains separate. Applications own translations for their content and can register additional
252
- dictionaries.
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.
253
308
 
254
309
  Switch language on the fly via `TranslationService`:
255
310
 
@@ -294,3 +349,6 @@ MIT © [Guanghui Wang](https://github.com/wghglory)
294
349
  See
295
350
  [service scoping, clocks, localization and query diagnostics](https://github.com/wghglory/ngx-lift-workspace/blob/main/docs/guides/demo-and-library-integration.md)
296
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.