@devjuliovilla/jv-ui 1.13.0 → 1.15.0

package/README.md

@@ -1,994 +1,1035 @@
-# @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({ messagesLocale: 'en', formatLocale: 'en-US' })],
-};
-```
-
-```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` |
-| Calendar | `JvMonthCalendar`, `JvDayPlanner` — reusable month view and agenda primitives, usable together or independently |
-| Forms | `JvInput`, `JvTextarea`, `JvCode`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvDatePicker`, `JvModalSelector`, `JvFileInput`, `JvFormContainer` |
-| Data Grid | `JvGrid` — full-featured data table (see below) |
-| Containers | `JvCard`, `JvSection`, `JvDivider` |
-| List | `JvList`, `JvListItem` — list with title, description, icons, badges, and interactive items |
-| Tabs | `JvTabs`, `JvTabPanelDirective` — horizontal tabs with keyboard navigation and animated transitions |
-| Slider | `JvImageSlider` — responsive image slider with thumbnails and keyboard navigation |
-| Gallery | `JvImageGallery` — horizontal image gallery with wheel scrolling and full-screen viewer |
-| Feedback | `JvAlert`, `JvBadge`, `JvLoader`, `JvToast` |
-| Dialogs | `JvDialog`, `JvConfirmDialog`, `JvWindowModal` — compact dialogs plus a larger workflow overlay surface |
-| 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 |
-
-## Calendar API
-
-The scheduling primitives are split into **two separate components**:
-
-- `JvMonthCalendar`: inline month grid with selection, navigation, and day markers
-- `JvDayPlanner`: agenda / list view for scheduled items with optional grouping and expandable details
-
-You can use either one on its own, or compose both together in a master-detail scheduling layout.
-
-### JvMonthCalendar
-
-```typescript
-import {
-  JvMonthCalendarComponent,
-  JvMonthCalendarDayDirective,
-  JvMonthCalendarDayMeta,
-} from '@devjuliovilla/jv-ui';
-```
-
-**Inputs:**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `value` | `Date \| string \| null` | `undefined` | Selected day |
-| `visibleMonth` | `Date \| string \| null` | `undefined` | Controlled visible month independent from the selected day |
-| `dayMeta` | `JvMonthCalendarDayMeta[]` | `[]` | Marker/counter metadata per day |
-| `ariaLabel` | `string` | localized default | Accessible label for the grid |
-| `monthLabel` | `string` | `Month` | Accessible label for the month selector |
-| `yearLabel` | `string` | `Year` | Accessible label for the year selector |
-| `minYear` | `number` | current year - 10 | Lower year bound for the year selector |
-| `maxYear` | `number` | current year + 10 | Upper year bound for the year selector |
-| `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 |
-
-**Outputs:**
-
-| Output | Type |
-|---|---|
-| `selectionChange` | `Date` |
-| `visibleMonthChange` | `Date` |
-
-**Day metadata:**
-
-| Property | Type | Description |
-|---|---|---|
-| `date` | `Date \| string` | Day associated with the marker |
-| `count` | `number` | Optional numeric badge rendered inside the cell |
-| `tone` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'neutral'` | Visual tone for the badge or dot |
-| `label` | `string` | Extra accessibility text appended to the day `aria-label` |
-
-**Template hook:**
-
-Use `ng-template[jvMonthCalendarDay]` to fully customize the day cell.
-
-**Standalone example:**
-
-```typescript
-import { Component, signal } from '@angular/core';
-import { JvMonthCalendarComponent, JvMonthCalendarDayMeta } from '@devjuliovilla/jv-ui';
-
-@Component({
-  selector: 'app-calendar-only',
-  standalone: true,
-  imports: [JvMonthCalendarComponent],
-  template: `
-    <jv-month-calendar
-      [value]="selectedDate()"
-      [dayMeta]="calendarMeta"
-      (selectionChange)="selectedDate.set($event)"
-    />
-  `,
-})
-export class CalendarOnlyComponent {
-  readonly selectedDate = signal(new Date(2026, 5, 15));
-  readonly calendarMeta: JvMonthCalendarDayMeta[] = [
-    { date: '2026-06-15', count: 2, tone: 'primary', label: '2 activities' },
-    { date: '2026-06-16', count: 1, tone: 'secondary', label: '1 activity' },
-  ];
-}
-```
-
-### JvDayPlanner
-
-```typescript
-import {
-  JvDayPlannerComponent,
-  JvDayPlannerDetailDirective,
-  JvDayPlannerItem,
-  JvDayPlannerItemDirective,
-} from '@devjuliovilla/jv-ui';
-```
-
-**Inputs:**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `items` | `JvDayPlannerItem[]` | `[]` | Agenda items |
-| `groupByDate` | `boolean` | `false` | Group items under a date heading |
-| `emptyMessage` | `string` | localized default | Empty state copy |
-| `ariaLabel` | `string` | localized default | Accessible label for the agenda |
-| `defaultExpandedItemIds` | `(string \| number)[]` | `[]` | Items whose detail should start expanded |
-
-**Outputs:**
-
-| Output | Type |
-|---|---|
-| `itemSelect` | `JvDayPlannerItem` |
-
-**Planner item shape:**
-
-| Property | Type | Description |
-|---|---|---|
-| `id` | `string \| number` | Stable identity |
-| `title` | `string` | Primary label |
-| `date` | `Date \| string \| null` | Logical day when start time is not enough |
-| `start` | `Date \| string \| null` | Optional start datetime |
-| `end` | `Date \| string \| null` | Optional end datetime |
-| `status` | `string` | Status badge label |
-| `statusTone` | `JvTone` | Visual tone for status badge |
-| `type` | `string` | Type/category badge label |
-| `typeTone` | `JvTone` | Visual tone for type badge |
-| `responsible` | `string` | Responsible person |
-| `location` | `string` | Location metadata |
-| `details` | `string` | Expandable detail text |
-| `completed` | `boolean` | Reduced emphasis for completed items |
-
-**Template hooks:**
-
-- `ng-template[jvDayPlannerItem]` customizes the visible item row
-- `ng-template[jvDayPlannerDetail]` customizes the expanded detail panel
-
-**Standalone example:**
-
-```typescript
-import { Component } from '@angular/core';
-import { JvDayPlannerComponent, JvDayPlannerItem } from '@devjuliovilla/jv-ui';
-
-@Component({
-  selector: 'app-planner-only',
-  standalone: true,
-  imports: [JvDayPlannerComponent],
-  template: `
-    <jv-day-planner
-      [items]="items"
-      [groupByDate]="true"
-      (itemSelect)="handleSelect($event)"
-    />
-  `,
-})
-export class PlannerOnlyComponent {
-  readonly items: JvDayPlannerItem[] = [
-    {
-      id: 1,
-      title: 'Venue setup',
-      start: '2026-06-15T08:30:00',
-      end: '2026-06-15T10:00:00',
-      status: 'Scheduled',
-      statusTone: 'primary',
-      type: 'Logistics',
-      responsible: 'Ana Lopez',
-      location: 'Main hall',
-      details: 'Prepare seating and signage.',
-    },
-  ];
-
-  handleSelect(item: JvDayPlannerItem) {
-    console.log(item);
-  }
-}
-```
-
-### Combined example
-
-Use both components together when you need a left-side month selector and a right-side agenda:
-
-```html
-<jv-month-calendar
-  [value]="selectedDate()"
-  [dayMeta]="calendarMeta()"
-  (selectionChange)="selectedDate.set($event)"
-/>
-
-<jv-day-planner
-  [items]="filteredItems()"
-  [groupByDate]="showAll()"
-  (itemSelect)="selectedItem.set($event)"
-/>
-```
-
-## 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' \| 'integer' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'time' \| 'datetime' \| 'boolean'` | Data type for formatting |
-| `formatOptions` | `Intl.NumberFormatOptions & Intl.DateTimeFormatOptions` | Per-column formatting overrides |
-| `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 |
-| `exportFileName` | `string` | `''` | Base filename used for CSV/Excel exports; the component applies the correct extension |
-| `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, exportFileName: 'products', 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 },
-  ];
-}
-```
-
-## List API
-
-```typescript
-import { JvListComponent, JvListItemComponent } from '@devjuliovilla/jv-ui';
-```
-
-**JvList inputs:**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `role` | `'list' \| 'navigation'` | `'list'` | ARIA role for the list |
-| `variant` | `'bordered' \| null` | `null` | Outer border + border-radius around the list (items always have bottom border) |
-| `ariaLabel` | `string` | `''` | Accessible label |
-
-**JvListItem inputs:**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `title` | `string` (required) | — | Primary text |
-| `description` | `string` | `''` | Secondary text below title |
-| `leadingIcon` | `string \| null` | `null` | Lucide icon name on the left |
-| `disabled` | `boolean` | `false` | Gray out and block interaction |
-| `active` | `boolean` | `false` | Highlight with primary color and left border |
-
-**JvListItem outputs:**
-
-| Output | Type |
-|---|---|
-| `activated` | `void` |
-
-**Content projection:** use the `meta` attribute selector for badges, icons, or any content on the right side:
-
-```html
-<jv-list-item title="Inbox" description="New messages">
-  <jv-badge tone="primary" meta>3</jv-badge>
-  <jv-icon name="chevron-right" meta />
-</jv-list-item>
-```
-
-### Example
-
-```typescript
-import { Component } from '@angular/core';
-import { JvListComponent, JvListItemComponent, JvBadgeComponent } from '@devjuliovilla/jv-ui';
-
-@Component({
-  selector: 'app-nav-list',
-  standalone: true,
-  imports: [JvListComponent, JvListItemComponent, JvBadgeComponent],
-  template: `
-    <jv-list variant="bordered">
-      <jv-list-item
-        title="Dashboard"
-        description="Main overview"
-        leadingIcon="layout-dashboard"
-        [active]="true"
-      />
-      <jv-list-item
-        title="Notifications"
-        description="3 pending"
-        (activated)="onOpen()"
-      >
-        <jv-badge tone="primary" meta>3</jv-badge>
-      </jv-list-item>
-      <jv-list-item
-        title="Reports"
-        description="Coming soon"
-        [disabled]="true"
-      />
-    </jv-list>
-  `,
-})
-export class NavListComponent {
-  onOpen() { /* handle activation */ }
-}
-```
-
-## 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 }` |
-
-## Tabs API
-
-```typescript
-import { JvTabsComponent, JvTabPanelDirective, JvTabItem } from '@devjuliovilla/jv-ui';
-```
-
-**Inputs:**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `tabs` | `JvTabItem[]` | `[]` | Tab definitions (`{ id, label, icon?, disabled? }`) |
-| `activeTabId` | `string \| null` | `null` | Controlled active tab ID |
-| `keepMounted` | `boolean` | `true` | Keep all panels in DOM; `false` renders only active panel |
-| `transition` | `'none' \| 'fade' \| 'slide' \| null` | `null` | Panel transition animation (falls back to global config) |
-
-**Outputs:**
-
-| Output | Type |
-|---|---|
-| `activeTabChange` | `string` |
-
-**Content projection:** use `jvTabPanel` directive on `ng-template` to define panel content:
-
-```html
-<jv-tabs [tabs]="tabs" [activeTabId]="activeTabId()" (activeTabChange)="activeTabId.set($event)">
-  <ng-template jvTabPanel="overview">
-    <p>Overview content</p>
-  </ng-template>
-  <ng-template jvTabPanel="analytics">
-    <p>Analytics content</p>
-  </ng-template>
-</jv-tabs>
-```
-
-### Tab Transitions
-
-Tabs support animated transitions between panels. Configure globally via `provideJvUi()` or per-instance via the `transition` input:
-
-```typescript
-// Global default
-provideJvUi({ tabsTransition: 'fade' })
-```
-
-```typescript
-// Per-instance override
-<jv-tabs transition="slide" [keepMounted]="false">...</jv-tabs>
-```
-
-| Transition | `keepMounted=true` | `keepMounted=false` | Description |
-|---|---|---|---|
-| `'none'` | Instant switch | Instant switch | No animation |
-| `'fade'` | Opacity cross-fade | Opacity cross-fade | Smooth fade between panels |
-| `'slide'` | Falls back to `'fade'` | Directional slide | Slides left/right based on tab index |
-
-**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`.
-
-### Tabs Example
-
-```typescript
-import { Component, signal } from '@angular/core';
-import { JvTabItem, JvTabPanelDirective, JvTabsComponent } from '@devjuliovilla/jv-ui';
-
-@Component({
-  standalone: true,
-  imports: [JvTabsComponent, JvTabPanelDirective],
-  template: `
-    <jv-tabs
-      [tabs]="tabs"
-      [activeTabId]="activeTabId()"
-      transition="fade"
-      (activeTabChange)="activeTabId.set($event)"
-    >
-      <ng-template jvTabPanel="overview">
-        <p>Overview content</p>
-      </ng-template>
-      <ng-template jvTabPanel="analytics">
-        <p>Analytics content</p>
-      </ng-template>
-    </jv-tabs>
-  `,
-})
-export class TabsExampleComponent {
-  readonly activeTabId = signal('overview');
-  readonly tabs: JvTabItem[] = [
-    { id: 'overview', label: 'Overview' },
-    { id: 'analytics', label: 'Analytics', icon: 'chart-column' },
-  ];
-}
-```
-
-## Image Slider API
-
-```typescript
-import { JvImageSliderComponent, JvSliderImage } from '@devjuliovilla/jv-ui';
-```
-
-**JvSliderImage:**
-
-| Property | Type | Required | Description |
-|---|---|---|---|
-| `src` | `string` | Yes | Image URL |
-| `alt` | `string` | Yes | Alternative text for accessibility |
-| `description` | `string` | No | Caption displayed below the image |
-| `thumbnail` | `string` | No | Custom thumbnail URL (defaults to `src`) |
-
-**Inputs:**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `images` | `JvSliderImage[]` | `[]` | Array of images to display |
-| `showThumbnails` | `boolean` | `true` | Show thumbnail strip below slider |
-| `showDescription` | `boolean` | `true` | Show image description |
-
-**Outputs:**
-
-| Output | Type | Description |
-|---|---|---|
-| `imageChange` | `number` | Emits index when active image changes |
-
-**i18n support:**
-
-The component automatically translates aria labels using `JvTranslationService`:
-
-| Key | English | Spanish |
-|---|---|---|
-| `slider.prevImage` | Previous image | Imagen anterior |
-| `slider.nextImage` | Next image | Imagen siguiente |
-| `slider.thumbnailList` | Image thumbnails | Miniaturas de imagenes |
-
-### Features
-
-- **Keyboard navigation:** ArrowLeft/ArrowRight to navigate, Home/End for first/last image
-- **Responsive:** Images scale to fit container with `object-fit: contain`
-- **Thumbnails:** Scrollable thumbnail strip with active state indicator
-- **Single image mode:** Navigation controls hidden when only one image is provided
-- **Lazy loading:** Images use native `loading="lazy"` attribute
-- **i18n:** Aria labels automatically translated based on configured locale
-
-### Example
-
-```typescript
-import { Component } from '@angular/core';
-import { JvImageSliderComponent, JvSliderImage } from '@devjuliovilla/jv-ui';
-
-@Component({
-  standalone: true,
-  imports: [JvImageSliderComponent],
-  template: `
-    <jv-image-slider
-      [images]="images"
-      [showThumbnails]="true"
-      [showDescription]="true"
-      (imageChange)="onImageChange($event)"
-    />
-  `,
-})
-export class SliderComponent {
-  readonly images: JvSliderImage[] = [
-    { src: 'photo1.jpg', alt: 'Sunset', description: 'Beautiful sunset over the ocean' },
-    { src: 'photo2.jpg', alt: 'Mountain', description: 'Snow-capped mountain peak' },
-    { src: 'photo3.jpg', alt: 'Forest', description: 'Dense forest trail' },
-  ];
-
-  onImageChange(index: number) {
-    console.log('Viewing image:', index);
-  }
-}
-```
-
-## Image Gallery API
-
-```typescript
-import { JvImageGalleryComponent, JvGalleryImage, JvGalleryAction } from '@devjuliovilla/jv-ui';
-```
-
-**JvGalleryImage:**
-
-| Property | Type | Required | Description |
-|---|---|---|---|
-| `src` | `string` | Yes | Image URL |
-| `alt` | `string` | Yes | Alternative text for accessibility |
-| `thumbnail` | `string` | No | Custom thumbnail URL (defaults to `src`) |
-
-**JvGalleryAction:**
-
-| Property | Type | Required | Description |
-|---|---|---|---|
-| `id` | `string` | Yes | Unique action identifier |
-| `label` | `string` | Yes | Button label text |
-| `icon` | `string` | No | Lucide icon name |
-| `tone` | `JvIntent` | No | Button variant |
-
-**Inputs:**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `images` | `JvGalleryImage[]` | `[]` | Array of images to display |
-| `stripHeightVh` | `number` | `25` | Height of the thumbnail strip in viewport-height units, clamped between `0` and `100` |
-| `actions` | `JvGalleryAction[]` | `[]` | Action buttons shown in dialog footer |
-
-**Outputs:**
-
-| Output | Type | Description |
-|---|---|---|
-| `imageClick` | `JvGalleryImage` | Emits when an image is clicked |
-| `actionClick` | `{ actionId: string; image: JvGalleryImage }` | Emits when an action button is clicked |
-
-### Features
-
-- **Horizontal strip:** Scrollable thumbnail strip with configurable height in `vh`
-- **Full-screen viewer:** Click any image to open in a dialog with dark background
-- **Navigation:** Prev/next buttons and keyboard arrows (← →) in the viewer
-- **Configurable actions:** Action buttons in dialog footer (favorite, edit, delete, etc.)
-- **Responsive:** Shows multiple columns on desktop, single column with scroll on mobile
-- **Lazy loading:** All images use native `loading="lazy"` attribute
-- **i18n:** Close and navigation labels automatically translated
-
-### Example
-
-```typescript
-import { Component } from '@angular/core';
-import { JvImageGalleryComponent, JvGalleryImage, JvGalleryAction } from '@devjuliovilla/jv-ui';
-
-@Component({
-  standalone: true,
-  imports: [JvImageGalleryComponent],
-  template: `
-    <jv-image-gallery
-      [images]="images"
-      [stripHeightVh]="30"
-      [actions]="actions"
-      (imageClick)="onImageClick($event)"
-      (actionClick)="onActionClick($event)"
-    />
-  `,
-})
-export class GalleryComponent {
-  readonly images: JvGalleryImage[] = [
-    { src: 'photo1.jpg', alt: 'Sunset' },
-    { src: 'photo2.jpg', alt: 'Mountain' },
-    { src: 'photo3.jpg', alt: 'Forest' },
-  ];
-
-  readonly actions: JvGalleryAction[] = [
-    { id: 'favorite', label: 'Favorite', icon: 'heart', tone: 'danger' },
-    { id: 'edit', label: 'Edit', icon: 'pencil' },
-    { id: 'delete', label: 'Delete', icon: 'trash-2', tone: 'danger' },
-  ];
-
-  onImageClick(image: JvGalleryImage) {
-    console.log('Viewing:', image.alt);
-  }
-
-  onActionClick(event: { actionId: string; image: JvGalleryImage }) {
-    console.log(event.actionId, 'on', event.image.alt);
-  }
-}
-```
-
-## 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: [''] });
-}
-```
-
-## Code API
-
-```typescript
-import { JvCodeComponent } from '@devjuliovilla/jv-ui';
-```
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `code` | `string` | — | Code or text content to render |
-| `language` | `string` | `''` | Optional language badge |
-| `title` | `string` | `''` | Optional header title |
-| `font` | `'jetbrains-mono' \| 'fira-code' \| 'cascadia' \| 'consolas' \| 'system'` | `'jetbrains-mono'` | Mono font preset for the rendered block |
-| `editable` | `boolean` | `false` | Renders a textarea-style editing surface instead of read-only preview |
-| `width` | `string` | `'100%'` | CSS width applied to the component |
-| `height` | `string` | `'auto'` | CSS height for the editable surface or minimum preview height |
-
-Use `JvCode` for read-only payloads or long single-line content where horizontal scrolling should be preserved instead of wrapping.
-The library does not bundle font files. `JvCode` references common mono families and will use any web font you load at the application level.
-
-When `editable` is enabled, `JvCode` emits `codeChange` on every edit so the parent can keep the source text in sync.
-
-### Example
-
-```typescript
-import { Component } from '@angular/core';
-import { JvCodeComponent } from '@devjuliovilla/jv-ui';
-
-@Component({
-  selector: 'app-payload-preview',
-  standalone: true,
-  imports: [JvCodeComponent],
-  template: `
-    <jv-code
-      [code]="payload"
-      language="json"
-      title="HTTP payload preview"
-      font="fira-code"
-      [editable]="true"
-      width="100%"
-      height="18rem"
-      (codeChange)="payload = $event"
-    />
-  `,
-})
-export class PayloadPreviewComponent {
-  payload = '{"status":"ok"}';
-}
-```
-
-If you want hosted fonts without shipping them in your package, load them at the app level, for example:
-
-```css
-@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap');
-```
-
-## Confirm Dialog Labels
-
-`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`.
-
-This lets you either:
-
-- override labels directly for a specific action like `Guardar evento` / `Descartar cambios`
-- or register translated defaults in your i18n dictionary for each supported language
-
-Example with business copy:
-
-```typescript
-const confirmed = await dialogService.confirm({
-  title: 'Guardar evento',
-  message: 'Se aplicaran cambios a la agenda del equipo.',
-  confirmLabel: 'Guardar evento',
-  cancelLabel: 'Descartar cambios',
-  tone: 'primary',
-});
-
-if (confirmed) {
-  saveEvent();
-}
-```
-
-Example using translated defaults from your dictionary:
-
-```typescript
-await dialogService.confirm({
-  message: 'This action will publish the current draft.',
-  tone: 'primary',
-});
-```
-
-## 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.
-
- ## Layout API
-
-### JvDashboardShell
-
-```typescript
-import { JvDashboardShellComponent } from '@devjuliovilla/jv-ui';
-```
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `title` | `string` | — | App / brand title |
-| `sidebarSubtitle` | `string` | `''` | Subtitle below brand |
-| `brandIcon` | `string` | `'monitor'` | Brand Lucide icon |
-| `navItems` | `JvNavItem[]` | `[]` | Navigation items (supports nested children) |
-| `sidebarCollapsed` | `boolean` | `false` | Desktop sidebar collapsed state |
-| `mobileSidebarOpen` | `boolean` | `false` | Mobile sidebar open/closed |
-| `topbarTitle` | `string` | `''` | Topbar page title |
-| `topbarSubtitle` | `string` | `''` | Topbar subtitle |
-| `currentTheme` | `JvTheme` | `'light'` | Active theme value |
-| `themeOptions` | `JvThemeOption[]` | `[]` | Theme selector options |
-| `topbarActions` | `JvTopbarAction[]` | `[]` | Icon buttons in topbar |
-| `showThemeSelector` | `boolean` | `true` | Show theme pills |
-
-| Output | Description |
-|---|---|
-| `menuClick` | Hamburger button clicked — toggle mobile sidebar |
-| `mobileClose` | Backdrop clicked or navigation selected — close mobile sidebar |
-| `sidebarCollapseToggle` | Collapse toggle clicked — collapse/expand sidebar |
-| `themeChange` | Theme pill clicked |
-| `topbarActionClick` | Topbar action button clicked |
-
-**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.
-
-### JvSidebar
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `title` | `string` | — | Brand title |
-| `subtitle` | `string` | `''` | Brand subtitle |
-| `brandIcon` | `string` | `'monitor'` | Brand icon |
-| `items` | `JvNavItem[]` | `[]` | Navigation items |
-| `collapsed` | `boolean` | `false` | Collapse to icon-only |
-| `mobileOpen` | `boolean` | `false` | Show on mobile |
-| `ariaLabel` | `string` | `'Sidebar navigation'` | Accessible label |
-
-| Output | Description |
-|---|---|
-| `collapseToggle` | Collapse button clicked |
-| `mobileClose` | Backdrop or nav item interaction — request close |
-
-## Responsive Design
-
-The library includes basic responsive behavior:
-
-- **Breakpoints** defined as CSS custom properties: `--jv-breakpoint-sm` (640px), `--jv-breakpoint-md` (768px), `--jv-breakpoint-lg` (1024px), `--jv-breakpoint-xl` (1280px)
-- **Dashboard shell** collapses to single column at ≤ 900px; sidebar becomes a slide-in overlay with backdrop
-- **Topbar** stacks vertically at ≤ 900px
-- **Grid** pagination and toolbar stack at ≤ 640px; table scrolls horizontally with `overflow-x: auto`
-- **Flex-wrap** is used extensively for natural overflow handling
-- **Dialog** and **Toast** constrain width with `min()` to never exceed the viewport
-
-## 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
+```
+
+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).
+
+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({ messagesLocale: 'en', formatLocale: 'en-US' })],
+};
+```
+
+```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`                                                                                                             |
+| Calendar   | `JvMonthCalendar`, `JvDayPlanner` — reusable month view and agenda primitives, usable together or independently                                         |
+| Forms      | `JvInput`, `JvTextarea`, `JvCode`, `JvSelect`, `JvCheckbox`, `JvRadio`, `JvSwitch`, `JvDatePicker`, `JvModalSelector`, `JvFileInput`, `JvFormContainer` |
+| Data Grid  | `JvGrid` — full-featured data table (see below)                                                                                                         |
+| Containers | `JvCard`, `JvSection`, `JvDivider`                                                                                                                      |
+| List       | `JvList`, `JvListItem` — list with title, description, icons, badges, and interactive items                                                             |
+| Tabs       | `JvTabs`, `JvTabPanelDirective` — horizontal tabs with keyboard navigation and animated transitions                                                     |
+| Slider     | `JvImageSlider` — responsive image slider with thumbnails and keyboard navigation                                                                       |
+| Gallery    | `JvImageGallery` — horizontal image gallery with wheel scrolling and full-screen viewer                                                                 |
+| Feedback   | `JvAlert`, `JvBadge`, `JvLoader`, `JvToast`                                                                                                             |
+| Dialogs    | `JvDialog`, `JvConfirmDialog`, `JvWindowModal` — compact dialogs plus a larger workflow overlay surface                                                 |
+| 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                                                                                                        |
+
+## Calendar API
+
+The scheduling primitives are split into **two separate components**:
+
+- `JvMonthCalendar`: inline month grid with selection, navigation, and day markers
+- `JvDayPlanner`: agenda / list view for scheduled items with optional grouping and expandable details
+
+You can use either one on its own, or compose both together in a master-detail scheduling layout.
+
+### JvMonthCalendar
+
+```typescript
+import {
+  JvMonthCalendarComponent,
+  JvMonthCalendarDayDirective,
+  JvMonthCalendarDayMeta,
+} from '@devjuliovilla/jv-ui';
+```
+
+**Inputs:**
+
+| Input          | Type                                                                                           | Default                                                                          | Description                                                |
+| -------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `value`        | `Date \| string \| null`                                                                       | `undefined`                                                                      | Selected day                                               |
+| `visibleMonth` | `Date \| string \| null`                                                                       | `undefined`                                                                      | Controlled visible month independent from the selected day |
+| `dayMeta`      | `JvMonthCalendarDayMeta[]`                                                                     | `[]`                                                                             | Marker/counter metadata per day                            |
+| `ariaLabel`    | `string`                                                                                       | localized default                                                                | Accessible label for the grid                              |
+| `monthLabel`   | `string`                                                                                       | `Month`                                                                          | Accessible label for the month selector                    |
+| `yearLabel`    | `string`                                                                                       | `Year`                                                                           | Accessible label for the year selector                     |
+| `minYear`      | `number`                                                                                       | current year - 10                                                                | Lower year bound for the year selector                     |
+| `maxYear`      | `number`                                                                                       | current year + 10                                                                | Upper year bound for the year selector                     |
+| `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  |
+
+**Outputs:**
+
+| Output               | Type   |
+| -------------------- | ------ |
+| `selectionChange`    | `Date` |
+| `visibleMonthChange` | `Date` |
+
+**Day metadata:**
+
+| Property | Type                                                                                    | Description                                               |
+| -------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `date`   | `Date \| string`                                                                        | Day associated with the marker                            |
+| `count`  | `number`                                                                                | Optional numeric badge rendered inside the cell           |
+| `tone`   | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'neutral'` | Visual tone for the badge or dot                          |
+| `label`  | `string`                                                                                | Extra accessibility text appended to the day `aria-label` |
+
+**Template hook:**
+
+Use `ng-template[jvMonthCalendarDay]` to fully customize the day cell.
+
+**Standalone example:**
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { JvMonthCalendarComponent, JvMonthCalendarDayMeta } from '@devjuliovilla/jv-ui';
+
+@Component({
+  selector: 'app-calendar-only',
+  standalone: true,
+  imports: [JvMonthCalendarComponent],
+  template: `
+    <jv-month-calendar
+      [value]="selectedDate()"
+      [dayMeta]="calendarMeta"
+      (selectionChange)="selectedDate.set($event)"
+    />
+  `,
+})
+export class CalendarOnlyComponent {
+  readonly selectedDate = signal(new Date(2026, 5, 15));
+  readonly calendarMeta: JvMonthCalendarDayMeta[] = [
+    { date: '2026-06-15', count: 2, tone: 'primary', label: '2 activities' },
+    { date: '2026-06-16', count: 1, tone: 'secondary', label: '1 activity' },
+  ];
+}
+```
+
+### JvDayPlanner
+
+```typescript
+import {
+  JvDayPlannerComponent,
+  JvDayPlannerDetailDirective,
+  JvDayPlannerItem,
+  JvDayPlannerItemDirective,
+} from '@devjuliovilla/jv-ui';
+```
+
+**Inputs:**
+
+| Input                    | Type                   | Default           | Description                              |
+| ------------------------ | ---------------------- | ----------------- | ---------------------------------------- |
+| `items`                  | `JvDayPlannerItem[]`   | `[]`              | Agenda items                             |
+| `groupByDate`            | `boolean`              | `false`           | Group items under a date heading         |
+| `emptyMessage`           | `string`               | localized default | Empty state copy                         |
+| `ariaLabel`              | `string`               | localized default | Accessible label for the agenda          |
+| `defaultExpandedItemIds` | `(string \| number)[]` | `[]`              | Items whose detail should start expanded |
+
+**Outputs:**
+
+| Output       | Type               |
+| ------------ | ------------------ |
+| `itemSelect` | `JvDayPlannerItem` |
+
+**Planner item shape:**
+
+| Property      | Type                     | Description                               |
+| ------------- | ------------------------ | ----------------------------------------- |
+| `id`          | `string \| number`       | Stable identity                           |
+| `title`       | `string`                 | Primary label                             |
+| `date`        | `Date \| string \| null` | Logical day when start time is not enough |
+| `start`       | `Date \| string \| null` | Optional start datetime                   |
+| `end`         | `Date \| string \| null` | Optional end datetime                     |
+| `status`      | `string`                 | Status badge label                        |
+| `statusTone`  | `JvTone`                 | Visual tone for status badge              |
+| `type`        | `string`                 | Type/category badge label                 |
+| `typeTone`    | `JvTone`                 | Visual tone for type badge                |
+| `responsible` | `string`                 | Responsible person                        |
+| `location`    | `string`                 | Location metadata                         |
+| `details`     | `string`                 | Expandable detail text                    |
+| `completed`   | `boolean`                | Reduced emphasis for completed items      |
+
+**Template hooks:**
+
+- `ng-template[jvDayPlannerItem]` customizes the visible item row
+- `ng-template[jvDayPlannerDetail]` customizes the expanded detail panel
+
+**Standalone example:**
+
+```typescript
+import { Component } from '@angular/core';
+import { JvDayPlannerComponent, JvDayPlannerItem } from '@devjuliovilla/jv-ui';
+
+@Component({
+  selector: 'app-planner-only',
+  standalone: true,
+  imports: [JvDayPlannerComponent],
+  template: `
+    <jv-day-planner [items]="items" [groupByDate]="true" (itemSelect)="handleSelect($event)" />
+  `,
+})
+export class PlannerOnlyComponent {
+  readonly items: JvDayPlannerItem[] = [
+    {
+      id: 1,
+      title: 'Venue setup',
+      start: '2026-06-15T08:30:00',
+      end: '2026-06-15T10:00:00',
+      status: 'Scheduled',
+      statusTone: 'primary',
+      type: 'Logistics',
+      responsible: 'Ana Lopez',
+      location: 'Main hall',
+      details: 'Prepare seating and signage.',
+    },
+  ];
+
+  handleSelect(item: JvDayPlannerItem) {
+    console.log(item);
+  }
+}
+```
+
+### Combined example
+
+Use both components together when you need a left-side month selector and a right-side agenda:
+
+```html
+<jv-month-calendar
+  [value]="selectedDate()"
+  [dayMeta]="calendarMeta()"
+  (selectionChange)="selectedDate.set($event)"
+/>
+
+<jv-day-planner
+  [items]="filteredItems()"
+  [groupByDate]="showAll()"
+  (itemSelect)="selectedItem.set($event)"
+/>
+```
+
+## 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' \| 'integer' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'time' \| 'datetime' \| 'boolean'` | Data type for formatting          |
+| `formatOptions` | `Intl.NumberFormatOptions & Intl.DateTimeFormatOptions`                                                     | Per-column formatting overrides   |
+| `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                                                         |
+| `exportFileName`         | `string`                                 | `''`                | Base filename used for CSV/Excel exports; the component applies the correct extension |
+| `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                                                         |
+| `keyboardNavigation`     | `boolean`                                | `false`             | Enable arrow-key cell navigation and `F2` editing flow                                |
+| `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, exportFileName: 'products', 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 },
+  ];
+}
+```
+
+### Grid behavior notes
+
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
+- **Formatting:** column `type` and `formatOptions` affect display only. Sorting and export use the raw field value, not the localized text shown in the cell.
+- **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.
+
+### Keyboard navigation example
+
+```typescript
+const gridOptions: JvGridOptions = {
+  keyboardNavigation: true,
+  editable: true,
+  pageable: false,
+};
+
+const columns: JvGridColumn<Product>[] = [
+  { key: 'name', header: 'Product', editable: true, editType: 'text' },
+  {
+    key: 'status',
+    header: 'Status',
+    editable: true,
+    editType: 'select',
+    editOptions: [
+      { label: 'Active', value: 'active' },
+      { label: 'Paused', value: 'paused' },
+    ],
+  },
+];
+```
+
+```html
+<jv-grid
+  [data]="products"
+  [columns]="columns"
+  [options]="gridOptions"
+  (rowEdit)="onRowEdit($event)"
+/>
+```
+
+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.
+
+## List API
+
+```typescript
+import { JvListComponent, JvListItemComponent } from '@devjuliovilla/jv-ui';
+```
+
+**JvList inputs:**
+
+| Input       | Type                     | Default  | Description                                                                    |
+| ----------- | ------------------------ | -------- | ------------------------------------------------------------------------------ |
+| `role`      | `'list' \| 'navigation'` | `'list'` | ARIA role for the list                                                         |
+| `variant`   | `'bordered' \| null`     | `null`   | Outer border + border-radius around the list (items always have bottom border) |
+| `ariaLabel` | `string`                 | `''`     | Accessible label                                                               |
+
+**JvListItem inputs:**
+
+| Input         | Type                | Default | Description                                  |
+| ------------- | ------------------- | ------- | -------------------------------------------- |
+| `title`       | `string` (required) | —       | Primary text                                 |
+| `description` | `string`            | `''`    | Secondary text below title                   |
+| `leadingIcon` | `string \| null`    | `null`  | Lucide icon name on the left                 |
+| `disabled`    | `boolean`           | `false` | Gray out and block interaction               |
+| `active`      | `boolean`           | `false` | Highlight with primary color and left border |
+
+**JvListItem outputs:**
+
+| Output      | Type   |
+| ----------- | ------ |
+| `activated` | `void` |
+
+**Content projection:** use the `meta` attribute selector for badges, icons, or any content on the right side:
+
+```html
+<jv-list-item title="Inbox" description="New messages">
+  <jv-badge tone="primary" meta>3</jv-badge>
+  <jv-icon name="chevron-right" meta />
+</jv-list-item>
+```
+
+### Example
+
+```typescript
+import { Component } from '@angular/core';
+import { JvListComponent, JvListItemComponent, JvBadgeComponent } from '@devjuliovilla/jv-ui';
+
+@Component({
+  selector: 'app-nav-list',
+  standalone: true,
+  imports: [JvListComponent, JvListItemComponent, JvBadgeComponent],
+  template: `
+    <jv-list variant="bordered">
+      <jv-list-item
+        title="Dashboard"
+        description="Main overview"
+        leadingIcon="layout-dashboard"
+        [active]="true"
+      />
+      <jv-list-item title="Notifications" description="3 pending" (activated)="onOpen()">
+        <jv-badge tone="primary" meta>3</jv-badge>
+      </jv-list-item>
+      <jv-list-item title="Reports" description="Coming soon" [disabled]="true" />
+    </jv-list>
+  `,
+})
+export class NavListComponent {
+  onOpen() {
+    /* handle activation */
+  }
+}
+```
+
+## 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 }` |
+
+## Tabs API
+
+```typescript
+import { JvTabsComponent, JvTabPanelDirective, JvTabItem } from '@devjuliovilla/jv-ui';
+```
+
+**Inputs:**
+
+| Input         | Type                                  | Default | Description                                               |
+| ------------- | ------------------------------------- | ------- | --------------------------------------------------------- |
+| `tabs`        | `JvTabItem[]`                         | `[]`    | Tab definitions (`{ id, label, icon?, disabled? }`)       |
+| `activeTabId` | `string \| null`                      | `null`  | Controlled active tab ID                                  |
+| `keepMounted` | `boolean`                             | `true`  | Keep all panels in DOM; `false` renders only active panel |
+| `transition`  | `'none' \| 'fade' \| 'slide' \| null` | `null`  | Panel transition animation (falls back to global config)  |
+
+**Outputs:**
+
+| Output            | Type     |
+| ----------------- | -------- |
+| `activeTabChange` | `string` |
+
+**Content projection:** use `jvTabPanel` directive on `ng-template` to define panel content:
+
+```html
+<jv-tabs [tabs]="tabs" [activeTabId]="activeTabId()" (activeTabChange)="activeTabId.set($event)">
+  <ng-template jvTabPanel="overview">
+    <p>Overview content</p>
+  </ng-template>
+  <ng-template jvTabPanel="analytics">
+    <p>Analytics content</p>
+  </ng-template>
+</jv-tabs>
+```
+
+### Tab Transitions
+
+Tabs support animated transitions between panels. Configure globally via `provideJvUi()` or per-instance via the `transition` input:
+
+```typescript
+// Global default
+provideJvUi({ tabsTransition: 'fade' });
+```
+
+```typescript
+// Per-instance override
+<jv-tabs transition="slide" [keepMounted]="false">...</jv-tabs>
+```
+
+| Transition | `keepMounted=true`     | `keepMounted=false` | Description                          |
+| ---------- | ---------------------- | ------------------- | ------------------------------------ |
+| `'none'`   | Instant switch         | Instant switch      | No animation                         |
+| `'fade'`   | Opacity cross-fade     | Opacity cross-fade  | Smooth fade between panels           |
+| `'slide'`  | Falls back to `'fade'` | Directional slide   | Slides left/right based on tab index |
+
+**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`.
+
+### Tabs Example
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { JvTabItem, JvTabPanelDirective, JvTabsComponent } from '@devjuliovilla/jv-ui';
+
+@Component({
+  standalone: true,
+  imports: [JvTabsComponent, JvTabPanelDirective],
+  template: `
+    <jv-tabs
+      [tabs]="tabs"
+      [activeTabId]="activeTabId()"
+      transition="fade"
+      (activeTabChange)="activeTabId.set($event)"
+    >
+      <ng-template jvTabPanel="overview">
+        <p>Overview content</p>
+      </ng-template>
+      <ng-template jvTabPanel="analytics">
+        <p>Analytics content</p>
+      </ng-template>
+    </jv-tabs>
+  `,
+})
+export class TabsExampleComponent {
+  readonly activeTabId = signal('overview');
+  readonly tabs: JvTabItem[] = [
+    { id: 'overview', label: 'Overview' },
+    { id: 'analytics', label: 'Analytics', icon: 'chart-column' },
+  ];
+}
+```
+
+## Image Slider API
+
+```typescript
+import { JvImageSliderComponent, JvSliderImage } from '@devjuliovilla/jv-ui';
+```
+
+**JvSliderImage:**
+
+| Property      | Type     | Required | Description                              |
+| ------------- | -------- | -------- | ---------------------------------------- |
+| `src`         | `string` | Yes      | Image URL                                |
+| `alt`         | `string` | Yes      | Alternative text for accessibility       |
+| `description` | `string` | No       | Caption displayed below the image        |
+| `thumbnail`   | `string` | No       | Custom thumbnail URL (defaults to `src`) |
+
+**Inputs:**
+
+| Input             | Type              | Default | Description                       |
+| ----------------- | ----------------- | ------- | --------------------------------- |
+| `images`          | `JvSliderImage[]` | `[]`    | Array of images to display        |
+| `showThumbnails`  | `boolean`         | `true`  | Show thumbnail strip below slider |
+| `showDescription` | `boolean`         | `true`  | Show image description            |
+
+**Outputs:**
+
+| Output        | Type     | Description                           |
+| ------------- | -------- | ------------------------------------- |
+| `imageChange` | `number` | Emits index when active image changes |
+
+**i18n support:**
+
+The component automatically translates aria labels using `JvTranslationService`:
+
+| Key                    | English          | Spanish                |
+| ---------------------- | ---------------- | ---------------------- |
+| `slider.prevImage`     | Previous image   | Imagen anterior        |
+| `slider.nextImage`     | Next image       | Imagen siguiente       |
+| `slider.thumbnailList` | Image thumbnails | Miniaturas de imagenes |
+
+### Features
+
+- **Keyboard navigation:** ArrowLeft/ArrowRight to navigate, Home/End for first/last image
+- **Responsive:** Images scale to fit container with `object-fit: contain`
+- **Thumbnails:** Scrollable thumbnail strip with active state indicator
+- **Single image mode:** Navigation controls hidden when only one image is provided
+- **Lazy loading:** Images use native `loading="lazy"` attribute
+- **i18n:** Aria labels automatically translated based on configured locale
+
+### Example
+
+```typescript
+import { Component } from '@angular/core';
+import { JvImageSliderComponent, JvSliderImage } from '@devjuliovilla/jv-ui';
+
+@Component({
+  standalone: true,
+  imports: [JvImageSliderComponent],
+  template: `
+    <jv-image-slider
+      [images]="images"
+      [showThumbnails]="true"
+      [showDescription]="true"
+      (imageChange)="onImageChange($event)"
+    />
+  `,
+})
+export class SliderComponent {
+  readonly images: JvSliderImage[] = [
+    { src: 'photo1.jpg', alt: 'Sunset', description: 'Beautiful sunset over the ocean' },
+    { src: 'photo2.jpg', alt: 'Mountain', description: 'Snow-capped mountain peak' },
+    { src: 'photo3.jpg', alt: 'Forest', description: 'Dense forest trail' },
+  ];
+
+  onImageChange(index: number) {
+    console.log('Viewing image:', index);
+  }
+}
+```
+
+## Image Gallery API
+
+```typescript
+import { JvImageGalleryComponent, JvGalleryImage, JvGalleryAction } from '@devjuliovilla/jv-ui';
+```
+
+**JvGalleryImage:**
+
+| Property    | Type     | Required | Description                              |
+| ----------- | -------- | -------- | ---------------------------------------- |
+| `src`       | `string` | Yes      | Image URL                                |
+| `alt`       | `string` | Yes      | Alternative text for accessibility       |
+| `thumbnail` | `string` | No       | Custom thumbnail URL (defaults to `src`) |
+
+**JvGalleryAction:**
+
+| Property | Type       | Required | Description              |
+| -------- | ---------- | -------- | ------------------------ |
+| `id`     | `string`   | Yes      | Unique action identifier |
+| `label`  | `string`   | Yes      | Button label text        |
+| `icon`   | `string`   | No       | Lucide icon name         |
+| `tone`   | `JvIntent` | No       | Button variant           |
+
+**Inputs:**
+
+| Input           | Type                | Default | Description                                                                           |
+| --------------- | ------------------- | ------- | ------------------------------------------------------------------------------------- |
+| `images`        | `JvGalleryImage[]`  | `[]`    | Array of images to display                                                            |
+| `stripHeightVh` | `number`            | `25`    | Height of the thumbnail strip in viewport-height units, clamped between `0` and `100` |
+| `actions`       | `JvGalleryAction[]` | `[]`    | Action buttons shown in dialog footer                                                 |
+
+**Outputs:**
+
+| Output        | Type                                          | Description                            |
+| ------------- | --------------------------------------------- | -------------------------------------- |
+| `imageClick`  | `JvGalleryImage`                              | Emits when an image is clicked         |
+| `actionClick` | `{ actionId: string; image: JvGalleryImage }` | Emits when an action button is clicked |
+
+### Features
+
+- **Horizontal strip:** Scrollable thumbnail strip with configurable height in `vh`
+- **Full-screen viewer:** Click any image to open in a dialog with dark background
+- **Navigation:** Prev/next buttons and keyboard arrows (← →) in the viewer
+- **Configurable actions:** Action buttons in dialog footer (favorite, edit, delete, etc.)
+- **Responsive:** Shows multiple columns on desktop, single column with scroll on mobile
+- **Lazy loading:** All images use native `loading="lazy"` attribute
+- **i18n:** Close and navigation labels automatically translated
+
+### Example
+
+```typescript
+import { Component } from '@angular/core';
+import { JvImageGalleryComponent, JvGalleryImage, JvGalleryAction } from '@devjuliovilla/jv-ui';
+
+@Component({
+  standalone: true,
+  imports: [JvImageGalleryComponent],
+  template: `
+    <jv-image-gallery
+      [images]="images"
+      [stripHeightVh]="30"
+      [actions]="actions"
+      (imageClick)="onImageClick($event)"
+      (actionClick)="onActionClick($event)"
+    />
+  `,
+})
+export class GalleryComponent {
+  readonly images: JvGalleryImage[] = [
+    { src: 'photo1.jpg', alt: 'Sunset' },
+    { src: 'photo2.jpg', alt: 'Mountain' },
+    { src: 'photo3.jpg', alt: 'Forest' },
+  ];
+
+  readonly actions: JvGalleryAction[] = [
+    { id: 'favorite', label: 'Favorite', icon: 'heart', tone: 'danger' },
+    { id: 'edit', label: 'Edit', icon: 'pencil' },
+    { id: 'delete', label: 'Delete', icon: 'trash-2', tone: 'danger' },
+  ];
+
+  onImageClick(image: JvGalleryImage) {
+    console.log('Viewing:', image.alt);
+  }
+
+  onActionClick(event: { actionId: string; image: JvGalleryImage }) {
+    console.log(event.actionId, 'on', event.image.alt);
+  }
+}
+```
+
+## 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: [''] });
+}
+```
+
+## Code API
+
+```typescript
+import { JvCodeComponent } from '@devjuliovilla/jv-ui';
+```
+
+| Input      | Type                                                                      | Default            | Description                                                           |
+| ---------- | ------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------- |
+| `code`     | `string`                                                                  | —                  | Code or text content to render                                        |
+| `language` | `string`                                                                  | `''`               | Optional language badge                                               |
+| `title`    | `string`                                                                  | `''`               | Optional header title                                                 |
+| `font`     | `'jetbrains-mono' \| 'fira-code' \| 'cascadia' \| 'consolas' \| 'system'` | `'jetbrains-mono'` | Mono font preset for the rendered block                               |
+| `editable` | `boolean`                                                                 | `false`            | Renders a textarea-style editing surface instead of read-only preview |
+| `width`    | `string`                                                                  | `'100%'`           | CSS width applied to the component                                    |
+| `height`   | `string`                                                                  | `'auto'`           | CSS height for the editable surface or minimum preview height         |
+
+Use `JvCode` for read-only payloads or long single-line content where horizontal scrolling should be preserved instead of wrapping.
+The library does not bundle font files. `JvCode` references common mono families and will use any web font you load at the application level.
+
+When `editable` is enabled, `JvCode` emits `codeChange` on every edit so the parent can keep the source text in sync.
+
+### Example
+
+```typescript
+import { Component } from '@angular/core';
+import { JvCodeComponent } from '@devjuliovilla/jv-ui';
+
+@Component({
+  selector: 'app-payload-preview',
+  standalone: true,
+  imports: [JvCodeComponent],
+  template: `
+    <jv-code
+      [code]="payload"
+      language="json"
+      title="HTTP payload preview"
+      font="fira-code"
+      [editable]="true"
+      width="100%"
+      height="18rem"
+      (codeChange)="payload = $event"
+    />
+  `,
+})
+export class PayloadPreviewComponent {
+  payload = '{"status":"ok"}';
+}
+```
+
+If you want hosted fonts without shipping them in your package, load them at the app level, for example:
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap');
+```
+
+## Confirm Dialog Labels
+
+`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`.
+
+This lets you either:
+
+- override labels directly for a specific action like `Guardar evento` / `Descartar cambios`
+- or register translated defaults in your i18n dictionary for each supported language
+
+Example with business copy:
+
+```typescript
+const confirmed = await dialogService.confirm({
+  title: 'Guardar evento',
+  message: 'Se aplicaran cambios a la agenda del equipo.',
+  confirmLabel: 'Guardar evento',
+  cancelLabel: 'Descartar cambios',
+  tone: 'primary',
+});
+
+if (confirmed) {
+  saveEvent();
+}
+```
+
+Example using translated defaults from your dictionary:
+
+```typescript
+await dialogService.confirm({
+  message: 'This action will publish the current draft.',
+  tone: 'primary',
+});
+```
+
+## 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.
+
+## Layout API
+
+### JvDashboardShell
+
+```typescript
+import { JvDashboardShellComponent } from '@devjuliovilla/jv-ui';
+```
+
+| Input               | Type               | Default     | Description                                 |
+| ------------------- | ------------------ | ----------- | ------------------------------------------- |
+| `title`             | `string`           | —           | App / brand title                           |
+| `sidebarSubtitle`   | `string`           | `''`        | Subtitle below brand                        |
+| `brandIcon`         | `string`           | `'monitor'` | Brand Lucide icon                           |
+| `navItems`          | `JvNavItem[]`      | `[]`        | Navigation items (supports nested children) |
+| `sidebarCollapsed`  | `boolean`          | `false`     | Desktop sidebar collapsed state             |
+| `mobileSidebarOpen` | `boolean`          | `false`     | Mobile sidebar open/closed                  |
+| `topbarTitle`       | `string`           | `''`        | Topbar page title                           |
+| `topbarSubtitle`    | `string`           | `''`        | Topbar subtitle                             |
+| `currentTheme`      | `JvTheme`          | `'light'`   | Active theme value                          |
+| `themeOptions`      | `JvThemeOption[]`  | `[]`        | Theme selector options                      |
+| `topbarActions`     | `JvTopbarAction[]` | `[]`        | Icon buttons in topbar                      |
+| `showThemeSelector` | `boolean`          | `true`      | Show theme pills                            |
+
+| Output                  | Description                                                    |
+| ----------------------- | -------------------------------------------------------------- |
+| `menuClick`             | Hamburger button clicked — toggle mobile sidebar               |
+| `mobileClose`           | Backdrop clicked or navigation selected — close mobile sidebar |
+| `sidebarCollapseToggle` | Collapse toggle clicked — collapse/expand sidebar              |
+| `themeChange`           | Theme pill clicked                                             |
+| `topbarActionClick`     | Topbar action button clicked                                   |
+
+**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.
+
+### JvSidebar
+
+| Input        | Type          | Default                | Description           |
+| ------------ | ------------- | ---------------------- | --------------------- |
+| `title`      | `string`      | —                      | Brand title           |
+| `subtitle`   | `string`      | `''`                   | Brand subtitle        |
+| `brandIcon`  | `string`      | `'monitor'`            | Brand icon            |
+| `items`      | `JvNavItem[]` | `[]`                   | Navigation items      |
+| `collapsed`  | `boolean`     | `false`                | Collapse to icon-only |
+| `mobileOpen` | `boolean`     | `false`                | Show on mobile        |
+| `ariaLabel`  | `string`      | `'Sidebar navigation'` | Accessible label      |
+
+| Output           | Description                                      |
+| ---------------- | ------------------------------------------------ |
+| `collapseToggle` | Collapse button clicked                          |
+| `mobileClose`    | Backdrop or nav item interaction — request close |
+
+## Responsive Design
+
+The library includes basic responsive behavior:
+
+- **Breakpoints** defined as CSS custom properties: `--jv-breakpoint-sm` (640px), `--jv-breakpoint-md` (768px), `--jv-breakpoint-lg` (1024px), `--jv-breakpoint-xl` (1280px)
+- **Dashboard shell** collapses to single column at ≤ 900px; sidebar becomes a slide-in overlay with backdrop
+- **Topbar** stacks vertically at ≤ 900px
+- **Grid** pagination and toolbar stack at ≤ 640px; table scrolls horizontally with `overflow-x: auto`
+- **Flex-wrap** is used extensively for natural overflow handling
+- **Dialog** and **Toast** constrain width with `min()` to never exceed the viewport
+
+## 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