Skip to content

Admin shell

The shared structure of every admin area and dashboard, with a side menu and the content.

<div data-mount="expanded"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/admin-shell.css";
import { enhance } from "capsomer/behavior/admin-shell";

enhance();

Usage

<div class="cap-admin" data-cap="admin-shell" data-variant="owner">
  [the site header: components/site-header's markup, with Search, Inbox, the theme button and the avatar]
  <nav class="cap-admin-strip" aria-label="Apps">
    <ul class="cap-admin-strip-group">
      <li><a class="cap-admin-tile" href="https://portal.dustinedwards.info/" aria-current="true"><svg class="cap-admin-logo">[the app's mark]</svg>[tip]</a></li>
      <li><a class="cap-admin-tile" href="https://desk.dustinedwards.info/" aria-label="Carrel Desk, 2 need you"><svg class="cap-admin-logo">…</svg><span class="cap-count cap-admin-badge" data-tone="need" aria-hidden="true">2</span>[tip]</a></li>
      [dustinedwards.info, germomics, Foxhound, Foxing, Capsomer, in that order]
    </ul>
  </nav>
  <nav class="cap-admin-menu" id="cap-admin-menu" aria-label="Sections">
    <button type="button" class="cap-admin-collapse" data-cap-part="menu-toggle" aria-label="Collapse menu" aria-expanded="true" aria-controls="cap-admin-menu">[icon]<span class="cap-admin-label">Collapse menu</span><span class="cap-keys"><kbd>[</kbd></span><span class="cap-admin-tip cap-popover" data-variant="tooltip" data-side="right" data-offset="12" popover="manual" role="tooltip" aria-hidden="true"><span class="cap-admin-tip-text">Collapse menu</span></span></button>
    <div class="cap-admin-group" role="group" aria-labelledby="g-watch">
      <div class="cap-admin-group-label" id="g-watch">Watch</div>
      <a href="/" aria-current="page">[icon]<span>Overview</span> <span class="cap-count cap-admin-count"></span></a>
      <a href="/queue" aria-label="Queue, 5 blocked">[icon]<span class="cap-admin-label">Queue</span><span class="cap-admin-tip cap-popover" data-variant="tooltip" data-side="right" data-offset="12" popover="manual" role="tooltip" aria-hidden="true"><span class="cap-admin-tip-text">Queue</span></span> <span class="cap-count cap-admin-count" data-tone="need">5</span></a>
    </div>
  </nav>
  <main class="cap-admin-main" id="cap-main" tabindex="-1">
    <div class="cap-admin-bar">
      <div class="cap-admin-bar-text"><nav class="cap-admin-trail" aria-label="Breadcrumb"><ol><li><a href="/components">Components</a></li><li><span aria-current="page">Shell</span></li></ol></nav>[below the top level only]<span class="cap-admin-fresh">Updated <time datetime="…">6 minutes ago</time> · refreshes itself</span><div class="cap-admin-bar-status">[status]</div></div>
      <div class="cap-admin-actions">[actions]<button type="button" class="cap-admin-btn" data-cap-part="refresh" aria-label="Refresh">[icon][tip]</button></div>
    </div>
    <div class="cap-admin-page">[the view]</div>
  </main>
  <nav class="cap-site-tabs" aria-label="Sections">[up to five links]</nav>
</div>

Examples

Menu collapsed to icons: every icon where it was, a divider between groups, counts at the icon's corner

<div data-mount="collapsed"></div>

Collapsed: a menu icon's name shown beside it, over every panel

<div data-mount="collapsed-tip"></div>

A page below the top level: the top bar shows the trail

<div data-mount="trail"></div>

A strip tile showing its name and key

<div data-mount="tip"></div>

The header's account menu: this app, View site and Help, sign out

<div data-mount="account"></div>

A user's dashboard: no strip, a 288px menu, the business and product switchers in the header

<div data-mount="user"></div>

A user's dashboard, the menu collapsed to icons

<div data-mount="user-collapsed"></div>

A reader's area: the user variant with a reading column

<div data-mount="reader"></div>

Comfortable density

<div data-mount="comfortable"></div>

Page transitions: the content cross-fades between pages, the strip and menu stay put

<div data-mount="transition"></div>

An app whose routes set their own tab titles: documentTitle={false} leaves them alone

<div data-mount="own-title"></div>

Phone width: the header's one row and the bottom bar of five tabs

<div data-mount="phone"></div>

Phone width: the menu button's sheet holds the apps and every page, Sign out pinned

<div data-mount="phone-sheet"></div>

Phone width: a count past 99 on a tab says 99+

<div data-mount="phone-counts"></div>

An app that passes only its own name: the strip still shows all seven apps with their marks

<div data-mount="minimal"></div>

Foxhound's mark: today's x and two alternatives, until Dustin picks

<div data-mount="foxhound-marks"></div>

API reference

AdminShell

PropTypeRequiredDoes
variant"owner" | "user""owner" (your admin): the strip of the family's apps, then a 232px menu. "user" (a customer's own dashboard): no strip and a 288px menu, so the page starts at the same left edge in both.
appFamilyAppIdThe family app this is. The strip lists every family app (FAMILY_APPS) in one order with this one marked, and the header's logo is its mark and name unless logo is given.
badgesPartial<Record<FamilyAppId, AdminBadge>>Other apps' badges, from Capsid's one "what needs the owner" answer. The current app's is never shown.
titlestringThe app's name, for the tab title and the sheet. Default: the family app's. Set it only outside the family.
appsAdminApp[]The strip for a site outside the family. Admin areas pass app.
navAdminEntry[]Yes
pathnamestringThe address you are on (React Router's useLocation().pathname). Given, every entry without its own current is marked from it, and page defaults to the current entry's label.
pagestringThe page being shown: the tab title "<page> · <app>", and the last step of the trail.
documentTitlebooleanWhether the shell writes the tab title from page and title. Default true. False leaves document.title to the app's routes; title still names the logo, the sheet and its groups.
trailAdminCrumb[]The levels above the page. Given, the top bar shows the trail ("Components / Shell"); a top-level page has none, so the bar never repeats the page's own heading.
tabsAdminEntry[]The phone's bottom bar: up to five of this app's top pages, no More. Default: the first five.
navLabelstring
logoHeaderLogoThe header (components/site-header): the site's logo, its band, a switcher (a dashboard's business and product), and its extras. Search and Inbox are the header's first two extras; Help is a row of the account menu.
letterheadbooleanThe family letterhead (components/site-header): the band as tall as the site's public pages, its second row holding where you are and View site; search is the header's search icon and field.
search{ action: string; label: string; name?: string; suggest?: Suggest }
band"dark"
translucentboolean
switchersHeaderSwitcher[]
extrasHeaderExtra[]
onSearch() => void
searchShortcutstring
inbox{ count?: number; countNote?: string; href?: string; onOpen?: () => void; shortcut?: string; }
onHelp() => void
viewSitestringThe account menu's View site row.
accountAdminAccount
updated{ at: number | Date | string; auto?: boolean }The page bar: the trail and how fresh the data is on the left; then the page-wide controls and Refresh (shown when the page can refresh), last. updated is the one freshness line every app shows: "Updated 6 minutes ago", with "· refreshes itself" when auto. status is anything else true of the page.
statusReactNode
actionsReactNode
onRefresh() => void
refreshingboolean
refreshShortcutstring
themePrefKeystringThe theme button's localStorage key ("cap-theme" by default), and the single key the app lets the header bind to it ("T"); leave it out where the app binds its own.
themeKeystring
themeCookieSiteHeaderProps["themeCookie"]Passed to the site header: where the theme choice is kept besides this browser (a cookie, the account), the server's answer, the no-script theme form, and whether the header hydrates.
onThemeSaveSiteHeaderProps["onThemeSave"]
themeInitialSiteHeaderProps["themeInitial"]
themeActionSiteHeaderProps["themeAction"]
hydrateSiteHeaderProps["hydrate"]
prefKeystring
jumpKeysbooleanG then 1 to 9 opens the app in that place (the key sequence of GitHub and Linear; Ctrl and a digit belong to the browser's tabs); on by default, and off with the shortcuts switch. false turns it off for this app alone.
collapseKeystring | falseThe menu's collapse key, shown on the collapse control and in its tip. The shell binds it (never while a person types, or with single-key shortcuts off); false shows no key and binds none.
renderLink(props: LinkProps) => ReactNode
mainPropsOmit<ComponentPropsWithRef<"main">, "id" | "className" | "tabIndex" | "children">The main region's own ref and handlers (an app that scrolls to a row, say). Its id, class and tab stop are the shell's.
collapsedboolean
onCollapsedChange(collapsed: boolean) => void
transitionbooleanPage transitions (View Transitions API): the content cross-fades between pages while the header, strip and menu stay put. Off by default; reduced motion and browsers without the API get no animation. The app wraps its page change in startPageTransition (a flushSync inside).
childrenReactNodeYes

Functions

FunctionSignatureDoes
pageTransitionsOn(shell?: HTMLElement | null): boolean
startPageTransition(update: () => void | Promise<void>, shell?: HTMLElement | null | undefined): Promise<void>
setMenu(shell: HTMLElement, collapsed: boolean, remember?: boolean): void
toggleMenu(shell: HTMLElement): void
jumpTarget(armed: { at: number; }, e: Pick<KeyboardEvent, "key" | "ctrlKey" | "metaKey" | "altKey" | "target">, apps: readonly { href: string; current?: boolean | undefined; }[], now?: number): string | null
isCollapseKey(e: Pick<KeyboardEvent, "key" | "ctrlKey" | "metaKey" | "altKey" | "target" | "defaultPrevented" | "isComposing">, key?: string): booleanThe menu's collapse key ([ by default): the shell binds it, so every app behaves the same. Never with a modifier, while a person types (a field, a contenteditable, a code editor), during IME composition, after another handler took the key, or while single-key shortcuts are off.
currentEntryId(pathname: string, entries: readonly MatchEntry[]): string | undefined
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="admin-shell"] under root that is not attached yet. Returns a function that detaches them all.

CSS variables

VariableDefault
--_bubblevar(--space-5)
--_gw20px
--_gxcalc(50% - 10px)
--admin-hovercolor-mix(in srgb, var(--ground), var(--text) 10%)
--admin-hover-edgevar(--line-strong)
--admin-menuvar(--admin-menu-open)
--admin-menu-collapsedcalc(var(--rail-w-collapsed) + var(--space-6))
--admin-menu-opencalc(var(--rail-w) + var(--space-6))
--admin-pillvar(--accent-12)
--admin-pill-fgvar(--ground)
--admin-row-padcalc((var(--admin-menu-collapsed) - 2 * var(--space-3) - var(--space-5)) / 2)
--admin-stripvar(--rail-w-collapsed)
--admin-strip-bgcolor-mix(in srgb, var(--ground), var(--text) 7%)
--admin-tile36px
--admin-topvar(--header-h)
--header-bgset by the page

Parts and data attributes

ClassIs
.cap-adminthe root
.cap-admin-actionsa part
.cap-admin-badgea part
.cap-admin-bara part
.cap-admin-bar-texta part
.cap-admin-btna part
.cap-admin-collapsea part
.cap-admin-counta part
.cap-admin-groupa part
.cap-admin-group-labela part
.cap-admin-icona part
.cap-admin-labela part
.cap-admin-lettera part
.cap-admin-logoa part
.cap-admin-maina part
.cap-admin-menua part
.cap-admin-pagea part
.cap-admin-stripa part
.cap-admin-strip-groupa part
.cap-admin-tilea part
.cap-admin-tipa part
.cap-admin-traila part
AttributeValues
data-measurereading
data-menucollapsed
data-monopresent or absent
data-standalonepresent or absent
data-tonepresent or absent
data-transitionpage
data-variantletterhead user
data-widthnarrow page
StateRead from
:activethe platform
:focusthe platform
:hoverthe platform
[aria-current="page"]an attribute
[aria-current="true"]an attribute

Accessibility

KeyDoes
TabThe skip link, the header (logo, switchers, Search, Inbox, the theme, the avatar), the strip's apps, the menu (the collapse control first), the main region
Enter or Space on the collapse controlCollapses or expands the menu
EscHides a shown name; closes the account menu and returns focus to the avatar; closes the sheet and returns focus to the menu button
G, then 1 to 9Opens the app in that place
Enter or Space on the avatarOpens the account menu; focus moves to its first item, Up and Down move between items
Any link, with transitions onMoves to the page as without them; the transition does not move focus
[Collapses or expands the menu (not while typing, or with single-key shortcuts off)
  • The header is the banner. The strip, the menu and the phone bar are navigation landmarks with their own names ("Apps", "Sections"); the menu and the bar are never displayed together.
  • Every strip control has an accessible name that contains what it shows; a badge says what it counts in the name ("Carrel Desk, 2 AI drafts waiting").
  • Names of the current app and page are aria-current (true on the tile, page on the menu link), and not conveyed by color alone (a dark fill, plus an outline in forced colors).
  • Menu text, counts and the pill reach their contrast in both themes; the tests measure the painted colors.