laif-ds 0.2.64 → 0.2.66

package/README.md

@@ -1,26 +1,37 @@
-## PUBBLICARE:
+# Laif Design System
 
-npm login
-npm whoami (verifica se sei loggato con accoutn corretto)
-yarn build (farà partire build per tailwindv3 e tailwindv4)
-npm publish --access public
+![NPM Version](https://img.shields.io/npm/v/laif-ds?style=flat&logo=npm&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2Flaif-ds)
 
-## INSTALL:
+## Install Laif DS on your project:
 
+```sh
 npm i @laif/ds
+```
 
-## HOW IT WORKS
+## Development mode
 
 Per vedere i componenti con storybook:
 
-```
+```sh
 yarn storybook
 ```
 
 Il comando esegue due operazioni in sequenza: prima compila il CSS con tailwindcss v4 salvandolo in un file output.css, poi avvia Storybook che utilizza questo file CSS precompilato.
 Questo approccio è necessario con Tailwind CSS v4 perché, a differenza delle versioni precedenti, v4 utilizza un'architettura "zero-runtime" che non si integra più direttamente con Storybook. La generazione separata del CSS è quindi la soluzione raccomandata per utilizzare Tailwind v4 con Storybook.
 
-## COME FUNZIONANO LE STORIES
+## Publish on NPM:
+
+```sh
+npm login
+
+npm whoami # verifica se sei loggato con account corretto
+
+yarn build # farà partire build per tailwindv3 e tailwindv4
+
+npm publish --access public
+```
+
+## How stories work
 
 Le stories in Storybook sono il modo in cui documentiamo e testiamo visivamente i nostri componenti. Ogni story rappresenta uno stato specifico di un componente.
 
@@ -82,7 +93,7 @@ export const Secondary: Story = {
 // Altre stories...
 ```
 
-### Come creare una nuova Story
+### How to create a new story
 
 1. Crea un nuovo file nella directory `src/components/stories/` con nome `nome-componente.stories.tsx`
 2. Importa il componente e le dipendenze necessarie

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

@@ -0,0 +1,225 @@
+# AppCheckbox
+
+## Overview
+
+Enhanced checkbox group component with support for icons, descriptions, card layout, horizontal/vertical orientation, and comprehensive error handling. Built on top of the base Checkbox component with additional styling and features.
+
+---
+
+## Types
+
+### AppCheckboxOption
+
+```ts
+export interface AppCheckboxOption {
+  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`         | `AppCheckboxOption[]`        | **required** | Array of checkbox options                       |
+| `value`           | `string[]`                   | `undefined`  | Controlled value (array of selected values)     |
+| `defaultValue`    | `string[]`                   | `undefined`  | Uncontrolled default value                      |
+| `onValueChange`   | `(value: string[]) => void`  | `undefined`  | Callback when value changes                     |
+| `label`           | `string \| React.ReactNode`  | `undefined`  | Label for the checkbox 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                              |
+| `className`       | `string`                     | `""`         | Additional classes for checkbox 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
+- **Multiple Selection**: Users can select multiple options simultaneously
+- **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 { AppCheckbox } from "laif-ds";
+import { useState } from "react";
+
+export function BasicCheckbox() {
+  const [value, setValue] = useState(["option1"]);
+
+  return (
+    <AppCheckbox
+      label="Choose options"
+      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 { AppCheckbox } from "laif-ds";
+import { useState } from "react";
+
+export function CheckboxWithIcons() {
+  const [value, setValue] = useState(["email"]);
+
+  return (
+    <AppCheckbox
+      label="Notification Preferences"
+      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 { AppCheckbox } from "laif-ds";
+import { useState } from "react";
+
+export function CardCheckbox() {
+  const [value, setValue] = useState(["feature1"]);
+
+  return (
+    <AppCheckbox
+      label="Select features"
+      layout="card"
+      options={[
+        {
+          value: "feature1",
+          label: "Advanced Analytics",
+          description: "Detailed insights and reports",
+          icon: "BarChart",
+        },
+        {
+          value: "feature2",
+          label: "Team Collaboration",
+          description: "Work together in real-time",
+          icon: "Users",
+        },
+        {
+          value: "feature3",
+          label: "Priority Support",
+          description: "24/7 dedicated support",
+          icon: "Headphones",
+        },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+}
+```
+
+### Horizontal Orientation
+
+```tsx
+import { AppCheckbox } from "laif-ds";
+import { useState } from "react";
+
+export function HorizontalCheckbox() {
+  const [value, setValue] = useState(["small"]);
+
+  return (
+    <AppCheckbox
+      label="Available Sizes"
+      orientation="horizontal"
+      options={[
+        { value: "small", label: "Small" },
+        { value: "medium", label: "Medium" },
+        { value: "large", label: "Large" },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+}
+```
+
+### With Error State
+
+```tsx
+import { AppCheckbox } from "laif-ds";
+import { useState } from "react";
+
+export function CheckboxWithError() {
+  const [value, setValue] = useState<string[]>([]);
+
+  return (
+    <AppCheckbox
+      label="Terms and Conditions"
+      required
+      options={[
+        { value: "terms", label: "I accept the terms and conditions" },
+        { value: "privacy", label: "I accept the privacy policy" },
+      ]}
+      value={value}
+      onValueChange={setValue}
+      error={
+        value.length === 0 ? "You must accept at least one 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
+- **Multiple Selection**: Unlike radio groups, checkboxes allow selecting multiple options

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

@@ -28,24 +28,27 @@ 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   |
+| 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                          |
+| `noGroupLabel`       | `string`                       | `"Nessun gruppo"`                                | Label shown for options without a group                     |
+| `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                            |
+| `labelClassName`     | `string`                       | `""`                                             | Additional Tailwind classes for the label                   |
+| `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                        |
+| `size`               | `"sm" \| "default" \| "lg"`    | `"default"`                                      | Size variant affecting height and text size                 |
+| `onClear`            | `() => void`                   | `undefined`                                      | Callback fired when clear button is clicked                 |
+| `id`                 | `string`                       | `undefined`                                      | HTML id attribute for the trigger (useful for testing)      |
+| `data-testid`        | `string`                       | `undefined`                                      | Test identifier attribute for E2E testing (e.g. Playwright) |
 
 ### Single Select Props
 
@@ -55,6 +58,7 @@ export type SingleSelectProps = BaseProps & {
   value?: string | number; // Controlled value
   defaultValue?: string | number; // Uncontrolled default value
   onValueChange?: (value: string | number | undefined) => void; // Value change callback
+  renderValue?: (option: AppSelectOption) => React.ReactNode; // Custom render for selected value
   isSingleSelectClearable?: boolean; // Shows clear button (default: false)
 };
 ```
@@ -67,6 +71,7 @@ export type MultiSelectProps = BaseProps & {
   value?: (string | number)[]; // Controlled values array
   defaultValue?: (string | number)[]; // Uncontrolled default values
   onValueChange?: (value: (string | number)[]) => void; // Value change callback
+  renderValue?: (option: AppSelectOption) => React.ReactNode; // Custom render for selected values
   maxSelected?: number; // Maximum number of selectable items
   showChipsInsteadOfCount?: boolean; // Display chips instead of count (default: false)
 };
@@ -146,8 +151,8 @@ 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
+- Options without a group value (empty string, undefined, or missing) appear under the `noGroupLabel` heading
+- Grouping is based on the `group` property of `AppSelectOption`
 
 ### Max Selection Limit
 
@@ -270,7 +275,6 @@ export function GroupedSelect() {
       onValueChange={setValues}
       placeholder="Select up to 2 technologies"
       label="Tech Stack"
-      groupBy="group"
       maxSelected={2}
       searchable
     />
@@ -416,6 +420,37 @@ export function SelectWithDisabled() {
 }
 ```
 
+### Custom Render Value
+
+```tsx
+import { AppSelect, AppSelectOption } from "laif-ds";
+import { Badge } from "laif-ds";
+import { useState } from "react";
+
+const options = [
+  { value: "react", label: "React" },
+  { value: "vue", label: "Vue" },
+  { value: "angular", label: "Angular" },
+];
+
+export function CustomRenderSelect() {
+  const [value, setValue] = useState<string | number | undefined>("react");
+
+  return (
+    <AppSelect
+      options={options}
+      value={value}
+      onValueChange={setValue}
+      placeholder="Select a framework"
+      label="Framework"
+      renderValue={(option: AppSelectOption) => (
+        <Badge variant="success">{option.label}</Badge>
+      )}
+    />
+  );
+}
+```
+
 ---
 
 ## Notes
@@ -425,3 +460,5 @@ export function SelectWithDisabled() {
 - **Keyboard Navigation**: Full keyboard support via Command component
 - **Accessibility**: Proper ARIA attributes and focus management
 - **Performance**: Efficient rendering with useMemo for computed values
+- **Custom Rendering**: Use `renderValue` prop to customize how selected options appear in the trigger
+- **Controlled Component Detection**: Uses `props.hasOwnProperty('value')` to determine if component is controlled, ensuring stable behavior even when value is `undefined`