@pramen/cms-editor 0.0.61 → 0.0.64

package/src/routes/admin-page.tsx

@@ -1,14 +1,26 @@
-// A custom admin page (`/apps/:slug`) — Block Kit, rendered inside the editor's own chrome.
+// A project's own screen (`/apps/:slug`), rendered inside the editor's own chrome.
 //
 // Routed BY THE EDITOR, which is the point: an `extraNav` link has to open a new tab,
 // because `_404.tsx` registers the catch-all `/:__notFound+` and a same-tab click on an
-// unmounted editor lands on the in-app 404. A registered page has a real route, so it is
+// unmounted editor lands on the in-app 404. A registered screen has a real route, so it is
 // part of the admin rather than a link out of it.
+//
+// ONE route for two kinds. A Block Kit page (`adminPage()`) is described as JSON by the
+// server and rendered here; a panel (`adminPanel()`) is a React component the deployment's
+// own bundle registered. They share this route because they share everything a URL and a nav
+// entry are made of — the slug space, the role filter, the "Apps" band, the breadcrumb — and
+// differ only in where the rendering happens. Splitting them would have meant a second
+// route, a second nav band and a slug that could mean two things.
 
-import { createPage, useNavigate } from "@buzola/router";
+import { createPage, useNavigate, useRouter } from "@buzola/router";
+import { useMemo, useSyncExternalStore } from "react";
 import { useApp } from "../app-context";
 import { AdminPageView } from "../blockkit";
 import { Notice } from "../components";
+import { PanelBoundary } from "../panel-boundary";
+import { getPanel, panelRefusal, panelsSettled, panelsVersion, subscribePanels, type PanelProps } from "../panels";
+import { useTheme } from "../theme";
+import { adminPageKind } from "../types";
 import { Button } from "@podoba/react";
 
 export default createPage()
@@ -29,8 +41,70 @@ export default createPage()
         </Notice>
       );
     }
+    if (adminPageKind(def) === "panel") return <PanelRoute slug={def.slug} />;
     // Keyed on the slug so switching between two pages REMOUNTS the view: buzola renders the
     // same component instance across a params-only change, and the blocks, the form values
     // and any toast all belong to one page.
     return <AdminPageView api={api} key={def.slug} slug={def.slug} label={def.label} onError={setError} />;
   });
+
+/**
+ * A panel: the component the deployment's own bundle registered for this slug.
+ *
+ * The registry is external state that changes without React knowing — bundles are imported
+ * from `main.tsx` and register whenever they land — so it is read through
+ * `useSyncExternalStore` rather than an effect. That is what makes a deep link to a panel
+ * work: the route can mount before the bundle has finished loading, and re-renders when it
+ * has, instead of deciding once and being wrong forever.
+ */
+function PanelRoute({ slug }: { slug: string }) {
+  const { api, setError } = useApp();
+  const theme = useTheme();
+  const basePath = useRouter().basePath;
+  const version = useSyncExternalStore(subscribePanels, panelsVersion, panelsVersion);
+  // `version` is the snapshot, not the value — a stable number is what a store hook needs,
+  // and the lookup is what the render actually wants. Depending on it is the point.
+  const panel = useMemo(() => getPanel(slug), [slug, version]);
+
+  if (!panel) {
+    // Three different situations, and only the first is a spinner.
+    //
+    // A REFUSAL comes first because it is the one the generic message would actively mislead
+    // about: the bundle is listed, it loaded, it ran, and it called `registerPanel` — telling
+    // the reader to go and check those four things sends them past the actual answer. The
+    // registry already holds a sentence naming the slug and the fix (a contract built against
+    // a different editor, a `render` that is not a component), so it is shown verbatim.
+    //
+    // Otherwise: the server listed this panel (it is in `adminPages`, so the caller may open
+    // it), which means the bundle either has not landed yet or landed and never registered
+    // this slug. The last is a deployment mistake — a missing `panels` entry, a bundle built
+    // without the `registerPanel` call, a slug typo between `app.ts` and the bundle — and it
+    // is one nobody can diagnose from a spinner.
+    //
+    // Read during render, not through a second store: a refusal calls the same `notify` a
+    // registration does, so `version` above is already the subscription that brings this
+    // component back when one is recorded.
+    const refused = panelRefusal(slug);
+    return (
+      <Notice>
+        {refused ??
+          (panelsSettled()
+            ? `No panel is registered for '${slug}'. Check that this deployment's panel bundle is listed in the admin's \`panels\` config and calls registerPanel({ slug: "${slug}", … }).`
+            : "Loading…")}
+      </Notice>
+    );
+  }
+
+  const props: PanelProps = { api, basePath, theme, setError };
+  // Keyed on the slug for the same reason a Block Kit page is: buzola keeps one component
+  // instance across a params-only change, and a panel's state belongs to its own screen.
+  //
+  // Wrapped, because this is someone else's component in our tree: React unmounts the whole
+  // root on an uncaught render error, so without the boundary one bad panel does not break a
+  // screen, it blanks the admin — no sidebar, and no way off the route that is failing.
+  return (
+    <PanelBoundary key={slug} slug={slug}>
+      <panel.render {...props} />
+    </PanelBoundary>
+  );
+}

