@jxsuite/studio 2.0.1 → 2.1.0

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

@@ -2,9 +2,18 @@
 /**
  * Ai-credentials-form.ts — reusable AI provider credentials form (key / model / endpoint).
  *
- * Extracted from the ai-panel key gate so other hosts (e.g. the New Project modal) can embed the
- * same form. All draft/model-list state lives inside the closure, so multiple instances never
- * share state. Persists via src/services/ai-settings.ts on Save.
+ * Embedded by every host that needs a provider configured — **Preferences › Assistant** (⌘,) and the
+ * New Project modal's Import/Agent gates. All draft/model-list state lives inside the closure, so
+ * multiple instances never share state. Persists via src/services/ai-settings.ts on Save.
+ *
+ * The interim `Assistant: Settings…` dialog that used to host it is deleted: a provider key is an
+ * application setting, and the surface that owns application settings is also the one that can list
+ * it and revoke it (plan §9.3). Nothing about this form changed for the move, which is the argument
+ * for it having been a reusable form rather than a section of a dialog.
+ *
+ * Built from Spectrum controls with its layout in `styles/shell.css`: a roaming credential the user
+ * configures once does not get its own bespoke inputs, and it certainly does not get 200-character
+ * inline `style=` strings that stop responding the moment the theme changes.
  *
  * @license MIT
  */
