@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/about.ts

@@ -0,0 +1,163 @@
+/// <reference lib="dom" />
+/**
+ * The About surface: the app's version, its links, and the `@jxsuite/*` versions it resolved.
+ *
+ * The adapter owns the state machine — what is loaded, what failed — and the document renders it.
+ * That is the whole shape of the conversion this replaced: `about-modal.ts` held module-level
+ * `_packages` and `_appInfo` and re-rendered the entire template whenever either landed. They are a
+ * reactive record now, so the list appears when it arrives and nothing else is touched.
+ *
+ * The platform is asked for both, and NEITHER is required. `listPackages` failing means the app
+ * still knows its own version, and `getAppInfo` is optional in the interface — only the desktop
+ * implements it — so a missing method is an absent row rather than a caught error.
+ *
+ * @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 aboutDoc from "./about.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("about", aboutDoc as unknown as JxDocument);
+
+/** One row of the metadata list: a label and the value beside it. */
+export interface AboutRow {
+  label: string;
+  value: string;
+}
+
+/** One external link in the dialog's link row. */
+export interface AboutLink {
+  href: string;
+  label: string;
+}
+
+export interface AboutSurfaceOptions {
+  /** Where the dialog is mounted — the dialog layer. */
+  layer: HTMLElement;
+  headline: string;
+  rows: AboutRow[];
+  links: AboutLink[];
+  /** The dialog closed, for any reason the platform owns as well as the Close button. */
+  onClosed: () => void;
+}
+
+/** What the flow may change once the dialog is up: the package list, when it arrives. */
+export interface AboutSurfacePatch {
+  rows?: AboutRow[];
+  packages?: { name: string; version: string }[];
+}
+
+export interface AboutSurfaceHandle {
+  host: HTMLElement;
+  ready: Promise<HTMLElement>;
+  update: (patch: AboutSurfacePatch) => void;
+  close: () => void;
+}
+
+interface AboutScope extends Record<string, unknown> {
+  headline: string;
+  rows: AboutRow[];
+  links: AboutLink[];
+  packages: { name: string; version: string }[];
+  /**
+   * Which of the three package states to draw, as a `$switch` discriminant.
+   *
+   * Three, not a boolean: "still loading" and "the platform reported none" are different things to
+   * say, and a list that renders empty for both tells a reader the app has no packages when it may
+   * simply not have asked yet.
+   */
+  packagesState: "loading" | "empty" | "listed";
+  close: () => void;
+  closed: () => void;
+}
+
+/** Open the About dialog. The handle's `ready` resolves once it is showing. */
+export function openAboutSurface(options: AboutSurfaceOptions): AboutSurfaceHandle {
+  const slot = document.createElement("div");
+  // The layer is `pointer-events: none` so a click passes through it when nothing is up.
+  slot.style.pointerEvents = "auto";
+  slot.setAttribute(REGION_ATTR, overlayRegion("dialog", "about"));
+  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. Without one guard a caller that opens, closes
+   * and reopens gets its `onClosed` after the SECOND open — clearing a handle that is now live.
+   */
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.onClosed();
+  };
+  const scope = reactive<AboutScope>({
+    close: () => handle.close(),
+    closed: finish,
+    headline: options.headline,
+    links: options.links,
+    packages: [],
+    packagesState: "loading",
+    rows: options.rows,
+  }) as AboutScope;
+
+  let mounted: SurfaceHandle | null = null;
+  const ready = mountSurface("about", scope, slot).then(async (surface) => {
+    mounted = surface;
+    const element = surface.root as HTMLElement;
+    if (closed) {
+      surface.dispose();
+      return element;
+    }
+    /* `whenReady` before `showModal`, and it is not belt and braces. The mount resolving means the
+       DOCUMENT rendered — the element exists and carries this surface's children — while the
+       element's OWN template is one `connectedCallback` later. Calling `showModal` in between finds
+       no `<dialog>` to open: the body is all there, correctly styled, and never shows. Shared with
+       `openDialogSurface` rather than reimplemented, because both surfaces are `jx-dialog`s and
+       there is one answer to when one of those is ready. */
+    await whenReady(element);
+    if (closed) {
+      return element;
+    }
+    showModal(element);
+    return element;
+  });
+
+  const handle: AboutSurfaceHandle = {
+    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,
+    update(patch) {
+      if (patch.rows !== undefined) {
+        scope.rows = patch.rows;
+      }
+      if (patch.packages !== undefined) {
+        scope.packages = patch.packages;
+        scope.packagesState = patch.packages.length === 0 ? "empty" : "listed";
+      }
+    },
+  };
+  return handle;
+}

