@gemboss/ui 0.39.0 → 0.40.0

package/README.md

@@ -59,6 +59,7 @@ its CSS out of the build with it (`sideEffects`). gzip of the minified file, as
 | auth | `@gemboss/ui/auth.css` | `packages/ui/src/auth.css` | the sign-in screen (+ the grid backdrop, 0.30.0) | 2.8 KB | `AuthLayout` & co. import it |
 | assistant | `@gemboss/ui/assistant.css` | `packages/ui/src/assistant.css` | the dock and the launcher | 2.2 KB | `AssistantHost`, the launcher import it |
 | portal | `@gemboss/ui/portal.css` | `packages/ui/src/portal.css` | `TopbarNav`, `SearchDialog`, `Avatar`, `Leaderboard`, `Podium`, the `ThemeToggle` button | 2.1 KB | those components import it |
+| site | `@gemboss/ui/site.css` | `packages/ui/src/site.css` | the public site layer (0.40.0): the bar, the lockup at the site size, links, buttons, the footer | 1.0 KB | `SiteHeader` / `SiteBrand` import it; a plain-HTML page links it |
 | theme-dark | `@gemboss/ui/theme-dark.css` | `packages/ui/src/theme-dark.css` | the dark palette | 0.6 KB | `ThemeToggle` and `themeScript` (`theme-script.ts`, without portal.css) import it |
 | collections | `@gemboss/ui/collections.css` | `packages/ui/src/collections.css` | tables, lists, grids, boards | 4.6 KB | `IndexTable`, `ResourceList`, `Board`… import it |
 | editor | `@gemboss/ui/editor.css` | `packages/ui/src/editor.css` | the editors | 7.9 KB | the `@gemboss/ui/editor` components import it |
@@ -70,7 +71,8 @@ its CSS out of the build with it (`sideEffects`). gzip of the minified file, as
 | assistant-chat | `@gemboss/ui/assistant-chat.css` | `packages/ui/src/assistant-chat.css` | the chat pieces the package draws (0.29.0): column, starters that wrap, meta, errors, notes, paperclip | 0.9 KB | `AssistantChat` and its pieces import it |
 | minichart | `@gemboss/ui/minichart.css` | `packages/ui/src/minichart.css` | `Sparkline`, `ShareBar` (0.30.0) | 0.5 KB | those components import it |
 | setup-guide | `@gemboss/ui/setup-guide.css` | `packages/ui/src/setup-guide.css` | `SetupGuide` (0.30.0) | 0.9 KB | `SetupGuide` imports it |
-| service-switcher | `@gemboss/ui/service-switcher.css` | `packages/ui/src/service-switcher.css` | `ServiceSwitcher`: the button after the brand and its panel of Gem services (0.36.0) | 1.8 KB | `ServiceSwitcher` imports it, and `BrandLockup` through it (README "ServiceSwitcher") |
+| service-switcher | `@gemboss/ui/service-switcher.css` | `packages/ui/src/service-switcher.css` | `ServiceSwitcher` and `Switcher`: the button after the brand and its panel (0.36.0; any list, illustrated tiles 0.40.0) | 2.2 KB | `ServiceSwitcher` imports it, and `BrandLockup` through it (README "ServiceSwitcher") |
+| team-chat | `@gemboss/ui/team-chat.css` | `packages/ui/src/team-chat.css` | the team chat layer (20/10/2026): rail, messages, composer, thread and people panels, the screen's layout | 3.6 KB | `TeamChat` and its pieces import it (with `Avatar`'s portal.css and `Reactions`' reactions.css); a plain-HTML page links it (README "The team chat layer") |
 | bundle | `@gemboss/ui/gemboss-ui.css` | `gemboss-ui.css` | core + components + shell + auth + assistant + chat + portal + theme-dark | 21.9 KB | compatibility only (see CHANGELOG 0.23.0) |
 
 The core alone is 14.7 KB against 21.7 for the bundle (each part opens with a short header naming the gemboss commit, kept through minify, so a surface serving the parts can still say which commit its CSS is); a list page adds collections (4.6), a sign-in page auth (2.6).
@@ -639,7 +641,7 @@ import "@gemboss/ui/editor.css";   // only on the screens that show an editor
 | Preview | `.gemboss-pv` › `.gemboss-pv-stage` › `.gemboss-pv-frame` (`.desktop` / `.tablet` / `.mobile`, `.gemboss-pv-fit` for scale-to-fit) › `iframe.gemboss-pv-iframe`; `.gemboss-pv-spin`; empty state `.gemboss-pv-empty` (`-art`, `-title`, `-sub`, `-cta`). Device toggle `.gemboss-pv-devices › button.gemboss-pv-device` |
 | Left column | tab row `div.gemboss-ec-tabs[role=tablist] › button[role=tab][aria-selected]` (add `.gemboss-ec-tab` for the 44px pointer floors); Configure pane `.gemboss-ec-dock-body` |
 | Inspector | `.gemboss-ei` (`--docked` inside the Configure pane) › `.gemboss-ei-head` (`-title`, `-x`, `-savedot`), `.gemboss-ei-tabs › .gemboss-ei-tab`, `.gemboss-ei-body`, `.gemboss-ei-foot`. Groups `.gemboss-ei-group › .gemboss-ei-grouphead` (collapsible) and `.gemboss-ei-gh` / `.gemboss-ei-grp`. Field `.gemboss-ei-fld › label + control + .gemboss-ei-hint` |
