@devjuliovilla/jv-ui 1.11.2 → 1.13.0

package/README.md

@@ -42,6 +42,7 @@ export class App {}
 | 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` |
@@ -50,12 +51,200 @@ export class App {}
 | 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` |
+| 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 |
@@ -147,10 +336,10 @@ import { JvGridComponent } from '@devjuliovilla/jv-ui';
 | `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 |
+| `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 |
@@ -183,7 +372,7 @@ interface Product {
     <jv-grid
       [data]="products"
       [columns]="columns"
-      [options]="{ selectable: true, exportable: true, exportFileName: 'products', pageSize: 10 }"
+      [options]="{ selectable: true, exportable: true, exportFileName: 'products', pageSize: 10 }"
       [trackBy]="'id'"
       [selectedIds]="selectedIds"
       (selectionChange)="selectedIds = $event"