Storyboard Core

Menu Button Types

There are three patterns, from simplest to most custom:

1. Sidepanel button (config-only, no component)

For buttons that toggle a side panel. Just add a config entry — no Svelte component needed.

"docs": {
  "ariaLabel": "Documentation",
  "icon": "primer/book",
  "modes": ["*"],
  "sidepanel": "docs"
}

2. Action menu button (config + registered action handler)

This is the preferred pattern for new dynamic menus. The config declares an "action" key pointing to a command action ID. CoreUIBar registers the handler in onMount. The generic ActionMenuButton.svelte renders the items.

"flows": {
  "label": "Flows",
  "ariaLabel": "Switch flow",
  "icon": "feather/fast-forward",
  "modes": ["*"],
  "action": "core/flows"
}

The handler is registered in CoreUIBar's onMount:

registerCommandAction('core/flows', {
  getChildren: () => {
    // return array of { id, label, type, active?, execute }
    return items.map(item => ({
      id: item.key,
      label: item.title,
      type: 'radio',       // or 'default', 'toggle'
      active: item.isActive,
      execute: () => { /* action */ },
    }))
  },
})

Supported child types: default (plain item), toggle (checkbox), radio (radio group with check indicator).

The button auto-hides when getChildren() returns an empty array.

3. Custom component (for complex UI that doesn't fit action items)

Only use when the menu needs UI beyond what action items support (e.g., auth flows, overlay panels, feature registries). Must still be declared in config and dynamically imported.

"comments": {
  "ariaLabel": "Comments",
  "icon": "primer/comment",
  "modes": ["*"]
}

Adding a New Menu Button

Step 1: Add config entry

Add an entry to packages/core/toolbar.config.json under menus. The key order determines position (top = leftmost, bottom = rightmost before command menu).

Config field reference

Step 2: Register the action handler (for action menus)

In CoreUIBar.svelte's onMount, register a handler for your action ID:

registerCommandAction('core/my-feature', {
  getChildren: () => {
    // Compute items dynamically based on current state
    return items.map(item => ({
      id: item.key,
      label: item.title,
      type: 'radio',       // 'default', 'toggle', or 'radio'
      active: item.isActive, // for radio/toggle: marks the selected item
      execute: () => { /* what happens on click */ },
    }))
  },
})

That's it. The generic ActionMenuButton.svelte handles all rendering. It:

• Reads children from the action registry via getActionChildren()
• Renders RadioGroup for radio type, CheckboxItem for toggle, Item for default
• Auto-hides when getChildren() returns an empty array
• Refreshes items on each open via onOpenChange

Step 3 (only for custom components): Wire into CoreUIBar.svelte

Only needed when the action system can't express the UI you need (auth flows, overlay panels, etc.).

1. Add state variable:

let MyFeatureButton: any = $state(null)

2. Add visibility filter in visibleMenus:

if (menu.key === 'my-feature') return !!MyFeatureButton

3. Dynamic import in onMount:

try {
  const mod = await import('./MyFeatureButton.svelte')
  MyFeatureButton = mod.default
} catch {}

4. Rendering branch in template:

{:else if menu.key === 'my-feature'}
  <MyFeatureButton config={menu} {basePath} tabindex={getTabindex(i)} />

Important: Data index timing

The storyboard data index (virtual:storyboard-data-index) is seeded by the React app, which initializes after the Svelte CoreUIBar mounts. If your handler reads from the data index (flows, objects, records), the action registry handles this naturally — getChildren() is called lazily when the menu opens, not at registration time.

Icon namespaces

The Icon.svelte component supports multiple icon sources via namespaced names:

Icon meta props: strokeWeight, scale, rotate, flipX, offsetX, offsetY.

Menu visibility

Menus can be hidden via:

• Mode filtering: "modes": ["inspect"] — only visible in inspect mode
• Route exclusion: "excludeRoutes": ["/viewfinder"] — hidden on specific routes
• UI config: storyboard.config.json → ui.hide.menus: ["my-feature"]
• Action menus: auto-hide when getChildren() returns empty array
• Conditional logic: custom visibility checks in the visibleMenus derived block

Existing menu buttons for reference