@stackloop/ui 3.3.5 → 4.0.4

package/README.md

@@ -163,7 +163,34 @@ import { Button, Modal } from '@stackloop/ui'
 
 Components with the `animate` prop:
 
-- `AudioRecorder`, `Badge`, `BottomSheet`, `Button`, `Card`, `CameraCapture`, `Checkbox`, `CountrySelect`, `DatePicker`, `Drawer`, `Dropdown`, `DualSlider`, `FileUploader`, `FloatingActionButton`, `Input`, `Modal`, `Pagination`, `PhoneInput`, `RadioPills`, `Select`, `Slider`, `Spinner`, `StepProgress`, `Table`, `Textarea`, `ThumbnailGrid`, `Toggle`, `ToastProvider`
+- `AudioRecorder`, `Badge`, `BottomSheet`, `Button`, `Card`, `CameraCapture`, `Checkbox`, `CountrySelect`, `DatePicker`, `Drawer`, `Dropdown`, `DualSlider`, `FileUploader`, `FloatingActionButton`, `Input`, `Modal`, `MultiSelect`, `Pagination`, `PhoneInput`, `RadioPills`, `Select`, `Slider`, `Spinner`, `StepProgress`, `Table`, `Textarea`, `ThumbnailGrid`, `Toggle`, `ToastProvider`
+
+## Ripple Behavior
+
+Ripple effects are **opt-in**. Initialize them once in your app entry file.
+
+```tsx
+// main.tsx or index.tsx
+import { setupRippleEffects } from '@stackloop/ui'
+
+setupRippleEffects()
+```
+
+After setup, ripple can apply to interactive elements (`button`, `a`, `[role="button"]`, and elements with `data-ripple="true"`).
+
+- Disable ripple for a specific element:
+
+  ```html
+  <button data-ripple="false">No ripple</button>
+  ```
+
+- Force ripple on a custom/non-button element:
+
+  ```html
+  <div role="button" data-ripple="true">Ripple enabled</div>
+  ```
+
+Call `setupRippleEffects()` only once per app (for example in `main.tsx`) to avoid duplicate global listeners.
 
 **Checkbox**:
 - **Description:** Accessible checkbox with optional label and description.
@@ -199,16 +226,25 @@ Components with the `animate` prop:
   ```
 
 **Input**:
-- **Description:** Text input with label, error and optional icons. Includes automatic password visibility toggle for password inputs.
+- **Description:** Unified input API with smart type routing. Supports native text/password/email/etc plus `phone`, `country`, and `date` while keeping a consistent `value` + `onChange` pattern.
 - **Props:**
+  - **`type`**: Native HTML input types plus `'phone' | 'country'`.
+    - `type="date"` renders the library `DatePicker`.
+    - `type="country"` renders `CountrySelect`.
+    - `type="phone"` renders `PhoneInput`.
+  - **`value`**: `string | number | readonly string[] | Date`.
+  - **`onChange`**: `(value: string | Date) => void` — value-based callback used consistently across smart/native modes.
+  - **`onValueChange`**: `(value: string | Date) => void` — optional backward-compatible alias.
   - **`label`**: `string` — optional.
   - **`error`**: `string` — optional.
   - **`hint`**: `string` — optional.
   - **`leftIcon`** / **`rightIcon`**: `ReactNode` — optional.
   - **`className`**: `string` — optional.
-  - Inherits `input` HTML attributes.
+  - Inherits most `input` HTML attributes.
 - **Features:**
   - **Password Toggle:** When `type="password"`, automatically displays an Eye/EyeOff icon to toggle password visibility. This overrides any custom `rightIcon`.
+  - **Consistent Value API:** Same controlled pattern for text, phone, country, and date.
+  - **Lightweight Composition:** Smart types reuse existing specialized components instead of duplicating logic.
   - **Icon Support:** Display icons on left or right side of input
   - **Validation:** Built-in error and hint display
   - **Accessibility:** Proper labels and ARIA attributes
@@ -221,6 +257,32 @@ Components with the `animate` prop:
   
   // Password with automatic toggle
   <Input label="Password" type="password" placeholder="Enter password" />
+
+  // Phone (single combined value)
+  <Input
+    label="Phone"
+    type="phone"
+    value={phone}
+    onChange={(nextValue) => setPhone(String(nextValue))}
+  />
+
+  // Country
+  <Input
+    label="Country"
+    type="country"
+    value={country}
+    onChange={(nextValue) => setCountry(String(nextValue))}
+  />
+
+  // Date
+  <Input
+    label="Date"
+    type="date"
+    value={selectedDate}
+    onChange={(nextValue) => {
+      if (nextValue instanceof Date) setSelectedDate(nextValue)
+    }}
+  />
   
   // With icons
   <Input 
@@ -231,10 +293,10 @@ Components with the `animate` prop:
   ```
 
 **PhoneInput**:
