@rogieking/figui3 7.0.0 → 8.0.0

package/fig-editor.js

@@ -16,6 +16,1326 @@ function figEditorEscapeAttribute(value) {
     .replace(/>/g, ">");
 }
 
+function figEditorBooleanAttribute(element, name) {
+  return element.hasAttribute(name) && element.getAttribute(name) !== "false";
+}
+
+function figEditorUniqueId() {
+  return Date.now().toString(36) + Math.random().toString(36).substring(2);
+}
+
+function figEditorCreateIcon(name, options = {}) {
+  const icon = document.createElement("fig-icon");
+  if (name) icon.setAttribute("name", name);
+  if (options.size) icon.setAttribute("size", options.size);
+  if (options.className) icon.className = options.className;
+  return icon;
+}
+
+function figEditorCreateOverflowButtons({
+  owner,
+  onStart,
+  onEnd,
+  startClass = "",
+  endClass = "",
+  chevronClass = "",
+  startLabel = "Scroll back",
+  endLabel = "Scroll forward",
+} = {}) {
+  const makeButton = (direction, onPointerDown) => {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = [
+      "fig-overflow",
+      `fig-overflow-${direction}`,
+      direction === "start" ? startClass : endClass,
+    ]
+      .filter(Boolean)
+      .join(" ");
+    button.dataset.figOverflow = direction;
+    if (owner) button.setAttribute(`data-fig-${owner}-nav`, direction);
+    button.setAttribute("tabindex", "-1");
+    button.setAttribute(
+      "aria-label",
+      direction === "start" ? startLabel : endLabel,
+    );
+    button.appendChild(
+      figEditorCreateIcon("chevron", {
+        size: "small",
+        className: ["fig-overflow-chevron", chevronClass].filter(Boolean).join(" "),
+      }),
+    );
+    button.addEventListener("click", (event) => {
+      event.preventDefault();
+      event.stopPropagation();
+      onPointerDown?.(event);
+    });
+    return button;
+  };
+
+  return {
+    start: makeButton("start", onStart),
+    end: makeButton("end", onEnd),
+  };
+}
+
+function figEditorSyncOverflowState(host, scrollEl, axis = "x", threshold = 2) {
+  if (!host || !scrollEl) return false;
+  const isHorizontal = axis === "x";
+  const scrollSize = isHorizontal ? scrollEl.scrollWidth : scrollEl.scrollHeight;
+  const clientSize = isHorizontal ? scrollEl.clientWidth : scrollEl.clientHeight;
+  const scrollPosition = isHorizontal ? scrollEl.scrollLeft : scrollEl.scrollTop;
+  const scrollable = scrollSize - clientSize > threshold;
+  const atStart = !scrollable || scrollPosition <= threshold;
+  const atEnd = !scrollable || scrollPosition + clientSize >= scrollSize - threshold;
+  host.classList.toggle("overflow-start", !atStart);
+  host.classList.toggle("overflow-end", !atEnd);
+  return scrollable;
+}
+
+function figEditorScrollOverflowPage(scrollEl, axis = "x", direction = 1) {
+  if (!scrollEl) return;
+  const isHorizontal = axis === "x";
+  const pageSize = isHorizontal ? scrollEl.clientWidth : scrollEl.clientHeight;
+  const scrollAmount = pageSize * 0.8 * direction;
+  scrollEl.scrollBy({
+    [isHorizontal ? "left" : "top"]: scrollAmount,
+    behavior: "smooth",
+  });
+}
+
+function figEditorScrollElementToCenter(
+  scrollEl,
+  element,
+  axis = "y",
+  behavior = "auto",
+) {
+  if (!scrollEl || !element || !scrollEl.contains(element)) return;
+  requestAnimationFrame(() => {
+    if (!scrollEl.isConnected || !element.isConnected) return;
+    const isHorizontal = axis === "x";
+    const scrollSize = isHorizontal
+      ? scrollEl.scrollWidth
+      : scrollEl.scrollHeight;
+    const clientSize = isHorizontal
+      ? scrollEl.clientWidth
+      : scrollEl.clientHeight;
+    if (scrollSize <= clientSize + 1) {
+      figEditorSyncOverflowState(scrollEl, scrollEl, axis);
+      return;
+    }
+    const elementRect = element.getBoundingClientRect();
+    const hostRect = scrollEl.getBoundingClientRect();
+    const currentScroll = isHorizontal
+      ? scrollEl.scrollLeft
+      : scrollEl.scrollTop;
+    const elementStart =
+      (isHorizontal ? elementRect.left - hostRect.left : elementRect.top - hostRect.top) +
+      currentScroll;
+    const elementSize = isHorizontal ? elementRect.width : elementRect.height;
+    const maxScroll = scrollSize - clientSize;
+    const nextScroll = Math.max(
+      0,
+      Math.min(elementStart + elementSize / 2 - clientSize / 2, maxScroll),
+    );
+    scrollEl.scrollTo({
+      [isHorizontal ? "left" : "top"]: nextScroll,
+      behavior,
+    });
+    figEditorSyncOverflowState(scrollEl, scrollEl, axis);
+  });
+}
+
+
+/* Select — dropdown-styled trigger + fig-popup listbox */
+/** Parse options attr — same formats as fig-options / propskit-select. */
+function figSelectParseOptionsAttribute(raw) {
+  const text = raw || "";
+  if (text.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(text);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      /* fall through */
+    }
+  }
+  const delimiter = text.includes("\n") ? "\n" : ",";
+  return text
+    .split(delimiter)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function figSelectOptionEntryValue(opt) {
+  if (opt && typeof opt === "object") {
+    return String(opt.value ?? opt.label ?? "");
+  }
+  return String(opt ?? "");
+}
+
+function figSelectOptionEntryLabel(opt) {
+  if (opt && typeof opt === "object") {
+    return String(opt.label ?? opt.value ?? "");
+  }
+  return String(opt ?? "");
+}
+
+/**
+ * A selectable option for fig-select.
+ * Supports light-DOM slots: `slot="prepend"` (leading) and `slot="append"` (trailing).
+ * Use the `label` attribute for the closed-trigger label when option content is rich.
+ *
+ * @attr {string} value - Option value
+ * @attr {string} label - Optional display label for the select trigger
+ * @attr {boolean} disabled - Whether the option is disabled
+ * @attr {boolean} selected - Whether the option is selected
+ */
+class FigSelectOption extends HTMLElement {
+  static get observedAttributes() {
+    return ["value", "disabled", "selected", "label"];
+  }
+
+  get value() {
+    const attr = this.getAttribute("value");
+    if (attr !== null) return attr;
+    return (this.textContent || "").trim();
+  }
+
+  set value(val) {
+    if (val === null || val === undefined) {
+      this.removeAttribute("value");
+    } else {
+      this.setAttribute("value", String(val));
+    }
+  }
+
+  get disabled() {
+    return figEditorBooleanAttribute(this, "disabled");
+  }
+
+  set disabled(val) {
+    if (val) this.setAttribute("disabled", "");
+    else this.removeAttribute("disabled");
+  }
+
+  get selected() {
+    return figEditorBooleanAttribute(this, "selected");
+  }
+
+  set selected(val) {
+    if (val) this.setAttribute("selected", "");
+    else this.removeAttribute("selected");
+  }
+
+  connectedCallback() {
+    if (!this.hasAttribute("role")) this.setAttribute("role", "option");
+    if (!this.hasAttribute("tabindex")) this.setAttribute("tabindex", "-1");
+    this.#syncDisabled();
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) return;
+    if (name === "disabled") this.#syncDisabled();
+  }
+
+  #syncDisabled() {
+    const disabled = this.disabled;
+    if (disabled) {
+      this.setAttribute("aria-disabled", "true");
+      this.setAttribute("tabindex", "-1");
+    } else {
+      this.removeAttribute("aria-disabled");
+      if (!this.hasAttribute("tabindex")) this.setAttribute("tabindex", "-1");
+    }
+  }
+}
+figEditorDefineElement("fig-select-option", FigSelectOption);
+
+/** Light-DOM panel wrapper projected into fig-select's popup; owns overflow buttons. */
+class FigSelectOptions extends HTMLElement {
+  #navStart = null;
+  #navEnd = null;
+  #resizeObserver = null;
+  #boundSyncOverflow = this.syncOverflow.bind(this);
+
+  connectedCallback() {
+    if (!this.hasAttribute("slot")) this.setAttribute("slot", "panel");
+    this.#unwrapLegacyChooser();
+    this.#markFirstSeparatorBorderless();
+    this.#ensureNavButtons();
+    this.addEventListener("scroll", this.#boundSyncOverflow, { passive: true });
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = new ResizeObserver(() => this.syncOverflow());
+    this.#resizeObserver.observe(this);
+    requestAnimationFrame(() => this.syncOverflow());
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener("scroll", this.#boundSyncOverflow);
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = null;
+    this.#removeNavButtons();
+  }
+
+  syncOverflow() {
+    this.#markFirstSeparatorBorderless();
+    return figEditorSyncOverflowState(this, this, "y");
+  }
+
+  scrollToOption(option, behavior = "auto") {
+    figEditorScrollElementToCenter(this, option, "y", behavior);
+  }
+
+  #unwrapLegacyChooser() {
+    const chooser = this.querySelector(":scope > fig-chooser");
+    if (!chooser) return;
+    while (chooser.firstChild) {
+      this.insertBefore(chooser.firstChild, chooser);
+    }
+    chooser.remove();
+  }
+
+  #markFirstSeparatorBorderless() {
+    const firstContent = Array.from(this.children).find(
+      (child) => !child.hasAttribute("data-fig-select-nav"),
+    );
+    if (firstContent?.tagName === "FIG-SEPARATOR") {
+      firstContent.setAttribute("borderless", "");
+    }
+  }
+
+  #ensureNavButtons() {
+    if (
+      this.#navStart &&
+      this.#navEnd &&
+      this.contains(this.#navStart) &&
+      this.contains(this.#navEnd)
+    ) {
+      return;
+    }
+    this.#removeNavButtons();
+    const buttons = figEditorCreateOverflowButtons({
+      owner: "select",
+      startLabel: "Scroll up",
+      endLabel: "Scroll down",
+      onStart: () => figEditorScrollOverflowPage(this, "y", -1),
+      onEnd: () => figEditorScrollOverflowPage(this, "y", 1),
+    });
+    this.#navStart = buttons.start;
+    this.#navEnd = buttons.end;
+    this.prepend(this.#navStart);
+    this.append(this.#navEnd);
+  }
+
+  #removeNavButtons() {
+    this.#navStart?.remove();
+    this.#navEnd?.remove();
+    this.#navStart = null;
+    this.#navEnd = null;
+    this.classList.remove("overflow-start", "overflow-end");
+  }
+}
+figEditorDefineElement("fig-select-options", FigSelectOptions);
+
+class FigSelect extends HTMLElement {
+  #button = null;
+  #popup = null;
+  #prependEl = null;
+  #labelEl = null;
+  #panelSlot = null;
+  #observer = null;
+  #initialized = false;
+  #focusedIndex = -1;
+  #syncingValue = false;
+  #popupPositionPatched = false;
+  #originalPositionPopup = null;
+  /**
+   * After open align, ignore content/scroll-driven positionPopup passes so
+   * overflow paging isn't yanked back. Still realign when the trigger moves
+   * or the viewport size changes (window resize, layout shift, page scroll).
+   */
+  #freezeMenuPosition = false;
+  #frozenLabelRect = null;
+  #frozenViewport = null;
+  #syncingOptions = false;
+  #boundTriggerClick = this.#handleTriggerClick.bind(this);
+  #boundOptionClick = this.#handleOptionClick.bind(this);
+  #boundOptionPointerOver = this.#handleOptionPointerOver.bind(this);
+  #boundKeydown = this.#handleKeydown.bind(this);
+  #boundPopupClose = this.#handlePopupClose.bind(this);
+  #boundSlotChange = this.#handleSlotChange.bind(this);
+
+  static get observedAttributes() {
+    return [
+      "value",
+      "disabled",
+      "label",
+      "options",
+      "position",
+      "offset",
+      "closedby",
+      "open",
+    ];
+  }
+
+  get value() {
+    return this.getAttribute("value") ?? "";
+  }
+
+  set value(val) {
+    if (val === null || val === undefined) this.removeAttribute("value");
+    else this.setAttribute("value", String(val));
+  }
+
+  get open() {
+    return figEditorBooleanAttribute(this, "open");
+  }
+
+  set open(val) {
+    if (val) this.setAttribute("open", "");
+    else this.removeAttribute("open");
+  }
+
+  connectedCallback() {
+    if (!this.#initialized) this.#initialize();
+    this.#ensurePanelSlotAttrs();
+    this.#syncOptionsFromAttribute();
+    this.#syncDisabled();
+    this.#syncPopupAttrs();
+    this.#syncValue();
+    this.#setupListeners();
+    this.#setupObserver();
+    if (this.open) this.#openList();
+  }
+
+  disconnectedCallback() {
+    this.#teardownListeners();
+    document.removeEventListener("keydown", this.#boundKeydown, true);
+    this.#observer?.disconnect();
+    this.#observer = null;
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue || !this.#initialized) return;
+    if (name === "options") {
+      this.#syncOptionsFromAttribute();
+      this.#syncValue();
+      return;
+    }
+    if (name === "value" || name === "label") {
+      this.#syncValue();
+      return;
+    }
+    if (name === "disabled") {
+      this.#syncDisabled();
+      return;
+    }
+    if (name === "open") {
+      if (newValue === null || newValue === "false") this.#closeList();
+      else this.#openList();
+      return;
+    }
+    if (name === "position" || name === "offset" || name === "closedby") {
+      this.#syncPopupAttrs();
+    }
+  }
+
+  focus(options) {
+    this.#button?.focus(options);
+  }
+
+  blur() {
+    this.#button?.blur();
+  }
+
+  #isMenuChild(node) {
+    return (
+      node?.nodeType === 1 &&
+      (node.tagName === "FIG-SELECT-OPTION" ||
+        node.tagName === "FIG-SEPARATOR" ||
+        node.tagName === "FIG-SELECT-OPTIONS")
+    );
+  }
+
+  #ensurePanelSlotAttrs() {
+    for (const panel of this.querySelectorAll(":scope > fig-select-options")) {
+      if (!panel.hasAttribute("slot")) panel.setAttribute("slot", "panel");
+    }
+  }
+
+  #getPanel() {
+    const assigned = this.#panelSlot?.assignedElements({ flatten: true }) ?? [];
+    const fromSlot = assigned.find(
+      (el) => el.tagName === "FIG-SELECT-OPTIONS",
+    );
+    if (fromSlot) return fromSlot;
+    return this.querySelector(":scope > fig-select-options");
+  }
+
+  #hasAuthoredOptions() {
+    return Boolean(
+      this.querySelector(
+        ":scope > fig-select-option:not([data-fig-generated]), :scope > fig-select-options > fig-select-option:not([data-fig-generated])",
+      ),
+    );
+  }
+
+  #ensureOptionsPanel() {
+    let panel = this.#getPanel();
+    if (panel) {
+      if (!panel.hasAttribute("slot")) panel.setAttribute("slot", "panel");
+      return panel;
+    }
+    panel = document.createElement("fig-select-options");
+    panel.setAttribute("slot", "panel");
+    panel.setAttribute("data-fig-generated", "");
+    this.appendChild(panel);
+    return panel;
+  }
+
+  /**
+   * When no authored fig-select-option exists, build panel/options from the
+   * options attribute (comma / newline / JSON — same as fig-options).
+   */
+  #syncOptionsFromAttribute() {
+    if (this.#hasAuthoredOptions()) return;
+
+    const hasOptionsAttr = this.hasAttribute("options");
+    const panel = hasOptionsAttr
+      ? this.#ensureOptionsPanel()
+      : this.#getPanel();
+    if (!panel) return;
+
+    this.#syncingOptions = true;
+    try {
+      for (const opt of panel.querySelectorAll(
+        ":scope > fig-select-option[data-fig-generated]",
+      )) {
+        opt.remove();
+      }
+
+      if (!hasOptionsAttr) return;
+
+      const parsed = figSelectParseOptionsAttribute(this.getAttribute("options"));
+      const endBtn = panel.querySelector(":scope > .fig-overflow-end");
+      for (const entry of parsed) {
+        const el = document.createElement("fig-select-option");
+        el.setAttribute("data-fig-generated", "");
+        el.setAttribute("value", figSelectOptionEntryValue(entry));
+        el.textContent = figSelectOptionEntryLabel(entry);
+        if (endBtn) panel.insertBefore(el, endBtn);
+        else panel.appendChild(el);
+      }
+    } finally {
+      this.#syncingOptions = false;
+    }
+  }
+
+  #initialize() {
+    this.#initialized = true;
+    const shadow = this.attachShadow({ mode: "open" });
+    shadow.innerHTML = `
+      <style>
+        :host {
+          display: inline-flex;
+          position: relative;
+          align-items: center;
+          min-width: 0;
+        }
+        :host([full]:not([full="false"])) {
+          display: flex;
+          width: 100%;
+        }
+        .fig-select-trigger {
+          display: flex;
+          align-items: center;
+          justify-content: flex-start;
+          flex: 1;
+          min-width: 0;
+          width: var(--fig-select-trigger-width, 100%);
+          height: 100%;
+          margin: 0;
+          padding: 0 var(--spacer-4, 1rem) 0 var(--spacer-2, 0.5rem);
+          border: 0;
+          border-radius: inherit;
+          background: transparent;
+          box-shadow: none;
+          color: inherit;
+          font: inherit;
+          font-weight: inherit;
+          text-align: left;
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          cursor: default;
+        }
+        .fig-select-trigger:has(.fig-select-prepend:not(:empty)) {
+          padding-left: 0;
+        }
+        .fig-select-trigger:hover,
+        .fig-select-trigger:active,
+        .fig-select-trigger:active:hover {
+          background: transparent;
+          box-shadow: none;
+          color: inherit;
+        }
+        .fig-select-trigger:focus-visible,
+        .fig-select-trigger[data-focus-visible] {
+          outline: var(--figma-focus-outline);
+          outline-offset: var(--figma-focus-outline-offset);
+        }
+        :host([disabled]:not([disabled="false"])) .fig-select-trigger,
+        :host([disabled]:not([disabled="false"])) .fig-select-label {
+          color: var(--figma-color-text-tertiary);
+        }
+        .fig-select-label {
+          display: block;
+          width: 100%;
+          min-width: 0;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+          text-align: left;
+        }
+        .fig-select-prepend {
+          display: inline-flex;
+          flex: 0 0 auto;
+          align-items: center;
+          margin-right: var(--spacer-1, 0.25rem);
+          pointer-events: none;
+        }
+        .fig-select-prepend:empty {
+          display: none;
+        }
+        /* Listbox chrome from document fig-select::part(listbox).
+           Overflow UI lives on slotted fig-select-options.
+           Never set display except when open — closed <dialog> must stay display:none. */
+        dialog[is="fig-popup"] {
+          flex-direction: column;
+          overflow: hidden;
+        }
+        dialog[is="fig-popup"][open] {
+          display: flex;
+        }
+        ::slotted(fig-select-options) {
+          flex: 1 1 auto;
+          min-height: 0;
+          max-height: inherit;
+        }
+      </style>
+    `;
+
+    const button = document.createElement("fig-button");
+    button.className = "fig-select-trigger";
+    button.setAttribute("part", "trigger");
+    button.setAttribute("variant", "ghost");
+    button.setAttribute("aria-haspopup", "listbox");
+    button.setAttribute("aria-expanded", "false");
+
+    const prependEl = document.createElement("span");
+    prependEl.className = "fig-select-prepend";
+    prependEl.setAttribute("part", "prepend");
+    prependEl.setAttribute("aria-hidden", "true");
+
+    const labelEl = document.createElement("span");
+    labelEl.className = "fig-select-label";
+    labelEl.setAttribute("part", "label");
+    button.append(prependEl, labelEl);
+
+    const popup = document.createElement("dialog", { is: "fig-popup" });
+    popup.setAttribute("is", "fig-popup");
+    popup.setAttribute("part", "listbox");
+    popup.setAttribute("theme", "menu");
+    popup.setAttribute("role", "listbox");
+    // Top-layer via popover so the menu escapes ancestor contain/overflow
+    // (e.g. fig-fill-picker-dialog). Stays in shadow so option slots still work —
+    // unlike tooltips, we cannot portal this popup to the overlay root.
+    if ("popover" in HTMLElement.prototype) {
+      popup.setAttribute("popover", "manual");
+    }
+    popup.id = figEditorUniqueId();
+    button.setAttribute("aria-controls", popup.id);
+
+    const panelSlot = document.createElement("slot");
+    panelSlot.setAttribute("name", "panel");
+    popup.appendChild(panelSlot);
+
+    shadow.append(button, popup);
+
+    this.#button = button;
+    this.#prependEl = prependEl;
+    this.#labelEl = labelEl;
+    this.#popup = popup;
+    this.#panelSlot = panelSlot;
+    popup.anchor = button;
+
+    this.#ensurePanelSlotAttrs();
+    this.#installPopupPositioning();
+
+    if (!this.hasAttribute("value")) {
+      const selected = this.#getOptions().find((opt) =>
+        figEditorBooleanAttribute(opt, "selected"),
+      );
+      if (selected) this.setAttribute("value", selected.value);
+    }
+  }
+
+  #installPopupPositioning() {
+    if (!this.#popup || this.#popupPositionPatched) return;
+    if (typeof this.#popup.positionPopup !== "function") return;
+    this.#originalPositionPopup = this.#popup.positionPopup.bind(this.#popup);
+    this.#popup.positionPopup = () => {
+      if (!this.open) {
+        this.#originalPositionPopup?.();
+        return;
+      }
+      this.#positionPopupOverSelected();
+    };
+    this.#popupPositionPatched = true;
+  }
+
+  #getOptionTextRect(option) {
+    if (!option) return null;
+    const range = document.createRange();
+    range.selectNodeContents(option);
+    const rects = [...range.getClientRects()].filter(
+      (rect) => rect.width > 0 && rect.height > 0,
+    );
+    if (rects.length) return rects[0];
+    return option.getBoundingClientRect();
+  }
+
+  #getViewportMargins() {
+    if (typeof this.#popup?.parseViewportMargins === "function") {
+      return this.#popup.parseViewportMargins();
+    }
+    return { top: 8, right: 8, bottom: 8, left: 8 };
+  }
+
+  #readLabelRectSnapshot() {
+    const rect = this.#labelEl?.getBoundingClientRect();
+    if (!rect) return null;
+    return {
+      x: rect.x,
+      y: rect.y,
+      width: rect.width,
+      height: rect.height,
+    };
+  }
+
+  #readViewportSnapshot() {
+    const vv = window.visualViewport;
+    return {
+      width: vv?.width ?? window.innerWidth,
+      height: vv?.height ?? window.innerHeight,
+      offsetLeft: vv?.offsetLeft ?? 0,
+      offsetTop: vv?.offsetTop ?? 0,
+    };
+  }
+
+  #rectSnapshotChanged(prev, next, epsilon = 0.25) {
+    if (!prev && !next) return false;
+    if (!prev || !next) return true;
+    return (
+      Math.abs(prev.x - next.x) > epsilon ||
+      Math.abs(prev.y - next.y) > epsilon ||
+      Math.abs(prev.width - next.width) > epsilon ||
+      Math.abs(prev.height - next.height) > epsilon
+    );
+  }
+
+  #viewportSnapshotChanged(prev, next, epsilon = 0.25) {
+    if (!prev && !next) return false;
+    if (!prev || !next) return true;
+    return (
+      Math.abs(prev.width - next.width) > epsilon ||
+      Math.abs(prev.height - next.height) > epsilon ||
+      Math.abs(prev.offsetLeft - next.offsetLeft) > epsilon ||
+      Math.abs(prev.offsetTop - next.offsetTop) > epsilon
+    );
+  }
+
+  #shouldSkipFrozenPositionPass() {
+    if (!this.#freezeMenuPosition) return false;
+    const labelMoved = this.#rectSnapshotChanged(
+      this.#frozenLabelRect,
+      this.#readLabelRectSnapshot(),
+    );
+    const viewportChanged = this.#viewportSnapshotChanged(
+      this.#frozenViewport,
+      this.#readViewportSnapshot(),
+    );
+    // Skip only when neither the trigger nor the viewport moved — typical of
+    // overflow scroll / content sync fighting the open-time alignment.
+    return !labelMoved && !viewportChanged;
+  }
+
+  #rememberFrozenGeometry() {
+    this.#frozenLabelRect = this.#readLabelRectSnapshot();
+    this.#frozenViewport = this.#readViewportSnapshot();
+  }
+
+  #positionPopupOverSelected() {
+    // Content ResizeObserver / overflow scroll re-enter here; keep the
+    // open-time alignment unless the trigger or viewport actually changed.
+    if (this.#shouldSkipFrozenPositionPass()) return;
+
+    const popup = this.#popup;
+    const label = this.#labelEl;
+    if (!popup || !label) {
+      this.#originalPositionPopup?.();
+      return;
+    }
+
+    const options = this.#getOptions();
+    const selected =
+      options.find((opt) => this.#optionValue(opt) === this.value) ||
+      options[0];
+    if (!selected) {
+      this.#originalPositionPopup?.();
+      return;
+    }
+
+    // Lay out with the default positioning first so option metrics are valid.
+    this.#originalPositionPopup?.();
+
+    const popupRect = popup.getBoundingClientRect();
+    const labelRect = label.getBoundingClientRect();
+    const optionTextRect = this.#getOptionTextRect(selected);
+    if (
+      !popupRect.width ||
+      !popupRect.height ||
+      !labelRect.width ||
+      !optionTextRect
+    ) {
+      return;
+    }
+
+    const selectedOffsetX = optionTextRect.left - popupRect.left;
+    const selectedOffsetY = optionTextRect.top - popupRect.top;
+    const full = figEditorBooleanAttribute(this, "full");
+    // [full]: pin menu to host width/edges. Otherwise overlay selected
+    // option text on the trigger label (blend-mode style).
+    let left = full
+      ? this.getBoundingClientRect().left
+      : labelRect.left - selectedOffsetX;
+    let top = labelRect.top - selectedOffsetY;
+
+    // Keep the whole menu in-view when aligning over the selected option
+    // would otherwise push it past a viewport edge (corners / far sides).
+    const margins = this.#getViewportMargins();
+    if (typeof popup.clampToViewport === "function") {
+      ({ left, top } = popup.clampToViewport({ left, top }, popupRect, margins));
+    } else {
+      const minLeft = margins.left;
+      const minTop = margins.top;
+      const maxLeft = window.innerWidth - popupRect.width - margins.right;
+      const maxTop = window.innerHeight - popupRect.height - margins.bottom;
+      left = Math.min(Math.max(left, minLeft), Math.max(minLeft, maxLeft));
+      top = Math.min(Math.max(top, minTop), Math.max(minTop, maxTop));
+    }
+
+    // !important: fig-select::part(listbox) and dialog UA rules can otherwise
+    // keep the menu at its static/anchor position past the viewport edge.
+    popup.style.setProperty("right", "auto", "important");
+    popup.style.setProperty("bottom", "auto", "important");
+    popup.style.setProperty("left", `${Math.round(left)}px`, "important");
+    popup.style.setProperty("top", `${Math.round(top)}px`, "important");
+
+    // Nudge the panel scroller so the selected label stays over the trigger.
+    const panel = this.#getPanel();
+    const alignedTextRect = this.#getOptionTextRect(selected);
+    if (
+      alignedTextRect &&
+      panel &&
+      panel.scrollHeight > panel.clientHeight + 1
+    ) {
+      const deltaY = alignedTextRect.top - labelRect.top;
+      if (Math.abs(deltaY) > 0.5) {
+        panel.scrollTop += deltaY;
+      }
+      panel.syncOverflow?.();
+    }
+
+    if (this.#freezeMenuPosition || this.open) {
+      this.#rememberFrozenGeometry();
+    }
+  }
+
+  #setupListeners() {
+    this.#button?.addEventListener("click", this.#boundTriggerClick);
+    this.#button?.addEventListener("keydown", this.#boundKeydown);
+    // Host click: slotted options stay in light DOM (not dialog.contains).
+    this.addEventListener("click", this.#boundOptionClick);
+    this.addEventListener("pointerover", this.#boundOptionPointerOver);
+    this.#popup?.addEventListener("keydown", this.#boundKeydown);
+    this.#popup?.addEventListener("close", this.#boundPopupClose);
+    this.#panelSlot?.addEventListener("slotchange", this.#boundSlotChange);
+  }
+
+  #teardownListeners() {
+    this.#button?.removeEventListener("click", this.#boundTriggerClick);
+    this.#button?.removeEventListener("keydown", this.#boundKeydown);
+    this.removeEventListener("click", this.#boundOptionClick);
+    this.removeEventListener("pointerover", this.#boundOptionPointerOver);
+    this.#popup?.removeEventListener("keydown", this.#boundKeydown);
+    this.#popup?.removeEventListener("close", this.#boundPopupClose);
+    this.#panelSlot?.removeEventListener("slotchange", this.#boundSlotChange);
+  }
+
+  #handleSlotChange() {
+    this.#ensurePanelSlotAttrs();
+    this.#syncValue();
+  }
+
+  #setupObserver() {
+    if (this.#observer) return;
+    this.#observer = new MutationObserver((mutations) => {
+      if (this.#syncingValue || this.#syncingOptions) return;
+      let needsSync = false;
+      for (const mutation of mutations) {
+        if (mutation.type === "childList") {
+          if (
+            [...mutation.addedNodes].some((node) => this.#isMenuChild(node)) ||
+            [...mutation.removedNodes].some((node) => this.#isMenuChild(node)) ||
+            mutation.target?.closest?.("fig-select-option")
+          ) {
+            needsSync = true;
+          }
+        }
+        if (
+          mutation.type === "attributes" &&
+          mutation.target?.tagName === "FIG-SELECT-OPTION"
+        ) {
+          if (
+            mutation.attributeName === "value" ||
+            mutation.attributeName === "disabled" ||
+            mutation.attributeName === "label"
+          ) {
+            needsSync = true;
+          } else if (mutation.attributeName === "selected") {
+            if (figEditorBooleanAttribute(mutation.target, "selected")) {
+              const nextValue = this.#optionValue(mutation.target);
+              if ((this.getAttribute("value") ?? "") !== nextValue) {
+                this.setAttribute("value", nextValue);
+                needsSync = true;
+              }
+            } else if (
+              this.#optionValue(mutation.target) ===
+              (this.getAttribute("value") ?? "")
+            ) {
+              needsSync = true;
+            }
+          }
+        }
+        if (
+          mutation.type === "characterData" &&
+          mutation.target?.parentElement?.tagName === "FIG-SELECT-OPTION"
+        ) {
+          needsSync = true;
+        }
+      }
+      if (needsSync) this.#syncValue();
+    });
+    this.#observer.observe(this, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ["value", "disabled", "selected", "label"],
+    });
+  }
+
+  #getOptions({ enabledOnly = false } = {}) {
+    const panel = this.#getPanel();
+    const options = panel
+      ? Array.from(panel.querySelectorAll(":scope > fig-select-option"))
+      : [];
+    if (!enabledOnly) return options;
+    return options.filter((opt) => !figEditorBooleanAttribute(opt, "disabled"));
+  }
+
+  #optionValue(option) {
+    if (!option) return "";
+    if (typeof option.value === "string") return option.value;
+    const attr = option.getAttribute?.("value");
+    if (attr != null) return attr;
+    return (option.textContent || "").trim();
+  }
+
+  #optionLabel(option) {
+    if (!option) return "";
+    const labelAttr = option.getAttribute?.("label");
+    if (labelAttr != null && labelAttr !== "") return labelAttr.trim();
+
+    // Ignore prepend/append slot content when deriving a label from children.
+    const parts = [];
+    for (const node of option.childNodes) {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const text = node.textContent?.trim();
+        if (text) parts.push(text);
+        continue;
+      }
+      if (!(node instanceof Element)) continue;
+      const slot = node.getAttribute("slot");
+      if (slot === "prepend" || slot === "append") continue;
+      const text = node.textContent?.trim();
+      if (text) parts.push(text);
+    }
+    if (parts.length) return parts.join(" ").trim();
+    return (option.textContent || "").trim();
+  }
+
+  #syncPrepend(option) {
+    if (!this.#prependEl) return;
+    const source = option?.querySelector?.(':scope > [slot="prepend"]');
+    this.#prependEl.replaceChildren(
+      ...Array.from(source?.childNodes ?? [], (node) => node.cloneNode(true)),
+    );
+  }
+
+  #syncPopupAttrs() {
+    if (!this.#popup) return;
+    this.#popup.setAttribute(
+      "position",
+      this.getAttribute("position") || "bottom left",
+    );
+    const offset = this.getAttribute("offset");
+    if (offset) this.#popup.setAttribute("offset", offset);
+    else this.#popup.removeAttribute("offset");
+    const closedby = this.getAttribute("closedby");
+    if (closedby) this.#popup.setAttribute("closedby", closedby);
+    else this.#popup.removeAttribute("closedby");
+  }
+
+  #syncDisabled() {
+    const disabled = figEditorBooleanAttribute(this, "disabled");
+    if (this.#button) {
+      if (disabled) this.#button.setAttribute("disabled", "");
+      else this.#button.removeAttribute("disabled");
+    }
+    if (disabled && this.open) this.open = false;
+  }
+
+  #pickFallbackOption(options) {
+    if (!options.length) return null;
+    const selected = options.find((opt) =>
+      figEditorBooleanAttribute(opt, "selected"),
+    );
+    if (selected && !figEditorBooleanAttribute(selected, "disabled")) {
+      return selected;
+    }
+    return (
+      options.find((opt) => !figEditorBooleanAttribute(opt, "disabled")) ||
+      options[0] ||
+      null
+    );
+  }
+
+  #emitValueEvents(value) {
+    this.dispatchEvent(
+      new CustomEvent("input", {
+        detail: value,
+        bubbles: true,
+        composed: true,
+      }),
+    );
+    this.dispatchEvent(
+      new CustomEvent("change", {
+        detail: value,
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  #syncValue() {
+    if (this.#syncingValue) return;
+    this.#syncingValue = true;
+    try {
+      const options = this.#getOptions();
+      const hasValueAttr = this.hasAttribute("value");
+      const previousValue = hasValueAttr ? this.getAttribute("value") : null;
+      let match = hasValueAttr
+        ? options.find((opt) => this.#optionValue(opt) === previousValue)
+        : null;
+      let valueCorrected = false;
+
+      if (!match) {
+        if (hasValueAttr) {
+          // Options may not be built yet (options attr sync). Keep value until then.
+          if (!options.length) {
+            if (this.#labelEl) {
+              this.#labelEl.textContent =
+                previousValue || this.getAttribute("label") || "";
+            }
+            return;
+          }
+          // Value orphaned (option removed / value attr changed) — clamp or clear.
+          match = this.#pickFallbackOption(options);
+          if (match) {
+            const nextValue = this.#optionValue(match);
+            if (previousValue !== nextValue) {
+              this.setAttribute("value", nextValue);
+              valueCorrected = true;
+            }
+          } else {
+            this.removeAttribute("value");
+            valueCorrected = true;
+          }
+        } else {
+          // No host value yet — honor a selected option if present.
+          match = options.find((opt) =>
+            figEditorBooleanAttribute(opt, "selected"),
+          );
+          if (match) {
+            this.setAttribute("value", this.#optionValue(match));
+            valueCorrected = true;
+          }
+        }
+      }
+
+      for (const opt of options) {
+        const selected = opt === match;
+        opt.setAttribute("aria-selected", selected ? "true" : "false");
+        if (selected) opt.setAttribute("selected", "");
+        else opt.removeAttribute("selected");
+      }
+
+      const label =
+        (match && this.#optionLabel(match)) || this.getAttribute("label") || "";
+      if (this.#labelEl) this.#labelEl.textContent = label;
+      this.#syncPrepend(match);
+
+      const ariaLabel = this.getAttribute("label") || "Select";
+      this.#button?.setAttribute("aria-label", ariaLabel);
+
+      // Don't scrollToOption while open — reposition/sync would fight overflow paging.
+      this.#getPanel()?.syncOverflow?.();
+
+      if (valueCorrected) {
+        this.#emitValueEvents(this.getAttribute("value") ?? "");
+      }
+    } finally {
+      this.#syncingValue = false;
+    }
+  }
+
+  #handleTriggerClick(e) {
+    if (figEditorBooleanAttribute(this, "disabled")) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const nextOpen = !this.open;
+    if (nextOpen && this.#popup && this.#button) {
+      this.#popup.anchor = this.#button;
+    }
+    this.open = nextOpen;
+  }
+
+  #handleOptionClick(e) {
+    const path = typeof e.composedPath === "function" ? e.composedPath() : [];
+    const option = path.find(
+      (node) => node?.tagName === "FIG-SELECT-OPTION",
+    );
+    if (!option || !this.contains(option)) return;
+    if (figEditorBooleanAttribute(option, "disabled")) return;
+    // Do not stopPropagation — React light-DOM onClick must still fire.
+    this.#selectOption(option);
+  }
+
+  /**
+   * Fires `optionhover` with the enabled option's value in `event.detail`
+   * without changing the current selection.
+   */
+  #handleOptionPointerOver(e) {
+    const path = typeof e.composedPath === "function" ? e.composedPath() : [];
+    const option = path.find(
+      (node) => node?.tagName === "FIG-SELECT-OPTION",
+    );
+    if (!option || !this.contains(option)) return;
+    if (figEditorBooleanAttribute(option, "disabled")) return;
+    if (
+      e.relatedTarget instanceof Node &&
+      option.contains(e.relatedTarget)
+    ) {
+      return;
+    }
+    this.dispatchEvent(
+      new CustomEvent("optionhover", {
+        detail: this.#optionValue(option),
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  #handleKeydown(e) {
+    if (e.currentTarget === document && e.key !== "Escape") return;
+
+    const listOpen = this.open && (this.#popup?.matches?.(":open") ?? false);
+    if (!listOpen) {
+      if (
+        this.#button?.contains(e.target) &&
+        (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ")
+      ) {
+        e.preventDefault();
+        if (this.#popup && this.#button) this.#popup.anchor = this.#button;
+        this.open = true;
+        requestAnimationFrame(() => {
+          const options = this.#getOptions({ enabledOnly: true });
+          const selectedIndex = options.findIndex(
+            (opt) => this.#optionValue(opt) === this.value,
+          );
+          this.#focusOptionAt(selectedIndex >= 0 ? selectedIndex : 0);
+        });
+      }
+      return;
+    }
+
+    const options = this.#getOptions({ enabledOnly: true });
+    if (!options.length) return;
+
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        this.#syncFocusedIndex();
+        this.#focusOptionAt(this.#focusedIndex + 1);
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        this.#syncFocusedIndex();
+        this.#focusOptionAt(this.#focusedIndex - 1);
+        break;
+      case "Home":
+        e.preventDefault();
+        this.#focusOptionAt(0);
+        break;
+      case "End":
+        e.preventDefault();
+        this.#focusOptionAt(options.length - 1);
+        break;
+      case "Escape":
+        e.preventDefault();
+        this.open = false;
+        this.#button?.focus();
+        break;
+      case "Enter":
+      case " ": {
+        this.#syncFocusedIndex();
+        const focused = options[this.#focusedIndex];
+        if (!focused) return;
+        e.preventDefault();
+        this.#selectOption(focused);
+        break;
+      }
+    }
+  }
+
+  #handlePopupClose() {
+    if (this.hasAttribute("open")) this.removeAttribute("open");
+    this.#button?.setAttribute("aria-expanded", "false");
+    this.#button?.focus();
+    this.#focusedIndex = -1;
+  }
+
+  #selectOption(option) {
+    const value = this.#optionValue(option);
+    this.setAttribute("value", value);
+    this.#syncValue();
+    this.#emitValueEvents(value);
+    this.open = false;
+  }
+
+  #getEnabledOptions() {
+    return this.#getOptions({ enabledOnly: true });
+  }
+
+  #syncFocusedIndex() {
+    const options = this.#getEnabledOptions();
+    if (!options.length) {
+      this.#focusedIndex = -1;
+      return;
+    }
+    const active = options.find((opt) => opt === document.activeElement);
+    const index = active ? options.indexOf(active) : -1;
+    this.#focusedIndex = index >= 0 ? index : this.#focusedIndex;
+  }
+
+  #focusOptionAt(index) {
+    const options = this.#getEnabledOptions();
+    if (!options.length) return;
+    const next = ((index % options.length) + options.length) % options.length;
+    this.#focusedIndex = next;
+    options[next]?.focus();
+  }
+
+  #syncPopupWidth() {
+    if (!this.#popup || !this.#button) return;
+    const hostWidth = Math.ceil(this.getBoundingClientRect().width);
+    const triggerWidth = Math.ceil(this.#button.getBoundingClientRect().width);
+    const anchorWidth = Math.max(hostWidth, triggerWidth, 96);
+
+    // Use !important — fig-select::part(listbox) width rules beat element.style.
+    // Menus size to their options while remaining at least as wide as the trigger.
+    this.#popup.style.setProperty("width", "max-content", "important");
+    this.#popup.style.setProperty("min-width", `${anchorWidth}px`, "important");
+    this.#popup.style.setProperty(
+      "max-width",
+      "min(20rem, calc(100vw - 1rem))",
+      "important",
+    );
+  }
+
+  #openList() {
+    if (!this.#popup || figEditorBooleanAttribute(this, "disabled")) return;
+    if (this.#button) this.#popup.anchor = this.#button;
+    this.#installPopupPositioning();
+    this.#freezeMenuPosition = false;
+    this.#frozenLabelRect = null;
+    this.#frozenViewport = null;
+    this.#syncValue();
+    this.#syncPopupWidth();
+    this.#popup.open = true;
+    document.addEventListener("keydown", this.#boundKeydown, true);
+    this.#button?.setAttribute("aria-expanded", "true");
+    this.#focusedIndex = -1;
+    requestAnimationFrame(() => {
+      this.#syncPopupWidth();
+      this.#positionPopupOverSelected();
+      const panel = this.#getPanel();
+      const options = this.#getEnabledOptions();
+      const selectedIndex = options.findIndex(
+        (opt) => this.#optionValue(opt) === this.value,
+      );
+      if (selectedIndex >= 0) {
+        this.#focusOptionAt(selectedIndex);
+      } else if (
+        this.#button?.hasAttribute("data-focus-visible") ||
+        this.#button?.matches?.(":focus-visible")
+      ) {
+        this.#focusOptionAt(0);
+      }
+      panel?.syncOverflow?.();
+      // Freeze after open align so later positionPopup passes don't undo scroll.
+      // Window resize / trigger movement still realigns via geometry checks.
+      this.#freezeMenuPosition = true;
+      this.#rememberFrozenGeometry();
+    });
+  }
+
+  #closeList() {
+    if (!this.#popup) return;
+    this.#freezeMenuPosition = false;
+    this.#frozenLabelRect = null;
+    this.#frozenViewport = null;
+    document.removeEventListener("keydown", this.#boundKeydown, true);
+    this.#popup.open = false;
+    this.#button?.setAttribute("aria-expanded", "false");
+  }
+}
+figEditorDefineElement("fig-select", FigSelect);
+
+
 // FigFillPicker
 const GRADIENT_INTERPOLATION_SPACES = [
   "srgb",