@jxsuite/studio 4.0.0 → 5.0.0

package/src/canvas/diff-view.ts

@@ -0,0 +1,123 @@
+/**
+ * A diff pane's review state: the comparison's change map, and where in it the author is.
+ *
+ * **The store is a module-local `Map` keyed by pane**, the shape `_editWidths` in `edit-width.ts`
+ * and `_fits` in `canvas-utils.ts` already use. The value is transient — it is rebuilt by the
+ * render pass that computes the comparison — and its only readers are that pass, the stepper and
+ * the diff header, so a field on `CanvasSurface` would buy nothing and a field on `shell` would be
+ * an app-level slot for a per-pane fact, which is exactly the defect the Diff LENS was built to
+ * avoid (`workspace/pane-derive.ts`, finding 4: one app-level `diffState` meant two panes drew one
+ * comparison).
+ *
+ * **Keyed by PANE, because two panes can compare two different files at once** — the Source Control
+ * panel's diff in the primary and a Diff lens beside it — and because a lens must never write the
+ * source tab's `session.ui`. `canvasModeOfPane` and `derivationOfPane` are keyed the same way for
+ * the same reason.
+ *
+ * **This file is a LEAF.** It imports one type and nothing else, so the render pass, the stepper
+ * and the header can all reach it without any of them reaching each other.
+ */
+
+import type { ChangeMap } from "./diff-marks";
+
+/** Which half of a comparison a pane is showing. */
+export type DiffView = "visual" | "code";
+
+interface DiffRecord {
+  map: ChangeMap | null;
+  /** Index into `map.steps`, or -1 for "arrived, not yet stepping". */
+  step: number;
+  view: DiffView;
+}
+
+const _records = new Map<string, DiffRecord>();
+
+function recordFor(paneId: string): DiffRecord {
+  const existing = _records.get(paneId);
+  if (existing) {
+    return existing;
+  }
+  const fresh: DiffRecord = { map: null, step: -1, view: "visual" };
+  _records.set(paneId, fresh);
+  return fresh;
+}
+
+/**
+ * Record the comparison this pane's render just computed.
+ *
+ * **The cursor is CLAMPED rather than reset**, and that is the difference between a review loop
+ * somebody uses and one they abandon. Every save re-reads the comparison and rebuilds the map, so
+ * resetting here would send an author who fixed change 7 of 12 back to change 1 each time they hit
+ * ⌘S. Clamping keeps them where they were unless the list actually got shorter than their
+ * position.
+ */
+export function setDiffChangeMap(paneId: string, map: ChangeMap | null): void {
+  const record = recordFor(paneId);
+  record.map = map;
+  const total = map?.steps.length ?? 0;
+  record.step = total === 0 ? -1 : Math.min(record.step, total - 1);
+}
+
+/** This pane's comparison, or null when none has been computed (or it could not be). */
+export function diffChangeMapOf(paneId: string): ChangeMap | null {
+  return _records.get(paneId)?.map ?? null;
+}
+
+/** How many changes this pane's comparison found. */
+export function diffChangeCount(paneId: string): number {
+  return _records.get(paneId)?.map?.steps.length ?? 0;
+}
+
+/** Where the author is in the list: 0-based, or -1 before the first step. */
+export function diffStepOf(paneId: string): number {
+  return _records.get(paneId)?.step ?? -1;
+}
+
+/**
+ * Move the cursor and answer where it landed, or null when there is nowhere to go.
+ *
+ * **Stops at the ends rather than wrapping.** A tab strip is a ring with no ends, so `document
+ * .nextTab` cycles; a change list is a document read top to bottom, and wrapping past the last
+ * change silently returns a reviewer to part of the page they have already cleared. The header
+ * disables the button that cannot move and says which end it is at.
+ */
+export function stepDiff(paneId: string, delta: 1 | -1): number | null {
+  const record = _records.get(paneId);
+  const total = record?.map?.steps.length ?? 0;
+  if (!record || total === 0) {
+    return null;
+  }
+  // From -1 a forward step lands on 0 and a backward step on the last change, so either chord
+  // Enters the list from the end it is aimed at rather than refusing on arrival.
+  const next = record.step === -1 ? (delta === 1 ? 0 : total - 1) : record.step + delta;
+  if (next < 0 || next >= total) {
+    return null;
+  }
+  record.step = next;
+  return next;
+}
+
+/** Which half of the comparison this pane is showing. */
+export function diffViewOf(paneId: string): DiffView {
+  return _records.get(paneId)?.view ?? "visual";
+}
+
+/**
+ * Show the visual comparison or the code one.
+ *
+ * The caller pairs this with a repaint: the store is deliberately not reactive (its writers are a
+ * render pass and a toolbar click, both of which already know to redraw), so nothing observes it.
+ */
+export function setDiffView(paneId: string, view: DiffView): void {
+  recordFor(paneId).view = view;
+}
+
+/** Drop this pane's review state — called from the stage teardown, beside `clearEditWidth`. */
+export function clearDiffView(paneId: string): void {
+  _records.delete(paneId);
+}
+
+/** Drop every record. Tests only; there is no runtime caller. */
+export function resetDiffViews(): void {
+  _records.clear();
+}

