Navigation and satellites

svelte

<script lang="ts">
  import {
    Navigation,
    ContentPage,
    SidebarNavigation,
    Section,
  } from '@page-sections/svelte';
  import { resolveNavigation, type MenuItem } from '@page-sections/core';
  const tree: MenuItem[] = [
    {
      id: 'guides',
      label: 'Guides',
      href: '/guides/',
      children: [
        {
          id: 'garden',
          label: 'Garden',
          href: '/guides/garden/',
          children: [
            { id: 'planting', label: 'Planting', href: '/guides/garden/planting/' },
          ],
        },
      ],
    },
  ];
  const navigation = resolveNavigation(tree, { currentId: 'planting' });
</script>

<Navigation items={navigation.items}>
  {#snippet brand()}<a href="/">Garden journal</a>{/snippet}
</Navigation>
<ContentPage
  page={{ title: 'Planting', breadcrumbs: navigation.breadcrumbs }}
  showContentMenu
>
  {#snippet leftSidebar()}<SidebarNavigation items={navigation.sidebarItems} />{/snippet}
  <Section section={{ id: 'soil', title: 'Soil' }}
    ><p>Start with healthy soil.</p></Section
  >
</ContentPage>

items: MenuItem[] supplies the site tree. Every entry requires a stable id, label and href; children are recursive. Optional current marks the current page, active marks an ancestor, and icon is an application-defined key.

Navigation accepts brand, tools, left and right snippets, plus menuIcon and settingsIcon. Satellites appear from XL and move into settings below XL. The optional menu snippet replaces the desktop menu; items still supplies the mobile tree. closeKey closes open menus when the host changes routes. scrollBehavior supports static (default), delayed and fixed.

itemIcon?: Snippet<[MenuItem]> renders second-level icons. The website uses Lucide; the library has no icon dependency.

MainMenu and interaction

On XS–M, the burger contains every hierarchy level. A page link and a separate native disclosure control keep navigation distinct from expanding children. On L and above, the header shows the first level. Hover or keyboard focus reveals the second level in an overlay, while the page behind it blurs. The overlay does not list deeper levels.

Clicking any menu link immediately navigates to its page. Links retain open-in-new-tab and other browser behavior. Escape closes the overlay and restores focus when appropriate. Parent pages must link to their children, so every level remains reachable on touchscreens and without hover.

Standalone MainMenu accepts items, icon, variant (desktop/mobile), closeKey and onOpenChange. Use Navigation for the complete header, satellites and backdrop.

Supply items, optional activeId, an accessible label and an optional icon snippet. The active page receives an accent line; its ancestors open automatically. The usual items are resolveNavigation(tree, location).sidebarItems, representing the second and subsequent levels of the selected main entry.

resolveNavigation accepts pathname or currentId. Explicit IDs also support detail routes. It returns items with current/active markers, activeId, root, sidebarItems and breadcrumbs without changing the supplied tree. The tree starts at the main-menu entries; keep Home as the brand link.

ButtonGroup

Prop	Type	Default
`items`	`ButtonGroupItem[]`	Required
`label`	`string`	Required accessible group label
`onselect`	`(item: ButtonGroupItem) => void`	Optional callback for button activation

ButtonGroupItem field	Type	Behavior
`id`	`string`, required	Unique group key
`label`	`string`, required	Visible text
`href`	`string`	A non-disabled item with href becomes a native link
`selected`	`boolean`	Button aria-pressed or link aria-current=true; not updated internally
`disabled`	`boolean`	Renders a disabled button, even if href exists

Button activation calls onselect; links navigate normally and do not call it. There is no radio-group selection algorithm or automatic state mutation. Buttons use type=button and normal keyboard focus; the wrapper has role=group and its label. Rendered buttons require JavaScript for their callbacks; links remain functional in SSR HTML.

ButtonGroup does not import full shared theme styles on its own. Navigation does, or import the stylesheet explicitly when using them elsewhere.

Site navigation, breadcrumbs and section navigation answer different questions: where can I go, where am I in the site, and what is on this page? Give each landmark a suitable label.

Navigation links use neutral --ps-ink; content links retain --ps-accent. Header and satellites share --ps-navigation-shadow. Set this token on a navigation ancestor to customize or disable elevation. If host button groups paint their own outline and radius, leave the satellite wrapper unpainted and apply the token to the actual group to avoid duplicate edges.

The current page and its ancestors retain a muted background in both menus. Only the current page is bold. The main menu marks the top-level ancestor with an accent line; the sidebar marks the actual page. Top-level menu backgrounds fill the menu height with square corners. Sidebar branches reopen along the current page path after navigation. Desktop submenus connect directly to their parent link and are centered beneath it. Selected ButtonGroup items use a muted background and accent text; icons that inherit the text color follow the same selection treatment.