@pmeweb/content 1.1.0 → 2.0.0

package/README.md

@@ -9,6 +9,9 @@ collections in `src/content.schema.json`; this package is what reads that declar
 | `@pmeweb/content/zodFrom` | declaration -> Astro zod schema (needs `astro`) | sites |
 | `@pmeweb/content/fields` | `isDate`, `isDateTime`, `isTime`, `isDayDate`, `TIME_RE` | portal tier 1, `zodFrom` |
 | `@pmeweb/content/schedule` | `scheduleState`, `visibleOnSite`, `portalPreview`, `scheduleErrors`, `jourQuebec`, `quebecDay` | sites, portal |
+| `@pmeweb/content/collection` | `titleFieldError`, `thumbnailError`, `richErrors`, `collectionErrors`, `schemaErrors`, `richBodyField`, `hasThumbnails` | portal, `zodFrom` |
+| `@pmeweb/content/published` | `getPublished`, the one filter every site's pages go through | sites |
+| `@pmeweb/content/prose.css` | the structure of a row of images in a rich body | sites' `Prose.astro` |
 
 ## Dated kinds
 
@@ -33,10 +36,31 @@ collections in `src/content.schema.json`; this package is what reads that declar
 The builder sets `PMEWEB_PORTAL_PREVIEW=1` on the portal's preview builds, and
 `PMEWEB_PORTAL_PREVIEW_PAST=1` too when the client ticked « Afficher les entrées passées ». A site
 reads both once, `const APERCU = portalPreview(process.env)`, and filters with
-`visibleOnSite(scheduleState(data, decl.<collection>, now), APERCU)`: live entries always,
-scheduled ones in the preview, removed ones only in a preview that asked for them. Only the exact
+`getPublished(entries, decl.<collection>, now, APERCU)`: live entries always, scheduled ones and
+drafts in the preview, removed ones only in a preview that asked for them. Only the exact
 string `'1'` counts, and the past flag means nothing without the preview flag.
 
+## 2.0.0
+
+Four declaration keys:
+
+- `titleField` (REQUIRED): the entry's human title, a top-level `line`. Lists, reference dropdowns
+  and confirmations show it. May name the same field as `slugField`, which only builds the address.
+- `thumbnail` (optional): a top-level `image` shown as the entry's thumbnail in the portal's list.
+  A collection with a `rich` body takes its first body image instead.
+- `rich: true` on a `markdown` field: the portal's visual editor. Only on the `contentField`.
+- `schedule.draft`: a top-level `boolean`. Exactly `true` makes the entry a `draft`, whatever its
+  dates: never on the live site, shown in the portal's private preview. May be declared alone.
+
+Every site filters through `getPublished(entries, decl, now, portalPreview(process.env))` from
+`@pmeweb/content/published`: live entries always, scheduled ones and drafts in the preview,
+removed ones only when asked for. The `collection` helpers check the keys above, one function per
+key so the portal can drop the faulty one alone. `prose.css`: import it in the site's
+`Prose.astro`; it holds the structure of a row of images, the look stays per site.
+
+Why it is major: `scheduleState` can return `draft`, and `zodFrom` refuses a collection without
+`titleField` (or with any other error `collectionErrors` reports).
+
 ## Versioning
 
 Sites and the portal pin an EXACT version. What `scheduleState` returns and what the field checks

package/dist/collection.d.ts

@@ -0,0 +1,26 @@
+import { type FieldLike } from './schedule.js';
+export interface CollectionLike {
+    titleField?: unknown;
+    thumbnail?: unknown;
+    contentField?: string;
+    fields: Record<string, FieldLike & {
+        rich?: unknown;
+    }>;
+    schedule?: {
+        publishAt?: unknown;
+        removeAt?: unknown;
+        draft?: unknown;
+    };
+}
+export declare function titleFieldError(c: CollectionLike): string | null;
+export declare function thumbnailError(c: CollectionLike): string | null;
+/** `rich: true` only on the `contentField`, and only on a `markdown` one. `false` means nothing. */
+export declare function richErrors(c: CollectionLike): string[];
+/** Every error of one collection; `[]` means valid. */
+export declare function collectionErrors(c: CollectionLike): string[];
+/** Every error of a whole `content.schema.json`, each prefixed with its collection's key. */
+export declare function schemaErrors(schema: Record<string, CollectionLike>): string[];
+/** The field that gets the visual editor, or null. */
+export declare function richBodyField(c: CollectionLike): string | null;
+/** Whether the portal's list draws thumbnails for this collection at all. */
+export declare function hasThumbnails(c: CollectionLike): boolean;

