Application Shell

AppShell is the whole frame: sidebar, header, workspace switcher, product launcher, user menu, mobile menu and the ⌘K palette slot, around a scrolling <main>. You pass data once at the layout; every part reads it back from the shell context. Two things live in the frame rather than in any page: workspace notices, queued with Banners, and a first-run Tour.

The notice above the page follows the workspace, not the route. Acme Corp has two — a declined card and the weekend’s maintenance — and Banners shows the more urgent one; close it and the next slides in. Northwind only has the maintenance, and a notice you closed stays closed when you come back. Notices go in through useBanners().onBannerAdd, once per workspace: they are data that follows the workspace rather than markup in the layout, and the queue owns each one until someone closes it. Declaring <Banner>s inside <Banners> works too — they keep their place when the layout re-renders.

The tour starts from the card on Overview, from md up, and makes four stops. It moves focus into each step, keeps Tab there, ends on Escape or a click outside, and hands focus back to the button that started it. Create workspace in the switcher opens the flow from Workspace Setup below: finish it and the new workspace joins the switcher — start a trial and it brings a notice of its own.

Root Layout and Language

The package draws every string in English — visible text, accessible names, screen-reader-only text, drag-and-drop announcements — until one ComitorLocaleProvider says otherwise. It belongs in the root layout, above the shell: sign-in, error pages and anything portalled out of the frame render outside AppShell, and they must speak its language. A Comitor app takes the language from the user’s settings through next-intl; an app with one language writes locale="vi". The rest is in Set the language.

// app/layout.tsx — the ROOT layout, a server component
import type { ReactNode } from 'react'
import { NextIntlClientProvider } from 'next-intl'
import { getLocale } from 'next-intl/server'
import { ComitorLocaleProvider } from '@comitor/ui'
import { ThemeProvider } from '@comitor/ui/shell'
import './globals.css' // @import "tailwindcss"; @import "@comitor/ui/styles.css";

/**
 * Every string the package draws — visible text, aria-labels, sr-only text,
 * drag-and-drop announcements — is English until ONE provider says otherwise,
 * and this is where it goes:
 *
 * - The ROOT, not the shell layout. Sign-in, error pages and anything portalled
 *   out of the frame render outside AppShell, and must speak its language.
 * - A Comitor app never hard-codes the language: it is the USER's setting
 *   (Account profile → cookie → next-intl), so the provider takes getLocale().
 *   An app with one language writes locale="vi" and needs no next-intl.
 * - locale is BCP 47. It picks the built-in table (vi → Vietnamese, anything
 *   else → English) AND drives Intl: numbers, times, the 12/24-hour clock.
 */
export default async function RootLayout({ children }: { children: ReactNode }) {
  const locale = await getLocale()

  return (
    <html lang={locale} suppressHydrationWarning>
      <body>
        <NextIntlClientProvider>
          <ThemeProvider>
            <ComitorLocaleProvider locale={locale}>{children}</ComitorLocaleProvider>
          </ThemeProvider>
        </NextIntlClientProvider>
      </body>
    </html>
  )
}

// app/locale-provider.tsx — only once you pass FUNCTIONS. The root layout then
// renders <AppLocaleProvider locale={locale}> where ComitorLocaleProvider was.
'use client'

import type { ReactNode } from 'react'
import { ComitorLocaleProvider, type ComitorMessagesOverride } from '@comitor/ui'
import { enGB } from 'date-fns/locale'

/**
 * A string that counts is a function (members(3) → "3 people"), and a date-fns
 * locale object is mostly functions. Neither crosses from a server component
 * into a client one, so the provider that receives them sits in a client file.
 * Module-level on purpose: a new messages object every render re-renders every
 * component that reads the provider.
 */
const MESSAGES: ComitorMessagesOverride = {
  shell: {
    workspace: 'Company',
    members: (count) => `${count} ${count === 1 ? 'person' : 'people'}`,
  },
}

export function AppLocaleProvider({ locale, children }: { locale: string; children: ReactNode }) {
  return (
    <ComitorLocaleProvider
      locale={locale}
      messages={MESSAGES}
      // date-fns dates map only vi → vi; every other code gets en-US (12/25/2026).
      // British dates need their locale passed in.
      dateFnsLocale={locale === 'en-GB' ? enGB : undefined}
    >
      {children}
    </ComitorLocaleProvider>
  )
}

