@xzibit/ui 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,7 +2,34 @@
 
 All notable changes to `@xzibit/ui` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/) loosely; versioning follows [SemVer](https://semver.org/).
 
-## [0.1.0] — 2026-05-22
+## [0.1.1] — 2026-05-24
+
+### Fixed
+- **Peer dependency widened** to accept React 19 (`react@"^18.0.0 || ^19.0.0"` and `react-dom` same). Surfaced during ERP Overview migration — `--legacy-peer-deps` was needed to install on the React 19 app. Affects every React 19 app planning to adopt; v0.1.0 blocked clean install.
+- **API field-name contract resilience.** `useApps` now normalizes raw Supabase column names (`app_url`, `display_section`, `display_order`) to the canonical `App` shape (`url`, `section`, `section_order`) via internal `normalizeApp()` at the fetch boundary. Apps with existing endpoints returning raw query rows now work without changes; new endpoints can return either shape. Surfaced during ERP Overview migration — package rendered empty dropdown until CC added a manual `.map()` normalization in the route handler.
+
+### Added
+- `RawApp` type exported for apps that want to type their endpoint response explicitly
+- `normalizeApp(raw: RawApp): App` helper exported for apps that want to call it directly (rare; `useApps` calls it automatically)
+
+### Documentation
+- README's `/api/me/apps` section now documents both accepted field-name conventions and the normalization behaviour.
+
+---
+
+## [0.1.0] — 2026-05-22 (drafted) / 2026-05-23 (published)
+
+### Published artifact
+- npm: https://www.npmjs.com/package/@xzibit/ui
+- Provenance attestation: present
+- Install: `npm install @xzibit/ui`
+
+### Bug fixes applied between draft and publish (sync'd back into this draft 2026-05-23)
+- **`package-lock.json` generated** via `npm install` (not present in initial draft — required for `npm ci` in CI).
+- **Removed stale `import React` namespace imports** from 4 source files (`TopBar.tsx`, `XzibitMark.tsx`, `BackToLauncher.tsx`, `AppsDropdown.tsx`). The package's `tsconfig.json` uses `"jsx": "react-jsx"` (modern transform, doesn't need React import) + `noUnusedLocals: true`, so bare `import React from 'react'` fails the DTS build. Fixed by removing the unused namespace import — named imports (`useState`, `useEffect`, etc.) where actually needed are kept.
+
+### Future-package note
+When drafting any future React component package for the `@xzibit/*` scope, omit `import React from 'react'` unless React is actually used directly (e.g. `React.forwardRef`). Just import the hooks / types you need by name.
 
 ### Added
 

package/README.md

@@ -58,7 +58,15 @@ That's it. The bar renders:
 
 ### `/api/me/apps` endpoint required
 
