@gemboss/ui 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@gemboss/ui",
+  "version": "0.1.0",
+  "description": "GemBoss design system for every surface in the fleet: the admin shell (topbar + rail + drawer) as React components, and the admin stylesheet exported as one CSS file.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./gemboss-ui.css": "./gemboss-ui.css",
+    "./gemboss-tokens.css": "./src/gemboss-tokens.css",
+    "./ui.css": "./src/ui.css",
+    "./gemboss-field.css": "./src/gemboss-field.css",
+    "./app-shell.css": "./src/app-shell.css",
+    "./shell.css": "./src/shell.css",
+    "./auth.css": "./src/auth.css",
+    "./assistant": "./src/assistant/index.ts",
+    "./assistant/dock": "./src/assistant/dock.ts",
+    "./assistant.css": "./src/assistant.css"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/*.css",
+    "!src/**/*.test.*",
+    "gemboss-ui.css",
+    "catalog/index.html",
+    "README.md"
+  ],
+  "scripts": {
+    "build:css": "node scripts/build-css.mjs",
+    "prepack": "node scripts/build-css.mjs && node scripts/build-catalog.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "catalog": "node scripts/build-css.mjs && node scripts/build-catalog.mjs"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chriskoh26/gemboss",
+    "directory": "packages/ui"
+  }
+}

package/src/GemMark.tsx

@@ -0,0 +1,22 @@
+/**
+ * The brilliant-cut gem: white outline on an ink tile, iris only in the table facet. The same
+ * geometry as public/gemboss-mark.svg and the admin sign-in; content-radar, gemwatcher and the
+ * community login each carried a hand copy of these three paths.
+ */
+import React from "react";
+
+export function GemMark({ size = 32, tile = "var(--gb-mark-bg, #0b0b0c)" }: { size?: number; tile?: string }) {
+  return (
+    <svg viewBox="0 0 32 32" width={size} height={size} aria-hidden="true" focusable="false">
+      {/* `style`, not the `fill` attribute: var() in a presentation attribute is not read by every
+          browser, and the fallback is near-black anyway, so a lost override would go unnoticed. */}
+      <rect width="32" height="32" rx="7" style={{ fill: tile }} />
+      <g transform="translate(16,16) scale(0.24) translate(-50,-62)">
+        <polygon points="26,14 74,14 66,50 34,50" fill="#8a93ff" />
+        <path d="M26,14 74,14 96,50 50,110 4,50Z" fill="none" stroke="#f4f4f2" strokeWidth="5" strokeLinejoin="round" />
+        <path d="M4,50H96M26,14 34,50M74,14 66,50M34,50 50,110M66,50 50,110" fill="none" stroke="#f4f4f2"
+              strokeOpacity="0.72" strokeWidth="3" strokeLinejoin="round" />
+      </g>
+    </svg>
+  );
+}

