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

package/src/a11y/useNotes.ts

@@ -0,0 +1,139 @@
+import {
+  resolveMediaPath,
+  type A11yNote,
+  type BodyFormat,
+  type CollectionManifest,
+  type DataObject,
+  type Manifest,
+  type PdfFacts,
+  type PdfTarget,
+} from '@vespercms/core';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { a11yChecker } from './run.ts';
+
+type Checks = typeof import('./run.ts');
+type Checker = ReturnType<typeof a11yChecker>;
+
+export type EntryNotes = {
+  /** Field notes in form order, then the body's, then the PDFs'. */
+  notes: A11yNote[];
+  /** PDFs the entry points at. */
+  pdfs: PdfTarget[];
+};
+
+const NONE: EntryNotes = { notes: [], pdfs: [] };
+
+export type EntryNotesResult = EntryNotes & {
+  /** Checks the current values now, without the pause (for a save). PDFs keep their last result. */
+  recheck: () => Promise<A11yNote[]>;
+};
+
+/**
+ * What each PDF says about itself, by the URL the studio reads it from, for
+ * as long as the studio is open: a PDF is read once, however often its entry
+ * is checked. A file that can't be read gets no notes rather than wrong ones.
+ */
+const pdfFacts = new Map<string, Promise<PdfFacts | null>>();
+
+function factsFor(url: string): Promise<PdfFacts | null> {
+  let facts = pdfFacts.get(url);
+  if (!facts) {
+    facts = (async () => {
+      try {
+        const response = await fetch(url);
+        if (!response.ok) return null;
+        const bytes = await response.arrayBuffer();
+        const { readPdfFacts } = await import('./pdf.ts');
+        return await readPdfFacts(bytes);
+      } catch {
+        return null;
+      }
+    })();
+    pdfFacts.set(url, facts);
+  }
+  return facts;
+}
+
+/**
+ * The entry's accessibility notes (spec §6.18, layer 1), checked a moment
+ * after typing stops, the same pause as the body's validation. PDFs are read
+ * with PDF.js, and their notes join when they have been.
+ */
+export function useEntryNotes(options: {
+  manifest: Manifest;
+  collection: CollectionManifest;
+  values: DataObject;
+  /** The body without its leading line breaks, as the body editor has it. */
+  body: string | undefined;
+  format: BodyFormat;
+  /** The entry's file, which relative PDF paths are resolved against. */
+  entryPath: string;
+  /** Where the studio reads a site file from. */
+  fileUrl: (path: string) => Promise<string>;
+}): EntryNotesResult {
+  const { manifest, collection, values, body, format, entryPath, fileUrl } = options;
+  const load = useMemo(() => {
+    let loaded: Promise<{ checks: Checks; check: Checker }> | null = null;
+    return () =>
+      (loaded ??= import('./run.ts').then((checks) => ({
+        checks,
+        check: checks.a11yChecker(manifest),
+      })));
+  }, [manifest]);
+
+  const [found, setFound] = useState<EntryNotes>(NONE);
+  useEffect(() => {
+    let live = true;
+    const timer = setTimeout(() => {
+      void load().then(({ check }) => {
+        if (live)
+          setFound(check(collection, { values, ...(body !== undefined ? { body } : {}), format }));
+      });
+    }, 300);
+    return () => {
+      live = false;
+      clearTimeout(timer);
+    };
+  }, [load, collection, values, body, format]);
+
+  const [pdfNotes, setPdfNotes] = useState<A11yNote[]>([]);
+  useEffect(() => {
+    let live = true;
+    void load()
+      .then(({ checks }) =>
+        Promise.all(
+          found.pdfs.map(async (pdf) => {
+            const path = resolveMediaPath(pdf.href, entryPath);
+            const facts = path === null ? null : await factsFor(await fileUrl(path));
+            return facts ? checks.pdfNotes(pdf, facts) : [];
+          }),
+        ),
+      )
+      .then((notes) => {
+        if (live) setPdfNotes(notes.flat());
+      });
+    return () => {
+      live = false;
+    };
+  }, [load, found.pdfs, entryPath, fileUrl]);
+
+  const latest = useRef({ collection, values, body, format, pdfNotes });
+  useEffect(() => {
+    latest.current = { collection, values, body, format, pdfNotes };
+  });
+  const recheck = useCallback(async () => {
+    const { check } = await load();
+    const now = latest.current;
+    const fresh = check(now.collection, {
+      values: now.values,
+      ...(now.body !== undefined ? { body: now.body } : {}),
+      format: now.format,
+    });
+    return [...fresh.notes, ...now.pdfNotes];
+  }, [load]);
+
+  return useMemo(
+    () => ({ notes: [...found.notes, ...pdfNotes], pdfs: found.pdfs, recheck }),
+    [found, pdfNotes, recheck],
+  );
+}

package/src/app/App.tsx

