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 +167 -184
- package/fesm2022/clr-lift.mjs +2676 -773
- package/fesm2022/clr-lift.mjs.map +1 -1
- package/package.json +5 -3
- package/types/clr-lift.d.ts +380 -73
package/README.md
CHANGED
|
@@ -2,260 +2,243 @@
|
|
|
2
2
|
|
|
3
3
|
# 🎨 clr-lift
|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**Enterprise Angular components, utilities, and operators built on Clarity Design System**
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/clr-lift)
|
|
8
8
|
[](https://www.npmjs.com/package/clr-lift)
|
|
9
9
|
[](https://opensource.org/licenses/MIT)
|
|
10
|
-
[](https://angular.dev)
|
|
11
|
+
[](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
|
-
[💻
|
|
14
|
+
[💻 GitHub Repository](https://github.com/wghglory/ngx-lift-workspace)
|
|
15
15
|
|
|
16
16
|
</div>
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
-
|
|
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
|
-
|
|
28
|
+
<!-- Zero-config light/dark theme switcher -->
|
|
29
|
+
<cll-theme-toggle />
|
|
30
|
+
```
|
|
71
31
|
|
|
72
|
-
|
|
32
|
+
---
|
|
73
33
|
|
|
74
|
-
##
|
|
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
|
-
|
|
77
|
-
- **@clr/angular**: >= 18.0.0
|
|
78
|
-
- **ngx-lift**: >= 21.0.0
|
|
79
|
-
- **RxJS**: >= 7.8.0
|
|
49
|
+
---
|
|
80
50
|
|
|
81
|
-
##
|
|
51
|
+
## 🚀 Quick Start (60 Seconds)
|
|
82
52
|
|
|
83
|
-
|
|
53
|
+
### 1. Install
|
|
84
54
|
|
|
85
55
|
```bash
|
|
86
|
-
npm install clr-lift @clr/angular
|
|
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
|
-
|
|
59
|
+
### 2. Add Clarity Styles
|
|
94
60
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
###
|
|
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 {
|
|
111
|
-
import {
|
|
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
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
127
|
-
this.
|
|
94
|
+
notifySuccess(): void {
|
|
95
|
+
this.toastService.success('Cluster backup initiated successfully!');
|
|
128
96
|
}
|
|
129
97
|
}
|
|
130
98
|
```
|
|
131
99
|
|
|
132
|
-
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 🌟 Flagship Features
|
|
133
103
|
|
|
134
|
-
|
|
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 {
|
|
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-
|
|
142
|
-
imports: [AlertComponent, SpinnerComponent, PageContainerComponent],
|
|
116
|
+
selector: 'app-users-grid',
|
|
143
117
|
template: `
|
|
144
|
-
<
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
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
|
|
156
|
-
private
|
|
133
|
+
export class UsersGridComponent {
|
|
134
|
+
private userService = inject(UserService);
|
|
157
135
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
190
|
-
(stepChange)="
|
|
191
|
-
|
|
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
|
-
|
|
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
|
-
|
|
164
|
+
No need to mess with native `<input type="file">` change events or manual Base64 reading:
|
|
205
165
|
|
|
206
|
-
|
|
207
|
-
-
|
|
208
|
-
|
|
209
|
-
-
|
|
210
|
-
-
|
|
211
|
-
|
|
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
|
-
|
|
173
|
+
---
|
|
216
174
|
|
|
217
|
-
|
|
218
|
-
|
|
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
|
-
|
|
197
|
+
---
|
|
222
198
|
|
|
223
|
-
|
|
224
|
-
nx test clr-lift --coverage
|
|
225
|
-
```
|
|
199
|
+
## 🌍 Built-in Localization
|
|
226
200
|
|
|
227
|
-
|
|
201
|
+
All interactive messages, placeholders, and labels in `clr-lift` are fully localized in:
|
|
228
202
|
|
|
229
|
-
|
|
230
|
-
|
|
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
|
-
|
|
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
|
-
|
|
210
|
+
```typescript
|
|
211
|
+
const translationService = inject(TranslationService);
|
|
239
212
|
|
|
240
|
-
|
|
213
|
+
// Change locale at runtime - all clr-lift components react immediately!
|
|
214
|
+
translationService.setLanguage('zh-CN');
|
|
215
|
+
```
|
|
241
216
|
|
|
242
|
-
|
|
217
|
+
---
|
|
243
218
|
|
|
244
|
-
|
|
245
|
-
foundational work that enables the development of **clr-lift**.
|
|
219
|
+
## 🧪 Testing
|
|
246
220
|
|
|
247
|
-
|
|
221
|
+
`clr-lift` is built with 100% test focus. When testing components that consume `clr-lift`:
|
|
248
222
|
|
|
249
|
-
|
|
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
|
-
|
|
237
|
+
## 📄 License
|
|
254
238
|
|
|
255
|
-
|
|
239
|
+
MIT © [Guanghui Wang](https://github.com/wghglory)
|
|
256
240
|
|
|
257
|
-
|
|
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
|
-
|
|
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).
|