@jxsuite/studio 4.1.0 → 5.0.0

package/src/ui/cf-account-picker.ts

@@ -16,17 +16,19 @@
  * holding a pasted API token (desktop, dev server) keeps its own local account field and this
  * resolves null without opening anything.
  *
+ * The dialog itself is `src/surfaces/cf-account-picker.json`, a `jx-dialog`; this module is the
+ * flow around it. It used to be a lit template rendered through `showDialog`, with its own
+ * `repaint()` re-rendering the whole body into the slot's parent whenever anything landed — the
+ * surface is reactive now, so a listing that arrives late, or a refusal, changes only what it names.
+ *
  * @docs studio/ai
  * @license MIT
  */
 
-import { html, render as litRender, nothing } from "lit-html";
-import { ref } from "lit-html/directives/ref.js";
-import type { TemplateResult } from "lit-html";
 import { getPlatform, hasPlatform } from "../platform";
 import { notifyCredentialsChanged } from "../settings/preferences-accounts";
-import { showDialog } from "./layers";
-import { overlayRegion } from "./regions";
+import { openCfAccountPickerSurface } from "../surfaces/cf-account-picker";
+import { layerHost } from "./layers";
 import type { CfAccountSummary } from "../types";
 
 /** Whether this platform brokers the connection, and so can be asked which accounts it reaches. */
@@ -38,6 +40,11 @@ function canPick(): boolean {
   return Boolean(platform.cfAccounts && platform.cfSelectAccount);
 }
 
