@pramen/cms-editor 0.0.50 → 0.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms-editor",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "description": "Visual block/page editor for @pramen/cms \u2014 a standalone React SPA that talks to the CMS handlers over HTTP.",
   "license": "MIT",
   "repository": {

package/src/app-context.tsx

@@ -6,7 +6,8 @@
 import { Button, Input } from "@podoba/react";
 import { createContext, use, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Api, clearConfig, isTokenExpired, loadConfig, saveConfig, type Config } from "./api";
-import type { CollectionMeta, JsonValue } from "./types";
+import { BRAND, SETUP_TITLE, type BrandConfig } from "./brand";
+import { DEFAULT_CAPABILITIES, type CmsCapabilities, type CollectionMeta, type JsonValue } from "./types";
 
 declare global {
   interface Window {
@@ -20,6 +21,13 @@ declare global {
       /** Extra top-nav links to companion tools the host serves (e.g. a curation page).
        * Rendered as plain external `<a>` links after the built-in tabs. */
       extraNav?: { label: string; href: string }[];
+      /** The wordmark in the topbar, on the Setup screen, and in the browser tab.
+       *
+       * This editor ships as a package an agency deploys FOR ITS CLIENT, so the default
+       * put the framework's name where the client's belongs — someone logging into their
+       * own CMS was greeted by "pramen". Set `name` (and optionally `suffix`) to the
+       * deployment's own; `suffix: null` drops the "· cms" half entirely. */
+      brand?: BrandConfig;
     };
   }
 }
@@ -53,6 +61,10 @@ interface AppContextValue {
   /** Collections registered on the server (from `listCollections`) — drives the nav + the
    * generic list/edit routes. Empty when the server registers none. */
   collections: CollectionMeta[];
+  /** What the SERVER says this deployment supports (from `listCmsCapabilities`) — today,
+   * its declared locales. The editor renders its i18n surface off this rather than a local
+   * flag, so the UI and the data can never disagree about whether the site is multilingual. */
+  cms: CmsCapabilities;
   error: string;
   setError: (s: string) => void;
   /** Sign out — drop the token so the config gate falls back to Setup. */
@@ -79,6 +91,7 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
   const [cfg, setCfg] = useState<Config>(loadConfig());
   const [me, setMe] = useState<Me | null>(null);
   const [collections, setCollections] = useState<CollectionMeta[]>([]);
+  const [cms, setCms] = useState<CmsCapabilities>(DEFAULT_CAPABILITIES);
   const [error, setError] = useState("");
   // A usable session = a base URL + a token that is NOT expired. An expired token counts as
   // no session: otherwise the editor mounts and every RPC 403s into an error banner.
@@ -118,6 +131,9 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
     // Collections drive the nav + list/edit routes. An app that registers none (or an older
     // server without the handler) just leaves the nav as-is — a failure is non-fatal.
     api.call<CollectionMeta[]>("listCollections").then(setCollections).catch(() => setCollections([]));
+    // A server older than this handler leaves the monolingual default, which is the safe
+    // way round: the i18n surface stays hidden rather than half-rendered.
+    api.call<CmsCapabilities>("listCmsCapabilities").then(setCms).catch(() => setCms(DEFAULT_CAPABILITIES));
   }, [api, authValid]);
 
   if (!authValid) {
@@ -132,6 +148,7 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
     me,
     isAdmin: (me?.roles ?? []).includes("admin"),
     collections,
+    cms,
     error,
     setError,
     confirmNavigation,
@@ -149,8 +166,10 @@ function Setup({ cfg, onSave }: { cfg: Config; onSave: (c: Config) => void }) {
   return (
     <div className="mx-auto mt-[14vh] w-full max-w-[520px] px-6">
       <div className="rounded-panel border border-border bg-surface-card px-10 py-8 shadow-[0_24px_60px_rgba(30,20,10,0.08)]">
+        {/* `SETUP_TITLE`, not `BRAND.title`: this screen has always read "… cms editor", and
+            the default has to render byte-identical to before the brand seam existed. */}
         <h1 className="mb-4 text-display text-fg">
-          pramen <span className="text-fg-subtle">· cms editor</span>
+          {BRAND.name} <span className="text-fg-subtle">{SETUP_TITLE}</span>
         </h1>
         <p className="mb-6 text-sm text-fg-muted">
           Point at your Worker and paste an editor/reviewer JWT. CORS must allow this origin (<code>CORS_ORIGINS</code>).

package/src/brand.ts

@@ -0,0 +1,96 @@
+// The deployment's wordmark, resolved once from the host's /config.js.
+//
+// Deliberately free of React, podoba and DOM-lib imports: it is read at module load (before
+// any component renders) and it is the one piece of chrome a host is expected to change, so
+// it stays a pure function of config that can be exercised without a browser.
+
+/** What the host may set under `window.PRAMEN_CMS_EDITOR.brand`. */
+export interface BrandConfig {
+  /** The wordmark. Blank/absent keeps the default. */
+  name?: string;
+  /** The muted half after the middot. Absent keeps the default; `null` drops it. */
+  suffix?: string | null;
+}
+
+/** A resolved wordmark. */
+export interface Brand {
+  name: string;
+  suffix: string | null;
+  /** Name and suffix joined for `document.title` — where the middot reads correctly. */
+  title: string;
+  /** The same words with no punctuation, for an accessible name. A screen reader announces
+   * "·" as "middle dot" at higher verbosity, so the decorative separator that belongs in a
+   * tab title does not belong in an aria-label. */
+  spoken: string;
+}
+
+export const DEFAULT_BRAND_NAME = "pramen";
+export const DEFAULT_BRAND_SUFFIX = "cms";
+
+/** Coerce one config value to a trimmed string, or undefined for anything else.
+ *
+ * /config.js is hand-edited, untyped, and often templated from an env var, so a value here
+ * can be any JSON type. `?.trim()` guards null and undefined ONLY — `suffix: false` (a
+ * plausible slip next to `hidePages: true`) or `name: 123` would THROW, and since `BRAND` is
+ * resolved at module load in the entry bundle's import graph, that throw aborts evaluation
+ * before `createRoot` and renders a blank page with nothing but a console error. Every other
+ * field in this config object already fails safe; this one must too. */
+function str(v: unknown): string | undefined {
+  if (typeof v !== "string") return undefined;
+  const trimmed = v.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** Resolve the configured wordmark, falling back to what used to be hardcoded.
+ *
+ * The distinction that matters is ABSENT vs. `null` on `suffix`: a host that only renames
+ * the product keeps the "· cms" half, while `suffix: null` is the explicit "just our name".
+ *
+ * A `brand` that is present but yields no usable name is WARNED about rather than silently
+ * accepted: `brand: "Acme"` (the shorthand instead of `{ name: "Acme" }`), a misspelled key,
+ * or a template that resolved to an empty string all end up shipping the framework's name to
+ * the client — the exact outcome this config exists to prevent — and a green deploy is the
+ * worst place to discover it. */
+export function resolveBrand(cfg?: BrandConfig): Brand {
+  const configured = str(cfg?.name);
+  if (cfg !== undefined && cfg !== null && configured === undefined) {
+    console.warn(
+      `pramen/cms-editor: \`brand\` is set but has no usable \`name\`, so the wordmark stays "${DEFAULT_BRAND_NAME}". Expected \`brand: { name: "Your name" }\`.`,
+    );
+  }
+  const name = configured ?? DEFAULT_BRAND_NAME;
+  // `undefined` (not configured) keeps the default; `null` — and any non-string — drops it.
+  const suffix = cfg?.suffix === undefined ? DEFAULT_BRAND_SUFFIX : (str(cfg.suffix) ?? null);
+  return { name, suffix, title: suffix ? `${name} · ${suffix}` : name, spoken: suffix ? `${name} ${suffix}` : name };
+}
+
+/** The global the host's /config.js writes. Declared structurally rather than reaching for
+ * `Window`, so this module needs no DOM lib — and so a test can hand it a plain object. */
+export interface BrandHost {
+  PRAMEN_CMS_EDITOR?: { brand?: BrandConfig };
+}
+
+/** Pull the brand config off a host global, tolerating its absence (SSR, tests, a /config.js
+ * that 404'd). Exported so the READ is testable, not just the resolution. */
+export function readBrandConfig(host: BrandHost | undefined): BrandConfig | undefined {
+  return host?.PRAMEN_CMS_EDITOR?.brand;
+}
+
+/** The wordmark for THIS page load. Read at module load, like `SIGN_IN_URL` — /config.js is
+ * a plain script tag ahead of the bundle, so it is already set. */
+export const BRAND: Brand = resolveBrand(readBrandConfig(globalThis as BrandHost));
+
+/** The two chrome strings built from the wordmark, in one place so the words that are NOT
+ * the client's name can be seen together — and so neither call site re-invents them.
+ *
+ * Both keep saying "editor" on the DEFAULT wordmark, because that is what the Setup screen
+ * and the browser tab have always said; a configured brand replaces the lot rather than
+ * having an English noun appended to it. */
+export const SETUP_TITLE: string = BRAND.suffix ? `· ${BRAND.suffix}${isDefault(BRAND) ? " editor" : ""}` : "";
+export const DOCUMENT_TITLE: string = isDefault(BRAND) ? `${BRAND.title} editor` : BRAND.title;
+
+/** Whether nothing was configured — the unbranded default, which must render exactly as it
+ * did before this module existed. */
+function isDefault(b: Brand): boolean {
+  return b.name === DEFAULT_BRAND_NAME && b.suffix === DEFAULT_BRAND_SUFFIX;
+}

package/src/components.tsx

@@ -7,13 +7,20 @@ import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } fro
 import { Api, ApiError } from "./api";
 import { CONTROL, FieldForm, formatWhen, fromLocalInput, slugify, toLocalInput } from "./fields";
 import type { Config } from "./api";
-import type { Me } from "./app-context";
+import { useApp, type Me } from "./app-context";
 import { isRichTextDoc, richTextToPlainText } from "./rich-text";
 import type { AssembledPage, AuditEntry, BlockType, CollectionMeta, ContentType, FieldDefinition, FieldValue, FieldValues, Media, Page, RegionDefinition, RenderedBlock } from "./types";
 
 export type InspectorTab = "settings" | "seo" | "workflow" | "i18n" | "audit";
 export const INSPECTOR_TABS: InspectorTab[] = ["settings", "seo", "workflow", "i18n", "audit"];
 
+/** The tabs a deployment actually shows. ONE definition, used by the tab bar, the panel
+ * switch and the route's deep-link fallback — three places that previously each re-derived
+ * "is i18n visible?" and could disagree. */
+export function visibleTabs(multilingual: boolean): InspectorTab[] {
+  return multilingual ? INSPECTOR_TABS : INSPECTOR_TABS.filter((t) => t !== "i18n");
+}
+
 // --- presentational primitives (podoba tokens; replaces styles.ts classes) ---
 
 const ROW = "flex items-center gap-3 rounded-[14px] border border-transparent bg-surface-card px-[18px] py-3.5";
@@ -102,6 +109,8 @@ const Dim = ({ children }: { children: ReactNode }) => <span className="text-fg-
 // --- pages list --------------------------------------------------------------
 
 export function PageList({ api, pages, blockTypes, onOpen, onCreated, onError }: { api: Api; pages: Page[]; blockTypes: BlockType[]; onOpen: (p: Page) => void; onCreated: () => void; onError: (s: string) => void }) {
+  // From the SERVER (listCmsCapabilities), not a local flag — see `CmsCapabilities`.
+  const { cms: { multilingual } } = useApp();
   const [creating, setCreating] = useState(false);
   return (
     <>
@@ -116,7 +125,7 @@ export function PageList({ api, pages, blockTypes, onOpen, onCreated, onError }:
             <div className={`${ROW} cursor-pointer hover:bg-surface-muted`} key={p.id} onClick={() => onOpen(p)}>
               <span className="flex-1 truncate font-medium">{p.title}</span>
               <span className="text-fg-subtle">/{p.slug}</span>
-              <span className="text-fg-subtle">{p.locale}</span>
+              {multilingual ? <span className="text-fg-subtle">{p.locale}</span> : null}
               <Pill status={p.status}>{p.status}</Pill>
             </div>
           ))}
@@ -538,6 +547,7 @@ export function CollectionEditor({ api, def, id, onSaved, onDeleted, onBack, onE
 // --- page editor -------------------------------------------------------------
 
 export function PageEditor({ api, page, blockTypes, tab, onTab, onBack, onChange, registerGuard }: { api: Api; page: Page; blockTypes: BlockType[]; tab: InspectorTab; onTab: (t: InspectorTab) => void; onBack: () => void; onChange: (p: Page) => void; registerGuard: (fn: (() => boolean) | null) => void }) {
+  const { cms: { multilingual } } = useApp();
   const [ct, setCt] = useState<ContentType | null>(null);
   const [assembled, setAssembled] = useState<AssembledPage | null>(null);
   const [err, setErr] = useState("");
@@ -776,14 +786,14 @@ export function PageEditor({ api, page, blockTypes, tab, onTab, onBack, onChange
 
       <div className="overflow-auto rounded-panel border border-border bg-surface-card p-5">
         <div className="mb-3 flex gap-1">
-          {INSPECTOR_TABS.map((t) => (
+          {visibleTabs(multilingual).map((t) => (
             <Button key={t} variant="ghost" size="sm" className={tab === t ? "bg-surface-muted text-fg" : "text-fg-muted"} onPress={() => onTab(t)}>{t}</Button>
           ))}
         </div>
         {tab === "settings" ? <PageMeta api={api} page={page} onSaved={onChange} onError={setErr} /> : null}
         {tab === "seo" ? <SeoPanel api={api} page={page} onError={setErr} /> : null}
         {tab === "workflow" ? <Workflow api={api} page={page} onChanged={(p) => { onChange(p); }} onError={setErr} /> : null}
-        {tab === "i18n" ? <I18n api={api} page={page} onError={setErr} /> : null}
+        {tab === "i18n" && multilingual ? <I18n api={api} page={page} onError={setErr} /> : null}
         {tab === "audit" ? <AuditLog api={api} pageId={page.id} onError={setErr} /> : null}
       </div>
     </div>
@@ -1044,6 +1054,7 @@ function Inserter({ allowed, btBySlug, onAdd, compact }: { allowed: string[]; bt
  * type has no regions look empty — a wide, blank canvas next to a cramped form.
  */
 function PageMeta({ api, page, onSaved, onError }: { api: Api; page: Page; onSaved: (p: Page) => void; onError: (s: string) => void }) {
+  const { cms: { multilingual, locales } } = useApp();
   const [title, setTitle] = useState(page.title);
   const [slug, setSlug] = useState(page.slug);
   const [locale, setLocale] = useState(page.locale);
@@ -1057,7 +1068,12 @@ function PageMeta({ api, page, onSaved, onError }: { api: Api; page: Page; onSav
     try {
       // Meta only — `fields` is deliberately omitted so saving here can never clobber
       // content edited in the canvas (updatePage patches only what it is given).
-      const r = await api.call<{ page?: Page }>("updatePage", { pageId: page.id, title, slug, locale });
+      // `locale` is sent ONLY where it is editable. On a single-locale deployment there is
+      // no control for it, so including it would blind-overwrite whatever the row holds
+      // with mount-time state — reverting an import or another editor's change through a
+      // field this user cannot see. `updatePage` treats an absent key as no-change.
+      const patch = multilingual ? { title, slug: slug.trim(), locale } : { title, slug: slug.trim() };
+      const r = await api.call<{ page?: Page }>("updatePage", { pageId: page.id, ...patch });
       if (r?.page) onSaved(r.page);
       setOk(true);
       setTimeout(() => setOk(false), 1500);
@@ -1074,7 +1090,18 @@ function PageMeta({ api, page, onSaved, onError }: { api: Api; page: Page; onSav
       {ok ? <Banner ok>saved</Banner> : null}
       <Input label="Title" value={title} onChange={setTitle} />
       <Input label="Slug" value={slug} onChange={setSlug} />
-      <Input label="Locale" value={locale} onChange={setLocale} />
+      {/* A SELECT over the declared locales, not free text: a typo'd or blank locale saves
+          fine, previews fine (the editor round-trips the same string) and then 404s on the
+          live site, which is the hardest kind of wrong to see. */}
+      {multilingual ? (
+        <label className="flex flex-col gap-1 text-sm">
+          <span className="font-medium text-fg">Locale</span>
+          <select className={CONTROL} value={locale} onChange={(e) => setLocale(e.target.value)}>
+            {locales.includes(locale) ? null : <option value={locale}>{locale || "(unset)"} — not a declared locale</option>}
+            {locales.map((l) => <option key={l} value={l}>{l}</option>)}
+          </select>
+        </label>
+      ) : null}
       <Button onPress={save} isDisabled={busy || !title.trim() || !slug.trim()}>{busy ? "Saving…" : "Save"}</Button>
       <KV><span>Status</span><span>{page.status}</span></KV>
     </div>

package/src/main.tsx

@@ -3,10 +3,20 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { pageRegistry, routes } from "virtual:buzola/routes";
 import { AppProvider } from "./app-context";
+import { DOCUMENT_TITLE } from "./brand";
 
 // Styling is podoba: @podoba/tokens/variables.css + the compiled Tailwind (podoba
 // preset) are <link>ed by index.html (see scripts/build.ts). No more inline CSS.
 
+// The <title> in index.html is baked at build time, before any host config exists, so it
+// can only be the default. Re-apply the configured wordmark once /config.js has been read —
+// the static tag stays the pre-hydration fallback.
+//
+// `DOCUMENT_TITLE`, not `${BRAND.title} editor`: appending a fixed English noun to the one
+// string this feature exists to hand over would put a foreign word in a rebranded client's
+// tab, and `suffix: null` ("just our name") could never drop it.
+document.title = DOCUMENT_TITLE;
+
 const el = document.getElementById("app");
 if (el)
   createRoot(el).render(

package/src/routes/_layout.tsx

@@ -6,6 +6,7 @@ import { Outlet, useNavigate, useRoute } from "@buzola/router";
 import { Button, Card, MoonIcon, SunIcon, Text, Topbar } from "@podoba/react";
 import { useEffect, useState } from "react";
 import { useApp } from "../app-context";
+import { BRAND } from "../brand";
 
 const THEME_KEY = "pramen.cms.theme";
 
@@ -57,11 +58,11 @@ export default function RootLayout() {
           <button
             type="button"
             onClick={guarded(() => navigate("home"))}
-            aria-label="pramen cms — home"
+            aria-label={`${BRAND.spoken} — home`}
             className="flex items-baseline gap-1 rounded-md px-1 py-0.5 transition-colors hover:bg-surface-muted"
           >
-            <span className="text-callout font-bold tracking-[0.01em] text-fg">pramen</span>
-            <span className="text-fg-subtle">· cms</span>
+            <span className="text-callout font-bold tracking-[0.01em] text-fg">{BRAND.name}</span>
+            {BRAND.suffix ? <span className="text-fg-subtle">· {BRAND.suffix}</span> : null}
           </button>
         </Topbar.Brand>
         <Topbar.Nav aria-label="Primary">
@@ -89,8 +90,14 @@ export default function RootLayout() {
           </Button>
           {extraNav.map((l) => (
             // Companion tools live OUTSIDE this SPA (a separate static page/worker route), so
-            // open them in a new tab. A same-tab click would be caught by the client router
-            // (Navigation API) and fall to the in-app 404, since the path isn't an SPA route.
+            // open them in a new tab. NOT a style choice, and `target: "_self"` alone would not
+            // fix it: `_404.tsx` registers the catch-all `/:__notFound+`, so buzola matches
+            // EVERY same-origin path and intercepts it — a same-tab click and `location.assign`
+            // both land on the in-app 404 (verified). Only a cross-origin url escapes on its own.
+            //
+            // The supported same-tab route is `router.leaveApp(href)` (@buzola/router >= 0.0.16),
+            // which releases one navigation to the browser. This package still pins ^0.0.12, so
+            // adopting it is a version bump plus a `target` option on the config item.
             <a
               key={l.href}
               href={l.href}

package/src/routes/page.tsx

@@ -6,14 +6,14 @@ import { createPage, useNavigate } from "@buzola/router";
 import { Button } from "@podoba/react";
 import { useEffect, useState } from "react";
 import { useApp } from "../app-context";
-import { INSPECTOR_TABS, PageEditor, errMsg, type InspectorTab } from "../components";
+import { PageEditor, errMsg, visibleTabs, type InspectorTab } from "../components";
 import type { BlockType, Page } from "../types";
 
 export default createPage()
   .params({ pageId: "string", tab: "?string" })
   .route("/pages/:pageId")
   .render(function PageEditorRoute({ params }) {
-    const { api, setError, setNavGuard } = useApp();
+    const { api, cms, setError, setNavGuard } = useApp();
     const navigate = useNavigate();
     const [page, setPage] = useState<Page | null>(null);
     const [blockTypes, setBlockTypes] = useState<BlockType[]>([]);
@@ -35,8 +35,17 @@ export default createPage()
       return () => { live = false; };
     }, [api, params.pageId, setError]);
 
-    const tab: InspectorTab = INSPECTOR_TABS.includes(params.tab as InspectorTab) ? (params.tab as InspectorTab) : "settings";
+    // The visible set comes from the server (`visibleTabs`), so a deep link to `?tab=i18n`
+    // on a single-locale deployment falls back to settings — and the URL is REWRITTEN to
+    // match. Rendering one tab under another tab's address means a refresh, a Back, or a
+    // shared link all disagree with what is on screen; `setTab` already replaces without
+    // adding a history entry, so reconciling costs nothing.
+    const shown = visibleTabs(cms.multilingual);
+    const tab: InspectorTab = shown.includes(params.tab as InspectorTab) ? (params.tab as InspectorTab) : "settings";
     const setTab = (t: InspectorTab) => navigate("page", { params: { pageId: params.pageId, tab: t }, replace: true });
+    useEffect(() => {
+      if (params.tab !== undefined && params.tab !== tab) setTab(tab);
+    }, [params.tab, tab]);
 
     if (missing) {
       return (

package/src/types.ts

@@ -134,6 +134,25 @@ export interface CollectionMeta {
   supports?: CollectionFeature[];
 }
 
+/** What the server says this deployment supports (mirror of `listCmsCapabilities`).
+ *
+ * Server-declared, like a collection's `supports: [...]`: the editor asks what exists
+ * rather than being configured to hide things locally, so the chrome and the data cannot
+ * disagree. `multilingual` is the derived answer to the question the UI actually asks. */
+export interface CmsCapabilities {
+  /** Declared locales, most-preferred first. */
+  locales: string[];
+  /** The locale a page gets when created without one — `locales[0]`. */
+  defaultLocale: string;
+  /** More than one declared locale. Gates the whole i18n surface. */
+  multilingual: boolean;
+}
+
+/** Used until `listCmsCapabilities` answers, and when it cannot (an older server). Assumes
+ * MONOLINGUAL: a hidden i18n surface on a multilingual site is recoverable by reloading,
+ * where a half-rendered one on a single-locale site is what this replaced. */
+export const DEFAULT_CAPABILITIES: CmsCapabilities = { locales: ["en"], defaultLocale: "en", multilingual: false };
+
 /** Mirror of @pramen/cms `CollectionFeature`. */
 export type CollectionFeature = "drafts" | "scheduling" | "revisions" | "preview";