@vespercms/admin 0.0.0-stage → 0.1.0-next.0

package/src/schedule/ScheduledView.tsx

@@ -0,0 +1,294 @@
+import {
+  decodeData,
+  encodeValue,
+  scheduleTime,
+  zoneName,
+  type EntryDocument,
+  type ScheduledChange,
+} from '@vespercms/core';
+import { Link, Menu, Table, cx, type TableColumn } from '@vespercms/ui';
+import { useState } from 'react';
+import { useStudio } from '../app/context.tsx';
+import { useLoad } from '../app/load.ts';
+import { entriesChanged } from '../app/entries-changed.ts';
+import { hrefFor } from '../app/router.ts';
+import { Screen } from '../app/Screen.tsx';
+import { entryShownTo } from '../cloud/access.ts';
+import { useDrafts } from '../cloud/editor.tsx';
+import { cloudEventOf, cloudStateWords, holdUntil } from './cloud.ts';
+import { useNow } from './now.ts';
+import { ScheduleDialog } from './ScheduleDialog.tsx';
+import { siteZone, timesOf, withTimes, type ScheduleTimes } from './times.ts';
+
+/*
+ * The Scheduled view (spec §6.17, call 11): every change still to come
+ * across the site, soonest first, read from the files in every mode. It's
+ * a screen reached from Home's line and from a list's Scheduled filter,
+ * never a navigation item. A row's "…" menu reschedules it, and cancels a
+ * time to come down. A publish can't be cancelled where there are no
+ * drafts to go back to (call 9), so it's rescheduled instead; in the
+ * cloud it can, and each change's state shows beside it.
+ */
+
+const COLUMNS: TableColumn[] = [
+  { id: 'at', label: 'When' },
+  { id: 'entry', label: 'Entry', isRowHeader: true },
+  { id: 'change', label: 'Change' },
+  { id: 'collection', label: 'Collection' },
+  { id: 'actions', label: 'Actions' },
+];
+/** Connected to the cloud, where each change stands comes after what it is. */
+const CLOUD_COLUMNS: TableColumn[] = [
+  ...COLUMNS.slice(0, 3),
+  { id: 'state', label: 'State' },
+  ...COLUMNS.slice(3),
+];
+
+type Row = ScheduledChange & { id: string; entryId: string };
+
+export function ScheduledView() {
+  const { api, manifest, cloud } = useStudio();
+  const { schedule: cloudSchedule, drafts } = useDrafts();
+  const [load, reload] = useLoad(() => api.listScheduled(), 'scheduled');
+  const { zone, isSite } = siteZone(manifest);
+  const [editing, setEditing] = useState<{ row: Row; doc: EntryDocument } | null>(null);
+  const [outcome, setOutcome] = useState('');
+  const now = useNow();
+  const rows: Row[] =
+    load.state === 'ready'
+      ? load.value
+          .filter((change) => entryShownTo(cloud, change.path))
+          .map((change) => ({
+            ...change,
+            entryId: change.id,
+            id: `${change.collection}/${change.id}/${change.change}`,
+          }))
+      : [];
+  const collectionOf = (name: string) => manifest.collections.find((c) => c.name === name);
+  const mayChange = (row: Row) =>
+    collectionOf(row.collection)?.editable === true && (cloud?.access(row.path).edit ?? true);
+
+  /** Saves new times into the entry; in the cloud, publishes the draft where the member may. */
+  const apply = async (row: Row, doc: EntryDocument, times: ScheduleTimes, done: string) => {
+    const collection = collectionOf(row.collection);
+    if (!collection) return;
+    setOutcome('');
+    const next = withTimes(collection, decodeData(doc.data), times);
+    const result = await api.saveEntry({
+      collection: row.collection,
+      id: row.entryId,
+      version: doc.version,
+      data: encodeValue(next),
+    });
+    if (!result.ok) {
+      setOutcome(
+        `Nothing changed. ${'message' in result ? result.message : 'The entry has problems to fix in its editor first.'}`,
+      );
+      return;
+    }
+    let text = done;
+    if (cloud) {
+      await cloud.drafts.refresh();
+      const draft = cloud.drafts.draftOf(result.path);
+      const until = holdUntil(cloud.drafts.get().schedule, times.publishAt);
+      if (draft && cloud.access(result.path).publish) {
+        const sent = until
+          ? await cloud.drafts.hold([draft.id], until)
+          : await cloud.drafts.publish([draft.id]);
+        if (!sent.ok) text = `${done} It’s saved as a draft, not published yet.`;
+      } else if (draft) text = `${done} It’s saved as a draft for review.`;
+    }
+    entriesChanged(row.collection);
+    setOutcome(text);
+    reload();
+  };
+
+  /** In the cloud, a publish still to come is cancelled: a held draft stops waiting, a published entry goes back to a draft. */
+  const cancelPublish = async (row: Row) => {
+    if (!cloud) return;
+    setOutcome('');
+    const held = cloud.drafts.draftOf(row.path)?.held;
+    if (held) await cloud.drafts.release(held.event);
+    else {
+      const result = await cloud.drafts.backToDraft(row.path, {
+        summary: `Take “${row.title}” off the schedule in ${collectionOf(row.collection)?.label ?? row.collection}`,
+        trailers: { 'Vesper-Collection': row.collection },
+      });
+      if (!result.ok) {
+        setOutcome(`Nothing changed. ${result.message}`);
+        return;
+      }
+    }
+    entriesChanged(row.collection);
+    setOutcome(`“${row.title}” is no longer scheduled. It’s a draft.`);
+    reload();
+  };
+  /** A publish in the cloud can be cancelled when it's held, or published with no draft over it. */
+  const mayCancelPublish = (row: Row) => {
+    if (!cloud || row.change !== 'publish' || !cloud.access(row.path).publish) return false;
+    const draft = cloud.drafts.draftOf(row.path);
+    return !draft || draft.held !== undefined;
+  };
+
+  // Held changes that couldn't be published at their time, in words, for whoever may fix them.
+  const failures = (cloudSchedule?.events ?? []).flatMap((event) => {
+    if (event.state !== 'failed' || !event.held) return [];
+    const draft = drafts.find((d) => event.held?.drafts.includes(d.id));
+    if (!draft || !cloud?.draftAccess(draft).edit) return [];
+    return [
+      {
+        id: event.id,
+        text: `“${draft.summary}”, scheduled for ${scheduleTime(new Date(event.at), zone, now)}, wasn’t published. ${event.message ?? ''}`,
+      },
+    ];
+  });
+
+  const open = async (row: Row) => {
+    setOutcome('');
+    try {
+      setEditing({ row, doc: await api.readEntry(row.collection, row.entryId) });
+    } catch (error) {
+      setOutcome(error instanceof Error ? error.message : String(error));
+    }
+  };
+
+  const editingCollection = editing ? collectionOf(editing.row.collection) : undefined;
+  const editingTimes =
+    editing && editingCollection ? timesOf(editingCollection, decodeData(editing.doc.data)) : {};
+
+  return (
+    <Screen title="Scheduled">
+      <p className="mb-6 max-w-2xl text-content-muted">
+        Changes still to come across the site, soonest first.{' '}
+        {isSite
+          ? `Times are in ${zoneName(zone)}, the site’s time zone.`
+          : `Times are in your time zone, ${zoneName(zone)}.`}
+      </p>
+      {load.state === 'failed' && (
+        <p role="alert" className="mb-6 text-danger">
+          Couldn’t read what’s scheduled: {load.message}
+        </p>
+      )}
+      <p role="status" className={cx('mb-6 max-w-2xl', !outcome && 'sr-only')}>
+        {outcome}
+      </p>
+      {failures.map((failure) => (
+        <p key={failure.id} className="mb-6 max-w-2xl text-danger">
+          {failure.text}
+        </p>
+      ))}
+      {load.state === 'loading' ? (
+        <p className="text-small text-content-muted">Reading the schedule…</p>
+      ) : (
+        <Table
+          label="Scheduled changes"
+          columns={cloudSchedule ? CLOUD_COLUMNS : COLUMNS}
+          rows={rows}
+          emptyState="Nothing is scheduled."
+          renderCell={(row, column) => {
+            if (column === 'at') return scheduleTime(new Date(row.at), zone, now);
+            if (column === 'state' && cloudSchedule) {
+              return cloudStateWords(
+                cloudSchedule,
+                cloudEventOf(cloudSchedule, row),
+                new Date(row.at),
+                zone,
+              );
+            }
+            if (column === 'entry') {
+              return (
+                <Link
+                  href={hrefFor({ screen: 'edit', collection: row.collection, id: row.entryId })}
+                >
+                  {row.title}
+                </Link>
+              );
+            }
+            if (column === 'change') return row.change === 'publish' ? 'Goes live' : 'Comes down';
+            if (column === 'collection')
+              return collectionOf(row.collection)?.label ?? row.collection;
+            if (!mayChange(row)) return null;
+            return (
+              <Menu
+                label={`Actions for ${row.title}, ${row.change === 'publish' ? 'going live' : 'coming down'}`}
+                items={[
+                  { id: 'reschedule', label: 'Reschedule…', icon: 'schedule' },
+                  ...(row.change === 'unpublish'
+                    ? [{ id: 'cancel', label: 'Cancel', icon: 'unschedule' as const }]
+                    : []),
+                  ...(mayCancelPublish(row)
+                    ? [{ id: 'cancel-publish', label: 'Cancel', icon: 'unschedule' as const }]
+                    : []),
+                ]}
+                onAction={(action) => {
+                  if (action === 'reschedule') void open(row);
+                  if (action === 'cancel-publish') void cancelPublish(row);
+                  if (action === 'cancel') {
+                    void api.readEntry(row.collection, row.entryId).then((doc) => {
+                      const collection = collectionOf(row.collection);
+                      if (!collection) return;
+                      const times = timesOf(collection, decodeData(doc.data));
+                      return apply(
+                        row,
+                        doc,
+                        { ...(times.publishAt ? { publishAt: times.publishAt } : {}) },
+                        `“${row.title}” no longer comes down.`,
+                      );
+                    });
+                  }
+                }}
+              />
+            );
+          }}
+        />
+      )}
+      {editing && editingCollection && (
+        <ScheduleDialog
+          isOpen
+          onOpenChange={(open) => {
+            if (!open) setEditing(null);
+          }}
+          collection={editingCollection}
+          initial={editingTimes}
+          live={!(editingTimes.publishAt && editingTimes.publishAt.getTime() > now.getTime())}
+          purpose="publish"
+          nowLabel={api.publishesOnSave() ? 'Publish now' : 'Make it live now'}
+          onSubmit={(times) => {
+            const { row, doc } = editing;
+            void apply(row, doc, times, `“${row.title}” is rescheduled.`);
+          }}
+          onNow={() => {
+            const { row, doc } = editing;
+            const { publishAt: _now, ...rest } = editingTimes;
+            void apply(row, doc, rest, `“${row.title}” goes live at the next build.`);
+          }}
+        />
+      )}
+    </Screen>
+  );
+}
+
+/**
+ * "3 scheduled changes", linking to the Scheduled view: on Home, and among
+ * panes at the top of the collections. Absent when nothing is scheduled.
+ */
+export function ScheduledLine({ className }: { className?: string }) {
+  const { api, manifest, cloud } = useStudio();
+  const scheduled = manifest.collections.some((c) => c.presentation.schedule);
+  const [load] = useLoad(
+    () => (scheduled ? api.listScheduled() : Promise.resolve([])),
+    'scheduled-line',
+  );
+  const count =
+    load.state === 'ready'
+      ? load.value.filter((change) => entryShownTo(cloud, change.path)).length
+      : 0;
+  if (count === 0) return null;
+  return (
+    <p className={cx('m-0 text-small', className)}>
+      <Link href={hrefFor({ screen: 'scheduled' })}>
+        {count === 1 ? '1 scheduled change' : `${String(count)} scheduled changes`}
+      </Link>
+    </p>
+  );
+}