@@ -118,35 +127,34 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
   function render(): TemplateResult {
     const haveKey = hasOpenAiKey();
     return html`
-      <div
-        class="ai-creds-form"
-        style="display:flex;flex-direction:column;gap:10px;max-width:320px;text-align:left"
-      >
-        <div style="font-weight:600;align-self:center">AI provider key</div>
-        ${
-          opts.intro === undefined
-            ? html`
-                <div style="font-size:11px;color:var(--fg-dim)">
+      <div class="ai-creds-form">
+        <div class="ai-creds-title">AI provider key</div>
+        <div class="ai-creds-note">
+          ${
+            opts.intro === undefined
+              ? html`
                   Any OpenAI-compatible key works. Stored locally in this browser; sent only to the
                   Studio proxy (never to a third party except your chosen endpoint).
-                </div>
-              `
-            : html`<div style="font-size:11px;color:var(--fg-dim)">${opts.intro}</div>`
-        }
-        <input
+                `
+              : opts.intro
+          }
+        </div>
+        <sp-textfield
+          class="ai-creds-field"
           type="password"
-          style="width:100%;box-sizing:border-box;padding:6px 8px;border-radius:4px;border:1px solid var(--border);background:var(--bg-input);color:var(--fg);font-size:12px"
+          size="s"
           placeholder="sk-… or any compatible key"
           .value=${keyDraft}
           @input=${(e: Event) => {
             keyDraft = (e.target as HTMLInputElement).value;
           }}
-        />
-        <div style="font-weight:500;font-size:11px;margin-top:4px">Model</div>
+        ></sp-textfield>
+        <div class="ai-creds-label">Model</div>
         ${
           availableModels.length > 0
             ? html`
                 <sp-combobox
+                  class="ai-creds-field"
                   size="s"
                   allows-custom-value
                   .value=${modelDraft}
@@ -163,18 +171,18 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
                 </sp-combobox>
               `
             : html`
-                <input
-                  type="text"
-                  style="width:100%;box-sizing:border-box;padding:6px 8px;border-radius:4px;border:1px solid var(--border);background:var(--bg-input);color:var(--fg);font-size:12px"
+                <sp-textfield
+                  class="ai-creds-field"
+                  size="s"
                   placeholder="Model ID (e.g. gpt-4o, claude-sonnet-4-20250514, etc.)"
                   .value=${modelDraft}
                   @input=${(e: Event) => {
                     modelDraft = (e.target as HTMLInputElement).value;
                   }}
-                />
+                ></sp-textfield>
               `
         }
-        <div style="display:flex;gap:8px;align-items:center">
+        <div class="ai-creds-models">
           <sp-button size="s" variant="secondary" ?disabled=${modelsLoading} @click=${fetchModels}>
             ${
               modelsLoading
@@ -184,22 +192,18 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
                   : "Fetch models"
             }
           </sp-button>
-          ${
-            modelsError
-              ? html`<span style="font-size:10px;color:var(--danger)">${modelsError}</span>`
-              : nothing
-          }
+          ${modelsError ? html`<span class="ai-creds-error">${modelsError}</span>` : nothing}
         </div>
-        <input
-          type="text"
-          style="width:100%;box-sizing:border-box;padding:6px 8px;border-radius:4px;border:1px solid var(--border);background:var(--bg-input);color:var(--fg);font-size:12px"
+        <sp-textfield
+          class="ai-creds-field"
+          size="s"
           placeholder="Endpoint (optional, e.g. http://localhost:11434/v1)"
           .value=${baseUrlDraft}
           @input=${(e: Event) => {
             baseUrlDraft = (e.target as HTMLInputElement).value;
           }}
-        />
-        <div style="display:flex;gap:8px;align-self:flex-end">
+        ></sp-textfield>
+        <div class="ai-creds-actions">
           ${
             haveKey
               ? html`<sp-button size="s" variant="secondary" @click=${cancel}>Cancel</sp-button>`

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

@@ -94,7 +94,13 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
     return html`
       <div class="ai-managed-connect">
         <div>Use Workers AI on your own Cloudflare account — no API key needed.</div>
-        <sp-button size="s" ?disabled=${busy} @click=${() => void connect()}>
+        <sp-button
+          size="s"
+          ?disabled=${busy}
+          @click=${() => {
+            void connect();
+          }}
+        >
           ${busy ? "Connecting…" : "Connect Cloudflare"}
         </sp-button>
         ${connectError ? html`<div class="ai-managed-connect-error">${connectError}</div>` : nothing}

package/src/ui/dynamic-slot.ts

@@ -1,59 +1,120 @@
 /// <reference lib="dom" />
 /**
- * Dynamic-slot — the shared "make this dynamic" control for any bindable document position.
+ * Dynamic-slot — the shared Value Source control for any bindable document position.
  *
- * Renders the panel-provided static widget plus a label-side mode button that cycles the value up
- * the Rule of Least Power ladder (spec §2.2): literal → $ref pointer → ${} template → $expression.
- * Capability-driven: each slot offers only the modes its schema position allows, so panels stay
- * decoupled from which rungs are blessed where. Each mode's last value is remembered per field for
- * the session, so cycling back to an earlier mode restores what the user had there.
+ * Renders the panel-provided static widget plus a label-side chip that names, in plain language,
+ * how this value is produced — Fixed value / From data… / Mixed text / Formula
+ * (`ui/value-source.ts` owns the vocabulary). Clicking the chip opens a picker listing every rung
+ * the position permits, so **any rung is one action away**. It used to be a cycle ring: `$ref →
+ * literal` meant passing through `${}`, committing a template to the document on the way past, and
+ * the only way to know where the next click would land was the tooltip.
+ *
+ * The rungs are not declared by the caller but **derived from the schema** at the named position
+ * (plan §6.3): `caps` is a {@link SlotPosition}, or a schema handed in for the one case a position
+ * name cannot cover — a field in an extension's config form, whose schema arrives at runtime. There
+ * is no way for a caller to state a rung list of its own.
+ *
+ * Each mode's last value is remembered per field for the session, so switching back to an earlier
+ * mode restores what the user had there. The same memory is exported for the Events tab, which
+ * offers the same ladder in its own layout.
  */
 
 import { html, nothing } from "lit-html";
 import { live } from "lit-html/directives/live.js";
-import { isRef, isTemplateString } from "@jxsuite/schema/guards";
+import { isRef } from "@jxsuite/schema/guards";
 import { cloneValue } from "../tabs/doc-op-apply";
 import { activeTab } from "../workspace/workspace";
 import { renderExpressionEditor } from "./expression-editor";
+import { VALUE_SOURCE_HINTS, VALUE_SOURCE_LABELS, slotCaps, slotMode } from "./value-source";
 
 import type { TemplateResult } from "lit-html";
 import type { EditorPreview } from "./expression-editor";
 import type { JxStateDefinition } from "@jxsuite/schema/types";
 import type { JsonValue } from "../types";
+import type { SlotCapsSource, SlotMode } from "./value-source";
 
-export type SlotMode = "literal" | "ref" | "template" | "expression";
-
-const MODE_LABELS: Record<SlotMode, string> = {
-  expression: "fx",
-  literal: "abc",
-  ref: "$ref",
-  template: "${}",
-};
-
-const MODE_NOUNS: Record<SlotMode, string> = {
-  expression: "expression",
-  literal: "static",
-  ref: "signal binding",
-  template: "template literal",
-};
+export type { SlotCapsSource, SlotMode, SlotPosition } from "./value-source";
+export { slotCaps, slotMode } from "./value-source";
 
 /*
- * Session memory of each field's last value per mode, so cycling modes round-trips user input.
+ * Session memory of each field's last value per mode, so switching modes round-trips user input.
  * Keyed `${tabId}|${fieldKey}|${mode}`; the mode key is derived from the value at stash time, so a
  * restore always lands a value whose slotMode() matches the target mode. `undefined` is a
  * legitimate stash (cleared literal), hence Map.has() discrimination on recall.
  */
 const slotModeMemory = new Map<string, JsonValue | undefined>();
 
-/** Test hook: drop all remembered per-mode field values. */
+/*
+ * The rung each field is CURRENTLY being edited at, keyed `${tabId}|${fieldKey}`.
+ *
+ * Without this the rendered rung was re-sniffed from the document value on every render, so typing
+ * `${` into a Fixed value field swapped the widget out from under the cursor mid-keystroke — and
+ * typing the closing brace away swapped it back. A keystroke can only ever move a value between
+ * the literal and mixed-text rungs (both are plain strings); every other transition needs a
+ * structural change to the value, which a text edit cannot make. So those two rungs hold once
+ * entered, and everything else still follows the document.
+ */
+const slotModeRendered = new Map<string, SlotMode>();
+
+/** Test hook: drop all remembered per-mode field values and per-field rungs. */
 export function resetSlotModeMemory(): void {
   slotModeMemory.clear();
+  slotModeRendered.clear();
 }
 
 function memoryKey(fieldKey: string, mode: SlotMode): string {
   return `${activeTab.value?.id ?? "-"}|${fieldKey}|${mode}`;
 }
 
+function fieldScopeKey(fieldKey: string): string {
+  return `${activeTab.value?.id ?? "-"}|${fieldKey}`;
+}
+
+/** Remember `value` as this field's representation at `mode`, for a later switch back. */
+export function stashSlotValue(
+  fieldKey: string,
+  mode: SlotMode,
+  value: JsonValue | undefined,
+): void {
+  slotModeMemory.set(memoryKey(fieldKey, mode), cloneValue(value));
+}
+
+/** Whether this field has a remembered representation at `mode`. */
+export function hasStashedSlotValue(fieldKey: string, mode: SlotMode): boolean {
+  return slotModeMemory.has(memoryKey(fieldKey, mode));
+}
+
+/** This field's remembered representation at `mode` (a fresh clone). */
+export function recallSlotValue(fieldKey: string, mode: SlotMode): JsonValue | undefined {
+  return cloneValue(slotModeMemory.get(memoryKey(fieldKey, mode)));
+}
+
+/** Record the rung the user just chose for this field, so the next render honours it. */
+export function setSlotMode(fieldKey: string, mode: SlotMode): void {
+  slotModeRendered.set(fieldScopeKey(fieldKey), mode);
+}
+
+/** Whether a keystroke alone could have produced this rung transition. */
+function isTextEditRung(mode: SlotMode): boolean {
+  return mode === "literal" || mode === "template";
+}
+
+/**
+ * The rung to render this field at: the one it is already being edited at when a text edit could
+ * explain the difference, otherwise whatever the document value says. Records its answer.
+ */
+export function effectiveSlotMode(fieldKey: string, value: unknown): SlotMode {
+  const key = fieldScopeKey(fieldKey);
+  const sniffed = slotMode(value);
+  const previous = slotModeRendered.get(key);
+  const mode =
+    previous !== undefined && isTextEditRung(previous) && isTextEditRung(sniffed)
+      ? previous
+      : sniffed;
+  slotModeRendered.set(key, mode);
+  return mode;
+}
+
 function hasRefOptions(opts: DynamicSlotOpts): boolean {
   return opts.stateDefs.length > 0 || Boolean(opts.extraSignals?.length);
 }
@@ -72,10 +133,19 @@ export interface DynamicSlotOpts {
   onChange: (v?: JsonValue) => void;
   /** Panel-provided literal editor for this slot's type. */
   staticWidget: unknown;
-  /** Modes this schema position allows, in ladder order. "literal" and "ref" are the floor. */
-  caps: SlotMode[];
+  /** Where this slot's rungs are derived from — a named document position, or a schema. */
+  caps: SlotCapsSource;
   /** State keys offered by the ref picker and expression editor. */
   stateDefs: string[];
+  /**
+   * Let the From data… rung take a pointer that is not in its list.
+   *
+   * The list is complete wherever it is a component's own signals. It is not complete in an
+   * extension's config form, where a value may point at a route param, a signal, or a pointer
+   * neither the form nor the panel enumerates — so there the same rung is a combobox whose options
+   * are suggestions, which is what `jx-value-selector` is for.
+   */
+  allowCustomRef?: boolean;
   /** Full state defs map — lets expression mode resolve named-formula catalog entries. */
   stateEntries?: Record<string, JxStateDefinition> | null;
   /** Extra pointer options beyond #/state/* (e.g. $map/item within repeater templates). */
@@ -86,20 +156,16 @@ export interface DynamicSlotOpts {
   preview?: EditorPreview | null;
   /** Static value restored when de-escalating to literal mode. */
   literalDefault?: JsonValue;
-}
-
-/** Detect which rung of the ladder a raw document value occupies. */
-export function slotMode(value: unknown): SlotMode {
-  if (isRef(value)) {
-    return "ref";
-  }
-  if (isTemplateString(value)) {
-    return "template";
-  }
-  if (value && typeof value === "object" && "$expression" in value) {
-    return "expression";
-  }
-  return "literal";
+  /**
+   * A position-specific seed for a rung, overriding the generic one.
+   *
+   * The generic expression seed is `{ operator: "??" }`, which is a sensible starting point almost
+   * everywhere and an INVALID document in a position whose schema narrows which operators it takes.
+   * An element's `tagName` is the first such position — a `TagExpression` is `?:` or `switch` and
+   * nothing else — so a generic seed would drop a document that fails its own validator the moment
+   * the chip is clicked. Return `undefined` to accept the generic seed.
+   */
+  seedFor?: (mode: SlotMode) => JsonValue | undefined;
 }
 
 function defaultForSlotMode(mode: SlotMode, opts: DynamicSlotOpts): JsonValue | undefined {
@@ -115,13 +181,47 @@ function defaultForSlotMode(mode: SlotMode, opts: DynamicSlotOpts): JsonValue |
     case "expression": {
       return { $expression: { operator: "??", target: null, value: null } };
     }
+    case "function": {
+      return { $prototype: "Function", body: "", parameters: [] };
+    }
     default: {
       return opts.literalDefault;
     }
   }
 }
 
+/** Every pointer the From data… rung offers, as `{ value, label }` options. */
+function refOptions(opts: DynamicSlotOpts): SignalOption[] {
+  return [
+    ...opts.stateDefs.map((name) => ({ label: name, value: `#/state/${name}` })),
+    ...(opts.extraSignals ?? []),
+  ];
+}
+
+function renderCustomRefWidget(refVal: string, opts: DynamicSlotOpts) {
+  return html`
+    <jx-value-selector
+      size="s"
+      style="flex:1"
+      placeholder="#/state/…"
+      .value=${refVal}
+      .options=${refOptions(opts)}
+      @change=${(e: Event & { detail?: { value?: string } }) => {
+        const v = (e.detail?.value ?? (e.target as HTMLInputElement).value ?? "").trim();
+        if (v) {
+          opts.onChange({ $ref: v });
+        } else {
+          opts.onChange();
+        }
+      }}
+    ></jx-value-selector>
+  `;
+}
+
 function renderRefWidget(refVal: string, opts: DynamicSlotOpts) {
+  if (opts.allowCustomRef) {
+    return renderCustomRefWidget(refVal, opts);
+  }
   return html`
     <sp-picker
       size="s"
@@ -168,26 +268,52 @@ function renderTemplateWidget(value: unknown, opts: DynamicSlotOpts) {
 }
 
 export interface DynamicSlotParts {
-  /** Label-side mode-cycle button. */
+  /** Label-side Value Source chip and its picker. */
   modeButton: TemplateResult;
   /** Active-mode widget, sized to fill the row's widget column. */
   widget: TemplateResult;
 }
 
 /**
- * The label-side field-mode button. Shows the current mode's glyph — quiet/gray while static and
- * accent-tinted once the value is dynamic — and each click cycles to the next capped mode, stashing
- * the outgoing mode's value and restoring the incoming mode's remembered one.
+ * Switch a field to `next`: stash the outgoing representation, restore the incoming one if this
+ * field has been there before, and record the new rung. Shared with the Events tab, which used to
+ * throw the outgoing representation away on every mode change.
+ */
+export function switchSlotMode(
+  fieldKey: string,
+  from: SlotMode,
+  to: SlotMode,
+  current: JsonValue | undefined,
+  seed: JsonValue | undefined,
+): JsonValue | undefined {
+  stashSlotValue(fieldKey, from, current);
+  setSlotMode(fieldKey, to);
+  return hasStashedSlotValue(fieldKey, to) ? recallSlotValue(fieldKey, to) : seed;
+}
+
+/** A DOM id for the chip, so `sp-overlay` can name it as its trigger. */
+function chipId(fieldKey: string): string {
+  return `value-source-${fieldKey.replaceAll(/[^\dA-Za-z]+/g, "-")}`;
+}
+
+/**
+ * The label-side Value Source chip: the current rung in plain language — quiet while the value is
+ * fixed, accent-tinted once it is produced from something else — opening a picker of every rung
+ * this position permits.
  */
-function renderModeButton(mode: SlotMode, caps: SlotMode[], opts: DynamicSlotOpts): TemplateResult {
+function renderModeChip(mode: SlotMode, caps: SlotMode[], opts: DynamicSlotOpts): TemplateResult {
   const color =
-    mode !== "literal"
-      ? "color:var(--spectrum-accent-content-color-default, #5c9dff)"
-      : "color:var(--spectrum-gray-600, #808080)";
-  // A ref rung with nothing to point at is a dead end — drop it rather than trap the cycle there.
-  const cycle = caps.filter((m) => m !== "ref" || hasRefOptions(opts));
-  if (cycle.length < 2) {
-    const hint = `Field mode: ${MODE_NOUNS[mode]} (no other modes available)`;
+    mode === "literal"
+      ? "color:var(--spectrum-gray-600, #808080)"
+      : "color:var(--spectrum-accent-content-color-default, #5c9dff)";
+  // A ref rung with nothing to point at is a dead end — drop it rather than offer an empty picker.
+  const offered = caps.filter((m) => m !== "ref" || hasRefOptions(opts));
+  const label = VALUE_SOURCE_LABELS[mode];
+  /* Disabled only when the rung this value already sits on is the only one there is. A value on a
+     rung the position does NOT permit — a fixed string left in a `$switch`, say — is exactly the
+     case that needs the chip most, and counting rungs alone used to grey it out. */
+  if (!offered.some((m) => m !== mode)) {
+    const hint = `Value source: ${label} (no other source available here)`;
     return html`
       <sp-action-button
         size="xs"
@@ -197,53 +323,70 @@ function renderModeButton(mode: SlotMode, caps: SlotMode[], opts: DynamicSlotOpt
         style=${color}
         title=${hint}
         aria-label=${hint}
-        >${MODE_LABELS[mode]}</sp-action-button
+        >${label}</sp-action-button
       >
     `;
   }
-  // An uncapped current mode indexes to -1, so its next stop is cycle[0] (literal).
-  const next = cycle[(cycle.indexOf(mode) + 1) % cycle.length]!;
-  const hint = `Field mode: ${MODE_NOUNS[mode]} — click for ${MODE_NOUNS[next]}`;
+  const id = chipId(opts.fieldKey);
+  const hint = `Value source: ${label} — click to change`;
+  const choose = (next: SlotMode) => {
+    if (next === mode) {
+      return;
+    }
+    /* Leaving ref seeds an empty literal stash with the signal's declared default, so
+       unbind-restores-default survives a detour (ref → mixed text → fixed value). */
+    if (
+      mode === "ref" &&
+      opts.literalDefault !== undefined &&
+      !hasStashedSlotValue(opts.fieldKey, "literal")
+    ) {
+      stashSlotValue(opts.fieldKey, "literal", opts.literalDefault);
+    }
+    opts.onChange(
+      switchSlotMode(
+        opts.fieldKey,
+        mode,
+        next,
+        cloneValue(opts.value as JsonValue | undefined),
+        opts.seedFor?.(next) ?? defaultForSlotMode(next, opts),
+      ),
+    );
+  };
   return html`
     <sp-action-button
+      id=${id}
       size="xs"
       quiet
       class="dynamic-slot-mode"
       style=${color}
       title=${hint}
       aria-label=${hint}
-      @click=${() => {
-        slotModeMemory.set(
-          memoryKey(opts.fieldKey, mode),
-          cloneValue(opts.value as JsonValue | undefined),
-        );
-        // Leaving ref seeds an empty literal stash with the signal's declared default.
-        // Unbind-restores-default thus survives multi-hop cycles (ref → template → literal).
-        if (mode === "ref" && opts.literalDefault !== undefined) {
-          const litKey = memoryKey(opts.fieldKey, "literal");
-          if (!slotModeMemory.has(litKey)) {
-            slotModeMemory.set(litKey, cloneValue(opts.literalDefault));
-          }
-        }
-        const key = memoryKey(opts.fieldKey, next);
-        opts.onChange(
-          slotModeMemory.has(key)
-            ? cloneValue(slotModeMemory.get(key))
-            : defaultForSlotMode(next, opts),
-        );
-      }}
-      >${MODE_LABELS[mode]}</sp-action-button
+      >${label}</sp-action-button
     >
+    <sp-overlay trigger="${id}@click" placement="bottom-start" type="auto">
+      <sp-popover>
+        <sp-menu size="s" label="Value source">
+          ${offered.map(
+            (m) => html`
+              <sp-menu-item data-mode=${m} ?selected=${m === mode} @click=${() => choose(m)}
+                >${VALUE_SOURCE_LABELS[m]}
+                <span slot="description">${VALUE_SOURCE_HINTS[m]}</span></sp-menu-item
+              >
+            `,
+          )}
+        </sp-menu>
+      </sp-popover>
+    </sp-overlay>
   `;
 }
 
 /**
  * Render a bindable slot as two parts the panel places independently: the active mode's widget for
- * the row's value column, and the mode-cycle button for the label side.
+ * the row's value column, and the Value Source chip for the label side.
  */
 export function renderDynamicSlot(opts: DynamicSlotOpts): DynamicSlotParts {
-  const caps: SlotMode[] = opts.caps.length > 0 ? opts.caps : ["literal", "ref"];
-  const mode = slotMode(opts.value);
+  const caps = slotCaps(opts.caps);
+  const mode = effectiveSlotMode(opts.fieldKey, opts.value);
 
   const widget =
     mode === "ref"
@@ -264,7 +407,7 @@ export function renderDynamicSlot(opts: DynamicSlotOpts): DynamicSlotParts {
           : opts.staticWidget;
 
   return {
-    modeButton: renderModeButton(mode, caps, opts),
+    modeButton: renderModeChip(mode, caps, opts),
     widget: html`
       <div class="dynamic-slot" style="display:flex;flex:1;min-width:0">
         <div style="flex:1;min-width:0">${widget}</div>