@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/ai-managed-connect.ts

@@ -0,0 +1,123 @@
+/// <reference lib="dom" />
+/**
+ * The keyless "Connect Cloudflare" offer, as a mounted document.
+ *
+ * `ui/ai-managed-connect.ts` is the flow — it decides whether a managed platform can broker Workers
+ * AI at all, what a finished OAuth round trip meant, and which words a fresh grant and a lapsed one
+ * get — and this is the surface it draws into.
+ *
+ * **The host element belongs to this module, not to the gate.** Every credentials gate is still a
+ * lit template that interpolates the offer beside the key form, so there is no container in the
+ * host to mount into and no way to make one without editing three surfaces this conversion does not
+ * own. So the surface carries its own: one `<div>` per controller, mounted once and handed to lit
+ * as a child value. lit inserts a Node it is given rather than cloning it, and re-inserting the
+ * same node is a no-op, so the document survives every repaint of the gate around it — and when the
+ * offer is withdrawn lit merely `remove()`s the node, which leaves the mount inside it intact for
+ * the next time it is offered.
+ *
+ * The host is `display: contents` for the same reason: the gates lay their children out in a flex
+ * column (`.prefs-assistant` centres them, `.new-project-creds` stretches them), and a wrapper box
+ * would become the flex item in the document root's place and take the `width: 100%` below it with
+ * it.
+ *
+ * @docs studio/ai
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import connectDoc from "./ai-managed-connect.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("ai-managed-connect", connectDoc as unknown as JxDocument);
+
+/** What the offer says right now. Every field is the flow's wording, never a state it derives. */
+export interface ManagedConnectView {
+  /** The recommendation, or the explanation a lapsed grant gets instead. */
+  intro: string;
+  /** What the button reads — including while it is working. */
+  buttonLabel: string;
+  /** A flow already in flight: the button says so and refuses a second one. */
+  busy: boolean;
+  /** Why the last attempt did not finish. Empty draws nothing. */
+  error: string;
+}
+
+/** The one thing the reader can do here. */
+export interface ManagedConnectActions {
+  /** Run the hosted OAuth flow. Read once, when the surface is created. */
+  connect: () => void;
+}
+
+export interface ManagedConnectSurface {
+  /** The element the document lives in — handed to a gate's lit template as a child value. */
+  readonly host: HTMLElement;
+  /** Bring the standing surface up to date, remounting only if its root has been taken away. */
+  update: (view: ManagedConnectView) => void;
+}
+
+/** What the document discriminates on, derived here so the flow never has to spell it. */
+interface ManagedConnectFlags {
+  /** Whether there is a refusal to draw. The `$switch` reads it, so `true` names the case. */
+  hasError: boolean;
+}
+
+interface ManagedConnectScope
+  extends Record<string, unknown>, ManagedConnectView, ManagedConnectActions, ManagedConnectFlags {}
+
+/** The view plus the flag the document switches on. */
+function derive(view: ManagedConnectView): ManagedConnectView & ManagedConnectFlags {
+  return { ...view, hasError: view.error !== "" };
+}
+
+/**
+ * Create the offer's surface, mounted into a host of its own.
+ *
+ * There is no teardown, deliberately: a controller lives as long as the gate that made it, and the
+ * host it owns is the thing lit takes in and out of the page. Withdrawing the offer is a `remove()`
+ * of that node, which leaves the document inside it intact and ready to be inserted again.
+ *
+ * @param {ManagedConnectView} view What the offer says to begin with.
+ * @param {ManagedConnectActions} actions What the button does.
+ * @returns {ManagedConnectSurface}
+ */
+export function createManagedConnectSurface(
+  view: ManagedConnectView,
+  actions: ManagedConnectActions,
+): ManagedConnectSurface {
+  const host = document.createElement("div");
+  host.style.display = "contents";
+  const scope = reactive({ ...derive(view), ...actions }) as ManagedConnectScope;
+
+  /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
+  let handle: SurfaceHandle | null = null;
+  let mounting = false;
+
+  function mount(): void {
+    mounting = true;
+    void mountSurface("ai-managed-connect", scope, host).then((mounted) => {
+      mounting = false;
+      handle = mounted;
+    });
+  }
+
+  mount();
+
+  return {
+    host,
+    update(next) {
+      Object.assign(scope, derive(next));
+      /* A standing mount is only ASSIGNED to: rebuilding it on every repaint of the gate around it
+         would take the button out from under a reader mid-press. The remount below answers the one
+         case assignment cannot — a host the document has been taken out of — and it cannot fire
+         while a mount is in flight, because a record with no handle yet IS the standing one. */
+      if (mounting || (handle !== null && host.contains(handle.root))) {
+        return;
+      }
+      handle?.dispose();
+      handle = null;
+      host.textContent = "";
+      mount();
+    },
+  };
+}

