@qeetrix/react 0.0.1 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,293 @@
 # @qeetrix/react
 
+## 0.0.3
+
+The first two Phase 5 increments, from `@qeetrix/react/experimental`: C1, the console frame, and
+C2, secure entry. Experimental parts may change in a patch release; each moves to the root export
+once it has shipped in its product (07-components.md).
+
+### C1 · Console frame
+
+- **`AppShell`** (design B · Ruled, chosen from three researched concepts; 07-components.md):
+  - the frame of every Qeet console: a skip link, the sticky TopBar across the full width, the
+    navigation column on the canvas tone, the page, and an end-edge panel; every seam a 1px rule;
+  - from 840px the navigation collapses to a 48px rail (`sidebarCollapsed` /
+    `defaultSidebarCollapsed` / `onSidebarCollapsedChange`) that expands over the page while hovered
+    or focused; below 840px it opens as a drawer from the start edge;
+  - `drawers` (help, assistant, activity), opened from the TopBar's tools: one at a time, pushing
+    the page from 1200px; `notifications` above the page; `density`, compact by default;
+  - `useAppShell()` tells content inside the frame when the sidebar is a rail.
+- **`TopBar`, `TopBarSwitcher`, `TopBarSearch`:**
+  - black in light and dark (the dark scheme on itself), topped by a 2px Ember line;
+  - product to global, left to right: launcher cell, product, the scope path with drawn slashes,
+    centred search, panel triggers and utilities, account;
+  - `TopBarSwitcher` is a step of the path (organisation mark, environment status dot, always a
+    word) and works as a Menu trigger; `TopBarSearch` is a field-shaped button with its shortcut.
+- **`PageHeader`, `PageContent`:** breadcrumb, `title.lg` title with count and status, actions, a
+  `summary` strip bled to the page edges, and tabs at the foot; a 32px page gutter.
+- **`Stat`, `StatGroup`:** key numbers in ruled cells; numeric values formatted for the locale; an
+  optional decorative trend line whose last point is the Ember mark. Server-safe.
+- **`Sidebar`, `SidebarGroup`, `SidebarItem`:**
+  - links only, one level of nesting, every item in the Tab order;
+  - square rows edge to edge with round icons; the current page gets `aria-current`, the 3px Ember
+    bar, weight 600 and an Ember (optionally filled) icon;
+  - groups between hairlines under tracked small capitals (`typography.label.caps`; untracked for
+    Indic text, which has no case); an optional `title`, `filter` and `footer`;
+  - in the rail, icons stay where they are and labels become tooltips.
+- **`Breadcrumb`, `BreadcrumbItem`:** server-safe; mirrored chevrons; long labels truncate and keep a
+  title.
+- **`EmptyState`:** a 24px icon, a title (a heading when given a `level`), a description and actions,
+  in `page` or `section` size and `neutral` or `danger` tone. Server-safe.
+- **`DataState`:** loading, then error, then empty, then the content. The error state never shows the
+  raw error, and `onRetry` adds "Try again".
+- **Colour scheme:**
+  - `QeetrixProvider` takes `colorScheme`, `defaultColorScheme` and `onColorSchemeChange`, writes
+    `data-qx-color-scheme` on `<html>`, and follows the operating system while `system`;
+  - `useColorScheme()` returns the scheme and a setter. The product persists the choice.
+- **`Button` and `IconButton`:**
+  - a `neutral` tone for ghost utility actions in toolbars and headers, whose icons stay neutral
+    (design rules §16);
+  - a Button's icon sits in its own zone (the new `button-zone` slot), behind a 1px rule as tall as
+    the icon, in the label's colour (design rules §7).
+- **Strings:** new `appShell`, `sidebar`, `breadcrumb` and `dataState` groups, in English and Hindi.
+- **Peer dependency:** `@qeetrix/tokens` `^0.0.7`, for `typography.label.caps`. Since tokens 0.0.6
+  the stylesheet also loads Qeet Sans and Fira Code, so the tests now render in the real typefaces.
+- **Source check:** every `var(--qx-*)` must name a token in the installed `@qeetrix/tokens` or a
+  property the package declares itself, so a token from a newer tokens release can't ship
+  unresolved.
+- **Platform:**
+  - the CSS build, the dist check and the screenshot coverage test understand
+    `src/experimental/<family>/`;
+  - the test helper treats cancelled animations as settled.
+
+### C2 · Secure entry
+
+- **`CopyButton`:** copies a value (or what a function returns, even asynchronously); the icon
+  turns into a check, "Copied" is announced politely, focus stays, and it resets after 2 seconds.
+  It fails visibly where there's no clipboard. An IconButton named by `label`, or a Button with a
+  visible label.
+- **`Alert`:** `info`, `success`, `warning` or `danger` on the status tint with the 3px status edge;
+  a title (led by a hidden tone word), a description, actions and an optional Dismiss. `announce`
+  makes it `role="status"` or `role="alert"` only when it appears after something happens. It never
+  takes focus or disappears by itself.
+- **`PasswordInput`:** an Input with a pressed-state Show password toggle, announced; hidden by
+  default and hidden again when its form submits; `current-password` / `new-password` / `off`;
+  spelling and capitalisation tools off; a Caps Lock warning; `endAdornment` for a CopyButton.
+- **`OTPInput`:** one-time codes in slots on Base UI's OTP Field: typing moves on, paste fills
+  every slot, SMS autofill lands at once; numeric by default; `groups`, `md` and `lg` sizes; the
+  first slot takes the field's label, the rest are "Character 2 of 6".
+- **Strings:** new `copyButton`, `alert`, `passwordInput` and `otpInput` groups, in English and
+  Hindi.
+
+## 0.0.2
+
+Every primitive, in six increments: the foundation, actions, form controls, overlays, selection and
+disclosure, and display and status. Then the Phase 4 close-out: localisation, forced colours,
+right-to-left, reduced motion and the sign-in exit screen.
+
+### Foundation
+
+All nine are server-safe and render in React Server Components.
+
+- **Layout:**
+  - `Box`: a token-only surface (padding, background, border, corners);
+  - `Stack` and `Inline`: vertical and horizontal flows with token gaps;
+  - `Grid`: responsive equal columns on the window size classes.
+- **Type:**
+  - `Text`: body roles, weights, tones, monospace, truncation;
+  - `Heading`: the level sets the element, the size sets the look; Geo letterforms for display.
+- **`Separator`:** 1px, horizontal or vertical, optionally decorative.
+- **Accessibility:**
+  - `VisuallyHidden`: screen-reader-only content;
+  - `SkipLink`: the first focusable element on a page, hidden until focused.
+- **Shared types:** `Space`, `Inset`, `TextAlign`, `RenderProp`.
+- **Imports:** every component also has its own entry point (`@qeetrix/react/stack`) and stylesheet
+  (`@qeetrix/react/css/stack.css`).
+
+### Actions
+
+- **`Button`** (on Base UI Button):
+  - the label comes first, with an optional sharp trailing icon;
+  - variants `solid` (Ember primary), `soft` (warm-graphite secondary) and `ghost`; tones `brand` and
+    `danger`; sizes that follow the density;
+  - `loading` sets `aria-busy` and shows a spinner in the icon's place;
+  - a disabled button stays focusable, so its reason can be read.
+- **`IconButton`:** square and icon-only; its `aria-label` is required by its type.
+- **`Link`:** default, subtle and inherit tones. `external` opens a new tab with
+  `rel="noopener noreferrer"`, an arrow mark and a screen-reader note.
+- **`Toggle` and `ToggleGroup`** (on Base UI):
+  - pressed state with `onPressedChange`, and `filledWhenPressed` swaps to the icon's filled drawing;
+  - groups are segmented or separate, single-choice or `multiple`, with arrow-key focus.
+- **`Spinner`:** four sizes. It is announced as a status unless `decorative`, and fades instead of
+  spinning under reduced motion.
+- **Shared types:** `ControlSize`, `QeetrixIcon`.
+- **Dependencies:**
+  - new peer `@base-ui/react` ^1.9.0;
+  - new dependency `@qeetrix/icons` ^1.0.12, for the external-link mark.
+
+### Form controls
+
+All are client components on Base UI's Field, Fieldset, Input, Checkbox, Radio Group and Switch, so
+labels, descriptions and errors link to their controls without ids. On every form control, `ref` and
+extra props go to the control, while `className` and `style` place the row.
+
+- **`Field`:**
+  - a label, help text and error around any control;
+  - `optional` adds "(optional)", and Qeetrix never marks required fields;
+  - `error` shows a message now (from the server, say) and marks the field invalid. Without it, the
+    browser's or `validate`'s message shows with a sharp alert icon;
+  - the error replaces the help text;
+  - `hideLabel` is for toolbar searches only.
+- **`Input`:** the filled box with a bottom line, a leading `icon`, and start and end adornments.
+  It takes its focus, invalid, read-only and disabled looks from the input.
+- **`Textarea`:** the same look. It grows with its content between `rows` and `maxRows` through CSS
+  `field-sizing`, with no script.
+- **`TextField`:** Field and Input in one, the default form row.
+- **`Fieldset`:** a section of fields under a `title.sm` legend, spaced by the density's form gap.
+  `disabled` disables everything inside.
+- **`Checkbox` and `CheckboxGroup`:**
+  - the 16px box with a sharp tick, and the mixed state with a dash;
+  - a `parent` checkbox selects the whole group;
+  - the label row is at least 24px tall.
+- **`Radio` and `RadioGroup`:** the 5px Ember ring. Arrow keys move and select, and RadioGroup is
+  generic over its value type.
+- **`Switch`:** a 32×18 track with a square thumb that moves to the end side, in either text
+  direction.
+- With no visible label, Checkbox, Radio and Switch require `aria-label` or `aria-labelledby` by
+  their type.
+- **Shared types:** `FieldMessageProps`, `ChoiceLabelProps`, `ChoiceOrientation`.
+
+### Overlays
+
+All are client components on Base UI. Each has a root, a trigger that renders your control, and a
+content part that assembles the portal, positioner and popup.
+
+- **`Popover`:** an anchored panel with an optional title and description. Focus moves in on open
+  and returns to the trigger on close.
+- **`Tooltip`:** one component around its trigger. It opens after 500ms of hover or at once on
+  focus. `TooltipProvider` groups neighbours, so the next one opens at once.
+- **`Menu`:**
+  - items with sharp icons, shortcuts and a `danger` tone;
+  - checkbox and radio items in a 16px mark column;
+  - group labels, separators and submenus;
+  - the 2px Ember start bar on the highlighted item, which follows the text direction.
+- **`Dialog`:**
+  - `intent` is `standard`, `danger` or `warning`, the last two as alert dialogs with a red or amber
+    intent line;
+  - `dismissible`, off by default for `danger`, so only its actions close it;
+  - sizes 400, 560 and 800px;
+  - the close button comes last in the focus order, so a dialog opens on its first field or its
+    least destructive action.
+- **`Drawer`:**
+  - a full-height side panel at the `end` or `start` edge;
+  - ruled header and footer, and a scrolling body;
+  - focus goes to the first field, except on touch;
+  - it can be swiped away.
+- **`ToastProvider` and `useToast`:**
+  - `add`, `close`, `update` and `promise`;
+  - tones `info`, `success`, `warning` and `danger`, each with a 3px status edge and a sharp icon;
+  - one action at most;
+  - `danger` toasts stay until dismissed and are announced at once.
+- **`IconButton`** now shows its `aria-label` as a tooltip. `tooltip={false}` turns it off, and
+  other text replaces it.
+- **Stacking:** anchored layers use `z.popover`, so a menu opened in a dialog sits above it.
+
+### Selection and disclosure
+
+- **`Select`:**
+  - a field-style trigger with a chevron, and a menu-style list below it;
+  - the chosen option carries an Ember check;
+  - `items` can be flat or grouped, and `multiple` lists the chosen labels;
+  - generic over the value. A Field labels it.
+- **`Tabs`, `TabsList`, `Tab`, `TabsPanel`:**
+  - the 3px Ember bar slides under the selected tab, and `TabsList` draws it;
+  - a selected tab has weight 600 and can fill its icon;
+  - padding is 12px at compact density and 16px otherwise;
+  - `activateOnFocus` is on by default;
+  - vertical tabs carry the line and bar on the start edge.
+- **`Slider`:**
+  - a 4px track, the Ember range, and a 16px square thumb ringed in the surface colour;
+  - `label` and `showValue` with `Intl` formatting;
+  - a range renders one thumb per value, named Minimum and Maximum.
+- **`Accordion`, `AccordionItem`:**
+  - ruled sections with a `title.sm` trigger inside a heading (`headingLevel`), and a turning
+    chevron;
+  - the panel's height animates;
+  - find in page opens a closed section that holds the match.
+- **`Collapsible`, `CollapsibleTrigger`, `CollapsiblePanel`:** one unruled section.
+- **`ScrollArea`:** 8px scrollbars that show on hover, while scrolling and on keyboard focus. The
+  region takes focus when it overflows.
+
+### Display and status
+
+- **`Card`:**
+  - a raised surface with a 1px line, 4px corners and no shadow;
+  - a ruled header with `title`, the required heading `level`, `description` and `actions`, and an
+    optional ruled `footer`;
+  - a titled card is a section labelled by its title, and a table in the body runs edge to edge.
+  - Server-safe.
+- **`Table`, `TableCaption`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`:**
+  - a neutral header band and row heights from the density;
+  - `numeric` cells use tabular figures, end-aligned;
+  - `selected` rows keep their Ember tint under the pointer.
+  - Server-safe.
+- **`Badge`:** pills in six tones with an optional sharp icon. The `brand` fill is
+  `bg.brand.subtle`, so its text meets AA. Server-safe.
+- **`Avatar`:** a circle with the photo, or initials while it loads or when it fails. The initials
+  use whole graphemes, so Indic names stay intact. It can be `decorative`.
+- **`Progress` and `Meter`:** Slider's header, a 4px track and an Ember indicator (Meter takes a
+  status tone). Indeterminate progress slides, and fades under reduced motion.
+- **`Skeleton`:** `text`, `block` or `circle`. It pulses, holds still under reduced motion, and is
+  always hidden from assistive technology. Server-safe.
+
+### Phase 4 close-out
+
+- **`QeetrixProvider`:**
+  - `locale` (default `en-IN`) for formatting;
+  - `direction`, which wraps Base UI's DirectionProvider;
+  - `messages`, merged over the English defaults group by group.
+  - Nested providers inherit what they don't set. `useLocale()` reads the locale.
+- **Strings:**
+  - every library string comes from one typed catalogue (`QeetrixMessages`);
+  - Field, TextField, DialogContent, DrawerContent, ToastProvider, Slider and Link take a `messages`
+    prop that wins over the provider;
+  - Link stays server-safe, so it takes its string per instance.
+- **Locale packs:** Hindi (`@qeetrix/react/locales/hi`) is the first. It's a separate entry point,
+  typed as the complete catalogue, and uses Qeet ID's own Hindi words.
+- **Formatting:** `formatNumber`, `formatCurrency` (lakh and crore grouping by default) and
+  `formatRelativeTime`. They're pure, server-safe and cache their formatters. Slider, Progress and
+  Meter format in the provider's locale.
+- **Forced colours (Windows High Contrast):**
+  - surfaces that showed only a fill or a shadow get a system-colour edge;
+  - on states use `Highlight`: pressed Toggle, Switch, checked Checkbox, the Slider and Progress
+    fills, the Tabs bar, and highlighted Menu and Select items;
+  - separators and the tab list's base line stay visible.
+- **Right-to-left:** tests cover arrow keys in Tabs, ToggleGroup, RadioGroup, Slider and the Menu
+  submenu, plus the Drawer edge, the Menu bar side and the Input adornment order.
+- **Reduced motion:** a test checks that durations collapse and that Spinner and indeterminate
+  Progress fade instead.
+- **Slider:** a slider named by `aria-label` (no visible label) now passes the name on to its
+  thumbs, which are what carry the slider role. A range adds Minimum and Maximum.
+- **Sign-in exit screen:** built from primitives alone. Its keyboard order, axe, and its light,
+  dark, right-to-left and forced-colours screenshots are all tested.
+
+### Platform
+
+- **Source check:**
+  - it bans physical CSS properties and system colours outside forced-colours blocks;
+  - it ignores comments when looking for client-only code.
+
+- Each family's stylesheet (`css/<family>.css`) now imports the base layer and the stylesheets of
+  the families it renders, so it works on its own.
+- Screenshots wait for transitions to finish, and overlays are captured across the whole viewport.
+  The accessibility check also waits, since contrast measured mid-fade isn't real. It skips Base
+  UI's aria-hidden focus guards, which hand focus on the moment it lands.
+- A type-only import between families no longer pulls in the other family's stylesheet.
+- Screenshots freeze endless animations (spinner, skeleton, indeterminate progress), so they match
+  every run.
+- The nightly Firefox and WebKit run tests without V8 coverage, which works only in Chromium.
+  Every browser test passes in all three engines.
+
 ## 0.0.1
 
 The engineering platform, with no components yet:

package/README.md

@@ -3,16 +3,19 @@
 The React components of **Qeetrix**, the Qeet Group design system: accessible, token-driven
 primitives built on [Base UI](https://base-ui.com), styled by the Qeetrix design language.
 
-> **Status: 0.0.x, platform only.** This release sets up the build, the stylesheet and the quality
-> gates. The first primitives (layout, text, separator and accessibility utilities) arrive in the
-> next increment.
+> **Status: 0.0.x.** Every primitive is here: foundation, actions, form controls, overlays, selection
+> and disclosure, and display and status. Components and patterns follow as Qeet products ask for
+> them.
 
 ## Install
 
 ```bash
