laif-ds 0.2.75 → 0.2.77

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

@@ -11,8 +11,10 @@ Dynamic form component that integrates with React Hook Form to provide a configu
 ### AppFormItem
 
 ```ts
-export interface AppFormItem {
-  label: string; // Field label
+export type AppFormItem<TAsyncOption = unknown> = {
+  /** Field label displayed above the component. */
+  label: string;
+  /** The type of form component to render. */
   component:
     | "input"
     | "select"
@@ -24,29 +26,98 @@ export interface AppFormItem {
     | "switch"
     | "slider"
     | "async"
-    | "async-multiple"; // Field type
-  name: string; // Field name (used for form state and validation)
-  inputType?: ComponentProps<"input">["type"]; // HTML input type for "input" component (e.g. "text", "email", "password", "number", "url", "search", "tel")
-  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 (enables range mode)
-  min?: number; // Minimum value for slider
-  max?: number; // Maximum value for slider
-  step?: number; // Step value for slider
-  fetcher?: (query?: string) => Promise<any[]>; // Async select data loader
-  renderOptionItem?: (option: any) => React.ReactNode; // Customize render of async option
-  resolveOptionValue?: (option: any) => string; // Value extractor for async option
-  renderSelectedValue?: (option: any) => React.ReactNode; // Customize render of selected async option
-  initialOptions?: any[]; // Optional cache for async select hydration
-  notFound?: React.ReactNode; // Custom not found message for async select
-  noResultsMessage?: string; // No results message for async select
-  debounce?: number; // Debounce time for async select search
-  clearable?: boolean; // Allow clearing async select value
-  datePickerProps?: Partial<ComponentProps<typeof DatePicker>>; // Additional DatePicker props (locale, dateFormat, numberOfMonths, minDate, maxDate, etc.)
-}
+    | "async-multiple"
+    | "custom";
+  /** Field name used for React Hook Form state binding and validation. */
+  name: string;
+  /**
+   * HTML input type. Only applies when `component` is `"input"`.
+   * @example "text" | "email" | "password" | "number" | "url" | "search" | "tel"
+   */
+  inputType?: ComponentProps<"input">["type"];
+  /** Initial value for the field. */
+  defaultValue?: string | boolean | number | string[] | Date | number[];
+  /** Options list for `select`, `multiselect`, and `radio` components. */
+  options?: AppSelectOption[];
+  /** Disables the field, preventing user interaction. @default false */
+  disabled?: boolean;
+  /** Placeholder text shown when no value is selected or entered. */
+  placeholder?: string;
+  /** Helper text displayed below the field. */
+  caption?: string;
+  /**
+   * Enables range mode on the `datepicker` component when provided.
+   * The two dates define the selectable calendar boundaries.
+   */
+  calendarRange?: [Date, Date];
+  /** Minimum value for the `slider` component. @default 0 */
+  min?: number;
+  /** Maximum value for the `slider` component. @default 100 */
+  max?: number;
+  /** Step increment for the `slider` component. @default 1 */
+  step?: number;
+  /**
+   * Async data loader for `async` and `async-multiple` components.
+   * Called with the current search query; must return a promise of options.
+   */
+  fetcher?: (query?: string) => Promise<TAsyncOption[]>;
+  /**
+   * Custom render function for each option item in the async dropdown.
+   * Required for `async` and `async-multiple` components.
+   */
+  renderOptionItem?: (option: TAsyncOption) => React.ReactNode;
+  /**
+   * Extracts the unique string value from an async option object.
+   * Required for `async` and `async-multiple` components.
+   */
+  resolveOptionValue?: (option: TAsyncOption) => string;
+  /**
+   * Custom render function for the selected value chip/label.
+   * Required for `async` and `async-multiple` components.
+   */
+  renderSelectedValue?: (option: TAsyncOption) => React.ReactNode;
+  /**
+   * Pre-loaded options used to hydrate the async select on mount,
+   * avoiding an initial fetch when the value is already known.
+   */
+  initialOptions?: TAsyncOption[];
+  /** Custom node displayed when the async fetcher returns no results at all. */
+  notFound?: React.ReactNode;
+  /** Message shown when the async search query returns no matching results. */
+  noResultsMessage?: string;
+  /** Debounce delay in milliseconds for the async search input. @default 300 */
+  debounce?: number;
+  /** Allows the user to clear the selected value in the async select. @default false */
+  clearable?: boolean;
+  /** Extra props forwarded directly to the `DatePicker` component. */
+  datePickerProps?: Partial<DatePickerProps>;
+  /** Column span for the item in the grid. @default undefined (auto, or "full" for the last item) */
+  colSpan?: "1" | "2" | "3" | "full";
+  /** Icon on the left side. Only applies when `component` is `"input"`. */
+  iconLeft?: IconName;
+  /** Icon on the right side. Only applies when `component` is `"input"`. */
+  iconRight?: IconName;
+  /** Enables search/filter inside `select` and `multiselect` dropdowns. @default true */
+  searchable?: boolean;
+  /** Hides the label above the field. @default false */
+  hideLabel?: boolean;
+  /** Additional CSS class name applied to the item container div. */
+  className?: string;
+  /**
+   * Additional props forwarded to the underlying UI component.
+   * Strongly typed based on the chosen `component` value.
+   */
+  componentProps?: AppFormItemComponentProps[TComponent];
+  /**
+   * Custom render function for the component.
+   * Required when `component` is `"custom"`.
+   */
+  render?: (props: {
+    field: ControllerRenderProps<FieldValues, string>;
+    error?: string;
+    label: React.ReactNode;
+  }) => React.ReactNode;
+};
 ```
 
 ### Submit Button Inside vs Outside
