@jxsuite/studio 4.1.0 → 5.0.0

package/src/surfaces/ai-credentials-form.json

@@ -0,0 +1,332 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioAiCredentialsForm",
+  "$description": "The AI provider credentials form every gate embeds below the keyless offer: a key, a model, an endpoint, and the two buttons that keep or abandon them. Everything here is a projection — `ui/ai-credentials-form.ts` keeps the drafts, decides what a fetch is sent with, what Save actually persists and whether Cancel is on offer at all. This document never reads a setting and never calls the proxy.",
+  "tagName": "div",
+  "attributes": {
+    "part": "ai-creds-form",
+    "role": "group",
+    "aria-label": "AI provider key"
+  },
+  "style": {
+    "$description": "The seven `.ai-creds*` rules from `styles/shell.css`, keyed on `part` and repaired on the way. Three of them read `--spectrum-font-size-50`, which resolves only inside `<sp-theme>`; this document is mounted into a plain host inside the gate, outside that element, so each would silently have taken its hard-coded 11px fallback. The 10px column gap comes onto the kit's spacing scale at 8px.",
+    "display": "flex",
+    "flexDirection": "column",
+    "gap": "var(--jx-space-3)",
+    "width": "100%",
+    "maxWidth": "320px",
+    "textAlign": "left",
+    "& [part=\"title\"]": {
+      "$description": "Centred over a left-aligned column: the form is a titled block, not a list of labelled rows.",
+      "alignSelf": "center",
+      "fontWeight": "600"
+    },
+    "& [part=\"note\"]": {
+      "$description": "Where the key goes and where it does not. Quiet, because it is reassurance rather than instruction.",
+      "margin": "0",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"label\"]": {
+      "$description": "The one visible heading in the column, over the field whose catalogue is fetched by the button under it.",
+      "marginTop": "var(--jx-space-2)",
+      "fontWeight": "500",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"key\"], & [part=\"model\"], & [part=\"endpoint\"]": {
+      "$description": "Every control takes the column's width; the kit's fields are inline-flex by default.",
+      "width": "100%"
+    },
+    "& [part=\"models\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-3)"
+    },
+    "& [part=\"models-error\"]": {
+      "$description": "Why the listing did not finish, beside the button that would try it again. Named `models-error` rather than `error` because the kit's own fields render a permanent `[part=\"error\"]` region of their own, and a surface that reused the name would be addressing three empty paragraphs before it reached its own.",
+      "color": "var(--danger)",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"actions\"]": {
+      "$description": "Buttons at the end of the column, in the order a dismissal precedes a commitment.",
+      "display": "flex",
+      "alignSelf": "flex-end",
+      "gap": "var(--jx-space-3)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "title"
+      },
+      "textContent": "AI provider key"
+    },
+    {
+      "tagName": "p",
+      "attributes": {
+        "part": "note"
+      },
+      "textContent": "${state.intro}"
+    },
+    {
+      "tagName": "jx-textfield",
+      "attributes": {
+        "part": "key"
+      },
+      "$props": {
+        "label": "AI provider key",
+        "type": "password",
+        "size": "sm",
+        "placeholder": "sk-… or any compatible key",
+        "value": {
+          "$ref": "#/state/keyDraft"
+        }
+      },
+      "oninput": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/setKey"
+            },
+            "value": [
+              {
+                "$ref": "event#/target/value"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "label"
+      },
+      "textContent": "Model"
+    },
+    {
+      "$description": "One `jx-combobox` with `allows-custom-value` over the catalogue: the field IS the value, and the rows under it are what the provider happened to list. It was one `sp-combobox`, then — while the kit had no combobox — a text field and a `jx-select` bound to ONE draft, because a self-hosted id is the normal case and typing one is why the field exists. The element is built for exactly that: it filters nothing, so `options` is the catalogue as fetched; a keystroke highlights nothing, so Enter commits what was typed; and with no rows it is a text field with no chevron, which is what the form is until a listing lands. Both handlers read the ELEMENT's value, `event.currentTarget`, rather than the event target's. Not because the two ever disagree: a pick says `input` from the element, typing lets the control's own bubble, and when a listed id typed in the wrong case commits, the element has written the row's spelling to its own `value` AND to the control before the control's `change` reaches here, the runtime's bindings being synchronous — so `event.target.value` reads the same string, and no test can tell the two refs apart. `currentTarget` is read because the element is the thing whose value the form means: the ref names the contract rather than the node that happened to dispatch.",
+      "tagName": "jx-combobox",
+      "attributes": {
+        "part": "model"
+      },
+      "$props": {
+        "label": "Model ID",
+        "size": "sm",
+        "placeholder": "Model ID (e.g. gpt-4o, claude-sonnet-4-20250514, etc.)",
+        "allowsCustomValue": true,
+        "value": {
+          "$ref": "#/state/modelDraft"
+        },
+        "options": {
+          "$ref": "#/state/modelOptions"
+        }
+      },
+      "oninput": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/setModel"
+            },
+            "value": [
+              {
+                "$ref": "event#/currentTarget/value"
+              }
+            ]
+          }
+        ]
+      },
+      "onchange": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/setModel"
+            },
+            "value": [
+              {
+                "$ref": "event#/currentTarget/value"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "models"
+      },
+      "children": [
+        {
+          "tagName": "jx-button",
+          "attributes": {
+            "part": "fetch"
+          },
+          "$props": {
+            "size": "sm",
+            "disabled": {
+              "$ref": "#/state/modelsLoading"
+            }
+          },
+          "onclick": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/fetchModels"
+                },
+                "value": []
+              }
+            ]
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "textContent": "${state.fetchLabel}"
+            }
+          ]
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "error-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/hasError"
+          },
+          "cases": {
+            "true": {
+              "tagName": "span",
+              "attributes": {
+                "part": "models-error",
+                "role": "status"
+              },
+              "textContent": "${state.modelsError}"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "jx-textfield",
+      "attributes": {
+        "part": "endpoint"
+      },
+      "$props": {
+        "label": "Endpoint",
+        "size": "sm",
+        "placeholder": "Endpoint (optional, e.g. http://localhost:11434/v1)",
+        "value": {
+          "$ref": "#/state/baseUrlDraft"
+        }
+      },
+      "oninput": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/setBaseUrl"
+            },
+            "value": [
+              {
+                "$ref": "event#/target/value"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "actions"
+      },
+      "children": [
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "cancel-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/haveKey"
+          },
+          "cases": {
+            "true": {
+              "$description": "Only offered once a key exists: with nothing stored there is nothing to go back to, and a Cancel that abandons an empty form to an empty form is a button that does nothing.",
+              "tagName": "jx-button",
+              "attributes": {
+                "part": "cancel"
+              },
+              "$props": {
+                "size": "sm"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/cancel"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Cancel"
+                }
+              ]
+            }
+          }
+        },
+        {
+          "tagName": "jx-button",
+          "attributes": {
+            "part": "save"
+          },
+          "$props": {
+            "size": "sm",
+            "variant": "accent"
+          },
+          "onclick": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/save"
+                },
+                "value": []
+              }
+            ]
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "textContent": "Save"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/ai-credentials-form.ts

