@ubx/docs-ui 0.1.0 → 0.4.0

package/dist/Footer.d.ts

@@ -1 +1,9 @@
-export declare function Footer(): import("react").JSX.Element;
+export declare function Footer({ tagline, links, }: {
+    /** The one-line statement of what this particular site's content is. */
+    tagline: React.ReactNode;
+    /** Footer destinations, stated per site rather than shared. */
+    links: {
+        label: string;
+        href: string;
+    }[];
+}): import("react").JSX.Element;

package/dist/Footer.js

@@ -2,10 +2,25 @@ 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" })] }) }));
+//
+// IDENTITY IS A PROP, NOT A DEFAULT, for the same reason it is on
+// GlobalSearch, and this component is the proof that the reason is real.
+//
+// Extracted with the provider site's own identity hardcoded: a tagline
+// reading "Reference content is generated from each provider's own real
+// schema, not hand-written" and a License link pointing at
+// ubx-docs-providers. Both were correct for the site they came from and
+// silently wrong on the user docs site, where all 137 pages are
+// hand-written MDX and the repo is a different one. The tagline did not
+// merely fail to apply, it asserted the exact opposite of the truth on
+// every page of the site.
+//
+// GlobalSearch was caught during extraction because its regression was
+// visible (a pill turned into a rectangle). This one was not, because
+// wrong prose looks exactly like right prose until someone reads it. So
+// the rule cannot be "check carefully during extraction"; it has to be
+// that the type system refuses to let a site inherit an identity it did
+// not state. Hence both props are required and neither has a default.
+export function Footer({ tagline, links, }) {
+    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: tagline }), _jsx("nav", { className: "flex items-center gap-5", children: links.map((l) => (_jsx("a", { href: l.href, className: "hover:text-primary", children: l.label }, l.href))) })] }), _jsx("p", { className: "mt-4 text-center text-xs sm:text-left", children: "\u00A9 2026 Ubiquex" })] }) }));
 }

package/dist/Header.d.ts

@@ -8,11 +8,21 @@ export type SectionTab = {
     label: string;
     href: string;
 };
-export declare function Header({ nav, tabs, activeTab, mobileMenu, }: {
+export declare function Header({ nav, tabs, activeTab, mobileMenu, search, }: {
     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;
+    /**
+     * Search control, rendered to the left of the theme toggle.
+     *
+     * In the header rather than in page content because the alternative
+     * put it on exactly one page type per site: the provider site's home
+     * page, and the user docs site's section landing pages, which are the
+     * pages being removed. Every content page on both sites had no way to
+     * search at all.
+     */
+    search?: React.ReactNode;
 }): import("react").JSX.Element;

package/dist/Header.js

@@ -1,13 +1,13 @@
 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, }) {
+export function Header({ nav, tabs, activeTab, mobileMenu, search, }) {
     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) => {
+                        }) }), search ? _jsx("div", { className: "w-40 shrink-0 sm:w-56 lg:w-64", children: search }) : null, _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 + "/");

package/dist/MobileSidebarToggle.d.ts

