@pramen/cms-editor 0.0.59 → 0.0.60

package/src/types.ts

@@ -58,6 +58,9 @@ export type FieldType =
   | "slug"
   | "media"
   | "select"
+  /** A pointer to a record that is not this row — a pramen row or an external record.
+   * Stored as an opaque id; resolved through `referenceFrom`. */
+  | "reference"
   | "repeater"
   | "group";
 
@@ -77,6 +80,27 @@ export interface FieldDefinition {
   optionsFrom?: string;
   /** For `slug`: the sibling field this one is derived from (e.g. `"title"`). */
   from?: string;
+  /** For `reference`: the query handler that resolves it. Called `{ search?, limit, offset }`
+   * to browse and `{ ids }` to resolve labels for stored values; returns
+   * {@link ReferenceResult} either way. */
+  referenceFrom?: string;
+  /** For `reference`: store a list of ids rather than one. */
+  multiple?: boolean;
+}
+
+/** One option a `reference` field's handler returns. */
+export interface ReferenceOption {
+  value: string;
+  label: string;
+  /** Secondary text under the label — a date, an owner, a status. A picker over a thousand
+   * records usually needs more than a name to tell two rows apart. */
+  hint?: string;
+}
+
+/** What a `reference` field's handler returns, for both request shapes. */
+export interface ReferenceResult {
+  items: ReferenceOption[];
+  hasMore?: boolean;
 }
 
 export interface RegionDefinition {
@@ -99,6 +123,13 @@ export interface BlockType {
   fieldsSchema?: FieldDefinition[] | null;
   icon?: string | null;
   category?: string | null;
+  /** The `cmsBootstrap` owner that declares this type in the app's code, or null/absent when
+   * an editor authored it. The builder renders an owned type read-only: a save would 409, and
+   * before it did, it would have been quietly reverted at the next cold start.
+   *
+   * Only meaningful when `CmsCapabilities.codeDefinedTypes` is true — an older server sends
+   * no owner for any row, which is indistinguishable from "nothing is code-defined". */
+  managedBy?: string | null;
 }
 
 export interface ContentType {
@@ -108,6 +139,8 @@ export interface ContentType {
   regions?: RegionDefinition[] | null;
   fieldsSchema?: FieldDefinition[] | null;
   defaultBlocks?: DefaultBlockDefinition[] | null;
+  /** See `BlockType.managedBy`. */
+  managedBy?: string | null;
 }
 
 /** A collection: one of the host app's own pramen entities, edited generically via a
@@ -119,6 +152,11 @@ export interface CollectionMeta {
   label: string;
   pluralLabel: string;
   icon?: string;
+  /** Where this collection sits in the primary nav — see {@link NAV_ORDER}. Filled in
+   * server-side, so the editor sorts one list of numbers. Optional here only because an
+   * OLDER server does not send it; `NAV_ORDER.collections` is the fallback, which is
+   * exactly where collections rendered before the key existed. */
+  navOrder?: number;
   fields: FieldDefinition[];
   list: string[];
   titleField: string;
@@ -152,12 +190,66 @@ export interface CmsCapabilities {
    * without this probe the editor renders N tabs that all show every type's pages under a
    * heading claiming otherwise, and "New page" from any of them stamps that tab's type. */
   pagesByType: boolean;
+  /** The server has the site-furniture handlers (menus, redirects, taxonomies, widget
+   * areas). Declared, not probed: an older server answers `listMenus` with a 404 like any
+   * unknown handler, and a nav section whose every screen fails is worse than no section. */
+  siteFurniture: boolean;
+  /** The server stamps `managedBy` on the types `cmsBootstrap` declares, and refuses to
+   * update one. Declared rather than inferred from the rows: this package has no dependency
+   * on `@pramen/cms`, so a NEWER editor can run against an older server — where every row
+   * reports no owner, which reads identically to "no type is code-defined". Trusting the row
+   * there means the builder offers a save the server accepts and the next cold start
+   * reverts, i.e. GitHub #48 in the deployment that upgraded the editor to fix it. */
+  codeDefinedTypes: boolean;
+  /** Whether THIS caller may author, i.e. holds one of the deployment's `editorRoles`.
+   *
+   * Per-caller, unlike the rest of this probe. The read handlers are open to
+   * `editorRoles ∪ reviewerRoles` but every write is editor-only, and the editor cannot
+   * derive that: it knows the caller's roles from `me` but not which roles the deployment
+   * configured. Without it a reviewer-only session gets the authoring nav and every screen
+   * 403s on its first save. */
+  canEdit: boolean;
 }
 
+/**
+ * Where each built-in section sits in the primary nav — the editor's mirror of
+ * `NAV_ORDER` in @pramen/cms.
+ *
+ * A mirror, not an import: the editor is a standalone browser app that speaks to the CMS
+ * purely over HTTP and has no server-package dependency (see the note at the top of this
+ * file). The numbers are ordinals spaced 100 apart; only their relative order is contract.
+ */
+export const NAV_ORDER = {
+  pages: 100,
+  collections: 200,
+  media: 300,
+  menus: 400,
+  taxonomies: 500,
+  widgets: 600,
+  redirects: 700,
+  adminPages: 800,
+  types: 900,
+  users: 1000,
+  settings: 1100,
+  extra: 1200,
+} as const;
+
 /** 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, pagesByType: false };
+export const DEFAULT_CAPABILITIES: CmsCapabilities = {
+  locales: ["en"],
+  defaultLocale: "en",
+  multilingual: false,
+  pagesByType: false,
+  siteFurniture: false,
+  codeDefinedTypes: 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
+  // boundary either way — this only decides what is drawn.
+  canEdit: true,
+};
 
 /** Mirror of @pramen/cms `CollectionFeature`. */
 export type CollectionFeature = "drafts" | "scheduling" | "revisions" | "preview";
@@ -223,3 +315,147 @@ export interface AuditEntry {
   note: string | null;
   createdAt: string;
 }
+
+// --- site furniture (mirrors of the @pramen/cms shapes) ----------------------
+
+/** What a menu item points at. `custom` is a literal href; the rest are references the
+ * server resolves at read time, so a link follows its page instead of freezing a slug. */
+export type MenuItemKind = "custom" | "page" | "term" | "collection";
+
+export interface MenuItem {
+  id: string;
+  label: string;
+  kind?: MenuItemKind;
+  /** `page`: a page id · `term`: a term id · `collection`: a collection slug. */
+  ref?: string | null;
+  /** `custom`: the href as authored. Filled in by `getMenu` for the resolved kinds. */
+  url?: string;
+  target?: string;
+  titleAttr?: string;
+  cssClasses?: string;
+  children?: MenuItem[];
+}
+
+export interface Menu {
+  id: string;
+  name: string;
+  label: string;
+  items?: MenuItem[] | null;
+  /** Optimistic-concurrency counter — send it back as `expectedVersion` so a second
+   * editor's whole-tree overwrite is a 409 rather than a silent replacement. */
+  version?: number;
+}
+
+/** Mirror of `MAX_MENU_DEPTH` in @pramen/cms — the editor refuses to nest deeper rather
+ * than letting a save fail on the server with the tree already reordered on screen. */
+export const MAX_MENU_DEPTH = 5;
+
+export interface Redirect {
+  id: string;
+  fromPath: string;
+  toPath: string;
+  status: number;
+  enabled: boolean;
+  note?: string | null;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/** Mirror of `REDIRECT_STATUSES` in @pramen/cms. */
+export const REDIRECT_STATUSES = [301, 302, 307, 308] as const;
+
+export interface Taxonomy {
+  id: string;
+  slug: string;
+  label: string;
+  pluralLabel?: string | null;
+  description?: string | null;
+  hierarchical?: boolean;
+}
+
+export interface Term {
+  id: string;
+  taxonomyId: string;
+  slug: string;
+  label: string;
+  description?: string | null;
+  parentId?: string | null;
+  position?: number;
+  children?: Term[];
+}
+
+export type WidgetType = "content" | "menu" | "component";
+
+export interface Widget {
+  id: string;
+  type: WidgetType;
+  title?: string | null;
+  content?: RichTextDoc;
+  menuName?: string;
+  componentId?: string;
+  componentProps?: FieldValues;
+}
+
+export interface WidgetArea {
+  id: string;
+  name: string;
+  label: string;
+  description?: string | null;
+  widgets?: Widget[] | null;
+  /** See {@link Menu.version}. */
+  version?: number;
+}
+
+// --- Block Kit: custom admin pages (mirrors @pramen/cms `./blockkit`) ----------------
+
+/** An input a Block Kit form or actions row can carry. */
+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 }
+  /** 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 };
+
+export interface AdminButton {
+  type: "button";
+  action_id: string;
+  label: string;
+  style?: "primary" | "secondary" | "danger";
+  value?: string;
+  /** Ask before firing. A page has no code in the browser, so it cannot put up its own. */
+  confirm?: string;
+}
+
+export type AdminElement = AdminButton | AdminInput;
+
+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: "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 } }
+  | { type: "image"; url: string; alt?: string; caption?: string }
+  | { type: "columns"; columns: AdminBlock[][] }
+  | { type: "empty"; text: string; hint?: string }
+  | { type: "accordion"; title: string; blocks: AdminBlock[]; open?: boolean };
+
+/** What a Block Kit page answers with. The WHOLE page comes back on every interaction. */
+export interface AdminPageResponse {
+  blocks: AdminBlock[];
+  toast?: { text: string; tone?: "info" | "success" | "error" };
+}
+
+/** 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 {
+  slug: string;
+  label: string;
+  icon?: string;
+  navOrder?: number;
+}