package/src/account.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+/**
+ * The account chip at the right of the topbar, and its menu — @gemboss/ui (28/09/2026).
+ *
+ * The admin's is `AccountChip` (apps/admin/src/components/shell/AccountChip.tsx): a 32px initials
+ * circle that opens a popover with name, email and role, then the menu items. Its CSS
+ * (`.gemboss-account-chip / -menu / -menu-item`, on `.gemboss-popover-surface`) now reaches other
+ * surfaces through gemboss-ui.css; this renders the same classes, so the look has one owner.
+ *
+ * A `<details>`, not state: it opens and closes with no JavaScript at all, so a surface that renders
+ * static HTML (GemFactory) gets a working menu from the markup alone. Where React does hydrate, the
+ * effect below adds what `<details>` lacks: close on a click outside, and on Escape.
+ */
+import React, { useEffect, useRef } from "react";
+
+export function initialsOf(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return "?";
+  const letters = words.length === 1 ? words[0].slice(0, 2) : words[0][0] + words[words.length - 1][0];
+  return letters.toUpperCase();
+}
+
+export function AccountMenu({ name, email, role, initials, label, children }: {
+  name: string;
+  email?: string;
+  role?: string;
+  /** Defaults to the first and last word's first letters ("Minh Anh" → "MA"). */
+  initials?: string;
+  /** Accessible name of the chip. Default "Account · <name>". */
+  label?: string;
+  /** The menu's items: `AccountMenuItem`s, or any element wearing `gemboss-account-menu-item`. */
+  children?: React.ReactNode;
+}) {
+  const ref = useRef<HTMLDetailsElement>(null);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    const onDoc = (e: MouseEvent) => { if (el.open && !el.contains(e.target as Node)) el.open = false; };
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape" && el.open) { el.open = false; el.querySelector("summary")?.focus(); } };
+    document.addEventListener("click", onDoc);
+    document.addEventListener("keydown", onKey);
+    return () => { document.removeEventListener("click", onDoc); document.removeEventListener("keydown", onKey); };
+  }, []);
+  return (
+    <details ref={ref} className="gb-account">
+      <summary className="gemboss-account-chip" aria-label={label ?? `Account · ${name}`} title={name}>
+        {initials ?? initialsOf(name)}
+      </summary>
+      <div role="menu" className="gemboss-popover-surface gemboss-account-menu">
+        <div className="gb-account-head">
+          <div className="gb-account-name">{name}</div>
+          {email ? <div className="gb-account-email">{email}</div> : null}
+          {role ? <div className="gb-account-role">{role}</div> : null}
+        </div>
+        {children}
+      </div>
+    </details>
+  );
+}
+
+/** One row of the account menu: a link (`href`), a button, or the submit button of a form — a POST
+ *  sign-out works without JavaScript. `danger` for the destructive row (sign out). A button row closes
+ *  the menu after its handler, as the admin's does; a link or a form leaves the page anyway. */
+export function AccountMenuItem({ href, formAction, danger, children, onClick, ...rest }: {
+  href?: string;
+  /** Renders `<form method="post" action=…>` around a submit button. */
+  formAction?: string;
+  danger?: boolean;
+  children?: React.ReactNode;
+  onClick?: React.MouseEventHandler<HTMLElement>;
+} & Omit<React.HTMLAttributes<HTMLElement>, "onClick"> & Pick<React.AnchorHTMLAttributes<HTMLAnchorElement>, "target" | "rel" | "download">) {
+  const className = danger ? "gemboss-account-menu-item danger" : "gemboss-account-menu-item";
+  // Every prop reaches whichever element renders — a link row used to drop `onClick`, `target`, `aria-*`.
+  if (href) return <a role="menuitem" className={className} href={href} onClick={onClick} {...rest}>{children}</a>;
+  if (formAction) {
+    return (
+      <form method="post" action={formAction} className="gb-account-form">
+        <button role="menuitem" type="submit" className={className} onClick={onClick} {...rest}>{children}</button>
+      </form>
+    );
+  }
+  const close: React.MouseEventHandler<HTMLButtonElement> = (e) => {
+    onClick?.(e);
+    e.currentTarget.closest("details")?.removeAttribute("open");
+  };
+  return <button role="menuitem" type="button" className={className} onClick={close} {...rest}>{children}</button>;
+}

package/src/app-shell.css

