@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/settings-defs.ts

@@ -0,0 +1,232 @@
+/// <reference lib="dom" />
+/**
+ * The Data Shapes surface: Project Settings › Data Shapes, as a Jx document over the kit.
+ *
+ * The adapter owns the MOUNT and the scope; `settings/defs-editor.ts` owns the decisions — what a
+ * shape is, what a field may be renamed to, and what reaches `project.json`. The split is the one
+ * `surfaces/settings-contexts.ts` draws: a reactive record of exactly what the document renders,
+ * and a handle whose `update` writes a fresh projection into it. Nothing repaints; the row whose
+ * type changed is the row that changes, and the field the reader is typing in keeps its caret.
+ *
+ * **Every list here is keyed by its name on disk, not by its position.** A rename is a key move and
+ * a delete is a key removal, so the row a reader is editing survives every other row changing
+ * around it — which is the whole of what the lit version's wholesale rebuild could not do.
+ *
+ * **Re-entrancy is the section's, not the host's.** A settings section is handed a container by
+ * `panels/settings-pane.ts`, which may hand it the SAME container again (a nav click, an extension
+ * registering, a command selecting an entry) and may in between give that container to a different
+ * section, whose `litRender` replaces everything in it. So the handle can say whether what it
+ * mounted is still there ({@link DefsSurfaceHandle.attached}), which is what lets the section
+ * re-use one mount for the ordinary case and rebuild only when it has actually been evicted.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import defsDoc from "./settings-defs.json";
+
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("settings-defs", defsDoc as unknown as JxDocument);
+
+/** One row of a picker: a field type, a format, or a reference target. */
+export interface DefsChoice {
+  value: string;
+  label: string;
+}
+
+/** One data shape in the left column. */
+export interface DefsShapeView {
+  name: string;
+  selected: boolean;
+}
+
+/**
+ * One child of an `object` field. It carries its parent, because a nested `$map` has no other way
+ * to name the field it is inside: `$map/item` is the child by the time the row is drawn.
+ */
+export interface NestedFieldView {
+  parent: string;
+  /** The property name on disk. The row's identity, and its `data-nested`. */
+  key: string;
+  /** What the name field holds, which is the key until the reader types something else. */
+  name: string;
+  type: string;
+  format: string;
+  /** Only `string` and `array` carry a format, so only they draw the picker. */
+  hasFormat: boolean;
+  required: boolean;
+}
+
+/** One field of the selected shape. */
+export interface DefsFieldView {
+  /** The property name on disk. The row's identity, and its `data-field`. */
+  key: string;
+  /** The name in words, as the row's caption. */
+  label: string;
+  name: string;
+  type: string;
+  format: string;
+  hasFormat: boolean;
+  required: boolean;
+  /**
+   * What the card draws under its row, as a `$switch` discriminant: a reference target, an object's
+   * children, or nothing. `"reference"` means BOTH that the field is one and that there is
+   * something to point at — a picker over an empty list is a control with no answers in it.
+   */
+  extra: "none" | "reference" | "nested";
+  /** The content type this reference points at, without its `#/content/` prefix. */
+  refTarget: string;
+  children: NestedFieldView[];
+  /** The nested add row's unsubmitted name, kept so an outside redraw does not take it away. */
+  draftName: string;
+  draftType: string;
+}
+
+/** Everything the document draws, as one value. */
+export interface DefsView {
+  shapes: DefsShapeView[];
+  /** Whether the left column is offering the new-shape button or the form. */
+  newState: "closed" | "open";
+  newName: string;
+  /** Whether the right column is editing a shape or saying that none is chosen. */
+  editorState: "empty" | "editing";
+  selected: string;
+  fields: DefsFieldView[];
+  typeOptions: DefsChoice[];
+  formatOptions: DefsChoice[];
+  /** The content types a reference field can point at. */
+  targets: DefsChoice[];
+  addState: "closed" | "open";
+  addName: string;
+  addType: string;
+  addFormat: string;
+  addRequired: boolean;
+  addHasFormat: boolean;
+}
+
+/** What the reader can do here. Every one of them is a write the section decides and makes. */
+export interface DefsActions {
+  select: (name: string) => void;
+  openNew: () => void;
+  editNew: (value: string) => void;
+  createNew: () => void;
+  cancelNew: () => void;
+  removeShape: () => void;
+  renameField: (key: string, value: string) => void;
+  setType: (key: string, value: string) => void;
+  setFormat: (key: string, value: string) => void;
+  setTarget: (key: string, value: string) => void;
+  setRequired: (key: string, required: boolean) => void;
+  removeField: (key: string) => void;
+  renameNested: (parent: string, key: string, value: string) => void;
+  setNestedType: (parent: string, key: string, value: string) => void;
+  setNestedFormat: (parent: string, key: string, value: string) => void;
+  setNestedRequired: (parent: string, key: string, required: boolean) => void;
+  removeNested: (parent: string, key: string) => void;
+  editDraftName: (parent: string, value: string) => void;
+  editDraftType: (parent: string, value: string) => void;
+  addNested: (parent: string) => void;
+  openAdd: () => void;
+  editAddName: (value: string) => void;
+  editAddType: (value: string) => void;
+  editAddFormat: (value: string) => void;
+  editAddRequired: (required: boolean) => void;
+  confirmAdd: () => void;
+  cancelAdd: () => void;
+}
+
+export interface DefsSurfaceHandle {
+  /** The container the document was mounted into. */
+  host: HTMLElement;
+  /** Resolves with the document's root once it has rendered. */
+  ready: Promise<HTMLElement>;
+  /** Whether what was mounted is still inside the host — see this module's header. */
+  attached: () => boolean;
+  update: (view: DefsView) => void;
+  dispose: () => void;
+}
+
+interface DefsScope extends Record<string, unknown>, DefsView, DefsActions {}
+
+/** The view a freshly mounted surface starts on: no shapes, and nothing chosen. */
+function emptyView(): DefsView {
+  return {
+    addFormat: "",
+    addHasFormat: true,
+    addName: "",
+    addRequired: false,
+    addState: "closed",
+    addType: "string",
+    editorState: "empty",
+    fields: [],
+    formatOptions: [],
+    newName: "",
+    newState: "closed",
+    selected: "",
+    shapes: [],
+    targets: [],
+    typeOptions: [],
+  };
+}
+
+/**
+ * Mount the Data Shapes document into `host`, wired to `actions`.
+ *
+ * @param {HTMLElement} host - The settings pane's section body
+ * @param {DefsActions} actions - What each control does
+ * @returns {DefsSurfaceHandle}
+ */
+export function mountDefsSurface(host: HTMLElement, actions: DefsActions): DefsSurfaceHandle {
+  host.textContent = "";
+  const scope = reactive<DefsScope>({ ...emptyView(), ...actions }) as DefsScope;
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("settings-defs", scope, host).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return surface.root as HTMLElement;
+    }
+    mounted = surface;
+    return surface.root as HTMLElement;
+  });
+
+  return {
+    attached: () => {
+      if (disposed) {
+        return false;
+      }
+      const root = mounted?.root;
+      /* A mount still in flight has nothing in the host yet, and answering "no" to that would make
+         a second synchronous render tear down the mount it is waiting for and start another. */
+      return root === undefined ? true : root instanceof HTMLElement && host.contains(root);
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    host,
+    ready,
+    update(view) {
+      scope.addFormat = view.addFormat;
+      scope.addHasFormat = view.addHasFormat;
+      scope.addName = view.addName;
+      scope.addRequired = view.addRequired;
+      scope.addState = view.addState;
+      scope.addType = view.addType;
+      scope.editorState = view.editorState;
+      scope.fields = view.fields;
+      scope.formatOptions = view.formatOptions;
+      scope.newName = view.newName;
+      scope.newState = view.newState;
+      scope.selected = view.selected;
+      scope.shapes = view.shapes;
+      scope.targets = view.targets;
+      scope.typeOptions = view.typeOptions;
+    },
+  };
+}

