@ubx/docs-ui 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @ubx/docs-ui
+
+Shared UI for ubx's two documentation sites, `ubx-docs-providers` and
+`ubx-docs-users`.
+
+Extracted only after both consumers existed. Three interfaces had to
+change to be shareable at all, and one of those was not predicted:
+`MobileSidebarToggle` imported `ProviderSidebar` directly, found only
+when the second site failed to build. Extracting against a single call
+site would have carried that coupling in unnoticed.
+
+## What is here
+
+| Export | Note |
+|---|---|
+| `CodeBlock` | Shiki-backed, async server component, build-time only |
+| `themeA` | Theme A as a TextMate theme, CSS variables not hex |
+| `Header` | Takes `nav` and optional `tabs` as props |
+| `GlobalSearch` | Takes a generic `SearchEntry` |
+| `MobileSidebarToggle` | Takes drawer contents as `children` |
+| `ThemeToggle`, `Footer` | Unchanged from the originals |
+
+## Theme A and the consuming site
+
+`themeA` emits `var(--color-code-green)` and friends rather than hex, so
+the consuming site's own `globals.css` keeps driving light and dark
+through its existing `[data-theme]` contract with zero client JS. This
+package never needs to know the actual colors.
+
+The site must define: `--color-code-green`, `--color-code-red`,
+`--color-code-yellow`, `--color-foreground`, `--color-foreground-muted`,
+`--color-code-bg`.
+
+Read `src/theme-a.ts` before changing the scope mapping. The three
+overrides at the bottom were findable only by inspecting real token
+output per language, and without them the naive mapping is visibly worse
+than the hand-rolled tokenizer this replaces.

package/dist/CodeBlock.d.ts

@@ -0,0 +1,4 @@
+export declare function CodeBlock({ code, lang }: {
+    code: string;
+    lang: string;
+}): Promise<import("react").JSX.Element>;

package/dist/CodeBlock.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { codeToHtml } from "shiki";
+import { themeA, isSupportedLang } from "./theme-a";
+// Shiki-backed, replacing the hand-rolled tokenizer both sites used to
+// carry a copy of. That tokenizer's own comment already named a real
+// highlighting library as the honest long-term answer; six languages
+// across two consumers is past where hand rolling pays.
+//
+// This is an async server component. Both sites statically export, so
+// Shiki runs at build time only and contributes nothing to the client
+// bundle.
+//
+// Two behaviours are strictly better than what it replaces, both
+// verified against real token output rather than assumed:
+//   - JSON keys render yellow. The old regex matched quoted strings
+//     first, so keys came out red, which theme A reserves for string
+//     literals.
+//   - HCL attribute names render yellow. The old property rule only
+//     recognised `name:`, so HCL's `name =` was left plain.
+export async function CodeBlock({ code, lang }) {
+    const trimmed = code.replace(/\n$/, "");
+    // An unknown language renders in the same code surface, uncoloured,
+    // rather than being forced through a grammar built for something else.
+    if (!isSupportedLang(lang)) {
+        return (_jsx("pre", { className: "overflow-x-auto rounded-2xl bg-code p-4 text-sm leading-relaxed", children: _jsx("code", { className: "font-mono-tabular text-foreground", children: trimmed }) }));
+    }
+    const html = await codeToHtml(trimmed, {
+        lang,
+        theme: themeA,
+    });
+    // Shiki emits its own <pre class="shiki">; the wrapper below keeps the
+    // surface, radius and spacing identical to what both sites already
+    // render, so the swap is invisible outside the token colors themselves.
+    return (_jsx("div", { className: "overflow-x-auto rounded-2xl bg-code p-4 text-sm leading-relaxed [&_pre]:bg-transparent [&_pre]:m-0 [&_code]:font-mono-tabular", dangerouslySetInnerHTML: { __html: html } }));
+}

package/dist/Footer.d.ts

@@ -0,0 +1 @@
+export declare function Footer(): import("react").JSX.Element;

