@rogieking/figui3 6.20.2 → 6.21.1

package/fig.js

@@ -223,12 +223,18 @@ function figDefineCustomizedBuiltIn(name, constructor, options) {
   });
 }
 
+function figDefineElement(name, constructor) {
+  if (!customElements.get(name)) {
+    customElements.define(name, constructor);
+  }
+}
+
 function figUniqueId() {
   return Date.now().toString(36) + Math.random().toString(36).substring(2);
 }
 
 /** Zero-size portal for fixed overlays so they never affect body layout metrics. */
-function figGetOverlayRoot() {
+function figGetOverlayRoot(source) {
   if (!document.body) return null;
   const attr = "data-figui-overlay-root";
   let root = document.body.querySelector(`:scope > [${attr}]`);
@@ -237,9 +243,40 @@ function figGetOverlayRoot() {
     root.setAttribute(attr, "");
     document.body.append(root);
   }
+  figSyncOverlayThemeFromSource(root, source);
   return root;
 }
 
+/** Copy PropsKit / FigUI theme onto the overlay portal so portaled popups stay themed. */
+function figSyncOverlayThemeFromSource(overlayRoot, source) {
+  if (!overlayRoot) return;
+  const panel =
+    (source instanceof Element
+      ? source.closest(".figui-root")
+      : null) || document.querySelector(".figui-root");
+  if (!panel) return;
+
+  const themeAttr = panel.getAttribute("theme");
+  const theme =
+    themeAttr === "light" || themeAttr === "dark" || themeAttr === "system"
+      ? themeAttr
+      : panel.classList.contains("figma-dark")
+        ? "dark"
+        : panel.classList.contains("figma-light")
+          ? "light"
+          : "system";
+
+  overlayRoot.classList.toggle("figma-light", theme === "light");
+  overlayRoot.classList.toggle("figma-dark", theme === "dark");
+  if (theme === "system") {
+    overlayRoot.style.setProperty("color-scheme", "light dark");
+  } else {
+    overlayRoot.style.setProperty("color-scheme", theme);
+  }
+  if (themeAttr) overlayRoot.setAttribute("theme", theme);
+  else overlayRoot.removeAttribute("theme");
+}
+
 let _figZCounter = 10000;
 function figGetHighestZIndex() {
   return _figZCounter++;
@@ -520,7 +557,7 @@ class FigButton extends HTMLElement {
     this.removeEventListener("keydown", this.#boundHandleControlKeydown);
   }
 }
-customElements.define("fig-button", FigButton);
+figDefineElement("fig-button", FigButton);
 
 /**
  * A custom dropdown/select element.
@@ -823,7 +860,7 @@ class FigDropdown extends HTMLElement {
   }
 }
 
-customElements.define("fig-dropdown", FigDropdown);
+figDefineElement("fig-dropdown", FigDropdown);
 
 /* Tooltip */
 /**
@@ -1045,13 +1082,13 @@ class FigTooltip extends HTMLElement {
     // - Without popover support, fall back to today's behavior: nearest open
     //   <dialog> ancestor if present, else document.body.
     if (supportsPopover) {
-      (figGetOverlayRoot() ?? document.body).append(this.popup);
+      (figGetOverlayRoot(this) ?? document.body).append(this.popup);
     } else {
       const parentDialog = this.closest("dialog");
       if (parentDialog && parentDialog.open) {
         parentDialog.append(this.popup);
       } else {
-        (figGetOverlayRoot() ?? document.body).append(this.popup);
+        (figGetOverlayRoot(this) ?? document.body).append(this.popup);
       }
     }
 
@@ -1433,13 +1470,13 @@ class FigTooltip extends HTMLElement {
       popup.append(content);
 
       if (supportsPopover) {
-        (figGetOverlayRoot() ?? document.body).append(popup);
+        (figGetOverlayRoot(anchor) ?? document.body).append(popup);
       } else {
         const parentDialog = anchor.closest?.("dialog");
         if (parentDialog && parentDialog.open) {
           parentDialog.append(popup);
         } else {
-          (figGetOverlayRoot() ?? document.body).append(popup);
+          (figGetOverlayRoot(anchor) ?? document.body).append(popup);
         }
       }
 
@@ -1464,7 +1501,7 @@ class FigTooltip extends HTMLElement {
   }
 }
 
-customElements.define("fig-tooltip", FigTooltip);
+figDefineElement("fig-tooltip", FigTooltip);
 
 /* Text Truncation */
 class FigTruncate extends HTMLElement {
@@ -1543,7 +1580,7 @@ class FigTruncate extends HTMLElement {
     FigTooltip.hide(this);
   }
 }
-customElements.define("fig-truncate", FigTruncate);
+figDefineElement("fig-truncate", FigTruncate);
 
 /* Dialog */
 /**
@@ -3837,7 +3874,7 @@ class FigTab extends HTMLElement {
     }
   }
 }
-customElements.define("fig-tab", FigTab);
+figDefineElement("fig-tab", FigTab);
 
 /**
  * A custom tabs container element.
@@ -4167,7 +4204,7 @@ class FigTabs extends HTMLElement {
     }
   }
 }
-customElements.define("fig-tabs", FigTabs);
+figDefineElement("fig-tabs", FigTabs);
 
 /* Segmented Control */
 /**
@@ -4255,7 +4292,7 @@ class FigSegment extends HTMLElement {
     }
   }
 }
-customElements.define("fig-segment", FigSegment);
+figDefineElement("fig-segment", FigSegment);
 
 /**
  * A custom segmented control container element.
@@ -4739,7 +4776,7 @@ class FigSegmentedControl extends HTMLElement {
     }
   }
 }
-customElements.define("fig-segmented-control", FigSegmentedControl);
+figDefineElement("fig-segmented-control", FigSegmentedControl);
 
 /* Options */
 /**
@@ -5084,7 +5121,7 @@ class FigOptions extends HTMLElement {
     }
   }
 }
-customElements.define("fig-options", FigOptions);
+figDefineElement("fig-options", FigOptions);
 
 /* Slider */
 /**
@@ -5769,7 +5806,7 @@ class FigSlider extends HTMLElement {
     }
   }
 }
-customElements.define("fig-slider", FigSlider);
+figDefineElement("fig-slider", FigSlider);
 
 /**
  * A custom text input element.
@@ -6373,7 +6410,7 @@ class FigInputText extends HTMLElement {
     }
   }
 }
-customElements.define("fig-input-text", FigInputText);
+figDefineElement("fig-input-text", FigInputText);
 
 /**
  * A custom numeric input element that uses type="text" with inputmode="decimal".
@@ -7078,7 +7115,7 @@ class FigInputNumber extends HTMLElement {
     }
   }
 }
-customElements.define("fig-input-number", FigInputNumber);
+figDefineElement("fig-input-number", FigInputNumber);
 
 /* Avatar */
 class FigAvatar extends HTMLElement {
@@ -7130,7 +7167,7 @@ class FigAvatar extends HTMLElement {
     }
   }
 }
-customElements.define("fig-avatar", FigAvatar);
+figDefineElement("fig-avatar", FigAvatar);
 
 /* Form Field */
 class FigField extends HTMLElement {
@@ -7329,7 +7366,7 @@ class FigField extends HTMLElement {
     }
   }
 }
