@urbicon-ui/blocks 6.3.11 → 6.3.12

package/dist/primitives/Combobox/Combobox.svelte

@@ -7,7 +7,7 @@
   import CloseIconDefault from '../../icons/CloseIcon.svelte';
   import ChevronDownIconDefault from '../../icons/ChevronDownIcon.svelte';
   import CheckIconDefault from '../../icons/CheckIcon.svelte';
-  import { useFormField, getTierContext, useFloatingPanel } from '../../utils';
+  import { useFormField, getTierContext, useFloatingPanel, floatingPanelStyle } from '../../utils';
   import type { ComboboxProps, ComboboxOption } from './index';
 
   const bt = useBlocksI18n();
@@ -263,7 +263,7 @@
     }
   });
 
-  useFloatingPanel({
+  const panel = useFloatingPanel({
     reference: () => inputEl,
     floating: () => listboxEl,
     open: () => open,
@@ -369,21 +369,23 @@
     {/if}
 
     <!--
-      Listbox stays mounted (with `popover="manual"`) so `bind:this`
-      and `aria-controls` are stable across open/close cycles. Native
-      `[popover]:not(:popover-open)` UA-rule hides it via display:none
-      until `showPopover()` runs in the effect above.
+      Listbox stays mounted so `bind:this` and `aria-controls` are stable across
+      open/close cycles. In top-layer mode the `popover="manual"` UA-rule
+      `[popover]:not(:popover-open)` hides it until `showPopover()` runs; inside a
+      modal dialog (`panel.topLayer === false`) the popover attribute is dropped
+      and `floatingPanelStyle` drives visibility via `display` instead, so the
+      listbox renders in the dialog's own top-layer subtree (Codeberg #23).
     -->
     <div
       bind:this={listboxEl}
       id={listboxId}
       role="listbox"
-      popover="manual"
+      popover={panel.topLayer ? 'manual' : null}
       tabindex={-1}
       class={unstyled
         ? (slotClasses?.listbox ?? '')
         : styles.listbox({ class: slotClasses?.listbox })}
-      style="position: fixed; margin: 0; inset: auto; overflow-y: auto;"
+      style={floatingPanelStyle(panel, open, 'overflow-y: auto; ')}
     >
       {#if open}
         {#if filtered.length === 0}

package/dist/primitives/Popover/Popover.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { untrack } from 'svelte';
   import { getBlocksConfig, resolveSlotClasses } from '../../provider';
-  import { useFloatingPanel } from '../../utils';
+  import { useFloatingPanel, floatingPanelStyle } from '../../utils';
   import { popoverVariants } from './popover.variants';
   import type { PopoverProps } from './index';
 
@@ -52,6 +52,30 @@
 
   const effectiveTriggerElement = $derived(triggerElement || internalTriggerElement);
 
+  // ── Floating UI positioning + native show/hide ─────────────
+  //
+  // Delegated to the shared `useFloatingPanel` helper — the same positioning
+  // codepath Select/Combobox use — so the iOS/visualViewport handling and the
+  // keyboard-aware height cap (`--blocks-overlay-available-height`, consumed by
+  // popoverVariants/menuVariants) land here too instead of being a second,
+  // drifting copy. The helper drives `showPopover()`/`hidePopover()` purely from
+  // `open` and reports the effective render mode (`panel.topLayer` /
+  // `panel.strategy`), read below by `popoverMode` (so a panel that leaves the
+  // top layer inside a modal dialog switches to manual dismiss) and by the panel
+  // markup. The `popover="auto"`/`"manual"` dismiss wiring stays independent of
+  // show/hide.
+  const panel = useFloatingPanel({
+    reference: () => effectiveTriggerElement,
+    floating: () => popoverElement,
+    open: () => open,
+    portal: () => usePortal,
+    placement: () => placement,
+    offsetDistance: () => offsetDistance,
+    shiftPadding: () => shiftPadding,
+    syncWidth: () => syncWidth,
+    syncMinWidth: () => syncMinWidth
+  });
+
   // Forward aria-expanded / aria-haspopup to the first interactive descendant
   // of the trigger wrapper. Without this, the wrapper div itself would need
   // those attributes — but axe flags `aria-expanded` on an element with no
@@ -109,8 +133,12 @@
   // timing. Consumers with an external CLICK trigger (Menu, DatePicker)
   // get a clean toggle; hover-driven external triggers (Calendar event
   // popovers) are unaffected since they never relied on light-dismiss.
+  // A panel that is NOT top-layer-promoted (nested in a modal dialog → Codeberg
+  // #23) emits no native `toggle` events, so `auto` mode's browser-driven
+  // Escape / light-dismiss never fires. Force `manual` there so the explicit
+  // Escape / outside-pointerdown listeners below own the dismiss instead.
   const popoverMode = $derived<'auto' | 'manual'>(
-    autoTrigger && closeOnEscape && closeOnClickOutside ? 'auto' : 'manual'
+    panel.topLayer && autoTrigger && closeOnEscape && closeOnClickOutside ? 'auto' : 'manual'
   );
 
   // ── Native popover state sync (popover="auto" mode only) ──
@@ -236,27 +264,6 @@
     }
   });
 
-  // ── Floating UI positioning + native show/hide ─────────────
-  //
-  // Delegated to the shared `useFloatingPanel` helper — the same positioning
-  // codepath Select/Combobox use — so the iOS/visualViewport handling and the
-  // keyboard-aware height cap (`--blocks-overlay-available-height`, consumed by
-  // popoverVariants/menuVariants) land here too instead of being a second,
-  // drifting copy. The helper drives `showPopover()`/`hidePopover()` purely
-  // from `open`; the `popover="auto"`/`"manual"` dismiss wiring above is
-  // independent of it.
-  useFloatingPanel({
-    reference: () => effectiveTriggerElement,
-    floating: () => popoverElement,
-    open: () => open,
-    portal: () => usePortal,
-    placement: () => placement,
-    offsetDistance: () => offsetDistance,
-    shiftPadding: () => shiftPadding,
-    syncWidth: () => syncWidth,
-    syncMinWidth: () => syncMinWidth
-  });
-
   // ── Trigger handlers ───────────────────────────────────────
 
   function handleTriggerPointerDown() {
@@ -301,32 +308,30 @@
   `{...restProps}` so a consumer-supplied `popover="manual"` or override
   of `role`/`id` cannot silently break the show/hide flow or ARIA pairing.
 
-  The explicit `style` prop is interpolated FIRST so that the load-bearing
-  positioning tokens (`position: fixed`, `margin: 0`, `inset: auto`) come
-  last and win the CSS cascade. A consumer passing `style="background:
+  The explicit `style` prop is interpolated FIRST (via `floatingPanelStyle`) so
+  that the load-bearing positioning tokens (`position`, `margin: 0`, `inset:
+  auto`) come last and win the CSS cascade. A consumer passing `style="background:
   red"` still works; a consumer passing `style="position: absolute"`
   cannot accidentally break Floating UI's coordinate system.
 -->
 <!--
-  `usePortal=false` mode renders the panel in the regular DOM flow with
-  `position: absolute`, anchored to the trigger's offset parent. The
-  `popover` attribute is suppressed so the browser does not promote the
-  element to the top layer; Floating UI still drives `left` / `top` via
-  `useFloatingPanel` (which skips show/hide when not portalled), and the
-  `open`/`!open` toggle just shows / hides the element. Used by Menu /
-  Select consumers that live inside another popover (avoids nested-top-layer
-  focus & z-index quirks).
+  Non-top-layer render (`panel.topLayer === false`): the `popover` attribute is
+  suppressed so the browser does not promote the element to the top layer;
+  `floatingPanelStyle` drives `position` + `display` while Floating UI drives
+  `left` / `top`. Two triggers:
+    • `usePortal=false` (e.g. Menu / Select inside another popover) →
+      `position: absolute`, avoiding nested-top-layer focus & z-index quirks.
+    • nested in an open modal `<dialog>` → `position: fixed`, so the panel paints
+      in the dialog's own top-layer subtree instead of a second popover WebKit
+      drops over a modal dialog (Codeberg #23).
 -->
+
 <div
   bind:this={popoverElement}
   class={popoverClasses}
   {...restProps}
-  popover={usePortal ? popoverMode : null}
-  style={usePortal
-    ? `${style}; position: fixed; margin: 0; inset: auto;`
-    : open
-      ? `${style}; position: absolute; margin: 0; inset: auto;`
-      : `${style}; position: absolute; margin: 0; inset: auto; display: none;`}
+  popover={panel.topLayer ? popoverMode : null}
+  style={floatingPanelStyle(panel, open, style ? `${style}; ` : '')}
   {role}
   aria-modal={ariaModal || undefined}
   {id}

package/dist/primitives/Popover/Popover.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { PopoverProps } from './index.js';
-declare const Popover: import("svelte").Component<PopoverProps, {}, "triggerElement" | "open">;
+declare const Popover: import("svelte").Component<PopoverProps, {}, "open" | "triggerElement">;
 type Popover = ReturnType<typeof Popover>;
 export default Popover;

package/dist/primitives/Select/Select.svelte

@@ -1,6 +1,6 @@
 <script lang="ts" generics="T extends string | number | boolean = string">
   import { useBlocksI18n, mintRegistry } from '../..';
-  import { useFormField, getTierContext, useFloatingPanel } from '../../utils';
+  import { useFormField, getTierContext, useFloatingPanel, floatingPanelStyle } from '../../utils';
   import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { resolveIcon } from '../../icons';
   import ChevronDownIconDefault from '../../icons/ChevronDownIcon.svelte';
@@ -228,7 +228,7 @@
     activeIndex = next;
   });
 
-  useFloatingPanel({
+  const panel = useFloatingPanel({
     reference: () => triggerRef,
     floating: () => listboxRef,
     open: () => open,
@@ -505,10 +505,12 @@
     {/if}
 
     <!--
-      Listbox stays mounted (with `popover="manual"`) so `bind:this`
-      and `aria-controls` are stable across open/close cycles. Native
-      `[popover]:not(:popover-open)` UA-rule hides it via display:none
-      until `showPopover()` runs in the effect above.
+      Listbox stays mounted so `bind:this` and `aria-controls` are stable across
+      open/close cycles. Top-layer mode uses `popover="manual"` + the UA
+      `[popover]:not(:popover-open)` display rule until `showPopover()` runs; the
+      in-place modes (nested in a modal dialog → Codeberg #23, or the explicit
+      `usePortal=false`) drop the popover attribute and let `floatingPanelStyle`
+      drive visibility via `display`.
 
       `tabindex={-1}` keeps the listbox programmatically focusable without
       adding it to the tab order — the ARIA Listbox / `aria-activedescendant`
@@ -522,17 +524,13 @@
       bind:this={listboxRef}
       id={listboxId}
       role="listbox"
-      popover={usePortal ? 'manual' : null}
+      popover={panel.topLayer ? 'manual' : null}
       aria-multiselectable={multiple || undefined}
       tabindex={-1}
       class={unstyled
         ? (slotClasses?.listbox ?? '')
         : styles.listbox({ class: slotClasses?.listbox })}
-      style={usePortal
-        ? 'position: fixed; margin: 0; inset: auto; overflow-y: auto;'
-        : open
-          ? 'position: absolute; overflow-y: auto;'
-          : 'display: none; position: absolute; overflow-y: auto;'}
+      style={floatingPanelStyle(panel, open, 'overflow-y: auto; ')}
       aria-labelledby={labelId}
     >
       {#if open}

package/dist/primitives/Tooltip/Tooltip.svelte

@@ -11,6 +11,7 @@
     offset,
     arrow as floatingArrow
   } from '../../utils/floating';
+  import { isAnchoredInModalDialog } from '../../utils/overlay';
 
   let {
     children,
@@ -48,6 +49,14 @@
     resolveSlotClasses(blocksConfig, 'Tooltip', preset, variantProps, slotClassesProp)
   );
 
+  // Inside an open modal <dialog>, a popover shown via showPopover() forms a
+  // second top-layer element WebKit won't render above the dialog (Codeberg
+  // #23). Evaluated while `visible` so the check runs once the dialog is
+  // already modal; the tooltip then renders in place (position:fixed + the
+  // opacity `visible` variant + pointer-events-none) within the dialog's own
+  // top-layer subtree, no showPopover() needed.
+  const topLayer = $derived(visible ? !isAnchoredInModalDialog(triggerElement) : true);
+
   let showTimeout: number;
   let hideTimeout: number;
   let cleanup: (() => void) | undefined = undefined;
@@ -174,7 +183,9 @@
       return;
     }
 
-    if (!tooltipElement.matches(':popover-open')) {
+    // Skip top-layer promotion inside a modal dialog (see `topLayer`): the
+    // tooltip stays a dialog descendant and shows via the opacity variant.
+    if (topLayer && !tooltipElement.matches(':popover-open')) {
       try {
         tooltipElement.showPopover();
       } catch (err) {
@@ -216,8 +227,10 @@
   Tooltip element stays mounted so `bind:this={tooltipElement}` is stable
   across hover cycles and Floating UI's `arrow` middleware always has a
   target (otherwise the first showPopover would compute positions before
-  the arrow node existed). The `popover="manual"` attribute hides it
-  via the UA stylesheet until `showPopover()` is called.
+  the arrow node existed). In top-layer mode the `popover="manual"` attribute
+  hides it via the UA stylesheet until `showPopover()` is called; inside a
+  modal dialog (`topLayer === false`) the attribute is dropped and the
+  `visible` opacity variant drives visibility instead (Codeberg #23).
 
   Load-bearing attributes (`popover`, `style`, `role`, `id`) intentionally
   follow `{...restProps}` so a consumer-supplied `popover="auto"`, custom
@@ -230,7 +243,7 @@
     ? [slotClasses?.base, className].filter(Boolean).join(' ')
     : styles.base({ class: [slotClasses?.base, className] })}
   {...restProps}
-  popover="manual"
+  popover={topLayer ? 'manual' : null}
   style="position: fixed; margin: 0; inset: auto; overflow: visible;"
   role="tooltip"
   id={tooltipId}

package/dist/utils/index.d.ts

@@ -11,6 +11,6 @@ export { type EasingFn, getOverlayMotion, OVERLAY_MOTION_DEFAULTS, type OverlayM
 export * from './persistent-state.svelte.js';
 export { getTierContext, type InteractiveTier, setTierContext, type TierContext } from './tier-context.js';
 export * from './types.js';
-export { type FloatingPanelOptions, useFloatingPanel } from './use-floating-panel.svelte.js';
+export { type FloatingPanelOptions, type FloatingPanelState, floatingPanelStyle, useFloatingPanel } from './use-floating-panel.svelte.js';
 export { computeFormFieldAria, type UseFormFieldInputs, type UseFormFieldReturn, useFormField } from './use-form-field.svelte.js';
 export { cx, type TVProps, tv, type VariantProps } from './variants.js';

package/dist/utils/index.js

@@ -11,6 +11,6 @@ export { getOverlayMotion, OVERLAY_MOTION_DEFAULTS } from './overlay-tokens.js';
 export * from './persistent-state.svelte.js';
 export { getTierContext, setTierContext } from './tier-context.js';
 export * from './types.js';
-export { useFloatingPanel } from './use-floating-panel.svelte.js';
+export { floatingPanelStyle, useFloatingPanel } from './use-floating-panel.svelte.js';
 export { computeFormFieldAria, useFormField } from './use-form-field.svelte.js';
 export { cx, tv } from './variants.js';

package/dist/utils/overlay.d.ts

@@ -6,3 +6,21 @@ export declare function unlockBodyScroll(): void;
 export declare function focusFirstElement(container: HTMLElement | undefined): void;
 export declare function showDialogModal(dialogEl: HTMLDialogElement | undefined, panelEl: HTMLElement | undefined): void;
 export declare function closeDialogModal(dialogEl: HTMLDialogElement | undefined, previouslyFocused: HTMLElement | null): void;
+/**
+ * True when `el` is a descendant of an OPEN *modal* `<dialog>` — one opened via
+ * `showModal()`, which matches `:modal` and occupies the browser top layer.
+ *
+ * A popover shown via `showPopover()` from inside such a dialog forms a *second*
+ * top-layer element, which WebKit/iOS fails to render above the dialog (Codeberg
+ * #23 — the documented "top layer: popover vs. dialog" conflict; Chromium
+ * tolerates it). Anchored overlays use this to skip top-layer promotion when
+ * nested in a modal dialog and render inside the dialog's own subtree instead.
+ *
+ * DOM-based on purpose: it transparently covers `Drawer` (also `showModal()`)
+ * and even consumer-authored `<dialog>` wrappers, and distinguishes modal from
+ * non-modal (`show()`) dialogs — neither of which a context/registry would catch.
+ *
+ * Null-safe so it can be called during SSR, before `bind:this` resolves, or
+ * while an anchor is mid-teardown.
+ */
+export declare function isAnchoredInModalDialog(el: HTMLElement | null | undefined): boolean;

package/dist/utils/overlay.js

@@ -81,3 +81,35 @@ export function closeDialogModal(dialogEl, previouslyFocused) {
     unlockBodyScroll();
     previouslyFocused?.focus();
 }
+/**
+ * True when `el` is a descendant of an OPEN *modal* `<dialog>` — one opened via
+ * `showModal()`, which matches `:modal` and occupies the browser top layer.
+ *
+ * A popover shown via `showPopover()` from inside such a dialog forms a *second*
+ * top-layer element, which WebKit/iOS fails to render above the dialog (Codeberg
+ * #23 — the documented "top layer: popover vs. dialog" conflict; Chromium
+ * tolerates it). Anchored overlays use this to skip top-layer promotion when
+ * nested in a modal dialog and render inside the dialog's own subtree instead.
+ *
+ * DOM-based on purpose: it transparently covers `Drawer` (also `showModal()`)
+ * and even consumer-authored `<dialog>` wrappers, and distinguishes modal from
+ * non-modal (`show()`) dialogs — neither of which a context/registry would catch.
+ *
+ * Null-safe so it can be called during SSR, before `bind:this` resolves, or
+ * while an anchor is mid-teardown.
+ */
+export function isAnchoredInModalDialog(el) {
+    if (!isBrowser || !el)
+        return false;
+    const dialog = el.closest('dialog');
+    if (!dialog)
+        return false;
+    try {
+        return dialog.matches(':modal');
+    }
+    catch {
+        // `:modal` predates the Popover API in every engine, so an engine that
+        // throws on the selector cannot exhibit the top-layer conflict anyway.
+        return false;
+    }
+}

package/dist/utils/use-floating-panel.svelte.d.ts

@@ -7,9 +7,17 @@ export interface FloatingPanelOptions {
     /** Whether the panel is currently open. */
     open: () => boolean;
     /**
-     * Render in the browser top layer via the native popover API (default).
-     * `false` keeps the panel in normal DOM flow (`position: absolute`) for
-     * nested-overlay scenarios — the caller drives visibility via `display`.
+     * Caller hint for top-layer promotion via the native popover API (default
+     * `true`). `false` forces the panel into normal DOM flow (`position:
+     * absolute`) for nested-overlay scenarios (e.g. a Menu/Select inside a
+     * Popover) — the caller drives visibility via `display`.
+     *
+     * Even when `true`, the panel is automatically kept OUT of the top layer
+     * while it sits inside an open modal `<dialog>` — it then renders
+     * `position: fixed` within the dialog's own subtree, because a second
+     * top-layer element over a modal dialog is invisible on iOS/WebKit
+     * (Codeberg #23). Read the effective state from the returned
+     * `topLayer`/`strategy`.
      */
     portal?: () => boolean;
     /** Preferred placement. @default 'bottom-start' */
@@ -23,6 +31,23 @@ export interface FloatingPanelOptions {
     /** Clamp the panel's *min*-width to the anchor width (it may still grow). @default false */
     syncMinWidth?: () => boolean;
 }
+/**
+ * Effective render mode of a floating panel, returned by {@link useFloatingPanel}
+ * so the calling component's markup stays in lockstep with the positioning
+ * effect — both read the same derived values, so the `popover` attribute and the
+ * `showPopover()` decision can never diverge.
+ */
+export interface FloatingPanelState {
+    /**
+     * `true` when the panel is promoted to the browser top layer (the markup sets
+     * the `popover` attribute and the effect calls `showPopover()`); `false` when
+     * it renders in place — inside a modal `<dialog>`, or the explicit
+     * `portal=false` inline mode.
+     */
+    readonly topLayer: boolean;
+    /** CSS positioning strategy the panel element must match (`position: <strategy>`). */
+    readonly strategy: 'fixed' | 'absolute';
+}
 /**
  * Manages native popover state + Floating UI positioning for anchored overlay
  * panels (Select, Combobox, Popover, and through it Menu). Handles show/hide,
@@ -35,10 +60,30 @@ export interface FloatingPanelOptions {
  * the caller's own dismiss handlers in control; this helper only drives
  * `showPopover()`/`hidePopover()` and never reads the dismiss mode.
  *
+ * Top-layer promotion is automatic but conditional: the helper skips it (and
+ * returns `topLayer: false`) when the anchor sits inside an open modal
+ * `<dialog>`, where a second top-layer element is invisible on iOS/WebKit
+ * (Codeberg #23) — the panel then renders `position: fixed` in place. Callers
+ * mirror the returned `topLayer`/`strategy` in their markup via
+ * {@link floatingPanelStyle}.
+ *
  * The Floating-UI `size` middleware feeds the room actually left between the
  * anchor and the (visual) viewport edge into `--blocks-overlay-available-height`.
  * Variants cap height via `max-h-[min(<design-cap>,var(--…,100dvh))]`, so the
  * static design cap stays in CSS and the panel only ever shrinks to fit — and
  * recovers once room is restored (e.g. the iOS keyboard closes).
  */
-export declare function useFloatingPanel(opts: FloatingPanelOptions): void;
+export declare function useFloatingPanel(opts: FloatingPanelOptions): FloatingPanelState;
+/**
+ * Inline style for a panel driven by {@link useFloatingPanel}. Pins the
+ * positioning coordinate system Floating UI expects — `position` matches the
+ * strategy, `margin:0; inset:auto` neutralise the UA popover centering — and,
+ * when the panel is NOT top-layer-promoted, drives visibility from `open` (the
+ * UA `[popover]:not(:popover-open){display:none}` rule only applies while the
+ * `popover` attribute is present, which the in-place modes omit).
+ *
+ * `extra` is prepended so a caller's own declarations (e.g. a consumer `style`
+ * prop, or `overflow-y:auto`) stay overridable by the load-bearing positioning
+ * tokens that follow.
+ */
+export declare function floatingPanelStyle(panel: FloatingPanelState, open: boolean, extra?: string): string;

package/dist/utils/use-floating-panel.svelte.js

@@ -1,4 +1,5 @@
 import { autoUpdate, computePosition, flip, size as floatingSize, offset, shift } from './floating.js';
+import { isAnchoredInModalDialog } from './overlay.js';
 /**
  * Manages native popover state + Floating UI positioning for anchored overlay
  * panels (Select, Combobox, Popover, and through it Menu). Handles show/hide,
@@ -11,6 +12,13 @@ import { autoUpdate, computePosition, flip, size as floatingSize, offset, shift
  * the caller's own dismiss handlers in control; this helper only drives
  * `showPopover()`/`hidePopover()` and never reads the dismiss mode.
  *
+ * Top-layer promotion is automatic but conditional: the helper skips it (and
+ * returns `topLayer: false`) when the anchor sits inside an open modal
+ * `<dialog>`, where a second top-layer element is invisible on iOS/WebKit
+ * (Codeberg #23) — the panel then renders `position: fixed` in place. Callers
+ * mirror the returned `topLayer`/`strategy` in their markup via
+ * {@link floatingPanelStyle}.
+ *
  * The Floating-UI `size` middleware feeds the room actually left between the
  * anchor and the (visual) viewport edge into `--blocks-overlay-available-height`.
  * Variants cap height via `max-h-[min(<design-cap>,var(--…,100dvh))]`, so the
@@ -19,11 +27,24 @@ import { autoUpdate, computePosition, flip, size as floatingSize, offset, shift
  */
 export function useFloatingPanel(opts) {
     let cleanupPosition;
+    // Effective render mode — derived synchronously, never via an $effect-set
+    // $state. A lagged mode would leave the element carrying a stale
+    // `popover="manual"` for one frame and re-trigger the exact WebKit
+    // double-top-layer bug this guards against (Codeberg #23).
+    const inModalDialog = $derived(opts.open() ? isAnchoredInModalDialog(opts.reference()) : false);
+    const portalHint = $derived(opts.portal?.() ?? true);
+    // Top layer (native popover) only when the caller opted in AND the anchor is
+    // not nested in a modal dialog. `strategy` stays `fixed` for the dialog case
+    // so the panel escapes the dialog body's overflow clipping; only the explicit
+    // inline mode (`portal=false`) falls back to `absolute`.
+    const topLayer = $derived(portalHint && !inModalDialog);
+    const strategy = $derived(portalHint ? 'fixed' : 'absolute');
     $effect(() => {
         const ref = opts.reference();
         const floating = opts.floating();
         const isOpen = opts.open();
-        const usePortal = opts.portal?.() ?? true;
+        const useTopLayer = topLayer;
+        const positionStrategy = strategy;
         const placement = opts.placement?.() ?? 'bottom-start';
         const offsetDistance = opts.offsetDistance?.() ?? 4;
         const shiftPadding = opts.shiftPadding?.() ?? 8;
@@ -42,29 +63,41 @@ export function useFloatingPanel(opts) {
             // Drop the keyboard-aware height clamp so the next open re-measures from
             // the full design cap instead of inheriting a stale value.
             floating.style.removeProperty('--blocks-overlay-available-height');
-            if (usePortal && floating.matches(':popover-open')) {
+            // Guard on the live `:popover-open` state only (not the current mode):
+            // a panel that was promoted to the top layer must still be torn down even
+            // if its mode has since flipped to `fixed`/`inline`.
+            if (floating.matches(':popover-open')) {
                 try {
                     floating.hidePopover();
                 }
-                catch {
-                    /* already hidden */
+                catch (err) {
+                    // Pre-check ruled out "already hidden": a real failure here is a
+                    // detached node or a consumer-overridden popover attribute. Surface
+                    // it (as Tooltip/Guide do) instead of leaving the panel stuck in the
+                    // top layer with no diagnostics.
+                    console.warn('[useFloatingPanel] hidePopover failed', err);
                 }
             }
             return;
         }
-        if (usePortal && !floating.matches(':popover-open')) {
+        if (useTopLayer && !floating.matches(':popover-open')) {
             try {
                 floating.showPopover();
             }
-            catch {
-                /* already shown or not supported */
+            catch (err) {
+                // Pre-check ruled out "already shown": a real failure here (missing
+                // Popover API on a legacy browser, a detached node, or a consumer-
+                // overridden popover attribute) would leave the panel stuck
+                // `display:none` via the UA rule with no diagnostics — exactly the
+                // silent "overlay never opens" class of bug. Surface it for telemetry.
+                console.warn('[useFloatingPanel] showPopover failed', err);
             }
         }
         cleanupPosition?.();
         cleanupPosition = autoUpdate(ref, floating, () => {
             computePosition(ref, floating, {
                 placement,
-                strategy: usePortal ? 'fixed' : 'absolute',
+                strategy: positionStrategy,
                 middleware: [
                     offset(offsetDistance),
                     flip(),
@@ -99,11 +132,38 @@ export function useFloatingPanel(opts) {
                     top: `${y}px`
                 });
             })
-                .catch(() => { });
+                // Mirrors Tooltip/Guide: middleware can throw synchronously on a
+                // detached node; surface it instead of swallowing it silently.
+                .catch((err) => console.warn('[useFloatingPanel] computePosition failed', err));
         });
         return () => {
             cleanupPosition?.();
             cleanupPosition = undefined;
         };
     });
+    return {
+        get topLayer() {
+            return topLayer;
+        },
+        get strategy() {
+            return strategy;
+        }
+    };
+}
+/**
+ * Inline style for a panel driven by {@link useFloatingPanel}. Pins the
+ * positioning coordinate system Floating UI expects — `position` matches the
+ * strategy, `margin:0; inset:auto` neutralise the UA popover centering — and,
+ * when the panel is NOT top-layer-promoted, drives visibility from `open` (the
+ * UA `[popover]:not(:popover-open){display:none}` rule only applies while the
+ * `popover` attribute is present, which the in-place modes omit).
+ *
+ * `extra` is prepended so a caller's own declarations (e.g. a consumer `style`
+ * prop, or `overflow-y:auto`) stay overridable by the load-bearing positioning
+ * tokens that follow.
+ */
+export function floatingPanelStyle(panel, open, extra = '') {
+    const positioning = `position: ${panel.strategy}; margin: 0; inset: auto;`;
+    const hidden = !panel.topLayer && !open ? ' display: none;' : '';
+    return `${extra}${positioning}${hidden}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.3.11",
+  "version": "6.3.12",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -91,8 +91,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.3.11",
-    "@urbicon-ui/shared-types": "6.3.11",
+    "@urbicon-ui/i18n": "6.3.12",
+    "@urbicon-ui/shared-types": "6.3.12",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",