@@ -103,12 +174,12 @@ export function SubmitInsideVsOutside() {
 
 | Prop               | Type                  | Default      | Description                                              |
 | ------------------ | --------------------- | ------------ | -------------------------------------------------------- |
-| `items`            | `AppFormItem[]`       | **required** | Array of form field configurations                       |
-| `form`             | `UseFormReturn<any>`  | **required** | React Hook Form instance                                 |
+| `items`            | `AppFormItem[]`       | **required** | Array of field configurations                            |
+| `form`             | `UseFormReturn<any>`  | **required** | React Hook Form instance returned by `useForm`           |
 | `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                     |
+| `submitText`       | `string`              | `"Invia"`    | Text label for the internal submit button                |
+| `onSubmit`         | `(data: any) => void` | `undefined`  | Callback fired with validated form data on submission    |
+| `isSubmitting`     | `boolean`             | `false`      | Shows loading spinner on the submit button               |
 | `showSubmitButton` | `boolean`             | `false`      | Renders an internal submit button at the end of the form |
 
 ---
@@ -117,9 +188,9 @@ export function SubmitInsideVsOutside() {
 
 - **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
+- **Grid Layout**: Automatically arranges fields in a responsive grid based on `cols` prop. Use `colSpan` on items for fine-grained control.
 - **Submit Button**: Rendered only when `showSubmitButton` is `true`. When shown, it is disabled when the form is invalid or pristine. Otherwise, manage submit externally with `form.handleSubmit(...)`.
-- **Last Field Spanning**: The last field automatically spans full width
+- **Last Field Spanning**: The last field automatically spans full width unless `colSpan` is explicitly set.
 - **Error Highlighting**: Fields with errors get red border styling
 
 ---
@@ -128,360 +199,102 @@ export function SubmitInsideVsOutside() {
 
 ### input
 
-Standard text input field
-
-Standard text input field. When `component: "input"`, you can use the `inputType` property to control the underlying HTML input type (e.g. `"text"`, `"email"`, `"password"`, `"number"`, `"url"`).
-
-For a complete showcase of different input types, see the Storybook story `UI/AppForm/DifferentInputTypes`.
+Standard text input field. Supports `iconLeft` and `iconRight`.
 
-### textarea
+When `component: "input"`, use the `inputType` property to control the underlying HTML input type (e.g. `"text"`, `"email"`, `"password"`, `"number"`, `"url"`).
 
-Multi-line text area
+### select / multiselect
 
-### select
+Single or multiple selection dropdown using `AppSelect`. Supports `searchable: true`.
 
-Single selection dropdown using AppSelect
+### custom
 
-### multiselect
+Allows rendering any arbitrary content within the form grid. Requires the `render` function.
 
-Multiple selection dropdown using AppSelect with `multiple` prop
+```tsx
+{
+  label: "Custom Section",
+  component: "custom",
+  name: "customInfo",
+  render: ({ field, error, label }) => (
+    <div className="p-4 border rounded">
+      {label}
+      <input {...field} className="border p-2" />
+      {error && <span className="text-red-500">{error}</span>}
+    </div>
+  ),
+  colSpan: "full"
+}
+```
 
 ### async / async-multiple
 
-Use `AsyncSelect` for server-side driven selects. `async` gestisce un valore singolo, `async-multiple` un array di stringhe. Richiede i seguenti prop sull'item:
-
-- `fetcher`: funzione che restituisce `Promise<Option[]>`
-- `renderOptionItem`, `resolveOptionValue`, `renderSelectedValue`: per gestire il rendering e la selezione
-- `initialOptions` (opzionale ma consigliata) per idratare i valori preimpostati
-- `defaultValue` va impostato nei `defaultValues` di React Hook Form
+Use `AsyncSelect` for server-side driven selects. `async` handles a single string value, `async-multiple` an array of strings.
 
-Esempio:
-
-```tsx
-const items: AppFormItem[] = [
-  {
-    component: "async",
-    name: "business",
-    label: "Business (async)",
-    placeholder: "Seleziona un business",
-    fetcher: mockAsyncSelectFetcher,
-    initialOptions: asyncSelectMockUsers,
-    renderOptionItem: (user) => (
-      <div>
-        <strong>{user.name}</strong>
-        <span className="text-muted-foreground text-xs">{user.email}</span>
-      </div>
-    ),
-    resolveOptionValue: (user) => user.id,
-    renderSelectedValue: (user) => user.name,
-  },
-  {
-    component: "async-multiple",
-    name: "team",
-    label: "Team (async)",
-    placeholder: "Seleziona i membri",
-    fetcher: mockAsyncSelectFetcher,
-    initialOptions: asyncSelectMockUsers,
-    renderOptionItem: (user) => user.name,
-    resolveOptionValue: (user) => user.id,
-    renderSelectedValue: (user) => user.name,
-  },
-];
+Required props for both: `fetcher`, `renderOptionItem`, `resolveOptionValue`, `renderSelectedValue`.
 
-const form = useForm({
-  defaultValues: {
-    business: asyncSelectMockUsers[0]?.id ?? "",
-    team: asyncSelectMockUsers.slice(0, 2).map((u) => u.id),
-  },
-});
-```
+### datepicker
 
-Ricorda che il fetch parte solo quando il menu è aperto; eventuali valori iniziali devono essere già presenti in `initialOptions`.
+Date picker component with optional range selection via `calendarRange`. Pass `datePickerProps` for locale, format, or other `DatePicker` customisation.
 
-### datepicker
+### radio / checkbox / switch / slider
 
-Date picker component with optional range selection via `calendarRange`. Use `datePickerProps` to customize the DatePicker behavior such as locale, date format, number of months displayed, min/max dates, etc.
+Standard form components for various input types.
 
-**Available datePickerProps options:**
+---
 
-- `locale`: Locale object from `date-fns/locale` (e.g., `enUS`, `it`, `fr`)
-- `dateFormat`: Date format string (e.g., `"MM/dd/yyyy"`, `"dd/MM/yyyy"`)
-- `numberOfMonths`: Number of months to display in the calendar
-- `minDate`: Minimum selectable date
-- `maxDate`: Maximum selectable date
-- `firstDate`: First available date (disables dates before)
-- `lastDate`: Last available date (disables dates after)
-- `availableDates`: Array of specific dates that are selectable
-- `showTime`: Show time picker columns (HH, MM)
-- `withSeconds`: Show seconds column in the time picker (requires `showTime`)
-- `minuteStep`: Minute step interval for the time picker
-- `secondStep`: Second step interval for the time picker
-- And other DatePicker props
+## Examples
 
-**Example with English locale:**
+### Grid and Icons Example
 
 ```tsx
-import { enUS } from "date-fns/locale";
-
 const items: AppFormItem[] = [
   {
-    label: "Appointment Date",
-    component: "datepicker",
-    name: "appointmentDate",
-    placeholder: "Pick a date",
-    datePickerProps: {
-      locale: enUS,
-      dateFormat: "MM/dd/yyyy HH:mm",
-      showTime: true,
-    },
+    label: "First Name",
+    component: "input",
+    name: "firstName",
+    colSpan: "1",
   },
   {
-    label: "Event Date Range",
-    component: "datepicker",
-    name: "eventRange",
-    placeholder: "Select date range",
-    calendarRange: [new Date(), new Date()],
-    datePickerProps: {
-      locale: enUS,
-      dateFormat: "MM/dd/yyyy",
-      numberOfMonths: 2,
-    },
+    label: "Last Name",
+    component: "input",
+    name: "lastName",
+    colSpan: "1",
+  },
+  {
+    label: "Email",
+    component: "input",
+    name: "email",
+    iconLeft: "Mail",
+    colSpan: "full",
+  },
+  {
+    label: "Department",
+    component: "select",
+    name: "dept",
+    options: [
+      /* ... */
+    ],
+    colSpan: "full",
   },
 ];
-```
-
-### 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",
-          inputType: "email",
-          placeholder: "Enter your email",
-        },
-        {
-          label: "Message",
-          component: "textarea",
-          name: "message",
-          placeholder: "Enter your message",
-        },
-      ]}
-      onSubmit={(data) => console.log(data)}
-    />
-  );
-}
+return <AppForm form={form} items={items} cols="2" showSubmitButton />;
 ```
 
-### 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)}
-    />
-  );
-}
-```
+### Advanced componentProps
 
-### With Date Range
+Use `componentProps` to pass specific properties to the underlying UI components that are not exposed directly in `AppFormItem`.
 
 ```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)}
