@xzibit/ui 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,7 +2,50 @@
 
 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.2.0] — 2026-05-24
+
+### Added
+
+- **`<ContentContainer tier="...">`** — implements DESIGN-STANDARD v2.4 §Content Density Tiers. Three tiers: `'editorial'` (720px), `'reference'` (1200px, DEFAULT), `'data'` (unconstrained with 32px side padding). Drop-in wrapper for `<main>` content. Per-page overrides via `tier` prop.
+- **`ContentTier`** type exported for app authors wanting to type tier props at their own layer.
+
+### Coming next
+
+- `<Toast />` + `useToast()` — wrapper around `sonner` per DESIGN-STANDARD §Toast / Notification (v2.2). Will ship as v0.2.1 once drafted.
+- `<Modal />` — wrapper around `@radix-ui/react-dialog` per DESIGN-STANDARD §Modal / Dialog (v2.2). Will ship as v0.2.2 once drafted.
+
+(Joel chose Option A 2026-05-24 — fast-ship v0.2.0 with just ContentContainer to unblock portfolio-wide adoption of the new content tier system. Toast + Modal ship as subsequent patches.)
+
+---
+
+## [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
@@ -138,6 +146,7 @@ This sets `--xz-charcoal`, `--xz-teal`, `--xz-white`, `--border`, etc. — and `
 | `<AppsDropdown />` | Sectioned + alphabetical apps dropdown driven by `/api/me/apps` |
 | `<XzibitMark size={28} />` | Xzibit X brand mark as inline SVG (any size, any density) |
 | `useApps()` | React hook fetching `/api/me/apps` with loading + error + refetch |
+| `<ContentContainer tier="reference">` *(v0.2+)* | Content max-width container per DESIGN-STANDARD v2.4 §Content Density Tiers — tiers: `'editorial'` (720px), `'reference'` (1200px, default), `'data'` (unconstrained). Wraps `<main>` content. |
 
 ---
 

package/dist/index.cjs

@@ -22,8 +22,10 @@ var index_exports = {};
 __export(index_exports, {
   AppsDropdown: () => AppsDropdown,
   BackToLauncher: () => BackToLauncher,
+  ContentContainer: () => ContentContainer,
   TopBar: () => TopBar,
   XzibitMark: () => XzibitMark,
+  normalizeApp: () => normalizeApp,
   useApps: () => useApps
 });
 module.exports = __toCommonJS(index_exports);
@@ -133,6 +135,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 +168,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");
@@ -545,11 +560,28 @@ function BuildBadge({
     }
   );
 }
+
+// src/ContentContainer.tsx
+var import_jsx_runtime5 = require("react/jsx-runtime");
+var TIER_STYLES = {
+  editorial: { maxWidth: 720, margin: "0 auto", padding: "3rem 2rem" },
+  reference: { maxWidth: 1200, margin: "0 auto", padding: "3rem 2rem" },
+  data: { maxWidth: "100%", margin: "0 auto", padding: "1.5rem 2rem" }
+};
+function ContentContainer({
+  tier = "reference",
+  className,
+  children
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { className, style: TIER_STYLES[tier], children });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AppsDropdown,
   BackToLauncher,
+  ContentContainer,
   TopBar,
   XzibitMark,
+  normalizeApp,
   useApps
 });

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
 
 interface TopBarProps {
     /** App display name shown in the wordmark slot (e.g. "ERP Overview"). */
@@ -95,11 +96,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 +115,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 +182,50 @@ 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 };
+/**
+ * Content density tier per DESIGN-STANDARD v2.4 §Content Density Tiers.
+ *
+ * - `'editorial'`: 720px max-width — marketing / public-facing docs / long-form prose
+ * - `'reference'` (DEFAULT): 1200px max-width — internal docs / wikis / dashboards / most app pages
+ * - `'data'`: unconstrained with 32px min side padding — wide tables / kanban / calendars / heatmaps
+ */
+type ContentTier = 'editorial' | 'reference' | 'data';
+interface ContentContainerProps {
+    /**
+     * Content density tier — picks max-width + padding.
+     * Defaults to `'reference'` (the portfolio default per v2.4).
+     */
+    tier?: ContentTier;
+    /** Optional className for additional styling. */
+    className?: string;
+    /** Children to render inside the container. */
+    children: ReactNode;
+}
+/**
+ * Content container that applies the right max-width + padding for its content
+ * density tier per DESIGN-STANDARD v2.4 §Content Density Tiers.
+ *
+ * Per the spec:
+ * - Component override > page override > app default (most-specific wins)
+ * - Cards INHERIT the parent container's max-width — they do NOT set their own
+ *
+ * Typical app usage in `src/app/layout.tsx`:
+ *
+ * ```tsx
+ * <main id="main" style={{ marginTop: 44 }}>
+ *   <ContentContainer>{children}</ContentContainer>
+ * </main>
+ * ```
+ *
+ * Per-page override (rare):
+ *
+ * ```tsx
+ * // A wide-table page within an otherwise-reference app
+ * <ContentContainer tier="data">
+ *   <DataTable ... />
+ * </ContentContainer>
+ * ```
+ */
+declare function ContentContainer({ tier, className, children, }: ContentContainerProps): react_jsx_runtime.JSX.Element;
+
+export { type App, AppsDropdown, type AppsDropdownProps, type AppsResponse, BackToLauncher, type BackToLauncherProps, ContentContainer, type ContentContainerProps, type ContentTier, type RawApp, TopBar, type TopBarProps, type UseAppsOptions, type UseAppsResult, XzibitMark, type XzibitMarkProps, normalizeApp, useApps };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
 
 interface TopBarProps {
     /** App display name shown in the wordmark slot (e.g. "ERP Overview"). */
@@ -95,11 +96,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 +115,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 +182,50 @@ 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 };
+/**
+ * Content density tier per DESIGN-STANDARD v2.4 §Content Density Tiers.
+ *
+ * - `'editorial'`: 720px max-width — marketing / public-facing docs / long-form prose
+ * - `'reference'` (DEFAULT): 1200px max-width — internal docs / wikis / dashboards / most app pages
+ * - `'data'`: unconstrained with 32px min side padding — wide tables / kanban / calendars / heatmaps
+ */
+type ContentTier = 'editorial' | 'reference' | 'data';
+interface ContentContainerProps {
+    /**
+     * Content density tier — picks max-width + padding.
+     * Defaults to `'reference'` (the portfolio default per v2.4).
+     */
+    tier?: ContentTier;
+    /** Optional className for additional styling. */
+    className?: string;
+    /** Children to render inside the container. */
+    children: ReactNode;
+}
+/**
+ * Content container that applies the right max-width + padding for its content
+ * density tier per DESIGN-STANDARD v2.4 §Content Density Tiers.
+ *
+ * Per the spec:
+ * - Component override > page override > app default (most-specific wins)
+ * - Cards INHERIT the parent container's max-width — they do NOT set their own
+ *
+ * Typical app usage in `src/app/layout.tsx`:
+ *
+ * ```tsx
+ * <main id="main" style={{ marginTop: 44 }}>
+ *   <ContentContainer>{children}</ContentContainer>
+ * </main>
+ * ```
+ *
+ * Per-page override (rare):
+ *
+ * ```tsx
+ * // A wide-table page within an otherwise-reference app
+ * <ContentContainer tier="data">
+ *   <DataTable ... />
+ * </ContentContainer>
+ * ```
+ */
+declare function ContentContainer({ tier, className, children, }: ContentContainerProps): react_jsx_runtime.JSX.Element;
+
+export { type App, AppsDropdown, type AppsDropdownProps, type AppsResponse, BackToLauncher, type BackToLauncherProps, ContentContainer, type ContentContainerProps, type ContentTier, 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");
@@ -515,10 +528,27 @@ function BuildBadge({
     }
   );
 }
+
+// src/ContentContainer.tsx
+import { jsx as jsx5 } from "react/jsx-runtime";
+var TIER_STYLES = {
+  editorial: { maxWidth: 720, margin: "0 auto", padding: "3rem 2rem" },
+  reference: { maxWidth: 1200, margin: "0 auto", padding: "3rem 2rem" },
+  data: { maxWidth: "100%", margin: "0 auto", padding: "1.5rem 2rem" }
+};
+function ContentContainer({
+  tier = "reference",
+  className,
+  children
+}) {
+  return /* @__PURE__ */ jsx5("div", { className, style: TIER_STYLES[tier], children });
+}
 export {
   AppsDropdown,
   BackToLauncher,
+  ContentContainer,
   TopBar,
   XzibitMark,
+  normalizeApp,
   useApps
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xzibit/ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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",