laif-ds 0.2.43 → 0.2.45

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

@@ -0,0 +1,427 @@
+# AppSelect
+
+## Overview
+
+A flexible select component supporting both single and multiple selection modes with advanced features including search, grouping, custom labels (JSX), clear actions, chips display, and optional item creation. Built on top of Command and Popover components.
+
+---
+
+## Types
+
+### AppSelectOption
+
+```ts
+export interface AppSelectOption {
+  value: string | number; // Unique identifier for the option
+  label: string | React.ReactNode; // Display label (can be JSX for custom rendering)
+  disabled?: boolean; // Disables selection of this option
+  group?: string; // Group name for grouping options
+  fixed?: boolean; // In chip mode, prevents removal of this option
+}
+```
+
+---
+
+## Props
+
+The component uses discriminated union types based on the `multiple` prop.
+
+### Base Props (Common to both modes)
+
+| Prop                 | Type                           | Default                                          | Description                                   |
+| -------------------- | ------------------------------ | ------------------------------------------------ | --------------------------------------------- |
+| `options`            | `AppSelectOption[]`            | **required**                                     | Array of selectable options                   |
+| `placeholder`        | `string`                       | `"Seleziona..."`                                 | Text shown in trigger when no selection       |
+| `searchPlaceholder`  | `string`                       | `"Cerca..."`                                     | Placeholder for search input                  |
+| `emptyPlaceholder`   | `string`                       | `"Nessun risultato"`                             | Text shown when no options match search       |
+| `addItemPlaceholder` | `string`                       | `"Aggiungi"`                                     | Text prefix for creating new items            |
+| `itemCountMessage`   | `(selected: number) => string` | `(n) => "${n} elementi selezionati"`             | Message function for selected count display   |
+| `maxSelectedMessage` | `(max: number) => string`      | `(m) => "Puoi selezionare fino a ${m} elementi"` | Message shown when max selection reached      |
+| `label`              | `string \| React.ReactNode`    | `undefined`                                      | Label displayed above the select              |
+| `className`          | `string`                       | `""`                                             | Additional Tailwind classes for the trigger   |
+| `wrpClassName`       | `string`                       | `""`                                             | Additional Tailwind classes for the wrapper   |
+| `searchable`         | `boolean`                      | `false`                                          | Enables search/filter functionality           |
+| `creatable`          | `boolean`                      | `false`                                          | Allows creating new options from search input |
+| `disabled`           | `boolean`                      | `false`                                          | Disables the entire select component          |
+| `groupBy`            | `keyof AppSelectOption`        | `"group"`                                        | Property key used to group options            |
+| `size`               | `"sm" \| "default" \| "lg"`    | `"default"`                                      | Size variant affecting height and text size   |
+| `onClear`            | `() => void`                   | `undefined`                                      | Callback fired when clear button is clicked   |
+
+### Single Select Props
+
+```ts
+export type SingleSelectProps = BaseProps & {
+  multiple?: false; // Single selection mode (default)
+  value?: string | number; // Controlled value
+  defaultValue?: string | number; // Uncontrolled default value
+  onValueChange?: (value: string | number | undefined) => void; // Value change callback
+  isSingleSelectClearable?: boolean; // Shows clear button (default: false)
+};
+```
+
+### Multi Select Props
+
+```ts
+export type MultiSelectProps = BaseProps & {
+  multiple: true; // Multiple selection mode
+  value?: (string | number)[]; // Controlled values array
+  defaultValue?: (string | number)[]; // Uncontrolled default values
+  onValueChange?: (value: (string | number)[]) => void; // Value change callback
+  maxSelected?: number; // Maximum number of selectable items
+  showChipsInsteadOfCount?: boolean; // Display chips instead of count (default: false)
+};
+```
+
+### Combined Type
+
+```ts
+export type AppSelectProps = SingleSelectProps | MultiSelectProps;
+```
+
+---
+
+## Prop Details
+
+### Size Variants
+
+The `size` prop controls the trigger height and text size:
+
+- **`sm`**: `min-h-8 h-8 text-xs py-1.5`
+- **`default`**: `min-h-9 h-9 text-sm py-2`
+- **`lg`**: `min-h-10 h-10 text-base py-2`
+
+### Custom Labels (JSX Support)
+
+The `label` property in `AppSelectOption` supports both strings and React nodes, allowing for rich custom rendering with icons, badges, or any JSX content. When using JSX labels, the component properly handles them without wrapping issues (React 19 compatible).
+
+### Controlled vs Uncontrolled
+
+- **Controlled**: Component is controlled when the `value` prop is provided (checked via `props.hasOwnProperty('value')`)
+- **Uncontrolled**: Uses internal state when only `defaultValue` is provided
+- The component remains in its initial mode throughout its lifecycle
+
+---
+
+## Behavior
+
+### Selection Modes
+
+#### Single Select
+
+- Clicking an option selects it and closes the popover
+- Only one option can be selected at a time
+- Clear button appears when `isSingleSelectClearable={true}` and a value is selected
+- Clearing sets value to `undefined`
+
+#### Multiple Select
+
+- Clicking an option toggles its selection state
+- Popover remains open for multiple selections
+- Selected count or chips displayed in trigger
+- Clear button always visible when selections exist
+- Clearing sets value to empty array `[]`
+
+### Search Functionality
+
+When `searchable={true}`:
+
+- Search input appears at the top of the popover
+- Options are filtered client-side based on label text
+- Search is case-insensitive
+- Empty state shows `emptyPlaceholder` when no matches
+
+### Creatable Options
+
+When `creatable={true}`:
+
+- Requires `searchable={true}` to work
+- Shows "Aggiungi '[input]'" option when search text doesn't match existing options
+- Selecting the create option adds the input text as a new value
+- In single mode, closes popover after creation
+- In multiple mode, keeps popover open for more selections
+
+### Grouping
+
+When options have a `group` property:
+
+- Options are automatically grouped under headings
+- Groups are rendered in the order they appear in the options array
+- Use `groupBy` prop to specify which property to group by (default: `"group"`)
+- Options without a group value appear in an unnamed group
+
+### Max Selection Limit
+
+In multiple mode with `maxSelected` set:
+
+- Prevents selecting more than the specified number of items
+- Unselected options become disabled when limit is reached
+- Footer message appears showing the limit via `maxSelectedMessage`
+- Selected items can still be deselected
+
+### Chips Display
+
+In multiple mode with `showChipsInsteadOfCount={true}`:
+
+- Shows individual badge chips for each selected item
+- Each chip has an X button to remove the item
+- Options with `fixed={true}` show chips without X button (cannot be removed)
+- Chips are scrollable horizontally if they overflow
+
+### Disabled Options
+
+Options with `disabled={true}`:
+
+- Appear grayed out with reduced opacity
+- Cannot be selected or deselected
+- Cursor changes to `not-allowed`
+
+### Disabled Component
+
+When `disabled={true}`:
+
+- Entire component is non-interactive
+- Trigger shows reduced opacity
+- Popover cannot be opened
+- Cursor changes to `not-allowed`
+
+---
+
+## Examples
+
+### Basic Single Select
+
+```tsx
+import { AppSelect } from "laif-ds";
+import { useState } from "react";
+
+const options = [
+  { value: "react", label: "React" },
+  { value: "vue", label: "Vue" },
+  { value: "angular", label: "Angular" },
+];
+
+export function BasicSelect() {
+  const [value, setValue] = useState<string | number | undefined>();
+
+  return (
+    <AppSelect
+      options={options}
+      value={value}
+      onValueChange={setValue}
+      placeholder="Select a framework"
+      label="Framework"
+    />
+  );
+}
+```
+
+### Multiple Select with Search and Chips
+
+```tsx
+import { AppSelect } from "laif-ds";
+import { useState } from "react";
+
+const options = [
+  { value: 1, label: "React" },
+  { value: 2, label: "Vue" },
+  { value: 3, label: "Angular" },
+  { value: 4, label: "Svelte" },
+];
+
+export function MultiSelectWithChips() {
+  const [values, setValues] = useState<(string | number)[]>([]);
+
+  return (
+    <AppSelect
+      multiple
+      options={options}
+      value={values}
+      onValueChange={setValues}
+      placeholder="Select frameworks"
+      label="Frameworks"
+      searchable
+      showChipsInsteadOfCount
+    />
+  );
+}
+```
+
+### Grouped Options with Max Selection
+
+```tsx
+import { AppSelect } from "laif-ds";
+import { useState } from "react";
+
+const options = [
+  { value: "react", label: "React", group: "Frontend" },
+  { value: "vue", label: "Vue", group: "Frontend" },
+  { value: "node", label: "Node.js", group: "Backend" },
+  { value: "django", label: "Django", group: "Backend" },
+];
+
+export function GroupedSelect() {
+  const [values, setValues] = useState<(string | number)[]>([]);
+
+  return (
+    <AppSelect
+      multiple
+      options={options}
+      value={values}
+      onValueChange={setValues}
+      placeholder="Select up to 2 technologies"
+      label="Tech Stack"
+      groupBy="group"
+      maxSelected={2}
+      searchable
+    />
+  );
+}
+```
+
+### Creatable Select
+
+```tsx
+import { AppSelect } from "laif-ds";
+import { useState } from "react";
+
+const initialOptions = [
+  { value: "tag1", label: "Tag 1" },
+  { value: "tag2", label: "Tag 2" },
+];
+
+export function CreatableSelect() {
+  const [values, setValues] = useState<(string | number)[]>([]);
+
+  return (
+    <AppSelect
+      multiple
+      options={initialOptions}
+      value={values}
+      onValueChange={setValues}
+      placeholder="Create or select tags"
+      label="Tags"
+      searchable
+      creatable
+      showChipsInsteadOfCount
+    />
+  );
+}
+```
+
+### Custom JSX Labels
+
+```tsx
+import { AppSelect } from "laif-ds";
+import { useState } from "react";
+
+const options = [
+  {
+    value: "react",
+    label: (
+      <div className="flex items-center gap-2">
+        <span className="text-blue-600">⚛</span>
+        React
+      </div>
+    ),
+  },
+  {
+    value: "vue",
+    label: (
+      <div className="flex items-center gap-2">
+        <span className="text-green-600">●</span>
+        Vue
+      </div>
+    ),
+  },
+  {
+    value: "angular",
+    label: (
+      <div className="flex items-center gap-2">
+        <span className="text-red-600">▲</span>
+        Angular
+      </div>
+    ),
+  },
+];
+
+export function CustomLabelsSelect() {
+  const [value, setValue] = useState<string | number | undefined>();
+
+  return (
+    <AppSelect
+      options={options}
+      value={value}
+      onValueChange={setValue}
+      placeholder="Select a framework"
+      label="Framework with Icons"
+    />
+  );
+}
+```
+
+### Clearable Single Select
+
+```tsx
+import { AppSelect } from "laif-ds";
+import { useState } from "react";
+
+const options = [
+  { value: 1, label: "Option 1" },
+  { value: 2, label: "Option 2" },
+  { value: 3, label: "Option 3" },
+];
+
+export function ClearableSelect() {
+  const [value, setValue] = useState<string | number | undefined>(1);
+
+  return (
+    <AppSelect
+      options={options}
+      value={value}
+      onValueChange={setValue}
+      placeholder="Select an option"
+      label="Status"
+      isSingleSelectClearable
+      onClear={() => console.log("Cleared!")}
+    />
+  );
+}
+```
+
+### With Disabled Options
+
+```tsx
+import { AppSelect } from "laif-ds";
+import { useState } from "react";
+
+const options = [
+  { value: "it", label: "Italia" },
+  { value: "fr", label: "Francia" },
+  { value: "de", label: "Germania" },
+  { value: "uk", label: "Regno Unito", disabled: true },
+];
+
+export function SelectWithDisabled() {
+  const [value, setValue] = useState<string | number | undefined>();
+
+  return (
+    <AppSelect
+      options={options}
+      value={value}
+      onValueChange={setValue}
+      placeholder="Select a country"
+      label="Country"
+    />
+  );
+}
+```
+
+---
+
+## Notes
+
+- **React 19 Compatible**: Properly handles JSX labels without ref warnings
+- **Responsive Width**: Popover automatically matches trigger width
+- **Keyboard Navigation**: Full keyboard support via Command component
+- **Accessibility**: Proper ARIA attributes and focus management
+- **Performance**: Efficient rendering with useMemo for computed values

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