package/src/surfaces/ai-model-picker.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioAiModelPicker",
+  "$description": "The provider's model catalogue as one control, for every surface that chooses a model — the assistant's composer and the New Project Import source. Everything here is a projection: `ui/ai-model-picker.ts` decides which credentials the catalogue was listed under, which rows it holds, which of them is selected and what a failed listing said. This document never fetches anything and never learns what a credential is.",
+  "tagName": "div",
+  "attributes": {
+    "part": "model-picker",
+    "data-width": "${state.width}"
+  },
+  "style": {
+    "$description": "`.ai-model-picker` (shell.css) and `.new-project-import-model` (overlays.css) were the same control at two widths, so the two rules become one attribute the host sets. The wrapper is the flex item now rather than the control, which is what lets the retry button sit beside the picker without the host laying it out.",
+    "display": "flex",
+    "alignItems": "center",
+    "gap": "var(--jx-space-2)",
+    "minWidth": "0",
+    "&[data-width=\"compact\"]": {
+      "$description": "The composer's row: the picker may not push the send button off the end, so it is capped and allowed to shrink.",
+      "maxWidth": "140px"
+    },
+    "&[data-width=\"fill\"]": {
+      "$description": "A field in a form column, where the control takes the column's width.",
+      "width": "100%"
+    },
+    "& [part=\"select\"]": {
+      "minWidth": "0",
+      "flex": "1 1 auto"
+    }
+  },
+  "children": [
+    {
+      "tagName": "jx-select",
+      "attributes": {
+        "part": "select",
+        "title": "${state.hint}"
+      },
+      "$props": {
+        "label": "Model",
+        "size": {
+          "$ref": "#/state/size"
+        },
+        "options": {
+          "$ref": "#/state/options"
+        },
+        "value": {
+          "$ref": "#/state/value"
+        }
+      },
+      "onchange": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/choose"
+            },
+            "value": [
+              {
+                "$ref": "event#/target/value"
+              }
+            ]
+          }
+        ],
+        "description": "The change bubbles out of the inner control, so the picked id is read off the event rather than off the element."
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "retry-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/hasFailure"
+      },
+      "cases": {
+        "true": {
+          "$description": "Retry is a BUTTON beside the picker, not a row inside it. As a row it was a value the select could hold and did not mean — one press left the control reporting `__retry_models__` as the chosen model, and the write that would have corrected it is exactly the write a document's bindings skip when the scope never moved. A button says the same thing and holds no value at all.",
+          "tagName": "jx-button",
+          "attributes": {
+            "part": "retry"
+          },
+          "$props": {
+            "size": {
+              "$ref": "#/state/size"
+            },
+            "quiet": true,
+            "label": "Retry loading models"
+          },
+          "onclick": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/retry"
+                },
+                "value": []
+              }
+            ]
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "textContent": "Retry"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/src/surfaces/ai-model-picker.ts

