@stackloop/ui 4.1.2 → 4.2.1

package/README.md

@@ -225,9 +225,18 @@ Call `setupRippleEffects()` only once per app (for example in `main.tsx`) to avo
 **ButtonGroup**:
 - **Description:** Segmented button group with a rounded outer container and separate buttons divided by borders.
 - **Props:**
-  - **`options`**: `{ value: string; label: string; icon?: ReactNode; disabled?: boolean }[]` — required.
+  - **`options`**: `ButtonGroupOption[]` — required.
+    - `value`: `string` — required unique option value.
+    - `label`: `string` — required fallback text label.
+    - `icon`: `ReactNode` — optional leading icon.
+    - `disabled`: `boolean` — optional per-option disabled state.
+    - `className`: `string` — optional per-option class override.
+    - `ariaLabel`: `string` — optional aria-label for accessibility.
+    - `render`: `(option, state) => ReactNode` — optional custom content renderer. If omitted, the default icon + label layout is used.
+    - `onClick`: `(option, event) => void` — optional per-option click callback.
   - **`value`**: `string` — optional selected value.
   - **`onChange`**: `(value: string) => void` — optional change callback.
+  - **`onOptionClick`**: `(option, index) => void` — optional group-level callback for any option click.
   - **`size`**: `'sm' | 'md' | 'lg'` — default: `'md'`.
   - **`disabled`**: `boolean` — default: `false`.
   - **`className`**: `string` — optional.
@@ -248,6 +257,32 @@ Call `setupRippleEffects()` only once per app (for example in `main.tsx`) to avo
     value={selectedRange}
     onChange={setSelectedRange}
   />
+
+  // Custom render + per-option and group-level click hooks
+  const customOptions = [
+    {
+      label: 'Overview',
+      value: 'overview',
+      render: (option, state) => (
+        <span className="flex flex-col items-start leading-tight">
+          <span className="text-[10px] uppercase tracking-[0.2em] opacity-70">View</span>
+          <span className={state.selected ? 'font-semibold' : 'font-medium'}>{option.label}</span>
+        </span>
+      ),
+      onClick: (option) => console.log('Option clicked:', option.value)
+    },
+    { label: 'Details', value: 'details' },
+    { label: 'Activity', value: 'activity' }
+  ]
+
+  <ButtonGroup
+    options={customOptions}
+    value={selectedView}
+    onChange={setSelectedView}
+    onOptionClick={(option, index) => {
+      console.log('Group handler:', option.value, index)
+    }}
+  />
   ```
 
 **Input**:
@@ -652,20 +687,77 @@ Call `setupRippleEffects()` only once per app (for example in `main.tsx`) to avo
   />
   ```
 
-**Dropdown**:
-- **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.
-  - **`onChange`**: `(value: string) => void` — required.
-  - **`placeholder`**: `string` — default: `'Select an option'`.
-  - **`label`**, **`error`**, **`searchable`** (default `false`), **`clearable`** (default `true`), **`disabled`**, **`className`**.
+**DropdownMenu**:
+- **Description:** Headless-style dropdown menu primitive with custom trigger support, outside-click close behavior, and nested submenus.
+- **Placement behavior:**
+  - Root menu opens **down or up** based on viewport space (or can be forced).
+  - Root menu opens **right or left** based on viewport space and will clamp inside the viewport to avoid horizontal overflow.
+  - Nested submenus open **right or left** based on side space (or can be forced).
+- **Use case:**
+  - Nested navigation or action menus where each menu item can itself open another submenu.
+  - Context menus launched from custom triggers like icon buttons, cards, or toolbar actions.
+- **Core Components:**
+  - **`DropdownMenu`**: Root wrapper with controlled/uncontrolled open state.
+  - **`DropdownMenuTrigger`**: Trigger button or custom trigger with `asChild`.
+  - **`DropdownMenuContent`**: Root menu panel.
+  - **`DropdownMenuItem`**: Clickable item (button or custom child with `asChild`).
+  - **`DropdownMenuSub`**: Nested menu wrapper.
+  - **`DropdownMenuSubTrigger`**: Trigger for nested menu.
+  - **`DropdownMenuSubContent`**: Nested panel.
+- **Root Props (`DropdownMenu`):**
+  - **`open`**: `boolean` — optional controlled state.
+  - **`defaultOpen`**: `boolean` — default: `false`.
+  - **`onOpenChange`**: `(open: boolean) => void` — optional callback.
+  - **`placement`**: `'auto' | 'top' | 'bottom'` — default: `'auto'`.
+  - **`className`**: `string` — optional.
+- **Content Props (`DropdownMenuContent`):**
+  - **`side`**: `'auto' | 'left' | 'right'` — default: `'auto'`. Controls root horizontal direction.
+  - **`align`**: `'start' | 'end'` — default: `'start'`. Used as fallback preference when `side="auto"`.
+  - **`sideOffset`**: `number` — default: `8`. Gap between trigger and content.
 - **Usage:**
 
   ```jsx
-  import { Dropdown } from '@stackloop/ui'
-
-  <Dropdown options={[{value:'a',label:'A'}]} value={val} onChange={setVal} searchable />
+  import {
+    DropdownMenu,
+    DropdownMenuTrigger,
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuSub,
+    DropdownMenuSubTrigger,
+    DropdownMenuSubContent
+  } from '@stackloop/ui'
+
+  <DropdownMenu>
+    <DropdownMenuTrigger>Open menu</DropdownMenuTrigger>
+    <DropdownMenuContent side="auto">
+      <DropdownMenuItem asChild>
+        <a href="/dashboard">Dashboard</a>
+      </DropdownMenuItem>
+
+      <DropdownMenuSub>
+        <DropdownMenuSubTrigger>Products</DropdownMenuSubTrigger>
+        <DropdownMenuSubContent>
+          <DropdownMenuItem asChild>
+            <a href="/products/new">New Arrivals</a>
+          </DropdownMenuItem>
+
+          <DropdownMenuSub>
+            <DropdownMenuSubTrigger>Categories</DropdownMenuSubTrigger>
+            <DropdownMenuSubContent>
+              <DropdownMenuItem asChild>
+                <a href="/products/categories/tools">Tools</a>
+              </DropdownMenuItem>
+              <DropdownMenuItem asChild>
+                <a href="/products/categories/home">Home</a>
+              </DropdownMenuItem>
+            </DropdownMenuSubContent>
+          </DropdownMenuSub>
+        </DropdownMenuSubContent>
+      </DropdownMenuSub>
+
+      <DropdownMenuItem onClick={() => console.log('Signed out')}>Sign out</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
   ```
 
 **Tooltip**:
