@devjuliovilla/jv-ui 1.5.4 → 1.5.6

package/README.md

@@ -8,19 +8,26 @@ Accessibility-first Angular component library built with signals and standalone
 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 { Component } from '@angular/core';
+import { ApplicationConfig } from '@angular/core';
 import { provideJvUi } from '@devjuliovilla/jv-ui';
-import { JvButtonComponent } from '@devjuliovilla/jv-ui';
 
-// In your app.config.ts:
 export const appConfig: ApplicationConfig = {
   providers: [provideJvUi({ locale: 'en' })],
 };
+```
+
+```typescript
+import { Component } from '@angular/core';
+import { JvButtonComponent } from '@devjuliovilla/jv-ui';
 
-// In your component:
 @Component({
   selector: 'app-root',
   standalone: true,
@@ -35,56 +42,236 @@ export class App {}
 | Category | Components |
 |---|---|
 | Buttons | `JvButton`, `JvButtonGroup`, `JvIconButton` |
-| Forms | `JvInput`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvFormContainer` |
-| Data Grid | `JvGrid` — sortable, searchable, paged, selectable, row actions, density modes, sticky columns, column resize/reorder, grouped headers, per-column filters, inline editing, virtual scrolling, CSV/Excel export, server-side mode |
+| 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+ icons auto-generated from lucide-static |
-| Pagination | `JvPagination` — standalone pagination with page size selector, max visible pages, i18n, and full event handling |
+| Icon | `JvIcon` — Lucide-based icon component with 1500+ auto-generated icons |
+| Pagination | `JvPagination` — standalone pagination with i18n |
 
-## Services
+## Grid Features
 
-| Service | Description |
+| Feature | Description |
 |---|---|
-| `JvThemeService` | Light / dark / high-contrast theme switching |
-| `JvTranslationService` | Locale switching (es/en) with dictionary-based i18n |
-| `JvToastService` | Toast notification system |
-| `JvLoaderService` | Full-screen loader overlay |
-| `JvDialogService` | Programmatic confirm dialogs |
-| `JvAnnouncementService` | Screen-reader live-region announcements |
+| 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 Features
+### Grid API
 
-`JvGrid` includes the following capabilities:
+```typescript
+import { JvGridComponent } from '@devjuliovilla/jv-ui';
+```
 
-| Feature | Description |
+**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 |
 |---|---|
-| Sorting | Client-side multi-column sorting with sort icons |
-| Search | Global text search across all visible columns |
-| Pagination | Built-in pagination with configurable page sizes |
-| Selection | Checkbox row selection with `selectedIds` input / `selectionChange` output |
-| Row actions | Custom action buttons per row via `rowActions` template |
-| Density modes | Compact / comfortable / spacious |
-| Sticky columns | Pin columns to left or right via `sticky` column option |
-| Column resizing | Drag column header borders to resize (`resizableColumns` option) |
-| Column reordering | Drag and drop column headers to reorder (`reorderableColumns` option) |
-| Grouped headers | Multi-row header with `colspan` via `children` on column definitions |
-| Per-column filters | Filter input row below headers with operator selection (`filterable` option) |
-| Inline editing | Edit cells inline with text/number/select/boolean editors (`editable` option) |
-| Virtual scrolling | Render only visible rows for large datasets (`virtualScroll` option) |
-| CSV/Excel export | Export toolbar buttons (`exportable` option), no external dependencies |
-| Server-side mode | Disable client-side sorting/filtering/paging, emit events for server handling |
-| TrackBy | Custom trackBy function or property key for optimized rendering |
+| `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 }` |
 
-## Requirements
+**JvGridColumn options:**
 
-- Angular 21.2+
-- TypeScript 5.9+
+| 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
 
-## Icon generation
+```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:
 
@@ -92,7 +279,34 @@ Icons are auto-generated from [lucide-static](https://www.npmjs.com/package/luci
 node tools/generate-icons.mjs
 ```
 
-The script reads all ~1500 SVG files from `lucide-static/icons` and produces `jv-icon-registry.ts` with the complete set. Run it after updating lucide-static to keep icons in sync.
+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