@jxsuite/studio 10.2.0 → 10.4.0

package/src/surfaces/image-editor.ts

@@ -0,0 +1,272 @@
+/// <reference lib="dom" />
+/**
+ * The Image editor surface: one image asset, edited where it is opened (studio.md §9.5).
+ *
+ * This is the adapter. `media/image-editor.ts` keeps the recipe, its undo stack, the decoded source
+ * and the one write door, and hands this module a flat projection: pre-formatted geometry strings,
+ * the values the fields show, and the words the `$switch`es read. The document renders that and
+ * decides nothing.
+ *
+ * **One island.** A drag converts screen pixels into the image's own frame, which needs the frame's
+ * drawn size, so the frame element is captured as it is created (`onNodeCreated`,
+ * studio-ui-guidelines.md §9.4) and the flow asks for its rect. The handles are captured the same
+ * way, so moving the roving tab stop to the next handle focuses an element this module was handed
+ * rather than one it searched for.
+ *
+ * **The container is CLEARED, because this is a pane and not a panel** — the reason
+ * `surfaces/media-pane.ts` gives: the canvas stage is handed to whichever mode owns it whole.
+ *
+ * @docs studio/projects/media
+ */
+
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { rectOf } from "../utils/geometry";
+import imageEditorDoc from "./image-editor.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { JxElement } from "@jxsuite/schema/types";
+
+registerSurface("image-editor", imageEditorDoc);
+
+/** One crop handle as the document draws it. */
+export interface ImageHandleRow {
+  id: string;
+  /** Where it sits on screen, as a reader hears it. */
+  label: string;
+  /** `"0"` for the one handle in the tab order, `"-1"` for the other seven. */
+  tabindex: string;
+}
+
+/** Everything the document draws, as one value. */
+export interface ImageEditorView {
+  region: string;
+  /** `loading` while the bytes are read, `refused` with the reason, `ready` with a picture. */
+  status: "loading" | "ready" | "refused";
+  /** What the loading or refused box says. */
+  message: string;
+  name: string;
+  alt: string;
+  /** A same-origin `blob:` URL for the bytes the editor holds. */
+  src: string;
+  /** The oriented aspect, width over height, as a number string. */
+  ratio: string;
+  /** The oriented width in CSS pixels, so the preview is never upscaled. */
+  maxWidth: string;
+  imageWidth: string;
+  imageHeight: string;
+  imageTransform: string;
+  /** The tone pass, the same string the bake sets on its context; `none` when neutral. */
+  filter: string;
+  cropX: string;
+  cropY: string;
+  cropW: string;
+  cropH: string;
+  handles: ImageHandleRow[];
+  handleHelpId: string;
+  /** The ratio the crop is held to, and the picker's rows. */
+  aspect: string;
+  aspectOptions: { label: string; value: string }[];
+  /** The crop area's cursor: `move`, or `default` when there is nowhere for it to go. */
+  moveCursor: string;
+  facts: string;
+  width: string;
+  maxOutputWidth: string;
+  fitLabel: string;
+  fitHint: string;
+  quality: "shown" | "hidden";
+  qualityValue: string;
+  brightness: string;
+  contrast: string;
+  saturation: string;
+  warning: string;
+  /** Disabled flags, each named for the state that disables. */
+  busy: boolean;
+  undecoded: boolean;
+  cannotUndo: boolean;
+  cannotRedo: boolean;
+  cannotFit: boolean;
+  clean: boolean;
+  cannotSave: boolean;
+  saving: boolean;
+}
+
+/** What a control can ask the editor to do. Every one is a decision the flow owns. */
+export interface ImageEditorActions {
+  imageLoaded: (width: number, height: number) => void;
+  imageFailed: (src: string) => void;
+  rotate: (direction: number) => void;
+  flip: (axis: string) => void;
+  undo: () => void;
+  redo: () => void;
+  reset: () => void;
+  save: () => void;
+  fieldEdited: () => void;
+  fitForWeb: () => void;
+  setWidth: (value: string) => void;
+  setAspect: (value: string) => void;
+  setValue: (key: string, value: string) => void;
+  handleDown: (
+    handle: string,
+    pointerId: number,
+    clientX: number,
+    clientY: number,
+    target: Element,
+  ) => void;
+  handleMove: (pointerId: number, clientX: number, clientY: number) => void;
+  handleUp: (pointerId: number) => void;
+  handleFocused: (handle: string) => void;
+  nudge: (handle: string, dx: number, dy: number, large: boolean) => void;
+  cycleHandle: (handle: string, step: number) => void;
+}
+
+export interface ImageEditorSurfaceHandle {
+  ready: Promise<HTMLElement>;
+  /** Whether what was mounted is still inside the host; true while the mount is in flight. */
+  attached: () => boolean;
+  update: (view: ImageEditorView) => void;
+  /** The drawn frame's rect, or null before it exists. */
+  frameRect: () => DOMRect | null;
+  /** Move focus to one handle, when it has been drawn. */
+  focusHandle: (handle: string) => void;
+  /** Commit a number still being typed, so a save writes what is on screen. Keeps the focus. */
+  flushFields: () => void;
+  /** Put the view's values back in the number fields, whatever was typed into them. */
+  syncFields: (view: ImageEditorView) => void;
+  dispose: () => void;
+}
+
+type ImageEditorScope = ImageEditorView & ImageEditorActions;
+
+/** Each number field's `part`, which is also the name of the view value it shows. */
+const FIELD_VALUES = {
+  brightness: "brightness",
+  contrast: "contrast",
+  quality: "qualityValue",
+  saturation: "saturation",
+  width: "width",
+} as const;
+
+function isFieldPart(part: string): part is keyof typeof FIELD_VALUES {
+  return Object.hasOwn(FIELD_VALUES, part);
+}
+
+/**
+ * The `part` a definition declares, or `""`. Read off the DEFINITION, because a node is announced
+ * as it is created, before its attributes are applied.
+ */
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
+}
+
+/** The handle a mapped row stands for, read off its `$map` item. */
+function mappedHandle(state: JxScope | undefined): string | null {
+  const map = state?.["$map"];
+  const item = isNonNullObject(map) && "item" in map ? map.item : undefined;
+  return isNonNullObject(item) && "id" in item && isString(item.id) ? item.id : null;
+}
+
+/**
+ * Write a projection into the scope. Each key is assigned through the reactive proxy, which
+ * notifies only when a value moved, so a drag that changes four crop strings redraws those four.
+ */
+function project(scope: ImageEditorScope, view: ImageEditorView): void {
+  Object.assign(scope, view);
+}
+
+/**
+ * Mount the Image editor document into `host`, wired to `actions`.
+ *
+ * @param {HTMLElement} host - The pane's canvas stage
+ * @param {ImageEditorView} view - What to draw right now
+ * @param {ImageEditorActions} actions - What each control does
+ * @returns {ImageEditorSurfaceHandle}
+ */
+export function mountImageEditorSurface(
+  host: HTMLElement,
+  view: ImageEditorView,
+  actions: ImageEditorActions,
+): ImageEditorSurfaceHandle {
+  host.replaceChildren();
+  const scope = reactive<ImageEditorScope>({ ...view, ...actions });
+
+  let frame: Element | null = null;
+  const handles = new Map<string, HTMLElement>();
+  const fields = new Map<keyof typeof FIELD_VALUES, HTMLElement>();
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("image-editor", 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 === "frame") {
+        frame = element;
+      } else if (part === "handle") {
+        const id = mappedHandle(state);
+        if (id !== null) {
+          handles.set(id, element);
+        }
+      } else if (isFieldPart(part)) {
+        fields.set(part, element);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+    } else {
+      mounted = surface;
+    }
+    /* SAFETY: `image-editor.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 : host.contains(root);
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+      frame = null;
+      handles.clear();
+      fields.clear();
+    },
+    focusHandle: (handle) => {
+      const element = handles.get(handle);
+      if (element?.isConnected) {
+        element.focus();
+      }
+    },
+    frameRect: () => (frame?.isConnected ? rectOf(frame) : null),
+    flushFields: () => {
+      /* A number input commits on blur, which fires its change event synchronously, and the
+         document's handler then takes the value. Focused straight back, so the author's place is
+         not lost to a keystroke that only meant "save". */
+      const active = document.activeElement;
+      if (active instanceof HTMLInputElement && host.contains(active)) {
+        active.blur();
+        active.focus();
+      }
+    },
+    ready,
+    syncFields: (next) => {
+      for (const [part, element] of fields) {
+        if (element.isConnected && "value" in element) {
+          element.value = next[FIELD_VALUES[part]];
+        }
+      }
+    },
+    update: (next) => project(scope, next),
+  };
+}

