@jxsuite/studio 3.0.0 → 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-view.ts

@@ -228,13 +228,27 @@ export function createGridView(host: HTMLElement, controller: GridController): G
    * 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 && table.getRanges().length === 0) {
-      return `grid[${gridId}]: selection range not laid out`;
+    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;
   };

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,
+  });
+}

package/src/media/media-pane.ts

@@ -0,0 +1,310 @@
+/// <reference lib="dom" />
+/**
+ * The Media viewer — a pane that SHOWS a file the studio has no document model for.
+ *
+ * Clicking an image in the Files tree used to end in a toast: `openFileInTab` reads every file as
+ * text, finds no format class and no `.json`, and throws — so a PNG produced _"No format class
+ * imported for public/hero.jpg — add one to project.json imports"_, advice that means nothing about
+ * a binary asset. Video, audio, fonts and PDFs all failed the same way, and so did every tile in
+ * the Library, which routes to the same function. There was no way at all to look at an asset the
+ * project contains, which is exactly what somebody who has just imported a site needs to do.
+ *
+ * Almost nothing here is new. `files/media-paths.ts` already computes a src the parent realm can
+ * load, `files/media-meta.ts` already holds size, modified time and — once an `<img>` has loaded —
+ * pixel dimensions, and `files/media-usage.ts` already answers "which pages use this?" honestly.
+ * That last one had, in `site-architecture.md` §9.4's own words, _no reader but the delete
+ * confirmation_: you could only learn what an image was used for by trying to remove it. This is
+ * the surface that query was waiting for.
+ *
+ * Read-only, deliberately. Rename, delete and reveal are the file tree's, and a second set of
+ * buttons for them here would be a second place to keep them right.
+ *
+ * @docs studio/projects/media
+ */
+
+import { html, nothing, render as litRender } from "lit-html";
+import { effect, effectScope } from "../reactivity";
+import { paneRegion } from "../ui/regions";
+import { mediaSiteUrl, previewFileSrc } from "../files/media-paths";
+import { formatBytes, loadMediaMeta, peekMediaMeta, recordImageSize } from "../files/media-meta";
+import { extensionOf, mediaKind } from "../files/media-upload";
+import { loadMediaUsages, mediaUsageHeadline, peekMediaUsages } from "../files/media-usage";
+import type { MediaMeta } from "../files/media-meta";
+import type { UsageState } from "../services/references";
+import type { Tab } from "../tabs/tab";
+import type { CanvasSurface } from "../canvas/canvas-surface";
+
+/** The `canvasMode` the media viewer draws under. */
+export const MEDIA_MODE = "media";
+
+/** Extensions the viewer renders as a font specimen rather than as a file it cannot show. */
+const FONT_EXTENSIONS = new Set([".woff", ".woff2", ".ttf", ".otf"]);
+
+/** The pangram the font specimen is set in — short, and every letter of the alphabet once. */
+const SPECIMEN = "The quick brown fox jumps over the lazy dog";
+
+/** Specimen sizes, largest first: enough to judge a display face and a body face in one look. */
+const SPECIMEN_SIZES = [48, 32, 24, 18, 14];
+
+// ─── Mounting ────────────────────────────────────────────────────────────────
+
+interface ActiveMediaPane {
+  paneId: string;
+  tabId: string;
+  wrap: HTMLElement;
+  scope: { stop: () => void; run: <T>(fn: () => T) => T | undefined };
+}
+
+/**
+ * The viewer mounted in each pane, keyed by pane id.
+ *
+ * Per pane rather than a singleton, for the reason `content/entry-editor.ts` documents: `media` is
+ * a kind the side pane may host, so two panes can hold one at once and a shared slot would let the
+ * second mount stop the first one's effect scope.
+ */
+const _active = new Map<string, ActiveMediaPane>();
+
+function activeIn(paneId: string): ActiveMediaPane | null {
+  return _active.get(paneId) ?? null;
+}
+
+/** Whether this tab's viewer is already mounted in this pane and still in the document. */
+export function mediaPaneMounted(paneId: string, tab: Tab): boolean {
+  const panel = activeIn(paneId);
+  return panel !== null && panel.tabId === tab.id && panel.wrap.isConnected;
+}
+
+/** Tear one pane's viewer down (mode change, tab switch, project close). Idempotent. */
+export function detachMediaPane(paneId: string): void {
+  const panel = _active.get(paneId);
+  if (!panel) {
+    return;
+  }
+  panel.scope.stop();
+  _active.delete(paneId);
+}
+
+// ─── Templates ───────────────────────────────────────────────────────────────
+
+/**
+ * The asset itself, in whatever element can show it.
+ *
+ * A file the browser cannot render is not a failure state — it is a font, or a zip, or a format
+ * this build has never heard of — so the fallback says what the file IS rather than apologising.
+ */
+function assetTpl(path: string, src: string, redraw: () => void) {
+  const ext = extensionOf(path);
+  const kind = mediaKind({ name: path });
+
+  if (FONT_EXTENSIONS.has(ext)) {
+    /* A font is shown by being USED. The @font-face is scoped to a generated family name so two
+       specimens open side by side cannot claim the same one. */
+    const family = `jx-specimen-${path.replaceAll(/[^a-zA-Z0-9]/g, "-")}`;
+    return html`
+      <style>
+        @font-face {
+          font-family: "${family}";
+          src: url("${src}");
+        }
+      </style>
+      <div class="media-specimen" style="font-family: '${family}', system-ui, sans-serif">
+        ${SPECIMEN_SIZES.map(
+          (size) => html`<p class="media-specimen-line" style="font-size: ${size}px">
+            ${SPECIMEN}
+          </p>`,
+        )}
+      </div>
+    `;
+  }
+
+  switch (kind) {
+    case "image": {
+      return html`<img
+        class="media-image"
+        src=${src}
+        alt=""
+        @load=${(e: Event) => {
+          const img = e.target as HTMLImageElement;
+          /* The only honest source of pixel dimensions in a browser is an image that has loaded,
+             and this viewer is showing one at full size anyway. `recordImageSize` reports whether
+             the number was new, so a repaint happens once rather than on every load event. */
+          if (recordImageSize(path, img.naturalWidth, img.naturalHeight)) {
+            redraw();
+          }
+        }}
+      />`;
+    }
+    case "video": {
+      return html`<video class="media-video" src=${src} controls></video>`;
+    }
+    case "audio": {
+      return html`<audio class="media-audio" src=${src} controls></audio>`;
+    }
+    default: {
+      return ext === ".pdf"
+        ? html`<embed class="media-embed" src=${src} type="application/pdf" />`
+        : html`<div class="media-unviewable">
+            <p>Jx has no viewer for <code>${ext || "this file"}</code>.</p>
+            <p class="media-note">The file is in the project and builds normally.</p>
+          </div>`;
+    }
+  }
+}
+
+/** Kind, dimensions, size and modified time — each omitted rather than zeroed when unknown. */
+function factsTpl(path: string, meta: MediaMeta | null) {
+  const facts: string[] = [mediaKind({ name: path })];
+  if (meta?.width != null && meta.height != null) {
+    facts.push(`${meta.width} × ${meta.height}`);
+  }
+  if (meta?.bytes != null) {
+    facts.push(formatBytes(meta.bytes));
+  }
+  if (meta?.modified) {
+    facts.push(`modified ${meta.modified.slice(0, 10)}`);
+  }
+  return html`<p class="media-facts">${facts.join(" · ")}</p>`;
+}
+
+/**
+ * The URL a document would reference this file by, with a copy button.
+ *
+ * The single most useful fact about an asset that is not the asset: `public/hero.jpg` is written
+ * `/hero.jpg`, a string that shares not one path segment with the file, and getting it wrong is the
+ * commonest way an image ends up missing from a page.
+ */
+function refTpl(path: string) {
+  const ref = mediaSiteUrl(path);
+  return html`
+    <div class="media-ref">
+      <code class="media-ref-value">${ref}</code>
+      <sp-action-button
+        size="s"
+        quiet
+        title="Copy the reference"
+        @click=${() => {
+          void navigator.clipboard?.writeText(ref);
+        }}
+        >Copy</sp-action-button
+      >
+    </div>
+  `;
+}
+
+/** Which documents reference this file, or the honest reason there is no list. */
+function usageTpl(usage: UsageState | null) {
+  const headline = mediaUsageHeadline(usage);
+  if (headline === null) {
+    // The host has no reference index. A zero here would be a number nobody can stand behind.
+    return nothing;
+  }
+  const files = usage?.status === "ready" ? usage.result.files : [];
+  return html`
+    <div class="media-usage">
+      <h4 class="media-usage-title">Used by</h4>
+      <p class="media-usage-headline">${headline}</p>
+      ${
+        files.length === 0
+          ? nothing
+          : html`<ul class="media-usage-list">
+              ${files.map(
+                (file) => html`<li>
+                  <button
+                    type="button"
+                    class="media-usage-link"
+                    @click=${() => {
+                      void openDocument(file.path);
+                    }}
+                  >
+                    ${file.path}
+                  </button>
+                  <span class="media-usage-count">${file.count}</span>
+                </li>`,
+              )}
+            </ul>`
+      }
+    </div>
+  `;
+}
+
+/**
+ * Open a document that references this file.
+ *
+ * Dynamic, for the reason `content/entry-editor.ts` gives: `files/files.ts` reaches the platform,
+ * the format registry and the packages layer, and a static edge would drag all of it in here.
+ */
+async function openDocument(path: string): Promise<void> {
+  const { openFileInTab } = await import("../files/files");
+  await openFileInTab(path);
+}
+
+// ─── Render ──────────────────────────────────────────────────────────────────
+
+/**
+ * Mount the media viewer into the pane.
+ *
+ * The same non-iframe-editor pattern as the grid, the Library, Project Settings and the Entry form:
+ * it owns its own effect scope from here, so learning an image's dimensions repaints this panel and
+ * nothing else.
+ *
+ * @param {CanvasSurface} surface
+ * @param {Tab} tab
+ */
+export function renderMediaMode(surface: CanvasSurface, tab: Tab): void {
+  const { paneId, wrap: canvasWrap } = surface;
+  if (mediaPaneMounted(paneId, tab)) {
+    return;
+  }
+  detachMediaPane(paneId);
+
+  const scope = effectScope();
+  const panel: ActiveMediaPane = { paneId, scope, tabId: tab.id, wrap: canvasWrap };
+  _active.set(paneId, panel);
+
+  const path = tab.documentPath ?? "";
+
+  const redraw = () => {
+    if (activeIn(paneId) === panel) {
+      draw();
+    }
+  };
+
+  const draw = () => {
+    const meta = peekMediaMeta(path);
+    const usage = peekMediaUsages(path);
+    /* Asked on the first paint that finds it missing, never on every paint: both loaders cache and
+       de-duplicate in flight, and both repaint through `redraw` when they land. */
+    if (meta === null) {
+      void loadMediaMeta(path).then(redraw);
+    }
+    if (usage === null || usage.status === "pending") {
+      void loadMediaUsages(path).then(redraw);
+    }
+
+    litRender(
+      html`
+        <div class="media-viewer" data-jx-region=${paneRegion(paneId, "media")}>
+          <div class="media-stage">${assetTpl(path, previewFileSrc(path), redraw)}</div>
+          <div class="media-details">
+            <h3 class="media-name">${path.split("/").pop()}</h3>
+            ${factsTpl(path, meta)} ${refTpl(path)} ${usageTpl(usage)}
+          </div>
+        </div>
+      `,
+      canvasWrap,
+    );
+  };
+
+  scope.run(() => {
+    effect(() => {
+      if (activeIn(paneId) !== panel) {
+        return;
+      }
+      /* The tab's path is the whole of what this pane draws from — the file's bytes are the
+         browser's problem, and its metadata repaints through `redraw`. Reading it here is what
+         makes a rename repaint the viewer rather than leave it pointing at a name that is gone. */
+      void tab.documentPath;
+      draw();
+    });
+  });
+}