package/src/surfaces/add-repo.json

@@ -0,0 +1,486 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioAddRepo",
+  "$description": "The repository picker: every repo the platform's account link can reach, filtered by name, and one of them adopted as a Jx project. Two flows share it — Add existing repository, and Open Project on a platform whose projects ARE repositories — so the headline is state rather than text. A `jx-dialog`, so the platform owns modality, Escape, focus restoration and the backdrop, which is what retired the `sp-underlay` this surface used to paint beside a fixed card and the `z-index: 1000` that card needed to climb back out from under its own scrim. There is no confirming button: each row commits itself, because a picker whose answer is one of N rows has N answers rather than one. Nothing here knows what `not_jx_project` means, which permission counts as write, or that a Jx-tagged repository sorts first — `new-project/add-repo-modal.ts` keeps the listing, the ordering and the adoption, and hands over rows that are already strings and booleans.",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": {
+      "$ref": "#/state/title"
+    },
+    "confirmLabel": "",
+    "cancelLabel": "Cancel",
+    "size": "md"
+  },
+  "attributes": {
+    "part": "add-repo"
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "style": {
+    "$description": "Seventeen `.add-repo-*` rules in `styles/overlays.css` become the parts below, and four of them do not travel: `.add-repo-modal .new-project-modal-body` inherited a fixed card, a scroll body and a border from `.new-project-modal`, and a modal `<dialog>` is every one of those; `.add-repo-refresh` and its hover and disabled variants drew a button by hand, and the refresh is a `jx-button` now. The row's own `font-size: 13px` goes with them: a `<button>` does not inherit type, which is what `font: inherit` is for, and what it now inherits is the dialog's own body size rather than a number this surface picked. Six token repairs travel with the rest — `--spectrum-font-size-50` and `--spectrum-font-size-75` resolve only inside `<sp-theme>`, and a document mounted in the dialog layer is outside it, so every one of them would silently have taken its hard-coded fallback — and the two links lose the hard-coded blue they carried as a fallback behind `var(--accent)`, which is the same bug written the other way round.",
+    "& [part=\"picker\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-3)"
+    },
+    "& [part=\"list\"]": {
+      "$description": "The list scrolls, not the dialog. `jx-dialog` already scrolls its own body, so a cap here looks redundant — it is not: the filter above the list and the access footer below it are the two things that widen a listing that is missing what the reader came for, and a dialog that scrolls as one takes both of them off screen exactly when the list is long enough to need them.",
+      "display": "flex",
+      "flexDirection": "column",
+      "maxHeight": "320px",
+      "overflowY": "auto"
+    },
+    "& [part=\"row\"]": {
+      "$description": "A whole row is the button, because the answer is the repository rather than a control inside it. `baseline` rather than `center`: the name and the metadata beside it are different sizes, and aligning their boxes leaves the two strings visibly off each other.",
+      "display": "flex",
+      "alignItems": "baseline",
+      "gap": "var(--jx-space-3)",
+      "width": "100%",
+      "padding": "var(--jx-space-2) var(--jx-space-3)",
+      "background": "none",
+      "border": "none",
+      "borderRadius": "var(--radius)",
+      "font": "inherit",
+      "color": "var(--fg)",
+      "cursor": "pointer",
+      "textAlign": "left",
+      "&:hover:not([disabled])": {
+        "background": "var(--hover-bg)"
+      },
+      "&[disabled]": {
+        "$description": "Every row goes quiet while any one of them is importing: one adoption at a time, and the row that is running says so itself rather than the list going grey around it.",
+        "opacity": "0.6",
+        "cursor": "default"
+      }
+    },
+    "& [part=\"name\"]": {
+      "color": "var(--accent)"
+    },
+    "& [part=\"meta\"]": {
+      "display": "flex",
+      "alignItems": "baseline",
+      "gap": "var(--jx-space-2)",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"badge\"]": {
+      "padding": "0 var(--jx-space-2)",
+      "border": "1px solid var(--border)",
+      "borderRadius": "var(--jx-radius-lg)"
+    },
+    "& [part=\"busy\"]": {
+      "$description": "Pushed to the far end of the row it belongs to, so \"Importing…\" reads as this repository's state rather than as another piece of its metadata.",
+      "marginLeft": "auto",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"empty\"]": {
+      "margin": "0",
+      "padding": "var(--jx-space-4) var(--jx-space-3)",
+      "fontSize": "var(--jx-text-md)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"install\"], & [part=\"access-link\"]": {
+      "color": "var(--accent)",
+      "textDecoration": "underline"
+    },
+    "& [part=\"failure\"]": {
+      "$description": "The refusal from the last adoption, said above the list the reader is still looking at, because the list survives it: a repository with no readable project.json is a fact about that repository, and the ones beside it are still on offer. It is `failure` rather than `error` because `jx-textfield` draws a `[part=\"error\"]` of its own inside this same tree — the kit is light DOM, so a scoped rule on that name would style the filter field's error line too.",
+      "margin": "0",
+      "fontSize": "var(--jx-text-md)",
+      "color": "var(--danger)"
+    },
+    "& [part=\"access\"]": {
+      "$description": "The listing is bounded by what the Jx Suite GitHub App was granted, so the dialog always offers a way out of that boundary rather than only saying the list is short.",
+      "display": "flex",
+      "flexWrap": "wrap",
+      "alignItems": "baseline",
+      "gap": "var(--jx-space-2)",
+      "paddingTop": "var(--jx-space-3)",
+      "borderTop": "1px solid var(--border)",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"access-note\"]": {
+      "flex": "1 1 auto"
+    },
+    "& [part=\"access-links\"]": {
+      "display": "flex",
+      "flexWrap": "wrap",
+      "gap": "var(--jx-space-3)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "picker"
+      },
+      "children": [
+        {
+          "tagName": "jx-textfield",
+          "attributes": {
+            "part": "filter"
+          },
+          "$props": {
+            "label": "Filter repositories",
+            "placeholder": "Filter repositories…",
+            "size": "sm",
+            "value": {
+              "$ref": "#/state/filter"
+            }
+          },
+          "oninput": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setFilter"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "body-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/listState"
+          },
+          "cases": {
+            "loading": {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty"
+              },
+              "textContent": "Loading repositories…"
+            },
+            "empty-filter": {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty"
+              },
+              "textContent": "No repositories match the filter."
+            },
+            "empty-write": {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty"
+              },
+              "textContent": "No repositories with write access. Widen the Jx Suite GitHub App's repository access below, or ask a repository admin for write access."
+            },
+            "empty-install": {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty"
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "No repositories are reachable yet. "
+                },
+                {
+                  "tagName": "a",
+                  "attributes": {
+                    "part": "install",
+                    "href": "${state.installUrl}",
+                    "target": "_blank",
+                    "rel": "noreferrer"
+                  },
+                  "textContent": "Install the Jx Suite GitHub App"
+                },
+                {
+                  "tagName": "span",
+                  "textContent": " to grant repository access, then use Refresh below."
+                }
+              ]
+            },
+            "empty-none": {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty"
+              },
+              "textContent": "No repositories are reachable. Install the GitHub App (or widen its repository access) and try again."
+            },
+            "listed": {
+              "tagName": "div",
+              "attributes": {
+                "part": "list"
+              },
+              "children": [
+                {
+                  "$prototype": "Array",
+                  "items": {
+                    "$ref": "#/state/rows"
+                  },
+                  "key": {
+                    "$ref": "$map/item/fullName"
+                  },
+                  "map": {
+                    "tagName": "button",
+                    "attributes": {
+                      "part": "row",
+                      "type": "button",
+                      "data-repo": "${$map.item.fullName}",
+                      "title": "${$map.item.fullName}",
+                      "disabled": {
+                        "$ref": "$map/item/disabled"
+                      }
+                    },
+                    "onclick": {
+                      "$prototype": "Function",
+                      "body": [
+                        {
+                          "operator": "call",
+                          "target": {
+                            "$ref": "#/state/choose"
+                          },
+                          "value": [
+                            {
+                              "$ref": "$map/item/fullName"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "children": [
+                      {
+                        "tagName": "span",
+                        "attributes": {
+                          "part": "name"
+                        },
+                        "textContent": "${$map.item.fullName}"
+                      },
+                      {
+                        "tagName": "span",
+                        "attributes": {
+                          "part": "meta"
+                        },
+                        "children": [
+                          {
+                            "tagName": "span",
+                            "attributes": {
+                              "part": "tag-slot",
+                              "role": "none"
+                            },
+                            "style": {
+                              "display": "contents"
+                            },
+                            "$switch": {
+                              "$ref": "$map/item/isJx"
+                            },
+                            "cases": {
+                              "true": {
+                                "tagName": "span",
+                                "attributes": {
+                                  "part": "badge"
+                                },
+                                "textContent": "Jx"
+                              }
+                            }
+                          },
+                          {
+                            "tagName": "span",
+                            "attributes": {
+                              "part": "private-slot",
+                              "role": "none"
+                            },
+                            "style": {
+                              "display": "contents"
+                            },
+                            "$switch": {
+                              "$ref": "$map/item/isPrivate"
+                            },
+                            "cases": {
+                              "true": {
+                                "tagName": "span",
+                                "attributes": {
+                                  "part": "badge"
+                                },
+                                "textContent": "private"
+                              }
+                            }
+                          },
+                          {
+                            "tagName": "span",
+                            "textContent": "${$map.item.meta}"
+                          }
+                        ]
+                      },
+                      {
+                        "tagName": "span",
+                        "attributes": {
+                          "part": "busy-slot",
+                          "role": "none"
+                        },
+                        "style": {
+                          "display": "contents"
+                        },
+                        "$switch": {
+                          "$ref": "$map/item/importing"
+                        },
+                        "cases": {
+                          "true": {
+                            "tagName": "span",
+                            "attributes": {
+                              "part": "busy"
+                            },
+                            "textContent": "Importing…"
+                          }
+                        }
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "failure-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/hasFailure"
+          },
+          "cases": {
+            "true": {
+              "tagName": "p",
+              "attributes": {
+                "part": "failure"
+              },
+              "textContent": "${state.failure}"
+            }
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "access-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/hasAccess"
+          },
+          "cases": {
+            "true": {
+              "tagName": "div",
+              "attributes": {
+                "part": "access"
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "attributes": {
+                    "part": "access-note"
+                  },
+                  "textContent": "Missing a repository? Grant the Jx Suite GitHub App access to more of them:"
+                },
+                {
+                  "tagName": "span",
+                  "attributes": {
+                    "part": "access-links"
+                  },
+                  "children": [
+                    {
+                      "$prototype": "Array",
+                      "items": {
+                        "$ref": "#/state/access"
+                      },
+                      "key": {
+                        "$ref": "$map/item/url"
+                      },
+                      "map": {
+                        "tagName": "a",
+                        "attributes": {
+                          "part": "access-link",
+                          "href": "${$map.item.url}",
+                          "target": "_blank",
+                          "rel": "noreferrer",
+                          "title": "${$map.item.title}"
+                        },
+                        "textContent": "${$map.item.label}"
+                      }
+                    }
+                  ]
+                },
+                {
+                  "tagName": "jx-button",
+                  "attributes": {
+                    "part": "refresh"
+                  },
+                  "$props": {
+                    "size": "sm",
+                    "disabled": {
+                      "$ref": "#/state/refreshDisabled"
+                    }
+                  },
+                  "onclick": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/refresh"
+                        },
+                        "value": []
+                      }
+                    ]
+                  },
+                  "children": [
+                    {
+                      "tagName": "span",
+                      "textContent": "Refresh"
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        }
+      ]
+    }
+  ]
+}