-bun add @qeetrix/react @qeetrix/tokens
+bun add @qeetrix/react @qeetrix/tokens @base-ui/react @qeetrix/icons
 ```
 
+`@base-ui/react` powers the interactive components. Icons come from `@qeetrix/icons`: a component's
+`icon` prop takes any of its icons, e.g. `icon={PlusIcon}`.
+
 ## Styles
 
 Load the tokens, then the component styles, once at the root of your app:
@@ -26,6 +29,239 @@ The stylesheet is precompiled. Your Tailwind setup doesn't need to scan this pac
 utility classes. Qeetrix styles sit in the `qx.base` and `qx.components` cascade layers, so your own
 layout utilities override them without `!important`.
 
+## Use
+
+```tsx
+import { PlusIcon } from "@qeetrix/icons/icons/plus";
+import { Box, Button, Grid, Heading, Inline, SkipLink, Stack, Text } from "@qeetrix/react";
+
+export function Invoices() {
+  return (
+    <>
+      <SkipLink />
+      <main id="main">
+        <Stack gap="xl">
+          <Inline justify="between">
+            <Heading level={1}>Invoices</Heading>
+            <Button icon={PlusIcon}>New invoice</Button>
+          </Inline>
+          <Grid columns={{ base: 1, medium: 2, large: 3 }} gap="md">
+            <Box padding="lg" background="raised" border="default" radius="surface">
+              <Text tone="subtle">Due this month</Text>
+            </Box>
+          </Grid>
+        </Stack>
+      </main>
+    </>
+  );
+}
+```
+
+- **Server-safe:** layout, type, `Link`, `Spinner`, `Card`, `Table`, `Badge` and `Skeleton` render in
+  React Server Components. Everything built on Base UI is a client component; its `"use client"`
+  directive ships in the build.
+- **`render` prop:** renders a different element with the same props, e.g. `render={<section />}`.
+- **Per-component entry points:** `@qeetrix/react/stack`, plus its own stylesheet at
+  `@qeetrix/react/css/stack.css` if you'd rather not load the full one. A family's stylesheet brings
+  the base styles and those of the components it renders (`css/text-field.css` brings Field and
+  Input).
+
+| Component | For |
+|---|---|
+| `Box` | A token-only surface: padding, background, border, corners |
+| `Stack`, `Inline` | Vertical and horizontal flows with token gaps (`none` … `4xl`) |
+| `Grid` | Equal columns per window size class (600 / 840 / 1200 / 1600px) |
+| `Text` | Body text: size, weight, tone, monospace, truncation |
+| `Heading` | `level` sets h1–h6; `size` sets the look (display, heading, title) |
+| `Separator` | A 1px line, horizontal or vertical |
+| `VisuallyHidden` | Content for screen readers only |
+| `SkipLink` | "Skip to main content", hidden until focused |
+| `Button` | Label first, an optional trailing icon; solid (primary), soft (secondary), ghost; brand or danger; `loading` |
+| `IconButton` | A square, icon-only button; `aria-label` is required by its type and shows as a tooltip |
+| `Link` | Inline navigation; `external` opens a new tab safely and says so to screen readers |
+| `Toggle`, `ToggleGroup` | Pressed or not; segmented or separate groups, single or `multiple` |
+| `Spinner` | An indeterminate wait, announced as a status unless `decorative` |
+| `TextField` | Label, input, help text and error in one: the default form row |
+| `Field` | The label, help text and error around any control; `optional` adds "(optional)" |
+| `Input`, `Textarea` | The filled text box with a bottom line; Textarea grows with its content |
+| `Fieldset` | A section of fields under a heading, spaced by the density's form gap |
+| `Checkbox`, `CheckboxGroup` | On/off or several of a set; mixed state; a `parent` checkbox selects all |
+| `Radio`, `RadioGroup` | One of a set; arrow keys move and select |
+| `Switch` | A setting that applies at once |
+| `Popover` | A panel anchored to a trigger: filters, details, a short form |
+| `Tooltip` | A short label for a control; `TooltipProvider` groups neighbours |
+| `Menu` | Actions and options from a trigger: icons, shortcuts, checkbox and radio items, submenus |
+| `Dialog` | A focused task or decision; `intent="danger"` makes a confirmation only its actions close |
+| `Drawer` | A side panel for details or an edit form, swipeable on touch |
+| `ToastProvider`, `useToast` | Brief notifications with a status edge; errors stay until dismissed |
+| `Select` | One option, or several, from up to about 15; looks like a field, opens like a menu |
+| `Tabs` | Views of one context, with the sliding Ember bar |
+| `Slider` | A number or a range on a scale, with a formatted value |
+| `Accordion`, `Collapsible` | Ruled sections, or one section, that show and hide |
+| `ScrollArea` | A scrolling region with Qeetrix scrollbars |
+| `Card` | A raised, ruled surface with a title, actions and footer; a table inside runs edge to edge |
+| `Table` | Semantic table parts with the header band, density row heights and selected rows |
+| `Badge` | A static status pill in six tones |
+| `Avatar` | A person's photo, or their initials |
+| `Progress`, `Meter` | A task advancing, or a measurement within a range |
+| `Skeleton` | A placeholder shaped like the content that's loading |
+
+**Layout:** `className` is for placement only (margin, width, grid placement). Visual changes go
+through props, so every Qeet product looks the same. On a form control, `className` and `style` place
+the whole row, while `ref` and every other prop go to the control itself.
+
+```tsx
+import { Checkbox, CheckboxGroup, Fieldset, Radio, RadioGroup, TextField } from "@qeetrix/react";
+
+<Fieldset legend="Company">
+  <TextField label="Trade name" name="tradeName" optional />
+  <TextField label="GSTIN" name="gstin" required description="15 characters." />
+  <RadioGroup label="Billing cycle" name="cycle" defaultValue="monthly">
+    <Radio value="monthly" label="Monthly" />
+    <Radio value="yearly" label="Yearly" description="Two months free." />
+  </RadioGroup>
+  <CheckboxGroup label="Notify me by" name="notify" orientation="horizontal">
+    <Checkbox value="email" label="Email" />
+    <Checkbox value="sms" label="SMS" />
+  </CheckboxGroup>
+</Fieldset>
+```
+
+## Locale, direction and strings
+
+Wrap the app in `QeetrixProvider` to set the locale (used for formatting), the reading direction and
+the library's own strings ("Close", "(optional)", "Loading"…). Locale packs are separate imports, so
+a language you don't use never ships:
+
+```tsx
+import { QeetrixProvider } from "@qeetrix/react";
+import { hi } from "@qeetrix/react/locales/hi";
+
+<QeetrixProvider locale="hi-IN" messages={hi}>{app}</QeetrixProvider>
+```
+
+- **Override one string:** pass a `messages` prop to the component, e.g.
+  `<Field messages={{ optional: "(if any)" }}>`.
+- **Right-to-left:** use `direction="rtl"`, and set `dir="rtl"` on `<html>` too.
+- **Server-safe components** (Link, Spinner, SkipLink) can't read the provider. Pass their strings
+  per instance.
+
+Formatting helpers are plain functions and work on the server too:
+
+```ts
+import { formatCurrency, formatNumber, formatRelativeTime } from "@qeetrix/react";
+
+formatCurrency(124500, "INR");        // "₹1,24,500.00"
+formatNumber(1234567);                // "12,34,567"
+formatRelativeTime(updatedAt, "en-IN", now); // "2 minutes ago"
+```
+
+Every primitive also works in Windows High Contrast (forced colours) and under reduced motion. Tests
+emulate both.
+
+## Experimental: the console frame
+
+Components and patterns in their first product ship from `@qeetrix/react/experimental`. They may
+change in a patch release until they're Ready.
+
+```tsx
+import {
+  AppShell, PageContent, PageHeader, Sidebar, SidebarGroup, SidebarItem, Stat, StatGroup,
+  TopBar, TopBarSearch, TopBarSwitcher,
+} from "@qeetrix/react/experimental";
+import { Menu, MenuContent, MenuItem, MenuTrigger } from "@qeetrix/react";
+
+<AppShell
+  topBar={
+    <TopBar
+      logo={<QeetLogo variant="dark" height={20} />}
+      product="Qeet ID"
+      context={
+        <>
+          <Menu>
+            <MenuTrigger render={<TopBarSwitcher mark="AC" label="Acme Pvt Ltd" />} />
+            <MenuContent>{organisations}</MenuContent>
+          </Menu>
+          <TopBarSwitcher status="success" label="Production" />
+        </>
+      }
+      search={<TopBarSearch placeholder="Search or jump to…" shortcut={["⌘", "K"]} onClick={openPalette} />}
+      account={accountMenu}
+    />
+  }
+  sidebar={
+    <Sidebar label="Qeet ID">
+      <SidebarGroup label="Directory">
+        <SidebarItem label="Users" icon={UsersIcon} current render={<Link to="/users" />} />
+      </SidebarGroup>
+    </Sidebar>
+  }
+  drawers={[{ id: "help", label: "Help", icon: CircleQuestionMarkIcon, content: help }]}
+>
+  <PageHeader
+    title="Users"
+    actions={<Button icon={PlusIcon}>Invite users</Button>}
+    summary={
+      <StatGroup>
+        <Stat label="Total users" value={1284} note="+38 this week" tone="positive" trend={weekly} />
+      </StatGroup>
+    }
+  />
+  <PageContent>{table}</PageContent>
+</AppShell>
+```
+
+The bar is black in light and dark, topped by a 2px Ember line; the navigation collapses to a 48px
+rail that expands while hovered. Also there: `Breadcrumb`, `EmptyState` and `DataState` (loading,
+error, empty, content), and the secure-entry parts:
+
+```tsx
+<Alert tone="warning" title="Copy this client secret now">It can't be shown again.</Alert>
+<Field label="Client secret">
+  <PasswordInput readOnly autoComplete="off" defaultValue={secret}
+    endAdornment={<CopyButton value={secret} label="Copy client secret" size="sm" />} />
+</Field>
+<Field label="Verification code"><OTPInput size="lg" onValueComplete={verify} /></Field>
+```
+ Colour-scheme switching lives in `QeetrixProvider`
+(`defaultColorScheme="system"`, `useColorScheme()`).
+
+## Overlays
+
+Overlays share one shape: a root that holds the state, a trigger that renders your control, and a
+content part that assembles everything else. Wrap the app once in `ToastProvider` (and, if you like,
+`TooltipProvider`).
+
+```tsx
+import {
+  Button, Dialog, DialogClose, DialogContent, DialogFooter, DialogTrigger, useToast,
+} from "@qeetrix/react";
+
+function RevokeKey({ onRevoke }: { onRevoke: () => Promise<void> }) {
+  const toast = useToast();
+  return (
+    <Dialog intent="danger">
+      <DialogTrigger render={<Button tone="danger">Revoke key</Button>} />
+      <DialogContent title="Revoke this API key?" description="Apps using it stop working at once.">
+        <DialogFooter>
+          <DialogClose render={<Button variant="ghost">Cancel</Button>} />
+          <DialogClose
+            render={<Button tone="danger">Revoke key</Button>}
+            onClick={() =>
+              toast.promise(onRevoke(), {
+                loading: { title: "Revoking…" },
+                success: { title: "Key revoked" },
+                error: { title: "Couldn't revoke the key" },
+              })
+            }
+          />
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
 ## License
 
 [MIT](https://github.com/qeetgroup/qeetrix-react/blob/main/LICENSE) © Qeet Group

package/dist/accordion/accordion.d.ts

@@ -0,0 +1,42 @@
+import { HeadingLevel } from "../heading/heading.js";
+import { Accordion } from "@base-ui/react/accordion";
+import { Collapsible } from "@base-ui/react/collapsible";
+import { CSSProperties, ReactElement, ReactNode } from "react";
+export interface AccordionProps<Value = string> extends Omit<Accordion.Root.Props<Value>, "className" | "style"> {
+  /** Placement only. */
+  className?: string;
+  style?: CSSProperties;
+}
+export interface AccordionItemProps extends Omit<Accordion.Item.Props, "className" | "style" | "title" | "children"> {
+  /** The section's title: the trigger's text. */
+  title: ReactNode;
+  /** The heading level that wraps the trigger. Default 3. */
+  headingLevel?: Exclude<HeadingLevel, 1>;
+  /** The section's content. */
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+export type CollapsibleProps = Collapsible.Root.Props;
+export type CollapsibleTriggerProps = Collapsible.Trigger.Props;
+export interface CollapsiblePanelProps extends Omit<Collapsible.Panel.Props, "className" | "style"> {
+  className?: string;
+  style?: CSSProperties;
+}
+/**
+ * Stacked sections that show and hide, ruled between (06-component-specs.md, increment 5):
+ * `value` / `defaultValue` / `onValueChange(value[], details)`, `multiple`, `disabled`.
+ */
+declare function Accordion$1<Value = string>({ className, ...props }: AccordionProps<Value>): ReactElement;
+/**
+ * One section: a full-width trigger with a chevron, inside a heading, then the panel. Find in page
+ * opens a closed section that holds the match.
+ */
+export declare function AccordionItem({ title, headingLevel, className, children, ...props }: AccordionItemProps): ReactElement;
+/** One section without the rules, for "Show more" or advanced options. */
+declare function Collapsible$1(props: CollapsibleProps): ReactElement;
+/** Shows and hides the panel. Render your own control: `render={<Button variant="ghost" />}`. */
+export declare function CollapsibleTrigger(props: CollapsibleTriggerProps): ReactElement;
+/** The content that shows and hides, with the accordion's height animation. */
+export declare function CollapsiblePanel({ className, ...props }: CollapsiblePanelProps): ReactElement;
+export { Accordion$1 as Accordion, Collapsible$1 as Collapsible };

package/dist/accordion/accordion.js

@@ -0,0 +1,72 @@
+"use client";
+import { cx } from "../internal/cx.js";
+import { Accordion } from "@base-ui/react/accordion";
+import { Collapsible } from "@base-ui/react/collapsible";
+import { ChevronDownIcon } from "@qeetrix/icons/icons/chevron-down";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/accordion/accordion.tsx
+/**
+* Stacked sections that show and hide, ruled between (06-component-specs.md, increment 5):
+* `value` / `defaultValue` / `onValueChange(value[], details)`, `multiple`, `disabled`.
+*/
+function Accordion$1({ className, ...props }) {
+	return /* @__PURE__ */ jsx(Accordion.Root, {
+		...props,
+		className: cx("qx-accordion", className),
+		"data-slot": "accordion"
+	});
+}
+/**
+* One section: a full-width trigger with a chevron, inside a heading, then the panel. Find in page
+* opens a closed section that holds the match.
+*/
+function AccordionItem({ title, headingLevel = 3, className, children, ...props }) {
+	const Heading = `h${headingLevel}`;
+	return /* @__PURE__ */ jsxs(Accordion.Item, {
+		...props,
+		className: cx("qx-accordion-item", className),
+		"data-slot": "accordion-item",
+		children: [/* @__PURE__ */ jsx(Accordion.Header, {
+			render: /* @__PURE__ */ jsx(Heading, {}),
+			className: "qx-accordion-header",
+			children: /* @__PURE__ */ jsxs(Accordion.Trigger, {
+				className: "qx-accordion-trigger",
+				"data-slot": "accordion-trigger",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "qx-accordion-title",
+					children: title
+				}), /* @__PURE__ */ jsx(ChevronDownIcon, {
+					shape: "sharp",
+					size: 16,
+					"aria-hidden": true,
+					className: "qx-accordion-icon"
+				})]
+			})
+		}), /* @__PURE__ */ jsx(Accordion.Panel, {
+			hiddenUntilFound: true,
+			className: "qx-accordion-panel",
+			"data-slot": "accordion-panel",
+			children: /* @__PURE__ */ jsx("div", {
+				className: "qx-accordion-content",
+				children
+			})
+		})]
+	});
+}
+/** One section without the rules, for "Show more" or advanced options. */
+function Collapsible$1(props) {
+	return /* @__PURE__ */ jsx(Collapsible.Root, { ...props });
+}
+/** Shows and hides the panel. Render your own control: `render={<Button variant="ghost" />}`. */
+function CollapsibleTrigger(props) {
+	return /* @__PURE__ */ jsx(Collapsible.Trigger, { ...props });
+}
+/** The content that shows and hides, with the accordion's height animation. */
+function CollapsiblePanel({ className, ...props }) {
+	return /* @__PURE__ */ jsx(Collapsible.Panel, {
+		...props,
+		className: cx("qx-collapsible-panel", className),
+		"data-slot": "collapsible-panel"
+	});
+}
+export { Accordion$1 as Accordion, AccordionItem, Collapsible$1 as Collapsible, CollapsiblePanel, CollapsibleTrigger };