@@ -1,3 +1,8 @@
-export declare function MobileSidebarToggle({ children }: {
+export declare function MobileSidebarToggle({ children, label, }: {
     children: React.ReactNode;
+    /**
+     * What this drawer contains, in the consuming site's own vocabulary.
+     * Used as the drawer heading and as the basis for both aria-labels.
+     */
+    label: string;
 }): import("react").JSX.Element;

package/dist/MobileSidebarToggle.js

@@ -18,14 +18,29 @@ import { useEffect, useRef, useState } from "react";
 // 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 }) {
+// constructing a ProviderSidebar itself. The provider site passes
+// <ProviderSidebar .../>, this site passes <DocSidebar .../>, and the
+// open/close/transition/route-change behaviour below is identical for
+// both.
+//
+// This comment used to claim that the `children` coupling "was the one
+// thing in this component that was not generic." That was wrong, and it
+// is left recorded here rather than quietly deleted because the way it
+// was wrong is the useful part. Three strings a few lines below still
+// said "Services" and "service navigation", which is AWS provider
+// vocabulary: the provider site's mobile drawer holds a provider's
+// service groups. The user docs site's drawer holds documentation
+// pages, so it announced the wrong thing to every mobile reader and to
+// every screen reader.
+//
+// It survived because the extraction was audited per component by
+// reading each one, and reading is exactly what does not catch a
+// plausible-sounding noun. It was found later by mechanically
+// extracting every user-visible string literal in the package and
+// asking of each one whether it could be true on both sites. `label` is
+// required for the same reason Footer's props are: a default here is a
+// silent claim about which site you are.
+export function MobileSidebarToggle({ children, label, }) {
     const [mounted, setMounted] = useState(false);
     const [visible, setVisible] = useState(false);
     const closeTimer = useRef(null);
@@ -68,8 +83,8 @@ export function MobileSidebarToggle({ children }) {
         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 " +
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: open, "aria-label": `Open ${label} 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 ${label} 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] })] }))] }));
+                            (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: label }), _jsx("button", { type: "button", onClick: close, "aria-label": `Close ${label} 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/PageShell.d.ts

@@ -0,0 +1,54 @@
+import type React from "react";
+import { type NavLink, type SectionTab } from "./Header";
+export type PageShellProps = {
+    nav: NavLink[];
+    /** Omit for a single-tier header. The provider site omits it. */
+    tabs?: SectionTab[];
+    /** href of the active tab, prefix-matched so nested pages stay lit. */
+    activeTab?: string;
+    /**
+     * Sidebar tree. When present the shell renders the two-column rail and
+     * wires the same node into the mobile drawer, so the desktop and mobile
+     * navigation can never disagree about what they contain.
+     */
+    sidebar?: React.ReactNode;
+    /** Drawer heading, in the consuming site's own vocabulary. */
+    sidebarLabel?: string;
+    /**
+     * Search placeholder. Presence of this prop is what mounts search.
+     *
+     * The placeholder is a prop because it is genuinely site-specific
+     * ("Search resources and data sources..." against "Search the docs").
+     * The input's styling is NOT a prop, which reverses the decision
+     * GlobalSearch made when it was extracted. That decision was right at
+     * the time: the two sites styled the box differently, and a default
+     * would have silently imposed one site's look on the other. Now that
+     * the shell owns the placement, one styling is the correct answer for
+     * both, and leaving it configurable would just re-open the drift.
+     */
+    searchPlaceholder?: string;
+    /** Footer identity. Required for the reason stated on Footer itself. */
+    footer: {
+        tagline: React.ReactNode;
+        links: {
+            label: string;
+            href: string;
+        }[];
+    };
+    children: React.ReactNode;
+};
+export declare function PageShell({ nav, tabs, activeTab, sidebar, sidebarLabel, searchPlaceholder, footer, children, }: PageShellProps): React.JSX.Element;
+/**
+ * Sets data-theme from localStorage before paint.
+ *
+ * Both sites carried this as a verbatim string constant in their own root
+ * layout, which is duplication the package could not see. It has to be an
+ * exported string rather than a component because it goes in <head> via
+ * dangerouslySetInnerHTML and must run ahead of hydration: a React
+ * component would run too late and the reader would see a flash of the
+ * OS default before their stored choice applied.
+ *
+ * Absent or invalid storage leaves no attribute at all, which is exactly
+ * "follow the OS".
+ */
+export declare const THEME_INIT_SCRIPT = "(function () {\n  try {\n    var stored = window.localStorage.getItem(\"ubx-docs-theme\");\n    if (stored === \"light\" || stored === \"dark\") {\n      document.documentElement.setAttribute(\"data-theme\", stored);\n    }\n  } catch (e) {}\n})();";

package/dist/PageShell.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Header } from "./Header";
+import { Footer } from "./Footer";
+import { GlobalSearch } from "./GlobalSearch";
+import { MobileSidebarToggle } from "./MobileSidebarToggle";
+/** Shared header search styling. See searchPlaceholder above. */
+const SEARCH_INPUT_CLASS = "w-full rounded-full bg-field px-4 py-1.5 text-sm text-foreground outline-none " +
+    "placeholder:text-foreground-muted focus:ring-2 focus:ring-primary/30";
+export function PageShell({ nav, tabs, activeTab, sidebar, sidebarLabel = "Navigation", searchPlaceholder, footer, children, }) {
+    const search = searchPlaceholder ? (_jsx(GlobalSearch, { placeholder: searchPlaceholder, inputClassName: SEARCH_INPUT_CLASS })) : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(Header, { nav: nav, tabs: tabs, activeTab: activeTab, search: search, mobileMenu: sidebar ? (_jsx(MobileSidebarToggle, { label: sidebarLabel, children: sidebar })) : undefined }), sidebar ? (_jsxs("div", { className: "mx-auto flex w-full max-w-7xl flex-1 gap-10 px-6 py-10", children: [_jsx("aside", { className: "hidden w-64 shrink-0 lg:block", children: sidebar }), _jsx("main", { className: "min-w-0 flex-1", children: children })] })) : (_jsx("main", { className: "mx-auto w-full max-w-7xl flex-1 px-6 py-12", children: children })), _jsx(Footer, { tagline: footer.tagline, links: footer.links })] }));
+}
+/**
+ * Sets data-theme from localStorage before paint.
+ *
+ * Both sites carried this as a verbatim string constant in their own root
+ * layout, which is duplication the package could not see. It has to be an
+ * exported string rather than a component because it goes in <head> via
+ * dangerouslySetInnerHTML and must run ahead of hydration: a React
+ * component would run too late and the reader would see a flash of the
+ * OS default before their stored choice applied.
+ *
+ * Absent or invalid storage leaves no attribute at all, which is exactly
+ * "follow the OS".
+ */
+export const THEME_INIT_SCRIPT = `(function () {
+  try {
+    var stored = window.localStorage.getItem("ubx-docs-theme");
+    if (stored === "light" || stored === "dark") {
+      document.documentElement.setAttribute("data-theme", stored);
+    }
+  } catch (e) {}
+})();`;

