@jxsuite/studio 10.1.0 → 10.3.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/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/surfaces/settings-contributed.json

@@ -24,7 +24,7 @@
       "marginBottom": "12px"
     },
     "& [part=\"columns\"]": {
-      "$description": "The 1px gap over the border colour is the divider between the two columns: two panels on `--bg-panel` with `--border` showing through the gap, so nothing draws a rule of its own.",
+      "$description": "The 1px gap over the border colour is the divider between the two columns: two panels on the page's own `--bg` with `--border` showing through the gap, so nothing draws a rule of its own. The panels are `--bg`, not `--bg-panel`, because the section is drawn on the Settings home, whose background is `--bg`: a second shade under one section of the form reads as a box nobody asked for.",
       "display": "flex",
       "height": "100%",
       "gap": "1px",
@@ -37,7 +37,7 @@
       "padding": "12px",
       "width": "200px",
       "minWidth": "200px",
-      "background": "var(--bg-panel)",
+      "background": "var(--bg)",
       "overflowY": "auto"
     },
     "& [part=\"entry\"], & [part=\"new-open\"]": {
@@ -62,7 +62,7 @@
       "display": "flex",
       "alignItems": "center",
       "justifyContent": "center",
-      "background": "var(--bg-panel)",
+      "background": "var(--bg)",
       "color": "var(--fg-dim)",
       "fontSize": "13px"
     },
@@ -70,7 +70,7 @@
       "$description": "`min-width: 0` is the one line `.settings-editor-panel` did not have and needed: a flex child's floor is its content, and the schema form inside this one is a whole form rather than the short cards Data Shapes puts here — so a long pointer or a wide row pushed the column past the right edge of the pane instead of scrolling inside it.",
       "flex": "1",
       "padding": "16px",
-      "background": "var(--bg-panel)",
+      "background": "var(--bg)",
       "overflowY": "auto",
       "minWidth": "0"
     },

package/src/surfaces/settings-contributed.ts

@@ -41,7 +41,7 @@ export interface ContributedEntryView {
   /** The key in the section's map on disk — the row's identity and its `data-entry`. */
   key: string;
   selected: boolean;
-  /** `overlay.dialog:settings/entry:<key>`, so a shot can name the row without a selector. */
+  /** `pane.<id>/settings/entry:<key>`, so a shot can name the row without a selector. */
   region: string;
 }
 
@@ -61,7 +61,7 @@ export interface ContributedView {
   editorState: "empty" | "editing";
   /** What the rename field holds — the key on disk, or what the reader has just typed. */
   entryName: string;
-  /** `overlay.dialog:settings/editor`. */
+  /** `pane.<id>/settings/editor`. */
   editorRegion: string;
   /** The new-entry button: "New content type", or "New entry" when the section names none. */
   newLabel: string;