@jxsuite/studio 0.37.1 → 1.0.0

package/src/settings/contributed-section.ts

@@ -0,0 +1,406 @@
+/// <reference lib="dom" />
+/**
+ * Contributed settings section — the generic renderer behind `$studio.settings`
+ * (specs/extensions.md §9.1). An extension's `project` class declares a settings section and this
+ * module renders it over `projectConfig[key]`: layout "form" is one schema form over the whole
+ * section value; layout "map" is master-detail (key list left, entry form right) for `type: object`
+ * + `additionalProperties` sections. Persistence mirrors the content-types editor: mutate
+ * projectState.projectConfig and rewrite project.json through the platform.
+ */
+
+import { html, nothing, render as litRender } from "lit-html";
+import { getPlatform } from "../platform";
+import { projectState } from "../store";
+import { renderForm } from "../ui/schema-form";
+import { resolveContextPointer } from "../services/context-resolver";
+import { deriveSecretEnvName } from "../services/data-service";
+
+import type { TemplateResult } from "lit-html";
+import type { JsonSchema, SchemaFormContext } from "../ui/schema-form";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+// ─── Contribution shape ───────────────────────────────────────────────────────
+
+/** A `$studio.settings` contribution paired with the entry schema from the project fragment. */
+export interface SettingsContribution {
+  /** The project.json top-level property the section owns. */
+  key: string;
+  /** Section heading; falls back to the key. */
+  title?: string | undefined;
+  /** The `$studio.settings` block from the class descriptor. */
+  settings: {
+    layout?: "map" | "form" | undefined;
+    entry?:
+      | {
+          ui?: Record<string, { control?: string; enum?: unknown }> | undefined;
+          newEntry?: Record<string, unknown> | undefined;
+        }
+      | undefined;
+  };
+  /** JSON Schema for one entry (map layout) or the whole section value (form layout). */
+  entrySchema: JsonSchema;
+}
+
+/** Context handed to a host-provided section actions renderer. */
+export interface SectionActionsContext {
+  sectionKey: string;
+  /** The selected entry key (map layout), or null. */
+  selected: string | null;
+  rerender: () => void;
+}
+
+/** Host options threaded to the schema-form context. */
+export interface ContributedSectionOptions {
+  /** Registered formats backing the `$formats` virtual root. */
+  formats?: { name: string }[] | undefined;
+  /**
+   * Optional actions row rendered under the section title — the hook domain modules use to surface
+   * section-scoped operations (e.g. the data surface's Test/Push actions) without the generic
+   * renderer knowing any extension.
+   */
+  actions?: ((ctx: SectionActionsContext) => TemplateResult) | undefined;
+}
+
+// ─── Module state ─────────────────────────────────────────────────────────────
+
+/** Selected entry key per section (map layout). */
+const selectedEntries = new Map<string, string | null>();
+/** Sections whose new-entry form is open (map layout). */
+const newEntryOpen = new Set<string>();
+/** Pending new-entry names per section (map layout). */
+const newEntryNames = new Map<string, string>();
+
+/** Reset contributed-section ephemeral UI state (test hook). */
+export function resetContributedSectionState(): void {
+  selectedEntries.clear();
+  newEntryOpen.clear();
+  newEntryNames.clear();
+}
+
+// ─── Persistence ──────────────────────────────────────────────────────────────
+
+async function saveProjectConfig() {
+  const platform = getPlatform();
+  const config = (projectState as { projectConfig: ProjectConfig }).projectConfig;
+  await platform.writeFile("project.json", JSON.stringify(config, null, "\t"));
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Apply a schema-form patch onto a record in place; `undefined` values unset the key. */
+function applyPatch(target: Record<string, unknown>, patch: Record<string, unknown>) {
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) {
+      delete target[key];
+    } else {
+      target[key] = value;
+    }
+  }
+}
+
+/** Slugify a user-entered entry name — same rules as new content-type names. */
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replaceAll(/\s+/g, "-")
+    .replaceAll(/[^a-z0-9-]/g, "");
+}
+
+/** Instantiate a newEntry template, substituting `${key}` in every string value. */
+function instantiateNewEntry(
+  template: Record<string, unknown> | undefined,
+  key: string,
+): Record<string, unknown> {
+  if (!template) {
+    return {};
+  }
+  const substitute = (value: unknown): unknown => {
+    if (typeof value === "string") {
+      return value.replaceAll("${key}", key);
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => substitute(item));
+    }
+    if (value && typeof value === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value)) {
+        out[k] = substitute(v);
+      }
+      return out;
+    }
+    return value;
+  };
+  return substitute(template) as Record<string, unknown>;
+}
+
+/**
+ * Schema-form context resolving `#/$context/…` pointers over the live project config. When the
+ * platform has a secrets surface, `commitSecret` backs the "secret" control: the VALUE goes to
+ * platform.setSecrets under a derived env name; the returned NAME is what lands in project.json.
+ */
+function buildContext(
+  sectionKey: string,
+  opts: ContributedSectionOptions,
+  entryKey: string | null = null,
+): SchemaFormContext {
+  const platform = getPlatform();
+  return {
+    fieldKeyPrefix: `$settings.${sectionKey}`,
+    resolvePointer: (pointer, scope) =>
+      resolveContextPointer(pointer, {
+        projectConfig: (projectState?.projectConfig ?? {}) as Record<string, unknown>,
+        ...(scope !== undefined && { scope }),
+        ...(opts.formats !== undefined && { formats: opts.formats }),
+      }),
+    ...(typeof platform.setSecrets === "function"
+      ? {
+          commitSecret: async (key: string, value: string) => {
+            const envName = deriveSecretEnvName(sectionKey, entryKey, key);
+            await platform.setSecrets!({ set: { [envName]: value } });
+            return envName;
+          },
+        }
+      : {}),
+  };
+}
+
+/** The section's value object in the project config, created on demand. */
+function sectionValue(key: string): Record<string, unknown> | null {
+  const config = projectState?.projectConfig as Record<string, unknown> | null | undefined;
+  if (!config) {
+    return null;
+  }
+  const existing = config[key];
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+    return existing as Record<string, unknown>;
+  }
+  const fresh: Record<string, unknown> = {};
+  config[key] = fresh;
+  return fresh;
+}
+
+// ─── Render ───────────────────────────────────────────────────────────────────
+
+/**
+ * Render a contributed settings section into a settings-modal content container.
+ *
+ * @param {HTMLElement} container
+ * @param {SettingsContribution} contribution
+ * @param {ContributedSectionOptions} [opts]
+ */
+export function renderContributedSection(
+  container: HTMLElement,
+  contribution: SettingsContribution,
+  opts: ContributedSectionOptions = {},
+) {
+  const rerender = () => renderContributedSection(container, contribution, opts);
+  const title = contribution.title ?? contribution.key;
+  const layout = contribution.settings.layout ?? "form";
+
+  const body =
+    layout === "map"
+      ? renderMapLayout(contribution, opts, rerender)
+      : renderFormLayout(contribution, opts, rerender);
+
+  const selected = layout === "map" ? (selectedEntries.get(contribution.key) ?? null) : null;
+  const actions = opts.actions
+    ? opts.actions({ rerender, sectionKey: contribution.key, selected })
+    : nothing;
+
+  const tpl = html`
+    <div class="settings-section contributed-section">
+      <h3 class="settings-section-title">${title}</h3>
+      ${actions}${body}
+    </div>
+  `;
+
+  litRender(tpl, container);
+}
+
+/** Layout "form" — one schema form over the whole section value. */
+function renderFormLayout(
+  contribution: SettingsContribution,
+  opts: ContributedSectionOptions,
+  rerender: () => void,
+): TemplateResult {
+  const value = sectionValue(contribution.key) ?? {};
+  const ui = contribution.settings.entry?.ui;
+
+  return html`
+    <div class="settings-form-panel">
+      ${renderForm(contribution.entrySchema, value, {
+        context: buildContext(contribution.key, opts, null),
+        onChange: (patch) => {
+          const target = sectionValue(contribution.key);
+          if (!target) {
+            return;
+          }
+          applyPatch(target, patch);
+          rerender();
+          void saveProjectConfig();
+        },
+        rerender,
+        ...(ui !== undefined && { ui }),
+      })}
+    </div>
+  `;
+}
+
+/** Layout "map" — master-detail: entry key list left, entry form right. */
+function renderMapLayout(
+  contribution: SettingsContribution,
+  opts: ContributedSectionOptions,
+  rerender: () => void,
+): TemplateResult {
+  const { key: sectionKey } = contribution;
+  const entries = sectionValue(sectionKey) ?? {};
+  const entryKeys = Object.keys(entries);
+  const selected = selectedEntries.get(sectionKey) ?? null;
+  const ui = contribution.settings.entry?.ui;
+
+  const handleCreate = () => {
+    const slug = slugify(newEntryNames.get(sectionKey) ?? "");
+    const target = sectionValue(sectionKey);
+    if (!slug || !target || target[slug]) {
+      return;
+    }
+    target[slug] = instantiateNewEntry(contribution.settings.entry?.newEntry, slug);
+    selectedEntries.set(sectionKey, slug);
+    newEntryOpen.delete(sectionKey);
+    newEntryNames.delete(sectionKey);
+    rerender();
+    void saveProjectConfig();
+  };
+
+  const handleDelete = () => {
+    const target = sectionValue(sectionKey);
+    if (!selected || !target?.[selected]) {
+      return;
+    }
+    delete target[selected];
+    selectedEntries.set(sectionKey, null);
+    rerender();
+    void saveProjectConfig();
+  };
+
+  const handleRename = (newName: string) => {
+    const target = sectionValue(sectionKey);
+    const slug = slugify(newName);
+    if (!selected || !target || !slug || slug === selected || target[slug]) {
+      return;
+    }
+    // Rebuild the map to preserve entry order under the new key
+    const next: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(target)) {
+      next[k === selected ? slug : k] = v;
+      delete target[k];
+    }
+    Object.assign(target, next);
+    selectedEntries.set(sectionKey, slug);
+    rerender();
+    void saveProjectConfig();
+  };
+
+  // Left column — entry key list
+  const listTpl = html`
+    <div class="settings-list-panel">
+      ${entryKeys.map(
+        (name) => html`
+          <sp-action-button
+            size="s"
+            ?selected=${selected === name}
+            @click=${() => {
+              selectedEntries.set(sectionKey, name);
+              rerender();
+            }}
+          >
+            ${name}
+          </sp-action-button>
+        `,
+      )}
+      ${newEntryOpen.has(sectionKey)
+        ? html`
+            <div class="settings-inline-form">
+              <sp-textfield
+                size="s"
+                placeholder="entry-name"
+                .value=${newEntryNames.get(sectionKey) ?? ""}
+                @input=${(e: Event) => {
+                  newEntryNames.set(sectionKey, (e.target as HTMLInputElement).value);
+                }}
+                @keydown=${(e: KeyboardEvent) => {
+                  if (e.key === "Enter") {
+                    handleCreate();
+                  }
+                  if (e.key === "Escape") {
+                    newEntryOpen.delete(sectionKey);
+                    rerender();
+                  }
+                }}
+              ></sp-textfield>
+              <sp-action-button size="s" @click=${handleCreate}>Create</sp-action-button>
+            </div>
+          `
+        : html`
+            <sp-action-button
+              size="s"
+              quiet
+              @click=${() => {
+                newEntryOpen.add(sectionKey);
+                rerender();
+              }}
+            >
+              <sp-icon-add slot="icon"></sp-icon-add> New Entry
+            </sp-action-button>
+          `}
+    </div>
+  `;
+
+  // Right column — entry form
+  const selectedEntry = selected ? entries[selected] : undefined;
+  const editorTpl: TemplateResult =
+    selected && selectedEntry && typeof selectedEntry === "object"
+      ? html`
+          <div class="settings-editor-panel">
+            <div class="settings-editor-header">
+              <sp-textfield
+                size="s"
+                quiet
+                class="entry-name-input"
+                value=${selected}
+                @change=${(e: Event) => {
+                  const target = e.target as HTMLInputElement;
+                  handleRename(target.value.trim());
+                  target.value = selectedEntries.get(sectionKey) ?? selected;
+                }}
+                @keydown=${(e: KeyboardEvent) => {
+                  const target = e.target as HTMLInputElement;
+                  if (e.key === "Enter") {
+                    target.blur();
+                  }
+                  if (e.key === "Escape") {
+                    target.value = selected;
+                    target.blur();
+                  }
+                }}
+              ></sp-textfield>
+              <sp-action-button size="xs" quiet title="Delete entry" @click=${handleDelete}>
+                <sp-icon-delete slot="icon"></sp-icon-delete>
+              </sp-action-button>
+            </div>
+            ${renderForm(contribution.entrySchema, selectedEntry as Record<string, unknown>, {
+              context: buildContext(sectionKey, opts, selected),
+              onChange: (patch) => {
+                applyPatch(selectedEntry as Record<string, unknown>, patch);
+                rerender();
+                void saveProjectConfig();
+              },
+              rerender,
+              ...(ui !== undefined && { ui }),
+            })}
+          </div>
+        `
+      : html`<div class="settings-empty-state">Select or create an entry</div>`;
+
+  return html` <div class="settings-two-col">${listTpl} ${editorTpl}</div> `;
+}