@@ -695,7 +787,7 @@ Call `setupRippleEffects()` only once per app (for example in `main.tsx`) to avo
   ```
 
 **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.).
+- **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. It includes form-focused features like `required`, 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.

package/dist/ButtonGroup.d.ts

@@ -4,11 +4,20 @@ export interface ButtonGroupOption {
     label: string;
     icon?: React.ReactNode;
     disabled?: boolean;
+    className?: string;
+    ariaLabel?: string;
+    render?: (option: ButtonGroupOption, state: {
+        selected: boolean;
+        disabled: boolean;
+        index: number;
+    }) => React.ReactNode;
+    onClick?: (option: ButtonGroupOption, event: React.MouseEvent<HTMLButtonElement>) => void;
 }
 export interface ButtonGroupProps {
     options: ButtonGroupOption[];
     value?: string;
     onChange?: (value: string) => void;
+    onOptionClick?: (option: ButtonGroupOption, index: number) => void;
     size?: 'sm' | 'md' | 'lg';
     disabled?: boolean;
     className?: string;

package/dist/DropdownMenu.d.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+import { type HTMLMotionProps } from 'framer-motion';
+type RootVerticalPlacement = 'auto' | 'top' | 'bottom';
+type RootHorizontalPlacement = 'auto' | 'left' | 'right';
+type SubmenuHorizontalPlacement = 'auto' | 'left' | 'right';
+export interface DropdownMenuProps {
+    children: React.ReactNode;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    placement?: RootVerticalPlacement;
+    className?: string;
+}
+export declare const DropdownMenu: React.FC<DropdownMenuProps>;
+export interface DropdownMenuTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    asChild?: boolean;
+    children: React.ReactNode;
+}
+export declare const DropdownMenuTrigger: React.ForwardRefExoticComponent<DropdownMenuTriggerProps & React.RefAttributes<HTMLElement>>;
+export interface DropdownMenuContentProps extends Omit<HTMLMotionProps<'div'>, 'children'> {
+    children: React.ReactNode;
+    align?: 'start' | 'end';
+    side?: RootHorizontalPlacement;
+    sideOffset?: number;
+    animate?: boolean;
+}
+export declare const DropdownMenuContent: React.FC<DropdownMenuContentProps>;
+export interface DropdownMenuItemProps extends React.HTMLAttributes<HTMLElement> {
+    children: React.ReactNode;
+    asChild?: boolean;
+    disabled?: boolean;
+    closeOnSelect?: boolean;
+}
+export declare const DropdownMenuItem: React.ForwardRefExoticComponent<DropdownMenuItemProps & React.RefAttributes<HTMLElement>>;
+export interface DropdownMenuSubProps {
+    children: React.ReactNode;
+    defaultOpen?: boolean;
+    placement?: SubmenuHorizontalPlacement;
+}
+export declare const DropdownMenuSub: React.FC<DropdownMenuSubProps>;
+export interface DropdownMenuSubTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    asChild?: boolean;
+    children: React.ReactNode;
+}
+export declare const DropdownMenuSubTrigger: React.ForwardRefExoticComponent<DropdownMenuSubTriggerProps & React.RefAttributes<HTMLElement>>;
+export interface DropdownMenuSubContentProps extends Omit<HTMLMotionProps<'div'>, 'children'> {
+    children: React.ReactNode;
+    sideOffset?: number;
+    animate?: boolean;
+}
+export declare const DropdownMenuSubContent: React.FC<DropdownMenuSubContentProps>;
+export {};