@jxsuite/studio 2.4.3 → 4.0.0

package/src/format/format-choices.ts

@@ -0,0 +1,199 @@
+/**
+ * Format-choices — the two derived predicates behind "which format may I create?" and "which format
+ * may I convert to?".
+ *
+ * Both are computed from what a format class DECLARES — `capabilities.parse`,
+ * `capabilities.serialize`, `format.documentKinds` — so a third format extension appears in the New
+ * File picker and in Convert To with no edit to this file, which is the same contract
+ * `format/format-host.ts` already keeps for opening and saving.
+ *
+ * Pure and synchronous over the loaded registry and `projectState`, because the Files tree's
+ * context menu is built during a render and cannot await anything.
+ */
+
+import { collectionForFile } from "../content/collection-match";
+import { documentExtensions, formatByExtension, formatForPath, getFormats } from "./format-host";
+import { projectState } from "../store";
+
+/** One row of a format picker: the extension it writes, and the name the reader sees. */
+export interface FormatChoiceRow {
+  ext: string;
+  label: string;
+}
+
+/**
+ * The document kinds that mean "this format's `parse` returns a Jx document".
+ *
+ * There is no separate declaration for the SHAPE `parse` returns, and none is needed: the compiler
+ * builds its page and component globs from `documentExtensions("page")` /
+ * `documentExtensions("component")` and casts every `parse` result to `JxDocument`
+ * (`packages/compiler/src/site/pages-discovery.ts`). So declaring either kind IS the claim, already
+ * relied upon by the build. A `content`-only format — Csv, whose `parse` returns
+ * `ContentLoaderEntry[]` rows — makes no such claim and is excluded by the same test.
+ */
+const DOCUMENT_KINDS = ["page", "component"] as const;
+
+/**
+ * Where a Jx document lives.
+ *
+ * Both keys are conventions the build hard-codes rather than reads (`site-build.ts` resolves
+ * `pages` against the project root), so a convert may lean on them. It is deliberately
+ * conservative: a component kept in `shared/` is not offered a conversion, which is a smaller wrong
+ * than offering one for `package.json`, `tsconfig.json` or a `nav.json` that no format and no
+ * schema claims.
+ */
+const DOCUMENT_ROOTS = { components: "component", pages: "page" } as const;
+
+/** Normalise a project-relative path for prefix comparison. */
+function normalize(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+/** Which document root a path sits under, or null. */
+function documentRootOf(path: string): "page" | "component" | null {
+  const lower = normalize(path).toLowerCase();
+  for (const [dir, kind] of Object.entries(DOCUMENT_ROOTS)) {
+    if (lower.startsWith(`${dir}/`)) {
+      return kind;
+    }
+  }
+  return null;
+}
+
+/** Whether a format declares at least one of the document kinds. */
+function declaresDocumentKind(kinds: readonly string[]): boolean {
+  return DOCUMENT_KINDS.some((kind) => kinds.includes(kind));
+}
+
+/**
+ * Whether this path is (or is used as) a layout.
+ *
+ * Layouts are JSON at BOTH readers — `packages/compiler/src/site/layout-resolver.ts` `JSON.parse`s
+ * and throws, `packages/studio/src/site-context.ts` `JSON.parse`s and silently returns null — and
+ * there is no `"layout"` document kind for a format to declare, so this clause is hand-written and
+ * cannot be derived. `layouts/` is excluded by {@link DOCUMENT_ROOTS} already; what remains is a
+ * project whose `layout` points somewhere inside a document root.
+ */
+function isLayoutPath(path: string): boolean {
+  const declared = projectState?.projectConfig?.layout;
+  if (typeof declared !== "string") {
+    return false;
+  }
+  return normalize(declared).toLowerCase() === normalize(path).toLowerCase();
+}
+
+/**
+ * The rows the New File format picker offers, `.json` first.
+ *
+ * A format qualifies only when SOME registered class can both `parse` and `serialize` its
+ * extension. Both halves are load-bearing and neither is cosmetic:
+ *
+ * - Without `parse`, opening the file that was just created throws `noFormatError`
+ *   (`files/file-ops.ts`'s `parseSourceForPath`);
+ * - Without `serialize`, the first save falls through to `defaultContentFormat()` and writes ANOTHER
+ *   format's bytes into the file (`files/file-ops.ts`'s `serializeDocument`).
+ *
+ * Looked up per `(extension, capability)` rather than per format row because the registry
+ * deliberately legalises a split claim — one class parsing an extension, another serializing it.
+ *
+ * @param kind - Restrict to formats declaring this document kind (the Library's New ▸ Page).
+ * @returns The picker's format rows, without the caller's own sentinel rows.
+ */
+export function creationFormats(kind?: "page" | "component" | "content"): FormatChoiceRow[] {
+  const rows: FormatChoiceRow[] = [{ ext: ".json", label: "JSON (.json)" }];
+  for (const ext of documentExtensions(kind)) {
+    const reader = formatByExtension(ext, "parse");
+    if (reader && formatByExtension(ext, "serialize")) {
+      rows.push({ ext, label: `${reader.name} (${ext})` });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Every extension the studio recognises as a document — `.json` plus everything any registered
+ * format claims, whether or not it is creatable.
+ *
+ * This is the set a name is tested against, not {@link creationFormats}: a typed `notes.csv` must be
+ * recognised as naming a format the picker did not offer, rather than treated as an unremarkable
+ * suffix.
+ */
+export function knownDocumentExtensions(): Set<string> {
+  return new Set([".json", ...getFormats().flatMap((format) => format.extensions)]);
+}
+
+/**
+ * The formats this file may be converted INTO, or an empty list when it may not be converted at
+ * all.
+ *
+ * Empty is the answer for, and only for:
+ *
+ * - A file outside `pages/` and `components/` — including every `.json` that is configuration rather
+ *   than a document, and every `layouts/` file;
+ * - The project's declared `layout`, wherever it lives;
+ * - Anything inside a content collection, in EITHER direction. Converting an entry drops it out of
+ *   its collection's discovery glob; converting a co-located file INTO the collection's format
+ *   enlists it as an entry nobody seeded. Source and target share a directory, so one test covers
+ *   both;
+ * - A source whose format cannot `parse`, or declares no document kind (Csv);
+ * - A source for which no OTHER format can `serialize` a document.
+ *
+ * @param path - Project-relative file path.
+ * @returns The target rows, or `[]`.
+ */
+export function convertTargets(path: string | null | undefined): FormatChoiceRow[] {
+  if (path === null || path === undefined || path === "") {
+    return [];
+  }
+  const root = documentRootOf(path);
+  if (root === null || isLayoutPath(path) || collectionForFile(path)) {
+    return [];
+  }
+
+  const source = formatForPath(path);
+  const readable = source
+    ? Boolean(source.capabilities.parse) && declaresDocumentKind(source.documentKinds)
+    : normalize(path).toLowerCase().endsWith(".json");
+  if (!readable) {
+    return [];
+  }
+
+  const rows: FormatChoiceRow[] = [];
+  if (source) {
+    rows.push({ ext: ".json", label: "JSON (.json)" });
+  }
+  for (const ext of documentExtensions()) {
+    const writer = formatByExtension(ext, "serialize");
+    if (
+      !writer ||
+      writer.name === source?.name ||
+      !declaresDocumentKind(writer.documentKinds) ||
+      !writer.documentKinds.includes(root)
+    ) {
+      continue;
+    }
+    rows.push({ ext, label: `${writer.name} (${ext})` });
+  }
+  return rows;
+}
+
+/**
+ * Every extension that is a conversion target SOMEWHERE in this project — the enum behind
+ * `file.convertFormat`'s `format` argument.
+ *
+ * Necessarily broader than {@link convertTargets}, which is answered per file: a command argument's
+ * declared values cannot depend on another argument. The per-file rule still decides, and
+ * `convertFile` re-checks it, so this list is what may be ASKED for and not what will be accepted.
+ */
+export function convertTargetExtensions(): string[] {
+  const exts = new Set<string>([".json"]);
+  for (const format of getFormats()) {
+    if (!format.capabilities.serialize || !declaresDocumentKind(format.documentKinds)) {
+      continue;
+    }
+    for (const ext of format.extensions) {
+      exts.add(ext);
+    }
+  }
+  return [...exts].toSorted();
+}

package/src/grid/grid-idle.ts

@@ -0,0 +1,45 @@
+/**
+ * Grid-idle.ts — the grid's quiescence registry, and nothing else.
+ *
+ * A separate module from `grid-view.ts` for one reason: `services/idle.ts` must be able to ASK
+ * whether any grid is mid-flight without pulling Tabulator into its import graph. It read the
+ * probes from `grid-view.ts` first, and `grid-view.ts` imports `tabulator-tables` at module load —
+ * so every test that transitively reached `idle.ts` (which is most of them, through the shell)
+ * tried to evaluate the Tabulator ESM bundle and died with `Export named 'ClipboardModule' not
+ * found` unless it had thought to mock a module it never uses.
+ *
+ * So the dependency points the other way: this file imports nothing, `idle.ts` reads it, and
+ * `grid-view.ts` writes to it.
+ */
+
+/** Answers `null` when its grid is settled, or a human-readable reason when it is not. */
+export type GridProbe = () => string | null;
+
+const liveGrids = new Set<GridProbe>();
+
+/** Register a live grid. The returned function deregisters it — call it from `destroy()`. */
+export function registerGridProbe(probe: GridProbe): () => void {
+  liveGrids.add(probe);
+  return () => liveGrids.delete(probe);
+}
+
+/**
+ * Grids still building, or still laying out their selection range.
+ *
+ * A probe must never throw: it runs inside the idle predicate, and an exception there would be
+ * indistinguishable from a subsystem that never settles.
+ */
+export function gridIdleBlockers(): readonly string[] {
+  const blockers: string[] = [];
+  for (const probe of liveGrids) {
+    try {
+      const reason = probe();
+      if (reason) {
+        blockers.push(reason);
+      }
+    } catch {
+      // A table torn down between registration and probe is settled by definition.
+    }
+  }
+  return blockers;
+}

package/src/grid/grid-view.ts

@@ -40,6 +40,7 @@ import type {
 } from "tabulator-tables";
 import type { GridCellValue, GridColumn } from "./grid-source";
 import type { GridController } from "./grid-controller";
+import { registerGridProbe } from "./grid-idle";
 
 export interface GridView {
   /** Re-pull controller.effectiveRows() into the table (buffer → table sync). */
@@ -222,6 +223,37 @@ export function createGridView(host: HTMLElement, controller: GridController): G
     }
   });
 
+  /*
+   * Settled means BUILT AND LAID OUT, not merely constructed. `selectableRange: 1` gives a
+   * non-empty table an initial range, and that range's outline is a rendered element — so until it
+   * exists the picture is still changing. An empty table is exempt, because it never gets one and
+   * waiting for it would be waiting forever.
+   *
+   * The MODEL is not the picture, and that distinction is the whole bug this second clause fixes.
+   * `getRanges()` answers from Tabulator's range model, which is populated when the range is
+   * created; the outline is a `.tabulator-range` div the SelectRange module paints into
+   * `.tabulator-range-overlay` on a later frame. Between the two, the grid reports itself settled
+   * and the capture lands on a table whose selected cell has no outline — so `data-grid.png`
+   * alternated between an outlined "Elena M." and a bare one, 16 rewrites in ten days at a steady
+   * 0.089 %. Asking the DOM for a laid-out box closes the window that the model check leaves open.
+   */
+  const probe = (): string | null => {
+    if (!built) {
+      return `grid[${gridId}]: building`;
+    }
+    if (controller.effectiveRows().length > 0) {
+      if (table.getRanges().length === 0) {
+        return `grid[${gridId}]: selection range not laid out`;
+      }
+      const outline = host.querySelector(".tabulator-range-overlay .tabulator-range");
+      if (!outline || rectOf(outline).width === 0) {
+        return `grid[${gridId}]: selection range outline not painted`;
+      }
+    }
+    return null;
+  };
+  const unregisterProbe = registerGridProbe(probe);
+
   table.on("cellEdited", (cell: CellComponent) => {
     if (suppress) {
       return;
@@ -307,6 +339,9 @@ export function createGridView(host: HTMLElement, controller: GridController): G
 
   return {
     destroy() {
+      // Before `table.destroy()`: a probe left registered against a torn-down table would be asking
+      // Tabulator questions it can no longer answer.
+      unregisterProbe();
       controller.bindView(null);
       table.destroy();
     },

package/src/grid/schema-columns.ts

@@ -10,6 +10,7 @@
  */
 import type { GridCellValue, GridColumn, GridColumnKind } from "./grid-source";
 import type { JsonSchema } from "../ui/schema-form";
+import { isMediaFormat } from "../utils/studio-utils";
 
 /** JSON-Schema property as it appears in content-type schemas (superset of ui JsonSchema). */
 interface PropSchema extends JsonSchema {
@@ -44,7 +45,7 @@ export function kindForProp(prop: PropSchema): GridColumnKind {
     return "enum";
   }
   const format = prop.type === "array" ? undefined : prop.format;
-  if (format === "image") {
+  if (isMediaFormat(format)) {
     return "image";
   }
   if (format === "date" || format === "date-time") {

package/src/grid/sources/content-source.ts

@@ -269,20 +269,41 @@ function buildEntryFileSource(opts: EntryFileSourceOptions): GridSource {
       const files = await opts.list();
       entries.clear();
       columnsCache = null;
-      await mapLimit(files, 8, async (path) => {
+      /*
+       * Read concurrently, INSERT IN ORDER.
+       *
+       * `entries` is a Map and the grid renders it in insertion order, so setting it from inside
+       * the worker made row order the order the reads happened to FINISH in — which is a race
+       * between two `platform.readFile` calls, not a property of the collection. The two posts in
+       * the `first-collection` fixture swapped places between runs, and that alone rewrote
+       * `blog-grid.png` in 3 of the 21 images the screenshot lane pushed over 24 commits.
+       *
+       * `mapLimit` already documents that it preserves item order; the fix is to USE its result
+       * rather than to mutate shared state from inside it. The concurrency is worth keeping — a
+       * collection is a directory of files and reading it eight at a time is why the grid opens
+       * quickly.
+       */
+      const loaded = await mapLimit(files, 8, async (path): Promise<EntryRecord | null> => {
         try {
           const text = await platform.readFile(path);
           const parsed = await parseSourceForPath(path, text);
-          entries.set(path, {
+          return {
             document: parsed.document,
             formatName: parsed.format.name,
             frontmatter: parsed.frontmatter ?? {},
             rawText: text,
-          });
+          };
         } catch {
           // Unparseable entry — leave it out rather than failing the whole grid.
+          return null;
         }
       });
+      for (const [index, path] of files.entries()) {
+        const record = loaded[index];
+        if (record) {
+          entries.set(path, record);
+        }
+      }
     })();
     return loadPromise;
   };

package/src/media/media-open.ts

@@ -0,0 +1,58 @@
+/**
+ * Open a media file in the viewer.
+ *
+ * The shape of `grid/grid-open.ts`'s `openCsvGridTab`, and for the same reason: a real file tab
+ * keyed by its path, with a stub document, because the tab model wants A DOCUMENT and this file is
+ * not one. The viewer never reads it — it reads `tab.documentPath` and shows the bytes at that path
+ * through an `<img>`, a `<video>` or a font specimen.
+ *
+ * `.svg` gets a `source` mode beside the viewer: it is the one media format that is also text, and
+ * hand-editing one is an ordinary thing to want.
+ *
+ * The modes are set HERE rather than in `tabs/tab.ts`'s `inferModes`, which is the same division
+ * CSV already lives under: `inferModes` answers for DOCUMENTS, from the format registry, and an
+ * opener answers for the files that are not documents. Every media tab is created through this
+ * function — `openFileInTab` routes to it, and session restore goes through `openFileInTab` — so
+ * there is no path by which one is built without them.
+ *
+ * @docs studio/projects/media
+ */
+
+import { activateTab, openTab, workspace } from "../workspace/workspace";
+import { extensionOf, isMediaFile } from "../files/media-upload";
+import { MEDIA_MODE } from "./media-pane";
+import type { Tab } from "../tabs/tab";
+
+/** Placeholder document for a media tab — the viewer never reads it, and there is nothing to save. */
+const MEDIA_STUB_DOCUMENT = { children: [], tagName: "div" };
+
+/** Whether this path opens in the media viewer rather than through a document parse. */
+export function isViewableMedia(path: string): boolean {
+  return isMediaFile(path);
+}
+
+/** The modes a media tab offers. SVG is also text, so it keeps a source alternate. */
+export function mediaTabModes(path: string): string[] {
+  return extensionOf(path) === ".svg" ? [MEDIA_MODE, "source"] : [MEDIA_MODE];
+}
+
+/**
+ * Open (or activate) a media file's viewer tab.
+ *
+ * @param {string} path - Project-relative path of the file
+ * @returns {Tab}
+ */
+export function openMediaTab(path: string): Tab {
+  const existing = workspace.tabs.get(path);
+  if (existing) {
+    activateTab(path);
+    return existing;
+  }
+  return openTab({
+    capabilities: { modes: mediaTabModes(path) },
+    document: structuredClone(MEDIA_STUB_DOCUMENT),
+    documentPath: path,
+    id: path,
+    sourceFormat: null,
+  });
+}