@jxsuite/studio 4.1.0 → 5.0.0

package/src/settings/schema-field-ui.ts

@@ -1,11 +1,17 @@
-/// <reference lib="dom" />
 /**
- * Schema field UI — shared field-card and add-field-dialog templates for the content types and
- * definitions editors.
+ * Schema field semantics — what a studio field type IS, in JSON Schema terms, for every surface
+ * that edits one.
+ *
+ * There is no markup here any more, and that is the point. This module was the shared FIELD CARD
+ * for the content-types builder and the `$defs` editor, in lit over Spectrum; both draw the same
+ * card as a Jx document now (`surfaces/schema-builder.json` and `surfaces/settings-defs.json`, one
+ * vocabulary), and what neither of them could take with it is the dispatch below — which type a
+ * property has, which format it carries, and what a chosen type writes back. Three surfaces agree
+ * on that by importing it rather than by each reading `type`, `items.format` and `$ref` their own
+ * way; `grid/schema-columns.ts` says so at its own door.
  */
 
-import { html, nothing } from "lit-html";
-import { camelToLabel, isMediaFormat } from "../utils/studio-utils";
+import { isMediaFormat } from "../utils/studio-utils";
 
 export interface SchemaProperty {
   type?: string;
@@ -16,24 +22,6 @@ export interface SchemaProperty {
   $ref?: string;
 }
 
-export interface FieldHandlers {
-  onDelete: (name: string) => void;
-  onToggleRequired: (name: string) => void;
-  onRename: (oldName: string, newName: string) => void;
-  onChangeType: (name: string, newType: string) => void;
-  onChangeFormat?: (name: string, format: string) => void;
-  onChangeRefTarget?: (name: string, target: string) => void;
-  onAddNestedField?: (
-    parentName: string,
-    state: { name: string; type: string; required: boolean },
-  ) => void;
-  onDeleteNested?: (parentName: string, childName: string) => void;
-  onToggleNestedRequired?: (parentName: string, childName: string) => void;
-  onRenameNested?: (parentName: string, oldChild: string, newChild: string) => void;
-  onChangeNestedType?: (parentName: string, childName: string, newType: string) => void;
-  onChangeNestedFormat?: (parentName: string, childName: string, format: string) => void;
-}
-
 export const FIELD_TYPES = ["string", "number", "boolean", "array", "object", "reference"];
 
 export const FORMAT_OPTIONS = ["", "image", "date", "color"];
@@ -64,382 +52,6 @@ export function detectFieldFormat(schema: SchemaProperty) {
   return schema.format || "";
 }
 
-/**
- * Render a single schema field as an inline-editable form row.
- *
- * @param {string} fieldName
- * @param {SchemaProperty} fieldSchema — JSON Schema property definition
- * @param {boolean} isRequired
- * @param {FieldHandlers} handlers
- * @param {string[]} [contentTypeNames] - Available content type names for reference target picker
- * @returns {import("lit-html").TemplateResult}
- */
-export function fieldCardTpl(
-  fieldName: string,
-  fieldSchema: SchemaProperty,
-  isRequired: boolean,
-  handlers: FieldHandlers,
-  contentTypeNames: string[] = [],
-) {
-  const type = detectFieldType(fieldSchema);
-  const format = detectFieldFormat(fieldSchema);
-  const isNested = type === "object";
-  const isRef = type === "reference";
-  const nestedProps = fieldSchema.properties || {};
-  const nestedRequired = fieldSchema.required || [];
-  // Reference targets live under a referenceable project section (e.g. `#/content/<type>`); strip
-  // The section prefix generically so any section's targets round-trip.
-  const refTarget = fieldSchema.$ref ? fieldSchema.$ref.replace(/^#\/[^/]+\//, "") : "";
-
-  return html`
-    <div class="schema-field-card">
-      <div class="schema-field-row">
-        <sp-field-label size="s" class="schema-field-label"
-          >${camelToLabel(fieldName)}</sp-field-label
-        >
-        <sp-textfield
-          size="s"
-          quiet
-          value=${fieldName}
-          class="schema-field-name-input"
-          @change=${(e: Event) => {
-            const target = e.target as HTMLInputElement;
-            const newName = target.value.trim();
-            if (newName && newName !== fieldName) {
-              handlers.onRename(fieldName, newName);
-            } else {
-              target.value = fieldName;
-            }
-          }}
-          @keydown=${(e: KeyboardEvent) => {
-            const target = e.target as HTMLInputElement;
-            if (e.key === "Enter") {
-              target.blur();
-            }
-            if (e.key === "Escape") {
-              target.value = fieldName;
-              target.blur();
-            }
-          }}
-        ></sp-textfield>
-        ${typePickerTpl(type, (newType) => handlers.onChangeType(fieldName, newType))}
-        ${
-          type === "string" || type === "array"
-            ? formatPickerTpl(format, (f) => {
-                if (handlers.onChangeFormat) {
-                  handlers.onChangeFormat(fieldName, f);
-                }
-              })
-            : nothing
-        }
-        <sp-switch
-          size="s"
-          ?checked=${isRequired}
-          @change=${() => handlers.onToggleRequired(fieldName)}
-        >
-          Req
-        </sp-switch>
-        <sp-action-button
-          size="xs"
-          quiet
-          title="Delete field"
-          @click=${() => handlers.onDelete(fieldName)}
-        >
-          <sp-icon-delete slot="icon"></sp-icon-delete>
-        </sp-action-button>
-      </div>
-      ${
-        isRef && contentTypeNames.length > 0
-          ? html`
-              <div class="schema-field-ref-target">
-                <sp-picker
-                  size="s"
-                  label="Target"
-                  value=${refTarget}
-                  @change=${(e: Event) => {
-                    if (handlers.onChangeRefTarget) {
-                      handlers.onChangeRefTarget(fieldName, (e.target as HTMLInputElement).value);
-                    }
-                  }}
-                >
-                  ${contentTypeNames.map((n) => html`<sp-menu-item value=${n}>${n}</sp-menu-item>`)}
-                </sp-picker>
-              </div>
-            `
-          : nothing
-      }
-      ${
-        isNested
-          ? html`
-              <div class="schema-field-nested">
-                ${Object.entries(nestedProps).map(([name, sub]) =>
-                  nestedFieldCardTpl(
-                    fieldName,
-                    name,
-                    /** @type {SchemaProperty} */ sub,
-                    nestedRequired.includes(name),
-                    handlers,
-                  ),
-                )}
-                ${nestedAddFieldTpl(fieldName, handlers)}
-              </div>
-            `
-          : nothing
-      }
-    </div>
-  `;
-}
-
-/**
- * Render a nested (child) field card — same inline-editable pattern but delegates to nested
- * handlers.
- *
- * @param {string} parentName
- * @param {string} childName
- * @param {SchemaProperty} childSchema
- * @param {boolean} isRequired
- * @param {FieldHandlers} handlers
- * @returns {import("lit-html").TemplateResult}
- */
-function nestedFieldCardTpl(
-  parentName: string,
-  childName: string,
-  childSchema: SchemaProperty,
-  isRequired: boolean,
-  handlers: FieldHandlers,
-) {
-  const type = detectFieldType(childSchema);
-  const format = detectFieldFormat(childSchema);
-
-  return html`
-    <div class="schema-field-card schema-field-card--nested">
-      <div class="schema-field-row">
-        <sp-textfield
-          size="s"
-          quiet
-          value=${childName}
-          class="schema-field-name-input"
-          @change=${(e: Event) => {
-            const target = e.target as HTMLInputElement;
-            const newName = target.value.trim();
-            if (newName && newName !== childName && handlers.onRenameNested) {
-              handlers.onRenameNested(parentName, childName, newName);
-            } else {
-              target.value = childName;
-            }
-          }}
-          @keydown=${(e: KeyboardEvent) => {
-            const target = e.target as HTMLInputElement;
-            if (e.key === "Enter") {
-              target.blur();
-            }
-            if (e.key === "Escape") {
-              target.value = childName;
-              target.blur();
-            }
-          }}
-        ></sp-textfield>
-        ${typePickerTpl(type, (newType) => {
-          if (handlers.onChangeNestedType) {
-            handlers.onChangeNestedType(parentName, childName, newType);
-          }
-        })}
-        ${
-          type === "string" || type === "array"
-            ? formatPickerTpl(format, (f) => {
-                if (handlers.onChangeNestedFormat) {
-                  handlers.onChangeNestedFormat(parentName, childName, f);
-                }
-              })
-            : nothing
-        }
-        <sp-switch
-          size="s"
-          ?checked=${isRequired}
-          @change=${() => {
-            if (handlers.onToggleNestedRequired) {
-              handlers.onToggleNestedRequired(parentName, childName);
-            }
-          }}
-        >
-          Req
-        </sp-switch>
-        <sp-action-button
-          size="xs"
-          quiet
-          title="Delete field"
-          @click=${() => {
-            if (handlers.onDeleteNested) {
-              handlers.onDeleteNested(parentName, childName);
-            }
-          }}
-        >
-          <sp-icon-delete slot="icon"></sp-icon-delete>
-        </sp-action-button>
-      </div>
-    </div>
-  `;
-}
-
-/**
- * Render an inline "Add Field" row for nested objects.
- *
- * @param {string} parentName
- * @param {FieldHandlers} handlers
- * @returns {import("lit-html").TemplateResult}
- */
-function nestedAddFieldTpl(parentName: string, handlers: FieldHandlers) {
-  return html`
-    <div class="schema-nested-add">
-      <sp-textfield
-        size="s"
-        placeholder="field name"
-        class="schema-nested-add-name"
-        @keydown=${(e: KeyboardEvent) => {
-          if (e.key === "Enter") {
-            const target = e.target as HTMLInputElement;
-            const row = target.closest(".schema-nested-add");
-            const name = target.value.trim();
-            const typePicker = row?.querySelector("sp-picker") as HTMLInputElement | null;
-            const type = typePicker?.value || "string";
-            if (name && handlers.onAddNestedField) {
-              handlers.onAddNestedField(parentName, {
-                name,
-                required: false,
-                type,
-              });
-              target.value = "";
-            }
-          }
-        }}
-      ></sp-textfield>
-      ${typePickerTpl("string", () => {})}
-      <sp-action-button
-        size="xs"
-        quiet
-        title="Add nested field"
-        @click=${(e: Event) => {
-          const target = e.target as HTMLElement;
-          const row = target.closest(".schema-nested-add");
-          const nameInput = row?.querySelector(
-            ".schema-nested-add-name",
-          ) as HTMLInputElement | null;
-          const typePicker = row?.querySelector("sp-picker") as HTMLInputElement | null;
-          const name = nameInput?.value?.trim();
-          const type = typePicker?.value || "string";
-          if (name && handlers.onAddNestedField) {
-            handlers.onAddNestedField(parentName, {
-              name,
-              required: false,
-              type,
-            });
-            if (nameInput) {
-              nameInput.value = "";
-            }
-          }
-        }}
-      >
-        <sp-icon-add slot="icon"></sp-icon-add>
-      </sp-action-button>
-    </div>
-  `;
-}
-
-/**
- * Render the type picker as an sp-picker dropdown.
- *
- * @param {string} value
- * @param {(type: string) => void} onChange
- * @returns {import("lit-html").TemplateResult}
- */
-export function typePickerTpl(value: string, onChange: (type: string) => void) {
-  return html`
-    <sp-picker
-      size="s"
-      label="Type"
-      value=${value}
-      @change=${(e: Event) => onChange((e.target as HTMLInputElement).value)}
-    >
-      ${FIELD_TYPES.map((t) => html`<sp-menu-item value=${t}>${t}</sp-menu-item>`)}
-    </sp-picker>
-  `;
-}
-
-/**
- * Render the format picker as an sp-picker dropdown.
- *
- * @param {string} value
- * @param {(format: string) => void} onChange
- * @returns {import("lit-html").TemplateResult}
- */
-export function formatPickerTpl(value: string, onChange: (format: string) => void) {
-  return html`
-    <sp-picker
-      size="s"
-      label="Format"
-      value=${value}
-      @change=${(e: Event) => onChange((e.target as HTMLInputElement).value)}
-    >
-      ${FORMAT_OPTIONS.map((f) => html`<sp-menu-item value=${f}>${f || "(none)"}</sp-menu-item>`)}
-    </sp-picker>
-  `;
-}
-
-/**
- * Render the add-field form (inline, not a dialog).
- *
- * @param {{ name: string; type: string; format: string; required: boolean }} state
- * @param {{
- *   onInput: (field: string, value: string | boolean) => void;
- *   onConfirm: () => void;
- *   onCancel: () => void;
- * }} handlers
- * @returns {import("lit-html").TemplateResult}
- */
-export function addFieldFormTpl(
-  state: { name: string; type: string; format: string; required: boolean },
-  handlers: {
-    onInput: (field: string, value: string | boolean) => void;
-    onConfirm: () => void;
-    onCancel: () => void;
-  },
-) {
-  return html`
-    <div class="schema-add-field">
-      <sp-textfield
-        size="s"
-        placeholder="Field name"
-        .value=${state.name}
-        @input=${(e: Event) => handlers.onInput("name", (e.target as HTMLInputElement).value)}
-        @keydown=${(e: KeyboardEvent) => {
-          if (e.key === "Enter") {
-            handlers.onConfirm();
-          }
-          if (e.key === "Escape") {
-            handlers.onCancel();
-          }
-        }}
-      ></sp-textfield>
-      ${typePickerTpl(state.type, (t) => handlers.onInput("type", t))}
-      ${
-        state.type === "string" || state.type === "array"
-          ? formatPickerTpl(state.format || "", (f) => handlers.onInput("format", f))
-          : nothing
-      }
-      <sp-switch
-        size="s"
-        ?checked=${state.required}
-        @change=${(e: Event) =>
-          handlers.onInput("required", (e.target as HTMLInputElement).checked)}
-      >
-        Required
-      </sp-switch>
-      <sp-action-button size="s" @click=${handlers.onConfirm}>Add</sp-action-button>
-      <sp-action-button size="s" quiet @click=${handlers.onCancel}>Cancel</sp-action-button>
-    </div>
-  `;
-}
-
 /**
  * Build a JSON Schema property definition from a type and optional format.
  *

package/src/settings/section-registry.ts

@@ -25,7 +25,14 @@
 export interface SettingsSection {
   key: string;
   label: string;
-  /** Nav icon name (reserved for future nav treatments). */
+  /**
+   * Nav icon name (reserved for future nav treatments).
+   *
+   * A KEY into the kit's glyph manifest (`@jxsuite/ui/icons`), the same space `PanelRecord.icon`
+   * resolves in — never a tag. A key with no row is not a missing element, it is zero nodes
+   * (`studio.md` §13.5), so a wrong name here is silent in both directions: silent now because
+   * nothing draws it, and silent later because `jx-icon` falls back to nothing.
+   */
   icon?: string | undefined;
   /** Sort position — lower orders render higher in the inner nav. */
   order: number;

package/src/settings/settings-document.ts

@@ -31,6 +31,7 @@ import { optionalStringArg, stringProperty } from "../commands/command-args";
 import { notify } from "../services/notify";
 import { requireProjectState } from "../state";
 import { PROJECT_CONFIG_PATH } from "../tabs/tab";
+import { lendProjectConfigLayout } from "../tabs/project-config";
 import { activeTab, focusPane, openTab, workspace } from "../workspace/workspace";
 import {
   notifySettingsDocument,
@@ -43,11 +44,8 @@ import { renderContextsSection } from "./contexts-section";
 import { renderCssVarsEditor } from "./css-vars-editor";
 import { renderDefsEditor } from "./defs-editor";
 import { renderDependenciesEditor } from "./dependencies-editor";
-import {
-  renderDeploySection,
-  renderExtensionsSection,
-  renderRawJsonSection,
-} from "./project-sections";
+import { renderExtensionsSection } from "./extensions-section";
+import { renderDeploySection, renderRawJsonSection } from "./project-sections";
 import { renderGeneralSettings } from "./general-settings";
 import { renderHeadEditor } from "./head-editor";
 import { renderLocalesSection } from "./locales-section";
@@ -73,10 +71,18 @@ const SETTINGS_TAB_MODES = [SETTINGS_MODE, "stylebook", "source"];
 /* Orders leave gaps so a contribution can land between two built-ins. Content Types is NOT here —
    the parser extension contributes it (order 50) through its Content class descriptor's
    `$studio.settings` block, registered via ./extension-sections, which is the same path any
-   extension's section takes. */
+   extension's section takes.
+
+   `icon` is a KEY into the kit's glyph manifest (`@jxsuite/ui/icons`), not a tag — `studio.md`
+   §13.5 is about exactly this distinction, and a key with no row draws nothing and says nothing.
+   These were `sp-icon-*` names, which is the OTHER key space: they named Spectrum elements, so
+   every one of them resolved to nothing the moment the nav was ready to draw one. The field is
+   still documented as reserved (`section-registry.ts`), so nothing here draws today; the names are
+   held to the kit's manifest by `settings-document.test.ts` so that a name is right when the inner
+   nav does draw it, rather than discovered wrong then. */
 
 registerSettingsSection({
-  icon: "sp-icon-properties",
+  icon: "sliders-horizontal",
   key: "overview",
   label: "Overview",
   order: 10,
@@ -90,14 +96,14 @@ registerSettingsSection({
  * registry and moves into the document's inner nav without its renderer being touched.
  */
 registerSettingsSection({
-  icon: "sp-icon-device-desktop",
+  icon: "browser",
   key: "contexts",
   label: "Contexts",
   order: 15,
   render: renderContextsSection,
 });
 registerSettingsSection({
-  icon: "sp-icon-file-single-web-page",
+  icon: "file-code",
   key: "head",
   label: "Site head",
   order: 20,
@@ -111,7 +117,7 @@ registerSettingsSection({
  * is the form over it.
  */
 registerSettingsSection({
-  icon: "sp-icon-globe",
+  icon: "globe",
   key: "locales",
   label: "Locales",
   order: 25,
@@ -124,42 +130,42 @@ registerSettingsSection({
  * key by name.
  */
 registerSettingsSection({
-  icon: "sp-icon-brush",
+  icon: "paint-brush",
   key: "cssVars",
   label: "CSS Variables",
   order: 30,
   render: renderCssVarsEditor,
 });
 registerSettingsSection({
-  icon: "sp-icon-data",
+  icon: "brackets-curly",
   key: "definitions",
   label: "Data Shapes",
   order: 40,
   render: renderDefsEditor,
 });
 registerSettingsSection({
-  icon: "sp-icon-box",
+  icon: "cube",
   key: "dependencies",
   label: "Packages",
   order: 60,
   render: renderDependenciesEditor,
 });
 registerSettingsSection({
-  icon: "sp-icon-plug",
+  icon: "share-network",
   key: "extensions",
   label: "Extensions",
   order: 70,
   render: renderExtensionsSection,
 });
 registerSettingsSection({
-  icon: "sp-icon-publish-check",
+  icon: "upload-simple",
   key: "deploy",
   label: "Deploy",
   order: 80,
   render: renderDeploySection,
 });
 registerSettingsSection({
-  icon: "sp-icon-code",
+  icon: "code",
   key: "rawJson",
   label: "Raw JSON",
   order: 900,
@@ -224,6 +230,12 @@ export function showSettingsDocument(mode: string = SETTINGS_MODE): Tab | null {
      Editor control offers the modes in that order. */
   tab.session.ui.canvasMode = mode;
   tab.session.ui.preview = false;
+  /* The tab was opened over the configuration OBJECT — the platform parsed it, so there is no text
+     here to read a layout from, and `doc.layout` is null. A ⌘S on it would then write the
+     formatter's layout for fresh output while a settings commit on the same document wrote the
+     file's (`tabs/project-config.ts`, issue 308). The chokepoint reads the file once anyway; it
+     lends the tab that record, and the Code view re-renders when it lands (`doc` is reactive). */
+  void lendProjectConfigLayout(tab);
   return tab;
 }
 
@@ -350,13 +362,8 @@ export function settingsCommands(): AnyCommand[] {
          unchanged — `enabledWith` still refuses, so `registry.run` and the assistant's tool still
          throw `CommandUnavailableError` exactly as before. */
       enablement: (ctx) => ctx.project.open,
-      aiTool: {
-        description:
-          "Open the project's Settings, optionally on a named section (overview, contexts, head, " +
-          "locales, cssVars, definitions, dependencies, extensions, deploy, rawJson, or a section " +
-          "an extension contributes) and optionally at a named entry within it.",
-        name: "open_settings",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person; the model
+         writes `project.json` through `write_file` and the extension verbs. */
       run: async (_commandCtx, args) => {
         const section = optionalStringArg("settings.open", args, "section");
         const entry = optionalStringArg("settings.open", args, "entry");
@@ -415,12 +422,7 @@ export function settingsCommands(): AnyCommand[] {
       requires: "an open project",
       // §12.4: two verbs over ONE document declare ONE availability rule, byte-identical.
       enablement: (ctx) => ctx.project.open,
-      aiTool: {
-        description:
-          "Open the project's configuration document in its Project Styles editor — the design " +
-          "tokens and the default element styles that apply across every page.",
-        name: "open_project_styles",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person. */
       run: () => {
         showSettingsDocument(PROJECT_STYLES_VIEW);
       },