@jxsuite/studio 2.0.0 → 2.1.0

package/src/settings/defs-editor.ts

@@ -1,23 +1,26 @@
 /// <reference lib="dom" />
 /**
- * Definitions Editor — visual editor for project-level $defs (JSON Schema type definitions).
+ * Definitions — the visual editor for project-level `$defs` (JSON Schema type definitions).
  *
  * Manages entries in project.json `$defs` — reusable type schemas for external datasets, API
- * responses, CMS payloads, etc. Same concept as component-level $defs but scoped to the entire
- * project.
+ * responses, CMS payloads, etc. Same concept as component-level `$defs` but scoped to the entire
+ * project. The on-disk key stays `$defs` and the section key stays `definitions`.
+ *
+ * **The reference field type is complete here for the first time.** `schema-field-ui.ts` has always
+ * been able to draw the target picker, and `ui/form-controls.ts` (the content-types builder) has
+ * always passed it the available content types — this editor never did, so choosing "reference"
+ * emitted a bare `#/content/` that pointed at nothing and offered no way to say what it pointed at.
+ * The list is read straight off the live config's `content` map, which is where a
+ * `#/content/<type>` pointer resolves.
  */
 
 import { html, render as litRender } from "lit-html";
-import { getPlatform } from "../platform";
 import { projectState } from "../store";
+import { commitProjectConfig } from "../tabs/project-config";
 import { addFieldFormTpl, detectFieldFormat, fieldCardTpl, schemaForType } from "./schema-field-ui";
 
 import type { FieldHandlers, SchemaProperty } from "./schema-field-ui.js";
-import type {
-  ContentTypeSchema,
-  ContentTypeSchemaField,
-  ProjectConfig,
-} from "@jxsuite/schema/types";
+import type { ContentTypeSchema, ContentTypeSchemaField } from "@jxsuite/schema/types";
 
 // ─── Module state ─────────────────────────────────────────────────────────────
 
@@ -29,10 +32,21 @@ let newDefName = "";
 
 // ─── Persistence ──────────────────────────────────────────────────────────────
 