package/dist/Footer.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Footer: Material style, a hairline divider and quiet text, not a
+// heavy block -- the same restrained treatment already established
+// for hairline dividers site-wide (globals.css's own --color-border).
+// Links repeat two of Header's own real, checked destinations
+// (Documentation, GitHub) rather than inventing new ones, plus a
+// License link to this repo's own real LICENSE file (Apache 2.0,
+// confirmed directly from the file, not assumed).
+export function Footer() {
+    return (_jsx("footer", { className: "border-t border-border", children: _jsxs("div", { className: "mx-auto max-w-7xl px-6 py-8 text-sm text-foreground-muted", children: [_jsxs("div", { className: "flex flex-col items-center gap-3 sm:flex-row sm:justify-between", children: [_jsx("p", { children: "Reference content is generated from each provider\u2019s own real schema, not hand-written." }), _jsxs("nav", { className: "flex items-center gap-5", children: [_jsx("a", { href: "https://docs.ubiquex.io", className: "hover:text-primary", children: "Documentation" }), _jsx("a", { href: "https://github.com/Ubiquex", className: "hover:text-primary", children: "GitHub" }), _jsx("a", { href: "https://github.com/Ubiquex/ubx-docs-providers/blob/main/LICENSE", className: "hover:text-primary", children: "License" })] })] }), _jsx("p", { className: "mt-4 text-center text-xs sm:text-left", children: "\u00A9 2026 Ubiquex" })] }) }));
+}

package/dist/GlobalSearch.d.ts

@@ -0,0 +1,15 @@
+export type SearchEntry = {
+    title: string;
+    subtitle?: string;
+    group?: string;
+    /** Short tag rendered on the right, e.g. the provider site's "data". */
+    badge?: string;
+    path: string;
+};
+export declare function GlobalSearch({ indexUrl, placeholder, inputClassName, emptyMessage, }: {
+    indexUrl?: string;
+    placeholder: string;
+    inputClassName: string;
+    /** Rendered when a non-empty query matches nothing. */
+    emptyMessage?: (query: string) => React.ReactNode;
+}): import("react").JSX.Element;

package/dist/GlobalSearch.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import Link from "next/link";
+import { useEffect, useState } from "react";
+// PRESENTATION IS A PROP, NOT A DEFAULT, and that is deliberate.
+//
+// The first draft of this extraction silently carried the USER site's
+// input styling into the provider site, changing its search box from a
+// pill (rounded-full, px-5 py-3, text-base) to a bordered rectangle and
+// its placeholder from "Search resources and data sources..." to
+// "Search". Caught by diffing the provider site's rendered markup
+// against the live site before and after the swap. A shared component
+// quietly restyling a working site is exactly the failure mode this
+// extraction was supposed to avoid, so both consumers now state their
+// own presentation explicitly and neither inherits the other's.
+export function GlobalSearch({ indexUrl = "/search-index.json", placeholder, inputClassName, emptyMessage, }) {
+    const [index, setIndex] = useState([]);
+    const [query, setQuery] = useState("");
+    useEffect(() => {
+        fetch(indexUrl)
+            .then((r) => r.json())
+            .then(setIndex)
+            .catch(() => setIndex([]));
+    }, [indexUrl]);
+    const q = query.trim().toLowerCase();
+    const results = q
+        ? index
+            .filter((e) => e.title.toLowerCase().includes(q) ||
+            e.subtitle?.toLowerCase().includes(q) ||
+            e.group?.toLowerCase().includes(q))
+            .slice(0, 20)
+        : [];
+    return (_jsxs("div", { className: "relative", children: [_jsx("input", { type: "search", value: query, onChange: (e) => setQuery(e.target.value), placeholder: placeholder, className: inputClassName }), q && (_jsx("div", { className: "absolute z-10 mt-2 w-full rounded-2xl bg-surface shadow-lg", children: results.length === 0 ? (_jsx("p", { className: "px-4 py-3 text-sm text-foreground-muted", children: emptyMessage ? emptyMessage(query) : _jsxs(_Fragment, { children: ["No matches for \u201C", query, "\u201D."] }) })) : (_jsx("ul", { className: "max-h-96 overflow-y-auto divide-y divide-border", children: results.map((r) => (_jsx("li", { children: _jsxs(Link, { href: r.path, className: "flex items-center justify-between gap-3 px-4 py-2 text-sm hover:bg-surface", children: [_jsxs("span", { children: [_jsx("span", { className: "text-primary", children: r.title }), r.subtitle ? (_jsx("span", { className: "ml-2 text-xs text-foreground-muted", children: r.subtitle })) : null] }), r.badge ? (_jsx("span", { className: "shrink-0 rounded-full bg-foreground-muted/10 px-2 py-0.5 text-xs text-foreground-muted", children: r.badge })) : null] }) }, r.path))) })) }))] }));
+}

