@pramen/cms-editor 0.0.63 → 0.0.64

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

@@ -431,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";
@@ -453,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 } }
@@ -474,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 {
@@ -481,6 +505,16 @@ 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 -----------------------------------------------------------