@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/media-field.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioMediaField",
+  "$description": "The media field: a thumbnail of what the value names, the value itself, and the two doors to a different one. It is a LEAF a caller interpolates \u2014 the Inspector's Content tab, the Signals panel and the grid's image-cell panel each draw an empty host and `ui/media-picker.ts` mounts this into it \u2014 so it has no chrome of its own and takes its width from whatever row it lands in. **Browse is addressed through its `part`, not through a class.** `ui/regions.ts` derives `inspector/field:<prop>/browse` by finding the Browse control inside the Inspector's own `[data-prop]` row; the handle used to be `.media-picker-browse`, and a document emits no class, so `[part=\"browse\"]` is the handle now. The four `.media-picker*` rules from `styles/overlays.css` are TRANSCRIBED here rather than shared, for the reason `doc-header.json` gives: a class a document does not emit cannot style it. `--radius` becomes `--jx-radius-sm` on the way, because a document mounted in a pane's stage is outside `<sp-theme>` and would otherwise take a fallback rather than follow the theme.",
+  "tagName": "div",
+  "attributes": {
+    "part": "media-field"
+  },
+  "style": {
+    "$description": "The row's own layout and the four transcribed `.media-picker*` rules. Upload and Browse never shrink, so the FIELD is what yields width when the row is narrow \u2014 the buttons would otherwise collapse into unreadable stubs before the text did.",
+    "display": "flex",
+    "alignItems": "center",
+    "gap": "var(--jx-space-1)",
+    "flex": "1",
+    "minWidth": "0",
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-md)",
+    "color": "var(--fg)",
+    "& [part=\"value\"]": {
+      "flex": "1",
+      "minWidth": "0"
+    },
+    "& [part=\"upload\"]": {
+      "flexShrink": "0"
+    },
+    "& [part=\"browse\"]": {
+      "flexShrink": "0"
+    },
+    "& [part=\"thumb\"]": {
+      "width": "24px",
+      "height": "24px",
+      "objectFit": "cover",
+      "borderRadius": "var(--jx-radius-sm)",
+      "border": "1px solid var(--border)",
+      "flexShrink": "0"
+    }
+  },
+  "children": [
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "thumb-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/thumbState"
+      },
+      "cases": {
+        "shown": {
+          "$description": "Decorative on purpose: the field beside it already states the path in text, so a caption here would be the same fact twice to a screen reader and nothing to anyone else.",
+          "tagName": "img",
+          "attributes": {
+            "part": "thumb",
+            "src": "${state.thumbSrc}",
+            "alt": ""
+          }
+        }
+      }
+    },
+    {
+      "tagName": "jx-textfield",
+      "attributes": {
+        "part": "value"
+      },
+      "$props": {
+        "size": "sm",
+        "label": "${state.label}",
+        "placeholder": "/image.jpg",
+        "value": {
+          "$ref": "#/state/value"
+        }
+      },
+      "oninput": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/edit"
+            },
+            "value": [
+              {
+                "$ref": "event#/target/value"
+              }
+            ]
+          }
+        ],
+        "description": "Every keystroke, because the host debounces it: the canvas follows the typing without a document write per character."
+      },
+      "onfocus": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/warm"
+            },
+            "value": []
+          }
+        ],
+        "description": "Entering the field is the earliest honest signal that a pick is coming, so the project's media are listed then rather than when Browse is pressed."
+      }
+    },
+    {
+      "tagName": "jx-action-button",
+      "attributes": {
+        "part": "upload"
+      },
+      "$props": {
+        "size": "sm",
+        "quiet": true,
+        "icon": "upload-simple",
+        "label": "Upload media",
+        "hint": "Upload media"
+      },
+      "onclick": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/upload"
+            },
+            "value": []
+          }
+        ]
+      }
+    },
+    {
+      "tagName": "jx-action-button",
+      "attributes": {
+        "part": "browse"
+      },
+      "$props": {
+        "size": "sm",
+        "quiet": true,
+        "icon": "image",
+        "label": "Browse media",
+        "hint": "Browse media"
+      },
+      "onclick": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/browse"
+            },
+            "value": [
+              {
+                "$ref": "event#/currentTarget"
+              }
+            ]
+          }
+        ],
+        "description": "The button hands over ITSELF: the browser is a popover and the platform wants its invoker, both so a second press on this control toggles rather than reopens and so focus comes back here when it closes."
+      }
+    }
+  ]
+}