package/dist/Header.d.ts

@@ -0,0 +1,18 @@
+export type NavLink = {
+    label: string;
+    href: string;
+    /** Marks the destination representing the current site. */
+    current?: boolean;
+};
+export type SectionTab = {
+    label: string;
+    href: string;
+};
+export declare function Header({ nav, tabs, activeTab, mobileMenu, }: {
+    nav: NavLink[];
+    /** Omit entirely for a single-tier header, which is the provider site. */
+    tabs?: SectionTab[];
+    /** href of the active tab, matched by prefix so nested pages stay lit. */
+    activeTab?: string;
+    mobileMenu?: React.ReactNode;
+}): import("react").JSX.Element;

package/dist/Header.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Link from "next/link";
+import { ThemeToggle } from "./ThemeToggle";
+export function Header({ nav, tabs, activeTab, mobileMenu, }) {
+    return (_jsxs("header", { className: "border-b border-border bg-background", children: [_jsxs("div", { className: "relative mx-auto flex max-w-7xl items-center gap-3 px-6 py-4", children: [mobileMenu, _jsxs(Link, { href: "/", className: "flex shrink-0 items-center", children: [_jsx("img", { src: "/logo/logo.png", alt: "ubx", className: "logo-light h-6 w-auto" }), _jsx("img", { src: "/logo/logo-dark.png", alt: "ubx", className: "logo-dark h-6 w-auto" })] }), _jsx("div", { className: "flex-1" }), _jsx("nav", { className: "absolute left-1/2 hidden -translate-x-1/2 items-center gap-5 md:flex", children: nav.map((item) => {
+                            const className = item.current
+                                ? "text-sm text-primary"
+                                : "text-sm text-foreground-muted hover:text-primary";
+                            return item.href.startsWith("/") ? (_jsx(Link, { href: item.href, className: className, children: item.label }, item.label)) : (_jsx("a", { href: item.href, className: className, children: item.label }, item.label));
+                        }) }), _jsx(ThemeToggle, {})] }), tabs && tabs.length > 0 ? (_jsx("div", { className: "mx-auto max-w-7xl px-6", children: _jsx("nav", { className: "flex gap-6 overflow-x-auto", children: tabs.map((tab) => {
+                        // Prefix match, so /concepts/ledger keeps the Concepts tab
+                        // lit rather than only the exact section index.
+                        const active = activeTab === tab.href || activeTab?.startsWith(tab.href + "/");
+                        return (_jsx(Link, { href: tab.href, className: active
+                                ? "-mb-px border-b-2 border-primary py-2 text-sm text-primary"
+                                : "-mb-px border-b-2 border-transparent py-2 text-sm text-foreground-muted hover:text-primary", children: tab.label }, tab.href));
+                    }) }) })) : null] }));
+}

package/dist/MobileSidebarToggle.d.ts

@@ -0,0 +1,3 @@
+export declare function MobileSidebarToggle({ children }: {
+    children: React.ReactNode;
+}): import("react").JSX.Element;

package/dist/MobileSidebarToggle.js

