@odla-ai/chapter 0.20.2 → 0.21.0

package/README.md

@@ -8,7 +8,7 @@ email. The host still builds the public pages, routing, and brand presentation;
 Chapter supplies their application mechanics.
 
 ```sh
-npm i --save-exact @odla-ai/chapter@0.20.2
+npm i --save-exact @odla-ai/chapter@0.21.0
 ```
 
 > **Agentic experiment.** Built and maintained by AI agents from bounded runbooks
@@ -101,34 +101,38 @@ secrets out of source and require development proof before production.
     presentational component without the Clerk browser SDK. (A bundle-graph test
     enforces this.)
   - `@odla-ai/chapter/ui/admin` — the Clerk-gated console `ChapterAdmin` + the
-    section catalog. `<ChapterAdmin chapter={chapter}/>` derives the brand and
-    standard sections automatically: every configured CRM collection plus the
-    chapter operational surfaces. Pass `sections` only for a deliberate custom
-    console. This one needs auth-clerk + crm/ui.
+    workspace catalog. In chapter mode, `<ChapterAdmin chapter={chapter}/>`
+    defaults to just three top-level workspaces: Dashboard, People, and
+    Settings. Operational detail belongs in nested page tabs; CRM record
+    operations belong in record tabs. Pass `workspaces` to transform or replace
+    that information architecture. This entry needs auth-clerk + crm/ui.
   - `@odla-ai/chapter/ui` — the full barrel, for back-compat.
 
   Authored against React, rendered as Preact via `preact/compat` in the reference
   sites. Brand tokens (`brandTokens`/`<BrandStyle>`) re-skin all of it from
   `brand` (now light **and** dark, via `brand.palette` + `brand.paletteDark`).
 
-### Theme tokens (or the console renders broken)
+### Theme tokens and scoped branding
 
 The UI reads its colors from `--ui-*` design tokens whose **values come from a
-theme layer, not `@odla-ai/ui/index.css`.** Use the one-import application sheet;
-it expands to the token layer, Salt's familiar editorial component treatment,
-then the shared component sheet in the required order:
+theme layer, not `@odla-ai/ui/index.css`.** For an admin surface isolated from
+the public site, import one scoped theme, the shared component sheet, and the
+CRM layout:
 
 ```ts
-import "@odla-ai/ui/themes/salt/app.css";
+import "@odla-ai/ui/fonts/plex.css";
+import "@odla-ai/ui/themes/paper/scope.css";
+import "@odla-ai/ui/index.css";
+import "@odla-ai/crm/ui.css";
 ```
 
 `ChapterAdmin` guards against this at runtime: if a `.panel` has no background
 (the theme layer is missing), it renders a **loud red banner** at the top of the
-console instead of failing silently. To brand it, pass `brand.palette` /
-`brand.paletteDark` — `brandTokens(brand)` emits both a `:root` block and a
-`[data-theme="dark"]` / `prefers-color-scheme: dark` block, so your accent/colors
-override the shared visual grammar in both modes. When the `chapter` prop is
-present, `ChapterAdmin` installs those brand tokens itself.
+console instead of failing silently. Set `brand.theme`, `brand.colorScheme`,
+and semantic `brand.tokens` / `brand.tokensDark` for normal configuration.
+`brand.palette` / `brand.paletteDark` remain the low-level custom-property
+escape hatch. Chapter scopes these overrides to `[data-chapter-admin]`, so an
+admin brand cannot recolor the document root or vendor sign-in UI.
 
 ## API quick start
 