package/dist/collection.js

@@ -0,0 +1,74 @@
+// @pmeweb/content/collection
+// The collection-level keys `schedule.ts` does not own: which field is the title, which is the
+// thumbnail, which body is rich. Checked here once, read the same way by a site's build
+// (`zodFrom` throws on any error) and by the portal (which DROPS the faulty key with a warning,
+// key by key -- hence one function per key, not just the total).
+//
+// STRUCTURAL AND LOOSE, like `SchedulableLike`: a site passes its imported JSON (every `kind`
+// widened to `string`) and the portal its own parsed schema; neither should need a cast.
+import { scheduleErrors } from './schedule.js';
+export function titleFieldError(c) {
+    const name = c.titleField;
+    if (name === undefined)
+        return 'titleField : absent (le champ qui sert de titre)';
+    if (typeof name !== 'string' || !c.fields[name])
+        return `titleField : « ${String(name)} » n’est pas un champ`;
+    if (c.fields[name].kind !== 'line')
+        return `titleField : « ${name} » n’est pas une ligne de texte`;
+    return null;
+}
+export function thumbnailError(c) {
+    const name = c.thumbnail;
+    if (name === undefined)
+        return null;
+    if (typeof name !== 'string' || !c.fields[name])
+        return `thumbnail : « ${String(name)} » n’est pas un champ`;
+    if (c.fields[name].kind !== 'image')
+        return `thumbnail : « ${name} » n’est pas une image`;
+    return null;
+}
+/** `rich: true` only on the `contentField`, and only on a `markdown` one. `false` means nothing. */
+export function richErrors(c) {
+    const out = [];
+    for (const [key, f] of Object.entries(c.fields)) {
+        if (f.rich === undefined || f.rich === false)
+            continue;
+        if (f.rich !== true)
+            out.push(`fields.${key}.rich : seule la valeur true est permise`);
+        else if (f.kind !== 'markdown')
+            out.push(`fields.${key}.rich : « ${key} » n’est pas un champ markdown`);
+        else if (c.contentField !== key)
+            out.push(`fields.${key}.rich : « ${key} » n’est pas le contentField`);
+    }
+    return out;
+}
+/** Every error of one collection; `[]` means valid. */
+export function collectionErrors(c) {
+    const out = [];
+    const title = titleFieldError(c);
+    if (title)
+        out.push(title);
+    const thumb = thumbnailError(c);
+    if (thumb)
+        out.push(thumb);
+    out.push(...richErrors(c), ...scheduleErrors(c));
+    return out;
+}
+/** Every error of a whole `content.schema.json`, each prefixed with its collection's key. */
+export function schemaErrors(schema) {
+    return Object.entries(schema).flatMap(([key, c]) => collectionErrors(c).map((e) => `${key}.${e}`));
+}
+/** The field that gets the visual editor, or null. */
+export function richBodyField(c) {
+    const key = c.contentField;
+    if (!key)
+        return null;
+    const f = c.fields[key];
+    return f && f.kind === 'markdown' && f.rich === true ? key : null;
+}
+/** Whether the portal's list draws thumbnails for this collection at all. */
+export function hasThumbnails(c) {
+    if (typeof c.thumbnail === 'string' && c.fields[c.thumbnail]?.kind === 'image')
+        return true;
+    return richBodyField(c) !== null;
+}

package/dist/published.d.ts

@@ -0,0 +1,4 @@
+import { type PortalPreview, type SchedulableLike } from './schedule.js';
+export declare function getPublished<E extends {
+    data: object;
+}>(entries: readonly E[], decl: SchedulableLike, now: Date, preview: PortalPreview): E[];

package/dist/published.js

