@vialiq/web-components 0.17.0 → 0.19.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 +392 -118
- package/base/draggable-mixin.d.ts +2 -0
- package/base/draggable-mixin.d.ts.map +1 -1
- package/base/focus-trap-mixin.d.ts.map +1 -1
- package/base/overlay-manager.d.ts +16 -6
- package/base/overlay-manager.d.ts.map +1 -1
- package/base/resizable-mixin.d.ts +28 -0
- package/base/resizable-mixin.d.ts.map +1 -0
- package/index.d.ts +4 -0
- package/index.js +7 -1299
- package/overlay-manager-Ch_6fr_D.js +168 -0
- package/package.json +2 -2
- package/tooltip/vi-tooltip.js +1 -1
- package/overlay-manager-CZSDXl6Z.js +0 -108
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
,# @vialiq/web-components
|
|
2
2
|
|
|
3
3
|
Buildable and publishable Lit web component library for the Vi design system.
|
|
4
4
|
|
|
@@ -20,6 +20,7 @@ npm install @vialiq/web-components lit
|
|
|
20
20
|
Since these components are built using standard Custom Elements APIs, they are compatible with any web framework or vanilla web stack.
|
|
21
21
|
|
|
22
22
|
### Subpath Exports & Tree-Shaking
|
|
23
|
+
|
|
23
24
|
To keep your bundle sizes minimal, import only the components you need:
|
|
24
25
|
|
|
25
26
|
```ts
|
|
@@ -39,9 +40,11 @@ import { registerIcons, ViButton } from '@vialiq/web-components';
|
|
|
39
40
|
### Framework Guides
|
|
40
41
|
|
|
41
42
|
#### 1. React
|
|
43
|
+
|
|
42
44
|
React 19 supports Custom Elements natively. If you are using React <19, you must set properties and custom events manually via `ref` or use custom wrapper packages.
|
|
43
45
|
|
|
44
46
|
**React 19 Example:**
|
|
47
|
+
|
|
45
48
|
```tsx
|
|
46
49
|
import React from 'react';
|
|
47
50
|
import '@vialiq/web-components/button';
|
|
@@ -49,38 +52,43 @@ import '@vialiq/web-components/input';
|
|
|
49
52
|
|
|
50
53
|
export function SearchForm() {
|
|
51
54
|
return (
|
|
52
|
-
<form
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
/>
|
|
59
|
-
<vi-button type="submit" variant="primary">
|
|
55
|
+
<form
|
|
56
|
+
onSubmit={(e) => {
|
|
57
|
+
e.preventDefault();
|
|
58
|
+
console.log('Submitted');
|
|
59
|
+
}}
|
|
60
|
+
>
|
|
61
|
+
<vi-input name="query" placeholder="Search..." required onvialiq-input={(e: any) => console.log(e.detail.value)} />
|
|
62
|
+
<vi-button type="submit" variant="primary">
|
|
63
|
+
Search
|
|
64
|
+
</vi-button>
|
|
60
65
|
</form>
|
|
61
66
|
);
|
|
62
67
|
}
|
|
63
68
|
```
|
|
64
69
|
|
|
65
70
|
#### 2. Vue
|
|
71
|
+
|
|
66
72
|
Vue supports custom elements seamlessly out-of-the-box. Register the tags so Vue's compiler knows not to treat them as Vue components:
|
|
67
73
|
|
|
68
74
|
**vite.config.ts:**
|
|
75
|
+
|
|
69
76
|
```ts
|
|
70
77
|
export default defineConfig({
|
|
71
78
|
plugins: [
|
|
72
79
|
vue({
|
|
73
80
|
template: {
|
|
74
81
|
compilerOptions: {
|
|
75
|
-
isCustomElement: (tag) => tag.startsWith('vi-')
|
|
76
|
-
}
|
|
77
|
-
}
|
|
78
|
-
})
|
|
79
|
-
]
|
|
82
|
+
isCustomElement: (tag) => tag.startsWith('vi-'),
|
|
83
|
+
},
|
|
84
|
+
},
|
|
85
|
+
}),
|
|
86
|
+
],
|
|
80
87
|
});
|
|
81
88
|
```
|
|
82
89
|
|
|
83
90
|
**Vue Component Template:**
|
|
91
|
+
|
|
84
92
|
```html
|
|
85
93
|
<template>
|
|
86
94
|
<div>
|
|
@@ -91,9 +99,11 @@ export default defineConfig({
|
|
|
91
99
|
```
|
|
92
100
|
|
|
93
101
|
#### 3. Angular
|
|
102
|
+
|
|
94
103
|
To use Custom Elements in Angular, you must add the `CUSTOM_ELEMENTS_SCHEMA` to the `schemas` array of the `@Component` (for standalone components) or `@NgModule` where they are consumed.
|
|
95
104
|
|
|
96
105
|
**Standalone Component Setup:**
|
|
106
|
+
|
|
97
107
|
```typescript
|
|
98
108
|
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
|
|
99
109
|
|
|
@@ -101,7 +111,7 @@ import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
|
|
|
101
111
|
selector: 'app-search-form',
|
|
102
112
|
standalone: true,
|
|
103
113
|
templateUrl: './search-form.component.html',
|
|
104
|
-
schemas: [CUSTOM_ELEMENTS_SCHEMA]
|
|
114
|
+
schemas: [CUSTOM_ELEMENTS_SCHEMA],
|
|
105
115
|
})
|
|
106
116
|
export class SearchFormComponent {
|
|
107
117
|
searchQuery = '';
|
|
@@ -114,19 +124,17 @@ export class SearchFormComponent {
|
|
|
114
124
|
```
|
|
115
125
|
|
|
116
126
|
**search-form.component.html Template:**
|
|
127
|
+
|
|
117
128
|
```html
|
|
118
129
|
<div>
|
|
119
|
-
<vi-input
|
|
120
|
-
|
|
121
|
-
(vialiq-input)="onInput($event)"
|
|
122
|
-
placeholder="Search catalog..."
|
|
123
|
-
></vi-input>
|
|
124
|
-
|
|
130
|
+
<vi-input [value]="searchQuery" (vialiq-input)="onInput($event)" placeholder="Search catalog..."></vi-input>
|
|
131
|
+
|
|
125
132
|
<vi-button variant="primary">Search</vi-button>
|
|
126
133
|
</div>
|
|
127
134
|
```
|
|
128
135
|
|
|
129
136
|
#### 4. Next.js (SSR / React Server Components)
|
|
137
|
+
|
|
130
138
|
Custom Elements must register on the browser's `window` object. Next.js and server-side rendering environments require lazy-loading or dynamic imports to ensure registration occurs client-side.
|
|
131
139
|
|
|
132
140
|
```tsx
|
|
@@ -144,29 +152,32 @@ export default function MyClientComponent() {
|
|
|
144
152
|
}
|
|
145
153
|
```
|
|
146
154
|
|
|
147
|
-
|
|
148
155
|
---
|
|
149
156
|
|
|
150
157
|
## Component API & Detailed Examples
|
|
151
158
|
|
|
152
159
|
### Button ([vi-button](./src/button/vi-button.ts))
|
|
160
|
+
|
|
153
161
|
The [ViButton](./src/button/vi-button.ts) is a versatile button component that wraps a native `<button>` element with keyboard interaction, focus indicators, visual variations, and slot options.
|
|
154
162
|
|
|
155
163
|
#### Properties & Attributes
|
|
156
|
-
|
|
157
|
-
|
|
|
158
|
-
|
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
+
|
|
165
|
+
| Attribute | Property | Type | Default | Description |
|
|
166
|
+
| :--------------- | :-------------- | :------------------------------------------------------------- | :---------- | :-------------------------------------------------------------- |
|
|
167
|
+
| `variant` | `variant` | `'primary'\|'secondary'\|'danger'\|'success'\|'info'\|'ghost'` | `'primary'` | Visual design style. |
|
|
168
|
+
| `size` | `size` | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Sizing scale. |
|
|
169
|
+
| `icon-placement` | `iconPlacement` | `'start'\|'end'` | `'start'` | Location of the icon relative to the label. |
|
|
170
|
+
| `full-width` | `fullWidth` | `boolean` | `false` | Sets width to 100% of container. |
|
|
171
|
+
| `icon-only` | `iconOnly` | `boolean` | `false` | Squares padding and matches dimensions for an icon-only layout. |
|
|
172
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables button interactions and sets `tabindex="-1"`. |
|
|
164
173
|
|
|
165
174
|
#### Slots
|
|
175
|
+
|
|
166
176
|
- **Default Slot**: Button label (text/content).
|
|
167
177
|
- **`icon` Slot**: Container for standard icons.
|
|
168
178
|
|
|
169
179
|
#### CSS Parts
|
|
180
|
+
|
|
170
181
|
- `button`: The native internal `<button>` element.
|
|
171
182
|
- `icon`: The icon wrapper element.
|
|
172
183
|
- `label`: The text label span wrapper.
|
|
@@ -174,6 +185,7 @@ The [ViButton](./src/button/vi-button.ts) is a versatile button component that w
|
|
|
174
185
|
#### Snippets
|
|
175
186
|
|
|
176
187
|
**Standard Button Variants:**
|
|
188
|
+
|
|
177
189
|
```html
|
|
178
190
|
<vi-button variant="primary">Primary Action</vi-button>
|
|
179
191
|
<vi-button variant="secondary">Secondary Action</vi-button>
|
|
@@ -182,6 +194,7 @@ The [ViButton](./src/button/vi-button.ts) is a versatile button component that w
|
|
|
182
194
|
```
|
|
183
195
|
|
|
184
196
|
**Sizes & Layouts:**
|
|
197
|
+
|
|
185
198
|
```html
|
|
186
199
|
<vi-button size="xs">Extra Small</vi-button>
|
|
187
200
|
<vi-button size="sm">Small</vi-button>
|
|
@@ -193,6 +206,7 @@ The [ViButton](./src/button/vi-button.ts) is a versatile button component that w
|
|
|
193
206
|
```
|
|
194
207
|
|
|
195
208
|
**Icons Support:**
|
|
209
|
+
|
|
196
210
|
```html
|
|
197
211
|
<!-- Icon at start (default) -->
|
|
198
212
|
<vi-button>
|
|
@@ -215,34 +229,40 @@ The [ViButton](./src/button/vi-button.ts) is a versatile button component that w
|
|
|
215
229
|
---
|
|
216
230
|
|
|
217
231
|
### Input ([vi-input](./src/input/vi-input.ts))
|
|
232
|
+
|
|
218
233
|
The [ViInput](./src/input/vi-input.ts) component is a form-associated custom text input control. It wraps a native single-line input field and automatically supports accessibility features, validation states, helper text slots, and custom style configuration.
|
|
219
234
|
|
|
220
235
|
#### Properties & Attributes
|
|
221
|
-
|
|
222
|
-
|
|
|
223
|
-
|
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
234
|
-
| `aria-
|
|
236
|
+
|
|
237
|
+
| Attribute | Property | Type | Default | Description |
|
|
238
|
+
| :----------------- | :---------------- | :-------------------------------------------------------------- | :---------- | :----------------------------------------------- |
|
|
239
|
+
| `type` | `type` | `'text'\|'email'\|'password'\|'search'\|'tel'\|'url'\|'number'` | `'text'` | Renders appropriate input format. |
|
|
240
|
+
| `placeholder` | `placeholder` | `string` | `''` | Input placeholder text. |
|
|
241
|
+
| `name` | `name` | `string` | `''` | Form participation field name. |
|
|
242
|
+
| `value` | `value` | `string` | `''` | Controlled input value. |
|
|
243
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables field interactions. |
|
|
244
|
+
| `readonly` | `readonly` | `boolean` | `false` | Disables keyboard editing. |
|
|
245
|
+
| `required` | `required` | `boolean` | `false` | Marks field validation as mandatory. |
|
|
246
|
+
| `status` | `status` | `'default'\|'valid'\|'invalid'` | `'default'` | Controls validation visual presentation. |
|
|
247
|
+
| `validity-message` | `validityMessage` | `string` | `''` | Native or custom error message to display in UI. |
|
|
248
|
+
| `size` | `size` | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Controls font sizes and paddings. |
|
|
249
|
+
| `aria-label` | `ariaLabel` | `string` | `''` | Accessibility label. |
|
|
250
|
+
| `aria-labelledby` | `ariaLabelledby` | `string` | `''` | ID reference of accessible label. |
|
|
235
251
|
|
|
236
252
|
#### Slots
|
|
253
|
+
|
|
237
254
|
- **`helper` Slot**: Location to insert description text below the input field.
|
|
238
255
|
|
|
239
256
|
#### Events
|
|
257
|
+
|
|
240
258
|
- `vialiq-input`: Fires on every keypress. Detail: `{ value: string }`.
|
|
241
259
|
- `vialiq-change`: Fires when element loses focus (blur). Detail: `{ value: string }`.
|
|
242
260
|
- `invalid`: Native HTML5 validation failed event.
|
|
243
261
|
|
|
244
262
|
#### CSS Custom Properties
|
|
263
|
+
|
|
245
264
|
Exposes variables for custom theme styling:
|
|
265
|
+
|
|
246
266
|
```css
|
|
247
267
|
vi-input {
|
|
248
268
|
--vi-input-border-color: #d1d5db;
|
|
@@ -260,6 +280,7 @@ vi-input {
|
|
|
260
280
|
#### Snippets
|
|
261
281
|
|
|
262
282
|
**Basic Text & Password Inputs:**
|
|
283
|
+
|
|
263
284
|
```html
|
|
264
285
|
<vi-input name="username" placeholder="Enter username"></vi-input>
|
|
265
286
|
|
|
@@ -268,13 +289,9 @@ vi-input {
|
|
|
268
289
|
```
|
|
269
290
|
|
|
270
291
|
**Required with Helper Text & Validation:**
|
|
292
|
+
|
|
271
293
|
```html
|
|
272
|
-
<vi-input
|
|
273
|
-
type="email"
|
|
274
|
-
name="email"
|
|
275
|
-
placeholder="you@vialiq.com"
|
|
276
|
-
required
|
|
277
|
-
>
|
|
294
|
+
<vi-input type="email" name="email" placeholder="you@vialiq.com" required>
|
|
278
295
|
<span slot="helper">We will never share your email address.</span>
|
|
279
296
|
</vi-input>
|
|
280
297
|
```
|
|
@@ -282,26 +299,30 @@ vi-input {
|
|
|
282
299
|
---
|
|
283
300
|
|
|
284
301
|
### Checkbox ([vi-checkbox](./src/checkbox/vi-checkbox.ts))
|
|
302
|
+
|
|
285
303
|
The [ViCheckbox](./src/checkbox/vi-checkbox.ts) is a customizable form-associated checkbox control using SVG graphics for checkmarks and supporting the indeterminate (mixed) validation state.
|
|
286
304
|
|
|
287
305
|
#### Properties & Attributes
|
|
288
|
-
|
|
289
|
-
|
|
|
290
|
-
|
|
|
291
|
-
| `
|
|
292
|
-
| `
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
296
|
-
| `
|
|
297
|
-
| `
|
|
306
|
+
|
|
307
|
+
| Attribute | Property | Type | Default | Description |
|
|
308
|
+
| :-------------- | :-------------- | :------------------------------ | :---------- | :---------------------------------------- |
|
|
309
|
+
| `checked` | `checked` | `boolean` | `false` | Checked state. |
|
|
310
|
+
| `indeterminate` | `indeterminate` | `boolean` | `false` | Indeterminate (mixed) dash state. |
|
|
311
|
+
| `value` | `value` | `string` | `'on'` | Submitted form value. |
|
|
312
|
+
| `name` | `name` | `string` | `''` | Form field identifier. |
|
|
313
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables checkbox toggles. |
|
|
314
|
+
| `required` | `required` | `boolean` | `false` | Makes checking field mandatory. |
|
|
315
|
+
| `status` | `status` | `'default'\|'valid'\|'invalid'` | `'default'` | Controls validation visual border colors. |
|
|
316
|
+
| `size` | `size` | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Controls dimension metrics. |
|
|
298
317
|
|
|
299
318
|
#### Events
|
|
319
|
+
|
|
300
320
|
- `vialiq-change`: Fired on user toggle. Detail: `{ checked: boolean, value: string }`.
|
|
301
321
|
|
|
302
322
|
#### Snippets
|
|
303
323
|
|
|
304
324
|
**Simple Configurations:**
|
|
325
|
+
|
|
305
326
|
```html
|
|
306
327
|
<vi-checkbox name="agree" required>I accept the terms and conditions</vi-checkbox>
|
|
307
328
|
|
|
@@ -309,6 +330,7 @@ The [ViCheckbox](./src/checkbox/vi-checkbox.ts) is a customizable form-associate
|
|
|
309
330
|
```
|
|
310
331
|
|
|
311
332
|
**Indeterminate State (Parent/Child controls):**
|
|
333
|
+
|
|
312
334
|
```html
|
|
313
335
|
<vi-checkbox id="select-all" indeterminate>Select All Modules</vi-checkbox>
|
|
314
336
|
```
|
|
@@ -316,29 +338,33 @@ The [ViCheckbox](./src/checkbox/vi-checkbox.ts) is a customizable form-associate
|
|
|
316
338
|
---
|
|
317
339
|
|
|
318
340
|
### Radio Group & Radio ([vi-radio-group](./src/radio/vi-radio-group.ts) & [vi-radio](./src/radio/vi-radio.ts))
|
|
341
|
+
|
|
319
342
|
The [ViRadioGroup](./src/radio/vi-radio-group.ts) and [ViRadio](./src/radio/vi-radio.ts) work in tandem. The group container handles form-association, propagation of attributes (`name`, `disabled`, `size`), roving tabindexes, and WAI-ARIA compliant keyboard navigation via arrow keys.
|
|
320
343
|
|
|
321
344
|
#### `<vi-radio-group>` Properties & Attributes
|
|
322
|
-
|
|
323
|
-
|
|
|
324
|
-
|
|
|
325
|
-
| `
|
|
326
|
-
| `
|
|
327
|
-
| `
|
|
328
|
-
| `
|
|
329
|
-
| `
|
|
330
|
-
| `
|
|
331
|
-
| `
|
|
332
|
-
| `
|
|
345
|
+
|
|
346
|
+
| Attribute | Property | Type | Default | Description |
|
|
347
|
+
| :--------------------- | :------------------- | :------------------------------ | :----------- | :--------------------------------------------- |
|
|
348
|
+
| `value` | `value` | `string` | `''` | Selection value. |
|
|
349
|
+
| `name` | `name` | `string` | `''` | Shared name propagated to children. |
|
|
350
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables entire selection array. |
|
|
351
|
+
| `required` | `required` | `boolean` | `false` | Marks group validation as mandatory. |
|
|
352
|
+
| `status` | `status` | `'default'\|'valid'\|'invalid'` | `'default'` | Group visual status. |
|
|
353
|
+
| `validity-message` | `validity-message` | `string` | `''` | Helper error label when validation triggers. |
|
|
354
|
+
| `orientation` | `orientation` | `'vertical'\|'horizontal'` | `'vertical'` | Direction grid layout. |
|
|
355
|
+
| `size` | `size` | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Shared size propagated to children. |
|
|
356
|
+
| `allow-dblclick-clear` | `allowDblclickClear` | `boolean` | `false` | Double clicking a selected radio deselects it. |
|
|
333
357
|
|
|
334
358
|
#### `<vi-radio>` Properties & Attributes
|
|
335
|
-
|
|
336
|
-
|
|
|
337
|
-
|
|
|
338
|
-
| `
|
|
359
|
+
|
|
360
|
+
| Attribute | Property | Type | Default | Description |
|
|
361
|
+
| :--------- | :--------- | :-------- | :------ | :--------------------------- |
|
|
362
|
+
| `value` | `value` | `string` | `''` | Value this radio represents. |
|
|
363
|
+
| `checked` | `checked` | `boolean` | `false` | Checked selection status. |
|
|
339
364
|
| `disabled` | `disabled` | `boolean` | `false` | Local disable flag override. |
|
|
340
365
|
|
|
341
366
|
#### Slots (`<vi-radio-group>`)
|
|
367
|
+
|
|
342
368
|
- **Default Slot**: Holds the list of `<vi-radio>` child tags.
|
|
343
369
|
- **`label` Slot**: Legend label displayed above the list.
|
|
344
370
|
- **`helper` Slot**: Support text shown below the components.
|
|
@@ -346,6 +372,7 @@ The [ViRadioGroup](./src/radio/vi-radio-group.ts) and [ViRadio](./src/radio/vi-r
|
|
|
346
372
|
#### Snippets
|
|
347
373
|
|
|
348
374
|
**Vertical Layout (Default):**
|
|
375
|
+
|
|
349
376
|
```html
|
|
350
377
|
<vi-radio-group name="shipping" value="standard">
|
|
351
378
|
<span slot="label">Choose Shipping Method</span>
|
|
@@ -357,13 +384,9 @@ The [ViRadioGroup](./src/radio/vi-radio-group.ts) and [ViRadio](./src/radio/vi-r
|
|
|
357
384
|
```
|
|
358
385
|
|
|
359
386
|
**Horizontal Layout with Double-Click Clear:**
|
|
387
|
+
|
|
360
388
|
```html
|
|
361
|
-
<vi-radio-group
|
|
362
|
-
name="rating"
|
|
363
|
-
orientation="horizontal"
|
|
364
|
-
size="lg"
|
|
365
|
-
allow-dblclick-clear
|
|
366
|
-
>
|
|
389
|
+
<vi-radio-group name="rating" orientation="horizontal" size="lg" allow-dblclick-clear>
|
|
367
390
|
<span slot="label">Score rating (Double-click to clear)</span>
|
|
368
391
|
<vi-radio value="1">1 Star</vi-radio>
|
|
369
392
|
<vi-radio value="2">2 Stars</vi-radio>
|
|
@@ -376,31 +399,36 @@ The [ViRadioGroup](./src/radio/vi-radio-group.ts) and [ViRadio](./src/radio/vi-r
|
|
|
376
399
|
---
|
|
377
400
|
|
|
378
401
|
### Tooltip ([vi-tooltip](./src/tooltip/vi-tooltip.ts))
|
|
402
|
+
|
|
379
403
|
The [ViTooltip](./src/tooltip/vi-tooltip.ts) manages floating help text. It leverages `@floating-ui/dom` under the hood for collision-detection, auto-flipping, dynamic viewport alignments, and manual trigger controls.
|
|
380
404
|
|
|
381
405
|
#### Properties & Attributes
|
|
382
|
-
|
|
383
|
-
|
|
|
384
|
-
|
|
|
385
|
-
| `
|
|
386
|
-
| `
|
|
387
|
-
| `
|
|
388
|
-
| `
|
|
389
|
-
| `
|
|
390
|
-
| `
|
|
391
|
-
| `
|
|
406
|
+
|
|
407
|
+
| Attribute | Property | Type | Default | Description |
|
|
408
|
+
| :--------------- | :-------------- | :----------------- | :-------------- | :------------------------------------------------------------------------------------------------- |
|
|
409
|
+
| `content` | `content` | `string` | `''` | Plain text tooltip label. Overridden if the `content` slot is populated. |
|
|
410
|
+
| `placement` | `placement` | `TooltipPlacement` | `'top'` | Direction: `top`\|`top-start`\|`top-end`\|`bottom`\|`bottom-start`\|`bottom-end`\|`left`\|`right`. |
|
|
411
|
+
| `trigger` | `trigger` | `TooltipTrigger` | `'hover focus'` | Trigger events: `hover focus`\|`hover`\|`focus`\|`click`. |
|
|
412
|
+
| `delay` | `delay` | `number` | `500` | Wait delay before displaying in ms. |
|
|
413
|
+
| `hide-delay` | `hide-delay` | `number` | `100` | Hide delay after trigger lost in ms. |
|
|
414
|
+
| `max-width` | `max-width` | `number` | `240` | Max width bounds size in pixels. |
|
|
415
|
+
| `disabled` | `disabled` | `boolean` | `false` | Prevents rendering/open operations. |
|
|
416
|
+
| `popper-options` | `popperOptions` | `object` | `{}` | Custom options passed directly to Floating UI's `computePosition`. |
|
|
392
417
|
|
|
393
418
|
#### Slots
|
|
419
|
+
|
|
394
420
|
- **Default Slot**: The target anchor element (e.g. `<vi-button>`).
|
|
395
421
|
- **`content` Slot**: Holds rich interactive HTML content. (When used, automatically updates ARIA parameters from `aria-describedby` to `aria-details` for screen readers).
|
|
396
422
|
|
|
397
423
|
#### Methods
|
|
424
|
+
|
|
398
425
|
- `show()`: Force displays the tooltip pane.
|
|
399
426
|
- `hide(immediate = false)`: Force hides the tooltip pane.
|
|
400
427
|
|
|
401
428
|
#### Snippets
|
|
402
429
|
|
|
403
430
|
**Basic Text Tooltip:**
|
|
431
|
+
|
|
404
432
|
```html
|
|
405
433
|
<vi-tooltip content="Press to permanently remove configuration" placement="right">
|
|
406
434
|
<vi-button variant="danger">Delete Account</vi-button>
|
|
@@ -408,6 +436,7 @@ The [ViTooltip](./src/tooltip/vi-tooltip.ts) manages floating help text. It leve
|
|
|
408
436
|
```
|
|
409
437
|
|
|
410
438
|
**Rich Interactive Content (Aria-Details compliant):**
|
|
439
|
+
|
|
411
440
|
```html
|
|
412
441
|
<vi-tooltip placement="bottom-start" trigger="click">
|
|
413
442
|
<vi-button>View Pricing Plan</vi-button>
|
|
@@ -434,24 +463,17 @@ If you want the tooltip to dynamically choose the absolute best side (e.g., auto
|
|
|
434
463
|
|
|
435
464
|
```html
|
|
436
465
|
<!-- Passing custom autoPlacement middleware via popper-options property -->
|
|
437
|
-
<vi-tooltip
|
|
438
|
-
id="auto-placement-tooltip"
|
|
439
|
-
content="Dynamic placement based on available viewport space"
|
|
440
|
-
>
|
|
466
|
+
<vi-tooltip id="auto-placement-tooltip" content="Dynamic placement based on available viewport space">
|
|
441
467
|
<vi-button>Auto placement</vi-button>
|
|
442
468
|
</vi-tooltip>
|
|
443
469
|
|
|
444
470
|
<script>
|
|
445
471
|
import { autoPlacement, offset, shift } from '@floating-ui/dom';
|
|
446
|
-
|
|
472
|
+
|
|
447
473
|
const tooltip = document.getElementById('auto-placement-tooltip');
|
|
448
474
|
// Configure custom options directly to override default middleware list
|
|
449
475
|
tooltip.popperOptions = {
|
|
450
|
-
middleware: [
|
|
451
|
-
offset(12),
|
|
452
|
-
autoPlacement({ padding: 8 }),
|
|
453
|
-
shift({ padding: 8 })
|
|
454
|
-
]
|
|
476
|
+
middleware: [offset(12), autoPlacement({ padding: 8 }), shift({ padding: 8 })],
|
|
455
477
|
};
|
|
456
478
|
</script>
|
|
457
479
|
```
|
|
@@ -459,16 +481,19 @@ If you want the tooltip to dynamically choose the absolute best side (e.g., auto
|
|
|
459
481
|
---
|
|
460
482
|
|
|
461
483
|
### Icon ([vi-icon](./src/icons/vi-icon.ts))
|
|
484
|
+
|
|
462
485
|
The [ViIcon](./src/icons/vi-icon.ts) component renders named inline SVG elements. It depends on a dynamic map store, registering only the icons utilized in your project to allow bundlers to prune unused assets (tree-shaking).
|
|
463
486
|
|
|
464
487
|
#### Properties & Attributes
|
|
465
|
-
|
|
466
|
-
|
|
|
467
|
-
|
|
|
468
|
-
| `
|
|
469
|
-
| `
|
|
488
|
+
|
|
489
|
+
| Attribute | Property | Type | Default | Description |
|
|
490
|
+
| :-------- | :------- | :------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------- |
|
|
491
|
+
| `name` | `name` | `string` | `''` | Name identifier inside the registry. |
|
|
492
|
+
| `size` | `size` | `number` | `24` | Width/height footprint dimension in pixels. |
|
|
493
|
+
| `label` | `label` | `string` | `''` | Accessibility label. When set, renders as an interactive image with `role="img"`. When empty, marks element as `aria-hidden="true"`. |
|
|
470
494
|
|
|
471
495
|
#### Icon Registration API
|
|
496
|
+
|
|
472
497
|
Before rendering `<vi-icon>`, you must register the required icon definitions using the [registerIcons](./src/icons/registry.ts) function:
|
|
473
498
|
|
|
474
499
|
```ts
|
|
@@ -480,11 +505,12 @@ import { settingsIcon } from '@vialiq/icons/settings';
|
|
|
480
505
|
registerIcons([checkIcon, settingsIcon]);
|
|
481
506
|
```
|
|
482
507
|
|
|
483
|
-
|
|
508
|
+
_Note: For security, `registerIcons` includes internal sanity checks that filter out inline `<script>` tags or event handlers (e.g. `onload=`) to prevent XSS exploits._
|
|
484
509
|
|
|
485
510
|
#### Snippets
|
|
486
511
|
|
|
487
512
|
**Usage Example:**
|
|
513
|
+
|
|
488
514
|
```html
|
|
489
515
|
<!-- Decorative usage (aria-hidden is true) -->
|
|
490
516
|
<vi-icon name="check" size="20"></vi-icon>
|
|
@@ -493,6 +519,89 @@ registerIcons([checkIcon, settingsIcon]);
|
|
|
493
519
|
<vi-icon name="settings" size="32" label="Open workspace settings"></vi-icon>
|
|
494
520
|
```
|
|
495
521
|
|
|
522
|
+
### Modal ([vi-modal](./src/modal/vi-modal.ts))
|
|
523
|
+
|
|
524
|
+
The [ViModal](./src/modal/vi-modal.ts) is a focus-trapping dialog that dynamically teleports itself to `document.body` to guarantee stacking context above all other elements. It supports multiple layout variants (default, drawer, alert), draggable boundaries, resize handles, and stacking multiple modals automatically using an internal OverlayManager.
|
|
525
|
+
|
|
526
|
+
#### Properties & Attributes
|
|
527
|
+
|
|
528
|
+
| Attribute | Property | Type | Default | Description |
|
|
529
|
+
| :----------------- | :---------------- | :--------------------------------------------------------- | :---------- | :------------------------------------------------------------------------ |
|
|
530
|
+
| `open` | `open` | `boolean` | `false` | Controls the visibility of the modal. |
|
|
531
|
+
| `variant` | `variant` | `'default'\|'drawer'\|'alert'` | `'default'` | Core layout mode. |
|
|
532
|
+
| `size` | `size` | `'xs'\|'sm'\|'md'\|'lg'\|'xl'\|'full-width'\|'fullscreen'` | `'md'` | Dialog dimensions. |
|
|
533
|
+
| `position` | `position` | `'center'\|'top'\|'bottom'\|'left'\|'right'\|...` | `'center'` | Screen positioning for default variant. |
|
|
534
|
+
| `persistent` | `persistent` | `boolean` | `false` | Prevent closing on backdrop click or Escape key (triggers shake instead). |
|
|
535
|
+
| `no-backdrop` | `no-backdrop` | `boolean` | `false` | Hides the backdrop overlay and allows background interaction (modeless). |
|
|
536
|
+
| `draggable` | `draggable` | `boolean` | `false` | Allows dragging the modal by its header. |
|
|
537
|
+
| `resizable` | `resizable` | `boolean` | `false` | Adds 8-point resize handles to the modal edges. |
|
|
538
|
+
| `scrollable` | `scrollable` | `boolean` | `true` | Body content scrolls while header/footer stay fixed. |
|
|
539
|
+
| `drawer-placement` | `drawerPlacement` | `'left'\|'right'` | `'right'` | Edge attachment for the drawer variant. |
|
|
540
|
+
| `append-to` | `appendTo` | `string\|HTMLElement` | `'body'` | Selector or Element to teleport the modal into. |
|
|
541
|
+
|
|
542
|
+
#### Slots
|
|
543
|
+
|
|
544
|
+
- **Default Slot**: The main body content.
|
|
545
|
+
- **`header` Slot**: Overrides the title text.
|
|
546
|
+
- **`header-actions` Slot**: Insert custom buttons next to close/maximize.
|
|
547
|
+
- **`footer` Slot**: Bottom action bar content.
|
|
548
|
+
- **`icon` Slot**: (Alert variant only) Override the default status icon.
|
|
549
|
+
|
|
550
|
+
#### Events
|
|
551
|
+
|
|
552
|
+
- `vi-modal-before-open`: Fires immediately on `open=true` (cancelable).
|
|
553
|
+
- `vi-modal-open`: Fires as the modal begins opening.
|
|
554
|
+
- `vi-modal-after-open`: Fires after enter animations complete.
|
|
555
|
+
- `vi-modal-before-close`: Fires immediately on `open=false` (cancelable). Detail: `{ reason: string }`
|
|
556
|
+
- `vi-modal-close`: Fires as the modal begins closing. Detail: `{ reason: string }`
|
|
557
|
+
- `vi-modal-after-close`: Fires after exit animations complete and modal is removed.
|
|
558
|
+
- `vi-modal-request-close`: Fires when user attempts to close via backdrop/escape. Detail: `{ reason: 'escape' \| 'backdrop' }`
|
|
559
|
+
|
|
560
|
+
#### Snippets
|
|
561
|
+
|
|
562
|
+
**Standard Modal:**
|
|
563
|
+
|
|
564
|
+
```html
|
|
565
|
+
<vi-modal>
|
|
566
|
+
<vi-modal-header slot="header" closable>Title</vi-modal-header>
|
|
567
|
+
<p>Content</p>
|
|
568
|
+
<vi-modal-footer slot="footer">
|
|
569
|
+
<vi-button>Save</vi-button>
|
|
570
|
+
</vi-modal-footer>
|
|
571
|
+
</vi-modal>
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
**Draggable & Resizable Modeless Dialog:**
|
|
575
|
+
|
|
576
|
+
```html
|
|
577
|
+
<vi-modal no-backdrop draggable resizable position="bottom-right">
|
|
578
|
+
<vi-modal-header slot="header" closable>Floating Tool</vi-modal-header>
|
|
579
|
+
<p>This modal doesn't block interaction with the page behind it!</p>
|
|
580
|
+
</vi-modal>
|
|
581
|
+
```
|
|
582
|
+
|
|
583
|
+
**Right-Side Drawer:**
|
|
584
|
+
|
|
585
|
+
```html
|
|
586
|
+
<vi-modal variant="drawer" drawer-placement="right" size="sm">
|
|
587
|
+
<vi-modal-header slot="header" closable>Settings</vi-modal-header>
|
|
588
|
+
<p>Drawer contents here...</p>
|
|
589
|
+
</vi-modal>
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
**Destructive Alert:**
|
|
593
|
+
|
|
594
|
+
```html
|
|
595
|
+
<vi-modal variant="alert" persistent>
|
|
596
|
+
<vi-modal-header slot="header" alert-variant="danger" closable>Delete Workspace?</vi-modal-header>
|
|
597
|
+
<p>This action cannot be undone. All data will be permanently lost.</p>
|
|
598
|
+
<vi-modal-footer slot="footer">
|
|
599
|
+
<vi-button variant="ghost">Cancel</vi-button>
|
|
600
|
+
<vi-button variant="danger">Confirm Deletion</vi-button>
|
|
601
|
+
</vi-modal-footer>
|
|
602
|
+
</vi-modal>
|
|
603
|
+
```
|
|
604
|
+
|
|
496
605
|
---
|
|
497
606
|
|
|
498
607
|
## Form Validation & ElementInternals
|
|
@@ -500,20 +609,14 @@ registerIcons([checkIcon, settingsIcon]);
|
|
|
500
609
|
Custom controls inside this library utilize the native browser [ValidityMixin](./src/base/validity-mixin.ts) to integrate with standard `<form>` features like `.elements`, `.checkValidity()`, and `.reportValidity()`.
|
|
501
610
|
|
|
502
611
|
### Handling Submit Validation
|
|
612
|
+
|
|
503
613
|
```html
|
|
504
614
|
<form id="profile-form">
|
|
505
|
-
<vi-input
|
|
506
|
-
type="text"
|
|
507
|
-
name="fullname"
|
|
508
|
-
placeholder="John Doe"
|
|
509
|
-
required
|
|
510
|
-
>
|
|
615
|
+
<vi-input type="text" name="fullname" placeholder="John Doe" required>
|
|
511
616
|
<span slot="helper">Enter your full name.</span>
|
|
512
617
|
</vi-input>
|
|
513
618
|
|
|
514
|
-
<vi-checkbox name="newsletter" required>
|
|
515
|
-
Confirm subscription policy
|
|
516
|
-
</vi-checkbox>
|
|
619
|
+
<vi-checkbox name="newsletter" required> Confirm subscription policy </vi-checkbox>
|
|
517
620
|
|
|
518
621
|
<vi-button type="submit" variant="primary">Submit</vi-button>
|
|
519
622
|
</form>
|
|
@@ -522,7 +625,7 @@ Custom controls inside this library utilize the native browser [ValidityMixin](.
|
|
|
522
625
|
const form = document.getElementById('profile-form');
|
|
523
626
|
form.addEventListener('submit', (e) => {
|
|
524
627
|
e.preventDefault();
|
|
525
|
-
|
|
628
|
+
|
|
526
629
|
// Checks validity for all elements in the form
|
|
527
630
|
if (form.checkValidity()) {
|
|
528
631
|
const formData = new FormData(form);
|
|
@@ -535,6 +638,7 @@ Custom controls inside this library utilize the native browser [ValidityMixin](.
|
|
|
535
638
|
```
|
|
536
639
|
|
|
537
640
|
### Custom Error Reporting
|
|
641
|
+
|
|
538
642
|
Use `setCustomValidity` to configure custom error messages or run manual server-side validation responses:
|
|
539
643
|
|
|
540
644
|
```javascript
|
|
@@ -542,7 +646,7 @@ const emailField = document.querySelector('vi-input[name="email"]');
|
|
|
542
646
|
|
|
543
647
|
emailField.addEventListener('vialiq-change', (e) => {
|
|
544
648
|
const email = e.detail.value;
|
|
545
|
-
|
|
649
|
+
|
|
546
650
|
if (email.endsWith('@forbidden-domain.com')) {
|
|
547
651
|
emailField.setCustomValidity('Registrations from this domain are forbidden.');
|
|
548
652
|
emailField.reportValidity(); // Displays the custom validation message tooltip
|
|
@@ -559,6 +663,7 @@ emailField.addEventListener('vialiq-change', (e) => {
|
|
|
559
663
|
Web Components utilize CSS Shadow Roots to encapsulate logic and layout styles. To override designs safely without bleeding global configurations, use **CSS Shadow Parts** or **CSS Variables**.
|
|
560
664
|
|
|
561
665
|
### CSS Shadow Parts (`::part`)
|
|
666
|
+
|
|
562
667
|
Elements expose internal sub-nodes through the `part="..."` syntax. Customize these nodes using the CSS `::part()` selector:
|
|
563
668
|
|
|
564
669
|
```css
|
|
@@ -580,6 +685,7 @@ vi-checkbox::part(box) {
|
|
|
580
685
|
```
|
|
581
686
|
|
|
582
687
|
### CSS Variables Custom Properties
|
|
688
|
+
|
|
583
689
|
For variables used repeatedly, custom elements offer direct CSS property bindings. Customize them globally or on single layouts:
|
|
584
690
|
|
|
585
691
|
```css
|
|
@@ -617,6 +723,174 @@ npx nx run web-components:storybook
|
|
|
617
723
|
npx nx run web-components:test-wdio
|
|
618
724
|
```
|
|
619
725
|
|
|
726
|
+
---
|
|
727
|
+
|
|
728
|
+
### Badge ([vi-badge](./src/badge/vi-badge.ts))
|
|
729
|
+
|
|
730
|
+
The `<vi-badge>` is a compact inline indicator used to communicate status, category, or count. It supports various color semantics, sizes, pill vs. square shapes, dot-only mode, and numeric count capping.
|
|
731
|
+
|
|
732
|
+
#### Properties & Attributes
|
|
733
|
+
|
|
734
|
+
| Attribute | Property | Type | Default | Description |
|
|
735
|
+
| :---------- | :--------- | :------------------------------------------------------------- | :---------- | :---------------------------------------------------------------------- |
|
|
736
|
+
| `variant` | `variant` | `'neutral'\|'primary'\|'success'\|'warning'\|'danger'\|'info'` | `'neutral'` | Color semantic. |
|
|
737
|
+
| `size` | `size` | `'sm'\|'md'\|'lg'` | `'md'` | Size of the badge. |
|
|
738
|
+
| `dot` | `dot` | `boolean` | `false` | Renders a small colored dot instead of text. |
|
|
739
|
+
| `pill` | `pill` | `boolean` | `true` | Renders fully rounded ends (pill) vs slightly rounded corners (square). |
|
|
740
|
+
| `count` | `count` | `number` | `undefined` | Numeric count to display. Overrides default slot content. |
|
|
741
|
+
| `show-zero` | `showZero` | `boolean` | `false` | Displays the badge even if the count is zero. |
|
|
742
|
+
| `max` | `max` | `number` | `99` | Max count before showing `{max}+`. |
|
|
743
|
+
| `outline` | `outline` | `boolean` | `false` | Renders the badge with an outline/ghost style. |
|
|
744
|
+
|
|
745
|
+
#### Slots
|
|
746
|
+
|
|
747
|
+
- **Default Slot**: Badge text content (ignored if `count` is set).
|
|
748
|
+
- **`icon` Slot**: Optional leading icon.
|
|
749
|
+
|
|
750
|
+
#### Snippets
|
|
751
|
+
|
|
752
|
+
**Standard Variants:**
|
|
753
|
+
|
|
754
|
+
```html
|
|
755
|
+
<vi-badge variant="neutral">Draft</vi-badge>
|
|
756
|
+
<vi-badge variant="primary">Submitted</vi-badge>
|
|
757
|
+
<vi-badge variant="success">Locked</vi-badge>
|
|
758
|
+
<vi-badge variant="warning">In Review</vi-badge>
|
|
759
|
+
<vi-badge variant="danger">Query Open</vi-badge>
|
|
760
|
+
```
|
|
761
|
+
|
|
762
|
+
**Outlined & Square Styles:**
|
|
763
|
+
|
|
764
|
+
```html
|
|
765
|
+
<vi-badge variant="info" outline>Outline Mode</vi-badge> <vi-badge variant="primary" :pill="false">Square Badge</vi-badge>
|
|
766
|
+
```
|
|
767
|
+
|
|
768
|
+
**Numeric Counts:**
|
|
769
|
+
|
|
770
|
+
```html
|
|
771
|
+
<vi-badge count="5" variant="danger"></vi-badge> <vi-badge count="120" max="99" variant="danger"></vi-badge>
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
**Dot Indicators:**
|
|
775
|
+
|
|
776
|
+
```html
|
|
777
|
+
<vi-badge dot variant="success"></vi-badge>
|
|
778
|
+
```
|
|
779
|
+
|
|
780
|
+
---
|
|
781
|
+
|
|
782
|
+
### Chip & Chip Group ([vi-chip](./src/chip/vi-chip.ts), [vi-chip-group](./src/chip/vi-chip-group.ts))
|
|
783
|
+
|
|
784
|
+
The `<vi-chip>` is an interactive pill-shaped element used for selection, filtering, or categorisation. Chips are usually managed inside a `<vi-chip-group>`, which provides multi-select or single-select logic and arrow-key navigation.
|
|
785
|
+
|
|
786
|
+
#### `<vi-chip>` Properties & Attributes
|
|
787
|
+
|
|
788
|
+
| Attribute | Property | Type | Default | Description |
|
|
789
|
+
| :------------------ | :---------------- | :------------------------------------------------------------- | :---------- | :--------------------------------------------------- |
|
|
790
|
+
| `value` | `value` | `string` | `''` | Value used for selection tracking within a group. |
|
|
791
|
+
| `selected` | `selected` | `boolean` | `false` | Sets the active/selected visual state and checkmark. |
|
|
792
|
+
| `disabled` | `disabled` | `boolean` | `false` | Makes the chip non-interactive. |
|
|
793
|
+
| `removable` | `removable` | `boolean` | `false` | Shows a trailing "×" remove button. |
|
|
794
|
+
| `variant` | `variant` | `'neutral'\|'primary'\|'success'\|'warning'\|'danger'\|'info'` | `'neutral'` | Color semantic. |
|
|
795
|
+
| `size` | `size` | `'sm'\|'md'\|'lg'` | `'md'` | Size of the chip. |
|
|
796
|
+
| `remove-aria-label` | `removeAriaLabel` | `string` | `'Remove'` | Accessible label for the remove button. |
|
|
797
|
+
|
|
798
|
+
**`<vi-chip>` Slots:**
|
|
799
|
+
|
|
800
|
+
- **Default Slot**: Label text content.
|
|
801
|
+
- **`avatar` Slot**: Leading avatar image or initials.
|
|
802
|
+
- **`icon` Slot**: Leading icon (used when no avatar).
|
|
803
|
+
- **`trailing-icon` Slot**: Trailing icon (separate from the remove button).
|
|
804
|
+
|
|
805
|
+
#### `<vi-chip-group>` Properties & Attributes
|
|
806
|
+
|
|
807
|
+
| Attribute | Property | Type | Default | Description |
|
|
808
|
+
| :--------- | :--------- | :--------- | :------ | :----------------------------------------------------------- |
|
|
809
|
+
| `value` | `value` | `string[]` | `[]` | Array of currently selected chip values. |
|
|
810
|
+
| `multi` | `multi` | `boolean` | `true` | Allows multiple selections vs. single selection. |
|
|
811
|
+
| `name` | `name` | `string` | `''` | Form field name for native form participation. |
|
|
812
|
+
| `required` | `required` | `boolean` | `false` | Requires at least one chip to be selected for form validity. |
|
|
813
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables all child chips. |
|
|
814
|
+
| `wrap` | `wrap` | `boolean` | `true` | Controls whether chips wrap to the next line. |
|
|
815
|
+
| `gap` | `gap` | `string` | `'8px'` | Gap spacing between chips. |
|
|
816
|
+
|
|
817
|
+
**`<vi-chip-group>` Events:**
|
|
818
|
+
|
|
819
|
+
- `vi-chip-group-change`: Fired when the selection changes (event detail contains `value: string[]`).
|
|
820
|
+
|
|
821
|
+
#### Snippets
|
|
822
|
+
|
|
823
|
+
**Multi-Select Group:**
|
|
824
|
+
|
|
825
|
+
```html
|
|
826
|
+
<vi-chip-group multi name="grades" value='["grade-1"]'>
|
|
827
|
+
<vi-chip value="grade-1">Grade 1</vi-chip>
|
|
828
|
+
<vi-chip value="grade-2">Grade 2</vi-chip>
|
|
829
|
+
<vi-chip value="grade-3" variant="warning">Grade 3</vi-chip>
|
|
830
|
+
<vi-chip value="grade-4" variant="danger">Grade 4</vi-chip>
|
|
831
|
+
</vi-chip-group>
|
|
832
|
+
```
|
|
833
|
+
|
|
834
|
+
**Single-Select Group:**
|
|
835
|
+
|
|
836
|
+
```html
|
|
837
|
+
<vi-chip-group :multi="false" name="visit">
|
|
838
|
+
<vi-chip value="1" variant="primary">Visit 1</vi-chip>
|
|
839
|
+
<vi-chip value="2" variant="primary">Visit 2</vi-chip>
|
|
840
|
+
</vi-chip-group>
|
|
841
|
+
```
|
|
842
|
+
|
|
843
|
+
---
|
|
844
|
+
|
|
845
|
+
---
|
|
846
|
+
|
|
847
|
+
---
|
|
848
|
+
|
|
849
|
+
### Switch ([vi-switch](./src/switch/vi-switch.ts))
|
|
850
|
+
|
|
851
|
+
The `<vi-switch>` component is a form-associated toggle switch used for boolean settings. It supports size variants, custom label placements, and native HTML form participation.
|
|
852
|
+
|
|
853
|
+
#### Properties & Attributes
|
|
854
|
+
|
|
855
|
+
| Attribute | Property | Type | Default | Description |
|
|
856
|
+
| :---------------- | :--------------- | :----------------- | :------ | :---------------------------------------------------- |
|
|
857
|
+
| `checked` | `checked` | `boolean` | `false` | Checked state of the switch. |
|
|
858
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables the switch. |
|
|
859
|
+
| `size` | `size` | `'sm'\|'md'\|'lg'` | `'md'` | Visual size scale. |
|
|
860
|
+
| `label-placement` | `labelPlacement` | `'start'\|'end'` | `'end'` | Placement of the label relative to the switch toggle. |
|
|
861
|
+
| `name` | `name` | `string` | `''` | Form field name. |
|
|
862
|
+
| `value` | `value` | `string` | `'on'` | Form submission value when checked. |
|
|
863
|
+
|
|
864
|
+
**Slots:**
|
|
865
|
+
|
|
866
|
+
- **Default Slot**: Label text/content.
|
|
867
|
+
- **`on-label` Slot**: Optional text displayed inside the track when checked.
|
|
868
|
+
- **`off-label` Slot**: Optional text displayed inside the track when unchecked.
|
|
869
|
+
|
|
870
|
+
**Events:**
|
|
871
|
+
|
|
872
|
+
- `vi-switch-change`: Fires when the user toggles the checked state. (Detail: `{ checked: boolean }`).
|
|
873
|
+
|
|
874
|
+
#### Snippets
|
|
875
|
+
|
|
876
|
+
**Basic Usage:**
|
|
877
|
+
|
|
878
|
+
```html
|
|
879
|
+
<vi-switch>Enable Notifications</vi-switch>
|
|
880
|
+
<vi-switch checked>Marketing Emails</vi-switch>
|
|
881
|
+
<vi-switch disabled>Disabled Toggle</vi-switch>
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
**Custom Label Placement & Sizes:**
|
|
885
|
+
|
|
886
|
+
```html
|
|
887
|
+
<!-- Label to the left of the switch -->
|
|
888
|
+
<vi-switch label-placement="start" size="lg">Auto-save</vi-switch>
|
|
889
|
+
<vi-switch size="sm">Compact Mode</vi-switch>
|
|
890
|
+
```
|
|
891
|
+
|
|
892
|
+
---
|
|
893
|
+
|
|
620
894
|
## Storybook
|
|
621
895
|
|
|
622
896
|
The project uses **Storybook 10** with the `@storybook/web-components-vite` framework.
|