# WeeklyCalendar

## Overview

Week-view calendar with day columns, time column, current timeline, optional week navigation and appointment grouping by category.

---

## Props

| Prop                | Type                                                               | Default     | Description                                          |
| ------------------- | ------------------------------------------------------------------ | ----------- | ---------------------------------------------------- |
| `appointments`      | `CalendarAppointment[]`                                            | `[]`        | Appointments to render across the week.              |
| `onWeekChange`      | `(weekOffset: number, weekStart: string, weekEnd: string) => void` | `undefined` | Emitted when navigating weeks.                       |
| `initialWeekOffset` | `number`                                                           | `0`         | 0 = current week; negative/positive for past/future. |
| `showNavigation`    | `boolean`                                                          | `true`      | Show previous/next/current week controls.            |
| `showWeekIndicator` | `boolean`                                                          | `false`     | Show current week label.                             |
| `enableGrouping`    | `boolean`                                                          | `false`     | Group appointments by `appointment.groupBy`.         |
| `groupLabel`        | `string`                                                           | `undefined` | Group header label.                                  |
| `calendarStartHour` | `number`                                                           | `8`         | First visible hour (0-23).                           |
| `calendarEndHour`   | `number`                                                           | `20`        | Last visible hour (0-23).                            |
| `todayString`       | `string`                                                           | `"Oggi"`    | Label for "today" button.                            |

`CalendarAppointment` minimal shape: `{ id: number|string; title: string; date: YYYY-MM-DD; startTime: HH:mm; endTime: HH:mm; description?: string; color?: string; attributes?: { key: string; value: string; showTooltip?: boolean; showPreview?: boolean }[]; groupBy?: string }`.

---

## Behavior

- **Navigation**: Previous/next/current week; `onWeekChange` returns offset and ISO dates.
- **Grouping**: When `enableGrouping`, appointments are grouped under `groupBy` headings per day.
- **Attributes**: Show in tooltip or in preview card depending on flags.

---

## Examples

```tsx
import { WeeklyCalendar } from "laif-ds";
import { mockAppointments } from "laif-ds";

export function GroupedCalendar() {
  return (
    <div className="container mx-auto overflow-y-auto">
      <WeeklyCalendar
        appointments={mockAppointments}
        calendarStartHour={6}
        calendarEndHour={21}
        enableGrouping
        groupLabel="Aula studio"
        showNavigation
      />
    </div>
  );
}
```

---

## Notes

- **Localization**: Weekday labels are Italian by default; adapt as needed in upstream module.
- **Performance**: Efficient day partitioning and rendering; large datasets should still be chunked server-side when possible.