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

package/src/cloud/connection.ts

@@ -0,0 +1,281 @@
+import {
+  CloudError,
+  changeAccess,
+  editsAnything,
+  encodeChange,
+  fileAccess,
+  fromBase64,
+  wholeSite,
+  type CloudClient,
+  type CloudUser,
+  type CommitTrailers,
+  type DeployStatus,
+  type Draft,
+  type HoldResponse,
+  type Manifest,
+  type Member,
+  type PublishResponse,
+  type Review,
+  type ScheduleResponse,
+} from '@vespercms/core';
+import { ApiError, type StudioApi } from '../app/api.ts';
+import { createBrowserApi } from '../app/browser-api.ts';
+import { keyValueStore } from '../app/idb.ts';
+import type { CloudSettings } from './session.ts';
+import { CloudStorage } from './storage.ts';
+
+/*
+ * The studio connected to the cloud (spec §6.9): its back end, the drafts
+ * and reviews screens subscribe to, and what the signed-in member may do.
+ * Screens find it on the studio as `cloud`; when it's absent, every cloud
+ * feature is absent too, never disabled (spec §6.9).
+ */
+
+export type CloudConnection = {
+  user: CloudUser;
+  member: Member;
+  siteName: string;
+  dashboardUrl: string;
+  client: CloudClient;
+  storage: CloudStorage;
+  drafts: DraftsStore;
+  /** What the member may do to a file. */
+  access: (path: string) => { edit: boolean; publish: boolean };
+  /** What the member may do with a whole draft: the API refuses the same (spec §7.5). */
+  draftAccess: (draft: Draft) => { edit: boolean; publish: boolean };
+  /** True when the member's grants cover the whole site (the redirects, settings outside collections). */
+  wholeSite: boolean;
+  /** True when the member may change anything at all. */
+  editsAnything: boolean;
+};
+
+export type DraftsSnapshot = {
+  drafts: readonly Draft[];
+  reviews: readonly Review[];
+  version: string;
+  /**
+   * How the site publishes on schedule, and where each change stands (spec
+   * §6.17). Absent on a site with no scheduled collection, or until read.
+   */
+  schedule?: ScheduleResponse;
+};
+
+/** Drafts and reviews as screens see them, kept current after every change. */
+export class DraftsStore {
+  private snapshot: DraftsSnapshot = { drafts: [], reviews: [], version: '' };
+  private readonly listeners = new Set<() => void>();
+  private readonly client: CloudClient;
+  private readonly storage: CloudStorage;
+  private readonly scheduled: boolean;
+
+  /** `scheduled`: the site has a scheduled collection, so the schedule is read with the drafts. */
+  constructor(client: CloudClient, storage: CloudStorage, scheduled = false) {
+    this.client = client;
+    this.storage = storage;
+    this.scheduled = scheduled;
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  get = (): DraftsSnapshot => this.snapshot;
+
+  /** Called by the storage whenever the drafts change. */
+  setDrafts(drafts: readonly Draft[], version: string): void {
+    this.snapshot = { ...this.snapshot, drafts, version };
+    this.emit();
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) listener();
+  }
+
+  /** Asks the cloud for the drafts and reviews again, and the schedule where the site has one. */
+  async refresh(): Promise<void> {
+    this.storage.invalidate();
+    const [{ drafts, version }, { reviews }, schedule] = await Promise.all([
+      this.storage.drafts(),
+      this.client.reviews(),
+      // The schedule only adds words; without it, scheduling works as in GitHub mode.
+      this.scheduled
+        ? this.client.schedule().catch(() => this.snapshot.schedule)
+        : Promise.resolve(undefined),
+    ]);
+    this.snapshot = { drafts, reviews, version, ...(schedule ? { schedule } : {}) };
+    this.emit();
+  }
+
+  /** The draft holding a file, if one does. */
+  draftOf(path: string): Draft | undefined {
+    return this.snapshot.drafts.find((d) => d.files.some((f) => f.path === path));
+  }
+
+  async publish(ids: readonly string[]): Promise<PublishResponse> {
+    const result = await this.client.publish(ids);
+    await this.refresh();
+    return result;
+  }
+
+  async discard(id: string): Promise<void> {
+    await this.client.discardDraft(id);
+    await this.refresh();
+  }
+
+  async keepMine(id: string, paths: readonly string[]): Promise<void> {
+    await this.client.rebaseDraft(id, paths);
+    await this.refresh();
+  }
+
+  async requestReview(ids: readonly string[], note: string): Promise<Review> {
+    const review = await this.client.requestReview({ drafts: [...ids], ...(note ? { note } : {}) });
+    await this.refresh();
+    return review;
+  }
+
+  async answer(id: string, action: 'comment' | 'request-changes', body: string): Promise<Review> {
+    const review = await this.client.answerReview(id, { action, body });
+    await this.refresh();
+    return review;
+  }
+
+  status(commit: string): Promise<DeployStatus> {
+    return this.client.status(commit);
+  }
+
+  /** Holds drafts in the cloud until `at`, to be published then (`holdScheduledDrafts`). */
+  async hold(ids: readonly string[], at: Date): Promise<HoldResponse> {
+    const result = await this.client.hold(ids, at.toISOString());
+    await this.refresh();
+    return result;
+  }
+
+  /** A held draft stops waiting, and stays a draft. */
+  async release(event: string): Promise<void> {
+    await this.client.release(event);
+    await this.refresh();
+  }
+
+  /**
+   * Cancels a published entry's time to go live (call 9): one publish takes
+   * its file out of the site, and its content comes back as a draft. The
+   * file isn't live yet, so visitors see no change.
+   */
+  async backToDraft(
+    path: string,
+    message: { summary: string; trailers?: CommitTrailers },
+  ): Promise<{ ok: true } | { ok: false; message: string }> {
+    const words = (result: { ok: false; reason: string; message?: string }) =>
+      result.message ?? 'Someone changed it since you opened it. Reload to see the new version.';
+    const version = (await this.client.tree()).entries.find((e) => e.path === path)?.version;
+    if (!version)
+      return { ok: false, message: 'It isn’t published, so there’s nothing to cancel.' };
+    const text = (await this.client.blobs([version])).blobs[version];
+    if (text === undefined) return { ok: false, message: 'Its text couldn’t be read. Try again.' };
+    const removal = await this.client.saveDraft({
+      changes: [{ op: 'delete', path, expectedVersion: version }],
+      message,
+    });
+    if (!removal.ok) {
+      await this.refresh();
+      return { ok: false, message: words(removal) };
+    }
+    const published = removal.draft ? await this.client.publish([removal.draft.id]) : null;
+    if (!published?.ok) {
+      if (removal.draft) await this.client.discardDraft(removal.draft.id);
+      await this.refresh();
+      return { ok: false, message: published ? words(published) : 'Nothing changed.' };
+    }
+    const kept = await this.client.saveDraft({
+      changes: [encodeChange({ op: 'put', path, bytes: fromBase64(text), expectedVersion: null })],
+      message,
+    });
+    await this.refresh();
+    return kept.ok
+      ? { ok: true }
+      : {
+          ok: false,
+          message: `It’s off the site, but its draft couldn’t be saved: ${words(kept)} It’s in the site’s history.`,
+        };
+  }
+}
+
+/** The cloud's errors in the studio's terms: plain words, and a status the screens understand. */
+export function cloudApiError(error: unknown, onExpired?: () => void): unknown {
+  if (error instanceof CloudError) {
+    if (error.status === 401) {
+      onExpired?.();
+      return new ApiError(401, 'Your Vesper sign-in has ended. Sign in again to keep working.');
+    }
+    return new ApiError(error.status, error.message);
+  }
+  if (error instanceof TypeError) {
+    return new ApiError(0, 'Vesper can’t be reached. Your changes are kept on this device.');
+  }
+  return error;
+}
+
+export type ConnectOptions = {
+  settings: CloudSettings;
+  client: CloudClient;
+  user: CloudUser;
+  member: Member;
+  siteName: string;
+  manifest: Manifest;
+  loadMdxProps: () => Promise<Readonly<Record<string, unknown>>>;
+  loadUrlFunctions?: Parameters<typeof createBrowserApi>[0]['loadUrlFunctions'];
+  routes?: readonly (readonly [string, string])[];
+  onExpired?: () => void;
+};
+
+/** The studio's back end over the cloud, and the connection screens use. */
+export function connect(options: ConnectOptions): { api: StudioApi; connection: CloudConnection } {
+  let store: DraftsStore | null = null;
+  const storage = new CloudStorage({
+    client: options.client,
+    cache: keyValueStore<Uint8Array>('vesper-cloud-blobs', 'blobs'),
+    onDrafts: (drafts, version) => store?.setDrafts(drafts, version),
+  });
+  store = new DraftsStore(
+    options.client,
+    storage,
+    options.manifest.collections.some((c) => c.presentation.schedule),
+  );
+  const api = createBrowserApi({
+    storage,
+    manifest: options.manifest,
+    schemas: options.settings.schemas,
+    loadMdxProps: options.loadMdxProps,
+    ...(options.loadUrlFunctions ? { loadUrlFunctions: options.loadUrlFunctions } : {}),
+    ...(options.routes ? { routes: options.routes } : {}),
+    publishesOnSave: false,
+    mapError: (error) => cloudApiError(error, options.onExpired),
+  });
+  const member = options.member;
+  const connection: CloudConnection = {
+    user: options.user,
+    member,
+    siteName: options.siteName,
+    dashboardUrl: `${options.settings.app.replace(/\/+$/, '')}/sites/${encodeURIComponent(options.settings.project)}`,
+    client: options.client,
+    storage,
+    drafts: store,
+    access: (path) => fileAccess(member, options.manifest, path),
+    draftAccess: (draft) => {
+      const result = changeAccess(
+        member,
+        options.manifest,
+        draft.files.map((file) =>
+          file.op === 'delete'
+            ? { op: 'delete', path: file.path, expectedVersion: file.base }
+            : { op: 'put', path: file.path, bytes: new Uint8Array(), expectedVersion: file.base },
+        ),
+      );
+      return result.ok ? { edit: true, publish: result.publish } : { edit: false, publish: false };
+    },
+    wholeSite: wholeSite(member),
+    editsAnything: editsAnything(member),
+  };
+  return { api, connection };
+}