-    />
-  );
-}
-```
-
-### External Form Control
-
-You can access the form instance to programmatically control values, watch changes, and reset the form:
-
-```tsx
-import { AppForm, Button } from "laif-ds";
-import { useForm } from "react-hook-form";
-import { useState, useEffect } from "react";
-
-export function ExternalControlForm() {
-  const [formValues, setFormValues] = useState({});
-  const [watchedValues, setWatchedValues] = useState({});
-
-  const form = useForm({
-    defaultValues: {
-      name: "",
-      email: "",
-    },
-  });
-
-  const { watch, setValue, reset } = form;
-
-  // Watch specific fields
-  const nameValue = watch("name");
-  const emailValue = watch("email");
-
-  // Auto-fill handler
-  const handleAutoFill = () => {
-    setValue("name", "Mario Rossi");
-    setValue("email", "mario@example.com");
-  };
-
-  // Reset handler
-  const handleReset = () => {
-    reset();
-    setFormValues({});
-    setWatchedValues({});
-  };
-
-  // Watch all form values
-  useEffect(() => {
-    const subscription = watch((values) => {
-      setWatchedValues(values);
-    });
-    return () => subscription.unsubscribe();
-  }, [watch]);
-
-  return (
-    <div>
-      <div className="mb-4 flex gap-2">
-        <Button type="button" variant="outline" onClick={handleAutoFill}>
-          Auto-fill
-        </Button>
-        <Button type="button" variant="outline" onClick={handleReset}>
-          Reset
-        </Button>
-      </div>
-
-      <AppForm
-        form={form}
-        items={[
-          { label: "Name", component: "input", name: "name" },
-          { label: "Email", component: "input", name: "email" },
-        ]}
-        onSubmit={(data) => setFormValues(data)}
-        showSubmitButton
-      />
-
-      <div className="mt-4">
-        <p>Name: {nameValue || "(empty)"}</p>
-        <p>Email: {emailValue || "(empty)"}</p>
-        <pre>{JSON.stringify(watchedValues, null, 2)}</pre>
-      </div>
-    </div>
-  );
+{
+  label: "Bio",
+  component: "textarea",
+  name: "bio",
+  componentProps: {
+    rows: 10,
+    className: "resize-none"
+  }
 }
 ```
 
@@ -490,7 +303,5 @@ export function ExternalControlForm() {
 ## 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**: Use `showSubmitButton` to render the internal submit button at the end of the form, or provide your own external submit control.
-- **Error Display**: Errors appear inline above each field and as border highlighting
+- **Type Safety**: `componentProps` is strictly typed based on the `component` chosen.

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

@@ -32,6 +32,7 @@ Powerful table built on TanStack Table v8. Supports client-side and server-side
 | `disableAutoPageSize`   | `boolean`                             | `false`                | Disable auto pageSize (still updates pageIndex).                                        |
 | `id`                    | `string`                              | `undefined`            | Test/accessibility hook for the root element.                                           |
 | `data-testid`           | `string`                              | `undefined`            | Test identifier forwarded to the root element.                                          |
+| `rowClassName`          | `string \| ((row) => string)`         | `undefined`            | Add custom CSS classes to table rows based on row data or state.                        |
 
 ---
 
@@ -56,6 +57,8 @@ type ColumnMeta = {
   searchable?: boolean;
   pinned?: "left" | "right";
   listOptions?: { value: string; label: string }[];
+  cellClassName?: string | ((value: any, row: TData) => string);
+  headerClassName?: string;
 };
 ```
 

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

@@ -20,7 +20,7 @@ Drag-and-drop uploader with keyboard activation, file type filtering, limits (co
 | `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`.
+`AcceptItem` includes: `pdf | doc | docx | xls | xlsx | ppt | pptx | txt | csv | jpg | jpeg | png | gif | image | video | audio | zip | rar | 7z | tar | gz | tgz`.
 
 ---
 
@@ -68,6 +68,12 @@ const exts: AcceptItem[] = [
   "image",
   "video",
   "audio",
+  "zip",
+  "rar",
+  "7z",
+  "tar",
+  "gz",
+  "tgz",
 ];
 
 export function MultiUploader() {

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

@@ -46,6 +46,7 @@ This document provides a complete mapping of all components available in the lai
 ### Layout & Structure Components
 
 - **Accordion** - Collapsible content panels for organizing information hierarchically
+- **AppCard** - Enhanced card component with variant styles, semantic states, size control, and loading skeleton support
 - **AppSidebar** - Application sidebar navigation component
 - **AppStepper** - Step-by-step progress indicator for multi-step processes
 - **AspectRatio** - Container that maintains a specific aspect ratio for responsive layouts
@@ -85,6 +86,7 @@ This document provides a complete mapping of all components available in the lai
 - **Pagination** - Page navigation component for paginated content
 - **Table** - Basic table component with styling
 - **TableSkeleton** - Loading skeleton for table components
+- **TruncatedCell** - Text display component with automatic truncation detection and popover preview
 - **Typo** - Typography component for consistent text styling
 
 ### Content & Media Components