@@ -0,0 +1,122 @@
+ # AppSidebar
+ 
+ ## Overview
+ 
+ High-level app sidebar built on top of `Sidebar` primitives. Renders navigation groups, nested items, header/footer content, optional versions area and an optional rail for resizing/collapsing.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop               | Type                                 | Default     | Description |
+ | ------------------ | ------------------------------------ | ----------- | ----------- |
+ | `navigation`       | `NavGroup[]`                         | **required**| Main navigation groups. |
+ | `navigationFooter` | `NavGroup[]`                         | `undefined` | Footer navigation groups. |
+ | `versions`         | `string[]`                           | `undefined` | Optional versions list. |
+ | `defaultVersion`   | `string`                             | `undefined` | Default selected version. |
+ | `headerContent`    | `React.ReactNode`                    | `undefined` | Custom content at the top. |
+ | `footerContent`    | `React.ReactNode`                    | `undefined` | Custom content at the bottom. |
+ | `showRail`         | `boolean`                            | `true`      | Show the draggable sidebar rail. |
+ | `linkComponent`    | `React.ComponentType<any>`           | `undefined` | Custom link component for items. |
+ | `linkProps`        | `Record<string, any>`                | `{}`        | Extra props passed to the link component. |
+ 
+ `NavGroup` → `{ title: string; url?: string; items: NavItem[] }`
+ 
+ `NavItem` → `{ title: string; url: string; isActive?: boolean; iconName?: IconName; subItems?: NavSubItem[] }`
+ 
+ `NavSubItem` → `{ title: string; url: string; isActive?: boolean; iconName?: IconName }`
+ 
+ Inherits other props from `Sidebar` via `React.ComponentProps<typeof Sidebar>`.
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Collapsible groups**: Clicking items with `subItems` toggles nested lists.
+ - **Active state**: `isActive` highlights and expands relevant items/groups.
+ - **Links**: Use `linkComponent` for framework routers (e.g., Next.js `Link`).
+ - **Rail**: `showRail` displays a thin draggable handle to collapse/expand.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ### Basic
+ 
+ ```tsx
+ import { SidebarProvider, SidebarTrigger } from "laif-ds";
+ import { AppSidebar } from "laif-ds";
+ 
+ const navigation = [
+   {
+     title: "Generale",
+     items: [
+       { title: "Dashboard", url: "#", isActive: true, iconName: "Home" },
+       { title: "Utenti", url: "#", iconName: "Users" },
+       {
+         title: "Messaggi",
+         url: "#",
+         iconName: "MessageSquare",
+         subItems: [
+           { title: "Inbox", url: "#inbox", iconName: "Inbox" },
+           { title: "Inviati", url: "#sent", iconName: "Send" },
+         ],
+       },
+     ],
+   },
+ ];
+ 
+ export function Layout() {
+   return (
+     <SidebarProvider>
+       <div className="flex h-[100vh] overflow-hidden">
+         <AppSidebar navigation={navigation} showRail />
+         <div className="flex-1 overflow-auto p-4">
+           <SidebarTrigger />
+           {/* Page content */}
+         </div>
+       </div>
+     </SidebarProvider>
+   );
+ }
+ ```
+ 
+ ### With Header/Footer Content
+ 
+ ```tsx
+ import { Button, Input } from "laif-ds";
+ 
+ export function WithHeaderFooter() {
+   return (
+     <SidebarProvider>
+       <div className="flex h-[100vh] overflow-hidden">
+         <AppSidebar
+           navigation={[]}
+           headerContent={
+             <div className="p-4">
+               <Input iconLeft="Search" placeholder="Cerca..." className="bg-d-background pl-8" />
+             </div>
+           }
+           footerContent={
+             <div className="border-d-border border-t p-4">
+               <Button variant="ghost" className="w-full justify-start" iconLeft="Settings">
+                 Impostazioni
+               </Button>
+             </div>
+           }
+         />
+         <div className="flex-1 overflow-auto p-4" />
+       </div>
+     </SidebarProvider>
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Routing**: Prefer `linkComponent` to avoid full page reloads (e.g., `next/link`).
+ - **Icons**: Use `laif-ds` `Icon` by passing `iconName` in navigation items.
+ - **Accessibility**: Sidebar primitives manage keyboard navigation and focus.
+ 

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

@@ -0,0 +1,77 @@
+ # AppStepper
+ 
+ ## Overview
+ 
+ High-level stepper built on `Stepper` primitives. Renders labeled steps with indicators and panels, supports horizontal/vertical layouts, separators, controlled navigation and custom click behavior.
+ 
+ ---
+ 
+ ## Props
+ 
+ | Prop                     | Type                                             | Default       | Description |
+ | ------------------------ | ------------------------------------------------ | ------------- | ----------- |
+ | `steps`                  | `{ id: number; label: ReactNode; component: ReactNode; completed?; disabled?; loading?; }[]` | **required** | Steps to render (id is the step value). |
+ | `align`                  | `"horizontal" | "vertical"`                    | `"horizontal"` | Layout orientation. |
+ | `size`                   | `"sm" | "md"`                                 | `"sm"`        | Indicator/title sizing. |
+ | `showSeparators`         | `boolean`                                        | `true`        | Show separators between steps. |
+ | `value`                  | `number`                                         | first step id | Current step value (controlled). |
+ | `onValueChange`          | `(value: number) => void`                        | `undefined`   | Called when step changes. |
+ | `defaultStep`            | `number`                                         | `undefined`   | Initial step if `value` is not provided. |
+ | `allowStepNavigation`    | `boolean`                                        | `true`        | If `false`, steps are not clickable. |
+ | `allowClickOnlyCompleted`| `boolean`                                        | `false`       | If `true`, only completed steps are clickable. |
+ | `onStepClick`            | `(step, index) => void`                          | `undefined`   | Custom click handler; if provided, handles activation manually. |
+ | `indicators`             | `{ active?; completed?; inactive?; loading? }`   | `undefined`   | Custom indicator content per state. |
+ 
+ Inherits the rest of `StepperProps` (e.g., `orientation` is controlled by `align`).
+ 
+ ---
+ 
+ ## Behavior
+ 
+ - **Controlled**: Always passes a `value` to `Stepper`. Update via `onValueChange`.
+ - **Clickable steps**: Governed by `allowStepNavigation` and `allowClickOnlyCompleted`.
+ - **Indicators**: Customize the indicator content through `indicators`.
+ 
+ ---
+ 
+ ## Examples
+ 
+ ```tsx
+ import * as React from "react";
+ import { AppStepper } from "laif-ds";
+ 
+ const steps = [
+   { id: 1, label: "Account Setup", component: <div>Step 1</div> },
+   { id: 2, label: "Profile Information", component: <div>Step 2</div> },
+   { id: 3, label: "Preferences", component: <div>Step 3</div> },
+ ] as const;
+ 
+ export function HorizontalStepper() {
+   const [current, setCurrent] = React.useState(1);
+   return (
+     <AppStepper
+       steps={steps}
+       value={current}
+       onValueChange={setCurrent}
+       align="horizontal"
+       size="md"
+       showSeparators
+     />
+   );
+ }
+ 
+ export function VerticalStepper() {
+   const [current, setCurrent] = React.useState(1);
+   return (
+     <AppStepper steps={steps} value={current} onValueChange={setCurrent} align="vertical" />
+   );
+ }
+ ```
+ 
+ ---
+ 
+ ## Notes
+ 
+ - **Accessibility**: Based on `Stepper` primitives which manage keyboard and focus.
+ - **Custom click logic**: Provide `onStepClick` to intercept clicks (e.g., validation before navigation).
+