-| Controls | text / select `.gemboss-field.gemboss-ei-inp` (+ `.gemboss-ei-suffix`, `.gemboss-ei-mono`), segmented `.gemboss-ei-seg`, colour `.gemboss-ei-color` / `.gemboss-ei-swatches › .gemboss-ei-sw` / `.gemboss-ei-swatch`, range `.gemboss-ei-range` + `.gemboss-ei-rangeval`, spacing box `.gemboss-ei-edgebox › .gemboss-ei-edge`, image `.gemboss-ei-img` (`-thumb`, `-ctl`, `-actions`, `-grid`, `-cell`), repeater `.gemboss-ei-rep-item` (`-head`, `-acts`, `-add`), blocks `.gemboss-ei-block` (`-head`, `-x`), add `.gemboss-ei-addrow` / `.gemboss-ei-addchip`, element tree `.gemboss-ei-tree › .gemboss-ei-tnode` (`-tname`, `-tacts`, `-tadd`), notes `.gemboss-ei-note`, `.gemboss-ei-oos` (`-h`), `.gemboss-ei-empty`, drag `.gemboss-ei-drag` / `.gemboss-ei-dragmask` |
+| Controls | text / select `.gemboss-field.gemboss-ei-inp` (+ `.gemboss-ei-mono`), a number with its unit inside `UnitField` (`label.gemboss-field.gemboss-field--group` › `.gemboss-field__bare` + `.gemboss-field__suffix`, 0.40.0; `.gemboss-ei-suffix` is gone), segmented `.gemboss-ei-seg`, colour `.gemboss-ei-color` / `.gemboss-ei-swatches › .gemboss-ei-sw` / `.gemboss-ei-swatch`, range `.gemboss-ei-range` + `.gemboss-ei-rangeval`, spacing box `.gemboss-ei-edgebox › .gemboss-ei-edge`, image `.gemboss-ei-img` (`-thumb`, `-ctl`, `-actions`, `-grid`, `-cell`), repeater `.gemboss-ei-rep-item` (`-head`, `-acts`, `-add`), blocks `.gemboss-ei-block` (`-head`, `-x`), add `.gemboss-ei-addrow` (its buttons are the kit's `.ui-btn` via `ChipButton`, 0.40.0; `.gemboss-ei-addchip` is gone), element tree `.gemboss-ei-tree › .gemboss-ei-tnode` (`-tname`, `-tacts`, `-tadd`), notes `.gemboss-ei-note`, `.gemboss-ei-oos` (`-h`), `.gemboss-ei-empty`, drag `.gemboss-ei-drag` / `.gemboss-ei-dragmask` |
 | Layers | `.gemboss-layers` › `.gemboss-layer-head` + `.gemboss-layers-list` › `.gemboss-layer` (`.is-sel`) › `.gemboss-layer-main` (`.gemboss-layer-type`) + `.gemboss-layer-acts` (`.gemboss-layer-del`) |
 | Settings drawer | `.gemboss-settings` › `.gemboss-picker-head` + `.gemboss-settings-body` › `.gemboss-settings-field`, `-grouphead`, `-gen`, `-note`, `-error`, `-handle`; `.gemboss-settings-foot` (`-save`, `-cancel`); backdrop `.gemboss-picker-backdrop`, empty `.gemboss-picker-empty` |
 | Page / section editor bar | `.gemboss-pageedit` (`-top`, `-title`, `-kind`, `-status`, `-standing`, `-scope`, `-modes`, `-notice`, `-chip`, `-pv`; the left cluster's gap is `--gemboss-tb-gap`, 12px, for a child that hands it back; above 1000px the bar's tracks are `auto fit-content(100%) auto`, so its free space sits beside the centre), `.gemboss-sec-type`, section insert `.gemboss-sec-insert-*`, draft preview `.gemboss-page-draft-stage` / `-status`, `.gemboss-page-section-content`, global styles bundle `.gemboss-bundle-look` |
@@ -766,7 +768,7 @@ import { ColorControl, EdgeBox, Field, ImageControl, InspectorGroup, PanelAction
 |---|---|---|
 | `PanelTabs` | `variant="column"`: `.gemboss-ec-tabs` › `.gemboss-ec-tab` (Configure · Chat, `icon` before the label). `variant="inspector"`: `.gemboss-ei-tabs` › `.gemboss-ei-tab(.on)` | `role=tablist` / `tab`, `aria-selected`, `data-value` (the tab's id, for plain HTML), `aria-controls` from a tab's `controls`. `roving` (default on): only the selected tab is a Tab stop, ←/→ move the selection and the focus, wrapping. The admin's Configure · Chat row passes `roving={false}` (both tabs Tab stops, no arrows: how it always behaved). |
 | `PanelHeader`, `PanelAction` | `header.gemboss-ei-head` › `.gemboss-ei-title` (+ `small` subtitle) · `.gemboss-ei-act` buttons · `.gemboss-ei-x` ✕ | ✕ only with `onClose` (a docked panel has none); `onDragStart` adds `.gemboss-ei-drag` and takes the mouse-down of a floating panel. |
-| `InspectorGroup` | `.gemboss-ei-grp` › `button.gemboss-ei-gh` (▾ / ▸, 11px / 700 uppercase, `note` as `.gemboss-ei-gh-note`) + the body | `aria-expanded`, `data-open`; closed, CSS hides everything after the header (the body stays mounted). Controlled (`open` + `onOpenChange`, which receives the NEXT state) or not (`defaultOpen`). `collapsible={false}`: the schema form's static group, `section.gemboss-ei-group` › `h4.gemboss-ei-grouphead` + `hint`. |
+| `InspectorGroup` | `.gemboss-ei-grp` › `button.gemboss-ei-gh` (13px / 650, the chevron at its end, `note` as `.gemboss-ei-gh-note`) + the body | `aria-expanded`, `data-open`; closed, CSS hides everything after the header (the body stays mounted; an inline `display` on the body's first element would win over that, so give it a bare wrapper). Controlled (`open` + `onOpenChange`, which receives the NEXT state) or not (`defaultOpen`). `attrs`: `data-*` on the group itself, so a page that finds groups by an attribute needs no wrapper (a wrapper drops the divider between groups). `collapsible={false}`: the schema form's static group, `section.gemboss-ei-group` › `h4.gemboss-ei-grouphead` + `hint`. |
 | `Field` | `.gemboss-ei-fld` › `label` (13px / 500; `htmlFor`; `labelValue` as `.gemboss-ei-rangeval` at its right edge) · control · `hint` | No label when `label` is undefined / null. `className` (the admin's `togrow`), `style`. |
 | `Seg` | `.gemboss-ei-seg[role=group]` › `button[aria-pressed][data-value]` (`.on`) | A click hands back the option's value; `label` names the group; `style` on the group. |
 | `ColorControl` | `.gemboss-ei-color` › `input[type=color].gemboss-ei-swatch` + text box | The swatch commits on every change; the text box keeps a draft and commits on blur (every blur) or Enter. Anything but a 6-digit hex disables the swatch, with a title saying why (`swatchState`). |
@@ -1228,6 +1230,32 @@ import { AppShell, BrandLockup, ServiceSwitcher } from "@gemboss/ui";
 **When.** On the topbar of an INTERNAL service, beside its logo. Not on a public surface (GemFeedback's board,
 GemCommunity, a storefront): the panel names internal tools and links to their admin pages.
 
+**The same panel for any list: `Switcher` (0.40.0).** `ServiceSwitcher` is `Switcher` with the Gem services. A public
+surface that has its own list to switch between (GemCommunity's groups: Chris 20/10/2026, "kèm hình ảnh minh hoạ, tên và
+description … như các dịch vụ gemboss") uses `Switcher` with its own items, never the services:
+
+```tsx
+import { Switcher } from "@gemboss/ui";
+
+<Switcher
+  items={[
+    { id: "gemcommunity", name: "GemCommunity", description: "The GemBoss users' group.", href: "/c/gemcommunity", group: "mine", media: { glyph: "◈" }, tint: "iris" },
+    { id: "sellers-cn", name: "China Brands Go Global", description: "Chinese brands going global.", href: "/c/sellers-cn/signup", group: "discover", media: { src: "/covers/cn.jpg" }, badge: "Apply" },
+  ]}
+  groups={[{ id: "mine", title: "Your groups" }, { id: "discover", title: "Discover" }]}
+  current="gemcommunity"
+  labels={{ trigger: "Switch group", title: "Communities", search: "Find a group" }}
+  foot={<button type="button" className="ui-btn">Create a community</button>}
+/>
+```
+
+| | |
+| --- | --- |
+| Items | `id`, `name`, `href` (same tab), `description` (two lines at most), `group` (a `groups` id; unknown or none: a last group without a heading), `tint` (`SERVICE_TINTS`), `badge` (a chip after the name: "Apply"). The picture: `media: { src }` (an image) or `media: { glyph }` (an emoji or two letters, drawn 44px on a panel of the tint) makes the tile a card; without `media`, the service kind: a 40px mark (`icon` or `glyph`). |
+| A card | `a.gb-svc__tile.gb-svc__tile--media` > `span.gb-svc__media` (16:9 across the tile, an `<img alt="" loading="lazy">` covering it, or `span.gb-svc__media-glyph`), the name (+ `span.gb-svc__badge`), the line. A group with a card lays its grid out as `gb-svc__grid--media`: 208px columns, two a row on a phone. |
+| Props | `items`, `groups`, `current`, `labels` (as ServiceSwitcher's), `search`, `allHref` (default none) or `foot` (the app's own foot, actions; wins), `triggerIcon` (default `apps`), `className`. Everything else (the dialog, where it opens, search, keys, the phone sheet) is ServiceSwitcher's, because it is the same code. |
+
+
 | | |
 | --- | --- |
 | Props | `current` (a `ServiceId`, required): the service this page belongs to. `services` (default `GEM_SERVICES`; another list keeps the groups' order). `labels`: `trigger` ("Switch service", the button's name and tooltip), `title` ("Gem services"), `close`, `search` ("Find a service"), `noMatch` ("No service matches “{query}”."), `all`. `allHref`: the foot link, default `SERVICES_HEALTH_URL` (GemFactory's `/services`, every service and its health); `null` draws no foot. `search` (default true). `className` (the button). `BrandLockup switcher={…}` takes the same, less `className`. Every prop is plain data, so a server component can pass it (BrandLockup is not a client module; ServiceSwitcher is) |
@@ -1540,6 +1568,69 @@ import { Avatar, Dialog, Leaderboard, Podium, SearchDialog, ThemeToggle, themeSc
   (after the name, e.g. a level) and `id` (a `#me` anchor). `title` may be left out on a page whose own
   `<h1>` names the board; pass `label` then. Screen-reader text uses `.gb-sr-only`, styled in portal.css.
 
+## The public site layer (0.40.0): `SiteHeader`, `SiteBrand`, links, buttons, footer
+
+**Which layer.** A PUBLIC page (gemboss.ai, the docs, news, a product's home page before sign-in) uses this layer. An APP
+surface (the admin, a portal behind sign-in, GemFeedback's board) keeps `Topbar` + `BrandLockup`. Chris 20/10/2026: "có gemboss
+ui thì có gemboss website ui"; measured the same day, the public pages had drifted on the same detail: the logo name 18px on
+gemboss.ai and the docs, 16px on news, 13.3px on the community home; the bar 65 / 57 / 69 / 56px.
+
+**Two lockup sizes, one gem** (Chris 20/10/2026): site 18px (`SiteBrand`, `.gb-brand--site`), app 13.3px (`BrandLockup`). The gem
+is the same 26px-tall drawing (`brand-gem.tsx`). The site name stays on a phone; the app one hides at ≤460px, where an app's bar
+is full of controls. `SiteBrand` does not go through `BrandLockup`: brand.tsx brings the ServiceSwitcher, whose panel names
+internal tools and their admin URLs, and a public page must not carry it.
+
+The values are gemboss.ai's own (`website/assets/styles.css`): the bar 64px with the content in a 1132px column, nav links
+14px/500, the primary button ink (dark: it inverts with `--gemboss-primary`) 40px and 36px in the bar, footer headings 13px/600
+and links 14px. Every colour is a `--gemboss-*` token, so `theme-dark.css` applies unchanged.
+
+```tsx
+import { SiteBrand, SiteHeader } from "@gemboss/ui";   // brings @gemboss/ui/site.css
+
+<SiteHeader
+  brand={<SiteBrand name="GemBoss" href="/" />}
+  nav={<><a className="gb-site-link" href="/product" aria-current="page">Product</a><a className="gb-site-link" href="/pricing">Pricing</a></>}
+  actions={<><a className="gb-site-link" href="/login">Sign in</a><a className="gb-site-btn gb-site-btn--primary" href="/start">Start free</a></>} />
+```
+
+**Plain HTML** needs only the tokens and `site.css`, NOT the core (which resets the page): site.css repeats the lockup's base
+rules under `gb-brand--site`, so gemboss.ai and the docs can adopt it beside their own stylesheet (`site-browser.test.tsx`
+"standalone" holds it). Link `gemboss-tokens.css` (or map the `--gemboss-*` tokens the file reads onto your own palette, which
+also carries your dark mode), then `site.css`, and write the same markup (the catalog's "Trang công khai" section shows it
+rendered; copy the gem's `<svg>` from there):
+
+```html
+<header class="gb-site-header"><div class="gb-site-header__in">
+  <a class="gb-brand gb-brand--site" href="/" aria-label="GemBoss home"><svg class="gb-brand-gem" …></svg><span class="gb-brand-name">GemBoss</span></a>
+  <nav class="gb-site-nav" aria-label="Main"><a class="gb-site-link" href="/pricing">Pricing</a></nav>
+  <div class="gb-site-actions"><a class="gb-site-link" href="/login">Sign in</a><a class="gb-site-btn gb-site-btn--primary" href="/start">Start free</a></div>
+</div></header>
+
+<footer class="gb-site-footer"><div class="gb-site-wrap">
+  <div class="gb-site-footer__grid">
+    <div><!-- brand + a line --></div>
+    <div class="gb-site-footer__col"><h4>Product</h4><a href="/funnels">Adaptive funnels</a></div>
+  </div>
+  <div class="gb-site-footer__bottom"><span>© 2026 GemBoss</span><span><a href="/terms">Terms</a></span></div>
+</div></footer>
+```
+
+| Class | What |
+|---|---|
+| `gb-site-header`, `gb-site-header__in` | the sticky bar (64px) and its 1132px row; ≤900px the nav folds away, ≤380px the bar's text actions too |
+| `gb-brand gb-brand--site` | the lockup at the site size (`SiteBrand` writes it) |
+| `gb-site-nav`, `gb-site-link` | the bar's links, 14px/500; `aria-current="page"` is 600 |
+| `gb-site-actions` | the right side of the bar |
+| `gb-site-btn` + `--primary` / `--secondary` | the site's buttons: 40px, 36px in the bar, 44px under a finger or at ≤768px |
+| `gb-site-footer`, `__grid`, `__col`, `__bottom`, `gb-site-wrap` | the footer: a brand column + link columns, then one row of small print |
+
+What it holds, measured in Chromium (`site-browser.test.tsx`): the bar 64px; the site name 18px and the app name 13.3px side by
+side; at 390px the site name shown, every control 44px, the nav folded; no sideways scroll at 1280, 390 or 320 (at 320 it was 15px
+too wide with "Sign in" in the bar, hence the ≤380px rule).
+
+Not in this layer yet: a menu button for the folded nav (each site keeps its own), and the page sections (hero, features, FAQ,
+pricing, CTA band), which are the next step.
+
 ## Reactions (0.21.0): one emoji set and one chip for the fleet
 
 Chris 06/10/2026: "reaction các thứ comment nên chuẩn hoá một kiểu, bên gemcare cũng có, nên đưa vào gemboss ui". GemCare's
@@ -1558,6 +1649,458 @@ message with reactions does not grow by a full line. A plain-HTML surface writes
 `reactions.css`, and the catalog's "Reactions" section).
 
 
+## The team chat layer (20/10/2026): `TeamChat`, the rail, messages, composer, thread and people
+
+Chris 20/10/2026: bring GemCare's Slack-like channel chat to GemCommunity, and make the two inherit the same UI so the next
+upgrade happens in one place. GemCare built the chat (its `public/assets/inbox.{html,css,js}`, origin/main 20/10/2026); its
+look and behaviour moved here: the channel rail with unread and @mention badges, day separators, the "New messages" line,
+a person's consecutive messages grouped into one turn, the reply quote, "(edited)", the read receipt, reactions, the thread
+preview under a message, the hover action bar, the thread panel on the right, the round "jump to the latest". New for the
+community: the PEOPLE panel, and a layout that gives a small screen its space back.
+
+**What it needs.** `team-chat.css`, its own entry (the React components import it); `Avatar` from `portal.css` and
+`Reactions` from `reactions.css` (reused, not redrawn: the components import them too); the kit's `ui-btn` and `ui-check`
+from the core's `components.css`; `theme-dark.css` for the dark palette. Every colour in `team-chat.css` is a `--gemboss-*`
+token, so `data-theme="dark"` turns it dark unchanged. It holds no rule on `:root`, `html` or `body`.
+
+| Component | Draws | Takes |
+|---|---|---|
+| `TeamChat` | the screen: `div.gb-tc[data-view][data-panel]` = rail · `section.gb-tc-main` · scrim · panel | `rail`, `children`, `panel`, `panelKind` (`"thread"` / `"people"`), `panelOpen`, `onClosePanel`, `view` (`"list"` / `"conversation"`) |
+| `ChannelRail`, `ChannelSection`, `ChannelItem` | `nav.gb-tc-rail`: head (title + actions), groups ("Channels", "Direct messages"), rows with a kind glyph (# · lock · person), `@n` and unread badges | `title`, `actions`; `label`; `name`, `kind`, `unread`, `mentions`, `active` (`aria-current`), `online` (a DM), `href` + `linkAs` or `onOpen` |
+| `ChatHeader` | `header.gb-tc-head`: back (phone only), glyph + name, topic, actions, the members toggle | `name`, `kind`, `topic`, `onBack`, `members: { count, open, onToggle, controls }`, `actions` |
+| `MessageList`, `DaySeparator`, `NewMessagesLine`, `JumpToLatest` | `div.gb-tc-body` > `div.gb-tc-log[role=log][aria-live=polite]` > `ol.gb-tc-list`; the sticky day pill; the "New messages" line; the round button with a count | `label`, `before` ("Load earlier"), `after` ("Linh is typing…"), `empty`, `jump`, `logRef`, `onScroll`; `label`, `dateTime`; `count`, `visible`, `onJump` |
+| `Message`, `ReadReceipt` | `li.gb-tc-msg`: avatar or (in a turn) the time on hover, quote, name + time, body, "(edited)", receipt, files, link cards, `Reactions`, thread preview, the action bar | `author`, `avatarSrc` / `avatar`, `time`, `dateTime`, `body`, `grouped`, `edited`, `mentionsMe`, `highlight`, `sending`, `failed`, `status`, `badges`, `replyTo`, `attachments`, `extra`, `reactions`, `onReact`, `thread`, `receipt`, `onReply`, `onOpenThread`, `moreActions`, `editor`, `messageId`; `read`, `of`, `label` |
+| `Composer` | `form.gb-tc-composer`: "Replying to…", files, mention picker, one box (paperclip · field · send), "Also send to…", error | `onSend`, `value` / `defaultValue` + `onValueChange`, `placeholder`, `label`, `replyingTo` + `onCancelReply`, `files`, `picker`, `onAttach`, `also`, `error`, `busy`, `disabled`, `canSendEmpty`, `inputRef`, `onKeyDown`, `onPaste` |
+| `ThreadPanel` | `aside.gb-tc-thread`: head + close, notice (`gb-tc-thread__note`, `--error` in the danger colour), the root message, "N replies", the replies flat, a composer | `onClose`, `root`, `replyCount`, `children`, `composer`, `notice`, `noticeTone` (`"error"`), `title`, `subtitle` |
+| `PeoplePanel`, `PeopleSection`, `PersonRow` | `aside.gb-tc-people[data-collapsed]`: head + collapse button, sections "Online — 3", rows with avatar + presence dot, name, a line under it, a role chip | `collapsed`, `onToggleCollapse`, `actions`, `title`; `label`, `count`; `name`, `src` / `avatar`, `subtitle`, `role`, `presence` (`online` / `away` / `offline`), `href` + `linkAs` or `onSelect` |
+
+Props only: no fetching, no store, no router. The app owns the data and the actions; the components keep only the screen's
+own state (the reaction picker a message opened, the composer's text when the app does not hold it, focus). Every word they
+write themselves is in `TEAM_CHAT_LABELS`; pass `labels` (any subset) to translate. `teamChatRows(messages, { meId,
+isUnread })` (plain TS, `team-chat-data.ts`) says where the day separators and the "New messages" line go and which
+messages are `grouped`: same author, same day, under 5 minutes apart, not a reply, and not the first new one (GemCare's
+rules). `chatDayWord` gives "Today" / "Yesterday"; older days the app formats in its own locale.
+
+**The layout.** `.gb-tc` is a CSS grid and a size container: it decides by its OWN width (in an app shell the chat is the
+window minus the shell's rail), with container queries. `TEAM_CHAT_DRAWER_MAX` (1100) and `TEAM_CHAT_PHONE_MAX` (760) are the
+same numbers for JS.
+
+| Width of `.gb-tc` | Right panel | Rail / conversation |
+|---|---|---|
+| > 1100px | a third column: a thread 380px (`--gb-tc-thread-w`), the people panel 260px (`--gb-tc-people-w`), 56px collapsed | rail 240px (`--gb-tc-rail-w`) + conversation |
+| ≤ 1100px | a drawer over the conversation from the right (thread 380px, people 300px), with a scrim; a collapsed people panel is a CLOSED drawer | the conversation keeps its whole width |
+| ≤ 760px | a sheet over the whole chat | `data-view="list"`: the rail alone; `"conversation"`: the conversation alone, with a back button in its head |
+
+While the panel is a drawer, `TeamChat` moves focus into it on open, makes the rail and the conversation `inert` (Tab stays
+in the drawer), closes it on Escape or a press on the scrim (`onClosePanel`), and gives focus back to what opened it.
+Escape closes a thread at any width. The message list is a container too: where IT is narrower than 560px (the thread
+panel, a docked window) the action bar drops its quick reactions and the rows their side padding.
+
+**Under a finger** (`pointer: coarse`) and at phone width every control is 44px: rail rows, people rows, the quote, the
+thread preview, the action bar's buttons, the composer's buttons (the jump button 48px); under a mouse the rail rows and
+the action bar are 32px, as the admin's density. The composer's field is 16px there (iOS zooms the page under it). With
+no hover (`hover: none`) the action bar is ONE TAP away: a tap focuses the message row (`tabindex="-1"`) and the bar shows.
+GemCare's bar was always on under a finger, a row of 44px buttons under every message; this gives that height back to
+the conversation.
+
+### Plain HTML: the markup contract
+
+A surface with no React (GemCare) writes exactly this, links `team-chat.css` beside the core, `portal.css` and
+`reactions.css`, and does the behaviour itself (below). `team-chat-contract.test.tsx` renders every component with the data
+of the block named after it and holds the two to the same tree (tags, classes, attributes, text; `<svg>…</svg>` is an
+icon from the set, `Icon` in React, drawn as in the catalog), so this markup and the components cannot drift. Ids here
+(`tc-…`) are the app's own; keep the pairs (`aria-labelledby` → `id`, `for` → `id`, `aria-controls` → `id`) pointing at
+each other.
+
+The screen. `data-panel` names the panel in the right slot (absent: none); the scrim is drawn only while the panel is
+OPEN (a thread is open; the people panel is not collapsed).
+
+<!-- team-chat: screen -->
+```html
+<div class="gb-tc" data-view="conversation" data-panel="thread">
+  <nav class="gb-tc-rail" aria-label="Channels">…</nav>
+  <section class="gb-tc-main" aria-label="Conversation">…</section>
+  <div class="gb-tc-scrim" aria-hidden="true">
+  </div>
+  <aside class="gb-tc-thread" aria-label="Thread">…</aside>
+</div>
+```
+
+The rail. The active row has `aria-current` (`"page"` on a link, `"true"` on a button); a row with unread messages adds
+`gb-tc-channel--unread`; its `aria-label` says the counts (a badge cannot be read out). A DM row may carry a presence dot.
+
+<!-- team-chat: rail -->
+```html
+<nav class="gb-tc-rail" aria-label="Channels">
+  <div class="gb-tc-rail__head">
+    <h2 class="gb-tc-rail__title">Acme team</h2>
+    <div class="gb-tc-rail__actions">
+      <button type="button" class="ui-btn ui-btn--ghost ui-btn--icon" aria-label="New message">
+        <svg>…</svg>
+      </button>
+    </div>
+  </div>
+  <div class="gb-tc-rail__scroll">
+    <div class="gb-tc-rail__section" role="group" aria-labelledby="tc-channels-h">
+      <h3 class="gb-tc-rail__heading" id="tc-channels-h">Channels</h3>
+      <ul class="gb-tc-rail__list">
+        <li>
+          <button type="button" class="gb-tc-channel" aria-current="true" aria-label="general">
+            <span class="gb-tc-channel__glyph" aria-hidden="true">
+              <svg>…</svg>
+            </span>
+            <span class="gb-tc-channel__name">general</span>
+          </button>
+        </li>
+        <li>
+          <button type="button" class="gb-tc-channel gb-tc-channel--unread" aria-label="launch, 2 mentioning you, 5 unread">
+            <span class="gb-tc-channel__glyph" aria-hidden="true">
+              <svg>…</svg>
+            </span>
+            <span class="gb-tc-channel__name">launch</span>
+            <span class="gb-tc-badge gb-tc-badge--mention" aria-hidden="true">@2</span>
+            <span class="gb-tc-badge" aria-hidden="true">5</span>
+          </button>
+        </li>
+        <li>
+          <button type="button" class="gb-tc-channel" aria-label="payroll, private channel">
+            <span class="gb-tc-channel__glyph" aria-hidden="true">
+              <svg>…</svg>
+            </span>
+            <span class="gb-tc-channel__name">payroll</span>
+          </button>
+        </li>
+      </ul>
+    </div>
+    <div class="gb-tc-rail__section" role="group" aria-labelledby="tc-dms-h">
+      <h3 class="gb-tc-rail__heading" id="tc-dms-h">Direct messages</h3>
+      <ul class="gb-tc-rail__list">
+        <li>
+          <a class="gb-tc-channel gb-tc-channel--unread" href="/chat/dm/linh" aria-label="Linh Tran, direct message, 1 unread">
+            <span class="gb-tc-channel__glyph" aria-hidden="true">
+              <svg>…</svg>
+              <span class="gb-tc-presence gb-tc-presence--online">
+              </span>
+            </span>
+            <span class="gb-tc-channel__name">Linh Tran</span>
+            <span class="gb-tc-badge" aria-hidden="true">1</span>
+          </a>
+        </li>
+      </ul>
+    </div>
+  </div>
+</nav>
+```
+
+The conversation's head. The back button shows only at phone width; the members toggle is `aria-expanded` and points at
+the people panel.
+
+<!-- team-chat: header -->
+```html
+<header class="gb-tc-head">
+  <button type="button" class="ui-btn ui-btn--ghost ui-btn--icon gb-tc-head__back" aria-label="Back to channels">
+    <svg>…</svg>
+  </button>
+  <div class="gb-tc-head__text">
+    <h2 class="gb-tc-head__title">
+      <span class="gb-tc-head__glyph" aria-hidden="true">
+        <svg>…</svg>
+      </span>
+      <span class="gb-tc-head__name">general</span>
+    </h2>
+    <p class="gb-tc-head__sub">Everyone on the team is here.</p>
+  </div>
+  <div class="gb-tc-head__actions">
+    <button type="button" class="ui-btn ui-btn--ghost gb-tc-head__members" aria-expanded="false" aria-controls="tc-people" aria-label="Members, 12">
+      <svg>…</svg>
+      <span class="gb-tc-head__count">12</span>
+    </button>
+  </div>
+</header>
+```
+
+The list: a day, a message that starts a turn, the "New messages" line, and a turn of two (the second `gb-tc-msg--grouped`:
+the time in the avatar's column, shown on hover, and the author for screen readers). The jump button is `hidden` while the
+reader is at the bottom.
+
+<!-- team-chat: list -->
+```html
+<div class="gb-tc-body">
+  <div class="gb-tc-log" role="log" aria-live="polite" aria-label="Messages in #general" tabindex="0">
+    <ol class="gb-tc-list">
+      <li class="gb-tc-day">
+        <time class="gb-tc-day__label" datetime="2026-10-20">Today</time>
+      </li>
+      <li class="gb-tc-msg" tabindex="-1">
+        <span class="gb-avatar gb-avatar--32 gb-tc-msg__av" data-tone="4" aria-hidden="true">LT</span>
+        <div class="gb-tc-msg__main">
+          <div class="gb-tc-msg__who">
+            <span class="gb-tc-msg__name">Linh Tran</span>
+            <time class="gb-tc-msg__time" datetime="2026-10-20T09:41:00+07:00">09:41</time>
+          </div>
+          <div class="gb-tc-msg__body">Morning! The launch checklist is in the doc.</div>
+        </div>
+      </li>
+      <li class="gb-tc-new">
+        <span class="gb-tc-new__label" role="separator" aria-label="New messages">New messages</span>
+      </li>
+      <li class="gb-tc-msg" tabindex="-1">
+        <span class="gb-avatar gb-avatar--32 gb-tc-msg__av" data-tone="0" aria-hidden="true">QL</span>
+        <div class="gb-tc-msg__main">
+          <div class="gb-tc-msg__who">
+            <span class="gb-tc-msg__name">Quan Le</span>
+            <time class="gb-tc-msg__time" datetime="2026-10-20T09:44:00+07:00">09:44</time>
+          </div>
+          <div class="gb-tc-msg__body">On it.</div>
+        </div>
+      </li>
+      <li class="gb-tc-msg gb-tc-msg--grouped" tabindex="-1">
+        <time class="gb-tc-msg__hover-time" datetime="2026-10-20T09:45:00+07:00">09:45</time>
+        <div class="gb-tc-msg__main">
+          <span class="gb-tc-sr">Quan Le, 09:45: </span>
+          <div class="gb-tc-msg__body">Pushed the fix for the cart drawer.</div>
+        </div>
+      </li>
+    </ol>
+  </div>
+  <button type="button" class="gb-tc-jump" aria-label="Jump to the latest message, 3 new">
+    <svg>…</svg>
+    <span class="gb-tc-jump__n" aria-hidden="true">3</span>
+  </button>
+</div>
+```
+
+A message with everything: the quote it answers, "(edited)", a read receipt (the viewer's own messages; a ring, a slice
+per share, filled and ticked when everyone has read it), reactions (the package's `Reactions`; none, no row), the thread
+preview, the action bar. Modifiers on the `li`: `gb-tc-msg--mention` (calls the viewer: an amber bar on the left),
+`--highlight` (jumped to), `--sending` (faded, no bar, `p.gb-tc-msg__status` "Sending…"), `--failed` (the status in the danger
+colour), `--active` (the reaction picker is open: the bar stays), `--editing` (the app's edit box in `div.gb-tc-msg__editor`
+in place of the body, no bar). Slots: `div.gb-tc-msg__files` (pictures, files), `div.gb-tc-msg__extra` (link cards), the
+app's own buttons at the end of `div.gb-tc-acts`. "Add reaction" opens the package's picker (`ui-reaction-picker`) in the
+flow under the body; the quick pair (👍 ✅) is `gb-tc-act--quick`.
+
+<!-- team-chat: message -->
+```html
+<li class="gb-tc-msg" data-msg-id="42" tabindex="-1">
+  <span class="gb-avatar gb-avatar--32 gb-tc-msg__av" data-tone="7" aria-hidden="true">MP</span>
+  <div class="gb-tc-msg__main">
+    <button type="button" class="gb-tc-quote">
+      <span class="gb-tc-quote__who">Linh Tran</span>
+      <span class="gb-tc-quote__text">Can someone own the hero copy?</span>
+    </button>
+    <div class="gb-tc-msg__who">
+      <span class="gb-tc-msg__name">Mai Pham</span>
+      <time class="gb-tc-msg__time" datetime="2026-10-20T10:02:00+07:00">10:02</time>
+    </div>
+    <div class="gb-tc-msg__body">Mine, shipping it at noon.<span class="gb-tc-msg__edited">(edited)</span>
+      <span class="gb-tc-receipt gb-tc-receipt--all" role="img" aria-label="Read by everyone (3)" title="Read by everyone (3)">
+        <svg>…</svg>
+      </span>
+    </div>
+    <div class="ui-reactions">
+      <div class="ui-reactions__row">
+        <button type="button" class="ui-reaction" aria-pressed="false" title="Linh, Quan" aria-label="👍, Linh, Quan. Add yours">
+          <span class="ui-reaction__emoji">👍</span>
+          <span class="ui-reaction__names">Linh, Quan</span>
+        </button>
+        <button type="button" class="ui-reaction-add" title="Add reaction" aria-label="Add a reaction to the message from Mai Pham" aria-expanded="false">
+          <svg>…</svg>
+        </button>
+      </div>
+    </div>
+    <button type="button" class="gb-tc-threadprev" aria-label="Open the thread, 3 replies, Last reply 2 hours ago">
+      <span class="gb-tc-threadprev__faces" aria-hidden="true">
+        <span class="gb-avatar gb-avatar--24" data-tone="4" aria-hidden="true">LT</span>
+        <span class="gb-avatar gb-avatar--24" data-tone="0" aria-hidden="true">QL</span>
+      </span>
+      <span class="gb-tc-threadprev__count">3 replies</span>
+      <span class="gb-tc-threadprev__last">Last reply 2 hours ago</span>
+    </button>
+  </div>
+  <div class="gb-tc-acts" role="toolbar" aria-label="Actions for the message from Mai Pham">
+    <button type="button" class="gb-tc-act gb-tc-act--quick" aria-pressed="false" aria-label="Add 👍 on the message from Mai Pham">👍</button>
+    <button type="button" class="gb-tc-act gb-tc-act--quick" aria-pressed="false" aria-label="Add ✅ on the message from Mai Pham">✅</button>
+    <button type="button" class="gb-tc-act" aria-expanded="false" aria-label="More reactions for the message from Mai Pham" title="Add reaction">
+      <svg>…</svg>
+    </button>
+    <button type="button" class="gb-tc-act" aria-label="Reply to the message from Mai Pham" title="Reply">
+      <svg>…</svg>
+    </button>
+    <button type="button" class="gb-tc-act" aria-label="Reply in thread to the message from Mai Pham" title="Reply in thread">
+      <svg>…</svg>
+    </button>
+  </div>
+</li>
+```
+
+The composer. "Replying to…" sits right above the box; `div.gb-tc-composer__files` and `div.gb-tc-composer__picker` hold
+the app's files and @mention list; Send is `disabled` while there is nothing to send.
+
+<!-- team-chat: composer -->
+```html
+<form class="gb-tc-composer">
+  <div class="gb-tc-replying">
+    <span class="gb-tc-replying__text">Replying to Linh Tran: Can someone own the hero copy?</span>
+    <button type="button" class="ui-btn ui-btn--ghost ui-btn--icon" aria-label="Stop replying">
+      <svg>…</svg>
+    </button>
+  </div>
+  <div class="gb-tc-composer__files">…</div>
+  <div class="gb-tc-composer__picker">…</div>
+  <div class="gb-tc-composer__box">
+    <button type="button" class="ui-btn ui-btn--ghost ui-btn--icon gb-tc-composer__attach" aria-label="Attach a file">
+      <svg>…</svg>
+    </button>
+    <label class="gb-tc-sr" for="tc-input">Message</label>
+    <textarea id="tc-input" class="gb-tc-composer__input" rows="1" maxlength="4000" placeholder="Message #general">
+    </textarea>
+    <button type="submit" class="ui-btn ui-btn--primary ui-btn--icon gb-tc-composer__send" aria-label="Send" disabled="">
+      <svg>…</svg>
+    </button>
+  </div>
+</form>
+```
+
+The thread panel: the root, the "N replies" rule, the replies flat, a composer with "Also send to the channel".
+
+<!-- team-chat: thread -->
+```html
+<aside id="tc-thread" class="gb-tc-thread" aria-labelledby="tc-thread-title" tabindex="-1">
+  <header class="gb-tc-panel-head">
+    <div class="gb-tc-panel-head__text">
+      <h2 class="gb-tc-panel-head__title" id="tc-thread-title">Thread</h2>
+      <p class="gb-tc-panel-head__sub">#general</p>
+    </div>
+    <button type="button" class="ui-btn ui-btn--ghost ui-btn--icon gb-tc-panel-head__close" aria-label="Close thread">
+      <svg>…</svg>
+    </button>
+  </header>
+  <div class="gb-tc-body">
+    <div class="gb-tc-log" role="log" aria-live="polite" aria-labelledby="tc-thread-title" tabindex="0">
+      <ol class="gb-tc-list">
+        <li class="gb-tc-msg" tabindex="-1">
+          <span class="gb-avatar gb-avatar--32 gb-tc-msg__av" data-tone="4" aria-hidden="true">LT</span>
+          <div class="gb-tc-msg__main">
+            <div class="gb-tc-msg__who">
+              <span class="gb-tc-msg__name">Linh Tran</span>
+              <time class="gb-tc-msg__time" datetime="2026-10-20T09:41:00+07:00">09:41</time>
+            </div>
+            <div class="gb-tc-msg__body">Can someone own the hero copy?</div>
+          </div>
+        </li>
+        <li class="gb-tc-thread__count">
+          <span>1 reply</span>
+        </li>
+        <li class="gb-tc-msg" tabindex="-1">
+          <span class="gb-avatar gb-avatar--32 gb-tc-msg__av" data-tone="7" aria-hidden="true">MP</span>
+          <div class="gb-tc-msg__main">
+            <div class="gb-tc-msg__who">
+              <span class="gb-tc-msg__name">Mai Pham</span>
+              <time class="gb-tc-msg__time" datetime="2026-10-20T10:02:00+07:00">10:02</time>
+            </div>
+            <div class="gb-tc-msg__body">Mine, shipping it at noon.</div>
+          </div>
+        </li>
+      </ol>
+    </div>
+  </div>
+  <form class="gb-tc-composer">
+    <div class="gb-tc-composer__box">
+      <label class="gb-tc-sr" for="tc-thread-input">Reply to thread</label>
+      <textarea id="tc-thread-input" class="gb-tc-composer__input" rows="1" maxlength="4000" placeholder="Reply…">
+      </textarea>
+      <button type="submit" class="ui-btn ui-btn--primary ui-btn--icon gb-tc-composer__send" aria-label="Send" disabled="">
+        <svg>…</svg>
+      </button>
+    </div>
+    <label class="ui-check gb-tc-composer__also">
+      <input type="checkbox"/>
+      <span>Also send to #general</span>
+    </label>
+  </form>
+</aside>
+```
+
+The people panel. Collapsed: `data-collapsed` on the `aside`, the toggle `aria-expanded="false"` and labelled "Show
+members", no `gb-tc-panel-head__actions`; the names stay in the accessibility tree (clipped, not removed). A row is a link,
+a button, or a `div` when it does nothing; `gb-tc-person--offline` fades it. On its own (outside `.gb-tc`, e.g. an app
+shell's right column) it fills its column's height.
+
+<!-- team-chat: people -->
+```html
+<aside id="tc-people" class="gb-tc-people" aria-labelledby="tc-people-title" tabindex="-1">
+  <header class="gb-tc-panel-head">
+    <div class="gb-tc-panel-head__text">
+      <h2 class="gb-tc-panel-head__title" id="tc-people-title">Members</h2>
+    </div>
+    <button type="button" class="ui-btn ui-btn--ghost ui-btn--icon gb-tc-people__toggle" aria-expanded="true" aria-controls="tc-people-body" aria-label="Hide members" title="Hide members">
+      <svg>…</svg>
+    </button>
+  </header>
+  <div class="gb-tc-people__body" id="tc-people-body">
+    <div class="gb-tc-people__section" role="group" aria-labelledby="tc-online-h">
+      <h3 class="gb-tc-people__heading" id="tc-online-h">Online — 2</h3>
+      <ul class="gb-tc-people__list">
+        <li>
+          <button type="button" class="gb-tc-person" title="Linh Tran">
+            <span class="gb-tc-person__av">
+              <span class="gb-avatar gb-avatar--32" data-tone="4" aria-hidden="true">LT</span>
+              <span class="gb-tc-presence gb-tc-presence--online">
+                <span class="gb-tc-sr">Online</span>
+              </span>
+            </span>
+            <span class="gb-tc-person__text">
+              <span class="gb-tc-person__name">Linh Tran</span>
+              <span class="gb-tc-person__sub">Support lead</span>
+            </span>
+            <span class="gb-tc-person__role">Admin</span>
+          </button>
+        </li>
+        <li>
+          <a class="gb-tc-person" href="/u/quan" title="Quan Le">
+            <span class="gb-tc-person__av">
+              <span class="gb-avatar gb-avatar--32" data-tone="0" aria-hidden="true">QL</span>
+              <span class="gb-tc-presence gb-tc-presence--away">
+                <span class="gb-tc-sr">Away</span>
+              </span>
+            </span>
+            <span class="gb-tc-person__text">
+              <span class="gb-tc-person__name">Quan Le</span>
+              <span class="gb-tc-person__sub">In a meeting</span>
+            </span>
+          </a>
+        </li>
+      </ul>
+    </div>
+    <div class="gb-tc-people__section" role="group" aria-labelledby="tc-members-h">
+      <h3 class="gb-tc-people__heading" id="tc-members-h">Members — 1</h3>
+      <ul class="gb-tc-people__list">
+        <li>
+          <div class="gb-tc-person gb-tc-person--offline" title="Bao Ngo">
+            <span class="gb-tc-person__av">
+              <span class="gb-avatar gb-avatar--32" data-tone="6" aria-hidden="true">BN</span>
+              <span class="gb-tc-presence gb-tc-presence--offline">
+                <span class="gb-tc-sr">Offline</span>
+              </span>
+            </span>
+            <span class="gb-tc-person__text">
+              <span class="gb-tc-person__name">Bao Ngo</span>
+            </span>
+          </div>
+        </li>
+      </ul>
+    </div>
+  </div>
+</aside>
+```
+
+**What a plain-HTML surface does itself** (the React components do it): Enter sends and Shift+Enter is a new line, but not
+during an IME composition (`isComposing`, keyCode 229); the field grows with its text (`field-sizing: content`; where a
+browser lacks it, set `height` from `scrollHeight` through CSSOM, which a `style-src 'self'` CSP allows); Escape or the scrim
+closes a drawer, focus moves into it and back, the rail and the conversation are `inert` meanwhile; the reaction picker's
+open state (`gb-tc-msg--active`, `aria-expanded` on its button); arrow keys along `div.gb-tc-acts[role=toolbar]`; when to
+show `.gb-tc-jump` and its count.
+
 ## Action card (0.28.0): an assistant proposes, a person applies
 
 Chris 08/10/2026: the Feedback Assistant lists likely duplicates and merges them, and carries out status, owner, label