@@ -0,0 +1,139 @@
+/// <reference lib="dom" />
+/**
+ * The model catalogue as a mounted document.
+ *
+ * `ui/ai-model-picker.ts` is the flow — it decides which credentials a catalogue may be shown for,
+ * when to list, what a failed listing said and where a choice goes — and this is the surface it
+ * draws into.
+ *
+ * **The host element belongs to this module, not to the host surface.** Both callers are still lit
+ * templates that interpolate the picker into a row of their own (`panels/ai-chat/composer.ts`'s
+ * button row, `new-project/import-tab.ts`'s field column), so there is no container in either to
+ * mount into. So the surface carries its own: one `<div>` per controller, mounted once and handed
+ * to lit as a child value. lit inserts a Node it is given rather than cloning it, and re-inserting
+ * the same node is a no-op, so the document survives every repaint of the row around it. This is
+ * the seam `surfaces/ai-managed-connect.ts` established; nothing here is new but the contents.
+ *
+ * The host is `display: contents` for the same reason it is there: both rows lay their children out
+ * themselves (a flex row and a flex column), and a wrapper box would become the flex item in the
+ * document root's place and take the width rule below it with it.
+ *
+ * @docs studio/ai
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import pickerDoc from "./ai-model-picker.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("ai-model-picker", pickerDoc as unknown as JxDocument);
+
+/** One row the control offers. Already a label — the flow decides what a row is called. */
+export interface ModelPickerRow {
+  /** The model id, which is both the row's key and what a choice reports. */
+  value: string;
+  /** What the row reads, including any note the flow attached to it. */
+  label: string;
+  /** A row that stands for a state rather than a model, and so may not be chosen. */
+  disabled?: boolean;
+}
+
+/** How wide the control is drawn. Two hosts, two shapes, and no class between them. */
+export type ModelPickerWidth = "compact" | "fill";
+
+/** What the picker says right now. Every field is the flow's, never a state it derives. */
+export interface ModelPickerView {
+  /** The rows to offer, in order, already including any placeholder the flow wants shown. */
+  options: ModelPickerRow[];
+  /** The id shown as chosen. The flow guarantees the rows contain it. */
+  value: string;
+  /** The control's tooltip: "Model", or what the last listing refused with. */
+  hint: string;
+  /** Why the last listing did not finish. Empty draws no retry button. */
+  failure: string;
+  /** The kit control size, `"sm"` or `"md"` — the host's to set. */
+  size: "sm" | "md";
+  /** Which of the two shapes to draw. */
+  width: ModelPickerWidth;
+}
+
+/** The two things the reader can do here. */
+export interface ModelPickerActions {
+  /** A row was picked. Read once, when the surface is created. */
+  choose: (id: string) => void;
+  /** List again after a failure. */
+  retry: () => void;
+}
+
+export interface ModelPickerSurface {
+  /** The element the document lives in — handed to a host's lit template as a child value. */
+  readonly host: HTMLElement;
+  /** Bring the standing surface up to date, remounting only if its root has been taken away. */
+  update: (view: ModelPickerView) => void;
+}
+
+/** What the document discriminates on, derived here so the flow never has to spell it. */
+interface ModelPickerFlags {
+  /** Whether there is a refusal, and so a retry button. The `$switch` reads it. */
+  hasFailure: boolean;
+}
+
+interface ModelPickerScope
+  extends Record<string, unknown>, ModelPickerView, ModelPickerActions, ModelPickerFlags {}
+
+/** The view plus the flag the document switches on. */
+function derive(view: ModelPickerView): ModelPickerView & ModelPickerFlags {
+  return { ...view, hasFailure: view.failure !== "" };
+}
+
+/**
+ * Create the picker's surface, mounted into a host of its own.
+ *
+ * There is no teardown, deliberately: a controller lives as long as the surface that made it, and
+ * the host it owns is the thing lit takes in and out of the page.
+ *
+ * @param {ModelPickerView} view What the picker offers to begin with.
+ * @param {ModelPickerActions} actions What a pick and a retry do.
+ * @returns {ModelPickerSurface}
+ */
+export function createModelPickerSurface(
+  view: ModelPickerView,
+  actions: ModelPickerActions,
+): ModelPickerSurface {
+  const host = document.createElement("div");
+  host.style.display = "contents";
+  const scope = reactive({ ...derive(view), ...actions }) as ModelPickerScope;
+
+  /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
+  let handle: SurfaceHandle | null = null;
+  let mounting = false;
+
+  function mount(): void {
+    mounting = true;
+    void mountSurface("ai-model-picker", scope, host).then((mounted) => {
+      mounting = false;
+      handle = mounted;
+    });
+  }
+
+  mount();
+
+  return {
+    host,
+    update(next) {
+      Object.assign(scope, derive(next));
+      /* A standing mount is only ASSIGNED to: rebuilding it on every repaint of the row around it
+         would take the control out from under a reader who has it open. The remount below answers
+         the one case assignment cannot — a host the document has been taken out of — and it cannot
+         fire while a mount is in flight, because a record with no handle yet IS the standing one. */
+      if (mounting || (handle !== null && host.contains(handle.root))) {
+        return;
+      }
+      handle?.dispose();
+      handle = null;
+      host.textContent = "";
+      mount();
+    },
+  };
+}