@@ -0,0 +1,156 @@
+import type { CollectionManifest } from '@vespercms/core';
+import { Button, Dialog } from '@vespercms/ui';
+import { lazy, useEffect, useMemo, useRef, useState } from 'react';
+import { Unavailable } from '../screens/Unavailable.tsx';
+import { ChangesProvider } from '../cloud/changes.tsx';
+import { CloudGate } from '../cloud/CloudGate.tsx';
+import { GitHubGate } from '../github/GitHubGate.tsx';
+import { readSession } from '../github/session.ts';
+import type { StudioOptions, WidgetComponent, WidgetLoader } from '../types.ts';
+import { StudioContext, VESPER_NAME, type Studio } from './context.tsx';
+import { useMediaQuery } from './media.ts';
+import { NavigationContext } from './navigation.ts';
+import { PANES, PaneShell } from './panes.tsx';
+import { useRouter, type Route } from './router.ts';
+
+const NO_WIDGETS: Record<string, WidgetLoader> = {};
+const NO_PROPS = (): Promise<Record<string, unknown>> => Promise.resolve({});
+
+export function App({
+  manifest,
+  api,
+  widgets = NO_WIDGETS,
+  loadMdxProps = NO_PROPS,
+  siteName = VESPER_NAME,
+  siteUrl,
+  github,
+  routes,
+  loadUrlFunctions,
+  account,
+  cloud,
+  connection,
+}: StudioOptions) {
+  const { route, pending, leave, stay } = useRouter();
+  const panes = useMediaQuery(PANES);
+  const navigation = useNavigationCount(route);
+
+  const studio = useMemo<Studio | null>(() => {
+    if (!api) return null;
+    const byName = new Map<string, CollectionManifest>(
+      manifest.collections.map((c) => [c.name, c]),
+    );
+    return {
+      manifest,
+      api,
+      widgets: lazyWidgets(widgets),
+      loadMdxProps,
+      siteName,
+      siteUrl,
+      collection: (name) => byName.get(name),
+      ...(account ? { account } : {}),
+      ...(connection ? { cloud: connection } : {}),
+    };
+  }, [manifest, api, widgets, loadMdxProps, siteName, siteUrl, account, connection]);
+
+  // Stable, so the gate keeps one GitHub API for the whole visit.
+  const gateOptions = useMemo(
+    () => ({
+      manifest,
+      widgets,
+      loadMdxProps,
+      siteName,
+      ...(siteUrl !== undefined ? { siteUrl } : {}),
+      ...(routes ? { routes } : {}),
+      ...(loadUrlFunctions ? { loadUrlFunctions } : {}),
+    }),
+    [manifest, widgets, loadMdxProps, siteName, siteUrl, routes, loadUrlFunctions],
+  );
+
+  if (!studio) {
+    // Sign in first, then this same App with the cloud or GitHub as its back end.
+    // The cloud's gate offers GitHub too; once GitHub is chosen, its own gate takes over.
+    if (cloud && !(github && gitHubChosen()))
+      return <CloudGate settings={cloud} github={github ?? null} options={gateOptions} />;
+    if (github) return <GitHubGate settings={github} options={gateOptions} />;
+    return <Unavailable siteName={siteName} />;
+  }
+
+  // Wide: panes, full width; narrow: one screen at a time (app/panes.tsx).
+  const screen = <PaneShell route={route} studio={studio} wide={panes} />;
+  return (
+    <StudioContext.Provider value={studio}>
+      <NavigationContext.Provider value={navigation}>
+        {/* The cloud's Changes drawer, reachable from every screen (spec §7.4). */}
+        {connection ? (
+          <ChangesProvider linked={route.screen === 'changes'}>{screen}</ChangesProvider>
+        ) : (
+          screen
+        )}
+        <Dialog
+          title="Leave without saving?"
+          role="alertdialog"
+          isOpen={pending !== null}
+          onOpenChange={(open) => {
+            if (!open) stay();
+          }}
+        >
+          <p className="mb-6">Your changes to this entry haven’t been saved. They’ll be lost.</p>
+          <div className="flex flex-wrap justify-end gap-3">
+            <Button onPress={stay}>Keep editing</Button>
+            <Button variant="danger" onPress={leave}>
+              Leave without saving
+            </Button>
+          </div>
+        </Dialog>
+      </NavigationContext.Provider>
+    </StudioContext.Provider>
+  );
+}
+
+const lazyCache = new WeakMap<WidgetLoader, WidgetComponent>();
+
+/** Custom widget loaders as lazy components, made once per loader. */
+function lazyWidgets(loaders: Record<string, WidgetLoader>): Record<string, WidgetComponent> {
+  return Object.fromEntries(
+    Object.entries(loaders).map(([name, loader]) => {
+      let component = lazyCache.get(loader);
+      if (!component) {
+        component = lazy(loader);
+        lazyCache.set(loader, component);
+      }
+      return [name, component];
+    }),
+  );
+}
+
+/**
+ * Each route gets a fresh screen, so no state leaks from one entry to the
+ * next. Changes is Home under the drawer, so closing it keeps the same Home.
+ */
+function routeKey(route: Route): string {
+  return JSON.stringify(route.screen === 'changes' ? { screen: 'home' } : route);
+}
+
+/**
+ * Counts in-app navigations, so a new screen can take focus. It compares the
+ * route with the last one counted rather than skipping a "first run": React's
+ * StrictMode runs effects twice on mount in development, and a first-run flag
+ * then counted the load as a navigation and moved focus past the top bar.
+ */
+function useNavigationCount(route: Route): { count: number } {
+  const [count, setCount] = useState(0);
+  const key = routeKey(route);
+  const counted = useRef(key);
+  useEffect(() => {
+    if (counted.current === key) return;
+    counted.current = key;
+    setCount((n) => n + 1);
+  }, [key]);
+  return useMemo(() => ({ count }), [count]);
+}
+
+/** True when the editor signed in with GitHub, or is on the way back from doing so. */
+function gitHubChosen(): boolean {
+  const params = new URLSearchParams(window.location.search);
+  return params.has('github') || params.has('github_error') || readSession() !== null;
+}