Product Grid

Image-led cards with a rating, a price and an add action that works without hover. This is the part of commerce that is genuinely just layout: a Badge for the promo tag, a Button for the action, your own photography — and a read-only Rating for the stars, half stars included, with a sentence beside it for screen readers. Adding an item swaps the button for a stepper and updates the cart readout.

Product Detail

Gallery on the left, buy box on the right. The variant pickers are a Combobox — searchable, with a description per option — and availability is a StatusPill reading the same stock table the warehouse screen uses. Pick Charcoal ash to see the sold-out state.

Reviews

One Rating component, two different jobs. The average is data — 4.8 from 124 reviews — so its stars are drawn and hidden, and a sentence says the number. The form is a control: a real radiogroup, each star named through itemLabel (“4 stars — Great”) and driven by a tap, a click or the keyboard — Tab lands on the stars without rating the product, and the arrow keys choose as they move. Post a review and the average and the bars move with it.

Cart

Line items with steppers, a promo field that accepts SPRING10 and rejects everything else, and a free-shipping Progress bar. Empty the cart and the screen hands over to EmptyState — an empty cart is a real state with a way out, not a blank panel.

Checkout

Four steps beside a summary that never leaves the screen. Stepper draws the step list and runs onValidate before every move forward — Continue, a click on a later step, an arrow key in the list. The step being left has to be complete; if it is not, focus goes to the first field that says why, and steps nobody has reached stay disabled. FormSection and FormField carry the label, hint and error wiring, and the phone number is a PhoneInput given the store’s country: type (503) 555-0142 the way people say it and the value is +15035550142. Press Continue with the fields empty to see the invalid state.

Two things to know. The card fields are stand-ins for the payment provider’s hosted iframe: MaskInput ships creditCard and creditCardExpiry masks with a Luhn check, but a card number typed into your own page puts that page in PCI scope — the provider’s field formats and checks the number itself. And keep the steps written out in the JSX, as they are here: the Stepper reads them while it renders, so the server HTML already has the numbers and a working Continue — a step rendered by a component of your own leaves the whole list at 0, with Back and Continue disabled, until hydration.

Order Confirmation

The reassurance screen: what was bought, what it cost, when it lands. CopyButton puts the order number on the clipboard, RelativeTime dates it in the app’s language with no locale prop, and the four stages are a Timeline. Not a Stepper: nothing here navigates. The current stage carries aria-current="step", and only what has happened gets a <time> — the rest are written as estimates.

Order History

The customer’s own list — the same orders the back office sees, at a shopper’s density. Item rows, StatusPill from the shared fulfilment table, and FilterChips with live counts. Filter down to Returned and then away again to see both states.

Orders Console

The screen the merchandising team lives in, and a working list rather than a short one: ten fields an order, and questions that combine them — paid and unfulfilled and placed this week, or marketplace orders over $500, oldest first. So under the PageHeader and the StatCard tiles sits a DataGrid, whose Filter and Sort menus take several conditions at once. The fulfilment FilterChips and the channel Combobox write the very filters that menu lists, and the chip counts come from TanStack’s faceting, which counts under every filter except the chips’ own. Finding one order or one customer is the menu’s “contains” on that column, and Ctrl+F finds a string anywhere in the grid. There is no pager — the grid virtualises, so a year of orders scrolls like a page of them — and its View menu hides columns. The grid is readOnly: an order changes through actions that leave a history, never by typing into a cell. Its checkboxes stay, though — tick a few rows and an ActionBar rises with the bulk actions. Mark them shipped and the rows, the tiles and each order’s history change together, because all three read the same state. The panel under the grid follows the focused row — arrow keys and clicks both move it — and draws what a cell cannot: the pills, the history and the order’s own actions.

A refund asks first, through one ConfirmDialog for the bar and the panel’s menu alike. It sits outside both and holds the order numbers in state, because the panel’s Refund has no selection behind it. A click in the dialog is not a click outside the grid, so “Keep them” leaves the ticks and the bar where they were. The bar’s own contract is small: open follows the grid’s selection, onOpenChange(false) — the ✕, Escape, or an action that has run — clears it with table.resetRowSelection(), and portalContainer puts it right after the grid in tab order instead of at the end of the page, and anchor="container" centres it on the grid rather than the window. Since 3.1.0 the grid counts clicks and focus inside the bar as its own, so choosing an action no longer clears the ticks before the action can read them. The result — “Marked as shipped: 3 orders” — goes to a role="status" line, because by then the bar has gone.

Inventory

