@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/settings-overview.json

@@ -0,0 +1,423 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioSettingsOverview",
+  "$description": "Project Settings › Overview: the project's identity. Its name, the description meta a search result reads, the production URL a sitemap is built from, its favicon, and the way through to Project Styles. Every row is a `jx-field` and every text control a `jx-textfield`, so the label, the sentence under it, the naming of the control and the announced refusal are all the kit's — this document draws the section's own rhythm and the favicon row, and nothing else. The adapter decides what is written and what is refused; nothing here reads `project.json`.",
+  "tagName": "div",
+  "attributes": {
+    "part": "overview"
+  },
+  "style": {
+    "$description": "What is NOT in this block is the conversion. Four stylesheet rules had no counterpart to write: `.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>` they styled never did; `.settings-field-error` drew a refused value's sentence, and `jx-textfield` draws that into a permanent live region under the field, so the first refusal is announced rather than only a later one; and `.settings-site-description`'s `min-height` sized a textarea the kit already gives three rows. What is left is what this section decides for itself.",
+    "display": "flex",
+    "flexDirection": "column",
+    "gap": "20px",
+    "fontFamily": "var(--jx-font-sans)",
+    "color": "var(--fg)",
+    "& [part=\"heading\"]": {
+      "margin": "0",
+      "fontSize": "16px",
+      "fontWeight": "600",
+      "color": "var(--fg)"
+    },
+    "& jx-textfield": {
+      "$description": "How wide a text control may grow. A name field spanning a 900px pane is a line the eye has to travel to read six characters; 420px is the measure `.settings-site-name`, `.settings-site-url` and `.settings-site-description` shared, and it is the one thing those three rules said that the kit does not.",
+      "width": "100%",
+      "maxWidth": "420px"
+    },
+    "& [part=\"favicon-row\"], & [part=\"styles-row\"]": {
+      "$description": "The two rows whose control is not a single field, and the reason each opens with a plain `div`: `jx-field` names the first thing slotted into it, and a button named by its row would be announced as \"Favicon\" or \"Global Styles\" instead of the verb it carries. A `div` observes no naming, so the row leaves it alone and the buttons keep the names they say on screen.",
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-4)"
+    },
+    "& [part=\"favicon\"], & [part=\"favicon-empty\"]": {
+      "$description": "One box, whether or not there is an icon in it, so the row does not resize the moment an upload lands.",
+      "width": "32px",
+      "height": "32px",
+      "boxSizing": "border-box",
+      "borderRadius": "var(--radius)"
+    },
+    "& [part=\"favicon\"]": {
+      "objectFit": "contain",
+      "border": "1px solid var(--border)",
+      "padding": "2px"
+    },
+    "& [part=\"favicon-empty\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "justifyContent": "center",
+      "border": "1px dashed var(--border)",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"favicon-path\"]": {
+      "$description": "Where the icon came from. It read `--spectrum-font-size-50` with an 11px fallback, which resolved only inside `<sp-theme>` — this document is mounted in the settings pane, where that name is not in scope and every one of these would have taken the fallback — so the size is the kit's scale and the colour is the studio layer's.",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)",
+      "wordBreak": "break-all"
+    },
+    "& [part=\"section-error\"], & [part=\"favicon-error\"]": {
+      "$description": "A failed write with no control of its own to sit under. Settings save on change, so a rejection nobody shows reads as \"my edit just vanished\"; the sentence stands, in the danger colour, until a later write succeeds.",
+      "margin": "0",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--danger)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "h3",
+      "attributes": {
+        "part": "title"
+      },
+      "textContent": "Overview"
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "section-error-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/hasSectionError"
+      },
+      "cases": {
+        "true": {
+          "tagName": "p",
+          "attributes": {
+            "part": "section-error",
+            "role": "alert"
+          },
+          "textContent": "${state.sectionError}"
+        }
+      }
+    },
+    {
+      "tagName": "jx-field",
+      "$props": {
+        "span": true,
+        "label": "Site Name",
+        "description": "What this site is called — used in page titles and the project list.",
+        "invalid": {
+          "$ref": "#/state/nameInvalid"
+        }
+      },
+      "attributes": {
+        "part": "row",
+        "data-field": "name"
+      },
+      "children": [
+        {
+          "tagName": "jx-textfield",
+          "$props": {
+            "size": "sm",
+            "placeholder": "My Site",
+            "value": {
+              "$ref": "#/state/nameValue"
+            },
+            "invalid": {
+              "$ref": "#/state/nameInvalid"
+            },
+            "error": {
+              "$ref": "#/state/nameError"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setName"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "jx-field",
+      "$props": {
+        "span": true,
+        "label": "Description",
+        "description": "One or two sentences about the site. Search engines and link previews show this.",
+        "invalid": {
+          "$ref": "#/state/descriptionInvalid"
+        }
+      },
+      "attributes": {
+        "part": "row",
+        "data-field": "description"
+      },
+      "children": [
+        {
+          "tagName": "jx-textfield",
+          "$props": {
+            "size": "sm",
+            "multiline": true,
+            "placeholder": "A short description of the site",
+            "value": {
+              "$ref": "#/state/descriptionValue"
+            },
+            "invalid": {
+              "$ref": "#/state/descriptionInvalid"
+            },
+            "error": {
+              "$ref": "#/state/descriptionError"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setDescription"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "jx-field",
+      "$props": {
+        "span": true,
+        "label": "Production URL",
+        "description": "Where the published site lives. Sitemaps and absolute links are built from it.",
+        "invalid": {
+          "$ref": "#/state/urlInvalid"
+        }
+      },
+      "attributes": {
+        "part": "row",
+        "data-field": "url"
+      },
+      "children": [
+        {
+          "tagName": "jx-textfield",
+          "$props": {
+            "size": "sm",
+            "type": "url",
+            "placeholder": "https://example.com",
+            "value": {
+              "$ref": "#/state/urlValue"
+            },
+            "invalid": {
+              "$ref": "#/state/urlInvalid"
+            },
+            "error": {
+              "$ref": "#/state/urlError"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setUrl"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "jx-field",
+      "$props": {
+        "span": true,
+        "label": "Favicon",
+        "description": "Upload an image to use as the site favicon."
+      },
+      "attributes": {
+        "part": "row",
+        "data-field": "favicon"
+      },
+      "children": [
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "favicon-row"
+          },
+          "children": [
+            {
+              "tagName": "div",
+              "attributes": {
+                "part": "favicon-slot",
+                "role": "none"
+              },
+              "style": {
+                "display": "contents"
+              },
+              "$switch": {
+                "$ref": "#/state/hasFavicon"
+              },
+              "cases": {
+                "true": {
+                  "tagName": "img",
+                  "attributes": {
+                    "part": "favicon",
+                    "src": "${state.favicon}",
+                    "alt": "Current favicon"
+                  }
+                },
+                "false": {
+                  "tagName": "div",
+                  "attributes": {
+                    "part": "favicon-empty",
+                    "aria-hidden": "true"
+                  },
+                  "textContent": "—"
+                }
+              }
+            },
+            {
+              "tagName": "jx-button",
+              "$props": {
+                "size": "sm"
+              },
+              "attributes": {
+                "part": "favicon-upload"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/uploadFavicon"
+                    }
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Upload Favicon"
+                }
+              ]
+            },
+            {
+              "tagName": "span",
+              "attributes": {
+                "part": "favicon-path-slot",
+                "role": "none"
+              },
+              "style": {
+                "display": "contents"
+              },
+              "$switch": {
+                "$ref": "#/state/hasFavicon"
+              },
+              "cases": {
+                "true": {
+                  "tagName": "span",
+                  "attributes": {
+                    "part": "favicon-path"
+                  },
+                  "textContent": "${state.favicon}"
+                }
+              }
+            }
+          ]
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "favicon-error-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/hasFaviconError"
+          },
+          "cases": {
+            "true": {
+              "tagName": "p",
+              "attributes": {
+                "part": "favicon-error",
+                "role": "alert"
+              },
+              "textContent": "${state.faviconError}"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "jx-field",
+      "$props": {
+        "span": true,
+        "label": "Global Styles",
+        "description": "Design tokens and the default element styles that apply across every page. Opens Project Styles over this same document."
+      },
+      "attributes": {
+        "part": "row",
+        "data-field": "styles"
+      },
+      "children": [
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "styles-row"
+          },
+          "children": [
+            {
+              "tagName": "jx-button",
+              "$props": {
+                "size": "sm",
+                "disabled": {
+                  "$ref": "#/state/stylesDisabled"
+                }
+              },
+              "attributes": {
+                "part": "styles-open",
+                "title": "${state.stylesTitle}"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/openStyles"
+                    }
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Edit Global Styles"
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/settings-overview.ts

@@ -0,0 +1,218 @@
+/// <reference lib="dom" />
+/**
+ * The Overview surface: Project Settings' identity section, as a Jx document over the kit.
+ *
+ * This is the adapter. `settings/general-settings.ts` keeps the section — what a value means, what
+ * is refused, what is written to `project.json` and what a failed write says — and hands this
+ * module a projection: five values, the styles command's title and whether it can be run, and the
+ * ONE failure the section is currently showing. The document renders that.
+ *
+ * The projection is flattened here rather than in the document because a document has no
+ * conditional beyond `$switch` over a value: "is there an error, and is it this control's" is two
+ * questions, so the adapter answers them and the surface reads booleans. That is the same division
+ * `surfaces/about.ts` draws — the state machine on this side, the markup on the other.
+ *
+ * **A control the reader has typed into is not the scope's**, and that is why `update` takes a
+ * patch rather than a whole projection. The section echoes what a control now holds before it
+ * decides what to do with it, so that a refused or normalised value is a real change to the scope
+ * and the runtime writes it back — `live()` did this for the lit template, and a binding that never
+ * moved would otherwise leave a rejected value sitting in the field.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import overviewDoc from "./settings-overview.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("settings-overview", overviewDoc as unknown as JxDocument);
+
+/** Which control a failure belongs under. `"section"` puts it at the top of the section. */
+export type OverviewErrorField = "name" | "description" | "url" | "favicon" | "section";
+
+/** The one failure the section is showing, and where it belongs. */
+export interface OverviewError {
+  field: OverviewErrorField;
+  message: string;
+}
+
+/** What the section says the surface should be showing right now. */
+export interface OverviewValues {
+  name: string;
+  description: string;
+  url: string;
+  /** The configured favicon path, or `""` for none. */
+  favicon: string;
+  /** The `styles.open` record's own title, which is the button's tooltip. */
+  stylesTitle: string;
+  stylesDisabled: boolean;
+  /** The last failure, or `null` when the last write succeeded. */
+  error: OverviewError | null;
+}
+
+/** What a control can ask the section to do. Every one of them is a decision the section owns. */
+export interface OverviewActions {
+  setName: (value: string) => void;
+  setDescription: (value: string) => void;
+  setUrl: (value: string) => void;
+  uploadFavicon: () => void;
+  openStyles: () => void;
+}
+
+export interface OverviewSurfaceHandle {
+  /** Bring the mounted document up to date. A key left out is left alone. */
+  update: (patch: Partial<OverviewValues>) => 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: one field per binding, because `$switch` is the only conditional a
+ * document has and `error.field === "name"` is not a value it can switch on.
+ */
+interface OverviewScope extends Record<string, unknown> {
+  nameValue: string;
+  nameError: string;
+  nameInvalid: boolean;
+  descriptionValue: string;
+  descriptionError: string;
+  descriptionInvalid: boolean;
+  urlValue: string;
+  urlError: string;
+  urlInvalid: boolean;
+  favicon: string;
+  hasFavicon: boolean;
+  faviconError: string;
+  hasFaviconError: boolean;
+  sectionError: string;
+  hasSectionError: boolean;
+  stylesTitle: string;
+  stylesDisabled: boolean;
+  setName: (value: string) => void;
+  setDescription: (value: string) => void;
+  setUrl: (value: string) => void;
+  uploadFavicon: () => void;
+  openStyles: () => void;
+}
+
+/** The failure's message when it belongs to `field`, and `""` when it belongs anywhere else. */
+function messageFor(error: OverviewError | null, field: OverviewErrorField): string {
+  return error?.field === field ? error.message : "";
+}
+
+/**
+ * Write a patch into the scope.
+ *
+ * `error` is spread over all five of its slots at once — a failure lands under exactly one control,
+ * so setting one of them without clearing the other four is how two rejections end up on screen
+ * together.
+ */
+function project(scope: OverviewScope, patch: Partial<OverviewValues>): void {
+  if (patch.name !== undefined) {
+    scope.nameValue = patch.name;
+  }
+  if (patch.description !== undefined) {
+    scope.descriptionValue = patch.description;
+  }
+  if (patch.url !== undefined) {
+    scope.urlValue = patch.url;
+  }
+  if (patch.favicon !== undefined) {
+    scope.favicon = patch.favicon;
+    scope.hasFavicon = patch.favicon !== "";
+  }
+  if (patch.stylesTitle !== undefined) {
+    scope.stylesTitle = patch.stylesTitle;
+  }
+  if (patch.stylesDisabled !== undefined) {
+    scope.stylesDisabled = patch.stylesDisabled;
+  }
+  if (patch.error !== undefined) {
+    const { error } = patch;
+    scope.nameError = messageFor(error, "name");
+    scope.nameInvalid = scope.nameError !== "";
+    scope.descriptionError = messageFor(error, "description");
+    scope.descriptionInvalid = scope.descriptionError !== "";
+    scope.urlError = messageFor(error, "url");
+    scope.urlInvalid = scope.urlError !== "";
+    scope.faviconError = messageFor(error, "favicon");
+    scope.hasFaviconError = scope.faviconError !== "";
+    scope.sectionError = messageFor(error, "section");
+    scope.hasSectionError = scope.sectionError !== "";
+  }
+}
+
+/**
+ * Mount the Overview 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 mountOverviewSurface(
+  container: HTMLElement,
+  values: OverviewValues,
+  actions: OverviewActions,
+): OverviewSurfaceHandle {
+  const scope = reactive<OverviewScope>({
+    descriptionError: "",
+    descriptionInvalid: false,
+    descriptionValue: "",
+    favicon: "",
+    faviconError: "",
+    hasFavicon: false,
+    hasFaviconError: false,
+    hasSectionError: false,
+    nameError: "",
+    nameInvalid: false,
+    nameValue: "",
+    openStyles: actions.openStyles,
+    sectionError: "",
+    setDescription: actions.setDescription,
+    setName: actions.setName,
+    setUrl: actions.setUrl,
+    stylesDisabled: false,
+    stylesTitle: "",
+    uploadFavicon: actions.uploadFavicon,
+    urlError: "",
+    urlInvalid: false,
+    urlValue: "",
+  }) as OverviewScope;
+  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 the kit elements inside it settle their own templates one
+     `connectedCallback` later without anybody here asking them to (§1.1, "await the element"). */
+  void mountSurface("settings-overview", 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),
+  };
+}