laif-ds 0.2.44 → 0.2.45

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

@@ -0,0 +1,125 @@
+ # Dialog
+ 
+ ## Overview
+ 
+ Accessible modal dialog built on Radix. Includes overlay, content with size variants, header/footer layout, title/description, trigger and close controls.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### Dialog (Root)
+ 
+ | Prop           | Type                | Default     | Description                              |
+ | -------------- | ------------------- | ----------- | ---------------------------------------- |
+ | `open`         | `boolean`           | `undefined` | Controlled open state.                    |
+ | `defaultOpen`  | `boolean`           | `false`     | Uncontrolled initial open state.          |
+ | `onOpenChange` | `(open: boolean) => void` | `undefined` | Called when open state changes.      |
+ | `modal`        | `boolean`           | `true`      | Modal behavior (trap focus, background).  |
+ 
+ ### DialogContent
+ 
+ Additional prop:
+ 
+ | Prop     | Type                          | Default     | Description                           |
+ | -------- | ----------------------------- | ----------- | ------------------------------------- |
+ | `size`   | `"sm" | "default" | "lg" | "xl"` | `"default"` | Max-width preset for the content.     |
+ | `className` | `string`                    | `""`        | Additional classes for the panel.     |
+ 
+ ### Subcomponents
+ 
+ - `DialogTrigger`: Element that opens the dialog (supports `asChild`).
+ - `DialogPortal` / `DialogOverlay`: Portal root and backdrop.
+ - `DialogContent`: Centered panel with animations and close button.
+ - `DialogHeader` / `DialogFooter`: Layout helpers for content.
+ - `DialogTitle` / `DialogDescription`: Accessible title and description.
+ - `DialogClose`: Close button (already included inside `DialogContent`).
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Focus management**: Traps focus while open; returns on close.
+ - **Pointer outside exception**: Clicks inside elements marked `data-command-portal` are ignored to prevent unintended close.
+ - **Sizes**: `size` controls the max-width (`sm`, `default`, `lg`, `xl`).
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Basic
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ import {
+   Dialog,
+   DialogTrigger,
+   DialogContent,
+   DialogHeader,
+   DialogTitle,
+   DialogDescription,
+   DialogFooter,
+ } from "laif-ds";
+ 
+ export function BasicDialog() {
+   return (
+     <Dialog>
+       <DialogTrigger asChild>
+         <Button variant="outline">Open Dialog</Button>
+       </DialogTrigger>
+       <DialogContent>
+         <DialogHeader>
+           <DialogTitle>Basic Dialog</DialogTitle>
+           <DialogDescription>
+             This is a basic dialog with title and description.
+           </DialogDescription>
+         </DialogHeader>
+         <div className="py-4">
+           <p className="text-d-secondary-foreground text-sm">
+             Dialog content goes here.
+           </p>
+         </div>
+         <DialogFooter>
+           <Button type="submit">Save changes</Button>
+         </DialogFooter>
+       </DialogContent>
+     </Dialog>
+   );
+ }
+ ```
+ 
+ ### Size Variants
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle } from "laif-ds";
+ 
+ export function SizeVariants() {
+   return (
+     <div className="flex flex-wrap gap-3">
+       {["sm", "default", "lg", "xl"].map((sz) => (
+         <Dialog key={sz as string}>
+           <DialogTrigger asChild>
+             <Button variant="outline">Open {String(sz)}</Button>
+           </DialogTrigger>
+           <DialogContent size={sz as any}>
+             <DialogHeader>
+               <DialogTitle>Size: {String(sz)}</DialogTitle>
+             </DialogHeader>
+             <div className="text-sm">Content for {String(sz)}</div>
+           </DialogContent>
+         </Dialog>
+       ))}
+     </div>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Accessibility**: Use `DialogTitle` and `DialogDescription` for screen readers.
+ - **Styling**: Customize panel via `className` on `DialogContent`.
+ - **Closing**: A close button is rendered in the top-right of `DialogContent`.
+ 

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

@@ -0,0 +1,127 @@
+ # Drawer
+ 
+ ## Overview
+ 
+ Sliding panel component (top/right/bottom/left) built on Vaul. Supports modal behavior, background scaling, snap points, and full keyboard accessibility.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### Drawer (Root)
+ 
+ | Prop                 | Type                                  | Default     | Description                                                        |
+ | -------------------- | ------------------------------------- | ----------- | ------------------------------------------------------------------ |
+ | `open`               | `boolean`                              | `undefined` | Controlled open state.                                             |
+ | `onOpenChange`       | `(open: boolean) => void`              | `undefined` | Called when open state changes.                                    |
+ | `direction`          | `"top" | "right" | "bottom" | "left"` | `"bottom"`  | Drawer opening direction.                                          |
+ | `modal`              | `boolean`                              | `true`      | Modal behavior (trap focus, block background interaction).         |
+ | `shouldScaleBackground` | `boolean`                           | `true`      | Scales the background when the drawer is open.                     |
+ | `snapPoints`         | `number[]`                             | `[]`        | Optional snap points (fractions of viewport: e.g., `0.4`, `0.6`).  |
+ | `activeSnapPoint`    | `number | string`                      | `undefined` | The active snap point index/value.                                  |
+ | `closeThreshold`     | `number`                               | `undefined` | Threshold to trigger close on drag.                                 |
+ 
+ ### Subcomponents
+ 
+ - `DrawerTrigger`: Element that opens the drawer (supports `asChild`).
+ - `DrawerPortal` / `DrawerOverlay`: Portal root and backdrop.
+ - `DrawerContent`: Panel container; includes a grab handle in bottom direction.
+ - `DrawerHeader` / `DrawerFooter`: Layout helpers for content.
+ - `DrawerTitle` / `DrawerDescription`: Header title and description.
+ - `DrawerClose`: Close button helper to wrap an element.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Directions**: Open from any side via `direction` prop.
+ - **Snap points**: Provide a list of fractional heights; control active point via `activeSnapPoint`.
+ - **Modal**: When `modal` is true, interaction outside is blocked and overlay is shown.
+ - **Accessibility**: Focus trapping and keyboard navigation handled by the underlying library.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Interactive Drawer
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ import {
+   Drawer,
+   DrawerTrigger,
+   DrawerContent,
+   DrawerHeader,
+   DrawerTitle,
+   DrawerDescription,
+   DrawerFooter,
+   DrawerClose,
+ } from "laif-ds";
+ import { Input } from "laif-ds";
+ 
+ export function InteractiveDrawer() {
+   return (
+     <Drawer direction="bottom" modal shouldScaleBackground>
+       <DrawerTrigger asChild>
+         <Button variant="outline">Apri Drawer</Button>
+       </DrawerTrigger>
+       <DrawerContent>
+         <DrawerHeader>
+           <DrawerTitle>Drawer di Esempio</DrawerTitle>
+           <DrawerDescription>
+             Personalizza contenuti e comportamento tramite le props.
+           </DrawerDescription>
+         </DrawerHeader>
+         <div className="space-y-4 p-4">
+           <Input label="Nome" placeholder="Inserisci il tuo nome" />
+           <Input label="Email" type="email" placeholder="Inserisci la tua email" />
+         </div>
+         <DrawerFooter>
+           <Button>Salva modifiche</Button>
+           <DrawerClose asChild>
+             <Button variant="outline">Annulla</Button>
+           </DrawerClose>
+         </DrawerFooter>
+       </DrawerContent>
+     </Drawer>
+   );
+ }
+ ```
+ 
+ ### With Snap Points
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter, DrawerClose } from "laif-ds";
+ 
+ export function DrawerWithSnapPoints() {
+   const snapPoints = [0.4, 0.6, 0.9];
+   return (
+     <Drawer snapPoints={snapPoints} activeSnapPoint={0}>
+       <DrawerTrigger asChild>
+         <Button variant="outline">Drawer con Snap Points</Button>
+       </DrawerTrigger>
+       <DrawerContent>
+         <DrawerHeader>
+           <DrawerTitle>Drawer con Snap Points</DrawerTitle>
+           <DrawerDescription>Snap a 40%, 60% e 90% dell'altezza.</DrawerDescription>
+         </DrawerHeader>
+         <DrawerFooter>
+           <DrawerClose asChild>
+             <Button variant="outline">Chiudi</Button>
+           </DrawerClose>
+         </DrawerFooter>
+       </DrawerContent>
+     </Drawer>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Handle**: A grab handle is visible for bottom direction.
+ - **Layout**: Use `DrawerHeader`/`DrawerFooter` and your own content in between.
+ - **Styling**: Customize via `className` on `DrawerContent`.
+ 

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

@@ -0,0 +1,57 @@
+# DropdownMenu
+
+## Overview
+
+Contextual menu built on Radix Dropdown Menu with support for submenus, checkboxes, radio items, labels, separators, and shortcuts.
+
+---
+
+## Exports
+
+- `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`
+- `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioItem`
+- `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`
+- `DropdownMenuGroup`, `DropdownMenuPortal`
+- `DropdownMenuSub`, `DropdownMenuSubContent`, `DropdownMenuSubTrigger`
+- `DropdownMenuRadioGroup`
+
+All components extend Radix props.
+
+---
+
+## Example
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+} from "laif-ds";
+import { Button } from "laif-ds";
+
+export function UserMenu() {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline">Open</Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent sideOffset={4}>
+        <DropdownMenuItem>Profile</DropdownMenuItem>
+        <DropdownMenuItem>Settings</DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>More</DropdownMenuSubTrigger>
+          <DropdownMenuSubContent>
+            <DropdownMenuItem>Theme</DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+```

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

@@ -0,0 +1,99 @@
+ # FilePreview
+ 
+ ## Overview
+ 
+ Compact file chip with name, format/size info, optional remove button, and optional action menu (preview/download/remove). Automatically adapts its preview based on file type (image, text, generic).
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop             | Type                                                                 | Default       | Description                                                |
+ | ---------------- | -------------------------------------------------------------------- | ------------- | ---------------------------------------------------------- |
+ | `file`           | `File \| { name: string; url: string; type?: string }`               | **required**  | File object or remote descriptor with `url`.               |
+ | `onRemove`       | `(url: string) => void`                                              | `undefined`   | Called when user removes the file.                         |
+ | `onPreview`      | `(url: string) => void`                                              | `undefined`   | Called when user clicks Preview from the action menu.      |
+ | `onDownload`     | `(url: string) => void`                                              | `undefined`   | Called when user clicks Download from the action menu.     |
+ | `showActionMenu` | `boolean`                                                            | `false`       | Show overflow menu (Preview/Download/Delete if provided).  |
+ | `className`      | `string`                                                             | `""`         | Additional classes for the wrapper.                         |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Automatic preview**: 
+   - Images: thumbnail preview.
+   - Text: small snippet (first 100 chars).
+   - Generic: file-type icon and labels.
+ - **Format & size**: Displays file size (if available) and format label (e.g., PDF, JPG).
+ - **Actions**: 
+   - Inline remove button if `onRemove` is provided and `showActionMenu` is false.
+   - Popover action menu when `showActionMenu` is true, using `onPreview`, `onDownload`, `onRemove`.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Image
+ 
+ ```tsx
+ import { FilePreview } from "laif-ds";
+ 
+ export function ImagePreview() {
+   return (
+     <FilePreview
+       file={{ name: "photo.jpg", url: "https://picsum.photos/id/237/200/200", type: "image/jpeg" }}
+       onPreview={(url) => console.log("preview", url)}
+       onDownload={(url) => console.log("download", url)}
+     />
+   );
+ }
+ ```
+ 
+ ### With Remove Button
+ 
+ ```tsx
+ import { FilePreview } from "laif-ds";
+ 
+ export function RemovablePreview() {
+   return (
+     <FilePreview
+       file={{
+         name: "document.docx",
+         url: "https://example.com/document.docx",
+         type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+       }}
+       onRemove={(url) => console.log("remove", url)}
+       onPreview={(url) => console.log("preview", url)}
+       onDownload={(url) => console.log("download", url)}
+     />
+   );
+ }
+ ```
+ 
+ ### With Action Menu
+ 
+ ```tsx
+ import { FilePreview } from "laif-ds";
+ 
+ export function WithMenu() {
+   return (
+     <FilePreview
+       file={{ name: "presentation.ppt", url: "https://example.com/presentation.ppt", type: "application/vnd.ms-powerpoint" }}
+       showActionMenu
+       onPreview={(url) => console.log("preview", url)}
+       onDownload={(url) => console.log("download", url)}
+       onRemove={(url) => console.log("remove", url)}
+     />
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Thumbnails**: Image previews use object-fit to contain within the chip.
+ - **Security**: For local `File` previews, temporary object URLs are created; cleanup is handled by the browser GC.
+ - **Internationalization**: Text labels in the action menu can be adjusted at call sites when needed.
+ 

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

@@ -0,0 +1,139 @@
+ # FilePreviewer
+ 
+ ## Overview
+ 
+ Modal file preview component with support for images, PDFs (including secure read-only mode), audio, video, text, and Office documents (via online viewers). Use helper functions to open the modal from anywhere; mount the component once.
+ 
+ ---
+ 
+ ## API
+ 
+ ### Functions
+ 
+ | Function                | Signature                                                     | Description                                               |
+ | ----------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
+ | `previewFileModal`      | `(arg: string | PreviewOptions) => Promise<void>`             | Opens the preview modal. Resolves when closed.            |
+ | `safePreviewFileModal`  | `(arg: string | PreviewOptions) => Promise<void | undefined>` | Safe variant that never throws on close.                   |
+ 
+ ```ts
+ export type PreviewOptions = {
+   url?: string;
+   filename?: string;
+   mimeType?: string;
+   title?: React.ReactNode;
+   readOnly?: boolean; // Enables SecurePdfViewer for PDFs
+   page?: number;      // Initial page for PDFs (1-based)
+ };
+ ```
+ 
+ ### Component
+ 
+ - `FilePreviewer`: Mount once near the app root. Controls the dialog UI and renders the appropriate preview body.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Kind detection**: Determines preview type from `mimeType`, `filename` or `url`.
+ - **Image**: Responsive `<img>` with contain fit.
+ - **PDF**: 
+   - `readOnly=true` uses `SecurePdfViewer` with `page` support.
+   - Otherwise embedded via `<iframe>` (supports `#page=` parameter).
+ - **Audio/Video**: Native `<audio>`/`<video>` players.
+ - **Text**: Rendered in an `<iframe>` for remote text URLs.
+ - **Office**: Uses an online viewer when `url` is HTTP(S); otherwise shows a fallback notice.
+ - **Dialog**: Uses `Dialog` with `size="xl"` and a heading showing `title` or `filename` with a file icon.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Preview an Image (URL)
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ import { FilePreviewer, previewFileModal } from "laif-ds";
+ 
+ export function PreviewImageButton() {
+   return (
+     <>
+       <Button
+         onClick={() =>
+           previewFileModal({
+             url: "https://picsum.photos/id/1003/1200/800",
+             filename: "image.jpg",
+             title: "Random Image",
+           })
+         }
+       >
+         Preview Image
+       </Button>
+       <FilePreviewer />
+     </>
+   );
+ }
+ ```
+ 
+ ### PDF with Read-only Secure Viewer
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ import { FilePreviewer, previewFileModal } from "laif-ds";
+ 
+ export function PreviewPdf() {
+   return (
+     <>
+       <Button
+         onClick={() =>
+           previewFileModal({
+             url: "https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf",
+             filename: "dummy.pdf",
+             title: "PDF Document",
+             readOnly: true,
+             page: 1,
+           })
+         }
+       >
+         Preview PDF
+       </Button>
+       <FilePreviewer />
+     </>
+   );
+ }
+ ```
+ 
+ ### Office Document (XLSX)
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ import { FilePreviewer, previewFileModal } from "laif-ds";
+ 
+ export function PreviewSpreadsheet() {
+   return (
+     <>
+       <Button
+         onClick={() =>
+           previewFileModal({
+             url: "https://filesamples.com/samples/document/xlsx/sample3.xlsx",
+             filename: "spreadsheet.xlsx",
+             title: "Excel Spreadsheet",
+             readOnly: true,
+           })
+         }
+       >
+         Preview XLSX
+       </Button>
+       <FilePreviewer />
+     </>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Mount**: Add a single `<FilePreviewer />` near app root or in Storybook decorators.
+ - **Filenames**: If `filename` is omitted, it is inferred from `url`.
+ - **Security**: For local files, prefer read-only mode for PDFs when appropriate.
+ 

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

@@ -0,0 +1,129 @@
+ # FileUploader
+ 
+ ## Overview
+ 
+ Drag-and-drop uploader with keyboard activation, file type filtering, limits (count/total size), previews via `FilePreview`, and external upload integration.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop               | Type                                    | Default                                                   | Description                                                |
+ | ------------------ | --------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------- |
+ | `extensions`       | `AcceptItem[]`                          | `["pdf","image","video","audio"]`                    | Allowed extensions/categories (maps to accept attribute).  |
+ | `multiple`         | `boolean`                               | `false`                                                   | Enables multiple file selection.                           |
+ | `onUpload`         | `(files: File[]) => void`               | `undefined`                                               | Called whenever selected files change.                     |
+ | `description`      | `string`                                | `"Trascina un file o clicca per selezionare"`            | Dropzone hint.                                             |
+ | `formatDescription`| `string`                                | `"Formato accettato: PDF, Immagini, Video, Audio"`       | Accepted formats hint.                                     |
+ | `selectedLabel`    | `string`                                | `"File selezionati"`                                     | Title shown above selected files list.                     |
+ | `removeAllLabel`   | `string`                                | `"rimuovi tutto"`                                        | Label for the "remove all" button.                        |
+ | `maxTotalSize`     | `number` (bytes)                        | `undefined`                                               | Maximum total size of selected files.                      |
+ | `maxFiles`         | `number`                                | `undefined`                                               | Maximum number of files (when `multiple` is true).         |
+ 
+ `AcceptItem` includes: `pdf | doc | docx | xls | xlsx | ppt | pptx | txt | csv | jpg | jpeg | png | gif | image | video | audio`.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Dropzone**: Click or drag files; keyboard accessible (Enter/Space opens file dialog).
+ - **Filtering**: `extensions` map to accept string; only matching files are added.
+ - **Limits**: Enforces `maxFiles` and `maxTotalSize` (with compact error caption).
+ - **Previews**: Renders selected files with `FilePreview`; supports remove per file and remove-all.
+ - **Integration**: `onUpload` provides the current `File[]`; perform the actual upload externally.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Default
+ 
+ ```tsx
+ import { FileUploader } from "laif-ds";
+ 
+ export function DefaultUploader() {
+   return <FileUploader multiple={false} />;
+ }
+ ```
+ 
+ ### Multiple + Custom Extensions
+ 
+ ```tsx
+ import { FileUploader, type AcceptItem } from "laif-ds";
+ 
+ const exts: AcceptItem[] = [
+   "pdf","doc","docx","xls","xlsx","ppt","pptx","txt","csv","jpg","jpeg","png","gif","image","video","audio",
+ ];
+ 
+ export function MultiUploader() {
+   return (
+     <FileUploader
+       multiple
+       extensions={exts}
+       description="Seleziona più file"
+       formatDescription="Trascina o clicca per selezionare più file"
+     />
+   );
+ }
+ ```
+ 
+ ### With Limits
+ 
+ ```tsx
+ import { FileUploader } from "laif-ds";
+ 
+ export function LimitedUploader() {
+   return (
+     <FileUploader
+       multiple
+       maxFiles={3}
+       maxTotalSize={10 * 1024 * 1024} // 10 MB
+       description="Con limiti su numero e dimensione totale"
+       formatDescription="Esempio: max 3 file, max totale 10 MB"
+     />
+   );
+ }
+ ```
+ 
+ ### External Upload Flow
+ 
+ ```tsx
+ import * as React from "react";
+ import { Button } from "laif-ds";
+ import { FileUploader } from "laif-ds";
+ 
+ export function ExternalUploadExample() {
+   const [files, setFiles] = React.useState<File[]>([]);
+   const [loading, setLoading] = React.useState(false);
+ 
+   const handleSubmit = async () => {
+     setLoading(true);
+     // ...upload files
+     await new Promise((r) => setTimeout(r, 1500));
+     setLoading(false);
+     alert(`Upload completato: ${files.length} file`);
+   };
+ 
+   return (
+     <div className="space-y-4">
+       <FileUploader multiple onUpload={setFiles} />
+       {files.length > 0 && (
+         <div className="flex justify-end">
+           <Button onClick={handleSubmit} isLoading={loading} iconLeft="Upload">
+             {loading ? "Caricamento..." : `Carica ${files.length} file`}
+           </Button>
+         </div>
+       )}
+     </div>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **A11y**: Dropzone is a button-like region with `aria-describedby` hints and keyboard support.
+ - **Errors**: Limit violations are summarized in a compact caption.
+ - **Localization**: Provide localized `description`/`formatDescription`/labels when needed.
+