Phoundry UI

Overlay setup

Call setupOverlays() once in your root layout to register the context menu and modal providers and to create the toast, tooltip, and command bar singletons. Render the overlay components alongside it.

import { setupOverlays } from 'phoundry-ui';

Root layout

Call setupOverlays() during layout initialization (not in a child or in a module top-level). Match overlay components to the features you use.

<script lang="ts">
  import {
    setupOverlays,
    ContextMenuOverlay,
    PopoverOverlay,
    ModalOverlay,
    TooltipOverlay,
    ToastOverlay,
    CommandBar,
  } from 'phoundry-ui';

  setupOverlays();

  const commands = [{ id: 'hello', label: 'Say hello', category: 'Demo' }];
  const commandBarConfig = {
    onExecute: (cmd) => console.log(cmd.id),
  };
</script>

<ContextMenuOverlay />
<PopoverOverlay />
<ModalOverlay />
<TooltipOverlay />
<ToastOverlay />
<CommandBar {commands} config={commandBarConfig} />

Options and return value

The return object is optional; you can keep using getToastManager() and the other getters. The modal API is not on the result — use useModalManagerAPI() or getModalManager().

const { contextMenu, popover, toast, tooltip, commandBar } = setupOverlays({
  maxToasts: 8,
});

// Modal: use useModalManagerAPI() in child components or getModalManager() elsewhere

SetupOverlaysOptions

PropTypeDefaultDescription
maxToasts number—Maximum concurrent toasts for the toast singleton. Only applies if no prior getToastManager() ran in this session.

SetupOverlaysResult

PropTypeDefaultDescription
contextMenu ContextMenuAPI—Programmatic context menu API (same as useContextMenuAPI() after setup).
toast ToastManager—Toast singleton; equivalent to getToastManager().
tooltip TooltipManager—Tooltip singleton; equivalent to getTooltipManager().
commandBar CommandBarState—Command palette state; equivalent to getCommandBarState().
popover PopoverAPI—Programmatic popover API; equivalent to getPopoverManager() after setup.

Usage tips

  • Call setupOverlays() only once per app shell; duplicate calls overlap Svelte context the same way duplicate provideModalManager() would.
  • Mount CommandBar when you use the command palette — pass your command list and a config with onExecute; open it via getCommandBarState().open().
  • provideContextMenu(), provideModalManager(), and the individual get* functions remain available if you need a different composition.