laif-ds 0.2.43 → 0.2.45

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

@@ -0,0 +1,242 @@
+# AppForm
+
+## Overview
+
+Dynamic form component that integrates with React Hook Form to provide a configurable form with multiple field types including input, textarea, select, multiselect, datepicker, radio, checkbox, switch, and slider. Automatically handles validation errors and form state.
+
+---
+
+## Types
+
+### AppFormItem
+
+```ts
+interface AppFormItem {
+  label: string; // Field label
+  component:
+    | "input"
+    | "select"
+    | "textarea"
+    | "checkbox"
+    | "multiselect"
+    | "datepicker"
+    | "radio"
+    | "switch"
+    | "slider"; // Field type
+  name: string; // Field name (used for form state and validation)
+  defaultValue?: string | boolean | number | string[] | Date | number[]; // Initial value
+  options?: AppSelectOption[]; // Options for select/multiselect/radio
+  disabled?: boolean; // Disables the field
+  placeholder?: string; // Placeholder text
+  caption?: string; // Helper text below the field
+  calendarRange?: [Date, Date]; // Date range for datepicker
+  min?: number; // Minimum value for slider
+  max?: number; // Maximum value for slider
+  step?: number; // Step value for slider
+}
+```
+
+---
+
+## Props
+
+| Prop            | Type                       | Default   | Description                              |
+| --------------- | -------------------------- | --------- | ---------------------------------------- |
+| `items`         | `AppFormItem[]`            | **required** | Array of form field configurations    |
+| `form`          | `UseFormReturn<any>`       | **required** | React Hook Form instance              |
+| `cols`          | `"1" \| "2" \| "3"`        | `"2"`     | Number of grid columns                   |
+| `submitText`    | `string`                   | `"Invia"` | Text for submit button                   |
+| `onSubmit`      | `(data: any) => void`      | `undefined` | Form submission callback               |
+| `isSubmitting`  | `boolean`                  | `false`   | Shows loading state on submit button     |
+
+---
+
+## Behavior
+
+- **React Hook Form Integration**: Uses `Controller` from React Hook Form for each field
+- **Validation Display**: Shows validation errors inline with each field
+- **Grid Layout**: Automatically arranges fields in a responsive grid based on `cols` prop
+- **Submit Button**: Automatically disabled when form is invalid or pristine
+- **Last Field Spanning**: The last field automatically spans full width
+- **Error Highlighting**: Fields with errors get red border styling
+
+---
+
+## Field Types
+
+### input
+Standard text input field
+
+### textarea
+Multi-line text area
+
+### select
+Single selection dropdown using AppSelect
+
+### multiselect
+Multiple selection dropdown using AppSelect with `multiple` prop
+
+### datepicker
+Date picker component with optional range selection via `calendarRange`
+
+### radio
+Radio button group with options
+
+### checkbox
+Single checkbox with label
+
+### switch
+Toggle switch with label and optional caption
+
+### slider
+Range slider with min/max/step configuration
+
+---
+
+## Examples
+
+### Basic Form
+
+```tsx
+import { AppForm } from "laif-ds";
+import { useForm } from "react-hook-form";
+
+export function BasicForm() {
+  const form = useForm();
+
+  return (
+    <AppForm
+      form={form}
+      items={[
+        {
+          label: "Name",
+          component: "input",
+          name: "name",
+          placeholder: "Enter your name",
+        },
+        {
+          label: "Email",
+          component: "input",
+          name: "email",
+          placeholder: "Enter your email",
+        },
+        {
+          label: "Message",
+          component: "textarea",
+          name: "message",
+          placeholder: "Enter your message",
+        },
+      ]}
+      onSubmit={(data) => console.log(data)}
+    />
+  );
+}
+```
+
+### Full Feature Form
+
+```tsx
+import { AppForm } from "laif-ds";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+
+const schema = z.object({
+  name: z.string().min(1, "Name is required"),
+  category: z.string(),
+  isActive: z.boolean(),
+  priority: z.number(),
+});
+
+export function FullFeatureForm() {
+  const form = useForm({
+    resolver: zodResolver(schema),
+    defaultValues: {
+      name: "",
+      category: "",
+      isActive: false,
+      priority: 5,
+    },
+  });
+
+  return (
+    <AppForm
+      form={form}
+      cols="2"
+      items={[
+        {
+          label: "Name",
+          component: "input",
+          name: "name",
+          placeholder: "Enter name",
+        },
+        {
+          label: "Category",
+          component: "select",
+          name: "category",
+          options: [
+            { value: "tech", label: "Technology" },
+            { value: "design", label: "Design" },
+            { value: "marketing", label: "Marketing" },
+          ],
+        },
+        {
+          label: "Active",
+          component: "switch",
+          name: "isActive",
+          caption: "Enable this option",
+        },
+        {
+          label: "Priority",
+          component: "slider",
+          name: "priority",
+          min: 1,
+          max: 10,
+          step: 1,
+        },
+      ]}
+      submitText="Save"
+      onSubmit={(data) => console.log(data)}
+    />
+  );
+}
+```
+
+### With Date Range
+
+```tsx
+import { AppForm } from "laif-ds";
+import { useForm } from "react-hook-form";
+
+export function DateRangeForm() {
+  const form = useForm();
+  const startDate = new Date();
+  const endDate = new Date();
+  endDate.setMonth(endDate.getMonth() + 1);
+
+  return (
+    <AppForm
+      form={form}
+      items={[
+        {
+          label: "Date Range",
+          component: "datepicker",
+          name: "dateRange",
+          calendarRange: [startDate, endDate],
+        },
+      ]}
+      onSubmit={(data) => console.log(data)}
+    />
+  );
+}
+```
+
+---
+
+## Notes
+
+- **React Hook Form Required**: This component requires React Hook Form to be installed and configured
+- **Validation**: Use React Hook Form's resolver (e.g., Zod, Yup) for validation
+- **Grid Layout**: The grid uses Tailwind's grid system with `grid-cols-{n}` classes
+- **Submit Button**: Always appears at the end of the form on the right
+- **Error Display**: Errors appear inline above each field and as border highlighting

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

