@gemboss/ui 0.6.9 → 0.7.2

package/README.md

@@ -360,6 +360,55 @@ The admin's "Search ⌘K" box for every surface, as a real form (works with no J
 - Shortcut on a page without React: `gembossUI.initSearch()` from `kit-plain.js` (⌘K / Ctrl+K and "/" focus it,
   Escape leaves it). "/" is ignored while another field has focus.
 
+## Public portal pieces (0.7.0)
+
+For public surfaces laid out like the GemPages Featurebase board (GemFeedback) and for GemCommunity's
+"Top contributors" (Chris, 04/10/2026: one leaderboard for both, with medals, in the kit).
+
+```tsx
+import { Avatar, Dialog, Leaderboard, Podium, SearchDialog, ThemeToggle, themeScript, TopbarNav } from "@gemboss/ui";
+
+<Topbar>
+  <div className="gemboss-topbar-start"><BrandLockup name="GemFeedback" href="/" />
+    <TopbarNav as={Link} items={[{ href: "/", label: "Feedback", active: true }, { href: "/roadmap", label: "Roadmap" }]} /></div>
+  <div className="gemboss-topbar-center" />
+  <div className="gemboss-topbar-end"><SearchDialog search={find} initial={trending} fallbackHref="/?q=" /><ThemeToggle /></div>
+</Topbar>
+<head><script dangerouslySetInnerHTML={{ __html: themeScript }} /></head>   // no white flash in dark
+<Leaderboard title="Most helpful" rows={[{ key, name, value, avatar, href }]} unit="votes" viewAll={{ href, label }} />
+<Dialog open={open} onClose={close} title="Sign in">…</Dialog>
+```
+
+- `TopbarNav`: section tabs in the topbar after the brand, the active one underlined on the topbar's
+  edge. A topbar holding tabs drops the centre search column (`:has(.gb-topnav)`), so the tabs get the
+  room. 36px under a mouse, 44px under a finger. Under 600px the tabs fold into one button naming the
+  open tab, with the tabs in a list under it (a row that scrolls sideways hid the third tab at 390).
+- `SearchDialog`: the topbar search button opening a 640px popup (Featurebase's, the admin's ⌘K).
+  `initial` before typing, `search(q)` while typing (150 ms debounce, latest answer wins); ↑ ↓ Enter
+  Esc; ⌘K / Ctrl+K and "/" open it. Results are links; without JavaScript the button goes to
+  `fallbackHref`.
+- `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. `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.
+- `Leaderboard`: 🥇 🥈 🥉 then the rank, avatar, name, count; the leader's count in gold; nothing at
+  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)
 
 Plain CSS in `kit-plain.css` for a numbers page written by hand (first user: gemnews `/admin`, 03/10/2026; that page moved to GemCommunity the same day, so gemnews no longer takes the package). The