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

package/src/cloud/session.ts

@@ -0,0 +1,289 @@
+import {
+  CloudClient,
+  CloudError,
+  authorizeUrl,
+  createDpopKey,
+  createPkce,
+  type CloudStudioSettings,
+  type CloudTokens,
+  type CloudUser,
+  type Member,
+} from '@vespercms/core';
+import { keyValueStore, type KeyValueStore } from '../app/idb.ts';
+
+/*
+ * Signing in to the cloud (spec §6.9, §7.2): a top-level redirect to the
+ * app's /authorize with PKCE, and back to `/admin/#/callback` with a
+ * one-time code, which the studio exchanges for tokens bound to a key it
+ * made (DPoP). No popup and no third-party cookie (D14).
+ *
+ * The key pair, whose private half can't be read back out, and the tokens
+ * live together in IndexedDB, so a reload or a second tab stays signed in
+ * until the refresh token lapses (DECISIONS.md, "The studio stays signed in
+ * with tokens bound to a key").
+ */
+
+/** The cloud's settings, as the build writes them into the studio. */
+export type CloudSettings = CloudStudioSettings & {
+  /** The site's schemas built for the browser. */
+  schemas: string;
+};
+
+export type StoredSession = {
+  key: CryptoKeyPair;
+  tokens: CloudTokens | null;
+  user?: CloudUser;
+  member?: Member;
+  siteName?: string;
+};
+
+/*
+ * A sign-in in progress is kept by its state in localStorage, so any tab on
+ * the site can finish it. Signing in by email link comes back in the tab the
+ * mail client opened, whose sessionStorage is its own: kept there, the
+ * sign-in was refused as one that didn't start here. A state no tab began is
+ * still refused.
+ */
+const PENDING_PREFIX = 'vesper.cloud.pending.';
+/** Long enough to ask for a sign-in link (15 minutes) and use it. */
+const PENDING_TTL = 30 * 60 * 1000;
+
+type Pending = { state: string; verifier: string; route: string; started: number };
+
+let defaultStore: KeyValueStore<StoredSession> | null = null;
+export function sessionStore(): KeyValueStore<StoredSession> {
+  defaultStore ??= keyValueStore<StoredSession>('vesper-cloud', 'sessions');
+  return defaultStore;
+}
+
+function pendingStorage(): Storage | null {
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function readPending(storage: Storage, key: string): Pending | null {
+  try {
+    return JSON.parse(storage.getItem(key) ?? 'null') as Pending | null;
+  } catch {
+    return null;
+  }
+}
+
+/** Drops sign-ins that never came back, so they don't pile up. */
+function sweepPending(storage: Storage, now: number): void {
+  const keys: string[] = [];
+  for (let i = 0; i < storage.length; i++) {
+    const key = storage.key(i);
+    if (key?.startsWith(PENDING_PREFIX)) keys.push(key);
+  }
+  for (const key of keys) {
+    const pending = readPending(storage, key);
+    if (!pending || !(now - pending.started < PENDING_TTL)) storage.removeItem(key);
+  }
+}
+
+/** The sign-in this state began, once: it leaves storage as it's read. */
+function takePending(state: string | null): Pending | null {
+  const storage = pendingStorage();
+  if (!storage) return null;
+  const now = Date.now();
+  sweepPending(storage, now);
+  if (!state) return null;
+  const key = `${PENDING_PREFIX}${state}`;
+  const pending = readPending(storage, key);
+  storage.removeItem(key);
+  return pending?.state === state ? pending : null;
+}
+
+/** Runs `work` alone among this browser's tabs, where Web Locks exist. */
+function acrossTabs<T>(name: string, work: () => Promise<T>): Promise<T> {
+  const locks = typeof navigator === 'undefined' ? undefined : navigator.locks;
+  return locks ? locks.request(name, work) : work();
+}
+
+/** The stored key, made and kept on first use: a sign-in must exchange its code with the key it started with. */
+export async function sessionKey(
+  project: string,
+  store: KeyValueStore<StoredSession> = sessionStore(),
+): Promise<StoredSession> {
+  const found = await store.get(project);
+  if (found) return found;
+  const session: StoredSession = { key: await createDpopKey(), tokens: null };
+  await store.put(project, session);
+  return session;
+}
+
+/** The studio's own address, which the app sends the browser back to. */
+export function studioAddress(): string {
+  return `${window.location.origin}${window.location.pathname}`;
+}
+
+/** Goes to the app's sign-in. `route` is the studio's hash route to come back to. */
+export async function startCloudSignIn(
+  settings: CloudSettings,
+  route: string,
+  store?: KeyValueStore<StoredSession>,
+): Promise<void> {
+  await sessionKey(settings.project, store);
+  const state = crypto.randomUUID();
+  const { verifier, challenge } = await createPkce();
+  const storage = pendingStorage();
+  if (storage) {
+    const started = Date.now();
+    sweepPending(storage, started);
+    storage.setItem(
+      `${PENDING_PREFIX}${state}`,
+      JSON.stringify({ state, verifier, route, started } satisfies Pending),
+    );
+  }
+  window.location.assign(
+    authorizeUrl(settings, { redirectUri: studioAddress(), state, challenge }),
+  );
+}
+
+/** The callback's parameters, when the app sent the browser back here. */
+export function callbackParams(hash: string = window.location.hash): URLSearchParams | null {
+  const match = /^#\/callback\?(.*)$/.exec(hash);
+  return match ? new URLSearchParams(match[1]) : null;
+}
+
+export type CloudSignedIn = {
+  client: CloudClient;
+  user: CloudUser;
+  member: Member;
+  siteName: string;
+};
+
+export type CloudSignIn =
+  ({ ok: true; route: string } & CloudSignedIn) | { ok: false; message: string };
+
+function clientFor(
+  settings: CloudSettings,
+  session: StoredSession,
+  store: KeyValueStore<StoredSession>,
+  fetcher?: typeof fetch,
+): CloudClient {
+  return new CloudClient({
+    settings,
+    key: session.key,
+    tokens: session.tokens,
+    ...(fetcher ? { fetch: fetcher } : {}),
+    onTokens: (tokens) => {
+      session.tokens = tokens;
+      void store.put(settings.project, session);
+    },
+    latest: async () => (await store.get(settings.project))?.tokens ?? null,
+    exclusive: (work) => acrossTabs(`vesper-cloud-renew:${settings.project}`, work),
+  });
+}
+
+/**
+ * Finishes a sign-in when the app sent the browser back here, or returns
+ * null when it didn't. The code leaves the address either way.
+ */
+export async function finishCloudSignIn(
+  settings: CloudSettings,
+  options: { store?: KeyValueStore<StoredSession>; fetch?: typeof fetch } = {},
+): Promise<CloudSignIn | null> {
+  const params = callbackParams();
+  if (!params) return null;
+  const store = options.store ?? sessionStore();
+  const pending = takePending(params.get('state'));
+  const route = pending?.route && !pending.route.startsWith('#/callback') ? pending.route : '#/';
+  history.replaceState(history.state, '', `${window.location.pathname}${route}`);
+  const error = params.get('error');
+  if (error !== null) {
+    return {
+      ok: false,
+      message:
+        error === 'access_denied'
+          ? 'Your Vesper account doesn’t have access to this site. Ask the site’s admin to invite you.'
+          : 'Vesper didn’t sign you in. Try again.',
+    };
+  }
+  const code = params.get('code');
+  if (!pending || !code) {
+    return { ok: false, message: 'That sign-in didn’t start here. Try again.' };
+  }
+  const session = await sessionKey(settings.project, store);
+  const client = clientFor(settings, session, store, options.fetch);
+  try {
+    const tokens = await client.exchangeCode({
+      code,
+      verifier: pending.verifier,
+      redirectUri: studioAddress(),
+    });
+    Object.assign(session, {
+      user: tokens.user,
+      member: tokens.member,
+      siteName: tokens.site.name,
+    });
+    await store.put(settings.project, session);
+    return {
+      ok: true,
+      route,
+      client,
+      user: tokens.user,
+      member: tokens.member,
+      siteName: tokens.site.name,
+    };
+  } catch (thrown) {
+    return {
+      ok: false,
+      message:
+        thrown instanceof CloudError ? thrown.message : 'Vesper couldn’t be reached. Try again.',
+    };
+  }
+}
+
+export type Resumed =
+  ({ kind: 'signed-in' } & CloudSignedIn) | { kind: 'signed-out' } | { kind: 'unreachable' };
+
+/**
+ * Picks up a sign-in this browser already has. The refresh brings fresh
+ * tokens and the person's current role and grants, which may have changed
+ * in the dashboard since.
+ */
+export async function resumeCloudSession(
+  settings: CloudSettings,
+  options: { store?: KeyValueStore<StoredSession>; fetch?: typeof fetch } = {},
+): Promise<Resumed> {
+  const store = options.store ?? sessionStore();
+  const session = await store.get(settings.project);
+  if (!session?.tokens) return { kind: 'signed-out' };
+  const client = clientFor(settings, session, store, options.fetch);
+  try {
+    const tokens = await client.refresh();
+    Object.assign(session, {
+      user: tokens.user,
+      member: tokens.member,
+      siteName: tokens.site.name,
+    });
+    await store.put(settings.project, session);
+    return {
+      kind: 'signed-in',
+      client,
+      user: tokens.user,
+      member: tokens.member,
+      siteName: tokens.site.name,
+    };
+  } catch (thrown) {
+    if (thrown instanceof CloudError && thrown.status >= 400 && thrown.status < 500) {
+      return { kind: 'signed-out' };
+    }
+    return { kind: 'unreachable' };
+  }
+}
+
+/** Ends the sign-in, here and in the cloud. The key goes too: the next sign-in makes a new one. */
+export async function endCloudSession(
+  settings: CloudSettings,
+  client: CloudClient | null,
+  store: KeyValueStore<StoredSession> = sessionStore(),
+): Promise<void> {
+  await client?.signOut();
+  await store.delete(settings.project);
+}

package/src/cloud/storage.ts

@@ -0,0 +1,212 @@
+import {
+  encodeChange,
+  fromBase64,
+  overlayEntries,
+  type BlobCache,
+  type ChangeSet,
+  type CloudClient,
+  type CommitResult,
+  type Draft,
+  type FileChange,
+  type StorageAdapter,
+  type StorageEntry,
+  type StoredFile,
+} from '@vespercms/core';
+import { gitBlobSha } from '@vespercms/core';
+
+/*
+ * The cloud's storage (spec §7.4): the site as its drafts show it, read
+ * through the cloud's git proxy, and every save a draft rather than a
+ * commit. Core's services run over it unchanged, so a draft is exactly what
+ * a local save would have written (DECISIONS.md, "A draft is the file the
+ * save would write").
+ *
+ * Bytes are read by version (a git blob SHA), from IndexedDB when this
+ * browser has them and otherwise in batches from the API. A SHA always means
+ * the same bytes, so nothing cached goes stale.
+ */
+
+type Waiter = { resolve: (bytes: Uint8Array | null) => void; reject: (error: unknown) => void };
+
+type Snapshot = {
+  commit: string;
+  published: StorageEntry[];
+  drafts: Draft[];
+  draftsVersion: string;
+  at: number;
+};
+
+export type CloudStorageOptions = {
+  client: CloudClient;
+  cache?: BlobCache;
+  /** How long a snapshot of the tree and drafts is trusted. */
+  snapshotTtlMs?: number;
+  /** Told whenever the drafts change, here or as the API reports them. */
+  onDrafts?: (drafts: readonly Draft[], version: string) => void;
+  now?: () => number;
+};
+
+export class CloudStorage implements StorageAdapter {
+  readonly kind = 'cloud' as const;
+  private readonly client: CloudClient;
+  private readonly cache: BlobCache | undefined;
+  private readonly ttl: number;
+  private readonly onDrafts: CloudStorageOptions['onDrafts'];
+  private readonly now: () => number;
+  private snapshotting: Promise<Snapshot> | null = null;
+  private current: Snapshot | null = null;
+  /** New files waiting for the next save (`ChangeSet.defer`): an upload goes out with its entry. */
+  private readonly pending = new Map<string, { bytes: Uint8Array; version: string }>();
+  private wanted = new Map<string, Waiter[]>();
+  private batch: Promise<void> | null = null;
+
+  constructor(options: CloudStorageOptions) {
+    this.client = options.client;
+    this.cache = options.cache;
+    this.ttl = options.snapshotTtlMs ?? 10_000;
+    this.onDrafts = options.onDrafts;
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  /** Forgets the snapshot, so the next read asks the cloud again. */
+  invalidate(): void {
+    this.current = null;
+  }
+
+  private async snapshot(): Promise<Snapshot> {
+    if (this.current && this.now() - this.current.at < this.ttl) return this.current;
+    this.snapshotting ??= (async () => {
+      try {
+        const [tree, drafts] = await Promise.all([this.client.tree(), this.client.drafts()]);
+        const next: Snapshot = {
+          commit: tree.commit,
+          published: tree.entries,
+          drafts: drafts.drafts,
+          draftsVersion: drafts.version,
+          at: this.now(),
+        };
+        const changed = this.current?.draftsVersion !== next.draftsVersion;
+        this.current = next;
+        if (changed) this.onDrafts?.(next.drafts, next.draftsVersion);
+        return next;
+      } finally {
+        this.snapshotting = null;
+      }
+    })();
+    return this.snapshotting;
+  }
+
+  /** The drafts as of the latest snapshot, asking the cloud when that's old. */
+  async drafts(): Promise<{ drafts: Draft[]; version: string; commit: string }> {
+    const snap = await this.snapshot();
+    return { drafts: snap.drafts, version: snap.draftsVersion, commit: snap.commit };
+  }
+
+  async head(): Promise<{ version: string }> {
+    const snap = await this.snapshot();
+    return { version: `${snap.commit}:${snap.draftsVersion}` };
+  }
+
+  async list(options: { prefix?: string } = {}): Promise<StorageEntry[]> {
+    const snap = await this.snapshot();
+    const entries = overlayEntries(snap.published, snap.drafts);
+    for (const [path, held] of this.pending) {
+      if (!entries.some((e) => e.path === path)) {
+        entries.push({ path, version: held.version, size: held.bytes.length });
+      }
+    }
+    const prefix = options.prefix;
+    return prefix ? entries.filter((e) => e.path.startsWith(prefix)) : entries;
+  }
+
+  async read(path: string): Promise<StoredFile | null> {
+    const held = this.pending.get(path);
+    if (held) return { path, bytes: held.bytes, version: held.version };
+    const entry = (await this.list()).find((e) => e.path === path);
+    if (!entry) return null;
+    const bytes = await this.bytes(entry.version);
+    return bytes ? { path, bytes, version: entry.version } : null;
+  }
+
+  /** Bytes by version: the cache first, then batched requests to the API. */
+  private async bytes(version: string): Promise<Uint8Array | null> {
+    const cached = await this.cache?.get(version);
+    if (cached) return cached;
+    return new Promise((resolve, reject) => {
+      const waiting = this.wanted.get(version);
+      if (waiting) waiting.push({ resolve, reject });
+      else this.wanted.set(version, [{ resolve, reject }]);
+      this.batch ??= Promise.resolve().then(() => this.fetchWanted());
+    });
+  }
+
+  private async fetchWanted(): Promise<void> {
+    const wanted = this.wanted;
+    this.wanted = new Map();
+    this.batch = null;
+    const versions = [...wanted.keys()];
+    try {
+      for (let i = 0; i < versions.length; i += 100) {
+        const chunk = versions.slice(i, i + 100);
+        const { blobs } = await this.client.blobs(chunk);
+        for (const version of chunk) {
+          const text = blobs[version];
+          const bytes = text === undefined ? null : fromBase64(text);
+          // Only bytes that match their SHA are used or kept.
+          const verified = bytes && (await gitBlobSha(bytes)) === version ? bytes : null;
+          if (verified) await this.cache?.put(version, verified);
+          for (const waiter of wanted.get(version) ?? []) waiter.resolve(verified);
+          wanted.delete(version);
+        }
+      }
+    } catch (error) {
+      // A file the cloud couldn't send isn't a missing file: every read waiting on it fails.
+      for (const waiters of wanted.values()) {
+        for (const waiter of waiters) waiter.reject(error);
+      }
+    }
+  }
+
+  async commit(changeSet: ChangeSet): Promise<CommitResult> {
+    if (changeSet.defer) {
+      for (const change of changeSet.changes) {
+        if (change.op === 'put') {
+          this.pending.set(change.path, {
+            bytes: change.bytes,
+            version: await gitBlobSha(change.bytes),
+          });
+        }
+      }
+      return { ok: true, version: (await this.head()).version };
+    }
+    // Held uploads go out with this save, unless it deletes them.
+    const deleted = new Set(
+      changeSet.changes.flatMap((c) =>
+        c.op === 'delete' ? [c.path] : c.op === 'move' ? [c.from] : [],
+      ),
+    );
+    const held: FileChange[] = [...this.pending]
+      .filter(([path]) => !deleted.has(path))
+      .map(([path, file]) => ({ op: 'put', path, bytes: file.bytes, expectedVersion: null }));
+    const changes = [
+      ...held,
+      ...changeSet.changes.filter((c) => !(c.op === 'delete' && this.pending.has(c.path))),
+    ];
+    const answer = await this.client.saveDraft({
+      changes: changes.map(encodeChange),
+      message: changeSet.message,
+    });
+    if (!answer.ok) {
+      if (answer.reason === 'conflict')
+        return { ok: false, reason: 'conflict', conflicts: answer.conflicts };
+      return { ok: false, reason: 'rejected', message: answer.message };
+    }
+    this.pending.clear();
+    for (const change of changes) {
+      if (change.op === 'put') await this.cache?.put(await gitBlobSha(change.bytes), change.bytes);
+    }
+    this.invalidate();
+    const snap = await this.snapshot();
+    return { ok: true, version: `${snap.commit}:${snap.draftsVersion}` };
+  }
+}

package/src/editor/Field.tsx

@@ -0,0 +1,182 @@
+import type { FieldModel } from '@vespercms/core';
+import { cx, OptionalMark } from '@vespercms/ui';
+import { Component, Suspense, type ReactNode } from 'react';
+import { useStudio } from '../app/context.tsx';
+import type { WidgetProps } from '../types.ts';
+import { builtinWidget } from '../widgets/registry.ts';
+import { FieldNotes } from '../a11y/FieldNotes.tsx';
+import { useEditor } from './context.tsx';
+import { fieldId, getIn, pathKey, type ValuePath } from './values.ts';
+
+export type FieldProps = {
+  field: FieldModel;
+  /** Where the value lives in the entry (concrete indexes for array items). */
+  path: ValuePath;
+  /** Replaces the field's label, e.g. "Speaker 2" for an array item. */
+  label?: string;
+  /**
+   * A list item. An item of objects or images sits in its row's panel, which
+   * names and frames it, so its legend is for screen readers only. An item is
+   * never marked optional: it exists or it doesn't.
+   */
+  item?: 'row' | 'inline';
+  /** A top-level object or list is a section, except where the place already has its own heading (Details). */
+  asSection?: boolean;
+};
+
+/**
+ * One field: its label, help and error text, and the widget that edits it
+ * (spec §6.3.3: the editor renders the label, the widget the control).
+ * Group widgets (objects, lists, choices) render as a fieldset whose legend
+ * is the label. Errors are linked to the control with aria-describedby.
+ */
+export function Field({ field, path, label, item, asSection = true }: FieldProps) {
+  const editor = useEditor();
+  const { widgets } = useStudio();
+  const id = fieldId(path, editor.idPrefix);
+  const errors = editor.issues.get(pathKey(path)) ?? [];
+  const Custom = field.widget ? widgets[field.widget] : undefined;
+  const builtin = builtinWidget(field);
+  // Notes about a child the widget draws its own control for (an image's alt
+  // text) are shown by the widget, beside that control.
+  const childControls = Custom ? undefined : builtin.childControls;
+  const notes = (editor.notes?.get(pathKey(path)) ?? []).filter((note) => {
+    const child = note.target.kind === 'field' ? note.target.path[path.length] : undefined;
+    return !(typeof child === 'string' && childControls && child in childControls);
+  });
+  const helpId = field.description ? `${id}-help` : undefined;
+  const errorId = errors.length > 0 ? `${id}-error` : undefined;
+  const notesId = notes.length > 0 ? `${id}-a11y` : undefined;
+  const describedBy = [helpId, errorId, notesId].filter(Boolean).join(' ') || undefined;
+
+  const props: WidgetProps & { path: ValuePath } = {
+    value: getIn(editor.values, path),
+    onChange: (value) => {
+      editor.setValue(path, value as never);
+    },
+    field,
+    id,
+    describedBy,
+    invalid: errors.length > 0,
+    disabled: editor.disabled || field.readOnly === true,
+    path,
+  };
+
+  const own = item === 'row' ? { ...props, inRow: true } : props;
+  const control = Custom ? (
+    <WidgetBoundary fallback={<builtin.component {...own} />} name={field.widget ?? ''}>
+      <Suspense fallback={<p className="text-small text-content-muted">Loading…</p>}>
+        <Custom {...props} />
+      </Suspense>
+    </WidgetBoundary>
+  ) : (
+    <builtin.component {...own} />
+  );
+
+  const text = label ?? field.label;
+  // Most fields are required, so the few that aren't say so (DECISIONS.md,
+  // "The studio marks what's optional"). A switch is never empty, so it's never optional.
+  const mark =
+    !field.required && !item && field.kind !== 'boolean' && field.readOnly !== true ? (
+      <OptionalMark />
+    ) : null;
+  const help = helpId ? (
+    <p id={helpId} className="text-small text-content-muted">
+      {field.description}
+    </p>
+  ) : null;
+  const error = errorId ? (
+    <p id={errorId} className="text-small text-danger">
+      {errors.join(' ')}
+    </p>
+  ) : null;
+  const noteList = notesId ? <FieldNotes id={notesId} notes={notes} /> : null;
+
+  if (!Custom && builtin.group) {
+    const section = builtin.section && path.length === 1 && asSection && !editor.idPrefix && !item;
+    // Objects inside the form are set off by an indent guide, never a frame (spec §10.2).
+    const guided =
+      builtin.section &&
+      (field.kind === 'object' || field.kind === 'union') &&
+      !section &&
+      item !== 'row';
+    const fieldset = (
+      <fieldset
+        aria-describedby={describedBy}
+        className={cx(
+          'flex min-w-0 flex-col gap-2',
+          section && 'gap-3',
+          guided && 'border-l border-border pl-4',
+          builtin.group === 'boxed' && !item && 'rounded-md border border-border p-4',
+        )}
+      >
+        <legend
+          id={`${id}-label`}
+          tabIndex={-1}
+          className={cx(
+            'mb-1 outline-none',
+            // The row above it shows the item's name; screen readers still hear the group's.
+            item === 'row' ? 'sr-only' : 'text-label text-content',
+          )}
+        >
+          {section ? (
+            <h2 className="text-heading-3 text-content">
+              {text}
+              {mark}
+            </h2>
+          ) : (
+            <>
+              {text}
+              {mark}
+            </>
+          )}
+        </legend>
+        {help}
+        {control}
+        {error}
+        {noteList}
+      </fieldset>
+    );
+    // A section starts after a hairline, with more space above it than between fields.
+    return section ? <div className="mt-4 border-t border-border pt-6">{fieldset}</div> : fieldset;
+  }
+  return (
+    <div className="flex min-w-0 flex-col gap-2">
+      <label id={`${id}-label`} htmlFor={id} className="text-label text-content">
+        {text}
+        {mark}
+      </label>
+      {control}
+      {help}
+      {error}
+      {noteList}
+    </div>
+  );
+}
+
+/**
+ * A custom widget that throws falls back to the built-in control for the
+ * field, with a note, instead of taking the whole editor down.
+ */
+class WidgetBoundary extends Component<
+  { fallback: ReactNode; name: string; children: ReactNode },
+  { failed: boolean }
+> {
+  override state = { failed: false };
+
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true };
+  }
+
+  override render() {
+    if (!this.state.failed) return this.props.children;
+    return (
+      <>
+        <p className="text-small text-content-muted">
+          The “{this.props.name}” control couldn’t load, so this is a plain one.
+        </p>
+        {this.props.fallback}
+      </>
+    );
+  }
+}