@@ -0,0 +1,14 @@
+// @pmeweb/content/published
+// THE ONE FILTER every site's pages go through: an entry is built when its declared schedule
+// says it is on the site. It replaces the hand-written `isVisible` the blog sites carried and the
+// inline `!draft` checks elsewhere -- one function, the same one the portal badges with.
+//
+// NO ASTRO IMPORT. The site passes `getCollection(...)`'s result, so `astro` stays an optional
+// peer and this file stays testable.
+import { scheduleState, visibleOnSite } from './schedule.js';
+// `data: object`, NOT `Record<string, unknown>`: every site types its entries with an
+// `interface` (`BlogData`, `ArticleData`), and an interface has no implicit index signature, so
+// the narrower bound would refuse exactly the call this function exists for.
+export function getPublished(entries, decl, now, preview) {
+    return entries.filter((e) => visibleOnSite(scheduleState(e.data, decl, now), preview));
+}

package/dist/schedule.d.ts

@@ -1,6 +1,6 @@
 /** The zone every PmeWeb client lives in. One constant, named where it is used. */
 export declare const QUEBEC = "America/Toronto";
-export type ScheduleState = 'scheduled' | 'live' | 'removed';
+export type ScheduleState = 'draft' | 'scheduled' | 'live' | 'removed';
 /**
  * The slice of a declaration this module reads. STRUCTURAL AND LOOSE on purpose: a site passes
  * its imported `content.schema.json` (whose `kind`s TypeScript widens to `string`) and the portal
@@ -15,6 +15,7 @@ export interface SchedulableLike {
     schedule?: {
         publishAt?: unknown;
         removeAt?: unknown;
+        draft?: unknown;
     };
 }
 /**
@@ -41,9 +42,12 @@ export declare function scheduleErrors(c: SchedulableLike): string[];
 /**
  * Where an entry stands at `now`.
  *
- * `scheduled` BEATS `removed`. An entry whose publication is after its removal was mis-entered,
- * and « Programmé » is the state that makes someone look at it; « Retiré » would bury it behind
- * the portal's filter. An invalid declaration answers `live`: it must never hide anything.
+ * `draft` BEATS EVERYTHING: an unfinished entry is unfinished whatever its dates say, and only
+ * the exact value `true` makes one (a string « true » is a typo, and a typo must not hide a
+ * post). `scheduled` BEATS `removed`. An entry whose publication is after its removal was
+ * mis-entered, and « Programmé » is the state that makes someone look at it; « Retiré » would
+ * bury it behind the portal's filter. An invalid declaration answers `live`: it must never hide
+ * anything.
  */
 export declare function scheduleState(data: Record<string, unknown>, c: SchedulableLike, now: Date): ScheduleState;
 /**
@@ -64,5 +68,6 @@ export interface PortalPreview {
     showPast: boolean;
 }
 export declare function portalPreview(env: Record<string, string | undefined>): PortalPreview;
-/** What a site builds: live always; scheduled in the preview; removed only when asked for. */
+/** What a site builds: live always; a draft or a scheduled entry in the preview; removed only
+ *  when asked for. */
 export declare function visibleOnSite(state: ScheduleState, preview: PortalPreview): boolean;

package/dist/schedule.js

@@ -111,6 +111,18 @@ export function scheduleErrors(c) {
         check('publishAt', s.publishAt, false);
     for (const p of paths(s.removeAt))
         check('removeAt', p, true);
+    if (s.draft !== undefined) {
+        const name = s.draft;
+        if (typeof name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(name)) {
+            out.push(`schedule.draft : « ${String(name)} » n’est pas un nom de champ`);
+        }
+        else if (!c.fields[name]) {
+            out.push(`schedule.draft : « ${name} » n’est pas un champ`);
+        }
+        else if (c.fields[name].kind !== 'boolean') {
+            out.push(`schedule.draft : « ${name} » n’est pas une case à cocher`);
+        }
+    }
     return out;
 }
 /** The day `removeAt` resolves to: the first path that yields one; an array path yields its latest. */
