laif-ds 0.2.43 → 0.2.45

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

@@ -0,0 +1,63 @@
+# Table
+
+## Overview
+
+Styled table primitives for building data tables. Provides header, body, footer, rows, cells, and caption.
+
+---
+
+## Exports
+
+- `Table`
+- `TableHeader`
+- `TableBody`
+- `TableFooter`
+- `TableRow`
+- `TableHead`
+- `TableCell`
+- `TableCaption`
+
+All extend their corresponding HTML element props.
+
+---
+
+## Examples
+
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableCaption,
+} from "laif-ds";
+
+export function BasicTable() {
+  return (
+    <Table>
+      <TableCaption>Recent invoices</TableCaption>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Customer</TableHead>
+          <TableHead>Status</TableHead>
+          <TableHead>Amount</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        <TableRow>
+          <TableCell>Acme Inc.</TableCell>
+          <TableCell>Paid</TableCell>
+          <TableCell>€1,200.00</TableCell>
+        </TableRow>
+        <TableRow>
+          <TableCell>Globex</TableCell>
+          <TableCell>Open</TableCell>
+          <TableCell>€680.00</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+  );
+}
+```

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

@@ -0,0 +1,46 @@
+# TableSkeleton
+
+## Overview
+
+Skeleton placeholder for tables. Renders a header row and a configurable number of body rows with skeleton cells. Supports an optional top-left corner cell with two labels.
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `headerRow` | `string[]` | `[]` | Column headers. If empty, headers are skeletons |
+| `rowCount` | `number` | `5` | Number of skeleton rows |
+| `columnCount` | `number` | `5` | Used when `headerRow` is empty to define columns |
+| `className` | `string` | `undefined` | Additional wrapper classes |
+| `cornerHeaderFrom` | `string` | `undefined` | Top-left corner label (top-left) |
+| `cornerHeaderTo` | `string` | `undefined` | Top-left corner label (bottom-right) |
+
+---
+
+## Example
+
+```tsx
+import { TableSkeleton } from "laif-ds";
+
+export function LoadingTable() {
+  return (
+    <TableSkeleton
+      headerRow={["Name", "Email", "Role", "Status", "Actions"]}
+      rowCount={8}
+      className="mt-4"
+    />
+  );
+}
+```
+
+### With Corner Headers
+
+```tsx
+<TableSkeleton
+  headerRow={["Mon", "Tue", "Wed", "Thu", "Fri"]}
+  cornerHeaderFrom="From"
+  cornerHeaderTo="To"
+/>
+```

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

@@ -0,0 +1,86 @@
+ # Tabs
+ 
+ ## Overview
+ 
+ Radix Tabs with design-system styling. Provides a list of triggers and matching content panels, supporting horizontal and vertical orientations, disabled tabs, and manual/automatic activation.
+ 
+ ---
+ 
+ ## Components & Props
+ 
+ - **Tabs** (`Root`)
+   - `defaultValue?: string`
+   - `value?: string`
+   - `onValueChange?: (value: string) => void`
+   - `orientation?: "horizontal" | "vertical"` (default `"horizontal"`)
+   - `dir?: "ltr" | "rtl"` (default `"ltr"`)
+   - `activationMode?: "automatic" | "manual"` (default `"automatic"`)
+   - `className?: string`
+ - **TabsList**: Visual container for triggers.
+ - **TabsTrigger**
+   - `value: string`
+   - `disabled?: boolean`
+   - `className?: string`
+ - **TabsContent**
+   - `value: string`
+   - `className?: string`
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Activation**: `automatic` switches on focus; `manual` switches on click/Enter.
+ - **Orientation**: Vertical layout supported via `orientation="vertical"`.
+ - **Disabled**: `TabsTrigger` can be disabled and will not activate.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Default
+ 
+ ```tsx
+ import { Tabs, TabsList, TabsTrigger, TabsContent } from "laif-ds";
+ 
+ export function BasicTabs() {
+   return (
+     <Tabs defaultValue="account" className="w-[400px]">
+       <TabsList className="grid w-full grid-cols-2">
+         <TabsTrigger value="account">Account</TabsTrigger>
+         <TabsTrigger value="password">Password</TabsTrigger>
+       </TabsList>
+       <TabsContent value="account">Contenuto Account</TabsContent>
+       <TabsContent value="password">Contenuto Password</TabsContent>
+     </Tabs>
+   );
+ }
+ ```
+ 
+ ### Vertical
+ 
+ ```tsx
+ export function VerticalTabs() {
+   return (
+     <Tabs defaultValue="tab1" orientation="vertical" className="flex w-[600px]">
+       <TabsList className="flex h-auto w-[200px] flex-col">
+         <TabsTrigger value="tab1" className="justify-start">Profilo</TabsTrigger>
+         <TabsTrigger value="tab2" className="justify-start">Preferenze</TabsTrigger>
+         <TabsTrigger value="tab3" className="justify-start">Notifiche</TabsTrigger>
+       </TabsList>
+       <div className="ml-4 flex-1">
+         <TabsContent value="tab1" className="border-d-border rounded-md border p-4">Profilo</TabsContent>
+         <TabsContent value="tab2" className="border-d-border rounded-md border p-4">Preferenze</TabsContent>
+         <TabsContent value="tab3" className="border-d-border rounded-md border p-4">Notifiche</TabsContent>
+       </div>
+     </Tabs>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Styling**: `TabsList` uses DS tokens for backgrounds; `TabsTrigger` highlights when active.
+ - **Accessibility**: Uses Radix semantics for roles/aria and keyboard navigation out of the box.
+ 

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

@@ -0,0 +1,52 @@
+ # TextArea
+ 
+ ## Overview
+ 
+ Textarea with optional label wrapper and design-system focus/invalid styles. Accepts all native `<textarea>` props.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop             | Type               | Default     | Description |
+ | ---------------- | ------------------ | ----------- | ----------- |
+ | `label`          | `React.ReactNode`  | `undefined` | Optional label text/node above the textarea. |
+ | `labelClassName` | `string`           | `undefined` | Classes for `Label`. |
+ | `wrpClassName`   | `string`           | `undefined` | Wrapper classes. |
+ | `id`             | `string`           | `auto`      | If omitted and `label` is provided, an id is generated. |
+ | `...props`       | `React.ComponentProps<'textarea'>` | — | All native textarea props (e.g., `rows`, `placeholder`, `disabled`). |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Auto id**: When `label` exists and `id` is not provided, an id is generated and linked via `Label htmlFor`.
+ - **Styling**: Uses DS tokens for border, focus ring, disabled, and invalid states (`aria-invalid`).
+ 
+ ---
+ 
+ ## Example
+ 
+ ```tsx
+ import { Textarea } from "laif-ds";
+ 
+ export function Example() {
+   return (
+     <Textarea
+       label="Descrizione"
+       placeholder="Scrivi qui..."
+       defaultValue="Testo di esempio"
+       rows={4}
+       wrpClassName="w-[500px]"
+     />
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Validation**: Add `aria-invalid` to reflect error state.
+ - **Resize**: Control with native CSS `resize` via `className` if needed.
+ 

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

@@ -0,0 +1,69 @@
+ # ThemeSwitcher
+ 
+ ## Overview
+ 
+ Theme toggle with three options: system, light, dark. Uses a controlled/uncontrolled API and avoids hydration mismatch by rendering only after mount.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop           | Type                               | Default   | Description |
+ | -------------- | ---------------------------------- | --------- | ----------- |
+ | `value`        | `"light" | "dark" | "system"` | `undefined` | Controlled theme value. |
+ | `onChange`     | `(theme: "light" | "dark" | "system") => void` | `undefined` | Called when theme changes. |
+ | `defaultValue` | `"light" | "dark" | "system"` | `"system"` | Initial value when uncontrolled. |
+ | `className`    | `string`                            | `undefined` | Container classes. |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **SSR safe**: Renders `null` until mounted to prevent hydration mismatch.
+ - **Active state**: Highlights the active option with a rounded background.
+ - **Control**: Works in both controlled (`value`/`onChange`) and uncontrolled (`defaultValue`) modes.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Default (uncontrolled)
+ 
+ ```tsx
+ import { ThemeSwitcher } from "laif-ds";
+ 
+ export function DefaultTheme() {
+   return <ThemeSwitcher defaultValue="system" />;
+ }
+ ```
+ 
+ ### Controlled
+ 
+ ```tsx
+ import * as React from "react";
+ import { ThemeSwitcher } from "laif-ds";
+ 
+ export function ControlledTheme() {
+   const [theme, setTheme] = React.useState<"light" | "dark" | "system">("system");
+   return (
+     <div className="flex flex-col items-start gap-2">
+       <ThemeSwitcher value={theme} onChange={setTheme} />
+       <div className="text-d-muted-foreground text-sm">Current theme: <span className="font-medium">{theme}</span></div>
+     </div>
+   );
+ }
+ ```
+ 
+ ### Custom styling
+ 
+ ```tsx
+ <ThemeSwitcher defaultValue="system" className="h-10 w-32 p-2" />
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Icons**: The component renders icons internally; no configuration required.
+ - **Persistence**: Persisting theme choice is up to the app (e.g., localStorage + class on `html`).
+ 

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

@@ -0,0 +1,23 @@
+# Toaster
+
+## Overview
+
+Styled `sonner` Toaster with design-system classNames for toast, description, and action buttons.
+
+---
+
+## Usage
+
+```tsx
+import { Toaster } from "laif-ds";
+
+export function App() {
+  return <Toaster position="top-right" />;
+}
+```
+
+Applies classNames for:
+- `toast`
+- `description`
+- `actionButton`
+- `cancelButton`

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

@@ -0,0 +1,31 @@
+# Toggle
+
+## Overview
+
+Single toggle button component with variants and sizes. Built on Radix Toggle.
+
+---
+
+## Props
+
+Extends `@radix-ui/react-toggle` Root props plus variants.
+
+- `variant`: `"default" | "outline"` (default: `"default"`)
+- `size`: `"default" | "sm" | "lg"` (default: `"default"`)
+
+---
+
+## Example
+
+```tsx
+import { Toggle } from "laif-ds";
+import { Bold } from "lucide-react";
+
+export function BoldToggle() {
+  return (
+    <Toggle aria-label="Toggle bold">
+      <Bold />
+    </Toggle>
+  );
+}
+```

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

@@ -0,0 +1,30 @@
+# ToggleGroup
+
+## Overview
+
+Group of toggle buttons with shared variant/size context. Built on Radix Toggle Group.
+
+---
+
+## Exports
+
+- `ToggleGroup` — container; supports Radix `type="single" | "multiple"`
+- `ToggleGroupItem` — individual item inheriting variant/size from context
+
+---
+
+## Example
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "laif-ds";
+
+export function AlignmentGroup() {
+  return (
+    <ToggleGroup type="single" defaultValue="center" variant="outline">
+      <ToggleGroupItem value="left">Left</ToggleGroupItem>
+      <ToggleGroupItem value="center">Center</ToggleGroupItem>
+      <ToggleGroupItem value="right">Right</ToggleGroupItem>
+    </ToggleGroup>
+  );
+}
+```

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

@@ -0,0 +1,91 @@
+ # Tooltip
+ 
+ ## Overview
+ 
+ Radix Tooltip wrappers with DS tokens and variants. Includes `TooltipProvider` for global delay, `Tooltip` root, `TooltipTrigger`, and `TooltipContent` with `primary` and `card` looks.
+ 
+ ---
+ 
+ ## Components & Props
+ 
+ - **TooltipProvider**
+   - `delayDuration?: number` (default `0`)
+   - Provides default open delay for nested tooltips.
+ - **Tooltip** (Root)
+   - Inherits Radix `TooltipPrimitive.Root` props: `open?`, `defaultOpen?`, `onOpenChange?`, `disableHoverableContent?`.
+   - Note: `delayDuration` is set via `TooltipProvider`, not here.
+ - **TooltipTrigger**
+   - Inherits Radix `Trigger` props. Use `asChild` to wrap buttons/links.
+ - **TooltipContent**
+   - Inherits Radix `Content` props: `side?`, `align?`, `sideOffset?` (default `0`), `alignOffset?`.
+   - `variant?: "primary" | "card"` (default `"primary"`).
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Default
+ 
+ ```tsx
+ import { Button, Tooltip, TooltipTrigger, TooltipContent } from "laif-ds";
+ 
+ export function Basic() {
+   return (
+     <Tooltip>
+       <TooltipTrigger asChild>
+         <Button variant="outline">Passa sopra</Button>
+       </TooltipTrigger>
+       <TooltipContent>Questo è un tooltip</TooltipContent>
+     </Tooltip>
+   );
+ }
+ ```
+ 
+ ### Positioning
+ 
+ ```tsx
+ <div className="flex items-center gap-4">
+   <Tooltip>
+     <TooltipTrigger asChild><Button size="sm">Top</Button></TooltipTrigger>
+     <TooltipContent side="top" sideOffset={5}>Tooltip in alto</TooltipContent>
+   </Tooltip>
+   <Tooltip>
+     <TooltipTrigger asChild><Button size="sm">Right</Button></TooltipTrigger>
+     <TooltipContent side="right" sideOffset={5}>Tooltip a destra</TooltipContent>
+   </Tooltip>
+ </div>
+ ```
+ 
+ ### With Delay
+ 
+ ```tsx
+ import { TooltipProvider } from "laif-ds";
+ 
+ export function WithDelay() {
+   return (
+     <TooltipProvider delayDuration={500}>
+       <Tooltip>
+         <TooltipTrigger asChild><Button>Ritardo 500ms</Button></TooltipTrigger>
+         <TooltipContent>Appare dopo 500ms</TooltipContent>
+       </Tooltip>
+     </TooltipProvider>
+   );
+ }
+ ```
+ 
+ ### Card Variant
+ 
+ ```tsx
+ <Tooltip>
+   <TooltipTrigger asChild><Button variant="ghost">Info</Button></TooltipTrigger>
+   <TooltipContent variant="card">Contenuto con bordo e shadow</TooltipContent>
+ </Tooltip>
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Variants**: `primary` for compact color tooltip; `card` for bordered content blocks.
+ - **Groups**: Wrap toolbars with multiple triggers; provider can be defined once at app root.
+ 

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

@@ -0,0 +1,21 @@
+# TypingIndicator
+
+## Overview
+
+Animated three-dot typing indicator for chat UIs.
+
+---
+
+## Example
+
+```tsx
+import { TypingIndicator } from "laif-ds";
+
+export function ChatFooter() {
+  return (
+    <div className="p-2">
+      <TypingIndicator />
+    </div>
+  );
+}
+```

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

@@ -0,0 +1,65 @@
+ # Typo
+ 
+ ## Overview
+ 
+ Typography component with predefined variants for headings, body text, captions, and utility text. Renders a semantic HTML tag per variant (overridable via `as`).
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop       | Type                              | Default   | Description |
+ | ---------- | --------------------------------- | --------- | ----------- |
+ | `variant`  | `TypoVariant`                     | `"body"` | Typographic style to apply. |
+ | `as`       | `React.ElementType`               | auto      | Override rendered HTML element. |
+ | `className`| `string`                          | `undefined` | Extra classes. |
+ | `...props` | `React.HTMLAttributes<HTMLElement>` | —         | Spread to rendered element. |
+ 
+ `TypoVariant`:
+ 
+ - `"hero-title"`, `"title"`, `"subtitle"`
+ - `"body"`, `"body-bold"`
+ - `"caption"`, `"overline"`, `"button"`, `"small"`
+ - `"h1"`, `"h2"`, `"h3"`, `"h4"`, `"h5"`
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Semantic tag**: Each variant maps to a sensible HTML tag (e.g., `h1` for `h1`, `p` for `body`).
+ - **Theming**: Variants use DS tokens for color and size; add `className` to tweak.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ```tsx
+ import { Typo } from "laif-ds";
+ 
+ export function Variants() {
+   return (
+     <div className="space-y-2">
+       <Typo variant="hero-title">Hero Title</Typo>
+       <Typo variant="title">Page Title</Typo>
+       <Typo variant="subtitle">Subtitle</Typo>
+       <Typo variant="body">Regular body text</Typo>
+       <Typo variant="body-bold">Bold body text</Typo>
+       <Typo variant="caption">Caption</Typo>
+       <Typo variant="overline">Overline</Typo>
+       <Typo variant="small">Small text</Typo>
+     </div>
+   );
+ }
+ 
+ export function OverrideElement() {
+   return <Typo variant="body" as="span">Inline body as span</Typo>;
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Accessibility**: Use heading variants (`h1`–`h5`) to reflect document structure.
+ - **Consistency**: Prefer `variant` over ad‑hoc classes for consistent typography.
+ 

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

@@ -0,0 +1,64 @@
+ # 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.
+