package/src/surfaces/settings-deploy.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioSettingsDeploy",
+  "$description": "Project Settings › Deploy: where the site ships, and what it is built with. One row over `build.adapter`, and the sentence a failed write leaves behind. The adapter (`surfaces/settings-deploy.ts`) hands in the chosen adapter, the enumeration it is chosen from and whatever the last write had to say; the document draws them and hands the change straight back. Nothing here reads `project.json` — a section that re-read the config while drawing would be a second opinion about a file one module already owns.",
+  "tagName": "section",
+  "attributes": {
+    "part": "deploy"
+  },
+  "style": {
+    "$description": "What is NOT in this block is most of the conversion. Four borrowed rules had nothing to transcribe: `.settings-field-label` and `.settings-field-desc` drew a row's label and the sentence under it, and `jx-field` draws both — with the label actually NAMING the control, which the bare `<label class=…>` beside the picker never did; `.settings-field` added a 20px bottom margin to separate one row from the next, and this section has one row, so the margin separated it from the end of the section; and `.settings-section` was never defined by any stylesheet at all, which is why it sits in `check-styles.ts`'s allow-list rather than in a rule.",
+    "display": "block",
+    "fontFamily": "var(--jx-font-sans)",
+    "color": "var(--fg)",
+    "& [part=\"title\"]": {
+      "margin": "0 0 16px",
+      "fontSize": "16px",
+      "fontWeight": "600",
+      "color": "var(--fg)"
+    },
+    "& [part=\"error\"]": {
+      "$description": "A write that failed, said under the section title rather than pinned to the picker: settings save on change, so a silent rejection would read as \"my edit just vanished\", and what failed was the whole file rather than the value. Its size read `--spectrum-font-size-75` with a 12px fallback, which resolved only inside `<sp-theme>` — a document is mounted in the settings pane, where that name is not in scope and the fallback is all it would ever have taken — so the size is the kit's scale and the colour is the studio layer's.",
+      "margin": "0 0 16px",
+      "fontSize": "var(--jx-text-md)",
+      "color": "var(--danger)"
+    },
+    "& [part=\"adapter\"]": {
+      "$description": "How wide the picker may grow. A control offering five short words does not want the width of a 900px pane, and 320px is the one thing `.settings-build-adapter` said that the kit does not — the same measure the two pickers in Locales take.",
+      "maxWidth": "320px"
+    }
+  },
+  "children": [
+    {
+      "tagName": "h3",
+      "attributes": {
+        "part": "title"
+      },
+      "textContent": "Deploy"
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "error-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/hasError"
+      },
+      "cases": {
+        "true": {
+          "tagName": "p",
+          "attributes": {
+            "part": "error",
+            "role": "alert"
+          },
+          "textContent": "${state.error}"
+        }
+      }
+    },
+    {
+      "tagName": "jx-field",
+      "attributes": {
+        "part": "row",
+        "data-field": "adapter"
+      },
+      "$props": {
+        "span": true,
+        "label": "Platform Adapter",
+        "description": "What the site is built for. Static writes plain files; the others emit a server entry for that runtime."
+      },
+      "children": [
+        {
+          "tagName": "jx-select",
+          "attributes": {
+            "part": "adapter"
+          },
+          "$props": {
+            "size": "sm",
+            "options": {
+              "$ref": "#/state/adapters"
+            },
+            "value": {
+              "$ref": "#/state/adapter"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setAdapter"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/settings-deploy.ts

@@ -0,0 +1,135 @@
+/// <reference lib="dom" />
+/**
+ * The Deploy surface: Project Settings' one row over `build.adapter`, as a Jx document.
+ *
+ * This is the adapter. `settings/project-sections.ts` keeps the section — what an adapter name
+ * means, what reaches `project.json` and what a failed write says — and hands this module a
+ * projection: the chosen adapter, the enumeration it is chosen from, and the ONE failure the
+ * section is currently showing. The document renders that.
+ *
+ * **A control the reader has moved is not the scope's**, and that is why `update` takes a patch
+ * rather than a whole projection. The section echoes what the picker now holds before it decides
+ * what to do with it, so that a rejected write is a real change to the scope and the runtime puts
+ * the old adapter back — `live()` did this for the lit template, and a binding that never moved
+ * would otherwise leave the picker claiming a platform the file does not name.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import deployDoc from "./settings-deploy.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("settings-deploy", deployDoc as unknown as JxDocument);
+
+/** One row of the adapter picker. */
+export interface DeployChoice {
+  value: string;
+  label: string;
+}
+
+/** What the section says the surface should be showing right now. */
+export interface DeployValues {
+  /** The adapter the project is built with. */
+  adapter: string;
+  /** Every adapter it may be. */
+  adapters: DeployChoice[];
+  /** What the last write failed with, or `""`. */
+  error: string;
+}
+
+/** What the reader can do here. The one thing they can, and it is a write the section decides. */
+export interface DeployActions {
+  setAdapter: (value: string) => void;
+}
+
+export interface DeploySurfaceHandle {
+  /** Bring the mounted document up to date. A key left out is left alone. */
+  update: (patch: Partial<DeployValues>) => void;
+  /** Whether the document this mounted is still standing in the container it was given. */
+  connected: () => boolean;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+/**
+ * The scope the document reads. `hasError` is derived here: `$switch` is a document's only
+ * conditional.
+ */
+interface DeployScope extends Record<string, unknown> {
+  adapter: string;
+  adapters: DeployChoice[];
+  error: string;
+  hasError: boolean;
+  setAdapter: (value: string) => void;
+}
+
+/** Write a patch into the scope. */
+function project(scope: DeployScope, patch: Partial<DeployValues>): void {
+  if (patch.adapter !== undefined) {
+    scope.adapter = patch.adapter;
+  }
+  if (patch.adapters !== undefined) {
+    scope.adapters = patch.adapters;
+  }
+  if (patch.error !== undefined) {
+    scope.error = patch.error;
+    scope.hasError = patch.error !== "";
+  }
+}
+
+/**
+ * Mount the Deploy document into `container`.
+ *
+ * The container is cleared first: a settings section is handed the pane's content area, and
+ * whatever the last section drew into it is not this one's to keep.
+ */
+export function mountDeploySurface(
+  container: HTMLElement,
+  values: DeployValues,
+  actions: DeployActions,
+): DeploySurfaceHandle {
+  const scope = reactive<DeployScope>({
+    adapter: "",
+    adapters: [],
+    error: "",
+    hasError: false,
+    setAdapter: actions.setAdapter,
+  }) as DeployScope;
+  project(scope, values);
+
+  container.replaceChildren();
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  /* Nothing is called on the element, so the mount is all this has to wait for: the DOCUMENT is
+     what this surface renders, and `jx-field` and `jx-select` settle their own templates one
+     `connectedCallback` later without anybody here asking them to (§1.1, "await the element"). */
+  void mountSurface("settings-deploy", scope, container).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    /* While the mount is still in flight this surface owns the container only for as long as the
+       container is still the empty one it was handed: a settings section is drawn into the pane's
+       content area, and if something else has claimed it in the meantime the document must not
+       land on top of that. Once mounted, the question is simply whether the root is still there —
+       a section that was switched away from had its root taken out from under it. */
+    connected: () =>
+      !disposed &&
+      (mounted === null
+        ? container.childNodes.length === 0
+        : (mounted.root as Node).parentNode === container),
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (patch) => project(scope, patch),
+  };
+}