npm - @openkeyai/ui - Versions diffs - 0.1.0 - Mend

@openkeyai/ui 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Scott Goodwin
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,134 @@
+# `@openkeyai/ui`
+The shared design system + mandatory `<HubHeader />` for every [OpenKey AI](https://openkeyai.com) tool.
+```bash
+pnpm add @openkeyai/ui
+# or
+npm i @openkeyai/ui
+```
+## Mounting `<HubHeader />`
+Every tool **must** mount the header in its root layout. The OpenKey AI CI scanner (lands in Phase 9) enforces this — a tool repo's build will fail if the import + mount aren't both present.
+### Next.js (App Router)
+```tsx
+// app/layout.tsx
+import "@openkeyai/ui/css";
+import { HubHeader } from "@openkeyai/ui";
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  // `user` comes from your tool's session helper (Phase 8's SDK ships one).
+  return (
+    <html lang="en">
+      <body style={{ paddingTop: "var(--okai-header-h)" }}>
+        <HubHeader
+          toolName="YouTube Thumbnails"
+          user={{
+            displayName: "Scott G.",
+            avatarUrl: null,
+            email: "scott@example.com",
+          }}
+        />
+        <main>{children}</main>
+      </body>
+    </html>
+  );
+}
+```
+The header is fixed-position at `z-index: var(--okai-z-header)` and `var(--okai-header-h)` (56px) tall. Leave that much top padding on your root.
+### Signed-out state
+Pass `user={null}` (or omit) and the chip is replaced by a **Sign in** CTA that links back to `https://openkeyai.com/login`. Don't try to hide the chip altogether — it's part of the consistent user experience contract.
+## Tokens + Tailwind
+Two consumption paths besides the CSS sheet:
+### Tailwind preset
+```ts
+// tailwind.config.ts
+import type { Config } from "tailwindcss";
+import { hubTailwindPreset } from "@openkeyai/ui/tailwind";
+export default {
+  presets: [hubTailwindPreset],
+  content: [
+    "./app/**/*.{ts,tsx}",
+    "./node_modules/@openkeyai/ui/dist/**/*.{js,cjs}",
+  ],
+} satisfies Config;
+```
+Now `bg-okai-bg`, `text-okai-foreground`, `rounded-okai-xl`, `pt-okai-header` etc. are available alongside Tailwind's defaults.
+### Direct token access
+```ts
+import { tokens } from "@openkeyai/ui/tokens";
+const indigo = tokens.color.accent; // "#7c6cf5"
+```
+Use this for places utility classes can't reach — SVG gradients, canvas paints, programmatic colour pickups.
+## What you CANNOT do with `<HubHeader />`
+- Hide the OpenKey AI brand mark
+- Hide the user chip / sign-in CTA
+- Replace the brand wordmark
+- Change the header height or position
+- Theme it to match your tool's brand only
+The header is the shared trust surface — users need to recognise it across every tool. The `rightSlot` prop is the legitimate extension point for tool-specific controls (settings, help, share, …); they render to the left of the user chip.
+If you have a legitimate need that the current API doesn't cover, open an issue rather than monkey-patching the package. Major version bumps require 60 days notice to tool authors.
+## API
+### `HubHeader`
+```ts
+type HubHeaderProps = {
+  toolName: string;
+  user?: {
+    displayName: string;
+    avatarUrl?: string | null;
+    email?: string;
+  } | null;
+  hubUrl?: string;     // default: "https://openkeyai.com"
+  rightSlot?: React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+};
+```
+## Versioning
+This package follows semver. Breaking changes to `<HubHeader />` are major-version bumps and require the 60-day notice flow described above. Token additions are minor; pure-CSS tweaks are patch.
+`UI_VERSION` is re-exported from the entry so tools can log which build they shipped against:
+```ts
+import { UI_VERSION } from "@openkeyai/ui";
+console.log("openkeyai/ui", UI_VERSION); // → "0.1.0"
+```
+## Development
+```bash
+pnpm install
+pnpm dev        # tsup --watch
+pnpm build      # tsup
+pnpm typecheck
+pnpm test
+```
+## License
+MIT — see [LICENSE](./LICENSE).

package/dist/index.cjs ADDED Viewed

@@ -0,0 +1,98 @@
+'use strict';
+require('react');
+var jsxRuntime = require('react/jsx-runtime');
+// src/components/hub-header.tsx
+var DEFAULT_HUB_URL = "https://openkeyai.com";
+function getInitials(name) {
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  const first = parts[0];
+  if (!first) return "?";
+  if (parts.length === 1) return first.slice(0, 2).toUpperCase();
+  const last = parts[parts.length - 1] ?? first;
+  return ((first[0] ?? "") + (last[0] ?? "")).toUpperCase() || "?";
+}
+function HubHeader({
+  toolName,
+  user,
+  hubUrl = DEFAULT_HUB_URL,
+  rightSlot,
+  className,
+  style
+}) {
+  const hubHref = hubUrl;
+  const accountHref = `${hubUrl.replace(/\/$/, "")}/settings/account`;
+  const signInHref = `${hubUrl.replace(/\/$/, "")}/login`;
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "header",
+    {
+      className: className ? `okai-header ${className}` : "okai-header",
+      style,
+      role: "banner",
+      "data-okai-component": "hub-header",
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsxs(
+          "a",
+          {
+            className: "okai-header__brand",
+            href: hubHref,
+            "aria-label": "Open OpenKey AI hub",
+            children: [
+              /* @__PURE__ */ jsxRuntime.jsx("span", { className: "okai-header__brand-mark", "aria-hidden": "true" }),
+              /* @__PURE__ */ jsxRuntime.jsx("span", { className: "okai-header__brand-text", children: "OpenKey AI" })
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "okai-header__divider", "aria-hidden": "true" }),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "okai-header__tool-name", title: toolName, children: toolName }),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "okai-header__spacer", "aria-hidden": "true" }),
+        rightSlot != null ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "okai-header__right", children: rightSlot }) : null,
+        user ? /* @__PURE__ */ jsxRuntime.jsxs(
+          "a",
+          {
+            className: "okai-header__user",
+            href: accountHref,
+            title: user.email ?? user.displayName,
+            "aria-label": `Open account for ${user.displayName}`,
+            children: [
+              user.avatarUrl ? /* @__PURE__ */ jsxRuntime.jsx(
+                "span",
+                {
+                  className: "okai-header__user-avatar",
+                  role: "img",
+                  "aria-label": user.displayName,
+                  style: { backgroundImage: `url(${user.avatarUrl})` }
+                }
+              ) : /* @__PURE__ */ jsxRuntime.jsx(
+                "span",
+                {
+                  className: "okai-header__user-fallback",
+                  "aria-hidden": "true",
+                  children: getInitials(user.displayName)
+                }
+              ),
+              /* @__PURE__ */ jsxRuntime.jsx("span", { className: "okai-header__user-name", children: user.displayName })
+            ]
+          }
+        ) : /* @__PURE__ */ jsxRuntime.jsx(
+          "a",
+          {
+            className: "okai-header__signin",
+            href: signInHref,
+            "aria-label": "Sign in to OpenKey AI",
+            children: "Sign in"
+          }
+        )
+      ]
+    }
+  );
+}
+// src/index.ts
+var UI_VERSION = "0.1.0";
+exports.HubHeader = HubHeader;
+exports.UI_VERSION = UI_VERSION;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"sources":["../src/components/hub-header.tsx","../src/index.ts"],"names":["jsxs","jsx"],"mappings":"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","file":"index.cjs","sourcesContent":["import * as React from \"react\";\n\n/**\n * Mandatory shared header for every OpenKey AI tool.\n *\n * What it gives the user (consistent across every tool):\n * - The hub brand mark — clicking it returns to the hub\n * - The tool's name — so users know which tool they're in\n * - The signed-in user (avatar + display name) — clicking opens the hub\n * account page\n * - A sign-in CTA when no user is provided\n *\n * What it deliberately does NOT do (per docs/TOOL_CONTRACT.md):\n * - Provide props to hide the brand mark, tool name, or user/sign-in chip\n * - Theme the colours away from the hub palette\n * - Allow the tool to swap the brand text\n *\n * The header is fixed to the top of the viewport at `z-index:\n * var(--okai-z-header)` and is `var(--okai-header-h)` tall. Tools should\n * leave that much top padding on their root layout. The styles live in\n * `@openkeyai/ui/css` — import it once in the tool's global CSS.\n *\n * SSR-safe: pure render, no client-only APIs in the default path.\n */\nexport type HubHeaderUser = {\n /** Visible label on the chip. */\n displayName: string;\n /** Optional avatar; falls back to initials when missing. */\n avatarUrl?: string | null;\n /** Used as a tooltip and accessible label. Not displayed. */\n email?: string;\n};\n\nexport type HubHeaderProps = {\n /** Display name of the tool. Goes after the divider. */\n toolName: string;\n /** Signed-in user, or null/undefined to show the Sign in CTA. */\n user?: HubHeaderUser | null;\n /** Override the hub root URL. Defaults to https://openkeyai.com. */\n hubUrl?: string;\n /** Optional right-side slot — tool-specific controls (settings, help, …).\n * Rendered BEFORE the user chip so the chip always ends the row. */\n rightSlot?: React.ReactNode;\n /** Forwarded to the outer <header>. Avoid resetting position/z-index. */\n className?: string;\n /** Optional inline style override for the outer <header>. */\n style?: React.CSSProperties;\n};\n\nconst DEFAULT_HUB_URL = \"https://openkeyai.com\";\n\nfunction getInitials(name: string): string {\n const parts = name.trim().split(/\\s+/).filter(Boolean);\n const first = parts[0];\n if (!first) return \"?\";\n if (parts.length === 1) return first.slice(0, 2).toUpperCase();\n const last = parts[parts.length - 1] ?? first;\n return ((first[0] ?? \"\") + (last[0] ?? \"\")).toUpperCase() || \"?\";\n}\n\n/**\n * `<HubHeader />` — the mandatory header. See module doc above.\n */\nexport function HubHeader({\n toolName,\n user,\n hubUrl = DEFAULT_HUB_URL,\n rightSlot,\n className,\n style,\n}: HubHeaderProps) {\n const hubHref = hubUrl;\n const accountHref = `${hubUrl.replace(/\\/$/, \"\")}/settings/account`;\n const signInHref = `${hubUrl.replace(/\\/$/, \"\")}/login`;\n\n return (\n <header\n className={\n className ? `okai-header ${className}` : \"okai-header\"\n }\n style={style}\n role=\"banner\"\n data-okai-component=\"hub-header\"\n >\n <a\n className=\"okai-header__brand\"\n href={hubHref}\n aria-label=\"Open OpenKey AI hub\"\n >\n <span className=\"okai-header__brand-mark\" aria-hidden=\"true\" />\n <span className=\"okai-header__brand-text\">OpenKey AI</span>\n </a>\n\n <span className=\"okai-header__divider\" aria-hidden=\"true\" />\n\n <span className=\"okai-header__tool-name\" title={toolName}>\n {toolName}\n </span>\n\n <span className=\"okai-header__spacer\" aria-hidden=\"true\" />\n\n {rightSlot != null ? (\n <div className=\"okai-header__right\">{rightSlot}</div>\n ) : null}\n\n {user ? (\n <a\n className=\"okai-header__user\"\n href={accountHref}\n title={user.email ?? user.displayName}\n aria-label={`Open account for ${user.displayName}`}\n >\n {user.avatarUrl ? (\n <span\n className=\"okai-header__user-avatar\"\n role=\"img\"\n aria-label={user.displayName}\n style={{ backgroundImage: `url(${user.avatarUrl})` }}\n />\n ) : (\n <span\n className=\"okai-header__user-fallback\"\n aria-hidden=\"true\"\n >\n {getInitials(user.displayName)}\n </span>\n )}\n <span className=\"okai-header__user-name\">{user.displayName}</span>\n </a>\n ) : (\n <a\n className=\"okai-header__signin\"\n href={signInHref}\n aria-label=\"Sign in to OpenKey AI\"\n >\n Sign in\n </a>\n )}\n </header>\n );\n}\n","/**\n * `@openkeyai/ui` — public entry.\n *\n * Every OpenKey AI tool installs this package and mounts <HubHeader /> in\n * its root layout. CI in `Scott-Builds-AI/.github` enforces the mounting\n * via an AST scanner (lands in Phase 9).\n *\n * Entry paths:\n * - \"@openkeyai/ui\" → React components + their types (this file)\n * - \"@openkeyai/ui/tokens\" → Design tokens as a JS object\n * - \"@openkeyai/ui/tailwind\" → Tailwind preset\n * - \"@openkeyai/ui/css\" → The global stylesheet (CSS custom\n * properties + scoped .okai-* classes).\n * MUST be imported once by the consumer.\n *\n * See README.md for the canonical mounting pattern.\n */\n\nexport { HubHeader } from \"./components/hub-header\";\nexport type {\n HubHeaderProps,\n HubHeaderUser,\n} from \"./components/hub-header\";\n\n/** Bumped on each release. Useful for tools to log which UI version they shipped against. */\nexport const UI_VERSION = \"0.1.0\";\n"]}

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,74 @@
+import * as React from 'react';
+/**
+ * Mandatory shared header for every OpenKey AI tool.
+ *
+ * What it gives the user (consistent across every tool):
+ *   - The hub brand mark — clicking it returns to the hub
+ *   - The tool's name — so users know which tool they're in
+ *   - The signed-in user (avatar + display name) — clicking opens the hub
+ *     account page
+ *   - A sign-in CTA when no user is provided
+ *
+ * What it deliberately does NOT do (per docs/TOOL_CONTRACT.md):
+ *   - Provide props to hide the brand mark, tool name, or user/sign-in chip
+ *   - Theme the colours away from the hub palette
+ *   - Allow the tool to swap the brand text
+ *
+ * The header is fixed to the top of the viewport at `z-index:
+ * var(--okai-z-header)` and is `var(--okai-header-h)` tall. Tools should
+ * leave that much top padding on their root layout. The styles live in
+ * `@openkeyai/ui/css` — import it once in the tool's global CSS.
+ *
+ * SSR-safe: pure render, no client-only APIs in the default path.
+ */
+type HubHeaderUser = {
+    /** Visible label on the chip. */
+    displayName: string;
+    /** Optional avatar; falls back to initials when missing. */
+    avatarUrl?: string | null;
+    /** Used as a tooltip and accessible label. Not displayed. */
+    email?: string;
+};
+type HubHeaderProps = {
+    /** Display name of the tool. Goes after the divider. */
+    toolName: string;
+    /** Signed-in user, or null/undefined to show the Sign in CTA. */
+    user?: HubHeaderUser | null;
+    /** Override the hub root URL. Defaults to https://openkeyai.com. */
+    hubUrl?: string;
+    /** Optional right-side slot — tool-specific controls (settings, help, …).
+     *  Rendered BEFORE the user chip so the chip always ends the row. */
+    rightSlot?: React.ReactNode;
+    /** Forwarded to the outer <header>. Avoid resetting position/z-index. */
+    className?: string;
+    /** Optional inline style override for the outer <header>. */
+    style?: React.CSSProperties;
+};
+/**
+ * `<HubHeader />` — the mandatory header. See module doc above.
+ */
+declare function HubHeader({ toolName, user, hubUrl, rightSlot, className, style, }: HubHeaderProps): React.JSX.Element;
+/**
+ * `@openkeyai/ui` — public entry.
+ *
+ * Every OpenKey AI tool installs this package and mounts <HubHeader /> in
+ * its root layout. CI in `Scott-Builds-AI/.github` enforces the mounting
+ * via an AST scanner (lands in Phase 9).
+ *
+ * Entry paths:
+ *   - "@openkeyai/ui"              → React components + their types (this file)
+ *   - "@openkeyai/ui/tokens"       → Design tokens as a JS object
+ *   - "@openkeyai/ui/tailwind"     → Tailwind preset
+ *   - "@openkeyai/ui/css"          → The global stylesheet (CSS custom
+ *                                    properties + scoped .okai-* classes).
+ *                                    MUST be imported once by the consumer.
+ *
+ * See README.md for the canonical mounting pattern.
+ */
+/** Bumped on each release. Useful for tools to log which UI version they shipped against. */
+declare const UI_VERSION = "0.1.0";
+export { HubHeader, type HubHeaderProps, type HubHeaderUser, UI_VERSION };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,74 @@
+import * as React from 'react';
+/**
+ * Mandatory shared header for every OpenKey AI tool.
+ *
+ * What it gives the user (consistent across every tool):
+ *   - The hub brand mark — clicking it returns to the hub
+ *   - The tool's name — so users know which tool they're in
+ *   - The signed-in user (avatar + display name) — clicking opens the hub
+ *     account page
+ *   - A sign-in CTA when no user is provided
+ *
+ * What it deliberately does NOT do (per docs/TOOL_CONTRACT.md):
+ *   - Provide props to hide the brand mark, tool name, or user/sign-in chip
+ *   - Theme the colours away from the hub palette
+ *   - Allow the tool to swap the brand text
+ *
+ * The header is fixed to the top of the viewport at `z-index:
+ * var(--okai-z-header)` and is `var(--okai-header-h)` tall. Tools should
+ * leave that much top padding on their root layout. The styles live in
+ * `@openkeyai/ui/css` — import it once in the tool's global CSS.
+ *
+ * SSR-safe: pure render, no client-only APIs in the default path.
+ */
+type HubHeaderUser = {
+    /** Visible label on the chip. */
+    displayName: string;
+    /** Optional avatar; falls back to initials when missing. */
+    avatarUrl?: string | null;
+    /** Used as a tooltip and accessible label. Not displayed. */
+    email?: string;
+};
+type HubHeaderProps = {
+    /** Display name of the tool. Goes after the divider. */
+    toolName: string;
+    /** Signed-in user, or null/undefined to show the Sign in CTA. */
+    user?: HubHeaderUser | null;
+    /** Override the hub root URL. Defaults to https://openkeyai.com. */
+    hubUrl?: string;
+    /** Optional right-side slot — tool-specific controls (settings, help, …).
+     *  Rendered BEFORE the user chip so the chip always ends the row. */
+    rightSlot?: React.ReactNode;
+    /** Forwarded to the outer <header>. Avoid resetting position/z-index. */
+    className?: string;
+    /** Optional inline style override for the outer <header>. */
+    style?: React.CSSProperties;
+};
+/**
+ * `<HubHeader />` — the mandatory header. See module doc above.
+ */
+declare function HubHeader({ toolName, user, hubUrl, rightSlot, className, style, }: HubHeaderProps): React.JSX.Element;
+/**
+ * `@openkeyai/ui` — public entry.
+ *
+ * Every OpenKey AI tool installs this package and mounts <HubHeader /> in
+ * its root layout. CI in `Scott-Builds-AI/.github` enforces the mounting
+ * via an AST scanner (lands in Phase 9).
+ *
+ * Entry paths:
+ *   - "@openkeyai/ui"              → React components + their types (this file)
+ *   - "@openkeyai/ui/tokens"       → Design tokens as a JS object
+ *   - "@openkeyai/ui/tailwind"     → Tailwind preset
+ *   - "@openkeyai/ui/css"          → The global stylesheet (CSS custom
+ *                                    properties + scoped .okai-* classes).
+ *                                    MUST be imported once by the consumer.
+ *
+ * See README.md for the canonical mounting pattern.
+ */
+/** Bumped on each release. Useful for tools to log which UI version they shipped against. */
+declare const UI_VERSION = "0.1.0";
+export { HubHeader, type HubHeaderProps, type HubHeaderUser, UI_VERSION };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,95 @@
+import 'react';
+import { jsxs, jsx } from 'react/jsx-runtime';
+// src/components/hub-header.tsx
+var DEFAULT_HUB_URL = "https://openkeyai.com";
+function getInitials(name) {
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  const first = parts[0];
+  if (!first) return "?";
+  if (parts.length === 1) return first.slice(0, 2).toUpperCase();
+  const last = parts[parts.length - 1] ?? first;
+  return ((first[0] ?? "") + (last[0] ?? "")).toUpperCase() || "?";
+}
+function HubHeader({
+  toolName,
+  user,
+  hubUrl = DEFAULT_HUB_URL,
+  rightSlot,
+  className,
+  style
+}) {
+  const hubHref = hubUrl;
+  const accountHref = `${hubUrl.replace(/\/$/, "")}/settings/account`;
+  const signInHref = `${hubUrl.replace(/\/$/, "")}/login`;
+  return /* @__PURE__ */ jsxs(
+    "header",
+    {
+      className: className ? `okai-header ${className}` : "okai-header",
+      style,
+      role: "banner",
+      "data-okai-component": "hub-header",
+      children: [
+        /* @__PURE__ */ jsxs(
+          "a",
+          {
+            className: "okai-header__brand",
+            href: hubHref,
+            "aria-label": "Open OpenKey AI hub",
+            children: [
+              /* @__PURE__ */ jsx("span", { className: "okai-header__brand-mark", "aria-hidden": "true" }),
+              /* @__PURE__ */ jsx("span", { className: "okai-header__brand-text", children: "OpenKey AI" })
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsx("span", { className: "okai-header__divider", "aria-hidden": "true" }),
+        /* @__PURE__ */ jsx("span", { className: "okai-header__tool-name", title: toolName, children: toolName }),
+        /* @__PURE__ */ jsx("span", { className: "okai-header__spacer", "aria-hidden": "true" }),
+        rightSlot != null ? /* @__PURE__ */ jsx("div", { className: "okai-header__right", children: rightSlot }) : null,
+        user ? /* @__PURE__ */ jsxs(
+          "a",
+          {
+            className: "okai-header__user",
+            href: accountHref,
+            title: user.email ?? user.displayName,
+            "aria-label": `Open account for ${user.displayName}`,
+            children: [
+              user.avatarUrl ? /* @__PURE__ */ jsx(
+                "span",
+                {
+                  className: "okai-header__user-avatar",
+                  role: "img",
+                  "aria-label": user.displayName,
+                  style: { backgroundImage: `url(${user.avatarUrl})` }
+                }
+              ) : /* @__PURE__ */ jsx(
+                "span",
+                {
+                  className: "okai-header__user-fallback",
+                  "aria-hidden": "true",
+                  children: getInitials(user.displayName)
+                }
+              ),
+              /* @__PURE__ */ jsx("span", { className: "okai-header__user-name", children: user.displayName })
+            ]
+          }
+        ) : /* @__PURE__ */ jsx(
+          "a",
+          {
+            className: "okai-header__signin",
+            href: signInHref,
+            "aria-label": "Sign in to OpenKey AI",
+            children: "Sign in"
+          }
+        )
+      ]
+    }
+  );
+}
+// src/index.ts
+var UI_VERSION = "0.1.0";
+export { HubHeader, UI_VERSION };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"sources":["../src/components/hub-header.tsx","../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import * as React from \"react\";\n\n/**\n * Mandatory shared header for every OpenKey AI tool.\n *\n * What it gives the user (consistent across every tool):\n * - The hub brand mark — clicking it returns to the hub\n * - The tool's name — so users know which tool they're in\n * - The signed-in user (avatar + display name) — clicking opens the hub\n * account page\n * - A sign-in CTA when no user is provided\n *\n * What it deliberately does NOT do (per docs/TOOL_CONTRACT.md):\n * - Provide props to hide the brand mark, tool name, or user/sign-in chip\n * - Theme the colours away from the hub palette\n * - Allow the tool to swap the brand text\n *\n * The header is fixed to the top of the viewport at `z-index:\n * var(--okai-z-header)` and is `var(--okai-header-h)` tall. Tools should\n * leave that much top padding on their root layout. The styles live in\n * `@openkeyai/ui/css` — import it once in the tool's global CSS.\n *\n * SSR-safe: pure render, no client-only APIs in the default path.\n */\nexport type HubHeaderUser = {\n /** Visible label on the chip. */\n displayName: string;\n /** Optional avatar; falls back to initials when missing. */\n avatarUrl?: string | null;\n /** Used as a tooltip and accessible label. Not displayed. */\n email?: string;\n};\n\nexport type HubHeaderProps = {\n /** Display name of the tool. Goes after the divider. */\n toolName: string;\n /** Signed-in user, or null/undefined to show the Sign in CTA. */\n user?: HubHeaderUser | null;\n /** Override the hub root URL. Defaults to https://openkeyai.com. */\n hubUrl?: string;\n /** Optional right-side slot — tool-specific controls (settings, help, …).\n * Rendered BEFORE the user chip so the chip always ends the row. */\n rightSlot?: React.ReactNode;\n /** Forwarded to the outer <header>. Avoid resetting position/z-index. */\n className?: string;\n /** Optional inline style override for the outer <header>. */\n style?: React.CSSProperties;\n};\n\nconst DEFAULT_HUB_URL = \"https://openkeyai.com\";\n\nfunction getInitials(name: string): string {\n const parts = name.trim().split(/\\s+/).filter(Boolean);\n const first = parts[0];\n if (!first) return \"?\";\n if (parts.length === 1) return first.slice(0, 2).toUpperCase();\n const last = parts[parts.length - 1] ?? first;\n return ((first[0] ?? \"\") + (last[0] ?? \"\")).toUpperCase() || \"?\";\n}\n\n/**\n * `<HubHeader />` — the mandatory header. See module doc above.\n */\nexport function HubHeader({\n toolName,\n user,\n hubUrl = DEFAULT_HUB_URL,\n rightSlot,\n className,\n style,\n}: HubHeaderProps) {\n const hubHref = hubUrl;\n const accountHref = `${hubUrl.replace(/\\/$/, \"\")}/settings/account`;\n const signInHref = `${hubUrl.replace(/\\/$/, \"\")}/login`;\n\n return (\n <header\n className={\n className ? `okai-header ${className}` : \"okai-header\"\n }\n style={style}\n role=\"banner\"\n data-okai-component=\"hub-header\"\n >\n <a\n className=\"okai-header__brand\"\n href={hubHref}\n aria-label=\"Open OpenKey AI hub\"\n >\n <span className=\"okai-header__brand-mark\" aria-hidden=\"true\" />\n <span className=\"okai-header__brand-text\">OpenKey AI</span>\n </a>\n\n <span className=\"okai-header__divider\" aria-hidden=\"true\" />\n\n <span className=\"okai-header__tool-name\" title={toolName}>\n {toolName}\n </span>\n\n <span className=\"okai-header__spacer\" aria-hidden=\"true\" />\n\n {rightSlot != null ? (\n <div className=\"okai-header__right\">{rightSlot}</div>\n ) : null}\n\n {user ? (\n <a\n className=\"okai-header__user\"\n href={accountHref}\n title={user.email ?? user.displayName}\n aria-label={`Open account for ${user.displayName}`}\n >\n {user.avatarUrl ? (\n <span\n className=\"okai-header__user-avatar\"\n role=\"img\"\n aria-label={user.displayName}\n style={{ backgroundImage: `url(${user.avatarUrl})` }}\n />\n ) : (\n <span\n className=\"okai-header__user-fallback\"\n aria-hidden=\"true\"\n >\n {getInitials(user.displayName)}\n </span>\n )}\n <span className=\"okai-header__user-name\">{user.displayName}</span>\n </a>\n ) : (\n <a\n className=\"okai-header__signin\"\n href={signInHref}\n aria-label=\"Sign in to OpenKey AI\"\n >\n Sign in\n </a>\n )}\n </header>\n );\n}\n","/**\n * `@openkeyai/ui` — public entry.\n *\n * Every OpenKey AI tool installs this package and mounts <HubHeader /> in\n * its root layout. CI in `Scott-Builds-AI/.github` enforces the mounting\n * via an AST scanner (lands in Phase 9).\n *\n * Entry paths:\n * - \"@openkeyai/ui\" → React components + their types (this file)\n * - \"@openkeyai/ui/tokens\" → Design tokens as a JS object\n * - \"@openkeyai/ui/tailwind\" → Tailwind preset\n * - \"@openkeyai/ui/css\" → The global stylesheet (CSS custom\n * properties + scoped .okai-* classes).\n * MUST be imported once by the consumer.\n *\n * See README.md for the canonical mounting pattern.\n */\n\nexport { HubHeader } from \"./components/hub-header\";\nexport type {\n HubHeaderProps,\n HubHeaderUser,\n} from \"./components/hub-header\";\n\n/** Bumped on each release. Useful for tools to log which UI version they shipped against. */\nexport const UI_VERSION = \"0.1.0\";\n"]}