@jxsuite/studio 6.1.1 → 8.0.0

package/src/files/components.ts

@@ -4,7 +4,8 @@ import { getPlatform } from "../platform";
 import { projectState } from "../store";
 import type { ComponentMeta } from "../types";
 import { componentMetaFrom } from "@jxsuite/schema/component-meta";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue, JxMutableNode } from "@jxsuite/schema/types";
 
 /** A discovered component: project components carry a file path; package components may not. */
 export interface ComponentEntry extends Omit<ComponentMeta, "path"> {
@@ -17,14 +18,39 @@ export interface ComponentEntry extends Omit<ComponentMeta, "path"> {
 export let componentRegistry: ComponentEntry[] = [];
 export let _componentRegistryLoaded = false;
 
-export async function loadComponentRegistry() {
-  try {
-    const platform = getPlatform();
-    componentRegistry = await platform.discoverComponents(projectState?.projectRoot || undefined);
-    _componentRegistryLoaded = true;
-  } catch {
+/** Bumped by every load, so only the newest scan may write the registry. */
+let _generation = 0;
+/** The newest scan, which a superseded one waits on so its caller still sees a loaded registry. */
+let _newest: Promise<void> = Promise.resolve();
+
+/**
+ * Scan the project's components into the registry.
+ *
+ * Scans can overlap (the project-open path and the Site panel each start one), and a scan bound to
+ * the project being closed may resolve after the next project's. So the newest scan wins: an older
+ * one discards what it read and resolves when the newest has written the registry.
+ */
+export function loadComponentRegistry(): Promise<void> {
+  _generation += 1;
+  const generation = _generation;
+  const scan = (async () => {
+    let found: ComponentEntry[] | null = null;
+    try {
+      found = await getPlatform().discoverComponents(projectState?.projectRoot || undefined);
+    } catch {
+      found = null;
+    }
+    if (generation !== _generation) {
+      await _newest;
+      return;
+    }
+    if (found) {
+      componentRegistry = found;
+    }
     _componentRegistryLoaded = true;
-  }
+  })();
+  _newest = scan;
+  return scan;
 }
 
 /**
@@ -40,15 +66,17 @@ export async function loadComponentRegistry() {
  *
  * @param {string | null} path - The saved document's project-relative path; `null` for an unsaved
  *   draft, which no scan would have seen either.
- * @param {unknown} doc - The saved document.
+ * @param {JxMutableNode} doc - The saved document.
  * @returns {boolean} Whether the registry changed, so a caller knows to repaint what reads it.
  */
-export function noteComponentSaved(path: string | null, doc: unknown): boolean {
+export function noteComponentSaved(path: string | null, doc: JxMutableNode): boolean {
   if (!path) {
     return false;
   }
   const index = componentRegistry.findIndex((c) => c.path === path);
-  const meta = componentMetaFrom(doc, path);
+  /* SAFETY: a saved tab's document was parsed from JSON and has just been written back as JSON
+     (`serializeDocument`), so every value it holds is a JSON value — the model the extractor reads. */
+  const meta = componentMetaFrom(doc as JsonValue, path);
   if (!meta) {
     if (index === -1) {
       return false;
@@ -56,6 +84,8 @@ export function noteComponentSaved(path: string | null, doc: unknown): boolean {
     componentRegistry.splice(index, 1);
     return true;
   }
+  /* SAFETY: `componentMetaFrom` is the extractor every backend's `discoverComponents` scan runs to
+     Produce the registry's entries, so its output has the shape the registry already holds. */
   const entry = meta as ComponentEntry;
   if (index === -1) {
     componentRegistry.push(entry);
@@ -84,7 +114,7 @@ export function buildComponentInstance(comp: ComponentEntry): JxMutableNode {
     for (const child of structuredClone(slot.fallback ?? [])) {
       if (!slot.name) {
         children.push(child);
-      } else if (typeof child === "object" && child !== null && typeof child.tagName === "string") {
+      } else if (isNonNullObject(child) && isString(child.tagName)) {
         // Preserve an author-set slot attribute (slot forwarding inside fallback).
         child.attributes = { slot: slot.name, ...child.attributes };
         children.push(child);
@@ -94,26 +124,65 @@ export function buildComponentInstance(comp: ComponentEntry): JxMutableNode {
       }
     }
   }
-  return {
-    $props,
-    tagName: comp.tagName,
-    ...(children.length > 0 ? { children } : {}),
-  };
+  const instance: JxMutableNode = { $props, tagName: comp.tagName };
+  if (children.length > 0) {
+    instance.children = children;
+  }
+  return instance;
+}
+
+/**
+ * Walk `parts` the way a path resolver does: `.` stays, `..` climbs, the rest descend. A climb
+ * above the start is kept as a leading `..`, which is how a project-relative path names a file
+ * outside the project.
+ */
+function normalizeParts(parts: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const part of parts) {
+    if (part === ".") {
+      continue;
+    }
+    if (part === ".." && out.length > 0 && out.at(-1) !== "..") {
+      out.pop();
+    } else {
+      out.push(part);
+    }
+  }
+  return out;
 }
 
 /**
+ * The `$ref` a document at `fromDocPath` writes to reach `toCompPath`, both project-relative.
+ *
+ * A document can sit OUTSIDE the project: jxsuite.com's docs collection is `../../docs`, so an
+ * entry is `../../docs/extending/x.md`. Climbing from there back into the project needs the names
+ * of the folders the project sits in, which a project-relative path does not carry; counting its
+ * segments gave five `../` and a ref into a folder that does not exist, so every component a docs
+ * layout imports failed to register on the canvas. Such a path is resolved against `projectRoot`
+ * (the open project's, by default), the way the browser resolves the ref.
+ *
  * @param {string | null} fromDocPath
  * @param {string} toCompPath
+ * @param {string | null} [projectRoot]
  */
-export function computeRelativePath(fromDocPath: string | null, toCompPath: string) {
+export function computeRelativePath(
+  fromDocPath: string | null,
+  toCompPath: string,
+  projectRoot: string | null = projectState?.projectRoot ?? null,
+) {
   if (!fromDocPath) {
     return `./${toCompPath}`;
   }
   const from = fromDocPath.replaceAll("\\", "/");
   const to = toCompPath.replaceAll("\\", "/");
   const fromDir = from.includes("/") ? from.slice(0, from.lastIndexOf("/")) : "";
-  const fromParts = fromDir.split("/").filter(Boolean);
-  const toParts = to.split("/").filter(Boolean);
+  let fromParts = normalizeParts(fromDir.split("/").filter(Boolean));
+  let toParts = normalizeParts(to.split("/").filter(Boolean));
+  if (fromParts[0] === ".." && projectRoot) {
+    const rootParts = projectRoot.replaceAll("\\", "/").split("/").filter(Boolean);
+    fromParts = normalizeParts([...rootParts, ...fromParts]);
+    toParts = normalizeParts([...rootParts, ...toParts]);
+  }
   let common = 0;
   while (
     common < fromParts.length &&

package/src/files/elements.ts

@@ -20,6 +20,7 @@
  * they must not differ on is WHICH entries the list should hold.
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { computeRelativePath } from "./components";
 import type { ComponentEntry } from "./components";
 import type { JxElement } from "@jxsuite/schema/types";
@@ -29,9 +30,7 @@ export type ElementsEntry = string | JxElement | { $ref: string };
 
 /** The `$ref` of an entry, when it has one. */
 function refOf(entry: ElementsEntry): string | null {
-  return typeof entry === "object" && entry !== null && typeof entry.$ref === "string"
-    ? entry.$ref
-    : null;
+  return isNonNullObject(entry) && isString(entry.$ref) ? entry.$ref : null;
 }
 
 /**
@@ -81,7 +80,7 @@ export function hasElement(
   const specifier = npmSpecifier(comp);
   if (specifier) {
     return elements.some(
-      (entry) => typeof entry === "string" && (entry === specifier || entry === comp.package),
+      (entry) => isString(entry) && (entry === specifier || entry === comp.package),
     );
   }
   if (!comp.path) {
@@ -132,7 +131,7 @@ export function disableElement(
   if (specifier) {
     // Both spellings: a component ticked off must not stay imported through the package entry.
     return elements.filter(
-      (entry) => !(typeof entry === "string" && (entry === specifier || entry === comp.package)),
+      (entry) => !(isString(entry) && (entry === specifier || entry === comp.package)),
     );
   }
   if (!comp.path) {
@@ -151,7 +150,7 @@ export function removePackageElements(
   pkg: string,
 ): ElementsEntry[] {
   return elements.filter(
-    (entry) => typeof entry !== "string" || !(entry === pkg || entry.startsWith(`${pkg}/`)),
+    (entry) => !isString(entry) || !(entry === pkg || entry.startsWith(`${pkg}/`)),
   );
 }
 

package/src/files/file-ops.ts

@@ -28,6 +28,8 @@ import { showConfirmDialog } from "../ui/layers";
 import { locateDocument } from "../services/code-services";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { notify } from "../services/notify";
+import type { NotifyOptions } from "../services/notify";
+import { isString } from "@jxsuite/schema/guards";
 import { validateComponentSlots } from "../services/cem-export";
 import { reportPopoverProblems } from "../services/popover-report";
 import { getPlatform } from "../platform";
@@ -103,19 +105,68 @@ export async function parseSourceForPath(path: string, source: string) {
 export const parseCollabSource: CollabParser = async (tab, text) => {
   if (tab.documentPath && formatForPath(tab.documentPath)) {
     const parsed = await parseSourceForPath(tab.documentPath, text);
-    return { document: parsed.document as JxMutableNode, frontmatter: parsed.frontmatter };
+    // The peer's text is what this client saves against now, as `layout` is for a JSON file.
+    tab.doc.source = text;
+    return { document: parsed.document, frontmatter: parsed.frontmatter };
   }
   const parsed = parseJsonDocument(text);
   tab.doc.layout = parsed.layout;
+  /* SAFETY: a co-edited path no format class claims is a `.json` Jx document (every other path
+     `ensureCollab` attaches to is a format file, handled above), and that file's schema makes its
+     Top-level object a node — the object `parseJsonDocument` already states it returns. */
   return { document: parsed.document as JxMutableNode };
 };
 
+/** One `accept` group of a File System Access picker: media type → extensions, with a label. */
+interface FilePickerAcceptType {
+  accept: Record<string, string[]>;
+  description: string;
+}
+
+/**
+ * The File System Access pickers (WICG), which TypeScript's DOM lib does not declare. Only what
+ * this module passes and reads is spelled out.
+ */
+interface FilePickerWindow {
+  showOpenFilePicker: (options: {
+    types: FilePickerAcceptType[];
+  }) => Promise<FileSystemFileHandle[]>;
+  /* Export's single extension is `format.extensions[0]`, absent for a format that declares none —
+     So the save picker is typed with the value it is actually handed. */
+  showSaveFilePicker: (options: {
+    suggestedName?: string | undefined;
+    types: { accept: Record<string, (string | undefined)[]>; description: string }[];
+  }) => Promise<FileSystemFileHandle>;
+}
+
+/** Whether this browser offers `showOpenFilePicker` (Chromium does; Firefox and Safari do not). */
+function hasOpenFilePicker(
+  win: Window,
+): win is Window & Pick<FilePickerWindow, "showOpenFilePicker"> {
+  return "showOpenFilePicker" in win;
+}
+
+/** Whether this browser offers `showSaveFilePicker` (Chromium does; Firefox and Safari do not). */
+function hasSaveFilePicker(
+  win: Window,
+): win is Window & Pick<FilePickerWindow, "showSaveFilePicker"> {
+  return "showSaveFilePicker" in win;
+}
+
+/** Attach the tab's file to a notification's options, when it has one. */
+function atTabPath(tab: Tab, options: NotifyOptions): NotifyOptions {
+  if (tab.documentPath !== null) {
+    options.path = tab.documentPath;
+  }
+  return options;
+}
+
 /** Open a file via the File System Access API (or fallback input). */
 export async function openFile() {
   try {
     await loadFormats();
     const formats = getFormats();
-    const pickerTypes = [
+    const pickerTypes: FilePickerAcceptType[] = [
       {
         accept: { "application/json": [".json"] },
         description: "Jx Component",
@@ -146,6 +197,7 @@ export async function openFile() {
           fileHandle: handle,
           frontmatter,
           id: name,
+          source: text,
           sourceFormat: format.name,
         });
       } else if (name.endsWith(".json")) {
@@ -160,12 +212,8 @@ export async function openFile() {
       // Trail; it does not need a message that erases itself.
     };
 
-    if ("showOpenFilePicker" in window) {
-      const [handle] = await (
-        window as unknown as {
-          showOpenFilePicker: (options?: unknown) => Promise<FileSystemFileHandle[]>;
-        }
-      ).showOpenFilePicker({ types: pickerTypes });
+    if (hasOpenFilePicker(window)) {
+      const [handle] = await window.showOpenFilePicker({ types: pickerTypes });
       const file = await handle!.getFile();
       await handleSource(handle!.name, await file.text(), handle!);
     } else {
@@ -209,37 +257,38 @@ export async function openFile() {
  * **By injection**, the idiom `setSurfaceTeardown` and `setDiffRepaint` already use. The one
  * listener today is source control: a comparison is two texts read once, so it does not notice a
  * save on its own, and the file an author is most likely to save is the one they are reviewing. A
- * direct import would put `panels/git-panel.ts` into this module's graph, which is a load error for
- * every suite that mocks the canvas host out from under it.
+ * direct import would put `publish/source-control.ts` and the comparison opener behind it into this
+ * module's graph, which is a load error for every suite that mocks the canvas host out from under
+ * it.
  *
  * The listener is handed the document as well as the path, for the second listener: the live chrome
  * lane (`services/live-surfaces.ts`) re-mounts a saved surface from the document the tab just wrote
  * rather than reading the file back, which is what keeps the shipped app from ever reading its
  * chrome from disk.
  */
-let _onDocumentSaved: (path: string | null, doc: JxMutableNode) => void = () => {};
+let _onDocumentSaved: (path: string | null, doc: JxMutableNode, tab: Tab) => void = () => {};
 
 /** Register the save listener. Called once, from the bootstrap. */
 export function setDocumentSavedListener(
-  listener: (path: string | null, doc: JxMutableNode) => void,
+  listener: (path: string | null, doc: JxMutableNode, tab: Tab) => void,
 ): void {
   _onDocumentSaved = listener;
 }
 
 function reportSaved(tab: Tab) {
   const doc = tab.doc.document;
-  _onDocumentSaved(tab.documentPath, doc);
+  _onDocumentSaved(tab.documentPath, doc, tab);
   const warning =
-    typeof doc.tagName === "string" && doc.tagName.includes("-")
-      ? validateComponentSlots(doc)
-      : null;
+    isString(doc.tagName) && doc.tagName.includes("-") ? validateComponentSlots(doc) : null;
   if (warning) {
-    notify.warn(warning, {
-      key: `slots:${tab.documentPath ?? tab.id}`,
-      ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
-      source: "Components",
-      tier: "problem",
-    });
+    notify.warn(
+      warning,
+      atTabPath(tab, {
+        key: `slots:${tab.documentPath ?? tab.id}`,
+        source: "Components",
+        tier: "problem",
+      }),
+    );
   }
   /* Popover correctness, beside the slot check and for the same reason it is here: a successful
      save is the one chokepoint every edit passes through, whichever surface made it. A render-time
@@ -311,12 +360,11 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
     notify.warn(
       `You have read access to this session — changes to ${tab.documentPath ?? "this document"} ` +
         `stay in your browser and cannot be saved.`,
-      {
+      atTabPath(tab, {
         action: "file.save",
         key: `save.readOnly:${tab.documentPath ?? tab.id}`,
-        ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
         source: "Collaboration",
-      },
+      }),
     );
     return false;
   }
@@ -327,11 +375,10 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
   if (!hasSerializableDocument(tab)) {
     notify.warn(
       `${tab.documentPath ?? "This file"} is a media file, so there is no document for Save to write.`,
-      {
+      atTabPath(tab, {
         key: `save.notADocument:${tab.documentPath ?? tab.id}`,
-        ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
         source: "Save",
-      },
+      }),
     );
     return false;
   }
@@ -355,6 +402,9 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
       const platform = getPlatform();
       await platform.writeFile(tab.documentPath, output);
       tab.doc.dirty = false;
+      if (tab.doc.sourceFormat !== null) {
+        tab.doc.source = output;
+      }
       /* Retract the unsaved bytes NOW rather than a debounce later. The write also reaches the
          backend's filesystem watcher, and a live preview coalesces both into one reload only if
          they arrive together — otherwise a save costs two. */
@@ -375,19 +425,24 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
       await writable.write(output);
       await writable.close();
       tab.doc.dirty = false;
+      if (tab.doc.sourceFormat !== null) {
+        tab.doc.source = output;
+      }
       reportSaved(tab);
       return true;
     }
     notify.warn("This document has no save target — use Export.", { key: "save.noTarget" });
   } catch (error) {
     if (!(error instanceof Error && error.name === "AbortError")) {
-      notify.error(`Could not save ${tab.documentPath ?? tab.id}.`, {
-        action: "file.save",
-        detail: errorMessage(error),
-        key: `save:${tab.documentPath ?? tab.id}`,
-        ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
-        source: "Save",
-      });
+      notify.error(
+        `Could not save ${tab.documentPath ?? tab.id}.`,
+        atTabPath(tab, {
+          action: "file.save",
+          detail: errorMessage(error),
+          key: `save:${tab.documentPath ?? tab.id}`,
+          source: "Save",
+        }),
+      );
     }
   }
   return false;
@@ -418,13 +473,9 @@ export async function exportFile() {
     const description = format ? format.name : "Jx Component";
     const fallbackName = format ? `content${ext}` : "component.json";
 
-    if ("showSaveFilePicker" in window) {
+    if (hasSaveFilePicker(window)) {
       const suggestedName = tab.documentPath ? tab.documentPath.split("/").pop() : fallbackName;
-      const handle = await (
-        window as unknown as {
-          showSaveFilePicker: (options?: unknown) => Promise<FileSystemFileHandle>;
-        }
-      ).showSaveFilePicker({
+      const handle = await window.showSaveFilePicker({
         suggestedName,
         types: [{ accept: { [mimeType]: [ext] }, description }],
       });