laif-ds 0.2.44 → 0.2.45

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

@@ -0,0 +1,132 @@
+ # Select (Deprecated)
+ 
+ ## Overview
+ 
+ Single-selection dropdown built on Radix Select.
+ 
+ - ⚠️ This component is deprecated. Prefer `AppSelect` for new code.
+ 
+ ---
+ 
+ ## Subcomponents & Props
+ 
+ - **Select**: Root container with optional label
+   - `size`: `"sm" | "default" | "lg"` (default `"default"`)
+   - `label`: `string | React.ReactNode`
+   - `className`, `labelClassName`
+ - **SelectTrigger**: Button that opens the list
+   - `size?`: optional override of context size
+ - **SelectContent**: Floating list panel (Radix Content props)
+ - **SelectGroup**: Group wrapper
+ - **SelectItem**: Option row
+ - **SelectLabel**: Group label
+ - **SelectSeparator**: Separator line
+ - **SelectValue**: Selected value placeholder/slot
+ - **SelectScrollUpButton / SelectScrollDownButton**: Scroll affordances
+ 
+ Root also exposes typical controlled props from Radix (`value`, `defaultValue`, `onValueChange`, `disabled`, `required`, `name`).
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Sizes**: `size` controls trigger height and font size.
+ - **Keyboard**: Typeahead, arrow navigation, Enter/Space to select.
+ - **Accessibility**: Labels via `Label` + `htmlFor`/`id`.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Interactive
+ 
+ ```tsx
+ import { useState } from "react";
+ import { Label } from "laif-ds";
+ import {
+   Select,
+   SelectTrigger,
+   SelectValue,
+   SelectContent,
+   SelectGroup,
+   SelectLabel,
+   SelectItem,
+   SelectSeparator,
+ } from "laif-ds";
+ 
+ export function InteractiveSelect() {
+   const [value, setValue] = useState("");
+   return (
+     <div className="w-full max-w-sm space-y-6">
+       <div className="space-y-2">
+         <Label htmlFor="framework">Framework</Label>
+         <Select value={value} onValueChange={setValue}>
+           <SelectTrigger id="framework" className="w-full">
+             <SelectValue placeholder="Seleziona un framework" />
+           </SelectTrigger>
+           <SelectContent>
+             <SelectGroup>
+               <SelectLabel>Frontend</SelectLabel>
+               <SelectItem value="react">React</SelectItem>
+               <SelectItem value="vue">Vue</SelectItem>
+               <SelectItem value="angular">Angular</SelectItem>
+             </SelectGroup>
+             <SelectSeparator />
+             <SelectGroup>
+               <SelectLabel>Backend</SelectLabel>
+               <SelectItem value="node">Node.js</SelectItem>
+               <SelectItem value="django">Django</SelectItem>
+             </SelectGroup>
+           </SelectContent>
+         </Select>
+       </div>
+     </div>
+   );
+ }
+ ```
+ 
+ ### Sizes
+ 
+ ```tsx
+ import {
+   Select,
+   SelectTrigger,
+   SelectValue,
+   SelectContent,
+   SelectItem,
+ } from "laif-ds";
+ 
+ export function SelectSizes() {
+   return (
+     <div className="flex flex-col space-y-4">
+       <Select>
+         <SelectTrigger size="sm" className="w-[180px]">
+           <SelectValue placeholder="Small" />
+         </SelectTrigger>
+         <SelectContent>
+           <SelectItem value="1">Opzione 1</SelectItem>
+           <SelectItem value="2">Opzione 2</SelectItem>
+         </SelectContent>
+       </Select>
+ 
+       <Select>
+         <SelectTrigger className="w-[180px]">
+           <SelectValue placeholder="Default" />
+         </SelectTrigger>
+         <SelectContent>
+           <SelectItem value="1">Opzione 1</SelectItem>
+           <SelectItem value="2">Opzione 2</SelectItem>
+         </SelectContent>
+       </Select>
+     </div>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Use AppSelect**: Prefer `AppSelect` for production features (search, multiselect, async, etc.).
+ - **A11y**: Keep labels synchronized with triggers using `id` and `htmlFor`.
+ 

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

@@ -0,0 +1,32 @@
+# Separator
+
+## Overview
+
+Visual divider component. Built on Radix Separator.
+
+---
+
+## Props
+
+Extends `@radix-ui/react-separator` Root props.
+
+- `orientation`: `"horizontal" | "vertical"` (default: `"horizontal"`)
+- `decorative`: `boolean` (default: `true`)
+
+---
+
+## Example
+
+```tsx
+import { Separator } from "laif-ds";
+
+export function Example() {
+  return (
+    <div className="space-y-4">
+      <div>Section A</div>
+      <Separator />
+      <div>Section B</div>
+    </div>
+  );
+}
+```

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

@@ -0,0 +1,40 @@
+# Sheet
+
+## Overview
+
+Side sheet/dialog component with overlay, animated content, header/footer and close button. Built on Radix Dialog.
+
+---
+
+## Exports
+
+- `Sheet`, `SheetTrigger`, `SheetClose`, `SheetContent`
+- `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`
+
+`SheetContent` prop `side` supports: `"top" | "right" | "bottom" | "left"` (default: `"right"`).
+
+---
+
+## Example
+
+```tsx
+import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription } from "laif-ds";
+import { Button } from "laif-ds";
+
+export function FiltersSheet() {
+  return (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button variant="outline">Open filters</Button>
+      </SheetTrigger>
+      <SheetContent side="right">
+        <SheetHeader>
+          <SheetTitle>Filters</SheetTitle>
+          <SheetDescription>Select filters and apply</SheetDescription>
+        </SheetHeader>
+        {/* content */}
+      </SheetContent>
+    </Sheet>
+  );
+}
+```

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

@@ -0,0 +1,31 @@
+# ShikiHighlighter
+
+## Overview
+
+Client-side code highlighter using Shiki tokens. Falls back to plain `<pre><code>` when loading fails or language unsupported.
+
+---
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `string` | Code string to highlight |
+| `language` | `string` | Language key supported by Shiki |
+| `className` | `string` | Optional classes for `<pre>` |
+
+---
+
+## Example
+
+```tsx
+import ShikiHighlighter from "laif-ds/ShikiHighlighter";
+
+export function CodeBlock() {
+  return (
+    <ShikiHighlighter language="ts" className="rounded-md border p-3 text-sm">
+      {`const x: number = 42;`}
+    </ShikiHighlighter>
+  );
+}
+```

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

@@ -0,0 +1,85 @@
+ # Sidebar (Primitives)
+ 
+ ## Overview
+ 
+ Low-level primitives to build responsive sidebars with desktop/offcanvas modes, collapsible icon mode, floating/inset variants, groups, menus, badges, actions and a keyboard shortcut (⌘/Ctrl + B) to toggle.
+ 
+ ---
+ 
+ ## Main Components
+ 
+ - **SidebarProvider**: Context provider. Props: `defaultOpen?`, `open?`, `onOpenChange?`.
+ - **Sidebar**: Shell. Props: `side="left|right"`, `variant="sidebar|floating|inset"`, `collapsible="offcanvas|icon|none"`.
+ - **SidebarTrigger**: Button to toggle (uses provider).
+ - **SidebarRail**: Thin draggable/toggle rail.
+ - **SidebarInset**: Main content wrapper that adapts to inset variant.
+ - **SidebarHeader / SidebarFooter**: Top/bottom containers.
+ - **SidebarContent**: Scrollable body.
+ - **SidebarGroup / SidebarGroupLabel / SidebarGroupAction / SidebarGroupContent**: Labeled groups with optional action.
+ - **SidebarMenu / SidebarMenuItem / SidebarMenuButton / SidebarMenuAction / SidebarMenuBadge**: Menu building blocks.
+ - **SidebarMenuSub / SidebarMenuSubItem / SidebarMenuSubButton**: Nested menus.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Mobile**: Offcanvas via `Sheet` when on mobile; desktop uses fixed panel.
+ - **Collapsible**: `icon` mode shows only icons and tooltips; `offcanvas` moves panel off-screen.
+ - **Keyboard**: Toggle with ⌘/Ctrl + B.
+ - **Tooltips**: Menu buttons show tooltips only when collapsed on desktop.
+ 
+ ---
+ 
+ ## Example
+ 
+ ```tsx
+ import {
+   SidebarProvider, Sidebar, SidebarHeader, SidebarContent, SidebarFooter,
+   SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarMenuBadge,
+   SidebarGroup, SidebarGroupLabel, SidebarGroupContent, SidebarTrigger
+ } from "laif-ds";
+ 
+ export function Shell() {
+   return (
+     <SidebarProvider>
+       <div className="flex h-[100vh] overflow-hidden">
+         <Sidebar>
+           <SidebarHeader>Header</SidebarHeader>
+           <SidebarContent>
+             <SidebarMenu>
+               <SidebarMenuItem>
+                 <SidebarMenuButton isActive>
+                   <span>Dashboard</span>
+                 </SidebarMenuButton>
+                 <SidebarMenuBadge>3</SidebarMenuBadge>
+               </SidebarMenuItem>
+             </SidebarMenu>
+             <SidebarGroup>
+               <SidebarGroupLabel>Section</SidebarGroupLabel>
+               <SidebarGroupContent>
+                 <SidebarMenu>
+                   <SidebarMenuItem>
+                     <SidebarMenuButton>Item</SidebarMenuButton>
+                   </SidebarMenuItem>
+                 </SidebarMenu>
+               </SidebarGroupContent>
+             </SidebarGroup>
+           </SidebarContent>
+           <SidebarFooter>Footer</SidebarFooter>
+         </Sidebar>
+         <div className="flex-1 overflow-auto p-4">
+           <SidebarTrigger />
+         </div>
+       </div>
+     </SidebarProvider>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Icons**: Use `laif-ds` `Icon` component inside buttons.
+ - **A11y**: Focus management, ARIA attributes and tooltips included in primitives.
+ 

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

@@ -0,0 +1,29 @@
+# Skeleton
+
+## Overview
+
+Animated placeholder for loading states.
+
+---
+
+## Props
+
+Extends `<div>` props.
+
+---
+
+## Example
+
+```tsx
+import { Skeleton } from "laif-ds";
+
+export function CardSkeleton() {
+  return (
+    <div className="space-y-2">
+      <Skeleton className="h-6 w-1/3" />
+      <Skeleton className="h-4 w-2/3" />
+      <Skeleton className="h-4 w-1/2" />
+    </div>
+  );
+}
+```

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

@@ -0,0 +1,58 @@
+ # Slider
+ 
+ ## Overview
+ 
+ Radix-based slider with DS styling, optional value labels, sticky labels on thumbs, predefined step snapping, and center-offset fill.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop              | Type                                               | Default     | Description |
+ | ----------------- | -------------------------------------------------- | ----------- | ----------- |
+ | `value`           | `number[]`                                         | `undefined` | Controlled value (single `[n]` or range `[a,b]`). |
+ | `defaultValue`    | `number[]`                                         | `undefined` | Uncontrolled initial value. |
+ | `min`             | `number`                                           | `0`         | Minimum. |
+ | `max`             | `number`                                           | `100`       | Maximum. |
+ | `step`            | `number`                                           | `1`         | Increment. |
+ | `size`            | `"base" | "medium" | "large"`                 | `"base"`   | Track/thumb sizing. |
+ | `formatValue`     | `(value: number) => string`                        | `undefined` | Formatter for labels. |
+ | `showValues`      | `boolean`                                          | `false`     | Show min/current (and max for single-value). |
+ | `showStickyLabel` | `boolean`                                          | `false`     | Show a `Badge` over the thumb with current value. |
+ | `stickyLabelSuffix`| `string`                                          | `""`       | Suffix for sticky label. |
+ | `fillOffset`      | `boolean`                                          | `false`     | Fill track from center/`offsetValue` to current value. |
+ | `offsetValue`     | `number`                                           | `undefined` | Center reference for `fillOffset`. |
+ | `steps`           | `number[]`                                         | `undefined` | Predefined snapping steps. |
+ | `showStepMarkers` | `boolean`                                          | `false`     | Visual markers for `steps`. |
+ 
+ Inherits other Radix `Slider` props.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ```tsx
+ import * as React from "react";
+ import { Slider } from "laif-ds";
+ 
+ export function Controlled() {
+   const [value, setValue] = React.useState([25]);
+   return <Slider value={value} onValueChange={setValue} size="medium" />;
+ }
+ 
+ export function WithSteps() {
+   const [val, setVal] = React.useState([50]);
+   return (
+     <Slider value={val} onValueChange={setVal} steps={[0,25,50,75,100]} showStepMarkers />
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Snapping**: When `steps` provided, values snap to nearest step.
+ - **Range**: Provide two values like `[min, max]` to enable a range slider.
+ - **Theming**: Uses DS tokens for track, range and thumb states.
+ 

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

@@ -0,0 +1,21 @@
+# Sonner
+
+## Overview
+
+Theme-aware wrapper around `sonner` Toaster that syncs with `next-themes`.
+
+---
+
+## Usage
+
+```tsx
+import { Toaster } from "laif-ds/sonner"; // Ensure correct import path in your setup
+
+export function App() {
+  return <Toaster richColors closeButton />;
+}
+```
+
+Notes:
+- Sets CSS variables for popover colors to match the design system
+- `theme` derives from `useTheme()` (system, light, dark)

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

@@ -0,0 +1,139 @@
+# Spinner
+
+## Overview
+
+Animated loading spinner component with multiple size and color variants. Provides a rotating circular indicator for loading states.
+
+---
+
+## Props
+
+| Prop       | Type                                                      | Default     | Description                                  |
+| ---------- | --------------------------------------------------------- | ----------- | -------------------------------------------- |
+| `size`     | `"xxs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxl" \| number` | `"md"`      | Size of the spinner (preset or custom px)    |
+| `variant`  | `"default" \| "destructive" \| "primary" \| "secondary"`  | `"default"` | Color variant of the spinner                 |
+| `className`| `string`                                                  | `""`        | Additional Tailwind classes                  |
+
+---
+
+## Size Mapping
+
+| Size    | Pixels |
+| ------- | ------ |
+| `xxs`   | 12px   |
+| `xs`    | 14px   |
+| `sm`    | 16px   |
+| `md`    | 20px   |
+| `lg`    | 24px   |
+| `xl`    | 28px   |
+| `xxl`   | 36px   |
+
+You can also provide a custom number for precise pixel sizing.
+
+---
+
+## Variants
+
+- **`default`**: Uses foreground color (`text-d-foreground`)
+- **`destructive`**: Uses destructive color (`text-d-destructive`)
+- **`primary`**: Uses primary color (`text-d-primary`)
+- **`secondary`**: Uses secondary color (`text-d-secondary`)
+
+---
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { Spinner } from "laif-ds";
+
+export function BasicSpinner() {
+  return <Spinner />;
+}
+```
+
+### Size Variants
+
+```tsx
+import { Spinner } from "laif-ds";
+
+export function SpinnerSizes() {
+  return (
+    <div className="flex items-center gap-4">
+      <Spinner size="xxs" />
+      <Spinner size="xs" />
+      <Spinner size="sm" />
+      <Spinner size="md" />
+      <Spinner size="lg" />
+      <Spinner size="xl" />
+      <Spinner size="xxl" />
+    </div>
+  );
+}
+```
+
+### Color Variants
+
+```tsx
+import { Spinner } from "laif-ds";
+
+export function SpinnerColors() {
+  return (
+    <div className="flex items-center gap-4">
+      <Spinner variant="default" />
+      <Spinner variant="primary" />
+      <Spinner variant="secondary" />
+      <Spinner variant="destructive" />
+    </div>
+  );
+}
+```
+
+### Custom Size
+
+```tsx
+import { Spinner } from "laif-ds";
+
+export function CustomSizeSpinner() {
+  return <Spinner size={48} />;
+}
+```
+
+### In Button
+
+```tsx
+import { Spinner, Button } from "laif-ds";
+
+export function ButtonWithSpinner() {
+  return (
+    <Button disabled>
+      <Spinner size="sm" className="mr-2" />
+      Loading...
+    </Button>
+  );
+}
+```
+
+### Centered Loading
+
+```tsx
+import { Spinner } from "laif-ds";
+
+export function CenteredSpinner() {
+  return (
+    <div className="flex h-screen items-center justify-center">
+      <Spinner size="xl" variant="primary" />
+    </div>
+  );
+}
+```
+
+---
+
+## Notes
+
+- **Animation**: Uses Tailwind's `animate-spin` utility for smooth rotation
+- **SVG Based**: Rendered as an SVG element for crisp display at any size
+- **Current Color**: Inherits text color from parent if no variant specified
+- **Accessibility**: Consider adding `aria-label` or visually hidden text for screen readers

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

@@ -0,0 +1,67 @@
+ # Stepper (Primitives)
+ 
+ ## Overview
+ 
+ Accessible stepper primitives to build multi-step flows with keyboard navigation, indicators, separators and panels. Supports horizontal and vertical layouts.
+ 
+ ---
+ 
+ ## Subcomponents & Props
+ 
+ - **Stepper**: Root context.
+   - `defaultValue?: number` (default `1`)
+   - `value?: number`, `onValueChange?: (n:number)=>void`
+   - `orientation?: "horizontal" | "vertical"` (default `"horizontal"`)
+   - `indicators?: { active?, completed?, inactive?, loading? }`
+ - **StepperItem**: Defines a step. Props: `step` (number), `completed?`, `disabled?`, `loading?`, `orientation?`.
+ - **StepperTrigger**: Click/keyboard target to activate step. Props: `size?: "sm"|"default"|"lg"`.
+ - **StepperIndicator**: Circular indicator; accepts `size`.
+ - **StepperTitle / StepperDescription**: Labels; accept `size`.
+ - **StepperSeparator**: Visual separator between steps; respects orientation.
+ - **StepperNav**: Wraps triggers; accepts `orientation?`.
+ - **StepperPanel**: Container for contents.
+ - **StepperContent**: Conditional render area for a given `value` (step id). `forceMount?` keeps DOM mounted.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Keyboard**: Arrow keys navigate between triggers; Home/End jump to first/last; Enter/Space selects.
+ - **Controlled/Uncontrolled**: Use `value/onValueChange` or `defaultValue`.
+ - **Indicators**: Provide custom nodes for states via `indicators`.
+ 
+ ---
+ 
+ ## Example
+ 
+ ```tsx
+ import { Stepper, StepperNav, StepperItem, StepperTrigger, StepperIndicator, StepperTitle, StepperSeparator, StepperPanel, StepperContent } from "laif-ds";
+ 
+ export function BasicStepper() {
+   const [step, setStep] = React.useState(1);
+   return (
+     <Stepper value={step} onValueChange={setStep}>
+       <div className="flex w-full flex-col">
+         <StepperNav>
+           <StepperItem step={1}><StepperTrigger><StepperIndicator>1</StepperIndicator><StepperTitle>Account</StepperTitle></StepperTrigger><StepperSeparator/></StepperItem>
+           <StepperItem step={2}><StepperTrigger><StepperIndicator>2</StepperIndicator><StepperTitle>Profile</StepperTitle></StepperTrigger><StepperSeparator/></StepperItem>
+           <StepperItem step={3}><StepperTrigger><StepperIndicator>3</StepperIndicator><StepperTitle>Done</StepperTitle></StepperTrigger></StepperItem>
+         </StepperNav>
+         <StepperPanel className="mt-6">
+           <StepperContent value={1}>Step 1</StepperContent>
+           <StepperContent value={2}>Step 2</StepperContent>
+           <StepperContent value={3}>Step 3</StepperContent>
+         </StepperPanel>
+       </div>
+     </Stepper>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Focus**: Triggers manage focus order for accessible navigation.
+ - **Layouts**: Use `orientation="vertical"` to show left rail of steps with content on the right.
+ 

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

@@ -0,0 +1,42 @@
+ # Switch
+ 
+ ## Overview
+ 
+ Accessible on/off toggle built on Radix Switch with DS tokens and smooth thumb slide.
+ 
+ ---
+ 
+ ## Props
+ 
+ Inherits Radix Switch props:
+ 
+ - `checked?`, `defaultChecked?`
+ - `onCheckedChange?(checked: boolean)`
+ - `disabled?`, `required?`, `name?`, `value?`
+ 
+ ---
+ 
+ ## Example
+ 
+ ```tsx
+ import * as React from "react";
+ import { Switch } from "laif-ds";
+ 
+ export function ControlledSwitch() {
+   const [checked, setChecked] = React.useState(false);
+   return (
+     <div className="flex items-center gap-2">
+       <Switch id="wifi" checked={checked} onCheckedChange={setChecked} />
+       <label htmlFor="wifi">Wi‑Fi {checked ? "on" : "off"}</label>
+     </div>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - Track uses `bg-d-primary` when checked and `bg-d-foreground/20` when unchecked.
+ - Thumb translation is optimized for a 32px track with 16px thumb.
+