@devjuliovilla/jv-ui 1.5.3 → 1.5.5

package/README.md

@@ -1,65 +1,268 @@
-# @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
-```
-
-## Quick start
-
-```typescript
-import { Component } 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' })],
-};
-
-// In your component:
-@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` — sortable, searchable, paged, selectable, row actions, density modes |
-| 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 |
-
-## Services
-
-| Service | 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 |
-
-## 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`, `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