@gemboss/ui 0.7.2 → 0.8.1

package/README.md

@@ -40,6 +40,55 @@ Surfaces with no React (gemcare, gempress) use the CSS alone and write the same
 `nav.icon-nav > .gnav-scroll > .gnav-group > a.gnav-item > span.gnav-ico + span.gnav-label`.
 `packages/ui/src/shell.tsx` is the reference.
 
+## Page width (0.8.1)
+
+Chris, 04/10/2026: the rail on the left, and on the right a content column with the same max width on every
+service, not edge to edge. The tiers are the admin's (`gemboss-shell.css`, `.gemboss-w-*` around a Polaris Page),
+same numbers; `page-width.test.tsx` fails if the admin and the package disagree.
+
+| Tier | Class | Max width | For | Admin |
+|---|---|---|---|---|
+| `default` | `ui-page` | `--ui-content-max` (900px) | lists, tables, card grids, dashboards, detail pages | bare Page, `.gemboss-w-gallery`, `.gemboss-w-dashboard` |
+| `feed` | `ui-page ui-page--feed` | 720px | read top to bottom: activity, logs, timelines, a thread | `.gemboss-w-feed` |
+| `form` | `ui-page ui-page--form` | 662px | one column of fields: settings, a create form | `.gemboss-w-form` (Polaris narrowWidth) |
+| `canvas` | `ui-page ui-page--canvas` | 1440px | content measured to be wider than a column of text: a horizontal path, a wide comparison table | `.gemboss-w-canvas` (funnel path, 864px needed) |
+| `full` | `ui-page ui-page--full` | none | a board or an editor that IS the screen. Write the reason next to it. | the editor (fixed, its own frame) |
+
+React: one `PageContainer` directly inside `AppShell` caps every screen. Pass the CURRENT route's tier; a page
+cannot widen a cap its parent set, so a screen that needs `canvas` or `full` gets it here, not from a second
+wrapper of its own.
+
+```tsx
+<AppShell rail={rail}>
+  <PageContainer width={route === "settings" ? "form" : route === "board" ? "full" : "default"}>{page}</PageContainer>
+</AppShell>
+```
+
+`as="section"` changes the tag. `pageWidthClass("form")` returns the class string for a server template.
+`PageContainer` lives in its own plain module (`packages/ui/src/page.tsx`), not in `shell.tsx`, and `AppShell` has no width
+prop: the admin imports the shell pieces from `shell.tsx`, a client module its bundler keeps whole, and the
+admin's first-load shell budget had no room for even this much JS (240.0 / 240 KB, 04/10/2026).
+
+Plain HTML (GemFactory, gemcare, gempress): one wrapper as the first child of main.
+
+```html
+<main class="gemboss-platform-main">
+  <div class="ui-page ui-page--form">…</div>
+</main>
+```
+
+Delete the surface's own cap when it moves onto a tier (`maxWidth: 1160` on each gemwatcher screen, a
+`max-width` on a `.container`): two caps on one column means the narrower one wins and nobody can tell which.
+
+**A cap only exists where it is SMALLER than the room it sits in.** Right of the 240px rail, inside main's 24px
+padding, the room is `viewport − 288`: 992 at 1280, 1152 at 1440, 1632 at 1920. So 900 bites at all three, and
+1440 (`canvas`) bites only from about 1730px; below that the column is just the room. Before you quote a width,
+check `cap < viewport − rail − padding` at the width people actually use (the admin shipped two caps, 1040 then
+998, that were wider than the room at 1277 and did nothing there, 10/09/2026). The column is never wider than
+the room, so no tier makes a page scroll sideways; at ≤760px there is no rail and the column is `viewport − 32`.
+
+The page must reset `body { margin: 0 }` itself: `gemboss-ui.css` does not (the admin gets it from Polaris).
+
 ## The sign-in screen
 
 ```tsx
@@ -85,17 +134,27 @@ A live run is never thrown off screen (`assistant/dock.ts` holds that rule). The
 its top edge and slides along the bottom, by pointer or keyboard, and remembers both under
 `storagePrefix`.
 
-The side panel is opt-in: `<AssistantHost allowSide>` puts a "Pin to the side" button in the popup
-header, and the panel carries "Float as a popup" back. It stands under the topbar on the right, and
+The side panel is the DEFAULT shape since 0.8.0 (Chris, 04/10/2026): a browser that never chose opens the assistant
+there, and `allowSide` defaults to true — a surface whose layout cannot make room passes `allowSide={false}` and gets
+the popup. The popup header has "Pin to the side", and the panel carries "Float as a popup" back; the choice is kept
+under `<prefix>.shape` (the older `floatShape` key recorded the old default for everyone, so it is not read). The rail
+link reopens in that shape unless the person last worked full screen. A popup opens as tall as the window allows,
+12px under the topbar (it was min(480, viewport − 176)); a height the person dragged to is kept, and dragging it back
+to the top returns to "as tall as the window allows".
+
+**Upgrading to 0.8.0:** a host that never passed `allowSide` now offers the panel. Its page must make room — render
+inside `AppShell` (`.gemboss-platform-main` takes the margin) or pad by `var(--gb-assistant-side-w)` while
+`<prefix>-side` is on `<body>` — or pass `allowSide={false}`. A full-screen "shrink" handler should call `reopen()`
+(back to the working shape), not `openDock()`, which records "popup" as the person's choice. It stands under the topbar on the right, and
 the page moves over for it instead of being covered: the provider puts `<prefix>-side` on `<body>` and
 the width in `--gb-assistant-side-w` (`SIDE_WIDTH_VAR`), and `.gemboss-platform-main` takes that as
 `margin-right`. A surface with its own layout reads the same variable. Its left edge is a
 `.ui-resizer` (drag, or ←/→, Shift for 64px, Home/End), clamped to 380–720px and never leaving the page
 less than 480px; the width is remembered. Panel and page only fit side by side from 1100px (rail 240
-+ 380 + 480). Between 761 and 1099 the panel covers the content area and is not offered; on a phone
-it takes the screen. The status bar, a busy ×, leaving full screen mid-run and full
++ 380 + 480). Between 761 and 1099 the panel covers the content area and is not offered — the host
+withdraws `allowSide` there (`SIDE_FITS_QUERY`), so even the default opens the popup; on a phone it takes the screen. The status bar, a busy ×, leaving full screen mid-run and full
 screen's own way back ("Back to the side panel") all return to whichever shape the person last
-worked in (`floatShape`, remembered across reloads), so a pinned panel never pops back as a popup.
+worked in (`floatShape`, remembered across reloads under `<prefix>.shape`), so a pinned panel never pops back as a popup.
 The host registers `allowSide` with the provider, and every way into the panel checks it, including
 a "side" remembered in storage: a host without it gets the popup.
 
@@ -201,6 +260,7 @@ surfaces on the package, the same gaps were filled six ways. What 0.5.0 settles,
 |---|---|---|
 | Control height: `gemboss-field`, `ui-select`, `ui-btn`, `ui-seg` | **32px** (Polaris TextField / Select), `--ui-control-h` | **44px**, `ui-btn--sm` included |
 | `ui-btn--sm` | 28px | 44px |
+| `ui-btn` inside a popup's head or foot (0.7.3) | 28px, 12px | 44px |
 | Focus ring, every control | 2px iris `--ui-focus` (= `--gemboss-accent`, the admin's `--p-color-border-focus`) | same |
 | Body text (`html`, `body`, at zero specificity) | 13px / 20px, weight 450, `--gemboss-text`, antialiased (Polaris bodyMd) | same |
 | Kit text (tabs, table, notice, pager, empty, page-head lead) | `--ui-fs-body`, 13px | 16px in fields (iOS zoom) |
@@ -248,6 +308,42 @@ If your surface still sets any of these itself (a `body { font-size }`, a `min-h
 cascade over the package's zero-specificity base. `packages/ui/src/kit-look.test.ts` measures the table above in
 Chromium on the built CSS.
 
