laif-ds 0.2.44 → 0.2.45

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

@@ -0,0 +1,87 @@
+ # AspectRatio
+ 
+ ## Overview
+ 
+ A container that maintains a consistent aspect ratio for its content. Useful for images, videos, and any media that requires a fixed ratio.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### AspectRatio (Root)
+ 
+ | Prop        | Type                | Default     | Description                                     |
+ | ----------- | ------------------- | ----------- | ----------------------------------------------- |
+ | `ratio`     | `number`            | `undefined` | Aspect ratio expressed as a number (e.g., 16/9).|
+ | `className` | `string`            | `""`        | Additional classes applied to the container.     |
+ | `children`  | `React.ReactNode`   | **required**| Content inside the ratio-constrained container.  |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Responsive**: The container scales while preserving the specified ratio.
+ - **Content fill**: Child content should handle its own layout (e.g., `object-cover`).
+ - **Styling**: Apply width/height and styling via `className`.
+ 
+ ---
+ 
+ ## Examples
+ 
+### 16:9 Ratio
+ 
+```tsx
+import { AspectRatio } from "laif-ds";
+ 
+export function Ratio16x9() {
+  return (
+    <AspectRatio ratio={16 / 9} className="bg-d-secondary/10 w-[400px] rounded-md overflow-hidden">
+      <div className="flex h-full items-center justify-center">
+        <p className="text-sm text-d-secondary-foreground">16:9 Aspect Ratio</p>
+      </div>
+    </AspectRatio>
+  );
+}
+```
+ 
+### Square (1:1)
+ 
+```tsx
+import { AspectRatio } from "laif-ds";
+ 
+export function Square() {
+  return (
+    <AspectRatio ratio={1 / 1} className="bg-d-secondary/10 w-[400px] rounded-md overflow-hidden">
+      <div className="flex h-full items-center justify-center">
+        <p className="text-sm text-d-secondary-foreground">1:1 Aspect Ratio</p>
+      </div>
+    </AspectRatio>
+  );
+}
+```
+ 
+### With Image
+ 
+```tsx
+import { AspectRatio } from "laif-ds";
+ 
+ export function ImageRatio() {
+   return (
+     <AspectRatio ratio={16 / 9} className="w-[400px] rounded-md overflow-hidden">
+       <img
+         src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80"
+         alt="Image"
+         className="h-full w-full object-cover"
+       />
+     </AspectRatio>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Children**: Place any content inside; use `object-cover` for images to avoid distortion.
+ - **Width**: Control width via `className`; height is computed from the ratio.
+ 

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

@@ -0,0 +1,127 @@
+ # AsyncSelect
+ 
+ ## Overview
+ 
+ Generic async select with search input, popover list, optional preload and multiple selection. Fully render-prop driven for option content and value extraction.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop              | Type                                         | Default     | Description |
+ | ----------------- | -------------------------------------------- | ----------- | ----------- |
+ | `fetcher`         | `(query?: string) => Promise<T[]>`           | **required**| Async loader for options. Called on open and on search. |
+ | `preload`         | `boolean`                                    | `false`     | Preload all data once; then client-filter using `filterFn`. |
+ | `filterFn`        | `(option: T, query: string) => boolean`      | `undefined` | Custom client-side filter when `preload=true`. |
+ | `renderOption`    | `(option: T) => React.ReactNode`             | **required**| How to render each option row. |
+ | `getOptionValue`  | `(option: T) => string`                      | **required**| Extract option id. |
+ | `getDisplayValue` | `(option: T) => React.ReactNode`             | **required**| Display value for trigger. |
+ | `multiple`        | `boolean`                                    | `false`     | Enable multi-selection. Controls `value` type. |
+ | `value`           | `string | string[]`                          | `undefined` | Controlled value. |
+ | `onChange`        | `(value: string | string[]) => void`         | `undefined` | Change callback. |
+ | `label`           | `string | React.ReactNode`                   | `undefined` | Optional label above. |
+ | `labelClassName`  | `string`                                     | `undefined` | Label classes. |
+ | `placeholder`     | `string`                                     | `"Select..."` | Placeholder when empty. |
+ | `disabled`        | `boolean`                                    | `false`     | Disable trigger and input. |
+ | `width`           | `string | number | "auto"`                  | `200px`     | Popover width; `auto` matches trigger width. |
+ | `triggerClassName`| `string`                                     | `undefined` | Extra classes for trigger button. |
+ | `noResultsMessage`| `string`                                     | `undefined` | Message when list is empty. |
+ | `clearable`       | `boolean`                                    | `true`      | Show clear icon when a value is set. |
+ | `size`            | `"sm" | "default" | "lg"`                 | `"default"` | Trigger size. |
+ | `loadingSkeleton` | `React.ReactNode`                            | `undefined` | Custom loading skeleton list. |
+ | `notFound`        | `React.ReactNode`                            | `undefined` | Custom empty content. |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Search**: Debounced input (0ms when `preload=true`, 300ms otherwise).
+ - **Caching**: Results cached by query; reused when re-typing.
+ - **Multiple**: Renders selected count or first label; supports checkbox UI per item.
+ - **Clear**: Built-in clear icon (uses DS `Icon`), respects `clearable`.
+ - **A11y**: Trigger focus ring and keyboard navigation via `cmdk`.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Preloaded
+ 
+ ```tsx
+ import * as React from "react";
+ import { AsyncSelect } from "laif-ds";
+ 
+ type User = { id: number; name: string; email: string };
+ 
+ async function fetchUsers(query?: string): Promise<User[]> {
+   const res = await fetch("https://jsonplaceholder.typicode.com/users");
+   const data: User[] = await res.json();
+   if (!query) return data;
+   const q = query.toLowerCase();
+   return data.filter((u) => u.name.toLowerCase().includes(q));
+ }
+ 
+ export function PreloadedUsers() {
+   const [value, setValue] = React.useState("");
+   return (
+     <AsyncSelect<User>
+       preload
+       fetcher={fetchUsers}
+       value={value}
+       onChange={setValue}
+       renderOption={(u) => (
+         <div className="truncate">
+           <div className="font-medium">{u.name}</div>
+           <div className="text-d-muted-foreground text-xs">{u.email}</div>
+         </div>
+       )}
+       getOptionValue={(u) => String(u.id)}
+       getDisplayValue={(u) => u.name}
+       placeholder="Select a user..."
+       width="300px"
+     />
+   );
+ }
+ ```
+ 
+ ### Multiple with Steps
+ 
+ ```tsx
+ import * as React from "react";
+ import { AsyncSelect } from "laif-ds";
+ 
+ type Tag = { id: string; label: string };
+ const tags: Tag[] = [
+   { id: "react", label: "React" },
+   { id: "nextjs", label: "Next.js" },
+   { id: "tailwind", label: "Tailwind" },
+ ];
+ 
+ export function MultipleTags() {
+   const [value, setValue] = React.useState<string[]>([]);
+   const fetcher = async (q?: string) =>
+     !q ? tags : tags.filter((t) => t.label.toLowerCase().includes(q!.toLowerCase()));
+   return (
+     <AsyncSelect<Tag>
+       multiple
+       fetcher={fetcher}
+       value={value}
+       onChange={setValue}
+       renderOption={(t) => t.label}
+       getOptionValue={(t) => t.id}
+       getDisplayValue={(t) => t.label}
+       placeholder="Select tags..."
+       width="auto"
+     />
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Trigger width**: Use `width="auto"` to match trigger width; or a fixed `number|string`.
+ - **Filtering**: For big datasets prefer server search (no `preload`); for small datasets prefer `preload` + `filterFn`.
+ - **Theming**: Uses DS token classes across trigger, list, and states.
+ 

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

@@ -0,0 +1,41 @@
+# AudioVisualizer
+
+## Overview
+
+Canvas-based audio waveform visualizer for a MediaStream. Starts/stops with `isRecording` and resizes responsively.
+
+---
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `stream` | `MediaStream | null` | Input audio stream |
+| `isRecording` | `boolean` | Whether to render visualization |
+| `onClick` | `() => void` | Click handler (e.g., to toggle state) |
+
+---
+
+## Example
+
+```tsx
+import { useEffect, useState } from "react";
+import { AudioVisualizer } from "laif-ds";
+
+export function MicVisualizer() {
+  const [stream, setStream] = useState<MediaStream | null>(null);
+  const [isRecording, setIsRecording] = useState(false);
+
+  useEffect(() => {
+    navigator.mediaDevices.getUserMedia({ audio: true }).then(setStream);
+  }, []);
+
+  return (
+    <AudioVisualizer
+      stream={stream}
+      isRecording={isRecording}
+      onClick={() => setIsRecording((v) => !v)}
+    />
+  );
+}
+```

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

@@ -0,0 +1,113 @@
+ # Avatar
+ 
+ ## Overview
+ 
+ Circular user/avatar component with image and fallback. Accessible and easily styled.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### Avatar (Root)
+ 
+ | Prop        | Type              | Default     | Description                                      |
+ | ----------- | ----------------- | ----------- | ------------------------------------------------ |
+ | `className` | `string`          | `""`        | Additional classes for size/border/layout.        |
+ | `children`  | `React.ReactNode` | **required**| Typically `AvatarImage` and `AvatarFallback`.     |
+ 
+ ### Subcomponents
+ 
+ - `AvatarImage`: The image element.
+   - Props: `src`, `alt`, `className`.
+ - `AvatarFallback`: Fallback content shown when the image fails or loads slowly.
+   - Props: `children` (e.g., initials), `className`.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Shape**: Circular by default (`rounded-full`).
+ - **Sizing**: Control via `className` (e.g., `h-16 w-16`).
+ - **Fallback**: Displays initials or an icon when the image is unavailable.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### With Image
+ 
+ ```tsx
+ import { Avatar, AvatarImage, AvatarFallback } from "laif-ds";
+ 
+ export function WithImage() {
+   return (
+     <Avatar>
+       <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+       <AvatarFallback>CN</AvatarFallback>
+     </Avatar>
+   );
+ }
+ ```
+ 
+ ### With Fallback
+ 
+ ```tsx
+ import { Avatar, AvatarImage, AvatarFallback } from "laif-ds";
+ 
+ export function WithFallback() {
+   return (
+     <Avatar>
+       <AvatarImage src="" alt="User" />
+       <AvatarFallback>JD</AvatarFallback>
+     </Avatar>
+   );
+ }
+ ```
+ 
+ ### Custom Size
+ 
+ ```tsx
+ import { Avatar, AvatarImage, AvatarFallback } from "laif-ds";
+ 
+ export function CustomSize() {
+   return (
+     <Avatar className="h-16 w-16">
+       <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+       <AvatarFallback>CN</AvatarFallback>
+     </Avatar>
+   );
+ }
+ ```
+ 
+ ### Avatar Group
+ 
+ ```tsx
+ import { Avatar, AvatarImage, AvatarFallback } from "laif-ds";
+ 
+ export function AvatarGroup() {
+   return (
+     <div className="flex -space-x-2">
+       <Avatar className="border-background border-2">
+         <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+         <AvatarFallback>CN</AvatarFallback>
+       </Avatar>
+       <Avatar className="border-background border-2">
+         <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+         <AvatarFallback>JD</AvatarFallback>
+       </Avatar>
+       <Avatar className="border-background border-2">
+         <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+         <AvatarFallback>MK</AvatarFallback>
+       </Avatar>
+     </div>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Accessibility**: Provide `alt` text for `AvatarImage`.
+ - **Styling**: Combine with borders/shadows via `className`.
+ 

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

@@ -0,0 +1,118 @@
+ # Badge
+ 
+ ## Overview
+ 
+ Small, inline label for status and metadata. Supports many visual variants, optional icons, link mode, and disabled state.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### Badge (Root)
+ 
+ | Prop         | Type                                                                                                                                                                                                                      | Default      | Description                                 |
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------- |
+ | `variant`    | `"default" \| "destructive" \| "warning" \| "success" \| "outline" \| "outline-primary" \| "outline-destructive" \| "outline-warning" \| "outline-success" \| "secondary" \| "ghost" \| "ghost-destructive" \| "ghost-accent" \| "ghost-warning" \| "ghost-success" \| "link"` | `"default"` | Visual style of the badge.                  |
+ | `asChild`    | `boolean`                                                                                                                                                                                                                 | `false`      | Renders the badge as its child element.     |
+ | `disabled`   | `boolean`                                                                                                                                                                                                                 | `false`      | Disables interactions and dims the badge.   |
+ | `iconLeft`   | `IconName`                                                                                                                                                                                                                | `undefined`  | Optional left icon (uses `Icon` component). |
+ | `iconRight`  | `IconName`                                                                                                                                                                                                                | `undefined`  | Optional right icon (uses `Icon` component).|
+ | `className`  | `string`                                                                                                                                                                                                                  | `""`         | Additional classes on the root element.      |
+ | `children`   | `React.ReactNode`                                                                                                                                                                                                         | **required** | Text or content inside the badge.           |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Variants**: Outline, ghost, and semantic variants available for flexible UIs.
+ - **As child**: Use `asChild` to render as an anchor or any custom element.
+ - **Icons**: `iconLeft`/`iconRight` render `Icon` with appropriate sizes.
+ - **Disabled**: Applies `cursor-not-allowed` and reduces opacity.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Default
+ 
+ ```tsx
+ import { Badge } from "laif-ds";
+ 
+ export function DefaultBadge() {
+   return <Badge>Badge</Badge>;
+ }
+ ```
+ 
+ ### Variants Grid
+ 
+ ```tsx
+ import { Badge, type BadgeProps } from "laif-ds";
+ 
+ const variants: BadgeProps["variant"][] = [
+   "default",
+   "destructive",
+   "warning",
+   "success",
+   "outline",
+   "outline-primary",
+   "outline-destructive",
+   "outline-warning",
+   "outline-success",
+   "secondary",
+   "ghost",
+   "ghost-accent",
+   "ghost-destructive",
+   "ghost-warning",
+   "ghost-success",
+   "link",
+ ];
+ 
+ export function VariantsShowcase() {
+   return (
+     <div className="flex flex-wrap gap-2">
+       {variants.map((v) => (
+         <Badge key={v} variant={v}>
+           {v}
+         </Badge>
+       ))}
+     </div>
+   );
+ }
+ ```
+ 
+ ### With Icons
+ 
+ ```tsx
+ import { Badge } from "laif-ds";
+ 
+ export function WithIcons() {
+   return (
+     <div className="flex gap-2">
+       <Badge iconLeft="Check" iconRight="X">Approved</Badge>
+       <Badge variant="outline-primary" iconLeft="Pencil">Edit</Badge>
+     </div>
+   );
+ }
+ ```
+ 
+ ### As Link (asChild)
+ 
+ ```tsx
+ import { Badge } from "laif-ds";
+ 
+ export function LinkBadge() {
+   return (
+     <Badge asChild>
+       <a href="#" className="cursor-pointer">Clickable Badge</a>
+     </Badge>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Icons**: Use `IconName` values supported by the design system.
+ - **AsChild**: Useful to keep semantics (e.g., anchors) while styling as badges.
+ 

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

@@ -0,0 +1,78 @@
+# Breadcrumb
+
+## Overview
+
+Composable breadcrumb navigation components. Includes list, items, links, separators, current page, and ellipsis. Lightweight wrappers around semantic HTML with sensible styles.
+
+---
+
+## Subcomponents
+
+- `Breadcrumb`
+- `BreadcrumbList`
+- `BreadcrumbItem`
+- `BreadcrumbLink` (supports `asChild`)
+- `BreadcrumbPage`
+- `BreadcrumbSeparator` (defaults to chevron icon)
+- `BreadcrumbEllipsis` (three-dot ellipsis)
+
+All subcomponents extend their respective native element props.
+
+---
+
+## Examples
+
+### Basic
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "laif-ds";
+
+export function BasicBreadcrumb() {
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/">Home</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>Components</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}
+```
+
+### Custom Separator
+
+```tsx
+import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbSeparator, BreadcrumbPage } from "laif-ds";
+
+export function CustomSeparator() {
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/">Home</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator>/</BreadcrumbSeparator>
+        <BreadcrumbItem>
+          <BreadcrumbPage>Current</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}
+```

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

@@ -0,0 +1,129 @@
+ # Button
+ 
+ ## Overview
+ 
+ Versatile button with multiple variants and sizes, optional leading/trailing icons, loading state, and support for rendering as a child element.
+ 
+ ---
+ 
+ ## Props
+ 
+ ### Button (Root)
+ 
+ | Prop         | Type                                                                                                                                             | Default       | Description                                              |
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | -------------------------------------------------------- |
+ | `variant`    | `"default" | "destructive" | "outline" | "outline-primary" | "outline-destructive" | "secondary" | "ghost" | "ghost-destructive" | "ghost-accent" | "link"` | `"default"`  | Visual style of the button.                              |
+ | `size`       | `"default" | "sm" | "lg" | "icon"`                                                                                                             | `"default"`  | Size of the button.                                      |
+ | `asChild`    | `boolean`                                                                                                                                         | `false`       | Render as child (e.g., anchor) while preserving styles. |
+ | `iconLeft`   | `IconName`                                                                                                                                        | `undefined`   | Optional left icon name.                                 |
+ | `iconRight`  | `IconName`                                                                                                                                        | `undefined`   | Optional right icon name.                                |
+ | `isLoading`  | `boolean`                                                                                                                                         | `false`       | Shows a loading spinner; overrides `iconLeft`.          |
+ | `className`  | `string`                                                                                                                                          | `""`          | Additional classes for layout/width.                     |
+ | `disabled`   | `boolean`                                                                                                                                         | `false`       | Disables the button.                                     |
+ | `onClick`    | `(e: React.MouseEvent<HTMLButtonElement>) => void`                                                                                                | `undefined`   | Click handler.                                            |
+ | `children`   | `React.ReactNode`                                                                                                                                 | **required**  | Button label or content.                                 |
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Loading**: When `isLoading` is `true`, a spinner is shown and `iconLeft` is hidden.
+ - **Icons**: Icon sizes adapt to the button size (`sm`, `default`, `lg`, `icon`).
+ - **As Child**: Use `asChild` to render the button as a link or custom element while keeping button styles.
+ - **Accessibility**: Keyboard-focus ring and proper semantics are included.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Default
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ 
+ export function DefaultButton() {
+   return <Button>Button</Button>;
+ }
+ ```
+ 
+ ### Showcase (Variants × Sizes)
+ 
+ ```tsx
+ import { Button, type ButtonProps } from "laif-ds";
+ 
+ const variants: ButtonProps["variant"][] = [
+   "default",
+   "destructive",
+   "outline",
+   "outline-primary",
+   "outline-destructive",
+   "secondary",
+   "ghost",
+   "ghost-accent",
+   "ghost-destructive",
+   "link",
+ ];
+ 
+ const sizes: ButtonProps["size"][] = ["lg", "default", "sm", "icon"];
+ 
+ export function ButtonsGrid() {
+   return (
+     <div className="flex flex-col gap-4">
+       {variants.map((variant) => (
+         <div key={variant} className="flex items-center gap-2 flex-wrap">
+           {sizes.map((size) => (
+             size === "icon" ? (
+               <Button key={`${variant}-${size}`} variant={variant} size={size} iconLeft="BadgeInfo" />
+             ) : (
+               <Button key={`${variant}-${size}`} variant={variant} size={size}>
+                 {variant} - {size}
+               </Button>
+             )
+           ))}
+         </div>
+       ))}
+     </div>
+   );
+ }
+ ```
+ 
+ ### Full Width
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ 
+ export function FullWidthButton() {
+   return (
+     <Button className="w-full">Full Width Button</Button>
+   );
+ }
+ ```
+ 
+ ### With Icon
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ 
+ export function WithIcon() {
+   return <Button iconLeft="Check">Button with Icon</Button>;
+ }
+ ```
+ 
+ ### Loading
+ 
+ ```tsx
+ import { Button } from "laif-ds";
+ 
+ export function LoadingButton() {
+   return <Button isLoading>Loading Button</Button>;
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Disabled**: Applies reduced opacity and prevents interactions.
+ - **Icon-only**: Use `size="icon"` for square icon buttons.
+ - **Theming**: Use variants to match semantic meaning (primary, destructive, etc.).
+