@pramen/cms 0.0.61 → 0.0.64

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { HandlerContext, Policy, FileRef, BootstrapFn, JsonValue, SchemaDef } from "@pramen/server";
+import type { HandlerContext, Policy, FileRef, BootstrapFn, DataMigration, JsonValue, SchemaDef } from "@pramen/server";
 import type { EnvBag } from "@pramen/server";
 /** A field in a block type's (or content type's) field schema. Recursive: a `repeater`
  * or `group` nests `fields`. Mirrors WollyCMS's FieldDefinition. */
@@ -887,6 +887,9 @@ export declare const cmsSchema: {
         } & {
             readonly default: false;
         };
+        appliesTo: {
+            readonly type: "json";
+        };
         createdAt: {
             readonly type: "text";
         } & {
@@ -953,6 +956,11 @@ export declare const cmsSchema: {
             readonly target: "cms_page_terms";
             readonly column: string;
         };
+        media: {
+            readonly kind: "hasMany";
+            readonly target: "cms_media_terms";
+            readonly column: string;
+        };
     }>;
     cms_page_terms: import("@pramen/server").EntityDef<{
         id: {
@@ -991,6 +999,43 @@ export declare const cmsSchema: {
             readonly onDelete: import("@pramen/server").OnDelete | undefined;
         };
     }>;
+    cms_media_terms: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        mediaId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+        termId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+    }, {
+        media: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_media";
+            readonly column: string;
+            readonly onDelete: import("@pramen/server").OnDelete | undefined;
+        };
+        term: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_terms";
+            readonly column: string;
+            readonly onDelete: import("@pramen/server").OnDelete | undefined;
+        };
+    }>;
     cms_widget_areas: import("@pramen/server").EntityDef<{
         id: {
             readonly type: "uuid";
@@ -1046,6 +1091,19 @@ export declare const cmsSchema: {
         file: {
             readonly type: "fileRef";
         };
+        filename: {
+            readonly type: "text";
+        } & {
+            readonly index: true;
+        };
+        contentType: {
+            readonly type: "text";
+        } & {
+            readonly index: true;
+        };
+        size: {
+            readonly type: "integer";
+        };
         alt: {
             readonly type: "text";
         };
@@ -1059,12 +1117,44 @@ export declare const cmsSchema: {
         } & {
             readonly defaultExpr: string;
         };
-    }, Record<string, never>>;
+    }, {
+        terms: {
+            readonly kind: "manyToMany";
+            readonly target: "cms_terms";
+            readonly through: string;
+            readonly sourceColumn: string;
+            readonly targetColumn: string;
+        };
+    }>;
 };
+/** How a media list may be ordered. */
+export type MediaSort = "newest" | "oldest" | "name" | "name_desc" | "largest" | "smallest";
+/** The coarse type buckets the library filters by — the first segment of a MIME type, which
+ * is the distinction someone browsing a library actually makes ("show me the images"). */
+export declare const MEDIA_KINDS: readonly ["image", "video", "audio", "document", "other"];
+export type MediaKind = (typeof MEDIA_KINDS)[number];
+/** The object types a vocabulary can be applied to. A CLOSED vocabulary, like `MEDIA_KINDS`:
+ * it decides which panels offer a taxonomy AND which assignments are accepted, so an unknown
+ * value must not be storable. */
+export declare const TAXONOMY_TARGETS: readonly ["page", "media"];
+export type TaxonomyTarget = (typeof TAXONOMY_TARGETS)[number];
+/** Whether a vocabulary applies to `target`.
+ *
+ * The permissive readings all collapse to TRUE, deliberately: NULL (never narrowed, or written
+ * before the column existed), a non-array, an array of things that are not targets. A stored
+ * value nobody can interpret must not silently stop a vocabulary from working — the failure
+ * would be a taxonomy that has quietly vanished from every panel, with the row still there. */
+export declare function taxonomyApplies(row: {
+    appliesTo?: unknown;
+}, target: TaxonomyTarget): boolean;
 /** Block Kit — custom admin pages, described as JSON and rendered by the editor. See
  * `./blockkit`. Re-exported so a host imports `adminPage` beside `collection`. */