package/src/surfaces/media-field.ts

@@ -0,0 +1,116 @@
+/// <reference lib="dom" />
+/**
+ * The media field, as a mounted document.
+ *
+ * This is the adapter. `ui/media-picker.ts` is the flow — what the project's media are, what a
+ * thumbnail's URL is in a canvas realm, how long a keystroke waits before it becomes a document
+ * write, and what Upload and Browse actually do — and this is the control it draws into. Nothing
+ * here knows what a media file is: the scope is a string, a thumbnail URL, and four callbacks.
+ *
+ * **It is mounted into a host the CALLER owns**, which is the seam a leaf gets when the module
+ * interpolating it is still lit (specs/studio-ui-guidelines.md §9.4). Three callers draw an empty
+ * box and hand it over — `panels/properties-panel.ts` through the Content tab's
+ * `[part="control-host"]`, `panels/signals-panel.ts` through its island map, and
+ * `grid/cell-popovers.ts` through `grid-cell.json`'s `[part="picker-host"]` — and each of them used
+ * to `litRender` a template returned from here instead. A document cannot be handed back as a
+ * value, so the leaf is mounted rather than returned, and {@link MediaFieldHandle.update} is what a
+ * repaint calls in place of rendering the template again.
+ *
+ * @docs studio/projects/media
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import mediaFieldDoc from "./media-field.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("media-field", mediaFieldDoc as unknown as JxDocument);
+
+/** Everything the control draws, as one value. */
+export interface MediaFieldView {
+  /** The field's accessible name — the attribute or prop it edits. */
+  label: string;
+  /** What the field holds: the authored value, never the preview URL. */
+  value: string;
+  /** Whether a preview stands beside the field. Only an image value has one. */
+  thumbState: "hidden" | "shown";
+  /** The preview's URL, which is a realm-resolved projection of the value rather than the value. */
+  thumbSrc: string;
+}
+
+/** What a control asks the flow to do. */
+export interface MediaFieldActions {
+  /** A keystroke in the field. The flow debounces; the document reports every one. */
+  edit: (value: string) => void;
+  /** The field took focus: list the project's media, if that has not happened yet. */
+  warm: () => void;
+  /** Upload was pressed: open the OS file picker. */
+  upload: () => void;
+  /** Browse was pressed, from that control: open the project's media under it. */
+  browse: (anchor: HTMLElement) => void;
+}
+
+export interface MediaFieldHandle {
+  /** Bring the mounted control up to date; the document reconciles in place. */
+  update: (view: MediaFieldView) => void;
+  dispose: () => void;
+}
+
+/** The scope the document reads. */
+interface MediaFieldScope extends Record<string, unknown>, MediaFieldView, MediaFieldActions {}
+
+/** Write a projection into the scope. */
+function project(scope: MediaFieldScope, view: MediaFieldView): void {
+  scope.label = view.label;
+  scope.value = view.value;
+  scope.thumbState = view.thumbState;
+  scope.thumbSrc = view.thumbSrc;
+}
+
+/**
+ * Mount the media field into `host`, wired to `actions`.
+ *
+ * @param {HTMLElement} host - The empty box the caller drew for it
+ * @param {MediaFieldView} view - What to draw right now
+ * @param {MediaFieldActions} actions - What each control does
+ * @returns {MediaFieldHandle}
+ */
+export function mountMediaFieldSurface(
+  host: HTMLElement,
+  view: MediaFieldView,
+  actions: MediaFieldActions,
+): MediaFieldHandle {
+  const scope = reactive<MediaFieldScope>({
+    browse: actions.browse,
+    edit: actions.edit,
+    label: view.label,
+    thumbSrc: view.thumbSrc,
+    thumbState: view.thumbState,
+    upload: actions.upload,
+    value: view.value,
+    warm: actions.warm,
+  }) as MediaFieldScope;
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  /* The mount is async and the host may be gone before it lands — a projection can replace the row
+     that owns the box in the same turn it was announced — so the `.then` has to notice, exactly as
+     every other island adapter's does. */
+  void mountSurface("media-field", scope, host).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (next) => project(scope, next),
+  };
+}