@jxsuite/studio 6.1.2 → 8.0.0

package/src/panels/component-preview.ts

@@ -9,28 +9,25 @@
 import { defineElement, setSkipServerFunctions } from "@jxsuite/runtime";
 import { projectState } from "../store";
 import type { ComponentEntry } from "../files/components";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 /**
  * Render a live component preview by registering its custom element and instantiating it.
  *
  * @param {ComponentEntry} comp
+ * @param {ReadonlyMap<string, JsonValue>} [props] - Sample props (`browse/component-examples.ts`),
+ *   set as properties before the instance connects, the way a parent's `$props` reach it (spec.md
+ *   §16.2)
  * @returns {Promise<HTMLElement>}
  */
-export async function renderComponentPreview(comp: ComponentEntry) {
+export async function renderComponentPreview(
+  comp: ComponentEntry,
+  props: ReadonlyMap<string, JsonValue> = new Map(),
+) {
   setSkipServerFunctions(true);
   try {
-    if (comp.source === "npm") {
-      if (!customElements.get(comp.tagName)) {
-        return _componentFallback(comp.tagName);
-      }
-    } else {
-      if (comp.path && !comp.path.endsWith(".json")) {
-        // Format-class component sources (e.g. markdown) can't be imported as modules
-        return _componentFallback(comp.tagName);
-      }
-      const root = projectState?.projectRoot;
-      const url = `${location.origin}/${root ? `${root}/` : ""}${comp.path}`;
-      await defineElement(url);
+    if (!(await defineComponent(comp))) {
+      return _componentFallback(comp.tagName);
     }
     const el = document.createElement(comp.tagName);
     for (const p of comp.props || []) {
@@ -39,6 +36,13 @@ export async function renderComponentPreview(comp: ComponentEntry) {
         el.setAttribute(p.name, val);
       }
     }
+    // Read at connection as the instance's own props, ahead of the attribute defaults above.
+    /* SAFETY: an element is an ordinary extensible object, so any string key can be written; the
+       instance reads each declared prop back off itself when it connects. */
+    const properties = el as HTMLElement & Record<string, JsonValue>;
+    for (const [name, value] of props) {
+      properties[name] = value;
+    }
     return el;
   } catch (error) {
     console.warn("Component preview failed:", comp.tagName, error);
@@ -46,6 +50,24 @@ export async function renderComponentPreview(comp: ComponentEntry) {
   }
 }
 
+/**
+ * Make sure a component's element is defined in this window, registering a project definition from
+ * its file. Answers whether the tag can now be instantiated: a package's element only when its
+ * package already defined it, and a format-class source (Markdown) never, since it cannot be
+ * imported as a module.
+ */
+export async function defineComponent(comp: ComponentEntry): Promise<boolean> {
+  if (comp.source === "npm") {
+    return Boolean(customElements.get(comp.tagName));
+  }
+  if (comp.path && !comp.path.endsWith(".json")) {
+    return false;
+  }
+  const root = projectState?.projectRoot;
+  await defineElement(`${location.origin}/${root ? `${root}/` : ""}${comp.path}`);
+  return true;
+}
+
 /** @param {string} tagName */
 function _componentFallback(tagName: string) {
   const fallback = document.createElement("div");

package/src/panels/data-explorer.ts

@@ -419,7 +419,7 @@ export function registerDataExplorerCommands(
  * **Both halves are documents now** — `surfaces/panel-signals.{json,ts}` for the entry list and its
  * editors, `surfaces/panel-data.{json,ts}` for the value tree under an open row. So lit draws
  * nothing at all here: `render` returns `nothing` and `afterRender` mounts against the painted DOM,
- * which is the seam `panels/git-panel.ts` uses for the same reason. The mount comes through `deps`
+ * which is the seam every document-bodied Navigator panel uses. The mount comes through `deps`
  * rather than an import — this module owns the expansion store that one reads, so importing it back
  * would close a cycle — and it is idempotent, so running on every repaint is what keeps the
  * projection current.

package/src/panels/data-grid.ts

@@ -23,6 +23,7 @@ import { mountDataActionsSurface } from "../surfaces/data-actions";
 import { mountPushPlanSurface } from "../surfaces/push-plan";
 import { dataSurfaceAvailable, pushSchema, testConnection } from "../services/data-service";
 import { openGridSourcePicker } from "../grid/grid-open";
+import { closeSettingsDialog } from "../settings/settings-dialog";
 import type { DataActionsSurfaceHandle, DataActionsView } from "../surfaces/data-actions";
 import type { DialogSurfaceHandle } from "../surfaces/dialog";
 import type { PushPlanSurfaceHandle, PushPlanView } from "../surfaces/push-plan";
@@ -277,6 +278,9 @@ function paintSectionActions(
     host,
     mountDataActionsSurface(host, projectActions(sectionKey, selected), {
       openGrid: () => {
+        /* The actions row is drawn in the settings dialog, and a grid opens as a TAB: left up, the
+           dialog would cover the very tab the reader asked for (§17.1). */
+        closeSettingsDialog();
         void openGridSourcePicker();
       },
       push: () => {

package/src/panels/dnd.ts

@@ -10,7 +10,7 @@ import {
   monitorForElements,
 } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
 import { combine } from "@atlaskit/pragmatic-drag-and-drop/combine";
-import { displayTagName, isNumber } from "@jxsuite/schema/guards";
+import { isNumber } from "@jxsuite/schema/guards";
 import { disableNativeDragPreview } from "@atlaskit/pragmatic-drag-and-drop/element/disable-native-drag-preview";
 import {
   attachInstruction,
@@ -26,13 +26,12 @@ import {
   parentElementPath,
   renderOnly,
 } from "../store";
-import { mutateInsertNode, mutateMoveNode, transact, transactDoc } from "../tabs/transact";
+import { mutateInsertNode, mutateMoveNode, transactDoc } from "../tabs/transact";
 import { primarySelection } from "../tabs/selection";
 import { activeTab } from "../workspace/workspace";
 import { view } from "../view";
 import { buildComponentInstance, componentRegistry } from "../files/components";
-import { enableElement } from "../files/elements";
-import type { ElementsEntry } from "../files/elements";
+import { mutateImportComponent } from "../editor/insert-component";
 import { renderComponentPreview } from "./component-preview";
 import { defaultDef, unsafeTags } from "./shared";
 import { elementAtPoint } from "../utils/geometry";
@@ -487,33 +486,21 @@ export function applyDropInstruction(
     /* SAFETY: every minter of a "block" payload — the Insert palette's element and component cards
        and the file drop (`file-drop-action.ts`) — sets `fragment` to the JxMutableNode it inserts. */
     const fragment = srcData.fragment as JxMutableNode;
+    /* Auto-import to `$elements` if the dropped block is a custom component, through the rule
+       every insertion door shares (`editor/insert-component.ts`, over the one `$elements` service):
+       this call site once had its own duplicate rule and matched a local component by
+       `ref.endsWith(basename)`, so dropping `./components/card.json` into a page that already
+       imported `./vendor/card.json` counted as already imported. The import is part of the same
+       transaction as the insert, so one ⌘Z takes back both. */
     if (slot) {
-      transactDoc(tab, (t) =>
-        mutateInsertNode(t, slot.parent, slot.index, structuredClone(fragment)),
-      );
-    }
-
-    /* Auto-import to `$elements` if the dropped block is a custom component.
-       Through the ONE service (`files/elements.ts`), which is the whole point of it: this call site
-       had its own duplicate rule and matched a local component by `ref.endsWith(basename)`, so
-       dropping `./components/card.json` into a page that already imported `./vendor/card.json`
-       counted as already imported and produced an element the page could not resolve. */
-    const tag = fragment.tagName;
-    if (displayTagName(tag).includes("-")) {
-      const comp = componentRegistry.find((c: ComponentEntry) => c.tagName === tag);
-      /* SAFETY: `$elements` holds module specifiers and `{ $ref }` imports; the document type and
-         files/elements.ts spell an inline entry as JxMutableNode and JxElement respectively, two
-         editor views of the same JSON object that enableElement only compares by `$ref`. */
-      const before = (tab.doc.document.$elements ?? []) as ElementsEntry[];
-      const after = comp ? enableElement(before, comp, tab.documentPath ?? null) : before;
-      // Only when the list actually GREW. A component the registry cannot name — an npm entry with
-      // No package, a local one with no path — returns the list unchanged, and writing that back
-      // Would put an empty `$elements: []` on a document that had none.
-      if (after.length !== before.length) {
-        transact(tab, (d: JxMutableNode) => {
-          d.$elements = after;
-        });
-      }
+      transactDoc(tab, (t) => {
+        mutateInsertNode(t, slot.parent, slot.index, structuredClone(fragment));
+        mutateImportComponent(t, fragment.tagName);
+        /* The inserted node is the selection, as every other insert leaves it (the slash menu, Enter,
+           paste): the Inspector is then on the thing just placed, which is where a dropped image's
+           missing alt text or a component's props are filled in. */
+        t.session.selection = [[...slot.parent, "children", slot.index]];
+      });
     }
   }
 }

package/src/panels/elements-panel.ts

@@ -23,6 +23,7 @@
 import { isString } from "@jxsuite/schema/guards";
 import { nothing } from "lit-html";
 import { buildComponentInstance, componentRegistry } from "../files/components";
+import { mutateImportComponent } from "../editor/insert-component";
 import { childList, getNodeAtPath } from "../store";
 import { getEffectiveElements } from "../site-context";
 import { mountElementsSurface } from "../surfaces/panel-elements";
@@ -164,7 +165,10 @@ function panelValues(source: NavigatorPanelDeps): ElementsValues {
   };
 }
 
-/** Insert a node as the last child of the selected element — what both kinds of card do. */
+/**
+ * Insert a node as the last child of the selected element — what both kinds of card do — and import
+ * it when it is a component, as a drag of the same card does (§5.7: insertion has one meaning).
+ */
 function insertAtSelection(def: JxMutableNode): void {
   const tab = activeTab.value;
   if (!tab) {
@@ -173,7 +177,10 @@ function insertAtSelection(def: JxMutableNode): void {
   const parentPath = primarySelection(tab.session.selection) ?? [];
   const parent = getNodeAtPath(tab.doc.document, parentPath);
   const index = childList(parent).length;
-  transactDoc(tab, (tr) => mutateInsertNode(tr, parentPath, index, structuredClone(def)));
+  transactDoc(tab, (tr) => {
+    mutateInsertNode(tr, parentPath, index, structuredClone(def));
+    mutateImportComponent(tr, def.tagName);
+  });
 }
 
 /**

package/src/panels/empty-state.ts

@@ -24,8 +24,8 @@
  * There is no `icon` here any more, and its absence is the point rather than an omission: it was
  * typed `TemplateResult` and every value passed to it was an `sp-icon-*`, which is a Spectrum
  * element smuggled through a shared vocabulary into surfaces that have no other Spectrum in them.
- * `panels/git-panel.ts` was the last caller and it is a document now, so the field went with it —
- * `surfaces/empty-state.json` draws a word, and a region that needs a glyph beside one is asking
+ * The Source Control panel was the last caller and it became a document, so the field went with it
+ * — `surfaces/empty-state.json` draws a word, and a region that needs a glyph beside one is asking
  * for a control the kit declares rather than for a hole in this type.
  */
 export interface EmptyStateAction {

package/src/panels/formula-workspace.ts

@@ -302,9 +302,8 @@ function selectionKey(editing: FormulaEditDef): string {
  *
  * The document reports a chip by its key and a button by nothing at all, so the objects behind them
  * — the tab, the target, the root node, the sub-node a commit replaces — live here, rewritten by
- * every projection. Held rather than recomputed at click time for the reason `panels/git-panel.ts`
- * states about its own seat: a callback captured at mount would reach the FIRST projection's
- * document for the rest of the window.
+ * every projection. Held rather than recomputed at click time because a callback captured at mount
+ * would reach the FIRST projection's document for the rest of the window.
  */
 interface Resolved {
   tab: Tab;

package/src/panels/frontmatter-fields.ts

@@ -9,12 +9,12 @@
  *
  * {@link projectFmField} is the half that says WHAT ONE OF THEM LOOKS LIKE — which control it draws,
  * what that control currently holds, and how to read the control's answer back into a frontmatter
- * value. It is a projection rather than a renderer, and that is the whole of why it lives here:
- * both surfaces that edit frontmatter are Jx documents now (the Document Header card,
- * `src/surfaces/doc-header.json`, and the Navigator's Page panel, `src/surfaces/panel-page.json`),
- * and a document draws its own markup. What they must not each decide is that a `$ref` field is a
- * picker, that `"uri-reference"` is a media format, or that an array is a comma-separated line — so
- * they do not: they ask here and draw the answer.
+ * value. It is a projection rather than a renderer, and that is the whole of why it lives here: the
+ * surface that edits frontmatter is a Jx document (the Inspector's Page tab,
+ * `src/surfaces/panel-page.json`), and a document draws its own markup. What it must not decide for
+ * itself is that a `$ref` field is a picker, that `"uri-reference"` is a media format, or that an
+ * array is a comma-separated line — so it does not: it asks here and draws the answer. (The
+ * Document Header card that once drew the same rows above the canvas is gone, studio.md §4.2.)
  *
  * It replaces `renderFmField`, which was a lit template and could therefore only ever have ONE of
  * the two hosts. The Page panel was the last one, and the renderer went with it.
@@ -66,13 +66,13 @@ export interface FmFieldSet {
  *
  * @param {Tab} tab
  * @param {ProjectConfig | null | undefined} projectConfig
- * @param {Set<string>} reserved — keys managed by dedicated controls elsewhere
+ * @param {ReadonlySet<string>} reserved — keys managed by dedicated controls elsewhere
  * @returns {FmFieldSet}
  */
 export function collectFmFields(
   tab: Tab,
   projectConfig: ProjectConfig | null | undefined,
-  reserved: Set<string>,
+  reserved: ReadonlySet<string>,
 ): FmFieldSet {
   /* SAFETY: `FormatFrontmatter` holds `JxDocumentValue`, which is the JSON value space seen through
      the typed interfaces a document's declared keys use (JxRef, JxStatement, CemEvent, ...). Every
@@ -299,7 +299,7 @@ export function projectFmField(
     return {
       parse: (raw) => {
         /* NaN is deleted rather than written. The two surfaces this replaced disagreed here: the
-           Page panel's `spNumberField` refused a non-number and the Document Header card wrote
+           Page panel's `spNumberField` refused a non-number and the old Document Header card wrote
            `NaN` into the frontmatter, where it round-trips to `null`. One answer, and it is the
            one that cannot corrupt the document. */
         const trimmed = String(raw).trim();

package/src/panels/git-diff-open.ts

@@ -130,10 +130,14 @@ export function openDiffTab(path: string): Tab {
  * leave the comparison for Design without reopening anything; a file it cannot gets the stub tab
  * above. Both are keyed by the path, so §14.1 holds either way — one path, one tab.
  *
- * `files/files.ts` is imported dynamically because it imports `cleanupGitPanel` from
- * `panels/git-panel.ts`, which imports this module: a static edge back would close that cycle.
- * `openFileInTab` answers `void` whether it opens a new tab or reveals one that was already open,
- * so the tab is resolved from the workspace by its path.
+ * The document tab opens IN `git-diff`, and an already-open one is moved into it before it is
+ * revealed: a comparison belongs to Publish (studio.md §22.1), and a tab activated in its edit mode
+ * would enter Design, frame and all, for the moment before the mode followed.
+ *
+ * `files/files.ts` is imported dynamically because it imports `cleanupSourceControl` from
+ * `publish/source-control.ts`, which imports this module: a static edge back would close that
+ * cycle. `openFileInTab` answers `void` whether it opens a new tab or reveals one that was already
+ * open, so the tab is resolved from the workspace by its path.
  *
  * Answers null when the file could not be opened at all, which the caller states rather than
  * silently leaving the stage on someone else's document.
@@ -143,6 +147,6 @@ export async function openComparisonTab(path: string): Promise<Tab | null> {
     return openDiffTab(path);
   }
   const files = await import("../files/files");
-  await files.openFileInTab(path, {});
+  await files.openFileInTab(path, { canvasMode: "git-diff" });
   return [...workspace.tabs.values()].find((tab) => tab.documentPath === path) ?? null;
 }