@pmeweb/content 2.1.0 → 2.2.0

package/README.md

@@ -8,9 +8,9 @@ collections in `src/content.schema.json`; this package is what reads that declar
 | `@pmeweb/content/types` | `CollectionDecl`, `Field`, `ScheduleDecl`, `ContentSchema` | sites, portal |
 | `@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`, `quebecMidnight`, `nextQuebecDay`, `scheduledCollections`, `entryBoundaries`, `nextChangeAt`, `Schedule` | sites, portal |
+| `@pmeweb/content/schedule` | `scheduleState`, `visibleOnSite`, `portalPreview`, `scheduleErrors`, `jourQuebec`, `quebecDay`, `quebecMidnight`, `nextQuebecDay`, `scheduledCollections`, `entryBoundaries`, `nextChangeAt`, `Schedule`, `itemsField`, `itemState`, `itemStates`, `changePassed`, `entryEvents`, `ScheduleEvent` | 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/published` | `getPublished`, the one filter every site's pages go through; `getPublishedItems` | sites |
 | `@pmeweb/content/prose.css` | the structure of a row of images in a rich body | sites' `Prose.astro` |
 
 ## Dated kinds
@@ -30,6 +30,15 @@ collections in `src/content.schema.json`; this package is what reads that declar
 - `removeAt`: one path or several; the first that yields a value wins. `dates[].debut` takes the
   latest value in the array. Always read as a Quebec day: the entry stays through that whole day
   and comes off at the start of the next one.
+- `items` (2.2.0): `{ "field": "dates", "publishAt": "publierLe", "removeAt": "debut" }` -- an
+  array whose items go on and come off one by one, by the same rules on their sub-fields
+  (`itemState`); the entry is live while any item is. A site filters them with
+  `getPublishedItems(data, decl.<collection>, now, APERCU)`. NESTED so an older reader ignores it.
+  An entry-level `removeAt` path into the same array is refused (one fact, two declarations).
+- `changesAt` (2.2.0): `["prixFin"]` -- top-level dates whose passing changes the page without
+  changing whether the entry is on it. A `date` passes at the start of the next Quebec day, a
+  `datetime` at its instant. A site reads them with `changePassed(data, decl, field, now)`, which
+  THROWS for a field not listed, so `/schedule.json` always announces what the page compares.
 
 A site that declares a schedule serves `/schedule.json` (`{ next }`, built with
 `scheduledCollections`, `entryBoundaries` and `nextChangeAt`; the boilerplate ships the endpoint),
@@ -45,6 +54,18 @@ reads both once, `const APERCU = portalPreview(process.env)`, and filters with
 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.2.0
+
+Additive: every 2.1.0 declaration is valid and behaves identically.
+
+- `schedule.items` and `schedule.changesAt` (above), validated by `scheduleErrors`.
+- `itemState`, `itemStates`, `itemsField`; `scheduleState` reads `items`.
+- `changePassed`.
+- `entryEvents(data, decl, { ignoreDraft? })`: every moment an entry's page changes
+  (`publish` / `remove` / `change`, with the instant, the typed day, the field and the item). The
+  portal's calendar reads it; `entryBoundaries` is its instants.
+- `getPublishedItems` in `@pmeweb/content/published`.
+
 ## 2.1.0
 
 Additive, for `/schedule.json`:

package/dist/collection.d.ts

@@ -10,6 +10,8 @@ export interface CollectionLike {
         publishAt?: unknown;
         removeAt?: unknown;
         draft?: unknown;
+        items?: unknown;
+        changesAt?: unknown;
     };
 }
 export declare function titleFieldError(c: CollectionLike): string | null;

package/dist/published.d.ts

@@ -2,3 +2,10 @@ 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[];
+/**
+ * The items of `schedule.items.field` the site builds (2.2.0): each by its own `itemState`, through
+ * the same `visibleOnSite` as `getPublished`. Order kept: the site sorts. `I` is the site's item
+ * type -- the one cast, since the field is named by the declaration, not by the type. THROWS on a
+ * collection with no `items`: the call is a bug, and a build is where it should fail.
+ */
+export declare function getPublishedItems<I = unknown>(data: object, decl: SchedulableLike, now: Date, preview: PortalPreview): I[];

package/dist/published.js

@@ -5,10 +5,25 @@
 //
 // 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';
+import { itemState, itemsField, 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));
 }
+/**
+ * The items of `schedule.items.field` the site builds (2.2.0): each by its own `itemState`, through
+ * the same `visibleOnSite` as `getPublished`. Order kept: the site sorts. `I` is the site's item
+ * type -- the one cast, since the field is named by the declaration, not by the type. THROWS on a
+ * collection with no `items`: the call is a bug, and a build is where it should fail.
+ */
+export function getPublishedItems(data, decl, now, preview) {
+    const field = itemsField(decl);
+    if (field === null)
+        throw new Error('getPublishedItems : la collection ne déclare pas schedule.items');
+    const arr = data[field];
+    if (!Array.isArray(arr))
+        return [];
+    return arr.filter((it) => visibleOnSite(itemState(it, decl, now), preview));
+}

package/dist/schedule.d.ts

@@ -16,6 +16,8 @@ export interface SchedulableLike {
         publishAt?: unknown;
         removeAt?: unknown;
         draft?: unknown;
+        items?: unknown;
+        changesAt?: unknown;
     };
 }
 /**
@@ -49,8 +51,30 @@ export declare function quebecDay(value: unknown, kind: string): string | null;
  * The site's `zodFrom` THROWS on any of these, so a bad declaration fails the build that
  * introduced it. The portal DROPS the declaration with a warning: a list that hid nothing is a
  * better failure than a page that does not open.
+ *
+ * 2.2.0 adds `items` and `changesAt`; a 2.1.0 declaration gets exactly the sentences it got before.
  */
 export declare function scheduleErrors(c: SchedulableLike): string[];
+/** The array `schedule.items` publishes item by item, or null when the collection declares none. */
+export declare function itemsField(c: SchedulableLike): string | null;
+export type ItemState = 'scheduled' | 'live' | 'removed';
+/**
+ * Where ONE item of `schedule.items.field` stands at `now`: the entry's rules on its sub-fields.
+ * `scheduled` before its `publishAt`, `removed` once the Quebec day is past its `removeAt`,
+ * `scheduled` beats `removed`. No item-level draft. A non-object item, and any item of an invalid
+ * declaration, is `live`: never hide what cannot be read.
+ */
+export declare function itemState(item: unknown, c: SchedulableLike, now: Date): ItemState;
+/** Every item's state, by index; `[]` when the array is absent; null when no `items` is declared. */
+export declare function itemStates(data: object, c: SchedulableLike, now: Date): ItemState[] | null;
+/**
+ * Whether the change a `changesAt` field announces has happened at `now`.
+ *
+ * THROWS when `field` is not in `schedule.changesAt`: a page that compares the clock to a date its
+ * `/schedule.json` does not announce is a page the scheduler never rebuilds, and a throw fails the
+ * build that introduced it, as `zodFrom` does for a bad declaration.
+ */
+export declare function changePassed(data: object, c: SchedulableLike, field: string, now: Date): boolean;
 /**
  * Where an entry stands at `now`.
  *
@@ -60,6 +84,9 @@ export declare function scheduleErrors(c: SchedulableLike): string[];
  * 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.
+ *
+ * WITH `items`, the entry-level state wins when it is not `live`; otherwise the entry is live
+ * while any item is (`itemStates`).
  */
 export declare function scheduleState(data: Record<string, unknown>, c: SchedulableLike, now: Date): ScheduleState;
 /**
@@ -71,22 +98,36 @@ export declare function scheduleState(data: Record<string, unknown>, c: Schedula
  */
 export declare function scheduledCollections(schema: Record<string, SchedulableLike>): string[];
 /**
- * Every instant at which `scheduleState` of this entry changes, and only those, in time order.
- *
- * THE SAME RULES AS `scheduleState`, read from the same helpers, which is why this lives here:
- * publication is `publishInstant`; removal is the start of the Quebec day AFTER `removeDay`. A
- * `draft` has none: it is hidden by a rule that has nothing to do with the clock. A removal that
- * falls at or before the publication is not a change of its own (`scheduled` beats `removed`, so
- * the entry goes straight from `scheduled` to `removed` at the publication), and is left out.
- *
- * A site's `/schedule.json` is the earliest of these across its entries (`nextChangeAt`), and the
- * portal's hourly scheduler rebuilds the site once that instant has passed. A boundary missing
- * here is a site that silently stops aging.
- *
- * Only what the DECLARATION says. A site that filters by time on fields its `schedule` does not
- * name (jessyoga's per-date `publierLe`, its `prixFin`) must add those instants itself.
+ * One moment an entry's page changes. `at` is the instant it changes; `day` the Quebec day of the
+ * TYPED value (the calendar places by it); `timed` when `at` IS the typed instant (a `datetime`
+ * publication or change -- a removal always happens at a Quebec midnight, so it never is);
+ * `field` the field that gave it (the sub-field for an item); `item` the item's index or null.
+ */
+export interface ScheduleEvent {
+    kind: 'publish' | 'remove' | 'change';
+    at: number;
+    day: string;
+    timed: boolean;
+    field: string;
+    item: number | null;
+}
+/**
+ * Every moment this entry's page changes, in time order -- THE ONE LIST both a site's
+ * `/schedule.json` (through `entryBoundaries`) and the portal's calendar read, so they cannot
+ * disagree. The entry's publication and removal (`scheduleState`'s rules), each item's
+ * (`itemState`'s), each `changesAt` field (`changePassed`'s). A draft has none, unless
+ * `ignoreDraft` (the calendar's « prévu si publié »).
+ */
+export declare function entryEvents(data: object, c: SchedulableLike, opts?: {
+    ignoreDraft?: boolean;
+}): ScheduleEvent[];
+/**
+ * Every instant at which this entry's page changes -- `entryEvents`' instants. For a 2.1.0
+ * declaration the same list, in the same order, as 2.1.0 returned. A site's `/schedule.json` is
+ * the earliest across its entries (`nextChangeAt`); a boundary missing here is a site that
+ * silently stops aging.
  */
-export declare function entryBoundaries(data: Record<string, unknown>, c: SchedulableLike): number[];
+export declare function entryBoundaries(data: object, c: SchedulableLike): number[];
 /**
  * The earliest candidate strictly after `now`, as ISO (`toISOString`), or null when nothing is
  * pending. STRICTLY after: an instant that has arrived was already rendered by the build computing

package/dist/schedule.js

@@ -14,7 +14,8 @@
 // A STATIC SITE APPLIES THIS WHEN IT BUILDS. `now` is build time; the site serves the next instant
 // its output changes at `/schedule.json` (`scheduledCollections` + `entryBoundaries` +
 // `nextChangeAt`), and the portal's hourly scheduler (pmeweb-portail/src/server/schedule/) rebuilds
-// it once that instant has passed.
+// it once that instant has passed. Since 2.2.0 both `/schedule.json` and the portal's calendar
+// read ONE list, `entryEvents`: the publications, removals and declared changes of an entry.
 import { isDate, isDateTime } from './fields.js';
 /** The zone every PmeWeb client lives in. One constant, named where it is used. */
 export const QUEBEC = 'America/Toronto';
@@ -95,12 +96,46 @@ function paths(v) {
         return [];
     return Array.isArray(v) ? v : [v];
 }
+/**
+ * `schedule.items`'s faults, pushed onto `out`; the array field's name when the declaration names
+ * a real array (even if a sub-field is wrong), so the overlap with `removeAt` can still be judged.
+ */
+function itemsErrors(c, items, out) {
+    if (items === undefined)
+        return null;
+    if (typeof items !== 'object' || items === null || Array.isArray(items)) {
+        out.push('schedule.items : ce n’est pas un objet');
+        return null;
+    }
+    const { field, publishAt, removeAt } = items;
+    const f = typeof field === 'string' ? c.fields[field] : undefined;
+    if (!f || f.kind !== 'array' || !f.of) {
+        out.push(`schedule.items.field : « ${String(field)} » n’est pas un champ tableau`);
+        return null;
+    }
+    const name = field;
+    const of = f.of;
+    if (publishAt === undefined && paths(removeAt).length === 0)
+        out.push('schedule.items : ni publishAt ni removeAt');
+    const sub = (key, p) => {
+        const kind = typeof p === 'string' ? of[p]?.kind : undefined;
+        if (kind === undefined || !DATED.has(kind))
+            out.push(`schedule.items.${key} : « ${String(p)} » n’est pas une date du tableau « ${name} »`);
+    };
+    if (publishAt !== undefined)
+        sub('publishAt', publishAt);
+    for (const p of paths(removeAt))
+        sub('removeAt', p);
+    return name;
+}
 /**
  * Everything wrong with a collection's `schedule`, one French sentence each; `[]` means valid.
  *
  * The site's `zodFrom` THROWS on any of these, so a bad declaration fails the build that
  * introduced it. The portal DROPS the declaration with a warning: a list that hid nothing is a
  * better failure than a page that does not open.
+ *
+ * 2.2.0 adds `items` and `changesAt`; a 2.1.0 declaration gets exactly the sentences it got before.
  */
 export function scheduleErrors(c) {
     const s = c.schedule;
@@ -149,9 +184,30 @@ export function scheduleErrors(c) {
             out.push(`schedule.draft : « ${name} » n’est pas une case à cocher`);
         }
     }
+    const itemsField = itemsErrors(c, s.items, out);
+    if (itemsField !== null) {
+        for (const p of paths(s.removeAt)) {
+            const m = typeof p === 'string' ? PATH_RE.exec(p) : null;
+            if (m && m[2] !== undefined && m[1] === itemsField) {
+                out.push(`schedule.removeAt : « ${p} » lit le tableau déjà déclaré dans items`);
+            }
+        }
+    }
+    if (s.changesAt !== undefined) {
+        if (!Array.isArray(s.changesAt))
+            out.push('schedule.changesAt : ce n’est pas une liste');
+        else {
+            for (const name of s.changesAt) {
+                const f = typeof name === 'string' ? c.fields[name] : undefined;
+                if (!f || !DATED.has(f.kind))
+                    out.push(`schedule.changesAt : « ${String(name)} » n’est pas une date`);
+            }
+        }
+    }
     return out;
 }
-/** The day `removeAt` resolves to: the first path that yields one; an array path yields its latest. */
+/** The day `removeAt` resolves to, and the top-level field that gave it: the first path that
+ *  yields one; an array path yields its latest. */
 function removeDay(data, c) {
     for (const p of paths(c.schedule?.removeAt)) {
         const m = typeof p === 'string' ? PATH_RE.exec(p) : null;
@@ -164,7 +220,7 @@ function removeDay(data, c) {
         if (sub === undefined) {
             const d = quebecDay(data[top], f.kind);
             if (d)
-                return d;
+                return { day: d, field: top };
             continue;
         }
         const kind = f.of?.[sub]?.kind ?? '';
@@ -178,7 +234,7 @@ function removeDay(data, c) {
                 latest = d;
         }
         if (latest)
-            return latest;
+            return { day: latest, field: top };
     }
     return null;
 }
@@ -197,6 +253,95 @@ function isScheduled(data, c, now) {
     const d = quebecDay(data[key], f.kind);
     return d !== null && d > quebecDayOf(now.getTime());
 }
+/** When a value that STARTS something takes effect: a `date` at the start of its Quebec day, a
+ *  `datetime` at its instant. Null when empty or unreadable. */
+function startInstant(value, kind) {
+    if (kind === 'datetime')
+        return instant(value);
+    const d = quebecDay(value, kind);
+    const ms = d === null ? Number.NaN : quebecMidnight(d);
+    return Number.isFinite(ms) ? ms : null;
+}
+/** The start of the Quebec day after `day`: when something whose LAST day is `day` is gone. */
+function dayAfterStart(day) {
+    const next = nextQuebecDay(day);
+    const ms = next === null ? Number.NaN : quebecMidnight(next);
+    return Number.isFinite(ms) ? ms : null;
+}
+/** The declared `items`, or null. Read only after `scheduleErrors` said the declaration is valid. */
+function itemsDecl(c) {
+    const i = c.schedule?.items;
+    return typeof i === 'object' && i !== null && !Array.isArray(i) && typeof i.field === 'string'
+        ? i : null;
+}
+/** The array `schedule.items` publishes item by item, or null when the collection declares none. */
+export function itemsField(c) {
+    return itemsDecl(c)?.field ?? null;
+}
+/** The first of `subs` that yields a Quebec day on this item, and which one. */
+function firstItemDay(item, subs, of) {
+    for (const p of paths(subs)) {
+        if (typeof p !== 'string')
+            continue;
+        const d = quebecDay(item[p], of[p]?.kind ?? '');
+        if (d)
+            return { day: d, field: p };
+    }
+    return null;
+}
+/**
+ * Where ONE item of `schedule.items.field` stands at `now`: the entry's rules on its sub-fields.
+ * `scheduled` before its `publishAt`, `removed` once the Quebec day is past its `removeAt`,
+ * `scheduled` beats `removed`. No item-level draft. A non-object item, and any item of an invalid
+ * declaration, is `live`: never hide what cannot be read.
+ */
+export function itemState(item, c, now) {
+    const items = itemsDecl(c);
+    if (!items || scheduleErrors(c).length > 0)
+        return 'live';
+    if (typeof item !== 'object' || item === null || Array.isArray(item))
+        return 'live';
+    const it = item;
+    const of = c.fields[items.field]?.of ?? {};
+    if (typeof items.publishAt === 'string') {
+        const start = startInstant(it[items.publishAt], of[items.publishAt]?.kind ?? '');
+        if (start !== null && now.getTime() < start)
+            return 'scheduled';
+    }
+    const r = firstItemDay(it, items.removeAt, of);
+    return r !== null && quebecDayOf(now.getTime()) > r.day ? 'removed' : 'live';
+}
+/** Every item's state, by index; `[]` when the array is absent; null when no `items` is declared. */
+export function itemStates(data, c, now) {
+    const items = itemsDecl(c);
+    if (!items)
+        return null;
+    const arr = data[items.field];
+    return Array.isArray(arr) ? arr.map((it) => itemState(it, c, now)) : [];
+}
+/** When a `changesAt` value takes effect: a `date` at the start of the Quebec day AFTER it (the
+ *  date is the last day the old content is right), a `datetime` at its instant. */
+function changeInstant(value, kind) {
+    if (kind === 'datetime')
+        return instant(value);
+    const d = quebecDay(value, kind);
+    return d === null ? null : dayAfterStart(d);
+}
+/**
+ * Whether the change a `changesAt` field announces has happened at `now`.
+ *
+ * THROWS when `field` is not in `schedule.changesAt`: a page that compares the clock to a date its
+ * `/schedule.json` does not announce is a page the scheduler never rebuilds, and a throw fails the
+ * build that introduced it, as `zodFrom` does for a bad declaration.
+ */
+export function changePassed(data, c, field, now) {
+    const list = c.schedule?.changesAt;
+    if (!Array.isArray(list) || !list.includes(field)) {
+        throw new Error(`changePassed : « ${field} » n’est pas déclaré dans schedule.changesAt`);
+    }
+    const at = changeInstant(data[field], c.fields[field]?.kind ?? '');
+    return at !== null && now.getTime() >= at;
+}
 /**
  * Where an entry stands at `now`.
  *
@@ -206,6 +351,9 @@ function isScheduled(data, c, now) {
  * 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.
+ *
+ * WITH `items`, the entry-level state wins when it is not `live`; otherwise the entry is live
+ * while any item is (`itemStates`).
  */
 export function scheduleState(data, c, now) {
     if (!c.schedule || scheduleErrors(c).length > 0)
@@ -216,7 +364,15 @@ export function scheduleState(data, c, now) {
     if (isScheduled(data, c, now))
         return 'scheduled';
     const d = removeDay(data, c);
-    return d !== null && quebecDayOf(now.getTime()) > d ? 'removed' : 'live';
+    if (d !== null && quebecDayOf(now.getTime()) > d.day)
+        return 'removed';
+    // 2.2.0: live at entry level, so the items decide -- live while any item is, else scheduled
+    // while one is still to come, else removed. An empty array is live (an empty array path never
+    // removed in 2.1.0 either).
+    const states = itemStates(data, c, now);
+    if (states === null || states.length === 0 || states.includes('live'))
+        return 'live';
+    return states.includes('scheduled') ? 'scheduled' : 'removed';
 }
 /**
  * The collections of a site's `content.schema.json` that declare a VALID `schedule`, in
@@ -230,53 +386,73 @@ export function scheduledCollections(schema) {
         .filter(([, c]) => c.schedule !== undefined && scheduleErrors(c).length === 0)
         .map(([name]) => name);
 }
-/** The instant `publishAt` takes effect: a `date` at the start of its Quebec day, a `datetime` at
- *  its instant. The mirror of `isScheduled`: scheduled before it, not scheduled from it on. */
-function publishInstant(data, c) {
-    const key = c.schedule?.publishAt;
+function pushPublish(out, rec, key, fields, item) {
     if (typeof key !== 'string')
         return null;
-    const f = c.fields[key];
-    if (!f)
+    const kind = fields[key]?.kind ?? '';
+    const at = startInstant(rec[key], kind);
+    const day = quebecDay(rec[key], kind);
+    if (at === null || day === null)
         return null;
-    if (f.kind === 'datetime')
-        return instant(data[key]);
-    const d = quebecDay(data[key], f.kind);
-    const ms = d === null ? Number.NaN : quebecMidnight(d);
-    return Number.isFinite(ms) ? ms : null;
+    out.push({ kind: 'publish', at, day, timed: kind === 'datetime', field: key, item });
+    return at;
+}
+function pushRemove(out, r, publish, item) {
+    if (r === null)
+        return;
+    const at = dayAfterStart(r.day);
+    // A removal at or before the publication is no change of its own: `scheduled` beats `removed`,
+    // so the entry (or item) goes straight from scheduled to removed AT the publication.
+    if (at === null || (publish !== null && at <= publish))
+        return;
+    out.push({ kind: 'remove', at, day: r.day, timed: false, field: r.field, item });
 }
 /**
- * Every instant at which `scheduleState` of this entry changes, and only those, in time order.
- *
- * THE SAME RULES AS `scheduleState`, read from the same helpers, which is why this lives here:
- * publication is `publishInstant`; removal is the start of the Quebec day AFTER `removeDay`. A
- * `draft` has none: it is hidden by a rule that has nothing to do with the clock. A removal that
- * falls at or before the publication is not a change of its own (`scheduled` beats `removed`, so
- * the entry goes straight from `scheduled` to `removed` at the publication), and is left out.
- *
- * A site's `/schedule.json` is the earliest of these across its entries (`nextChangeAt`), and the
- * portal's hourly scheduler rebuilds the site once that instant has passed. A boundary missing
- * here is a site that silently stops aging.
- *
- * Only what the DECLARATION says. A site that filters by time on fields its `schedule` does not
- * name (jessyoga's per-date `publierLe`, its `prixFin`) must add those instants itself.
+ * Every moment this entry's page changes, in time order -- THE ONE LIST both a site's
+ * `/schedule.json` (through `entryBoundaries`) and the portal's calendar read, so they cannot
+ * disagree. The entry's publication and removal (`scheduleState`'s rules), each item's
+ * (`itemState`'s), each `changesAt` field (`changePassed`'s). A draft has none, unless
+ * `ignoreDraft` (the calendar's « prévu si publié »).
  */
-export function entryBoundaries(data, c) {
+export function entryEvents(data, c, opts = {}) {
     if (!c.schedule || scheduleErrors(c).length > 0)
         return [];
+    const d = data;
     const draftKey = c.schedule.draft;
-    if (typeof draftKey === 'string' && data[draftKey] === true)
+    if (!opts.ignoreDraft && typeof draftKey === 'string' && d[draftKey] === true)
         return [];
     const out = [];
-    const publish = publishInstant(data, c);
-    if (publish !== null)
-        out.push(publish);
-    const removal = removeDay(data, c);
-    const after = removal === null ? null : nextQuebecDay(removal);
-    const remove = after === null ? Number.NaN : quebecMidnight(after);
-    if (Number.isFinite(remove) && (publish === null || remove > publish))
-        out.push(remove);
-    return out;
+    const publish = pushPublish(out, d, c.schedule.publishAt, c.fields, null);
+    pushRemove(out, removeDay(d, c), publish, null);
+    const items = itemsDecl(c);
+    if (items) {
+        const of = c.fields[items.field]?.of ?? {};
+        const arr = Array.isArray(d[items.field]) ? d[items.field] : [];
+        arr.forEach((raw, i) => {
+            if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+                return;
+            const it = raw;
+            const p = pushPublish(out, it, items.publishAt, of, i);
+            pushRemove(out, firstItemDay(it, items.removeAt, of), p, i);
+        });
+    }
+    for (const f of Array.isArray(c.schedule.changesAt) ? c.schedule.changesAt : []) {
+        const kind = c.fields[f]?.kind ?? '';
+        const at = changeInstant(d[f], kind);
+        const day = quebecDay(d[f], kind);
+        if (at !== null && day !== null)
+            out.push({ kind: 'change', at, day, timed: kind === 'datetime', field: f, item: null });
+    }
+    return out.sort((a, b) => a.at - b.at);
+}
+/**
+ * Every instant at which this entry's page changes -- `entryEvents`' instants. For a 2.1.0
+ * declaration the same list, in the same order, as 2.1.0 returned. A site's `/schedule.json` is
+ * the earliest across its entries (`nextChangeAt`); a boundary missing here is a site that
+ * silently stops aging.
+ */
+export function entryBoundaries(data, c) {
+    return entryEvents(data, c).map((e) => e.at);
 }
 /** The last instant `toISOString` writes with a four-digit year, the only shape the portal reads. */
 const LAST_ISO = Date.parse('9999-12-31T23:59:59.999Z');

package/dist/types.d.ts

@@ -92,6 +92,24 @@ export interface ScheduleDecl {
      * is not a draft (booleans stay false-safe). May be declared alone.
      */
     draft?: string;
+    /**
+     * An array whose ITEMS go on and come off the site one by one (2.2.0): jessyoga's class dates.
+     * `field` names a top-level `array`; `publishAt` one `date`/`datetime` sub-field; `removeAt`
+     * one sub-field or several, THE FIRST THAT YIELDS WINS, read as a Quebec day. At least one of
+     * the two. The entry is then live while any item is: see `scheduleState`. NESTED, not flat, so
+     * an older reader (which ignores an unknown key) cannot mistake `publishAt` for a top-level one.
+     */
+    items?: {
+        field: string;
+        publishAt?: string;
+        removeAt?: string | string[];
+    };
+    /**
+     * Top-level `date`/`datetime` fields whose passing CHANGES THE PAGE without changing whether the
+     * entry is on it (2.2.0): jessyoga's `prixFin`, after which « Prévente » is no longer written. A
+     * site reads them with `changePassed`, which throws on a field not listed here.
+     */
+    changesAt?: string[];
 }
 export interface CollectionDecl {
     label: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmeweb/content",
-  "version": "2.1.0",
+  "version": "2.2.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",