-`AppsDropdown` calls `GET /api/me/apps` (same-origin) for the cross-app navigation list. Each consuming app must expose this endpoint per CODING-STANDARDS §6.3:
+`AppsDropdown` calls `GET /api/me/apps` (same-origin) for the cross-app navigation list. Each consuming app must expose this endpoint per CODING-STANDARDS §6.3.
+
+**Field-name contract (v0.1.1+):** the endpoint can return EITHER:
+- **Canonical shape** (recommended for new endpoints): `{ name, url, description?, section?, section_order? }`
+- **Supabase column-name passthrough** (for endpoints that return raw `public.apps` rows): `{ name, app_url, description?, display_section?, display_order? }`
+
+`useApps` normalizes both shapes to the canonical `App` interface at the fetch boundary — components downstream never see the raw form. Apps with existing endpoints that return raw column names work without changes.
+
+Example route handler:
 
 ```typescript
 // src/app/api/me/apps/route.ts

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   BackToLauncher: () => BackToLauncher,
   TopBar: () => TopBar,
   XzibitMark: () => XzibitMark,
+  normalizeApp: () => normalizeApp,
   useApps: () => useApps
 });
 module.exports = __toCommonJS(index_exports);
@@ -133,6 +134,19 @@ var import_react3 = require("react");
 
 // src/useApps.ts
 var import_react2 = require("react");
+
+// src/types.ts
+function normalizeApp(raw) {
+  return {
+    name: raw.name,
+    url: raw.url ?? raw.app_url ?? "",
+    description: raw.description,
+    section: raw.section ?? raw.display_section ?? null,
+    section_order: raw.section_order ?? raw.display_order
+  };
+}
+
+// src/useApps.ts
 function useApps(options = {}) {
   const { endpoint = "/api/me/apps", lazy = false } = options;
   const [apps, setApps] = (0, import_react2.useState)([]);
@@ -153,7 +167,7 @@ function useApps(options = {}) {
       if (data.error) {
         throw new Error(data.error);
       }
-      setApps(data.apps ?? []);
+      setApps((data.apps ?? []).map(normalizeApp));
     } catch (err) {
       console.error("[@xzibit/ui useApps] fetch failed:", err);
       setError(err instanceof Error ? err.message : "Unknown error");
@@ -551,5 +565,6 @@ function BuildBadge({
   BackToLauncher,
   TopBar,
   XzibitMark,
+  normalizeApp,
   useApps
 });

package/dist/index.d.cts

@@ -95,11 +95,12 @@ declare function XzibitMark({ size, className, ariaLabel }: XzibitMarkProps): re
  * Shared types for @xzibit/ui.
  */
 /**
- * An app in the Xzibit Apps portfolio.
+ * Canonical app shape consumed by `@xzibit/ui` components.
  *
- * 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.
+ * This is what `useApps` returns after normalization. App authors writing
+ * NEW `/api/me/apps` endpoints SHOULD return this shape directly. Apps with
+ * existing endpoints that return raw Supabase column names (see `RawApp` below)
+ * are also accepted — `useApps` normalizes at the fetch boundary.
  */
 interface App {
     /** Display name, e.g. "Capacity Planner". */
@@ -113,16 +114,46 @@ interface App {
     /** Sort order for the section itself (matches launcher curation). */
     section_order?: number;
 }
+/**
+ * Raw shape accepted from `/api/me/apps` endpoints.
+ *
+ * Supports two field-naming conventions:
+ * - **Canonical** (recommended for new endpoints): `url`, `section`, `section_order`
+ * - **Supabase column-name passthrough** (for endpoints that return raw query rows):
+ *   `app_url`, `display_section`, `display_order`
+ *
+ * `useApps` normalizes to the canonical `App` shape via `normalizeApp()` at the
+ * fetch boundary — components downstream only see the canonical shape.
+ *
+ * Added in v0.1.1 (2026-05-24) after ERP Overview migration surfaced the contract
+ * mismatch with raw Supabase column names.
+ */
+interface RawApp {
+    name: string;
+    url?: string;
+    app_url?: string;
+    description?: string;
+    section?: string | null;
+    display_section?: string | null;
+    section_order?: number;
+    display_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`).
+ * or domain-specific key (in this case `apps`). The `apps` array contains
+ * `RawApp` items; `useApps` normalizes them to `App`.
  */
 interface AppsResponse {
-    apps?: App[];
+    apps?: RawApp[];
     error?: string;
 }
