@jxsuite/studio 6.1.2 → 8.0.0

package/src/surfaces/media-library.ts

@@ -0,0 +1,282 @@
+/// <reference lib="dom" />
+/**
+ * The Media workspace's library, as a mounted document.
+ *
+ * This is the adapter. `media/media-library.ts` is the flow: which files a filter keeps, in what
+ * order, what each count may claim, which tile is selected, where an arrow lands and what Replace,
+ * Delete and an upload write. It hands this module one projection, and this module hands the
+ * document a scope and reports the nodes the flow needs to hold.
+ *
+ * **Four islands, all through `onNodeCreated`.** The flow needs four nodes the document creates:
+ * each tile (watched for viewport entry, so a thumbnail is requested only when it is looked at, and
+ * focused when the keyboard moves the selection onto it), the grid (measured, so ArrowDown lands on
+ * the tile drawn under the current one), and the two file inputs (opened by `media.upload` and
+ * `media.replace`). Each is announced as it is created, which is the one seam for a node a document
+ * made (`studio-ui-guidelines.md` §9.4); a node found by selector once would be detached DOM the
+ * moment a `$switch` moved.
+ *
+ * **The host is cleared in the pane and not in the dialog.** The pane's stage is handed to the mode
+ * that owns it whole, and emptying it is what stops two libraries stacking when a re-render lands
+ * before the first mount settled. The dialog's slot is this document's alone already.
+ *
+ * @docs studio/projects/media
+ */
+
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import mediaLibraryDoc from "./media-library.json";
+import type { JxElement } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+import type { MediaUsageRow } from "./media-pane";
+
+registerSurface("media-library", mediaLibraryDoc);
+
+/** One filter in the left column. */
+export interface MediaFilterRow {
+  key: string;
+  label: string;
+  /** The count, already a string; `""` while it is not known (Unused before its sweep). */
+  count: string;
+  pressed: "true" | "false";
+}
+
+/** One tile in the grid. */
+export interface MediaTileRow {
+  /** The row's identity across a filter or a sort: the file's path on disk. */
+  key: string;
+  file: string;
+  name: string;
+  /** "1200 × 800 · 84 KB", or the file's kind when nothing about it is measured yet. */
+  caption: string;
+  selected: "true" | "false";
+  /** The roving tab stop: `"0"` on exactly one tile, `"-1"` on every other. */
+  tabindex: "0" | "-1";
+  /** `pending` until the tile has scrolled into view, then `image`; a file with no picture: `glyph`. */
+  thumbState: "image" | "pending" | "glyph";
+  thumbSrc: string;
+  glyph: string;
+}
+
+/** Everything the document draws, as one value. */
+export interface MediaLibraryView {
+  region: string;
+  mode: "manage" | "pick";
+  dropActive: "true" | "false";
+  filters: MediaFilterRow[];
+  title: string;
+  titleId: string;
+  query: string;
+  sort: string;
+  sortOptions: { label: string; value: string }[];
+  uploadAccept: string;
+  /** Where an upload lands, said before the files are chosen: "Upload into public/media/". */
+  uploadHint: string;
+  gridState: "loading" | "counting" | "empty" | "nomatch" | "listed";
+  countingLabel: string;
+  emptyTitle: string;
+  emptyDetail: string;
+  tiles: MediaTileRow[];
+  detailState: "none" | "shown";
+  detailHint: string;
+  selectedFile: string;
+  detailName: string;
+  detailFacts: string;
+  detailRef: string;
+  /**
+   * The viewer's stage for the file (`media/media-pane.ts`), minus the ones a side pane cannot
+   * hold.
+   */
+  previewKind: "image" | "video" | "audio" | "font" | "glyph";
+  previewSrc: string;
+  previewGlyph: string;
+  /** A font's scoped `@font-face`, the declaration naming its family, and the pangram; else `""`. */
+  previewFontFace: string;
+  previewSpecimenFamily: string;
+  previewSpecimen: string;
+  /** The Replace input's `accept`: the selected file's own format only. */
+  replaceAccept: string;
+  usageState: "hidden" | "shown";
+  usageHeadline: string;
+  usageFiles: MediaUsageRow[];
+}
+
+/** What a control asks the flow to do. */
+export interface MediaLibraryActions {
+  setFilter: (key: string) => void;
+  setQuery: (value: string) => void;
+  setSort: (value: string) => void;
+  upload: (input: HTMLInputElement) => void;
+  dragOver: () => void;
+  dragOut: () => void;
+  drop: (files: FileList | null) => void;
+  select: (file: string) => void;
+  /** A tile received focus: selection follows it, so the first Enter acts on the tile in the ring. */
+  focusTile: (file: string) => void;
+  /** A double-click: open the file in its viewer, or in pick mode, use it. */
+  activate: (file: string) => void;
+  /** Enter on the grid: the same, for the selected file. */
+  activateSelected: () => void;
+  key: (key: string, ctrl: boolean) => void;
+  measure: (file: string, width: number, height: number) => void;
+  copyRef: () => void;
+  openDocument: (path: string) => void;
+  replace: (input: HTMLInputElement) => void;
+  remove: () => void;
+  openViewer: () => void;
+  reset: () => void;
+  /** A tile node was created for `file`. */
+  tileHost: (element: HTMLElement, file: string) => void;
+  /** The grid node was created. */
+  gridHost: (element: HTMLElement) => void;
+  /** A file input was created: the toolbar's Upload (`upload`) or the detail's Replace. */
+  inputHost: (element: HTMLInputElement, role: "upload" | "replace") => void;
+}
+
+export interface MediaLibrarySurfaceHandle {
+  ready: Promise<HTMLElement>;
+  /** Whether what was mounted is still inside the host (a mount still in flight counts). */
+  attached: () => boolean;
+  update: (view: MediaLibraryView) => void;
+  dispose: () => void;
+}
+
+/** The scope the document reads. */
+interface MediaLibraryScope
+  extends MediaLibraryView, Omit<MediaLibraryActions, "tileHost" | "gridHost" | "inputHost"> {
+  hasUsageFiles: boolean;
+}
+
+/** An empty view: what a scope holds before the first projection. */
+export function emptyMediaLibraryView(): MediaLibraryView {
+  return {
+    countingLabel: "",
+    detailFacts: "",
+    detailHint: "",
+    detailName: "",
+    detailRef: "",
+    detailState: "none",
+    dropActive: "false",
+    emptyDetail: "",
+    emptyTitle: "",
+    filters: [],
+    gridState: "loading",
+    mode: "manage",
+    previewFontFace: "",
+    previewGlyph: "",
+    previewKind: "glyph",
+    previewSpecimen: "",
+    previewSpecimenFamily: "",
+    previewSrc: "",
+    query: "",
+    region: "",
+    replaceAccept: "",
+    selectedFile: "",
+    sort: "",
+    sortOptions: [],
+    tiles: [],
+    title: "",
+    titleId: "",
+    uploadAccept: "",
+    uploadHint: "",
+    usageFiles: [],
+    usageHeadline: "",
+    usageState: "hidden",
+  };
+}
+
+function project(scope: MediaLibraryScope, view: MediaLibraryView): void {
+  Object.assign(scope, view);
+  scope.hasUsageFiles = view.usageFiles.length > 0;
+}
+
+/** The `part` a definition declares, or `""`. */
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
+}
+
+/** The file a mapped tile stands for, read off its `$map` item. */
+function mappedFile(state: JxScope | undefined): string | null {
+  const map = state?.["$map"];
+  const item = isNonNullObject(map) && "item" in map ? map.item : undefined;
+  return isNonNullObject(item) && "file" in item && isString(item.file) ? item.file : null;
+}
+
+/**
+ * Mount the library into `host`.
+ *
+ * @param {HTMLElement} host - The pane's stage, or the pick dialog's slot
+ * @param {MediaLibraryView} view - What to draw right now
+ * @param {MediaLibraryActions} actions - What each control does
+ * @param {{ clear: boolean }} options - Whether the host is a stage to be emptied first
+ * @returns {MediaLibrarySurfaceHandle}
+ */
+export function mountMediaLibrarySurface(
+  host: HTMLElement,
+  view: MediaLibraryView,
+  actions: MediaLibraryActions,
+  options: { clear: boolean },
+): MediaLibrarySurfaceHandle {
+  if (options.clear) {
+    host.replaceChildren();
+  }
+  const { tileHost, gridHost, inputHost, ...controls } = actions;
+  const scope = reactive<MediaLibraryScope>({
+    ...emptyMediaLibraryView(),
+    ...controls,
+    hasUsageFiles: false,
+  });
+  project(scope, view);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("media-library", scope, host, {
+    onNodeCreated: (element, _path, def, state) => {
+      // `disposed` first: nodes are still created while a mount that was taken down runs out.
+      if (disposed || !(element instanceof HTMLElement)) {
+        return;
+      }
+      const part = partOf(def);
+      if (part === "tile") {
+        const file = mappedFile(state);
+        if (file !== null) {
+          tileHost(element, file);
+        }
+      } else if (part === "grid") {
+        gridHost(element);
+      } else if (element instanceof HTMLInputElement && part === "upload-input") {
+        inputHost(element, "upload");
+      } else if (element instanceof HTMLInputElement && part === "replace-input") {
+        inputHost(element, "replace");
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+    } else {
+      mounted = surface;
+    }
+    /* SAFETY: `media-library.json`'s root definition is a `div` element, so the runtime mounts an
+       HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
+    return surface.root as HTMLElement;
+  });
+
+  return {
+    attached: () => {
+      if (disposed) {
+        return false;
+      }
+      const root = mounted?.root;
+      return root === undefined ? true : root instanceof HTMLElement && host.contains(root);
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update: (next) => project(scope, next),
+  };
+}

package/src/surfaces/media-pick-dialog.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioMediaPickDialog",
+  "$description": "The full-size media picker (`specs/studio.md` §9.3): a `jx-dialog` whose body is the Media workspace's own library surface in pick mode, so the picker and the workspace are one surface at two sizes. The dialog owns modality, Escape, the backdrop and focus restoration, and its footer is the answer: Cancel, or Use <file>, disabled until a file is chosen. The body is an ISLAND: this document draws the slot and nothing in it, and `surfaces/media-pick-dialog.ts` mounts `media-library.json` there through `onNodeCreated`.",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": {
+      "$ref": "#/state/headline"
+    },
+    "confirmLabel": {
+      "$ref": "#/state/confirmLabel"
+    },
+    "confirmDisabled": {
+      "$ref": "#/state/blocked"
+    },
+    "cancelLabel": "Cancel",
+    "dismissible": true,
+    "size": "xl"
+  },
+  "attributes": {
+    "part": "media-pick"
+  },
+  "onconfirm": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/confirm"
+        },
+        "value": []
+      }
+    ]
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "library-slot"
+      },
+      "style": {
+        "$description": "The library's box in pick mode is its own (`media-library.json`, `data-mode=\"pick\"`); the slot only gives it the dialog body's width.",
+        "minWidth": "0"
+      }
+    }
+  ]
+}

package/src/surfaces/media-pick-dialog.ts

@@ -0,0 +1,132 @@
+/// <reference lib="dom" />
+/**
+ * The full-size media picker's dialog, as a mounted document.
+ *
+ * A `jx-dialog` in the dialog layer whose body is an island: `media-pick-dialog.json` draws the
+ * slot, and the flow (`media/media-library.ts`) mounts the Media workspace's own library into it in
+ * pick mode, through the `onNodeCreated` seam (`studio-ui-guidelines.md` §9.4). So the picker and
+ * the workspace are one surface at two sizes, and the dialog is only the frame and the answer:
+ * Cancel, or Use <file>.
+ *
+ * **Await the ELEMENT, not just the mount.** `mountSurface` resolving means the document rendered;
+ * a `jx-dialog`'s own template is one `connectedCallback` later, and `showModal` in between finds
+ * no `<dialog>` to open. `whenReady` is shared with `surfaces/dialog.ts`.
+ *
+ * @docs studio/projects/media
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { whenReady } from "./dialog";
+import pickDoc from "./media-pick-dialog.json";
+import type { JxElement } from "@jxsuite/schema/types";
+import type { DialogLayerHandle, SurfaceHandle } from "../ui/surface";
+import { isString } from "@jxsuite/schema/guards";
+
+registerSurface("media-pick-dialog", pickDoc);
+
+/** The slot id, and so the dialog's region: `overlay.dialog:media-picker`. */
+export const MEDIA_PICK_SLOT = "media-picker";
+
+/** What the dialog's own chrome says. */
+export interface MediaPickDialogView {
+  headline: string;
+  /** "Use hero.jpg", or "Use file" while nothing is chosen. */
+  confirmLabel: string;
+  /** No file is chosen, so there is nothing to use yet. */
+  blocked: boolean;
+}
+
+export interface MediaPickDialogOptions {
+  layer: HTMLElement;
+  view: MediaPickDialogView;
+  /** The body slot was created: where the flow mounts the library. */
+  body: (host: HTMLElement) => void;
+  confirm: () => void;
+  /** The dialog closed, for any reason, once. */
+  closed: () => void;
+}
+
+export interface MediaPickDialogHandle extends DialogLayerHandle {
+  update: (view: MediaPickDialogView) => void;
+}
+
+interface MediaPickScope extends MediaPickDialogView {
+  confirm: () => void;
+  closed: () => void;
+}
+
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
+}
+
+/** Open the dialog. The handle's `ready` resolves once it is showing. */
+export function openMediaPickDialogSurface(options: MediaPickDialogOptions): MediaPickDialogHandle {
+  const slot = document.createElement("div");
+  /* The layer is `pointer-events: none`; every slot turns them back on for its own content, or a
+     modal `<dialog>` in it is painted above everything and hit-tests to nothing (surfaces/add-new). */
+  slot.style.pointerEvents = "auto";
+  slot.setAttribute(REGION_ATTR, overlayRegion("dialog", MEDIA_PICK_SLOT));
+  options.layer.append(slot);
+
+  let closed = false;
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.closed();
+  };
+  /** Read through a call, so a check after an `await` is not narrowed to the value before it. */
+  const isClosed = (): boolean => closed;
+
+  const scope = reactive<MediaPickScope>({
+    ...options.view,
+    closed: finish,
+    confirm: options.confirm,
+  });
+
+  let mounted: SurfaceHandle | null = null;
+  const ready = mountSurface("media-pick-dialog", scope, slot, {
+    onNodeCreated: (element, _path, def) => {
+      if (!isClosed() && element instanceof HTMLElement && partOf(def) === "library-slot") {
+        options.body(element);
+      }
+    },
+  }).then(async (surface) => {
+    mounted = surface;
+    /* SAFETY: `media-pick-dialog.json`'s root definition is a `jx-dialog` element, so the runtime
+       mounts an HTMLElement. */
+    const element = surface.root as HTMLElement;
+    if (isClosed()) {
+      surface.dispose();
+      return element;
+    }
+    await whenReady(element);
+    if (!isClosed()) {
+      showModal(element);
+    }
+    return element;
+  });
+
+  return {
+    close() {
+      const element = mounted?.root;
+      if (element instanceof HTMLElement) {
+        close(element);
+      }
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+      finish();
+    },
+    host: slot,
+    ready,
+    update(view) {
+      Object.assign(scope, view);
+    },
+  };
+}

package/src/surfaces/menu.ts

@@ -257,6 +257,7 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
       }
       // Run BEFORE closing: a command reads its target synchronously on entry, and closing the
       // Menu is what clears it.
+      handBackKeyboard(menu, options.opener ?? null);
       if (row.run) {
         row.run();
       } else {
@@ -367,6 +368,23 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
   return handle;
 }
 
+/**
+ * Give the keyboard back to the opener BEFORE a chosen row runs, while the menu still holds it.
+ *
+ * A row that opens a modal dialog (Open Project Settings, a confirmation) calls `showModal()` from
+ * inside its run, and the platform records whatever is focused at that moment as the element to
+ * restore when the dialog closes. Left alone that is the menu ROW, which is gone by the time the
+ * dialog closes, so Escape dropped focus on `<body>` instead of the gear that opened the menu. The
+ * opener is where focus goes when the menu closes anyway ({@link restoreFocus}); doing it first
+ * only makes it the element the dialog remembers. Only when the menu holds focus, for the reason
+ * `restoreFocus` gives.
+ */
+function handBackKeyboard(menu: MenuElement | null, opener: HTMLElement | null): void {
+  if (menu?.contains(document.activeElement) && opener?.isConnected && opener !== document.body) {
+    opener.focus({ preventScroll: true });
+  }
+}
+
 /**
  * Hand the keyboard back to the opener, only when the menu still held it: an outside CLICK has
  * already moved focus somewhere the author chose, and yanking it back would fight them. In a