laif-ds 0.2.43 → 0.2.45

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

@@ -0,0 +1,222 @@
+ # Calendar
+ 
+ ## Overview
+ 
+ Flexible calendar component built on `react-day-picker`. Supports single, multiple, and range selections, localization, week settings, and rich customization via class names and sub-components.
+ 
+ ---
+ 
+ ## Props
+ 
+ Props extend `DayPicker` props with a few defaults and additions.
+ 
+ | Prop             | Type                                         | Default      | Description                                      |
+ | ---------------- | -------------------------------------------- | ------------ | ------------------------------------------------ |
+ | `mode`           | `"default" | "single" | "multiple" | "range"`  | `"default"` | Selection mode.                                  |
+ | `selected`       | `Date | Date[] | DateRange`                  | `undefined`  | Controlled selection value.                      |
+ | `defaultMonth`   | `Date`                                        | `undefined`  | Month to display initially.                      |
+ | `fromDate`       | `Date`                                        | `undefined`  | Minimum selectable date.                         |
+ | `toDate`         | `Date`                                        | `undefined`  | Maximum selectable date.                         |
+ | `disabled`       | `Matcher | Matcher[]`                         | `undefined`  | Disabled dates.                                  |
+ | `showOutsideDays`| `boolean`                                     | `true`       | Show days from adjacent months.                  |
+ | `ISOWeek`        | `boolean`                                     | `false`      | Use ISO week numbering.                          |
+ | `fixedWeeks`     | `boolean`                                     | `false`      | Always show 6 weeks.                             |
+ | `numberOfMonths` | `number`                                      | `1`          | Number of months to display.                     |
+ | `locale`         | `Locale`                                      | `undefined`  | Locale object for formatting.                    |
+ | `weekStartsOn`   | `0 | 1 | 2 | 3 | 4 | 5 | 6`                   | `0`          | Start of the week (0=Sun, 1=Mon, ...).          |
+ | `captionLayout`  | `"label" | "dropdown"`                      | `"label"`   | Caption rendering mode.                          |
+ | `buttonVariant`  | `Button["variant"]`                          | `"ghost"`   | Variant for navigation buttons.                  |
+ | `formatters`     | `Partial<DayPickerFormatters>`                | `{}`         | Custom label formatters.                         |
+ | `components`     | `Partial<DayPickerComponents>`                | `{}`         | Custom component overrides.                      |
+ | `className`      | `string`                                      | `""`         | Additional container classes.                    |
+ | `onSelect`       | `(value: Date | Date[] | DateRange | undefined) => void` | `undefined` | Called when selection changes.       |
+ | `onDayClick`     | `(day: Date) => void`                         | `undefined`  | Called on day click.                             |
+ | `onMonthChange`  | `(month: Date) => void`                       | `undefined`  | Called when the displayed month changes.         |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Selection**: Single, multiple, and range selection with visual feedback.
+ - **Navigation**: Previous/next buttons use `buttonVariant` styling.
+ - **Localization**: Supply `locale`, `weekStartsOn`, and `formatters` for i18n.
+ - **Accessibility**: Keyboard navigation and focus management included.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Basic
+ 
+ ```tsx
+ import { Calendar } from "laif-ds";
+ 
+ export function BasicCalendar() {
+   return (
+     <Calendar
+       className="border-d-border rounded-md border"
+       showOutsideDays
+       onDayClick={(d) => console.log("day clicked", d)}
+       onMonthChange={(m) => console.log("month", m)}
+     />
+   );
+ }
+ ```
+ 
+ ### Single Selection
+ 
+ ```tsx
+ import { useState } from "react";
+ import { Calendar } from "laif-ds";
+ 
+ export function SingleSelection() {
+   const [date, setDate] = useState<Date | undefined>(new Date());
+ 
+   return (
+     <div className="flex flex-col gap-2">
+       <Calendar
+         mode="single"
+         selected={date}
+         onSelect={setDate}
+         className="border-d-border rounded-md border"
+       />
+       <p className="text-sm text-d-secondary-foreground text-center">
+         {date ? date.toDateString() : "Nessuna data selezionata"}
+       </p>
+     </div>
+   );
+ }
+ ```
+ 
+ ### Multiple Selection
+ 
+ ```tsx
+ import { useState } from "react";
+ import { Calendar } from "laif-ds";
+ 
+ export function MultipleSelection() {
+   const [dates, setDates] = useState<Date[] | undefined>([new Date()]);
+ 
+   return (
+     <div className="flex flex-col gap-2">
+       <Calendar
+         mode="multiple"
+         selected={dates}
+         onSelect={setDates}
+         className="border-d-border rounded-md border"
+       />
+       <p className="text-sm text-d-secondary-foreground text-center">
+         {dates && dates.length > 0 ? `${dates.length} date selezionate` : "Nessuna data selezionata"}
+       </p>
+     </div>
+   );
+ }
+ ```
+ 
+ ### Range Selection
+ 
+ ```tsx
+ import { useState } from "react";
+ import { Calendar } from "laif-ds";
+ import type { DateRange } from "react-day-picker";
+ 
+ export function RangeSelection() {
+   const [range, setRange] = useState<DateRange | undefined>({ from: new Date(), to: new Date() });
+ 
+   return (
+     <div className="flex flex-col gap-2">
+       <Calendar
+         mode="range"
+         selected={range}
+         onSelect={setRange}
+         className="border-d-border rounded-md border"
+         numberOfMonths={2}
+         showOutsideDays
+       />
+       <p className="text-sm text-d-secondary-foreground text-center">
+         {range?.from && range?.to
+           ? `${range.from.toDateString()} - ${range.to.toDateString()}`
+           : range?.from
+           ? `Da ${range.from.toDateString()}`
+           : "Seleziona un intervallo"}
+       </p>
+     </div>
+   );
+ }
+ ```
+ 
+ ### Disabled Dates
+ 
+ ```tsx
+ import { useState } from "react";
+ import { Calendar } from "laif-ds";
+ import { addDays } from "date-fns";
+ 
+ export function DisabledDates() {
+   const [date, setDate] = useState<Date | undefined>(new Date());
+   const disabledDays = [
+     { from: addDays(new Date(), 1), to: addDays(new Date(), 5) },
+     new Date(new Date().setDate(15)),
+     { before: addDays(new Date(), -10) },
+   ];
+ 
+   return (
+     <Calendar
+       mode="single"
+       selected={date}
+       onSelect={setDate}
+       disabled={disabledDays}
+       className="border-d-border rounded-md border"
+     />
+   );
+ }
+ ```
+ 
+ ### Localized (Italian) and Week Start
+ 
+ ```tsx
+ import { Calendar } from "laif-ds";
+ import { it } from "date-fns/locale";
+ import { format } from "date-fns";
+ 
+ export function LocalizedCalendar() {
+   return (
+     <Calendar
+       className="border-d-border rounded-md border"
+       locale={it}
+       weekStartsOn={1}
+       formatters={{
+         formatMonthCaption: (date: Date) => format(date, "MMMM yyyy", { locale: it }),
+         formatWeekdayName: (date: Date) => format(date, "EEEEEE", { locale: it }),
+       }}
+     />
+   );
+ }
+ ```
+ 
+ ### ISO Week, Fixed Weeks, Multiple Months
+ 
+ ```tsx
+ import { Calendar } from "laif-ds";
+ 
+ export function ISOWeekCalendar() {
+   return <Calendar className="border-d-border rounded-md border" ISOWeek weekStartsOn={1} />;
+ }
+ 
+ export function FixedWeeksCalendar() {
+   return <Calendar className="border-d-border rounded-md border" fixedWeeks showOutsideDays />;
+ }
+ 
+ export function MultiMonthCalendar() {
+   return <Calendar className="border-d-border rounded-md border" numberOfMonths={2} showOutsideDays />;
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Customization**: Use `classNames` and `components` to override internal parts.
+ - **Buttons**: `buttonVariant` controls navigation buttons’ appearance.
+ - **Range**: Range selection highlights start, middle, and end days with rounded edges.
+ 

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

@@ -0,0 +1,147 @@
+ # Card
+ 
+ ## Overview
+ 
+ Composable container with header, content, footer, and optional action area. Supports size variants that control internal padding and spacing.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### Card (Root)
+ 
+ | Prop        | Type                          | Default     | Description                                  |
+ | ----------- | ----------------------------- | ----------- | -------------------------------------------- |
+ | `size`      | `"default" | "sm" | "lg" | "none"` | `"default"` | Controls internal padding and spacing.       |
+ | `className` | `string`                      | `""`        | Additional classes for layout and width.      |
+ | `children`  | `React.ReactNode`             | **required**| Compose with subcomponents below.             |
+ 
+ ### Subcomponents
+ 
+ - `CardHeader`: Top section, usually with `CardTitle`, `CardDescription`, and optional `CardAction`.
+ - `CardTitle`: Title text area.
+ - `CardDescription`: Secondary text under the title.
+ - `CardAction`: Right-aligned area inside the header for buttons/menus.
+ - `CardContent`: Main content area.
+ - `CardFooter`: Bottom area for actions or summaries.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Size variants**: `sm`, `default`, `lg`, `none` change vertical padding and gaps.
+ - **Header/Footer borders**: Apply border utilities on header/footer to create separators.
+ - **Layout**: Use `className` for width and responsive behavior.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Basic
+ 
+ ```tsx
+ import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "laif-ds";
+ import { Button } from "laif-ds";
+ 
+ export function BasicCard() {
+   return (
+     <Card className="w-[350px]">
+       <CardHeader>
+         <CardTitle>Card Title</CardTitle>
+         <CardDescription>Card description goes here</CardDescription>
+       </CardHeader>
+       <CardContent>
+         <p>This is the main content of the card. You can put any content here.</p>
+       </CardContent>
+       <CardFooter>
+         <Button>Action</Button>
+       </CardFooter>
+     </Card>
+   );
+ }
+ ```
+ 
+ ### With Action
+ 
+ ```tsx
+ import { Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent } from "laif-ds";
+ import { Button } from "laif-ds";
+ 
+ export function CardWithAction() {
+   return (
+     <Card className="w-[350px]">
+       <CardHeader>
+         <CardTitle>Card with Action</CardTitle>
+         <CardDescription>Card with an action button in the header</CardDescription>
+         <CardAction>
+           <Button variant="ghost" size="icon">⋯</Button>
+         </CardAction>
+       </CardHeader>
+       <CardContent>
+         <p>This card has an action button in the top right corner.</p>
+       </CardContent>
+     </Card>
+   );
+ }
+ ```
+ 
+ ### Size Variants
+ 
+ ```tsx
+ import { Card, CardHeader, CardTitle, CardDescription, CardContent } from "laif-ds";
+ 
+ export function SizeVariants() {
+   return (
+     <div className="flex flex-col gap-8">
+       <Card size="sm" className="w-[350px]">
+         <CardHeader>
+           <CardTitle>Size: Small</CardTitle>
+           <CardDescription>Reduced padding (sm)</CardDescription>
+         </CardHeader>
+         <CardContent>
+           <p>This card uses size="sm".</p>
+         </CardContent>
+       </Card>
+ 
+       <Card size="default" className="w-[350px]">
+         <CardHeader>
+           <CardTitle>Size: Default</CardTitle>
+           <CardDescription>Standard padding (default)</CardDescription>
+         </CardHeader>
+         <CardContent>
+           <p>This card uses size="default".</p>
+         </CardContent>
+       </Card>
+ 
+       <Card size="lg" className="w-[350px]">
+         <CardHeader>
+           <CardTitle>Size: Large</CardTitle>
+           <CardDescription>Spacious padding (lg)</CardDescription>
+         </CardHeader>
+         <CardContent>
+           <p>This card uses size="lg".</p>
+         </CardContent>
+       </Card>
+ 
+       <Card size="none" className="w-[350px]">
+         <CardHeader className="border-d-border border-b p-4">
+           <CardTitle>Size: None</CardTitle>
+           <CardDescription>No default padding (none)</CardDescription>
+         </CardHeader>
+         <CardContent className="p-4">
+           <p>This card uses size="none" with custom padding.</p>
+         </CardContent>
+       </Card>
+     </div>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Composability**: Use only the subcomponents you need.
+ - **Borders**: Add `border-b`/`border-t` to header/footer for separation.
+ - **Action area**: `CardAction` aligns content to the top-right in the header.
+ 

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

@@ -0,0 +1,129 @@
+ # Carousel
+ 
+ ## Overview
+ 
+ A flexible, accessible carousel built on Embla. Supports horizontal/vertical orientation, previous/next controls, keyboard navigation, and responsive layouts.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### Carousel (Root)
+ 
+ | Prop           | Type                                   | Default        | Description                                        |
+ | -------------- | -------------------------------------- | -------------- | -------------------------------------------------- |
+ | `orientation`  | `"horizontal" | "vertical"`         | `"horizontal"` | Scroll axis for the carousel.                      |
+ | `opts`         | `EmblaOptionsType`                      | `{}`           | Embla options (e.g., loop).                        |
+ | `plugins`      | `EmblaPluginType[]`                     | `[]`           | Embla plugins.                                     |
+ | `setApi`       | `(api: CarouselApi) => void`            | `undefined`    | Receives the Embla API instance.                   |
+ | `className`    | `string`                                | `""`           | Additional classes for the container.              |
+ | `children`     | `React.ReactNode`                       | **required**   | Compose with subcomponents below.                  |
+ 
+ ### Subcomponents
+ 
+ - `CarouselContent`: Scroll container (wraps slides).
+ - `CarouselItem`: A single slide.
+ - `CarouselPrevious`: Previous button (disabled when not scrollable).
+ - `CarouselNext`: Next button (disabled when not scrollable).
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Keyboard**: Left/Right arrows move slides (when horizontal).
+ - **Controls**: Prev/Next buttons enable/disable based on scroll availability.
+ - **Orientation**: Vertical orientation rotates controls appropriately.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Basic
+ 
+ ```tsx
+ import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext } from "laif-ds";
+ import { Card, CardContent } from "laif-ds";
+ 
+ export function BasicCarousel() {
+   return (
+     <Carousel className="w-full max-w-xs">
+       <CarouselContent>
+         {Array.from({ length: 5 }).map((_, index) => (
+           <CarouselItem key={index}>
+             <div className="p-1">
+               <Card>
+                 <CardContent className="flex aspect-square items-center justify-center p-6">
+                   <span className="text-xl font-semibold">{index + 1}</span>
+                 </CardContent>
+               </Card>
+             </div>
+           </CarouselItem>
+         ))}
+       </CarouselContent>
+       <CarouselPrevious />
+       <CarouselNext />
+     </Carousel>
+   );
+ }
+ ```
+ 
+ ### Multiple Items per Row
+ 
+ ```tsx
+ import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext } from "laif-ds";
+ import { Card, CardContent } from "laif-ds";
+ 
+ export function MultipleItems() {
+   return (
+     <Carousel className="w-full max-w-md">
+       <CarouselContent className="-ml-1">
+         {Array.from({ length: 10 }).map((_, index) => (
+           <CarouselItem key={index} className="pl-1 md:basis-1/2 lg:basis-1/3">
+             <div className="p-1">
+               <Card>
+                 <CardContent className="flex aspect-square items-center justify-center p-6">
+                   <span className="text-lg font-semibold">{index + 1}</span>
+                 </CardContent>
+               </Card>
+             </div>
+           </CarouselItem>
+         ))}
+       </CarouselContent>
+       <CarouselPrevious />
+       <CarouselNext />
+     </Carousel>
+   );
+ }
+ ```
+ 
+ ### With API (loop)
+ 
+ ```tsx
+ import { useState } from "react";
+ import type { CarouselApi } from "laif-ds";
+ import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from "laif-ds";
+ 
+ export function CarouselWithApi() {
+   const [api, setApi] = useState<CarouselApi | null>(null);
+   return (
+     <Carousel className="w-full max-w-xs" setApi={setApi} opts={{ loop: true }}>
+       <CarouselContent>
+         {[1, 2, 3, 4, 5].map((n) => (
+           <CarouselItem key={n}><div className="p-6">Slide {n}</div></CarouselItem>
+         ))}
+       </CarouselContent>
+       <CarouselPrevious />
+       <CarouselNext />
+     </Carousel>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Focus**: The root handles arrow keys via `onKeyDownCapture`.
+ - **Responsiveness**: Use `basis-*` utilities on `CarouselItem` for multi-column layouts.
+ - **Plugins**: Pass Embla plugins via `plugins` prop when needed.
+ 

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

@@ -0,0 +1,75 @@
+# Chart
+
+## Overview
+
+Design-system primitives around Recharts providing a container with theme-aware color variables, tooltip and legend content helpers.
+
+---
+
+## Exports
+
+- `ChartContainer` — wraps `ResponsiveContainer` and provides CSS vars per series
+- `ChartTooltip`, `ChartTooltipContent` — tooltip with indicator and label formatting
+- `ChartLegend`, `ChartLegendContent` — legend component with icon/color support
+- `ChartStyle` — internal style tag used by `ChartContainer`
+
+---
+
+## Types
+
+```ts
+export type ChartConfig = {
+  [k: string]: {
+    label?: React.ReactNode;
+    icon?: React.ComponentType;
+  } & ({ color?: string } | { theme: { light: string; dark: string } });
+};
+```
+
+---
+
+## Example
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
+} from "laif-ds";
+import {
+  LineChart,
+  Line,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+} from "recharts";
+
+const data = [
+  { month: "Jan", users: 400 },
+  { month: "Feb", users: 800 },
+  { month: "Mar", users: 650 },
+];
+
+const config = {
+  users: { label: "Users", theme: { light: "#0ea5e9", dark: "#7dd3fc" } },
+};
+
+export function UsersChart() {
+  return (
+    <ChartContainer config={config} className="w-full">
+      <LineChart data={data} margin={{ left: 12, right: 12 }}>
+        <CartesianGrid strokeDasharray="3 3" />
+        <XAxis dataKey="month" />
+        <YAxis />
+        <Tooltip content={<ChartTooltipContent />} />
+        <Legend content={<ChartLegendContent />} />
+        <Line type="monotone" dataKey="users" stroke="var(--color-users)" />
+      </LineChart>
+    </ChartContainer>
+  );
+}
+```

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

@@ -0,0 +1,109 @@
+ # Chat
+ 
+ ## Overview
+ 
+ Complete chat interface: message list with markdown rendering, auto-scroll and typing indicator; composer with text, attachments, and voice; optional suggestions for empty state; message actions (copy, rate, save) and inline edit of assistant messages.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop               | Type                                           | Default     | Description |
+ | ------------------ | ---------------------------------------------- | ----------- | ----------- |
+ | `messages`         | `Message[]`                                    | **required**| Messages to render. See `ChatMessage` for shape. |
+ | `input`            | `string`                                       | **required**| Current input value. |
+ | `handleSubmit`     | `(event?, opts?) => void`                      | **required**| Called on form submit. Supports `{ experimental_attachments?: FileList }`. |
+ | `handleInputChange`| `React.ChangeEventHandler<HTMLTextAreaElement>`| **required**| Input change handler. |
+ | `isGenerating`     | `boolean`                                      | `false`     | Whether assistant is generating. Enables interrupt UI. |
+ | `stop`             | `() => void`                                   | `undefined` | Stop generation callback. |
+ | `allowAttachments` | `boolean`                                      | `false`     | Enable file attachments UI. |
+ | `transcribeAudio`  | `(blob: Blob) => Promise<string>`              | `undefined` | Speech-to-text function for voice input. |
+ | `onEdit`           | `(messageId: string, newContent: string) => void`| `undefined`| Enable inline edit on assistant messages. |
+ | `onMessageSave`    | `(messageId: string, content: string) => void` | `undefined` | Enable save action on assistant messages. |
+ | `onRateResponse`   | `(messageId: string, rating: "thumbs-up" | "thumbs-down") => void` | `undefined` | Enable rating actions. |
+ | `append`           | `(message: { role: "user"; content: string }) => void` | `undefined` | Show prompt suggestions and handle clicks. |
+ | `suggestions`      | `string[]`                                     | `undefined` | Suggestions displayed when empty. Requires `append`. |
+ | `className`        | `string`                                       | `undefined` | Wrapper classes. |
+ | `welcomeTitle`     | `string`                                       | `"Da dove iniziamo?"` | Title shown in empty state. |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Auto-scroll**: Scrolls to latest messages unless user scrolls up (then shows "scroll to bottom").
+ - **Composer**: `MessageInput` supports Enter-to-send, attachments, and voice input with transcription.
+ - **Actions**: Copy, save, thumbs up/down per assistant message.
+ - **Edit**: Inline edit of assistant messages with Enter to save / Esc to cancel.
+ - **Suggestions**: When `messages` is empty and `suggestions` provided, renders clickable suggestions via `append`.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Default
+ 
+ ```tsx
+ import * as React from "react";
+ import { Chat } from "laif-ds";
+ import type { Message } from "laif-ds";
+ 
+ export function BasicChat() {
+   const [messages, setMessages] = React.useState<Message[]>([
+     { id: "1", role: "user", content: "Hello!", createdAt: new Date() },
+     { id: "2", role: "assistant", content: "How can I help?", createdAt: new Date() },
+   ]);
+   const [input, setInput] = React.useState("");
+ 
+   const handleSubmit = () => {
+     if (!input.trim()) return;
+     setMessages((prev) => [...prev, { id: Date.now().toString(), role: "user", content: input, createdAt: new Date() }]);
+     setInput("");
+   };
+ 
+   return (
+     <div className="h-[500px] w-full max-w-3xl">
+       <Chat
+         messages={messages}
+         input={input}
+         handleInputChange={(e) => setInput(e.target.value)}
+         handleSubmit={handleSubmit}
+         isGenerating={false}
+       />
+     </div>
+   );
+ }
+ ```
+ 
+ ### With Attachments and Actions
+ 
+ ```tsx
+ import * as React from "react";
+ import { Chat } from "laif-ds";
+ 
+ export function FullChat() {
+   const [input, setInput] = React.useState("");
+   return (
+     <div className="h-[600px] w-full">
+       <Chat
+         messages={[]}
+         input={input}
+         handleInputChange={(e) => setInput(e.target.value)}
+         handleSubmit={() => {}}
+         isGenerating={false}
+         allowAttachments
+         onMessageSave={(id, content) => console.log("save", id, content)}
+         onRateResponse={(id, rating) => console.log("rate", id, rating)}
+       />
+     </div>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Types**: See `Message` in `chat-message.tsx` for full shape (supports tool invocations and parts).
+ - **Interrupt**: When `isGenerating` is true and `stop` provided, `Enter` prompts to stop then submit.
+ - **Composition**: Chat uses `MessageList`, `MessageInput`, and utilities like `CopyButton` and `PromptSuggestions`.
+