@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/publish-workspace.ts

@@ -0,0 +1,391 @@
+/// <reference lib="dom" />
+/**
+ * The Publish workspace, as a mounted document (studio.md §22.8).
+ *
+ * This is the adapter. `publish/publish-workspace.ts` is the flow: which sub-tab is showing, what
+ * the change list, the checks, the destinations, the deployments, the branches and the hosting rows
+ * say, and what every control does. It hands this module one projection, and this module hands the
+ * document a scope and reports the one node the flow needs to hold.
+ *
+ * **One island, through `onNodeCreated`.** Hosting's build adapter is the Deploy section that moved
+ * here from Project Settings (§17.1), mounted by `settings/project-sections.ts` into a box this
+ * document draws and never fills (`adapter-island`). The node is announced as it is created, which
+ * is the one seam for a node a document made (`studio-ui-guidelines.md` §9.4); a node found by
+ * selector once would be detached DOM the moment the Hosting case was switched away and back.
+ *
+ * **The host is cleared**, for the reason `surfaces/media-library.ts` gives: the pane's stage is
+ * handed to whichever mode owns it whole.
+ *
+ * @docs studio/publish
+ */
+
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import publishWorkspaceDoc from "./publish-workspace.json";
+import type { JxElement } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+import type { ChangeRow, CommitRow } from "../publish/source-control";
+import type { DestinationChoice } from "../publish/publish-changes";
+import type { PublishDestination, PublishTab } from "../publish/publish-ids";
+import type { DeployStepRowView } from "./panel-deploy-checklist";
+import type { ActivityRowView } from "./panel-activity";
+
+registerSurface("publish-workspace", publishWorkspaceDoc);
+
+/** One sub-tab in the strip. */
+export interface PublishTabRow {
+  value: PublishTab;
+  label: string;
+}
+
+/** One changed file in Review changes: the shared row, plus what its three controls are called. */
+export interface ReviewFileRow extends ChangeRow {
+  includeLabel: string;
+  compareLabel: string;
+  discardLabel: string;
+  discardHint: string;
+}
+
+/** One component's changed files. */
+export interface ReviewGroupRow {
+  key: string;
+  name: string;
+  files: ReviewFileRow[];
+}
+
+/** One check, with its glyph and the one button that resolves it. */
+export interface PublishCheckRow {
+  key: string;
+  state: string;
+  /** A kit icon name (`check`, `x`, `spinner`, `warning-circle`, `question`). */
+  icon: string;
+  /** The state in words, the icon's accessible name: "Passed", "To do", "Not checked yet". */
+  iconLabel: string;
+  text: string;
+  hasAction: boolean;
+  actionLabel: string;
+  actionTitle: string;
+  actionDisabled: boolean;
+}
+
+/** A command, drawn as a button: its id, its own title, and whether it may run now. */
+export interface CommandButtonRow {
+  id: string;
+  label: string;
+  /** The tooltip: the title, or the title and the reason it is refused. */
+  title: string;
+  disabled: boolean;
+}
+
+/** One deployment, in History or under Branch previews. */
+export interface DeploymentRow {
+  key: string;
+  /** "2h ago". */
+  when: string;
+  /** "Production", or the preview's branch. */
+  label: string;
+  environment: string;
+  /** The state in words: "Live", "Replaced", "Ready", "Building…", "Failed" or "Canceled". */
+  status: string;
+  /** What the host reported, as its stage and status ("deploy: success"): the status's tooltip. */
+  statusDetail: string;
+  /** The stage's status alone, for its colour: `success`, `failure`, `active`… */
+  statusKey: string;
+  url: string;
+  openLabel: string;
+}
+
+/** One local branch. */
+export interface BranchRow {
+  key: string;
+  name: string;
+  current: boolean;
+  /** For the current branch: "2 ahead, 1 behind" or "Up to date". */
+  note: string;
+  /** For any other: "Switch", or "Switch and reload" where a branch is a session. */
+  switchLabel: string;
+  /** The switch button's accessible name, which names the branch: "Switch to feature". */
+  switchName: string;
+}
+
+/** Everything the document draws, as one value. */
+export interface PublishWorkspaceView {
+  region: string;
+  titleId: string;
+  panelId: string;
+  /** The region of the destination card, which is the part a screenshot crops to. */
+  commitRegion: string;
+  destinationId: string;
+  tab: PublishTab;
+  tabTitle: string;
+  tabs: PublishTabRow[];
+  headline: string;
+  mood: "no-project" | "loading" | "no-repo" | "repo";
+  busy: boolean;
+  hasError: boolean;
+  error: string;
+  canClone: boolean;
+  // Review changes
+  syncLabel: string;
+  lastUpdated: string;
+  hasLastUpdated: boolean;
+  remoteState: "remote" | "local";
+  pullLabel: string;
+  pushLabel: string;
+  filesState: "listed" | "empty";
+  includedLabel: string;
+  allIncluded: boolean;
+  someIncluded: boolean;
+  groups: ReviewGroupRow[];
+  commitsState: "listed" | "empty";
+  commits: CommitRow[];
+  checks: PublishCheckRow[];
+  destination: PublishDestination;
+  destinations: DestinationChoice[];
+  hasRefusal: boolean;
+  refusal: string;
+  summary: string;
+  primaryLabel: string;
+  primaryDisabled: boolean;
+  hasBlocker: boolean;
+  blocker: string;
+  reviewState: "none" | "opened";
+  reviewLine: string;
+  reviewUrl: string;
+  // Deploys
+  hasLiveUrl: boolean;
+  liveUrl: string;
+  liveNone: string;
+  liveSummary: string;
+  deployCommands: CommandButtonRow[];
+  runningState: "none" | "running";
+  /** Each deploy in progress: the Activity record (§16.4), as the Activity feed draws it. */
+  running: ActivityRowView[];
+  deploysState: "listed" | "loading" | "note";
+  deploysNote: string;
+  deploysBusy: boolean;
+  historyState: "listed" | "empty";
+  history: DeploymentRow[];
+  previewsState: "listed" | "empty";
+  previews: DeploymentRow[];
+  // Branches
+  branchSummary: string;
+  newBranchDisabled: boolean;
+  hasBranchNote: boolean;
+  branchNote: string;
+  branchesState: "listed" | "empty";
+  branchesEmpty: string;
+  branches: BranchRow[];
+  // Hosting
+  sourceSummary: string;
+  sourceCommands: CommandButtonRow[];
+  hostTitle: string;
+  hostSummary: string;
+  hostCommands: CommandButtonRow[];
+  domainState: "set" | "none";
+  domain: string;
+  domainNote: string;
+  checklistSummary: string;
+  checklistSteps: DeployStepRowView[];
+}
+
+/** What a control asks the flow to do. */
+export interface PublishWorkspaceActions {
+  selectTab: (tab: string) => void;
+  refresh: () => void;
+  fetch: () => void;
+  pull: () => void;
+  push: () => void;
+  clone: () => void;
+  initRepository: () => void;
+  createRepository: () => void;
+  include: (path: string, included: boolean) => void;
+  includeAll: (included: boolean) => void;
+  compare: (path: string) => void;
+  discard: (path: string) => void;
+  runCheck: (key: string) => void;
+  pickDestination: (value: string) => void;
+  editSummary: (value: string) => void;
+  publish: () => void;
+  openUrl: (url: string) => void;
+  run: (commandId: string) => void;
+  reloadDeployments: () => void;
+  checkout: (name: string) => void;
+  newBranch: () => void;
+  /** The build adapter's mount box was created. */
+  adapterHost: (element: HTMLElement) => void;
+  /**
+   * A change row's Compare button was created, for the file at `path`: the control the keyboard
+   * goes back to when the comparison it opened is left.
+   */
+  compareHost: (element: HTMLElement, path: string) => void;
+}
+
+export interface PublishWorkspaceSurfaceHandle {
+  ready: Promise<HTMLElement>;
+  /** Whether what was mounted is still inside the host (a mount still in flight counts). */
+  attached: () => boolean;
+  update: (view: PublishWorkspaceView) => void;
+  dispose: () => void;
+}
+
+/** The scope the document reads: the view, and every action but the node callback. */
+type PublishWorkspaceScope = PublishWorkspaceView &
+  Omit<PublishWorkspaceActions, "adapterHost" | "compareHost">;
+
+/** An empty view: what a scope holds before the first projection. */
+export function emptyPublishWorkspaceView(): PublishWorkspaceView {
+  return {
+    allIncluded: false,
+    blocker: "",
+    branchNote: "",
+    branchSummary: "",
+    branches: [],
+    branchesEmpty: "",
+    branchesState: "empty",
+    busy: false,
+    canClone: false,
+    checklistSteps: [],
+    checklistSummary: "",
+    checks: [],
+    commitRegion: "",
+    commits: [],
+    commitsState: "empty",
+    deployCommands: [],
+    deploysBusy: false,
+    deploysNote: "",
+    deploysState: "note",
+    destination: "live",
+    destinationId: "",
+    destinations: [],
+    domain: "",
+    domainNote: "",
+    domainState: "none",
+    error: "",
+    filesState: "empty",
+    groups: [],
+    hasBlocker: false,
+    hasBranchNote: false,
+    hasError: false,
+    hasLastUpdated: false,
+    hasLiveUrl: false,
+    hasRefusal: false,
+    headline: "",
+    history: [],
+    historyState: "empty",
+    hostCommands: [],
+    hostSummary: "",
+    hostTitle: "",
+    includedLabel: "",
+    lastUpdated: "",
+    liveNone: "",
+    liveSummary: "",
+    liveUrl: "",
+    mood: "loading",
+    newBranchDisabled: false,
+    panelId: "",
+    previews: [],
+    previewsState: "empty",
+    primaryDisabled: true,
+    primaryLabel: "",
+    pullLabel: "Pull",
+    pushLabel: "Push",
+    refusal: "",
+    region: "",
+    remoteState: "local",
+    reviewLine: "",
+    reviewState: "none",
+    reviewUrl: "",
+    running: [],
+    runningState: "none",
+    someIncluded: false,
+    sourceCommands: [],
+    sourceSummary: "",
+    summary: "",
+    syncLabel: "",
+    tab: "review",
+    tabTitle: "",
+    tabs: [],
+    titleId: "",
+  };
+}
+
+/** The file a change row stands for, read from the row scope the runtime renders it with. */
+function rowPathOf(state: JxScope | undefined): string {
+  const map = state?.["$map"];
+  const row = isJsonObject(map) ? map["item"] : undefined;
+  const path = isJsonObject(row) ? row["path"] : undefined;
+  return isString(path) ? path : "";
+}
+
+/** The `part` a definition declares, or `""`. */
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
+}
+
+/**
+ * Mount the Publish workspace into a pane's stage.
+ *
+ * @param {HTMLElement} host - The pane's stage, emptied first
+ * @param {PublishWorkspaceView} view - What to draw right now
+ * @param {PublishWorkspaceActions} actions - What each control does
+ * @returns {PublishWorkspaceSurfaceHandle}
+ */
+export function mountPublishWorkspaceSurface(
+  host: HTMLElement,
+  view: PublishWorkspaceView,
+  actions: PublishWorkspaceActions,
+): PublishWorkspaceSurfaceHandle {
+  host.replaceChildren();
+  const { adapterHost, compareHost, ...controls } = actions;
+  const scope = reactive<PublishWorkspaceScope>({ ...emptyPublishWorkspaceView(), ...controls });
+  Object.assign(scope, view);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("publish-workspace", scope, host, {
+    onNodeCreated: (element, _path, def, state) => {
+      // `disposed` first: nodes are still created while a mount that was taken down runs out.
+      if (disposed || !(element instanceof HTMLElement)) {
+        return;
+      }
+      const part = partOf(def);
+      if (part === "adapter-island") {
+        adapterHost(element);
+      } else if (part === "compare") {
+        compareHost(element, rowPathOf(state));
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+    } else {
+      mounted = surface;
+    }
+    /* SAFETY: `publish-workspace.json`'s root definition is a `div` element, so the runtime mounts
+       an HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
+    return surface.root as HTMLElement;
+  });
+
+  return {
+    attached: () => {
+      if (disposed) {
+        return false;
+      }
+      const root = mounted?.root;
+      return root === undefined ? true : root instanceof HTMLElement && host.contains(root);
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update: (next) => {
+      Object.assign(scope, next);
+    },
+  };
+}

package/src/surfaces/publish.ts

@@ -31,23 +31,16 @@
 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 { close, showModal } from "@jxsuite/ui/behaviors/dialog";
 import { whenReady } from "./dialog";
 import publishDoc from "./publish.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("publish", publishDoc as unknown as JxDocument);
+registerSurface("publish", publishDoc);
 
 /** Where the Cloudflare Pages GitHub App is installed from. */
 const PAGES_APP_INSTALL_URL = "https://github.com/apps/cloudflare-pages/installations/new";
 
-/** One Cloudflare account, as the picker draws it. */
-export interface PublishAccountRow {
-  value: string;
-  label: string;
-}
-
 /** The create-and-connect form, as the reader has filled it in so far. */
 export interface PublishForm {
   accountId: string;
@@ -95,7 +88,7 @@ export interface PublishView {
   busy: boolean;
   /** The last refusal, verbatim from whatever raised it. Empty draws nothing. */
   error: string;
-  accounts: PublishAccountRow[];
+  accounts: SurfaceOption[];
   form: PublishForm;
   /** The connected Pages project, or null when this site has none yet. */
   deploy: PublishDeploy | null;
@@ -164,7 +157,7 @@ interface PublishFlags {
    */
   needsPagesApp: boolean;
   pagesAppUrl: string;
-  accountOptions: PublishAccountRow[];
+  accountOptions: SurfaceOption[];
   accountId: string;
   projectName: string;
   owner: string;
@@ -181,7 +174,7 @@ interface PublishFlags {
   busy: boolean;
 }
 
-interface PublishScope extends Record<string, unknown>, PublishFlags {
+interface PublishScope extends PublishFlags {
   connect: () => void;
   replace: () => void;
   setToken: (value: string) => void;
@@ -286,8 +279,12 @@ export function openPublishSurface(options: PublishSurfaceOptions): PublishSurfa
     closed = true;
     options.onClosed();
   };
+  /* Read through a call, not the bare binding: `close()` can run while the mount is awaiting the
+     element, and a direct `closed` test after that `await` would be narrowed to the value the test
+     before it saw. */
+  const isClosed = (): boolean => closed;
 
-  const scope = reactive({
+  const scope: PublishScope = reactive<PublishScope>({
     ...derive(options.view),
     closed: finish,
     connect: () => {
@@ -341,18 +338,21 @@ export function openPublishSurface(options: PublishSurfaceOptions): PublishSurfa
       tokenDraft = "";
       options.onSaveToken(token);
     },
-  }) as PublishScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("publish", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `publish.json`'s root definition carries `tagName: "jx-dialog"`, so the runtime
+       mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare
+       string. */
     const element = surface.root as HTMLElement;
-    if (closed) {
+    if (isClosed()) {
       surface.dispose();
       return element;
     }
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     /* The region goes on the platform's own `<dialog>`, which is the one element here that HAS a
@@ -375,7 +375,7 @@ export function openPublishSurface(options: PublishSurfaceOptions): PublishSurfa
       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);
+        close(element);
       }
       // A mount that has not landed yet is disposed by `ready` when it does — `finish` tells it so.
       mounted?.dispose();

package/src/surfaces/push-plan.ts

@@ -13,10 +13,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import pushPlanDoc from "./push-plan.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("push-plan", pushPlanDoc as unknown as JxDocument);
+registerSurface("push-plan", pushPlanDoc);
 
 /** One step of the plan. `kind` colours the rule beside it; nothing here reads it otherwise. */
 export interface PushStepRow {
@@ -44,8 +43,6 @@ export interface PushPlanSurfaceHandle {
   dispose: () => void;
 }
 
-interface PushPlanScope extends Record<string, unknown>, PushPlanView {}
-
 /**
  * Mount the plan into `host`.
  *
@@ -54,20 +51,22 @@ interface PushPlanScope extends Record<string, unknown>, PushPlanView {}
  * @returns {PushPlanSurfaceHandle}
  */
 export function mountPushPlanSurface(host: HTMLElement, view: PushPlanView): PushPlanSurfaceHandle {
-  const scope = reactive<PushPlanScope>({
+  const scope: PushPlanView = reactive<PushPlanView>({
     errors: view.errors,
     steps: view.steps,
     warnings: view.warnings,
-  }) as PushPlanScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
   const ready = mountSurface("push-plan", scope, host).then((surface) => {
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+    } else {
+      mounted = surface;
     }
-    mounted = surface;
+    /* SAFETY: `push-plan.json`'s root definition is a `div` element, so the runtime mounts an
+       HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
     return surface.root as HTMLElement;
   });