basis-design 0.1.1 → 0.2.0

package/src/capture/main.tsx

@@ -0,0 +1,146 @@
+import { Component, useEffect, useMemo, useState, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { captureShots, READY_ATTRIBUTE, type CaptureView } from "../../shared/capture.ts";
+import { parseDesignText, type Design } from "../../shared/design.ts";
+import { previewCss } from "../../shared/tokens.ts";
+import type { ScreenProps, SpecimenBlock } from "../../template/components/specimen.ts";
+import { loadSpecimens, type LoadedSpecimen } from "../preview/specimens.tsx";
+import "./capture.css";
+
+/*
+ * One screen of a view, alone on the page at the size the browser gives it, for the verification kit's
+ * screenshots: `?view=<view id>&screen=<screen id>&theme=light|dark`. `?list` instead reports every view and
+ * the shots its screens ask for (window.__basisViews). The design comes from design.json beside this page, so
+ * the same page runs on Basis' preview server and as the kit's static copy of the design.
+ */
+
+declare global {
+  interface Window {
+    __basisViews?: { views: CaptureView[]; problems: string[] };
+  }
+}
+
+const params = new URLSearchParams(location.search);
+type FlowBlock = Extract<SpecimenBlock, { kind: "flow" }>;
+
+function flows(specimen: LoadedSpecimen): FlowBlock[] {
+  return specimen.blocks.filter((block): block is FlowBlock => block.kind === "flow");
+}
+
+function views(): { views: CaptureView[]; problems: string[] } {
+  const { specimens, problems } = loadSpecimens();
+  const list = specimens
+    .filter((specimen) => specimen.page === "views")
+    .map((specimen) => ({
+      id: specimen.id,
+      title: specimen.title,
+      screens: flows(specimen).flatMap((flow) =>
+        flow.screens.map((screen) => ({ id: screen.id, label: screen.label, shots: captureShots(flow.capture) })),
+      ),
+    }))
+    .filter((view) => view.screens.length > 0);
+  return { views: list, problems: problems.map((problem) => `${problem.file}: ${problem.message}`) };
+}
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Marks the page ready once it has settled: fonts loaded, images decoded, and the layout the same size twice in
+ * a row. Timers rather than animation frames, which a background tab does not run.
+ */
+async function markReady(): Promise<void> {
+  await document.fonts.ready;
+  await Promise.all([...document.images].map((image) => image.decode().catch(() => undefined)));
+  let last = "";
+  for (let attempt = 0; attempt < 40; attempt++) {
+    await wait(50);
+    const size = `${document.documentElement.scrollWidth}x${document.documentElement.scrollHeight}`;
+    if (size === last) break;
+    last = size;
+  }
+  document.documentElement.setAttribute(READY_ATTRIBUTE, "true");
+}
+
+class Boundary extends Component<{ children: ReactNode }, { error: unknown }> {
+  state = { error: null as unknown };
+  static getDerivedStateFromError(error: unknown) {
+    return { error };
+  }
+  componentDidCatch() {
+    document.documentElement.setAttribute("data-basis-error", "true");
+  }
+  render() {
+    const { error } = this.state;
+    if (error === null) return this.props.children;
+    return <p className="capture-problem">This screen failed to render: {String(error)}</p>;
+  }
+}
+
+function Screen({ design, theme }: { design: Design; theme: "light" | "dark" }) {
+  const { specimens } = useMemo(() => loadSpecimens(), []);
+  const view = specimens.find((specimen) => specimen.page === "views" && specimen.id === params.get("view"));
+  const screens = view ? flows(view).flatMap((flow) => flow.screens) : [];
+  // The kit's copy of the design is clickable: `go` moves through the flow as in the gallery.
+  const [position, setPosition] = useState<{ id: string; data?: unknown }>({
+    id: params.get("screen") ?? screens[0]?.id ?? "",
+  });
+  const screen = screens.find((item) => item.id === position.id);
+
+  useEffect(() => {
+    void markReady();
+  }, [position]);
+
+  if (!view || !screen) {
+    return (
+      <p className="capture-problem">
+        No screen "{position.id}" in the view "{params.get("view")}".
+      </p>
+    );
+  }
+  const go: ScreenProps["go"] = (id, data) => {
+    const next = new URLSearchParams(location.search);
+    next.set("screen", id);
+    history.replaceState(null, "", `?${next}`);
+    document.documentElement.removeAttribute(READY_ATTRIBUTE);
+    setPosition({ id, data });
+  };
+  const Render = screen.render;
+  return (
+    <div className="ds-root" data-theme={theme}>
+      <Boundary key={screen.id}>
+        <Render design={design as unknown as ScreenProps["design"]} go={go} data={position.data} />
+      </Boundary>
+    </div>
+  );
+}
+
+function Page({ design }: { design: Design }) {
+  const theme = params.get("theme") === "dark" ? "dark" : "light";
+  return (
+    <>
+      <style>{previewCss(design, ".ds-root")}</style>
+      {design.typography.fontImports.map((href) => (
+        <link key={href} rel="stylesheet" href={href} />
+      ))}
+      <Screen design={design} theme={theme} />
+    </>
+  );
+}
+
+async function start(): Promise<void> {
+  const root = createRoot(document.getElementById("root")!);
+  if (params.has("list")) {
+    window.__basisViews = views();
+    document.documentElement.setAttribute(READY_ATTRIBUTE, "true");
+    return;
+  }
+  const result = parseDesignText(await (await fetch("./design.json", { cache: "no-store" })).text());
+  if (!result.ok) {
+    root.render(<p className="capture-problem">design.json is not valid: {result.errors.join("; ")}</p>);
+    document.documentElement.setAttribute(READY_ATTRIBUTE, "true");
+    return;
+  }
+  root.render(<Page design={result.design} />);
+}
+
+void start();

package/src/preview/specimens.tsx

@@ -53,6 +53,26 @@ function isComponent(value: unknown): value is ComponentType<never> {
   return typeof value === "function" || (typeof value === "object" && value !== null && "$$typeof" in value);
 }
 
+/** What is wrong with a flow block's `capture`, or null when it is absent or well formed. */
+function captureProblem(capture: unknown): string | null {
+  if (capture === undefined) return null;
+  if (!capture || typeof capture !== "object") return "capture must be an object: { widths, height, themes }";
+  const { widths, height, themes } = capture as Record<string, unknown>;
+  if (widths !== undefined && (!Array.isArray(widths) || widths.some((width) => typeof width !== "number"))) {
+    return "capture.widths must be an array of numbers (viewport widths in px)";
+  }
+  if (height !== undefined && height !== "full" && typeof height !== "number") {
+    return 'capture.height must be "full" or a number (viewport height in px)';
+  }
+  if (
+    themes !== undefined &&
+    (!Array.isArray(themes) || themes.some((theme) => theme !== "light" && theme !== "dark"))
+  ) {
+    return 'capture.themes must be an array of "light" and "dark"';
+  }
+  return null;
+}
+
 /** Why a block cannot be rendered, or null when it is well formed. */
 function blockProblem(block: unknown): string | null {
   if (!block || typeof block !== "object") return "a block is not an object";
@@ -78,6 +98,7 @@ function blockProblem(block: unknown): string | null {
     if (screens.some((screen) => !screen || typeof screen.id !== "string" || !isComponent(screen.render))) {
       return "every screen needs an id, a label and a render component";
     }
+    return captureProblem(b.capture);
   } else if (!isComponent(b.render)) {
     return `a ${String(b.kind)} block needs a render component`;
   }

package/src/shell/ExportDialog.tsx

@@ -2,8 +2,10 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import type { Design } from "../../shared/design.ts";
 import type { ClientMessage, ExportWriteResult } from "../../shared/protocol.ts";
 import { exportCss, exportJson, exportTailwind } from "../../shared/tokens.ts";
+import { BrowseButton } from "./FolderField.tsx";
 import { readPref, writePref } from "./prefs.ts";
 import styles from "./Shell.module.css";
+import { VerifyKit, type VerifyKitProps } from "./VerifyKit.tsx";
 
 const FORMATS = [
   { id: "css", label: "CSS variables", file: "tokens.css", type: "text/css", build: exportCss },
@@ -11,7 +13,7 @@ const FORMATS = [
   { id: "json", label: "JSON", file: "design-system.json", type: "application/json", build: exportJson },
 ] as const;
 
-type Tab = "kit" | (typeof FORMATS)[number]["id"];
+type Tab = "kit" | "verify" | (typeof FORMATS)[number]["id"];
 
 interface ExportDialogProps {
   design: Design;
@@ -22,6 +24,7 @@ interface ExportDialogProps {
   result: ExportWriteResult | null;
   send: (message: ClientMessage) => void;
   onClose: () => void;
+  verify: Omit<VerifyKitProps, "workspace" | "send">;
 }
 
 /** The folder the kit was last written to, remembered per project so one never writes into another's. */
@@ -40,6 +43,7 @@ function StarterKit({
 }: Pick<ExportDialogProps, "workspace" | "problems" | "manifest" | "result" | "send">) {
   const [target, setTarget] = useState(() => readPref(targetPref(workspace)) ?? "");
   const [pending, setPending] = useState(false);
+  const [browseError, setBrowseError] = useState<string | null>(null);
   // Only show results of writes made while this dialog is open.
   const [stale] = useState(latest);
   const result = latest === stale ? null : latest;
@@ -103,13 +107,20 @@ function StarterKit({
             id="export-target"
             value={target}
             onChange={(event) => setTarget(event.target.value)}
-            placeholder="C:\Code\my-app\src\design-system"
+            placeholder="Browse, or paste the folder's path"
             spellCheck={false}
           />
+          <BrowseButton
+            title="Choose the folder to write the starter kit into"
+            start={target}
+            onPick={setTarget}
+            onError={setBrowseError}
+          />
           <button type="submit" className={styles.chromeButton} disabled={!target.trim() || pending}>
             {pending ? "Writing…" : "Write files"}
           </button>
         </div>
+        {browseError && <p className={styles.kitError}>{browseError}</p>}
         {result?.error && <p className={styles.kitError}>{result.error}</p>}
         {conflicts && (
           <div className={styles.kitConflicts}>
@@ -138,7 +149,16 @@ function StarterKit({
   );
 }
 
-export function ExportDialog({ design, workspace, problems, manifest, result, send, onClose }: ExportDialogProps) {
+export function ExportDialog({
+  design,
+  workspace,
+  problems,
+  manifest,
+  result,
+  send,
+  onClose,
+  verify,
+}: ExportDialogProps) {
   const dialog = useRef<HTMLDialogElement>(null);
   const [tab, setTab] = useState<Tab>("kit");
   const [copied, setCopied] = useState(false);
@@ -189,6 +209,9 @@ export function ExportDialog({ design, workspace, problems, manifest, result, se
           <button type="button" role="tab" aria-selected={tab === "kit"} onClick={() => setTab("kit")}>
             Starter kit
           </button>
+          <button type="button" role="tab" aria-selected={tab === "verify"} onClick={() => setTab("verify")}>
+            Verification kit
+          </button>
           {FORMATS.map((item) => (
             <button
               key={item.id}
@@ -203,11 +226,25 @@ export function ExportDialog({ design, workspace, problems, manifest, result, se
         </div>
         {tab === "kit" ? (
           <StarterKit workspace={workspace} problems={problems} manifest={manifest} result={result} send={send} />
+        ) : tab === "verify" ? (
+          <VerifyKit workspace={workspace} send={send} {...verify} />
         ) : (
           <pre className={styles.code}>{code}</pre>
         )}
         <footer className={styles.dialogFooter}>
-          {tab === "kit" ? (
+          {tab === "verify" ? (
+            <>
+              <span className={styles.muted}>basis-verify/ · takes a few seconds per screen</span>
+              <button
+                type="button"
+                className={styles.primaryButton}
+                disabled={verify.progress !== null}
+                onClick={() => send({ type: "verify-kit" })}
+              >
+                {verify.progress ? "Building…" : "Build .zip"}
+              </button>
+            </>
+          ) : tab === "kit" ? (
             <>
               <span className={styles.muted}>{manifest ? `${manifest.folder}.zip` : ""}</span>
               <a className={styles.primaryButton} href="/export/starter-kit.zip" download>

package/src/shell/FolderField.tsx

@@ -0,0 +1,131 @@
+import { useEffect, useState } from "react";
+import styles from "./Shell.module.css";
+
+/*
+ * Choosing a folder without typing its path: the operating system's own folder dialog, opened by the Basis server
+ * (it runs on this computer), and the git repos it finds in the usual places for code.
+ */
+
+async function api<T>(path: string, body: object = {}): Promise<T> {
+  const response = await fetch(path, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) throw new Error(`Basis answered ${response.status}`);
+  return (await response.json()) as T;
+}
+
+interface BrowseButtonProps {
+  /** The title of the system's folder dialog. */
+  title: string;
+  /** Where the dialog starts; the user's home folder when empty or missing. */
+  start: string;
+  onPick: (path: string) => void;
+  onError: (message: string | null) => void;
+}
+
+/** Opens the system's folder dialog; the folder the user chooses fills the field. */
+export function BrowseButton({ title, start, onPick, onError }: BrowseButtonProps) {
+  const [open, setOpen] = useState(false);
+  const browse = async () => {
+    setOpen(true);
+    onError(null);
+    try {
+      const answer = await api<{ path: string | null; error?: string }>("/api/pick-folder", { title, start });
+      if (answer.path) onPick(answer.path);
+      if (answer.error) onError(answer.error);
+    } catch (error) {
+      onError((error as Error).message);
+    } finally {
+      setOpen(false);
+    }
+  };
+  return (
+    <button type="button" className={styles.chromeButton} onClick={() => void browse()} disabled={open}>
+      {open ? "Choose in the dialog…" : "Browse…"}
+    </button>
+  );
+}
+
+interface RepoSuggestion {
+  name: string;
+  dir: string;
+}
+
+interface FolderFieldProps {
+  id: string;
+  label: string;
+  value: string;
+  onChange: (path: string) => void;
+  placeholder: string;
+  /** The title of the system's folder dialog. */
+  dialogTitle: string;
+  /** Offers the git repos found on this computer, the most recently used first. */
+  suggestRepos?: boolean;
+  autoFocus?: boolean;
+}
+
+/** A folder path: typed or pasted, chosen in the system's dialog, or picked from the repos Basis found. */
+export function FolderField({
+  id,
+  label,
+  value,
+  onChange,
+  placeholder,
+  dialogTitle,
+  suggestRepos = false,
+  autoFocus,
+}: FolderFieldProps) {
+  const [error, setError] = useState<string | null>(null);
+  const [repos, setRepos] = useState<RepoSuggestion[]>([]);
+
+  useEffect(() => {
+    if (!suggestRepos) return;
+    let current = true;
+    api<{ repos: RepoSuggestion[] }>("/api/repos")
+      .then((answer) => current && setRepos(answer.repos))
+      .catch(() => {});
+    return () => {
+      current = false;
+    };
+  }, [suggestRepos]);
+
+  return (
+    <>
+      <label htmlFor={id}>{label}</label>
+      <div className={styles.folderRow}>
+        <input
+          id={id}
+          value={value}
+          onChange={(event) => onChange(event.target.value)}
+          placeholder={placeholder}
+          spellCheck={false}
+          autoComplete="off"
+          autoFocus={autoFocus}
+        />
+        <BrowseButton title={dialogTitle} start={value} onPick={onChange} onError={setError} />
+      </div>
+      {error && <p className={styles.kitError}>{error}</p>}
+      {repos.length > 0 && (
+        <div className={styles.repoSuggestions} role="group" aria-label="Repos on this computer">
+          <span className={styles.muted}>Repos on this computer</span>
+          <div>
+            {repos.slice(0, 8).map((repo) => (
+              <button
+                key={repo.dir}
+                type="button"
+                className={styles.repoChip}
+                aria-pressed={value === repo.dir}
+                title={repo.dir}
+                onClick={() => onChange(repo.dir)}
+              >
+                {repo.name}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+    </>
+  );
+}

package/src/shell/ProjectMenu.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useId, useRef, useState } from "react";
 import type { ClientMessage, ProjectEntry, TemplateUpdate } from "../../shared/protocol.ts";
+import { FolderField } from "./FolderField.tsx";
 import styles from "./Shell.module.css";
 
 interface ProjectMenuProps {
@@ -341,32 +342,33 @@ function ProjectDialog({ mode, current, error, onSubmit, onClose }: ProjectDialo
                 </label>
               </fieldset>
               {fromRepo && (
-                <>
-                  <label htmlFor="project-repo">Repo folder</label>
-                  <input
-                    id="project-repo"
-                    value={dir}
-                    onChange={(event) => setDir(event.target.value)}
-                    placeholder="C:\\Code\\my-app"
-                    spellCheck={false}
-                    autoComplete="off"
-                  />
-                </>
+                <FolderField
+                  id="project-repo"
+                  label="Repo folder"
+                  value={dir}
+                  onChange={setDir}
+                  placeholder="Browse, pick a repo below, or paste its path"
+                  dialogTitle="Choose the product repo"
+                  suggestRepos
+                />
               )}
             </>
           ) : (
             <>
-              <label htmlFor="project-dir">{mode === "repo" ? "Repo folder" : "Folder"}</label>
-              <input
+              <FolderField
                 id="project-dir"
+                label={mode === "repo" ? "Repo folder" : "Folder"}
                 value={dir}
-                onChange={(event) => setDir(event.target.value)}
-                placeholder={mode === "repo" ? "C:\\Code\\my-app" : "C:\\Code\\my-app\\design-system"}
-                spellCheck={false}
-                autoComplete="off"
+                onChange={setDir}
+                placeholder={
+                  mode === "repo" ? "Browse, pick a repo below, or paste its path" : "Browse, or paste its path"
+                }
+                dialogTitle={
+                  mode === "repo" ? "Choose the product repo" : "Choose a Basis workspace or an empty folder"
+                }
+                suggestRepos={mode === "repo"}
                 autoFocus
               />
-              <p className={styles.muted}>Use the full path.</p>
               {mode === "repo" && (
                 <label className={styles.projectCheck}>
                   <input type="checkbox" checked={bringIn} onChange={(event) => setBringIn(event.target.checked)} />