## Overview [#overview]

`Document.Toolbar` provides shared toolbar components that can be used across different document features (annotations, editing, etc.). The toolbar appears contextually based on user interactions like text selection.

## Document.Toolbar.Selection [#documenttoolbarselection]

Floating toolbar that appears when text is selected in the document.

```tsx
<Document.Toolbar.Selection>
  <Document.Annotation.AddButton />
</Document.Toolbar.Selection>
```

### Props [#props]

| Prop        | Type        | Description                |
| ----------- | ----------- | -------------------------- |
| `className` | `string`    | Additional classes         |
| `children`  | `ReactNode` | Toolbar content (required) |

### Behavior [#behavior]

* Appears above the text selection on mouse release (not during drag)
* Automatically positions to stay within viewport
* Hidden when selection is cleared or an action is taken

### Combining Features [#combining-features]

The toolbar can contain actions from multiple features:

```tsx
<Document.Toolbar.Selection>
  <Document.Annotation.AddButton />
  {/* Future: <Document.Editing.FormatButton /> */}
</Document.Toolbar.Selection>
```

### Hooks [#hooks]

#### useSelectionToolbarContext [#useselectiontoolbarcontext]

Access toolbar actions from within the toolbar. Available inside `Document.Toolbar.Selection`.

```tsx
import { useSelectionToolbarContext } from "@tilt-legal/cubitt-components/composites";

function CustomToolbarButton() {
  const context = useSelectionToolbarContext();

  return (
    <button
      onClick={() => {
        doSomething();
        context?.hideToolbar();
      }}
    >
      Custom Action
    </button>
  );
}
```

| Property      | Type         | Description      |
| ------------- | ------------ | ---------------- |
| `hideToolbar` | `() => void` | Hide the toolbar |

#### useSelectionToolbar [#useselectiontoolbar]

Low-level hook for building completely custom selection toolbars. Takes the TipTap editor instance.

```tsx
import { useSelectionToolbar, useDocument } from "@tilt-legal/cubitt-components/composites";

function CustomToolbar() {
  const { editor } = useDocument();
  const { isVisible, position, selectedText, selectionRange, hideToolbar } =
    useSelectionToolbar(editor);

  if (!isVisible) return null;

  return (
    <div style={{ top: position.top, left: position.left }}>
      Selected: "{selectedText}"
    </div>
  );
}
```

| Property         | Type                            | Description                 |
| ---------------- | ------------------------------- | --------------------------- |
| `isVisible`      | `boolean`                       | Whether toolbar should show |
| `position`       | `{ top: number, left: number }` | Toolbar position in pixels  |
| `selectedText`   | `string`                        | Currently selected text     |
| `selectionRange` | `{ from: number, to: number }`  | Selection positions         |
| `hideToolbar`    | `() => void`                    | Hide the toolbar            |