@pramen/cms 0.0.46 → 0.0.47

package/dist/index.d.ts

@@ -4,7 +4,34 @@ import type { HandlerContext, Policy, FileRef, BootstrapFn } from "@pramen/serve
 export interface FieldDefinition {
     name: string;
     label?: string;
-    type: "text" | "textarea" | "richtext" | "url" | "number" | "boolean" | "date" | "datetime" | "media" | "select" | "repeater" | "group";
+    type: "text" | "textarea" | "richtext" | "url" | "number" | "boolean" | "date" | "datetime"
+    /**
+     * A publication timestamp with three states: unset (hidden), a past time
+     * (published), or a future time (scheduled). The editor renders it as
+     * publish-now / schedule / unpublish rather than a bare date picker, because that is
+     * the decision an editor is actually making.
+     *
+     * Validated as a `datetime` on the wire, but NOT interchangeable with one: the
+     * `publish` control always writes a UTC instant with a `Z` suffix
+     * (`2026-08-20T12:00:00.000Z`), where the `datetime` control writes the picker's
+     * naive local string (`2026-08-20T14:00`). Both land in the same TEXT column and
+     * both pass validation, yet they sort and range-compare lexicographically against
+     * each other as if hours apart — so converting an existing `datetime` field to
+     * `publish` needs a backfill of the stored values, not just a type change.
+     *
+     * A collection has no page-style publish workflow, so this is how a row goes live.
+     * Scope the anonymous read policy to it with `$now()` from `@pramen/server`:
+     *
+     * ```ts
+     * policy("cms_lectures", { read: { where: { publishedAt: { lte: $now() } } } })
+     * ```
+     *
+     * That, and not `{ publishedAt: { isNull: false } }`, is the real access boundary.
+     * `isNull: false` matches a FUTURE timestamp too, so a row the editor scheduled for
+     * next week would be anonymously readable the moment it was saved — the scheduling
+     * affordance would be a UI label over no enforcement at all.
+     */
+     | "publish" | "media" | "select" | "repeater" | "group";
     required?: boolean;
     default?: unknown;
     /** repeater/group only — the nested fields. */
@@ -38,7 +65,7 @@ export type RichText = string | {
 };
 /** Map one FieldDefinition (as a const literal) to the TS type of its RENDERED value.
  * Media resolves to `ResolvedMedia` (the assemble-time shape a component receives). */
-export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" | "date" | "datetime" ? string : D["type"] extends "richtext" ? RichText : D["type"] extends "number" ? number : D["type"] extends "boolean" ? boolean : D["type"] extends "media" ? ResolvedMedia | null : D["type"] extends "group" ? InferBlockFields<NonNullable<D["fields"]>> : D["type"] extends "repeater" ? InferBlockFields<NonNullable<D["fields"]>>[] : unknown;
+export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" | "date" | "datetime" | "publish" ? string : D["type"] extends "richtext" ? RichText : D["type"] extends "number" ? number : D["type"] extends "boolean" ? boolean : D["type"] extends "media" ? ResolvedMedia | null : D["type"] extends "group" ? InferBlockFields<NonNullable<D["fields"]>> : D["type"] extends "repeater" ? InferBlockFields<NonNullable<D["fields"]>>[] : unknown;
 /** Infer the `fields` object type from a const `FieldDefinition[]`. Required fields are
  * present; optional ones are `| undefined`. */
 export type InferBlockFields<T extends readonly FieldDefinition[]> = {

package/dist/index.js

@@ -118,6 +118,7 @@ function tsTypeOf(f) {
         case "select":
         case "date":
         case "datetime":
+        case "publish":
             return "string";
         case "richtext":
             return "RichText";
@@ -321,6 +322,8 @@ export function validateFields(schema, values, path = "", opts = {}) {
                     throw new BadRequest(`field '${at}' must be a date (YYYY-MM-DD)`);
                 break;
             case "datetime":
+            // `publish` is a datetime on the wire; only the editor control differs.
+            case "publish":
                 if (typeof v !== "string" || !isDateTimeString(v))
                     throw new BadRequest(`field '${at}' must be a date-time (ISO 8601)`);
                 break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "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.46",
+    "@pramen/server": "0.0.47",
     "xss": "^1.0.15"
   },
   "peerDependencies": {

package/src/index.ts

@@ -61,6 +61,33 @@ export interface FieldDefinition {
     | "boolean"
     | "date"
     | "datetime"
+    /**
+     * A publication timestamp with three states: unset (hidden), a past time
+     * (published), or a future time (scheduled). The editor renders it as
+     * publish-now / schedule / unpublish rather than a bare date picker, because that is
+     * the decision an editor is actually making.
+     *
+     * Validated as a `datetime` on the wire, but NOT interchangeable with one: the
+     * `publish` control always writes a UTC instant with a `Z` suffix
+     * (`2026-08-20T12:00:00.000Z`), where the `datetime` control writes the picker's
+     * naive local string (`2026-08-20T14:00`). Both land in the same TEXT column and
+     * both pass validation, yet they sort and range-compare lexicographically against
+     * each other as if hours apart — so converting an existing `datetime` field to
+     * `publish` needs a backfill of the stored values, not just a type change.
+     *
+     * A collection has no page-style publish workflow, so this is how a row goes live.
+     * Scope the anonymous read policy to it with `$now()` from `@pramen/server`:
+     *
+     * ```ts
+     * policy("cms_lectures", { read: { where: { publishedAt: { lte: $now() } } } })
+     * ```
+     *
+     * That, and not `{ publishedAt: { isNull: false } }`, is the real access boundary.
+     * `isNull: false` matches a FUTURE timestamp too, so a row the editor scheduled for
+     * next week would be anonymously readable the moment it was saved — the scheduling
+     * affordance would be a UI label over no enforcement at all.
+     */
+    | "publish"
     | "media"
     | "select"
     | "repeater"
@@ -107,7 +134,7 @@ export type RichText = string | { type: string; content?: unknown[] };
 
 /** Map one FieldDefinition (as a const literal) to the TS type of its RENDERED value.
  * Media resolves to `ResolvedMedia` (the assemble-time shape a component receives). */
-export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" | "date" | "datetime"
+export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" | "date" | "datetime" | "publish"
   ? string
   : D["type"] extends "richtext"
     ? RichText
@@ -282,6 +309,7 @@ function tsTypeOf(f: FieldDefinition): string {
     case "select":
     case "date":
     case "datetime":
+    case "publish":
       return "string";
     case "richtext":
       return "RichText";
@@ -514,6 +542,8 @@ export function validateFields(schema: FieldDefinition[] | undefined | null, val
         if (typeof v !== "string" || !isDateString(v)) throw new BadRequest(`field '${at}' must be a date (YYYY-MM-DD)`);
         break;
       case "datetime":
+      // `publish` is a datetime on the wire; only the editor control differs.
+      case "publish":
         if (typeof v !== "string" || !isDateTimeString(v)) throw new BadRequest(`field '${at}' must be a date-time (ISO 8601)`);
         break;
       case "media":