@pramen/cms 0.0.46 → 0.0.48

package/dist/index.d.ts

@@ -4,7 +4,45 @@ 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"
+    /**
+     * A URL segment, derived from another field as you type.
+     *
+     * Set `from` to the field it follows (usually the title). The editor keeps them in
+     * sync only while the slug is untouched — once it has been edited, or on a row that
+     * already has one, it stops following, because silently rewriting a slug changes a
+     * live URL and breaks every link to it.
+     *
+     * Stored as text. Uniqueness is the schema's job (`unique(t.text())`).
+     */
+     | "slug" | "media" | "select" | "repeater" | "group";
     required?: boolean;
     default?: unknown;
     /** repeater/group only — the nested fields. */
@@ -17,6 +55,8 @@ export interface FieldDefinition {
     /** select only — fetch options at edit time from a query handler of this name (returns
      * `{ value, label }[]`), e.g. a live list of campaigns. Takes precedence over `options`. */
     optionsFrom?: string;
+    /** slug only — the sibling field this one is derived from (e.g. `"title"`). */
+    from?: string;
 }
 /** A named region on a content type; `allowedTypes` (block-type slugs) restricts what
  * may be placed there — `null`/omitted means any. */
@@ -38,7 +78,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" | "slug" ? 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,8 @@ function tsTypeOf(f) {
         case "select":
         case "date":
         case "datetime":
+        case "publish":
+        case "slug":
             return "string";
         case "richtext":
             return "RichText";
@@ -274,6 +276,12 @@ export const cmsSchema = {
 function isDateString(v) {
     return /^\d{4}-\d{2}-\d{2}$/.test(v) && Number.isFinite(Date.parse(v));
 }
+/** A URL segment: lowercase a-z/0-9 groups joined by single hyphens, capped like the editor
+ * control caps it. Normalization lives in the editor, but the editor is not the only writer —
+ * a script or another client posting "Hello World/../x" would otherwise land it in a route. */
+function isSlugString(v) {
+    return v.length <= 80 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v);
+}
 /** A date-time: `YYYY-MM-DDTHH:MM[:SS[.sss]][Z|±HH:MM]` (ISO 8601 / datetime-local). */
 function isDateTimeString(v) {
     return /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/.test(v) && Number.isFinite(Date.parse(v));
@@ -304,6 +312,13 @@ export function validateFields(schema, values, path = "", opts = {}) {
                     throw new BadRequest(`field '${at}' must be one of: ${def.options.join(", ")}`);
                 }
                 break;
+            // A slug is text on the wire; only the editor control differs.
+            case "slug":
+                if (typeof v !== "string")
+                    throw new BadRequest(`field '${at}' must be a string`);
+                if (!isSlugString(v))
+                    throw new BadRequest(`field '${at}' must be a slug (lowercase letters, digits and single hyphens)`);
+                break;
             case "richtext":
                 if (typeof v !== "string" && typeof v !== "object")
                     throw new BadRequest(`field '${at}' must be rich text`);
@@ -321,6 +336,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.48",
   "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.48",
     "xss": "^1.0.15"
   },
   "peerDependencies": {

package/src/index.ts

@@ -61,6 +61,44 @@ 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"
+    /**
+     * A URL segment, derived from another field as you type.
+     *
+     * Set `from` to the field it follows (usually the title). The editor keeps them in
+     * sync only while the slug is untouched — once it has been edited, or on a row that
+     * already has one, it stops following, because silently rewriting a slug changes a
+     * live URL and breaks every link to it.
+     *
+     * Stored as text. Uniqueness is the schema's job (`unique(t.text())`).
+     */
+    | "slug"
     | "media"
     | "select"
     | "repeater"
@@ -77,6 +115,8 @@ export interface FieldDefinition {
   /** select only — fetch options at edit time from a query handler of this name (returns
    * `{ value, label }[]`), e.g. a live list of campaigns. Takes precedence over `options`. */
   optionsFrom?: string;
+  /** slug only — the sibling field this one is derived from (e.g. `"title"`). */
+  from?: string;
 }
 
 /** A named region on a content type; `allowedTypes` (block-type slugs) restricts what
@@ -107,7 +147,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" | "slug"
   ? string
   : D["type"] extends "richtext"
     ? RichText
@@ -282,6 +322,8 @@ function tsTypeOf(f: FieldDefinition): string {
     case "select":
     case "date":
     case "datetime":
+    case "publish":
+    case "slug":
       return "string";
     case "richtext":
       return "RichText";
@@ -473,6 +515,12 @@ export interface ValidateOpts {
 function isDateString(v: string): boolean {
   return /^\d{4}-\d{2}-\d{2}$/.test(v) && Number.isFinite(Date.parse(v));
 }
+/** A URL segment: lowercase a-z/0-9 groups joined by single hyphens, capped like the editor
+ * control caps it. Normalization lives in the editor, but the editor is not the only writer —
+ * a script or another client posting "Hello World/../x" would otherwise land it in a route. */
+function isSlugString(v: string): boolean {
+  return v.length <= 80 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v);
+}
 /** A date-time: `YYYY-MM-DDTHH:MM[:SS[.sss]][Z|±HH:MM]` (ISO 8601 / datetime-local). */
 function isDateTimeString(v: string): boolean {
   return /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/.test(v) && Number.isFinite(Date.parse(v));
@@ -501,6 +549,11 @@ export function validateFields(schema: FieldDefinition[] | undefined | null, val
           throw new BadRequest(`field '${at}' must be one of: ${def.options.join(", ")}`);
         }
         break;
+      // A slug is text on the wire; only the editor control differs.
+      case "slug":
+        if (typeof v !== "string") throw new BadRequest(`field '${at}' must be a string`);
+        if (!isSlugString(v)) throw new BadRequest(`field '${at}' must be a slug (lowercase letters, digits and single hyphens)`);
+        break;
       case "richtext":
         if (typeof v !== "string" && typeof v !== "object") throw new BadRequest(`field '${at}' must be rich text`);
         break;
@@ -514,6 +567,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":