@stackloop/ui 3.3.4 → 4.0.3

package/README.md

@@ -165,6 +165,33 @@ 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`
 
+## 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.
 - **Props:**
@@ -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,18 +293,27 @@ 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.
   - **`onCountryChange`**: `(country: Country) => void` — optional.
+  - **`label`**: `string` — optional.
+  - **`required`**: `boolean` — optional. Shows a required marker (`*`) on label and passes `required` to the inner input.
+  - **`error`**: `string` — optional. Shows error state and helper text.
+  - **`hint`**: `string` — optional. Shown only when `error` is not present.
   - **`searchable`**: `boolean` — default: `true`.
   - **`showFlags`**: `boolean` — default: `true`.
   - **`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
@@ -251,7 +322,9 @@ Components with the `animate` prop:
   <PhoneInput
     label="Phone"
     value={phone}
-    onChange={(dialCode, value) => setPhone(`${dialCode}${value}`)}
+    onChange={setPhone}
+    required
+    hint="Include area code"
     searchable
     autoDetect
   />
@@ -264,11 +337,16 @@ Components with the `animate` prop:
   - **`onChange`**: `(value: string) => void` — optional.
   - **`onCountryChange`**: `(country: Country) => void` — optional.
   - **`label`**: `string` — optional.
+  - **`required`**: `boolean` — optional. Shows a required marker (`*`) and `aria-required` on trigger.
   - **`placeholder`**: `string` — optional.
+  - **`error`**: `string` — optional. Adds error border/ring and error message.
+  - **`hint`**: `string` — optional. Shown only when `error` is not present.
   - **`searchable`**: `boolean` — default: `true`.
   - **`clearable`**: `boolean` — default: `true`.
   - **`showFlags`**: `boolean` — default: `true`.
+  - **`disabled`**: `boolean` — optional.
   - **`animate`**: `boolean` — default: `true`.
+  - **`className`**: `string` — optional.
 - **Usage:**
 
   ```jsx
@@ -278,6 +356,8 @@ Components with the `animate` prop:
     label="Country"
     value={country}
     onChange={setCountry}
+    required
+    hint="Used for regional formatting"
     searchable
   />
   ```
@@ -644,17 +724,35 @@ Components with the `animate` prop:
   ```
 
 **DatePicker**:
-- **Description:** Date picker with month navigation and min/max options.
+- **Description:** Date picker with day grid, min/max date constraints, and fast custom month/year pickers.
 - **Props:**
   - **`value`**: `Date` — optional.
   - **`onChange`**: `(date: Date) => void` — required.
-  - **`label`**, **`placeholder`** (default `'Select date'`), **`error`**, **`disabled`**, **`minDate`**, **`maxDate`**, **`className`**.
+  - **`label`**: `string` — optional.
+  - **`required`**: `boolean` — optional. Shows required marker (`*`) and `aria-required`.
+  - **`placeholder`**: `string` — default: `'Select date'`.
+  - **`error`**: `string` — optional.
+  - **`hint`**: `string` — optional. Shown only when `error` is not present.
+  - **`disabled`**: `boolean` — optional.
+  - **`minDate`** / **`maxDate`**: `Date` — optional.
+  - **`animate`**: `boolean` — default: `true`.
+  - **`className`**: `string` — optional.
+- **Features:**
+  - **Custom Month Menu:** Scrollable month dropdown/dropup (no native browser select).
+  - **Custom Year Menu:** Scrollable year dropdown/dropup that supports quick jumps across many years.
+  - **Adaptive Positioning:** Month/year menus open upward when there is insufficient viewport space below.
 - **Usage:**
 
   ```jsx
   import { DatePicker } from '@stackloop/ui'
 
-  <DatePicker value={date} onChange={setDate} />
+  <DatePicker
+    label="Date of birth"
+    value={date}
+    onChange={setDate}
+    required
+    hint="Choose month/year quickly from the menu"
+  />
   ```
 
 **DualSlider**:

package/dist/CountrySelect.d.ts

@@ -5,7 +5,10 @@ export interface CountrySelectProps {
     onChange?: (value: string) => void;
     onCountryChange?: (country: Country) => void;
     label?: string;
+    required?: boolean;
     placeholder?: string;
+    error?: string;
+    hint?: string;
     searchable?: boolean;
     clearable?: boolean;
     showFlags?: boolean;

package/dist/DatePicker.d.ts

@@ -3,8 +3,10 @@ export interface DatePickerProps {
     value?: Date;
     onChange: (date: Date) => void;
     label?: string;
+    required?: boolean;
     placeholder?: string;
     error?: string;
+    hint?: string;
     disabled?: boolean;
     minDate?: Date;
     maxDate?: Date;

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/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;