@@ -144,7 +148,13 @@ export const chapter = defineChapter({
     badge: "EX",
     wordmark: "Example Chapter",
     tagline: "Capital and craft for durable local businesses.",
-    palette: { "--ui-accent": "#2f6f4f" },
+    theme: "paper",
+    colorScheme: "light",
+    tokens: {
+      accent: "#2f6f4f",
+      accentStrong: "#244f3b",
+      accentSoft: "#dfece4",
+    },
     fonts: { display: "GT Sectra" },
   },
   prices: { standardCents: 100000, foundingDiscountCents: 10000 },
@@ -160,8 +170,11 @@ export default chapterWorker({ chapter });
 ```
 
 ```tsx
-// src/app/admin.tsx — brand + familiar sections come from the same config.
-import "@odla-ai/ui/themes/salt/app.css";
+// src/app/admin.tsx — brand + familiar workspaces come from the same config.
+import "@odla-ai/ui/fonts/plex.css";
+import "@odla-ai/ui/themes/paper/scope.css";
+import "@odla-ai/ui/index.css";
+import "@odla-ai/crm/ui.css";
 import { render } from "preact";
 import { ChapterAdmin } from "@odla-ai/chapter/ui/admin";
 import { chapter } from "../chapter.config.mjs";
@@ -274,24 +287,24 @@ records, not `crm_link` relation rows; create or curate `works_at` links locally
 
 #### Custom leader consoles must mount the sharing UI
 
-Automatic “Share with …” actions come from chapter's standard collection
-sections. They are present when the console uses
-`<ChapterAdmin chapter={chapter} />`. Passing an explicit `sections` array
-replaces that catalog, so a custom console must deliberately compose it:
+Automatic “Share with …” actions come from Chapter's standard People workspace.
+They are present when the console uses `<ChapterAdmin chapter={chapter} />`.
+Passing a `workspaces` array replaces that catalog, so a custom console must
+deliberately compose it:
 
 ```tsx
 import {
   ChapterAdmin,
-  defaultAdminSections,
+  defaultAdminWorkspaces,
 } from "@odla-ai/chapter/ui/admin";
 
-const sections = [
-  customOverviewSection,
-  ...defaultAdminSections(chapter),
+const workspaces = [
+  customOperationsWorkspace,
+  ...defaultAdminWorkspaces(chapter),
 ];
 
 render(
-  <ChapterAdmin chapter={chapter} sections={sections} />,
+  <ChapterAdmin chapter={chapter} workspaces={workspaces} />,
   document.getElementById("admin-root"),
 );
 ```
@@ -333,10 +346,43 @@ Only after this contract passes against development origins should the leader
 target be changed to a production follower origin and the matching production
 vault values be installed.
 
-Section navigation defaults to `/admin/?tab=people`, not
-`/admin/people`. Query routing deliberately works in both leader-style SPAs and
-ordinary static subdirectories. Legacy path links still open, and
-`routing="path"` remains available only for hosts with an explicit SPA fallback.
+Admin navigation defaults to link-backed fragments:
+`/admin/#people/person/record-id/profile`. The four segments are workspace,
+nested view, selected record, and record-detail tab. This keeps meaningful,
+reloadable URLs without requiring a server-side SPA fallback, and it avoids
+competing with Clerk's sign-in hash: while signed out, Chapter carries the
+requested state through the redirect query and canonicalizes it after sign-in.
+Legacy `?tab=` and path links still open, while `routing="query"` and
+`routing="path"` remain compatibility modes.
+
+### Admin information architecture and migration
+
+The default chapter console deliberately has only three top-level workspaces:
+
+- **Dashboard** — Overview and Billing page tabs.
+- **People** — configured CRM collections as page tabs, then a master/detail
+  record view with Stage, Profile, communications, scheduling, Billing, Notes,
+  Connections, Access, and Sharing record tabs when those capabilities apply.
+- **Settings** — Calendar and Email page tabs.
+
+Use `chrome="editorial"` (the default), `chrome="none"` when the host supplies
+its own site header, or `renderHeader` for a fully custom header. The deprecated
+`chrome="topbar"` and `sections` APIs remain available for migration, but do
+not add operational detail back to the global site navigation.
+
+When upgrading a flat console:
+
+1. Import the scoped UI theme, `@odla-ai/ui/index.css`, and
+   `@odla-ai/crm/ui.css`.
+2. Remove top-level Billing, Email, Calendar, or collection links that duplicate
+   the standard nested tabs.
+3. Replace `sections` with `workspaces`, or omit it to accept the defaults.
+4. Remove host-owned record drawers and compose extra operations with
+   `collectionSection` or CRM `extendRecordTabs`.
+5. Change generated links to `adminRouteHref`; keep legacy query/path URLs only
+   as inbound compatibility links.
+6. Verify refresh, back/forward navigation, keyboard tab behavior, mobile
+   list/detail switching, and brand containment before deleting old routes.
 
 ## Adopting into an existing site
 
@@ -467,7 +513,7 @@ These bite silently — a smoke test won't catch them:
   invitation mail. Importing the full `@odla-ai/chapter/ui` barrel pulls the admin
   half, so prefer the narrower entry.
 - **Known-good application set** (installs clean, no flags):
-  `@odla-ai/chapter` 0.20.2, `@odla-ai/ui` 0.10.0, `@odla-ai/crm` 0.1.4,
+  `@odla-ai/chapter` 0.21.0, `@odla-ai/ui` 0.11.0, `@odla-ai/crm` 0.2.0,
   `@odla-ai/db` 0.6.6,
   `@odla-ai/calendar` 0.2.0, `@odla-ai/email` 0.3.1,
   `@odla-ai/auth-clerk` 0.4.0, `@odla-ai/o11y` 2.2.2, `jose` 6.2.3, React

package/dist/chunk-3JG5X2LT.js

@@ -0,0 +1,80 @@
+// src/brand.ts
+function paletteVar(key) {
+  return key.startsWith("--") ? key : `--${key}`;
+}
+function cleanValue(value) {
+  return value.replace(/[<>{};]/g, "").trim();
+}
+function paletteDecls(palette) {
+  const decls = [];
+  for (const [key, value] of Object.entries(palette ?? {})) {
+    if (typeof value === "string" && value.trim()) decls.push(`${paletteVar(key)}: ${cleanValue(value)};`);
+  }
+  return decls;
+}
+var TOKEN_VARS = {
+  background: "--ui-bg",
+  surface: "--ui-surface",
+  surface2: "--ui-surface-2",
+  text: "--ui-text",
+  textMuted: "--ui-text-muted",
+  textFaint: "--ui-text-faint",
+  border: "--ui-border",
+  borderStrong: "--ui-border-strong",
+  accent: "--ui-accent",
+  accentStrong: "--ui-accent-strong",
+  accentSoft: "--ui-accent-soft",
+  onAccent: "--ui-on-accent",
+  good: "--ui-good",
+  warn: "--ui-warn",
+  danger: "--ui-danger",
+  chart1: "--ui-chart-1",
+  chart2: "--ui-chart-2",
+  chartPositive: "--ui-chart-pos",
+  chartNegative: "--ui-chart-neg"
+};
+function semanticDecls(tokens) {
+  return Object.entries(tokens ?? {}).flatMap(
+    ([key, value]) => typeof value === "string" && value.trim() ? [`${TOKEN_VARS[key]}: ${cleanValue(value)};`] : []
+  );
+}
+function brandTokens(brand, options = {}) {
+  if (!brand) return "";
+  const light = [...paletteDecls(brand.palette), ...semanticDecls(brand.tokens)];
+  const fonts = brand.fonts;
+  if (fonts?.display) light.push(`--ui-font-display: ${cleanValue(fonts.display)};`);
+  if (fonts?.body) light.push(`--ui-font-sans: ${cleanValue(fonts.body)};`);
+  if (fonts?.numeral) light.push(`--ui-font-numeral: ${cleanValue(fonts.numeral)};`);
+  const dark = [...paletteDecls(brand.paletteDark), ...semanticDecls(brand.tokensDark)];
+  const selector = options.selector ?? ":root";
+  const darkSelector = selector === ":root" ? ':root[data-theme="dark"]' : `${selector}[data-theme="dark"]`;
+  const systemSelector = selector === ":root" ? ':root:not([data-theme="light"])' : `${selector}:not([data-theme="light"])`;
+  let css = light.length ? `${selector} {
+  ${light.join("\n  ")}
+}
+` : "";
+  if (dark.length) {
+    const block = `{
+  ${dark.join("\n  ")}
+}`;
+    css += `${darkSelector} ${block}
+@media (prefers-color-scheme: dark) {
+  ${systemSelector} ${block}
+}
+`;
+  }
+  return css;
+}
+
+// src/ui/brand-style.tsx
+import { jsx } from "react/jsx-runtime";
+function BrandStyle(props) {
+  const css = brandTokens(props.brand, { selector: props.selector });
+  if (!css) return null;
+  return /* @__PURE__ */ jsx("style", { children: css });
+}
+
+export {
+  BrandStyle
+};
+//# sourceMappingURL=chunk-3JG5X2LT.js.map

package/dist/chunk-3JG5X2LT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/brand.ts","../src/ui/brand-style.tsx"],"sourcesContent":["// Brand tokens (H4). defineChapter accepts a `brand` block; this turns it into a\n// `:root { --…: … }` CSS block, so a chapter re-skins the WHOLE UI — the\n// @odla-ai/ui components, the admin shell, and the member islands, which all read\n// --ui-* design tokens — from one config instead of hand-writing inline CSS.\n//\n// Pure string generation, so it is unit-testable and can be emitted at\n// build/SSR time into the page <head> (no flash of unstyled content), or via the\n// <BrandStyle> component from @odla-ai/chapter/ui.\nimport type { ChapterBrand, ChapterBrandTokens } from \"./types\";\n\n// A palette entry is either a direct custom property (already `--…`, e.g.\n// `--ui-accent` to retheme components) or a bare name we expose as `--<name>`\n// (e.g. `moss` → `--moss`, for a site to reference in its own CSS).\nfunction paletteVar(key: string): string {\n  return key.startsWith(\"--\") ? key : `--${key}`;\n}\n\n// Strip characters that could break out of a `--var: value;` declaration or the\n// surrounding <style>. Brand config is trusted author input, so this is a\n// belt-and-suspenders guard, not a security boundary.\nfunction cleanValue(value: string): string {\n  return value.replace(/[<>{};]/g, \"\").trim();\n}\n\nfunction paletteDecls(palette: Record<string, string> | undefined): string[] {\n  const decls: string[] = [];\n  for (const [key, value] of Object.entries(palette ?? {})) {\n    if (typeof value === \"string\" && value.trim()) decls.push(`${paletteVar(key)}: ${cleanValue(value)};`);\n  }\n  return decls;\n}\n\nconst TOKEN_VARS: Record<keyof ChapterBrandTokens, string> = {\n  background: \"--ui-bg\",\n  surface: \"--ui-surface\",\n  surface2: \"--ui-surface-2\",\n  text: \"--ui-text\",\n  textMuted: \"--ui-text-muted\",\n  textFaint: \"--ui-text-faint\",\n  border: \"--ui-border\",\n  borderStrong: \"--ui-border-strong\",\n  accent: \"--ui-accent\",\n  accentStrong: \"--ui-accent-strong\",\n  accentSoft: \"--ui-accent-soft\",\n  onAccent: \"--ui-on-accent\",\n  good: \"--ui-good\",\n  warn: \"--ui-warn\",\n  danger: \"--ui-danger\",\n  chart1: \"--ui-chart-1\",\n  chart2: \"--ui-chart-2\",\n  chartPositive: \"--ui-chart-pos\",\n  chartNegative: \"--ui-chart-neg\",\n};\n\nfunction semanticDecls(tokens: ChapterBrandTokens | undefined): string[] {\n  return Object.entries(tokens ?? {}).flatMap(([key, value]) =>\n    typeof value === \"string\" && value.trim()\n      ? [`${TOKEN_VARS[key as keyof ChapterBrandTokens]}: ${cleanValue(value)};`]\n      : [],\n  );\n}\n\n/**\n * Build the CSS that maps a chapter's brand onto the design tokens the UI reads:\n * each `palette` entry becomes a custom property (light, and dark unless\n * `paletteDark` overrides), and `fonts` (display/body/numeral) map to\n * `--ui-font-display` / `--ui-font-sans` / `--ui-font-numeral`. The dark block is\n * emitted under both `:root[data-theme=\"dark\"]` (the odla-ui theme toggle) and\n * `@media (prefers-color-scheme: dark)`. Returns \"\" when there is nothing to\n * theme. These are brand OVERRIDES on top of a base theme — they do not replace\n * the theme layer the components need (see {@link brandTokens} usage in the docs).\n */\nexport function brandTokens(\n  brand: ChapterBrand | undefined,\n  options: { selector?: string } = {},\n): string {\n  if (!brand) return \"\";\n  const light = [...paletteDecls(brand.palette), ...semanticDecls(brand.tokens)];\n  const fonts = brand.fonts;\n  if (fonts?.display) light.push(`--ui-font-display: ${cleanValue(fonts.display)};`);\n  if (fonts?.body) light.push(`--ui-font-sans: ${cleanValue(fonts.body)};`);\n  if (fonts?.numeral) light.push(`--ui-font-numeral: ${cleanValue(fonts.numeral)};`);\n  const dark = [...paletteDecls(brand.paletteDark), ...semanticDecls(brand.tokensDark)];\n  const selector = options.selector ?? \":root\";\n  const darkSelector = selector === \":root\" ? ':root[data-theme=\"dark\"]' : `${selector}[data-theme=\"dark\"]`;\n  const systemSelector = selector === \":root\"\n    ? ':root:not([data-theme=\"light\"])'\n    : `${selector}:not([data-theme=\"light\"])`;\n\n  let css = light.length ? `${selector} {\\n  ${light.join(\"\\n  \")}\\n}\\n` : \"\";\n  if (dark.length) {\n    const block = `{\\n  ${dark.join(\"\\n  \")}\\n}`;\n    css += `${darkSelector} ${block}\\n@media (prefers-color-scheme: dark) {\\n  ${systemSelector} ${block}\\n}\\n`;\n  }\n  return css;\n}\n","// Client-side convenience for brand tokens: render the chapter's brand as a\n// <style> tag. Prefer emitting brandTokens() into the page <head> at build/SSR\n// time (no flash); use this when that isn't available (e.g. a pure SPA mount).\nimport { brandTokens } from \"../brand.js\";\nimport type { ChapterBrand } from \"../types\";\n\n/** Props for {@link BrandStyle}. */\nexport interface BrandStyleProps {\n  brand: ChapterBrand | undefined;\n  /** CSS selector receiving the variables. Default `:root`. */\n  selector?: string;\n}\n\n/** Render a chapter's brand tokens as an inline <style> block (or nothing when\n *  there is no brand to theme). */\nexport function BrandStyle(props: BrandStyleProps) {\n  const css = brandTokens(props.brand, { selector: props.selector });\n  if (!css) return null;\n  return <style>{css}</style>;\n}\n"],"mappings":";AAaA,SAAS,WAAW,KAAqB;AACvC,SAAO,IAAI,WAAW,IAAI,IAAI,MAAM,KAAK,GAAG;AAC9C;AAKA,SAAS,WAAW,OAAuB;AACzC,SAAO,MAAM,QAAQ,YAAY,EAAE,EAAE,KAAK;AAC5C;AAEA,SAAS,aAAa,SAAuD;AAC3E,QAAM,QAAkB,CAAC;AACzB,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,WAAW,CAAC,CAAC,GAAG;AACxD,QAAI,OAAO,UAAU,YAAY,MAAM,KAAK,EAAG,OAAM,KAAK,GAAG,WAAW,GAAG,CAAC,KAAK,WAAW,KAAK,CAAC,GAAG;AAAA,EACvG;AACA,SAAO;AACT;AAEA,IAAM,aAAuD;AAAA,EAC3D,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,UAAU;AAAA,EACV,MAAM;AAAA,EACN,WAAW;AAAA,EACX,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,cAAc;AAAA,EACd,QAAQ;AAAA,EACR,cAAc;AAAA,EACd,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,MAAM;AAAA,EACN,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,eAAe;AAAA,EACf,eAAe;AACjB;AAEA,SAAS,cAAc,QAAkD;AACvE,SAAO,OAAO,QAAQ,UAAU,CAAC,CAAC,EAAE;AAAA,IAAQ,CAAC,CAAC,KAAK,KAAK,MACtD,OAAO,UAAU,YAAY,MAAM,KAAK,IACpC,CAAC,GAAG,WAAW,GAA+B,CAAC,KAAK,WAAW,KAAK,CAAC,GAAG,IACxE,CAAC;AAAA,EACP;AACF;AAYO,SAAS,YACd,OACA,UAAiC,CAAC,GAC1B;AACR,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,QAAQ,CAAC,GAAG,aAAa,MAAM,OAAO,GAAG,GAAG,cAAc,MAAM,MAAM,CAAC;AAC7E,QAAM,QAAQ,MAAM;AACpB,MAAI,OAAO,QAAS,OAAM,KAAK,sBAAsB,WAAW,MAAM,OAAO,CAAC,GAAG;AACjF,MAAI,OAAO,KAAM,OAAM,KAAK,mBAAmB,WAAW,MAAM,IAAI,CAAC,GAAG;AACxE,MAAI,OAAO,QAAS,OAAM,KAAK,sBAAsB,WAAW,MAAM,OAAO,CAAC,GAAG;AACjF,QAAM,OAAO,CAAC,GAAG,aAAa,MAAM,WAAW,GAAG,GAAG,cAAc,MAAM,UAAU,CAAC;AACpF,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,eAAe,aAAa,UAAU,6BAA6B,GAAG,QAAQ;AACpF,QAAM,iBAAiB,aAAa,UAChC,oCACA,GAAG,QAAQ;AAEf,MAAI,MAAM,MAAM,SAAS,GAAG,QAAQ;AAAA,IAAS,MAAM,KAAK,MAAM,CAAC;AAAA;AAAA,IAAU;AACzE,MAAI,KAAK,QAAQ;AACf,UAAM,QAAQ;AAAA,IAAQ,KAAK,KAAK,MAAM,CAAC;AAAA;AACvC,WAAO,GAAG,YAAY,IAAI,KAAK;AAAA;AAAA,IAA8C,cAAc,IAAI,KAAK;AAAA;AAAA;AAAA,EACtG;AACA,SAAO;AACT;;;AC7ES;AAHF,SAAS,WAAW,OAAwB;AACjD,QAAM,MAAM,YAAY,MAAM,OAAO,EAAE,UAAU,MAAM,SAAS,CAAC;AACjE,MAAI,CAAC,IAAK,QAAO;AACjB,SAAO,oBAAC,WAAO,eAAI;AACrB;","names":[]}