App shell

The frame, live

Anatomy

import {
  AppShell, Canvas, Sidebar, SidebarHeader, SidebarNav, SidebarSection, SidebarItem,
  SidebarFooter, StoreButton, ShellBrand, SidebarToggle, TopBar, Breadcrumbs, SearchTrigger, Avatar,
} from '@orbitcommerce/constellation'
import { HouseIcon, ReceiptIcon } from '@orbitcommerce/constellation/icons'
import { Link, NavLink } from 'react-router'

<AppShell
  sidebar={
    <Sidebar label="Harbour Desk Co">
      <SidebarHeader>
        <Link to="/">
          <ShellBrand placement="header" name="Store Dashboard" />
        </Link>
        <SidebarToggle />
      </SidebarHeader>
      <SidebarNav>
        <SidebarSection>
          <SidebarItem label="Home" icon={<HouseIcon />} activeIcon={<HouseIcon weight="duotone" />}
            link={<NavLink to="/" />} active={path === '/'} />
        </SidebarSection>
        <SidebarSection title="Commerce">
          <SidebarItem label="Orders" icon={<ReceiptIcon />} activeIcon={<ReceiptIcon weight="duotone" />}
            link={<NavLink to="/orders" />} active={path === '/orders'} current={path.startsWith('/orders/')}
            badge={toFulfil} badgeLabel={`${toFulfil} orders to fulfil`} toggleLabel="Show order pages">
            <SidebarItem label="Drafts" link={<NavLink to="/orders/drafts" />} active={path === '/orders/drafts'} />
            <SidebarItem label="Returns" link={<NavLink to="/orders/returns" />} active={path === '/orders/returns'} />
          </SidebarItem>
        </SidebarSection>
      </SidebarNav>
      <SidebarFooter>
        {/* The host's store switcher: a Menu opening upwards, triggered by the StoreButton. */}
        <StoreButton
          name="Harbour Desk Co"
          detail="harbourdesk.co.uk"
          avatar={<Avatar shape="square" size="sm" name="Harbour Desk Co" />}
        />
      </SidebarFooter>
    </Sidebar>
  }
  header={
    <TopBar
      start={<Breadcrumbs items={[{ label: 'Orders', link: <Link to="/orders" /> }, { label: 'Returns' }]} />}
      center={<SearchTrigger onOpen={() => setSearchOpen(true)} />}
      end={<>{/* ghost icon buttons, View store, the account avatar */}</>}
    />
  }
>
  <Canvas>{/* the page */}</Canvas>
</AppShell>

Sidebar items

Expanded and the icon rail

• [ folds and unfolds the rail on desktop and tablet. It is ignored while someone is typing in a field, and when a modifier key is held.
• SidebarToggle does the same from beside the logo. In the rail it waits over the mark and shows on hover or keyboard focus. Its tooltip shows the [ key.
• Leave the state to the shell, or control it with collapsed and onCollapsedChange to remember the merchant's choice.

const [folded, setFolded] = useState(() => localStorage.getItem('sidebar') === 'rail')

<AppShell
  collapsed={folded}
  onCollapsedChange={(next) => {
    setFolded(next)
    localStorage.setItem('sidebar', next ? 'rail' : 'expanded')
  }}
  sidebar={…}
  header={…}
>

Tablet and phone

• The menu button opens the drawer; tapping the scrim or pressing Escape closes it, and so does widening the window past 768px.
• Close the drawer yourself when a page is chosen: call setDrawerOpen(false) from useShell() in the item's onSelect, as the frame above does.
• On phones the rail does not exist: collapsed reads false and [ does nothing.
• Drop the actions that do not fit a phone header, the way Orbit Commerce's store dashboard drops View store, the plan pill and help on phones.

useShell and useOptionalShell

import { useShell } from '@orbitcommerce/constellation'

function PageHeader() {
  const shell = useShell()
  return shell.mode === 'mobile' ? null : <Button size="sm">View store</Button>
}

Header, breadcrumbs and brand

Guidelines

• One AppShell per app, at the root. Pages render inside Canvas; they never draw their own frame.
• Keep the sidebar and header on the ground: no backgrounds, cards or shadows of their own. The canvas is the only raised surface.
• Group items under short sentence-case section titles, with a Phosphor icon for each top-level item: regular at rest, duotone when active.
• Name items for the place, in a word or two: Orders, Gift cards, Media library.
• Give every icon-only header button a label and a tooltip, and keep the header to a handful of actions.

Accessibility

• Landmarks: the sidebar is an aside named by label (default "Main") with a nav inside (default "Primary"), the top bar is a header, and the canvas is the main element unless you change as.
• Sections are groups named by their titles. The active item carries aria-current="page", and its count is left out of its name, with badgeLabel attached as a description.
• A parent without a page is a button with aria-expanded. A parent with a page has a separate toggle named by toggleLabel, with aria-expanded and aria-controls. Closed groups are inert, so their links leave the tab order.
• Items are ordinary links and buttons in tab order. In the rail their names stay in place for screen readers and show as tooltips for everyone else.
• SidebarToggle has aria-expanded and aria-keyshortcuts="[". The phone menu button has aria-expanded, and Escape closes the drawer.
• Breadcrumbs are a nav named "Breadcrumb" holding an ordered list, with the current page marked and the separators hidden.
• Focus rings are teal and 2px on every item, toggle, crumb and the store button.
• With reduced motion the columns and the drawer change at once, the pills jump instead of gliding, groups open without the slide, and counts neither bump nor ping.

Props