@devjuliovilla/jv-ui 1.14.0 → 1.15.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.
Files changed (7) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +1035 -1033
  3. package/fesm2022/devjuliovilla-jv-ui.mjs +3792 -3802
  4. package/fesm2022/devjuliovilla-jv-ui.mjs.map +1 -1
  5. package/package.json +1 -1
  6. package/styles/jv-theme.css +135 -135
  7. package/types/devjuliovilla-jv-ui.d.ts +13 -17
package/README.md CHANGED
@@ -1,1033 +1,1035 @@
1
- # @devjuliovilla/jv-ui
2
-
3
- Accessibility-first Angular component library built with signals and standalone APIs. Includes components, forms, data grids, dialogs, layout primitives, services, and i18n infrastructure.
4
-
5
- ## Installation
6
-
7
- ```bash
8
- npm install @devjuliovilla/jv-ui
9
- ```
10
-
11
- Import the theme CSS in your `angular.json` or `styles` array:
12
-
13
- ```json
14
- "styles": ["@devjuliovilla/jv-ui/styles/jv-theme.css"]
15
- ```
16
-
17
- ## Quick start
18
-
19
- ```typescript
20
- import { ApplicationConfig } from '@angular/core';
21
- import { provideJvUi } from '@devjuliovilla/jv-ui';
22
-
23
- export const appConfig: ApplicationConfig = {
24
- providers: [provideJvUi({ messagesLocale: 'en', formatLocale: 'en-US' })],
25
- };
26
- ```
27
-
28
- ```typescript
29
- import { Component } from '@angular/core';
30
- import { JvButtonComponent } from '@devjuliovilla/jv-ui';
31
-
32
- @Component({
33
- selector: 'app-root',
34
- standalone: true,
35
- imports: [JvButtonComponent],
36
- template: '<jv-button variant="primary">Hello</jv-button>',
37
- })
38
- export class App {}
39
- ```
40
-
41
- ## Components
42
-
43
- | Category | Components |
44
- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
45
- | Buttons | `JvButton`, `JvButtonGroup`, `JvIconButton` |
46
- | Calendar | `JvMonthCalendar`, `JvDayPlanner` — reusable month view and agenda primitives, usable together or independently |
47
- | Forms | `JvInput`, `JvTextarea`, `JvCode`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvDatePicker`, `JvModalSelector`, `JvFileInput`, `JvFormContainer` |
48
- | Data Grid | `JvGrid` — full-featured data table (see below) |
49
- | Containers | `JvCard`, `JvSection`, `JvDivider` |
50
- | List | `JvList`, `JvListItem` — list with title, description, icons, badges, and interactive items |
51
- | Tabs | `JvTabs`, `JvTabPanelDirective` — horizontal tabs with keyboard navigation and animated transitions |
52
- | Slider | `JvImageSlider` — responsive image slider with thumbnails and keyboard navigation |
53
- | Gallery | `JvImageGallery` — horizontal image gallery with wheel scrolling and full-screen viewer |
54
- | Feedback | `JvAlert`, `JvBadge`, `JvLoader`, `JvToast` |
55
- | Dialogs | `JvDialog`, `JvConfirmDialog`, `JvWindowModal` — compact dialogs plus a larger workflow overlay surface |
56
- | Layout | `JvDashboardShell`, `JvSidebar`, `JvTopbar`, `JvBreadcrumb`, `JvPage` |
57
- | Auth Pages | `JvLoginPage`, `JvForgotPasswordPage`, `JvChangePasswordPage` |
58
- | Icon | `JvIcon` — Lucide-based icon component with 1500+ auto-generated icons |
59
- | Pagination | `JvPagination` — standalone pagination with i18n |
60
-
61
- ## Calendar API
62
-
63
- The scheduling primitives are split into **two separate components**:
64
-
65
- - `JvMonthCalendar`: inline month grid with selection, navigation, and day markers
66
- - `JvDayPlanner`: agenda / list view for scheduled items with optional grouping and expandable details
67
-
68
- You can use either one on its own, or compose both together in a master-detail scheduling layout.
69
-
70
- ### JvMonthCalendar
71
-
72
- ```typescript
73
- import {
74
- JvMonthCalendarComponent,
75
- JvMonthCalendarDayDirective,
76
- JvMonthCalendarDayMeta,
77
- } from '@devjuliovilla/jv-ui';
78
- ```
79
-
80
- **Inputs:**
81
-
82
- | Input | Type | Default | Description |
83
- | -------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- |
84
- | `value` | `Date \| string \| null` | `undefined` | Selected day |
85
- | `visibleMonth` | `Date \| string \| null` | `undefined` | Controlled visible month independent from the selected day |
86
- | `dayMeta` | `JvMonthCalendarDayMeta[]` | `[]` | Marker/counter metadata per day |
87
- | `ariaLabel` | `string` | localized default | Accessible label for the grid |
88
- | `monthLabel` | `string` | `Month` | Accessible label for the month selector |
89
- | `yearLabel` | `string` | `Year` | Accessible label for the year selector |
90
- | `minYear` | `number` | current year - 10 | Lower year bound for the year selector |
91
- | `maxYear` | `number` | current year + 10 | Upper year bound for the year selector |
92
- | `navigation` | `{ previousMonth?: boolean; nextMonth?: boolean; previousYear?: boolean; nextYear?: boolean }` | `{ previousMonth: true, nextMonth: true, previousYear: false, nextYear: false }` | Controls which month/year navigation buttons are rendered |
93
-
94
- **Outputs:**
95
-
96
- | Output | Type |
97
- | -------------------- | ------ |
98
- | `selectionChange` | `Date` |
99
- | `visibleMonthChange` | `Date` |
100
-
101
- **Day metadata:**
102
-
103
- | Property | Type | Description |
104
- | -------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
105
- | `date` | `Date \| string` | Day associated with the marker |
106
- | `count` | `number` | Optional numeric badge rendered inside the cell |
107
- | `tone` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'neutral'` | Visual tone for the badge or dot |
108
- | `label` | `string` | Extra accessibility text appended to the day `aria-label` |
109
-
110
- **Template hook:**
111
-
112
- Use `ng-template[jvMonthCalendarDay]` to fully customize the day cell.
113
-
114
- **Standalone example:**
115
-
116
- ```typescript
117
- import { Component, signal } from '@angular/core';
118
- import { JvMonthCalendarComponent, JvMonthCalendarDayMeta } from '@devjuliovilla/jv-ui';
119
-
120
- @Component({
121
- selector: 'app-calendar-only',
122
- standalone: true,
123
- imports: [JvMonthCalendarComponent],
124
- template: `
125
- <jv-month-calendar
126
- [value]="selectedDate()"
127
- [dayMeta]="calendarMeta"
128
- (selectionChange)="selectedDate.set($event)"
129
- />
130
- `,
131
- })
132
- export class CalendarOnlyComponent {
133
- readonly selectedDate = signal(new Date(2026, 5, 15));
134
- readonly calendarMeta: JvMonthCalendarDayMeta[] = [
135
- { date: '2026-06-15', count: 2, tone: 'primary', label: '2 activities' },
136
- { date: '2026-06-16', count: 1, tone: 'secondary', label: '1 activity' },
137
- ];
138
- }
139
- ```
140
-
141
- ### JvDayPlanner
142
-
143
- ```typescript
144
- import {
145
- JvDayPlannerComponent,
146
- JvDayPlannerDetailDirective,
147
- JvDayPlannerItem,
148
- JvDayPlannerItemDirective,
149
- } from '@devjuliovilla/jv-ui';
150
- ```
151
-
152
- **Inputs:**
153
-
154
- | Input | Type | Default | Description |
155
- | ------------------------ | ---------------------- | ----------------- | ---------------------------------------- |
156
- | `items` | `JvDayPlannerItem[]` | `[]` | Agenda items |
157
- | `groupByDate` | `boolean` | `false` | Group items under a date heading |
158
- | `emptyMessage` | `string` | localized default | Empty state copy |
159
- | `ariaLabel` | `string` | localized default | Accessible label for the agenda |
160
- | `defaultExpandedItemIds` | `(string \| number)[]` | `[]` | Items whose detail should start expanded |
161
-
162
- **Outputs:**
163
-
164
- | Output | Type |
165
- | ------------ | ------------------ |
166
- | `itemSelect` | `JvDayPlannerItem` |
167
-
168
- **Planner item shape:**
169
-
170
- | Property | Type | Description |
171
- | ------------- | ------------------------ | ----------------------------------------- |
172
- | `id` | `string \| number` | Stable identity |
173
- | `title` | `string` | Primary label |
174
- | `date` | `Date \| string \| null` | Logical day when start time is not enough |
175
- | `start` | `Date \| string \| null` | Optional start datetime |
176
- | `end` | `Date \| string \| null` | Optional end datetime |
177
- | `status` | `string` | Status badge label |
178
- | `statusTone` | `JvTone` | Visual tone for status badge |
179
- | `type` | `string` | Type/category badge label |
180
- | `typeTone` | `JvTone` | Visual tone for type badge |
181
- | `responsible` | `string` | Responsible person |
182
- | `location` | `string` | Location metadata |
183
- | `details` | `string` | Expandable detail text |
184
- | `completed` | `boolean` | Reduced emphasis for completed items |
185
-
186
- **Template hooks:**
187
-
188
- - `ng-template[jvDayPlannerItem]` customizes the visible item row
189
- - `ng-template[jvDayPlannerDetail]` customizes the expanded detail panel
190
-
191
- **Standalone example:**
192
-
193
- ```typescript
194
- import { Component } from '@angular/core';
195
- import { JvDayPlannerComponent, JvDayPlannerItem } from '@devjuliovilla/jv-ui';
196
-
197
- @Component({
198
- selector: 'app-planner-only',
199
- standalone: true,
200
- imports: [JvDayPlannerComponent],
201
- template: `
202
- <jv-day-planner [items]="items" [groupByDate]="true" (itemSelect)="handleSelect($event)" />
203
- `,
204
- })
205
- export class PlannerOnlyComponent {
206
- readonly items: JvDayPlannerItem[] = [
207
- {
208
- id: 1,
209
- title: 'Venue setup',
210
- start: '2026-06-15T08:30:00',
211
- end: '2026-06-15T10:00:00',
212
- status: 'Scheduled',
213
- statusTone: 'primary',
214
- type: 'Logistics',
215
- responsible: 'Ana Lopez',
216
- location: 'Main hall',
217
- details: 'Prepare seating and signage.',
218
- },
219
- ];
220
-
221
- handleSelect(item: JvDayPlannerItem) {
222
- console.log(item);
223
- }
224
- }
225
- ```
226
-
227
- ### Combined example
228
-
229
- Use both components together when you need a left-side month selector and a right-side agenda:
230
-
231
- ```html
232
- <jv-month-calendar
233
- [value]="selectedDate()"
234
- [dayMeta]="calendarMeta()"
235
- (selectionChange)="selectedDate.set($event)"
236
- />
237
-
238
- <jv-day-planner
239
- [items]="filteredItems()"
240
- [groupByDate]="showAll()"
241
- (itemSelect)="selectedItem.set($event)"
242
- />
243
- ```
244
-
245
- ## Grid Features
246
-
247
- | Feature | Description |
248
- | ------------------ | ---------------------------------------------------------------- |
249
- | Sorting | Client-side multi-column sorting with sort icons and `aria-sort` |
250
- | Search | Global text search across visible columns |
251
- | Pagination | Configurable page size, page range buttons, first/last/prev/next |
252
- | Selection | Checkbox row selection with `selectedIds` / `selectionChange` |
253
- | Row actions | Custom action buttons per row |
254
- | Density modes | Compact, normal, comfortable |
255
- | Sticky columns | Pin columns to left or right |
256
- | Column resizing | Drag column header borders to resize |
257
- | Column reordering | Drag & drop column headers |
258
- | Grouped headers | Multi-row header with `colspan` via `children` |
259
- | Per-column filters | Filter input row with operators |
260
- | Inline editing | Double-click or Enter to edit: text, number, select, boolean |
261
- | Virtual scrolling | Render only visible rows for large datasets |
262
- | CSV/Excel export | Built-in toolbar buttons, no external deps |
263
- | Server-side mode | Delegate sort/filter/page to parent component |
264
- | TrackBy | Custom trackBy key or function |
265
- | i18n | All labels configurable via translation dictionary |
266
-
267
- ### Grid API
268
-
269
- ```typescript
270
- import { JvGridComponent } from '@devjuliovilla/jv-ui';
271
- ```
272
-
273
- **Inputs:**
274
-
275
- | Input | Type | Default | Description |
276
- | ------------- | ----------------------------- | ------- | -------------------------- |
277
- | `data` | `T[]` | `[]` | Row data array |
278
- | `columns` | `JvGridColumn<T>[]` | `[]` | Column definitions |
279
- | `actions` | `JvGridAction<T>[]` | `[]` | Row action button configs |
280
- | `options` | `Partial<JvGridOptions>` | `{}` | Feature toggles and config |
281
- | `trackBy` | `keyof T \| Function \| null` | `null` | Row identity |
282
- | `selectedIds` | `(string \| number)[]` | `[]` | Controlled selection IDs |
283
-
284
- **Outputs:**
285
-
286
- | Output | Type |
287
- | ----------------- | ----------------------------------------------------------- |
288
- | `rowClick` | `T` |
289
- | `rowDoubleClick` | `T` |
290
- | `actionClick` | `{ actionId: string; row: T }` |
291
- | `selectionChange` | `(string \| number)[]` |
292
- | `pageChange` | `{ pageIndex: number; pageSize: number }` |
293
- | `searchChange` | `string` |
294
- | `sortChange` | `{ columnKey: string; direction: 'asc' \| 'desc' \| null }` |
295
- | `columnFilter` | `{ columnKey: string; value: string }` |
296
- | `columnResize` | `{ columnKey: string; width: string }` |
297
- | `columnReorder` | `{ columnKey: string; newIndex: number }` |
298
- | `rowEdit` | `{ row: T; column: JvGridColumn<T>; value: unknown }` |
299
-
300
- **JvGridColumn options:**
301
-
302
- | Property | Type | Description |
303
- | --------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------- |
304
- | `key` | `keyof T \| string` | Data field key |
305
- | `header` | `string` | Column display header |
306
- | `sortable` | `boolean` | Enable column sorting |
307
- | `searchable` | `boolean` | Include in global search |
308
- | `filterable` | `boolean` | Show per-column filter input |
309
- | `hidden` | `boolean` | Hide column from display |
310
- | `sticky` | `'left' \| 'right'` | Pin column position |
311
- | `editable` | `boolean` | Allow inline cell editing |
312
- | `editType` | `'text' \| 'number' \| 'select' \| 'boolean'` | Editor type |
313
- | `editOptions` | `{ label: string; value: unknown }[]` | Options for select editor |
314
- | `width` | `string` | Column width (e.g. '8rem') |
315
- | `align` | `'start' \| 'center' \| 'end'` | Text alignment |
316
- | `type` | `'text' \| 'integer' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'time' \| 'datetime' \| 'boolean'` | Data type for formatting |
317
- | `formatOptions` | `Intl.NumberFormatOptions & Intl.DateTimeFormatOptions` | Per-column formatting overrides |
318
- | `format` | `(value, row) => string` | Custom display formatter |
319
- | `children` | `JvGridColumn<T>[]` | Child columns for grouped headers |
320
- | `resizable` | `boolean` | Allow column resize |
321
- | `cellClass` | `string` | CSS class for cells |
322
- | `headerClass` | `string` | CSS class for header |
323
-
324
- **JvGridOptions:**
325
-
326
- | Option | Type | Default | Description |
327
- | ------------------------ | ---------------------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
328
- | `searchable` | `boolean` | `true` | Show search bar |
329
- | `sortable` | `boolean` | `true` | Enable column sorting |
330
- | `pageable` | `boolean` | `true` | Enable pagination |
331
- | `selectable` | `boolean` | `false` | Show selection checkboxes |
332
- | `pageSize` | `number` | `20` | Default page size |
333
- | `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size selector options |
334
- | `density` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Row density |
335
- | `loading` | `boolean` | `false` | Show loading spinner |
336
- | `emptyMessage` | `string` | — | Empty state message |
337
- | `exportable` | `boolean` | `false` | Show CSV/Excel export buttons |
338
- | `exportFileName` | `string` | `''` | Base filename used for CSV/Excel exports; the component applies the correct extension |
339
- | `serverSide` | `boolean` | `false` | Disable client-side processing |
340
- | `totalItems` | `number` | `0` | Total items for server-side mode |
341
- | `stickyColumns` | `boolean` | `false` | Enable sticky column support |
342
- | `resizableColumns` | `boolean` | `false` | Enable column resizing |
343
- | `reorderableColumns` | `boolean` | `false` | Enable column reordering |
344
- | `editable` | `boolean` | `false` | Enable inline editing |
345
- | `virtualScroll` | `boolean` | `false` | Enable virtual scrolling |
346
- | `virtualScrollRowHeight` | `number` | `48` | Row height for virtual scroll |
347
- | `columnFilters` | `boolean` | `false` | Show filter row below headers |
348
- | `rowDoubleClick` | `boolean` | `false` | Enable row double-click event |
349
- | `keyboardNavigation` | `boolean` | `false` | Enable arrow-key cell navigation and `F2` editing flow |
350
- | `ariaLabel` | `string` | — | Accessible label for the grid |
351
-
352
- ### Grid example
353
-
354
- ```typescript
355
- import { Component } from '@angular/core';
356
- import { JvGridComponent, JvGridColumn, JvGridOptions } from '@devjuliovilla/jv-ui';
357
-
358
- interface Product {
359
- id: number;
360
- name: string;
361
- price: number;
362
- status: string;
363
- }
364
-
365
- @Component({
366
- selector: 'app-products',
367
- standalone: true,
368
- imports: [JvGridComponent],
369
- template: `
370
- <jv-grid
371
- [data]="products"
372
- [columns]="columns"
373
- [options]="{ selectable: true, exportable: true, exportFileName: 'products', pageSize: 10 }"
374
- [trackBy]="'id'"
375
- [selectedIds]="selectedIds"
376
- (selectionChange)="selectedIds = $event"
377
- />
378
- `,
379
- })
380
- export class ProductsComponent {
381
- products: Product[] = [
382
- /* ... */
383
- ];
384
- selectedIds: (string | number)[] = [];
385
- columns: JvGridColumn<Product>[] = [
386
- { key: 'id', header: 'ID', width: '4rem' },
387
- { key: 'name', header: 'Product', sortable: true, filterable: true },
388
- { key: 'price', header: 'Price', type: 'number', align: 'end', format: (v) => '$' + v },
389
- { key: 'status', header: 'Status', sortable: true },
390
- ];
391
- }
392
- ```
393
-
394
- ### Grid behavior notes
395
-
396
- - **Row identity:** when `trackBy` is not provided, rows with an `id` property use that value as their identity. Provide `[trackBy]` when the row identity uses another field or a custom function.
397
- - **Controlled selection:** use `[selectedIds]` together with `(selectionChange)` when the parent owns selection state. The component accepts an empty array, so selection can start fully controlled without special initialization.
398
- - **Pagination:** `pageSize` is clamped to the configured `pageSizeOptions`, and page indexes are clamped when the data or page size changes. Use `(pageChange)` to synchronize server-side pagination.
399
- - **Grouped headers:** define parent columns with `children`. The grouped header is rendered with `colspan`, while sorting, filtering, editing, resizing, reordering, and export operate on the leaf columns.
400
- - **Virtual scrolling:** place the grid inside a container with a constrained height and set `virtualScroll: true`. The default row height is `48`; set `virtualScrollRowHeight` to the actual rendered row height when it differs.
401
- - **Formatting:** column `type` and `formatOptions` affect display only. Sorting and export use the raw field value, not the localized text shown in the cell.
402
- - **Inline editing:** set both `editable: true` in `options` and `editable: true` on the column. `select` editors emit the configured option value, while `boolean` editors emit a boolean. Press `F2` to start, `Enter` to commit, and `Escape` to cancel when keyboard navigation is enabled.
403
-
404
- ### Keyboard navigation example
405
-
406
- ```typescript
407
- const gridOptions: JvGridOptions = {
408
- keyboardNavigation: true,
409
- editable: true,
410
- pageable: false,
411
- };
412
-
413
- const columns: JvGridColumn<Product>[] = [
414
- { key: 'name', header: 'Product', editable: true, editType: 'text' },
415
- {
416
- key: 'status',
417
- header: 'Status',
418
- editable: true,
419
- editType: 'select',
420
- editOptions: [
421
- { label: 'Active', value: 'active' },
422
- { label: 'Paused', value: 'paused' },
423
- ],
424
- },
425
- ];
426
- ```
427
-
428
- ```html
429
- <jv-grid
430
- [data]="products"
431
- [columns]="columns"
432
- [options]="gridOptions"
433
- (rowEdit)="onRowEdit($event)"
434
- />
435
- ```
436
-
437
- With `keyboardNavigation` enabled, arrow keys move between data cells without trapping row action buttons. `Tab` continues to the row actions, `F2` starts editing, `Enter` commits, and `Escape` cancels.
438
-
439
- ## List API
440
-
441
- ```typescript
442
- import { JvListComponent, JvListItemComponent } from '@devjuliovilla/jv-ui';
443
- ```
444
-
445
- **JvList inputs:**
446
-
447
- | Input | Type | Default | Description |
448
- | ----------- | ------------------------ | -------- | ------------------------------------------------------------------------------ |
449
- | `role` | `'list' \| 'navigation'` | `'list'` | ARIA role for the list |
450
- | `variant` | `'bordered' \| null` | `null` | Outer border + border-radius around the list (items always have bottom border) |
451
- | `ariaLabel` | `string` | `''` | Accessible label |
452
-
453
- **JvListItem inputs:**
454
-
455
- | Input | Type | Default | Description |
456
- | ------------- | ------------------- | ------- | -------------------------------------------- |
457
- | `title` | `string` (required) | — | Primary text |
458
- | `description` | `string` | `''` | Secondary text below title |
459
- | `leadingIcon` | `string \| null` | `null` | Lucide icon name on the left |
460
- | `disabled` | `boolean` | `false` | Gray out and block interaction |
461
- | `active` | `boolean` | `false` | Highlight with primary color and left border |
462
-
463
- **JvListItem outputs:**
464
-
465
- | Output | Type |
466
- | ----------- | ------ |
467
- | `activated` | `void` |
468
-
469
- **Content projection:** use the `meta` attribute selector for badges, icons, or any content on the right side:
470
-
471
- ```html
472
- <jv-list-item title="Inbox" description="New messages">
473
- <jv-badge tone="primary" meta>3</jv-badge>
474
- <jv-icon name="chevron-right" meta />
475
- </jv-list-item>
476
- ```
477
-
478
- ### Example
479
-
480
- ```typescript
481
- import { Component } from '@angular/core';
482
- import { JvListComponent, JvListItemComponent, JvBadgeComponent } from '@devjuliovilla/jv-ui';
483
-
484
- @Component({
485
- selector: 'app-nav-list',
486
- standalone: true,
487
- imports: [JvListComponent, JvListItemComponent, JvBadgeComponent],
488
- template: `
489
- <jv-list variant="bordered">
490
- <jv-list-item
491
- title="Dashboard"
492
- description="Main overview"
493
- leadingIcon="layout-dashboard"
494
- [active]="true"
495
- />
496
- <jv-list-item title="Notifications" description="3 pending" (activated)="onOpen()">
497
- <jv-badge tone="primary" meta>3</jv-badge>
498
- </jv-list-item>
499
- <jv-list-item title="Reports" description="Coming soon" [disabled]="true" />
500
- </jv-list>
501
- `,
502
- })
503
- export class NavListComponent {
504
- onOpen() {
505
- /* handle activation */
506
- }
507
- }
508
- ```
509
-
510
- ## Pagination API
511
-
512
- ```typescript
513
- import { JvPaginationComponent } from '@devjuliovilla/jv-ui';
514
- ```
515
-
516
- | Input | Type | Default | Description |
517
- | ----------------- | ---------- | ------------------- | ------------------------ |
518
- | `totalItems` | `number` | `0` | Total items |
519
- | `pageSize` | `number` | `20` | Items per page |
520
- | `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size options |
521
- | `pageIndex` | `number` | `0` | Current page (0-based) |
522
- | `maxVisiblePages` | `number` | `5` | Max page buttons to show |
523
-
524
- | Output | Type |
525
- | ------------ | ----------------------------------------- |
526
- | `pageChange` | `{ pageIndex: number; pageSize: number }` |
527
-
528
- ## Tabs API
529
-
530
- ```typescript
531
- import { JvTabsComponent, JvTabPanelDirective, JvTabItem } from '@devjuliovilla/jv-ui';
532
- ```
533
-
534
- **Inputs:**
535
-
536
- | Input | Type | Default | Description |
537
- | ------------- | ------------------------------------- | ------- | --------------------------------------------------------- |
538
- | `tabs` | `JvTabItem[]` | `[]` | Tab definitions (`{ id, label, icon?, disabled? }`) |
539
- | `activeTabId` | `string \| null` | `null` | Controlled active tab ID |
540
- | `keepMounted` | `boolean` | `true` | Keep all panels in DOM; `false` renders only active panel |
541
- | `transition` | `'none' \| 'fade' \| 'slide' \| null` | `null` | Panel transition animation (falls back to global config) |
542
-
543
- **Outputs:**
544
-
545
- | Output | Type |
546
- | ----------------- | -------- |
547
- | `activeTabChange` | `string` |
548
-
549
- **Content projection:** use `jvTabPanel` directive on `ng-template` to define panel content:
550
-
551
- ```html
552
- <jv-tabs [tabs]="tabs" [activeTabId]="activeTabId()" (activeTabChange)="activeTabId.set($event)">
553
- <ng-template jvTabPanel="overview">
554
- <p>Overview content</p>
555
- </ng-template>
556
- <ng-template jvTabPanel="analytics">
557
- <p>Analytics content</p>
558
- </ng-template>
559
- </jv-tabs>
560
- ```
561
-
562
- ### Tab Transitions
563
-
564
- Tabs support animated transitions between panels. Configure globally via `provideJvUi()` or per-instance via the `transition` input:
565
-
566
- ```typescript
567
- // Global default
568
- provideJvUi({ tabsTransition: 'fade' });
569
- ```
570
-
571
- ```typescript
572
- // Per-instance override
573
- <jv-tabs transition="slide" [keepMounted]="false">...</jv-tabs>
574
- ```
575
-
576
- | Transition | `keepMounted=true` | `keepMounted=false` | Description |
577
- | ---------- | ---------------------- | ------------------- | ------------------------------------ |
578
- | `'none'` | Instant switch | Instant switch | No animation |
579
- | `'fade'` | Opacity cross-fade | Opacity cross-fade | Smooth fade between panels |
580
- | `'slide'` | Falls back to `'fade'` | Directional slide | Slides left/right based on tab index |
581
-
582
- **Note:** `slide` requires `keepMounted=false` because it needs to animate both entering and exiting panels simultaneously. When used with `keepMounted=true`, it automatically falls back to `fade`.
583
-
584
- ### Tabs Example
585
-
586
- ```typescript
587
- import { Component, signal } from '@angular/core';
588
- import { JvTabItem, JvTabPanelDirective, JvTabsComponent } from '@devjuliovilla/jv-ui';
589
-
590
- @Component({
591
- standalone: true,
592
- imports: [JvTabsComponent, JvTabPanelDirective],
593
- template: `
594
- <jv-tabs
595
- [tabs]="tabs"
596
- [activeTabId]="activeTabId()"
597
- transition="fade"
598
- (activeTabChange)="activeTabId.set($event)"
599
- >
600
- <ng-template jvTabPanel="overview">
601
- <p>Overview content</p>
602
- </ng-template>
603
- <ng-template jvTabPanel="analytics">
604
- <p>Analytics content</p>
605
- </ng-template>
606
- </jv-tabs>
607
- `,
608
- })
609
- export class TabsExampleComponent {
610
- readonly activeTabId = signal('overview');
611
- readonly tabs: JvTabItem[] = [
612
- { id: 'overview', label: 'Overview' },
613
- { id: 'analytics', label: 'Analytics', icon: 'chart-column' },
614
- ];
615
- }
616
- ```
617
-
618
- ## Image Slider API
619
-
620
- ```typescript
621
- import { JvImageSliderComponent, JvSliderImage } from '@devjuliovilla/jv-ui';
622
- ```
623
-
624
- **JvSliderImage:**
625
-
626
- | Property | Type | Required | Description |
627
- | ------------- | -------- | -------- | ---------------------------------------- |
628
- | `src` | `string` | Yes | Image URL |
629
- | `alt` | `string` | Yes | Alternative text for accessibility |
630
- | `description` | `string` | No | Caption displayed below the image |
631
- | `thumbnail` | `string` | No | Custom thumbnail URL (defaults to `src`) |
632
-
633
- **Inputs:**
634
-
635
- | Input | Type | Default | Description |
636
- | ----------------- | ----------------- | ------- | --------------------------------- |
637
- | `images` | `JvSliderImage[]` | `[]` | Array of images to display |
638
- | `showThumbnails` | `boolean` | `true` | Show thumbnail strip below slider |
639
- | `showDescription` | `boolean` | `true` | Show image description |
640
-
641
- **Outputs:**
642
-
643
- | Output | Type | Description |
644
- | ------------- | -------- | ------------------------------------- |
645
- | `imageChange` | `number` | Emits index when active image changes |
646
-
647
- **i18n support:**
648
-
649
- The component automatically translates aria labels using `JvTranslationService`:
650
-
651
- | Key | English | Spanish |
652
- | ---------------------- | ---------------- | ---------------------- |
653
- | `slider.prevImage` | Previous image | Imagen anterior |
654
- | `slider.nextImage` | Next image | Imagen siguiente |
655
- | `slider.thumbnailList` | Image thumbnails | Miniaturas de imagenes |
656
-
657
- ### Features
658
-
659
- - **Keyboard navigation:** ArrowLeft/ArrowRight to navigate, Home/End for first/last image
660
- - **Responsive:** Images scale to fit container with `object-fit: contain`
661
- - **Thumbnails:** Scrollable thumbnail strip with active state indicator
662
- - **Single image mode:** Navigation controls hidden when only one image is provided
663
- - **Lazy loading:** Images use native `loading="lazy"` attribute
664
- - **i18n:** Aria labels automatically translated based on configured locale
665
-
666
- ### Example
667
-
668
- ```typescript
669
- import { Component } from '@angular/core';
670
- import { JvImageSliderComponent, JvSliderImage } from '@devjuliovilla/jv-ui';
671
-
672
- @Component({
673
- standalone: true,
674
- imports: [JvImageSliderComponent],
675
- template: `
676
- <jv-image-slider
677
- [images]="images"
678
- [showThumbnails]="true"
679
- [showDescription]="true"
680
- (imageChange)="onImageChange($event)"
681
- />
682
- `,
683
- })
684
- export class SliderComponent {
685
- readonly images: JvSliderImage[] = [
686
- { src: 'photo1.jpg', alt: 'Sunset', description: 'Beautiful sunset over the ocean' },
687
- { src: 'photo2.jpg', alt: 'Mountain', description: 'Snow-capped mountain peak' },
688
- { src: 'photo3.jpg', alt: 'Forest', description: 'Dense forest trail' },
689
- ];
690
-
691
- onImageChange(index: number) {
692
- console.log('Viewing image:', index);
693
- }
694
- }
695
- ```
696
-
697
- ## Image Gallery API
698
-
699
- ```typescript
700
- import { JvImageGalleryComponent, JvGalleryImage, JvGalleryAction } from '@devjuliovilla/jv-ui';
701
- ```
702
-
703
- **JvGalleryImage:**
704
-
705
- | Property | Type | Required | Description |
706
- | ----------- | -------- | -------- | ---------------------------------------- |
707
- | `src` | `string` | Yes | Image URL |
708
- | `alt` | `string` | Yes | Alternative text for accessibility |
709
- | `thumbnail` | `string` | No | Custom thumbnail URL (defaults to `src`) |
710
-
711
- **JvGalleryAction:**
712
-
713
- | Property | Type | Required | Description |
714
- | -------- | ---------- | -------- | ------------------------ |
715
- | `id` | `string` | Yes | Unique action identifier |
716
- | `label` | `string` | Yes | Button label text |
717
- | `icon` | `string` | No | Lucide icon name |
718
- | `tone` | `JvIntent` | No | Button variant |
719
-
720
- **Inputs:**
721
-
722
- | Input | Type | Default | Description |
723
- | --------------- | ------------------- | ------- | ------------------------------------------------------------------------------------- |
724
- | `images` | `JvGalleryImage[]` | `[]` | Array of images to display |
725
- | `stripHeightVh` | `number` | `25` | Height of the thumbnail strip in viewport-height units, clamped between `0` and `100` |
726
- | `actions` | `JvGalleryAction[]` | `[]` | Action buttons shown in dialog footer |
727
-
728
- **Outputs:**
729
-
730
- | Output | Type | Description |
731
- | ------------- | --------------------------------------------- | -------------------------------------- |
732
- | `imageClick` | `JvGalleryImage` | Emits when an image is clicked |
733
- | `actionClick` | `{ actionId: string; image: JvGalleryImage }` | Emits when an action button is clicked |
734
-
735
- ### Features
736
-
737
- - **Horizontal strip:** Scrollable thumbnail strip with configurable height in `vh`
738
- - **Full-screen viewer:** Click any image to open in a dialog with dark background
739
- - **Navigation:** Prev/next buttons and keyboard arrows (← →) in the viewer
740
- - **Configurable actions:** Action buttons in dialog footer (favorite, edit, delete, etc.)
741
- - **Responsive:** Shows multiple columns on desktop, single column with scroll on mobile
742
- - **Lazy loading:** All images use native `loading="lazy"` attribute
743
- - **i18n:** Close and navigation labels automatically translated
744
-
745
- ### Example
746
-
747
- ```typescript
748
- import { Component } from '@angular/core';
749
- import { JvImageGalleryComponent, JvGalleryImage, JvGalleryAction } from '@devjuliovilla/jv-ui';
750
-
751
- @Component({
752
- standalone: true,
753
- imports: [JvImageGalleryComponent],
754
- template: `
755
- <jv-image-gallery
756
- [images]="images"
757
- [stripHeightVh]="30"
758
- [actions]="actions"
759
- (imageClick)="onImageClick($event)"
760
- (actionClick)="onActionClick($event)"
761
- />
762
- `,
763
- })
764
- export class GalleryComponent {
765
- readonly images: JvGalleryImage[] = [
766
- { src: 'photo1.jpg', alt: 'Sunset' },
767
- { src: 'photo2.jpg', alt: 'Mountain' },
768
- { src: 'photo3.jpg', alt: 'Forest' },
769
- ];
770
-
771
- readonly actions: JvGalleryAction[] = [
772
- { id: 'favorite', label: 'Favorite', icon: 'heart', tone: 'danger' },
773
- { id: 'edit', label: 'Edit', icon: 'pencil' },
774
- { id: 'delete', label: 'Delete', icon: 'trash-2', tone: 'danger' },
775
- ];
776
-
777
- onImageClick(image: JvGalleryImage) {
778
- console.log('Viewing:', image.alt);
779
- }
780
-
781
- onActionClick(event: { actionId: string; image: JvGalleryImage }) {
782
- console.log(event.actionId, 'on', event.image.alt);
783
- }
784
- }
785
- ```
786
-
787
- ## Textarea API
788
-
789
- ```typescript
790
- import { JvTextareaComponent } from '@devjuliovilla/jv-ui';
791
- ```
792
-
793
- | Input | Type | Default | Description |
794
- | ------------- | --------- | ----------------- | ---------------------------------------------------- |
795
- | `placeholder` | `string` | `''` | Placeholder text |
796
- | `required` | `boolean` | `false` | Mark field as required |
797
- | `invalid` | `boolean` | `false` | Show invalid state |
798
- | `readonly` | `boolean` | `false` | Make textarea read-only |
799
- | `rows` | `number` | `3` | Visible number of rows |
800
- | `cols` | `number` | — | Visible width in columns |
801
- | `maxlength` | `number` | — | Maximum character length |
802
- | `describedBy` | `string` | `''` | ID of description/error element for aria-describedby |
803
- | `inputId` | `string` | `jv-textarea-{n}` | Auto-generated unique ID |
804
-
805
- Implements `ControlValueAccessor` — compatible with `[(ngModel)]` and reactive forms via `formControlName`.
806
-
807
- ### Example
808
-
809
- ```typescript
810
- import { Component } from '@angular/core';
811
- import { JvTextareaComponent } from '@devjuliovilla/jv-ui';
812
- import { ReactiveFormsModule, FormBuilder } from '@angular/forms';
813
-
814
- @Component({
815
- selector: 'app-profile',
816
- standalone: true,
817
- imports: [ReactiveFormsModule, JvTextareaComponent],
818
- template: `
819
- <jv-textarea
820
- formControlName="bio"
821
- placeholder="Tell us about yourself..."
822
- [rows]="4"
823
- [maxlength]="500"
824
- />
825
- `,
826
- })
827
- export class ProfileComponent {
828
- form = inject(FormBuilder).group({ bio: [''] });
829
- }
830
- ```
831
-
832
- ## Code API
833
-
834
- ```typescript
835
- import { JvCodeComponent } from '@devjuliovilla/jv-ui';
836
- ```
837
-
838
- | Input | Type | Default | Description |
839
- | ---------- | ------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------- |
840
- | `code` | `string` | — | Code or text content to render |
841
- | `language` | `string` | `''` | Optional language badge |
842
- | `title` | `string` | `''` | Optional header title |
843
- | `font` | `'jetbrains-mono' \| 'fira-code' \| 'cascadia' \| 'consolas' \| 'system'` | `'jetbrains-mono'` | Mono font preset for the rendered block |
844
- | `editable` | `boolean` | `false` | Renders a textarea-style editing surface instead of read-only preview |
845
- | `width` | `string` | `'100%'` | CSS width applied to the component |
846
- | `height` | `string` | `'auto'` | CSS height for the editable surface or minimum preview height |
847
-
848
- Use `JvCode` for read-only payloads or long single-line content where horizontal scrolling should be preserved instead of wrapping.
849
- The library does not bundle font files. `JvCode` references common mono families and will use any web font you load at the application level.
850
-
851
- When `editable` is enabled, `JvCode` emits `codeChange` on every edit so the parent can keep the source text in sync.
852
-
853
- ### Example
854
-
855
- ```typescript
856
- import { Component } from '@angular/core';
857
- import { JvCodeComponent } from '@devjuliovilla/jv-ui';
858
-
859
- @Component({
860
- selector: 'app-payload-preview',
861
- standalone: true,
862
- imports: [JvCodeComponent],
863
- template: `
864
- <jv-code
865
- [code]="payload"
866
- language="json"
867
- title="HTTP payload preview"
868
- font="fira-code"
869
- [editable]="true"
870
- width="100%"
871
- height="18rem"
872
- (codeChange)="payload = $event"
873
- />
874
- `,
875
- })
876
- export class PayloadPreviewComponent {
877
- payload = '{"status":"ok"}';
878
- }
879
- ```
880
-
881
- If you want hosted fonts without shipping them in your package, load them at the app level, for example:
882
-
883
- ```css
884
- @import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap');
885
- ```
886
-
887
- ## Confirm Dialog Labels
888
-
889
- `JvDialogService.confirm()` already supports `confirmLabel` and `cancelLabel` overrides per dialog. If you omit them, the defaults come from the active translation dictionary using `dialog.confirm` and `dialog.cancel`.
890
-
891
- This lets you either:
892
-
893
- - override labels directly for a specific action like `Guardar evento` / `Descartar cambios`
894
- - or register translated defaults in your i18n dictionary for each supported language
895
-
896
- Example with business copy:
897
-
898
- ```typescript
899
- const confirmed = await dialogService.confirm({
900
- title: 'Guardar evento',
901
- message: 'Se aplicaran cambios a la agenda del equipo.',
902
- confirmLabel: 'Guardar evento',
903
- cancelLabel: 'Descartar cambios',
904
- tone: 'primary',
905
- });
906
-
907
- if (confirmed) {
908
- saveEvent();
909
- }
910
- ```
911
-
912
- Example using translated defaults from your dictionary:
913
-
914
- ```typescript
915
- await dialogService.confirm({
916
- message: 'This action will publish the current draft.',
917
- tone: 'primary',
918
- });
919
- ```
920
-
921
- ## Icon System
922
-
923
- ```typescript
924
- import { JvIconComponent, JV_LUCIDE_ICON_REGISTRY } from '@devjuliovilla/jv-ui';
925
- ```
926
-
927
- | Input | Type | Default | Description |
928
- | ------------- | --------- | ------- | ----------------------------------------------- |
929
- | `name` | `string` | — | Icon name (from auto-generated Lucide registry) |
930
- | `size` | `number` | `24` | Width and height in pixels |
931
- | `strokeWidth` | `number` | `2` | SVG stroke width |
932
- | `decorative` | `boolean` | `true` | `aria-hidden="true"` when decorative |
933
- | `ariaLabel` | `string` | — | Accessible label when not decorative |
934
-
935
- Icons are auto-generated from [lucide-static](https://www.npmjs.com/package/lucide-static) via:
936
-
937
- ```bash
938
- node tools/generate-icons.mjs
939
- ```
940
-
941
- This reads all SVG files from `lucide-static/icons` and produces `jv-icon-registry.ts` with the complete set (~1500 icons). Run it after updating `lucide-static` to keep icons in sync.
942
-
943
- ## Layout API
944
-
945
- ### JvDashboardShell
946
-
947
- ```typescript
948
- import { JvDashboardShellComponent } from '@devjuliovilla/jv-ui';
949
- ```
950
-
951
- | Input | Type | Default | Description |
952
- | ------------------- | ------------------ | ----------- | ------------------------------------------- |
953
- | `title` | `string` | — | App / brand title |
954
- | `sidebarSubtitle` | `string` | `''` | Subtitle below brand |
955
- | `brandIcon` | `string` | `'monitor'` | Brand Lucide icon |
956
- | `navItems` | `JvNavItem[]` | `[]` | Navigation items (supports nested children) |
957
- | `sidebarCollapsed` | `boolean` | `false` | Desktop sidebar collapsed state |
958
- | `mobileSidebarOpen` | `boolean` | `false` | Mobile sidebar open/closed |
959
- | `topbarTitle` | `string` | `''` | Topbar page title |
960
- | `topbarSubtitle` | `string` | `''` | Topbar subtitle |
961
- | `currentTheme` | `JvTheme` | `'light'` | Active theme value |
962
- | `themeOptions` | `JvThemeOption[]` | `[]` | Theme selector options |
963
- | `topbarActions` | `JvTopbarAction[]` | `[]` | Icon buttons in topbar |
964
- | `showThemeSelector` | `boolean` | `true` | Show theme pills |
965
-
966
- | Output | Description |
967
- | ----------------------- | -------------------------------------------------------------- |
968
- | `menuClick` | Hamburger button clicked — toggle mobile sidebar |
969
- | `mobileClose` | Backdrop clicked or navigation selected — close mobile sidebar |
970
- | `sidebarCollapseToggle` | Collapse toggle clicked — collapse/expand sidebar |
971
- | `themeChange` | Theme pill clicked |
972
- | `topbarActionClick` | Topbar action button clicked |
973
-
974
- **Mobile behavior:** at viewports ≤ 900px the sidebar becomes a fixed overlay with slide-in animation (`transform: translateX`) and a semi-transparent backdrop. The sidebar emits `mobileClose` when the backdrop is clicked or a nav link is followed.
975
-
976
- ### JvSidebar
977
-
978
- | Input | Type | Default | Description |
979
- | ------------ | ------------- | ---------------------- | --------------------- |
980
- | `title` | `string` | — | Brand title |
981
- | `subtitle` | `string` | `''` | Brand subtitle |
982
- | `brandIcon` | `string` | `'monitor'` | Brand icon |
983
- | `items` | `JvNavItem[]` | `[]` | Navigation items |
984
- | `collapsed` | `boolean` | `false` | Collapse to icon-only |
985
- | `mobileOpen` | `boolean` | `false` | Show on mobile |
986
- | `ariaLabel` | `string` | `'Sidebar navigation'` | Accessible label |
987
-
988
- | Output | Description |
989
- | ---------------- | ------------------------------------------------ |
990
- | `collapseToggle` | Collapse button clicked |
991
- | `mobileClose` | Backdrop or nav item interaction — request close |
992
-
993
- ## Responsive Design
994
-
995
- The library includes basic responsive behavior:
996
-
997
- - **Breakpoints** defined as CSS custom properties: `--jv-breakpoint-sm` (640px), `--jv-breakpoint-md` (768px), `--jv-breakpoint-lg` (1024px), `--jv-breakpoint-xl` (1280px)
998
- - **Dashboard shell** collapses to single column at ≤ 900px; sidebar becomes a slide-in overlay with backdrop
999
- - **Topbar** stacks vertically at ≤ 900px
1000
- - **Grid** pagination and toolbar stack at ≤ 640px; table scrolls horizontally with `overflow-x: auto`
1001
- - **Flex-wrap** is used extensively for natural overflow handling
1002
- - **Dialog** and **Toast** constrain width with `min()` to never exceed the viewport
1003
-
1004
- ## Services
1005
-
1006
- | Service | Import Path | Description |
1007
- | ----------------------- | ---------------------- | -------------------------------------------- |
1008
- | `JvThemeService` | `@devjuliovilla/jv-ui` | Light / dark / high-contrast theme switching |
1009
- | `JvTranslationService` | `@devjuliovilla/jv-ui` | Dictionary-based i18n (en/es) |
1010
- | `JvToastService` | `@devjuliovilla/jv-ui` | Toast notification system |
1011
- | `JvLoaderService` | `@devjuliovilla/jv-ui` | Full-screen loader with request counter |
1012
- | `JvDialogService` | `@devjuliovilla/jv-ui` | Programmatic confirm dialogs |
1013
- | `JvAnnouncementService` | `@devjuliovilla/jv-ui` | Screen-reader live-region announcements |
1014
-
1015
- ## Accessibility
1016
-
1017
- - WCAG 2.2 AA target
1018
- - Keyboard navigation for all interactive components
1019
- - Focus management with visible focus indicators
1020
- - Screen reader announcements (loading, empty states, page changes)
1021
- - `aria-sort` on sortable grid headers
1022
- - `aria-selected` on selectable grid rows
1023
- - `aria-label` and `aria-labelledby` on interactive controls
1024
- - Supports `prefers-reduced-motion`
1025
-
1026
- ## Requirements
1027
-
1028
- - Angular 21.2+
1029
- - TypeScript 5.9+
1030
-
1031
- ## License
1032
-
1033
- MIT
1
+ # @devjuliovilla/jv-ui
2
+
3
+ Accessibility-first Angular component library built with signals and standalone APIs. Includes components, forms, data grids, dialogs, layout primitives, services, and i18n infrastructure.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @devjuliovilla/jv-ui
9
+ ```
10
+
11
+ This release line targets Angular 21. Future package changes will be tracked in the repository [CHANGELOG.md](https://github.com/devjuliovilla/JV_UI/blob/develop/CHANGELOG.md).
12
+
13
+ Import the theme CSS in your `angular.json` or `styles` array:
14
+
15
+ ```json
16
+ "styles": ["@devjuliovilla/jv-ui/styles/jv-theme.css"]
17
+ ```
18
+
19
+ ## Quick start
20
+
21
+ ```typescript
22
+ import { ApplicationConfig } from '@angular/core';
23
+ import { provideJvUi } from '@devjuliovilla/jv-ui';
24
+
25
+ export const appConfig: ApplicationConfig = {
26
+ providers: [provideJvUi({ messagesLocale: 'en', formatLocale: 'en-US' })],
27
+ };
28
+ ```
29
+
30
+ ```typescript
31
+ import { Component } from '@angular/core';
32
+ import { JvButtonComponent } from '@devjuliovilla/jv-ui';
33
+
34
+ @Component({
35
+ selector: 'app-root',
36
+ standalone: true,
37
+ imports: [JvButtonComponent],
38
+ template: '<jv-button variant="primary">Hello</jv-button>',
39
+ })
40
+ export class App {}
41
+ ```
42
+
43
+ ## Components
44
+
45
+ | Category | Components |
46
+ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
47
+ | Buttons | `JvButton`, `JvButtonGroup`, `JvIconButton` |
48
+ | Calendar | `JvMonthCalendar`, `JvDayPlanner` — reusable month view and agenda primitives, usable together or independently |
49
+ | Forms | `JvInput`, `JvTextarea`, `JvCode`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvDatePicker`, `JvModalSelector`, `JvFileInput`, `JvFormContainer` |
50
+ | Data Grid | `JvGrid` — full-featured data table (see below) |
51
+ | Containers | `JvCard`, `JvSection`, `JvDivider` |
52
+ | List | `JvList`, `JvListItem` — list with title, description, icons, badges, and interactive items |
53
+ | Tabs | `JvTabs`, `JvTabPanelDirective` — horizontal tabs with keyboard navigation and animated transitions |
54
+ | Slider | `JvImageSlider` — responsive image slider with thumbnails and keyboard navigation |
55
+ | Gallery | `JvImageGallery` — horizontal image gallery with wheel scrolling and full-screen viewer |
56
+ | Feedback | `JvAlert`, `JvBadge`, `JvLoader`, `JvToast` |
57
+ | Dialogs | `JvDialog`, `JvConfirmDialog`, `JvWindowModal` — compact dialogs plus a larger workflow overlay surface |
58
+ | Layout | `JvDashboardShell`, `JvSidebar`, `JvTopbar`, `JvBreadcrumb`, `JvPage` |
59
+ | Auth Pages | `JvLoginPage`, `JvForgotPasswordPage`, `JvChangePasswordPage` |
60
+ | Icon | `JvIcon` — Lucide-based icon component with 1500+ auto-generated icons |
61
+ | Pagination | `JvPagination` — standalone pagination with i18n |
62
+
63
+ ## Calendar API
64
+
65
+ The scheduling primitives are split into **two separate components**:
66
+
67
+ - `JvMonthCalendar`: inline month grid with selection, navigation, and day markers
68
+ - `JvDayPlanner`: agenda / list view for scheduled items with optional grouping and expandable details
69
+
70
+ You can use either one on its own, or compose both together in a master-detail scheduling layout.
71
+
72
+ ### JvMonthCalendar
73
+
74
+ ```typescript
75
+ import {
76
+ JvMonthCalendarComponent,
77
+ JvMonthCalendarDayDirective,
78
+ JvMonthCalendarDayMeta,
79
+ } from '@devjuliovilla/jv-ui';
80
+ ```
81
+
82
+ **Inputs:**
83
+
84
+ | Input | Type | Default | Description |
85
+ | -------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- |
86
+ | `value` | `Date \| string \| null` | `undefined` | Selected day |
87
+ | `visibleMonth` | `Date \| string \| null` | `undefined` | Controlled visible month independent from the selected day |
88
+ | `dayMeta` | `JvMonthCalendarDayMeta[]` | `[]` | Marker/counter metadata per day |
89
+ | `ariaLabel` | `string` | localized default | Accessible label for the grid |
90
+ | `monthLabel` | `string` | `Month` | Accessible label for the month selector |
91
+ | `yearLabel` | `string` | `Year` | Accessible label for the year selector |
92
+ | `minYear` | `number` | current year - 10 | Lower year bound for the year selector |
93
+ | `maxYear` | `number` | current year + 10 | Upper year bound for the year selector |
94
+ | `navigation` | `{ previousMonth?: boolean; nextMonth?: boolean; previousYear?: boolean; nextYear?: boolean }` | `{ previousMonth: true, nextMonth: true, previousYear: false, nextYear: false }` | Controls which month/year navigation buttons are rendered |
95
+
96
+ **Outputs:**
97
+
98
+ | Output | Type |
99
+ | -------------------- | ------ |
100
+ | `selectionChange` | `Date` |
101
+ | `visibleMonthChange` | `Date` |
102
+
103
+ **Day metadata:**
104
+
105
+ | Property | Type | Description |
106
+ | -------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
107
+ | `date` | `Date \| string` | Day associated with the marker |
108
+ | `count` | `number` | Optional numeric badge rendered inside the cell |
109
+ | `tone` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'neutral'` | Visual tone for the badge or dot |
110
+ | `label` | `string` | Extra accessibility text appended to the day `aria-label` |
111
+
112
+ **Template hook:**
113
+
114
+ Use `ng-template[jvMonthCalendarDay]` to fully customize the day cell.
115
+
116
+ **Standalone example:**
117
+
118
+ ```typescript
119
+ import { Component, signal } from '@angular/core';
120
+ import { JvMonthCalendarComponent, JvMonthCalendarDayMeta } from '@devjuliovilla/jv-ui';
121
+
122
+ @Component({
123
+ selector: 'app-calendar-only',
124
+ standalone: true,
125
+ imports: [JvMonthCalendarComponent],
126
+ template: `
127
+ <jv-month-calendar
128
+ [value]="selectedDate()"
129
+ [dayMeta]="calendarMeta"
130
+ (selectionChange)="selectedDate.set($event)"
131
+ />
132
+ `,
133
+ })
134
+ export class CalendarOnlyComponent {
135
+ readonly selectedDate = signal(new Date(2026, 5, 15));
136
+ readonly calendarMeta: JvMonthCalendarDayMeta[] = [
137
+ { date: '2026-06-15', count: 2, tone: 'primary', label: '2 activities' },
138
+ { date: '2026-06-16', count: 1, tone: 'secondary', label: '1 activity' },
139
+ ];
140
+ }
141
+ ```
142
+
143
+ ### JvDayPlanner
144
+
145
+ ```typescript
146
+ import {
147
+ JvDayPlannerComponent,
148
+ JvDayPlannerDetailDirective,
149
+ JvDayPlannerItem,
150
+ JvDayPlannerItemDirective,
151
+ } from '@devjuliovilla/jv-ui';
152
+ ```
153
+
154
+ **Inputs:**
155
+
156
+ | Input | Type | Default | Description |
157
+ | ------------------------ | ---------------------- | ----------------- | ---------------------------------------- |
158
+ | `items` | `JvDayPlannerItem[]` | `[]` | Agenda items |
159
+ | `groupByDate` | `boolean` | `false` | Group items under a date heading |
160
+ | `emptyMessage` | `string` | localized default | Empty state copy |
161
+ | `ariaLabel` | `string` | localized default | Accessible label for the agenda |
162
+ | `defaultExpandedItemIds` | `(string \| number)[]` | `[]` | Items whose detail should start expanded |
163
+
164
+ **Outputs:**
165
+
166
+ | Output | Type |
167
+ | ------------ | ------------------ |
168
+ | `itemSelect` | `JvDayPlannerItem` |
169
+
170
+ **Planner item shape:**
171
+
172
+ | Property | Type | Description |
173
+ | ------------- | ------------------------ | ----------------------------------------- |
174
+ | `id` | `string \| number` | Stable identity |
175
+ | `title` | `string` | Primary label |
176
+ | `date` | `Date \| string \| null` | Logical day when start time is not enough |
177
+ | `start` | `Date \| string \| null` | Optional start datetime |
178
+ | `end` | `Date \| string \| null` | Optional end datetime |
179
+ | `status` | `string` | Status badge label |
180
+ | `statusTone` | `JvTone` | Visual tone for status badge |
181
+ | `type` | `string` | Type/category badge label |
182
+ | `typeTone` | `JvTone` | Visual tone for type badge |
183
+ | `responsible` | `string` | Responsible person |
184
+ | `location` | `string` | Location metadata |
185
+ | `details` | `string` | Expandable detail text |
186
+ | `completed` | `boolean` | Reduced emphasis for completed items |
187
+
188
+ **Template hooks:**
189
+
190
+ - `ng-template[jvDayPlannerItem]` customizes the visible item row
191
+ - `ng-template[jvDayPlannerDetail]` customizes the expanded detail panel
192
+
193
+ **Standalone example:**
194
+
195
+ ```typescript
196
+ import { Component } from '@angular/core';
197
+ import { JvDayPlannerComponent, JvDayPlannerItem } from '@devjuliovilla/jv-ui';
198
+
199
+ @Component({
200
+ selector: 'app-planner-only',
201
+ standalone: true,
202
+ imports: [JvDayPlannerComponent],
203
+ template: `
204
+ <jv-day-planner [items]="items" [groupByDate]="true" (itemSelect)="handleSelect($event)" />
205
+ `,
206
+ })
207
+ export class PlannerOnlyComponent {
208
+ readonly items: JvDayPlannerItem[] = [
209
+ {
210
+ id: 1,
211
+ title: 'Venue setup',
212
+ start: '2026-06-15T08:30:00',
213
+ end: '2026-06-15T10:00:00',
214
+ status: 'Scheduled',
215
+ statusTone: 'primary',
216
+ type: 'Logistics',
217
+ responsible: 'Ana Lopez',
218
+ location: 'Main hall',
219
+ details: 'Prepare seating and signage.',
220
+ },
221
+ ];
222
+
223
+ handleSelect(item: JvDayPlannerItem) {
224
+ console.log(item);
225
+ }
226
+ }
227
+ ```
228
+
229
+ ### Combined example
230
+
231
+ Use both components together when you need a left-side month selector and a right-side agenda:
232
+
233
+ ```html
234
+ <jv-month-calendar
235
+ [value]="selectedDate()"
236
+ [dayMeta]="calendarMeta()"
237
+ (selectionChange)="selectedDate.set($event)"
238
+ />
239
+
240
+ <jv-day-planner
241
+ [items]="filteredItems()"
242
+ [groupByDate]="showAll()"
243
+ (itemSelect)="selectedItem.set($event)"
244
+ />
245
+ ```
246
+
247
+ ## Grid Features
248
+
249
+ | Feature | Description |
250
+ | ------------------ | ---------------------------------------------------------------- |
251
+ | Sorting | Client-side multi-column sorting with sort icons and `aria-sort` |
252
+ | Search | Global text search across visible columns |
253
+ | Pagination | Configurable page size, page range buttons, first/last/prev/next |
254
+ | Selection | Checkbox row selection with `selectedIds` / `selectionChange` |
255
+ | Row actions | Custom action buttons per row |
256
+ | Density modes | Compact, normal, comfortable |
257
+ | Sticky columns | Pin columns to left or right |
258
+ | Column resizing | Drag column header borders to resize |
259
+ | Column reordering | Drag & drop column headers |
260
+ | Grouped headers | Multi-row header with `colspan` via `children` |
261
+ | Per-column filters | Filter input row with operators |
262
+ | Inline editing | Double-click or Enter to edit: text, number, select, boolean |
263
+ | Virtual scrolling | Render only visible rows for large datasets |
264
+ | CSV/Excel export | Built-in toolbar buttons, no external deps |
265
+ | Server-side mode | Delegate sort/filter/page to parent component |
266
+ | TrackBy | Custom trackBy key or function |
267
+ | i18n | All labels configurable via translation dictionary |
268
+
269
+ ### Grid API
270
+
271
+ ```typescript
272
+ import { JvGridComponent } from '@devjuliovilla/jv-ui';
273
+ ```
274
+
275
+ **Inputs:**
276
+
277
+ | Input | Type | Default | Description |
278
+ | ------------- | ----------------------------- | ------- | -------------------------- |
279
+ | `data` | `T[]` | `[]` | Row data array |
280
+ | `columns` | `JvGridColumn<T>[]` | `[]` | Column definitions |
281
+ | `actions` | `JvGridAction<T>[]` | `[]` | Row action button configs |
282
+ | `options` | `Partial<JvGridOptions>` | `{}` | Feature toggles and config |
283
+ | `trackBy` | `keyof T \| Function \| null` | `null` | Row identity |
284
+ | `selectedIds` | `(string \| number)[]` | `[]` | Controlled selection IDs |
285
+
286
+ **Outputs:**
287
+
288
+ | Output | Type |
289
+ | ----------------- | ----------------------------------------------------------- |
290
+ | `rowClick` | `T` |
291
+ | `rowDoubleClick` | `T` |
292
+ | `actionClick` | `{ actionId: string; row: T }` |
293
+ | `selectionChange` | `(string \| number)[]` |
294
+ | `pageChange` | `{ pageIndex: number; pageSize: number }` |
295
+ | `searchChange` | `string` |
296
+ | `sortChange` | `{ columnKey: string; direction: 'asc' \| 'desc' \| null }` |
297
+ | `columnFilter` | `{ columnKey: string; value: string }` |
298
+ | `columnResize` | `{ columnKey: string; width: string }` |
299
+ | `columnReorder` | `{ columnKey: string; newIndex: number }` |
300
+ | `rowEdit` | `{ row: T; column: JvGridColumn<T>; value: unknown }` |
301
+
302
+ **JvGridColumn options:**
303
+
304
+ | Property | Type | Description |
305
+ | --------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------- |
306
+ | `key` | `keyof T \| string` | Data field key |
307
+ | `header` | `string` | Column display header |
308
+ | `sortable` | `boolean` | Enable column sorting |
309
+ | `searchable` | `boolean` | Include in global search |
310
+ | `filterable` | `boolean` | Show per-column filter input |
311
+ | `hidden` | `boolean` | Hide column from display |
312
+ | `sticky` | `'left' \| 'right'` | Pin column position |
313
+ | `editable` | `boolean` | Allow inline cell editing |
314
+ | `editType` | `'text' \| 'number' \| 'select' \| 'boolean'` | Editor type |
315
+ | `editOptions` | `{ label: string; value: unknown }[]` | Options for select editor |
316
+ | `width` | `string` | Column width (e.g. '8rem') |
317
+ | `align` | `'start' \| 'center' \| 'end'` | Text alignment |
318
+ | `type` | `'text' \| 'integer' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'time' \| 'datetime' \| 'boolean'` | Data type for formatting |
319
+ | `formatOptions` | `Intl.NumberFormatOptions & Intl.DateTimeFormatOptions` | Per-column formatting overrides |
320
+ | `format` | `(value, row) => string` | Custom display formatter |
321
+ | `children` | `JvGridColumn<T>[]` | Child columns for grouped headers |
322
+ | `resizable` | `boolean` | Allow column resize |
323
+ | `cellClass` | `string` | CSS class for cells |
324
+ | `headerClass` | `string` | CSS class for header |
325
+
326
+ **JvGridOptions:**
327
+
328
+ | Option | Type | Default | Description |
329
+ | ------------------------ | ---------------------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
330
+ | `searchable` | `boolean` | `true` | Show search bar |
331
+ | `sortable` | `boolean` | `true` | Enable column sorting |
332
+ | `pageable` | `boolean` | `true` | Enable pagination |
333
+ | `selectable` | `boolean` | `false` | Show selection checkboxes |
334
+ | `pageSize` | `number` | `20` | Default page size |
335
+ | `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size selector options |
336
+ | `density` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Row density |
337
+ | `loading` | `boolean` | `false` | Show loading spinner |
338
+ | `emptyMessage` | `string` | — | Empty state message |
339
+ | `exportable` | `boolean` | `false` | Show CSV/Excel export buttons |
340
+ | `exportFileName` | `string` | `''` | Base filename used for CSV/Excel exports; the component applies the correct extension |
341
+ | `serverSide` | `boolean` | `false` | Disable client-side processing |
342
+ | `totalItems` | `number` | `0` | Total items for server-side mode |
343
+ | `stickyColumns` | `boolean` | `false` | Enable sticky column support |
344
+ | `resizableColumns` | `boolean` | `false` | Enable column resizing |
345
+ | `reorderableColumns` | `boolean` | `false` | Enable column reordering |
346
+ | `editable` | `boolean` | `false` | Enable inline editing |
347
+ | `virtualScroll` | `boolean` | `false` | Enable virtual scrolling |
348
+ | `virtualScrollRowHeight` | `number` | `48` | Row height for virtual scroll |
349
+ | `columnFilters` | `boolean` | `false` | Show filter row below headers |
350
+ | `rowDoubleClick` | `boolean` | `false` | Enable row double-click event |
351
+ | `keyboardNavigation` | `boolean` | `false` | Enable arrow-key cell navigation and `F2` editing flow |
352
+ | `ariaLabel` | `string` | — | Accessible label for the grid |
353
+
354
+ ### Grid example
355
+
356
+ ```typescript
357
+ import { Component } from '@angular/core';
358
+ import { JvGridComponent, JvGridColumn, JvGridOptions } from '@devjuliovilla/jv-ui';
359
+
360
+ interface Product {
361
+ id: number;
362
+ name: string;
363
+ price: number;
364
+ status: string;
365
+ }
366
+
367
+ @Component({
368
+ selector: 'app-products',
369
+ standalone: true,
370
+ imports: [JvGridComponent],
371
+ template: `
372
+ <jv-grid
373
+ [data]="products"
374
+ [columns]="columns"
375
+ [options]="{ selectable: true, exportable: true, exportFileName: 'products', pageSize: 10 }"
376
+ [trackBy]="'id'"
377
+ [selectedIds]="selectedIds"
378
+ (selectionChange)="selectedIds = $event"
379
+ />
380
+ `,
381
+ })
382
+ export class ProductsComponent {
383
+ products: Product[] = [
384
+ /* ... */
385
+ ];
386
+ selectedIds: (string | number)[] = [];
387
+ columns: JvGridColumn<Product>[] = [
388
+ { key: 'id', header: 'ID', width: '4rem' },
389
+ { key: 'name', header: 'Product', sortable: true, filterable: true },
390
+ { key: 'price', header: 'Price', type: 'number', align: 'end', format: (v) => '$' + v },
391
+ { key: 'status', header: 'Status', sortable: true },
392
+ ];
393
+ }
394
+ ```
395
+
396
+ ### Grid behavior notes
397
+
398
+ - **Row identity:** when `trackBy` is not provided, rows with an `id` property use that value as their identity. Provide `[trackBy]` when the row identity uses another field or a custom function.
399
+ - **Controlled selection:** use `[selectedIds]` together with `(selectionChange)` when the parent owns selection state. The component accepts an empty array, so selection can start fully controlled without special initialization.
400
+ - **Pagination:** `pageSize` is clamped to the configured `pageSizeOptions`, and page indexes are clamped when the data or page size changes. Use `(pageChange)` to synchronize server-side pagination.
401
+ - **Grouped headers:** define parent columns with `children`. The grouped header is rendered with `colspan`, while sorting, filtering, editing, resizing, reordering, and export operate on the leaf columns.
402
+ - **Virtual scrolling:** place the grid inside a container with a constrained height and set `virtualScroll: true`. The default row height is `48`; set `virtualScrollRowHeight` to the actual rendered row height when it differs.
403
+ - **Formatting:** column `type` and `formatOptions` affect display only. Sorting and export use the raw field value, not the localized text shown in the cell.
404
+ - **Inline editing:** set both `editable: true` in `options` and `editable: true` on the column. `select` editors emit the configured option value, while `boolean` editors emit a boolean. Press `F2` to start, `Enter` to commit, and `Escape` to cancel when keyboard navigation is enabled.
405
+
406
+ ### Keyboard navigation example
407
+
408
+ ```typescript
409
+ const gridOptions: JvGridOptions = {
410
+ keyboardNavigation: true,
411
+ editable: true,
412
+ pageable: false,
413
+ };
414
+
415
+ const columns: JvGridColumn<Product>[] = [
416
+ { key: 'name', header: 'Product', editable: true, editType: 'text' },
417
+ {
418
+ key: 'status',
419
+ header: 'Status',
420
+ editable: true,
421
+ editType: 'select',
422
+ editOptions: [
423
+ { label: 'Active', value: 'active' },
424
+ { label: 'Paused', value: 'paused' },
425
+ ],
426
+ },
427
+ ];
428
+ ```
429
+
430
+ ```html
431
+ <jv-grid
432
+ [data]="products"
433
+ [columns]="columns"
434
+ [options]="gridOptions"
435
+ (rowEdit)="onRowEdit($event)"
436
+ />
437
+ ```
438
+
439
+ With `keyboardNavigation` enabled, arrow keys move between data cells without trapping row action buttons. `Tab` continues to the row actions, `F2` starts editing, `Enter` commits, and `Escape` cancels.
440
+
441
+ ## List API
442
+
443
+ ```typescript
444
+ import { JvListComponent, JvListItemComponent } from '@devjuliovilla/jv-ui';
445
+ ```
446
+
447
+ **JvList inputs:**
448
+
449
+ | Input | Type | Default | Description |
450
+ | ----------- | ------------------------ | -------- | ------------------------------------------------------------------------------ |
451
+ | `role` | `'list' \| 'navigation'` | `'list'` | ARIA role for the list |
452
+ | `variant` | `'bordered' \| null` | `null` | Outer border + border-radius around the list (items always have bottom border) |
453
+ | `ariaLabel` | `string` | `''` | Accessible label |
454
+
455
+ **JvListItem inputs:**
456
+
457
+ | Input | Type | Default | Description |
458
+ | ------------- | ------------------- | ------- | -------------------------------------------- |
459
+ | `title` | `string` (required) | — | Primary text |
460
+ | `description` | `string` | `''` | Secondary text below title |
461
+ | `leadingIcon` | `string \| null` | `null` | Lucide icon name on the left |
462
+ | `disabled` | `boolean` | `false` | Gray out and block interaction |
463
+ | `active` | `boolean` | `false` | Highlight with primary color and left border |
464
+
465
+ **JvListItem outputs:**
466
+
467
+ | Output | Type |
468
+ | ----------- | ------ |
469
+ | `activated` | `void` |
470
+
471
+ **Content projection:** use the `meta` attribute selector for badges, icons, or any content on the right side:
472
+
473
+ ```html
474
+ <jv-list-item title="Inbox" description="New messages">
475
+ <jv-badge tone="primary" meta>3</jv-badge>
476
+ <jv-icon name="chevron-right" meta />
477
+ </jv-list-item>
478
+ ```
479
+
480
+ ### Example
481
+
482
+ ```typescript
483
+ import { Component } from '@angular/core';
484
+ import { JvListComponent, JvListItemComponent, JvBadgeComponent } from '@devjuliovilla/jv-ui';
485
+
486
+ @Component({
487
+ selector: 'app-nav-list',
488
+ standalone: true,
489
+ imports: [JvListComponent, JvListItemComponent, JvBadgeComponent],
490
+ template: `
491
+ <jv-list variant="bordered">
492
+ <jv-list-item
493
+ title="Dashboard"
494
+ description="Main overview"
495
+ leadingIcon="layout-dashboard"
496
+ [active]="true"
497
+ />
498
+ <jv-list-item title="Notifications" description="3 pending" (activated)="onOpen()">
499
+ <jv-badge tone="primary" meta>3</jv-badge>
500
+ </jv-list-item>
501
+ <jv-list-item title="Reports" description="Coming soon" [disabled]="true" />
502
+ </jv-list>
503
+ `,
504
+ })
505
+ export class NavListComponent {
506
+ onOpen() {
507
+ /* handle activation */
508
+ }
509
+ }
510
+ ```
511
+
512
+ ## Pagination API
513
+
514
+ ```typescript
515
+ import { JvPaginationComponent } from '@devjuliovilla/jv-ui';
516
+ ```
517
+
518
+ | Input | Type | Default | Description |
519
+ | ----------------- | ---------- | ------------------- | ------------------------ |
520
+ | `totalItems` | `number` | `0` | Total items |
521
+ | `pageSize` | `number` | `20` | Items per page |
522
+ | `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size options |
523
+ | `pageIndex` | `number` | `0` | Current page (0-based) |
524
+ | `maxVisiblePages` | `number` | `5` | Max page buttons to show |
525
+
526
+ | Output | Type |
527
+ | ------------ | ----------------------------------------- |
528
+ | `pageChange` | `{ pageIndex: number; pageSize: number }` |
529
+
530
+ ## Tabs API
531
+
532
+ ```typescript
533
+ import { JvTabsComponent, JvTabPanelDirective, JvTabItem } from '@devjuliovilla/jv-ui';
534
+ ```
535
+
536
+ **Inputs:**
537
+
538
+ | Input | Type | Default | Description |
539
+ | ------------- | ------------------------------------- | ------- | --------------------------------------------------------- |
540
+ | `tabs` | `JvTabItem[]` | `[]` | Tab definitions (`{ id, label, icon?, disabled? }`) |
541
+ | `activeTabId` | `string \| null` | `null` | Controlled active tab ID |
542
+ | `keepMounted` | `boolean` | `true` | Keep all panels in DOM; `false` renders only active panel |
543
+ | `transition` | `'none' \| 'fade' \| 'slide' \| null` | `null` | Panel transition animation (falls back to global config) |
544
+
545
+ **Outputs:**
546
+
547
+ | Output | Type |
548
+ | ----------------- | -------- |
549
+ | `activeTabChange` | `string` |
550
+
551
+ **Content projection:** use `jvTabPanel` directive on `ng-template` to define panel content:
552
+
553
+ ```html
554
+ <jv-tabs [tabs]="tabs" [activeTabId]="activeTabId()" (activeTabChange)="activeTabId.set($event)">
555
+ <ng-template jvTabPanel="overview">
556
+ <p>Overview content</p>
557
+ </ng-template>
558
+ <ng-template jvTabPanel="analytics">
559
+ <p>Analytics content</p>
560
+ </ng-template>
561
+ </jv-tabs>
562
+ ```
563
+
564
+ ### Tab Transitions
565
+
566
+ Tabs support animated transitions between panels. Configure globally via `provideJvUi()` or per-instance via the `transition` input:
567
+
568
+ ```typescript
569
+ // Global default
570
+ provideJvUi({ tabsTransition: 'fade' });
571
+ ```
572
+
573
+ ```typescript
574
+ // Per-instance override
575
+ <jv-tabs transition="slide" [keepMounted]="false">...</jv-tabs>
576
+ ```
577
+
578
+ | Transition | `keepMounted=true` | `keepMounted=false` | Description |
579
+ | ---------- | ---------------------- | ------------------- | ------------------------------------ |
580
+ | `'none'` | Instant switch | Instant switch | No animation |
581
+ | `'fade'` | Opacity cross-fade | Opacity cross-fade | Smooth fade between panels |
582
+ | `'slide'` | Falls back to `'fade'` | Directional slide | Slides left/right based on tab index |
583
+
584
+ **Note:** `slide` requires `keepMounted=false` because it needs to animate both entering and exiting panels simultaneously. When used with `keepMounted=true`, it automatically falls back to `fade`.
585
+
586
+ ### Tabs Example
587
+
588
+ ```typescript
589
+ import { Component, signal } from '@angular/core';
590
+ import { JvTabItem, JvTabPanelDirective, JvTabsComponent } from '@devjuliovilla/jv-ui';
591
+
592
+ @Component({
593
+ standalone: true,
594
+ imports: [JvTabsComponent, JvTabPanelDirective],
595
+ template: `
596
+ <jv-tabs
597
+ [tabs]="tabs"
598
+ [activeTabId]="activeTabId()"
599
+ transition="fade"
600
+ (activeTabChange)="activeTabId.set($event)"
601
+ >
602
+ <ng-template jvTabPanel="overview">
603
+ <p>Overview content</p>
604
+ </ng-template>
605
+ <ng-template jvTabPanel="analytics">
606
+ <p>Analytics content</p>
607
+ </ng-template>
608
+ </jv-tabs>
609
+ `,
610
+ })
611
+ export class TabsExampleComponent {
612
+ readonly activeTabId = signal('overview');
613
+ readonly tabs: JvTabItem[] = [
614
+ { id: 'overview', label: 'Overview' },
615
+ { id: 'analytics', label: 'Analytics', icon: 'chart-column' },
616
+ ];
617
+ }
618
+ ```
619
+
620
+ ## Image Slider API
621
+
622
+ ```typescript
623
+ import { JvImageSliderComponent, JvSliderImage } from '@devjuliovilla/jv-ui';
624
+ ```
625
+
626
+ **JvSliderImage:**
627
+
628
+ | Property | Type | Required | Description |
629
+ | ------------- | -------- | -------- | ---------------------------------------- |
630
+ | `src` | `string` | Yes | Image URL |
631
+ | `alt` | `string` | Yes | Alternative text for accessibility |
632
+ | `description` | `string` | No | Caption displayed below the image |
633
+ | `thumbnail` | `string` | No | Custom thumbnail URL (defaults to `src`) |
634
+
635
+ **Inputs:**
636
+
637
+ | Input | Type | Default | Description |
638
+ | ----------------- | ----------------- | ------- | --------------------------------- |
639
+ | `images` | `JvSliderImage[]` | `[]` | Array of images to display |
640
+ | `showThumbnails` | `boolean` | `true` | Show thumbnail strip below slider |
641
+ | `showDescription` | `boolean` | `true` | Show image description |
642
+
643
+ **Outputs:**
644
+
645
+ | Output | Type | Description |
646
+ | ------------- | -------- | ------------------------------------- |
647
+ | `imageChange` | `number` | Emits index when active image changes |
648
+
649
+ **i18n support:**
650
+
651
+ The component automatically translates aria labels using `JvTranslationService`:
652
+
653
+ | Key | English | Spanish |
654
+ | ---------------------- | ---------------- | ---------------------- |
655
+ | `slider.prevImage` | Previous image | Imagen anterior |
656
+ | `slider.nextImage` | Next image | Imagen siguiente |
657
+ | `slider.thumbnailList` | Image thumbnails | Miniaturas de imagenes |
658
+
659
+ ### Features
660
+
661
+ - **Keyboard navigation:** ArrowLeft/ArrowRight to navigate, Home/End for first/last image
662
+ - **Responsive:** Images scale to fit container with `object-fit: contain`
663
+ - **Thumbnails:** Scrollable thumbnail strip with active state indicator
664
+ - **Single image mode:** Navigation controls hidden when only one image is provided
665
+ - **Lazy loading:** Images use native `loading="lazy"` attribute
666
+ - **i18n:** Aria labels automatically translated based on configured locale
667
+
668
+ ### Example
669
+
670
+ ```typescript
671
+ import { Component } from '@angular/core';
672
+ import { JvImageSliderComponent, JvSliderImage } from '@devjuliovilla/jv-ui';
673
+
674
+ @Component({
675
+ standalone: true,
676
+ imports: [JvImageSliderComponent],
677
+ template: `
678
+ <jv-image-slider
679
+ [images]="images"
680
+ [showThumbnails]="true"
681
+ [showDescription]="true"
682
+ (imageChange)="onImageChange($event)"
683
+ />
684
+ `,
685
+ })
686
+ export class SliderComponent {
687
+ readonly images: JvSliderImage[] = [
688
+ { src: 'photo1.jpg', alt: 'Sunset', description: 'Beautiful sunset over the ocean' },
689
+ { src: 'photo2.jpg', alt: 'Mountain', description: 'Snow-capped mountain peak' },
690
+ { src: 'photo3.jpg', alt: 'Forest', description: 'Dense forest trail' },
691
+ ];
692
+
693
+ onImageChange(index: number) {
694
+ console.log('Viewing image:', index);
695
+ }
696
+ }
697
+ ```
698
+
699
+ ## Image Gallery API
700
+
701
+ ```typescript
702
+ import { JvImageGalleryComponent, JvGalleryImage, JvGalleryAction } from '@devjuliovilla/jv-ui';
703
+ ```
704
+
705
+ **JvGalleryImage:**
706
+
707
+ | Property | Type | Required | Description |
708
+ | ----------- | -------- | -------- | ---------------------------------------- |
709
+ | `src` | `string` | Yes | Image URL |
710
+ | `alt` | `string` | Yes | Alternative text for accessibility |
711
+ | `thumbnail` | `string` | No | Custom thumbnail URL (defaults to `src`) |
712
+
713
+ **JvGalleryAction:**
714
+
715
+ | Property | Type | Required | Description |
716
+ | -------- | ---------- | -------- | ------------------------ |
717
+ | `id` | `string` | Yes | Unique action identifier |
718
+ | `label` | `string` | Yes | Button label text |
719
+ | `icon` | `string` | No | Lucide icon name |
720
+ | `tone` | `JvIntent` | No | Button variant |
721
+
722
+ **Inputs:**
723
+
724
+ | Input | Type | Default | Description |
725
+ | --------------- | ------------------- | ------- | ------------------------------------------------------------------------------------- |
726
+ | `images` | `JvGalleryImage[]` | `[]` | Array of images to display |
727
+ | `stripHeightVh` | `number` | `25` | Height of the thumbnail strip in viewport-height units, clamped between `0` and `100` |
728
+ | `actions` | `JvGalleryAction[]` | `[]` | Action buttons shown in dialog footer |
729
+
730
+ **Outputs:**
731
+
732
+ | Output | Type | Description |
733
+ | ------------- | --------------------------------------------- | -------------------------------------- |
734
+ | `imageClick` | `JvGalleryImage` | Emits when an image is clicked |
735
+ | `actionClick` | `{ actionId: string; image: JvGalleryImage }` | Emits when an action button is clicked |
736
+
737
+ ### Features
738
+
739
+ - **Horizontal strip:** Scrollable thumbnail strip with configurable height in `vh`
740
+ - **Full-screen viewer:** Click any image to open in a dialog with dark background
741
+ - **Navigation:** Prev/next buttons and keyboard arrows (← →) in the viewer
742
+ - **Configurable actions:** Action buttons in dialog footer (favorite, edit, delete, etc.)
743
+ - **Responsive:** Shows multiple columns on desktop, single column with scroll on mobile
744
+ - **Lazy loading:** All images use native `loading="lazy"` attribute
745
+ - **i18n:** Close and navigation labels automatically translated
746
+
747
+ ### Example
748
+
749
+ ```typescript
750
+ import { Component } from '@angular/core';
751
+ import { JvImageGalleryComponent, JvGalleryImage, JvGalleryAction } from '@devjuliovilla/jv-ui';
752
+
753
+ @Component({
754
+ standalone: true,
755
+ imports: [JvImageGalleryComponent],
756
+ template: `
757
+ <jv-image-gallery
758
+ [images]="images"
759
+ [stripHeightVh]="30"
760
+ [actions]="actions"
761
+ (imageClick)="onImageClick($event)"
762
+ (actionClick)="onActionClick($event)"
763
+ />
764
+ `,
765
+ })
766
+ export class GalleryComponent {
767
+ readonly images: JvGalleryImage[] = [
768
+ { src: 'photo1.jpg', alt: 'Sunset' },
769
+ { src: 'photo2.jpg', alt: 'Mountain' },
770
+ { src: 'photo3.jpg', alt: 'Forest' },
771
+ ];
772
+
773
+ readonly actions: JvGalleryAction[] = [
774
+ { id: 'favorite', label: 'Favorite', icon: 'heart', tone: 'danger' },
775
+ { id: 'edit', label: 'Edit', icon: 'pencil' },
776
+ { id: 'delete', label: 'Delete', icon: 'trash-2', tone: 'danger' },
777
+ ];
778
+
779
+ onImageClick(image: JvGalleryImage) {
780
+ console.log('Viewing:', image.alt);
781
+ }
782
+
783
+ onActionClick(event: { actionId: string; image: JvGalleryImage }) {
784
+ console.log(event.actionId, 'on', event.image.alt);
785
+ }
786
+ }
787
+ ```
788
+
789
+ ## Textarea API
790
+
791
+ ```typescript
792
+ import { JvTextareaComponent } from '@devjuliovilla/jv-ui';
793
+ ```
794
+
795
+ | Input | Type | Default | Description |
796
+ | ------------- | --------- | ----------------- | ---------------------------------------------------- |
797
+ | `placeholder` | `string` | `''` | Placeholder text |
798
+ | `required` | `boolean` | `false` | Mark field as required |
799
+ | `invalid` | `boolean` | `false` | Show invalid state |
800
+ | `readonly` | `boolean` | `false` | Make textarea read-only |
801
+ | `rows` | `number` | `3` | Visible number of rows |
802
+ | `cols` | `number` | — | Visible width in columns |
803
+ | `maxlength` | `number` | — | Maximum character length |
804
+ | `describedBy` | `string` | `''` | ID of description/error element for aria-describedby |
805
+ | `inputId` | `string` | `jv-textarea-{n}` | Auto-generated unique ID |
806
+
807
+ Implements `ControlValueAccessor` — compatible with `[(ngModel)]` and reactive forms via `formControlName`.
808
+
809
+ ### Example
810
+
811
+ ```typescript
812
+ import { Component } from '@angular/core';
813
+ import { JvTextareaComponent } from '@devjuliovilla/jv-ui';
814
+ import { ReactiveFormsModule, FormBuilder } from '@angular/forms';
815
+
816
+ @Component({
817
+ selector: 'app-profile',
818
+ standalone: true,
819
+ imports: [ReactiveFormsModule, JvTextareaComponent],
820
+ template: `
821
+ <jv-textarea
822
+ formControlName="bio"
823
+ placeholder="Tell us about yourself..."
824
+ [rows]="4"
825
+ [maxlength]="500"
826
+ />
827
+ `,
828
+ })
829
+ export class ProfileComponent {
830
+ form = inject(FormBuilder).group({ bio: [''] });
831
+ }
832
+ ```
833
+
834
+ ## Code API
835
+
836
+ ```typescript
837
+ import { JvCodeComponent } from '@devjuliovilla/jv-ui';
838
+ ```
839
+
840
+ | Input | Type | Default | Description |
841
+ | ---------- | ------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------- |
842
+ | `code` | `string` | — | Code or text content to render |
843
+ | `language` | `string` | `''` | Optional language badge |
844
+ | `title` | `string` | `''` | Optional header title |
845
+ | `font` | `'jetbrains-mono' \| 'fira-code' \| 'cascadia' \| 'consolas' \| 'system'` | `'jetbrains-mono'` | Mono font preset for the rendered block |
846
+ | `editable` | `boolean` | `false` | Renders a textarea-style editing surface instead of read-only preview |
847
+ | `width` | `string` | `'100%'` | CSS width applied to the component |
848
+ | `height` | `string` | `'auto'` | CSS height for the editable surface or minimum preview height |
849
+
850
+ Use `JvCode` for read-only payloads or long single-line content where horizontal scrolling should be preserved instead of wrapping.
851
+ The library does not bundle font files. `JvCode` references common mono families and will use any web font you load at the application level.
852
+
853
+ When `editable` is enabled, `JvCode` emits `codeChange` on every edit so the parent can keep the source text in sync.
854
+
855
+ ### Example
856
+
857
+ ```typescript
858
+ import { Component } from '@angular/core';
859
+ import { JvCodeComponent } from '@devjuliovilla/jv-ui';
860
+
861
+ @Component({
862
+ selector: 'app-payload-preview',
863
+ standalone: true,
864
+ imports: [JvCodeComponent],
865
+ template: `
866
+ <jv-code
867
+ [code]="payload"
868
+ language="json"
869
+ title="HTTP payload preview"
870
+ font="fira-code"
871
+ [editable]="true"
872
+ width="100%"
873
+ height="18rem"
874
+ (codeChange)="payload = $event"
875
+ />
876
+ `,
877
+ })
878
+ export class PayloadPreviewComponent {
879
+ payload = '{"status":"ok"}';
880
+ }
881
+ ```
882
+
883
+ If you want hosted fonts without shipping them in your package, load them at the app level, for example:
884
+
885
+ ```css
886
+ @import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap');
887
+ ```
888
+
889
+ ## Confirm Dialog Labels
890
+
891
+ `JvDialogService.confirm()` already supports `confirmLabel` and `cancelLabel` overrides per dialog. If you omit them, the defaults come from the active translation dictionary using `dialog.confirm` and `dialog.cancel`.
892
+
893
+ This lets you either:
894
+
895
+ - override labels directly for a specific action like `Guardar evento` / `Descartar cambios`
896
+ - or register translated defaults in your i18n dictionary for each supported language
897
+
898
+ Example with business copy:
899
+
900
+ ```typescript
901
+ const confirmed = await dialogService.confirm({
902
+ title: 'Guardar evento',
903
+ message: 'Se aplicaran cambios a la agenda del equipo.',
904
+ confirmLabel: 'Guardar evento',
905
+ cancelLabel: 'Descartar cambios',
906
+ tone: 'primary',
907
+ });
908
+
909
+ if (confirmed) {
910
+ saveEvent();
911
+ }
912
+ ```
913
+
914
+ Example using translated defaults from your dictionary:
915
+
916
+ ```typescript
917
+ await dialogService.confirm({
918
+ message: 'This action will publish the current draft.',
919
+ tone: 'primary',
920
+ });
921
+ ```
922
+
923
+ ## Icon System
924
+
925
+ ```typescript
926
+ import { JvIconComponent, JV_LUCIDE_ICON_REGISTRY } from '@devjuliovilla/jv-ui';
927
+ ```
928
+
929
+ | Input | Type | Default | Description |
930
+ | ------------- | --------- | ------- | ----------------------------------------------- |
931
+ | `name` | `string` | — | Icon name (from auto-generated Lucide registry) |
932
+ | `size` | `number` | `24` | Width and height in pixels |
933
+ | `strokeWidth` | `number` | `2` | SVG stroke width |
934
+ | `decorative` | `boolean` | `true` | `aria-hidden="true"` when decorative |
935
+ | `ariaLabel` | `string` | — | Accessible label when not decorative |
936
+
937
+ Icons are auto-generated from [lucide-static](https://www.npmjs.com/package/lucide-static) via:
938
+
939
+ ```bash
940
+ node tools/generate-icons.mjs
941
+ ```
942
+
943
+ This reads all SVG files from `lucide-static/icons` and produces `jv-icon-registry.ts` with the complete set (~1500 icons). Run it after updating `lucide-static` to keep icons in sync.
944
+
945
+ ## Layout API
946
+
947
+ ### JvDashboardShell
948
+
949
+ ```typescript
950
+ import { JvDashboardShellComponent } from '@devjuliovilla/jv-ui';
951
+ ```
952
+
953
+ | Input | Type | Default | Description |
954
+ | ------------------- | ------------------ | ----------- | ------------------------------------------- |
955
+ | `title` | `string` | — | App / brand title |
956
+ | `sidebarSubtitle` | `string` | `''` | Subtitle below brand |
957
+ | `brandIcon` | `string` | `'monitor'` | Brand Lucide icon |
958
+ | `navItems` | `JvNavItem[]` | `[]` | Navigation items (supports nested children) |
959
+ | `sidebarCollapsed` | `boolean` | `false` | Desktop sidebar collapsed state |
960
+ | `mobileSidebarOpen` | `boolean` | `false` | Mobile sidebar open/closed |
961
+ | `topbarTitle` | `string` | `''` | Topbar page title |
962
+ | `topbarSubtitle` | `string` | `''` | Topbar subtitle |
963
+ | `currentTheme` | `JvTheme` | `'light'` | Active theme value |
964
+ | `themeOptions` | `JvThemeOption[]` | `[]` | Theme selector options |
965
+ | `topbarActions` | `JvTopbarAction[]` | `[]` | Icon buttons in topbar |
966
+ | `showThemeSelector` | `boolean` | `true` | Show theme pills |
967
+
968
+ | Output | Description |
969
+ | ----------------------- | -------------------------------------------------------------- |
970
+ | `menuClick` | Hamburger button clicked — toggle mobile sidebar |
971
+ | `mobileClose` | Backdrop clicked or navigation selected — close mobile sidebar |
972
+ | `sidebarCollapseToggle` | Collapse toggle clicked — collapse/expand sidebar |
973
+ | `themeChange` | Theme pill clicked |
974
+ | `topbarActionClick` | Topbar action button clicked |
975
+
976
+ **Mobile behavior:** at viewports ≤ 900px the sidebar becomes a fixed overlay with slide-in animation (`transform: translateX`) and a semi-transparent backdrop. The sidebar emits `mobileClose` when the backdrop is clicked or a nav link is followed.
977
+
978
+ ### JvSidebar
979
+
980
+ | Input | Type | Default | Description |
981
+ | ------------ | ------------- | ---------------------- | --------------------- |
982
+ | `title` | `string` | — | Brand title |
983
+ | `subtitle` | `string` | `''` | Brand subtitle |
984
+ | `brandIcon` | `string` | `'monitor'` | Brand icon |
985
+ | `items` | `JvNavItem[]` | `[]` | Navigation items |
986
+ | `collapsed` | `boolean` | `false` | Collapse to icon-only |
987
+ | `mobileOpen` | `boolean` | `false` | Show on mobile |
988
+ | `ariaLabel` | `string` | `'Sidebar navigation'` | Accessible label |
989
+
990
+ | Output | Description |
991
+ | ---------------- | ------------------------------------------------ |
992
+ | `collapseToggle` | Collapse button clicked |
993
+ | `mobileClose` | Backdrop or nav item interaction — request close |
994
+
995
+ ## Responsive Design
996
+
997
+ The library includes basic responsive behavior:
998
+
999
+ - **Breakpoints** defined as CSS custom properties: `--jv-breakpoint-sm` (640px), `--jv-breakpoint-md` (768px), `--jv-breakpoint-lg` (1024px), `--jv-breakpoint-xl` (1280px)
1000
+ - **Dashboard shell** collapses to single column at ≤ 900px; sidebar becomes a slide-in overlay with backdrop
1001
+ - **Topbar** stacks vertically at ≤ 900px
1002
+ - **Grid** pagination and toolbar stack at ≤ 640px; table scrolls horizontally with `overflow-x: auto`
1003
+ - **Flex-wrap** is used extensively for natural overflow handling
1004
+ - **Dialog** and **Toast** constrain width with `min()` to never exceed the viewport
1005
+
1006
+ ## Services
1007
+
1008
+ | Service | Import Path | Description |
1009
+ | ----------------------- | ---------------------- | -------------------------------------------- |
1010
+ | `JvThemeService` | `@devjuliovilla/jv-ui` | Light / dark / high-contrast theme switching |
1011
+ | `JvTranslationService` | `@devjuliovilla/jv-ui` | Dictionary-based i18n (en/es) |
1012
+ | `JvToastService` | `@devjuliovilla/jv-ui` | Toast notification system |
1013
+ | `JvLoaderService` | `@devjuliovilla/jv-ui` | Full-screen loader with request counter |
1014
+ | `JvDialogService` | `@devjuliovilla/jv-ui` | Programmatic confirm dialogs |
1015
+ | `JvAnnouncementService` | `@devjuliovilla/jv-ui` | Screen-reader live-region announcements |
1016
+
1017
+ ## Accessibility
1018
+
1019
+ - WCAG 2.2 AA target
1020
+ - Keyboard navigation for all interactive components
1021
+ - Focus management with visible focus indicators
1022
+ - Screen reader announcements (loading, empty states, page changes)
1023
+ - `aria-sort` on sortable grid headers
1024
+ - `aria-selected` on selectable grid rows
1025
+ - `aria-label` and `aria-labelledby` on interactive controls
1026
+ - Supports `prefers-reduced-motion`
1027
+
1028
+ ## Requirements
1029
+
1030
+ - Angular 21.2+
1031
+ - TypeScript 5.9+
1032
+
1033
+ ## License
1034
+
1035
+ MIT