-- **Description:** Phone number input with a country calling code selector and optional locale-based default.
+- **Description:** Phone input with country selector and a single editable value field (country code + number in the same input).
 - **Props:**
   - **`value`**: `string` — optional.
-  - **`onChange`**: `(dialCode: string, value: string) => void` — optional.
+  - **`onChange`**: `(value: string) => void` — optional.
   - **`country`**: `string` — optional ISO2 override (e.g. `US`).
   - **`defaultCountry`**: `string` — default: `'US'`.
   - **`autoDetect`**: `boolean` — default: `true`. Uses `navigator.language` to select a country.
@@ -248,6 +310,10 @@ Components with the `animate` prop:
   - **`animate`**: `boolean` — default: `true`.
   - **`className`**: `string` — optional.
   - Inherits standard `input` HTML attributes.
+- **Behavior:**
+  - Default selected country auto-fills dial code when the input is empty.
+  - User can edit/delete the dial code directly in the same input.
+  - Dropdown opens up or down based on available viewport space.
 - **Usage:**
 
   ```jsx
@@ -256,7 +322,7 @@ Components with the `animate` prop:
   <PhoneInput
     label="Phone"
     value={phone}
-    onChange={(dialCode, value) => setPhone(`${dialCode}${value}`)}
+    onChange={setPhone}
     required
     hint="Include area code"
     searchable
@@ -640,6 +706,108 @@ Components with the `animate` prop:
   />
   ```
 
+**MultiSelect**:
+- **Description:** Multi-select component that allows selecting multiple items with chips display. Each selected item appears as a removable chip with an X button. Perfect for selecting multiple options like staff members, tags, skills, etc.
+- **Props:**
+  - **`options`**: `{ value: string; label: string; icon?: ReactNode; disabled?: boolean }[]` — required. Array of selectable options with optional icons and disabled state.
+  - **`value`**: `string[]` — optional. Array of currently selected values (default: `[]`).
+  - **`onChange`**: `(values: string[]) => void` — required. Callback fired when selections change, receives array of selected values.
+  - **`placeholder`**: `string` — default: `'Select options...'`. Shown when no items are selected.
+  - **`label`**: `string` — optional. Label displayed above the multi-select.
+  - **`error`**: `string` — optional. Error message displayed below with error styling.
+  - **`hint`**: `string` — optional. Helper text displayed below when no error is present.
+  - **`searchable`**: `boolean` — default: `false`. Enables search input to filter options.
+  - **`clearable`**: `boolean` — default: `true`. Shows "Clear all" option in dropdown when items are selected.
+  - **`maxItems`**: `number` — optional. Maximum number of items that can be selected.
+  - **`chipVariant`**: `'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'` — default: `'primary'`. Styles for the selected item chips.
+  - **`required`**: `boolean` — optional. Displays asterisk (*) next to label and sets aria-required.
+  - **`disabled`**: `boolean` — optional. Disables the multi-select.
+  - **`className`**: `string` — optional. Additional CSS classes for the wrapper.
+- **Features:**
+  - **Chips Display:** Selected items show as removable chips with X buttons inline in the button
+  - **Multi-Select:** Choose multiple items from a list with checkboxes in the dropdown
+  - **Form Integration:** Works seamlessly with form libraries (React Hook Form, Formik, etc.)
+  - **Validation Support:** Built-in error and hint display with animated transitions
+  - **Accessibility:** Full ARIA attributes, keyboard navigation, and screen reader support
+  - **Search:** Optional searchable mode with real-time filtering across all options
+  - **Icons:** Support for icons in options for better visual recognition
+  - **Disabled Options:** Individual options can be disabled
+  - **Max Items:** Optional limit on the number of items that can be selected
+  - **Clear All:** "Clear all" button in dropdown to remove all selected items at once
+  - **Remove Individual:** Click X on any chip to remove just that item
+  - **Touch-Friendly:** Optimized for mobile with proper touch targets
+- **Usage:**
+
+  ```jsx
+  import { MultiSelect } from '@stackloop/ui'
+  import { Users, Award, Code } from 'lucide-react'
+
+  // Basic multi-select for team members
+  const [selectedStaff, setSelectedStaff] = useState<string[]>([])
+
+  <MultiSelect 
+    label="Select Staff Members"
+    options={[
+      { value: 'john', label: 'John Doe' },
+      { value: 'jane', label: 'Jane Smith' },
+      { value: 'bob', label: 'Bob Johnson' }
+    ]} 
+    value={selectedStaff}
+    onChange={setSelectedStaff}
+    placeholder="Choose staff members..."
+    required
+  />
+
+  // With icons and search
+  <MultiSelect 
+    label="Skills"
+    options={[
+      { value: 'react', label: 'React', icon: <Code /> },
+      { value: 'vue', label: 'Vue.js', icon: <Code /> },
+      { value: 'angular', label: 'Angular', icon: <Code /> },
+      { value: 'node', label: 'Node.js', icon: <Code /> }
+    ]}
+    value={skills}
+    onChange={setSkills}
+    searchable
+    placeholder="Select your skills"
+  />
+
+  // With max items limit and chip styling
+  <MultiSelect 
+    label="Team Members (Max 5)"
+    options={teamMembers}
+    value={selectedTeam}
+    onChange={setSelectedTeam}
+    maxItems={5}
+    chipVariant="primary"
+    error={errors.team}
+    hint="Select up to 5 team members for this project"
+  />
+
+  // With React Hook Form
+  import { useForm, Controller } from 'react-hook-form'
+
+  const { control, formState: { errors } } = useForm()
+
+  <Controller
+    name="assignees"
+    control={control}
+    rules={{ validate: (v) => v?.length > 0 || 'Please select at least one assignee' }}
+    render={({ field }) => (
+      <MultiSelect
+        label="Assign to"
+        options={users}
+        value={field.value || []}
+        onChange={field.onChange}
+        error={errors.assignees?.message}
+        searchable
+        required
+      />
+    )}
+  />
+  ```
+
 **BottomSheet**:
 - **Description:** Mobile bottom sheet with header and optional close button.
 - **Props:**