Stock per variant, per location — and the one list on this page that is edited where it stands, because that is what a stock count is. Another DataGrid, one line per variant per location. The location and category Combobox pickers and the stock-level FilterChips write conditions the Filter menu lists, so low stock in Seating is two clicks, and the Sort menu takes Stock and then Available for a worst-first review. On hand and Reorder point are the numbers a stock-taker fixes, so they edit in the cell: type over one, or paste a column straight from a spreadsheet with Ctrl+V. Everything else is locked with meta.readOnly. Product, variant, SKU, category, location and the committed units belong to the catalogue and the order system; Available and Stock are worked out again in onDataChange for every line an edit touches, so they move on the same row as the count. The card under the grid follows the focused line and shows the same variant at every location. Switch the location to the flagship store and the chip counts move; press Recount and the grid gives way to its skeleton.

Product Editor

Adding a listing. Every field is a package component that hands back plain data: a price typed as money in MaskInput and stored as the number 36; tags from TagsInput as a string array; specifications from KeyValue as key/value pairs; and a photo framed in Cropper, which reports the crop rather than cutting it — drag, scroll, pinch with two fingers, or use the arrow keys and + and −. Save, and the product joins the catalogue — a short list people read, so a DataTable rather than a grid — where BadgeOverflow folds the tags that do not fit a cell into +N.

PreviewCode

New product

Draft · not in the store yet

DiscardSave product

Details

What the product card and the search index read.

Title*

Price*

Typed as money, stored as a number.

Compare-at price

Struck through beside the price.

Tags

Tableware

Stoneware

Handmade

Dishwasher safe

Gift idea

Enter or a comma adds a tag; Backspace in the empty field removes the last. 5 of 8.

Specifications

The table on the product page.

Glazed stoneware

180 ml

Dishwasher and microwave safe

Add a specification

Photo

Drag to frame it; scroll, pinch or press + and − to zoom. Sends the whole photo.

In the storefront

Crema Cup & Saucer$36

Material

Glazed stoneware

Capacity

180 ml

Care

Dishwasher and microwave safe

Product	Price	Tags
Aria Lounge ChairARI-LC-01	$389	SeatingSolid oakBestsellerLiving roomMade to order+99and 99 more SeatingSolid oakBestseller
Linen Throw PillowLIN-TP-04	$42	TextilesLinenMachine washable+99and 99 more TextilesLinenMachine washable
Oak Side TableOAK-ST-02	$215	TablesSolid oakOn saleLiving room+99and 99 more TablesSolid oakOn sale
Halo Floor LampHAL-FL-03	$249	LightingBrassNew seasonDimmableLiving roomBedroom+99and 99 more LightingBrassNew season
Terra Ceramic VaseTER-CV-07	$68	DecorCeramicHandmade+99and 99 more DecorCeramicHandmade
Willow Two-SeaterWIL-2S-01	$1,290	SeatingBoucléOn saleTwo-seaterLiving room+99and 99 more SeatingBoucléOn sale

Language Once, Region Explicitly

Every string on these screens — the aria-label and sr-only text included — comes from the package in English, and Vietnamese is a built-in table. So the three label objects this page used to hand every table, toolbar and pager are gone: the language is chosen once, by one ComitorLocaleProvider at the root (Set the language). The label props that remain carry this store’s own wording — the bulk bar’s labels (“3 orders selected”), a clearLabel that names its filter, the review form’s star names — not translation.

import { ComitorLocaleProvider } from '@comitor/ui'
import { getUserLocale } from '@/lib/session'

// The admin's language comes from their profile: "en", "vi", "en-GB"… One provider at the root
// reaches every table, pager, dialog, toast and aria-label — including the screens outside the
// app frame (sign-in, error pages) and dialogs portalled to the end of <body>.
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const locale = await getUserLocale()

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

What the provider never decides is the region. A store trades in a currency and ships from a country whatever language its admin reads, so both come from the store’s settings and are passed explicitly: currency on every MaskInput, defaultCountry on every PhoneInput. Neither is inferred any more. Without them a price is in dollars, and a phone field has no country at all.

// Where the store TRADES — read from its settings, never from the language its admin reads.
// A Vietnamese-speaking merchant can sell in dollars; an English-speaking one can ship from Hanoi.
export const STORE_REGION = { currency: 'USD', country: 'US', locale: 'en-US' } as const

export const money = new Intl.NumberFormat(STORE_REGION.locale, {
  style: 'currency',
  currency: STORE_REGION.currency,
})

// …and handed to every field that needs it, explicitly:
//
//   <MaskInput mask="currency" currency={STORE_REGION.currency} />
//     Leave it out and the field prices in USD, whatever the store sells in.
//
//   <PhoneInput defaultCountry={STORE_REGION.country}>
//     Leave it out and there is no country at all: a domestic number is read as if it began
//     with a country code, and "(503) 555-0142" is stored as +5035550142 — El Salvador.

Best Practices