package/src/surfaces/inspector-dock.json

@@ -54,8 +54,8 @@
       "maxWidth": "none",
       "padding": "var(--jx-space-1) var(--jx-space-2)"
     },
-    "& [part=\"panel\"]": {
-      "$description": "`#right-panel > .panel-body { flex: 1; min-height: 0; overflow-y: auto }`, now a flex column: Element's sub-switch sits above its leaves and must not scroll away with them. The kit's tab panel pads itself for a dialog; a dock's tab is the whole column and each body pads its own content.",
+    "& > [part=\"panel\"]": {
+      "$description": "`#right-panel > .panel-body { flex: 1; min-height: 0; overflow-y: auto }`, now a flex column: Element's sub-switch sits above its leaves and must not scroll away with them. The kit's tab panel pads itself for a dialog; a dock's tab is the whole column and each body pads its own content. The child combinator is load-bearing: the leaves mount in this same light DOM, the Style leaf's root and every `jx-color-field`'s picker are also `part=\"panel\"`, and a descendant selector put this `overflow: hidden` on them. The Style root then clipped its own rows, so `panel-body` below saw nothing to scroll and every property past the fold was unreachable.",
       "display": "flex",
       "flexDirection": "column",
       "flex": "1",
@@ -63,7 +63,7 @@
       "padding": "0",
       "overflow": "hidden"
     },
-    "& [part=\"panel\"][hidden]": {
+    "& > [part=\"panel\"][hidden]": {
       "$description": "Out of sight, out of the layout and out of the accessibility tree, but not `display: none`: a panel that left the box tree is restyled whole when it comes back, and the Inspector shows its Page panel on every deselect and on every close of the Assistant (§6), which made each of those a 300-element style recalculation. `content-visibility: hidden` skips the subtree while keeping its computed style, so a return restyles only what changed while it was away; `visibility: hidden` keeps it unfocusable and unexposed, as `hidden` means.",
       "display": "flex",
       "flex": "0 0 0",

package/src/surfaces/media-library.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioMediaLibrary",
-  "$description": "The Media workspace's library (`specs/studio.md` §22.6): the project's media as filters, a grid and the selected file's detail. ONE document in two modes. In `manage` it is the Media home tab, with Replace, Open in viewer and Delete under the detail; in `pick` it is the full-size picker inside a `jx-dialog` (`media-pick-dialog.json`), and the dialog's own footer answers Cancel or Use <file>. `media/media-library.ts` keeps every decision (which files a filter keeps, the sort, what a count may claim, where an arrow lands, what Replace writes) and hands this document strings and discriminants. **Unused is drawn with no number until the usage sweep has settled**, and Missing alt text and tags are not drawn at all: each needs a store that does not exist, and a filter that cannot be answered is not shipped as one that always answers nothing.",
+  "$description": "The Media workspace's library (`specs/studio.md` §22.6): the project's media as filters, a grid and the selected file's detail. ONE document in two modes. In `manage` it is the Media home tab, with Replace, Open in viewer, Rename, Duplicate and Delete under the detail; in `pick` it is the full-size picker inside a `jx-dialog` (`media-pick-dialog.json`), and the dialog's own footer answers Cancel or Use <file>. `media/media-library.ts` keeps every decision (which files a filter keeps, the sort, what a count may claim, where an arrow lands, what Replace writes) and hands this document strings and discriminants. **Unused is drawn with no number until the usage sweep has settled**, and Missing alt text and tags are not drawn at all: each needs a store that does not exist, and a filter that cannot be answered is not shipped as one that always answers nothing.",
   "tagName": "div",
   "attributes": {
     "part": "media-library",
@@ -1578,6 +1578,134 @@
                             }
                           ]
                         },
+                        {
+                          "tagName": "div",
+                          "attributes": {
+                            "part": "edit-slot",
+                            "role": "none"
+                          },
+                          "style": {
+                            "display": "contents"
+                          },
+                          "$switch": {
+                            "$ref": "#/state/editable"
+                          },
+                          "cases": {
+                            "yes": {
+                              "tagName": "jx-button",
+                              "attributes": {
+                                "part": "edit-image"
+                              },
+                              "$props": {
+                                "size": "sm",
+                                "variant": "secondary"
+                              },
+                              "onclick": {
+                                "$prototype": "Function",
+                                "body": [
+                                  {
+                                    "operator": "call",
+                                    "target": {
+                                      "$ref": "#/state/editImage"
+                                    },
+                                    "value": []
+                                  }
+                                ],
+                                "description": "Withheld, not disabled, for a file the editor cannot write: a refused format is not offered rather than offered and then refused (studio.md §9.5)."
+                              },
+                              "children": [
+                                {
+                                  "tagName": "span",
+                                  "textContent": "Edit image"
+                                }
+                              ]
+                            },
+                            "no": {
+                              "tagName": "span",
+                              "attributes": {
+                                "hidden": true
+                              }
+                            }
+                          }
+                        },
+                        {
+                          "tagName": "jx-button",
+                          "attributes": {
+                            "part": "rename"
+                          },
+                          "$props": {
+                            "size": "sm",
+                            "variant": "secondary"
+                          },
+                          "onclick": {
+                            "$prototype": "Function",
+                            "body": [
+                              {
+                                "operator": "call",
+                                "target": {
+                                  "$ref": "#/state/rename"
+                                },
+                                "value": []
+                              }
+                            ]
+                          },
+                          "children": [
+                            {
+                              "tagName": "span",
+                              "textContent": "Rename"
+                            }
+                          ]
+                        },
+                        {
+                          "tagName": "div",
+                          "attributes": {
+                            "part": "duplicate-slot",
+                            "role": "none"
+                          },
+                          "style": {
+                            "display": "contents"
+                          },
+                          "$switch": {
+                            "$ref": "#/state/duplicable"
+                          },
+                          "cases": {
+                            "yes": {
+                              "tagName": "jx-button",
+                              "attributes": {
+                                "part": "duplicate"
+                              },
+                              "$props": {
+                                "size": "sm",
+                                "variant": "secondary"
+                              },
+                              "onclick": {
+                                "$prototype": "Function",
+                                "body": [
+                                  {
+                                    "operator": "call",
+                                    "target": {
+                                      "$ref": "#/state/duplicate"
+                                    },
+                                    "value": []
+                                  }
+                                ],
+                                "description": "Withheld, not disabled, on a backend that cannot read a file's raw bytes: a copy read as text would be a broken file (studio.md §9.3)."
+                              },
+                              "children": [
+                                {
+                                  "tagName": "span",
+                                  "textContent": "Duplicate"
+                                }
+                              ]
+                            },
+                            "no": {
+                              "tagName": "span",
+                              "attributes": {
+                                "hidden": true
+                              }
+                            }
+                          }
+                        },
                         {
                           "tagName": "jx-button",
                           "attributes": {

package/src/surfaces/media-library.ts

@@ -4,8 +4,8 @@
  *
  * 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.
+ * Rename, Duplicate, 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
@@ -97,6 +97,13 @@ export interface MediaLibraryView {
   previewSpecimen: string;
   /** The Replace input's `accept`: the selected file's own format only. */
   replaceAccept: string;
+  /**
+   * Whether the selected file opens in the Image editor (studio.md §9.5): withheld on exactly the
+   * conditions `media.edit` gates on, so the palette and this pane cannot give two answers.
+   */
+  editable: "yes" | "no";
+  /** Whether the host can copy the selected file: `media.duplicate` gates on the same capability. */
+  duplicable: "yes" | "no";
   usageState: "hidden" | "shown";
   usageHeadline: string;
   usageFiles: MediaUsageRow[];
@@ -126,7 +133,13 @@ export interface MediaLibraryActions {
   openDocument: (path: string) => void;
   replace: (input: HTMLInputElement) => void;
   remove: () => void;
+  /** Rename the selected file, through the Rename dialog. */
+  rename: () => void;
+  /** Copy the selected file to a new name beside it, and select the copy. */
+  duplicate: () => void;
   openViewer: () => void;
+  /** Open the selected image in its Image editor. */
+  editImage: () => void;
   reset: () => void;
   /** A tile node was created for `file`. */
   tileHost: (element: HTMLElement, file: string) => void;
@@ -174,6 +187,8 @@ export function emptyMediaLibraryView(): MediaLibraryView {
     query: "",
     region: "",
     replaceAccept: "",
+    editable: "no",
+    duplicable: "no",
     selectedFile: "",
     sort: "",
     sortOptions: [],

package/src/types.ts

@@ -406,7 +406,8 @@ export interface StudioPlatform {
    * tainting stops being a thing that can happen rather than a thing that is worked around.
    *
    * Optional, and feature-detected like every optional member: a backend without it simply does not
-   * offer the image editor, which is the honest degradation `specs/desktop.md` §3.1 asks for.
+   * offer the image editor or a file's Duplicate, which is the honest degradation
+   * `specs/desktop.md` §3.1 asks for.
    */
   readFileBytes?: (path: string) => Promise<ArrayBuffer>;
   writeFile: (path: string, content: string) => Promise<void>;

package/src/workspace/tab-workspace.ts

@@ -47,7 +47,8 @@ export function workspaceOfTab(tab: Tab): WorkspaceId {
   if (mode === "git-diff") {
     return "publish";
   }
-  if (mode === "media") {
+  // The viewer and its editing sibling (`media/image-editor.ts`, §9.5): one file, one workspace.
+  if (mode === "media" || mode === "image") {
     return "media";
   }
   if (CONTENT_MODES.has(mode)) {

package/src/workspace/workspace-switch.ts

@@ -46,6 +46,7 @@ import {
   setCloseLanding,
   setEmptyPaneFallback,
   setTabScope,
+  tabHoldsEditBesideDocument,
   workspace,
 } from "./workspace";
 import { homeWorkspaceOfTabId, isHomeWorkspace, workspaceHomeTabId } from "./workspace-ids";
@@ -119,7 +120,8 @@ export function viewsReplacedBy(
       homeWorkspaceOfTabId(other) !== id &&
       workspaceOfTab(tab) === id &&
       !tab.pinned &&
-      !tab.doc.dirty
+      !tab.doc.dirty &&
+      !tabHoldsEditBesideDocument(tab)
     );
   });
 }

package/src/workspace/workspace.ts

@@ -1063,12 +1063,33 @@ export function promoteTab(tabId: string) {
  */
 export function promoteDirtyPreviewTabs() {
   for (const [id, tab] of workspace.tabs) {
-    if (tab.preview && tab.doc.dirty) {
+    if (tab.preview && (tab.doc.dirty || tabHoldsEditBesideDocument(tab))) {
       promoteTab(id);
     }
   }
 }
 
+/** The answer to {@link tabHoldsEditBesideDocument}, injected by the module that holds the edit. */
+let editBesideDocument: ((tab: Tab) => boolean) | null = null;
+
+/**
+ * Register who answers {@link tabHoldsEditBesideDocument}. Injected rather than imported, because
+ * the Image editor (`media/image-editor.ts`, studio.md §9.5) reaches the upload and collab layers,
+ * every one of which imports this module.
+ */
+export function setEditBesideDocument(answer: (tab: Tab) => boolean): void {
+  editBesideDocument = answer;
+}
+
+/**
+ * Whether this tab holds unsaved work that is NOT in its document: a media tab's document is a
+ * stub, and an image edit is a recipe held beside it, so `tab.doc.dirty` cannot say. Every gate
+ * that discards a tab without asking has to ask this too, or a pending crop goes in silence.
+ */
+export function tabHoldsEditBesideDocument(tab: Tab): boolean {
+  return editBesideDocument?.(tab) ?? false;
+}
+
 /**
  * Pin or unpin a tab, moving it to the boundary of the pinned prefix so the head of the strip is
  * always exactly the pinned set.

package/dist/chunks/adapter-pp011m5x.js

@@ -1,4 +0,0 @@
-import{Gs,Ks,Wr}from"./studio-sxdb9h3q.js";export{Wr as draggable,Gs as dropTargetForElements,Ks as monitorForElements};
-
-//# debugId=12250D3D5E1C3ED864756E2164756E21
-//# sourceMappingURL=adapter-pp011m5x.js.map