@pramen/cms 0.0.50 → 0.0.51

package/README.md

@@ -467,6 +467,28 @@ index is what turns a concurrent duplicate into a visible failure instead of a s
 ambiguous history. For the same reason the delete-and-purge pair is atomic on the DO but not
 on D1.
 
+### Locales
+
+A deployment declares the locales it publishes in, and the editor renders its i18n surface
+off that — the Translations panel, the Locale field, the per-row locale column:
+
+```ts
+const handlers = { ...createCmsHandlers({ locales: ["cs", "en"] }), ... };
+```
+
+One locale (or none declared) means monolingual: no i18n chrome anywhere, and the editor
+stops sending `locale` on a page save at all, so nothing can blind-overwrite a field it no
+longer shows. The FIRST entry is the locale a page is stamped with when created without
+one — derived, not a second `defaultLocale` option, because two settings that can disagree
+about the same fact is how a Czech-only site ends up publishing `en`.
+
+Declared, not inferred from the data: the only way to create a second locale is
+`createTranslation`, which the editor exposes from inside the Translations panel — so a rule
+like "show i18n once a second locale exists" would mean a monolingual site could never
+become multilingual. `listCmsCapabilities` is what the editor reads; `listLocales` remains a
+DATA query (which locales are actually authored), and the two differ while a locale is
+declared but not yet used.
+
 ## Limitations
 
 - **Block `fields` are opaque JSON**, so pramen's row/cell-level ACL and relational queries

package/dist/index.d.ts

@@ -791,8 +791,19 @@ export interface CmsHandlerOpts {
     editorRoles?: readonly string[];
     /** Max accepted media upload size in bytes (enforced at the Worker). Default 25 MB. */
     mediaMaxSize?: number;
-    /** Default locale used when `getPage`/`createPage` omit one. Default `"en"`. */
-    defaultLocale?: string;
+    /** The locales this deployment publishes in, most-preferred first. Default `["en"]`.
+     *
+     * DECLARED, not inferred. The editor renders its i18n surface — the Translations panel,
+     * the Locale field, the per-row locale column — only when there is more than one, and
+     * `listCmsCapabilities` is how it finds out. Inferring "is this site multilingual?" from
+     * the locales PRESENT IN DATA cannot work: the only way to create a second locale is
+     * `createTranslation`, which the editor exposes from inside the very panel that would
+     * stay hidden, so a monolingual site could never become multilingual.
+     *
+     * The first entry is the default stamped on a page created without one, which is why
+     * `defaultLocale` is derived from this rather than configured beside it — two options
+     * that can disagree about the same fact is how a Czech-only site ends up stamping "en". */
+    locales?: readonly string[];
     /** Roles permitted to approve/reject a page in review and publish (the editorial gate).
      * Default `["reviewer", "admin"]`. */
     reviewerRoles?: readonly string[];
@@ -960,7 +971,21 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         title: string;
         status: string;
     }[]>;
