@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/git-panel.ts

@@ -0,0 +1,272 @@
+/// <reference lib="dom" />
+/**
+ * The Source Control panel, as a mounted document.
+ *
+ * `panels/git-panel.ts` is the flow — what git is asked, what a comparison is, which files group
+ * under which component, what a commit does before it runs, and which of the four moods the panel
+ * is in — and this is the surface it draws into: the reactive scope the document reads, the flags
+ * it discriminates on, and the mount that stays put while the Navigator repaints around it.
+ *
+ * **The flow tells the surface what a row says, never what it means.** A changed file arrives as a
+ * name, a directory, a status letter, that status said aloud, and two booleans; nothing here learns
+ * what `U` is or that a `.png` has no comparison to open. That matters more here than in the
+ * settings sections, because the file rows are NESTED — inside the per-file map `$map/item` is the
+ * file, so a row genuinely cannot reach the group it is under — and a path it can hand straight
+ * back is the whole answer.
+ *
+ * **The container is not cleared**, which is the one line where a panel differs from a settings
+ * section. A section is handed the pane's whole content area and starts by emptying it; a panel
+ * body is a node lit renders into, and its comment markers are how lit finds its own content again.
+ * So the document is APPENDED, and {@link GitPanelSurfaceHandle.connected} is how the panel finds
+ * out that the Navigator has since painted another panel over the top of it.
+ *
+ * @docs studio/publish/source-control
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import gitPanelDoc from "./git-panel.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("git-panel", gitPanelDoc as unknown as JxDocument);
+
+/** One changed file, as the document draws it. Every field is a value: no records, no closures. */
+export interface GitFileRowView {
+  /** The row's reconcile key AND what every button hands back — the project-relative path. */
+  key: string;
+  path: string;
+  /** The last segment, which is what the row reads as. */
+  name: string;
+  /** Everything before it, drawn small beside the name. */
+  dir: string;
+  /** Whether there is a directory to draw; the document has no `length` to ask. */
+  hasDir: boolean;
+  /** The open button's accessible name: the path and the status in words. */
+  label: string;
+  /** The one-letter badge — `M`, `A`, `D`, `R`, `U`. */
+  status: string;
+  /** Which pair of verbs the row offers: Unstage, or Discard and Stage. */
+  staged: boolean;
+  /**
+   * Whether Discard is refused, spelled the way the document reads it. An untracked file has no
+   * committed version to come back to, so there is nothing to discard TO.
+   */
+  cannotDiscard: boolean;
+}
+
+/** One component's changed files, under the heading the flow spelled. */
+export interface GitGroupView {
+  key: string;
+  name: string;
+  files: GitFileRowView[];
+}
+
+/** One commit in the log. */
+export interface GitCommitView {
+  key: string;
+  /** The short hash, already sliced. */
+  hash: string;
+  message: string;
+  /** "ada · 5m ago" — the author and the age, joined by the flow that knows the clock. */
+  meta: string;
+}
+
+/** One row of the branch picker. `__new__` is a row like any other; the flow knows what it means. */
+export interface GitBranchOption {
+  value: string;
+  label: string;
+}
+
+/** What the panel says the surface should be showing right now. */
+export interface GitPanelValues {
+  /**
+   * Which of the four moods the panel is in: no project open, a first read still in flight, a
+   * project git is not tracking, or a repository. The flow decides; the document switches.
+   */
+  view: "no-project" | "loading" | "no-repo" | "repo";
+  /** Whether this platform can clone at all — the one action the no-project state offers. */
+  canClone: boolean;
+  /** A git verb is in flight: every button that would start a second one is off. */
+  busy: boolean;
+  hasError: boolean;
+  error: string;
+  /** `remote` or `local`: which sync bar is drawn. */
+  remoteState: "remote" | "local";
+  /** "Up to date", or "3 ahead, 1 behind". */
+  syncLabel: string;
+  /** "Last updated 02:04 PM", or empty. */
+  lastUpdated: string;
+  hasLastUpdated: boolean;
+  /** The pull and push buttons' names, which carry their counts: "Pull (2 behind)". */
+  pullLabel: string;
+  pushLabel: string;
+  branchName: string;
+  /** What the picker currently holds. Not always {@link branchName} — see the adapter's note. */
+  branchValue: string;
+  branchOptions: GitBranchOption[];
+  /** `changes` or `history` — `shell.git.subTab`, which names the `$switch` case. */
+  subTab: string;
+  /** "Local Changes (6)" — the count is part of the tab's label, not a badge of its own. */
+  changesLabel: string;
+  commitMessage: string;
+  hasStaged: boolean;
+  stagedCount: string;
+  stagedFiles: GitFileRowView[];
+  changedCount: string;
+  /** Whether Stage all has anything to stage. */
+  hasUnstaged: boolean;
+  filesState: "listed" | "empty";
+  groups: GitGroupView[];
+  historyState: "listed" | "empty";
+  commits: GitCommitView[];
+}
+
+/** What a control can ask the panel to do. Every one of them is a decision the flow owns. */
+export interface GitPanelActions {
+  clone: () => void;
+  initRepository: () => void;
+  createRepository: () => void;
+  refresh: () => void;
+  fetch: () => void;
+  pull: () => void;
+  push: () => void;
+  /** A pick from the branch picker — including the row that means "make a new one". */
+  chooseBranch: (value: string) => void;
+  selectTab: (tab: string) => void;
+  /** State what the commit field now holds, before anything is decided about it. */
+  editMessage: (value: string) => void;
+  /** Commit without pushing — the chord, and the menu row. */
+  commit: () => void;
+  commitAndSync: () => void;
+  /** The split button's second half: the kit menu, hung off the control that was clicked. */
+  openCommitMenu: (anchor: HTMLElement) => void;
+  openFile: (path: string) => void;
+  stage: (path: string) => void;
+  unstage: (path: string) => void;
+  discard: (path: string) => void;
+  stageAll: () => void;
+  unstageAll: () => void;
+}
+
+export interface GitPanelSurfaceHandle {
+  /** Bring the mounted document up to date with a whole projection. */
+  update: (values: GitPanelValues) => 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: the projection, plus everything a control can ask for. */
+interface GitPanelScope extends Record<string, unknown>, GitPanelValues, GitPanelActions {}
+
+/** Write a projection into the scope. Assignment by assignment, so an unchanged field is inert. */
+function project(scope: GitPanelScope, values: GitPanelValues): void {
+  scope.view = values.view;
+  scope.canClone = values.canClone;
+  scope.busy = values.busy;
+  scope.hasError = values.hasError;
+  scope.error = values.error;
+  scope.remoteState = values.remoteState;
+  scope.syncLabel = values.syncLabel;
+  scope.lastUpdated = values.lastUpdated;
+  scope.hasLastUpdated = values.hasLastUpdated;
+  scope.pullLabel = values.pullLabel;
+  scope.pushLabel = values.pushLabel;
+  scope.branchName = values.branchName;
+  scope.branchValue = values.branchValue;
+  scope.branchOptions = values.branchOptions;
+  scope.subTab = values.subTab;
+  scope.changesLabel = values.changesLabel;
+  scope.commitMessage = values.commitMessage;
+  scope.hasStaged = values.hasStaged;
+  scope.stagedCount = values.stagedCount;
+  scope.stagedFiles = values.stagedFiles;
+  scope.changedCount = values.changedCount;
+  scope.hasUnstaged = values.hasUnstaged;
+  scope.filesState = values.filesState;
+  scope.groups = values.groups;
+  scope.historyState = values.historyState;
+  scope.commits = values.commits;
+}
+
+/** The scope's starting shape, before the first projection lands on it. */
+function emptyValues(): GitPanelValues {
+  return {
+    branchName: "",
+    branchOptions: [],
+    branchValue: "",
+    busy: false,
+    canClone: false,
+    changedCount: "0",
+    changesLabel: "Local Changes",
+    commitMessage: "",
+    commits: [],
+    error: "",
+    filesState: "empty",
+    groups: [],
+    hasError: false,
+    hasLastUpdated: false,
+    hasStaged: false,
+    hasUnstaged: false,
+    historyState: "empty",
+    lastUpdated: "",
+    pullLabel: "Pull",
+    pushLabel: "Push",
+    remoteState: "local",
+    stagedCount: "0",
+    stagedFiles: [],
+    subTab: "changes",
+    syncLabel: "",
+    view: "loading",
+  };
+}
+
+/**
+ * Mount the Source Control document into `container`, which is the `.panel-content` the Navigator
+ * just painted.
+ *
+ * Nothing is called on the elements, 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 (guidelines §1.1, "await the
+ * element").
+ */
+export function mountGitPanelSurface(
+  container: HTMLElement,
+  values: GitPanelValues,
+  actions: GitPanelActions,
+): GitPanelSurfaceHandle {
+  const scope = reactive<GitPanelScope>({
+    ...emptyValues(),
+    ...actions,
+  }) as GitPanelScope;
+  project(scope, values);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  void mountSurface("git-panel", scope, container).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    /* While the mount is still in flight there is nothing in the container to ask about, so the
+       answer is simply whether this handle is still wanted — answering no would start a second
+       mount racing the first. Once mounted, the question is whether the root is still where it was
+       put: a Navigator that painted another panel cleared this document out from under it. */
+    connected: () =>
+      !disposed && (mounted === null || (mounted.root as Node).parentNode === container),
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (next) => {
+      project(scope, next);
+    },
+  };
+}

