@rogieking/figui3 2.17.1 → 2.17.2

package/components.css

@@ -2044,6 +2044,68 @@ dialog[is="fig-dialog"] {
   z-index: var(--z-index);
 }
 
+dialog[is="fig-popup"] {
+  --z-index: 999999;
+  z-index: var(--z-index);
+  position: fixed;
+  margin: 0;
+  min-width: 0;
+  width: max-content;
+  max-width: calc(100vw - var(--spacer-4));
+  max-height: calc(100vh - var(--spacer-4));
+  padding: var(--spacer-2);
+  overflow: auto;
+
+  &[open] {
+    display: block;
+  }
+
+  &[variant="popover"] {
+    overflow: visible;
+    box-shadow: inset 0 0.5px 0 0 rgba(255, 255, 255, 0.1);
+    filter: drop-shadow(0px 1px 1.5px rgba(0, 0, 0, 0.1))
+      drop-shadow(0px 2.5px 6px rgba(0, 0, 0, 0.13))
+      drop-shadow(0px 0px 0.5px rgba(0, 0, 0, 0.15));
+
+    &:after {
+      content: "";
+      background-color: inherit;
+      clip-path: path(
+        "M16 0H0L0 1H0.757359C1.55301 1 2.31607 1.31607 2.87868 1.87868L6.29587 5.29587C7.23704 6.23704 8.76296 6.23704 9.70413 5.29587L13.1213 1.87868C13.6839 1.31607 14.447 1 15.2426 1H16V0Z"
+      );
+      position: absolute;
+      width: 1rem;
+      height: 6px;
+      z-index: 2;
+      pointer-events: none;
+    }
+
+    &[data-beak-side="bottom"]:after {
+      top: calc(100% - 1px);
+      left: var(--beak-offset, 50%);
+      transform: translateX(-50%);
+    }
+
+    &[data-beak-side="top"]:after {
+      top: 1px;
+      left: var(--beak-offset, 50%);
+      transform: translate(-50%, -100%) scaleY(-1);
+    }
+
+    &[data-beak-side="left"]:after {
+      left: 1px;
+      top: var(--beak-offset, 50%);
+      transform: translate(-100%, -50%) rotate(90deg);
+    }
+
+    &[data-beak-side="right"]:after {
+      left: calc(100% - 1px);
+      top: var(--beak-offset, 50%);
+      transform: translate(0, -50%) rotate(-90deg);
+    }
+  }
+}
+
 dialog[is="fig-toast"] {
   --z-index: 999999;
   z-index: var(--z-index);

package/fig.js

@@ -1050,6 +1050,547 @@ class FigDialog extends HTMLDialogElement {
 }
 customElements.define("fig-dialog", FigDialog, { extends: "dialog" });
 
+/* Popup */
+/**
+ * A floating popup foundation component based on <dialog>.
+ * @attr {string} anchor - CSS selector used to resolve the anchor element.
+ * @attr {string} position - Preferred placement as "vertical horizontal" (default: "top center").
+ * @attr {string} offset - Horizontal and vertical offset as "x y" (default: "0 0").
+ * @attr {string} variant - Visual variant. Use variant="popover" to show an anchor beak.
+ * @attr {boolean|string} open - Open when present and not "false".
+ */
+class FigPopup extends HTMLDialogElement {
+  #viewportPadding = 8;
+  #anchorObserver = null;
+  #contentObserver = null;
+  #mutationObserver = null;
+  #isPopupActive = false;
+  #boundReposition;
+  #boundScroll;
+  #boundOutsidePointerDown;
+  #rafId = null;
+
+  constructor() {
+    super();
+    this.#boundReposition = this.#queueReposition.bind(this);
+    this.#boundScroll = this.#queueReposition.bind(this);
+    this.#boundOutsidePointerDown = this.#handleOutsidePointerDown.bind(this);
+  }
+
+  static get observedAttributes() {
+    return ["open", "anchor", "position", "offset", "variant"];
+  }
+
+  get open() {
+    return this.hasAttribute("open") && this.getAttribute("open") !== "false";
+  }
+
+  set open(value) {
+    if (value === false || value === "false" || value === null) {
+      if (!this.open) return;
+      this.removeAttribute("open");
+      return;
+    }
+    if (this.open) return;
+    this.setAttribute("open", "true");
+  }
+
+  connectedCallback() {
+    if (!this.hasAttribute("position")) {
+      this.setAttribute("position", "top center");
+    }
+    if (!this.hasAttribute("role")) {
+      this.setAttribute("role", "dialog");
+    }
+    // Default dialog outside-close behavior.
+    if (!this.hasAttribute("closedby")) {
+      this.setAttribute("closedby", "any");
+    }
+
+    this.addEventListener("close", () => {
+      this.#teardownObservers();
+      if (this.hasAttribute("open")) {
+        this.removeAttribute("open");
+      }
+    });
+
+    if (this.open) {
+      this.#showPopup();
+    } else {
+      this.#hidePopup();
+    }
+  }
+
+  disconnectedCallback() {
+    this.#teardownObservers();
+    document.removeEventListener(
+      "pointerdown",
+      this.#boundOutsidePointerDown,
+      true
+    );
+    if (this.#rafId !== null) {
+      cancelAnimationFrame(this.#rafId);
+      this.#rafId = null;
+    }
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) return;
+
+    if (name === "open") {
+      if (newValue === null || newValue === "false") {
+        this.#hidePopup();
+        return;
+      }
+      this.#showPopup();
+      return;
+    }
+
+    if (this.open) {
+      this.#queueReposition();
+      this.#setupObservers();
+    }
+  }
+
+  #showPopup() {
+    if (this.#isPopupActive) {
+      this.#queueReposition();
+      return;
+    }
+
+    this.style.position = "fixed";
+    this.style.inset = "auto";
+    this.style.margin = "0";
+    this.style.zIndex = String(figGetHighestZIndex() + 1);
+
+    if (!super.open) {
+      try {
+        this.show();
+      } catch (e) {
+        // Ignore when dialog cannot be shown yet.
+      }
+    }
+
+    this.#setupObservers();
+    document.addEventListener("pointerdown", this.#boundOutsidePointerDown, true);
+    this.#queueReposition();
+    this.#isPopupActive = true;
+  }
+
+  #hidePopup() {
+    this.#isPopupActive = false;
+    this.#teardownObservers();
+    document.removeEventListener(
+      "pointerdown",
+      this.#boundOutsidePointerDown,
+      true
+    );
+
+    if (super.open) {
+      try {
+        this.close();
+      } catch (e) {
+        // Ignore when dialog is not in an open state.
+      }
+    }
+  }
+
+  #setupObservers() {
+    this.#teardownObservers();
+
+    const anchor = this.#resolveAnchor();
+    if (anchor && "ResizeObserver" in window) {
+      this.#anchorObserver = new ResizeObserver(this.#boundReposition);
+      this.#anchorObserver.observe(anchor);
+    }
+
+    if ("ResizeObserver" in window) {
+      this.#contentObserver = new ResizeObserver(this.#boundReposition);
+      this.#contentObserver.observe(this);
+    }
+
+    this.#mutationObserver = new MutationObserver(this.#boundReposition);
+    this.#mutationObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+
+    window.addEventListener("resize", this.#boundReposition);
+    window.addEventListener("scroll", this.#boundScroll, true);
+  }
+
+  #teardownObservers() {
+    if (this.#anchorObserver) {
+      this.#anchorObserver.disconnect();
+      this.#anchorObserver = null;
+    }
+    if (this.#contentObserver) {
+      this.#contentObserver.disconnect();
+      this.#contentObserver = null;
+    }
+    if (this.#mutationObserver) {
+      this.#mutationObserver.disconnect();
+      this.#mutationObserver = null;
+    }
+    window.removeEventListener("resize", this.#boundReposition);
+    window.removeEventListener("scroll", this.#boundScroll, true);
+  }
+
+  #handleOutsidePointerDown(event) {
+    if (!this.open || !super.open) return;
+    const target = event.target;
+    if (!(target instanceof Node)) return;
+    if (this.contains(target)) return;
+
+    // Fallback for browsers that do not honor dialog closedby consistently.
+    this.open = false;
+  }
+
+  #resolveAnchor() {
+    const selector = this.getAttribute("anchor");
+    if (!selector) return null;
+
+    // Local-first: nearest parent subtree.
+    const localScope = this.parentElement;
+    if (localScope?.querySelector) {
+      const localMatch = localScope.querySelector(selector);
+      if (localMatch && !this.contains(localMatch)) return localMatch;
+    }
+
+    // Fallback: global document query.
+    return document.querySelector(selector);
+  }
+
+  #parsePosition() {
+    const raw = (this.getAttribute("position") || "top center")
+      .trim()
+      .toLowerCase();
+    const tokens = raw.split(/\s+/).filter(Boolean);
+    const verticalValues = new Set(["top", "center", "bottom"]);
+    const horizontalValues = new Set(["left", "center", "right"]);
+
+    let vertical = "top";
+    let horizontal = "center";
+    let shorthand = null;
+
+    // Treat position as "vertical horizontal" to avoid center ambiguity.
+    if (tokens.length >= 2) {
+      if (verticalValues.has(tokens[0])) {
+        vertical = tokens[0];
+      }
+      if (horizontalValues.has(tokens[1])) {
+        horizontal = tokens[1];
+      }
+      return { vertical, horizontal, shorthand };
+    }
+
+    // Single-token fallback: apply only if non-ambiguous.
+    if (tokens.length === 1) {
+      const token = tokens[0];
+      if (token === "top" || token === "bottom") {
+        vertical = token;
+        shorthand = token;
+      } else if (token === "left" || token === "right") {
+        horizontal = token;
+        shorthand = token;
+      } else if (token === "center") {
+        vertical = "center";
+        horizontal = "center";
+      }
+    }
+
+    return { vertical, horizontal, shorthand };
+  }
+
+  #normalizeOffsetToken(token, fallback = "0px") {
+    if (!token) return fallback;
+    const trimmed = token.trim();
+    if (!trimmed) return fallback;
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+      return `${trimmed}px`;
+    }
+    return trimmed;
+  }
+
+  #measureLengthPx(value, axis = "x") {
+    if (!value) return 0;
+    const normalized = this.#normalizeOffsetToken(value, "0px");
+    if (normalized.endsWith("px")) {
+      const px = parseFloat(normalized);
+      return Number.isFinite(px) ? px : 0;
+    }
+
+    const probe = document.createElement("div");
+    probe.style.position = "fixed";
+    probe.style.visibility = "hidden";
+    probe.style.pointerEvents = "none";
+    probe.style.left = "0";
+    probe.style.top = "0";
+    probe.style.margin = "0";
+    probe.style.padding = "0";
+    probe.style.border = "0";
+    if (axis === "x") {
+      probe.style.width = normalized;
+      probe.style.height = "0";
+    } else {
+      probe.style.height = normalized;
+      probe.style.width = "0";
+    }
+    document.body.appendChild(probe);
+    const rect = probe.getBoundingClientRect();
+    probe.remove();
+    return axis === "x" ? rect.width : rect.height;
+  }
+
+  #parseOffset() {
+    const raw = (this.getAttribute("offset") || "0 0").trim();
+    const tokens = raw.split(/\s+/).filter(Boolean);
+
+    const xToken = this.#normalizeOffsetToken(tokens[0], "0px");
+    const yToken = this.#normalizeOffsetToken(tokens[1], "0px");
+
+    return {
+      xToken,
+      yToken,
+      xPx: this.#measureLengthPx(xToken, "x"),
+      yPx: this.#measureLengthPx(yToken, "y"),
+    };
+  }
+
+  #getOrder(preferred, axis) {
+    const verticalMap = {
+      top: ["top", "bottom", "center"],
+      center: ["center", "top", "bottom"],
+      bottom: ["bottom", "top", "center"],
+    };
+    const horizontalMap = {
+      left: ["left", "right", "center"],
+      center: ["center", "left", "right"],
+      right: ["right", "left", "center"],
+    };
+
+    return axis === "vertical"
+      ? verticalMap[preferred] || verticalMap.top
+      : horizontalMap[preferred] || horizontalMap.center;
+  }
+
+  #computeCoords(anchorRect, popupRect, vertical, horizontal, offset, shorthand) {
+    let top;
+    let left;
+
+    // Shorthand support:
+    // position="right" => top edges aligned, popup sits to the right of anchor.
+    // position="left"  => top edges aligned, popup sits to the left of anchor.
+    if (shorthand === "right") {
+      return {
+        top: anchorRect.top,
+        left: anchorRect.right + offset.xPx,
+      };
+    }
+    if (shorthand === "left") {
+      return {
+        top: anchorRect.top,
+        left: anchorRect.left - popupRect.width - offset.xPx,
+      };
+    }
+    if (shorthand === "top") {
+      return {
+        top: anchorRect.top - popupRect.height - offset.yPx,
+        left: anchorRect.left,
+      };
+    }
+    if (shorthand === "bottom") {
+      return {
+        top: anchorRect.bottom + offset.yPx,
+        left: anchorRect.left,
+      };
+    }
+
+    if (vertical === "top") {
+      top = anchorRect.top - popupRect.height - offset.yPx;
+    } else if (vertical === "bottom") {
+      top = anchorRect.bottom + offset.yPx;
+    } else {
+      top = anchorRect.top + (anchorRect.height - popupRect.height) / 2;
+    }
+
+    if (horizontal === "left") {
+      left = anchorRect.left - popupRect.width - offset.xPx;
+    } else if (horizontal === "right") {
+      left = anchorRect.right + offset.xPx;
+    } else {
+      left = anchorRect.left + (anchorRect.width - popupRect.width) / 2;
+    }
+
+    return { top, left };
+  }
+
+  #oppositeSide(side) {
+    const map = {
+      top: "bottom",
+      bottom: "top",
+      left: "right",
+      right: "left",
+    };
+    return map[side] || "bottom";
+  }
+
+  #getPlacementSide(vertical, horizontal, shorthand) {
+    if (shorthand === "top") return "top";
+    if (shorthand === "bottom") return "bottom";
+    if (shorthand === "left") return "left";
+    if (shorthand === "right") return "right";
+
+    if (vertical !== "center") return vertical;
+    if (horizontal !== "center") return horizontal;
+    return "top";
+  }
+
+  #updatePopoverBeak(anchorRect, popupRect, left, top, placementSide) {
+    if (this.getAttribute("variant") !== "popover" || !anchorRect) {
+      this.style.removeProperty("--beak-offset");
+      this.removeAttribute("data-beak-side");
+      return;
+    }
+
+    const beakSide = this.#oppositeSide(placementSide);
+    this.setAttribute("data-beak-side", beakSide);
+
+    const anchorCenterX = anchorRect.left + anchorRect.width / 2;
+    const anchorCenterY = anchorRect.top + anchorRect.height / 2;
+
+    let beakOffset;
+    if (beakSide === "top" || beakSide === "bottom") {
+      beakOffset = anchorCenterX - left;
+      const min = 8;
+      const max = Math.max(min, popupRect.width - 8);
+      beakOffset = Math.min(max, Math.max(min, beakOffset));
+    } else {
+      beakOffset = anchorCenterY - top;
+      const min = 8;
+      const max = Math.max(min, popupRect.height - 8);
+      beakOffset = Math.min(max, Math.max(min, beakOffset));
+    }
+
+    this.style.setProperty("--beak-offset", `${beakOffset}px`);
+  }
+
+  #overflowScore(coords, popupRect) {
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const right = coords.left + popupRect.width;
+    const bottom = coords.top + popupRect.height;
+    const pad = this.#viewportPadding;
+
+    const overflowLeft = Math.max(0, pad - coords.left);
+    const overflowTop = Math.max(0, pad - coords.top);
+    const overflowRight = Math.max(0, right - (vw - pad));
+    const overflowBottom = Math.max(0, bottom - (vh - pad));
+
+    return overflowLeft + overflowTop + overflowRight + overflowBottom;
+  }
+
+  #fits(coords, popupRect) {
+    return this.#overflowScore(coords, popupRect) === 0;
+  }
+
+  #clamp(coords, popupRect) {
+    const pad = this.#viewportPadding;
+    const minLeft = pad;
+    const minTop = pad;
+    const maxLeft = Math.max(pad, window.innerWidth - popupRect.width - pad);
+    const maxTop = Math.max(pad, window.innerHeight - popupRect.height - pad);
+
+    return {
+      left: Math.min(maxLeft, Math.max(minLeft, coords.left)),
+      top: Math.min(maxTop, Math.max(minTop, coords.top)),
+    };
+  }
+
+  #positionPopup() {
+    if (!this.open || !super.open) return;
+
+    const popupRect = this.getBoundingClientRect();
+    const offset = this.#parseOffset();
+    const { vertical, horizontal, shorthand } = this.#parsePosition();
+    const verticalOrder = this.#getOrder(vertical, "vertical");
+    const horizontalOrder = this.#getOrder(horizontal, "horizontal");
+    const anchor = this.#resolveAnchor();
+
+    if (!anchor) {
+      this.#updatePopoverBeak(null, popupRect, 0, 0, "top");
+      const centered = {
+        left: (window.innerWidth - popupRect.width) / 2,
+        top: (window.innerHeight - popupRect.height) / 2,
+      };
+      const clamped = this.#clamp(centered, popupRect);
+      this.style.left = `${clamped.left}px`;
+      this.style.top = `${clamped.top}px`;
+      return;
+    }
+
+    const anchorRect = anchor.getBoundingClientRect();
+    let best = null;
+    let bestSide = "top";
+    let bestScore = Number.POSITIVE_INFINITY;
+
+    for (const v of verticalOrder) {
+      for (const h of horizontalOrder) {
+        const coords = this.#computeCoords(
+          anchorRect,
+          popupRect,
+          v,
+          h,
+          offset,
+          shorthand
+        );
+        const placementSide = this.#getPlacementSide(v, h, shorthand);
+        if (this.#fits(coords, popupRect)) {
+          this.style.left = `${coords.left}px`;
+          this.style.top = `${coords.top}px`;
+          this.#updatePopoverBeak(
+            anchorRect,
+            popupRect,
+            coords.left,
+            coords.top,
+            placementSide
+          );
+          return;
+        }
+        const score = this.#overflowScore(coords, popupRect);
+        if (score < bestScore) {
+          bestScore = score;
+          best = coords;
+          bestSide = placementSide;
+        }
+      }
+    }
+
+    const clamped = this.#clamp(best || { left: 0, top: 0 }, popupRect);
+    this.style.left = `${clamped.left}px`;
+    this.style.top = `${clamped.top}px`;
+    this.#updatePopoverBeak(
+      anchorRect,
+      popupRect,
+      clamped.left,
+      clamped.top,
+      bestSide
+    );
+  }
+
+  #queueReposition() {
+    if (!this.open) return;
+    if (this.#rafId !== null) return;
+
+    this.#rafId = requestAnimationFrame(() => {
+      this.#rafId = null;
+      this.#positionPopup();
+    });
+  }
+}
+customElements.define("fig-popup", FigPopup, { extends: "dialog" });
+
 /**
  * A popover element using the native Popover API.
  * @attr {string} trigger-action - The trigger action: "click" (default) or "hover"

package/index.html

@@ -184,6 +184,7 @@
             <a href="#input-text">Input Text</a>
             <a href="#layer">Layer</a>
             <a href="#popover">Popover</a>
+            <a href="#popup">Popup</a>
             <a href="#radio">Radio</a>
             <a href="#segmented-control">Segmented Control</a>
             <a href="#shimmer">Shimmer</a>
@@ -2635,6 +2636,296 @@
         </section>
         <hr>
 
+        <!-- Popup -->
+        <section id="popup">
+            <h2>Popup</h2>
+            <p class="description">A floating foundation component built as <code>&lt;dialog is="fig-popup"&gt;</code>
+                with anchor-based positioning and viewport-aware fallback.</p>
+
+            <h3>Default Position (top center)</h3>
+            <hstack>
+                <fig-button id="popup-open-default">Open Popup</fig-button>
+                <fig-button id="popup-close-default"
+                            variant="secondary">Close Popup</fig-button>
+            </hstack>
+            <dialog id="popup-default"
+                    is="fig-popup"
+                    anchor="#popup-open-default">
+                <vstack style="min-width: 12rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Default Popup</strong>
+                    <fig-field direction="horizontal">
+                        <label>Opacity</label>
+                        <fig-slider value="50"
+                                    text="true"
+                                    units="%"></fig-slider>
+                    </fig-field>
+                </vstack>
+            </dialog>
+
+            <h3>Preferred Position (bottom right)</h3>
+            <hstack>
+                <fig-button id="popup-open-preferred">Open Bottom Right</fig-button>
+                <fig-button id="popup-close-preferred"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-preferred"
+                    is="fig-popup"
+                    anchor="#popup-open-preferred"
+                    position="bottom right">
+                <vstack style="min-width: 10rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Preferred Placement</strong>
+                    <fig-checkbox label="Apply to existing strokes"
+                                  checked></fig-checkbox>
+                    <fig-checkbox label="Apply to shapes with fills"></fig-checkbox>
+                </vstack>
+            </dialog>
+
+            <h3>Popover Variant (with Arrow)</h3>
+            <p class="description">Use <code>variant="popover"</code> to show the beak and automatically point it at the
+                anchor.</p>
+            <hstack>
+                <fig-button id="popup-open-popover">Open Popover Variant</fig-button>
+                <fig-button id="popup-close-popover"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-popover"
+                    is="fig-popup"
+                    anchor="#popup-open-popover"
+                    position="top center"
+                    variant="popover">
+                <vstack style="min-width: 12rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Popover Beak</strong>
+                    <fig-field direction="horizontal">
+                        <label>Apply</label>
+                        <fig-switch checked></fig-switch>
+                    </fig-field>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-popover"&gt;Open Popover Variant&lt;/fig-button&gt;
+&lt;dialog is="fig-popup"
+        anchor="#popup-open-popover"
+        position="top center"
+        variant="popover"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h3>Property API</h3>
+            <p class="description">Uses the popup <code>open</code> property setter/getter (attribute wrapper).</p>
+            <hstack>
+                <fig-button id="popup-open-prop">popup.open = true</fig-button>
+                <fig-button id="popup-close-prop"
+                            variant="secondary">popup.open = false</fig-button>
+            </hstack>
+            <dialog id="popup-prop"
+                    is="fig-popup"
+                    anchor="#popup-open-prop"
+                    position="top left">
+                <vstack style="min-width: 11rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Property Controlled</strong>
+                    <fig-input-text placeholder="Type here"></fig-input-text>
+                </vstack>
+            </dialog>
+
+            <h3>Position Examples</h3>
+            <p class="description">Each example uses a different popup position with a dedicated open button and code
+                snippet.</p>
+
+            <h4>Top Left</h4>
+            <hstack>
+                <fig-button id="popup-open-top-left">Open Top Left</fig-button>
+                <fig-button id="popup-close-top-left"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-top-left"
+                    is="fig-popup"
+                    anchor="#popup-open-top-left"
+                    position="top left">
+                <vstack style="min-width: 10rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Top Left</strong>
+                    <fig-input-number value="12"
+                                      units="px"></fig-input-number>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-top-left"&gt;Open Top Left&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-top-left" position="top left"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h4>Top Center</h4>
+            <hstack>
+                <fig-button id="popup-open-top-center">Open Top Center</fig-button>
+                <fig-button id="popup-close-top-center"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-top-center"
+                    is="fig-popup"
+                    anchor="#popup-open-top-center"
+                    position="top center">
+                <vstack style="min-width: 10rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Top Center</strong>
+                    <fig-switch label="Enabled"></fig-switch>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-top-center"&gt;Open Top Center&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-top-center" position="top center"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h4>Top Right</h4>
+            <hstack>
+                <fig-button id="popup-open-top-right">Open Top Right</fig-button>
+                <fig-button id="popup-close-top-right"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-top-right"
+                    is="fig-popup"
+                    anchor="#popup-open-top-right"
+                    position="top right">
+                <vstack style="min-width: 10rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Top Right</strong>
+                    <fig-input-number value="24"
+                                      units="px"></fig-input-number>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-top-right"&gt;Open Top Right&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-top-right" position="top right"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h4>Bottom Left</h4>
+            <hstack>
+                <fig-button id="popup-open-bottom-left">Open Bottom Left</fig-button>
+                <fig-button id="popup-close-bottom-left"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-bottom-left"
+                    is="fig-popup"
+                    anchor="#popup-open-bottom-left"
+                    position="bottom left">
+                <vstack style="min-width: 10rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Bottom Left</strong>
+                    <fig-checkbox label="Snap to pixel grid"></fig-checkbox>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-bottom-left"&gt;Open Bottom Left&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-bottom-left" position="bottom left"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h4>Bottom Right</h4>
+            <hstack>
+                <fig-button id="popup-open-bottom-right">Open Bottom Right</fig-button>
+                <fig-button id="popup-close-bottom-right"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-bottom-right"
+                    is="fig-popup"
+                    anchor="#popup-open-bottom-right"
+                    position="bottom right">
+                <vstack style="min-width: 10rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Bottom Right</strong>
+                    <fig-dropdown>
+                        <option>Normal</option>
+                        <option>Multiply</option>
+                        <option>Screen</option>
+                    </fig-dropdown>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-bottom-right"&gt;Open Bottom Right&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-bottom-right" position="bottom right"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h4>Center Right (Vertical Centering)</h4>
+            <hstack>
+                <fig-button id="popup-open-center-right">Open Center Right</fig-button>
+                <fig-button id="popup-close-center-right"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-center-right"
+                    is="fig-popup"
+                    anchor="#popup-open-center-right"
+                    position="center right"
+                    offset="12 8">
+                <vstack style="min-width: 11rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Center Right</strong>
+                    <fig-input-text placeholder="Vertically centered"></fig-input-text>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-center-right"&gt;Open Center Right&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-center-right" position="center right" offset="12 8"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h4>Center Left (Vertical Centering)</h4>
+            <hstack>
+                <fig-button id="popup-open-center-left">Open Center Left</fig-button>
+                <fig-button id="popup-close-center-left"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-center-left"
+                    is="fig-popup"
+                    anchor="#popup-open-center-left"
+                    position="center left"
+                    offset="12 8">
+                <vstack style="min-width: 11rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Center Left</strong>
+                    <fig-input-text placeholder="Vertically centered"></fig-input-text>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-center-left"&gt;Open Center Left&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-center-left" position="center left" offset="12 8"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h3>Single-Value Position Shorthand</h3>
+            <p class="description">Single values are supported for directional shorthand (for example:
+                <code>top</code>, <code>right</code>).</p>
+
+            <h4>Top (left edges aligned)</h4>
+            <hstack>
+                <fig-button id="popup-open-top-single">Open Top (single)</fig-button>
+                <fig-button id="popup-close-top-single"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-top-single"
+                    is="fig-popup"
+                    anchor="#popup-open-top-single"
+                    position="top"
+                    offset="12 8">
+                <vstack style="min-width: 11rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Top Shorthand</strong>
+                    <fig-input-text placeholder="position='top'"></fig-input-text>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-top-single"&gt;Open Top (single)&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-top-single" position="top" offset="12 8"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+
+            <h4>Right (top edges aligned)</h4>
+            <hstack>
+                <fig-button id="popup-open-right-single">Open Right (single)</fig-button>
+                <fig-button id="popup-close-right-single"
+                            variant="secondary">Close</fig-button>
+            </hstack>
+            <dialog id="popup-right-single"
+                    is="fig-popup"
+                    anchor="#popup-open-right-single"
+                    position="right"
+                    offset="12 8">
+                <vstack style="min-width: 11rem;">
+                    <strong style="padding: 0 var(--spacer-1);">Right Shorthand</strong>
+                    <fig-input-text placeholder="position='right'"></fig-input-text>
+                </vstack>
+            </dialog>
+            <pre><code>&lt;fig-button id="popup-open-right-single"&gt;Open Right (single)&lt;/fig-button&gt;
+&lt;dialog is="fig-popup" anchor="#popup-open-right-single" position="right" offset="12 8"&gt;
+  ...
+&lt;/dialog&gt;</code></pre>
+        </section>
+        <hr>
+
         <!-- Radio -->
         <section id="radio">
             <h2>Radio</h2>
@@ -3871,6 +4162,55 @@ button.addEventListener('click', () => {
             setTheme(true);
         });
 
+        // FigPopup demos
+        const popupDefault = document.getElementById('popup-default');
+        const popupPreferred = document.getElementById('popup-preferred');
+        const popupProp = document.getElementById('popup-prop');
+
+        document.getElementById('popup-open-default')?.addEventListener('click', () => {
+            popupDefault?.setAttribute('open', 'true');
+        });
+        document.getElementById('popup-close-default')?.addEventListener('click', () => {
+            popupDefault?.removeAttribute('open');
+        });
+
+        document.getElementById('popup-open-preferred')?.addEventListener('click', () => {
+            popupPreferred?.setAttribute('open', 'true');
+        });
+        document.getElementById('popup-close-preferred')?.addEventListener('click', () => {
+            popupPreferred?.removeAttribute('open');
+        });
+
+        document.getElementById('popup-open-prop')?.addEventListener('click', () => {
+            if (popupProp) popupProp.open = true;
+        });
+        document.getElementById('popup-close-prop')?.addEventListener('click', () => {
+            if (popupProp) popupProp.open = false;
+        });
+
+        const popupExamples = [
+            ['popup-open-popover', 'popup-close-popover', 'popup-popover'],
+            ['popup-open-top-left', 'popup-close-top-left', 'popup-top-left'],
+            ['popup-open-top-center', 'popup-close-top-center', 'popup-top-center'],
+            ['popup-open-top-right', 'popup-close-top-right', 'popup-top-right'],
+            ['popup-open-bottom-left', 'popup-close-bottom-left', 'popup-bottom-left'],
+            ['popup-open-bottom-right', 'popup-close-bottom-right', 'popup-bottom-right'],
+            ['popup-open-center-right', 'popup-close-center-right', 'popup-center-right'],
+            ['popup-open-center-left', 'popup-close-center-left', 'popup-center-left'],
+            ['popup-open-top-single', 'popup-close-top-single', 'popup-top-single'],
+            ['popup-open-right-single', 'popup-close-right-single', 'popup-right-single'],
+        ];
+
+        popupExamples.forEach(([openId, closeId, popupId]) => {
+            const popup = document.getElementById(popupId);
+            document.getElementById(openId)?.addEventListener('click', () => {
+                popup?.setAttribute('open', 'true');
+            });
+            document.getElementById(closeId)?.addEventListener('click', () => {
+                popup?.removeAttribute('open');
+            });
+        });
+
         // Listen for system preference changes
         window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
             if (!localStorage.getItem('theme')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rogieking/figui3",
-  "version": "2.17.1",
+  "version": "2.17.2",
   "description": "A lightweight web components library for building Figma plugin and widget UIs with native look and feel",
   "author": "Rogie King",
   "license": "MIT",