-customElements.define("fig-field", FigField);
+figDefineElement("fig-field", FigField);
 
 /* Color swatch */
 class FigInputColor extends HTMLElement {
@@ -8025,7 +8062,7 @@ class FigInputColor extends HTMLElement {
     return { r, g, b, a };
   }
 }
-customElements.define("fig-input-color", FigInputColor);
+figDefineElement("fig-input-color", FigInputColor);
 
 /* Input Fill */
 const GRADIENT_INTERPOLATION_SPACES = [
@@ -8034,6 +8071,7 @@ const GRADIENT_INTERPOLATION_SPACES = [
   "display-p3",
   "oklab",
   "oklch",
+  "hsl",
 ];
 const GRADIENT_HUE_INTERPOLATIONS = [
   "shorter",
@@ -8041,6 +8079,7 @@ const GRADIENT_HUE_INTERPOLATIONS = [
   "increasing",
   "decreasing",
 ];
+const GRADIENT_HUE_SPACES = new Set(["oklch", "hsl"]);
 
 const GRADIENT_PICKER_SPACES = ["srgb", "srgb-linear", "oklab", "oklch"];
 
@@ -8069,7 +8108,7 @@ function gradientToValueShape(gradient) {
     ...normalized,
     interpolationSpace: normalized.interpolationSpace,
   };
-  if (normalized.interpolationSpace === "oklch") {
+  if (GRADIENT_HUE_SPACES.has(normalized.interpolationSpace)) {
     output.hueInterpolation = normalized.hueInterpolation;
   } else {
     delete output.hueInterpolation;
@@ -8082,8 +8121,8 @@ function gradientInterpolationClause(gradient) {
   if (normalized.interpolationSpace === "srgb") {
     return "";
   }
-  if (normalized.interpolationSpace === "oklch") {
-    return `in oklch ${normalized.hueInterpolation} hue`;
+  if (GRADIENT_HUE_SPACES.has(normalized.interpolationSpace)) {
+    return `in ${normalized.interpolationSpace} ${normalized.hueInterpolation} hue`;
   }
   return `in ${normalized.interpolationSpace}`;
 }
@@ -8232,6 +8271,25 @@ function figSampleGradientAt(
     r = rgb.r;
     g = rgb.g;
     b = rgb.b;
+  } else if (space === "hsl") {
+    const hsl1 = figRgbToHsl(c1.r, c1.g, c1.b);
+    const hsl2 = figRgbToHsl(c2.r, c2.g, c2.b);
+    const H = figInterpolateHue(
+      hsl1.h,
+      hsl2.h,
+      t,
+      hueInterpolation || "shorter",
+    );
+    const S = hsl1.s + (hsl2.s - hsl1.s) * t;
+    const L = hsl1.l + (hsl2.l - hsl1.l) * t;
+    const rgb = hslToSRGB(H, S, L);
+    r = rgb[0];
+    g = rgb[1];
+    b = rgb[2];
+  } else if (space === "srgb") {
+    r = Math.round(c1.r + (c2.r - c1.r) * t);
+    g = Math.round(c1.g + (c2.g - c1.g) * t);
+    b = Math.round(c1.b + (c2.b - c1.b) * t);
   } else {
     const lab1 = figRGBToOklab(c1.r, c1.g, c1.b);
     const lab2 = figRGBToOklab(c2.r, c2.g, c2.b);
@@ -8247,6 +8305,33 @@ function figSampleGradientAt(
   return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`.toUpperCase();
 }
 
+function figRgbToHsl(r, g, b) {
+  const R = r / 255;
+  const G = g / 255;
+  const B = b / 255;
+  const max = Math.max(R, G, B);
+  const min = Math.min(R, G, B);
+  const l = (max + min) / 2;
+  if (max === min) {
+    return { h: 0, s: 0, l: l * 100 };
+  }
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  switch (max) {
+    case R:
+      h = ((G - B) / d + (G < B ? 6 : 0)) / 6;
+      break;
+    case G:
+      h = ((B - R) / d + 2) / 6;
+      break;
+    default:
+      h = ((R - G) / d + 4) / 6;
+      break;
+  }
+  return { h: h * 360, s: s * 100, l: l * 100 };
+}
+
 function hslToP3(h, s, l) {
   const sRGB = hslToSRGB(h, s, l);
   return sRGB.map((c) => +(c / 255).toFixed(4));
@@ -8311,6 +8396,7 @@ class FigInputFill extends HTMLElement {
     angle: 180,
     interpolationSpace: "srgb",
     hueInterpolation: "shorter",
+    opacity: 1,
     stops: [
       { position: 0, color: "#D9D9D9", opacity: 100 },
       { position: 100, color: "#737373", opacity: 100 },
@@ -8371,6 +8457,15 @@ class FigInputFill extends HTMLElement {
               ...this.#gradient,
               ...parsed.gradient,
             });
+            this.#gradient.opacity = this.#normalizeFillOpacity(
+              parsed.gradient.opacity ?? parsed.opacity ?? parsed.alpha,
+              this.#gradient.opacity ?? 1,
+            );
+          } else if (parsed.opacity !== undefined || parsed.alpha !== undefined) {
+            this.#gradient.opacity = this.#normalizeFillOpacity(
+              parsed.opacity ?? parsed.alpha,
+              this.#gradient.opacity ?? 1,
+            );
           }
           break;
         case "image":
@@ -8446,10 +8541,20 @@ class FigInputFill extends HTMLElement {
     }
   }
 
+  #normalizeFillOpacity(value, fallback = 1) {
+    if (value === undefined || value === null || value === "") return fallback;
+    const n = Number(value);
+    if (!Number.isFinite(n)) return fallback;
+    if (n > 1) return Math.max(0, Math.min(1, n / 100));
+    return Math.max(0, Math.min(1, n));
+  }
+
   #fillPickerSwatchAlpha() {
     switch (this.#fillType) {
       case "solid":
         return this.#solid.alpha;
+      case "gradient":
+        return this.#gradient.opacity ?? 1;
       case "image":
         return this.#image.opacity ?? 1;
       case "video":
@@ -8507,9 +8612,9 @@ class FigInputFill extends HTMLElement {
     const opacityHtml = (value) =>
       showAlpha
         ? `<fig-tooltip text="Opacity">
-            <fig-input-number 
+            <fig-input-number
               class="fig-input-fill-opacity"
-              placeholder="##" 
+              placeholder="##"
               min="0"
               max="100"
               value="${value}"
@@ -8539,7 +8644,8 @@ class FigInputFill extends HTMLElement {
           this.#gradient.type.charAt(0).toUpperCase() +
           this.#gradient.type.slice(1);
         controlsHtml = `
-          <label class="fig-input-fill-label">${figEscapeAttribute(gradientLabel)}</label>`;
+          <label class="fig-input-fill-label">${figEscapeAttribute(gradientLabel)}</label>
+          ${opacityHtml(Math.round((this.#gradient.opacity ?? 1) * 100))}`;
         break;
       }
 
@@ -8679,6 +8785,7 @@ class FigInputFill extends HTMLElement {
             this.#solid.alpha = alpha;
             break;
           case "gradient":
+            this.#gradient.opacity = alpha;
             break;
           case "image":
             this.#image.opacity = alpha;
@@ -8727,6 +8834,12 @@ class FigInputFill extends HTMLElement {
             this.#gradient.type.slice(1);
           label.textContent = newLabel;
         }
+        if (this.#opacityInput) {
+          this.#opacityInput.setAttribute(
+            "value",
+            Math.round((this.#gradient.opacity ?? 1) * 100),
+          );
+        }
         break;
       }
       case "image":
@@ -8803,7 +8916,18 @@ class FigInputFill extends HTMLElement {
           this.#gradient.type.charAt(0).toUpperCase() +
           this.#gradient.type.slice(1);
         controlsHtml = `
-          <label class="fig-input-fill-label">${figEscapeAttribute(gradientLabel)}</label>`;
+          <label class="fig-input-fill-label">${figEscapeAttribute(gradientLabel)}</label>
+          ${showAlpha ? `<fig-tooltip text="Opacity">
+            <fig-input-number
+              class="fig-input-fill-opacity"
+              placeholder="##"
+              min="0"
+              max="100"
+              value="${Math.round((this.#gradient.opacity ?? 1) * 100)}"
+              units="%"
+              ${disabled ? "disabled" : ""}>
+            </fig-input-number>
+          </fig-tooltip>` : ""}`;
         break;
       }
       case "image":
@@ -8899,6 +9023,7 @@ class FigInputFill extends HTMLElement {
             this.#solid.alpha = alpha;
             break;
           case "gradient":
+            this.#gradient.opacity = alpha;
             break;
           case "image":
             this.#image.opacity = alpha;
@@ -9038,7 +9163,7 @@ class FigInputFill extends HTMLElement {
     }
   }
 }
-customElements.define("fig-input-fill", FigInputFill);
+figDefineElement("fig-input-fill", FigInputFill);
 
 /* Input Palette */
 /**
@@ -9498,7 +9623,7 @@ class FigInputPalette extends HTMLElement {
     );
   }
 }
-customElements.define("fig-input-palette", FigInputPalette);
+figDefineElement("fig-input-palette", FigInputPalette);
 
 /* Input Gradient */
 /**
@@ -9743,6 +9868,11 @@ class FigInputGradient extends HTMLElement {
       .join(", ");
     const interp = gradientInterpolationClause(gradient);
     const interpolation = interp ? ` ${interp}` : "";
+    // Inline stop editor always previews L→R so handles match the track axis,
+    // regardless of linear angle / radial / angular type.
+    if (this.#editMode === "true") {
+      return `linear-gradient(to right${interpolation}, ${stops})`;
+    }
     if (gradient.type === "radial") {
       return `radial-gradient(circle at ${gradient.centerX}% ${gradient.centerY}%${interpolation}, ${stops})`;
     }
@@ -10405,7 +10535,7 @@ class FigInputGradient extends HTMLElement {
     }
   }
 }
-customElements.define("fig-input-gradient", FigInputGradient);
+figDefineElement("fig-input-gradient", FigInputGradient);
 
 /* Checkbox */
 /**
@@ -10643,7 +10773,7 @@ class FigCheckbox extends HTMLElement {
     );
   }
 }
-customElements.define("fig-checkbox", FigCheckbox);
+figDefineElement("fig-checkbox", FigCheckbox);
 
 /* Radio */
 /**
@@ -10663,7 +10793,7 @@ class FigRadio extends FigCheckbox {
     else this.input.removeAttribute("name");
   }
 }
-customElements.define("fig-radio", FigRadio);
+figDefineElement("fig-radio", FigRadio);
 
 /* Switch */
 /**
@@ -10680,7 +10810,7 @@ class FigSwitch extends FigCheckbox {
     this.input.setAttribute("role", "switch");
   }
 }
-customElements.define("fig-switch", FigSwitch);
+figDefineElement("fig-switch", FigSwitch);
 
 /* Combo Input */
 /**
@@ -10975,7 +11105,7 @@ class FigComboInput extends HTMLElement {
     }
   }
 }
-customElements.define("fig-combo-input", FigComboInput);
+figDefineElement("fig-combo-input", FigComboInput);
 
 /* Swatch */
 /**
@@ -11191,7 +11321,7 @@ class FigSwatch extends HTMLElement {
     }
   }
 }
-customElements.define("fig-swatch", FigSwatch);
+figDefineElement("fig-swatch", FigSwatch);
 
 /* Media */
 /**
@@ -11213,6 +11343,9 @@ customElements.define("fig-swatch", FigSwatch);
  * @attr {string} aria-label - Accessible label forwarded to generated video
  * @attr {string} aria-labelledby - Accessible label reference forwarded to generated video
  *
+ * When `controls` are shown and no video `src` is loaded, fig-media sets
+ * `disabled` on the associated `fig-media-controls` until media is available.
+ *
  * Sizing model:
  *   - Default: host shrinkwraps to its inner <img>/<video> intrinsic size.
  *   - `size` attribute applies a token-sized square.
@@ -11551,12 +11684,41 @@ class FigMedia extends HTMLElement {
     this.#mediaEl.playsInline = true;
     this.#syncMediaAccessibility();
     this.#syncControlsVisibility();
+    this.#syncControlsDisabled();
   }
 
   get mediaEl() {
     return this.#mediaEl;
   }
 
+  #hasPlayableVideo() {
+    if (this.mediaKind !== "video") return false;
+    return Boolean(this.#currentMediaSrc());
+  }
+
+  #syncControlsDisabled() {
+    const controls =
+      this.#controlsEl ||
+      this.querySelector(":scope > fig-media-controls");
+    if (!controls) return;
+    if (this.mediaKind !== "video") return;
+
+    if (this.#hasPlayableVideo()) {
+      // Only clear disabled when we set it for the empty state.
+      if (controls.hasAttribute("data-fig-empty-disabled")) {
+        controls.removeAttribute("disabled");
+        controls.removeAttribute("data-fig-empty-disabled");
+      }
+      return;
+    }
+
+    controls.setAttribute("disabled", "");
+    controls.setAttribute("data-fig-empty-disabled", "");
+    controls.playing = false;
+    controls.time = 0;
+    controls.duration = 0;
+  }
+
   #syncControlsVisibility() {
     if (this.mediaKind !== "video") {
       this.#removeControls();
@@ -11571,6 +11733,7 @@ class FigMedia extends HTMLElement {
         this.#controlsEl = userControls;
       }
       this.#wireControlsToMedia();
+      this.#syncControlsDisabled();
       return;
     }
     if (this.#isEnabledAttr("controls", false)) {
@@ -11590,6 +11753,7 @@ class FigMedia extends HTMLElement {
     if (existingControls) {
       this.#controlsEl = existingControls;
       this.#wireControlsToMedia();
+      this.#syncControlsDisabled();
       return;
     }
     const controls = document.createElement("fig-media-controls");
@@ -11597,6 +11761,7 @@ class FigMedia extends HTMLElement {
     this.append(controls);
     this.#controlsEl = controls;
     this.#wireControlsToMedia();
+    this.#syncControlsDisabled();
   }
 
   #wireControlsToMedia() {
@@ -11605,6 +11770,7 @@ class FigMedia extends HTMLElement {
       this.#controlsWiredFor === this.#mediaEl &&
       this.#controlsWiredControls === this.#controlsEl
     ) {
+      this.#syncControlsDisabled();
       return;
     }
     this.#unwireControls();
@@ -11616,6 +11782,8 @@ class FigMedia extends HTMLElement {
 
     let pendingSeekTime = null;
     const syncFromVideo = () => {
+      this.#syncControlsDisabled();
+      if (!this.#hasPlayableVideo()) return;
       controls.playing = !video.paused && !video.ended;
       if (Number.isFinite(video.duration)) controls.duration = video.duration;
       if (pendingSeekTime !== null) {
@@ -11628,11 +11796,13 @@ class FigMedia extends HTMLElement {
       controls.time = video.currentTime || 0;
     };
     const onPlay = () => {
+      if (!this.#hasPlayableVideo()) return;
       const p = video.play?.();
       if (p && typeof p.catch === "function") p.catch(() => {});
     };
     const onPause = () => video.pause?.();
     const onSeek = (e) => {
+      if (!this.#hasPlayableVideo()) return;
       const next = Number(e?.detail?.time);
       if (!Number.isFinite(next)) return;
       pendingSeekTime = next;
@@ -11907,21 +12077,21 @@ class FigMedia extends HTMLElement {
   }
 }
 
-customElements.define("fig-media", FigMedia);
+figDefineElement("fig-media", FigMedia);
 
 class FigImage extends FigMedia {
   get mediaKind() {
     return "image";
   }
 }
-customElements.define("fig-image", FigImage);
+figDefineElement("fig-image", FigImage);
 
 class FigVideo extends FigMedia {
   get mediaKind() {
     return "video";
   }
 }
-customElements.define("fig-video", FigVideo);
+figDefineElement("fig-video", FigVideo);
 
 /**
  * <fig-card> — Media card with optional link, selection chrome, and truncated label.
@@ -12194,7 +12364,7 @@ class FigCard extends HTMLElement {
     }
   }
 }
-customElements.define("fig-card", FigCard);
+figDefineElement("fig-card", FigCard);
 
 /**
  * <fig-media-controls> — Standalone playback controls UI.
@@ -12206,13 +12376,14 @@ customElements.define("fig-card", FigCard);
  *   - `playing` (boolean presence) — current play/pause state
  *   - `duration` (number, seconds) — total track length
  *   - `time` (number, seconds) — current playhead position
+ *   - `disabled` (boolean) — disables play/seek interaction
  *
  * Events:
  *   - `play` — emitted when the user toggles playback on (detail: { playing: true })
  *   - `pause` — emitted when the user toggles playback off (detail: { playing: false })
  *   - `seek` — emitted when the user drags the scrubber (detail: { time })
  *
- * Properties: `playing`, `duration`, `time` mirror the attributes.
+ * Properties: `playing`, `duration`, `time`, `disabled` mirror the attributes.
  */
 class FigMediaControls extends HTMLElement {
   #playBtn = null;
@@ -12223,13 +12394,14 @@ class FigMediaControls extends HTMLElement {
   #rendered = false;
 
   static get observedAttributes() {
-    return ["playing", "duration", "time"];
+    return ["playing", "duration", "time", "disabled"];
   }
 
   connectedCallback() {
     this.#render();
     this.#syncPlayingUi();
     this.#syncTimeUi();
+    this.#syncDisabled();
   }
 
   get playing() {
@@ -12266,10 +12438,19 @@ class FigMediaControls extends HTMLElement {
     this.setAttribute("time", String(n));
   }
 
+  get disabled() {
+    return figBooleanAttribute(this, "disabled");
+  }
+  set disabled(value) {
+    if (value) this.setAttribute("disabled", "");
+    else this.removeAttribute("disabled");
+  }
+
   attributeChangedCallback(name) {
     if (!this.#rendered) return;
     if (name === "playing") this.#syncPlayingUi();
     if (name === "duration" || name === "time") this.#syncTimeUi();
+    if (name === "disabled") this.#syncDisabled();
   }
 
   #render() {
@@ -12315,6 +12496,11 @@ class FigMediaControls extends HTMLElement {
     timeEl.textContent = this.#formatTime(this.time);
 
     const handleSeek = (e) => {
+      if (this.disabled) {
+        e.preventDefault?.();
+        e.stopPropagation();
+        return;
+      }
       const host = e.currentTarget;
       const next = Number(host?.value);
       if (!Number.isFinite(next)) return;
@@ -12340,6 +12526,20 @@ class FigMediaControls extends HTMLElement {
     this.#playTooltip = tooltip;
     this.#timeSlider = slider;
     this.#timeEl = timeEl;
+    this.#syncDisabled();
+  }
+
+  #syncDisabled() {
+    const disabled = this.disabled;
+    this.setAttribute("aria-disabled", disabled ? "true" : "false");
+    if (this.#playBtn) {
+      if (disabled) this.#playBtn.setAttribute("disabled", "");
+      else this.#playBtn.removeAttribute("disabled");
+    }
+    if (this.#timeSlider) {
+      if (disabled) this.#timeSlider.setAttribute("disabled", "");
+      else this.#timeSlider.removeAttribute("disabled");
+    }
   }
 
   #formatTime(seconds) {
@@ -12385,6 +12585,7 @@ class FigMediaControls extends HTMLElement {
   }
 
   toggle() {
+    if (this.disabled) return;
     const next = !this.playing;
     this.playing = next;
     this.dispatchEvent(
@@ -12397,16 +12598,16 @@ class FigMediaControls extends HTMLElement {
   }
 
   play() {
-    if (this.playing) return;
+    if (this.disabled || this.playing) return;
     this.toggle();
   }
 
   pause() {
-    if (!this.playing) return;
+    if (this.disabled || !this.playing) return;
     this.toggle();
   }
 }
-customElements.define("fig-media-controls", FigMediaControls);
+figDefineElement("fig-media-controls", FigMediaControls);
 
 /* File Upload Input */
 class FigInputFile extends HTMLElement {
@@ -12670,7 +12871,7 @@ class FigInputFile extends HTMLElement {
     }
   }
 }
-customElements.define("fig-input-file", FigInputFile);
+figDefineElement("fig-input-file", FigInputFile);
 
 /**
  * A bezier / spring easing curve editor with draggable control points.
@@ -13807,7 +14008,7 @@ class FigEasingCurve extends HTMLElement {
     document.addEventListener("pointerup", onUp);
   }
 }
-customElements.define("fig-easing-curve", FigEasingCurve);
+figDefineElement("fig-easing-curve", FigEasingCurve);
 
 /**
  * A 3D rotation control with an interactive cube preview.
@@ -14177,7 +14378,7 @@ class Fig3DRotate extends HTMLElement {
     this.#container.addEventListener("lostpointercapture", onEnd);
   }
 }
-customElements.define("fig-3d-rotate", Fig3DRotate);
+figDefineElement("fig-3d-rotate", Fig3DRotate);
 
 /**
  * A transform-origin grid control with draggable handle.
@@ -14727,7 +14928,7 @@ class FigOriginGrid extends HTMLElement {
     bindValueInput(this.#yInput, "y");
   }
 }
-customElements.define("fig-origin-grid", FigOriginGrid);
+figDefineElement("fig-origin-grid", FigOriginGrid);
 
 /**
  * A custom joystick input element.
@@ -15152,7 +15353,7 @@ class FigInputJoystick extends HTMLElement {
   }
 }
 
-customElements.define("fig-joystick", FigInputJoystick);
+figDefineElement("fig-joystick", FigInputJoystick);
 
 
 // FigInputAngle moved to fig-lab.js
@@ -15209,7 +15410,7 @@ class FigShimmer extends HTMLElement {
     }
   }
 }
-customElements.define("fig-shimmer", FigShimmer);
+figDefineElement("fig-shimmer", FigShimmer);
 
 // FigSkeleton
 class FigSkeleton extends FigShimmer {
@@ -15219,7 +15420,7 @@ class FigSkeleton extends FigShimmer {
     this.setAttribute("inert", "");
   }
 }
-customElements.define("fig-skeleton", FigSkeleton);
+figDefineElement("fig-skeleton", FigSkeleton);
 
 // FigGroup
 class FigGroup extends HTMLElement {
@@ -15365,7 +15566,7 @@ class FigGroup extends HTMLElement {
     }
   }
 }
-customElements.define("fig-group", FigGroup);
+figDefineElement("fig-group", FigGroup);
 
 /**
  * A presentational header element used inside fig-dialog, fig-group, and other containers.
@@ -15375,7 +15576,7 @@ customElements.define("fig-group", FigGroup);
  * @attr {boolean} dialog-header - Marks this as a dialog header (auto-generated by fig-dialog)
  */
 class FigHeader extends HTMLElement {}
-customElements.define("fig-header", FigHeader);
+figDefineElement("fig-header", FigHeader);
 
 /**
  * fig-footer
@@ -15384,7 +15585,7 @@ customElements.define("fig-header", FigHeader);
  * @attr {boolean} sticky - Pins the footer to the bottom of its scroll container
  */
 class FigFooter extends HTMLElement {}
-customElements.define("fig-footer", FigFooter);
+figDefineElement("fig-footer", FigFooter);
 
 /* Presentational elements (CSS-only, no behavior) */
 class FigSpinner extends HTMLElement {
@@ -15395,7 +15596,7 @@ class FigSpinner extends HTMLElement {
     }
   }
 }
-customElements.define("fig-spinner", FigSpinner);
+figDefineElement("fig-spinner", FigSpinner);
 
 /**
  * A styled visual preview layer for arbitrary content such as images, canvas,
@@ -15425,7 +15626,315 @@ class FigPreview extends HTMLElement {
     }
   }
 }
-customElements.define("fig-preview", FigPreview);
+figDefineElement("fig-preview", FigPreview);
+
+/**
+ * Compact swatch previewing gradient color-space interpolation.
+ * Polar: CSS conic-gradient masked (SVG data-URL, round linecaps) to an arc.
+ * Non-polar: CSS linear-gradient masked to a horizontal round-capped stroke.
+ * Accepts the same `value` shape as fig-input-gradient / fig-fill-picker.
+ *
+ * @element fig-interpolation-swatch
+ * @attr {string} value - JSON `{ type: "gradient", gradient: { … } }` (or a bare gradient object)
+ * @attr {string} size - `small` (default, 24px) or `large` (32px)
+ */
+class FigInterpolationSwatch extends HTMLElement {
+  static #HUE_SPACES = new Set(["oklch", "hsl"]);
+  static #CX = 10;
+  static #CY = 10;
+  static #R = 8;
+  static #STROKE = 3;
+  // Polar endpoints ≈ 10 o'clock → 2 o'clock (SVG deg: 0 = east, CW).
+  // CSS conic `from` is 0 = north; convert with +90.
+  static #START_DEG = 210;
+  static #DEFAULT_GRADIENT = {
+    type: "linear",
+    angle: 135,
+    interpolationSpace: "srgb",
+    hueInterpolation: "shorter",
+    stops: [
+      { color: "#FF0000", position: 0, opacity: 100 },
+      { color: "#4F9EFF", position: 100, opacity: 100 },
+    ],
+  };
+
+  #rendered = false;
+  #svgEl = null;
+  #fillEl = null;
+  #gradient = { ...FigInterpolationSwatch.#DEFAULT_GRADIENT };
+
+  static get observedAttributes() {
+    return ["value"];
+  }
+
+  get value() {
+    return {
+      type: "gradient",
+      gradient: { ...this.#gradient },
+    };
+  }
+
+  set value(val) {
+    if (val == null || val === "") {
+      this.removeAttribute("value");
+      return;
+    }
+    if (typeof val === "string") {
+      this.setAttribute("value", val);
+      return;
+    }
+    this.setAttribute("value", JSON.stringify(val));
+  }
+
+  connectedCallback() {
+    this.#ensureA11y();
+    this.#parseValue();
+    this.#render();
+    this.#updatePreview();
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) return;
+    if (name !== "value") return;
+    this.#parseValue();
+    if (this.#rendered) this.#updatePreview();
+  }
+
+  #ensureA11y() {
+    const named =
+      this.hasAttribute("aria-label") || this.hasAttribute("aria-labelledby");
+    if (!named && !this.hasAttribute("aria-hidden")) {
+      this.setAttribute("aria-hidden", "true");
+    }
+  }
+
+  #parseValue() {
+    const valueAttr = this.getAttribute("value");
+    if (!valueAttr) {
+      this.#gradient = {
+        ...FigInterpolationSwatch.#DEFAULT_GRADIENT,
+        stops: FigInterpolationSwatch.#DEFAULT_GRADIENT.stops.map((s) => ({
+          ...s,
+        })),
+      };
+      return;
+    }
+    try {
+      const parsed = JSON.parse(valueAttr);
+      const gradient = parsed?.type === "gradient" && parsed.gradient
+        ? parsed.gradient
+        : parsed?.gradient
+          ? parsed.gradient
+          : parsed;
+      if (!gradient || typeof gradient !== "object") return;
+      this.#gradient = this.#normalizeGradient({
+        ...FigInterpolationSwatch.#DEFAULT_GRADIENT,
+        ...gradient,
+      });
+    } catch {
+      // Keep current/default gradient on invalid JSON.
+    }
+  }
+
+  #normalizeGradient(gradient) {
+    const next = { ...(gradient ?? {}) };
+    const interpolationSpace = String(
+      next.interpolationSpace ?? "srgb",
+    ).toLowerCase();
+    const hueInterpolation = String(
+      next.hueInterpolation ?? "shorter",
+    ).toLowerCase();
+    const stops = Array.isArray(next.stops)
+      ? next.stops.map((stop) => ({
+          color: String(stop?.color || "#D9D9D9").replace(
+            /^(#(?:[0-9a-f]{6})).*/i,
+            "$1",
+          ),
+          position: stop?.position ?? 0,
+          opacity: stop?.opacity ?? 100,
+        }))
+      : FigInterpolationSwatch.#DEFAULT_GRADIENT.stops.map((s) => ({ ...s }));
+    if (stops.length < 2) {
+      return {
+        ...FigInterpolationSwatch.#DEFAULT_GRADIENT,
+        stops: FigInterpolationSwatch.#DEFAULT_GRADIENT.stops.map((s) => ({
+          ...s,
+        })),
+      };
+    }
+    return {
+      type: ["linear", "radial", "angular"].includes(next.type)
+        ? next.type
+        : "linear",
+      angle: Number.isFinite(Number(next.angle)) ? Number(next.angle) : 135,
+      interpolationSpace,
+      hueInterpolation,
+      stops,
+    };
+  }
+
+  #isPolar() {
+    return FigInterpolationSwatch.#HUE_SPACES.has(
+      this.#gradient.interpolationSpace || "srgb",
+    );
+  }
+
+  #hueForColor(color) {
+    const { r, g, b } = figHexToRGB(color);
+    if (this.#gradient.interpolationSpace === "hsl") {
+      return figRgbToHsl(r, g, b).h;
+    }
+    const lab = figRGBToOklab(r, g, b);
+    const hue = figOklabToOklch(lab.l, lab.a, lab.b).h;
+    return ((hue % 360) + 360) % 360;
+  }
+
+  #polarArcGeometry() {
+    const stops = this.#sortedStops();
+    const startHue = this.#hueForColor(stops[0]?.color || "#FF0000");
+    const endHue = this.#hueForColor(
+      stops[stops.length - 1]?.color || "#4F9EFF",
+    );
+    const startDeg = FigInterpolationSwatch.#START_DEG - startHue;
+    const endDeg = FigInterpolationSwatch.#START_DEG - endHue;
+    const clockwiseSweep = ((endDeg - startDeg) % 360 + 360) % 360;
+    const counterclockwiseSweep =
+      clockwiseSweep === 0 ? 0 : clockwiseSweep - 360;
+    const method = this.#gradient.hueInterpolation || "shorter";
+
+    let sweepDeg;
+    if (method === "increasing") {
+      sweepDeg = counterclockwiseSweep;
+    } else if (method === "decreasing") {
+      sweepDeg = clockwiseSweep;
+    } else if (method === "longer") {
+      sweepDeg =
+        clockwiseSweep < 180 ? counterclockwiseSweep : clockwiseSweep;
+    } else {
+      sweepDeg =
+        clockwiseSweep <= 180 ? clockwiseSweep : counterclockwiseSweep;
+    }
+
+    // A round cap extends beyond the path endpoint. Inset the centerline so
+    // the visible cap edges, rather than their centers, land on the hues.
+    const direction = Math.sign(sweepDeg);
+    const capAngle =
+      (Math.asin(FigInterpolationSwatch.#STROKE / 2 / FigInterpolationSwatch.#R) *
+        180) /
+      Math.PI;
+    const inset = Math.min(
+      capAngle,
+      Math.max(0, (Math.abs(sweepDeg) - 0.01) / 2),
+    );
+    return {
+      startDeg: startDeg + direction * inset,
+      sweepDeg: sweepDeg - direction * inset * 2,
+    };
+  }
+
+  #pointOnCircle(deg) {
+    const rad = (deg * Math.PI) / 180;
+    return {
+      x: FigInterpolationSwatch.#CX + FigInterpolationSwatch.#R * Math.cos(rad),
+      y: FigInterpolationSwatch.#CY + FigInterpolationSwatch.#R * Math.sin(rad),
+    };
+  }
+
+  #arcMaskPath(startDeg, sweepDeg) {
+    const endDeg = startDeg + sweepDeg;
+    const start = this.#pointOnCircle(startDeg);
+    const end = this.#pointOnCircle(endDeg);
+    const largeArc = Math.abs(sweepDeg) > 180 ? 1 : 0;
+    const sweepFlag = sweepDeg >= 0 ? 1 : 0;
+    return `M ${start.x} ${start.y} A ${FigInterpolationSwatch.#R} ${FigInterpolationSwatch.#R} 0 ${largeArc} ${sweepFlag} ${end.x} ${end.y}`;
+  }
+
+  #lineMaskPath() {
+    const start = this.#pointOnCircle(180);
+    const end = this.#pointOnCircle(0);
+    return `M ${start.x} ${start.y} L ${end.x} ${end.y}`;
+  }
+
+  #maskImageForPath(d) {
+    const stroke = FigInterpolationSwatch.#STROKE;
+    const svg =
+      `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="none">` +
+      `<path d="${d}" fill="none" stroke="white" stroke-width="${stroke}" ` +
+      `stroke-linecap="round" stroke-linejoin="round"/>` +
+      `</svg>`;
+    return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
+  }
+
+  #sortedStops() {
+    return [...this.#gradient.stops].sort(
+      (a, b) => (a.position ?? 0) - (b.position ?? 0),
+    );
+  }
+
+  #cssInterpolationClause() {
+    const space = this.#gradient.interpolationSpace || "srgb";
+    if (space === "srgb") return "";
+    if (FigInterpolationSwatch.#HUE_SPACES.has(space)) {
+      return ` in ${space} ${this.#gradient.hueInterpolation || "shorter"} hue`;
+    }
+    return ` in ${space}`;
+  }
+
+  #previewBackground() {
+    const stops = this.#sortedStops();
+    const clause = this.#cssInterpolationClause();
+    if (this.#isPolar()) {
+      // Fixed hue wheel. The mask maps gradient endpoint hues onto this wheel.
+      const cssFrom = (FigInterpolationSwatch.#START_DEG + 90) % 360;
+      const space = this.#gradient.interpolationSpace;
+      const wheelColor = (hue) =>
+        space === "oklch"
+          ? `oklch(65% 0.25 ${hue})`
+          : `hsl(${hue} 100% 50%)`;
+      const wheelStops = [0, 300, 240, 180, 120, 60, 0]
+        .map(wheelColor)
+        .join(", ");
+      return `conic-gradient(from ${cssFrom}deg in ${space} decreasing hue, ${wheelStops})`;
+    }
+    const stopList = stops
+      .map((s) => `${s.color} ${s.position ?? 0}%`)
+      .join(", ");
+    return `linear-gradient(90deg${clause}, ${stopList})`;
+  }
+
+  #render() {
+    if (this.#rendered) return;
+    const stroke = FigInterpolationSwatch.#STROKE;
+    this.innerHTML = `
+      <svg class="fig-interpolation-swatch-svg" width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+        <circle class="fig-interpolation-swatch-rim" cx="10" cy="10" r="8" fill="none" stroke="currentColor" stroke-width="${stroke}"/>
+      </svg>
+      <div class="fig-interpolation-swatch-fill" aria-hidden="true"></div>
+    `;
+    this.#svgEl = this.querySelector(".fig-interpolation-swatch-svg");
+    this.#fillEl = this.querySelector(".fig-interpolation-swatch-fill");
+    this.#rendered = true;
+  }
+
+  #updatePreview() {
+    if (!this.#fillEl) return;
+
+    const polar = this.#isPolar();
+    if (this.#svgEl) this.#svgEl.style.display = polar ? "" : "none";
+
+    const d = polar
+      ? (() => {
+          const { startDeg, sweepDeg } = this.#polarArcGeometry();
+          return this.#arcMaskPath(startDeg, sweepDeg);
+        })()
+      : this.#lineMaskPath();
+    const mask = this.#maskImageForPath(d);
+    this.#fillEl.style.setProperty("-webkit-mask-image", mask);
+    this.#fillEl.style.maskImage = mask;
+    this.#fillEl.style.background = this.#previewBackground();
+  }
+}
+figDefineElement("fig-interpolation-swatch", FigInterpolationSwatch);
 
 /** @type {Record<string, string | { medium: string, small: string }>} */
 const FIG_ICON_TOKENS = {
@@ -15512,19 +16021,19 @@ class FigIcon extends HTMLElement {
     }
   }
 }
-customElements.define("fig-icon", FigIcon);
+figDefineElement("fig-icon", FigIcon);
 
 class FigContent extends HTMLElement {}
-customElements.define("fig-content", FigContent);
+figDefineElement("fig-content", FigContent);
 
 class FigTabContent extends HTMLElement {}
-customElements.define("fig-tab-content", FigTabContent);
+figDefineElement("fig-tab-content", FigTabContent);
 
 class FigButtonCombo extends HTMLElement {}
-customElements.define("fig-button-combo", FigButtonCombo);
+figDefineElement("fig-button-combo", FigButtonCombo);
 
 class FigInputCombo extends HTMLElement {}
-customElements.define("fig-input-combo", FigInputCombo);
+figDefineElement("fig-input-combo", FigInputCombo);
 
 
 
@@ -15902,7 +16411,7 @@ class FigColorTip extends HTMLElement {
     this.toggleAttribute("disabled", Boolean(value));
   }
 }
-customElements.define("fig-color-tip", FigColorTip);
+figDefineElement("fig-color-tip", FigColorTip);
 
 /* Choice */
 /**
@@ -15951,7 +16460,7 @@ class FigChoice extends HTMLElement {
     }
   }
 }
-customElements.define("fig-choice", FigChoice);
+figDefineElement("fig-choice", FigChoice);
 
 /* Chooser */
 /**
@@ -16556,7 +17065,7 @@ class FigChooser extends HTMLElement {
     this.#mutationObserver.observe(this, { childList: true, subtree: false });
   }
 }
-customElements.define("fig-chooser", FigChooser);
+figDefineElement("fig-chooser", FigChooser);
 
 /* Handle */
 class FigHandle extends HTMLElement {
@@ -17478,7 +17987,7 @@ class FigHandle extends HTMLElement {
     return { x, y, px, py };
   }
 }
-customElements.define("fig-handle", FigHandle);
+figDefineElement("fig-handle", FigHandle);
 
 // ─── Menu ────────────────────────────────────────────────────────────────────
 
@@ -17526,7 +18035,7 @@ class FigMenuItem extends HTMLElement {
     }
   }
 }
-customElements.define("fig-menu-item", FigMenuItem);
+figDefineElement("fig-menu-item", FigMenuItem);
 
 /**
  * Visual divider between menu item groups.
@@ -17564,7 +18073,7 @@ class FigMenuSeparator extends HTMLElement {
     else this.removeAttribute("aria-label");
   }
 }
-customElements.define("fig-menu-separator", FigMenuSeparator);
+figDefineElement("fig-menu-separator", FigMenuSeparator);
 
 class FigMenu extends HTMLElement {
   #popup = null;
@@ -18007,4 +18516,4 @@ class FigMenu extends HTMLElement {
     this.#trigger?.setAttribute("aria-expanded", "false");
   }
 }
-customElements.define("fig-menu", FigMenu);
+figDefineElement("fig-menu", FigMenu);