@delightui/components 0.1.122 → 0.1.123

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
-import React__default, { ImgHTMLAttributes, SyntheticEvent, HTMLAttributes, ReactNode, MouseEvent, FormHTMLAttributes, Ref, InputHTMLAttributes, TextareaHTMLAttributes, ComponentType, LiHTMLAttributes, CSSProperties, RefObject, TableHTMLAttributes, TdHTMLAttributes, ReactElement, AriaRole, KeyboardEventHandler } from 'react';
+import React__default, { ImgHTMLAttributes, SyntheticEvent, HTMLAttributes, ReactNode, MouseEvent, FormHTMLAttributes, Ref, InputHTMLAttributes, TextareaHTMLAttributes, ComponentType, LiHTMLAttributes, CSSProperties, TableHTMLAttributes, TdHTMLAttributes, ReactElement, AriaRole, KeyboardEventHandler } from 'react';
 import { LinkProps } from 'react-router-dom';
 import { Plugin } from 'flatpickr/dist/types/options';
 import FlatPickr from 'react-flatpickr';
@@ -2007,22 +2007,136 @@ declare const useSelectContext: () => SelectContextType;
  */
 declare const SelectProvider: ({ children, value, multiple, disabled, invalid, onValueChange, closeSelectOptions, }: SelectProviderProps) => react_jsx_runtime.JSX.Element;
 
