

<Preview name="BasicSelectionToolbarExample" />

## Overview [#overview]

`SelectionToolbar` surfaces bulk actions for selected rows or items. It renders as a floating contextual surface and composes Cubitt `Button`, `Menu`, and `Popover` parts for actions.

## Usage [#usage]

```tsx
import {
  SelectionToolbar,
  type SelectionAction,
} from "@tilt-legal/cubitt-components/selection-toolbar";
```

## Examples [#examples]

### Basic [#basic]

A floating toolbar with direct actions, confirmation, success, and clear selection behavior.

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="BasicSelectionToolbarExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    import { Button } from "@tilt-legal/cubitt-components/button";
    import { SelectionToolbar } from "@tilt-legal/cubitt-components/selection-toolbar";
    import {
      Archive,
      PenWriting,
      Trash2,
    } from "@tilt-legal/cubitt-icons/ui/outline";
    import { useState } from "react";

    export default function Component() {
      const [selectedCount, setSelectedCount] = useState(3);

      const actions = [
        {
          id: "edit",
          label: "Edit",
          icon: PenWriting,
          onClick: async () => {},
          successMessage: "Items updated successfully",
        },
        {
          id: "archive",
          label: "Archive",
          icon: Archive,
          onClick: async () => {},
          successMessage: "Items archived",
        },
        {
          id: "delete",
          label: "Delete",
          icon: Trash2,
          variant: "destructive" as const,
          confirmationMessage: `Are you sure you want to delete ${selectedCount} item(s)?`,
          confirmText: "Delete",
          onClick: async () => {},
          successMessage: "Items deleted successfully",
        },
      ];

      return (
        <div className="relative h-24">
          <SelectionToolbar
            actions={actions}
            onClear={() => setSelectedCount(0)}
            position="container"
            selectedCount={selectedCount}
            totalCount={10}
          />
          <Button
            onClick={() => setSelectedCount(selectedCount > 0 ? 0 : 3)}
            size="sm"
            variant="secondary"
          >
            {selectedCount > 0 ? "Clear selection" : "Select items"}
          </Button>
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

### Button Actions [#button-actions]

Actions can be disabled while still remaining in the toolbar layout.

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="AdvancedSelectionToolbarExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    const actions = [
      {
        id: "duplicate",
        label: "Duplicate",
        icon: Copy,
        onClick: async () => {},
        successMessage: "Items duplicated successfully",
      },
      {
        id: "edit",
        label: "Edit",
        icon: PenWriting,
        disabled: selectedCount > 5,
        onClick: async () => {},
        successMessage: "Items updated",
      },
      {
        id: "delete",
        label: "Delete",
        icon: Trash2,
        variant: "destructive",
        confirmationMessage: `Are you sure you want to delete ${selectedCount} item(s)?`,
        onClick: async () => {},
      },
    ];
    ```
  </Tab>
</Tabs>

### Dropdown Actions [#dropdown-actions]

Use a dropdown action when selected items share several related bulk actions.

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="DropdownActionsSelectionToolbarExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    const actions = [
      {
        id: "bulk-actions",
        label: "Bulk Actions",
        type: "dropdown",
        icon: Dots,
        items: [
          {
            id: "archive",
            label: "Archive Items",
            icon: Archive,
            onClick: async () => {},
            successMessage: "Items archived successfully",
          },
          {
            id: "delete",
            label: "Delete Permanently",
            icon: Trash2,
            destructive: true,
            confirmationMessage: "This action cannot be undone. Are you sure?",
            confirmText: "Delete",
            onClick: async () => {},
          },
        ],
      },
    ];
    ```
  </Tab>
</Tabs>

### Custom Text [#custom-text]

Override the selection copy when the toolbar needs to summarize selected data.

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="CustomTextSelectionToolbarExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    <SelectionToolbar
      actions={actions}
      onClear={() => setSelectedCount(0)}
      position="container"
      selectedCount={selectedCount}
      selectionText={`${selectedCount} items selected`}
      totalCount={totalCount}
    />
    ```
  </Tab>
</Tabs>

### Popover Action [#popover-action]

Popover actions can render custom controls while still reporting processing, success, and error states through the toolbar.

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="ColorPickerSelectionToolbarExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    const actions = [
      {
        id: "color-picker",
        label: "Set Color",
        type: "popover",
        icon: Palette,
        popoverContent: ({ onProcessing, onSuccess, onError, onClose }) => (
          <div className="grid grid-cols-5 gap-2.5 p-4">
            {colors.map((color) => (
              <button
                key={color.name}
                onClick={async () => {
                  try {
                    onClose();
                    onProcessing();
                    await applyColor(color);
                    onSuccess(`${color.name} applied`);
                  } catch {
                    onError("Failed to apply color");
                  }
                }}
                style={{ backgroundColor: color.hex }}
                type="button"
              />
            ))}
          </div>
        ),
      },
    ];
    ```
  </Tab>
</Tabs>

## API Reference [#api-reference]

### SelectionToolbar [#selectiontoolbar]

| Prop              | Type                                      | Default                                      | Description                                                           |
| ----------------- | ----------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
| `selectedCount`   | `number`                                  | -                                            | Number of selected items.                                             |
| `totalCount`      | `number`                                  | -                                            | Total number of items in the selectable set.                          |
| `actions`         | `SelectionAction[]`                       | -                                            | Actions rendered after the selection summary.                         |
| `onClear`         | `() => void`                              | -                                            | Called when the clear selection button is activated.                  |
| `isVisible`       | `boolean`                                 | `selectedCount > 0`                          | Controls toolbar visibility.                                          |
| `selectionText`   | `string`                                  | `"{selectedCount} of {totalCount} selected"` | Custom summary text.                                                  |
| `position`        | `"container" \| "viewport"`               | `"viewport"`                                 | Positions the toolbar relative to its parent or the browser viewport. |
| `variant`         | `"default" \| "destructive" \| "success"` | `"default"`                                  | Visual state for the toolbar surface.                                 |
| `size`            | `"sm" \| "md" \| "lg"`                    | `"md"`                                       | Controls toolbar segment and action button sizing.                    |
| `successDuration` | `number`                                  | `2000`                                       | Milliseconds to show success or error feedback.                       |
| `children`        | `ReactNode`                               | -                                            | Additional content rendered beside the selection summary.             |
| `className`       | `string`                                  | -                                            | Additional classes for the toolbar root.                              |

### SelectionAction [#selectionaction]

| Prop                  | Type                                  | Description                                                     |
| --------------------- | ------------------------------------- | --------------------------------------------------------------- |
| `id`                  | `string`                              | Stable action identifier.                                       |
| `label`               | `string`                              | Visible action label.                                           |
| `type`                | `"button" \| "dropdown" \| "popover"` | Action presentation. Defaults to a direct button.               |
| `icon`                | `ElementType`                         | Optional icon component.                                        |
| `onClick`             | `() => void \| Promise<void>`         | Handler for button actions.                                     |
| `variant`             | `Button` variant                      | Visual style for the action trigger. Defaults to `ghost`.       |
| `disabled`            | `boolean`                             | Disables the action.                                            |
| `successMessage`      | `string`                              | Message shown after a successful action.                        |
| `confirmationMessage` | `string`                              | Message shown before executing the action.                      |
| `confirmText`         | `string`                              | Confirmation button text.                                       |
| `cancelText`          | `string`                              | Cancel button text.                                             |
| `iconProps`           | `object`                              | Additional icon props.                                          |
| `items`               | `SelectionDropdownItem[]`             | Dropdown items for `type="dropdown"`.                           |
| `popoverContent`      | `ReactNode \| (helpers) => ReactNode` | Popover content for `type="popover"`.                           |
| `popoverProps`        | `object`                              | Alignment, side, offset, and class options for popover content. |

### SelectionDropdownItem [#selectiondropdownitem]

| Prop                  | Type                          | Description                                     |
| --------------------- | ----------------------------- | ----------------------------------------------- |
| `id`                  | `string`                      | Stable item identifier.                         |
| `label`               | `string`                      | Visible item label.                             |
| `icon`                | `ElementType`                 | Optional icon component.                        |
| `onClick`             | `() => void \| Promise<void>` | Item action handler.                            |
| `disabled`            | `boolean`                     | Disables the item.                              |
| `destructive`         | `boolean`                     | Styles the item as destructive.                 |
| `successMessage`      | `string`                      | Message shown after a successful item action.   |
| `confirmationMessage` | `string`                      | Message shown before executing the item action. |
| `confirmText`         | `string`                      | Confirmation button text.                       |
| `cancelText`          | `string`                      | Cancel button text.                             |
| `iconProps`           | `object`                      | Additional icon props.                          |