clr-lift 21.0.0 → 21.2.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
@@ -2,260 +2,243 @@
2
2
 
3
3
  # 🎨 clr-lift
4
4
 
5
- **Production-ready Angular components built on Clarity Design System**
5
+ **Enterprise Angular components, utilities, and operators built on Clarity Design System**
6
6
 
7
7
  [![npm version](https://img.shields.io/npm/v/clr-lift.svg?logo=npm)](https://www.npmjs.com/package/clr-lift)
8
8
  [![npm downloads](https://img.shields.io/npm/dm/clr-lift.svg)](https://www.npmjs.com/package/clr-lift)
9
9
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
- [![Angular](https://img.shields.io/badge/Angular-%3E%3D19.0.0-red.svg)](https://angular.io)
11
- [![Clarity](https://img.shields.io/badge/Clarity-%3E%3D17.0.0-blue.svg)](https://clarity.design)
10
+ [![Angular](https://img.shields.io/badge/Angular-%3E%3D21.0.0-red.svg)](https://angular.dev)
11
+ [![Clarity](https://img.shields.io/badge/Clarity-%3E%3D18.0.0-blue.svg)](https://clarity.design)
12
12
 
13
13
  [📖 Documentation](https://ngx-lift.netlify.app/clr-lift) • [🎮 Live Demo](https://ngx-lift.netlify.app/clr-lift) •
14
- [💻 Source Code](https://github.com/wghglory/ngx-lift-workspace/tree/main/libs/clr-lift)
14
+ [💻 GitHub Repository](https://github.com/wghglory/ngx-lift-workspace)
15
15
 
16
16
  </div>
17
17
 
18
18
  ---
19
19
 
20
- A comprehensive Angular component library built on top of the **Clarity Design System**. **clr-lift** extends Clarity's
21
- capabilities by providing a rich set of production-ready, reusable components, utilities, and operators that simplify
22
- common development tasks.
20
+ **clr-lift** supercharges VMware's **Clarity Design System** with battle-tested enterprise primitives. It fills the gaps
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.
23
23
 
24
- **Why clr-lift?**
25
-
26
- - 🎨 **15+ Components** - Alerts, toasts, wizards, spinners, and more
27
- - 🏗️ **Built on Clarity** - Consistent with VMware Clarity Design System
28
- - ♿ **Accessible** - WCAG compliant with ARIA support
29
- - 🎯 **Type-Safe** - Full TypeScript support with strict mode
30
- - 🌓 **Theme Support** - Light and dark mode out of the box
31
- - 📦 **Tree-Shakable** - Import only what you need
32
-
33
- ## Features
34
-
35
- ### 🎨 Components
36
-
37
- - **`cll-alert`** - Enhanced alert component with customizable types and styling
38
- - **`cll-alerts`** - Alert container service for managing multiple alerts
39
- - **`cll-callout`** - Callout component for highlighting important information
40
- - **`cll-certificate-signpost`** - Certificate display and validation component
41
- - **`cll-file-reader`** - File input component with drag-and-drop support
42
- - **`cll-idle-detection`** - Idle detection component with configurable timeouts
43
- - **`cll-key-value-inputs`** - Key-value pair input component for forms
44
- - **`cll-page-container`** - Page layout container component
45
- - **`cll-spinner`** - Loading spinner component
46
- - **`cll-status-indicator`** - Status indicator component with various states
47
- - **`cll-theme-toggle`** - Theme toggle component for light/dark mode
48
- - **`cll-timeline-wizard`** - Timeline wizard component for multi-step flows
49
- - **`cll-toast`** - Toast notification component
50
- - **`cll-tooltip`** - Advanced tooltip component with rich content support
51
-
52
- ### 🔧 Operators
53
-
54
- - **`dgState`** - Streamlines Clarity datagrid state management, making it easier to work with datagrid state changes
55
-
56
- ### 🛠️ Utilities
57
-
58
- - **`convertToHttpParams`** - Converts Clarity datagrid state to HTTP query parameters
59
- - **Datagrid Utilities** - Helper functions for working with Clarity datagrids
60
-
61
- ### 📦 Models
62
-
63
- - **`PageQuery`** - Type for pagination query parameters
64
- - **`Rde`** - Type for RDE (Resource Definition Entity) objects
65
-
66
- ### 🌐 Services
67
-
68
- - **`TranslationService`** - Service for managing translations and i18n
24
+ ```html
25
+ <!-- Enhanced Clarity alert with automatic Error/HttpErrorResponse extraction -->
26
+ <cll-alert [error]="userError()" [isLightweight]="true" />
69
27
 
70
- ### 🔤 Pipes
28
+ <!-- Zero-config light/dark theme switcher -->
29
+ <cll-theme-toggle />
30
+ ```
71
31
 
72
- - **`translate`** - Translation pipe for displaying translated text
32
+ ---
73
33
 
74
- ## Requirements
34
+ ## ⚡ Highlights
35
+
36
+ - ⚡ **Flicker-Free Datagrids** - `dgState` eliminates search debounce lag and race conditions in server-side datagrids.
37
+ - 🔔 **Reactive Feedback Engine** - Signal-backed `cll-alert`, `AlertService`, and global `ToastService` with action
38
+ buttons.
39
+ - 🧙 **Async Timeline Wizard** - `cll-timeline-wizard` with step-level async validation, guard hooks, and reactive
40
+ progress.
41
+ - 📝 **Modern Form Controls** - Native `ControlValueAccessor` components: `cll-file-reader` (drag-and-drop file upload)
42
+ & `cll-key-value-inputs`.
43
+ - 🌓 **Zero-Config Theming** - `cll-theme-toggle` seamlessly flips Clarity light/dark themes with instant `localStorage`
44
+ 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.
47
+ - 📦 **100% Standalone & Tree-Shakable** - Built for Angular Signals and `OnPush` change detection.
75
48
 
76
- - **Angular**: >= 21.0.0
77
- - **@clr/angular**: >= 18.0.0
78
- - **ngx-lift**: >= 21.0.0
79
- - **RxJS**: >= 7.8.0
49
+ ---
80
50
 
81
- ## Installation
51
+ ## 🚀 Quick Start (60 Seconds)
82
52
 
83
- Install clr-lift and its peer dependencies:
53
+ ### 1. Install
84
54
 
85
55
  ```bash
86
- npm install clr-lift @clr/angular ngx-lift
87
- # or
88
- yarn add clr-lift @clr/angular ngx-lift
89
- # or
90
- pnpm add clr-lift @clr/angular ngx-lift
56
+ npm install clr-lift ngx-lift @clr/angular @clr/ui
91
57
  ```
92
58
 
93
- ## 🚀 Quick Start
59
+ ### 2. Add Clarity Styles
94
60
 
95
- ### Installation
96
-
97
- ```bash
98
- npm install clr-lift @clr/angular ngx-lift
99
- # or
100
- yarn add clr-lift @clr/angular ngx-lift
101
- # or
102
- pnpm add clr-lift @clr/angular ngx-lift
61
+ ```scss
62
+ // styles.scss
63
+ @import '@clr/ui/clr-ui.min.css';
103
64
  ```
104
65
 
105
- ### Using the dgState Operator
106
-
107
- **Simplified Datagrid State Management** - Streamline Clarity datagrid state handling:
66
+ ### 3. Use in Your Standalone Component
108
67
 
109
68
  ```typescript
110
- import {dgState, convertToHttpParams} from 'clr-lift';
111
- import {BehaviorSubject, switchMap, share} from 'rxjs';
112
- import {ClrDatagridStateInterface} from '@clr/angular';
69
+ import {Component, inject, signal} from '@angular/core';
70
+ import {AlertComponent, ToastService, ThemeToggleComponent} from 'clr-lift';
113
71
 
114
- export class UserDatagridComponent {
115
- private dgSource = new BehaviorSubject<ClrDatagridStateInterface | null>(null);
116
- private dgState$ = this.dgSource.pipe(dgState());
117
-
118
- usersState$ = this.dgState$.pipe(
119
- switchMap((state) => {
120
- const params = convertToHttpParams(state);
121
- return this.userService.getUsers(params);
122
- }),
123
- share(),
124
- );
72
+ @Component({
73
+ selector: 'app-dashboard',
74
+ imports: [AlertComponent, ThemeToggleComponent],
75
+ template: `
76
+ <header class="flex justify-between p-4">
77
+ <h2>Cluster Overview</h2>
78
+ <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>
87
+ </main>
88
+ `,
89
+ })
90
+ export class DashboardComponent {
91
+ private toastService = inject(ToastService);
92
+ readonly errorMessage = signal<string | null>(null);
125
93
 
126
- refresh(state: ClrDatagridStateInterface) {
127
- this.dgSource.next(state);
94
+ notifySuccess(): void {
95
+ this.toastService.success('Cluster backup initiated successfully!');
128
96
  }
129
97
  }
130
98
  ```
131
99
 
132
- ### Using Components
100
+ ---
101
+
102
+ ## 🌟 Flagship Features
133
103
 
134
- **Standalone Components** - Import only what you need:
104
+ ### 1. `dgState` — Server-Driven Datagrids without the Headache
105
+
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:
135
108
 
136
109
  ```typescript
137
- import {Component} from '@angular/core';
138
- import {AlertComponent, SpinnerComponent, PageContainerComponent, ToastService} from 'clr-lift';
110
+ import {Component, inject} from '@angular/core';
111
+ import {ClrDatagridStateInterface} from '@clr/angular';
112
+ import {dgState} from 'clr-lift';
113
+ import {UserService} from './user.service';
139
114
 
140
115
  @Component({
141
- selector: 'app-example',
142
- imports: [AlertComponent, SpinnerComponent, PageContainerComponent],
116
+ selector: 'app-users-grid',
143
117
  template: `
144
- <cll-alert [type]="'success'" [closable]="true"> Operation completed successfully! </cll-alert>
145
-
146
- <cll-spinner [size]="'lg'"></cll-spinner>
147
-
148
- <cll-page-container>
149
- <h1>Page Content</h1>
150
- </cll-page-container>
151
-
152
- <button (click)="showToast()">Show Toast</button>
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>
130
+ </clr-datagrid>
153
131
  `,
154
132
  })
155
- export class ExampleComponent {
156
- private toastService = inject(ToastService);
133
+ export class UsersGridComponent {
134
+ private userService = inject(UserService);
157
135
 
158
- showToast() {
159
- this.toastService.show({
160
- type: 'success',
161
- message: 'Operation completed!',
162
- });
163
- }
136
+ readonly usersState = dgState((state: ClrDatagridStateInterface) => this.userService.fetchUsers(state), {
137
+ debounceTime: 300,
138
+ });
164
139
  }
165
140
  ```
166
141
 
167
- ### Using File Reader Component
168
-
169
- ```html
170
- <cll-file-reader
171
- [(ngModel)]="file"
172
- [accept]="'.pdf,.doc,.docx'"
173
- [maxSize]="5242880"
174
- [multiple]="false"
175
- ></cll-file-reader>
176
- ```
177
-
178
- ### Using Theme Toggle
179
-
180
- ```html
181
- <cll-theme-toggle></cll-theme-toggle>
182
- ```
142
+ ### 2. `cll-timeline-wizard` — Declarative Multi-Step Workflows
183
143
 
184
- ### Using Timeline Wizard
144
+ Build complex provisioning wizards with per-step asynchronous validation:
185
145
 
186
146
  ```html
187
147
  <cll-timeline-wizard
188
148
  [steps]="wizardSteps"
189
- [currentStep]="currentStep"
190
- (stepChange)="onStepChange($event)"
191
- ></cll-timeline-wizard>
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>
192
160
  ```
193
161
 
194
- ## 📚 Documentation
195
-
196
- - **📖 Full Documentation**: [ngx-lift.netlify.app/clr-lift](https://ngx-lift.netlify.app/clr-lift)
197
- - **🎮 Interactive Demo**: [Live Examples](https://ngx-lift.netlify.app/clr-lift)
198
- - **💻 Source Code**: [GitHub Repository](https://github.com/wghglory/ngx-lift-workspace/tree/main/libs/clr-lift)
199
- - **📦 npm Package**: [npmjs.com/package/clr-lift](https://www.npmjs.com/package/clr-lift)
200
- - **🎨 Clarity Design System**: [clarity.design](https://clarity.design)
201
-
202
- ## 🎯 Use Cases
162
+ ### 3. `cll-file-reader` — Native Form-Controlled File Ingestion
203
163
 
204
- **clr-lift** is perfect for:
164
+ No need to mess with native `<input type="file">` change events or manual Base64 reading:
205
165
 
206
- - 🎨 **UI Components** - Production-ready components for Clarity-based applications
207
- - 📊 **Data Grids** - Simplified state management for Clarity datagrids
208
- - 🔔 **Notifications** - Toast notifications and alerts
209
- - 📝 **Forms** - Enhanced form components (file uploads, key-value inputs)
210
- - 🧭 **Navigation** - Wizards, timelines, and multi-step flows
211
- - 🎭 **Theming** - Easy theme switching between light and dark modes
212
-
213
- ## 🧪 Testing
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>
171
+ ```
214
172
 
215
- Run the unit tests for clr-lift:
173
+ ---
216
174
 
217
- ```bash
218
- nx test clr-lift
219
- ```
175
+ ## 🧩 Component & Operator Quick Reference
176
+
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. |
220
196
 
221
- Run tests with coverage:
197
+ ---
222
198
 
223
- ```bash
224
- nx test clr-lift --coverage
225
- ```
199
+ ## 🌍 Built-in Localization
226
200
 
227
- ## 🤝 Contributing
201
+ All interactive messages, placeholders, and labels in `clr-lift` are fully localized in:
228
202
 
229
- We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes this
230
- project better.
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`)** |
231
207
 
232
- - 🐛 **Found a bug?** [Open an issue](https://github.com/wghglory/ngx-lift-workspace/issues/new?template=bug_report.md)
233
- - 💡 **Have a feature request?**
234
- [Request a feature](https://github.com/wghglory/ngx-lift-workspace/issues/new?template=feature_request.md)
235
- - 📝 **Want to contribute?** See our
236
- [Contributing Guidelines](https://github.com/wghglory/ngx-lift-workspace/blob/main/CONTRIBUTING.md)
208
+ Switch language on the fly via `TranslationService`:
237
209
 
238
- ## 📄 License
210
+ ```typescript
211
+ const translationService = inject(TranslationService);
239
212
 
240
- **clr-lift** is licensed under the [MIT License](https://opensource.org/licenses/MIT).
213
+ // Change locale at runtime - all clr-lift components react immediately!
214
+ translationService.setLanguage('zh-CN');
215
+ ```
241
216
 
242
- ## 🙏 Acknowledgments
217
+ ---
243
218
 
244
- We would like to express our gratitude to the **Clarity Design System** maintainers and contributors for their
245
- foundational work that enables the development of **clr-lift**.
219
+ ## 🧪 Testing
246
220
 
247
- ## ⭐ Show Your Support
221
+ `clr-lift` is built with 100% test focus. When testing components that consume `clr-lift`:
248
222
 
249
- If this library helped you, please consider giving it a ⭐ on GitHub!
223
+ ```typescript
224
+ import {TestBed} from '@angular/core/testing';
225
+ import {TranslationService} from 'clr-lift';
226
+
227
+ beforeEach(async () => {
228
+ await TestBed.configureTestingModule({
229
+ imports: [MyComponent],
230
+ providers: [TranslationService],
231
+ }).compileComponents();
232
+ });
233
+ ```
250
234
 
251
235
  ---
252
236
 
253
- <div align="center">
237
+ ## 📄 License
254
238
 
255
- **Made with ❤️ for the Angular and Clarity community**
239
+ MIT © [Guanghui Wang](https://github.com/wghglory)
256
240
 
257
- [Report Bug](https://github.com/wghglory/ngx-lift-workspace/issues) •
258
- [Request Feature](https://github.com/wghglory/ngx-lift-workspace/issues) •
259
- [View Documentation](https://ngx-lift.netlify.app/clr-lift)
241
+ ## Lifecycle and production contracts
260
242
 
261
- </div>
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).