laif-ds 0.2.44 → 0.2.46

package/dist/agent-docs/components/ContextMenu.md

@@ -0,0 +1,191 @@
+ # ContextMenu
+ 
+ ## Overview
+ 
+ Right-click context menu built on Radix. Supports items, groups, separators, submenus, checkbox items, radio groups, and keyboard shortcuts.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### ContextMenu (Root)
+ 
+ | Prop        | Type              | Default     | Description                               |
+ | ----------- | ----------------- | ----------- | ----------------------------------------- |
+ | `children`  | `React.ReactNode` | **required**| Include `ContextMenuTrigger` and content. |
+ 
+ ### Subcomponents
+ 
+ - `ContextMenuTrigger`: The element that opens the menu on right-click.
+ - `ContextMenuContent`: The menu panel container.
+ - `ContextMenuItem`: A clickable item. Props:
+   - `variant?: "default" | "destructive"`
+   - `inset?: boolean`
+ - `ContextMenuCheckboxItem`: Checkbox-like item. Props:
+   - `checked?: boolean`
+ - `ContextMenuRadioGroup`: Radio group container. Props: `value: string`.
+ - `ContextMenuRadioItem`: A radio item. Props: `value: string`.
+ - `ContextMenuSub` / `ContextMenuSubTrigger` / `ContextMenuSubContent`: Submenu controls.
+ - `ContextMenuLabel`: Section label. Props: `inset?: boolean`.
+ - `ContextMenuSeparator`: Horizontal separator.
+ - `ContextMenuShortcut`: Right-aligned text (e.g., keyboard shortcut).
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Trigger**: Right-click (contextmenu) on the trigger shows the menu.
+ - **Submenus**: Use `ContextMenuSub` to nest menus.
+ - **Checkbox/Radio**: Use state to control `checked` and `value` props.
+ - **Accessibility**: Keyboard navigation and ARIA attributes handled by Radix.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Basic
+ 
+ ```tsx
+ import {
+   ContextMenu,
+   ContextMenuTrigger,
+   ContextMenuContent,
+   ContextMenuItem,
+   ContextMenuSeparator,
+   ContextMenuShortcut,
+ } from "laif-ds";
+ 
+ export function BasicContextMenu() {
+   return (
+     <ContextMenu>
+       <ContextMenuTrigger className="flex h-[150px] w-[300px] items-center justify-center rounded-md border border-dashed text-sm">
+         Right click here
+       </ContextMenuTrigger>
+       <ContextMenuContent className="w-64">
+         <ContextMenuItem>
+           Back
+           <ContextMenuShortcut>⌘[</ContextMenuShortcut>
+         </ContextMenuItem>
+         <ContextMenuItem>
+           Forward
+           <ContextMenuShortcut>⌘]</ContextMenuShortcut>
+         </ContextMenuItem>
+         <ContextMenuItem>
+           Reload
+           <ContextMenuShortcut>⌘R</ContextMenuShortcut>
+         </ContextMenuItem>
+         <ContextMenuSeparator />
+         <ContextMenuItem>
+           Save As...
+           <ContextMenuShortcut>⌘S</ContextMenuShortcut>
+         </ContextMenuItem>
+         <ContextMenuItem>
+           Print...
+           <ContextMenuShortcut>⌘P</ContextMenuShortcut>
+         </ContextMenuItem>
+       </ContextMenuContent>
+     </ContextMenu>
+   );
+ }
+ ```
+ 
+ ### With Submenu
+ 
+ ```tsx
+ import {
+   ContextMenu,
+   ContextMenuTrigger,
+   ContextMenuContent,
+   ContextMenuItem,
+   ContextMenuSub,
+   ContextMenuSubTrigger,
+   ContextMenuSubContent,
+   ContextMenuSeparator,
+   ContextMenuShortcut,
+ } from "laif-ds";
+ 
+ export function WithSubmenu() {
+   return (
+     <ContextMenu>
+       <ContextMenuTrigger className="flex h-[150px] w-[300px] items-center justify-center rounded-md border border-dashed text-sm">
+         Right click here
+       </ContextMenuTrigger>
+       <ContextMenuContent className="w-64">
+         <ContextMenuItem>
+           Back
+           <ContextMenuShortcut>⌘[</ContextMenuShortcut>
+         </ContextMenuItem>
+         <ContextMenuItem>
+           Forward
+           <ContextMenuShortcut>⌘]</ContextMenuShortcut>
+         </ContextMenuItem>
+         <ContextMenuSub>
+           <ContextMenuSubTrigger>More Tools</ContextMenuSubTrigger>
+           <ContextMenuSubContent className="w-48">
+             <ContextMenuItem>
+               Save Page As...
+               <ContextMenuShortcut>⇧⌘S</ContextMenuShortcut>
+             </ContextMenuItem>
+             <ContextMenuItem>Create Shortcut...</ContextMenuItem>
+             <ContextMenuItem>Name Window...</ContextMenuItem>
+             <ContextMenuSeparator />
+             <ContextMenuItem>Developer Tools</ContextMenuItem>
+           </ContextMenuSubContent>
+         </ContextMenuSub>
+         <ContextMenuSeparator />
+         <ContextMenuItem>
+           Print...
+           <ContextMenuShortcut>⌘P</ContextMenuShortcut>
+         </ContextMenuItem>
+       </ContextMenuContent>
+     </ContextMenu>
+   );
+ }
+ ```
+ 
+ ### With Checkbox and Radio
+ 
+ ```tsx
+ import {
+   ContextMenu,
+   ContextMenuTrigger,
+   ContextMenuContent,
+   ContextMenuCheckboxItem,
+   ContextMenuLabel,
+   ContextMenuSeparator,
+   ContextMenuRadioGroup,
+   ContextMenuRadioItem,
+ } from "laif-ds";
+ 
+ export function WithCheckboxAndRadio() {
+   return (
+     <ContextMenu>
+       <ContextMenuTrigger className="flex h-[150px] w-[300px] items-center justify-center rounded-md border border-dashed text-sm">
+         Right click here
+       </ContextMenuTrigger>
+       <ContextMenuContent className="w-64">
+         <ContextMenuLabel>Options</ContextMenuLabel>
+         <ContextMenuSeparator />
+         <ContextMenuCheckboxItem>Show Bookmarks Bar</ContextMenuCheckboxItem>
+         <ContextMenuCheckboxItem checked>Show Full URLs</ContextMenuCheckboxItem>
+         <ContextMenuSeparator />
+         <ContextMenuLabel>View</ContextMenuLabel>
+         <ContextMenuRadioGroup value="comfortable">
+           <ContextMenuRadioItem value="comfortable">Comfortable</ContextMenuRadioItem>
+           <ContextMenuRadioItem value="compact">Compact</ContextMenuRadioItem>
+           <ContextMenuRadioItem value="condensed">Condensed</ContextMenuRadioItem>
+         </ContextMenuRadioGroup>
+       </ContextMenuContent>
+     </ContextMenu>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Variants**: Use `variant="destructive"` on `ContextMenuItem` for dangerous actions.
+ - **Inset**: Use `inset` on items/labels to align with other content.
+ - **Keyboard**: Use arrow keys and Enter to navigate/activate items.
+ 

package/dist/agent-docs/components/CopyButton.md

@@ -0,0 +1,26 @@
+# CopyButton
+
+## Overview
+
+Button that copies provided content to clipboard and animates icon state.
+
+---
+
+## Props
+
+| Prop          | Type     | Description                                      |
+| ------------- | -------- | ------------------------------------------------ |
+| `content`     | `string` | Text to copy                                     |
+| `copyMessage` | `string` | Optional message displayed by the clipboard hook |
+
+---
+
+## Example
+
+```tsx
+import { CopyButton } from "laif-ds";
+
+export function CopySnippet() {
+  return <CopyButton content="npm i laif-ds" copyMessage="Copied!" />;
+}
+```

package/dist/agent-docs/components/DataCrossTable.md

@@ -0,0 +1,94 @@
+ # DataCrossTable
+ 
+ ## Overview
+ 
+ Cross table component that renders a matrix from two headers (top/left) with virtualized rows, sticky headers/first column, optional filtering/sorting, and an edit mode supported by a context provider and action buttons.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop               | Type                    | Default | Description |
+ | ------------------ | ----------------------- | ------- | ----------- |
+ | `crossTableData`   | `CrossTableData`        | —       | Matrix data and headers. |
+ | `filterable`       | `boolean`               | `false` | Enables sorting via header buttons and row sorting by selected row. |
+ | `loading`          | `boolean`               | `false` | Shows a skeleton table. |
+ | `emptyComponent`   | `ReactNode`             | `undefined` | Shown when no data. |
+ | `className`        | `string`                | `undefined` | Wrapper classes. |
+ | `notFoundMessage`  | `string`                | `"Nessun risultato trovato."` | Fallback empty message. |
+ | `cornerHeaderFrom` | `string`                | `"Da"`  | Corner label (top-left) from. |
+ | `cornerHeaderTo`   | `string`                | `"A"`   | Corner label (top-left) to. |
+ | `minWidthCell`     | `number`                | `160`   | Minimum cell width in px. |
+ | `editable`         | `boolean`               | `false` | Enable edit mode features. |
+ | `editMode`         | `boolean`               | `false` | Control edit mode from outside. |
+ | `onEditModeChange` | `(editMode: boolean) => void` | `undefined` | Notified when edit mode changes. |
+ | `onSelectedRow`    | `(row: CrossTableHeader) => void` | `undefined` | Emitted when selecting a row for sorting. |
+ | `selectedRow`      | `CrossTableHeader`      | `undefined` | Controlled selected row. |
+ | `rowSortAsc`       | `boolean`               | `true`  | Sort ascending when selecting a row. |
+ 
+ ### Types
+ 
+ - `CrossTableHeader` → `{ id: string; label: string }`
+ - `CrossTableCell` → `{ render?:(fromId,toId,id?)=>ReactNode; value?: number|string|null; bgColor?: string; textColor?: string; fromId: string; toId: string; id?: string; editable?: boolean }`
+ - `CrossTableData` → `{ headerTop: CrossTableHeader[]; headerLeft: CrossTableHeader[]; data: (CrossTableCell|null)[][] }`
+ 
+ ---
+ 
+ ## Provider & Actions
+ 
+ Use `DataCrossTableProvider` to manage edit state across the table and expose a buttons group.
+ 
+ - `DataCrossTableProvider` props:
+   - `onConfirmedCells?(data: { editedCells: ConfirmedCell[]; toDefaultCells: ConfirmedCell[] })`
+   - Labels: `editConfirmLabel`, `editCancelLabel`, `editRestoreDefaultLabel`
+   - Flags: `initialEditMode` (default `false`), `showDefaultActionButton` (default `false`)
+   - Editable input labels: `cellEditTitleLabel`, `cellEditModifiedLabel`, `cellConfirmButtonLabel`, `cellCancelButtonLabel`, `cellResetButtonLabel`
+ - `DataCrossTableButtonsGroup`: shows Confirm/Cancel/Restore actions when `editMode=true`.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Default with Provider
+ 
+ ```tsx
+ import { DataCrossTable, DataCrossTableProvider, DataCrossTableButtonsGroup } from "laif-ds";
+ 
+ export function CrossEditable({ data }: { data: CrossTableData }) {
+   return (
+     <DataCrossTableProvider initialEditMode onConfirmedCells={(cells) => console.log(cells)}>
+       {({ editMode }) => (
+         <div className="space-y-3">
+           <DataCrossTableButtonsGroup />
+           <DataCrossTable crossTableData={data} editable editMode={editMode} minWidthCell={200} />
+         </div>
+       )}
+     </DataCrossTableProvider>
+   );
+ }
+ ```
+ 
+ ### Filterable
+ 
+ ```tsx
+ <DataCrossTableProvider>
+   <DataCrossTable crossTableData={data} filterable minWidthCell={200} cornerHeaderFrom="From" cornerHeaderTo="To" />
+ </DataCrossTableProvider>
+ ```
+ 
+ ### Loading State
+ 
+ ```tsx
+ <DataCrossTableProvider>
+   <DataCrossTable loading crossTableData={{ headerTop: [], headerLeft: [], data: [] }} />
+ </DataCrossTableProvider>
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Virtualization**: Rows are virtualized for performance on large datasets.
+ - **Sticky**: Top header row and first column are sticky; corner cell has higher z-index.
+ - **Editing**: Editable cells open a popover editor; edited/reset markers are shown per cell.
+ 

