clr-lift 19.0.0 → 21.1.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
@@ -1,75 +1,239 @@
1
- # clr-lift Overview
1
+ <div align="center">
2
2
 
3
- The **clr-lift** library is designed to augment the capabilities of the Clarity library by providing a set of reusable
4
- components built on top of clarity components.
3
+ # 🎨 clr-lift
5
4
 
6
- ## Features
5
+ **Enterprise Angular components, utilities, and operators built on Clarity Design System**
7
6
 
8
- 1. **dgState Operator**
7
+ [![npm version](https://img.shields.io/npm/v/clr-lift.svg?logo=npm)](https://www.npmjs.com/package/clr-lift)
8
+ [![npm downloads](https://img.shields.io/npm/dm/clr-lift.svg)](https://www.npmjs.com/package/clr-lift)
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%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)
9
12
 
10
- The **clr-lift** library introduces the `dgState` operator, which enhances the functionality of the Clarity library.
11
- This operator streamlines the management of datagrid state, making it more intuitive and efficient for developers to
12
- work with Clarity datagrids.
13
+ [📖 Documentation](https://ngx-lift.netlify.app/clr-lift) • [🎮 Live Demo](https://ngx-lift.netlify.app/clr-lift) •
14
+ [💻 GitHub Repository](https://github.com/wghglory/ngx-lift-workspace)
13
15
 
14
- 2. **Datagrid Utilities**
16
+ </div>
15
17
 
16
- The library includes a set of utilities specifically tailored for Clarity datagrids. These utilities aim to simplify
17
- common tasks and operations related to datagrids, providing developers with a more streamlined and cohesive
18
- experience when working with Clarity components.
18
+ ---
19
19
 
20
- ## Requirements
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.
21
23
 
22
- To ensure optimal performance and compatibility, clr-lift requires **Angular version 17 or higher**.
24
+ ```html
25
+ <!-- Enhanced Clarity alert with automatic Error/HttpErrorResponse extraction -->
26
+ <cll-alert [error]="userError()" [isLightweight]="true" />
23
27
 
24
- ## Getting Started
28
+ <!-- Zero-config light/dark theme switcher -->
29
+ <cll-theme-toggle />
30
+ ```
25
31
 
26
- ### Installation
32
+ ---
27
33
 
28
- To use **clr-lift** in your project, you can install it using your preferred package manager. For example, with npm:
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.
48
+
49
+ ---
50
+
51
+ ## 🚀 Quick Start (60 Seconds)
52
+
53
+ ### 1. Install
29
54
 
30
55
  ```bash
31
- npm install clr-lift
56
+ npm install clr-lift ngx-lift @clr/angular @clr/ui
32
57
  ```
33
58
 
34
- ### Usage
59
+ ### 2. Add Clarity Styles
35
60
 
36
- ```ts
37
- import {dgState, convertToHttpParams} from 'clr-lift';
61
+ ```scss
62
+ // styles.scss
63
+ @import '@clr/ui/clr-ui.min.css';
64
+ ```
38
65
 
39
- export class UserDatagridComponent {
40
- private dgSource = new BehaviorSubject<ClrDatagridStateInterface | null>(null);
41
- private dgState$ = this.dgSource.pipe(dgState());
66
+ ### 3. Use in Your Standalone Component
67
+
68
+ ```typescript
69
+ import {Component, inject, signal} from '@angular/core';
70
+ import {AlertComponent, ToastService, ThemeToggleComponent} from 'clr-lift';
71
+
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);
93
+
94
+ notifySuccess(): void {
95
+ this.toastService.success('Cluster backup initiated successfully!');
96
+ }
97
+ }
98
+ ```
99
+
100
+ ---
42
101
 
43
- usersState$ = this.dgState$.pipe(
44
- switchMap((state) => {
45
- const params = convertToHttpParams(state);
46
- return this.userService.getUserAPI(params);
47
- }),
48
- share(),
49
- );
102
+ ## 🌟 Flagship Features
103
+
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:
108
+
109
+ ```typescript
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';
114
+
115
+ @Component({
116
+ selector: 'app-users-grid',
117
+ 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>
130
+ </clr-datagrid>
131
+ `,
132
+ })
133
+ export class UsersGridComponent {
134
+ private userService = inject(UserService);
135
+
136
+ readonly usersState = dgState((state: ClrDatagridStateInterface) => this.userService.fetchUsers(state), {
137
+ debounceTime: 300,
138
+ });
50
139
  }
51
140
  ```
52
141
 
53
- ## Running unit tests
142
+ ### 2. `cll-timeline-wizard` — Declarative Multi-Step Workflows
143
+
144
+ Build complex provisioning wizards with per-step asynchronous validation:
54
145
 
55
- Run `nx test clr-lift` to execute the unit tests.
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>
56
155
 
57
- ## Contributing
156
+ <ng-template cllStepContent="network">
157
+ <app-network-step [form]="networkForm" />
158
+ </ng-template>
159
+ </cll-timeline-wizard>
160
+ ```
58
161
 
59
- We welcome contributions to the **clr-lift** library. If you encounter any issues, have feature requests, or would like
60
- to contribute code, please check out our
61
- [contribution guidelines](https://github.com/wghglory/ngx-lift-workspace/CONTRIBUTING.md).
162
+ ### 3. `cll-file-reader` — Native Form-Controlled File Ingestion
62
163
 
63
- ## License
164
+ No need to mess with native `<input type="file">` change events or manual Base64 reading:
64
165
 
65
- **clr-lift** is licensed under the MIT License.
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
+ ```
66
172
 
67
- ## Acknowledgments
173
+ ---
68
174
 
69
- We would like to express our gratitude to the Clarity library maintainers and contributors for their foundational work
70
- that enables the development of **clr-lift**.
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. |
71
196
 
72
197
  ---
73
198
 
74
- Feel free to explore the **clr-lift** library and enhance your Clarity datagrid implementation with ease! If you have
75
- any questions or concerns, please don't hesitate to reach out to us. Happy coding!
199
+ ## 🌍 Built-in Localization
200
+
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`)** |
207
+
208
+ Switch language on the fly via `TranslationService`:
209
+
210
+ ```typescript
211
+ const translationService = inject(TranslationService);
212
+
213
+ // Change locale at runtime - all clr-lift components react immediately!
214
+ translationService.setLanguage('zh-CN');
215
+ ```
216
+
217
+ ---
218
+
219
+ ## 🧪 Testing
220
+
221
+ `clr-lift` is built with 100% test focus. When testing components that consume `clr-lift`:
222
+
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
+ ```
234
+
235
+ ---
236
+
237
+ ## 📄 License
238
+
239
+ MIT © [Guanghui Wang](https://github.com/wghglory)