package/src/canvas/edit-width-drag.ts

@@ -0,0 +1,187 @@
+/// <reference lib="dom" />
+/**
+ * Edit-width-drag — the gesture that resizes the Edit column, and only that.
+ *
+ * The store it writes through is `./edit-width`, deliberately a leaf: this module needs
+ * `applyEditZoom` from `canvas-utils.ts`, and `canvas-utils.ts` needs the store for the
+ * `canvas.setEditWidth` command, so keeping the two apart is what stops those imports closing a
+ * cycle. Everything here touches the DOM; nothing there does.
+ *
+ * @docs studio/design/breakpoints
+ */
+
+import { applyEditZoom } from "./canvas-utils";
+import { bindSplit } from "../ui/panel-resize";
+import {
+  EDIT_CANVAS_GUTTER,
+  EDIT_WIDTH_MIN,
+  EDIT_WIDTH_SNAP_TOLERANCE,
+  declaredWidthOfTab,
+  setEditWidth,
+  snapTargetsOfTab,
+} from "./edit-width";
+import { snapEditWidth } from "../utils/canvas-media";
+import { rectOf } from "../utils/geometry";
+import { tabOfPane } from "./canvas-surface";
+import type { CanvasSurface } from "./canvas-surface";
+import type { ResizeTarget, SplitElement } from "../ui/panel-resize";
+
+/**
+ * Apply a width to a live Edit column — the drag's only DOM writer.
+ *
+ * **Bare style writes, and never `renderPane`.** A full canvas render per `input` would rebuild the
+ * iframe DOM, break the `jx-split`'s own pointer capture along with it, and be far too slow to drag
+ * against — which is why this writes `session.ui.activeMedia` directly rather than going through
+ * `canvas.setBreakpoint`, whose `run` ends in a `repaint`. (It is NOT because a re-render would
+ * destroy an inline-edit session: pressing the handle already ended that, through the capture-phase
+ * `commitActiveEditSession` in `studio.ts`. The reason is cost and capture, not the caret.)
+ *
+ * The direct write is safe because `activeMedia` is deliberately absent from
+ * `installPaneRenderEffects`'s dependency list, so it repaints the Context bar, the overlays and
+ * the Inspector — none of which owns the column — and schedules no canvas pass at all.
+ *
+ * **{@link applyEditZoom} is called only when there IS a zoom**, and that is a correctness fix, not
+ * a micro-optimisation. It ends in `renderOnly("overlays")`, which is a full lit render of the
+ * block action bar — and that render's first act is to tear down the drag handle's pragmatic-dnd
+ * registration (`panels/block-action-bar.ts`, which already routes AROUND itself on scroll for
+ * exactly this reason). At `editZoom === 1` there is nothing for it to do anyway: the column is
+ * `width: 100%` under a `max-width` and the iframe is `width: 100%` under the column, so the CSS
+ * write above has already reflowed the frame. `settle()` re-anchors once, on release.
+ *
+ * The breakpoint is derived from the MEASURED width rather than the requested one: the column is
+ * `width: 100%` under a `max-width`, so a pane narrower than the request renders narrower than it,
+ * and a readout computed from the request would name a band the page is not in.
+ */
+export function applyEditWidth(surface: CanvasSurface, column: HTMLElement, width: number): void {
+  const tab = tabOfPane(surface.paneId);
+  if (!tab) {
+    return;
+  }
+  column.style.maxWidth = `${Math.round(width)}px`;
+  if ((tab.session.ui.editZoom ?? 1) !== 1) {
+    applyEditZoom(surface);
+  }
+  const rendered = rectOf(column).width || width;
+  setEditWidth(surface.paneId, tab, rendered);
+  column.dataset.editWidth = `${Math.round(rendered)}px`;
+  column.classList.add("is-resizing");
+}
+
+/**
+ * The Edit column, as a {@link ResizeTarget}.
+ *
+ * `grow` is the sign a rightward movement of the handle contributes: `+1` for the handle on the
+ * right of the column, `-1` for the one on the left. **`scale` doubles it, and that is what makes
+ * the two handles symmetric** — the column is centred by `justify-content: center`, so an edge that
+ * moves `dx` only stays under the pointer if the total width changes by `2·dx`, the opposite edge
+ * mirroring it. Both the placement and this sign are physical (`left`/`right`), because Studio's
+ * own chrome is left-to-right; the artboard's `dir` is a property of the document inside the
+ * iframe.
+ *
+ * **`lead` is the centre line.** The track a `jx-split` measures is the first boxed ancestor — the
+ * canvas, since each handle stands beside the column rather than inside it — and the column is
+ * centred in that canvas's CONTENT box, which is what `clientWidth` spans and a vertical scrollbar
+ * does not. So the right handle sits `clientWidth / 2 + width / 2` from the track's start, and the
+ * left one the same distance from its END, which for the trailing side is `track − clientWidth / 2`
+ * plus the half-width. Being exact about the scrollbar costs one subtraction and is what keeps
+ * `aria-valuenow` the handle's real position rather than one a few pixels off it.
+ */
+export function editWidthTarget(
+  surface: CanvasSurface,
+  column: HTMLElement,
+  grow: 1 | -1,
+): ResizeTarget {
+  const tabOf = () => tabOfPane(surface.paneId);
+  const centre = () => (column.parentElement?.clientWidth ?? 0) / 2;
+  return {
+    axis: "x",
+    lead: (track) => (grow === 1 ? centre() : track - centre()),
+    /*
+     * The widest the pane can actually show. Read fresh, per the ResizeTarget contract, because a
+     * dock drag or a window resize moves it under a drag that is already in flight. Before layout
+     * (happy-dom measures nothing) there is no honest ceiling, so the floor is the only bound.
+     */
+    max: () => {
+      const available = column.parentElement?.clientWidth ?? 0;
+      return available > 0
+        ? Math.max(EDIT_WIDTH_MIN, available - 2 * EDIT_CANVAS_GUTTER)
+        : Number.POSITIVE_INFINITY;
+    },
+    min: () => EDIT_WIDTH_MIN,
+    // The MEASURED width, not the stored one: a drag continues from what is on screen, which under
+    // A pane narrower than the request is not the number that was asked for.
+    read: () => rectOf(column).width || (tabOf() ? declaredWidthOfTab(tabOf()!) : EDIT_WIDTH_MIN),
+    reset: () => {
+      const tab = tabOf();
+      return tab ? declaredWidthOfTab(tab) : EDIT_WIDTH_MIN;
+    },
+    scale: () => 2 * grow,
+    settle: () => {
+      /* Nothing is PERSISTED — the width dies with the mode. What settles is the chrome: the
+         readout closes, and one `applyEditZoom` re-anchors the block action bar over the column's
+         final width. That call is withheld during the drag (see {@link applyEditWidth}), so this is
+         the one place per gesture the overlays are rebuilt. */
+      column.classList.remove("is-resizing");
+      applyEditZoom(surface);
+    },
+    snap: (value, modifiers) => {
+      const tab = tabOf();
+      if (modifiers.altKey || !tab) {
+        return value;
+      }
+      return snapEditWidth(value, snapTargetsOfTab(tab), EDIT_WIDTH_SNAP_TOLERANCE);
+    },
+    write: (value) => {
+      applyEditWidth(surface, column, value);
+    },
+  };
+}
+
+/**
+ * Handles already wired, each with the unbind {@link bindSplit} handed back, so a re-render cannot
+ * stack a second gesture on one element and a handle the stage has dropped does not keep
+ * listening.
+ *
+ * `canvas-render.ts` mounts the handles after every Edit pass, and the stage document reuses the
+ * nodes where it can — so a repeat mount of the same element must be a no-op. A mode round trip is
+ * the other case: the handles are drawn only while there is a column, so leaving Edit removes them
+ * and coming back draws two NEW ones. The old pair would otherwise stay bound — a window-resize
+ * listener each, and a row in the adapter's own registry that `syncSplits` walks on every dock move
+ * — so each mount first releases every handle no longer in the document. A `Map` rather than the
+ * `WeakSet` this used to be, because an unbind is a thing to hold, and the sweep is what bounds
+ * what it holds.
+ */
+const _wired = new Map<HTMLElement, () => void>();
+
+/** Release every wired handle the document no longer contains. */
+function sweepWired(): void {
+  for (const [wired, unbind] of _wired) {
+    if (!wired.isConnected) {
+      unbind();
+      _wired.delete(wired);
+    }
+  }
+}
+
+/**
+ * Drive one handle — a `jx-split` — from the column's width. Idempotent per element.
+ *
+ * **The column is passed rather than inferred**, and the two are still created and replaced
+ * together — a handle that outlived its column would be a handle with nothing to size. The handle
+ * is not inside the column at all: `surfaces/canvas-stage.json` draws each one in a `display:
+ * contents` slot BESIDE the column, in the canvas's own flex row, which is what makes the canvas
+ * the track the element measures. Naming both nodes is the honest shape — the caller already holds
+ * them — rather than walking from one to the other.
+ */
+export function mountEditWidthHandle(
+  surface: CanvasSurface,
+  handle: HTMLElement | undefined,
+  column: HTMLElement | undefined,
+  grow: 1 | -1,
+): void {
+  sweepWired();
+  if (!handle || !column || _wired.has(handle)) {
+    return;
+  }
+  _wired.set(handle, bindSplit(handle as SplitElement, editWidthTarget(surface, column, grow)));
+}

