@xzibit/ui 0.1.0

package/dist/index.cjs

@@ -0,0 +1,555 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AppsDropdown: () => AppsDropdown,
+  BackToLauncher: () => BackToLauncher,
+  TopBar: () => TopBar,
+  XzibitMark: () => XzibitMark,
+  useApps: () => useApps
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/BackToLauncher.tsx
+var import_react = require("react");
+
+// src/XzibitMark.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function XzibitMark({ size = 28, className, ariaLabel }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "svg",
+    {
+      width: size,
+      height: size,
+      viewBox: "0 0 100 100",
+      xmlns: "http://www.w3.org/2000/svg",
+      role: ariaLabel ? "img" : "presentation",
+      "aria-label": ariaLabel,
+      "aria-hidden": ariaLabel ? void 0 : true,
+      className,
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("rect", { x: 0, y: 0, width: 100, height: 100, fill: "#000000" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+          "g",
+          {
+            stroke: "#FFFFFF",
+            strokeWidth: 9,
+            fill: "none",
+            strokeLinecap: "square",
+            strokeLinejoin: "miter",
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M 22 22 L 30 22 L 30 32 L 50 50" }),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M 78 22 L 70 22 L 70 32 L 50 50" }),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M 22 78 L 30 78 L 30 68 L 50 50" }),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M 78 78 L 70 78 L 70 68 L 50 50" })
+            ]
+          }
+        )
+      ]
+    }
+  );
+}
+
+// src/BackToLauncher.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var DEFAULT_LAUNCHER_URL = "https://xzibit-apps.vercel.app";
+function BackToLauncher({
+  launcherUrl = DEFAULT_LAUNCHER_URL
+}) {
+  const [hover, setHover] = (0, import_react.useState)(false);
+  const chevronColor = hover ? "#ffffff" : "rgba(255, 255, 255, 0.7)";
+  const textColor = hover ? "#ffffff" : "rgba(255, 255, 255, 0.85)";
+  const bgColor = hover ? "rgba(255, 255, 255, 0.07)" : "transparent";
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+    "a",
+    {
+      href: launcherUrl,
+      "aria-label": "Back to Xzibit Apps launcher",
+      onMouseEnter: () => setHover(true),
+      onMouseLeave: () => setHover(false),
+      onFocus: () => setHover(true),
+      onBlur: () => setHover(false),
+      style: {
+        display: "flex",
+        alignItems: "center",
+        gap: "8px",
+        padding: "0 1rem",
+        height: "44px",
+        fontSize: "15px",
+        fontWeight: 500,
+        color: textColor,
+        background: bgColor,
+        textDecoration: "none",
+        transition: "background 120ms, color 120ms"
+      },
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+          "svg",
+          {
+            width: 12,
+            height: 12,
+            viewBox: "0 0 12 12",
+            fill: "none",
+            "aria-hidden": "true",
+            children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+              "path",
+              {
+                d: "M 8 2 L 3 6 L 8 10",
+                stroke: chevronColor,
+                strokeWidth: 1.8,
+                strokeLinecap: "round",
+                strokeLinejoin: "round"
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(XzibitMark, { size: 28 }),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: "Xzibit Apps" })
+      ]
+    }
+  );
+}
+
+// src/AppsDropdown.tsx
+var import_react3 = require("react");
+
+// src/useApps.ts
+var import_react2 = require("react");
+function useApps(options = {}) {
+  const { endpoint = "/api/me/apps", lazy = false } = options;
+  const [apps, setApps] = (0, import_react2.useState)([]);
+  const [loading, setLoading] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const fetchApps = (0, import_react2.useCallback)(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetch(endpoint, {
+        credentials: "include",
+        headers: { Accept: "application/json" }
+      });
+      if (!res.ok) {
+        throw new Error(`Failed to load apps (HTTP ${res.status})`);
+      }
+      const data = await res.json();
+      if (data.error) {
+        throw new Error(data.error);
+      }
+      setApps(data.apps ?? []);
+    } catch (err) {
+      console.error("[@xzibit/ui useApps] fetch failed:", err);
+      setError(err instanceof Error ? err.message : "Unknown error");
+      setApps([]);
+    } finally {
+      setLoading(false);
+    }
+  }, [endpoint]);
+  (0, import_react2.useEffect)(() => {
+    if (!lazy) {
+      fetchApps();
+    }
+  }, [fetchApps, lazy]);
+  return { apps, loading, error, refetch: fetchApps };
+}
+
+// src/AppsDropdown.tsx
+var import_jsx_runtime3 = require("react/jsx-runtime");
+function AppsDropdown({ endpoint } = {}) {
+  const [open, setOpen] = (0, import_react3.useState)(false);
+  const { apps, loading, error } = useApps({ endpoint });
+  const buttonRef = (0, import_react3.useRef)(null);
+  const panelRef = (0, import_react3.useRef)(null);
+  (0, import_react3.useEffect)(() => {
+    if (!open) return;
+    const handler = (e) => {
+      if (e.key === "Escape") {
+        setOpen(false);
+        buttonRef.current?.focus();
+      }
+    };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [open]);
+  (0, import_react3.useEffect)(() => {
+    if (!open) return;
+    const handler = (e) => {
+      const target = e.target;
+      if (panelRef.current?.contains(target)) return;
+      if (buttonRef.current?.contains(target)) return;
+      setOpen(false);
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [open]);
+  const grouped = groupAndSort(apps);
+  const hasApps = grouped.length > 0;
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { style: { position: "relative" }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+      "button",
+      {
+        ref: buttonRef,
+        type: "button",
+        onClick: () => setOpen((o) => !o),
+        "aria-haspopup": "menu",
+        "aria-expanded": open,
+        style: {
+          display: "flex",
+          alignItems: "center",
+          gap: "6px",
+          padding: "0 1rem",
+          height: "44px",
+          background: open ? "rgba(255, 255, 255, 0.05)" : "transparent",
+          border: "none",
+          color: open ? "#ffffff" : "rgba(255, 255, 255, 0.7)",
+          fontSize: "13px",
+          fontWeight: 400,
+          cursor: "pointer",
+          fontFamily: "inherit",
+          transition: "background 120ms, color 120ms"
+        },
+        children: [
+          "Apps",
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("svg", { width: 10, height: 10, viewBox: "0 0 10 10", fill: "none", "aria-hidden": "true", children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+            "path",
+            {
+              d: open ? "M 1 7 L 5 3 L 9 7" : "M 1 3 L 5 7 L 9 3",
+              stroke: "currentColor",
+              strokeWidth: 1.5,
+              strokeLinecap: "round",
+              strokeLinejoin: "round"
+            }
+          ) })
+        ]
+      }
+    ),
+    open && /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+      "div",
+      {
+        ref: panelRef,
+        role: "menu",
+        style: {
+          position: "absolute",
+          top: "44px",
+          left: 0,
+          minWidth: "280px",
+          maxWidth: "360px",
+          maxHeight: "60vh",
+          overflowY: "auto",
+          background: "var(--xz-white, #ffffff)",
+          border: "1px solid var(--border, #E2E4E5)",
+          borderRadius: "8px",
+          boxShadow: "var(--shadow-card-hover, 0 4px 12px rgba(29,37,45,0.10), 0 12px 32px rgba(29,37,45,0.10))",
+          padding: "0.5rem",
+          zIndex: 110
+        },
+        children: [
+          loading && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DropdownSkeleton, {}),
+          !loading && error && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DropdownError, { message: error }),
+          !loading && !error && !hasApps && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DropdownEmpty, {}),
+          !loading && !error && hasApps && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_jsx_runtime3.Fragment, { children: grouped.map((group, i) => /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_react3.Fragment, { children: [
+            i > 0 && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+              "hr",
+              {
+                "aria-hidden": "true",
+                style: {
+                  border: "none",
+                  borderTop: "1px solid var(--border, #E2E4E5)",
+                  margin: "8px 0"
+                }
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DropdownSection, { section: group.section, apps: group.apps })
+          ] }, group.section ?? "__no_section__")) })
+        ]
+      }
+    )
+  ] });
+}
+function groupAndSort(apps) {
+  const sectionMap = /* @__PURE__ */ new Map();
+  const sectionOrder = /* @__PURE__ */ new Map();
+  apps.forEach((app, i) => {
+    const key = app.section ?? null;
+    if (!sectionMap.has(key)) {
+      sectionMap.set(key, []);
+      sectionOrder.set(key, app.section_order ?? i);
+    }
+    sectionMap.get(key).push(app);
+  });
+  const groups = Array.from(sectionMap.entries()).map(
+    ([section, sectionApps]) => ({
+      section,
+      apps: [...sectionApps].sort(
+        (a, b) => a.name.localeCompare(b.name, void 0, { sensitivity: "base" })
+      )
+    })
+  );
+  groups.sort(
+    (a, b) => (sectionOrder.get(a.section) ?? Number.MAX_SAFE_INTEGER) - (sectionOrder.get(b.section) ?? Number.MAX_SAFE_INTEGER)
+  );
+  return groups;
+}
+function DropdownSection({
+  section,
+  apps
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { children: [
+    section && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+      "div",
+      {
+        style: {
+          fontSize: "11px",
+          fontWeight: 500,
+          color: "var(--muted-foreground, #888A8B)",
+          letterSpacing: "0.06em",
+          textTransform: "uppercase",
+          padding: "0 0.75rem",
+          marginBottom: "4px"
+        },
+        children: section
+      }
+    ),
+    apps.map((app) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DropdownItem, { app }, app.name + app.url))
+  ] });
+}
+function DropdownItem({ app }) {
+  const [hover, setHover] = (0, import_react3.useState)(false);
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+    "a",
+    {
+      href: app.url,
+      role: "menuitem",
+      onMouseEnter: () => setHover(true),
+      onMouseLeave: () => setHover(false),
+      style: {
+        display: "block",
+        padding: "0.5rem 0.75rem",
+        borderRadius: "4px",
+        fontSize: "14px",
+        fontWeight: 400,
+        color: "var(--foreground, #1D252D)",
+        textDecoration: "none",
+        background: hover ? "var(--xz-off-white, #F4F4F2)" : "transparent",
+        transition: "background 80ms"
+      },
+      children: app.name
+    }
+  );
+}
+function DropdownSkeleton() {
+  const widths = ["78%", "64%", "82%", "70%"];
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { style: { padding: "0.5rem 0.75rem" }, children: [
+    widths.map((w, i) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+      "div",
+      {
+        "aria-hidden": "true",
+        style: {
+          height: "14px",
+          background: "rgba(216, 218, 219, 0.4)",
+          borderRadius: "4px",
+          marginBottom: "8px",
+          width: w,
+          animation: "xzibit-pulse 1.4s ease-in-out infinite"
+        }
+      },
+      i
+    )),
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("style", { children: `@keyframes xzibit-pulse { 0%, 100% { opacity: 1 } 50% { opacity: 0.5 } }` })
+  ] });
+}
+function DropdownError({ message }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+    "div",
+    {
+      role: "alert",
+      style: {
+        padding: "0.75rem",
+        fontSize: "13px",
+        fontWeight: 400,
+        color: "var(--destructive, #C0392B)"
+      },
+      children: [
+        "Failed to load apps: ",
+        message
+      ]
+    }
+  );
+}
+function DropdownEmpty() {
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+    "div",
+    {
+      style: {
+        padding: "0.75rem",
+        fontSize: "13px",
+        fontWeight: 400,
+        color: "var(--muted-foreground, #888A8B)"
+      },
+      children: "No other apps available"
+    }
+  );
+}
+
+// src/TopBar.tsx
+var import_jsx_runtime4 = require("react/jsx-runtime");
+function TopBar({
+  appName,
+  appHomeUrl = "/",
+  buildSha,
+  buildTimestamp,
+  launcherUrl,
+  appsEndpoint
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
+    "header",
+    {
+      style: {
+        position: "fixed",
+        top: 0,
+        left: 0,
+        right: 0,
+        height: "44px",
+        zIndex: 100,
+        background: "var(--xz-charcoal, #252E38)",
+        borderBottom: "1px solid rgba(255, 255, 255, 0.08)",
+        padding: "0 1rem",
+        display: "flex",
+        alignItems: "center"
+      },
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          "a",
+          {
+            href: "#main",
+            style: {
+              position: "absolute",
+              left: "-9999px",
+              top: "auto",
+              width: "1px",
+              height: "1px",
+              overflow: "hidden"
+            },
+            children: "Skip to main content"
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(BackToLauncher, { launcherUrl }),
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(VerticalSeparator, {}),
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(AppWordmark, { appName, appHomeUrl }),
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(VerticalSeparator, {}),
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(AppsDropdown, { endpoint: appsEndpoint }),
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          "div",
+          {
+            style: {
+              marginLeft: "auto",
+              display: "flex",
+              alignItems: "center"
+            },
+            children: buildSha && /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(BuildBadge, { sha: buildSha, timestamp: buildTimestamp })
+          }
+        )
+      ]
+    }
+  );
+}
+function VerticalSeparator() {
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+    "div",
+    {
+      "aria-hidden": "true",
+      style: {
+        width: "1px",
+        height: "26px",
+        background: "rgba(255, 255, 255, 0.08)",
+        flexShrink: 0
+      }
+    }
+  );
+}
+function AppWordmark({
+  appName,
+  appHomeUrl
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
+    "a",
+    {
+      href: appHomeUrl,
+      style: {
+        display: "flex",
+        alignItems: "center",
+        gap: "8px",
+        padding: "0 1rem",
+        height: "44px",
+        textDecoration: "none",
+        color: "#ffffff",
+        fontSize: "18px",
+        fontWeight: 500
+      },
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          "span",
+          {
+            "aria-hidden": "true",
+            style: {
+              width: "4px",
+              height: "4px",
+              background: "var(--xz-teal, #19B1A1)",
+              borderRadius: "50%",
+              display: "inline-block",
+              flexShrink: 0
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { children: appName })
+      ]
+    }
+  );
+}
+function BuildBadge({
+  sha,
+  timestamp
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
+    "div",
+    {
+      "aria-hidden": "true",
+      style: {
+        fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+        fontSize: "11px",
+        fontWeight: 400,
+        color: "rgba(255, 255, 255, 0.5)",
+        padding: "0 1rem"
+      },
+      children: [
+        sha,
+        timestamp && ` \xB7 Last updated ${timestamp}`
+      ]
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppsDropdown,
+  BackToLauncher,
+  TopBar,
+  XzibitMark,
+  useApps
+});

package/dist/index.d.cts

@@ -0,0 +1,153 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface TopBarProps {
+    /** App display name shown in the wordmark slot (e.g. "ERP Overview"). */
+    appName: string;
+    /** Optional click target for the app wordmark. Defaults to "/" (app home). */
+    appHomeUrl?: string;
+    /** Build SHA — typically `process.env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7)`. */
+    buildSha?: string;
+    /**
+     * Last-updated timestamp string. Pre-format on the consumer side
+     * (e.g. "22 May 2026, 5:03 pm AEST"). Brisbane time recommended per
+     * portfolio convention.
+     */
+    buildTimestamp?: string;
+    /** Launcher URL override — defaults to https://xzibit-apps.vercel.app. */
+    launcherUrl?: string;
+    /** Override the /api/me/apps endpoint for the dropdown. */
+    appsEndpoint?: string;
+}
+/**
+ * Universal 44px fixed top bar across every Xzibit App.
+ *
+ * Per DESIGN-STANDARD v2.3 + v2.3.1 §Top Bar:
+ * - Absorbs back-to-launcher anchor + app wordmark + build badge
+ * - Adds Apps dropdown (dynamic data, sectioned + within-section alphabetical)
+ * - Sits above the left rail (Pattern A apps) at z-index 100
+ * - Page content offsets `margin-top: 44px`
+ *
+ * Reference impl: xzibit-apps/erp-overview SHA 6f1a5b5+
+ */
+declare function TopBar({ appName, appHomeUrl, buildSha, buildTimestamp, launcherUrl, appsEndpoint, }: TopBarProps): react_jsx_runtime.JSX.Element;
+
+interface BackToLauncherProps {
+    /** Launcher URL — defaults to the production Xzibit Apps launcher. */
+    launcherUrl?: string;
+}
+/**
+ * Back-to-launcher anchor for the TopBar's left cluster.
+ *
+ * Renders `[chevron-left] [Xzibit X logo] [Xzibit Apps text]` inside a single
+ * `<a>` element so the whole cluster is one click target with one navigation
+ * destination. Cross-deployment navigation — uses native anchor, NOT Next.js
+ * Link (cross-domain).
+ *
+ * Per DESIGN-STANDARD v2.3.1:
+ * - Text "Xzibit Apps" at 15px / 500 / 85% white (full white on hover)
+ * - Chevron 12×12 at 70% white (full white on hover)
+ * - X logo 28×28 unchanged on hover (stays native white-on-black stamp)
+ */
+declare function BackToLauncher({ launcherUrl, }: BackToLauncherProps): react_jsx_runtime.JSX.Element;
+
+interface AppsDropdownProps {
+    /** Override the endpoint URL. Default: '/api/me/apps' via useApps(). */
+    endpoint?: string;
+}
+/**
+ * Apps dropdown for the TopBar — sectioned + within-section alphabetical.
+ *
+ * Per DESIGN-STANDARD v2.3.1 §Top Bar §Apps dropdown panel:
+ * - Groups apps by `section` field
+ * - Section order from `section_order` (matches launcher curation)
+ * - Within each section: alphabetical by `name` ASC, case-insensitive
+ * - Section heading: 11px / 500 / muted / uppercase / +0.06em letter-spacing
+ * - Section divider: 1px var(--border), 8px margin top/bottom — NOT above
+ *   the first section, NOT below the last
+ * - Skeleton during fetch; empty-state copy if user has no other apps
+ *
+ * Accessibility: opens on click; closes on Esc; closes on outside-click;
+ * focus returns to trigger on close. Items are role="menuitem".
+ */
+declare function AppsDropdown({ endpoint }?: AppsDropdownProps): react_jsx_runtime.JSX.Element;
+
+interface XzibitMarkProps {
+    /** Size in pixels (square). Default 28 to fit inside the 44px TopBar. */
+    size?: number;
+    /** Optional className for additional styling. */
+    className?: string;
+    /** If provided, sets the accessible name. Omit for decorative usage (defaults to aria-hidden). */
+    ariaLabel?: string;
+}
+/**
+ * Xzibit X brand mark, rendered as inline SVG for crisp display at any pixel density.
+ *
+ * Native black background — the "stamp" treatment that gives the mark visual weight
+ * against the var(--xz-charcoal) TopBar background. The mark is geometric / angular,
+ * approximating the architectural character of the brand asset.
+ *
+ * Default usage is decorative (aria-hidden). Provide `ariaLabel` for cases where
+ * the mark is the sole semantic content of an interactive element.
+ */
+declare function XzibitMark({ size, className, ariaLabel }: XzibitMarkProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Shared types for @xzibit/ui.
+ */
+/**
+ * An app in the Xzibit Apps portfolio.
+ *
+ * Shape matches the response from each app's `/api/me/apps` endpoint,
+ * which queries `public.apps` JOIN `public.role_app_permissions` and returns
+ * the apps the authenticated user has access to per their role.
+ */
+interface App {
+    /** Display name, e.g. "Capacity Planner". */
+    name: string;
+    /** Full URL including protocol, e.g. "https://xzibit-capacity-planner.vercel.app". */
+    url: string;
+    /** Optional one-line description rendered as secondary text in the dropdown. */
+    description?: string;
+    /** Section grouping label, e.g. "Strategic", "Calculators". Null = no section. */
+    section?: string | null;
+    /** Sort order for the section itself (matches launcher curation). */
+    section_order?: number;
+}
+/**
+ * Response shape from `/api/me/apps`.
+ *
+ * Per CODING-STANDARDS §6.4 — successful responses are wrapped in a `data`
+ * or domain-specific key (in this case `apps`).
+ */
+interface AppsResponse {
+    apps?: App[];
+    error?: string;
+}
+
+interface UseAppsResult {
+    apps: App[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+}
+interface UseAppsOptions {
+    /** Override the endpoint URL. Default: '/api/me/apps' (same-origin per-app endpoint). */
+    endpoint?: string;
+    /** If true, defer the initial fetch until refetch() is called explicitly. Default false (fetch on mount). */
+    lazy?: boolean;
+}
+/**
+ * Fetch the list of Xzibit Apps the current user has access to.
+ *
+ * Each consuming app exposes its own `/api/me/apps` endpoint (same-origin)
+ * that queries shared `public.apps` + `public.role_app_permissions` and
+ * returns the filtered list. This hook wraps the fetch with loading + error
+ * state and an exposed `refetch()`.
+ *
+ * Per DESIGN-STANDARD v2.3 §Top Bar — the dropdown MUST be dynamic for
+ * production (no hardcoded lists). Adding a new portfolio app then becomes
+ * one INSERT in `public.apps` + role grants — zero per-app code changes.
+ */
+declare function useApps(options?: UseAppsOptions): UseAppsResult;
+
+export { type App, AppsDropdown, type AppsDropdownProps, type AppsResponse, BackToLauncher, type BackToLauncherProps, TopBar, type TopBarProps, type UseAppsOptions, type UseAppsResult, XzibitMark, type XzibitMarkProps, useApps };