package/src/schedule/cloud.ts

@@ -0,0 +1,66 @@
+import type { CloudScheduledEvent, ScheduleResponse } from '@vespercms/core';
+
+/*
+ * Scheduling connected to the cloud (spec §6.17): exact times, held drafts
+ * and where each change stands. Everything here is absent when the studio
+ * isn't connected (spec §6.9), where the files alone say what's scheduled.
+ */
+
+/** The time of day in the site's zone ("8:00 AM"), for a row whose day is beside it. */
+function clock(at: Date, zone: string): string {
+  return new Intl.DateTimeFormat('en-US', {
+    timeZone: zone,
+    hour: 'numeric',
+    minute: '2-digit',
+  }).format(at);
+}
+
+/** The cloud's own word on a change in the files, matched by file, change and instant. */
+export function cloudEventOf(
+  schedule: ScheduleResponse | undefined,
+  change: { path: string; change: 'publish' | 'unpublish'; at: string },
+): CloudScheduledEvent | undefined {
+  const at = Date.parse(change.at);
+  return schedule?.events.find(
+    (event) =>
+      event.path === change.path && event.change === change.change && Date.parse(event.at) === at,
+  );
+}
+
+/**
+ * Where a change still to come stands, in words: "Waiting in Vesper until
+ * 8:00 AM" for held drafts, "Rebuild at 8:00 AM" with a trigger, and "Next
+ * build after 8:00 AM" without one.
+ */
+export function cloudStateWords(
+  schedule: ScheduleResponse,
+  event: CloudScheduledEvent | undefined,
+  at: Date,
+  zone: string,
+): string {
+  if (event?.state === 'held') return `Waiting in Vesper until ${clock(at, zone)}`;
+  return schedule.trigger ? `Rebuild at ${clock(at, zone)}` : `Next build after ${clock(at, zone)}`;
+}
+
+/**
+ * True when the cloud keeps the time exactly: it asks for a rebuild then,
+ * or it publishes held drafts then, which starts the host's build. Only the
+ * publish waits in the cloud; a time to come down is a plain field.
+ */
+export function cloudKeepsTime(
+  schedule: ScheduleResponse | undefined,
+  change: 'publish' | 'unpublish',
+): boolean {
+  if (!schedule) return false;
+  return schedule.trigger !== null || (change === 'publish' && schedule.holdScheduledDrafts);
+}
+
+/** When the cloud should hold a draft rather than publish it: the site holds, and its time is still to come. */
+export function holdUntil(
+  schedule: ScheduleResponse | undefined,
+  publishAt: Date | undefined,
+  now: Date = new Date(),
+): Date | null {
+  if (!schedule?.holdScheduledDrafts || !publishAt) return null;
+  return publishAt.getTime() > now.getTime() ? publishAt : null;
+}