package/dist/agent-docs/components/DataTable.md

@@ -0,0 +1,254 @@
+ # DataTable
+ 
+ ## Overview
+ 
+ Powerful table built on TanStack Table v8. Supports client-side and server-side modes with a unified API, advanced filtering (badges + builder), global search, multi-column sorting, row selection, column pinning, dynamic pagination, i18n, and loading skeletons.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop                      | Type                                        | Default | Description |
+ | ------------------------- | ------------------------------------------- | ------- | ----------- |
+ | `columns`                 | `ColumnDef<TData, TValue>[]`                | —       | TanStack column definitions. Use `meta` to enable features. |
+ | `data`                    | `TData[]`                                   | —       | Table data. |
+ | `loading`                 | `boolean`                                   | `false` | Show skeleton rows. |
+ | `emptyComponent`          | `ReactNode`                                 | `undefined` | Rendered when no rows. |
+ | `className`               | `string`                                    | `undefined` | Wrapper classes. |
+ | `checkable`               | `boolean`                                   | `false` | Adds a left checkbox column for row selection. |
+ | `rowSelection`            | `Record<string, boolean>`                   | `{}`    | Controlled selection map. |
+ | `onRowSelectionChange`    | `OnChangeFn<Record<string, boolean>>`       | `undefined` | Selection change handler (controlled selection). |
+ | `onCheckedRowsChange`     | `(checkedRows: TData[]) => void`            | `undefined` | Returns selected row values (requires `checkable`). |
+ | `actions`                 | `DataTableActions[]`                        | `[]`    | Actions for the actions row. |
+ | `hidePagination`          | `boolean`                                   | `false` | Hide pagination UI. |
+ | `hideActionsRow`          | `boolean`                                   | `false` | Hide actions row. |
+ | `i18n`                    | `DataTableI18n`                             | `defaultDataTableI18n` | Internationalization strings. |
+ | `maxSortedColumns`        | `number`                                    | `2`     | Max number of sorted columns. |
+ | `initialState`            | `DataTableState`                            | `undefined` | Initial filters, sorting, pagination. |
+ | `serverMode`              | `boolean`                                   | `false` | Enable server-side mode. |
+ | `serverConfig`            | `DataTableServerConfig`                     | `undefined` | `{ totalItems, onStateChange }` handler for server mode. |
+ | `disableAutoPageSize`     | `boolean`                                   | `false` | Disable auto pageSize (still updates pageIndex). |
+ 
+ ---
+ 
+ ## Column meta
+ 
+ Configure columns via `column.meta`:
+ 
+ ```ts
+ type ColumnMeta = {
+   type: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'list_single_select' | 'list_multi_select' | 'other'
+   sortable?: boolean
+   filterable?: boolean
+   searchable?: boolean
+   pinned?: 'left' | 'right'
+   listOptions?: { value: string; label: string }[]
+ }
+ ```
+ 
+ Notes:
+ - `id` must match the field key used for filtering/sorting.
+ - Header should be a simple string (not JSX) for proper filtering/sorting UI.
+ - Filtering nested accessors (e.g., `"user.name"`) is not supported.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Filtering**: Badge filters + advanced builder with logical `_and`/`_or`.
+ - **Global search**: Across `meta.searchable` columns; strings use `like`, arrays use `array_overlap` (mapped automatically).
+ - **Operators**: Full operator set per type, including `eq_null`/`n_eq_null`, list operators (`array_overlap`, `n_array_overlap`), date/time before/after, checked/unchecked.
+ - **Sorting**: Multi-column (limited by `maxSortedColumns`).
+ - **Selection**: Integrated checkbox column when `checkable`.
+ - **Pinning**: `meta.pinned` supports left/right pinned columns.
+ - **Pagination**: Auto page size from container height; respects `disableAutoPageSize`.
+ - **Loading**: Skeleton rows adapt to viewport height (no hardcoded length).
+ - **i18n**: All labels (sorting/filtering menus included) use `DataTableI18n`.
+ - **Datetime**: Supports microseconds format like `2025-08-22T12:53:54.060315` and timezone-safe date handling.
+ 
+ ---
+ 
+ ## Server-side mode
+ 
+ When `serverMode=true`, the table emits state to `serverConfig.onStateChange(state)` with:
+ 
+ ```ts
+ type ServerState = {
+   pagination: { pageIndex: number; pageSize: number }
+   filters?: IFilterState
+   computedFilter?: SearchFilter
+   computedSorting?: { sort_by: string[]; sort_order: ('asc'|'desc')[] }
+ }
+ ```
+ 
+ The table manages debounced emissions and preserves computed values across updates.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Client mode using utilities (columns + filters + initial state)
+ 
+ ```tsx
+ import * as React from 'react'
+ import type { ColumnDef } from '@tanstack/react-table'
+ import {
+   DataTable,
+   createStringColumn,
+   createNumberColumn,
+   createSingleSelectColumn,
+   createMultiSelectColumn,
+   createActionColumn,
+   createInitialState,
+   createStringFilter,
+   createNumberFilter,
+ } from 'laif-ds'
+ import { Button } from 'laif-ds'
+ 
+ type Person = {
+   id: string
+   name: string
+   age: number
+   role: string
+   tags: string[]
+   created_at: string
+   active: boolean
+ }
+ 
+ const columns = [
+   createStringColumn<Person>({
+     accessorKey: 'name',
+     header: 'Nome',
+     sortable: true,
+     filterable: true,
+     searchable: true,
+   }),
+   createNumberColumn<Person>({
+     accessorKey: 'age',
+     header: 'Età',
+     sortable: true,
+     filterable: true,
+   }),
+   createSingleSelectColumn<Person>({
+     accessorKey: 'role',
+     header: 'Ruolo',
+     options: ['Admin', 'User', 'Guest'],
+     filterable: true,
+     searchable: true,
+   }),
+   createMultiSelectColumn<Person>({
+     accessorKey: 'tags',
+     header: 'Tags',
+     options: ['frontend', 'backend', 'devops'],
+     filterable: true,
+   }),
+   createActionColumn<Person>({
+     id: 'actions',
+     header: 'Azioni',
+     pinned: 'right',
+     cell: (row) => <Button size="sm">Edit {row.name}</Button>,
+   }),
+ ] satisfies ColumnDef<Person, any>[]
+ 
+ const initialState = createInitialState({
+   filters: [
+     createStringFilter('name', 'name', 'Nome', 'like', 'John'),
+     createNumberFilter('age', 'age', 'Età', 'ge', 18),
+   ],
+   searchbarFilter: 'developer',
+   sorting: [{ column: 'name', order: 'asc' }],
+   pagination: { pageIndex: 0, pageSize: 15 },
+ })
+ 
+ const actions = [
+   { label: 'Export CSV', icon: 'FileDown', onClick: () => {/* ... */} },
+   { label: 'Bulk Delete', icon: 'Trash2', onClick: () => {/* ... */} },
+ ]
+ 
+ export function ClientTable({ data }: { data: Person[] }) {
+   return (
+     <DataTable
+       columns={columns}
+       data={data}
+       initialState={initialState}
+       actions={actions}
+       checkable
+       onCheckedRowsChange={(rows) => console.log('checked rows', rows)}
+     />
+   )
+ }
+ ```
+ 
+ ### Server mode using utilities (state-driven fetch)
+ 
+ ```tsx
+ import * as React from 'react'
+ import type { ServerState } from 'laif-ds'
+ import { DataTable, createInitialState } from 'laif-ds'
+ 
+ export function ServerTable({ data, total }: { data: Person[]; total: number }) {
+   const [loading, setLoading] = React.useState(false)
+ 
+   const handleState = React.useCallback(async (state: ServerState) => {
+     // Use state.pagination, state.computedFilter, state.computedSorting
+     // to fetch from your backend
+     setLoading(true)
+     try {
+       await fetch('/api/people', {
+         method: 'POST',
+         headers: { 'Content-Type': 'application/json' },
+         body: JSON.stringify(state),
+       })
+       // Update your data + total here based on response
+     } finally {
+       setLoading(false)
+     }
+   }, [])
+ 
+   return (
+     <DataTable
+       columns={columns}
+       data={data}
+       loading={loading}
+       serverMode
+       serverConfig={{ totalItems: total, onStateChange: handleState }}
+       initialState={createInitialState({ pagination: { pageIndex: 0, pageSize: 20 } })}
+       checkable
+     />
+   )
+ }
+ ```
+ 
+ ### Utility recipes (pinning, list options, quick filters)
+ 
+ ```tsx
+ import {
+   pinColumns,
+   updateColumnListOptions,
+   toSelectOptions,
+   createFilterBadges,
+   createStringFilter,
+   createNumberFilter,
+ } from 'laif-ds'
+ 
+ // Pin columns to left/right
+ const pinnedColumns = pinColumns(columns, { left: ['name'], right: ['actions'] })
+ 
+ // Update list options dynamically (e.g., fetched from API)
+ const roleOptions = toSelectOptions(['Admin', 'User', 'Guest', 'Manager'])
+ const columnsWithUpdatedRoles = updateColumnListOptions(columns, 'role', roleOptions)
+ 
+ // Build multiple filter badges quickly
+ const quickFilters = createFilterBadges([
+   { columnId: 'name', columnAccessorKey: 'name', columnLabel: 'Nome', columnType: 'string', operator: 'like', value: 'Jane' },
+   { columnId: 'age', columnAccessorKey: 'age', columnLabel: 'Età', columnType: 'number', operator: 'ge', value: 30 },
+ ])
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Performance**: Client mode filters/sorts in-memory; use server mode for large datasets.
+ - **UX**: Page size auto-adapts; use `disableAutoPageSize` to manage it manually.
+ - **Internationalization**: Provide custom `i18n` for localized actions and labels.

package/dist/agent-docs/components/DatePicker.md

@@ -0,0 +1,109 @@
+ # DatePicker
+ 
+ ## Overview
+ 
+ Single-date picker composed of a `Button`-like trigger and a `Calendar` in a popover. Supports min/max date constraints, allowed dates, custom display format, sizes, and button variants.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop            | Type                                                                 | Default       | Description                                        |
+ | --------------- | -------------------------------------------------------------------- | ------------- | -------------------------------------------------- |
+ | `value`         | `Date`                                                                | `undefined`   | Controlled selected date.                          |
+ | `onChange`      | `(date: Date | undefined) => void`                                    | `undefined`   | Called when the date changes.                      |
+ | `placeholder`   | `string`                                                              | `"Seleziona data"` | Text when no date is selected.                |
+ | `dateFormat`    | `string`                                                              | `"PPP"`      | `date-fns` format string for the trigger text.     |
+ | `className`     | `string`                                                              | `""`         | Additional classes for the trigger.                 |
+ | `buttonVariant` | `"default" | "destructive" | "outline" | "secondary" | "ghost" | "link"` | `"default"` | Variant of the trigger button.             |
+ | `disabled`      | `boolean`                                                             | `false`       | Disables interactions and the popover.             |
+ | `size`          | `"sm" | "default" | "lg"`                                            | `"default"` | Trigger size.                                      |
+ | `firstDate`     | `Date`                                                                | `undefined`   | Minimum selectable date.                           |
+ | `lastDate`      | `Date`                                                                | `undefined`   | Maximum selectable date.                           |
+ | `availableDates`| `Date[]`                                                              | `undefined`   | Only these dates are selectable.                   |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Disabled dates**: `firstDate`, `lastDate`, and `availableDates` are combined into the `Calendar`’s `disabled` matcher array.
+ - **Disabled**: When `disabled` is true, the popover will not open and the trigger is non-interactive.
+ - **Formatting**: `dateFormat` is applied via `date-fns/format` to the selected date.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Basic
+ 
+ ```tsx
+ import { DatePicker } from "laif-ds";
+ 
+ export function BasicDatePicker() {
+   return <DatePicker />;
+ }
+ ```
+ 
+ ### Configurable
+ 
+ ```tsx
+ import { DatePicker } from "laif-ds";
+ 
+ export function ConfigurableDatePicker() {
+   return (
+     <DatePicker
+       value={new Date()}
+       placeholder="Seleziona una data"
+       dateFormat="PPP"
+       className="w-[300px]"
+       buttonVariant="outline"
+     />
+   );
+ }
+ ```
+ 
+ ### With Min/Max Dates
+ 
+ ```tsx
+ import { DatePicker } from "laif-ds";
+ 
+ export function WithMinMaxDates() {
+   return (
+     <DatePicker
+       placeholder="Seleziona una data tra le date minima e massima"
+       firstDate={new Date("2025-09-20")}
+       lastDate={new Date("2025-09-28")}
+       buttonVariant="outline"
+     />
+   );
+ }
+ ```
+ 
+ ### With Available Dates
+ 
+ ```tsx
+ import { DatePicker } from "laif-ds";
+ 
+ export function WithAvailableDates() {
+   return (
+     <DatePicker
+       placeholder="Scegli una delle date disponibili"
+       availableDates={[
+         new Date("2025-09-22"),
+         new Date("2025-09-25"),
+         new Date("2025-09-27"),
+       ]}
+       buttonVariant="outline"
+     />
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Sizing**: Use `size` to control the trigger typography and height.
+ - **Popover width**: The popover content uses the `Calendar` with no extra padding by default.
+ - **Internationalization**: The displayed date depends on the `dateFormat` string.
+