package/src/routes/page.tsx

@@ -73,6 +73,10 @@ export default createPage()
         tab={tab}
         onTab={setTab}
         onBack={backToList}
+        // Named for where it actually goes. On a per-type deployment `backToList` lands in
+        // this page's OWN type list, and a button labelled "Pages" then named a pooled list
+        // that deployment does not have.
+        backLabel={splitsByType(contentTypes, cms) && ownType ? ownType.name : "Pages"}
         onChange={setPage}
         registerGuard={setNavGuard}
       />

package/src/theme.ts

@@ -0,0 +1,80 @@
+// The chrome's light/dark choice, as a store rather than a component's state.
+//
+// It used to be a `useState` inside `_layout.tsx`, which was fine while the layout was the
+// only reader. It is not the only reader any more: a panel (a project's own React screen —
+// see `panels.ts`) is handed the theme, and it is rendered through `<Outlet />` under that
+// same layout. Threading it down as a prop would mean every route the layout renders had to
+// carry a value only one of them wants; a second `useState` would mean two sources of truth
+// for one document attribute, drifting the moment either is set.
+//
+// A store instead: one value, one place that writes the DOM attribute and localStorage, and
+// a `useSyncExternalStore` hook for anyone who wants to re-render on a change. It is also
+// what lets `main.tsx` apply the stored theme BEFORE the first paint, which the layout's
+// effect could not do — an editor left in dark mode used to flash white on every load.
+
+import { useSyncExternalStore } from "react";
+
+export type Theme = "light" | "dark";
+
+/** Per-browser, like the folded nav groups: a reading preference, not deployment
+ * configuration, so nothing server-side carries it. */
+const THEME_KEY = "pramen.cms.theme";
+
+let current: Theme = "light";
+const listeners = new Set<() => void>();
+
+/** Read the stored choice, tolerating every shape localStorage can be in (absent, another
+ * version's value, hand-edited, a private window that throws on access). Anything that is
+ * not exactly `"dark"` is light, which is the default the editor has always had. */
+function stored(): Theme {
+  try {
+    return localStorage.getItem(THEME_KEY) === "dark" ? "dark" : "light";
+  } catch {
+    return "light";
+  }
+}
+
+/** Put the choice where podoba can see it. The tokens flip under `[data-theme="dark"]` on
+ * the document root — there are no `dark:` variants to toggle — so this one attribute is the
+ * whole of "apply the theme". */
+function apply(theme: Theme): void {
+  if (typeof document !== "undefined") document.documentElement.dataset.theme = theme;
+}
+
+/** Adopt the stored choice and paint it. Called once, from `main.tsx`, before `createRoot`. */
+export function initTheme(): void {
+  current = stored();
+  apply(current);
+}
+
+export function getTheme(): Theme {
+  return current;
+}
+
+export function setTheme(theme: Theme): void {
+  if (theme === current) return;
+  current = theme;
+  apply(theme);
+  try {
+    localStorage.setItem(THEME_KEY, theme);
+  } catch {
+    // A private window that refuses writes costs the memory of the choice, nothing else.
+  }
+  for (const listener of [...listeners]) listener();
+}
+
+export function subscribeTheme(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** The current theme, re-rendering the caller when it changes. */
+export function useTheme(): Theme {
+  return useSyncExternalStore(subscribeTheme, getTheme, getTheme);
+}
+
+/** Drop every listener and return to the default. Tests only — the store is module state. */
+export function resetTheme(): void {
+  listeners.clear();
+  current = "light";
+}

package/src/types.ts

@@ -209,6 +209,11 @@ export interface CmsCapabilities {
    * configured. Without it a reviewer-only session gets the authoring nav and every screen
    * 403s on its first save. */
   canEdit: boolean;
+  /** The server has `listMediaTerms`/`setMediaTerms`, and `listMedia` understands `term`.
+   * Declared like `siteFurniture`: on an older server the detail panel's Tags section would
+   * 404 the moment a file is opened, and the library's tag filter would send an argument
+   * that is silently ignored — a control that visibly does nothing. */
+  mediaTerms: boolean;
 }
 
 /**
@@ -244,6 +249,7 @@ export const DEFAULT_CAPABILITIES: CmsCapabilities = {
   pagesByType: false,
   siteFurniture: false,
   codeDefinedTypes: false,
+  mediaTerms: false,
   // Fails OPEN, unlike its neighbours. An older server sends no `canEdit`, and hiding
   // every authoring control from a real editor is unrecoverable from inside the editor;
   // showing one that 403s is a legible error with a way forward. The server is the
@@ -371,8 +377,25 @@ export interface Taxonomy {
   pluralLabel?: string | null;
   description?: string | null;
   hierarchical?: boolean;
+  /** What this vocabulary classifies. `null`/absent means EVERYTHING — a vocabulary that was
+   * never narrowed, and the reading for a row written before the column existed. */
+  appliesTo?: TaxonomyTarget[] | null;
 }
 
