@pmeweb/content 2.0.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` | 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
@@ -29,7 +29,21 @@ collections in `src/content.schema.json`; this package is what reads that declar
   a `datetime` at its instant.
 - `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 next day's rebuild. A site that declares a schedule needs a daily rebuild.
+  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),
+and the portal's hourly scheduler rebuilds it once `next` has passed (its deploy hook goes in the
+admin's « Publication planifiée » card).
 
 ## The portal preview
 
@@ -40,6 +54,30 @@ 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`:
+
+- `scheduledCollections(schema)`: the collections that declare a valid `schedule`, in order.
+- `entryBoundaries(data, decl)`: every instant at which `scheduleState` of that entry changes, by
+  the same rules (none for a draft; a removal at or before the publication is not a change).
+- `nextChangeAt(candidates, now)`: the earliest one strictly after `now`, as `toISOString()`, or
+  `null`. `Schedule` is the `{ next }` shape the endpoint serves.
+- `quebecMidnight(day)` (the instant a Quebec day starts) and `nextQuebecDay(day)`, for a site
+  that adds instants its declaration does not name (jessyoga).
+
 ## 2.0.0
 
 Four declaration keys:

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,8 +16,22 @@ export interface SchedulableLike {
         publishAt?: unknown;
         removeAt?: unknown;
         draft?: unknown;
+        items?: unknown;
+        changesAt?: unknown;
     };
 }
+/**
+ * The instant a Quebec calendar day starts (00:00 in America/Toronto), as epoch ms; NaN for
+ * anything that is not a real `YYYY-MM-DD`.
+ *
+ * Toronto changes its clock at 02:00 local, so midnight always exists, once, at UTC-4 (daylight)
+ * or UTC-5 (standard). 04:00Z is that midnight when the day starts on daylight time; when it starts
+ * on standard time, 04:00Z is still 23:00 the evening before, so 05:00Z is the first candidate
+ * that falls on `day`. The earlier candidate that falls on the day is its start.
+ */
+export declare function quebecMidnight(day: string): number;
+/** The calendar day after `day`, or null when `day` is not one. */
+export declare function nextQuebecDay(day: string): string | null;
 /**
  * The Quebec calendar day `now` falls on, as UTC midnight of that day -- the same shape a `date`
  * field has once a site's zod has read it, so the two compare directly (`fin >= jourQuebec(now)`).
@@ -37,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`.
  *
