@stackloop/ui 1.0.10 → 2.0.1

package/README.md

@@ -181,7 +181,7 @@ You can add dark mode variants:
   ```
 
 **Input**:
-- **Description:** Text input with label, error and optional icons.
+- **Description:** Text input with label, error and optional icons. Includes automatic password visibility toggle for password inputs.
 - **Props:**
   - **`label`**: `string` — optional.
   - **`error`**: `string` — optional.
@@ -189,12 +189,27 @@ You can add dark mode variants:
   - **`leftIcon`** / **`rightIcon`**: `ReactNode` — optional.
   - **`className`**: `string` — optional.
   - Inherits `input` HTML attributes.
+- **Features:**
+  - **Password Toggle:** When `type="password"`, automatically displays an Eye/EyeOff icon to toggle password visibility. This overrides any custom `rightIcon`.
+  - **Icon Support:** Display icons on left or right side of input
+  - **Validation:** Built-in error and hint display
+  - **Accessibility:** Proper labels and ARIA attributes
 - **Usage:**
 
   ```jsx
   import { Input } from '@stackloop/ui'
 
   <Input label="Email" placeholder="you@example.com" />
+  
+  // Password with automatic toggle
+  <Input label="Password" type="password" placeholder="Enter password" />
+  
+  // With icons
+  <Input 
+    label="Search" 
+    leftIcon={<Search />} 
+    placeholder="Search..." 
+  />
   ```
 
 **Modal**:
@@ -436,7 +451,7 @@ You can add dark mode variants:
   ```
 
 **Dropdown**:
-- **Description:** Select with optional search, clear and icons.
+- **Description:** General-purpose select component with optional search, clear, and icons. Use this for general UI selections outside of forms. For form-specific needs with validation, use the **Select** component instead.
 - **Props:**
   - **`options`**: `{ value: string; label: string; icon?: ReactNode }[]` — required.
   - **`value`**: `string` — optional.
@@ -451,6 +466,96 @@ You can add dark mode variants:
   <Dropdown options={[{value:'a',label:'A'}]} value={val} onChange={setVal} searchable />
   ```
 
+**Select**:
+- **Description:** **Form-specific** select component with label, error, hint, and validation support. Specifically designed for use in forms with proper semantics, accessibility, and validation integration. Use this component when building forms. For general UI selections (navigation, filters, etc.), use the **Dropdown** component instead. Based on Dropdown but includes form-specific features like `required` prop, hint text, and better integration with form libraries (React Hook Form, Formik, 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. Currently selected value.
+  - **`onChange`**: `(value: string) => void` — required. Callback fired when selection changes.
+  - **`placeholder`**: `string` — default: `'Select an option'`. Shown when no value is selected.
+  - **`label`**: `string` — optional. Label displayed above the select.
+  - **`error`**: `string` — optional. Error message displayed below select with error styling.
+  - **`hint`**: `string` — optional. Helper text displayed below select when no error is present.
+  - **`searchable`**: `boolean` — default: `false`. Enables search input to filter options.
+  - **`clearable`**: `boolean` — default: `true`. Shows clear button when value is selected.
+  - **`required`**: `boolean` — optional. Displays asterisk (*) next to label and sets aria-required.
+  - **`disabled`**: `boolean` — optional. Disables the select.
+  - **`className`**: `string` — optional. Additional CSS classes for the wrapper.
+- **Features:**
+  - **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
+  - **Icons:** Support for icons in options for better visual recognition
+  - **Disabled Options:** Individual options can be disabled while keeping select active
+  - **Clearable:** Optional clear button to reset selection
+  - **Touch-Friendly:** Optimized for mobile with proper touch targets
+- **Usage:**
+
+  ```jsx
+  import { Select } from '@stackloop/ui'
+  import { User, Settings, Bell } from 'lucide-react'
+
+  // Basic usage
+  <Select 
+    label="Country"
+    options={[
+      { value: 'us', label: 'United States' },
+      { value: 'uk', label: 'United Kingdom' },
+      { value: 'ca', label: 'Canada' }
+    ]} 
+    value={country} 
+    onChange={setCountry}
+    required
+  />
+
+  // With icons and search
+  <Select 
+    label="Navigation"
+    options={[
+      { value: 'profile', label: 'Profile', icon: <User /> },
+      { value: 'settings', label: 'Settings', icon: <Settings /> },
+      { value: 'notifications', label: 'Notifications', icon: <Bell />, disabled: true }
+    ]}
+    value={selected}
+    onChange={setSelected}
+    searchable
+    placeholder="Choose a page"
+  />
+
+  // With error and hint
+  <Select 
+    label="Payment Method"
+    options={paymentMethods}
+    value={payment}
+    onChange={setPayment}
+    error={errors.payment}
+    hint="Select your preferred payment method"
+    required
+  />
+
+  // With React Hook Form
+  import { useForm, Controller } from 'react-hook-form'
+
+  const { control, formState: { errors } } = useForm()
+
+  <Controller
+    name="category"
+    control={control}
+    rules={{ required: 'Category is required' }}
+    render={({ field }) => (
+      <Select
+        label="Category"
+        options={categories}
+        value={field.value}
+        onChange={field.onChange}
+        error={errors.category?.message}
+        required
+      />
+    )}
+  />
+  ```
+
 **BottomSheet**:
 - **Description:** Mobile bottom sheet with header and optional close button.
 - **Props:**
@@ -528,6 +633,129 @@ You can add dark mode variants:
   <Badge variant="primary">New</Badge>
   ```
 
