@jxsuite/studio 6.1.2 → 8.0.0

package/src/surfaces/publish-quick.json

@@ -0,0 +1,428 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioPublishQuick",
+  "$description": "Quick publish (studio.md §22.8): the dialog the chevron beside the Publish workspace tab opens. The count, a short list of what changed, the destination, the summary that becomes the commit message, and the checks in one line; Publish now takes every change to the destination, and Review all opens the Publish workspace on Review changes instead. One `jx-dialog`, so the platform owns modality, Escape and focus restoration. `publish/publish-quick.ts` keeps every decision, and the words of the destinations and the checks are the same `publish/publish-changes.ts` hands Review changes, so the two cannot disagree about what a button does.",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": "Publish",
+    "confirmLabel": "Publish now",
+    "confirmDisabled": {
+      "$ref": "#/state/blocked"
+    },
+    "secondaryLabel": "Review all",
+    "cancelLabel": "Cancel",
+    "size": "md"
+  },
+  "attributes": {
+    "part": "publish-quick",
+    "data-destination": "${state.destination}"
+  },
+  "onconfirm": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/confirm"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onsecondary": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/reviewAll"
+        },
+        "value": []
+      }
+    ]
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "style": {
+    "& [part=\"sheet\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-3)",
+      "minWidth": "0"
+    },
+    "& [part=\"count\"]": {
+      "margin": "0",
+      "fontWeight": "600"
+    },
+    "& [part=\"change-list\"]": {
+      "margin": "0",
+      "padding": "0",
+      "listStyle": "none",
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-1)"
+    },
+    "& [part=\"change\"]": {
+      "display": "flex",
+      "alignItems": "baseline",
+      "gap": "var(--jx-space-2)",
+      "minWidth": "0"
+    },
+    "& [part=\"change-tag\"]": {
+      "$description": "NEW, EDIT, DELETED, as the board draws them: a word rather than git's letter, because this dialog is read by someone who has never seen a status column.",
+      "flex": "none",
+      "minWidth": "52px",
+      "fontSize": "var(--jx-text-xs)",
+      "fontWeight": "700",
+      "letterSpacing": "0.04em",
+      "color": "var(--signal)"
+    },
+    "& [part=\"change\"][data-status=\"A\"] > [part=\"change-tag\"], & [part=\"change\"][data-status=\"U\"] > [part=\"change-tag\"]": {
+      "color": "var(--success)"
+    },
+    "& [part=\"change\"][data-status=\"D\"] > [part=\"change-tag\"]": {
+      "color": "var(--danger)"
+    },
+    "& [part=\"change-name\"]": {
+      "minWidth": "0",
+      "overflow": "hidden",
+      "textOverflow": "ellipsis",
+      "whiteSpace": "nowrap"
+    },
+    "& [part=\"change-dir\"], & [part=\"more\"], & [part=\"choice-note\"], & [part=\"blocker\"]": {
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"more\"], & [part=\"blocker\"]": {
+      "margin": "0"
+    },
+    "& [part=\"destinations\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-2)"
+    },
+    "& [part=\"destination-card\"] > [part=\"control\"]": {
+      "$description": "The same card Review changes draws for the same choice: a name and a sentence inside one radio.",
+      "width": "100%",
+      "height": "auto",
+      "flexDirection": "column",
+      "alignItems": "flex-start",
+      "textAlign": "start",
+      "padding": "var(--jx-space-2) var(--jx-space-3)",
+      "gap": "2px",
+      "whiteSpace": "normal"
+    },
+    "& [part=\"choice-name\"]": {
+      "display": "block",
+      "fontWeight": "600"
+    },
+    "& [part=\"choice-note\"]": {
+      "display": "block"
+    },
+    "& [part=\"checks-line\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-2)",
+      "margin": "0",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"checks-line\"][data-state=\"done\"] > [part=\"checks-icon\"]": {
+      "color": "var(--success)"
+    },
+    "& [part=\"checks-line\"][data-state=\"open\"] > [part=\"checks-icon\"]": {
+      "color": "var(--warning)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "sheet"
+      },
+      "children": [
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "count"
+          },
+          "textContent": "${state.countLine}"
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "list-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/listState"
+          },
+          "cases": {
+            "listed": {
+              "tagName": "ul",
+              "attributes": {
+                "part": "change-list"
+              },
+              "children": [
+                {
+                  "$prototype": "Array",
+                  "items": {
+                    "$ref": "#/state/rows"
+                  },
+                  "key": {
+                    "$ref": "$map/item/key"
+                  },
+                  "map": {
+                    "tagName": "li",
+                    "attributes": {
+                      "part": "change",
+                      "data-status": "${$map.item.status}",
+                      "title": "${$map.item.path}"
+                    },
+                    "children": [
+                      {
+                        "tagName": "span",
+                        "attributes": {
+                          "part": "change-tag"
+                        },
+                        "textContent": "${$map.item.tag}"
+                      },
+                      {
+                        "tagName": "span",
+                        "attributes": {
+                          "part": "change-name"
+                        },
+                        "textContent": "${$map.item.name}"
+                      },
+                      {
+                        "tagName": "span",
+                        "attributes": {
+                          "part": "change-dir"
+                        },
+                        "textContent": "${$map.item.dir}"
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "more-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/hasMore"
+          },
+          "cases": {
+            "true": {
+              "tagName": "p",
+              "attributes": {
+                "part": "more"
+              },
+              "textContent": "${state.more}"
+            }
+          }
+        },
+        {
+          "tagName": "jx-action-group",
+          "attributes": {
+            "part": "destinations"
+          },
+          "$props": {
+            "selects": "single",
+            "label": "Destination",
+            "compact": false,
+            "orientation": "vertical"
+          },
+          "children": [
+            {
+              "$prototype": "Array",
+              "items": {
+                "$ref": "#/state/destinations"
+              },
+              "key": {
+                "$ref": "$map/item/value"
+              },
+              "map": {
+                "tagName": "jx-action-button",
+                "attributes": {
+                  "part": "destination-card",
+                  "data-destination": "${$map.item.value}"
+                },
+                "$props": {
+                  "label": {
+                    "$ref": "$map/item/label"
+                  },
+                  "checked": {
+                    "$ref": "$map/item/checked"
+                  },
+                  "disabled": {
+                    "$ref": "$map/item/disabled"
+                  },
+                  "hint": {
+                    "$ref": "$map/item/reason"
+                  },
+                  "quiet": false
+                },
+                "onclick": {
+                  "$prototype": "Function",
+                  "body": [
+                    {
+                      "operator": "call",
+                      "target": {
+                        "$ref": "#/state/pickDestination"
+                      },
+                      "value": [
+                        {
+                          "$ref": "$map/item/value"
+                        }
+                      ]
+                    }
+                  ]
+                },
+                "children": [
+                  {
+                    "tagName": "span",
+                    "attributes": {
+                      "part": "choice-name"
+                    },
+                    "textContent": "${$map.item.label}"
+                  },
+                  {
+                    "tagName": "span",
+                    "attributes": {
+                      "part": "choice-note"
+                    },
+                    "textContent": "${$map.item.note}"
+                  }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "tagName": "jx-field",
+          "attributes": {
+            "part": "summary-field"
+          },
+          "$props": {
+            "label": "Summary",
+            "span": true
+          },
+          "children": [
+            {
+              "tagName": "jx-textfield",
+              "attributes": {
+                "part": "summary"
+              },
+              "$props": {
+                "size": "sm",
+                "placeholder": "Describe what changed",
+                "value": {
+                  "$ref": "#/state/summary"
+                }
+              },
+              "oninput": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/editSummary"
+                    },
+                    "value": [
+                      {
+                        "$ref": "event#/target/value"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "checks-line",
+            "data-state": "${state.checksState}"
+          },
+          "children": [
+            {
+              "tagName": "jx-icon",
+              "attributes": {
+                "part": "checks-icon"
+              },
+              "$props": {
+                "name": {
+                  "$ref": "#/state/checksIcon"
+                }
+              }
+            },
+            {
+              "tagName": "span",
+              "attributes": {
+                "part": "checks-text"
+              },
+              "textContent": "${state.checksLine}"
+            }
+          ]
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "blocker-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/hasBlocker"
+          },
+          "cases": {
+            "true": {
+              "tagName": "p",
+              "attributes": {
+                "part": "blocker"
+              },
+              "textContent": "${state.blocker}"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/publish-quick.ts

@@ -0,0 +1,165 @@
+/// <reference lib="dom" />
+/**
+ * Quick publish, as a mounted dialog (studio.md §22.8).
+ *
+ * This is the adapter: the reactive scope `publish-quick.json` reads, and the mount that lives in
+ * the dialog layer until the flow (`publish/publish-quick.ts`) takes it down. The dialog is a
+ * `jx-dialog` opened with `showModal()`, so the platform owns modality, Escape and focus
+ * restoration (`studio-ui-guidelines.md` §8.7); nothing here draws a backdrop.
+ *
+ * **Await the ELEMENT, not just the mount**, for the reason `surfaces/add-new.ts` gives: the
+ * dialog's own template is one `connectedCallback` after the document renders.
+ *
+ * @docs studio/publish
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { whenReady } from "./dialog";
+import publishQuickDoc from "./publish-quick.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { DestinationChoice } from "../publish/publish-changes";
+import type { PublishDestination } from "../publish/publish-ids";
+
+registerSurface("publish-quick", publishQuickDoc);
+
+/** One changed file in the short list. */
+export interface QuickChangeRow {
+  key: string;
+  path: string;
+  /** NEW, EDIT, DELETED, RENAMED: a word, not git's letter. */
+  tag: string;
+  name: string;
+  dir: string;
+  status: string;
+}
+
+/** Everything the dialog draws. */
+export interface PublishQuickView {
+  /** "5 changes ready". */
+  countLine: string;
+  listState: "listed" | "empty";
+  rows: QuickChangeRow[];
+  hasMore: boolean;
+  /** "+ 2 more". */
+  more: string;
+  destination: PublishDestination;
+  destinations: DestinationChoice[];
+  summary: string;
+  /** `done` when every check passed, `open` while any is not. */
+  checksState: "done" | "open";
+  /**
+   * The kit icon beside the checks line: `check` when every check passed, `warning-circle` while
+   * any is open.
+   */
+  checksIcon: string;
+  checksLine: string;
+  blocked: boolean;
+  hasBlocker: boolean;
+  blocker: string;
+}
+
+/** What a control asks the flow to do. */
+export interface PublishQuickActions {
+  confirm: () => void;
+  reviewAll: () => void;
+  pickDestination: (value: string) => void;
+  editSummary: (value: string) => void;
+  /** The dialog closed, for any reason the platform owns as well as the flow's own `close`. */
+  closed: () => void;
+}
+
+export interface PublishQuickSurfaceOptions {
+  /** Where the dialog is mounted: the dialog layer, handed in so this module never reaches back. */
+  layer: HTMLElement;
+  view: PublishQuickView;
+  actions: PublishQuickActions;
+}
+
+export interface PublishQuickSurfaceHandle {
+  host: HTMLElement;
+  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
+  ready: Promise<HTMLElement>;
+  update: (view: PublishQuickView) => void;
+  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
+  close: () => void;
+}
+
+type PublishQuickScope = PublishQuickView & PublishQuickActions;
+
+/** Open the dialog. The handle's `ready` resolves once it is showing. */
+export function openPublishQuickSurface(
+  options: PublishQuickSurfaceOptions,
+): PublishQuickSurfaceHandle {
+  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 (`surfaces/add-new.ts` says why a modal
+     dialog in a slot that skipped this hit-tests to nothing). */
+  slot.style.pointerEvents = "auto";
+  slot.setAttribute(REGION_ATTR, overlayRegion("dialog", "publish-quick"));
+  options.layer.append(slot);
+
+  let closed = false;
+  /** Say it is over, once: the platform's own `close` and `close()` may each be first. */
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.actions.closed();
+  };
+  /* A function, not the flag: TypeScript narrows a `let` across the awaits below as if nothing
+     could have closed the dialog while the mount was in flight. */
+  const isClosed = (): boolean => closed;
+  const { actions } = options;
+  const scope = reactive<PublishQuickScope>({
+    ...options.view,
+    closed: finish,
+    confirm: actions.confirm,
+    editSummary: (value: string) => {
+      /* What the control holds, first and unconditionally: a binding only writes when the scope
+         CHANGES (`studio-ui-guidelines.md` §9.3). */
+      scope.summary = value;
+      actions.editSummary(value);
+    },
+    pickDestination: actions.pickDestination,
+    reviewAll: actions.reviewAll,
+  });
+
+  let mounted: SurfaceHandle | null = null;
+  const ready = mountSurface("publish-quick", scope, slot).then(async (surface) => {
+    mounted = surface;
+    /* SAFETY: `publish-quick.json`'s root definition is a `jx-dialog` element, so the runtime
+       mounts an HTMLElement; a `Text` root only comes from a document whose root is a string. */
+    const element = surface.root as HTMLElement;
+    if (isClosed()) {
+      surface.dispose();
+      return element;
+    }
+    await whenReady(element);
+    if (!isClosed()) {
+      showModal(element);
+    }
+    return element;
+  });
+
+  return {
+    close() {
+      const element = mounted?.root;
+      if (element instanceof HTMLElement) {
+        close(element);
+      }
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+      finish();
+    },
+    host: slot,
+    ready,
+    update(view) {
+      Object.assign(scope, view);
+    },
+  };
+}