App shell and navigation

MenuBar

Defines the application menu bar from serializable MenuSpec data. It must be a direct child of the React root.

<MenuBar
  menus={[
    {
      id: 'file',
      label: 'File',
      items: [{ id: 'new', label: 'New', shortcut: 'cmd+n' }],
    },
  ]}
  onSelect={(id) => handleCommand(id)}
/>

macOS prepends its standard application menu. Command-role items such as copy, paste, and quit invoke platform commands and do not emit onSelect. The about role opens the standard About panel on macOS and is inert on Windows.

Toolbar

Defines native window toolbar items from ToolbarItemSpec[]. It must be a direct root child.

<Toolbar
  items={[
    { type: 'button', id: 'add', label: 'Add', systemImage: 'plus' },
    { type: 'flexibleSpace' },
    { type: 'search', id: 'search', placeholder: 'Filter' },
  ]}
  onAction={handleAction}
  onSearch={setQuery}
/>

The host owns toolbar search text and reports it through onSearch. Both hosts preserve a surviving search item's text and focus across prop updates.

SplitView, Sidebar, and Detail

SplitView routes Sidebar and Detail children into native navigation slots. Use exactly one of each.

<SplitView value={visibility} onChange={setVisibility} sidebarWidth={220}>
  <Sidebar>{navigation}</Sidebar>
  <Detail>{content}</Detail>
</SplitView>

Use value="all" or value="detailOnly" to control visibility. Native visibility controls report changes through onChange. sidebarWidth, minSidebarWidth, and maxSidebarWidth constrain the sidebar.

TabView and Tab

<TabView value={tab} onChange={setTab}>
  <Tab id="overview" title="Overview" systemImage="info.circle">
    <Text>Summary</Text>
  </Tab>
  <Tab id="settings" title="Settings" badge={2}>
    <Text>Preferences</Text>
  </Tab>
</TabView>

TabView takes its controlled value from a child Tab id. A tab click updates native selection optimistically, then reports the id through onChange. Tab titles, system images, and badges render on both hosts.

Verification note

The kitchen-sink real-window suite exercises these seven app-shell kinds on macOS and Windows.