+## Popup density (0.7.3)
+
+The kit popup (`.ui-overlay > .ui-modal`, `<dialog class="ui-modal">`, `openModal`, `Dialog`) is drawn at Polaris
+Modal's density, the popup the admin opens. Chris, 04/10/2026, on GemFactory's detail popup: the admin's buttons are
+smaller and save room (GemFeedback #1099). Measured at 1280 with a mouse:
+
+| | Polaris Modal (admin) | 0.7.1 / 0.7.3 | 0.7.3 |
+|---|---|---|---|
+| × | 28×28 | 44×44 at every pointer | **28×28**; 44×44 under a thumb or ≤ 767px wide (head stays 53) |
+| Head | 53px, padding 12/16 | 61px, padding 16/20 | **53px**, padding 12/16, `align-items: center` |
+| Title | 14px / 650 | 15px / 620 | **14px / 650** |
+| `ui-btn` in `__head` / `__foot` | 28 tall, 12px, padding 0/12 | 32, 13px, 0/16 | **28, 12px, 0/12**; 44 under a thumb or ≤ 767px |
+| Body / foot padding | 16 / 16 | 16/20 / 12/20 | **16 / 12/16** |
+| Scrim | rgba(0,0,0,.5), no blur | .6, blur 2px | **.5, no blur** (`::backdrop` too) |
+
+Popup only: `--ui-control-h` stays 32, and a button outside a popup is still 32 tall.
+
+`.ui-modal__body` and `.ui-modal__foot` moved from `kit-plain.css` to `ui.css`. The admin loads `ui.css` and not
+`kit-plain.css`, so before 0.7.3 its kit popups drew a body with no padding and two foot buttons touching
+(AutopilotConfirmModal). The scrolling layout of a tall popup stays in `kit-plain.css`.
+
+A large popup can keep its subtitle and its own actions in the kit head instead of drawing a second bar
+(`kit-plain.css`):
+
+```html
+<div class="ui-modal__head">
+  <div class="ui-modal__title">Mega menu<span class="ui-modal__subtitle">chrome/header</span></div>
+  <div class="ui-modal__actions"><button class="ui-btn">Copy</button><button class="ui-btn ui-btn--icon" aria-label="More">…</button></div>
+  <button type="button" class="ui-modal__close" aria-label="Close">…</button>
+</div>
+```
+
+`packages/ui/src/modal-density.test.ts` measures the table in Chromium at 1280 (mouse), 390 and under a finger, on
+`gemboss-ui.css` and on the admin's sheets alone. `UI_MODAL_ROOT=<a 0.7.1 tree>` runs it against the old CSS, where
+it is red.
+
 ## Resizable panels
 
 `ui-resizer` is the seam a person drags between two panels; `ui-resizing` on `<body>` is the drag in
@@ -428,6 +524,31 @@ surface computes every number and ratio; the kit only draws. Markup for each is
 - `ui-grid--2` / `--3`: card grid that drops to one column; `ui-section-head`: an `h2` + note between page head and
   card titles.
 
+## Long lists: pages or "load more" (0.7.3)
+
+*Recommendation, not a rule: Claude, 04/10/2026, after Chris asked it to decide for GemFactory.*
+
+| List | Pattern | Why |
+|---|---|---|
+| A work list: items with an #ID, filters, a review queue, links people send each other (GemFactory board) | **Pages**, `ui-pager` with numbers, position in the URL (`?p=3`) | Back returns to the same place, a link opens the same page, the total is visible. Infinite scroll loses all three. |
+| One column of a Kanban (GemFactory), or a feed read top to bottom | **Load more**, `ui-more` | Nobody jumps to page 9 of one column or of a feed. |
+
+`ui-pager`: `<a rel="prev">` · page links · `<span class="ui-pager__gap" aria-hidden="true">…</span>` · the current page as
+`<a aria-current="page">` (filled) · `<a rel="next">` · `<span class="ui-pager__range">201–250 of 655</span>` (pushed right).
+On the first or last page the edge is `<a role="link" aria-disabled="true">` with no `href`: a screen reader still reads a
+link and says it is unavailable (a `<span aria-disabled>` has no role, so it reads as plain text). It is muted and does
+not react to hover. Page links are at least 32x32, 44x44 under a finger. Arrow and word are two flex items, hence the 4px
+gap. Under 576px only Previous · the current page · Next stay and the range wraps under them (eleven 44px targets
+took three to four rows at 320). The old form `<span aria-current="page">2 / 9</span>` keeps its muted look. The surface computes which numbers to
+show (first, last, current ± 1, a gap only where it hides two or more pages: GemFactory `pageWindow`).
+
+`ui-more`: one centred row. Idle: a `ui-btn` ("Show 24 more"). Loading: `<span class="ui-spinner" aria-hidden="true">` +
+`<span role="status">Loading…</span>`. Error: `<span role="alert">Couldn't load.</span>` + "Try again". End: a line. As an
+IntersectionObserver sentinel it has height from its padding; zero the padding and it has none.
+
+`.ui-prose` links are at `:where()` specificity, so a component's own link rule (`ui-pager`, `ui-seg`, `ui-tabs`) wins
+inside a page-wide `.ui-prose` (GemFactory wraps every page in it; its page numbers were drawn as blue underlined text).
+
 ## The catalog: every token, class and component, with its markup
 
 `npm run catalog` builds `catalog/index.html` (also shipped in the npm tarball, and built by `prepack`):
@@ -475,7 +596,7 @@ something the base cannot express, add a token or a prop here, and every surface
 | `packages/ui/src/shell.css` | the SHARED SHELL (rail, topbar, main, mobile drawer, the assistant's thread rail, popover surface, account chip). The admin's `gemboss-shell.css` @imports it on line 2; the export refuses a shared-shell rule in the admin's sheet or an admin-only rule here (one owner). |
 | `packages/ui/src/kit-plain.css` | primitives for surfaces that render plain HTML, not React (0.2.1): menu, key/value list, icon button; 0.3.0 adds `ui-link` / `ui-prose`, the media card (`ui-card--media`, `__media`, `__body`, `__foot`) and the popup's `ui-modal__body` / `__foot`. Shipped inside `gemboss-ui.css`; the admin does not import it (its first-load CSS budget has ~0.1 KB headroom).; (0.4.0) report pages: delta, large KPI grid, bar list, column chart, legend, funnel, card grid, section head. |
 | `packages/ui/src/kit-plain.js` | 0.3.0: the behaviour those surfaces each wrote by hand: `gembossUI.openModal` (Escape, backdrop, Tab trap, stacking, ask-before-close, focus back), `toast` (text, error tone), `initMenus` (outside click, item, blur, Escape closes the menu before the popup); 0.5.0: `confirm`, `initShell`, `initPasswordFields` / `resetPasswordFields`. A classic script: inline it or `<script src>`; see "Plain-HTML behaviour" above. |
-| `packages/ui/src/chat.css`, `chat-composer.css`, `assistant.css`, `auth.css`, `app-shell.css` | the chat body, the composer, the assistant frame, the sign-in screen, the topbar slots + base text. All inside `gemboss-ui.css`; the admin @imports `chat.css` and `chat-composer.css` itself. |
+| `packages/ui/src/chat.css`, `chat-composer.css`, `assistant.css`, `auth.css`, `app-shell.css` | the chat body, the composer, the assistant frame, the sign-in screen, the topbar slots + base text + the page width tiers (`ui-page`, 0.8.1). All inside `gemboss-ui.css`; the admin @imports `chat.css` and `chat-composer.css` itself. |
 | `packages/ui/src/icon.svg` | 0.5.0: the GemBoss app icon, for `<link rel="icon" type="image/svg+xml">`. Must stay byte-identical to `apps/admin/src/app/icon.svg` (`kit-look.test.ts` checks). |
 | `packages/ui/src/**/*.tsx` | the components, as TypeScript source. Next: add `@gemboss/ui` to `transpilePackages`. Vite compiles it as is. |