@@ -0,0 +1,65 @@
+/* Styles for the parts of the shell the PACKAGE owns — `AppShell`'s three topbar slots,
+ * `RailHeading`, `RailCount`. Everything else (rail, topbar, drawer, tokens, kit) is the admin's
+ * own CSS, exported by apps/admin/scripts/export-ui-css.mjs and concatenated ahead of this file into
+ * `gemboss-ui.css`. The admin does not load this file: it composes the shell itself and has no
+ * slots, headings or pills of this kind.
+ *
+ * Built only from --gemboss-* tokens, so a palette change in gemboss-tokens.css reaches it. */
+
+/* The base font. The admin's comes from Polaris, which no other surface loads, so without this rule
+ * every surface on gemboss-ui.css rendered in the browser's default serif. Same elements Polaris
+ * sets (html, body, button), same stack (--gemboss-font-sans resolves to Polaris's
+ * --p-font-family-sans fallback). `:where()` keeps it at (0,0,0): any rule a surface writes for
+ * these elements wins, wherever it sits in the cascade. Re-theme with the token, not a body rule.
+ * The admin does not load this file, so its own rendering is untouched. */
+:where(html, body, button) { font-family: var(--gemboss-font-sans); }
+
+.gemboss-topbar-start { display: flex; align-items: center; gap: 8px; min-width: 0; }
+.gemboss-topbar-center { display: flex; justify-content: center; min-width: 0; }
+.gemboss-topbar-end { display: flex; align-items: center; justify-content: flex-end; gap: 8px; min-width: 0; }
+@media (max-width: 760px) {
+  /* The topbar is one flex row here: the middle slot takes what is left. */
+  .gemboss-topbar-center { flex: 1 1 auto; justify-content: flex-start; }
+}
+
+.gnav-heading {
+  padding: 10px 12px 4px;
+  font-size: var(--gemboss-fs-micro); font-weight: 600; line-height: 1.2;
+  letter-spacing: 0.08em; text-transform: uppercase;
+  color: var(--gemboss-text-muted);
+}
+.gnav-scroll > .gnav-heading:first-child { padding-top: 2px; }
+
+.gnav-count {
+  margin-left: auto; flex: 0 0 auto; min-width: 20px; padding: 0 6px;
+  border-radius: var(--gemboss-radius-full);
+  background: var(--gemboss-hover); color: var(--gemboss-text-muted);
+  font-size: var(--gemboss-fs-micro); font-weight: 700; line-height: 18px;
+  text-align: center; font-variant-numeric: tabular-nums;
+}
+.gnav-item.active .gnav-count { background: var(--gemboss-primary); color: var(--gemboss-on-primary); }
+
+/* ── BrandLockup (./brand.tsx) ─────────────────────────────────────────────────────────────────
+ * The admin's `.gemboss-brand-lockup` box (40px tall, 8px padding, hover wash) around the wordmark's
+ * own proportions. Not that class itself: its ≤460px rule swaps in a background image at an
+ * admin-only path, which every other host would 404. Ink is the logo file's #14151a. */
+.gb-brand {
+  min-width: 0; height: 40px; margin: 0; padding: 0 8px;
+  border-radius: var(--gemboss-radius-md);
+  display: inline-flex; align-items: center; gap: 4.5px;
+  color: var(--gb-brand-ink, #14151a); text-decoration: none;
+  transition: background-color var(--gemboss-transition-base) ease;
+}
+.gb-brand:hover { background: var(--gemboss-hover); }
+.gb-brand:focus-visible { outline: 2px solid var(--gemboss-primary); outline-offset: 2px; }
+.gb-brand-gem { display: block; flex: 0 0 auto; }
+.gb-brand-name {
+  font-family: Inter, var(--gemboss-font-sans); font-size: 13.3px; font-weight: 700;
+  letter-spacing: -0.13px; line-height: 1; white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis; min-width: 0;
+}
+/* The admin shows only its mark below 460px; so does this. */
+@media (max-width: 460px) { .gb-brand-name { display: none; } }
+
+/* ── AccountMenu (./account.tsx): its rules live in shell.css since 29/09/2026, because the admin
+ * renders AccountMenu too now and loads shell.css, not this file. */

package/src/assistant/dock.ts

@@ -0,0 +1,142 @@
+/**
+ * How the assistant is PRESENTED, kept apart from the assistant itself.
+ *
+ * Moved from gemboss apps/admin/src/lib/assistant-dock.ts into @gemboss/ui (28/09/2026) so every
+ * surface that has an assistant — the admin, gemwatcher, content-radar — gets the same rules for when
+ * it shows, hides and collapses. The admin file re-exports this one.
+ *
+ * The bug this exists to kill: the assistant lived only at `/app/assistant`, so opening any
+ * other menu unmounted it — and `GemChat`'s unmount cleanup aborts the in-flight run. A seller
+ * who asked for a theme and then clicked Products came back to a dead turn with no answer and
+ * no error. Nothing in the UI said the run had been thrown away.
+ *
+ * The fix is to mount the assistant ONCE in the app shell and only change its geometry. This
+ * module owns the geometry decision as a pure reducer so the transitions are testable without
+ * a browser, and so the rule "a live run is never hidden" is stated in one place instead of
+ * being spread over three components' effects.
+ */
+
+/** Where the assistant is drawn. `hidden` still means MOUNTED — the run keeps going. */
+export type AssistantPresentation = "hidden" | "mini" | "dock" | "full";
+
+export interface AssistantDockState {
+  presentation: AssistantPresentation;
+  /** Mounted at all? The chat bundle is only pulled in once the seller first opens the assistant. */
+  mounted: boolean;
+  /** A turn is running right now (reported by the chat itself). */
+  busy: boolean;
+  /** A run finished while the seller was looking elsewhere — worth a dot on the rail. */
+  unread: boolean;
+  /** Dock height in px (seller-resizable, persisted). */
+  dockHeight: number;
+  /** Distance from the window's RIGHT edge, in px — the popup slides sideways along the bottom.
+   *  Anchored right, not left, so a narrower window moves it with the edge instead of off screen. */
+  dockOffsetRight: number;
+  /** Bumped every time the assistant is brought back on screen. Lets a mount that already exists
+   *  pick up a question handed over from ⌘K, which a mount-time read would only ever see once. */
+  openNonce: number;
+}
+
+export type AssistantDockEvent =
+  /** the /app/assistant route mounted */
+  | { type: "enter-full" }
+  /** the /app/assistant route unmounted — the seller opened another menu */
+  | { type: "leave-full" }
+  /** show the floating popup (restore from mini, or open it from anywhere) */
+  | { type: "dock" }
+  /** dock → the small status bar */
+  | { type: "minimize" }
+  /** the popup's × */
+  | { type: "dismiss" }
+  | { type: "busy"; busy: boolean }
+  | { type: "resize"; height: number; viewport: number }
+  | { type: "slide"; offsetRight: number; min: number; max: number };
+
+/** Tall enough for the composer, a status line and two message rows. */
+export const DOCK_MIN_HEIGHT = 280;
+export const DOCK_DEFAULT_HEIGHT = 480;
+/**
+ * Topbar (56) + a 12px gap: the tallest the popup may grow.
+ *
+ * Was 88 — a 32px band of dead page between the topbar and a fully-grown popup, which read as the
+ * popup stopping short rather than filling the room it was given. Chris asked for 10–15px; 12 keeps
+ * the topbar's shadow visibly separate from the popup's own top edge.
+ */
+export const DOCK_TOPBAR_HEIGHT = 56;
+export const DOCK_TOPBAR_GAP = 12;
+export const DOCK_VIEWPORT_RESERVE = DOCK_TOPBAR_HEIGHT + DOCK_TOPBAR_GAP;
+/** Matches the CSS `right: 24px` the popup starts at. */
+export const DOCK_DEFAULT_OFFSET_RIGHT = 24;
+
+/** Keep the popup inside the usable area: never under the rail, never off the right edge. */
+export function clampDockOffset(offsetRight: number, min: number, max: number): number {
+  if (max < min) return min;
+  return Math.min(Math.max(Math.round(offsetRight), min), max);
+}
+
+export function clampDockHeight(height: number, viewport: number): number {
+  const max = Math.max(DOCK_MIN_HEIGHT, viewport - DOCK_VIEWPORT_RESERVE);
+  return Math.min(Math.max(Math.round(height), DOCK_MIN_HEIGHT), max);
+}
+
+export const initialAssistantDockState: AssistantDockState = {
+  presentation: "hidden",
+  mounted: false,
+  busy: false,
+  unread: false,
+  dockHeight: DOCK_DEFAULT_HEIGHT,
+  dockOffsetRight: DOCK_DEFAULT_OFFSET_RIGHT,
+  openNonce: 0,
+};
+
+export function assistantDockReducer(state: AssistantDockState, event: AssistantDockEvent): AssistantDockState {
+  switch (event.type) {
+    case "enter-full":
+      return { ...state, presentation: "full", mounted: true, unread: false, openNonce: state.openNonce + 1 };
+
+    case "leave-full":
+      // Only the route that claimed full mode may release it. Without this guard a route
+      // unmounting AFTER the seller already shrank the popup by hand would yank it away again.
+      if (state.presentation !== "full") return state;
+      // A live run is never thrown off screen — that is the whole point of this file.
+      // Idle, it collapses to the status bar rather than vanishing: the popup is the only way to ask
+      // a question ABOUT the screen you are on, and with nothing on screen there was no way to open
+      // it anywhere but the assistant's own page — where there is no screen to ask about.
+      // `dismiss` on that bar is what hides it for good.
+      //
+      // There used to be a `pinned` flag here, and a 📌 in the header to set it. Two later changes
+      // ate its job: the bar already follows the seller, and the shell now reopens in whichever
+      // shape they last used. A control that no longer decides anything is worse than no control.
+      return { ...state, presentation: state.busy ? "dock" : "mini" };
+
+    case "dock":
+      return { ...state, presentation: "dock", mounted: true, unread: false, openNonce: state.openNonce + 1 };
+
+    case "minimize":
+      return { ...state, presentation: "mini" };
+
+    case "dismiss":
+      // × on a working assistant collapses to the status bar instead of hiding it: a seller who
+      // cannot see the run cannot tell it apart from one that died, which is the bug we are fixing.
+      // Stopping is a separate, explicit button in the composer.
+      // Pressing it AGAIN on that bar opens the popup rather than doing nothing twice — a button that
+      // visibly changes nothing is read as broken.
+      if (!state.busy) return { ...state, presentation: "hidden" };
+      return { ...state, presentation: state.presentation === "mini" ? "dock" : "mini" };
+
+    case "busy": {
+      if (event.busy === state.busy) return state;
+      const offscreen = state.presentation === "mini" || state.presentation === "hidden";
+      return { ...state, busy: event.busy, unread: !event.busy && offscreen ? true : state.unread };
+    }
+
+    case "resize":
+      return { ...state, dockHeight: clampDockHeight(event.height, event.viewport) };
+
+    case "slide":
+      return { ...state, dockOffsetRight: clampDockOffset(event.offsetRight, event.min, event.max) };
+
+    default:
+      return state;
+  }
+}