package/src/cloud/editor.tsx

@@ -0,0 +1,250 @@
+import {
+  decodeUtf8,
+  fromBase64,
+  type DeployStatus,
+  type Draft,
+  type Review,
+} from '@vespercms/core';
+import { Button, Dialog, Link, TextArea } from '@vespercms/ui';
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import { useStudio } from '../app/context.tsx';
+import { keyValueStore } from '../app/idb.ts';
+import type { CloudConnection, DraftsSnapshot } from './connection.ts';
+
+/*
+ * The cloud's parts of the entry editor (spec §7.4): the entry's draft and
+ * its review, deploy status after a publish, the side-by-side compare for a
+ * conflict, and the review request. The editor itself stays one screen for
+ * every mode; these appear only when the studio is connected (spec §6.9).
+ */
+
+const EMPTY: DraftsSnapshot = { drafts: [], reviews: [], version: '' };
+const noSubscribe = () => () => undefined;
+
+/** The drafts and reviews, current after every change. Empty when not connected. */
+export function useDrafts(): DraftsSnapshot {
+  const cloud = useStudio().cloud;
+  return useSyncExternalStore(
+    cloud ? cloud.drafts.subscribe : noSubscribe,
+    cloud ? cloud.drafts.get : () => EMPTY,
+  );
+}
+
+/** The draft holding a file, and the review that draft waits in. */
+export function useEntryDraft(path: string): {
+  draft: Draft | undefined;
+  review: Review | undefined;
+} {
+  const { drafts, reviews } = useDrafts();
+  const draft = drafts.find((d) => d.files.some((f) => f.path === path));
+  const review = draft?.review ? reviews.find((r) => r.id === draft.review) : undefined;
+  return { draft, review };
+}
+
+/** What the host reported for a published commit, asked again until the build is done. */
+export function useDeployStatus(commit: string | null): DeployStatus | null {
+  const cloud = useStudio().cloud;
+  const [status, setStatus] = useState<DeployStatus | null>(null);
+  useEffect(() => {
+    if (!cloud || !commit) return;
+    let live = true;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let tries = 0;
+    const ask = async () => {
+      const next = await cloud.drafts.status(commit).catch(() => null);
+      if (!live) return;
+      if (next) setStatus(next);
+      // A build takes minutes; asking every 10 seconds for 15 minutes covers most hosts.
+      if ((!next || next.state === 'building' || next.state === 'unknown') && ++tries < 90) {
+        timer = setTimeout(() => void ask(), 10_000);
+      }
+    };
+    void ask();
+    return () => {
+      live = false;
+      clearTimeout(timer);
+    };
+  }, [cloud, commit]);
+  return status;
+}
+
+/** The plain sentence after a publish (spec §6.16): building, live, failed, or nothing reported. */
+export function DeployLine({ commit }: { commit: string }) {
+  const status = useDeployStatus(commit);
+  const state = status?.state ?? 'unknown';
+  const text =
+    state === 'live'
+      ? 'Published. It’s live on the site.'
+      : state === 'failed'
+        ? 'Published, but the site’s build failed, so it isn’t live yet.'
+        : state === 'building'
+          ? 'Published. The site is building now.'
+          : 'Published. It will be live after the site is next built.';
+  return (
+    <p className="text-small text-content-muted">
+      {text}
+      {status?.url && state !== 'unknown' && (
+        <>
+          {' '}
+          <Link href={status.url} target="_blank" rel="noopener">
+            {state === 'failed' ? 'See what went wrong' : 'See the build'}
+          </Link>
+        </>
+      )}
+    </p>
+  );
+}
+
+/** A file's text at a version, through the cloud. */
+async function textAt(cloud: CloudConnection, version: string | null): Promise<string> {
+  if (!version) return '';
+  const { blobs } = await cloud.client.blobs([version]);
+  const found = blobs[version];
+  return found === undefined ? '' : (decodeUtf8(fromBase64(found)) ?? '');
+}
+
+/**
+ * A change published since the draft began (spec §7.4): the published file
+ * and the draft side by side, and the editor's choice. Nothing is
+ * overwritten silently.
+ */
+export function ConflictCompare({
+  path,
+  draft,
+  publishedVersion,
+  onKeep,
+  onDiscard,
+}: {
+  path: string;
+  draft: Draft;
+  publishedVersion: string | null;
+  onKeep: () => void;
+  onDiscard: () => void;
+}) {
+  const cloud = useStudio().cloud;
+  const [texts, setTexts] = useState<{ published: string; mine: string } | null>(null);
+  const file = draft.files.find((f) => f.path === path);
+  const mineVersion = file?.op === 'put' ? file.version : null;
+  useEffect(() => {
+    if (!cloud) return;
+    let live = true;
+    void Promise.all([textAt(cloud, publishedVersion), textAt(cloud, mineVersion)]).then(
+      ([published, mine]) => {
+        if (live) setTexts({ published, mine });
+      },
+      () => {
+        if (live) setTexts({ published: '', mine: '' });
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [cloud, publishedVersion, mineVersion]);
+  return (
+    <section
+      aria-labelledby="conflict-title"
+      className="flex flex-col gap-4 rounded-md border border-danger bg-surface-raised p-4"
+    >
+      <h2 id="conflict-title" className="m-0 text-heading-3 text-content">
+        Someone published this entry since your draft began
+      </h2>
+      <p className="m-0">
+        Nothing was published. Compare the two, then keep your draft (it replaces theirs when you
+        publish) or use theirs.
+      </p>
+      {texts ? (
+        <div className="grid gap-4 md:grid-cols-2">
+          <CompareColumn title="Published now" text={texts.published} />
+          <CompareColumn title="Your draft" text={texts.mine} />
+        </div>
+      ) : (
+        <p role="status" className="m-0 text-content-muted">
+          Loading both versions…
+        </p>
+      )}
+      <div className="flex flex-wrap gap-3">
+        <Button onPress={onKeep}>Keep my draft</Button>
+        <Button onPress={onDiscard}>Use the published version</Button>
+      </div>
+    </section>
+  );
+}
+
+function CompareColumn({ title, text }: { title: string; text: string }) {
+  return (
+    <div className="flex min-w-0 flex-col gap-2">
+      <h3 className="m-0 text-label text-content">{title}</h3>
+      {/* A scrolling box must be reachable by keyboard to be read (WCAG 2.1.1). */}
+      <pre
+        // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+        tabIndex={0}
+        aria-label={title}
+        className="m-0 max-h-96 overflow-auto rounded-sm border border-border bg-surface p-3 font-mono text-small whitespace-pre-wrap"
+      >
+        {text}
+      </pre>
+    </div>
+  );
+}
+
+/** Asks for review, with an optional note for the approvers. */
+export function RequestReviewDialog({
+  isOpen,
+  onOpenChange,
+  onSend,
+}: {
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  onSend: (note: string) => Promise<void>;
+}) {
+  const [note, setNote] = useState('');
+  const [sending, setSending] = useState(false);
+  return (
+    <Dialog title="Request review" isOpen={isOpen} onOpenChange={onOpenChange}>
+      <div className="flex flex-col gap-4">
+        <p className="m-0">
+          An approver for this site gets an email, and can publish your changes or ask for more.
+        </p>
+        <TextArea label="Note for the approver (optional)" value={note} onChange={setNote} />
+        <div className="flex flex-wrap justify-end gap-3">
+          <Button
+            onPress={() => {
+              onOpenChange(false);
+            }}
+          >
+            Cancel
+          </Button>
+          <Button
+            variant="primary"
+            isPending={sending}
+            onPress={() => {
+              setSending(true);
+              void onSend(note.trim()).finally(() => {
+                setSending(false);
+                setNote('');
+              });
+            }}
+          >
+            Send for review
+          </Button>
+        </div>
+      </div>
+    </Dialog>
+  );
+}
+
+/**
+ * Unsaved changes kept on this device while the cloud can't be reached
+ * (spec §6.9): written as they're typed, cleared once a draft is saved.
+ */
+export type KeptChanges = { values: unknown; body: string; raw: string };
+
+let keptStore: ReturnType<typeof keyValueStore<KeptChanges>> | null = null;
+export function keptChanges() {
+  keptStore ??= keyValueStore<KeptChanges>('vesper-cloud-unsaved', 'entries');
+  return keptStore;
+}
+
+export function keptKey(project: string, collection: string, id: string | null): string {
+  return `${project}:${collection}:${id ?? '(new)'}`;
+}