@@ -162,13 +174,19 @@ function isScheduled(data, c, now) {
 /**
  * Where an entry stands at `now`.
  *
- * `scheduled` BEATS `removed`. An entry whose publication is after its removal was mis-entered,
- * and « Programmé » is the state that makes someone look at it; « Retiré » would bury it behind
- * the portal's filter. An invalid declaration answers `live`: it must never hide anything.
+ * `draft` BEATS EVERYTHING: an unfinished entry is unfinished whatever its dates say, and only
+ * the exact value `true` makes one (a string « true » is a typo, and a typo must not hide a
+ * post). `scheduled` BEATS `removed`. An entry whose publication is after its removal was
+ * mis-entered, and « Programmé » is the state that makes someone look at it; « Retiré » would
+ * bury it behind the portal's filter. An invalid declaration answers `live`: it must never hide
+ * anything.
  */
 export function scheduleState(data, c, now) {
     if (!c.schedule || scheduleErrors(c).length > 0)
         return 'live';
+    const draftKey = c.schedule.draft;
+    if (typeof draftKey === 'string' && data[draftKey] === true)
+        return 'draft';
     if (isScheduled(data, c, now))
         return 'scheduled';
     const d = removeDay(data, c);
@@ -178,11 +196,12 @@ export function portalPreview(env) {
     const active = env.PMEWEB_PORTAL_PREVIEW === '1';
     return { active, showPast: active && env.PMEWEB_PORTAL_PREVIEW_PAST === '1' };
 }
-/** What a site builds: live always; scheduled in the preview; removed only when asked for. */
+/** What a site builds: live always; a draft or a scheduled entry in the preview; removed only
+ *  when asked for. */
 export function visibleOnSite(state, preview) {
     if (state === 'live')
         return true;
     if (!preview.active)
         return false;
-    return state === 'scheduled' || preview.showPast;
+    return state === 'scheduled' || state === 'draft' || preview.showPast;
 }

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 /** Every field kind, and the whole vocabulary a site may use. Widening this is a spec
- *  decision, not a convenience: see § 4 of the design. */
-export type FieldKind = 'line' | 'paragraph' | 'markdown' | 'slug' | 'image' | 'date' | 'datetime' | 'select' | 'multiselect' | 'number' | 'boolean' | 'array' | 'reference' | 'url' | 'time';
+ *  decision, not a convenience: see § 4 of the design. A RUNTIME LIST so the portal's
+ *  defensive parser checks against this one instead of a copy. */
+export declare const FIELD_KINDS: readonly ["line", "paragraph", "markdown", "slug", "image", "date", "datetime", "select", "multiselect", "number", "boolean", "array", "reference", "url", "time"];
+export type FieldKind = (typeof FIELD_KINDS)[number];
 /** Where an enum's vocabulary lives. A POINTER at a data file, never a copy -- the portal's
  *  blog pipeline reads AND WRITES that file (design § 4). */
 export interface OptionsRef {
@@ -46,7 +48,13 @@ export interface FieldCommon {
  * for free and a missing case is a compile error.
  */
 export type Field = (FieldCommon & {
-    kind: 'line' | 'paragraph' | 'markdown' | 'slug' | 'url' | 'time' | 'date' | 'datetime' | 'boolean' | 'image';
+    kind: 'line' | 'paragraph' | 'slug' | 'url' | 'time' | 'date' | 'datetime' | 'boolean' | 'image';
+})
+/** `rich: true` gives the body the portal's visual editor. Valid ONLY on the collection's
+ *  `contentField` (`richErrors`, collection.ts). Replaces the portal's hardcoded `blog`. */
+ | (FieldCommon & {
+    kind: 'markdown';
+    rich?: boolean;
 }) | (FieldCommon & {
     kind: 'number';
     int?: boolean;
@@ -78,6 +86,12 @@ export interface ScheduleDecl {
      * latest filled value. Read as a Quebec calendar day: visible through that whole day.
      */
     removeAt?: string | string[];
+    /**
+     * One top-level `boolean` field. When it holds exactly `true` the entry is a `draft`, whatever
+     * its dates: never on the live site, shown in the portal's private preview. Absent or `false`
+     * is not a draft (booleans stay false-safe). May be declared alone.
+     */
+    draft?: string;
 }
 export interface CollectionDecl {
     label: string;
@@ -87,6 +101,12 @@ export interface CollectionDecl {
     entryFile: string;
     /** The field the slug is derived from AT CREATION. Never re-derived on edit (design § 6). */
     slugField: string;
+    /** The entry's human title: lists, reference dropdowns, confirmations. A top-level `line`.
+     *  REQUIRED. May name the same field as `slugField`, which only builds the address. */
+    titleField: string;
+    /** A top-level `image` field shown as the entry's thumbnail in the portal's list. Optional:
+     *  a collection with a `rich` body takes its first body image instead (`hasThumbnails`). */
+    thumbnail?: string;
     /** Which field is the Markdown body. ABSENT on a collection that has no body -- `authors`
      *  is frontmatter only. Excluded from the generated zod: Astro's body is not a field. */
     contentField?: string;

package/dist/types.js

@@ -5,4 +5,10 @@
 // WHY THE JSON IS TYPED AT ALL. A mistyped `kind` is otherwise a runtime throw during
 // `astro build`, in a file with no line number that a reader associates with content. With
 // this, `npm run check` names the field.
-export {};
+/** Every field kind, and the whole vocabulary a site may use. Widening this is a spec
+ *  decision, not a convenience: see § 4 of the design. A RUNTIME LIST so the portal's
+ *  defensive parser checks against this one instead of a copy. */
+export const FIELD_KINDS = [
+    'line', 'paragraph', 'markdown', 'slug', 'image', 'date', 'datetime',
+    'select', 'multiselect', 'number', 'boolean', 'array', 'reference', 'url', 'time',
+];

package/dist/zodFrom.js

@@ -19,7 +19,7 @@
 // reason, which is why the generator lives here and takes what it needs as arguments.
 import { z } from 'astro/zod';
 import { TIME_RE, isDate, isDateTime, isDayDate } from './fields.js';
-import { scheduleErrors } from './schedule.js';
+import { collectionErrors } from './collection.js';
 function values(from, ctx) {
     const vocab = ctx.vocabularies[from];
     // THROWS rather than falling back to z.string(). A silent fallback accepts any value, and
@@ -139,9 +139,10 @@ function objectSchema(fields, ctx) {
  * to the type is silently unreachable in every template).
  */
 export function zodFrom(decl, ctx) {
-    // A schedule pointing at a field that is not a date fails the build that introduced it. The
-    // portal drops the same declaration with a warning instead (`scheduleErrors`).
-    const errors = scheduleErrors(decl);
+    // A declaration the package refuses -- a title that is not a line, a rich flag off the body, a
+    // schedule pointing at a non-date -- fails the build that introduced it. The portal drops the
+    // same key with a warning instead (`collection.ts`, `schedule.ts`).
+    const errors = collectionErrors(decl);
     if (errors.length > 0)
         throw new Error(`zodFrom: ${errors.join(' ; ')}`);
     const fields = Object.fromEntries(Object.entries(decl.fields).filter(([key]) => key !== decl.contentField));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmeweb/content",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "PmeWeb content contract: content.schema.json types, zodFrom, field checks, scheduling. Read by every site's build and by the client portal.",
   "type": "module",
   "license": "MIT",
@@ -8,7 +8,8 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "prose.css"
   ],
   "exports": {
     "./types": {
@@ -26,7 +27,16 @@
     "./zodFrom": {
       "types": "./dist/zodFrom.d.ts",
       "default": "./dist/zodFrom.js"
-    }
+    },
+    "./collection": {
+      "types": "./dist/collection.d.ts",
+      "default": "./dist/collection.js"
+    },
+    "./published": {
+      "types": "./dist/published.d.ts",
+      "default": "./dist/published.js"
+    },
+    "./prose.css": "./prose.css"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",

package/prose.css

@@ -0,0 +1,17 @@
+/* @pmeweb/content/prose.css -- the STRUCTURE a row of images needs, and nothing else.
+ * A paragraph holding two or more images (consecutive lines, no blank line) is a row; a blank
+ * line keeps them stacked. The portal's editor writes rows (chunk 9), so every site whose body is
+ * `rich` must show one: a copied rule is one a site forgets, and the client's click then does
+ * nothing with no error anywhere. The LOOK (border, radius, the row's margin) stays per site.
+ * Global on purpose: import it from the site's Prose component. */
+.prose p:has(img + img) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: var(--prose-row-gap, 14px);
+}
+.prose p:has(img + img) img {
+  flex: 1 1 260px;
+  min-width: 0;
+  margin: 0;
+}