@jxsuite/studio 6.1.1 → 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-pane.ts

@@ -24,10 +24,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import mediaDoc from "./media-pane.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("media-pane", mediaDoc as unknown as JxDocument);
+registerSurface("media-pane", mediaDoc);
 
 /**
  * Which element the stage draws the file in.
@@ -105,7 +104,7 @@ export interface MediaSurfaceHandle {
  * `$switch` discriminant derived here — "is there a list" is a restatement of the list, and a view
  * that had to keep the two in step would be a second place to get it wrong.
  */
-interface MediaScope extends Record<string, unknown>, MediaView, MediaActions {
+interface MediaScope extends MediaView, MediaActions {
   hasUsageFiles: boolean;
 }
 
@@ -141,7 +140,7 @@ export function mountMediaSurface(
   actions: MediaActions,
 ): MediaSurfaceHandle {
   host.replaceChildren();
-  const scope = reactive<MediaScope>({
+  const scope: MediaScope = reactive<MediaScope>({
     copyRef: actions.copyRef,
     extLabel: "",
     facts: "",
@@ -159,7 +158,7 @@ export function mountMediaSurface(
     usageFiles: [],
     usageHeadline: "",
     usageState: "hidden",
-  }) as MediaScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;
@@ -171,9 +170,11 @@ export function mountMediaSurface(
   const ready = mountSurface("media-pane", scope, host).then((surface) => {
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+    } else {
+      mounted = surface;
     }
-    mounted = surface;
+    /* SAFETY: `media-pane.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;
   });
 

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