+/**
+ * Internal helper — normalizes a `RawApp` to the canonical `App` shape.
+ * Used by `useApps` at the fetch boundary; not typically called by consumers.
+ */
+declare function normalizeApp(raw: RawApp): App;
 
 interface UseAppsResult {
     apps: App[];
@@ -150,4 +181,4 @@ interface UseAppsOptions {
  */
 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 };
+export { type App, AppsDropdown, type AppsDropdownProps, type AppsResponse, BackToLauncher, type BackToLauncherProps, type RawApp, TopBar, type TopBarProps, type UseAppsOptions, type UseAppsResult, XzibitMark, type XzibitMarkProps, normalizeApp, useApps };

package/dist/index.d.ts

@@ -95,11 +95,12 @@ declare function XzibitMark({ size, className, ariaLabel }: XzibitMarkProps): re
  * Shared types for @xzibit/ui.
  */
 /**
- * An app in the Xzibit Apps portfolio.
+ * Canonical app shape consumed by `@xzibit/ui` components.
  *
- * 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.
+ * This is what `useApps` returns after normalization. App authors writing
+ * NEW `/api/me/apps` endpoints SHOULD return this shape directly. Apps with
+ * existing endpoints that return raw Supabase column names (see `RawApp` below)
+ * are also accepted — `useApps` normalizes at the fetch boundary.
  */
 interface App {
     /** Display name, e.g. "Capacity Planner". */
@@ -113,16 +114,46 @@ interface App {
     /** Sort order for the section itself (matches launcher curation). */
     section_order?: number;
 }
+/**
+ * Raw shape accepted from `/api/me/apps` endpoints.
+ *
+ * Supports two field-naming conventions:
+ * - **Canonical** (recommended for new endpoints): `url`, `section`, `section_order`
+ * - **Supabase column-name passthrough** (for endpoints that return raw query rows):
+ *   `app_url`, `display_section`, `display_order`
+ *
+ * `useApps` normalizes to the canonical `App` shape via `normalizeApp()` at the
+ * fetch boundary — components downstream only see the canonical shape.
+ *
+ * Added in v0.1.1 (2026-05-24) after ERP Overview migration surfaced the contract
+ * mismatch with raw Supabase column names.
+ */
+interface RawApp {
+    name: string;
+    url?: string;
+    app_url?: string;
+    description?: string;
+    section?: string | null;
+    display_section?: string | null;
+    section_order?: number;
+    display_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`).
+ * or domain-specific key (in this case `apps`). The `apps` array contains
+ * `RawApp` items; `useApps` normalizes them to `App`.
  */
 interface AppsResponse {
-    apps?: App[];
+    apps?: RawApp[];
     error?: string;
 }
+/**
+ * Internal helper — normalizes a `RawApp` to the canonical `App` shape.
+ * Used by `useApps` at the fetch boundary; not typically called by consumers.
+ */
+declare function normalizeApp(raw: RawApp): App;
 
 interface UseAppsResult {
     apps: App[];
@@ -150,4 +181,4 @@ interface UseAppsOptions {
  */
 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 };
+export { type App, AppsDropdown, type AppsDropdownProps, type AppsResponse, BackToLauncher, type BackToLauncherProps, type RawApp, TopBar, type TopBarProps, type UseAppsOptions, type UseAppsResult, XzibitMark, type XzibitMarkProps, normalizeApp, useApps };

package/dist/index.js

@@ -103,6 +103,19 @@ import { useState as useState3, useEffect as useEffect2, useRef, Fragment } from
 
 // src/useApps.ts
 import { useState as useState2, useEffect, useCallback } from "react";
+
+// src/types.ts
+function normalizeApp(raw) {
+  return {
+    name: raw.name,
+    url: raw.url ?? raw.app_url ?? "",
+    description: raw.description,
+    section: raw.section ?? raw.display_section ?? null,
+    section_order: raw.section_order ?? raw.display_order
+  };
+}
+
+// src/useApps.ts
 function useApps(options = {}) {
   const { endpoint = "/api/me/apps", lazy = false } = options;
   const [apps, setApps] = useState2([]);
@@ -123,7 +136,7 @@ function useApps(options = {}) {
       if (data.error) {
         throw new Error(data.error);
       }
-      setApps(data.apps ?? []);
+      setApps((data.apps ?? []).map(normalizeApp));
     } catch (err) {
       console.error("[@xzibit/ui useApps] fetch failed:", err);
       setError(err instanceof Error ? err.message : "Unknown error");
@@ -520,5 +533,6 @@ export {
   BackToLauncher,
   TopBar,
   XzibitMark,
+  normalizeApp,
   useApps
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xzibit/ui",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared chrome components for the Xzibit Apps portfolio. v0.1: TopBar + BackToLauncher + AppsDropdown + XzibitMark + useApps hook. Single source of truth for portfolio chrome — tweak once, every app picks it up on next deploy.",
   "license": "MIT",
   "author": "Xzibit Apps",
@@ -42,8 +42,8 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",