-    /** Distinct locales present across all pages. */
+    /** What this deployment supports, for an editor to render against — the pages-side
+     * counterpart to `listCollections`' `supports: [...]`.
+     *
+     * The editor asks the SERVER what exists rather than being told by its own /config.js:
+     * a client flag can hide a control but cannot make the data right, and the two drift
+     * the moment someone adds a locale. `multilingual` is the derived answer to the only
+     * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+    listCmsCapabilities: import("@pramen/server").Handler<unknown, {
+        locales: string[];
+        defaultLocale: string;
+        multilingual: boolean;
+    }>;
+    /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
+     * store — not configuration. `listCmsCapabilities().locales` is what the deployment
+     * declares; these two differ while a locale is declared but not yet authored. */
     listLocales: import("@pramen/server").Handler<unknown, string[]>;
     /** Create a block instance and place it into a page region in one call (the common
      * editor action). Validates the fields against the block type's schema and the region
@@ -1300,7 +1325,21 @@ export declare const cmsHandlers: {
         title: string;
         status: string;
     }[]>;
-    /** Distinct locales present across all pages. */
+    /** What this deployment supports, for an editor to render against — the pages-side
+     * counterpart to `listCollections`' `supports: [...]`.
+     *
+     * The editor asks the SERVER what exists rather than being told by its own /config.js:
+     * a client flag can hide a control but cannot make the data right, and the two drift
+     * the moment someone adds a locale. `multilingual` is the derived answer to the only
+     * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+    listCmsCapabilities: import("@pramen/server").Handler<unknown, {
+        locales: string[];
+        defaultLocale: string;
+        multilingual: boolean;
+    }>;
+    /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
+     * store — not configuration. `listCmsCapabilities().locales` is what the deployment
+     * declares; these two differ while a locale is declared but not yet authored. */
     listLocales: import("@pramen/server").Handler<unknown, string[]>;
     /** Create a block instance and place it into a page region in one call (the common
      * editor action). Validates the fields against the block type's schema and the region

package/dist/index.js

@@ -959,7 +959,8 @@ export function createCmsHandlers(opts = {}) {
     const editorRoles = opts.editorRoles ?? ["editor", "admin"];
     const editor = { auth: editorRoles };
     const mediaMaxSize = opts.mediaMaxSize ?? 25_000_000;
-    const defaultLocale = opts.defaultLocale ?? "en";
+    const locales = opts.locales && opts.locales.length > 0 ? [...opts.locales] : ["en"];
+    const defaultLocale = locales[0];
     const reviewerRoles = opts.reviewerRoles ?? ["reviewer", "admin"];
     const reviewer = { auth: reviewerRoles };
     const previewTtl = opts.previewTtlSeconds ?? DEFAULT_PREVIEW_TTL_SECONDS;
@@ -1499,7 +1500,17 @@ export function createCmsHandlers(opts = {}) {
                 return o;
             },
         }),
-        /** Distinct locales present across all pages. */
+        /** What this deployment supports, for an editor to render against — the pages-side
+         * counterpart to `listCollections`' `supports: [...]`.
+         *
+         * The editor asks the SERVER what exists rather than being told by its own /config.js:
+         * a client flag can hide a control but cannot make the data right, and the two drift
+         * the moment someone adds a locale. `multilingual` is the derived answer to the only
+         * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+        listCmsCapabilities: query(() => ({ locales, defaultLocale, multilingual: locales.length > 1 }), viewer),
+        /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
+         * store — not configuration. `listCmsCapabilities().locales` is what the deployment
+         * declares; these two differ while a locale is declared but not yet authored. */
         listLocales: query(async (ctx) => {
             // Raw exec bypasses the ACL, so the trash filter has to be written out by hand —
             // otherwise the editor's locale switcher offers a locale with zero live pages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "description": "Optional block/page builder for pramen — Drupal-Paragraphs-style typed blocks in named regions, reusable blocks, scheduled publishing, built entirely from pramen primitives.",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pramen/server": "0.0.50"
+    "@pramen/server": "0.0.51"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/index.ts

@@ -1379,8 +1379,19 @@ export interface CmsHandlerOpts {
   editorRoles?: readonly string[];
   /** Max accepted media upload size in bytes (enforced at the Worker). Default 25 MB. */
   mediaMaxSize?: number;
-  /** Default locale used when `getPage`/`createPage` omit one. Default `"en"`. */
-  defaultLocale?: string;
+  /** The locales this deployment publishes in, most-preferred first. Default `["en"]`.
+   *
+   * DECLARED, not inferred. The editor renders its i18n surface — the Translations panel,
+   * the Locale field, the per-row locale column — only when there is more than one, and
+   * `listCmsCapabilities` is how it finds out. Inferring "is this site multilingual?" from
+   * the locales PRESENT IN DATA cannot work: the only way to create a second locale is
+   * `createTranslation`, which the editor exposes from inside the very panel that would
+   * stay hidden, so a monolingual site could never become multilingual.
+   *
+   * The first entry is the default stamped on a page created without one, which is why
+   * `defaultLocale` is derived from this rather than configured beside it — two options
+   * that can disagree about the same fact is how a Czech-only site ends up stamping "en". */
+  locales?: readonly string[];
   /** Roles permitted to approve/reject a page in review and publish (the editorial gate).
    * Default `["reviewer", "admin"]`. */
   reviewerRoles?: readonly string[];
@@ -1398,7 +1409,8 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
   const editorRoles = opts.editorRoles ?? ["editor", "admin"];
   const editor = { auth: editorRoles };
   const mediaMaxSize = opts.mediaMaxSize ?? 25_000_000;
-  const defaultLocale = opts.defaultLocale ?? "en";
+  const locales = opts.locales && opts.locales.length > 0 ? [...opts.locales] : ["en"];
+  const defaultLocale = locales[0]!;
   const reviewerRoles = opts.reviewerRoles ?? ["reviewer", "admin"];
   const reviewer = { auth: reviewerRoles };
   const previewTtl = opts.previewTtlSeconds ?? DEFAULT_PREVIEW_TTL_SECONDS;
@@ -1932,7 +1944,18 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       },
     }),
 
-    /** Distinct locales present across all pages. */
+    /** What this deployment supports, for an editor to render against — the pages-side
+     * counterpart to `listCollections`' `supports: [...]`.
+     *
+     * The editor asks the SERVER what exists rather than being told by its own /config.js:
+     * a client flag can hide a control but cannot make the data right, and the two drift
+     * the moment someone adds a locale. `multilingual` is the derived answer to the only
+     * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+    listCmsCapabilities: query(() => ({ locales, defaultLocale, multilingual: locales.length > 1 }), viewer),
+
+    /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
+     * store — not configuration. `listCmsCapabilities().locales` is what the deployment
+     * declares; these two differ while a locale is declared but not yet authored. */
     listLocales: query(async (ctx) => {
       // Raw exec bypasses the ACL, so the trash filter has to be written out by hand —
       // otherwise the editor's locale switcher offers a locale with zero live pages.