App Launcher

Why this is not one flat menu

A Comitor user belongs to many workspaces, and each workspace has many products enabled. The two are perpendicular — switching workspace does not switch product, and switching product does not switch workspace — so a single list would have to enumerate the cross product of both. The shell keeps them as two controls that read the same context:

Neither control takes its data through props. Both read useShell(), so the app list is handed to ShellProvider (or AppShell) once, and AppLauncher can then be dropped anywhere in the tree. Outside a provider useShell() throws rather than rendering an empty launcher, which is why every demo below is wrapped in one. The four display axes — light/dark, palette, density, font size — are a separate set entirely; they live at Display Axes.

The launcher

Six apps, two of them unlicensed. The header is a stand-in for AppHeader, which mounts this control at the right end by default.

Two layouts, one panel

AppLauncherPanel is the panel on its own, split out so MobileMenu can embed it without a second popover inside an already-open sheet. On desktop it is the 3-column grid. Inside the 20rem mobile sheet it becomes a list: that sheet is narrower than the popover the grid was measured for, and it shares one scroll area with the current app’s own menu — which is the thing people opened the sheet to reach. Same reason MobileMenu puts the app list after that menu rather than above it, inverting the desktop order, where the launcher lives in the header and costs the sidebar nothing.

• In the grid a long name wraps to two lines and then clamps — line-clamp-2 break-words, with auto-rows-fr on the grid so a taller row does not leave its neighbours short. break-words is not belt-and-braces: without it a name containing no space never reaches a third line, so the ellipsis never appears and the text is cut flat mid-letter instead.
• In the list a name truncates to one line, because a row that can be one or two lines tall makes the whole column ripple.
• The tile text column carries w-full in the grid, not just min-w-0: a grid tile is flex-col items-start, so that column sizes to its content and grows past the tile — measured at 272px inside a 109px tile — and nothing inside it ever has a width to clamp against. The list variant is immune; its row is horizontal, so flex-1 has already pinned the width.

Locked apps

An AppDescriptor with entitled: false is still rendered — under a second caption, with a grey icon well and a padlock badge — and clicking it calls onUpsell(app.id) instead of going anywhere. The panel splits the list with getEntitledApps and getLockedApps; the demo list above splits 4 / 2. A group with nothing in it is not rendered at all, so a fully licensed workspace never sees a “Discover more” heading.

import { ChartColumn, SquareCheckBig } from 'lucide-react'
import { AppShell, getEntitledApps, getLockedApps } from '@comitor/ui/shell'
import type { AppDescriptor } from '@comitor/ui/shell'

const apps: AppDescriptor[] = [
  { id: 'tasks', name: 'Tasks', icon: SquareCheckBig, href: '/tasks' },
  // Omitted or true = entitled. Only an explicit false locks a tile.
  { id: 'analytics', name: 'Analytics', icon: ChartColumn, href: '/analytics', entitled: false },
]

getEntitledApps(apps) // -> [tasks]      (rendered under labels.myApps)
getLockedApps(apps)   // -> [analytics]  (rendered under labels.discoverApps)

<AppShell
  apps={apps}
  // Fired instead of navigating when someone clicks a locked tile. The shell
  // has no opinion about what an upsell looks like — route, open a dialog,
  // fire an analytics event, whatever the product does.
  onUpsell={(appId) => router.push(`/billing?app=${appId}`)}
>
  {children}
</AppShell>

Which app is open

The current tile is marked aria-current="page" and tinted, and the whole frame inherits that app’s accent. Which app that is comes from currentAppId when you pass it, and otherwise from resolveCurrentApp. Longest path prefix wins, so an app mounted at / cannot swallow /crm/deals, and the query is stripped from each href first — a router pathname never carries one, so /crm?view=board would otherwise never match anything. The table is computed live from the demo app list, whose CRM entry does exactly that:

Identity-coloured tiles

Since 1.10.0 the launcher paints each tile's icon with an IconAvatar, seeded on the app's id. The old model made every app wait to be hand-assigned a colour, so the sixth product either collided with another or sat colourless until someone edited a table; now a new app has a colour the moment it exists — and the same colour in an email, on a canvas or in a PDF, because getAvatarToneColors reads the same tone table.

Pass tone on the AppDescriptor to pin one of the eight identity tones by hand; omit it and the colour is derived from id. The seed is the id, not the name: a display name changes with the interface language, and hashing it would flip an app's colour on vi ⇄ en. A locked tile stays grey through a className, not a tone — “not unlocked” is a state, and the tone table is identity colour.

import { SquareCheckBig, MessageSquare } from 'lucide-react'
import type { AppDescriptor } from '@comitor/ui/shell'

const apps: AppDescriptor[] = [
  // Pin a tile colour by hand — one of the eight AVATAR_TONE_NAMES.
  { id: 'tasks', name: 'Tasks', icon: SquareCheckBig, href: '/tasks', tone: 'teal' },
  // Or omit tone and let it derive from id — a new app is coloured for free.
  { id: 'chat', name: 'Chat', icon: MessageSquare, href: '/chat' },
]

// accent / accentForeground / accentInk are deprecated as of 1.10.0: the launcher
// ignores them. They still drive the FRAME accent through appAccentStyle, so keep
// them only where you rely on that.

The per-app accent

Each app may carry its own colour. appAccentStyle turns that into an inline style — never a generated class name, which Tailwind could not have compiled anyway — and the shell puts it on the frame root, on Sidebar and on MobileMenu. Everything below inherits it through CSS custom properties. (The launcher tile left this model in 1.10.0 — it is an IconAvatar now, coloured by identity; see the section above.)

