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

package/src/app/appearance.ts

@@ -0,0 +1,54 @@
+import { useCallback, useState } from 'react';
+
+/*
+ * Light, dark, or the system's choice (DECISIONS.md, "Appearance is in the
+ * user menu"). The tokens switch on `html[data-theme]`; with no attribute
+ * they follow the system. The choice is per viewer, in this browser, for this
+ * site. `admin.astro` applies it before the page paints, with the same key,
+ * so a dark choice doesn't flash light while the studio loads.
+ */
+
+export type Appearance = 'system' | 'light' | 'dark';
+
+export const APPEARANCE_KEY = 'vesper:appearance';
+
+export const APPEARANCES: readonly { id: Appearance; label: string }[] = [
+  { id: 'system', label: 'System' },
+  { id: 'light', label: 'Light' },
+  { id: 'dark', label: 'Dark' },
+];
+
+export function readAppearance(): Appearance {
+  try {
+    const value = localStorage.getItem(APPEARANCE_KEY);
+    return value === 'light' || value === 'dark' ? value : 'system';
+  } catch {
+    // Storage can be refused (a private window, a blocked site): follow the system.
+    return 'system';
+  }
+}
+
+export function applyAppearance(appearance: Appearance): void {
+  const root = document.documentElement;
+  if (appearance === 'system') delete root.dataset.theme;
+  else root.dataset.theme = appearance;
+}
+
+export function saveAppearance(appearance: Appearance): void {
+  applyAppearance(appearance);
+  try {
+    if (appearance === 'system') localStorage.removeItem(APPEARANCE_KEY);
+    else localStorage.setItem(APPEARANCE_KEY, appearance);
+  } catch {
+    // Kept for this visit only.
+  }
+}
+
+export function useAppearance(): [Appearance, (appearance: Appearance) => void] {
+  const [appearance, setAppearance] = useState(readAppearance);
+  const choose = useCallback((next: Appearance) => {
+    saveAppearance(next);
+    setAppearance(next);
+  }, []);
+  return [appearance, choose];
+}

package/src/app/browser-api.ts