package/src/surfaces/github-auth.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioGithubAuth",
+  "$description": "The RFC 8628 device flow's waiting room: the code GitHub minted, the page to type it into, and a Cancel. A `jx-dialog`, so the platform owns modality, Escape, focus restoration and the backdrop — and it is the reason the dialog has no confirm button at all: the answer arrives from GitHub over a poll rather than from anything the reader can press here, so a primary button would be a control with nothing to do. Nothing in this document talks to GitHub: `github/github-auth.ts` keeps the client id, the poll loop, its failure budget and every report the three outcomes raise.",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": "Sign in to GitHub",
+    "confirmLabel": "",
+    "cancelLabel": "Cancel",
+    "size": "sm"
+  },
+  "attributes": {
+    "part": "github-auth"
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/cancel"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "style": {
+    "$description": "Four `.github-auth-*` rules in `styles/overlays.css` become the parts below, and two things in them do not travel. `.github-auth-dialog`'s `padding: 16px 0` was the card's own body padding drawn by hand, and `jx-dialog` already pads its body; `.github-auth-dialog p { font-size: 13px }` was a body size this surface picked for itself, and what the paragraphs now inherit is the dialog's own `--jx-text-md`. The `8px 0` margins go with them — the column is a flex column with a gap, so a margin between two rows would be a second opinion about the same space. The code keeps its 24px, which is above the token scale on purpose: it is a string the reader has to copy onto another screen, and reading it out loud is the whole job of this dialog.",
+    "& [part=\"device\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "alignItems": "center",
+      "gap": "var(--jx-space-3)",
+      "textAlign": "center"
+    },
+    "& [part=\"lede\"], & [part=\"waiting\"]": {
+      "margin": "0"
+    },
+    "& [part=\"code\"]": {
+      "$description": "`<code>`, not a styled `<div>`: this is a literal string to be transcribed, and the element that says so is also the one a reader's own stylesheet and a screen reader's character-by-character mode already know about.",
+      "fontFamily": "var(--font-mono)",
+      "fontSize": "24px",
+      "fontWeight": "700",
+      "letterSpacing": "2px",
+      "padding": "var(--jx-space-3) var(--jx-space-4)",
+      "background": "var(--hover-bg)",
+      "borderRadius": "var(--radius)"
+    },
+    "& [part=\"link\"]": {
+      "$description": "The blue this carried as a `var(--accent, …)` fallback is gone: `--accent` is declared on `:root` in `styles/tokens.css`, so the fallback could only ever have painted when the token was missing — which is a theme fault to fix rather than a colour to hard-code.",
+      "color": "var(--accent)",
+      "textDecoration": "underline"
+    },
+    "& [part=\"waiting\"]": {
+      "color": "var(--fg-dim)",
+      "fontStyle": "italic"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "device"
+      },
+      "children": [
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "lede"
+          },
+          "textContent": "Enter this code on GitHub to authorize Jx Studio:"
+        },
+        {
+          "tagName": "code",
+          "attributes": {
+            "part": "code"
+          },
+          "textContent": "${state.userCode}"
+        },
+        {
+          "tagName": "a",
+          "attributes": {
+            "part": "link",
+            "href": "${state.verificationUri}",
+            "target": "_blank",
+            "rel": "noreferrer"
+          },
+          "textContent": "Open ${state.verificationUri}"
+        },
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "waiting"
+          },
+          "textContent": "Waiting for authorization…"
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/github-auth.ts