AppShell also accepts locale. It is a shortcut for an app with no root layout of its own: it wraps only the frame, in a fresh provider that does not inherit messages or dateFnsLocale from an outer one, and adding or removing the prop remounts the whole shell. Region is a separate setting again: PhoneInput takes defaultCountry and MaskInput takes currency from the workspace, never from the language.

App Header

Three zones — identity, a centred search pill that opens the command palette, and the action cluster. The notification panel is deliberately not in the package: only the bell is, because the payload of a notification differs per product.

Stat Cards

StatCard carries the label, the figure, an icon tone, a delta and an optional footer. Colour comes from direction times polarity, so “overdue is up” reads red while “spend is down” reads green. Flip the switch to see the loading skeleton the package ships.

Data Table

The list screen every product needs: SearchFilterBar + DataTable + TablePagination, with a column toggle, row selection, bulk actions in an ActionBar, a confirmation behind ConfirmDialog and two different empty states. Search, sort, filter, select and remove rows — all of it is live.

Select a row and the bar rises: it counts the selection, resends invitations or removes members, and its close button — or Escape — clears the selection. An Escape that already closed a menu or the confirmation is not counted twice, and neither is one pressed while a Vietnamese input method is still composing a word. In an app the bar floats at the bottom of the viewport and portals to the end of <body>, so a keyboard user reaches it last — and it centres on the viewport, half the sidebar’s width off the table’s centre. Portal it into an empty <div> right after the table and pass anchor="container" to fix both. This demo passes portalContainer to keep it inside the box and next in the Tab order.

Content with Tabs

A page header with a primary action over a tabbed list of resource cards. These panels live in one document, so this is Tabs — the moment a tab becomes its own URL, it is RouteTabs instead.

Create Dialog

A short create flow in a ResponsiveDialog — a centred dialog from 768px up, a bottom drawer below it, in reach of a thumb and dismissed with a swipe. Laid out with FormSection and FormField: spread the control argument into the input and label, description, error text and required state are wired for you.

Edit Drawer

The same fields in a side sheet — better for editing a record you want to keep in view, and it has room for a long form without the scrolling body a small dialog forces on you.

Workspace Setup

A create flow too long for one screen: Stepper in a ResponsiveDialog, with TagsInput for the people to invite. The shell only asks for it — the switcher shows Create workspace once onCreateWorkspace exists — and everything after that is the app’s.

Moving forward runs one validation, whether it came from Next or from a later step in the list — the list is a tablist, so the arrow keys walk it too. Back and Next stay the same two buttons from the first step to the last: StepperPrev and StepperNext disable themselves at the ends, and a focused button that is disabled or removed loses the keyboard user’s focus. The address comes from normalizeVi, so “Công ty Bình Minh” becomes cong-ty-binh-minh.

Settings Page

Four settings sections behind RouteTabs: real links carrying aria-current="page", drawn from the same class table as Tabs so the two are indistinguishable on screen. The header and the strip belong in the settings layout, not in each page. Billing measures its quotas with CircularProgress, whose arc turns to the warning ink from 80%.

Long Settings Page

When every setting belongs to one object — here, a webhook — one long page reads better than five tabs. ScrollSpy keeps an in-page table of contents in step with a fixed-height scroll area, and the custom headers are a KeyValue list: paste a few Header: value lines into a name field and they split into rows.

ScrollSpyLink cancels the native #fragment jump, so Tab would carry on from the table of contents rather than from the section you jumped to — each section takes tabIndex={-1} and its link focuses it. KeyValue keeps its default trim: the field shows the space in “Bearer token” as it is typed, and every header it hands back is already trimmed. Below sm the table of contents is hidden and the sections read in order.

Multi-app Navigation

Comitor navigation has two perpendicular axes: workspace and product. Here the frame runs layout="header-first", so the workspace switcher moves into the header and the launcher sits beside it. A product outside the plan shows a padlock and calls onUpsell rather than landing the reader on a 403.

Best Practices