package/src/schedule/now.ts

@@ -0,0 +1,18 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * The time, again each minute, so words that depend on it ("Scheduled ·
+ * …") change on their own once a time passes, and a render stays pure.
+ */
+export function useNow(): Date {
+  const [now, setNow] = useState(() => new Date());
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setNow(new Date());
+    }, 60_000);
+    return () => {
+      clearInterval(timer);
+    };
+  }, []);
+  return now;
+}

package/src/schedule/times.ts

@@ -0,0 +1,133 @@
+import {
+  isoWithOffset,
+  offsetOf,
+  publishWindow,
+  resolveTimeZone,
+  scheduleStatus,
+  type CollectionManifest,
+  type DataObject,
+  type DataValue,
+  type Manifest,
+  type SchedulePresentation,
+} from '@vespercms/core';
+
+/*
+ * An entry's schedule in the studio (spec §6.17): when it goes live, when it
+ * comes down and where visitors go then, read from and written to the fields
+ * its collection's `schedule` names. The words and the times come from core,
+ * so the editor, the lists and the Scheduled view say the same thing.
+ */
+
+/** When an entry goes live and comes down, and where its page sends visitors after. */
+export type ScheduleTimes = { publishAt?: Date; unpublishAt?: Date; redirect?: string };
+
+/** The site's zone, for showing and entering times, or the viewer's own when it has none. */
+export function siteZone(manifest: Manifest): { zone: string; isSite: boolean } {
+  return resolveTimeZone(manifest.site.timeZone);
+}
+
+/** The field that holds where visitors go after, when the collection's schema has one. */
+export function redirectField(collection: CollectionManifest): string | null {
+  const schedule = collection.presentation.schedule;
+  if (!schedule?.unpublish) return null;
+  const name = schedule.unpublishRedirect ?? 'unpublishRedirect';
+  return collection.fields?.some((field) => field.path.length === 1 && field.path[0] === name)
+    ? name
+    : null;
+}
+
+/** The schedule's field names, the redirect's when the schema has it. */
+export function scheduleKeys(collection: CollectionManifest): string[] {
+  const schedule = collection.presentation.schedule;
+  if (!schedule) return [];
+  const redirect = redirectField(collection);
+  return [
+    schedule.publishAt,
+    ...(schedule.unpublish ? [schedule.unpublishAt] : []),
+    ...(redirect ? [redirect] : []),
+  ];
+}
+
+export function timesOf(collection: CollectionManifest, values: DataObject): ScheduleTimes {
+  const { publishAt, unpublishAt } = publishWindow(collection.presentation.schedule, values);
+  const field = redirectField(collection);
+  const redirect = field ? values[field] : undefined;
+  return {
+    ...(publishAt ? { publishAt } : {}),
+    ...(unpublishAt ? { unpublishAt } : {}),
+    ...(typeof redirect === 'string' && redirect.trim() !== '' ? { redirect } : {}),
+  };
+}
+
+/**
+ * The values with these times in place of the old ones: a time left out is
+ * removed. A time stored as a quoted string stays a string, with its offset
+ * written out, as the date-time field keeps it.
+ */
+export function withTimes(
+  collection: CollectionManifest,
+  values: DataObject,
+  times: ScheduleTimes,
+): DataObject {
+  const schedule = collection.presentation.schedule;
+  if (!schedule) return values;
+  const changes = new Map<string, DataValue | undefined>();
+  const put = (key: string, value: DataValue | undefined) => {
+    changes.set(key, value);
+  };
+  const time = (key: string, date: Date | undefined) =>
+    date && typeof values[key] === 'string' ? isoWithOffset(date, offsetOf(date) ?? 0) : date;
+  put(schedule.publishAt, time(schedule.publishAt, times.publishAt));
+  if (schedule.unpublish) put(schedule.unpublishAt, time(schedule.unpublishAt, times.unpublishAt));
+  const field = redirectField(collection);
+  if (field) put(field, times.redirect?.trim() ? times.redirect.trim() : undefined);
+  // A time left out goes; the rest keep their place in the entry's values.
+  const next: DataObject = {};
+  for (const [key, value] of Object.entries(values)) {
+    const changed = changes.has(key) ? changes.get(key) : value;
+    if (changed !== undefined) next[key] = changed;
+  }
+  for (const [key, value] of changes) if (value !== undefined && !(key in next)) next[key] = value;
+  return next;
+}
+
+/** The entry's schedule as status words, or null when there's nothing to say. */
+export function scheduleWords(
+  schedule: SchedulePresentation | undefined,
+  data: DataValue,
+  zone: string,
+  now: Date = new Date(),
+): string | null {
+  return scheduleStatus(schedule, data, now, zone);
+}
+
+/** An entry row's schedule (ISO times) as values under the schedule's field names. */
+export function rowData(
+  schedule: SchedulePresentation | undefined,
+  times: { publishAt?: string; unpublishAt?: string } | undefined,
+): DataObject {
+  if (!schedule || !times) return {};
+  return {
+    ...(times.publishAt ? { [schedule.publishAt]: times.publishAt } : {}),
+    ...(times.unpublishAt ? { [schedule.unpublishAt]: times.unpublishAt } : {}),
+  };
+}
+
+/** Whether a row has a change still to come: it goes live or comes down later. */
+export function hasUpcoming(
+  times: { publishAt?: string; unpublishAt?: string } | undefined,
+  now: Date = new Date(),
+): boolean {
+  const later = (iso: string | undefined) =>
+    iso !== undefined && new Date(iso).getTime() > now.getTime();
+  return later(times?.publishAt) || later(times?.unpublishAt);
+}
+
+/** "every hour", "every 15 minutes", "every 2 hours". */
+export function everyText(minutes: number): string {
+  if (minutes % 60 === 0) {
+    const hours = minutes / 60;
+    return hours === 1 ? 'every hour' : `every ${String(hours)} hours`;
+  }
+  return `every ${String(minutes)} minutes`;
+}