package/dist/FloatingPortal.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+interface FloatingPortalProps {
+    open: boolean;
+    anchorRef: React.RefObject<HTMLElement | null>;
+    placement: 'top' | 'bottom';
+    children: React.ReactNode;
+    className?: string;
+    offset?: number;
+    matchWidth?: boolean;
+}
+export declare const FloatingPortal: React.FC<FloatingPortalProps>;
+export {};

package/dist/Input.d.ts

@@ -1,5 +1,10 @@
 import React from 'react';
-export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+type SmartInputType = React.HTMLInputTypeAttribute | 'country' | 'phone';
+export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'value' | 'onChange'> {
+    type?: SmartInputType;
+    value?: string | number | readonly string[] | Date;
+    onChange?: (value: string | Date) => void;
+    onValueChange?: (value: string | Date) => void;
     label?: string;
     error?: string;
     hint?: string;
@@ -8,3 +13,4 @@ export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement>
     animate?: boolean;
 }
 export declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/MultiSelect.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+export interface MultiSelectOption {
+    value: string;
+    label: string;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+}
+export interface MultiSelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'onChange' | 'size'> {
+    options: MultiSelectOption[];
+    value?: string[];
+    onChange: (values: string[]) => void;
+    placeholder?: string;
+    label?: string;
+    error?: string;
+    hint?: string;
+    searchable?: boolean;
+    clearable?: boolean;
+    maxItems?: number;
+    className?: string;
+    animate?: boolean;
+    chipVariant?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+}
+export declare const MultiSelect: React.ForwardRefExoticComponent<MultiSelectProps & React.RefAttributes<HTMLDivElement>>;

package/dist/PhoneInput.d.ts

@@ -2,7 +2,7 @@ import React from 'react';
 import { type Country } from './countries';
 export interface PhoneInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange'> {
     value?: string;
-    onChange?: (dialCode: string, value: string) => void;
+    onChange?: (value: string) => void;
     country?: string;
     defaultCountry?: string;
     autoDetect?: boolean;

package/dist/Toast.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-export type ToastVariant = 'success' | 'error' | 'warning' | 'info' | 'default';
+export type ToastVariant = 'success' | 'error' | 'warning' | 'info' | 'default' | 'loading';
 export type ToastPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 export interface Toast {
     id: string;