@@ -0,0 +1,38 @@
+# AppMultipleSelectDropdown
+
+> Deprecated: Use AppSelect instead.
+
+## Overview
+
+Legacy multi-select dropdown component. This component is deprecated in favor of `AppSelect` which provides better accessibility, features, and API consistency.
+
+---
+
+## Replacement
+
+Use `AppSelect` with `multiple` and an array of values.
+
+```tsx
+import { AppSelect } from "laif-ds";
+
+export function Replacement() {
+  return (
+    <AppSelect
+      multiple
+      options={[
+        { value: "a", label: "Option A" },
+        { value: "b", label: "Option B" },
+      ]}
+      value={["a"]}
+      onValueChange={(v) => console.log(v)}
+    />
+  );
+}
+```
+
+---
+
+## Notes
+
+- The old component supported search and maxSelectedItems, but `AppSelect` now provides these features with a more robust API and better UX.
+- Plan migration to `AppSelect` and remove this component from new code.

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

@@ -0,0 +1,223 @@
+# AppRadioGroup
+
+## Overview
+
+Enhanced radio group component with support for icons, descriptions, card layout, horizontal/vertical orientation, and comprehensive error handling. Built on top of the base RadioGroup component with additional styling and features.
+
+---
+
+## Types
+
+### AppRadioGroupOption
+
+```ts
+export interface AppRadioGroupOption {
+  value: string; // Unique value for the option
+  label: string | React.ReactNode; // Display label (can be JSX)
+  description?: string | React.ReactNode; // Optional description text
+  disabled?: boolean; // Disables this specific option
+  icon?: IconName; // Optional icon name
+}
+```
+
+---
+
+## Props
+
+| Prop              | Type                             | Default      | Description                                    |
+| ----------------- | -------------------------------- | ------------ | ---------------------------------------------- |
+| `options`         | `AppRadioGroupOption[]`          | **required** | Array of radio options                         |
+| `value`           | `string`                         | `undefined`  | Controlled value                               |
+| `defaultValue`    | `string`                         | `undefined`  | Uncontrolled default value                     |
+| `onValueChange`   | `(value: string) => void`        | `undefined`  | Callback when value changes                    |
+| `label`           | `string \| React.ReactNode`      | `undefined`  | Label for the radio group                      |
+| `description`     | `string \| React.ReactNode`      | `undefined`  | Description text below label                   |
+| `disabled`        | `boolean`                        | `false`      | Disables all options                           |
+| `required`        | `boolean`                        | `false`      | Shows required asterisk                        |
+| `name`            | `string`                         | `undefined`  | Form name attribute                            |
+| `orientation`     | `"horizontal" \| "vertical"`     | `"vertical"` | Layout orientation                             |
+| `loop`            | `boolean`                        | `true`       | Enable keyboard navigation looping             |
+| `className`       | `string`                         | `""`         | Additional classes for radio group container   |
+| `wrpClassName`    | `string`                         | `""`         | Additional classes for outer wrapper           |
+| `optionClassName` | `string`                         | `""`         | Additional classes for each option             |
+| `layout`          | `"default" \| "card"`            | `"default"`  | Visual layout style                            |
+| `error`           | `string`                         | `undefined`  | Error message to display                       |
+
+---
+
+## Behavior
+
+- **Controlled/Uncontrolled**: Supports both controlled (`value` + `onValueChange`) and uncontrolled (`defaultValue`) modes
+- **Keyboard Navigation**: Full keyboard support with arrow keys and looping
+- **Icons**: Automatically renders icons when provided in options
+- **Card Layout**: In card mode, options have border, shadow, and background styling
+- **Error State**: Red text for label and error message display when `error` prop is provided
+- **Disabled State**: Applies opacity and cursor changes to disabled options
+
+---
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { AppRadioGroup } from "laif-ds";
+import { useState } from "react";
+
+export function BasicRadioGroup() {
+  const [value, setValue] = useState("option1");
+
+  return (
+    <AppRadioGroup
+      label="Choose an option"
+      options={[
+        { value: "option1", label: "Option 1" },
+        { value: "option2", label: "Option 2" },
+        { value: "option3", label: "Option 3" },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+}
+```
+
+### With Icons and Descriptions
+
+```tsx
+import { AppRadioGroup } from "laif-ds";
+import { useState } from "react";
+
+export function RadioWithIcons() {
+  const [value, setValue] = useState("email");
+
+  return (
+    <AppRadioGroup
+      label="Notification Method"
+      description="Choose how you want to receive notifications"
+      options={[
+        {
+          value: "email",
+          label: "Email",
+          description: "Receive notifications via email",
+          icon: "Mail",
+        },
+        {
+          value: "sms",
+          label: "SMS",
+          description: "Receive notifications via text message",
+          icon: "MessageSquare",
+        },
+        {
+          value: "push",
+          label: "Push",
+          description: "Receive push notifications",
+          icon: "Bell",
+        },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+}
+```
+
+### Card Layout
+
+```tsx
+import { AppRadioGroup } from "laif-ds";
+import { useState } from "react";
+
+export function CardRadioGroup() {
+  const [value, setValue] = useState("basic");
+
+  return (
+    <AppRadioGroup
+      label="Choose a plan"
+      layout="card"
+      options={[
+        {
+          value: "basic",
+          label: "Basic",
+          description: "$9/month - Essential features",
+          icon: "Package",
+        },
+        {
+          value: "pro",
+          label: "Pro",
+          description: "$29/month - Advanced features",
+          icon: "Zap",
+        },
+        {
+          value: "enterprise",
+          label: "Enterprise",
+          description: "Custom pricing - All features",
+          icon: "Building",
+        },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+}
+```
+
+### Horizontal Orientation
+
+```tsx
+import { AppRadioGroup } from "laif-ds";
+import { useState } from "react";
+
+export function HorizontalRadioGroup() {
+  const [value, setValue] = useState("small");
+
+  return (
+    <AppRadioGroup
+      label="Size"
+      orientation="horizontal"
+      options={[
+        { value: "small", label: "Small" },
+        { value: "medium", label: "Medium" },
+        { value: "large", label: "Large" },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+}
+```
+
+### With Error State
+
+```tsx
+import { AppRadioGroup } from "laif-ds";
+import { useState } from "react";
+
+export function RadioWithError() {
+  const [value, setValue] = useState("");
+
+  return (
+    <AppRadioGroup
+      label="Choose an option"
+      required
+      options={[
+        { value: "option1", label: "Option 1" },
+        { value: "option2", label: "Option 2" },
+      ]}
+      value={value}
+      onValueChange={setValue}
+      error={!value ? "Please select an option" : undefined}
+    />
+  );
+}
+```
+
+---
+
+## Notes
+
+- **JSX Labels**: Both `label` and option labels support JSX for custom rendering
+- **Icon Support**: Uses the Icon component from laif-ds (Feather Icons)
+- **Accessibility**: Includes proper ARIA attributes and keyboard navigation
+- **Card Styling**: Card layout includes hover effects and focus states
+- **Disabled Options**: Individual options can be disabled while keeping others enabled