@@ -0,0 +1,75 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { usePathname } from "next/navigation";
+import { useEffect, useRef, useState } from "react";
+// Opens from the header, since the desktop sidebar (ProviderSidebar's
+// own "hidden lg:block" rail) contributes nothing below that
+// breakpoint -- without this, a reader on mobile has no way to reach
+// a provider's service groups or resources at all once past the
+// provider home page. Renders the identical ProviderSidebar (same
+// fetch, same filter, same tree) inside a drawer rather than a
+// second, parallel mobile nav that could drift from the real one.
+//
+// Two-state open/close (mounted + visible, not a single boolean) so
+// the close transition has time to actually play: closing flips
+// `visible` off immediately (the CSS transition animates toward the
+// closed position) and only removes the drawer from the DOM once that
+// transition has had time to finish, rather than the element
+// vanishing the instant the tap registers.
+const TRANSITION_MS = 200;
+// UBI-247: takes the drawer contents as `children` rather than
+// constructing a ProviderSidebar itself. That coupling was the one thing
+// in this component that was not generic, and it is exactly the kind of
+// thing that would have been carried into @ubx/docs-ui unnoticed had the
+// extraction been done first against a single call site. The provider
+// site passes <ProviderSidebar .../>, this site passes <DocSidebar .../>,
+// and the open/close/transition/route-change behaviour below is
+// identical for both.
+export function MobileSidebarToggle({ children }) {
+    const [mounted, setMounted] = useState(false);
+    const [visible, setVisible] = useState(false);
+    const closeTimer = useRef(null);
+    const pathname = usePathname();
+    const isFirstPathname = useRef(true);
+    function clearCloseTimer() {
+        if (closeTimer.current) {
+            clearTimeout(closeTimer.current);
+            closeTimer.current = null;
+        }
+    }
+    function open() {
+        clearCloseTimer();
+        setMounted(true);
+        // Mounts in the closed visual position first -- flipping to
+        // `visible` one frame later gives the browser an actual "from"
+        // state to transition out of, rather than painting already open.
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => setVisible(true));
+        });
+    }
+    function close() {
+        setVisible(false);
+        clearCloseTimer();
+        closeTimer.current = setTimeout(() => setMounted(false), TRANSITION_MS);
+    }
+    useEffect(() => clearCloseTimer, []);
+    // Explicit close-on-navigation rather than relying on this
+    // component happening to remount between routes -- Header sits
+    // directly in each page.tsx, not behind a shared layout boundary
+    // between different resource pages, so whether React actually tears
+    // this instance down on every navigation isn't guaranteed. Skips
+    // the very first render (mount already starts closed) so this only
+    // ever fires on a real route change.
+    useEffect(() => {
+        if (isFirstPathname.current) {
+            isFirstPathname.current = false;
+            return;
+        }
+        close();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [pathname]);
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: open, "aria-label": "Open service navigation", className: "flex h-9 w-9 shrink-0 items-center justify-center rounded text-foreground-muted hover:bg-surface hover:text-primary lg:hidden", children: _jsx("svg", { viewBox: "0 0 20 20", width: "20", height: "20", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M3 5.5h14M3 10h14M3 14.5h14", stroke: "currentColor", strokeWidth: "1.6", strokeLinecap: "round" }) }) }), mounted && (_jsxs("div", { role: "dialog", "aria-modal": "true", className: "fixed inset-0 z-50 lg:hidden", children: [_jsx("button", { type: "button", "aria-label": "Close service navigation", onClick: close, className: "absolute inset-0 bg-foreground/40 transition-opacity duration-200 motion-reduce:transition-none " +
+                            (visible ? "opacity-100" : "opacity-0") }), _jsxs("div", { className: "absolute inset-y-0 left-0 flex w-80 max-w-[85vw] flex-col overflow-y-auto bg-background p-4 shadow-lg " +
+                            "transition-transform duration-200 ease-out motion-reduce:transition-none " +
+                            (visible ? "translate-x-0" : "-translate-x-full"), children: [_jsxs("div", { className: "mb-3 flex items-center justify-between", children: [_jsx("span", { className: "text-sm font-semibold text-foreground", children: "Services" }), _jsx("button", { type: "button", onClick: close, "aria-label": "Close service navigation", className: "flex h-8 w-8 items-center justify-center rounded text-foreground-muted hover:bg-surface hover:text-primary", children: _jsx("svg", { viewBox: "0 0 16 16", width: "16", height: "16", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M4 4l8 8M12 4l-8 8", stroke: "currentColor", strokeWidth: "1.6", strokeLinecap: "round" }) }) })] }), children] })] }))] }));
+}

package/dist/ThemeToggle.d.ts

@@ -0,0 +1 @@
+export declare function ThemeToggle(): import("react").JSX.Element;

package/dist/ThemeToggle.js

@@ -0,0 +1,94 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+const STORAGE_KEY = "ubx-docs-theme";
+function applyTheme(choice) {
+    const root = document.documentElement;
+    if (choice === "system")
+        root.removeAttribute("data-theme");
+    else
+        root.setAttribute("data-theme", choice);
+}
+// localStorage is real external state, not React state -- read through
+// useSyncExternalStore rather than mirrored into a useState via a
+// useEffect (the latter renders "system" first, then immediately
+// re-renders to whatever was actually stored, a real extra render this
+// avoids). getServerSnapshot returns "system" unconditionally: the
+// server has no localStorage at all, and it's also the correct answer
+// for a first client render before the "ubx-theme-change" listener
+// below has run once -- the inline head script in app/layout.tsx has
+// already set the real data-theme attribute on the DOM by then, so the
+// page never actually shows the wrong theme, only this control's own
+// active-state highlight briefly lags by one render on a genuinely
+// fresh mount.
+function subscribe(callback) {
+    window.addEventListener("storage", callback);
+    window.addEventListener("ubx-theme-change", callback);
+    return () => {
+        window.removeEventListener("storage", callback);
+        window.removeEventListener("ubx-theme-change", callback);
+    };
+}
+function getSnapshot() {
+    // Same real risk app/layout.tsx's own inline THEME_INIT_SCRIPT
+    // already guards against for the identical read -- private
+    // browsing, a restrictive mobile browser or in-app-browser storage
+    // policy, or a managed device can make localStorage throw rather
+    // than return null. This runs inside useSyncExternalStore, during
+    // React's render pass, in a component mounted in Header on every
+    // page -- an uncaught throw here, with no error boundary anywhere
+    // in this app, can fail hydration for the whole page, not just this
+    // control.
+    try {
+        const stored = window.localStorage.getItem(STORAGE_KEY);
+        return stored === "light" || stored === "dark" ? stored : "system";
+    }
+    catch {
+        return "system";
+    }
+}
+function getServerSnapshot() {
+    return "system";
+}
+function SystemIcon() {
+    return (_jsxs("svg", { viewBox: "0 0 16 16", width: "14", height: "14", fill: "none", "aria-hidden": "true", children: [_jsx("rect", { x: "1.5", y: "2.5", width: "13", height: "8.5", rx: "1", stroke: "currentColor", strokeWidth: "1.3" }), _jsx("path", { d: "M5.5 14h5M8 11v3", stroke: "currentColor", strokeWidth: "1.3", strokeLinecap: "round" })] }));
+}
+function SunIcon() {
+    return (_jsxs("svg", { viewBox: "0 0 16 16", width: "14", height: "14", fill: "none", "aria-hidden": "true", children: [_jsx("circle", { cx: "8", cy: "8", r: "3", stroke: "currentColor", strokeWidth: "1.3" }), _jsx("path", { d: "M8 1v1.5M8 13.5V15M15 8h-1.5M2.5 8H1M12.7 3.3l-1 1M4.3 11.7l-1 1M12.7 12.7l-1-1M4.3 4.3l-1-1", stroke: "currentColor", strokeWidth: "1.3", strokeLinecap: "round" })] }));
+}
+function MoonIcon() {
+    return (_jsx("svg", { viewBox: "0 0 16 16", width: "14", height: "14", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M13.5 9.5A5.8 5.8 0 0 1 6.5 2.5 5.8 5.8 0 1 0 13.5 9.5Z", stroke: "currentColor", strokeWidth: "1.3", strokeLinejoin: "round" }) }));
+}
+const OPTIONS = [
+    { choice: "system", label: "System", Icon: SystemIcon },
+    { choice: "light", label: "Light", Icon: SunIcon },
+    { choice: "dark", label: "Dark", Icon: MoonIcon },
+];
+// A three-way segmented control, one icon per real state, all three
+// always visible -- replaces the earlier single cycling button (whose
+// current state was legible only from its text label, distinct icons
+// were the whole point of this pass).
+export function ThemeToggle() {
+    const choice = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    function choose(next) {
+        applyTheme(next);
+        try {
+            if (next === "system")
+                window.localStorage.removeItem(STORAGE_KEY);
+            else
+                window.localStorage.setItem(STORAGE_KEY, next);
+        }
+        catch {
+            // Storage blocked -- the choice still applies to this page via
+            // applyTheme/data-theme above, it just will not persist across
+            // a reload. Never let a blocked write crash the click handler.
+        }
+        window.dispatchEvent(new Event("ubx-theme-change"));
+    }
+    return (_jsx("div", { role: "radiogroup", "aria-label": "Theme", className: "inline-flex rounded-md border border-border p-0.5", children: OPTIONS.map(({ choice: c, label, Icon }) => {
+            const active = c === choice;
+            return (_jsx("button", { type: "button", role: "radio", "aria-checked": active, "aria-label": label, title: label, onClick: () => choose(c), className: active
+                    ? "flex h-6 w-6 items-center justify-center rounded bg-primary text-primary-foreground"
+                    : "flex h-6 w-6 items-center justify-center rounded text-foreground-muted hover:text-primary", children: _jsx(Icon, {}) }, c));
+        }) }));
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { CodeBlock } from "./CodeBlock";
+export { themeA, isSupportedLang, SUPPORTED_LANGS } from "./theme-a";
+export type { SupportedLang } from "./theme-a";
+export { Header } from "./Header";
+export type { NavLink, SectionTab } from "./Header";
+export { GlobalSearch } from "./GlobalSearch";
+export type { SearchEntry } from "./GlobalSearch";
+export { ThemeToggle } from "./ThemeToggle";
+export { Footer } from "./Footer";
+export { MobileSidebarToggle } from "./MobileSidebarToggle";

package/dist/index.js

@@ -0,0 +1,16 @@
+// @ubx/docs-ui: the components genuinely shared by ubx's two
+// documentation sites (ubx-docs-providers and ubx-docs-users).
+//
+// Extracted only after both consumers existed, deliberately. Three of
+// these interfaces had to change to be shareable at all, and one of
+// those was NOT predicted: MobileSidebarToggle imported ProviderSidebar
+// directly, which was found when the second site failed to build.
+// Extracting against a single call site would have carried that coupling
+// into this package unnoticed.
+export { CodeBlock } from "./CodeBlock";
+export { themeA, isSupportedLang, SUPPORTED_LANGS } from "./theme-a";
+export { Header } from "./Header";
+export { GlobalSearch } from "./GlobalSearch";
+export { ThemeToggle } from "./ThemeToggle";
+export { Footer } from "./Footer";
+export { MobileSidebarToggle } from "./MobileSidebarToggle";

package/dist/theme-a.d.ts

@@ -0,0 +1,6 @@
+import type { ThemeRegistration } from "shiki";
+export declare const themeA: ThemeRegistration;
+/** Languages theme A has been verified against, token by token. */
+export declare const SUPPORTED_LANGS: readonly ["go", "typescript", "python", "bash", "hcl", "json"];
+export type SupportedLang = (typeof SUPPORTED_LANGS)[number];
+export declare function isSupportedLang(lang: string): lang is SupportedLang;

package/dist/theme-a.js

@@ -0,0 +1,145 @@
+// Theme A as a real TextMate theme for Shiki.
+//
+// Every color is a CSS variable rather than a hex value, deliberately.
+// Both consuming sites already define --color-code-green/red/yellow,
+// --color-foreground, --color-foreground-muted and --color-code-bg in
+// their own globals.css, and already swap them under [data-theme] and
+// prefers-color-scheme. Emitting variables means light and dark keep
+// working through the existing mechanism with zero client JS, and this
+// package never has to know what the actual colors are.
+//
+// Theme A is deliberately coarse: green for keywords, types, numbers and
+// language constants; red for string literals; yellow for property
+// names; muted for comments; foreground for everything else. Mapping a
+// coarse palette onto TextMate's fine-grained scopes is many-to-one,
+// which is the easy direction.
+//
+// THE THREE OVERRIDES AT THE BOTTOM ARE THE POINT OF THIS FILE. They
+// were findable only by inspecting real Shiki token output per language,
+// not by reading scope documentation, and without them the naive mapping
+// is visibly WORSE than the hand-rolled tokenizer it replaces. They are
+// written out with their reasoning because the next person to touch this
+// will not otherwise know why a plausible-looking simplification breaks
+// the dominant language on the user docs site.
+export const themeA = {
+    name: "ubx-theme-a",
+    // Irrelevant in practice: every color below is a variable, and the
+    // consuming site's own [data-theme] contract decides light or dark.
+    type: "dark",
+    colors: {
+        "editor.foreground": "var(--color-foreground)",
+        "editor.background": "var(--color-code-bg)",
+    },
+    tokenColors: [
+        {
+            scope: ["comment", "punctuation.definition.comment"],
+            settings: { foreground: "var(--color-foreground-muted)" },
+        },
+        // GREEN: keywords, types, numeric and language constants.
+        {
+            scope: [
+                "keyword",
+                "storage",
+                "storage.type",
+                "storage.modifier",
+                "constant.language",
+                "constant.numeric",
+                "support.type",
+                "entity.name.type",
+                "entity.name.class",
+                "support.class",
+                // The shell command itself, a deliberate docs-specific choice
+                // rather than a general one. In these docs the subject of nearly
+                // every fence is a ubx command, and the hand-rolled tokenizer
+                // this replaces had "ubx" in a hardcoded keyword set for exactly
+                // that reason. Shiki scopes it precisely as entity.name.command,
+                // so the intent survives the swap without hardcoding a binary
+                // name into a shared library.
+                "entity.name.function.call",
+                "entity.name.command",
+            ],
+            settings: { foreground: "var(--color-code-green)" },
+        },
+        // RED: real string literals only. See override 1 below for what this
+        // must NOT catch.
+        {
+            scope: ["string", "string.quoted", "punctuation.definition.string"],
+            settings: { foreground: "var(--color-code-red)" },
+        },
+        // YELLOW: property and attribute names.
+        {
+            scope: [
+                "variable.other.member",
+                "meta.object-literal.key",
+                "support.type.property-name",
+                "meta.mapping.key",
+                // HCL attribute names. The hand-rolled tokenizer only recognised
+                // the `name:` form and so left HCL's `name =` plain. Shiki scopes
+                // it, so this is strictly closer to theme A's stated intent than
+                // what it replaces.
+                "variable.other.readwrite.hcl",
+                "variable.declaration.hcl",
+                // Go struct-literal field names. Verified against real token
+                // output: Go scopes `Owner:` inside a composite literal as
+                // variable.other.property, which is NOT covered by the generic
+                // object-literal scopes above. Without this, Go examples lose the
+                // yellow the hand-rolled tokenizer gave them, which showed up
+                // when the provider site's rendered code was diffed before and
+                // after the swap.
+                "variable.other.property",
+            ],
+            settings: { foreground: "var(--color-code-yellow)" },
+        },
+        // ---- Overrides. More specific scopes win, so these run last. ----
+        // OVERRIDE 1, the important one. Shell grammars scope every bare
+        // command argument as string.unquoted, so the naive mapping paints an
+        // ENTIRE command line red. Measured on the user docs site: 92 of 116
+        // code fences are bash, so this would have been the single most
+        // visible thing on the site, and it is also a lie about what red
+        // means in theme A (a string literal). Confirmed against real token
+        // output: `ubx scan --propose both` came out as
+        // ubx=plain scan=RED --propose=RED both=RED before this override, and
+        // ubx=GREEN with the rest plain after it.
+        {
+            scope: ["string.unquoted", "constant.other.option"],
+            settings: { foreground: "var(--color-foreground)" },
+        },
+        // OVERRIDE 2. An assignment operator is not a keyword in theme A's
+        // sense. Without this, HCL's `=` renders green and reads as though it
+        // were a language keyword, which is exactly the emphasis theme A
+        // reserves for real keywords and types.
+        {
+            scope: ["keyword.operator"],
+            settings: { foreground: "var(--color-foreground)" },
+        },
+        // OVERRIDE 4. TypeScript scopes the arrow of an arrow function as
+        // storage.type.function.arrow, which the generic `storage.type` rule
+        // above catches and paints green. The hand-rolled tokenizer left it
+        // plain, and theme A reserves green for keywords and type names, not
+        // punctuation. Also caught by the before/after diff rather than by
+        // reading scopes.
+        {
+            scope: ["storage.type.function.arrow"],
+            settings: { foreground: "var(--color-foreground)" },
+        },
+    ],
+};
+// OVERRIDE 3 is an omission rather than a rule, recorded here because it
+// was a real mistake made and corrected during the mapping work: adding
+// a blanket `punctuation` -> foreground override alongside the two above
+// looks tidy and is wrong. It strips the color from the quote marks
+// around JSON keys and string values, so `"provider"` renders with a
+// yellow key between two plain quotes. Leave punctuation inheriting from
+// its parent scope.
+/** Languages theme A has been verified against, token by token. */
+export const SUPPORTED_LANGS = [
+    "go",
+    "typescript",
+    "python",
+    "bash",
+    "hcl",
+    "json",
+];
+export function isSupportedLang(lang) {
+    return SUPPORTED_LANGS.includes(lang);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ubx/docs-ui",
+  "version": "0.1.0",
+  "description": "Shared UI for ubx documentation sites: theme A, Shiki-backed CodeBlock, header, search, theme toggle.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": ["dist"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "dependencies": {
+    "shiki": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "next": "16.3.4",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "^5"
+  },
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/Ubiquex/ubx-docs-ui.git" }
+}