@urbicon-ui/blocks 6.3.7 → 6.3.9

package/dist/primitives/Breadcrumb/Breadcrumb.svelte

@@ -7,6 +7,7 @@
   let {
     items,
     size = 'md',
+    wrap = true,
     separator,
     maxItems,
     itemsBeforeCollapse = 1,
@@ -23,7 +24,7 @@
   const blocksConfig = getBlocksConfig();
   const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
 
-  const variantProps: BreadcrumbVariants = $derived({ size });
+  const variantProps: BreadcrumbVariants = $derived({ size, wrap });
 
   const styles = $derived(breadcrumbVariants(variantProps));
 

package/dist/primitives/Breadcrumb/breadcrumb.variants.d.ts

@@ -14,45 +14,62 @@ export declare const breadcrumbVariants: (props?: import("../../utils/variants.j
             separator: string;
         };
     };
+    wrap: {
+        true: {
+            list: string;
+        };
+        false: {
+            nav: string;
+            list: string;
+            currentPage: string;
+        };
+    };
 }> | undefined) => {
     nav: (props?: ({
         size?: "sm" | "md" | "lg" | undefined;
+        wrap?: boolean | undefined;
     } & {
         class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
     }) | undefined) => string;
     list: (props?: ({
         size?: "sm" | "md" | "lg" | undefined;
+        wrap?: boolean | undefined;
     } & {
         class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
     }) | undefined) => string;
     item: (props?: ({
         size?: "sm" | "md" | "lg" | undefined;
+        wrap?: boolean | undefined;
     } & {
         class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
     }) | undefined) => string;
     link: (props?: ({
         size?: "sm" | "md" | "lg" | undefined;
+        wrap?: boolean | undefined;
     } & {
         class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
     }) | undefined) => string;
     currentPage: (props?: ({
         size?: "sm" | "md" | "lg" | undefined;
+        wrap?: boolean | undefined;
     } & {
         class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
     }) | undefined) => string;
     ellipsis: (props?: ({
         size?: "sm" | "md" | "lg" | undefined;
+        wrap?: boolean | undefined;
     } & {
         class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
     }) | undefined) => string;
     separator: (props?: ({
         size?: "sm" | "md" | "lg" | undefined;
+        wrap?: boolean | undefined;
     } & {
         class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;

package/dist/primitives/Breadcrumb/breadcrumb.variants.js

@@ -2,7 +2,7 @@ import { tv } from '../../utils/variants.js';
 export const breadcrumbVariants = tv({
     slots: {
         nav: 'flex items-center',
-        list: 'flex items-center flex-wrap',
+        list: 'flex items-center',
         item: 'inline-flex items-center',
         link: [
             'text-text-secondary hover:text-text-primary',
@@ -35,9 +35,29 @@ export const breadcrumbVariants = tv({
                 list: 'text-base gap-1',
                 separator: 'mx-2'
             }
+        },
+        // Overflow strategy when the trail runs out of horizontal room.
+        // `wrap` (default): the trail wraps to multiple lines — the standard
+        // free-flowing breadcrumb. `false`: the trail stays on one line and the
+        // current page (always the last item) truncates while the ancestor links
+        // hold their width — for tight single-line bars (sticky headers, toolbars)
+        // where the page name is the part worth shortening. Pair with `maxItems`
+        // to fold the middle into a "…" before the current page has to truncate.
+        wrap: {
+            true: {
+                list: 'flex-wrap'
+            },
+            false: {
+                nav: 'min-w-0',
+                list: 'flex-nowrap min-w-0 [&>li:not(:last-child)]:shrink-0 [&>li:last-child]:min-w-0 [&>li:last-child]:shrink',
+                // Let the current page consume the available width and truncate, rather
+                // than capping at the wrap-mode max-width.
+                currentPage: 'max-w-none'
+            }
         }
     },
     defaultVariants: {
-        size: 'md'
+        size: 'md',
+        wrap: true
     }
 });

package/dist/primitives/Breadcrumb/index.d.ts

@@ -52,6 +52,13 @@ export interface BreadcrumbProps extends BreadcrumbVariants, Omit<HTMLAttributes
     items: BreadcrumbItem[];
     /** Size @default 'md' */
     size?: 'sm' | 'md' | 'lg';
+    /**
+     * Let the trail wrap onto multiple lines (`true`, default) or keep it on a
+     * single line where the current page truncates and the ancestor links hold
+     * their width (`false`). Use `false` for tight single-line bars such as a
+     * sticky header or toolbar. @default true
+     */
+    wrap?: boolean;
     /** Custom separator snippet (default: "/") */
     separator?: Snippet;
     /**

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, useFloatingListbox } from '../../utils';
+  import { useFormField, getTierContext, useFloatingPanel } from '../../utils';
   import type { ComboboxProps, ComboboxOption } from './index';
 
   const bt = useBlocksI18n();
@@ -263,10 +263,13 @@
     }
   });
 
-  useFloatingListbox({
+  useFloatingPanel({
     reference: () => inputEl,
     floating: () => listboxEl,
-    open: () => open
+    open: () => open,
+    // The listbox always tracks the input width exactly; the generic panel
+    // helper defaults to no width-sync, so the listbox pattern opts in.
+    syncWidth: () => true
   });
 
   const listboxId = $derived(`${id}-listbox`);

package/dist/primitives/Menu/menu.variants.js

@@ -16,7 +16,12 @@ export const menuVariants = tv({
         // modify trigger stays on the subtler container border.
         content: [
             'box-border border shadow-[var(--blocks-shadow-md)] p-1',
-            'max-h-80 overflow-y-auto',
+            // 20rem (max-h-80) is the static design cap; the wrapping Popover's
+            // useFloatingPanel sets `--blocks-overlay-available-height` on the panel,
+            // which cascades to this content surface so the menu shrinks above the
+            // iOS keyboard and recovers when it closes. Falls back to the design cap
+            // when the var is unset (SSR / no JS).
+            'max-h-[min(20rem,var(--blocks-overlay-available-height,100dvh))] overflow-y-auto',
             'bg-surface-elevated'
         ],
         header: ['sticky top-0 z-10 bg-surface-elevated', 'px-2 py-1 border-b border-border-hairline'],

package/dist/primitives/Popover/Popover.svelte

@@ -1,14 +1,7 @@
 <script lang="ts">
   import { untrack } from 'svelte';
   import { getBlocksConfig, resolveSlotClasses } from '../../provider';
-  import {
-    autoUpdate,
-    computePosition,
-    flip,
-    size as floatingSize,
-    offset,
-    shift
-  } from '../../utils/floating';
+  import { useFloatingPanel } from '../../utils';
   import { popoverVariants } from './popover.variants';
   import type { PopoverProps } from './index';
 
@@ -56,7 +49,6 @@
 
   let internalTriggerElement = $state<HTMLElement | null>(null);
   let popoverElement = $state<HTMLElement | null>(null);
-  let cleanupFloatingUI = $state<(() => void) | undefined>();
 
   const effectiveTriggerElement = $derived(triggerElement || internalTriggerElement);
 
@@ -245,94 +237,24 @@
   });
 
   // ── Floating UI positioning + native show/hide ─────────────
-
-  $effect(() => {
-    if (!open || !effectiveTriggerElement || !popoverElement) {
-      if (popoverElement?.matches(':popover-open')) {
-        try {
-          popoverElement.hidePopover();
-        } catch (err) {
-          // Pre-check eliminated "already hidden"; real causes are
-          // detached elements or popover API absence. Surface to telemetry.
-          console.warn('[Popover] hidePopover failed', err);
-        }
-      }
-      return;
-    }
-
-    // Show the popover in the top layer so it has layout for positioning
-    if (!popoverElement.matches(':popover-open')) {
-      try {
-        popoverElement.showPopover();
-      } catch (err) {
-        // Real causes: legacy browser without Popover API (Safari < 17,
-        // Chrome < 114, Firefox < 125), element detached, or `popover`
-        // attribute overridden by a consumer via restProps.
-        console.warn('[Popover] showPopover failed', err);
-      }
-    }
-
-    const updatePosition = () => {
-      if (!effectiveTriggerElement || !popoverElement) return;
-
-      return computePosition(effectiveTriggerElement, popoverElement, {
-        placement,
-        // `fixed` is the right strategy when the panel sits in the popover
-        // top layer (viewport-coordinated); `absolute` matches the in-flow
-        // mode where the panel is positioned relative to the trigger's
-        // offset parent.
-        strategy: usePortal ? 'fixed' : 'absolute',
-        middleware: [
-          offset(offsetDistance),
-          flip(),
-          shift({ padding: shiftPadding }),
-          floatingSize({
-            apply({ rects }) {
-              if (!popoverElement) return;
-              // `syncWidth` clamps the panel to the trigger width exactly
-              // (Select/Combobox semantics — items longer than the field
-              // truncate or wrap). `syncMinWidth` is the looser Menu-style
-              // variant: panel ≥ trigger.width, but content is free to grow
-              // it. Hard sync wins if both are set.
-              popoverElement.style.width = syncWidth ? `${rects.reference.width}px` : '';
-              popoverElement.style.minWidth =
-                !syncWidth && syncMinWidth ? `${rects.reference.width}px` : '';
-            }
-          })
-        ]
-      })
-        .then(({ x, y }) => {
-          if (!popoverElement) return;
-          // `autoUpdate` may fire after the trigger has detached, in which
-          // case Floating UI returns NaN. Bail rather than writing `NaNpx`.
-          if (!Number.isFinite(x) || !Number.isFinite(y)) return;
-          Object.assign(popoverElement.style, {
-            left: `${x}px`,
-            top: `${y}px`
-          });
-        })
-        .catch((err) => {
-          // Middleware can throw synchronously (e.g. geometry read on a
-          // detached node). Without a catch this becomes an unhandled
-          // rejection with no Popover context.
-          console.warn('[Popover] computePosition failed', err);
-        });
-    };
-
-    updatePosition();
-    cleanupFloatingUI = autoUpdate(effectiveTriggerElement, popoverElement, updatePosition);
-
-    return () => {
-      cleanupFloatingUI?.();
-      cleanupFloatingUI = undefined;
-      if (popoverElement?.matches(':popover-open')) {
-        try {
-          popoverElement.hidePopover();
-        } catch (err) {
-          console.warn('[Popover] hidePopover failed', err);
-        }
-      }
-    };
+  //
+  // 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 ───────────────────────────────────────
@@ -390,9 +312,10 @@
   `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
-  the existing autoUpdate effect, 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).
+  `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).
 -->
 <div
   bind:this={popoverElement}

package/dist/primitives/Popover/popover.variants.js

@@ -4,7 +4,13 @@ export const popoverVariants = tv({
     base: [
         'bg-surface-elevated border border-border-hairline rounded-contain',
         'shadow-[var(--blocks-shadow-md)] backdrop-blur-sm',
-        'overflow-y-auto max-h-[calc(100dvh-4rem)]'
+        // `calc(100dvh-4rem)` is the static design cap; Floating UI's `size`
+        // middleware (via useFloatingPanel) narrows it to the room actually left
+        // between the anchor and the visual viewport edge through
+        // `--blocks-overlay-available-height`, so the panel shrinks above the iOS
+        // keyboard and recovers when it closes. The var falls back to 100dvh when
+        // unset (SSR / no JS), leaving the design cap in charge.
+        'overflow-y-auto max-h-[min(calc(100dvh-4rem),var(--blocks-overlay-available-height,100dvh))]'
     ],
     variants: {
         size: {

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, useFloatingListbox } from '../../utils';
+  import { useFormField, getTierContext, useFloatingPanel } from '../../utils';
   import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { resolveIcon } from '../../icons';
   import ChevronDownIconDefault from '../../icons/ChevronDownIcon.svelte';
@@ -228,7 +228,7 @@
     activeIndex = next;
   });
 
-  useFloatingListbox({
+  useFloatingPanel({
     reference: () => triggerRef,
     floating: () => listboxRef,
     open: () => open,

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 FloatingListboxOptions, useFloatingListbox } from './use-floating-listbox.svelte.js';
+export { type FloatingPanelOptions, 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 { useFloatingListbox } from './use-floating-listbox.svelte.js';
+export { 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/use-floating-panel.svelte.d.ts

@@ -0,0 +1,44 @@
+import { type Placement } from './floating.js';
+export interface FloatingPanelOptions {
+    /** The anchor the panel positions against. */
+    reference: () => HTMLElement | null | undefined;
+    /** The floating panel element. */
+    floating: () => HTMLElement | null | undefined;
+    /** 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`.
+     */
+    portal?: () => boolean;
+    /** Preferred placement. @default 'bottom-start' */
+    placement?: () => Placement;
+    /** Main-axis gap between anchor and panel, in px. @default 4 */
+    offsetDistance?: () => number;
+    /** Viewport padding kept by the shift middleware, in px. @default 8 */
+    shiftPadding?: () => number;
+    /** Clamp the panel width to exactly the anchor width. @default false */
+    syncWidth?: () => boolean;
+    /** Clamp the panel's *min*-width to the anchor width (it may still grow). @default false */
+    syncMinWidth?: () => boolean;
+}
+/**
+ * Manages native popover state + Floating UI positioning for anchored overlay
+ * panels (Select, Combobox, Popover, and through it Menu). Handles show/hide,
+ * the autoUpdate lifecycle, position computation, a keyboard-aware height cap,
+ * and cleanup — one positioning codepath shared across every overlay so an
+ * iOS/visualViewport or flip/shift fix lands everywhere at once.
+ *
+ * `popover` (top layer) keeps the panel above any `overflow` clipping from
+ * parent containers. `popover="manual"` (set by the caller in markup) leaves
+ * the caller's own dismiss handlers in control; this helper only drives
+ * `showPopover()`/`hidePopover()` and never reads the dismiss mode.
+ *
+ * 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;

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

@@ -0,0 +1,109 @@
+import { autoUpdate, computePosition, flip, size as floatingSize, offset, shift } from './floating.js';
+/**
+ * Manages native popover state + Floating UI positioning for anchored overlay
+ * panels (Select, Combobox, Popover, and through it Menu). Handles show/hide,
+ * the autoUpdate lifecycle, position computation, a keyboard-aware height cap,
+ * and cleanup — one positioning codepath shared across every overlay so an
+ * iOS/visualViewport or flip/shift fix lands everywhere at once.
+ *
+ * `popover` (top layer) keeps the panel above any `overflow` clipping from
+ * parent containers. `popover="manual"` (set by the caller in markup) leaves
+ * the caller's own dismiss handlers in control; this helper only drives
+ * `showPopover()`/`hidePopover()` and never reads the dismiss mode.
+ *
+ * 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 function useFloatingPanel(opts) {
+    let cleanupPosition;
+    $effect(() => {
+        const ref = opts.reference();
+        const floating = opts.floating();
+        const isOpen = opts.open();
+        const usePortal = opts.portal?.() ?? true;
+        const placement = opts.placement?.() ?? 'bottom-start';
+        const offsetDistance = opts.offsetDistance?.() ?? 4;
+        const shiftPadding = opts.shiftPadding?.() ?? 8;
+        const syncWidth = opts.syncWidth?.() ?? false;
+        const syncMinWidth = opts.syncMinWidth?.() ?? false;
+        // No panel element → nothing to show, hide, or position.
+        if (!floating)
+            return;
+        // Closed — OR open but the anchor has gone (e.g. a conditionally-rendered
+        // trigger unmounted while the panel was up). Either way tear down and hide
+        // so a portalled panel can't linger, unanchored, in the top layer. The
+        // hide path deliberately needs only `floating`, not `ref`.
+        if (!isOpen || !ref) {
+            cleanupPosition?.();
+            cleanupPosition = undefined;
+            // 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')) {
+                try {
+                    floating.hidePopover();
+                }
+                catch {
+                    /* already hidden */
+                }
+            }
+            return;
+        }
+        if (usePortal && !floating.matches(':popover-open')) {
+            try {
+                floating.showPopover();
+            }
+            catch {
+                /* already shown or not supported */
+            }
+        }
+        cleanupPosition?.();
+        cleanupPosition = autoUpdate(ref, floating, () => {
+            computePosition(ref, floating, {
+                placement,
+                strategy: usePortal ? 'fixed' : 'absolute',
+                middleware: [
+                    offset(offsetDistance),
+                    flip(),
+                    shift({ padding: shiftPadding }),
+                    floatingSize({
+                        apply({ availableHeight, rects }) {
+                            // Cap the panel to the room actually left between the anchor and
+                            // the (visual) viewport edge — decisive on iOS, where the
+                            // keyboard shrinks the visualViewport. Exposed as a CSS var that
+                            // the variant feeds into `max-h-[min(<cap>,var(--…))]`, so the
+                            // design token stays the upper bound while this tracks the live
+                            // available height (and recovers when room is restored).
+                            floating.style.setProperty('--blocks-overlay-available-height', `${Math.max(0, Math.round(availableHeight))}px`);
+                            // `syncWidth` clamps the panel to the anchor width exactly
+                            // (Select/Combobox semantics — items wider than the field
+                            // truncate or wrap). `syncMinWidth` is the looser Menu-style
+                            // variant: panel ≥ anchor width, but content is free to grow it.
+                            // Hard sync wins if both are set; otherwise width resets so a
+                            // toggled-off sync cannot leave a stale inline width behind.
+                            floating.style.width = syncWidth ? `${rects.reference.width}px` : '';
+                            floating.style.minWidth =
+                                !syncWidth && syncMinWidth ? `${rects.reference.width}px` : '';
+                        }
+                    })
+                ]
+            })
+                .then(({ x, y }) => {
+                if (!Number.isFinite(x) || !Number.isFinite(y))
+                    return;
+                Object.assign(floating.style, {
+                    left: `${x}px`,
+                    top: `${y}px`
+                });
+            })
+                .catch(() => { });
+        });
+        return () => {
+            cleanupPosition?.();
+            cleanupPosition = undefined;
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.3.7",
+  "version": "6.3.9",
   "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.7",
-    "@urbicon-ui/shared-types": "6.3.7",
+    "@urbicon-ui/i18n": "6.3.9",
+    "@urbicon-ui/shared-types": "6.3.9",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",

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

@@ -1,17 +0,0 @@
-export interface FloatingListboxOptions {
-    reference: () => HTMLElement | undefined;
-    floating: () => HTMLElement | undefined;
-    open: () => boolean;
-    portal?: () => boolean;
-    syncWidth?: () => boolean;
-}
-/**
- * Manages native popover state + Floating UI positioning for listbox-pattern
- * components (Select, Combobox). Handles show/hide, autoUpdate lifecycle,
- * position computation, and cleanup.
- *
- * `popover="manual"` puts the listbox in the browser top layer so overflow
- * clipping from parent containers cannot hide it. Manual mode (not auto)
- * keeps the component's own dismiss handlers in control.
- */
-export declare function useFloatingListbox(opts: FloatingListboxOptions): void;

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

@@ -1,87 +0,0 @@
-import { autoUpdate, computePosition, flip, size as floatingSize, offset, shift } from './floating.js';
-/**
- * Manages native popover state + Floating UI positioning for listbox-pattern
- * components (Select, Combobox). Handles show/hide, autoUpdate lifecycle,
- * position computation, and cleanup.
- *
- * `popover="manual"` puts the listbox in the browser top layer so overflow
- * clipping from parent containers cannot hide it. Manual mode (not auto)
- * keeps the component's own dismiss handlers in control.
- */
-export function useFloatingListbox(opts) {
-    let cleanupPosition;
-    $effect(() => {
-        const ref = opts.reference();
-        const floating = opts.floating();
-        if (!ref || !floating)
-            return;
-        const isOpen = opts.open();
-        const usePortal = opts.portal?.() ?? true;
-        const syncWidth = opts.syncWidth?.() ?? true;
-        if (!isOpen) {
-            cleanupPosition?.();
-            cleanupPosition = undefined;
-            // 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')) {
-                try {
-                    floating.hidePopover();
-                }
-                catch {
-                    /* already hidden */
-                }
-            }
-            return;
-        }
-        if (usePortal && !floating.matches(':popover-open')) {
-            try {
-                floating.showPopover();
-            }
-            catch {
-                /* already shown or not supported */
-            }
-        }
-        cleanupPosition?.();
-        cleanupPosition = autoUpdate(ref, floating, () => {
-            if (!ref || !floating)
-                return;
-            computePosition(ref, floating, {
-                placement: 'bottom-start',
-                strategy: usePortal ? 'fixed' : 'absolute',
-                middleware: [
-                    offset(4),
-                    flip(),
-                    shift({ padding: 8 }),
-                    floatingSize({
-                        apply({ availableHeight, rects }) {
-                            // Cap the panel to the room actually left between the anchor and
-                            // the (visual) viewport edge — decisive on iOS, where the
-                            // keyboard shrinks the visualViewport. Exposed as a CSS var that
-                            // the variant feeds into `max-h-[min(15rem,var(--…))]`, so the
-                            // 15rem design token stays the upper bound while this tracks the
-                            // live available height (and recovers when room is restored).
-                            floating.style.setProperty('--blocks-overlay-available-height', `${Math.max(0, Math.round(availableHeight))}px`);
-                            if (syncWidth) {
-                                floating.style.width = `${rects.reference.width}px`;
-                            }
-                        }
-                    })
-                ]
-            })
-                .then(({ x, y }) => {
-                if (!Number.isFinite(x) || !Number.isFinite(y))
-                    return;
-                Object.assign(floating.style, {
-                    left: `${x}px`,
-                    top: `${y}px`
-                });
-            })
-                .catch(() => { });
-        });
-        return () => {
-            cleanupPosition?.();
-            cleanupPosition = undefined;
-        };
-    });
-}