@jxsuite/studio 0.1.0 → 0.5.0

package/src/ui/button-group.js

@@ -0,0 +1,91 @@
+/**
+ * Button-group.js — Action group + overflow picker widget.
+ *
+ * Renders a compact button group for enum values with an optional overflow picker for additional
+ * options that don't fit in the button bar.
+ */
+
+import { html, nothing } from "lit-html";
+import { abbreviateValue, kebabToLabel } from "../utils/studio-utils.js";
+import icons from "./icons.js";
+
+/**
+ * Render a button group widget with optional overflow menu.
+ *
+ * @param {any} entry — css-meta entry with $buttonValues, enum, $icons
+ * @param {string} prop — property key (for menu ID namespace)
+ * @param {any} value — current value
+ * @param {(val: string) => void} onChange — commit callback
+ * @returns {any}
+ */
+export function renderButtonGroup(
+  /** @type {any} */ entry,
+  /** @type {any} */ prop,
+  /** @type {any} */ value,
+  /** @type {any} */ onChange,
+) {
+  const values = entry.$buttonValues || entry.enum || [];
+  /** @type {Record<string, any>} */
+  const iconMap = entry.$icons || {};
+  const extra =
+    entry.$buttonValues && entry.enum && entry.enum.length > entry.$buttonValues.length
+      ? entry.enum.filter((/** @type {any} */ v) => !entry.$buttonValues.includes(v))
+      : [];
+
+  const menuId = `style-btngrp-${prop}`;
+  const hasExtra = extra.length > 0;
+  const extraSelected = hasExtra && extra.includes(value);
+
+  return html`
+    <div class="button-group-combo ${hasExtra ? "has-overflow" : ""}">
+      <sp-action-group size="s" compact>
+        ${values.map(
+          (/** @type {any} */ v) => html`
+            <sp-action-button
+              size="s"
+              value=${v}
+              title=${v}
+              ?selected=${v === value}
+              @click=${() => onChange(v === value ? "" : v)}
+            >
+              ${
+                /** @type {any} */ (iconMap)[v] &&
+                /** @type {any} */ (icons)[/** @type {any} */ (iconMap)[v]]
+                  ? /** @type {any} */ (icons)[/** @type {any} */ (iconMap)[v]]
+                  : abbreviateValue(v)
+              }
+            </sp-action-button>
+          `,
+        )}
+      </sp-action-group>
+      ${hasExtra
+        ? html`
+            <sp-picker-button
+              size="s"
+              id=${menuId}
+              class=${extraSelected ? "has-selection" : ""}
+            ></sp-picker-button>
+            <sp-overlay trigger="${menuId}@click" placement="bottom-end" type="auto">
+              <sp-popover>
+                <sp-menu
+                  @change=${(/** @type {any} */ e) => {
+                    if (e.target.value) onChange(e.target.value);
+                  }}
+                >
+                  <sp-menu-item value="__none__">—</sp-menu-item>
+                  ${extra.map((/** @type {any} */ v) => {
+                    const label = v.includes("-")
+                      ? kebabToLabel(v)
+                      : v.replace(/^./, (/** @type {any} */ c) => c.toUpperCase());
+                    return html`<sp-menu-item value=${v} ?selected=${v === value}
+                      >${label}</sp-menu-item
+                    >`;
+                  })}
+                </sp-menu>
+              </sp-popover>
+            </sp-overlay>
+          `
+        : nothing}
+    </div>
+  `;
+}

package/src/ui/color-selector.js

