@jxsuite/studio 2.0.1 → 2.1.0

package/src/ui/media-picker.ts

@@ -6,6 +6,15 @@
  * project and assigns it, and a Browse dropdown of media already in the project's public/
  * directory, with thumbnail previews for images.
  *
+ * **The browse list carries metadata, and it costs nothing.** Size comes from the directory listing
+ * the widget already performs to enumerate the files (`seedMediaMeta`), and pixel dimensions come
+ * from the thumbnails it already loads (`recordImageSize`) — measuring an image is a decode the
+ * `<img>` has finished by the time `load` fires, so the caption is a read of work already done
+ * rather than a second fetch per row. What is NOT here is a usage count: `findReferences` sweeps
+ * every document in the project per query, and fifty of those to caption a dropdown is the wrong
+ * trade. Usage is asked once, about one file, where it changes a decision — the delete confirmation
+ * (`files/media-usage.ts`).
+ *
  * @docs studio/projects/media
  */
 
@@ -14,7 +23,8 @@ import { live } from "lit-html/directives/live.js";
 import { ref } from "lit-html/directives/ref.js";
 import { getPlatform } from "../platform";
 import { debouncedStyleCommit, renderOnly } from "../store";
-import { getLayerSlot } from "./layers";
+import { getLayerSlot, popoverLayerFor } from "./layers";
+import type { LayerKind } from "./layers";
 import { rectOf } from "../utils/geometry";
 import { loopbackAssetSrc } from "../canvas/canvas-origin";
 import { previewAssetSrc } from "../canvas/content-assets";
@@ -25,28 +35,42 @@ import {
   extensionOf,
   uploadAssets,
 } from "../files/media-upload";
+import {
+  invalidateMediaMeta,
+  mediaMetaSummary,
+  peekMediaMeta,
+  recordImageSize,
+  seedMediaMeta,
+} from "../files/media-meta";
+import { mediaSiteUrl } from "../files/media-paths";
 
 // ─── Media file cache ────────────────────────────────────────────────────────
 
