@bygghammar/cms-platform 0.90.0-m7.9 → 0.91.0

package/src/cms/page-publication.ts

@@ -0,0 +1,377 @@
+/**
+ * What the public sees, and until when.
+ *
+ * One module answers both questions so the page route, the sitemap and every
+ * cache along the way cannot disagree about whether a page is live. The rule is
+ * a single sentence:
+ *
+ *   the newest active publication whose `publishAt` has arrived governs, and
+ *   the page is public while that row's `unpublishAt` has not.
+ *
+ * The second half is why an older row never comes back into force behind a
+ * newer one. Without it, "hide this at midnight" would mean "show the previous
+ * version again at midnight", and `unpublishAt` would hide nothing at all on a
+ * page that has been published more than once.
+ *
+ * `pages.status` is not consulted here, by design. It records editorial intent
+ * — is this page finished? — and a page that is finished is not thereby public:
+ * a version scheduled for next week, a countdown target waiting for its
+ * deadline and a page whose window has closed are all finished and all hidden.
+ */
+
+/** The fields of a `page_publications` row these rules need. */
+export type PublicationWindow = {
+  versionId: string | null;
+  publishAt: string | null;
+  unpublishAt?: string | null;
+  /** Tie-break for two rows published at the same instant; newest wins. */
+  publishedAt?: string | null;
+};
+
+/**
+ * The same rows as a database hands them over.
+ *
+ * Both the public reader and the backoffice select these columns, so the
+ * translation lives here rather than once per caller — a second copy of it is
+ * a second chance to read `publish_at` into the wrong field.
+ */
+export function toPublicationWindows(rows: unknown): PublicationWindow[] {
+  return ((rows ?? []) as Array<{
+    version_id?: string | null;
+    publish_at?: string | null;
+    unpublish_at?: string | null;
+    published_at?: string | null;
+  }>).map((row) => ({
+    versionId: row.version_id ?? null,
+    publishAt: row.publish_at ?? null,
+    unpublishAt: row.unpublish_at ?? null,
+    publishedAt: row.published_at ?? null,
+  }));
+}
+
+/**
+ * An instant we cannot read is a window we cannot honour, and an unhonoured
+ * window shows nothing: an unreadable `publishAt` has not arrived, and an
+ * unreadable `unpublishAt` has already passed. Both fail towards hiding
+ * content, which is the only direction that is safe to be wrong in.
+ */
+const instant = (value: string | null | undefined): number | null => {
+  if (!value) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+};
+
+/**
+ * The row deciding what this page shows right now, or null when none has
+ * started yet. Rows may arrive in any order; the newest start wins.
+ */
+export function governingPublication<T extends PublicationWindow>(
+  rows: readonly T[],
+  now: number = Date.now(),
+): T | null {
+  let best: T | null = null;
+  let bestAt = Number.NEGATIVE_INFINITY;
+  let bestTie = Number.NEGATIVE_INFINITY;
+  for (const row of rows) {
+    const at = instant(row.publishAt);
+    if (at === null || at > now) continue;
+    const tie = instant(row.publishedAt) ?? Number.NEGATIVE_INFINITY;
+    if (at > bestAt || (at === bestAt && tie > bestTie)) {
+      best = row;
+      bestAt = at;
+      bestTie = tie;
+    }
+  }
+  return best;
+}
+
+/** Is the governing row still open? Closed at its `unpublishAt`, not after it. */
+function isOpen(row: PublicationWindow, now: number): boolean {
+  if (row.unpublishAt == null) return true;
+  const end = instant(row.unpublishAt);
+  return end !== null && now < end;
+}
+
+/**
+ * The version the public may read, or null when this page is not public.
+ *
+ * Visible at `publishAt` to the millisecond; hidden at `unpublishAt` to the
+ * millisecond, so a window is closed at the instant it ends rather than one
+ * tick later.
+ */
+export function publicVersionId(
+  rows: readonly PublicationWindow[],
+  now: number = Date.now(),
+): string | null {
+  const governing = governingPublication(rows, now);
+  if (!governing || !isOpen(governing, now)) return null;
+  return governing.versionId ?? null;
+}
+
+/**
+ * What the backoffice should say about this page, in the visitor's terms.
+ *
+ * `pages.status` cannot answer this and never could: it is one editor's note
+ * about whether the page is finished. These five states come from the same
+ * rows and the same rule the public reader uses, so a page the screen calls
+ * published is a page a visitor can open, and a page it calls hidden is one
+ * they cannot.
+ */
+export type PublicationState =
+  /** Nothing open and nothing scheduled — invisible until somebody publishes. */
+  | "draft"
+  /** Invisible now; a window opens later. */
+  | "scheduled"
+  /** Public, with no end date. */
+  | "published"
+  /** Public now, and already scheduled to disappear. */
+  | "ending"
+  /** Was public; the window has closed and nothing else is scheduled. */
+  | "expired";
+
+export function publicationStateAt(
+  rows: readonly PublicationWindow[],
+  now: number = Date.now(),
+): PublicationState {
+  const governing = governingPublication(rows, now);
+  if (governing && isOpen(governing, now)) {
+    return governing.unpublishAt ? "ending" : "published";
+  }
+  /*
+   * Not public. Which kind of hidden matters to the editor: "not yet" and "not
+   * any more" call for different actions, and neither is the "never published"
+   * a status column would report for all three.
+   */
+  const waiting = rows.some((row) => {
+    const at = instant(row.publishAt);
+    return at !== null && at > now;
+  });
+  if (waiting) return "scheduled";
+  return governing ? "expired" : "draft";
+}
+
+/** Can a visitor open this page right now? */
+export function isPubliclyVisible(state: PublicationState): boolean {
+  return state === "published" || state === "ending";
+}
+
+export const PUBLICATION_STATE_LABELS: Record<PublicationState, string> = {
+  draft: "Hidden",
+  scheduled: "Scheduled to publish",
+  published: "Published",
+  ending: "Scheduled to hide",
+  expired: "Hidden after expiry",
+};
+
+/** Longer wording for tooltips and screen-reader descriptions. */
+export const PUBLICATION_STATE_DESCRIPTIONS: Record<PublicationState, string> = {
+  draft: "Not visible on the public website. Staff can still edit and preview it.",
+  scheduled: "Not visible yet. It appears by itself when its publication window opens.",
+  published: "Visible on the public website right now.",
+  ending: "Visible now, and scheduled to disappear when its window closes.",
+  expired: "Not visible any more — its publication window has closed.",
+};
+
+/**
+ * What happens at the next boundary — not merely when it happens.
+ *
+ * A single state plus a date cannot say what a page with a replacement lined up
+ * is doing. "Live until the 20th, with version 4 taking over on the 10th" came
+ * out as `ending` with the 10th attached, which the badge then read aloud as
+ * "Scheduled to hide — September 10": the one day the page is certainly *not*
+ * hidden. Worse the other way round, an open-ended publication with a
+ * replacement due showed a plain "Published" and said nothing about the update
+ * at all.
+ *
+ * So the two questions are answered separately. {@link publicationStateAt} says
+ * what a visitor gets now; this says what changes next and into what.
+ */
+export type PublicationTransitionKind =
+  /** A hidden page becomes public. */
+  | "publish"
+  /** A public page stays public, showing a different version. */
+  | "replace"
+  /** A public page becomes hidden. */
+  | "hide";
+
+export type PublicationTransition = {
+  kind: PublicationTransitionKind;
+  /** When it happens, in milliseconds since the epoch. */
+  at: number;
+  /** The version the page shows afterwards; null for a hide. */
+  versionId: string | null;
+};
+
+/**
+ * The next change to this page's public answer, or null when nothing is due.
+ *
+ * Two things can change it: a window that has not opened yet, and the end of
+ * the one governing now. Whichever comes first wins, and a start that lands
+ * exactly on an end wins the tie — at that instant the newer row is the one
+ * that governs, so the page carries on with the new version rather than
+ * blinking out of existence.
+ */
+export function nextPublicationTransition(
+  rows: readonly PublicationWindow[],
+  now: number = Date.now(),
+): PublicationTransition | null {
+  let start: { at: number; row: PublicationWindow } | null = null;
+  for (const row of rows) {
+    const at = instant(row.publishAt);
+    if (at === null || at <= now) continue;
+    if (start === null || at < start.at) start = { at, row };
+  }
+
+  const governing = governingPublication(rows, now);
+  const live = governing !== null && isOpen(governing, now);
+  const end = live ? instant(governing.unpublishAt) : null;
+  const hideAt = end !== null && end > now ? end : null;
+
+  if (start !== null && (hideAt === null || start.at <= hideAt)) {
+    return {
+      kind: live ? "replace" : "publish",
+      at: start.at,
+      versionId: start.row.versionId ?? null,
+    };
+  }
+  if (hideAt !== null) return { kind: "hide", at: hideAt, versionId: null };
+  return null;
+}
+
+/**
+ * The next instant this page's public answer can change, or null when nothing
+ * is scheduled and it will go on saying the same thing indefinitely.
+ *
+ * How long an answer may be cached — the reason a twenty-second cache cannot
+ * outlive a publication.
+ */
+export function nextPublicationBoundary(
+  rows: readonly PublicationWindow[],
+  now: number = Date.now(),
+): number | null {
+  return nextPublicationTransition(rows, now)?.at ?? null;
+}
+
+/**
+ * What a badge should say, given both answers.
+ *
+ * A replacement is neither a publish nor a hide, and saying either of those is
+ * worse than saying nothing: an editor who reads "Scheduled to hide" on a page
+ * that will still be there tomorrow republishes it for no reason, and one who
+ * reads a bare "Published" on a page about to change under them never learns
+ * there is an update queued at all.
+ */
+export function publicationSummary(
+  state: PublicationState,
+  transition: PublicationTransitionKind | null | undefined,
+): { label: string; description: string; showsAt: boolean } {
+  if (transition === "replace") {
+    return {
+      label: "Published — update scheduled",
+      description:
+        "Visible on the public website right now. A newer version is scheduled " +
+        "to take over; the page does not disappear.",
+      showsAt: true,
+    };
+  }
+  return {
+    label: PUBLICATION_STATE_LABELS[state],
+    description: PUBLICATION_STATE_DESCRIPTIONS[state],
+    showsAt: state === "scheduled" || state === "ending",
+  };
+}
+
+/**
+ * Longest a single timer is trusted for.
+ *
+ * `setTimeout` overflows past about 24.8 days and fires at once, so a page
+ * scheduled for next year would refetch in a loop. Anything further away than
+ * this is waited for in stages, and the clock is re-read each time — which also
+ * keeps a screen left open over a laptop's sleep from waking up with a timer
+ * measured against a clock that has moved on.
+ */
+export const MAX_BOUNDARY_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * How long to wait before re-reading a page whose next boundary is `at`.
+ *
+ * Null when there is nothing to wait for. Zero when the boundary has already
+ * passed, so a screen that was open across it corrects itself immediately
+ * rather than at the next navigation.
+ */
+export function boundaryTimeoutMs(
+  at: string | number | null | undefined,
+  now: number = Date.now(),
+): number | null {
+  if (at == null) return null;
+  const when = typeof at === "number" ? at : instant(at);
+  if (when === null) return null;
+  return Math.max(0, Math.min(MAX_BOUNDARY_TIMEOUT_MS, when - now));
+}
+
+/**
+ * First wait after a boundary refresh that has not yet changed anything.
+ *
+ * A boundary that has passed makes `boundaryTimeoutMs` return zero, and it goes
+ * on returning zero until fresh data moves the boundary — which is a network
+ * round trip away, and may never arrive at all if the read fails. Re-arming on
+ * that zero is a refetch loop with no delay in it, so the wait after a refresh
+ * has been asked for comes from here instead.
+ */
+export const BOUNDARY_RETRY_MIN_MS = 30_000;
+
+/** Longest wait between those retries; a stale screen still recovers. */
+export const BOUNDARY_RETRY_MAX_MS = 5 * 60 * 1000;
+
+/**
+ * How long to wait before asking again, after `attempt` refreshes have been
+ * issued for a boundary that is still in the past.
+ *
+ * Doubling, capped. The first attempt is the ordinary case — the answer is in
+ * flight and about to arrive — and the cap is what keeps a screen whose host
+ * is down from turning into a poll every 30 seconds forever, while still
+ * recovering within five minutes of the host coming back.
+ */
+export function boundaryRetryMs(attempt: number): number {
+  const n = Math.max(1, Math.floor(attempt));
+  return Math.min(BOUNDARY_RETRY_MAX_MS, BOUNDARY_RETRY_MIN_MS * 2 ** (n - 1));
+}
+
+/**
+ * How long a cached public answer may still be served.
+ *
+ * `revalidateAt` is the boundary above, carried back from the server; the
+ * default is the ordinary freshness window a site is happy with. A missing
+ * boundary means nothing is scheduled, so the default stands.
+ *
+ * A page that is not public has no boundary to offer — there is no row to read
+ * one from — so a missing page is never cached. That costs a query on the rare
+ * 404 and buys the guarantee that a page appears the moment its window opens.
+ */
+export function publishedStaleTime(
+  revalidateAt: string | number | null | undefined,
+  defaultMs: number,
+  now: number = Date.now(),
+): number {
+  if (revalidateAt == null) return defaultMs;
+  const at = typeof revalidateAt === "number" ? revalidateAt : instant(revalidateAt);
+  if (at === null) return defaultMs;
+  return Math.max(0, Math.min(defaultMs, at - now));
+}
+
+/**
+ * The same ceiling for a fetched page, including the case where there is none.
+ *
+ * A page that is not public carries no boundary — there is no open row to read
+ * one from — so it is never held: the answer "no such page" must give way the
+ * instant a window opens, and the query that discovers that costs one round
+ * trip on a route nobody is looking at anyway.
+ */
+export function publishedPageStaleTime(
+  page: { revalidateAt?: string | null } | null | undefined,
+  defaultMs: number,
+  now: number = Date.now(),
+): number {
+  if (page == null) return 0;
+  return publishedStaleTime(page.revalidateAt, defaultMs, now);
+}