+/** Mirror of @pramen/cms `TAXONOMY_TARGETS` — the object types a vocabulary can classify.
+ * Mirrored rather than imported for the reason at the top of this file: the editor is a
+ * standalone browser app with no server-package dependency. The server is the authority; an
+ * unknown value here would just render an unchecked box it refuses to save. */
+export const TAXONOMY_TARGETS = ["page", "media"] as const;
+export type TaxonomyTarget = (typeof TAXONOMY_TARGETS)[number];
+
+/** What each target is called on screen — plural, because each names the SET of things the
+ * vocabulary would classify. */
+export const TAXONOMY_TARGET_LABELS = {
+  page: "Pages",
+  media: "Media",
+} satisfies Record<TaxonomyTarget, string>;
+
 export interface Term {
   id: string;
   taxonomyId: string;
@@ -408,15 +431,19 @@ export interface WidgetArea {
 
 // --- Block Kit: custom admin pages (mirrors @pramen/cms `./blockkit`) ----------------
 
-/** An input a Block Kit form or actions row can carry. */
+/** An input a Block Kit form, actions row or table cell can carry.
+ *
+ * `error` is the per-FIELD failure, drawn under the input it belongs to. It is part of the
+ * render, not client state: the whole page comes back on every interaction, so an error
+ * lasts exactly as long as the response that carried it. */
 export type AdminInput =
-  | { type: "text_input"; action_id: string; label?: string; placeholder?: string; initial_value?: string; multiline?: boolean; required?: boolean }
-  | { type: "number_input"; action_id: string; label?: string; placeholder?: string; initial_value?: number; min?: number; max?: number; required?: boolean }
-  | { type: "select"; action_id: string; label?: string; options: { value: string; label: string }[]; initial_value?: string; required?: boolean }
-  | { type: "toggle"; action_id: string; label?: string; initial_value?: boolean }
+  | { type: "text_input"; action_id: string; label?: string; placeholder?: string; initial_value?: string; multiline?: boolean; required?: boolean; error?: string }
+  | { type: "number_input"; action_id: string; label?: string; placeholder?: string; initial_value?: number; min?: number; max?: number; required?: boolean; error?: string }
+  | { type: "select"; action_id: string; label?: string; options: { value: string; label: string }[]; initial_value?: string; required?: boolean; error?: string }
+  | { type: "toggle"; action_id: string; label?: string; initial_value?: boolean; error?: string }
   /** Write-only: deliberately has NO `initial_value`, so a stored secret is never echoed
    * back into the admin's DOM. */
-  | { type: "secret_input"; action_id: string; label?: string; placeholder?: string; required?: boolean };
+  | { type: "secret_input"; action_id: string; label?: string; placeholder?: string; required?: boolean; error?: string };
 
 export interface AdminButton {
   type: "button";
@@ -430,13 +457,24 @@ export interface AdminButton {
 
 export type AdminElement = AdminButton | AdminInput;
 
+/** Every `AdminElement` tag, as a runtime set — the editor needs it to decide whether a
+ * table cell draws as text or as a control. Mirrors `@pramen/cms`; the two are asserted
+ * equal in `test/cms-editor-mirrors.test.ts`, because a tag missing here renders a live
+ * control as `[object Object]`. */
+export const ADMIN_ELEMENT_TYPES = ["button", "text_input", "number_input", "select", "toggle", "secret_input"] as const;
+
+/** What one table cell holds: a value to READ, or an element to ACT with. Told apart by
+ * shape — a display value is a primitive, an element is an object. The server refuses any
+ * other object on the way out. */
+export type AdminCell = string | number | boolean | null | AdminElement;
+
 export type AdminBlock =
   | { type: "header"; text: string; level?: 1 | 2 | 3 }
   | { type: "section"; text: string }
   | { type: "divider" }
   | { type: "context"; text: string }
   | { type: "fields"; fields: { label: string; value: string }[] }
-  | { type: "table"; columns: { key: string; label: string }[]; rows: Record<string, string | number | boolean | null>[]; empty?: string }
+  | { type: "table"; block_id?: string; columns: { key: string; label: string }[]; rows: Record<string, AdminCell>[]; empty?: string }
   | { type: "stats"; stats: { label: string; value: string; hint?: string }[] }
   | { type: "actions"; block_id?: string; elements: AdminElement[] }
   | { type: "form"; block_id: string; fields: AdminInput[]; submit: { label: string; action_id: string } }
@@ -451,6 +489,15 @@ export interface AdminPageResponse {
   toast?: { text: string; tone?: "info" | "success" | "error" };
 }
 
+/** How a registered admin screen draws. Mirror of `ADMIN_PAGE_KINDS` in @pramen/cms.
+ *
+ * `"blocks"` is Block Kit — the server describes the page as JSON and the editor renders it.
+ * `"panel"` is a React component the deployment's own panel bundle registered under the
+ * same slug (see `panels.ts`); the server still owns the entry, so the role filter, the
+ * label, the icon and the position are the same server facts for both. */
+export const ADMIN_PAGE_KINDS = ["blocks", "panel"] as const;
+export type AdminPageKind = (typeof ADMIN_PAGE_KINDS)[number];
+
 /** A custom admin page, as the editor sees it (from `listAdminPages`) — never the render
  * function, and never the role list. A page the caller may not open is simply absent. */
 export interface AdminPageMeta {
@@ -458,4 +505,53 @@ export interface AdminPageMeta {
   label: string;
   icon?: string;
   navOrder?: number;
+  /** Absent ⇒ `"blocks"`, which is what every entry was before panels existed and what an
+   * older server still sends. Read through {@link adminPageKind} rather than directly, so
+   * the default lives in one place and an unrecognised kind from a NEWER server degrades to
+   * a Block Kit page (which renders a legible server error) instead of a blank screen. */
+  kind?: string;
 }
+
+/** The kind an entry actually is, defaulted and validated. */
+export function adminPageKind(meta: AdminPageMeta): AdminPageKind {
+  return (ADMIN_PAGE_KINDS as readonly string[]).includes(meta.kind ?? "") ? (meta.kind as AdminPageKind) : "blocks";
+}
+
+// --- media sorting and filtering -----------------------------------------------------------
+//
+// Mirrors of the vocabularies `listMedia` accepts in @pramen/cms. Mirrored rather than
+// imported for the reason at the top of this file — the editor is a standalone browser app
+// with no server-package dependency — and checked against the originals in
+// `test/cms-editor-mirrors.test.ts`, because a duplicate nobody verifies is a latent bug with
+// a comment on it.
+//
+// The server treats an unrecognised value as absent, so a drift here degrades to the default
+// order rather than to an error. That is the failure worth having, and it is still a failure:
+// a sort the editor offers and the server drops is a control that silently does nothing.
+
+/** How the media library may be ordered. */
+export const MEDIA_SORTS = ["newest", "oldest", "name", "name_desc", "largest", "smallest"] as const;
+export type MediaSort = (typeof MEDIA_SORTS)[number];
+
+/** What each sort is called on screen. */
+export const MEDIA_SORT_LABELS = {
+  newest: "Newest first",
+  oldest: "Oldest first",
+  name: "Name A–Z",
+  name_desc: "Name Z–A",
+  largest: "Largest first",
+  smallest: "Smallest first",
+} satisfies Record<MediaSort, string>;
+
+/** The coarse type buckets the library filters by. */
+export const MEDIA_KINDS = ["image", "video", "audio", "document", "other"] as const;
+export type MediaKind = (typeof MEDIA_KINDS)[number];
+
+/** …and their labels. Plural, because each names a SET the filter narrows to. */
+export const MEDIA_KIND_LABELS = {
+  image: "Images",
+  video: "Video",
+  audio: "Audio",
+  document: "Documents",
+  other: "Other",
+} satisfies Record<MediaKind, string>;