@@ -0,0 +1,299 @@
+/**
+ * Color-selector.js — Color input widget with swatch, text field, and popover picker.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+import { LitElement, html, nothing } from "lit";
+import { html as litHtml } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+import { getState, debouncedStyleCommit } from "../store.js";
+import { getEffectiveStyle } from "../site-context.js";
+import { kebabToLabel } from "../utils/studio-utils.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Extract --color-* CSS custom properties from the effective (site + document) style. */
+function getColorVars() {
+  const S = getState();
+  const style = getEffectiveStyle(S?.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;
+}
+
+/**
+ * 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"
+ */
+function varToLabel(/** @type {string} */ name) {
+  return kebabToLabel(name.replace(/^--color-?/, ""));
+}
+
+/** Resolve a color value for display — if it's a var() reference, look up the actual color. */
+function resolveColorForDisplay(/** @type {any} */ val) {
+  if (!val) return "transparent";
+  const m = val.match(/^var\((--[^)]+)\)$/);
+  if (m) {
+    const S = getState();
+    const style = getEffectiveStyle(S?.document?.style);
+    const resolved = style?.[m[1]];
+    if (typeof resolved === "string") return resolved;
+    return "transparent";
+  }
+  return val;
+}
+
+function safeColor(/** @type {any} */ val) {
+  if (!val) return "transparent";
+  return resolveColorForDisplay(val);
+}
+
+/** Normalize a color string to include # prefix for hex values. */
+function normalizeHex(/** @type {string} */ c) {
+  if (!c) return c;
+  if (c.startsWith("var(") || c.startsWith("rgb") || c.startsWith("hsl")) return c;
+  return c.replace(/^#?/, "#");
+}
+
+/**
+ * Check if a value is a var() reference that matches a defined color variable.
+ *
+ * @param {any} value
+ * @param {{ name: string; value: string }[]} colorVars
+ */
+function matchesColorVar(value, colorVars) {
+  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 ──────────────────────────────────────────────
+
+/** @typedef {{ name: string; value: string }} ColorVar */
+
+export class JxColorPopover extends LitElement {
+  static properties = {
+    color: { type: String },
+    displayColor: { type: String, attribute: false },
+    colorVars: { attribute: false },
+  };
+
+  constructor() {
+    super();
+    /** @type {string} */ this.color = "";
+    /** @type {string} */ this.displayColor = "#000000";
+    /** @type {ColorVar[]} */ this.colorVars = [];
+  }
+
+  /** No shadow DOM — render directly into light DOM for Spectrum theming */
+  createRenderRoot() {
+    return this;
+  }
+
+  /** @param {Map<string, any>} changed */
+  willUpdate(changed) {
+    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(/** @type {any} */ e) {
+    const color = normalizeHex(String(e.target.color));
+    this.displayColor = color;
+    this.color = color;
+    this.dispatchEvent(new CustomEvent("color-change", { detail: color, bubbles: true }));
+  }
+
+  _handleSlider(/** @type {any} */ e) {
+    const color = normalizeHex(String(e.target.color));
+    this.displayColor = color;
+    this.color = color;
+    this.dispatchEvent(new CustomEvent("color-change", { detail: color, bubbles: true }));
+  }
+
+  _handleText(/** @type {any} */ e) {
+    const val = e.target.value.trim();
+    if (!val) return;
+    this.displayColor = val;
+    this.color = val;
+    this.dispatchEvent(new CustomEvent("color-change", { detail: val, bubbles: true }));
+  }
+
+  _handleSwatch(/** @type {any} */ e, /** @type {string} */ varName) {
+    e.stopPropagation();
+    const varRef = `var(${varName})`;
+    this.color = varRef;
+    this.dispatchEvent(new CustomEvent("color-change", { detail: varRef, bubbles: true }));
+  }
+
+  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=${(/** @type {any} */ e) => this._handleSwatch(e, cv.name)}
+                    ></sp-swatch>
+                  `,
+                )}
+              </sp-swatch-group>
+            `
+          : nothing}
+      </div>
+    `;
+  }
+}
+
+// ─── Color input widget ─────────────────────────────────────────────────────
+
+/**
+ * Render a color selector: swatch + text field + overlay popover. Uses sp-overlay trigger pattern
+ * (same as unit-selector and value-selector).
+ *
+ * When value is a var(--color-*) matching a defined variable, switches to picker mode showing
+ * title-cased label with swatch (e.g. "Primary Blue").
+ *
+ * @param {string} prop — property key (for debounce namespace)
+ * @param {any} value — current color value
+ * @param {(color: string) => void} onChange — commit callback
+ * @returns {any}
+ */
+export function renderColorSelector(
+  /** @type {any} */ prop,
+  /** @type {any} */ value,
+  /** @type {any} */ onChange,
+) {
+  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=${(/** @type {CustomEvent} */ e) => onChange(e.detail)}
+            ></jx-color-popover>
+          </sp-popover>
+        </sp-overlay>
+        <sp-picker
+          id=${pickerTriggerId}
+          size="s"
+          style="flex:1; min-width:0"
+          .value=${`var(${matchedVar.name})`}
+          @change=${(/** @type {any} */ e) => {
+            e.stopPropagation();
+            onChange(e.target.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>
+    `;
+  }
+
+  // ─── 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=${(/** @type {Event} */ e) => e.stopPropagation()}
+        @input=${debouncedStyleCommit(`color:${prop}`, 400, (/** @type {any} */ e) => {
+          onChange(e.target.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=${(/** @type {CustomEvent} */ e) => onChange(e.detail)}
+          ></jx-color-popover>
+        </sp-popover>
+      </sp-overlay>
+    </div>
+  `;
+}
+
+/** Whether any color popover is currently open. */
+export function isColorPopoverOpen() {
+  return !!document.querySelector(".style-input-color sp-overlay[open]");
+}

package/src/ui/field-row.js

@@ -0,0 +1,47 @@
+/**
+ * Field-row.js — Universal field row layout for all Studio panels.
+ *
+ * Renders the consistent pattern: indicator dot + label + widget slot. Used by style panel,
+ * attributes panel, frontmatter panel, signals panel, etc.
+ */
+
+import { html, nothing } from "lit-html";
+
+/**
+ * Render a universal field row with indicator dot, label, and widget.
+ *
+ * @param {{
+ *   prop: string;
+ *   label: string;
+ *   hasValue: boolean;
+ *   onClear?: () => void;
+ *   widget: any;
+ *   span?: number;
+ *   warning?: boolean;
+ * }} opts
+ * @returns {any}
+ */
+export function renderFieldRow({ prop, label, hasValue, onClear, widget, span, warning }) {
+  return html`
+    <div
+      class=${"style-row" + (warning ? " style-row--warning" : "")}
+      data-prop=${prop}
+      style=${span === 2 ? "grid-column: 1 / -1" : ""}
+    >
+      <div class="style-row-label">
+        ${hasValue && onClear
+          ? html`<span
+              class="set-dot"
+              title="Clear ${prop}"
+              @click=${(/** @type {any} */ e) => {
+                e.stopPropagation();
+                onClear();
+              }}
+            ></span>`
+          : nothing}
+        <sp-field-label size="s" title=${prop}>${label}</sp-field-label>
+      </div>
+      ${widget}
+    </div>
+  `;
+}

package/src/ui/media-picker.js

@@ -0,0 +1,172 @@
+/**
+ * Media Picker — combobox-style widget for selecting project media files.
+ *
+ * Shows an editable text input for manual URL entry combined with a dropdown of available media
+ * files from the project's public/ directory, with thumbnail previews for images.
+ */
+
+import { html, nothing } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+import { getPlatform } from "../platform.js";
+import { debouncedStyleCommit } from "../store.js";
+
+// ─── Media file cache ────────────────────────────────────────────────────────
+
+const IMAGE_EXTENSIONS = new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".svg",
+  ".webp",
+  ".avif",
+  ".ico",
+]);
+
+const MEDIA_EXTENSIONS = new Set([
+  ...IMAGE_EXTENSIONS,
+  ".mp4",
+  ".webm",
+  ".mp3",
+  ".wav",
+  ".ogg",
+  ".pdf",
+]);
+
+/** @type {{ path: string; name: string; isImage: boolean }[]} */
+let mediaCache = [];
+let mediaCacheLoaded = false;
+
+/**
+ * Recursively collect media files from a directory.
+ *
+ * @param {string} dir
+ * @param {ReturnType<typeof getPlatform>} platform
+ * @returns {Promise<{ path: string; name: string; isImage: boolean }[]>}
+ */
+async function collectMedia(dir, platform) {
+  /** @type {{ path: string; name: string; isImage: boolean }[]} */
+  const results = [];
+  try {
+    const entries = await platform.listDirectory(dir);
+    for (const entry of entries) {
+      if (entry.type === "directory") {
+        const sub = await collectMedia(entry.path, platform);
+        results.push(...sub);
+      } else {
+        const dot = entry.name.lastIndexOf(".");
+        const ext = dot > 0 ? entry.name.slice(dot).toLowerCase() : "";
+        if (MEDIA_EXTENSIONS.has(ext)) {
+          results.push({
+            path: `/${entry.path}`,
+            name: entry.name,
+            isImage: IMAGE_EXTENSIONS.has(ext),
+          });
+        }
+      }
+    }
+  } catch {
+    // Directory may not exist
+  }
+  return results;
+}
+
+async function loadMediaCache() {
+  if (mediaCacheLoaded) return;
+  const platform = getPlatform();
+  mediaCache = await collectMedia("public", platform);
+  // Strip "public/" prefix so paths match production (public/ contents served at root)
+  for (const m of mediaCache) {
+    m.path = m.path.replace(/^\/public\//, "/");
+  }
+  mediaCacheLoaded = true;
+}
+
+/** Force media cache reload (e.g. after upload). */
+export function invalidateMediaCache() {
+  mediaCache = [];
+  mediaCacheLoaded = false;
+}
+
+// ─── Render ──────────────────────────────────────────────────────────────────
+
+/**
+ * Render the media picker widget for src-type attributes.
+ *
+ * @param {string} prop — attribute name (e.g. "src")
+ * @param {any} value — current attribute value
+ * @param {(val: any) => void} onCommit — commit callback
+ * @returns {any}
+ */
+export function renderMediaPicker(prop, value, onCommit) {
+  // Kick off async load (won't block render)
+  loadMediaCache();
+
+  const currentValue = value || "";
+  const isImage = IMAGE_EXTENSIONS.has(
+    currentValue.slice(currentValue.lastIndexOf(".")).toLowerCase(),
+  );
+
+  // Filter media options based on current input
+  const query = currentValue.toLowerCase();
+  const filtered = query
+    ? mediaCache.filter(
+        (m) => m.path.toLowerCase().includes(query) || m.name.toLowerCase().includes(query),
+      )
+    : mediaCache;
+
+  // Limit displayed options
+  const options = filtered.slice(0, 20);
+
+  return html`
+    <div class="media-picker">
+      ${isImage && currentValue
+        ? html`<img class="media-picker-thumb" src=${currentValue} alt="" />`
+        : nothing}
+      <sp-textfield
+        size="s"
+        placeholder="/image.jpg"
+        .value=${live(currentValue)}
+        @input=${debouncedStyleCommit(`media:${prop}`, 400, (/** @type {any} */ e) =>
+          onCommit(e.target.value),
+        )}
+        @focus=${() => loadMediaCache()}
+      ></sp-textfield>
+      ${mediaCache.length > 0
+        ? html`
+            <overlay-trigger placement="bottom-end">
+              <sp-action-button size="xs" quiet slot="trigger" title="Browse media">
+                <sp-icon-image slot="icon"></sp-icon-image>
+              </sp-action-button>
+              <sp-popover slot="click-content" class="media-picker-popover">
+                <sp-menu
+                  @change=${(/** @type {any} */ e) => {
+                    onCommit(e.target.value);
+                  }}
+                >
+                  ${options.map(
+                    (m) => html`
+                      <sp-menu-item value=${m.path}>
+                        ${m.isImage
+                          ? html`<img
+                              slot="icon"
+                              src=${m.path}
+                              alt=""
+                              style="width:24px;height:24px;object-fit:cover;border-radius:2px"
+                            />`
+                          : nothing}
+                        ${m.name}
+                      </sp-menu-item>
+                    `,
+                  )}
+                  ${filtered.length > 20
+                    ? html`<sp-menu-item disabled>...${filtered.length - 20} more</sp-menu-item>`
+                    : nothing}
+                </sp-menu>
+              </sp-popover>
+            </overlay-trigger>
+          `
+        : nothing}
+    </div>
+  `;
+}