@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/github-publish.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioGithubPublish",
+  "$description": "Create GitHub Repository: the three things the flow needs before it calls the API — the repository's name, an optional description, and whether it is private. A `jx-dialog`, so the platform owns modality, Escape, focus restoration and the backdrop, and the kit draws both answer buttons. Nothing here reaches GitHub: `github/github-publish.ts` keeps the token, the request and the activity, and this document only collects.",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": "Create GitHub Repository",
+    "confirmLabel": "Create Repository",
+    "cancelLabel": "Cancel",
+    "size": "sm"
+  },
+  "attributes": {
+    "part": "github-publish"
+  },
+  "onconfirm": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/confirm"
+        },
+        "value": []
+      }
+    ]
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/cancel"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "style": {
+    "$description": "What is NOT here is most of the conversion. `.github-publish-dialog` was a flex column with an 8px gap and `8px 0` of padding: the gap is the one thing it said that nothing else draws, and `jx-dialog`'s own body already pads the content, so only the gap survives. `.github-publish-dialog sp-textfield { width: 100% }` had nothing to transcribe either — a `jx-field` row is a grid whose control cell stretches, so the field fills the row without being told to. The three `sp-field-label`s are gone with them, because `jx-field` draws the label AND names the control from it; the third of them carried no `for` at all, so \"Visibility\" was text beside a switch rather than a name for it.",
+    "& [part=\"rows\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-3)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "rows"
+      },
+      "children": [
+        {
+          "tagName": "jx-field",
+          "$props": {
+            "span": true,
+            "label": "Repository name"
+          },
+          "attributes": {
+            "part": "row",
+            "data-field": "name"
+          },
+          "children": [
+            {
+              "tagName": "jx-textfield",
+              "$props": {
+                "placeholder": "my-project",
+                "value": {
+                  "$ref": "#/state/name"
+                }
+              },
+              "attributes": {
+                "part": "field"
+              },
+              "oninput": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/setName"
+                    },
+                    "value": [
+                      {
+                        "$ref": "event#/target/value"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "tagName": "jx-field",
+          "$props": {
+            "span": true,
+            "label": "Description (optional)"
+          },
+          "attributes": {
+            "part": "row",
+            "data-field": "description"
+          },
+          "children": [
+            {
+              "tagName": "jx-textfield",
+              "$props": {
+                "placeholder": "A brief description",
+                "value": {
+                  "$ref": "#/state/description"
+                }
+              },
+              "attributes": {
+                "part": "field"
+              },
+              "oninput": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/setDescription"
+                    },
+                    "value": [
+                      {
+                        "$ref": "event#/target/value"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "tagName": "jx-field",
+          "$props": {
+            "span": true,
+            "label": "Visibility"
+          },
+          "attributes": {
+            "part": "row",
+            "data-field": "visibility"
+          },
+          "children": [
+            {
+              "tagName": "div",
+              "$description": "The row opens with a plain `div`, and that is the whole reason it exists: `jx-field` names the first thing slotted into it that observes `labelledby`, so a switch slotted straight in would be announced \"Visibility\" over the top of the words printed beside it. A `div` observes no naming, so the switch keeps the name its own label gives it.",
+              "attributes": {
+                "part": "visibility-row"
+              },
+              "children": [
+                {
+                  "tagName": "jx-switch",
+                  "attributes": {
+                    "part": "toggle"
+                  },
+                  "$props": {
+                    "checked": {
+                      "$ref": "#/state/isPrivate"
+                    }
+                  },
+                  "onchange": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/setPrivate"
+                        },
+                        "value": [
+                          {
+                            "$ref": "event#/target/checked"
+                          }
+                        ]
+                      }
+                    ]
+                  },
+                  "children": [
+                    {
+                      "tagName": "span",
+                      "textContent": "Private repository"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/github-publish.ts

@@ -0,0 +1,169 @@
+/// <reference lib="dom" />
+/**
+ * The Create GitHub Repository surface: the name, description and visibility the flow needs before
+ * it can create anything, as a `jx-dialog` mounted into the dialog layer.
+ *
+ * This is the adapter. `github/github-publish.ts` keeps the flow — the token, the three requests,
+ * the activity and every failure they can raise — and this module owns nothing but what the reader
+ * has typed so far and the three answers the dialog can give. That split is the conversion: the
+ * template it replaced held its three controls in `ref()` callbacks and read `.value` off them at
+ * the moment confirm fired, which is a surface whose state exists only in the DOM. The scope holds
+ * it now, so the flow is handed a record rather than a snapshot of three elements.
+ *
+ * **Each setter writes what the control now holds, first.** Nothing here refuses a value today, but
+ * a binding only writes when the scope CHANGES: an adapter that decided a value without announcing
+ * the raw one first would leave the field showing text the scope does not have, silently (§9.3, "a
+ * controlled input is authoritative only while the scope value moves"). The echo is one line per
+ * setter and it is what makes a later refusal possible at all.
+ *
+ * @docs studio/interface
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { whenReady } from "./dialog";
+import githubPublishDoc from "./github-publish.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("github-publish", githubPublishDoc as unknown as JxDocument);
+
+/**
+ * What the dialog collects.
+ *
+ * It lives beside the dialog rather than beside the flow, because the dialog is what decides the
+ * shape: `github/github-publish.ts` re-exports the name it has always exported.
+ */
+export interface RepoOptions {
+  name: string;
+  description: string;
+  isPrivate: boolean;
+}
+
+export interface GithubPublishSurfaceOptions {
+  /** Where the dialog is mounted — the dialog layer. */
+  layer: HTMLElement;
+  /** What the name field starts with: the project's own name. */
+  name: string;
+  /** The reader answered. The flow decides what an empty name falls back to. */
+  onConfirm: (values: RepoOptions) => void;
+  /** The reader declined — the Cancel button, or Escape. */
+  onCancel: () => void;
+  /** The dialog closed, for any reason the platform owns as well as this module's `close`. */
+  onClosed: () => void;
+}
+
+export interface GithubPublishSurfaceHandle {
+  host: HTMLElement;
+  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
+  ready: Promise<HTMLElement>;
+  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
+  close: () => void;
+}
+
+interface GithubPublishScope extends Record<string, unknown> {
+  name: string;
+  description: string;
+  isPrivate: boolean;
+  setName: (value: string) => void;
+  setDescription: (value: string) => void;
+  setPrivate: (value: boolean) => void;
+  confirm: () => void;
+  cancel: () => void;
+  closed: () => void;
+}
+
+/** Open the dialog. The handle's `ready` resolves once it is showing. */
+export function openGithubPublishSurface(
+  options: GithubPublishSurfaceOptions,
+): GithubPublishSurfaceHandle {
+  const slot = document.createElement("div");
+  /* The layer is `pointer-events: none` so a click passes through it when nothing is up, and every
+     slot in it turns them back on for its own content. */
+  slot.style.pointerEvents = "auto";
+  slot.setAttribute(REGION_ATTR, overlayRegion("dialog", "github-publish"));
+  options.layer.append(slot);
+
+  let closed = false;
+  /**
+   * Say it is over, once.
+   *
+   * Two paths reach here and either may be first: the platform's own `close` event, and `close()`
+   * on a dialog that never got as far as being shown.
+   */
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.onClosed();
+  };
+
+  const scope = reactive<GithubPublishScope>({
+    cancel: () => {
+      options.onCancel();
+    },
+    closed: finish,
+    confirm: () => {
+      options.onConfirm({
+        description: scope.description,
+        isPrivate: scope.isPrivate,
+        name: scope.name,
+      });
+    },
+    description: "",
+    isPrivate: true,
+    name: options.name,
+    setDescription: (value) => {
+      scope.description = value;
+    },
+    setName: (value) => {
+      scope.name = value;
+    },
+    setPrivate: (value) => {
+      scope.isPrivate = value;
+    },
+  }) as GithubPublishScope;
+
+  let mounted: SurfaceHandle | null = null;
+  const ready = mountSurface("github-publish", scope, slot).then(async (surface) => {
+    mounted = surface;
+    const element = surface.root as HTMLElement;
+    if (closed) {
+      surface.dispose();
+      return element;
+    }
+    /* `whenReady` before `showModal`: the mount resolving means the DOCUMENT rendered, while the
+       element's own template is one `connectedCallback` later, and `showModal` in between finds no
+       `<dialog>` to open — the body is all there, correctly styled, and never shows. Shared with
+       `openDialogSurface` and `openAboutSurface` rather than reimplemented. */
+    await whenReady(element);
+    if (closed) {
+      return element;
+    }
+    showModal(element);
+    return element;
+  });
+
+  const handle: GithubPublishSurfaceHandle = {
+    close() {
+      if (closed) {
+        return;
+      }
+      const element = mounted?.root;
+      if (element instanceof HTMLElement) {
+        // The platform's close first, so focus goes back where it came from; then the document.
+        closeDialog(element);
+      }
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+      finish();
+    },
+    host: slot,
+    ready,
+  };
+  return handle;
+}

package/src/surfaces/grid-cell.json

@@ -0,0 +1,218 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioGridCell",
+  "$description": "The value picker for a grid cell that cannot be edited in place. An image and a relationship both pick from a list that is bigger than a cell, and their pickers render OUTSIDE it \u2014 which Tabulator's range module reads as an outside interaction and blur-cancels. So these two kinds skip the in-cell editor session entirely: a double click opens this panel, anchored on the cell, and every pick writes straight through the edit buffer. The media picker is an ISLAND (\u00a79.4): `[part=\"picker-host\"]` is drawn empty and `ui/media-picker.ts` mounts `media-field.json` into it. It stays an island now that it is a document too, because what goes in the box is the caller's decision rather than this panel's.",
+  "tagName": "jx-popover",
+  "attributes": {
+    "part": "cell-panel"
+  },
+  "$props": {
+    "label": "${state.title}",
+    "x": {
+      "$ref": "#/state/x"
+    },
+    "y": {
+      "$ref": "#/state/y"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "body"
+      },
+      "style": {
+        "display": "flex",
+        "flexDirection": "column",
+        "gap": "var(--jx-space-2)",
+        "padding": "var(--jx-space-3)",
+        "minWidth": "260px",
+        "fontFamily": "var(--jx-font-sans)",
+        "fontSize": "var(--jx-text-md)",
+        "color": "var(--fg)",
+        "& [part=\"title\"]": {
+          "fontWeight": "600",
+          "fontSize": "var(--jx-text-sm)",
+          "margin": "0"
+        },
+        "& [part=\"hint\"]": {
+          "margin": "0",
+          "color": "var(--fg-dim)",
+          "fontSize": "var(--jx-text-xs)"
+        },
+        "& [part=\"actions\"]": {
+          "display": "flex",
+          "justifyContent": "flex-end"
+        },
+        "& [part=\"picker-host\"]": {
+          "display": "block",
+          "minWidth": "0"
+        }
+      },
+      "children": [
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "title"
+          },
+          "textContent": "${state.title}"
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "kind-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/kind"
+          },
+          "cases": {
+            "reference": {
+              "tagName": "div",
+              "attributes": {
+                "part": "reference"
+              },
+              "style": {
+                "display": "flex",
+                "flexDirection": "column",
+                "gap": "var(--jx-space-2)"
+              },
+              "children": [
+                {
+                  "tagName": "div",
+                  "attributes": {
+                    "part": "hint-slot",
+                    "role": "none"
+                  },
+                  "style": {
+                    "display": "contents"
+                  },
+                  "$switch": {
+                    "$ref": "#/state/hintState"
+                  },
+                  "cases": {
+                    "shown": {
+                      "tagName": "p",
+                      "attributes": {
+                        "part": "hint"
+                      },
+                      "textContent": "${state.hint}"
+                    }
+                  }
+                },
+                {
+                  "tagName": "jx-select",
+                  "attributes": {
+                    "part": "entry"
+                  },
+                  "$props": {
+                    "size": "sm",
+                    "label": "${state.title}",
+                    "options": {
+                      "$ref": "#/state/options"
+                    },
+                    "value": {
+                      "$ref": "#/state/value"
+                    }
+                  },
+                  "onchange": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/pick"
+                        },
+                        "value": [
+                          {
+                            "$ref": "event#/target/value"
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                },
+                {
+                  "$description": "An id the target collection does not hold is still a legal reference \u2014 a draft entry, or one another repository owns \u2014 so the list is a shortcut rather than the whole of what may be written.",
+                  "tagName": "jx-textfield",
+                  "attributes": {
+                    "part": "custom"
+                  },
+                  "$props": {
+                    "size": "sm",
+                    "label": "Custom id",
+                    "placeholder": "Custom id\u2026",
+                    "value": {
+                      "$ref": "#/state/custom"
+                    }
+                  },
+                  "onchange": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/pick"
+                        },
+                        "value": [
+                          {
+                            "$ref": "event#/target/value"
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                }
+              ]
+            },
+            "image": {
+              "tagName": "div",
+              "attributes": {
+                "part": "picker-host"
+              }
+            }
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "actions"
+          },
+          "children": [
+            {
+              "tagName": "jx-button",
+              "attributes": {
+                "part": "done"
+              },
+              "$props": {
+                "variant": "secondary",
+                "size": "sm"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/done"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Done"
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}