@@ -0,0 +1,173 @@
+import {
+  ContentService,
+  MEDIA_TYPES,
+  MediaService,
+  PageService,
+  extensionOf,
+  fieldModelIssues,
+  issuesFromZod,
+  type FieldIssue,
+  type Manifest,
+  type StorageAdapter,
+  type UrlEntry,
+} from '@vespercms/core';
+import { ApiError, type StudioApi } from './api.ts';
+
+/*
+ * The studio's back end in the browser (DECISIONS.md, "GitHub mode runs
+ * core's services in the browser"): the same core services local mode's dev
+ * API runs, over a storage adapter. GitHub mode passes its repository, the
+ * cloud its drafts; every screen, check and splice stays the same code.
+ *
+ * Saves are validated with the site's own Zod schemas, built for the
+ * browser at `astro build`. If that file can't load, the field model's
+ * checks stand in, and the site's build is the last check.
+ */
+
+type SafeParse = (
+  value: unknown,
+  params?: object,
+) => Promise<{ success: boolean; error?: { issues: unknown[] } }>;
+
+export type BrowserApiOptions = {
+  storage: StorageAdapter;
+  manifest: Manifest;
+  /** The site's schemas built for the browser. */
+  schemas: string;
+  loadMdxProps: () => Promise<Readonly<Record<string, unknown>>>;
+  loadUrlFunctions?: () => Promise<Readonly<Record<string, (entry: UrlEntry) => unknown>>>;
+  /** The site's static routes at build, for collision checks. */
+  routes?: readonly (readonly [string, string])[];
+  /** Whether a save publishes (GitHub mode) or keeps a draft (the cloud). */
+  publishesOnSave: boolean;
+  /** The storage's own errors in the studio's terms. */
+  mapError: (error: unknown) => unknown;
+};
+
+export function createBrowserApi(options: BrowserApiOptions): StudioApi {
+  const { storage, manifest } = options;
+
+  let schemas: Promise<Readonly<Record<string, unknown>> | null> | null = null;
+  const loadSchemas = () => {
+    schemas ??= (import(/* @vite-ignore */ options.schemas) as Promise<{ schemas?: unknown }>).then(
+      (module) =>
+        typeof module.schemas === 'object' && module.schemas !== null
+          ? (module.schemas as Record<string, unknown>)
+          : null,
+      () => null,
+    );
+    return schemas;
+  };
+  const validate = async (name: string, data: Record<string, unknown>): Promise<FieldIssue[]> => {
+    const all = await loadSchemas();
+    const schema = all?.[name] as { safeParseAsync?: SafeParse } | undefined;
+    if (typeof schema?.safeParseAsync === 'function') {
+      const result = await schema.safeParseAsync(data, { reportInput: true });
+      return result.success ? [] : issuesFromZod(result.error?.issues ?? []);
+    }
+    if (all !== null) return [];
+    const collection = manifest.collections.find((c) => c.name === name);
+    return fieldModelIssues(collection?.fields ?? null, data as never);
+  };
+
+  let ready: Promise<{ content: ContentService; pages: PageService; media: MediaService }> | null =
+    null;
+  const services = () => {
+    ready ??= (async () => {
+      const urlFunctions = (await options.loadUrlFunctions?.().catch(() => ({}))) ?? {};
+      const routes = new Map(options.routes ?? []);
+      const content: ContentService = new ContentService(storage, manifest, {
+        validate: (name, data) => validate(name, data),
+        validateBody: async ({ format, body, path }) => {
+          const { bodyChecks } = await import('../body/checks.ts');
+          const partials = format === 'mdoc' ? await content.listPartials() : [];
+          return bodyChecks({
+            manifest,
+            format,
+            loadMdxProps: options.loadMdxProps,
+            partials,
+            entryPath: path,
+          }).validate(body);
+        },
+        tree: () => pages.hooks(),
+      });
+      const pages: PageService = new PageService(storage, manifest, content, {
+        routes: () => routes,
+        urlFunctions,
+      });
+      const media = new MediaService(storage, content, {
+        roots: [`${manifest.site.srcDir}/assets`, 'public'],
+      });
+      return { content, pages, media };
+    })();
+    return ready;
+  };
+
+  /** Runs a request, with the storage's errors in the studio's terms. */
+  const call = async <T>(work: () => Promise<T>): Promise<T> => {
+    try {
+      return await work();
+    } catch (error) {
+      throw options.mapError(error);
+    }
+  };
+  const known = (name: string) => manifest.collections.some((c) => c.name === name);
+  const objectUrls = new Map<string, string>();
+
+  return {
+    publishesOnSave: () => options.publishesOnSave,
+    summary: () => call(async () => (await services()).content.summary()),
+    listEntries: (collection) =>
+      call(async () => {
+        if (!known(collection))
+          throw new ApiError(404, `There's no collection called "${collection}".`);
+        return (await services()).content.listEntries(collection);
+      }),
+    readEntry: (collection, id) =>
+      call(async () => {
+        const doc = known(collection)
+          ? await (await services()).content.readEntry(collection, id)
+          : null;
+        if (!doc) throw new ApiError(404, `"${id}" wasn't found in ${collection || 'this site'}.`);
+        return doc;
+      }),
+    saveEntry: (request) => call(async () => (await services()).content.saveEntry(request)),
+    deleteEntry: (collection, id, version) =>
+      call(async () => (await services()).content.deleteEntry(collection, id, version)),
+    listMedia: () => call(async () => (await services()).media.list()),
+    upload: (file, name, folder, uploadOptions) =>
+      call(async () =>
+        (await services()).media.upload(new Uint8Array(await file.arrayBuffer()), name, folder, {
+          defer: uploadOptions?.withNextSave === true,
+        }),
+      ),
+    deleteMedia: (path) => call(async () => (await services()).media.remove(path)),
+    listPartials: () => call(async () => (await services()).content.listPartials()),
+    fileUrl: (path) =>
+      call(async () => {
+        const file = await storage.read(path);
+        if (!file) throw new ApiError(404, `${path} wasn't found.`);
+        let url = objectUrls.get(file.version);
+        if (!url) {
+          const type = MEDIA_TYPES[extensionOf(path)] ?? 'application/octet-stream';
+          url = URL.createObjectURL(new Blob([file.bytes as BlobPart], { type }));
+          objectUrls.set(file.version, url);
+        }
+        return url;
+      }),
+    listPages: () => call(async () => (await services()).pages.pages()),
+    listScheduled: () => call(async () => (await services()).content.scheduledChanges(new Date())),
+    pageTree: (collection) => call(async () => (await services()).pages.tree(collection)),
+    movePage: (request, moveOptions) =>
+      call(async () => {
+        const { pages } = await services();
+        return moveOptions?.dryRun ? pages.planMove(request) : pages.move(request);
+      }),
+    reorderPage: (request) => call(async () => (await services()).pages.reorder(request)),
+    reorderEntry: (request) => call(async () => (await services()).content.reorderEntry(request)),
+    createSection: (collection, path) =>
+      call(async () => (await services()).pages.createSection(collection, path)),
+    readRedirects: () => call(async () => (await services()).pages.redirects()),
+    saveRedirects: (request) => call(async () => (await services()).pages.saveRedirects(request)),
+  };
+}