@@ -0,0 +1,139 @@
+/// <reference lib="dom" />
+/**
+ * The GitHub device-flow waiting room, as a mounted document.
+ *
+ * `github/github-auth.ts` is the flow — the client id, the device-code request, the poll loop, its
+ * failure budget and the three reports the outcomes raise — and this is the surface it draws into:
+ * the code GitHub minted, the page to type it into, and the one answer the reader can give.
+ *
+ * **There is nothing to update.** Both values are minted once by the device-code request and are
+ * dead the moment the flow ends, so the handle offers `close` and no `update`: a code that changed
+ * under the reader mid-transcription would be a defect rather than a feature, and a handle that
+ * could express it would invite one.
+ *
+ * **The dialog has no confirm.** The answer arrives from GitHub over a poll rather than from
+ * anything on screen, so the document sets `confirmLabel` empty and `jx-dialog` draws Cancel alone.
+ * A dialog that reports its own dismissal is the whole contract here: `onClosed` fires once, for
+ * the platform's `close` and for this module's, and the flow stops polling on it.
+ *
+ * **Await the ELEMENT, not just the mount.** `mountSurface` resolving means the DOCUMENT rendered;
+ * a `jx-dialog`'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. `whenReady` is
+ * shared with `surfaces/dialog.ts` rather than reimplemented.
+ *
+ * @docs studio/publish/github
+ */
+
+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 githubAuthDoc from "./github-auth.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("github-auth", githubAuthDoc as unknown as JxDocument);
+
+export interface GithubAuthSurfaceOptions {
+  /** Where the dialog is mounted — the dialog layer, handed in so this never reaches back. */
+  layer: HTMLElement;
+  /** The user code GitHub minted, exactly as it must be typed. */
+  userCode: string;
+  /** The page the code is typed into. Printed in full, because the reader may retype it. */
+  verificationUri: string;
+  /** 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 GithubAuthSurfaceHandle {
+  /** The slot in the dialog layer that carries the region. */
+  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 GithubAuthScope extends Record<string, unknown> {
+  userCode: string;
+  verificationUri: string;
+  cancel: () => void;
+  closed: () => void;
+}
+
+/** Put the code up. The handle's `ready` resolves once the dialog is showing. */
+export function openGithubAuthSurface(options: GithubAuthSurfaceOptions): GithubAuthSurfaceHandle {
+  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. `pointer-events` INHERITS, and the top layer
+     changes paint order rather than inheritance, so a modal `<dialog>` in a slot that skipped this
+     is painted above everything and hit-tests to nothing. */
+  slot.style.pointerEvents = "auto";
+  slot.setAttribute(REGION_ATTR, overlayRegion("dialog", "github-auth"));
+  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, which `close()`
+   * provokes, and `close()` on a dialog that never got as far as being shown — which is the
+   * ordinary end of this flow, because the token usually arrives while the dialog is still up.
+   */
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.onClosed();
+  };
+
+  const scope = reactive<GithubAuthScope>({
+    cancel: () => {
+      options.onCancel();
+    },
+    closed: finish,
+    userCode: options.userCode,
+    verificationUri: options.verificationUri,
+  }) as GithubAuthScope;
+
+  let mounted: SurfaceHandle | null = null;
+  const ready = mountSurface("github-auth", scope, slot).then(async (surface) => {
+    mounted = surface;
+    const element = surface.root as HTMLElement;
+    if (closed) {
+      surface.dispose();
+      return element;
+    }
+    await whenReady(element);
+    if (closed) {
+      return element;
+    }
+    showModal(element);
+    return element;
+  });
+
+  return {
+    close() {
+      /* Guarded on the WORK rather than on `closed`, and the difference is a slot that would
+         otherwise be left behind: the platform's own `close` runs `finish()` before any caller
+         reaches here, so a `close()` that returned early on `closed` would take the dialog down and
+         leave its host div in the layer. Every line below is idempotent instead. */
+      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);
+      }
+      // A mount that has not landed yet is disposed by `ready` when it does — `finish` tells it so.
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+      finish();
+    },
+    host: slot,
+    ready,
+  };
+}