+**Spinner**:
+- **Description:** Animated loading spinner with size variants and optional label.
+- **Props:**
+  - **`size`**: `'sm' | 'md' | 'lg' | 'xl'` — default: `'md'`. Controls spinner dimensions (sm=16px, md=32px, lg=48px, xl=64px).
+  - **`variant`**: `'primary' | 'secondary' | 'white'` — default: `'primary'`. Color variant of the spinner.
+  - **`label`**: `string` — optional. Text displayed below spinner.
+  - **`className`**: `string` — optional. Additional CSS classes for the wrapper.
+- **Usage:**
+
+  ```jsx
+  import { Spinner } from '@stackloop/ui'
+
+  // Basic spinner
+  <Spinner />
+
+  // With label
+  <Spinner label="Loading..." />
+
+  // Custom size and variant
+  <Spinner size="lg" variant="white" />
+
+  // In a button
+  <Button disabled>
+    <Spinner size="sm" variant="white" label="Processing..." />
+  </Button>
+  ```
+
+**Toast**:
+- **Description:** Context-based toast notification system with variants, actions, and customizable positioning. Provides non-intrusive feedback messages that auto-dismiss.
+- **Components:**
+  - **`ToastProvider`**: Wrapper component that manages toast state and rendering. Must wrap your app or components that use toasts.
+  - **`useToast`**: Hook to trigger toasts from any component within the provider.
+- **ToastProvider Props:**
+  - **`children`**: `ReactNode` — required. Your app content.
+  - **`position`**: `'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'` — default: `'top-right'`. Where toasts appear on screen.
+  - **`maxToasts`**: `number` — default: `5`. Maximum number of toasts shown at once.
+- **useToast() Returns:**
+  - **`addToast(toast)`**: Function to create a new toast notification.
+  - **`removeToast(id)`**: Function to manually dismiss a toast.
+  - **`toasts`**: Array of currently active toasts.
+- **Toast Object:**
+  - **`message`**: `string` — required. Toast content text.
+  - **`variant`**: `'success' | 'error' | 'warning' | 'info' | 'default'` — optional (default: `'default'`). Visual style with corresponding icon.
+  - **`duration`**: `number` — optional (default: `5000`ms). Auto-dismiss time in milliseconds. Set to `0` for persistent toast.
+  - **`action`**: `{ label: string; onClick: () => void }` — optional. Action button within the toast.
+- **Features:**
+  - **Auto-dismiss**: Toasts automatically disappear after duration
+  - **Manual dismiss**: Click X button or call `removeToast(id)`
+  - **Variants with icons**: Visual feedback with CheckCircle, AlertCircle, AlertTriangle, Info icons
+  - **Action buttons**: Add clickable actions to toasts
+  - **Animations**: Smooth enter/exit animations with Framer Motion
+  - **Position control**: Place toasts anywhere on screen
+  - **Max limit**: Prevents toast overflow
+  - **Responsive**: Adapts to mobile screens
+- **Usage:**
+
+  ```jsx
+  import { ToastProvider, useToast } from '@stackloop/ui'
+
+  // 1. Wrap your app with ToastProvider
+  function App() {
+    return (
+      <ToastProvider position="top-right" maxToasts={5}>
+        <YourApp />
+      </ToastProvider>
+    )
+  }
+
+  // 2. Use toasts in any component
+  function MyComponent() {
+    const { addToast } = useToast()
+
+    const handleSuccess = () => {
+      addToast({
+        message: 'Profile updated successfully!',
+        variant: 'success',
+        duration: 3000
+      })
+    }
+
+    const handleError = () => {
+      addToast({
+        message: 'Failed to save changes',
+        variant: 'error',
+        duration: 5000
+      })
+    }
+
+    const handleWithAction = () => {
+      addToast({
+        message: 'New message received',
+        variant: 'info',
+        duration: 0, // Persistent until dismissed
+        action: {
+          label: 'View',
+          onClick: () => navigate('/messages')
+        }
+      })
+    }
+
+    const handleWarning = () => {
+      addToast({
+        message: 'Your session will expire in 5 minutes',
+        variant: 'warning'
+      })
+    }
+
+    return (
+      <div>
+        <Button onClick={handleSuccess}>Save</Button>
+        <Button onClick={handleError}>Trigger Error</Button>
+        <Button onClick={handleWithAction}>Show Notification</Button>
+        <Button onClick={handleWarning}>Show Warning</Button>
+      </div>
+    )
+  }
+
+  // 3. Bottom-centered positioning
+  <ToastProvider position="bottom-center">
+    <App />
+  </ToastProvider>
+  ```
+
 **FloatingActionButton (FAB)**:
 - **Description:** Floating action button with expanded action list support.
 - **Props:**

package/dist/Select.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+export interface SelectOption {
+    value: string;
+    label: string;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+}
+export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'onChange' | 'size'> {
+    options: SelectOption[];
+    value?: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    label?: string;
+    error?: string;
+    hint?: string;
+    searchable?: boolean;
+    clearable?: boolean;
+    className?: string;
+}
+export declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLDivElement>>;

package/dist/Spinner.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+export interface SpinnerProps {
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    variant?: 'primary' | 'secondary' | 'white';
+    className?: string;
+    label?: string;
+}
+export declare const Spinner: React.FC<SpinnerProps>;

package/dist/Toast.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+export type ToastVariant = 'success' | 'error' | 'warning' | 'info' | 'default';
+export type ToastPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+export interface Toast {
+    id: string;
+    message: string;
+    variant?: ToastVariant;
+    duration?: number;
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+interface ToastContextType {
+    toasts: Toast[];
+    addToast: (toast: Omit<Toast, 'id'>) => void;
+    removeToast: (id: string) => void;
+}
+export declare const useToast: () => ToastContextType;
+interface ToastProviderProps {
+    children: React.ReactNode;
+    position?: ToastPosition;
+    maxToasts?: number;
+}
+export declare const ToastProvider: React.FC<ToastProviderProps>;
+export {};