-/** @type {{ path: string; name: string; isImage: boolean }[]} */
-let mediaCache: { path: string; name: string; isImage: boolean }[] = [];
+/** One browsable media file: the ref a pick writes, and the file that ref names. */
+interface MediaEntry {
+  /** The value committed to the field — the site URL, which is the authored form. */
+  path: string;
+  /** Project-relative path on disk, the key everything in `media-meta` is stored under. */
+  file: string;
+  name: string;
+  isImage: boolean;
+}
+
+let mediaCache: MediaEntry[] = [];
 let mediaCacheLoaded = false;
 
 /**
- * Recursively collect media files from a directory.
- *
- * @param {string} dir
- * @param {ReturnType<typeof getPlatform>} platform
- * @returns {Promise<{ path: string; name: string; isImage: boolean }[]>}
+ * Recursively collect media files from a directory, seeding {@link seedMediaMeta} with the listing
+ * on the way past — the size of every row is already in the response that enumerated it.
  */
 async function collectMedia(
   dir: string,
   platform: ReturnType<typeof getPlatform>,
-): Promise<{ path: string; name: string; isImage: boolean }[]> {
-  /** @type {{ path: string; name: string; isImage: boolean }[]} */
-  const results = [];
+): Promise<MediaEntry[]> {
+  const results: MediaEntry[] = [];
   try {
     const entries = await platform.listDirectory(dir);
+    seedMediaMeta(entries);
     for (const entry of entries) {
       if (entry.type === "directory") {
         const sub = await collectMedia(entry.path, platform);
@@ -55,9 +79,12 @@ async function collectMedia(
         const ext = extensionOf(entry.name);
         if (MEDIA_EXTENSIONS.has(ext)) {
           results.push({
+            file: entry.path,
             isImage: IMAGE_EXTENSIONS.has(ext),
             name: entry.name,
-            path: `/${entry.path}`,
+            // The site URL is what production serves and therefore what a document should say.
+            // Media-paths holds the one definition of that mapping.
+            path: mediaSiteUrl(entry.path),
           });
         }
       }
@@ -74,20 +101,22 @@ async function loadMediaCache() {
   }
   const platform = getPlatform();
   mediaCache = await collectMedia("public", platform);
-  // Strip "public/" prefix so paths match production (public/ contents served at root)
-  for (const m of mediaCache) {
-    m.path = m.path.replace(/^\/public\//, "/");
-  }
   mediaCacheLoaded = true;
   // Re-render the host panels so the browse popover has entries to show once the async listing
   // Resolves. Mirrors loadLayoutEntries()'s renderOnly() in head-panel.
   renderOnly("leftPanel", "rightPanel", "frontmatterPanel");
 }
 
-/** Force media cache reload (e.g. after upload). */
+/**
+ * Force media cache reload (e.g. after upload).
+ *
+ * The metadata cache goes with it, and for the same reason: both were derived from a listing that
+ * is now out of date, and a size that survives the write it contradicts is worse than no size.
+ */
 export function invalidateMediaCache() {
   mediaCache = [];
   mediaCacheLoaded = false;
+  invalidateMediaMeta();
 }
 
 // ─── Popover state ───────────────────────────────────────────────────────────
@@ -97,6 +126,32 @@ let _popoverOnCommit: ((val: string) => void) | null = null;
 
 /** @type {HTMLElement | null} */
 let _popoverAnchorEl: HTMLElement | null = null;
+/**
+ * Which layer the open popover is living in.
+ *
+ * Chosen from the anchor at open time and then REMEMBERED, because `getLayerSlot` keys its slots by
+ * `${layer}:${id}`: dismissing through a different layer than the one that opened would clear an
+ * empty slot and leave the real popover on screen.
+ */
+let _popoverLayer: LayerKind = "popover";
+
+/** The open popover's slot — the one place that names the layer and the id together. */
+function popoverSlot(): HTMLElement {
+  return getLayerSlot(_popoverLayer, "media-picker");
+}
+
+/**
+ * The popover's z-index, which depends on the company it is keeping.
+ *
+ * In `#layer-popover` it has the layer to itself and 30 is enough — that is what it has always
+ * been, and every panel-hosted picker keeps rendering identically. Sharing a layer with a modal
+ * body is different: those declare `z-index: 1000` (`.seo-modal`, `.about-modal`, `.settings-modal`
+ * — the house shape), so a picker anchored inside one is a later sibling that still paints beneath
+ * it. Beating that number is the whole point of moving layers in the first place.
+ */
+function popoverZIndex(): number {
+  return _popoverLayer === "popover" ? 30 : 1001;
+}
 
 /** @type {HTMLInputElement | null} */
 let _popoverFilterEl: HTMLInputElement | null = null;
@@ -110,7 +165,7 @@ function dismissMediaPickerPopover() {
   _popoverFilterEl = null;
   document.removeEventListener("keydown", onPopoverKeydown, true);
   document.removeEventListener("mousedown", onPopoverOutsideClick, true);
-  litRender(nothing, getLayerSlot("popover", "media-picker"));
+  litRender(nothing, popoverSlot());
 }
 
 /** @param {KeyboardEvent} e */
@@ -124,14 +179,38 @@ function onPopoverKeydown(e: KeyboardEvent) {
 
 /** @param {MouseEvent} e */
 function onPopoverOutsideClick(e: MouseEvent) {
-  const host = getLayerSlot("popover", "media-picker");
+  const host = popoverSlot();
   if (!host.contains(e.target as Node)) {
     dismissMediaPickerPopover();
   }
 }
 
+/** A repaint scheduled by a thumbnail that just reported its size, or 0 when none is pending. */
+let _sizeRepaint = 0;
+
+/**
+ * Fold a loaded thumbnail's intrinsic size into the metadata cache and, if that was news, repaint
+ * the popover once so the caption appears.
+ *
+ * The repaint is coalesced across a whole grid of images landing in the same frame, and it cannot
+ * loop: re-rendering recreates the `<img>` elements, whose `load` fires again from cache, and
+ * `recordImageSize` returns false the second time because the measurement has not changed.
+ */
+function noteImageSize(file: string, target: EventTarget | null) {
+  const img = target as HTMLImageElement | null;
+  if (!img || !recordImageSize(file, img.naturalWidth, img.naturalHeight) || _sizeRepaint !== 0) {
+    return;
+  }
+  _sizeRepaint = requestAnimationFrame(() => {
+    _sizeRepaint = 0;
+    if (_popoverAnchorEl) {
+      renderMediaPickerPopover();
+    }
+  });
+}
+
 function renderMediaPickerPopover() {
-  const host = getLayerSlot("popover", "media-picker");
+  const host = popoverSlot();
   const rect = _popoverAnchorEl ? rectOf(_popoverAnchorEl) : undefined;
   if (!rect) {
     return;
@@ -166,10 +245,11 @@ function renderMediaPickerPopover() {
     html`
       <sp-popover
         open
+        data-jx-region="overlay.menu:media-picker"
         ${ref((el) => {
           _popoverEl = (el as HTMLElement | undefined) || null;
         })}
-        style="position:fixed;left:${left}px;top:${top}px;z-index:30;max-height:360px;overflow-y:auto;min-width:240px"
+        style="position:fixed;left:${left}px;top:${top}px;z-index:${popoverZIndex()};max-height:360px;overflow-y:auto;min-width:240px"
       >
         <input
           class="media-picker-filter"
@@ -195,8 +275,9 @@ function renderMediaPickerPopover() {
         >
           ${
             options.length > 0
-              ? options.map(
-                  (m) => html`
+              ? options.map((m) => {
+                  const caption = mediaMetaSummary(peekMediaMeta(m.file));
+                  return html`
                     <sp-menu-item value=${m.path}>
                       ${
                         m.isImage
@@ -205,13 +286,15 @@ function renderMediaPickerPopover() {
                               src=${loopbackAssetSrc(m.path)}
                               alt=""
                               style="width:24px;height:24px;object-fit:cover;border-radius:var(--spectrum-corner-radius-75, 2px)"
+                              @load=${(e: Event) => noteImageSize(m.file, e.target)}
                             />`
                           : nothing
                       }
                       ${m.name}
+                      ${caption ? html`<span slot="description">${caption}</span>` : nothing}
                     </sp-menu-item>
-                  `,
-                )
+                  `;
+                })
               : html`<sp-menu-item disabled>No matches</sp-menu-item>`
           }
           ${
@@ -270,6 +353,8 @@ function showMediaPickerPopover(anchorEl: HTMLElement, onCommit: (val: string) =
   dismissMediaPickerPopover();
   _popoverOnCommit = onCommit;
   _popoverAnchorEl = anchorEl;
+  // Before the first render, so every later `popoverSlot()` agrees with where it was drawn.
+  _popoverLayer = popoverLayerFor(anchorEl);
   _popoverFilter = "";
   renderMediaPickerPopover();
   document.addEventListener("keydown", onPopoverKeydown, true);
@@ -362,6 +447,11 @@ export function renderMediaPicker(prop: string, value: string, onCommit: (val: s
       >
         <sp-icon-upload slot="icon"></sp-icon-upload>
       </sp-action-button>
+      <!-- No data-jx-region here. The class IS the handle: ui/regions.ts derives
+           inspector/field:PROP/browse by finding this button inside the Inspector's own
+           [data-prop] row, so the id resolves to one element however many panes are drawing a
+           media picker. The stamp claimed an inspector/... id on every picker the app renders,
+           including the two the Document Header card draws inside each pane's STAGE. -->
       <sp-action-button
         class="media-picker-browse"
         size="xs"

package/src/ui/panel-resize.ts

@@ -1,76 +1,88 @@
 /// <reference lib="dom" />
 /**
- * Panel-resize.js — Draggable resize handles for left and right sidebars.
+ * Panel-resize.js — Draggable resize handles for the three docks.
  *
- * Self-initializing module. Import it and the resize handles become interactive. Persists widths to
- * localStorage so they survive page reloads.
+ * Self-initializing module. Import it and the resize handles become interactive.
+ *
+ * The handles are the only thing here: dock sizes, their persistence and their projection onto the
+ * grid's CSS custom properties all belong to the reactive `shell` record (`../shell`). A drag
+ * writes `setDockSize()` and the shell's own effect moves the track; release persists once.
  */
 
-import { applyPanelCollapse, view } from "../view";
-
-const STORAGE_KEY = "jx-studio-panel-widths";
-const MIN_WIDTH = 160;
-const MAX_RATIO = 0.5; // Max 50% of viewport
-const DEFAULT_LEFT = 240;
-const DEFAULT_RIGHT = 280;
-const DEFAULT_CHAT = 320;
+import {
+  DOCK_DEFAULT_SIZES,
+  persistDocks,
+  registerShellSurface,
+  setDockSize,
+  shell,
+} from "../shell";
+import type { DockId } from "../shell";
 
-const root = document.documentElement;
-
-/** Read a px-valued CSS custom property as a number (e.g. "320px" → 320). */
-function readPxVar(cssVar: string): number {
-  return Number(getComputedStyle(root).getPropertyValue(cssVar).replace(/px$/, ""));
+/**
+ * What a handle drags.
+ *
+ * Generalised out of the three dock rows so the pane splitter can be the fourth. A dock is sized in
+ * px and a pane split is a ratio, which is the whole of the difference: `scale` converts a pointer
+ * delta in px into the target's own units, and everything else — capture, the dragging class, the
+ * text-selection suppression, the double-click reset, the one persist on release — is identical and
+ * was worth having once.
+ */
+export interface ResizeTarget {
+  /** Which coordinate the drag reads. */
+  axis: "x" | "y";
+  /** The current value. */
+  read: () => number;
+  /** Set it. Called on every pointermove, so it must be cheap and idempotent. */
+  write: (value: number) => void;
+  /** The value a double-click restores. */
+  reset: () => number;
+  /** Lower and upper bounds, read fresh because both can depend on the viewport. */
+  min: () => number;
+  max: () => number;
+  /** Target units per pixel of pointer movement, signed: negative grows toward the origin. */
+  scale: () => number;
+  /** Persist. Called once on release and once on reset — never during the drag. */
+  settle: () => void;
 }
 
-// ─── Restore saved widths & collapse state ──────────────────────────────────
+/**
+ * The smallest a dock may be dragged to, per axis.
+ *
+ * The Bottom dock's floor is lower because its content is rows of text: 120px is four problems or
+ * two activity rows, which is a useful dock, where 160px of a 24-row list is not meaningfully
+ * more.
+ */
+const MIN_SIZE: Readonly<Record<"x" | "y", number>> = { x: 160, y: 120 };
 
-try {
-  const saved = JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}") as {
-    left?: number;
-    right?: number;
-    chat?: number;
-    leftCollapsed?: boolean;
-    rightCollapsed?: boolean;
-    chatCollapsed?: boolean;
-  };
-  if (saved.left) {
-    root.style.setProperty("--panel-w-left", `${saved.left}px`);
-  }
-  if (saved.right) {
-    root.style.setProperty("--panel-w-right", `${saved.right}px`);
-  }
-  if (saved.chat) {
-    root.style.setProperty("--panel-w-chat", `${saved.chat}px`);
-  }
-  if (saved.leftCollapsed) {
-    view.leftPanelCollapsed = true;
-  }
-  if (saved.rightCollapsed) {
-    view.rightPanelCollapsed = true;
-  }
-  if (saved.chatCollapsed) {
-    view.chatPanelCollapsed = true;
-  }
-  applyPanelCollapse();
-} catch {
-  // Ignore
-}
+/** The largest, as a fraction of the viewport along the dragged axis. */
+const MAX_RATIO = 0.5;
 
-// ─── Setup handles ───────────────────────────────────────────────────────────
+/**
+ * Which handle drives which dock, and which direction grows it.
+ *
+ * Three rows, and the third resizes on the other axis: `grow` is the sign a pointer moving in the
+ * positive direction of `axis` contributes, so the Navigator grows rightward, and the Inspector and
+ * the Bottom dock grow back toward the pointer's origin. The assistant is not here and never will
+ * be — it is an Inspector TAB, resized by resizing the Inspector.
+ */
+const HANDLES: { selector: string; dock: DockId; axis: "x" | "y"; grow: 1 | -1 }[] = [
+  { axis: "x", dock: "left", grow: 1, selector: "#resize-left" },
+  { axis: "x", dock: "right", grow: -1, selector: "#resize-right" },
+  { axis: "y", dock: "bottom", grow: -1, selector: "#resize-bottom" },
+];
 
 /**
+ * Wire one handle to one dock.
+ *
  * @param {HTMLElement} handle
- * @param {string} cssVar
- * @param {"left" | "right"} side
- * @param {number} defaultWidth
+ * @param {DockId} dock
+ * @param {"x" | "y"} axis — which coordinate the drag reads
+ * @param {1 | -1} grow — the sign a positive move along `axis` contributes to the dock's size
  */
-function setupHandle(
-  handle: HTMLElement,
-  cssVar: string,
-  side: "left" | "right",
-  defaultWidth: number,
-) {
-  let drag: { startX: number; startWidth: number } | null = null;
+export function setupHandle(handle: HTMLElement, target: ResizeTarget) {
+  const { axis } = target;
+  let drag: { start: number; startSize: number } | null = null;
+  const coord = (e: { clientX: number; clientY: number }) => (axis === "x" ? e.clientX : e.clientY);
 
   handle.addEventListener("pointerdown", (e) => {
     e.preventDefault();
@@ -81,19 +93,17 @@ function setupHandle(
     }
     handle.classList.add("dragging");
     document.body.style.userSelect = "none";
-
-    const current = readPxVar(cssVar) || defaultWidth;
-    drag = { startWidth: current, startX: e.clientX };
+    drag = { start: coord(e), startSize: target.read() };
   });
 
   handle.addEventListener("pointermove", (e) => {
     if (!drag) {
       return;
     }
-    const delta = side === "left" ? e.clientX - drag.startX : drag.startX - e.clientX;
-    const maxWidth = window.innerWidth * MAX_RATIO;
-    const newWidth = Math.round(Math.min(maxWidth, Math.max(MIN_WIDTH, drag.startWidth + delta)));
-    root.style.setProperty(cssVar, `${newWidth}px`);
+    const delta = (coord(e) - drag.start) * target.scale();
+    const wanted = drag.startSize + delta;
+    const floored = Math.max(target.min(), wanted);
+    target.write(Math.min(target.max(), floored));
   });
 
   handle.addEventListener("pointerup", (e) => {
@@ -108,38 +118,46 @@ function setupHandle(
     }
     handle.classList.remove("dragging");
     document.body.style.userSelect = "";
-    persistWidths();
+    target.settle();
   });
 
   handle.addEventListener("dblclick", () => {
-    root.style.setProperty(cssVar, `${defaultWidth}px`);
-    persistWidths();
+    target.write(target.reset());
+    target.settle();
   });
 }
 
-function persistWidths() {
-  const left = readPxVar("--panel-w-left") || DEFAULT_LEFT;
-  const right = readPxVar("--panel-w-right") || DEFAULT_RIGHT;
-  const chat = readPxVar("--panel-w-chat") || DEFAULT_CHAT;
-  try {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify({ chat, left, right }));
-  } catch {
-    // Storage full or unavailable
-  }
+/** The largest a dock may be dragged to along `axis`. */
+function maxDockSize(axis: "x" | "y"): number {
+  const viewport = axis === "x" ? window.innerWidth : window.innerHeight;
+  return viewport * MAX_RATIO;
 }
 
-// ─── Initialize ──────────────────────────────────────────────────────────────
-
-const resizeLeft = document.querySelector<HTMLElement>("#resize-left");
-const resizeRight = document.querySelector<HTMLElement>("#resize-right");
-const resizeChat = document.querySelector<HTMLElement>("#resize-chat");
-
-if (resizeLeft) {
-  setupHandle(resizeLeft, "--panel-w-left", "left", DEFAULT_LEFT);
-}
-if (resizeRight) {
-  setupHandle(resizeRight, "--panel-w-right", "right", DEFAULT_RIGHT);
+/** A dock, as a {@link ResizeTarget}. The three rows of {@link HANDLES}, given the shared shape. */
+function dockTarget(dock: DockId, axis: "x" | "y", grow: 1 | -1): ResizeTarget {
+  return {
+    axis,
+    max: () => maxDockSize(axis),
+    min: () => MIN_SIZE[axis],
+    read: () => shell.docks[dock].size,
+    reset: () => DOCK_DEFAULT_SIZES[dock],
+    scale: () => grow,
+    settle: () => persistDocks(),
+    write: (value) => setDockSize(dock, Math.round(value)),
+  };
 }
-if (resizeChat) {
-  setupHandle(resizeChat, "--panel-w-chat", "right", DEFAULT_CHAT);
+
+/** Attach every handle present in the document. Idempotent per element by construction. */
+export function mountPanelResize(): void {
+  for (const { axis, dock, grow, selector } of HANDLES) {
+    const handle = document.querySelector<HTMLElement>(selector);
+    if (handle) {
+      setupHandle(handle, dockTarget(dock, axis, grow));
+    }
+  }
 }
+
+/* Mounted through the shell's own lifecycle rather than by a bare `mountPanelResize()` at module
+   scope. The import-time call read `document` before anything had said the tree existed, which is
+   the one part of `registerShellSurface`'s bargain this module was not keeping. */
+registerShellSurface({ mount: mountPanelResize, unmount: () => {} });