-export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
-export type { AdminBlock, AdminButton, AdminElement, AdminInput, AdminInteractionType, AdminPageDef, AdminPageHandlerOpts, AdminPageInteraction, AdminPageMeta, AdminPageResponse, AdminText, } from "./blockkit";
+export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, ADMIN_ELEMENT_TYPES, ADMIN_PAGE_KINDS, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
+export type { AdminBlock, AdminButton, AdminCell, AdminElement, AdminInput, AdminInteractionType, AdminPageDef, AdminPageHandlerOpts, AdminPageInteraction, AdminPageKind, AdminPageMeta, AdminPageResponse, AdminScreenDef, AdminText, } from "./blockkit";
+/** Custom admin PANELS — a project's own React screen inside the editor's chrome, for the
+ * screens a server-driven vocabulary cannot carry. See `./panel`. */
+export { adminPanel, isAdminPanel } from "./panel";
+export type { AdminPanelDef } from "./panel";
 /**
  * Columns this package wrote in the pre-ISO space form that the SCHEMA cannot identify.
  *
@@ -1478,28 +1568,48 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
     }, {
         ok: true;
     }>;
-    /** Every vocabulary. PUBLIC — like content types, a taxonomy's slug is structural (it
-     * is a URL segment) and a front end routes on it. */
-    listTaxonomies: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    /** Every vocabulary, or just the ones that classify `target`. PUBLIC — like content
+     * types, a taxonomy's slug is structural (it is a URL segment) and a front end routes on
+     * it.
+     *
+     * Narrowed HERE rather than in each caller, so the page panel, the media panel and the
+     * write-side guard cannot disagree about what a vocabulary applies to. In memory, because
+     * `appliesTo` is a `t.json()` column that `where` cannot see into — which costs nothing:
+     * this handler already reads every taxonomy, and nothing pages by them.
+     *
+     * No `target` means EVERY vocabulary, which is what the Taxonomies screen needs: the one
+     * place that edits `appliesTo` must be able to see a vocabulary it has narrowed away. */
+    listTaxonomies: import("@pramen/server").Handler<{
+        target?: TaxonomyTarget;
+    }, Record<string, unknown>[]>;
     createTaxonomy: import("@pramen/server").Handler<{
         slug: string;
         label: string;
         pluralLabel?: string;
         description?: string;
         hierarchical?: boolean;
+        appliesTo?: TaxonomyTarget[] | null;
     }, Record<string, unknown>>;
     /** Patch a vocabulary. `slug` is a URL segment and the key `listTerms` resolves, so it
      * is not mutable — the same rule content types and block types already follow.
      *
      * Turning `hierarchical` OFF is refused while any term still has a parent. Allowing it
      * would leave a stored hierarchy that no reader renders and no writer can clear, and
-     * flattening the terms silently is a destructive edit behind a checkbox. */
+     * flattening the terms silently is a destructive edit behind a checkbox.
+     *
+     * NARROWING `appliesTo` is refused on exactly the same grounds, and it is the same bug:
+     * dropping a target this vocabulary is already used for would strand those assignments —
+     * still stored, still returned by `listPageTerms`/`listMediaTerms`, but invisible in the
+     * panel that could remove them, because the panel only renders vocabularies that apply.
+     * Unassign them first; then the narrowing is a settings change rather than a silent
+     * orphaning. WIDENING is always fine — it strands nothing. */
     updateTaxonomy: import("@pramen/server").Handler<{
         id: string;
         label?: string;
         pluralLabel?: string | null;
         description?: string | null;
         hierarchical?: boolean;
+        appliesTo?: TaxonomyTarget[] | null;
     }, Record<string, unknown> | undefined>;
     /** Delete a vocabulary. Its terms go with it, and their page assignments with those —
      * both by real `ON DELETE CASCADE`, so the cleanup is the DB's and cannot be half-done
@@ -1617,6 +1727,10 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
     listMedia: import("@pramen/server").Handler<{
         limit?: number;
         offset?: number;
+        sort?: MediaSort;
+        kind?: MediaKind;
+        q?: string;
+        term?: string;
     }, Record<string, unknown>[]>;
     getMedia: import("@pramen/server").Handler<{
         id: string;
@@ -1626,6 +1740,25 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         id: string;
         alt: string | null;
     }, Record<string, unknown>>;
+    /** A media asset's assigned terms.
+     *
+     * The media row is read FIRST, through `ctx.db`, so the caller's own scope decides
+     * whether this answers — the junction and `cms_terms` are granted unscoped, so without
+     * it anyone holding an id could read a TRASHED file's tags and the non-empty answer
+     * would confirm the file exists. Same rule as `listPageTerms`, for the same reason. */
+    listMediaTerms: import("@pramen/server").Handler<{
+        mediaId: string;
+    }, Term[]>;
+    /** Replace a media asset's term assignments wholesale — set semantics, like
+     * `setPageTerms`, and for the same reason: the panel holds the whole selection, and two
+     * calls each patching one end of it race into a state neither asked for. */
+    setMediaTerms: import("@pramen/server").Handler<{
+        mediaId: string;
+        termIds: string[];
+    }, {
+        ok: true;
+        count: number;
+    }>;
     /** Trash a media row. The R2 OBJECT IS KEPT — deleting the bytes here would make
      * `restoreMedia` a lie, and a block still referencing the id would render a dead url
      * with no way back. `purgeMedia` is what drops both — and `listTrash` is how you find
@@ -1787,6 +1920,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         pagesByType: true;
         siteFurniture: true;
         codeDefinedTypes: true;
+        mediaTerms: true;
         canEdit: boolean;
     }>;
     /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
@@ -2077,28 +2211,48 @@ export declare const cmsHandlers: {
     }, {
         ok: true;
     }>;
-    /** Every vocabulary. PUBLIC — like content types, a taxonomy's slug is structural (it
-     * is a URL segment) and a front end routes on it. */
-    listTaxonomies: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    /** Every vocabulary, or just the ones that classify `target`. PUBLIC — like content
+     * types, a taxonomy's slug is structural (it is a URL segment) and a front end routes on
+     * it.
+     *
+     * Narrowed HERE rather than in each caller, so the page panel, the media panel and the
+     * write-side guard cannot disagree about what a vocabulary applies to. In memory, because
+     * `appliesTo` is a `t.json()` column that `where` cannot see into — which costs nothing:
+     * this handler already reads every taxonomy, and nothing pages by them.
+     *
+     * No `target` means EVERY vocabulary, which is what the Taxonomies screen needs: the one
+     * place that edits `appliesTo` must be able to see a vocabulary it has narrowed away. */
+    listTaxonomies: import("@pramen/server").Handler<{
+        target?: TaxonomyTarget;
+    }, Record<string, unknown>[]>;
     createTaxonomy: import("@pramen/server").Handler<{
         slug: string;
         label: string;
         pluralLabel?: string;
         description?: string;
         hierarchical?: boolean;
+        appliesTo?: TaxonomyTarget[] | null;
     }, Record<string, unknown>>;
     /** Patch a vocabulary. `slug` is a URL segment and the key `listTerms` resolves, so it
      * is not mutable — the same rule content types and block types already follow.
      *
      * Turning `hierarchical` OFF is refused while any term still has a parent. Allowing it
      * would leave a stored hierarchy that no reader renders and no writer can clear, and
-     * flattening the terms silently is a destructive edit behind a checkbox. */
+     * flattening the terms silently is a destructive edit behind a checkbox.
+     *
+     * NARROWING `appliesTo` is refused on exactly the same grounds, and it is the same bug:
+     * dropping a target this vocabulary is already used for would strand those assignments —
+     * still stored, still returned by `listPageTerms`/`listMediaTerms`, but invisible in the
+     * panel that could remove them, because the panel only renders vocabularies that apply.
+     * Unassign them first; then the narrowing is a settings change rather than a silent
+     * orphaning. WIDENING is always fine — it strands nothing. */
     updateTaxonomy: import("@pramen/server").Handler<{
         id: string;
         label?: string;
         pluralLabel?: string | null;
         description?: string | null;
         hierarchical?: boolean;
+        appliesTo?: TaxonomyTarget[] | null;
     }, Record<string, unknown> | undefined>;
     /** Delete a vocabulary. Its terms go with it, and their page assignments with those —
      * both by real `ON DELETE CASCADE`, so the cleanup is the DB's and cannot be half-done
@@ -2216,6 +2370,10 @@ export declare const cmsHandlers: {
     listMedia: import("@pramen/server").Handler<{
         limit?: number;
         offset?: number;
+        sort?: MediaSort;
+        kind?: MediaKind;
+        q?: string;
+        term?: string;
     }, Record<string, unknown>[]>;
     getMedia: import("@pramen/server").Handler<{
         id: string;
@@ -2225,6 +2383,25 @@ export declare const cmsHandlers: {
         id: string;
         alt: string | null;
     }, Record<string, unknown>>;
+    /** A media asset's assigned terms.
+     *
+     * The media row is read FIRST, through `ctx.db`, so the caller's own scope decides
+     * whether this answers — the junction and `cms_terms` are granted unscoped, so without
+     * it anyone holding an id could read a TRASHED file's tags and the non-empty answer
+     * would confirm the file exists. Same rule as `listPageTerms`, for the same reason. */
+    listMediaTerms: import("@pramen/server").Handler<{
+        mediaId: string;
+    }, Term[]>;
+    /** Replace a media asset's term assignments wholesale — set semantics, like
+     * `setPageTerms`, and for the same reason: the panel holds the whole selection, and two
+     * calls each patching one end of it race into a state neither asked for. */
+    setMediaTerms: import("@pramen/server").Handler<{
+        mediaId: string;
+        termIds: string[];
+    }, {
+        ok: true;
+        count: number;
+    }>;
     /** Trash a media row. The R2 OBJECT IS KEPT — deleting the bytes here would make
      * `restoreMedia` a lie, and a block still referencing the id would render a dead url
      * with no way back. `purgeMedia` is what drops both — and `listTrash` is how you find
@@ -2386,6 +2563,7 @@ export declare const cmsHandlers: {
         pagesByType: true;
         siteFurniture: true;
         codeDefinedTypes: true;
+        mediaTerms: true;
         canEdit: boolean;
     }>;
     /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
@@ -2916,6 +3094,18 @@ export declare function createCollectionTasks(collections: readonly CollectionDe
  * between the revision insert and the page update leaves the page unpublished with an orphan
  * revision until the next at-least-once redelivery re-runs (the token still matches, so it
  * completes). Acceptable for a scheduled job; the interactive path is atomic. */
+/**
+ * The CMS's own data migrations — spread into `app.migrations`.
+ *
+ *     migrations: [...cmsMigrations]
+ *
+ * Opt-in like every other fragment this package ships (`cmsHandlers`, `cmsPolicies`,
+ * `cmsTasks`), and with the same consequence for forgetting it: nothing breaks loudly. Media
+ * rows written before the projection columns existed keep NULL `filename`/`contentType`, so
+ * they sort together under a name sort and answer only the `other` type filter. New uploads
+ * are unaffected — `createMedia` writes the columns itself.
+ */
+export declare const cmsMigrations: readonly DataMigration[];
 export declare const cmsTasks: {
     "cms:publish": (ctx: HandlerContext, payload: unknown) => Promise<void>;
     "cms:unpublish": (ctx: HandlerContext, payload: unknown) => Promise<void>;