@arche-mc2/vue-ui-lib 1.2.40 → 1.2.44

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,4 +1,500 @@
1
- ## Librairie de composants vuejs
2
-
3
- Librairie de composants vuejs
4
- Technos utilisées : Vue 3 + TypeScript + Vite
1
+ # @arche-mc2/vue-ui-lib
2
+
3
+ Bibliothèque de composants UI Vue 3 + TypeScript.
4
+
5
+ **Stack :** Vue 3 · TypeScript · Vite · SCSS · Storybook 9
6
+
7
+ ---
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ yarn add @arche-mc2/vue-ui-lib
13
+ # ou
14
+ npm install @arche-mc2/vue-ui-lib
15
+ ```
16
+
17
+ ## Setup
18
+
19
+ Dans `main.ts`, importer les styles et initialiser le système de toast :
20
+
21
+ ```ts
22
+ import { createApp } from 'vue'
23
+ import '@arche-mc2/vue-ui-lib/dist/vue-ui-lib.css'
24
+ import { provideToast } from '@arche-mc2/vue-ui-lib'
25
+ import App from './App.vue'
26
+
27
+ const app = createApp(App)
28
+ provideToast(app) // requis pour les toasts
29
+ app.mount('#app')
30
+ ```
31
+
32
+ Placer `<ToastBase />` une seule fois dans `App.vue` :
33
+
34
+ ```html
35
+ <template>
36
+ <RouterView />
37
+ <ToastBase />
38
+ </template>
39
+ ```
40
+
41
+ ## Utilisation
42
+
43
+ ```ts
44
+ import { ButtonBase, InputBase, SelectBase } from '@arche-mc2/vue-ui-lib'
45
+ import type { Option, ButtonTypes, IconName } from '@arche-mc2/vue-ui-lib'
46
+ ```
47
+
48
+ ---
49
+
50
+ ## Composants disponibles (23)
51
+
52
+ | Composant | Description |
53
+ |-----------|-------------|
54
+ | [ButtonBase](#buttonbase) | Bouton avec variantes, icône, loader |
55
+ | [InputBase](#inputbase) | Input texte/date/password/search avec label flottant |
56
+ | [SelectBase](#selectbase) | Dropdown mono/multi-sélection |
57
+ | [CheckboxBase](#checkboxbase) | Case à cocher avec état indéterminé |
58
+ | [RadioBase](#radiobase) | Bouton radio |
59
+ | [ToggleBase](#togglebase) | Interrupteur on/off |
60
+ | [ToggleAdvanced](#toggleadvanced) | Interrupteur 2 boutons gauche/droite |
61
+ | [SegmentedButton](#segmentedbutton) | Bouton 3 positions (gauche/centre/droite) |
62
+ | [ModalBase](#modalbase) | Modale avec titre et overlay |
63
+ | [ToastBase](#toastbase--usetoast) | Notifications (système inject/provide) |
64
+ | [TooltipBase](#tooltipbase) | Tooltip au survol |
65
+ | [FlyoutMenu](#flyoutmenu) | Menu contextuel positionné |
66
+ | [SideMenu](#sidemenu) | Menu latéral hiérarchique |
67
+ | [TabBar](#tabbar) | Barre d'onglets |
68
+ | [DataGrid](#datagrid) | Grille de données avancée |
69
+ | [WidgetBase](#widgetbase) | Carte conteneur avec slots |
70
+ | [CalendarBase](#calendarbase) | Calendrier (FullCalendar) |
71
+ | [DatePicker](#datepicker) | Sélecteur de date |
72
+ | [SvgIcon](#svgicon) | Icône SVG (532 icônes) |
73
+ | [LoaderBase](#loaderbase) | Indicateur de chargement |
74
+ | [TagBase](#tagbase) | Badge coloré |
75
+ | [ListWithSearch](#listwithsearch) | Liste filtrée avec recherche |
76
+ | [SelectionGroup](#selectiongroup) | Tags de sélection avec débordement |
77
+
78
+ ---
79
+
80
+ ## API des composants
81
+
82
+ ### ButtonBase
83
+
84
+ ```html
85
+ <ButtonBase type="primary" @click="save">Enregistrer</ButtonBase>
86
+ <ButtonBase type="secondary" icon-name="plus" :loading="isSaving">Ajouter</ButtonBase>
87
+ ```
88
+
89
+ | Prop | Type | Défaut | Description |
90
+ |------|------|--------|-------------|
91
+ | `type` | `ButtonTypes` | `'primary'` | Variante visuelle |
92
+ | `iconName` | `IconName` | — | Icône à gauche du texte |
93
+ | `loading` | `boolean` | — | Affiche un loader |
94
+ | `disabled` | `boolean` | — | Désactive le bouton |
95
+ | `active` | `boolean` | — | État actif |
96
+ | `id` | `string` | — | Attribut id HTML |
97
+ | `inert` | `boolean` | — | Attribut inert HTML |
98
+
99
+ **Slot :** `default`
100
+
101
+ **`ButtonTypes` :** `'primary'` `'primary-pink'` `'secondary'` `'secondary-pink'` `'action1'`…`'action7'`
102
+
103
+ ---
104
+
105
+ ### InputBase
106
+
107
+ ```html
108
+ <InputBase v-model="name" label="Nom" />
109
+ <InputBase v-model="search" type="search" icon-name="search" clearable />
110
+ <InputBase v-model="pass" type="password" label="Mot de passe" password-control />
111
+ <InputBase v-model="date" type="date" label="Date de naissance" />
112
+ <InputBase v-model="email" type="email" label="Email" :error="true" error-message="Email invalide" required />
113
+ ```
114
+
115
+ | Prop | Type | Défaut | Description |
116
+ |------|------|--------|-------------|
117
+ | `modelValue` | `string \| number` | — | Valeur (v-model) |
118
+ | `label` | `string` | — | Label flottant |
119
+ | `type` | `'text'\|'number'\|'time'\|'search'\|'email'\|'password'\|'tel'\|'url'\|'date'` | `'text'` | Type d'input |
120
+ | `iconName` | `IconName` | — | Icône |
121
+ | `clearable` | `boolean` | — | Bouton de vidage |
122
+ | `passwordControl` | `boolean` | — | Bouton afficher/masquer |
123
+ | `disabled` | `boolean` | — | — |
124
+ | `error` | `boolean` | — | État d'erreur |
125
+ | `errorMessage` | `string` | — | Message sous le champ |
126
+ | `required` | `boolean` | — | Badge "Requis" |
127
+ | `placeholder` | `string` | — | — |
128
+ | `suggestions` | `Option[]` | — | Autocomplete |
129
+
130
+ **Événement :** `update:modelValue`
131
+
132
+ > Le type `date` intègre un masque `dd/mm/yyyy` et un DatePicker popup automatique.
133
+
134
+ ---
135
+
136
+ ### SelectBase
137
+
138
+ ```ts
139
+ const selected = ref<Option[]>([])
140
+ const options = [{ value: 'fr', label: 'France' }, { value: 'de', label: 'Allemagne' }]
141
+ ```
142
+ ```html
143
+ <SelectBase v-model="selected" :options="options" label="Pays" placeholder="Choisir..." />
144
+ <SelectBase v-model="tags" :options="tagOpts" label="Tags" multiple searchable />
145
+ ```
146
+
147
+ | Prop | Type | Défaut | Description |
148
+ |------|------|--------|-------------|
149
+ | `modelValue` | `Option[]` | requis | Sélection (v-model) — toujours un tableau |
150
+ | `options` | `Option[]` | requis | Options disponibles |
151
+ | `label` | `string` | — | Label flottant |
152
+ | `placeholder` | `string` | — | — |
153
+ | `multiple` | `boolean` | — | Multi-sélection |
154
+ | `searchable` | `boolean` | — | Filtre par recherche |
155
+ | `clearable` | `boolean` | `true` | Suppression des tags |
156
+ | `disabled` | `boolean` | — | — |
157
+
158
+ ---
159
+
160
+ ### CheckboxBase
161
+
162
+ ```html
163
+ <CheckboxBase v-model="accepted" label="J'accepte les CGU" />
164
+ <CheckboxBase v-model="allSelected" :indeterminate="isPartial" />
165
+ ```
166
+
167
+ | Prop | Type | Défaut |
168
+ |------|------|--------|
169
+ | `modelValue` | `boolean` | `false` |
170
+ | `label` | `string` | — |
171
+ | `indeterminate` | `boolean` | — |
172
+ | `disabled` | `boolean` | — |
173
+ | `icon` | `IconName` | — |
174
+ | `theme` | `{--amc2-checkbox-color?, --amc2-checkmark-color?, ...}` | — |
175
+
176
+ ---
177
+
178
+ ### RadioBase
179
+
180
+ ```html
181
+ <RadioBase v-model="gender" value="male" label="Homme" />
182
+ <RadioBase v-model="gender" value="female" label="Femme" />
183
+ ```
184
+
185
+ | Prop | Type | Description |
186
+ |------|------|-------------|
187
+ | `modelValue` | `any` | Valeur partagée du groupe (v-model) |
188
+ | `value` | `any` | **Requis** — valeur de cette option |
189
+ | `label` | `string` | — |
190
+ | `disabled` | `boolean` | — |
191
+ | `theme` | `{--amc2-radio-color?, ...}` | — |
192
+
193
+ ---
194
+
195
+ ### ToggleBase
196
+
197
+ ```html
198
+ <ToggleBase v-model="notifications" label="Notifications" />
199
+ ```
200
+
201
+ | Prop | Type | Description |
202
+ |------|------|-------------|
203
+ | `modelValue` | `boolean` | État (v-model) |
204
+ | `label` | `string` | — |
205
+ | `disabled` | `boolean` | — |
206
+ | `theme` | `ToggleTheme` | CSS custom properties de couleurs |
207
+
208
+ ---
209
+
210
+ ### ToggleAdvanced
211
+
212
+ ```html
213
+ <ToggleAdvanced v-model="isListView" label-left="Liste" icon-left="list"
214
+ label-right="Grille" icon-right="grid" />
215
+ ```
216
+
217
+ | Prop | Type | Description |
218
+ |------|------|-------------|
219
+ | `modelValue` | `boolean` | `true` = gauche actif (v-model) |
220
+ | `labelLeft` / `iconLeft` | `string` / `IconName` | Bouton gauche |
221
+ | `labelRight` / `iconRight` | `string` / `IconName` | Bouton droit |
222
+ | `disabled` | `boolean` | — |
223
+ | `theme` | `ToggleTheme` | — |
224
+
225
+ ---
226
+
227
+ ### SegmentedButton
228
+
229
+ ```html
230
+ <SegmentedButton v-model="sortOrder" label-left="A→Z" label-right="Z→A" />
231
+ ```
232
+
233
+ `modelValue` : `'left' | 'center' | 'right'` (défaut : `'center'`)
234
+
235
+ ---
236
+
237
+ ### ModalBase
238
+
239
+ ```html
240
+ <ModalBase :visible="showModal" title="Confirmation" @close="showModal = false">
241
+ <p>Êtes-vous sûr ?</p>
242
+ <ButtonBase @click="confirm">Confirmer</ButtonBase>
243
+ </ModalBase>
244
+ ```
245
+
246
+ | Prop | Type | Description |
247
+ |------|------|-------------|
248
+ | `visible` | `boolean` | **Requis** |
249
+ | `title` | `string` | **Requis** |
250
+ | `additionnal` | `boolean` | Modale secondaire (empilée) |
251
+
252
+ **Événement :** `close` | **Slot :** `default`
253
+
254
+ ---
255
+
256
+ ### ToastBase + useToast
257
+
258
+ ```ts
259
+ import { useToast } from '@arche-mc2/vue-ui-lib'
260
+ const toast = useToast()
261
+
262
+ toast.show('Enregistré !', 'success')
263
+ toast.show('Erreur réseau', 'error', 5000) // 3ème arg = durée ms
264
+ toast.show('Info disponible', 'info')
265
+ toast.show('Données incomplètes', 'warning')
266
+ ```
267
+
268
+ Intents : `'success'` · `'warning'` · `'error'` · `'info'`
269
+
270
+ ---
271
+
272
+ ### TooltipBase
273
+
274
+ ```html
275
+ <TooltipBase position="top">
276
+ <ButtonBase>Supprimer</ButtonBase>
277
+ <template #content>Action irréversible</template>
278
+ </TooltipBase>
279
+ ```
280
+
281
+ | Prop | Type | Défaut | Description |
282
+ |------|------|--------|-------------|
283
+ | `position` | `Position` | `'bottom'` | `top\|bottom\|left\|right\|bottom-left` |
284
+ | `removeDelay` | `number` | — | Délai disparition en ms |
285
+ | `style` | `CSSProperties` | — | Styles inline |
286
+
287
+ **Slots :** `default` (déclencheur) · `content` (contenu)
288
+
289
+ ---
290
+
291
+ ### FlyoutMenu
292
+
293
+ ```html
294
+ <!-- Liste d'actions -->
295
+ <FlyoutMenu :items="[{ label: 'Éditer', onClick: edit }]">
296
+ <ButtonBase>Actions</ButtonBase>
297
+ </FlyoutMenu>
298
+
299
+ <!-- Contenu libre -->
300
+ <FlyoutMenu position="bottom-left">
301
+ <SvgIcon icon-name="settings" />
302
+ <template #content><div>Filtres...</div></template>
303
+ </FlyoutMenu>
304
+ ```
305
+
306
+ | Prop | Type | Défaut |
307
+ |------|------|--------|
308
+ | `items` | `FlyoutMenuItem[]` | — |
309
+ | `position` | `Position` | `'bottom'` |
310
+ | `autoClose` | `boolean` | `true` |
311
+
312
+ **Événement :** `close` | **Slots :** `default` · `content`
313
+
314
+ ---
315
+
316
+ ### SideMenu
317
+
318
+ ```ts
319
+ const items: MenuItem[] = [
320
+ { id: 1, label: 'Accueil', icon: 'home', action: () => router.push('/') },
321
+ { id: 2, label: 'Gestion', icon: 'users', children: [
322
+ { id: 3, label: 'Clients', action: () => router.push('/clients') },
323
+ ]},
324
+ ]
325
+ ```
326
+ ```html
327
+ <SideMenu :items="items" :id-selected="activeId" />
328
+ ```
329
+
330
+ ---
331
+
332
+ ### TabBar
333
+
334
+ ```ts
335
+ const tabs = ['Infos', 'Documents', 'Historique']
336
+ const active = ref('Infos')
337
+ ```
338
+ ```html
339
+ <TabBar :list-items="tabs" :list-type="active" @change="active = $event" />
340
+ ```
341
+
342
+ ---
343
+
344
+ ### DataGrid
345
+
346
+ Grille avancée : colonnes configurables, tri, filtre, sélection, scroll infini, menu d'actions.
347
+
348
+ ```ts
349
+ const headers = ref<DatagridHeader[]>([
350
+ {
351
+ key: 'name', label: 'Nom', dataType: 'string', sortable: true,
352
+ visibility: { isShown: true, isDisabled: false, update: (v) => { headers.value[0].visibility.isShown = v } }
353
+ },
354
+ ])
355
+
356
+ const items = ref([
357
+ { id: 1, name: 'Alice', isSelected: false,
358
+ actions: [{ label: 'Éditer', onClick: () => open(1) }] }
359
+ ])
360
+ ```
361
+ ```html
362
+ <DataGrid
363
+ :headers="headers" :items="items" :has-more="hasMore"
364
+ selection
365
+ @load-more="loadMore"
366
+ @update-check-item="(id, v) => toggleItem(id, v)"
367
+ />
368
+ ```
369
+
370
+ **Props principales :**
371
+
372
+ | Prop | Type | Défaut |
373
+ |------|------|--------|
374
+ | `headers` | `DatagridHeader[]` | requis |
375
+ | `items` | `any[]` | requis |
376
+ | `hasMore` | `boolean` | requis |
377
+ | `selection` | `boolean` | `false` |
378
+ | `displaySettingsHeader` | `boolean` | `true` |
379
+ | `displaySettings` | `boolean` | `true` |
380
+ | `modalFilter` | `(header) => void` | — |
381
+ | `dataSort` | `(header) => void` | — |
382
+
383
+ **Événements :** `loadMore` · `updateCheckItem(id, isChecked)` · `updateCheckAll(isChecked)`
384
+
385
+ **Expose :** `resetScroll()` · `checkLoadMore()`
386
+
387
+ **Rendu custom dans une cellule :**
388
+ ```ts
389
+ import { h } from 'vue'
390
+ import { TagBase } from '@arche-mc2/vue-ui-lib'
391
+ items.value = [{ id: 1, status: { render: () => h(TagBase, { label: 'Actif', backgroundColor: 'green' }) } }]
392
+ ```
393
+
394
+ ---
395
+
396
+ ### WidgetBase
397
+
398
+ ```html
399
+ <WidgetBase width="100%" height="250px" :is-loading="loading">
400
+ <template #header><h3>Mon widget</h3></template>
401
+ <template #body><p>Contenu</p></template>
402
+ <template #footer><ButtonBase type="secondary">Voir plus</ButtonBase></template>
403
+ </WidgetBase>
404
+ ```
405
+
406
+ | Prop | Type | Défaut |
407
+ |------|------|--------|
408
+ | `width` | `string` | `'50%'` |
409
+ | `height` | `string` | `'180px'` |
410
+ | `color` | `string` | — |
411
+ | `isLoading` | `boolean` | — |
412
+
413
+ ---
414
+
415
+ ### CalendarBase
416
+
417
+ ```html
418
+ <CalendarBase
419
+ :events="events" initial-view="month" btn-today btn-view-option
420
+ @on-select-date="range => createEvent(range)"
421
+ @on-click-event="event => openEvent(event)"
422
+ />
423
+ ```
424
+
425
+ ```ts
426
+ // Type event
427
+ interface CalendarEvent { id: string; title: string; start: string; end: string }
428
+ ```
429
+
430
+ ---
431
+
432
+ ### DatePicker
433
+
434
+ Principalement utilisé via `InputBase` avec `type="date"`. Usage direct :
435
+
436
+ ```html
437
+ <DatePicker v-model="selectedDate" :min="minDate" :max="maxDate" />
438
+ ```
439
+
440
+ ---
441
+
442
+ ### SvgIcon
443
+
444
+ 532 icônes disponibles (liste via `import { iconNames } from '@arche-mc2/vue-ui-lib'`).
445
+
446
+ ```html
447
+ <SvgIcon icon-name="user" color="#5B4DBE" width="24" height="24" />
448
+ ```
449
+
450
+ | Prop | Type | Défaut |
451
+ |------|------|--------|
452
+ | `iconName` | `IconName` | requis |
453
+ | `color` | `string` | `'#2C2274'` |
454
+ | `colorHover` | `string` | — |
455
+ | `height` / `width` | `string` | `'20'` |
456
+ | `accessibilityTitle` | `string` | — |
457
+
458
+ ---
459
+
460
+ ### LoaderBase
461
+
462
+ ```html
463
+ <LoaderBase :size="30" />
464
+ ```
465
+
466
+ ---
467
+
468
+ ### TagBase
469
+
470
+ ```html
471
+ <TagBase label="Actif" background-color="green" />
472
+ ```
473
+
474
+ `backgroundColor` : `'blue'` · `'green'` · `'primary'` · `'secondary'`
475
+
476
+ ---
477
+
478
+ ## Types TypeScript exportés
479
+
480
+ ```ts
481
+ import type {
482
+ ButtonTypes, IconName, Option, Intent, Position,
483
+ MenuItem, Header, DatagridHeader,
484
+ FlyoutMenuItem, ToggleTheme,
485
+ CalendarEvent, CalendarRange,
486
+ Toast, DayInfo, WeekInfo
487
+ } from '@arche-mc2/vue-ui-lib'
488
+ ```
489
+
490
+ ---
491
+
492
+ ## Développement
493
+
494
+ ```bash
495
+ yarn storybook # Démo interactive http://localhost:6006
496
+ yarn build # Build bibliothèque → dist/
497
+ yarn build-storybook # Build Storybook statique
498
+ ```
499
+
500
+ Voir [storybook-docs.md](./storybook-docs.md) pour le guide complet de contribution et de publication.