package/src/app/collection-icon.ts

@@ -0,0 +1,15 @@
+import type { CollectionManifest } from '@vespercms/core';
+import type { IconName, IconNode } from '@vespercms/ui';
+
+/**
+ * A collection's icon: the Lucide icon vesper.config.ts names for it,
+ * resolved into the manifest at build, or a default by kind (DECISIONS.md,
+ * "A collection's icon is named in vesper.config.ts").
+ */
+export function collectionIcon(
+  collection: CollectionManifest,
+): { node: IconNode } | { name: IconName } {
+  const { icon, singleton, tree } = collection.presentation;
+  if (icon) return { node: icon.node };
+  return { name: singleton ? 'singleton' : tree ? 'tree' : 'collection' };
+}

package/src/app/context.tsx

@@ -0,0 +1,32 @@
+import type { CollectionManifest, Manifest } from '@vespercms/core';
+import { createContext, useContext } from 'react';
+import type { Account, WidgetComponent } from '../types.ts';
+import type { CloudConnection } from '../cloud/connection.ts';
+import type { StudioApi } from './api.ts';
+
+export type Studio = {
+  manifest: Manifest;
+  api: StudioApi;
+  /** Custom widgets, as lazy components: each loads the first time a field uses it. */
+  widgets: Record<string, WidgetComponent>;
+  /** Loads declared MDX components' Zod props schemas, from vesper.config.ts (spec §6.5.2). */
+  loadMdxProps: () => Promise<Readonly<Record<string, unknown>>>;
+  siteName: string;
+  siteUrl: string | undefined;
+  collection: (name: string) => CollectionManifest | undefined;
+  /** The signed-in editor, in GitHub mode or the cloud. */
+  account?: Account;
+  /** The cloud, when the studio is connected to it. Absent, every cloud feature is absent (spec §6.9). */
+  cloud?: CloudConnection;
+};
+
+/** The name the studio shows when the site gives none: Vesper's own, set lowercase as its wordmark. */
+export const VESPER_NAME = 'Vesper';
+
+export const StudioContext = createContext<Studio | null>(null);
+
+export function useStudio(): Studio {
+  const studio = useContext(StudioContext);
+  if (!studio) throw new Error('useStudio() must be used inside <App>.');
+  return studio;
+}

package/src/app/entries-changed.ts

@@ -0,0 +1,48 @@
+/*
+ * After a save, the lists beside the editor read their collection again, so
+ * a new title or status shows there (DECISIONS.md, "The studio is panes,
+ * full width").
+ */
+
+const listeners = new Set<(collection: string) => void>();
+
+export function entriesChanged(collection: string): void {
+  for (const listener of listeners) listener(collection);
+}
+
+const rewrites = new Set<(collection: string, ids: readonly string[]) => void>();
+
+/**
+ * Entries rewritten from outside their editor: a move in the list writes
+ * order numbers into them, and an editor open on one reads it again, or its
+ * next save would find a version it didn't start from.
+ */
+export function entriesRewritten(collection: string, ids: readonly string[]): void {
+  for (const listener of rewrites) listener(collection, ids);
+  entriesChanged(collection);
+}
+
+/** Calls `listener` with the IDs whenever entries in `collection` are rewritten; returns the way to stop. */
+export function onEntriesRewritten(
+  collection: string,
+  listener: (ids: readonly string[]) => void,
+): () => void {
+  const each = (changed: string, ids: readonly string[]) => {
+    if (changed === collection) listener(ids);
+  };
+  rewrites.add(each);
+  return () => {
+    rewrites.delete(each);
+  };
+}
+
+/** Calls `listener` after each save in `collection`; returns the way to stop. */
+export function onEntriesChanged(collection: string, listener: () => void): () => void {
+  const each = (changed: string) => {
+    if (changed === collection) listener();
+  };
+  listeners.add(each);
+  return () => {
+    listeners.delete(each);
+  };
+}