@@ -0,0 +1,151 @@
+/// <reference lib="dom" />
+/**
+ * The AI provider credentials form as a mounted document.
+ *
+ * `ui/ai-credentials-form.ts` is the flow — it holds the three drafts, decides which credentials a
+ * listing is made with, what Save persists and re-reads, and whether Cancel is on offer — 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 form beside the keyless offer, 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 — which
+ * matters more here than anywhere else in the batch, because this surface is three fields a reader
+ * is typing into and a repaint that rebuilt them would take the caret with it. The model field is
+ * the one that makes this concrete: it is a `jx-combobox` whose catalogue arrives from a fetch
+ * AFTER the field is drawn, and a rebuild on that arrival would have lost whatever id the reader
+ * had typed while they waited.
+ *
+ * The host is `display: contents` for the same reason `surfaces/ai-managed-connect.ts` gives: 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 `max-width` below it with it.
+ *
+ * @docs studio/ai
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import credentialsDoc from "./ai-credentials-form.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("ai-credentials-form", credentialsDoc as unknown as JxDocument);
+
+/** One row of the listed catalogue, as the combobox draws it. */
+export interface CredentialsModelRow {
+  /** The model id — the row's key, and what a pick writes into the model draft. */
+  value: string;
+  /** What the row reads. */
+  label: string;
+}
+
+/** What the form says right now. Every field is the flow's, never a state it derives. */
+export interface AiCredentialsView {
+  /** The line under the title: where the key goes, and where it does not. */
+  intro: string;
+  /** The three drafts, exactly as the flow holds them. */
+  keyDraft: string;
+  modelDraft: string;
+  baseUrlDraft: string;
+  /** The catalogue the last successful listing returned; empty draws no chevron on the field. */
+  models: CredentialsModelRow[];
+  /** A listing is in flight: the button says so and refuses a second one. */
+  modelsLoading: boolean;
+  /** What the fetch button reads — including while it is working, and once a list has landed. */
+  fetchLabel: string;
+  /** Why the last listing did not finish. Empty draws nothing. */
+  modelsError: string;
+  /** A key is already stored, so abandoning the drafts means something. */
+  haveKey: boolean;
+}
+
+/** Everything the reader can do here. */
+export interface AiCredentialsActions {
+  setKey: (value: string) => void;
+  setModel: (value: string) => void;
+  setBaseUrl: (value: string) => void;
+  fetchModels: () => void;
+  save: () => void;
+  cancel: () => void;
+}
+
+export interface AiCredentialsSurface {
+  /** 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: AiCredentialsView) => void;
+}
+
+/** What the document discriminates on, derived here so the flow never has to spell it. */
+interface AiCredentialsFlags {
+  /** Whether there is a refusal to draw beside the fetch button. */
+  hasError: boolean;
+  /** The catalogue as the kit's combobox draws it — the list, never a corpus it matches against. */
+  modelOptions: CredentialsModelRow[];
+}
+
+interface AiCredentialsScope
+  extends Record<string, unknown>, AiCredentialsView, AiCredentialsActions, AiCredentialsFlags {}
+
+/** The view plus the flags the document renders from. */
+function derive(view: AiCredentialsView): AiCredentialsView & AiCredentialsFlags {
+  return {
+    ...view,
+    hasError: view.modelsError !== "",
+    modelOptions: view.models,
+  };
+}
+
+/**
+ * Create the form'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.
+ *
+ * @param {AiCredentialsView} view What the form says to begin with.
+ * @param {AiCredentialsActions} actions What each control does.
+ * @returns {AiCredentialsSurface}
+ */
+export function createAiCredentialsSurface(
+  view: AiCredentialsView,
+  actions: AiCredentialsActions,
+): AiCredentialsSurface {
+  const host = document.createElement("div");
+  host.style.display = "contents";
+  const scope = reactive({ ...derive(view), ...actions }) as AiCredentialsScope;
+
+  /** `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-credentials-form", 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 empty the field the reader is typing in. 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-managed-connect.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioAiManagedConnect",
+  "$description": "The keyless \"Connect Cloudflare\" offer every AI credentials gate draws above the key form: a lede that says which of the two paths is recommended, the button that runs the hosted OAuth flow, whatever the last attempt refused with, and the line that hands the reader down to the key form beneath. Everything here is a projection — `ui/ai-managed-connect.ts` keeps the flow, decides whether the offer applies at all, and words the lede and the button for a fresh grant or a lapsed one. This document never learns what `cf_reconnect_required` is.",
+  "tagName": "div",
+  "attributes": {
+    "part": "managed-connect",
+    "data-jx-recommended": "cloudflare"
+  },
+  "style": {
+    "$description": "The four `.ai-managed-connect*` rules from `styles/shell.css`, keyed on `part` and repaired on the way. Both font sizes read `--spectrum-font-size-75` / `--spectrum-font-size-50`, which resolve only inside `<sp-theme>`; this document is mounted into a plain host inside the gate, outside that element, so every one of them would silently have taken its hard-coded fallback. The two off-scale gaps (10px and 6px) come onto the kit's spacing scale, which is what they were approximating.",
+    "display": "flex",
+    "flexDirection": "column",
+    "alignItems": "center",
+    "gap": "var(--jx-space-4)",
+    "width": "100%",
+    "& [part=\"intro\"]": {
+      "$description": "The lede reads as the recommendation, so it carries the primary foreground the divider beneath it does not. It is centred and narrow because it sits over a centred button rather than in a column of prose.",
+      "margin": "0",
+      "color": "var(--fg)",
+      "fontSize": "var(--jx-text-md)",
+      "maxWidth": "280px",
+      "textAlign": "center"
+    },
+    "& [part=\"error\"]": {
+      "$description": "Why the last attempt did not finish, said under the button that would try it again. Narrower than the lede: a refusal is a sentence to read once, not the thing the surface is about.",
+      "margin": "0",
+      "color": "var(--danger)",
+      "fontSize": "var(--jx-text-sm)",
+      "maxWidth": "260px"
+    },
+    "& [part=\"divider\"]": {
+      "$description": "The hand-off to the key form below. It is a label rather than a rule because both paths stay on offer — this is not a separator between a choice and its alternative, it is the second choice being introduced.",
+      "margin": "var(--jx-space-3) 0 0",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "p",
+      "attributes": {
+        "part": "intro"
+      },
+      "textContent": "${state.intro}"
+    },
+    {
+      "tagName": "jx-button",
+      "attributes": {
+        "part": "connect"
+      },
+      "$props": {
+        "size": "sm",
+        "variant": "accent",
+        "disabled": {
+          "$ref": "#/state/busy"
+        }
+      },
+      "onclick": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/connect"
+            },
+            "value": []
+          }
+        ]
+      },
+      "children": [
+        {
+          "tagName": "span",
+          "textContent": "${state.buttonLabel}"
+        }
+      ]
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "error-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/hasError"
+      },
+      "cases": {
+        "true": {
+          "tagName": "p",
+          "attributes": {
+            "part": "error"
+          },
+          "textContent": "${state.error}"
+        }
+      }
+    },
+    {
+      "tagName": "p",
+      "attributes": {
+        "part": "divider"
+      },
+      "textContent": "— or bring your own key —"
+    }
+  ]
+}