package/dist/index.d.ts

@@ -8,3 +8,5 @@ export type { SearchEntry } from "./GlobalSearch";
 export { ThemeToggle } from "./ThemeToggle";
 export { Footer } from "./Footer";
 export { MobileSidebarToggle } from "./MobileSidebarToggle";
+export { PageShell, THEME_INIT_SCRIPT } from "./PageShell";
+export type { PageShellProps } from "./PageShell";

package/dist/index.js

@@ -14,3 +14,4 @@ export { GlobalSearch } from "./GlobalSearch";
 export { ThemeToggle } from "./ThemeToggle";
 export { Footer } from "./Footer";
 export { MobileSidebarToggle } from "./MobileSidebarToggle";
+export { PageShell, THEME_INIT_SCRIPT } from "./PageShell";

package/dist/theme-a.d.ts

@@ -1,6 +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 declare const SUPPORTED_LANGS: readonly ["go", "typescript", "python", "bash", "hcl", "json", "yaml", "toml", "docker"];
 export type SupportedLang = (typeof SUPPORTED_LANGS)[number];
 export declare function isSupportedLang(lang: string): lang is SupportedLang;

package/dist/theme-a.js

@@ -87,6 +87,15 @@ export const themeA = {
                 // when the provider site's rendered code was diffed before and
                 // after the swap.
                 "variable.other.property",
+                // YAML and TOML mapping keys. UBI-247 slice 3: verified against
+                // real token output before being written, and the naive
+                // assumption was wrong in two ways. YAML keys carry BOTH
+                // entity.name.tag.yaml and string.unquoted.plain.out.yaml, so
+                // override 1 below (which exists for shell) was silently
+                // stripping every key in every CI example to plain. TOML keys
+                // are variable.other.key.toml, covered by nothing above.
+                "entity.name.tag",
+                "variable.other.key.toml",
             ],
             settings: { foreground: "var(--color-code-yellow)" },
         },
@@ -112,6 +121,24 @@ export const themeA = {
             scope: ["keyword.operator"],
             settings: { foreground: "var(--color-foreground)" },
         },
+        // OVERRIDE 5. The YAML grammar scopes a bare `on` as a boolean
+        // constant, not as a key, because YAML 1.1 really does treat `on` as
+        // true. In GitHub Actions `on:` is the trigger key and appears in
+        // essentially every CI example (25 of 29 YAML fences in these docs
+        // are Actions workflows), so leaving it green made one key in every
+        // file render as though it were a language keyword while its
+        // siblings were yellow.
+        //
+        // The grammar cannot distinguish the two, so this is a real
+        // trade-off rather than a clean fix: a genuine YAML boolean value
+        // now renders plain instead of green. Chosen deliberately, because
+        // in this corpus `on:` as a key is common and `true`/`false` as a
+        // scalar value is rare, and a wrongly-emphasised key is more
+        // misleading than an unemphasised boolean.
+        {
+            scope: ["constant.language.boolean.yaml"],
+            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
@@ -139,6 +166,12 @@ export const SUPPORTED_LANGS = [
     "bash",
     "hcl",
     "json",
+    // Added UBI-247 slice 3, each verified token by token: yaml (29
+    // fences, concentrated in the Integrations section where CI config is
+    // the entire subject), toml, and dockerfile.
+    "yaml",
+    "toml",
+    "docker",
 ];
 export function isSupportedLang(lang) {
     return SUPPORTED_LANGS.includes(lang);

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "@ubx/docs-ui",
-  "version": "0.1.0",
-  "description": "Shared UI for ubx documentation sites: theme A, Shiki-backed CodeBlock, header, search, theme toggle.",
+  "version": "0.4.0",
+  "description": "Shared UI for ubx documentation sites: the page shell, theme A, Shiki-backed CodeBlock, header, search, theme toggle.",
   "license": "Apache-2.0",
   "type": "module",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "check:package": "npm run build && node scripts/check-package.mjs"
   },
   "peerDependencies": {
     "next": ">=15",
@@ -32,6 +39,11 @@
     "react-dom": "19.2.8",
     "typescript": "^5"
   },
-  "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "git+https://github.com/Ubiquex/ubx-docs-ui.git" }
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ubiquex/ubx-docs-ui.git"
+  }
 }