package/src/app/file-url.tsx

@@ -0,0 +1,44 @@
+import { useEffect, useState } from 'react';
+import { useStudio } from './context.tsx';
+
+/**
+ * A URL the studio can show a site file from, or `''` until it's ready. In
+ * local mode it's the dev API's `/file`; in GitHub mode an object URL for
+ * the blob, since a private repository's files have no address a browser
+ * can load without the token.
+ */
+export function useFileUrl(path: string | null): string {
+  const { api } = useStudio();
+  const [found, setFound] = useState<{ path: string; url: string } | null>(null);
+  useEffect(() => {
+    if (!path) return;
+    let live = true;
+    api.fileUrl(path).then(
+      (url) => {
+        if (live) setFound({ path, url });
+      },
+      () => {
+        // No preview; the field still works.
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [api, path]);
+  return path && found?.path === path ? found.url : '';
+}
+
+/** A site image, shown once its URL is ready. Decorative: whatever lists it names it. */
+export function FileImage({
+  path,
+  className,
+  loading,
+}: {
+  path: string;
+  className?: string;
+  loading?: 'lazy' | 'eager';
+}) {
+  const url = useFileUrl(path);
+  if (!url) return <span aria-hidden="true" className={className} />;
+  return <img src={url} alt="" loading={loading} className={className} />;
+}

package/src/app/format.ts

@@ -0,0 +1,39 @@
+/*
+ * Words for numbers and times (spec §10.2: words over badges). Everything
+ * takes `now` and a locale so tests are deterministic.
+ */
+
+const UNITS: [Intl.RelativeTimeFormatUnit, number][] = [
+  ['year', 365 * 24 * 3600],
+  ['month', 30 * 24 * 3600],
+  ['week', 7 * 24 * 3600],
+  ['day', 24 * 3600],
+  ['hour', 3600],
+  ['minute', 60],
+];
+
+/** "just now", "5 minutes ago", "yesterday", "3 weeks ago". */
+export function formatRelative(iso: string, now: Date = new Date(), locale?: string): string {
+  const then = new Date(iso);
+  const seconds = Math.round((then.getTime() - now.getTime()) / 1000);
+  if (Number.isNaN(seconds)) return '';
+  if (Math.abs(seconds) < 45) return 'just now';
+  const format = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+  for (const [unit, size] of UNITS) {
+    if (Math.abs(seconds) >= size || unit === 'minute') {
+      return format.format(Math.round(seconds / size), unit);
+    }
+  }
+  return 'just now';
+}
+
+/** "1 entry", "12 entries". */
+export function formatCount(
+  count: number,
+  singular: string,
+  plural: string,
+  locale?: string,
+): string {
+  const number = new Intl.NumberFormat(locale).format(count);
+  return `${number} ${count === 1 ? singular : plural}`;
+}

package/src/app/idb.ts

@@ -0,0 +1,82 @@
+/*
+ * A small key-value store in IndexedDB. Without IndexedDB (a private window,
+ * blocked storage, jsdom) it keeps values in memory for the visit, so the
+ * studio still works; it only forgets them on reload.
+ */
+
+export type KeyValueStore<T> = {
+  get(key: string): Promise<T | undefined>;
+  put(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+};
+
+export function keyValueStore<T>(database: string, store: string): KeyValueStore<T> {
+  const memory = new Map<string, T>();
+  let opened: Promise<IDBDatabase | null> | null = null;
+  const open = () => {
+    opened ??= new Promise((resolve) => {
+      try {
+        if (typeof indexedDB === 'undefined') {
+          resolve(null);
+          return;
+        }
+        const request = indexedDB.open(database, 1);
+        request.onupgradeneeded = () => {
+          request.result.createObjectStore(store);
+        };
+        request.onsuccess = () => {
+          resolve(request.result);
+        };
+        request.onerror = () => {
+          resolve(null);
+        };
+      } catch {
+        resolve(null);
+      }
+    });
+    return opened;
+  };
+  const run = <R>(
+    mode: IDBTransactionMode,
+    act: (objects: IDBObjectStore) => IDBRequest<R>,
+  ): Promise<{ ok: true; value: R } | { ok: false }> =>
+    open().then(
+      (db) =>
+        new Promise((resolve) => {
+          if (!db) {
+            resolve({ ok: false });
+            return;
+          }
+          try {
+            const request = act(db.transaction(store, mode).objectStore(store));
+            request.onsuccess = () => {
+              resolve({ ok: true, value: request.result });
+            };
+            request.onerror = () => {
+              resolve({ ok: false });
+            };
+          } catch {
+            resolve({ ok: false });
+          }
+        }),
+    );
+  return {
+    get: async (key) => {
+      const found = await run<unknown>('readonly', (objects) => objects.get(key));
+      return found.ok ? (found.value as T | undefined) : memory.get(key);
+    },
+    put: async (key, value) => {
+      const done = await run('readwrite', (objects) => objects.put(value, key));
+      if (!done.ok) memory.set(key, value);
+    },
+    delete: async (key) => {
+      memory.delete(key);
+      await run('readwrite', (objects) => objects.delete(key));
+    },
+    keys: async () => {
+      const found = await run('readonly', (objects) => objects.getAllKeys());
+      return found.ok ? found.value.map(String) : [...memory.keys()];
+    },
+  };
+}

package/src/app/load.ts

@@ -0,0 +1,40 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export type Load<T> =
+  { state: 'loading' } | { state: 'ready'; value: T } | { state: 'failed'; message: string };
+
+/**
+ * Loads data for a screen. The loader runs again when `key` changes, or when
+ * `reload()` is called (after a save, for example); a reload keeps showing
+ * the old value until the new one arrives. A response that arrives after
+ * the key moved on is dropped.
+ */
+export function useLoad<T>(loader: () => Promise<T>, key = ''): [Load<T>, () => void] {
+  const [result, setResult] = useState<{ key: string; load: Load<T> } | null>(null);
+  const [generation, setGeneration] = useState(0);
+  const latest = useRef(loader);
+  useEffect(() => {
+    latest.current = loader;
+  });
+
+  useEffect(() => {
+    let current = true;
+    latest.current().then(
+      (value) => {
+        if (current) setResult({ key, load: { state: 'ready', value } });
+      },
+      (error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (current) setResult({ key, load: { state: 'failed', message } });
+      },
+    );
+    return () => {
+      current = false;
+    };
+  }, [key, generation]);
+
+  const reload = useCallback(() => {
+    setGeneration((n) => n + 1);
+  }, []);
+  return [result?.key === key ? result.load : { state: 'loading' }, reload];
+}

package/src/app/media.ts

@@ -0,0 +1,20 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * Whether a CSS media query matches, kept current as the window changes.
+ * False where there's no `matchMedia` (and so in jsdom's stub).
+ */
+export function useMediaQuery(query: string): boolean {
+  return useSyncExternalStore(
+    (onChange) => {
+      if (typeof window.matchMedia !== 'function') return () => undefined;
+      const list = window.matchMedia(query);
+      list.addEventListener('change', onChange);
+      return () => {
+        list.removeEventListener('change', onChange);
+      };
+    },
+    () => typeof window.matchMedia === 'function' && window.matchMedia(query).matches,
+    () => false,
+  );
+}

package/src/app/navigation.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react';
+
+/** How many in-app navigations have happened. 0 on the screen the studio opened on. */
+export const NavigationContext = createContext<{ count: number }>({ count: 0 });

package/src/app/pane-context.ts

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+
+/** Where a screen sits among the panes (app/panes.tsx), or null one screen at a time. */
+export type PaneInfo = {
+  /**
+   * `main` for the deepest pane, `nav` for the ones that lead to it, and
+   * `region` for a pane beside the deepest that leads nowhere (the cloud's
+   * waiting drafts on Home).
+   */
+  landmark: 'main' | 'nav' | 'region';
+  /** The deepest pane's title is the page's `h1`; the others are `h2`s. */
+  level: 1 | 2;
+  /** The deepest pane takes focus after a navigation, and names the browser tab. */
+  focusTarget: boolean;
+  /** How wide it is: the narrow panes get tighter padding and a smaller heading. */
+  width: 'structure' | 'list' | 'flex';
+  /** Folds the pane into a strip, when people may: every pane but the deepest. */
+  onCollapse?: () => void;
+};
+
+export const PaneContext = createContext<PaneInfo | null>(null);
+
+export function usePane(): PaneInfo | null {
+  return useContext(PaneContext);
+}