+/** What a thrown thing says, for a line the reader has to act on. */
+function reasonOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 /**
  * Ask which Cloudflare account this connection should use, and store the answer.
  *
@@ -51,150 +58,78 @@ export function openCfAccountPicker(): Promise<CfAccountSummary | null> {
   if (!canPick()) {
     return Promise.resolve(null);
   }
-  return showDialog<CfAccountSummary | null>(
-    (done) => {
-      let accounts: CfAccountSummary[] = [];
-      let loading = true;
-      /** The last refusal — a listing that failed, or an account the broker would not accept. */
-      let failure = "";
-      /** The id being committed, so its own row can say so rather than the whole list going grey. */
-      let choosing = "";
-      let settled = false;
-      let wrapperEl: HTMLElement | null = null;
+  return new Promise<CfAccountSummary | null>((resolve) => {
+    let accounts: CfAccountSummary[] = [];
+    /** The id being committed. Held here as well as in the scope: it is what guards a second press. */
+    let choosing = "";
+    let settled = false;
 
-      function finish(account: CfAccountSummary | null): void {
-        settled = true;
-        done(account);
+    /* Resolve once, and take the dialog down with it. `close()` provokes the platform's own
+       `close`, which comes back as `onClosed` — so the guard is what keeps a chosen account from
+       being overwritten by the dismissal its own commit caused. */
+    const finish = (account: CfAccountSummary | null): void => {
+      if (settled) {
+        return;
       }
+      settled = true;
+      handle.close();
+      resolve(account);
+    };
 
-      function repaint(): void {
-        /* Resolved lazily, and only while the dialog is still up: `done` releases the slot, so a
-           late `load()` landing after a dismissal would otherwise paint into a detached host. */
-        const host = settled ? null : wrapperEl?.parentElement;
-        if (host) {
-          litRender(build(), host);
-        }
+    async function load(): Promise<void> {
+      handle.update({ failure: "", loading: true });
+      let failure = "";
+      try {
+        accounts = (await getPlatform().cfAccounts?.()) ?? [];
+      } catch (error) {
+        accounts = [];
+        failure = reasonOf(error);
       }
-
-      async function load(): Promise<void> {
-        loading = true;
-        failure = "";
-        repaint();
-        try {
-          accounts = (await getPlatform().cfAccounts?.()) ?? [];
-        } catch (error) {
-          failure = error instanceof Error ? error.message : String(error);
-        }
-        loading = false;
-        repaint();
+      /* `done` released the slot, so a late listing landing after a dismissal would otherwise be a
+         write into a disposed surface. The lit version guarded the same moment by resolving its
+         host lazily and finding none. */
+      if (settled) {
+        return;
       }
+      handle.update({ accounts, failure, loading: false });
+    }
 
-      async function choose(account: CfAccountSummary): Promise<void> {
-        choosing = account.id;
-        failure = "";
-        repaint();
-        try {
-          await getPlatform().cfSelectAccount?.({ id: account.id, name: account.name });
-        } catch (error) {
-          failure = error instanceof Error ? error.message : String(error);
-          choosing = "";
-          repaint();
-          return;
-        }
-        /* The stored account is a credential like any other: the assistant's gate, the publish
-           panel and the Preferences row all re-read from the same announcement. */
-        notifyCredentialsChanged();
-        finish(account);
+    async function choose(id: string): Promise<void> {
+      const account = accounts.find((candidate) => candidate.id === id);
+      if (!account || choosing !== "") {
+        return;
       }
-
-      function listTpl(): TemplateResult | typeof nothing {
-        if (loading) {
-          return html`<p class="cf-account-picker-empty">Reading your Cloudflare accounts…</p>`;
+      choosing = id;
+      handle.update({ choosing: id, failure: "" });
+      try {
+        await getPlatform().cfSelectAccount?.({ id: account.id, name: account.name });
+      } catch (error) {
+        choosing = "";
+        if (!settled) {
+          /* The list survives a refusal, and the reason sits above it: listing again is not what
+             would fix an account the broker will not accept, so this state offers no retry. */
+          handle.update({ choosing: "", failure: reasonOf(error) });
         }
-        /* Nothing to show and a reason why. The retry is offered only here: a commit that was
-           refused (below) keeps the list, because listing again is not what would fix it. */
-        if (accounts.length === 0) {
-          return html`
-            <p class="cf-account-picker-empty">
-              ${
-                failure
-                  ? `Cloudflare could not be reached: ${failure}`
-                  : "This Cloudflare login reaches no accounts. Create one at dash.cloudflare.com, then try again."
-              }
-            </p>
-            ${
-              failure
-                ? html`<sp-button
-                    size="s"
-                    treatment="outline"
-                    @click=${() => {
-                      void load();
-                    }}
-                  >
-                    Try again
-                  </sp-button>`
-                : nothing
-            }
-          `;
-        }
-        /* The row shape is Preferences › Accounts', deliberately reused: this IS an account list,
-           and a second stylesheet entry for the same shape is how two lists drift apart. */
-        return html`
-          ${failure ? html`<p class="cf-account-picker-error">${failure}</p>` : nothing}
-          <div class="prefs-accounts">
-            ${accounts.map(
-              (account) => html`
-                <div class="prefs-account" data-account=${account.id}>
-                  <div class="prefs-account-text">
-                    <span class="prefs-account-label">${account.name}</span>
-                    <span class="prefs-account-detail">${account.id}</span>
-                  </div>
-                  <sp-button
-                    size="s"
-                    variant="accent"
-                    ?disabled=${choosing !== ""}
-                    @click=${() => {
-                      void choose(account);
-                    }}
-                  >
-                    ${choosing === account.id ? "Selecting…" : "Use this account"}
-                  </sp-button>
-                </div>
-              `,
-            )}
-          </div>
-        `;
-      }
-
-      function build(): TemplateResult {
-        return html`
-          <sp-dialog-wrapper
-            open
-            underlay
-            headline="Choose a Cloudflare account"
-            cancel-label="Cancel"
-            @cancel=${() => finish(null)}
-            @close=${() => finish(null)}
-            ${ref((el?: Element) => {
-              if (el) {
-                wrapperEl = el as HTMLElement;
-              }
-            })}
-          >
-            <div class="cf-account-picker">
-              <p class="cf-account-picker-lede">
-                Your Cloudflare login reaches more than one account. Publishing and the assistant
-                both run against the one you pick; you can change it in Preferences › Accounts.
-              </p>
-              ${listTpl()}
-            </div>
-          </sp-dialog-wrapper>
-        `;
+        return;
       }
+      /* The stored account is a credential like any other: the assistant's gate, the publish
+         panel and the Preferences row all re-read from the same announcement. */
+      notifyCredentialsChanged();
+      finish(account);
+    }
 
-      void load();
-      return build();
-    },
-    { region: overlayRegion("dialog", "cf-accounts") },
-  );
+    const handle = openCfAccountPickerSurface({
+      layer: layerHost("dialog"),
+      onChoose: (id) => {
+        void choose(id);
+      },
+      onClosed: () => {
+        finish(null);
+      },
+      onRetry: () => {
+        void load();
+      },
+    });
+    void load();
+  });
 }

package/src/ui/color-selector.ts

@@ -1,330 +1,109 @@
-/// <reference lib="dom" />
 /**
- * Color-selector.js — Color input widget with swatch, text field, and popover picker.
+ * The project's colour tokens, as a projection.
  *
- * Uses sp-overlay trigger pattern for positioning (same as unit-selector and value-selector). The
- * popover content is a JxColorPopover LitElement that reactively syncs color between the area,
- * slider, and text field via a single `color` property.
+ * This module used to be a CONTROL — a swatch, a text field and an `sp-overlay` holding an
+ * `sp-color-area`, an `sp-color-slider` and an `sp-swatch-group` — because `specs/ui.md` §5.6 was
+ * Pending and there was no colour element in the kit to draw a colour row with. It was the last
+ * Spectrum surface in Studio, and the island `studio-ui-guidelines.md` §9.4 describes: the Style
+ * tab and the Content tab each drew an empty `[part="control-host"]` and this filled it with lit.
  *
- * When the value is a var(--color-*) reference matching a defined color variable, the input
- * switches to picker mode showing the title-cased variable name (e.g. "Primary Blue") with a
- * swatch, similar to jx-value-selector's dual-mode behavior.
+ * §5.6 landed, so the control is `jx-color-field` and both tabs draw it inline in their own
+ * documents. What no kit element can answer is what is LEFT here: which colours this project has
+ * given a name to. That is a question about the document being edited — the `--color-*` custom
+ * properties of the effective style, site and document together — and it is Studio's to answer.
+ *
+ * A token is projected as three separate things on purpose, because they are three:
+ *
+ * - `value` is what choosing it COMMITS, and it is the reference (`var(--color-accent)`) rather than
+ *   the colour behind it. Committing the literal would resolve the token at the moment of the click
+ *   and quietly opt that one declaration out of the palette for ever.
+ * - `color` is how the chip LOOKS, which is the literal, and is not what the swatch means.
+ * - `label` is the word a reader would use. A colour is not a name: `jx-swatch` announces its own
+ *   `value` when it is given no label, and "var(--color-primary-blue)" read one character at a time
+ *   is a name in the same sense that a licence plate is.
+ *
+ * @docs studio/design/style-inspector
  */
 
-import { LitElement, html, nothing } from "lit";
-import { html as litHtml } from "lit-html";
-import { live } from "lit-html/directives/live.js";
-import { debouncedStyleCommit } from "../store";
 import { activeTab } from "../workspace/workspace";
 import { getEffectiveStyle } from "../site-context";
+import { resolveTokenValue, tokenRefName } from "../style/token-ref";
 import { kebabToLabel } from "../utils/studio-utils";
 
-interface ColorVar {
-  name: string;
+/**
+ * One colour the project has named, as a swatch reads it.
+ *
+ * `Record<string, unknown>` because it is a `$map` item: a repeater's scope is a record, and a
+ * shape that is not one cannot be read through `$map/item/...`.
+ */
+export interface ColorTokenView extends Record<string, unknown> {
+  /** What choosing this swatch commits — the reference, never the literal behind it. */
   value: string;
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-/** Extract --color-* CSS custom properties from the effective (site + document) style. */
-function getColorVars() {
-  const style = getEffectiveStyle(activeTab.value?.doc.document?.style);
-  if (!style) {
-    return [];
-  }
-  const vars = [];
-  for (const [k, v] of Object.entries(style)) {
-    if (k.startsWith("--color") && (typeof v === "string" || typeof v === "number")) {
-      vars.push({ name: k, value: String(v) });
-    }
-  }
-  return vars;
+  /** The chip's colour: how the token looks, which is not what it means. */
+  color: string;
+  /** The token's name, title-cased — "Primary Blue" — and the swatch's accessible name. */
+  label: string;
 }
 
 /**
- * Convert a color variable name to a title-case label. Strips the "--color-" prefix and converts
- * kebab to title case. e.g. "--color-primary-blue" → "Primary Blue"
+ * Convert a colour variable's name to a title-case label.
+ *
+ * Strips the `--color-` prefix and converts kebab to title case, so `--color-primary-blue` becomes
+ * "Primary Blue". A token named `--color` alone has nothing left after the prefix, and falls back
+ * to its own name rather than announcing itself as the empty string.
+ *
+ * @param {string} name The custom property's name, with its leading dashes.
+ * @returns {string}
  */
-function varToLabel(name: string) {
-  return kebabToLabel(name.replace(/^--color-?/, ""));
-}
-
-/** Resolve a color value for display — if it's a var() reference, look up the actual color. */
-function resolveColorForDisplay(val: string | number | undefined) {
-  if (!val) {
-    return "transparent";
-  }
-  const s = String(val);
-  const m = s.match(/^var\((--[^)]+)\)$/);
-  if (m) {
-    const style = getEffectiveStyle(activeTab.value?.doc.document?.style);
-    const resolved = style?.[m[1]!];
-    if (typeof resolved === "string") {
-      return resolved;
-    }
-    return "transparent";
-  }
-  return s;
-}
-
-function safeColor(val: string | number | undefined) {
-  if (!val) {
-    return "transparent";
-  }
-  return resolveColorForDisplay(val);
-}
-
-/** Normalize a color string to include # prefix for hex values. */
-function normalizeHex(c: string) {
-  if (!c) {
-    return c;
-  }
-  if (c.startsWith("var(") || c.startsWith("rgb") || c.startsWith("hsl")) {
-    return c;
-  }
-  return c.replace(/^#?/, "#");
+function varToLabel(name: string): string {
+  return kebabToLabel(name.replace(/^--color-?/, "")) || name;
 }
 
 /**
- * Check if a value is a var() reference that matches a defined color variable.
+ * The `--color-*` custom properties of the effective (site + document) style, in the order they are
+ * written.
+ *
+ * Only scalars are taken. A custom property whose value is an object is a nested rule rather than a
+ * colour, and a swatch drawn from one would be a chip of nothing labelled with a name that commits
+ * a reference to something that is not a colour.
  *
- * @param {string | number | undefined} value
- * @param {{ name: string; value: string }[]} colorVars
+ * @returns {ColorTokenView[]} The palette, empty when the document defines no colours.
  */
-function matchesColorVar(
-  value: string | number | undefined,
-  colorVars: { name: string; value: string }[],
-) {
-  if (!value || typeof value !== "string") {
-    return null;
-  }
-  const m = value.match(/^var\((--[^)]+)\)$/);
-  if (!m) {
-    return null;
-  }
-  return colorVars.find((cv) => cv.name === m[1]) || null;
-}
-
-// ─── JxColorPopover LitElement ──────────────────────────────────────────────
-
-export class JxColorPopover extends LitElement {
-  static override properties = {
-    color: { type: String },
-    colorVars: { attribute: false },
-    displayColor: { attribute: false, type: String },
-  };
-
-  declare color: string;
-  declare displayColor: string;
-  declare colorVars: ColorVar[];
-
-  constructor() {
-    super();
-    this.color = "";
-    this.displayColor = "#000000";
-    this.colorVars = [];
-  }
-
-  /** No shadow DOM — render directly into light DOM for Spectrum theming */
-  override createRenderRoot() {
-    return this;
-  }
-
-  /** @param {Map<string, unknown>} changed */
-  override willUpdate(changed: Map<string, unknown>) {
-    if (changed.has("color")) {
-      const raw = resolveColorForDisplay(this.color);
-      if (!raw || raw === "transparent") {
-        this.displayColor = "#000000";
-      } else if (raw.startsWith("#") || raw.startsWith("rgb") || raw.startsWith("hsl")) {
-        this.displayColor = raw;
-      } else {
-        this.displayColor = `#${raw}`;
-      }
-    }
-  }
-
-  _handleArea(e: Event) {
-    const color = normalizeHex(String((e.target as HTMLElement & { color: string }).color));
-    this.displayColor = color;
-    this.color = color;
-    this.dispatchEvent(new CustomEvent("color-change", { bubbles: true, detail: color }));
-  }
-
-  _handleSlider(e: Event) {
-    const color = normalizeHex(String((e.target as HTMLElement & { color: string }).color));
-    this.displayColor = color;
-    this.color = color;
-    this.dispatchEvent(new CustomEvent("color-change", { bubbles: true, detail: color }));
-  }
-
-  _handleText(e: Event) {
-    const val = (e.target as HTMLInputElement).value.trim();
-    if (!val) {
-      return;
+export function colorTokens(): ColorTokenView[] {
+  /* `getEffectiveStyle` answers with an object whatever it is given — the site's, the document's,
+     the two merged, or an empty one — so there is no absent case to guard, and the guard that used
+     to stand here was a branch no test could reach because nothing could produce it. */
+  const style = getEffectiveStyle(activeTab.value?.doc.document?.style);
+  const tokens: ColorTokenView[] = [];
+  for (const [name, value] of Object.entries(style)) {
+    if (name.startsWith("--color") && (typeof value === "string" || typeof value === "number")) {
+      tokens.push({ color: String(value), label: varToLabel(name), value: `var(${name})` });
     }
-    this.displayColor = val;
-    this.color = val;
-    this.dispatchEvent(new CustomEvent("color-change", { bubbles: true, detail: val }));
-  }
-
-  _handleSwatch(e: Event, varName: string) {
-    e.stopPropagation();
-    const varRef = `var(${varName})`;
-    this.color = varRef;
-    this.dispatchEvent(new CustomEvent("color-change", { bubbles: true, detail: varRef }));
-  }
-
-  override render() {
-    return html`
-      <div class="color-popover-inner">
-        <sp-color-area
-          style="width:200px; height:150px; --mod-colorarea-width:200px; --mod-colorarea-height:150px"
-          .color=${this.displayColor}
-          @input=${this._handleArea}
-        ></sp-color-area>
-        <sp-color-slider
-          style="width:200px; --mod-colorslider-length:200px"
-          .color=${this.displayColor}
-          @input=${this._handleSlider}
-        ></sp-color-slider>
-        <sp-textfield
-          size="s"
-          style="width:200px"
-          .value=${live(this.color || "")}
-          placeholder="#000000"
-          @change=${this._handleText}
-        ></sp-textfield>
-        ${
-          this.colorVars.length > 0
-            ? html`
-                <sp-divider size="s"></sp-divider>
-                <span class="color-popover-swatches-label">Color Tokens</span>
-                <sp-swatch-group size="xs" border="light" rounding="none">
-                  ${this.colorVars.map(
-                    (cv) => html`
-                      <sp-swatch
-                        color=${cv.value}
-                        .value=${cv.name}
-                        title=${cv.name}
-                        @click=${(e: Event) => this._handleSwatch(e, cv.name)}
-                      ></sp-swatch>
-                    `,
-                  )}
-                </sp-swatch-group>
-              `
-            : nothing
-        }
-      </div>
-    `;
   }
+  return tokens;
 }
 
-// ─── Color input widget ─────────────────────────────────────────────────────
-
 /**
- * Render a color selector: swatch + text field + overlay popover. Uses sp-overlay trigger pattern
- * (same as unit-selector and value-selector).
+ * The literal behind a colour value that is a token reference, for a chip to draw.
+ *
+ * `var(--color-accent)` is a perfectly good value for the document being edited and nothing at all
+ * for the page drawing the Inspector: the token lives in the project's style, which the canvas
+ * iframe loads and Studio's own chrome never sees, so a `jx-color-field` handed the reference alone
+ * drew the no-colour checkerboard the moment a palette swatch was picked. This is the answer both
+ * tabs hand the field's `resolved` prop (ui.md §5.6): the chain followed through the effective
+ * style to the colour at its end.
  *
- * When value is a var(--color-*) matching a defined variable, switches to picker mode showing
- * title-cased label with swatch (e.g. "Primary Blue").
+ * Empty for a literal, which draws itself, and for a reference the style cannot resolve — a token a
+ * stylesheet defines, or an alias loop — where the field's own fallback is the right one.
  *
- * @param {string} prop — property key (for debounce namespace)
- * @param {string | number | undefined} value — current color value
- * @param {(color: string) => void} onChange — commit callback
- * @returns {import("lit-html").TemplateResult}
+ * @param {string} value The row's value as the field holds it.
+ * @returns {string} The colour to draw, or the empty string.
  */
-export function renderColorSelector(
-  /** @type {string} */ prop: string,
-  /** @type {string | number | undefined} */ value: string | number | undefined,
-  /** @type {(color: string) => void} */ onChange: (color: string) => void,
-) {
-  const colorVars = getColorVars();
-  const matchedVar = matchesColorVar(value, colorVars);
-  const triggerId = `color-trigger-${prop}`;
-  const pickerTriggerId = `color-picker-${prop}`;
-
-  // ─── Picker mode: value matches a defined color variable ───
-  if (matchedVar) {
-    return litHtml`
-      <div class="style-input-color">
-        <sp-swatch
-          size="s"
-          rounding="none"
-          border="light"
-          color=${matchedVar.value}
-          id=${triggerId}
-        ></sp-swatch>
-        <sp-overlay trigger="${triggerId}@click" placement="bottom-start" type="auto">
-          <sp-popover style="padding:12px">
-            <jx-color-popover
-              .color=${value || ""}
-              .colorVars=${colorVars}
-              @color-change=${(e: CustomEvent) => onChange(e.detail as string)}
-            ></jx-color-popover>
-          </sp-popover>
-        </sp-overlay>
-        <sp-picker
-          id=${pickerTriggerId}
-          size="s"
-          style="flex:1; min-width:0"
-          .value=${`var(${matchedVar.name})`}
-          @change=${(e: Event) => {
-            e.stopPropagation();
-            onChange((e.target as HTMLInputElement).value);
-          }}
-        >
-          ${colorVars.map(
-            (cv) => litHtml`
-              <sp-menu-item value=${`var(${cv.name})`}>
-                <sp-swatch
-                  slot="icon"
-                  size="xs"
-                  rounding="none"
-                  border="light"
-                  color=${cv.value}
-                ></sp-swatch>
-                ${varToLabel(cv.name)}
-              </sp-menu-item>
-            `,
-          )}
-        </sp-picker>
-      </div>
-    `;
+export function resolvedColor(value: string): string {
+  if (tokenRefName(value) === null) {
+    return "";
   }
-
-  // ─── Text mode: custom color value or empty ───
-  return litHtml`
-    <div class="style-input-color" id=${triggerId}>
-      <sp-swatch
-        size="s"
-        rounding="none"
-        border="light"
-        color=${safeColor(value)}
-      ></sp-swatch>
-      <sp-textfield
-        size="s"
-        style="flex:1; min-width:0"
-        .value=${live(value || "")}
-        @click=${(e: Event) => e.stopPropagation()}
-        @input=${debouncedStyleCommit(`color:${prop}`, 400, (e: Event) => {
-          onChange((e.target as HTMLInputElement).value.trim());
-        })}
-      ></sp-textfield>
-      <sp-overlay trigger="${triggerId}@click" placement="bottom-start" type="auto">
-        <sp-popover style="padding:12px">
-          <jx-color-popover
-            .color=${value || ""}
-            .colorVars=${colorVars}
-            @color-change=${(e: CustomEvent) => onChange(e.detail as string)}
-          ></jx-color-popover>
-        </sp-popover>
-      </sp-overlay>
-    </div>
-  `;
-}
-
-/** Whether any color popover is currently open. */
-export function isColorPopoverOpen() {
-  return Boolean(document.querySelector(".style-input-color sp-overlay[open]"));
+  const style = getEffectiveStyle(activeTab.value?.doc.document?.style);
+  const resolved = resolveTokenValue(style, value);
+  return resolved === undefined ? "" : String(resolved);
 }