clr-lift 21.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 +164 -186
- package/fesm2022/clr-lift.mjs +876 -651
- package/fesm2022/clr-lift.mjs.map +1 -1
- package/package.json +4 -2
- package/types/clr-lift.d.ts +208 -60
package/README.md
CHANGED
|
@@ -2,260 +2,238 @@
|
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
### Installation
|
|
59
|
+
### 2. Add Clarity Styles
|
|
96
60
|
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
|
|
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';
|
|
113
|
-
|
|
114
|
-
export class UserDatagridComponent {
|
|
115
|
-
private dgSource = new BehaviorSubject<ClrDatagridStateInterface | null>(null);
|
|
116
|
-
private dgState$ = this.dgSource.pipe(dgState());
|
|
69
|
+
import {Component, inject, signal} from '@angular/core';
|
|
70
|
+
import {AlertComponent, ToastService, ThemeToggleComponent} from 'clr-lift';
|
|
117
71
|
|
|
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
|
|
103
|
+
|
|
104
|
+
### 1. `dgState` — Server-Driven Datagrids without the Headache
|
|
133
105
|
|
|
134
|
-
|
|
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
|
-
|
|
162
|
+
### 3. `cll-file-reader` — Native Form-Controlled File Ingestion
|
|
195
163
|
|
|
196
|
-
|
|
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)
|
|
164
|
+
No need to mess with native `<input type="file">` change events or manual Base64 reading:
|
|
201
165
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
-
|
|
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
|
|
214
|
-
|
|
215
|
-
Run the unit tests for clr-lift:
|
|
216
|
-
|
|
217
|
-
```bash
|
|
218
|
-
nx test clr-lift
|
|
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>
|
|
219
171
|
```
|
|
220
172
|
|
|
221
|
-
|
|
173
|
+
---
|
|
222
174
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
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. |
|
|
226
196
|
|
|
227
|
-
|
|
197
|
+
---
|
|
228
198
|
|
|
229
|
-
|
|
230
|
-
project better.
|
|
199
|
+
## 🌍 Built-in Localization
|
|
231
200
|
|
|
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)
|
|
201
|
+
All interactive messages, placeholders, and labels in `clr-lift` are fully localized in:
|
|
237
202
|
|
|
238
|
-
|
|
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`)** |
|
|
239
207
|
|
|
240
|
-
|
|
208
|
+
Switch language on the fly via `TranslationService`:
|
|
241
209
|
|
|
242
|
-
|
|
210
|
+
```typescript
|
|
211
|
+
const translationService = inject(TranslationService);
|
|
243
212
|
|
|
244
|
-
|
|
245
|
-
|
|
213
|
+
// Change locale at runtime - all clr-lift components react immediately!
|
|
214
|
+
translationService.setLanguage('zh-CN');
|
|
215
|
+
```
|
|
246
216
|
|
|
247
|
-
|
|
217
|
+
---
|
|
248
218
|
|
|
249
|
-
|
|
219
|
+
## 🧪 Testing
|
|
250
220
|
|
|
251
|
-
|
|
221
|
+
`clr-lift` is built with 100% test focus. When testing components that consume `clr-lift`:
|
|
252
222
|
|
|
253
|
-
|
|
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
|
+
```
|
|
254
234
|
|
|
255
|
-
|
|
235
|
+
---
|
|
256
236
|
|
|
257
|
-
|
|
258
|
-
[Request Feature](https://github.com/wghglory/ngx-lift-workspace/issues) •
|
|
259
|
-
[View Documentation](https://ngx-lift.netlify.app/clr-lift)
|
|
237
|
+
## 📄 License
|
|
260
238
|
|
|
261
|
-
|
|
239
|
+
MIT © [Guanghui Wang](https://github.com/wghglory)
|