package/src/settings/extension-sections.ts

@@ -0,0 +1,145 @@
+/// <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
+ * `$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
+ * path.
+ */
+
+import { getFormats, loadExtensions, loadFormats } from "../format/format-host";
+import { registerSettingsSection, unregisterSettingsSection } from "./settings-modal";
+import { renderContributedSection } from "./contributed-section";
+import { dataSectionActions } from "../panels/data-grid";
+import type { ExtensionContributionInfo } from "../types";
+import type { JsonSchema } from "../ui/schema-form";
+import type { SettingsContribution } from "./contributed-section";
+
+/** The `$studio.settings` block shape consumed here (nav metadata + the renderer inputs). */
+interface StudioSettingsBlock {
+  icon?: string;
+  label?: string;
+  order?: number;
+  layout?: "map" | "form";
+  entry?: SettingsContribution["settings"]["entry"];
+}
+
+/** A contribution resolved into settings-modal registration inputs. */
+export interface DerivedSettingsSection {
+  key: string;
+  label: string;
+  icon?: string | undefined;
+  order: number;
+  contribution: SettingsContribution;
+}
+
+/** Default sort position for contributed sections without an explicit `order`. */
+const DEFAULT_SECTION_ORDER = 100;
+
+/**
+ * Derive the settings-modal 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`.
+ *
+ * @param {ExtensionContributionInfo} info
+ * @returns {DerivedSettingsSection | null}
+ */
+export function deriveSettingsSection(
+  info: ExtensionContributionInfo,
+): DerivedSettingsSection | null {
+  const studio = info.studio as { settings?: StudioSettingsBlock } | null | undefined;
+  const settings = studio?.settings;
+  if (!settings) {
+    return null;
+  }
+  const { key } = info.project;
+  const layout = settings.layout ?? "form";
+  const sectionSchema = (info.entrySchema ?? {}) as JsonSchema & {
+    additionalProperties?: JsonSchema | boolean;
+  };
+  const entrySchema =
+    layout === "map"
+      ? typeof sectionSchema.additionalProperties === "object"
+        ? sectionSchema.additionalProperties
+        : {}
+      : (sectionSchema as JsonSchema);
+  const label = settings.label ?? info.project.title ?? key;
+  return {
+    contribution: {
+      entrySchema,
+      key,
+      settings: {
+        ...(settings.entry === undefined ? {} : { entry: settings.entry }),
+        ...(settings.layout === undefined ? {} : { layout: settings.layout }),
+      },
+      title: label,
+    },
+    icon: settings.icon,
+    key,
+    label,
+    order: settings.order ?? DEFAULT_SECTION_ORDER,
+  };
+}
+
+/** Section keys this module registered, so stale ones unregister on project/extension change. */
+const registeredKeys = new Set<string>();
+
+/**
+ * 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.
+ */
+export async function syncExtensionSettingsSections(): Promise<void> {
+  const [extensions] = await Promise.all([loadExtensions(), loadFormats()]);
+  const next = new Set<string>();
+  for (const ext of extensions) {
+    for (const info of ext.contributions) {
+      const derived = deriveSettingsSection(info);
+      if (!derived) {
+        continue;
+      }
+      const { contribution } = derived;
+      registerSettingsSection({
+        icon: derived.icon,
+        key: derived.key,
+        label: derived.label,
+        order: derived.order,
+        render: (container) => {
+          // Data-domain sections get the Test/Push/Data-grid actions slot when the platform
+          // Implements the protocol's data routes; every other section renders actions-free.
+          const actions = dataSectionActions(derived.key);
+          renderContributedSection(container, contribution, {
+            formats: getFormats(),
+            ...(actions === null ? {} : { actions }),
+          });
+        },
+      });
+      next.add(derived.key);
+    }
+  }
+  for (const key of registeredKeys) {
+    if (!next.has(key)) {
+      unregisterSettingsSection(key);
+    }
+  }
+  registeredKeys.clear();
+  for (const key of next) {
+    registeredKeys.add(key);
+  }
+}
+
+/** Unregister every section this module added and forget them (project close / tests). */
+export function resetExtensionSettingsSections(): void {
+  for (const key of registeredKeys) {
+    unregisterSettingsSection(key);
+  }
+  registeredKeys.clear();
+}
+
+/** The section keys currently registered by this module (diagnostics/tests). */
+export function extensionSectionKeys(): string[] {
+  return [...registeredKeys];
+}

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

@@ -87,7 +87,9 @@ export function fieldCardTpl(
   const isRef = type === "reference";
   const nestedProps = fieldSchema.properties || {};
   const nestedRequired = fieldSchema.required || [];
-  const refTarget = fieldSchema.$ref ? fieldSchema.$ref.replace("#/contentTypes/", "") : "";
+  // 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">
@@ -452,7 +454,7 @@ export function schemaForType(type: string, format?: string) {
       return { properties: {}, required: [], type: "object" };
     }
     case "reference": {
-      return { $ref: "#/contentTypes/" };
+      return { $ref: "#/content/" };
     }
     default: {
       return format ? { format, type: "string" } : { type: "string" };