-type ChipListItemTypeEnum = 'chip' | 'input';
-type ChipListItemProps = {
-    type: ChipListItemTypeEnum;
-    props: ChipProps | InputProps;
-    inputRef?: RefObject<HTMLInputElement>;
+/**
+ * Represents an option that can be selected in the ChipInput component.
+ * This is the normalized format used internally to handle both string arrays and object arrays.
+ */
+type OptionLike = {
+    /** Unique identifier for the option. Can be string or number. */
+    key: string | number;
+    /** Display text shown to the user for this option. */
+    label: string;
 };
-type ChipInputProps = ControlledFormComponentProps<string[]> & {
+/**
+ * Type alias for the key property of OptionLike.
+ * Used for type safety when working with selected values.
+ */
+type OptionLikeKey = OptionLike['key'];
+/**
+ * Props for the ChipInput component.
+ *
+ * @template T - The type of the value array. Can be string[] or OptionLike[].
+ *               This generic ensures type consistency between input and output.
+ *
+ * @example
+ * ```tsx
+ * // String array usage
+ * const [fruits, setFruits] = useState<string[]>(['apple']);
+ * <ChipInput
+ *   value={fruits}
+ *   onValueChange={setFruits}
+ *   options={['apple', 'banana', 'cherry']}
+ * />
+ *
+ * // OptionLike array usage
+ * const [items, setItems] = useState<OptionLike[]>([{key: 1, label: 'Apple'}]);
+ * <ChipInput
+ *   value={items}
+ *   onValueChange={setItems}
+ *   options={[{key: 1, label: 'Apple'}, {key: 2, label: 'Banana'}]}
+ * />
+ * ```
+ */
+type ChipInputProps<T = string[] | OptionLike[]> = Omit<ControlledFormComponentProps<OptionLikeKey[]>, 'value' | 'onValueChange'> & {
+    /**
+     * Current selected values. Type matches the generic T parameter.
+     * For string arrays: ['apple', 'banana']
+     * For OptionLike arrays: [{key: 1, label: 'Apple'}, {key: 2, label: 'Banana'}]
+     */
+    value?: T;
+    /**
+     * Callback fired when the selected values change.
+     * Returns the same type as the input value for type consistency.
+     *
+     * @param value - The new array of selected values in the same format as input
+     */
+    onValueChange?: (value: T) => void;
+    /**
+     * Current value of the text input field.
+     * Used for controlled input behavior and filtering.
+     */
     inputValue?: string;
+    /**
+     * Callback fired when the input field value changes.
+     *
+     * @param value - The new input field value
+     */
     onInputChange?: (value: string) => void;
-    options?: string[];
+    /**
+     * Available options for selection. Can be either:
+     * - string[]: Simple array of strings like ['apple', 'banana']
+     * - OptionLike[]: Array of objects like [{key: 1, label: 'Apple'}]
+     *
+     * Options are automatically filtered as the user types in the input field.
+     */
+    options?: string[] | OptionLike[];
+    /**
+     * Placeholder text shown in the input field when it's empty.
+     *
+     * @default undefined
+     */
     placeholder?: string;
+    /**
+     * Additional CSS class name applied to the root element.
+     */
     className?: string;
-    onAddNewOption?: (value: string) => void;
+    /**
+     * Optional callback for creating new items when they don't exist in options.
+     * Can be synchronous or asynchronous for API integration.
+     *
+     * When this prop is provided:
+     * - Optimistic UI updates are applied immediately
+     * - If async, the UI shows loading states and handles errors
+     * - Failed operations are automatically reverted
+     *
+     * @param newItemValue - The text value entered by the user
+     * @returns Promise<OptionLike> for async operations, OptionLike for sync operations
+     *
+     * @example
+     * ```tsx
+     * // Sync operation
+     * onAddItem={(value) => ({ key: value, label: value })}
+     *
+     * // Async operation
+     * onAddItem={async (value) => {
+     *   const newItem = await api.createItem(value);
+     *   return { key: newItem.id, label: newItem.name };
+     * }}
+     * ```
+     */
+    onAddItem?: (newItemValue: string) => Promise<OptionLike> | OptionLike;
+    /**
+     * Optional callback for deleting items.
+     * Typically used for API integration to sync deletions with backend.
+     *
+     * When provided, this callback is called when a chip is removed.
+     * The component handles UI updates automatically.
+     *
+     * @param keyToDelete - The key of the item being deleted
+     * @returns Promise<void> for the deletion operation
+     *
+     * @example
+     * ```tsx
+     * onDeleteItem={async (key) => {
+     *   await api.deleteItem(key);
+     *   // Component automatically updates UI
+     * }}
+     * ```
+     */
+    onDeleteItem?: (keyToDelete: OptionLikeKey) => Promise<void>;
 };
 
-declare const _default: React__default.NamedExoticComponent<ChipInputProps>;
+declare const ChipInput: <T extends string[] | OptionLike[]>(props: ChipInputProps<T>) => react_jsx_runtime.JSX.Element;
 
 /**
  * Enum for different search modes.
@@ -2548,4 +2662,4 @@ declare const NotificationContext: React__default.Context<NotificationContextVal
 declare const NotificationProvider: React__default.FC<NotificationProviderProps>;
 declare const useNotification: () => NotificationContextValue;
 
-export { type AccessibilityActions, type AccessibilityProps, Accordion, AccordionDetails, AccordionGroup, AccordionSummary, ActionCard, type ActionCardProps, ActionImage, type ActionImageProps, Breadcrumb, type BreadcrumbProps, Breadcrumbs, type BreadcrumbsProps, Breakpoint, type BreakpointProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Card, type CardProps, Checkbox, CheckboxItem, type CheckboxItemProps, type CheckboxLabelAlignmentEnum, type CheckboxProps, type CheckboxSizeEnum, type CheckboxTypeEnum, Chip, _default as ChipInput, type ChipInputProps, type ChipListItemProps, type ChipListItemTypeEnum, type ChipProps, ConditionalView, type ConditionalViewProps, ContextMenu, type ContextMenuProps, type CustomTimePickerConfig, CustomToggle, type CustomToggleProps, DatePicker, type DatePickerProps, SortableItem as DraggableItem, SortableTrigger as DraggableItemTrigger, Dropzone, DropzoneClear, DropzoneContent, type DropzoneContentProps, type DropzoneContentTypeEnum, DropzoneFilename, DropzoneFilename as DropzonePreview, type DropzoneProps, DropzoneSupportedFormats as DropzoneReject, DropzoneTrigger as DropzoneRoot, DropzoneSupportedFormats, DropzoneTrigger, type FieldValidationFunction, type FieldValidators, type FieldValue, Form, type FormContextValues, type FormErrors, FormField, type FormFieldProps, type FormProps, type FormProviderProps, type FormState, type FormStateChangeHandler, type FormSubmitHandler, type FormValidator, Grid, GridItem, type GridItemProps, GridList, type GridListProps, type GridProps, Icon, IconButton, type IconButtonProps, type IconButtonStyleEnum, type IconProps, type IconSizeEnum, type IconStyleEnum, Image, type ImageFitEnum, type ImageProps, Input, type InputProps, type InputTypeEnum, List, ListItem, type ListItemProps$1 as ListItemProps, type ListProps, Modal, type ModalComponentProps, ModalFooter, type ModalFooterProps, ModalHeader, type ModalHeaderProps, type ModalProps, ModalProvider, type ModalProviderProps, Nav, NavItem, type NavItemProps, NavLink, type NavLinkProps, type NavProps, type NotificationContainerProps, NotificationContext, NotificationProvider, Option, type OptionProps, type OverlayDirectionEnum, Pagination, PaginationNumberField, type PaginationNumberFieldProps, type PaginationProps, Password, Popover, type PopoverHandle, type PopoverProps, ProgressBar, type ProgressBarProps, RadioButton, RadioButtonItem, type RadioButtonItemProps, type RadioButtonLabelAlignmentEnum, type RadioButtonProps, type RadioButtonSizeEnum, RadioGroup, type RadioGroupProps, RenderStateView, type RenderStateViewProps, RepeaterList, type RepeaterListProps, type RequiredFields, ResponsiveComponent, type ResponsiveComponentProps, Search, type SearchCallback, type SearchStyleEnum as SearchModeEnum, type SearchProps, Select, SelectListItem, type SelectListItemProps, type SelectProps, SelectProvider, SlideOutPanel, type SlideOutPanelDirectionEnum, type SlideOutPanelProps, type SlideOutPanelSizeEnum, Slider, type SliderProps, Spinner, type SpinnerProps, TabContent, type TabContentProps, TabItem, type TabItemProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHeader, TableHeaderCell, type TableHeaderCellProps, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsProps, Text, TextArea, type TextAreaProps, type TextDecorationEnum, type TextProps, type TextTypeEnum, type TextWeightEnum, ThemeContext, type ThemeContextType, ThemeProvider, type ThemeProviderProps, Toggle, ToggleButton, type ToggleButtonProps, type ToggleLabelAlignmentEnum, type ToggleProps, Tooltip, type TooltipProps, type UseModalReturn, WrapTextNodes, type WrapTextNodesProps, applyPropsToChildren, getClickAccessibilityProps, mergeRefs, useDebounce, useDropzoneContext, useInflateView, useModal, useNotification, useSelectContext, useTab };
+export { type AccessibilityActions, type AccessibilityProps, Accordion, AccordionDetails, AccordionGroup, AccordionSummary, ActionCard, type ActionCardProps, ActionImage, type ActionImageProps, Breadcrumb, type BreadcrumbProps, Breadcrumbs, type BreadcrumbsProps, Breakpoint, type BreakpointProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Card, type CardProps, Checkbox, CheckboxItem, type CheckboxItemProps, type CheckboxLabelAlignmentEnum, type CheckboxProps, type CheckboxSizeEnum, type CheckboxTypeEnum, Chip, ChipInput, type ChipInputProps, type ChipProps, ConditionalView, type ConditionalViewProps, ContextMenu, type ContextMenuProps, type CustomTimePickerConfig, CustomToggle, type CustomToggleProps, DatePicker, type DatePickerProps, SortableItem as DraggableItem, SortableTrigger as DraggableItemTrigger, Dropzone, DropzoneClear, DropzoneContent, type DropzoneContentProps, type DropzoneContentTypeEnum, DropzoneFilename, DropzoneFilename as DropzonePreview, type DropzoneProps, DropzoneSupportedFormats as DropzoneReject, DropzoneTrigger as DropzoneRoot, DropzoneSupportedFormats, DropzoneTrigger, type FieldValidationFunction, type FieldValidators, type FieldValue, Form, type FormContextValues, type FormErrors, FormField, type FormFieldProps, type FormProps, type FormProviderProps, type FormState, type FormStateChangeHandler, type FormSubmitHandler, type FormValidator, Grid, GridItem, type GridItemProps, GridList, type GridListProps, type GridProps, Icon, IconButton, type IconButtonProps, type IconButtonStyleEnum, type IconProps, type IconSizeEnum, type IconStyleEnum, Image, type ImageFitEnum, type ImageProps, Input, type InputProps, type InputTypeEnum, List, ListItem, type ListItemProps$1 as ListItemProps, type ListProps, Modal, type ModalComponentProps, ModalFooter, type ModalFooterProps, ModalHeader, type ModalHeaderProps, type ModalProps, ModalProvider, type ModalProviderProps, Nav, NavItem, type NavItemProps, NavLink, type NavLinkProps, type NavProps, type NotificationContainerProps, NotificationContext, NotificationProvider, Option, type OptionLike, type OptionLikeKey, type OptionProps, type OverlayDirectionEnum, Pagination, PaginationNumberField, type PaginationNumberFieldProps, type PaginationProps, Password, Popover, type PopoverHandle, type PopoverProps, ProgressBar, type ProgressBarProps, RadioButton, RadioButtonItem, type RadioButtonItemProps, type RadioButtonLabelAlignmentEnum, type RadioButtonProps, type RadioButtonSizeEnum, RadioGroup, type RadioGroupProps, RenderStateView, type RenderStateViewProps, RepeaterList, type RepeaterListProps, type RequiredFields, ResponsiveComponent, type ResponsiveComponentProps, Search, type SearchCallback, type SearchStyleEnum as SearchModeEnum, type SearchProps, Select, SelectListItem, type SelectListItemProps, type SelectProps, SelectProvider, SlideOutPanel, type SlideOutPanelDirectionEnum, type SlideOutPanelProps, type SlideOutPanelSizeEnum, Slider, type SliderProps, Spinner, type SpinnerProps, TabContent, type TabContentProps, TabItem, type TabItemProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHeader, TableHeaderCell, type TableHeaderCellProps, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsProps, Text, TextArea, type TextAreaProps, type TextDecorationEnum, type TextProps, type TextTypeEnum, type TextWeightEnum, ThemeContext, type ThemeContextType, ThemeProvider, type ThemeProviderProps, Toggle, ToggleButton, type ToggleButtonProps, type ToggleLabelAlignmentEnum, type ToggleProps, Tooltip, type TooltipProps, type UseModalReturn, WrapTextNodes, type WrapTextNodesProps, applyPropsToChildren, getClickAccessibilityProps, mergeRefs, useDebounce, useDropzoneContext, useInflateView, useModal, useNotification, useSelectContext, useTab };

package/docs/components/molecules/ChipInput.md

@@ -2,7 +2,17 @@
 
 ## Description
 
-An input field component that allows users to enter multiple values as chips or tags. Automatically converts typed input into removable chip elements, providing an intuitive interface for managing lists of items like tags, categories, email addresses, or any collection of discrete values.
+A powerful input field component that allows users to enter multiple values as chips or tags. Features automatic input filtering, backspace deletion, async operations with optimistic UI updates, and support for both simple strings and complex objects. Perfect for managing tags, categories, email addresses, team assignments, or any collection of discrete values.
+
+## Key Features
+
+- **📝 Input Filtering**: Real-time filtering of dropdown options as you type
+- **⌫ Backspace Deletion**: Press backspace when input is empty to delete last chip
+- **⚡ Async Operations**: Support for async add/delete operations with optimistic UI updates
+- **🔄 Error Handling**: Automatic reversion of failed operations
+- **📊 Type Flexibility**: Works with both `string[]` and `OptionLike[]` arrays
+- **🎯 Form Integration**: Full compatibility with form validation and controlled components
+- **♿ Accessibility**: Keyboard navigation and screen reader support
 
 ## Aliases
 
@@ -14,33 +24,214 @@ An input field component that allows users to enter multiple values as chips or
 
 ## Props Breakdown
 
-**Extends:** `ControlledFormComponentProps<string[]>`
+**Generic Type:** `ChipInputProps<T = string[] | OptionLike[]>`
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `value` | `string[]` | - | No | Current array of chip values |
-| `onValueChange` | `(value: string[]) => void` | - | No | Callback fired when chip values change |
-| `inputValue` | `string` | - | No | Current input field value |
+| `value` | `T` (string[] or OptionLike[]) | - | No | Current array of selected values |
+| `onValueChange` | `(value: T) => void` | - | No | Callback fired when selected values change |
+| `inputValue` | `string` | - | No | Current input field value for controlled input |
 | `onInputChange` | `(value: string) => void` | - | No | Callback fired when input value changes |
-| `options` | `string[]` | - | No | Predefined options for autocomplete |
+| `options` | `string[]` or `OptionLike[]` | - | No | Available options (automatically filtered by input) |
 | `placeholder` | `string` | - | No | Placeholder text for the input field |
 | `className` | `string` | - | No | Additional CSS class names |
-| `onAddNewOption` | `(value: string) => void` | - | No | Callback fired when a new option is added |
+| `onAddItem` | `(value: string) => Promise<OptionLike>` or `OptionLike` | - | No | Async/sync callback for creating new items |
+| `onDeleteItem` | `(key: OptionLikeKey) => Promise<void>` | - | No | Async callback for deleting items |
+| `onAddNewOption` | `(value: string) => OptionLike` or `void` | - | No | **Deprecated:** Use `onAddItem` instead |
 
 ## Examples
 
-### Basic Usage
+### Basic Usage with Filtering
 ```tsx
 import { ChipInput } from '@delightui/components';
 
 function BasicExample() {
   const [tags, setTags] = useState(['react', 'javascript']);
+  const availableTags = ['react', 'javascript', 'typescript', 'vue', 'angular', 'svelte'];
+
+  return (
+    <ChipInput
+      value={tags}
+      onValueChange={setTags}
+      options={availableTags}
+      placeholder="Type to filter tags..."
+    />
+  );
+}
+```
+
+### OptionLike Objects
+```tsx
+function OptionLikeExample() {
+  const [selectedFruits, setSelectedFruits] = useState([]);
+  
+  const fruitOptions = [
+    { key: 1, label: 'Apple 🍎' },
+    { key: 2, label: 'Banana 🍌' },
+    { key: 3, label: 'Cherry 🍒' },
+    { key: 4, label: 'Date 🌴' },
+  ];
+
+  return (
+    <ChipInput
+      value={selectedFruits}
+      onValueChange={setSelectedFruits}
+      options={fruitOptions}
+      placeholder="Select fruits..."
+    />
+  );
+}
+```
+
+### Async Operations with Optimistic UI
+```tsx
+function AsyncExample() {
+  const [items, setItems] = useState([]);
+  const [options, setOptions] = useState([
+    { key: 1, label: 'Existing Item 1' },
+    { key: 2, label: 'Existing Item 2' },
+  ]);
+
+  const handleAddItem = async (value) => {
+    // Simulate API call
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    
+    // Simulate random error for demo
+    if (value === 'error') {
+      throw new Error('Simulated error');
+    }
+    
+    const newItem = {
+      key: Date.now(),
+      label: `${value} ✨`
+    };
+    
+    setOptions(prev => [...prev, newItem]);
+    return newItem;
+  };
+
+  const handleDeleteItem = async (key) => {
+    // Simulate API call
+    await new Promise(resolve => setTimeout(resolve, 500));
+    setOptions(prev => prev.filter(opt => opt.key !== key));
+  };
+
+  return (
+    <ChipInput
+      value={items}
+      onValueChange={setItems}
+      options={options}
+      onAddItem={handleAddItem}
+      onDeleteItem={handleDeleteItem}
+      placeholder='Try typing "error" to see error handling'
+    />
+  );
+}
+```
+
+### Keyboard Navigation Demo
+```tsx
+function KeyboardNavigationExample() {
+  const [tags, setTags] = useState(['frontend', 'javascript']);
+  const options = [
+    'frontend', 'backend', 'javascript', 'typescript', 'react', 
+    'vue', 'angular', 'node', 'python', 'java'
+  ];
+
+  return (
+    <div>
+      <ChipInput
+        value={tags}
+        onValueChange={setTags}
+        options={options}
+        placeholder="Try: type to filter, backspace to delete, enter to add"
+      />
+      <div style={{ marginTop: '8px', fontSize: '12px', color: '#666' }}>
+        <strong>Keyboard shortcuts:</strong>
+        <ul style={{ margin: 0, paddingLeft: '16px' }}>
+          <li>Type to filter available options</li>
+          <li>Press <kbd>Backspace</kbd> when input is empty to delete last chip</li>
+          <li>Press <kbd>Enter</kbd> to add typed text as new chip</li>
+        </ul>
+      </div>
+    </div>
+  );
+}
+```
+
+### API Integration Example
+```tsx
+function APIIntegrationExample() {
+  const [selectedUsers, setSelectedUsers] = useState([]);
+  const [availableUsers, setAvailableUsers] = useState([
+    { key: 1, label: 'John Doe' },
+    { key: 2, label: 'Jane Smith' },
+  ]);
+
+  const createUser = async (name) => {
+    // Call your API
+    const response = await fetch('/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name })
+    });
+    
+    if (!response.ok) {
+      throw new Error('Failed to create user');
+    }
+    
+    const newUser = await response.json();
+    setAvailableUsers(prev => [...prev, newUser]);
+    return newUser;
+  };
 
+  const deleteUser = async (userId) => {
+    await fetch(`/api/users/${userId}`, { method: 'DELETE' });
+    setAvailableUsers(prev => prev.filter(u => u.key !== userId));
+  };
+
+  return (
+    <ChipInput
+      value={selectedUsers}
+      onValueChange={setSelectedUsers}
+      options={availableUsers}
+      onAddItem={createUser}
+      onDeleteItem={deleteUser}
+      placeholder="Type to create or select users..."
+    />
+  );
+}
+```
+
+### Migration from Legacy onAddNewOption
+```tsx
+// ❌ Old way (still works but deprecated)
+function LegacyExample() {
+  const [tags, setTags] = useState([]);
+  
+  return (
+    <ChipInput
+      value={tags}
+      onValueChange={setTags}
+      onAddNewOption={(value) => {
+        console.log('Added:', value);
+      }}
+    />
+  );
+}
+
+// ✅ New way (recommended)
+function ModernExample() {
+  const [tags, setTags] = useState([]);
+  
   return (
     <ChipInput
       value={tags}
       onValueChange={setTags}
-      placeholder="Add tags..."
+      onAddItem={(value) => ({
+        key: value,
+        label: value
+      })}
     />
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delightui/components",
-  "version": "0.1.122",
+  "version": "0.1.123",
   "private": false,
   "scripts": {
     "start": "vite",