@@ -48,8 +84,62 @@ 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;
+/**
+ * The collections of a site's `content.schema.json` that declare a VALID `schedule`, in
+ * declaration order. A site's `/schedule.json` walks exactly these, so a collection that gains a
+ * `schedule` later is covered without anybody remembering to add it -- the silent failure of a
+ * hand-kept list is a site that quietly stops aging. An invalid declaration is left out because
+ * `scheduleState` answers `live` for it at every instant: it has no boundary to report.
+ */
+export declare function scheduledCollections(schema: Record<string, SchedulableLike>): string[];
+/**
+ * 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: 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
+ * this. A non-finite candidate is dropped, not allowed to make the answer « nothing », and so is
+ * one past year 9999, whose ISO form (`+010000-...`) the portal would refuse as unreadable.
+ */
+export declare function nextChangeAt(candidates: Iterable<number>, now: number): string | null;
+/** What `/schedule.json` serves. One field, so a reader cannot pick the wrong one. */
+export interface Schedule {
+    /** An ISO instant, or null when nothing is pending. */
+    next: string | null;
+}
 /**
  * What kind of build this is, read from the two variables the portal's builder sets.
  *

package/dist/schedule.js

@@ -11,9 +11,11 @@
 // during the evening it describes. So `now` is turned into the day it is in `America/Toronto`,
 // with Intl doing the clock changes, and compared as a `YYYY-MM-DD` string.
 //
-// A STATIC SITE APPLIES THIS WHEN IT BUILDS. `now` is build time; the daily rebuild (06:00
-// Quebec) is what makes an entry come off « the morning after ». A collection that declares a
-// schedule on a site with no daily rebuild keeps showing it until someone publishes.
+// 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. 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';
@@ -27,6 +29,31 @@ function quebecDayOf(ms) {
         p[part.type] = part.value;
     return `${p.year}-${p.month}-${p.day}`;
 }
+/**
+ * The instant a Quebec calendar day starts (00:00 in America/Toronto), as epoch ms; NaN for
+ * anything that is not a real `YYYY-MM-DD`.
+ *
+ * Toronto changes its clock at 02:00 local, so midnight always exists, once, at UTC-4 (daylight)
+ * or UTC-5 (standard). 04:00Z is that midnight when the day starts on daylight time; when it starts
+ * on standard time, 04:00Z is still 23:00 the evening before, so 05:00Z is the first candidate
+ * that falls on `day`. The earlier candidate that falls on the day is its start.
+ */
+export function quebecMidnight(day) {
+    if (!isDate(day))
+        return Number.NaN;
+    for (const h of [4, 5]) {
+        const ms = Date.parse(`${day}T0${h}:00:00.000Z`);
+        if (quebecDayOf(ms) === day)
+            return ms;
+    }
+    return Number.NaN;
+}
+/** The calendar day after `day`, or null when `day` is not one. */
+export function nextQuebecDay(day) {
+    if (!isDate(day))
+        return null;
+    return new Date(Date.parse(`${day}T00:00:00.000Z`) + 86_400_000).toISOString().slice(0, 10);
+}
 /**
  * The Quebec calendar day `now` falls on, as UTC midnight of that day -- the same shape a `date`
  * field has once a site's zod has read it, so the two compare directly (`fin >= jourQuebec(now)`).
@@ -69,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;
@@ -123,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;
@@ -138,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 ?? '';
@@ -152,7 +234,7 @@ function removeDay(data, c) {
                 latest = d;
         }
         if (latest)
-            return latest;
+            return { day: latest, field: top };
     }
     return null;
 }
@@ -171,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`.
  *
@@ -180,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)
@@ -190,7 +364,113 @@ 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
+ * declaration order. A site's `/schedule.json` walks exactly these, so a collection that gains a
+ * `schedule` later is covered without anybody remembering to add it -- the silent failure of a
+ * hand-kept list is a site that quietly stops aging. An invalid declaration is left out because
+ * `scheduleState` answers `live` for it at every instant: it has no boundary to report.
+ */
+export function scheduledCollections(schema) {
+    return Object.entries(schema)
+        .filter(([, c]) => c.schedule !== undefined && scheduleErrors(c).length === 0)
+        .map(([name]) => name);
+}
+function pushPublish(out, rec, key, fields, item) {
+    if (typeof key !== 'string')
+        return null;
+    const kind = fields[key]?.kind ?? '';
+    const at = startInstant(rec[key], kind);
+    const day = quebecDay(rec[key], kind);
+    if (at === null || day === null)
+        return 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 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 entryEvents(data, c, opts = {}) {
+    if (!c.schedule || scheduleErrors(c).length > 0)
+        return [];
+    const d = data;
+    const draftKey = c.schedule.draft;
+    if (!opts.ignoreDraft && typeof draftKey === 'string' && d[draftKey] === true)
+        return [];
+    const 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');
+/**
+ * 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
+ * this. A non-finite candidate is dropped, not allowed to make the answer « nothing », and so is
+ * one past year 9999, whose ISO form (`+010000-...`) the portal would refuse as unreadable.
+ */
+export function nextChangeAt(candidates, now) {
+    let best = null;
+    for (const at of candidates) {
+        if (!Number.isFinite(at) || at <= now || at > LAST_ISO)
+            continue;
+        if (best === null || at < best)
+            best = at;
+    }
+    return best === null ? null : new Date(best).toISOString();
 }
 export function portalPreview(env) {
     const active = env.PMEWEB_PORTAL_PREVIEW === '1';

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.0.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",