There are three variables, not one, and that is the whole reason accentInk exists as a separate field instead of being derived:

• --app-accent only ever fills a background — a solid bg-app-accent or a /5–/15 tint. text-app-accent and border-app-accent are wrong by definition, even though Tailwind generates them.
• --app-accent-foreground is what sits on that solid fill.
• --app-accent-ink is the same colour when it goes onto the page — text, standalone icons, borders, the active marker in SidebarMenuItem, the check mark in Select, the open-row rule in DataTable.

The two steps pull in opposite directions: the better a colour fills, the worse the same colour reads as text on white. The default gold makes the case — as a fill it is fine, but as text #E8B824 measures 1.86:1 on the page background and 1.69:1 on its own 15% tint, while the ink step #7A5800 reaches 6.51:1. The package deliberately does not derive one from the other with color-mix: every hue needs a different factor, and a derived number is a number nobody measured. Set accent and forget accentInk and every ink-coloured surface silently keeps the theme’s gold — the wrong colour, at a passing contrast ratio, which is exactly the failure no linter catches.

The same arithmetic governs the Tier-2 components that still use this accent: StatCard, PageHeader, DataTable and FilterChips fill a background with bg-app-accent, while StatCard and Select put the colour on the page with text-app-accent-ink. The launcher tile used to be one more consumer — a solid bg-app-accent well, chosen over the gold-on-gold-tint of 0.1.0 that measured 1.69:1 — but as of 1.10.0 it is an IconAvatar instead, coloured from the app's identity rather than its accent.

Link or callback

An unlocked tile is a real link unless you give the shell an onAppSelect, in which case it becomes a button. Links are the default because middle-click, cmd-click and “open in new tab” are free and a screen reader announces the right role; the callback exists because moving between products often is not a route change at all — a different subdomain, a prefetch, a socket to tear down. Links go through ShellNavLink, which uses the LinkComponent from context — next/link by default, your own router adapter outside Next.

// No onAppSelect -> every unlocked tile is a real link through
// LinkComponent (next/link by default). Middle-click, cmd-click and
// "open in new tab" all work, and a screen reader announces a link.
<AppShell apps={apps}>{children}</AppShell>

// With onAppSelect -> tiles become buttons and the app owns the transition:
// swap subdomain, prefetch, warm a cache, close a socket.
<AppShell apps={apps} onAppSelect={(app) => router.push(app.href)}>
  {children}
</AppShell>

Keyboard

The roving navigation finds its tiles by querying the DOM for [data-app-tile] rather than keeping an array of refs. That marker is the reason it keeps working when an app supplies its own LinkComponent: an unlocked tile may render as your router’s link component, and there is no guarantee that component forwards a ref. A DOM attribute survives whatever it is rendered as, and the arrow keys then just call .focus() on the element they found. The index is clamped, so ↓ on the last row lands on the last tile instead of losing focus.

The demos on this page pass enableShortcuts={false} so a documentation page does not take ⌘K and ⌘⇧K away from the site around it. Arrow-key navigation is local to the panel and stays live.

Labels

Every string in Tier 3 defaults to Vietnamese, screen-reader-only ones included. ShellLabels has 33 keys and is spread over DEFAULT_SHELL_LABELS, so overriding a handful is enough. These six are what the launcher reads.

AppLauncher props

AppLauncherPanel props

AppDescriptor

The data contract for one product. The package ships no app data of its own — this is a type, and the array is yours.

Helpers

Pure functions — no hooks, no 'use client' — so they run in a Server Component too. The shell calls all four internally; they are exported because an app that builds its own frame needs the same answers.

ShellProvider props that drive the launcher

A subset of ShellProviderProps — AppShell accepts every one of them and passes them straight through.

Accessibility

• The trigger is a real <button> wrapped in a Radix PopoverTrigger, so it carries aria-haspopup, aria-expanded and aria-controls without the shell writing them, and focus returns to it when the panel closes.
• Its accessible name is labels.appLauncherLabel while the visible tooltip is labels.apps. When you translate, keep the short visible string a substring of the long accessible one — otherwise “click Apps” in voice control matches nothing (WCAG 2.5.3, Label in Name). An English labels object over the Vietnamese visible text breaks the same criterion, which is why the demos override both.
• A locked tile is a <button> named `${app.name} — ${labels.locked}` with labels.lockedHint as its title. Never aria-disabled: it is operable, and it is the only route to the upgrade flow.
• Locked state is carried three ways — a grey icon well instead of the app colour, a padlock badge, and the accessible name — so it is never colour alone (WCAG 1.4.1). No opacity is used anywhere on the tile, for the contrast reasons measured above.
• The open app’s tile is marked aria-current="page" as well as tinted, on both the link and the button rendering.
• Arrow keys move focus; Enter and Space are never intercepted, so each tile behaves like the native button or link it is. Focus is moved by looking up [data-app-tile] in the DOM, which keeps working with a custom LinkComponent that does not forward refs.
• “My apps” and “Discover more” are visible captions on plain <section> elements, not ARIA groups — they organise the panel visually, and each tile’s own accessible name carries everything a screen reader needs on its own.
• The badge is a real Badge with visible text, announced in reading order right after the app name. It also carries shrink-0, though not to stop a long name squeezing it: measured either way the badge is the same width, because Badge is already whitespace-nowrap and all the shrink lands on the name column instead. It is there so this call site matches every other Badge in the shell, and so the guard stops depending on a class inside a component someone else may change.

Related