package/src/cms/page-status.ts

@@ -0,0 +1,152 @@
+/**
+ * The editorial status of a page: the vocabulary and the slug rules around it.
+ *
+ * `pages.status` records the last editorial decision somebody made about a
+ * page — publish it, or take it back to a draft. It does **not** say whether a
+ * visitor can reach the page, and no screen may present it as if it did: a
+ * draft whose scheduled window has opened is on the public website, and a
+ * published page whose window has closed is not. Publication rows answer that
+ * question, through `publicationStateAt` in `cms/page-publication`, and the
+ * backoffice shows both — what visitors get, and what an editor last decided.
+ *
+ * There is no one-click publish toggle anywhere in the UI: both directions are
+ * confirmed, using the wording below so every screen asks the same question.
+ */
+
+import type { PublicationState, PublicationTransitionKind } from "./page-publication";
+
+export const PAGE_STATUSES = ["draft", "published"] as const;
+export type PageStatus = (typeof PAGE_STATUSES)[number];
+
+/** New pages start unpublished. Duplicates do too, whatever the source was. */
+export const DEFAULT_PAGE_STATUS: PageStatus = "draft";
+
+/** Read an untrusted status column. Anything unknown is treated as a draft. */
+export function normalizePageStatus(raw: unknown): PageStatus {
+  return raw === "published" ? "published" : "draft";
+}
+
+export const PAGE_STATUS_LABELS: Record<PageStatus, string> = {
+  draft: "Draft",
+  published: "Published",
+};
+
+/**
+ * What each editorial status means — and, just as importantly, what it does not
+ * mean. Screens show these next to the page's actual public state, never
+ * instead of it.
+ */
+export const PAGE_STATUS_DESCRIPTIONS: Record<PageStatus, string> = {
+  draft:
+    "Editorial status: the last decision was to keep this page as a draft. " +
+    "It does not decide what visitors see — a scheduled publication window can " +
+    "still make a draft public.",
+  published:
+    "Editorial status: the last decision was to publish this page. " +
+    "It does not decide what visitors see — a page whose publication window has " +
+    "closed is published and still unreachable.",
+};
+
+/** Confirmation copy. Both directions ask; neither is a silent toggle. */
+export const PUBLISH_CONFIRMATION =
+  "Are you sure you want to publish this page? It will become visible on the public website.";
+export const UNPUBLISH_CONFIRMATION =
+  "Are you sure you want to unpublish this page? It will no longer be visible on the public website.";
+/** Publishing over a window that has not opened yet cancels the schedule. */
+export const PUBLISH_OVER_SCHEDULE_CONFIRMATION =
+  "This page is already scheduled to appear on its own. Publishing now makes it " +
+  "visible immediately and cancels that schedule. Are you sure?";
+/** Unpublishing something that is only public because of a window. */
+export const UNPUBLISH_SCHEDULED_CONFIRMATION =
+  "Are you sure you want to unpublish this page? It is visible on the public " +
+  "website right now, and unpublishing also cancels the window it is showing in.";
+/** Publishing over an update that is already queued to take over. */
+export const PUBLISH_OVER_REPLACEMENT_CONFIRMATION =
+  "An updated version of this page is already scheduled to take over. Publishing " +
+  "now makes the current draft visible immediately and cancels that update. " +
+  "Are you sure?";
+/** Unpublishing a page that has something scheduled behind it. */
+export const UNPUBLISH_OVER_SCHEDULE_CONFIRMATION =
+  "Are you sure you want to unpublish this page? It also cancels the publication " +
+  "already scheduled for it, which will not happen by itself afterwards.";
+
+/**
+ * The question to ask before a status change, from what a visitor gets now and
+ * what was going to happen next.
+ *
+ * Both directions retire every active publication row, scheduled ones
+ * included — an editor pressing Publish to fix a typo should not silently
+ * throw away the update a colleague queued for Monday. The wording lives here
+ * so the pages list and the builder ask the same question about the same page.
+ */
+export function statusChangeConfirmation(
+  next: PageStatus,
+  publication: PublicationState,
+  transition: PublicationTransitionKind | null | undefined,
+): string {
+  /*
+   * A queued transition is one that publishing or unpublishing now would throw
+   * away. `transition` is the precise answer; where a host has not been updated
+   * to send it, "scheduled" means exactly "a publish is queued and nothing is
+   * live", so the older field answers the same question for that one state.
+   */
+  const queued =
+    transition === "publish" ||
+    transition === "replace" ||
+    (transition == null && publication === "scheduled");
+  if (next === "published") {
+    if (transition === "replace") return PUBLISH_OVER_REPLACEMENT_CONFIRMATION;
+    if (queued) return PUBLISH_OVER_SCHEDULE_CONFIRMATION;
+    return PUBLISH_CONFIRMATION;
+  }
+  if (queued) return UNPUBLISH_OVER_SCHEDULE_CONFIRMATION;
+  return publication === "ending" ? UNPUBLISH_SCHEDULED_CONFIRMATION : UNPUBLISH_CONFIRMATION;
+}
+
+/**
+ * A page key from free text, following the existing rule: lowercase letters,
+ * digits, dash and underscore (`/^[a-z0-9_-]+$/`, as `cmsKey` enforces).
+ */
+export function slugifyPageKey(input: string): string {
+  return input
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+/** True when a key satisfies the platform's page-key rule. */
+export function isValidPageKey(key: string): boolean {
+  return /^[a-z0-9_-]+$/.test(key);
+}
+
+/**
+ * A key not already taken. `about-us` becomes `about-us-2`, then `-3`, and so
+ * on — the same shape `uniqueFileName` uses for media, so the two read alike.
+ */
+export function uniquePageKey(base: string, taken: Iterable<string>): string {
+  const used = new Set(taken);
+  const seed = slugifyPageKey(base) || "page";
+  if (!used.has(seed)) return seed;
+  for (let n = 2; n < 1000; n += 1) {
+    const candidate = `${seed}-${n}`;
+    if (!used.has(candidate)) return candidate;
+  }
+  return `${seed}-${Date.now()}`;
+}
+
+/**
+ * The name a duplicate is proposed with, e.g. "About us (copy)".
+ *
+ * Copying a copy counts up rather than stacking suffixes, so the third copy is
+ * "About us (copy) 3" and never "About us (copy) 2 (copy)".
+ */
+export function duplicateNameFor(name: string): string {
+  const trimmed = name.trim() || "Page";
+  const repeat = /^(.*\(copy\))(?: (\d+))?$/.exec(trimmed);
+  if (repeat) return `${repeat[1]} ${Number(repeat[2] ?? "1") + 1}`;
+  return `${trimmed} (copy)`;
+}