# Rokkit FloatingAction Component

> Data-driven floating action button (FAB) with radial/vertical/horizontal expand.

FloatingAction renders a single trigger button that expands a list of action items. The actions are data-driven — pass an `items` array and optionally use field mapping. Supports radial, vertical, and horizontal expand patterns.

## Quick Start

```svelte
<script>
  import { FloatingAction } from '@rokkit/ui'

  const actions = [
    { label: 'Add note',  icon: 'i-lucide:file-plus',  value: 'note' },
    { label: 'Add photo', icon: 'i-lucide:camera',      value: 'photo' },
    { label: 'Add task',  icon: 'i-lucide:check-square', value: 'task' }
  ]
</script>

<FloatingAction
  items={actions}
  icon="i-lucide:plus"
  onselect={(value, item) => console.log(value)}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `FloatingActionItem[]` | `[]` | Action items array |
| `fields` | `FloatingActionFields` | defaults | Field mapping |
| `icon` | `string` | `'i-lucide:plus'` | Trigger button icon |
| `closeIcon` | `string` | `'i-lucide:x'` | Icon shown when open |
| `label` | `string` | `'Actions'` | Accessible label for trigger |
| `size` | `'sm'|'md'|'lg'` | `'md'` | Size variant |
| `position` | `'bottom-right'|'bottom-left'|'top-right'|'top-left'` | `'bottom-right'` | Screen position |
| `expand` | `'radial'|'vertical'|'horizontal'` | `'vertical'` | Item expand direction |
| `itemAlign` | `'start'|'center'|'end'` | `'center'` | Alignment of items in menu |
| `disabled` | `boolean` | `false` | Disable the FAB |
| `open` | `boolean` | `false` | Open state — use `bind:open` |
| `backdrop` | `boolean` | `true` | Show backdrop overlay when open |
| `contained` | `boolean` | `false` | Position relative to nearest ancestor instead of viewport |
| `class` | `string` | `''` | Additional CSS classes |

## Field Mapping

| Field | Default | Description |
|-------|---------|-------------|
| `text` | `'text'` | Item label |
| `value` | `'value'` | Value emitted on selection |
| `icon` | `'icon'` | Item icon class |
| `label` | `'label'` | Aria-label override |
| `disabled` | `'disabled'` | Disabled state |

## Callbacks

| Callback | Signature | Description |
|----------|-----------|-------------|
| `onselect` | `(value, item) => void` | Action selected |
| `onopen` | `() => void` | Menu opened |
| `onclose` | `() => void` | Menu closed |

## Expand Variants

```svelte
<!-- Vertical stack (default) -->
<FloatingAction {items} expand="vertical" />

<!-- Horizontal row -->
<FloatingAction {items} expand="horizontal" />

<!-- Radial fan -->
<FloatingAction {items} expand="radial" />
```

## Custom Field Mapping

```svelte
<script>
  const actions = [
    { id: 'new',    title: 'New File',    glyph: 'i-lucide:file-plus' },
    { id: 'upload', title: 'Upload',      glyph: 'i-lucide:upload' }
  ]
  const fields = { value: 'id', label: 'title', icon: 'glyph' }
</script>

<FloatingAction items={actions} {fields} onselect={handleAction} />
```

## Controlled Open State

```svelte
<script>
  let open = $state(false)
</script>

<FloatingAction {items} bind:open onclose={() => console.log('closed')} />
```

## Custom Item Snippet

```svelte
<FloatingAction {items}>
  {#snippet item(data, fields, handlers)}
    <button onclick={handlers.onclick} onkeydown={handlers.onkeydown}
      data-floating-action-item>
      <span class={data.icon}></span>
      <span>{data.text}</span>
    </button>
  {/snippet}
</FloatingAction>
```

## Keyboard Navigation

| Key | Action |
|-----|--------|
| `Enter/Space` | Open menu / activate trigger |
| `ArrowUp/Down` | Navigate items (vertical) |
| `ArrowLeft/Right` | Navigate items (horizontal) |
| `Escape` | Close menu |
| `Tab` | Navigate through items |

## Data Attributes

| Attribute | Description |
|-----------|-------------|
| `data-floating-action` | Root element |
| `data-floating-action-trigger` | Main trigger button |
| `data-floating-action-menu` | Items container |
| `data-floating-action-item` | Individual action item |
| `data-position` | Screen position value |
| `data-expand` | Expand direction |
| `data-open` | Open state |

## Import

```javascript
import { FloatingAction } from '@rokkit/ui'
```

## TypeScript Types

```typescript
interface FloatingActionProps {
  items?: FloatingActionItem[]
  fields?: FloatingActionFields
  icon?: string
  closeIcon?: string
  label?: string
  size?: 'sm' | 'md' | 'lg'
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  expand?: 'radial' | 'vertical' | 'horizontal'
  itemAlign?: 'start' | 'center' | 'end'
  disabled?: boolean
  open?: boolean
  backdrop?: boolean
  contained?: boolean
  class?: string
  onselect?: (value: unknown, item: FloatingActionItem) => void
  onopen?: () => void
  onclose?: () => void
  item?: Snippet<[FloatingActionItem, FloatingActionFields, FloatingActionItemHandlers]>
}
```

## Related Components

- [Menu](/llms/components/dropdown.txt) — inline dropdown menu
- [Toolbar](/llms/components/toolbar.txt) — horizontal action bar
- [Button](/llms/components/button.txt) — standard button