@devjuliovilla/jv-ui 1.5.5 → 1.6.0

package/README.md

@@ -1,268 +1,313 @@
-# @devjuliovilla/jv-ui
-
-Accessibility-first Angular component library built with signals and standalone APIs. Includes components, forms, data grids, dialogs, layout primitives, services, and i18n infrastructure.
-
-## Installation
-
-```bash
-npm install @devjuliovilla/jv-ui
-```
-
-Import the theme CSS in your `angular.json` or `styles` array:
-```json
-"styles": ["@devjuliovilla/jv-ui/styles/jv-theme.css"]
-```
-
-## Quick start
-
-```typescript
-import { ApplicationConfig } from '@angular/core';
-import { provideJvUi } from '@devjuliovilla/jv-ui';
-
-export const appConfig: ApplicationConfig = {
-  providers: [provideJvUi({ locale: 'en' })],
-};
-```
-
-```typescript
-import { Component } from '@angular/core';
-import { JvButtonComponent } from '@devjuliovilla/jv-ui';
-
-@Component({
-  selector: 'app-root',
-  standalone: true,
-  imports: [JvButtonComponent],
-  template: '<jv-button variant="primary">Hello</jv-button>',
-})
-export class App {}
-```
-
-## Components
-
-| Category | Components |
-|---|---|
-| Buttons | `JvButton`, `JvButtonGroup`, `JvIconButton` |
-| Forms | `JvInput`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvFormContainer` |
-| Data Grid | `JvGrid` — full-featured data table (see below) |
-| Containers | `JvCard`, `JvSection`, `JvDivider` |
-| Feedback | `JvAlert`, `JvBadge`, `JvLoader`, `JvToast` |
-| Dialogs | `JvDialog`, `JvConfirmDialog` |
-| Layout | `JvDashboardShell`, `JvSidebar`, `JvTopbar`, `JvBreadcrumb`, `JvPage` |
-| Auth Pages | `JvLoginPage`, `JvForgotPasswordPage`, `JvChangePasswordPage` |
-| Icon | `JvIcon` — Lucide-based icon component with 1500+ auto-generated icons |
-| Pagination | `JvPagination` — standalone pagination with i18n |
-
-## Grid Features
-
-| Feature | Description |
-|---|---|
-| Sorting | Client-side multi-column sorting with sort icons and `aria-sort` |
-| Search | Global text search across visible columns |
-| Pagination | Configurable page size, page range buttons, first/last/prev/next |
-| Selection | Checkbox row selection with `selectedIds` / `selectionChange` |
-| Row actions | Custom action buttons per row |
-| Density modes | Compact, normal, comfortable |
-| Sticky columns | Pin columns to left or right |
-| Column resizing | Drag column header borders to resize |
-| Column reordering | Drag & drop column headers |
-| Grouped headers | Multi-row header with `colspan` via `children` |
-| Per-column filters | Filter input row with operators |
-| Inline editing | Double-click or Enter to edit: text, number, select, boolean |
-| Virtual scrolling | Render only visible rows for large datasets |
-| CSV/Excel export | Built-in toolbar buttons, no external deps |
-| Server-side mode | Delegate sort/filter/page to parent component |
-| TrackBy | Custom trackBy key or function |
-| i18n | All labels configurable via translation dictionary |
-
-### Grid API
-
-```typescript
-import { JvGridComponent } from '@devjuliovilla/jv-ui';
-```
-
-**Inputs:**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `data` | `T[]` | `[]` | Row data array |
-| `columns` | `JvGridColumn<T>[]` | `[]` | Column definitions |
-| `actions` | `JvGridAction<T>[]` | `[]` | Row action button configs |
-| `options` | `Partial<JvGridOptions>` | `{}` | Feature toggles and config |
-| `trackBy` | `keyof T \| Function \| null` | `null` | Row identity |
-| `selectedIds` | `(string \| number)[]` | `[]` | Controlled selection IDs |
-
-**Outputs:**
-
-| Output | Type |
-|---|---|
-| `rowClick` | `T` |
-| `rowDoubleClick` | `T` |
-| `actionClick` | `{ actionId: string; row: T }` |
-| `selectionChange` | `(string \| number)[]` |
-| `pageChange` | `{ pageIndex: number; pageSize: number }` |
-| `searchChange` | `string` |
-| `sortChange` | `{ columnKey: string; direction: 'asc' \| 'desc' \| null }` |
-| `columnFilter` | `{ columnKey: string; value: string }` |
-| `columnResize` | `{ columnKey: string; width: string }` |
-| `columnReorder` | `{ columnKey: string; newIndex: number }` |
-| `rowEdit` | `{ row: T; column: JvGridColumn<T>; value: unknown }` |
-
-**JvGridColumn options:**
-
-| Property | Type | Description |
-|---|---|---|
-| `key` | `keyof T \| string` | Data field key |
-| `header` | `string` | Column display header |
-| `sortable` | `boolean` | Enable column sorting |
-| `searchable` | `boolean` | Include in global search |
-| `filterable` | `boolean` | Show per-column filter input |
-| `hidden` | `boolean` | Hide column from display |
-| `sticky` | `'left' \| 'right'` | Pin column position |
-| `editable` | `boolean` | Allow inline cell editing |
-| `editType` | `'text' \| 'number' \| 'select' \| 'boolean'` | Editor type |
-| `editOptions` | `{ label: string; value: unknown }[]` | Options for select editor |
-| `width` | `string` | Column width (e.g. '8rem') |
-| `align` | `'start' \| 'center' \| 'end'` | Text alignment |
-| `type` | `'text' \| 'number' \| 'currency' \| 'date' \| 'datetime' \| 'boolean'` | Data type for formatting |
-| `format` | `(value, row) => string` | Custom display formatter |
-| `children` | `JvGridColumn<T>[]` | Child columns for grouped headers |
-| `resizable` | `boolean` | Allow column resize |
-| `cellClass` | `string` | CSS class for cells |
-| `headerClass` | `string` | CSS class for header |
-
-**JvGridOptions:**
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `searchable` | `boolean` | `true` | Show search bar |
-| `sortable` | `boolean` | `true` | Enable column sorting |
-| `pageable` | `boolean` | `true` | Enable pagination |
-| `selectable` | `boolean` | `false` | Show selection checkboxes |
-| `pageSize` | `number` | `20` | Default page size |
-| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size selector options |
-| `density` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Row density |
-| `loading` | `boolean` | `false` | Show loading spinner |
-| `emptyMessage` | `string` | — | Empty state message |
-| `exportable` | `boolean` | `false` | Show CSV/Excel export buttons |
-| `serverSide` | `boolean` | `false` | Disable client-side processing |
-| `totalItems` | `number` | `0` | Total items for server-side mode |
-| `stickyColumns` | `boolean` | `false` | Enable sticky column support |
-| `resizableColumns` | `boolean` | `false` | Enable column resizing |
-| `reorderableColumns` | `boolean` | `false` | Enable column reordering |
-| `editable` | `boolean` | `false` | Enable inline editing |
-| `virtualScroll` | `boolean` | `false` | Enable virtual scrolling |
-| `virtualScrollRowHeight` | `number` | `48` | Row height for virtual scroll |
-| `columnFilters` | `boolean` | `false` | Show filter row below headers |
-| `rowDoubleClick` | `boolean` | `false` | Enable row double-click event |
-| `ariaLabel` | `string` | — | Accessible label for the grid |
-
-### Grid example
-
-```typescript
-import { Component } from '@angular/core';
-import { JvGridComponent, JvGridColumn, JvGridOptions } from '@devjuliovilla/jv-ui';
-
-interface Product {
-  id: number;
-  name: string;
-  price: number;
-  status: string;
-}
-
-@Component({
-  selector: 'app-products',
-  standalone: true,
-  imports: [JvGridComponent],
-  template: `
-    <jv-grid
-      [data]="products"
-      [columns]="columns"
-      [options]="{ selectable: true, exportable: true, pageSize: 10 }"
-      [trackBy]="'id'"
-      [selectedIds]="selectedIds"
-      (selectionChange)="selectedIds = $event"
-    />
-  `,
-})
-export class ProductsComponent {
-  products: Product[] = [ /* ... */ ];
-  selectedIds: (string | number)[] = [];
-  columns: JvGridColumn<Product>[] = [
-    { key: 'id', header: 'ID', width: '4rem' },
-    { key: 'name', header: 'Product', sortable: true, filterable: true },
-    { key: 'price', header: 'Price', type: 'number', align: 'end', format: (v) => '$' + v },
-    { key: 'status', header: 'Status', sortable: true },
-  ];
-}
-```
-
-## Pagination API
-
-```typescript
-import { JvPaginationComponent } from '@devjuliovilla/jv-ui';
-```
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `totalItems` | `number` | `0` | Total items |
-| `pageSize` | `number` | `20` | Items per page |
-| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size options |
-| `pageIndex` | `number` | `0` | Current page (0-based) |
-| `maxVisiblePages` | `number` | `5` | Max page buttons to show |
-
-| Output | Type |
-|---|---|
-| `pageChange` | `{ pageIndex: number; pageSize: number }` |
-
-## Icon System
-
-```typescript
-import { JvIconComponent, JV_LUCIDE_ICON_REGISTRY } from '@devjuliovilla/jv-ui';
-```
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `name` | `string` | — | Icon name (from auto-generated Lucide registry) |
-| `size` | `number` | `24` | Width and height in pixels |
-| `strokeWidth` | `number` | `2` | SVG stroke width |
-| `decorative` | `boolean` | `true` | `aria-hidden="true"` when decorative |
-| `ariaLabel` | `string` | — | Accessible label when not decorative |
-
-Icons are auto-generated from [lucide-static](https://www.npmjs.com/package/lucide-static) via:
-
-```bash
-node tools/generate-icons.mjs
-```
-
-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.
-
-## Services
-
-| Service | Import Path | Description |
-|---|---|---|
-| `JvThemeService` | `@devjuliovilla/jv-ui` | Light / dark / high-contrast theme switching |
-| `JvTranslationService` | `@devjuliovilla/jv-ui` | Dictionary-based i18n (en/es) |
-| `JvToastService` | `@devjuliovilla/jv-ui` | Toast notification system |
-| `JvLoaderService` | `@devjuliovilla/jv-ui` | Full-screen loader with request counter |
-| `JvDialogService` | `@devjuliovilla/jv-ui` | Programmatic confirm dialogs |
-| `JvAnnouncementService` | `@devjuliovilla/jv-ui` | Screen-reader live-region announcements |
-
-## Accessibility
-
-- WCAG 2.2 AA target
-- Keyboard navigation for all interactive components
-- Focus management with visible focus indicators
-- Screen reader announcements (loading, empty states, page changes)
-- `aria-sort` on sortable grid headers
-- `aria-selected` on selectable grid rows
-- `aria-label` and `aria-labelledby` on interactive controls
-- Supports `prefers-reduced-motion`
-
-## Requirements
-
-- Angular 21.2+
-- TypeScript 5.9+
-
-## License
-
-MIT
+# @devjuliovilla/jv-ui
+
+Accessibility-first Angular component library built with signals and standalone APIs. Includes components, forms, data grids, dialogs, layout primitives, services, and i18n infrastructure.
+
+## Installation
+
+```bash
+npm install @devjuliovilla/jv-ui
+```
+
+Import the theme CSS in your `angular.json` or `styles` array:
+```json
+"styles": ["@devjuliovilla/jv-ui/styles/jv-theme.css"]
+```
+
+## Quick start
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideJvUi } from '@devjuliovilla/jv-ui';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideJvUi({ locale: 'en' })],
+};
+```
+
+```typescript
+import { Component } from '@angular/core';
+import { JvButtonComponent } from '@devjuliovilla/jv-ui';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [JvButtonComponent],
+  template: '<jv-button variant="primary">Hello</jv-button>',
+})
+export class App {}
+```
+
+## Components
+
+| Category | Components |
+|---|---|
+| Buttons | `JvButton`, `JvButtonGroup`, `JvIconButton` |
+| Forms | `JvInput`, `JvTextarea`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvFormContainer` |
+| Data Grid | `JvGrid` — full-featured data table (see below) |
+| Containers | `JvCard`, `JvSection`, `JvDivider` |
+| Feedback | `JvAlert`, `JvBadge`, `JvLoader`, `JvToast` |
+| Dialogs | `JvDialog`, `JvConfirmDialog` |
+| Layout | `JvDashboardShell`, `JvSidebar`, `JvTopbar`, `JvBreadcrumb`, `JvPage` |
+| Auth Pages | `JvLoginPage`, `JvForgotPasswordPage`, `JvChangePasswordPage` |
+| Icon | `JvIcon` — Lucide-based icon component with 1500+ auto-generated icons |
+| Pagination | `JvPagination` — standalone pagination with i18n |
+
+## Grid Features
+
+| Feature | Description |
+|---|---|
+| Sorting | Client-side multi-column sorting with sort icons and `aria-sort` |
+| Search | Global text search across visible columns |
+| Pagination | Configurable page size, page range buttons, first/last/prev/next |
+| Selection | Checkbox row selection with `selectedIds` / `selectionChange` |
+| Row actions | Custom action buttons per row |
+| Density modes | Compact, normal, comfortable |
+| Sticky columns | Pin columns to left or right |
+| Column resizing | Drag column header borders to resize |
+| Column reordering | Drag & drop column headers |
+| Grouped headers | Multi-row header with `colspan` via `children` |
+| Per-column filters | Filter input row with operators |
+| Inline editing | Double-click or Enter to edit: text, number, select, boolean |
+| Virtual scrolling | Render only visible rows for large datasets |
+| CSV/Excel export | Built-in toolbar buttons, no external deps |
+| Server-side mode | Delegate sort/filter/page to parent component |
+| TrackBy | Custom trackBy key or function |
+| i18n | All labels configurable via translation dictionary |
+
+### Grid API
+
+```typescript
+import { JvGridComponent } from '@devjuliovilla/jv-ui';
+```
+
+**Inputs:**
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `data` | `T[]` | `[]` | Row data array |
+| `columns` | `JvGridColumn<T>[]` | `[]` | Column definitions |
+| `actions` | `JvGridAction<T>[]` | `[]` | Row action button configs |
+| `options` | `Partial<JvGridOptions>` | `{}` | Feature toggles and config |
+| `trackBy` | `keyof T \| Function \| null` | `null` | Row identity |
+| `selectedIds` | `(string \| number)[]` | `[]` | Controlled selection IDs |
+
+**Outputs:**
+
+| Output | Type |
+|---|---|
+| `rowClick` | `T` |
+| `rowDoubleClick` | `T` |
+| `actionClick` | `{ actionId: string; row: T }` |
+| `selectionChange` | `(string \| number)[]` |
+| `pageChange` | `{ pageIndex: number; pageSize: number }` |
+| `searchChange` | `string` |
+| `sortChange` | `{ columnKey: string; direction: 'asc' \| 'desc' \| null }` |
+| `columnFilter` | `{ columnKey: string; value: string }` |
+| `columnResize` | `{ columnKey: string; width: string }` |
+| `columnReorder` | `{ columnKey: string; newIndex: number }` |
+| `rowEdit` | `{ row: T; column: JvGridColumn<T>; value: unknown }` |
+
+**JvGridColumn options:**
+
+| Property | Type | Description |
+|---|---|---|
+| `key` | `keyof T \| string` | Data field key |
+| `header` | `string` | Column display header |
+| `sortable` | `boolean` | Enable column sorting |
+| `searchable` | `boolean` | Include in global search |
+| `filterable` | `boolean` | Show per-column filter input |
+| `hidden` | `boolean` | Hide column from display |
+| `sticky` | `'left' \| 'right'` | Pin column position |
+| `editable` | `boolean` | Allow inline cell editing |
+| `editType` | `'text' \| 'number' \| 'select' \| 'boolean'` | Editor type |
+| `editOptions` | `{ label: string; value: unknown }[]` | Options for select editor |
+| `width` | `string` | Column width (e.g. '8rem') |
+| `align` | `'start' \| 'center' \| 'end'` | Text alignment |
+| `type` | `'text' \| 'number' \| 'currency' \| 'date' \| 'datetime' \| 'boolean'` | Data type for formatting |
+| `format` | `(value, row) => string` | Custom display formatter |
+| `children` | `JvGridColumn<T>[]` | Child columns for grouped headers |
+| `resizable` | `boolean` | Allow column resize |
+| `cellClass` | `string` | CSS class for cells |
+| `headerClass` | `string` | CSS class for header |
+
+**JvGridOptions:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `searchable` | `boolean` | `true` | Show search bar |
+| `sortable` | `boolean` | `true` | Enable column sorting |
+| `pageable` | `boolean` | `true` | Enable pagination |
+| `selectable` | `boolean` | `false` | Show selection checkboxes |
+| `pageSize` | `number` | `20` | Default page size |
+| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size selector options |
+| `density` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Row density |
+| `loading` | `boolean` | `false` | Show loading spinner |
+| `emptyMessage` | `string` | — | Empty state message |
+| `exportable` | `boolean` | `false` | Show CSV/Excel export buttons |
+| `serverSide` | `boolean` | `false` | Disable client-side processing |
+| `totalItems` | `number` | `0` | Total items for server-side mode |
+| `stickyColumns` | `boolean` | `false` | Enable sticky column support |
+| `resizableColumns` | `boolean` | `false` | Enable column resizing |
+| `reorderableColumns` | `boolean` | `false` | Enable column reordering |
+| `editable` | `boolean` | `false` | Enable inline editing |
+| `virtualScroll` | `boolean` | `false` | Enable virtual scrolling |
+| `virtualScrollRowHeight` | `number` | `48` | Row height for virtual scroll |
+| `columnFilters` | `boolean` | `false` | Show filter row below headers |
+| `rowDoubleClick` | `boolean` | `false` | Enable row double-click event |
+| `ariaLabel` | `string` | — | Accessible label for the grid |
+
+### Grid example
+
+```typescript
+import { Component } from '@angular/core';
+import { JvGridComponent, JvGridColumn, JvGridOptions } from '@devjuliovilla/jv-ui';
+
+interface Product {
+  id: number;
+  name: string;
+  price: number;
+  status: string;
+}
+
+@Component({
+  selector: 'app-products',
+  standalone: true,
+  imports: [JvGridComponent],
+  template: `
+    <jv-grid
+      [data]="products"
+      [columns]="columns"
+      [options]="{ selectable: true, exportable: true, pageSize: 10 }"
+      [trackBy]="'id'"
+      [selectedIds]="selectedIds"
+      (selectionChange)="selectedIds = $event"
+    />
+  `,
+})
+export class ProductsComponent {
+  products: Product[] = [ /* ... */ ];
+  selectedIds: (string | number)[] = [];
+  columns: JvGridColumn<Product>[] = [
+    { key: 'id', header: 'ID', width: '4rem' },
+    { key: 'name', header: 'Product', sortable: true, filterable: true },
+    { key: 'price', header: 'Price', type: 'number', align: 'end', format: (v) => '$' + v },
+    { key: 'status', header: 'Status', sortable: true },
+  ];
+}
+```
+
+## Pagination API
+
+```typescript
+import { JvPaginationComponent } from '@devjuliovilla/jv-ui';
+```
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `totalItems` | `number` | `0` | Total items |
+| `pageSize` | `number` | `20` | Items per page |
+| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size options |
+| `pageIndex` | `number` | `0` | Current page (0-based) |
+| `maxVisiblePages` | `number` | `5` | Max page buttons to show |
+
+| Output | Type |
+|---|---|
+| `pageChange` | `{ pageIndex: number; pageSize: number }` |
+
+## Textarea API
+
+```typescript
+import { JvTextareaComponent } from '@devjuliovilla/jv-ui';
+```
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `placeholder` | `string` | `''` | Placeholder text |
+| `required` | `boolean` | `false` | Mark field as required |
+| `invalid` | `boolean` | `false` | Show invalid state |
+| `readonly` | `boolean` | `false` | Make textarea read-only |
+| `rows` | `number` | `3` | Visible number of rows |
+| `cols` | `number` | — | Visible width in columns |
+| `maxlength` | `number` | — | Maximum character length |
+| `describedBy` | `string` | `''` | ID of description/error element for aria-describedby |
+| `inputId` | `string` | `jv-textarea-{n}` | Auto-generated unique ID |
+
+Implements `ControlValueAccessor` — compatible with `[(ngModel)]` and reactive forms via `formControlName`.
+
+### Example
+
+```typescript
+import { Component } from '@angular/core';
+import { JvTextareaComponent } from '@devjuliovilla/jv-ui';
+import { ReactiveFormsModule, FormBuilder } from '@angular/forms';
+
+@Component({
+  selector: 'app-profile',
+  standalone: true,
+  imports: [ReactiveFormsModule, JvTextareaComponent],
+  template: `
+    <jv-textarea
+      formControlName="bio"
+      placeholder="Tell us about yourself..."
+      [rows]="4"
+      [maxlength]="500"
+    />
+  `,
+})
+export class ProfileComponent {
+  form = inject(FormBuilder).group({ bio: [''] });
+}
+```
+
+## Icon System
+
+```typescript
+import { JvIconComponent, JV_LUCIDE_ICON_REGISTRY } from '@devjuliovilla/jv-ui';
+```
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | — | Icon name (from auto-generated Lucide registry) |
+| `size` | `number` | `24` | Width and height in pixels |
+| `strokeWidth` | `number` | `2` | SVG stroke width |
+| `decorative` | `boolean` | `true` | `aria-hidden="true"` when decorative |
+| `ariaLabel` | `string` | — | Accessible label when not decorative |
+
+Icons are auto-generated from [lucide-static](https://www.npmjs.com/package/lucide-static) via:
+
+```bash
+node tools/generate-icons.mjs
+```
+
+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.
+
+## Services
+
+| Service | Import Path | Description |
+|---|---|---|
+| `JvThemeService` | `@devjuliovilla/jv-ui` | Light / dark / high-contrast theme switching |
+| `JvTranslationService` | `@devjuliovilla/jv-ui` | Dictionary-based i18n (en/es) |
+| `JvToastService` | `@devjuliovilla/jv-ui` | Toast notification system |
+| `JvLoaderService` | `@devjuliovilla/jv-ui` | Full-screen loader with request counter |
+| `JvDialogService` | `@devjuliovilla/jv-ui` | Programmatic confirm dialogs |
+| `JvAnnouncementService` | `@devjuliovilla/jv-ui` | Screen-reader live-region announcements |
+
+## Accessibility
+
+- WCAG 2.2 AA target
+- Keyboard navigation for all interactive components
+- Focus management with visible focus indicators
+- Screen reader announcements (loading, empty states, page changes)
+- `aria-sort` on sortable grid headers
+- `aria-selected` on selectable grid rows
+- `aria-label` and `aria-labelledby` on interactive controls
+- Supports `prefers-reduced-motion`
+
+## Requirements
+
+- Angular 21.2+
+- TypeScript 5.9+
+
+## License
+
+MIT