-async function saveProjectConfig() {
-  const platform = getPlatform();
-  const config = (projectState as { projectConfig: ProjectConfig }).projectConfig;
-  await platform.writeFile("project.json", JSON.stringify(config, null, "\t"));
+/**
+ * Commit the configuration this editor has just mutated in place.
+ *
+ * Every handler below edits `projectState.projectConfig.$defs` directly and then says so here. The
+ * predecessor was this module's own writer — `JSON.stringify(config, null, "\t")` straight to
+ * `platform.writeFile`, called as `void saveProjectConfig()` at fourteen sites. It re-indented the
+ * whole file (every `project.json` on disk uses two spaces), it recorded nothing an undo could
+ * reach, and a rejected write became an unhandled rejection while the form went on showing a data
+ * shape that was never saved.
+ *
+ * `commitProjectConfig` transacts the mutation onto the configuration document and reports its own
+ * failures as Problems, so there is nothing left here to await or to swallow.
+ */
+function persist(): void {
+  void commitProjectConfig();
 }
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -43,6 +57,20 @@ function getSelectedDef(): ContentTypeSchema | undefined {
   return config?.$defs?.[selectedDef as string] as ContentTypeSchema | undefined;
 }
 
+/**
+ * The content types a `reference` field can point at — the same list the content-types builder
+ * resolves through `#/$context/content`, read here without a schema-form context to go through.
+ *
+ * @returns {string[]}
+ */
+function contentTypeNames(): string[] {
+  const content = (projectState?.projectConfig as Record<string, unknown> | null | undefined)
+    ?.content;
+  return content && typeof content === "object" && !Array.isArray(content)
+    ? Object.keys(content)
+    : [];
+}
+
 // ─── Handlers ─────────────────────────────────────────────────────────────────
 
 /** @param {() => void} rerender */
@@ -73,7 +101,7 @@ function handleNewDef(rerender: () => void) {
   showNewDef = false;
   newDefName = "";
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /** @param {() => void} rerender */
@@ -105,7 +133,7 @@ function handleAddField(rerender: () => void) {
   showAddField = false;
   newFieldState = { format: "", name: "", required: false, type: "string" };
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -124,7 +152,7 @@ function handleDeleteField(fieldName: string, rerender: () => void) {
   }
 
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -148,7 +176,7 @@ function handleToggleRequired(fieldName: string, rerender: () => void) {
   }
 
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -173,7 +201,7 @@ function handleRenameField(oldName: string, newName: string, rerender: () => voi
   }
 
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -193,7 +221,26 @@ function handleChangeType(fieldName: string, newType: string, rerender: () => vo
       : undefined;
   def.properties[fieldName] = schemaForType(newType, oldFormat || undefined);
   rerender();
-  void saveProjectConfig();
+  persist();
+}
+
+/**
+ * Point a reference field at a content type. The pointer form is `#/content/<type>` — the same one
+ * `ui/form-controls.ts` writes, so a reference authored here and one authored in the content-types
+ * builder are the same value.
+ *
+ * @param {string} fieldName
+ * @param {string} target
+ * @param {() => void} rerender
+ */
+function handleChangeRefTarget(fieldName: string, target: string, rerender: () => void) {
+  const def = getSelectedDef();
+  if (!def?.properties?.[fieldName]) {
+    return;
+  }
+  def.properties[fieldName] = { $ref: `#/content/${target}` } as ContentTypeSchemaField;
+  rerender();
+  persist();
 }
 
 /**
@@ -211,7 +258,7 @@ function handleChangeFormat(fieldName: string, format: string, rerender: () => v
   const type = prop.type || "string";
   def.properties[fieldName] = schemaForType(type, format || undefined);
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 // ─── Nested field handlers ───────────────────────────────────────────────────
@@ -247,7 +294,7 @@ function handleAddNestedField(
   }
 
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -268,7 +315,7 @@ function handleDeleteNested(parentName: string, childName: string, rerender: ()
   }
 
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -294,7 +341,7 @@ function handleToggleNestedRequired(parentName: string, childName: string, reren
   }
 
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -326,7 +373,7 @@ function handleRenameNested(
   }
 
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -353,7 +400,7 @@ function handleChangeNestedType(
       : undefined;
   parent.properties[childName] = schemaForType(newType, oldFormat || undefined);
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /**
@@ -378,7 +425,7 @@ function handleChangeNestedFormat(
   const type = prop.type || "string";
   parent.properties[childName] = schemaForType(type, format || undefined);
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 /** @param {() => void} rerender */
@@ -395,13 +442,13 @@ function handleDeleteDef(rerender: () => void) {
   selectedDef = null;
 
   rerender();
-  void saveProjectConfig();
+  persist();
 }
 
 // ─── Render ───────────────────────────────────────────────────────────────────
 
 /**
- * Render the definitions editor.
+ * Render the Data Shapes editor.
  *
  * @param {HTMLElement} container
  */
@@ -435,7 +482,7 @@ export function renderDefsEditor(container: HTMLElement) {
               <div class="settings-inline-form">
                 <sp-textfield
                   size="s"
-                  placeholder="TypeName"
+                  placeholder="ProductReview"
                   .value=${newDefName}
                   @input=${(e: Event) => {
                     newDefName = (e.target as HTMLInputElement).value;
@@ -464,7 +511,7 @@ export function renderDefsEditor(container: HTMLElement) {
                   rerender();
                 }}
               >
-                <sp-icon-add slot="icon"></sp-icon-add> New Definition
+                <sp-icon-add slot="icon"></sp-icon-add> New Data Shape
               </sp-action-button>
             `
       }
@@ -474,7 +521,9 @@ export function renderDefsEditor(container: HTMLElement) {
   // Right column — schema editor
   let editorTpl;
   if (!selectedDef || !defs[selectedDef]) {
-    editorTpl = html`<div class="settings-empty-state">Select or create a type definition</div>`;
+    editorTpl = html`<div class="settings-empty-state">
+      Pick a data shape on the left, or create one.
+    </div>`;
   } else {
     const def = defs[selectedDef] as ContentTypeSchema;
     const properties = def.properties || {};
@@ -488,6 +537,7 @@ export function renderDefsEditor(container: HTMLElement) {
         handleChangeNestedFormat(p, c, f, rerender),
       onChangeNestedType: (p: string, c: string, t: string) =>
         handleChangeNestedType(p, c, t, rerender),
+      onChangeRefTarget: (n: string, t: string) => handleChangeRefTarget(n, t, rerender),
       onChangeType: (n: string, t: string) => handleChangeType(n, t, rerender),
       onDelete: (n: string) => handleDeleteField(n, rerender),
       onDeleteNested: (p: string, c: string) => handleDeleteNested(p, c, rerender),
@@ -497,8 +547,9 @@ export function renderDefsEditor(container: HTMLElement) {
       onToggleRequired: (n: string) => handleToggleRequired(n, rerender),
     };
 
+    const targets = contentTypeNames();
     const fieldCards = Object.entries(properties).map(([name, fieldDef]) =>
-      fieldCardTpl(name, fieldDef as SchemaProperty, required.includes(name), handlers),
+      fieldCardTpl(name, fieldDef as SchemaProperty, required.includes(name), handlers, targets),
     );
 
     editorTpl = html`
@@ -508,7 +559,7 @@ export function renderDefsEditor(container: HTMLElement) {
           <sp-action-button
             size="xs"
             quiet
-            title="Delete definition"
+            title="Delete data shape"
             @click=${() => handleDeleteDef(rerender)}
           >
             <sp-icon-delete slot="icon"></sp-icon-delete>
@@ -551,7 +602,15 @@ export function renderDefsEditor(container: HTMLElement) {
     `;
   }
 
-  const tpl = html` <div class="settings-two-col">${listTpl} ${editorTpl}</div> `;
+  // Every section names itself in an <h3> matching its nav entry (Overview, Contexts, Head,
+  // Packages, Extensions, Deploy, Raw JSON). This one did not, so it was the only section whose
+  // Body never said what the reader had clicked.
+  const tpl = html`
+    <div class="settings-section">
+      <h3 class="settings-section-title">Data Shapes</h3>
+      <div class="settings-two-col">${listTpl} ${editorTpl}</div>
+    </div>
+  `;
 
   litRender(tpl, container);
 }

package/src/settings/dependencies-editor.ts

@@ -9,7 +9,7 @@
 import { html, render as litRender } from "lit-html";
 import { getPlatform } from "../platform";
 import { VERSION } from "../version";
-import { statusMessage } from "../panels/statusbar";
+import { notify } from "../services/notify";
 import { showProgressModal } from "../ui/progress-modal";
 import { isComparable, isUpgrade, stripRange } from "../packages/semver";
 import type { PackageInfo } from "../types";
@@ -83,14 +83,14 @@ async function onAdd() {
   await withBusy(async () => {
     await getPlatform().addPackage(name);
     _addName = "";
-    statusMessage(`Added ${name}`);
+    notify.success(`Added ${name}.`);
   });
 }
 
 async function onRemove(p: PackageInfo) {
   await withBusy(async () => {
     await getPlatform().removePackage(p.name);
-    statusMessage(`Removed ${p.name}`);
+    notify.success(`Removed ${p.name}.`);
   });
 }
 
@@ -107,7 +107,7 @@ async function onUpdate(p: PackageInfo, latest: string) {
     if (!res.ok) {
       throw new Error(res.log ?? "Update failed");
     }
-    statusMessage(`Updated ${p.name} to ${target}`);
+    notify.success(`Updated ${p.name} to ${target}.`);
   });
 }
 
@@ -132,7 +132,7 @@ async function onUpdateAll() {
     if (!res.ok) {
       throw new Error(res.log ?? "Update failed");
     }
-    statusMessage(`Updated ${updates.length} package(s)`);
+    notify.success(`Updated ${updates.length} package(s).`);
   });
 }
 
@@ -146,7 +146,7 @@ async function onReinstall() {
     if (!res.ok) {
       throw new Error(res.log ?? "Install failed");
     }
-    statusMessage("Dependencies reinstalled");
+    notify.success("Dependencies reinstalled.");
   });
 }
 
@@ -198,7 +198,7 @@ function render() {
 
   const tpl = html`
     <div class="settings-section">
-      <h3 class="settings-section-title">Dependencies</h3>
+      <h3 class="settings-section-title">Packages</h3>
       <p class="settings-field-desc">Manage this project's npm dependencies.</p>
 
       <div style="display:flex;gap:8px;margin-bottom:12px;align-items:center">

package/src/settings/extension-sections.ts

@@ -1,7 +1,7 @@
 /// <reference lib="dom" />
 /**
  * Extension settings sections — bridges the extensions payload (platform `listExtensions`) into the
- * settings-modal registry. Every project-section contribution whose class declares a
+ * Project Settings section registry. Every project-section contribution whose class declares a
  * `$studio.settings` block (specs/extensions.md §9.1) gets a section rendered generically by
  * renderContributedSection; sections vanish again when their extension is disabled. The studio
  * hard-codes nothing per extension — parser's Content Types section arrives through this exact
@@ -9,7 +9,7 @@
  */
 
 import { getFormats, loadExtensions, loadFormats } from "../format/format-host";
-import { registerSettingsSection, unregisterSettingsSection } from "./settings-modal";
+import { registerSettingsSection, unregisterSettingsSection } from "./section-registry";
 import { renderContributedSection } from "./contributed-section";
 import { dataSectionActions } from "../panels/data-grid";
 import type { ExtensionContributionInfo } from "../types";
@@ -25,7 +25,7 @@ interface StudioSettingsBlock {
   entry?: SettingsContribution["settings"]["entry"];
 }
 
-/** A contribution resolved into settings-modal registration inputs. */
+/** A contribution resolved into section-registry registration inputs. */
 export interface DerivedSettingsSection {
   key: string;
   label: string;
@@ -38,7 +38,7 @@ export interface DerivedSettingsSection {
 const DEFAULT_SECTION_ORDER = 100;
 
 /**
- * Derive the settings-modal registration for one contribution, or null when its class declares no
+ * Derive the section registration for one contribution, or null when its class declares no
  * `$studio.settings` block. The wire `entrySchema` is the SECTION value schema (`properties[<key>]`
  * of the project fragment); map layouts edit one entry at a time, so their form schema is that
  * section schema's `additionalProperties`.
@@ -86,13 +86,45 @@ export function deriveSettingsSection(
 /** Section keys this module registered, so stale ones unregister on project/extension change. */
 const registeredKeys = new Set<string>();
 
+/**
+ * The sync currently running, so concurrent callers join it instead of racing it.
+ *
+ * This is half of the deep-link fix (plan §12 P6.2). `refreshExtensionUi` (`format/format-host.ts`)
+ * fires this function **fire-and-forget** on project activation and after every `project.json`
+ * write, and the settings surface used to start a SECOND, interleaved run and await only its own.
+ * The two runs share {@link registeredKeys} and both reach {@link unregisterSettingsSection}, so a
+ * key one run had just registered could be seen as stale by the other and unregistered — after the
+ * awaited promise had already resolved. Coalescing makes "the sections are ready" one fact about
+ * the registry rather than one fact per caller.
+ */
+let _inFlight: Promise<void> | null = null;
+
+/**
+ * Await whatever contribution sync is in flight. Resolves immediately when none is.
+ *
+ * @returns {Promise<void>}
+ */
+export function extensionSectionsReady(): Promise<void> {
+  return _inFlight ?? Promise.resolve();
+}
+
 /**
  * Load the extensions payload and (re)register a settings section per `$studio.settings`
  * contribution, unregistering sections whose extension is no longer enabled. Formats load alongside
  * so the `$formats` context root has data at render time. Call on project activation and after
  * project.json `extensions` changes; loadExtensions caches, so repeat calls are cheap.
+ *
+ * Concurrent calls share one run — see {@link _inFlight}.
  */
-export async function syncExtensionSettingsSections(): Promise<void> {
+export function syncExtensionSettingsSections(): Promise<void> {
+  _inFlight ??= runSync().finally(() => {
+    _inFlight = null;
+  });
+  return _inFlight;
+}
+
+/** One pass over the extensions payload. Never called concurrently with itself. */
+async function runSync(): Promise<void> {
   const [extensions] = await Promise.all([loadExtensions(), loadFormats()]);
   const next = new Set<string>();
   for (const ext of extensions) {