@gemboss/ui 0.7.1 → 0.8.0

package/README.md

@@ -85,17 +85,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 +211,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 +259,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
@@ -390,7 +437,7 @@ import { Avatar, Dialog, Leaderboard, Podium, SearchDialog, ThemeToggle, themeSc
 - `Dialog`: the kit's native `<dialog class="ui-modal">` (see kit-plain.css) driven by `open`; a
   backdrop click closes it, focus returns to the opener.
 - `ThemeToggle` + `themeScript`: `data-theme="dark|light"` on <html>, remembered in localStorage
-  (`gemboss-theme`), the OS's choice until then. `portal.css` redefines every `--gemboss-*` colour under
+  (`gemboss-theme`), the OS's choice until then. `theme-dark.css` (in `gemboss-ui.css`) redefines every `--gemboss-*` colour under
   `[data-theme="dark"]` (a test fails if a colour token is left out), so every kit class follows.
   Opt-in: a surface without it (the admin) stays light.
 - `Avatar` (24 · 32 · 40 · 56): picture or initials on one of eight tones picked from the name.
@@ -398,6 +445,16 @@ import { Avatar, Dialog, Leaderboard, Podium, SearchDialog, ThemeToggle, themeSc
   all when empty. `Podium`: the first three, second · first · third.
 - `initialsOf` moved to `initials.ts` (plain, not "use client") so server components can call it; it is
   still exported from the package and from account.tsx.
+- **Without the whole kit (0.7.2):** a surface with its own skin (GemCommunity) takes only these pieces'
+  CSS: `@gemboss/ui/gemboss-tokens.css` (variables only, no rule) + `@gemboss/ui/portal.css`. `Avatar`,
+  `Leaderboard` and `Podium` read nothing but `--gemboss-*` tokens (a test holds that), so they look the
+  same as on GemFeedback without `gemboss-ui.css` restyling the rest of the page. `SearchDialog` and
+  `Dialog` still need `ui.css` (the modal). `portal.css` holds no rule on `:root`, `html` or `body`; the dark palette is its own file,
+  `theme-dark.css`, so a surface that uses `data-theme` for something else (GemCommunity's sign-in pages) is not
+  turned dark by importing the leaderboard.
+- Rows take `current` (the viewer's own row: tinted, and read as "Minh, you" via `currentLabel`), `badge`
+  (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.
 
 ## Report pages (0.4.0)
 
@@ -418,6 +475,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`):