package/src/canvas/edit-width.ts

@@ -0,0 +1,150 @@
+/// <reference lib="dom" />
+/**
+ * Edit-width — the Edit canvas's dragged width, and the breakpoint that width implies.
+ *
+ * Edit draws ONE column, and until now that column could only be one of the widths a project
+ * declares: the Size switcher wrote `session.ui.activeMedia` and `canvas-render.ts` looked the
+ * matching `$media` entry's width up. Everything BETWEEN two declared widths — which is where a
+ * responsive layout actually breaks — was unreachable without editing `project.json`. A handle on
+ * either side of the column makes the width continuous, and this module is what those handles
+ * drag.
+ *
+ * **The width picks the breakpoint, not only the other way round.** Crossing a band writes
+ * `activeMedia`, so the Context bar, the Style tab's Target Line and therefore the block a style
+ * edit lands in all follow the width on screen. One axis, one field (`studio.md` §6.2) — a canvas
+ * at 700px that still claimed to be at Base would be a control over a label.
+ *
+ * **Nothing here is persisted, and that is the whole design.** The drag is an inspection gesture:
+ * the record dies with the mode (`canvas-render.ts` clears it on a mode transition) and is never
+ * written to `localStorage`. What DOES survive is the breakpoint it landed on, because
+ * `activeMedia` already persists (`workspace/session.ts`) — so a relaunch reopens the document at
+ * that breakpoint's declared width, which is a truthful summary of where you left off.
+ *
+ * **The store is a module-local `Map` keyed by pane**, the shape `_fits` and `_editZoomRafs` in
+ * `canvas-utils.ts` already use, rather than a field on `CanvasSurface`: the value is transient and
+ * its only readers are the render pass and the drag itself.
+ *
+ * **A record carries the media it was written beside, and that is how it self-invalidates.** The
+ * alternative was for `canvas.setBreakpoint` to call `clearEditWidth`, which would have made
+ * `canvas-utils.ts` import this module while this module imports `applyEditZoom` from it — a cycle,
+ * for a fact both sides can already see. Instead: the drag writes width and media together, so any
+ * OTHER writer of `activeMedia` (the Size popover, an artboard header) leaves the record
+ * disagreeing with the tab, and a disagreeing record is discarded. The axis stays single-writer per
+ * gesture without anyone having to be told.
+ *
+ * **This file is a LEAF, and stays one.** The command `canvas.setEditWidth` lives in
+ * `canvas-utils.ts` beside the other rendering-context verbs, and the drag in `edit-width-drag.ts`
+ * needs `applyEditZoom` from that same module — so a store that reached for either would close a
+ * cycle between them. It imports nothing but the media model, and both sides import it.
+ *
+ * @docs studio/design/breakpoints
+ */
+
+import { getEffectiveMedia } from "../site-context";
+import { mediaForWidth, parseMediaEntries } from "../utils/canvas-media";
+import type { CanvasSurface } from "./canvas-surface";
+import type { Tab } from "../tabs/tab";
+
+/**
+ * The narrowest the column may be dragged.
+ *
+ * Below roughly this a page is no longer a page — 240px is narrower than any device a project is
+ * likely to declare, so the floor never gets in the way of a real breakpoint, and it stops the
+ * column collapsing to a sliver the handles cannot be prised back apart from.
+ */
+export const EDIT_WIDTH_MIN = 240;
+
+/** How close a drag must come to a declared width before it is pulled onto it. */
+export const EDIT_WIDTH_SNAP_TOLERANCE = 8;
+
+/**
+ * The clearance `.content-edit-canvas` keeps on each side of the column.
+ *
+ * It is what stops the handles — which hang OUTSIDE the column's box — being clipped by that
+ * container's `overflow-x: hidden`, so it must stay at least as wide as a handle.
+ */
+export const EDIT_CANVAS_GUTTER = 16;
+
+/** One pane's dragged width, and the rendering context it was dragged in. */
+interface EditWidthRecord {
+  /** The tab it belongs to — a record does not survive the pane showing a different document. */
+  tabId: string;
+  /** `activeMedia` as the drag left it. A disagreement means someone else moved the axis. */
+  media: string | null;
+  width: number;
+}
+
+const _editWidths = new Map<string, EditWidthRecord>();
+
+/** The size breakpoints and base width a tab renders against, site context included. */
+function mediaEntriesOfTab(tab: Tab) {
+  return parseMediaEntries(
+    getEffectiveMedia(tab.doc.document?.$media as Record<string, string> | undefined),
+  );
+}
+
+/**
+ * The width the Size switcher alone would give this column — today's expression, unchanged.
+ *
+ * A stored breakpoint the document no longer declares falls back to the base width rather than
+ * sizing the column from a query that does not exist (`studio.md` §6.2).
+ */
+export function declaredWidthOfTab(tab: Tab): number {
+  const { baseWidth, sizeBreakpoints } = mediaEntriesOfTab(tab);
+  const media = tab.session.ui.activeMedia;
+  return sizeBreakpoints.find((bp) => bp.name === media)?.width ?? baseWidth;
+}
+
+/**
+ * This pane's dragged width, or `null` when it has none that still applies.
+ *
+ * Discards — rather than merely ignores — a record belonging to another tab or written beside
+ * another breakpoint, so a stale entry cannot come back to life when the pane returns to that tab.
+ */
+export function editWidthOfPane(paneId: string, tab: Tab | null): number | null {
+  const record = _editWidths.get(paneId);
+  if (!record) {
+    return null;
+  }
+  if (!tab || record.tabId !== tab.id || record.media !== tab.session.ui.activeMedia) {
+    _editWidths.delete(paneId);
+    return null;
+  }
+  return record.width;
+}
+
+/** The width the Edit column should render at: the dragged one, else the switcher's. */
+export function resolveEditColumnWidth(surface: CanvasSurface, tab: Tab | null): number {
+  const fallback = tab ? declaredWidthOfTab(tab) : 0;
+  return editWidthOfPane(surface.paneId, tab) ?? fallback;
+}
+
+/** Forget this pane's dragged width — the mode transition's "start at the breakpoint" rule. */
+export function clearEditWidth(paneId: string): void {
+  _editWidths.delete(paneId);
+}
+
+/** Drop every record. Tests only; there is no runtime caller. */
+export function resetEditWidths(): void {
+  _editWidths.clear();
+}
+
+/** The widths a drag is magnetic towards: every declared breakpoint, plus Base. */
+export function snapTargetsOfTab(tab: Tab): number[] {
+  const { baseWidth, sizeBreakpoints } = mediaEntriesOfTab(tab);
+  return [baseWidth, ...sizeBreakpoints.map((bp) => bp.width)];
+}
+
+/**
+ * Record a width against a pane, and answer the breakpoint it puts the canvas in.
+ *
+ * The media is stored ALONGSIDE the width because that is what lets the record invalidate itself
+ * (see the header): the two are written together here and nowhere else.
+ */
+export function setEditWidth(paneId: string, tab: Tab, width: number): string | null {
+  const { sizeBreakpoints } = mediaEntriesOfTab(tab);
+  const media = mediaForWidth(sizeBreakpoints, width);
+  tab.session.ui.activeMedia = media;
+  _editWidths.set(paneId, { media, tabId: tab.id, width });
+  return media;
+}