@urbicon-ui/blocks 6.24.0 → 6.25.0

package/dist/primitives/ButtonGroup/ButtonGroup.svelte

@@ -247,6 +247,10 @@
   }
 
   const ariaRole = $derived(selection === 'single' ? 'radiogroup' : 'group');
+  // ARIA allows `aria-orientation` on `radiogroup`, not on `group` — emitting it
+  // on the multi-selection arm is an `aria-allowed-attr` violation. The visual
+  // orientation is unaffected; it comes from the variant classes, not from ARIA.
+  const ariaOrientation = $derived(ariaRole === 'radiogroup' ? orientation : undefined);
 </script>
 
 <div
@@ -257,7 +261,7 @@
     : styles.base({ class: [slotClasses?.base, className] })}
   aria-label={ariaLabel}
   aria-labelledby={ariaLabelledBy}
-  aria-orientation={orientation}
+  aria-orientation={ariaOrientation}
   aria-disabled={disabled || undefined}
   onkeydown={handleKeyDown}
   {...restProps}

package/dist/primitives/Collapsible/Collapsible.svelte

@@ -42,6 +42,16 @@
   let internalOpen = $state(defaultOpen ?? false);
   const isOpen = $derived(open !== undefined ? open : internalOpen);
 
+  // Single mutation point. Family contract (COMPONENT-API-CONVENTIONS.md
+  // §Open-state vocabulary): the transition is applied optimistically — `open`
+  // (or the uncontrolled seed) is written *before* `onOpenChange` fires, once
+  // per transition. With `bind:open` that write is the propagation. A consumer
+  // passing `open` without `bind:` must mirror every `onOpenChange` back into
+  // its state (Svelte can't distinguish `open={x}` from `bind:open={x}` at
+  // runtime, so a rejected transition is undetectable from in here). To veto
+  // transitions, own them instead: drive `open` from your source of truth and
+  // toggle it from a custom `trigger` snippet — see AccordionItem's
+  // collapsible=false handling.
   function toggle() {
     if (disabled) return;
     const next = !isOpen;

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

@@ -32,11 +32,22 @@ import type { CollapsibleSlots, CollapsibleVariants } from './collapsible.varian
  * ```
  */
 export interface CollapsibleProps extends CollapsibleVariants, Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
-    /** Whether the content is visible. Supports bind:open. */
+    /**
+     * Whether the content is visible. Supports bind:open. Trigger-driven transitions
+     * are applied optimistically: `open` is updated first, then `onOpenChange` reports
+     * the change. When passing `open` without `bind:`, mirror every `onOpenChange`
+     * back into your state — an ignored change leaves the component and your source
+     * of truth diverged. To conditionally reject transitions, drive `open` from your
+     * own state and toggle it from a custom `trigger` snippet instead of calling the
+     * provided `toggle`.
+     */
     open?: boolean;
     /** Initial open state for uncontrolled usage @default false */
     defaultOpen?: boolean;
-    /** Callback fired when open state changes */
+    /**
+     * Callback fired once per trigger-driven open transition, after the state is
+     * applied. Not fired for consumer writes via `bind:open`.
+     */
     onOpenChange?: (open: boolean) => void;
     /** Disable the trigger @default false */
     disabled?: boolean;

package/dist/primitives/ConfirmDialog/ConfirmDialog.svelte

@@ -15,6 +15,7 @@
     cancelLabel,
     confirmIntent,
     onConfirm,
+    onError,
     onCancel,
     loading = false,
     closeOnBackdropClick = true,
@@ -39,6 +40,19 @@
       busy = true;
       await onConfirm();
       open = false;
+    } catch (error) {
+      // Failure contract: skip the auto-close (dialog stays open) and re-enable
+      // (busy cleared in `finally`) so the user can retry or cancel. The
+      // rejection is handed to `onError`; without one it is surfaced DEV-only
+      // instead of escaping the ignored onclick promise as an unhandled
+      // rejection (Combobox queryFn / Toast promise precedent). A throwing
+      // `onError` is a consumer bug and deliberately escapes (fail-loud,
+      // mirrors createCronRunner).
+      if (onError) {
+        onError(error);
+      } else if (import.meta.env?.DEV) {
+        console.error('[ConfirmDialog] onConfirm rejected:', error);
+      }
     } finally {
       busy = false;
     }

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

@@ -16,7 +16,8 @@ export type ConfirmIntent = Exclude<DialogIntent, 'neutral'>;
  *
  * `onConfirm` may be `async`; while the returned promise is pending the
  * dialog locks itself (no backdrop dismiss, no escape, confirm button
- * shows a spinner). Auto-closes on resolve.
+ * shows a spinner). Auto-closes on resolve; on reject it stays open and
+ * re-enables, handing the error to `onError`.
  *
  * @tag overlay
  * @related Dialog
@@ -60,9 +61,19 @@ export interface ConfirmDialogProps extends Omit<HTMLDialogAttributes, 'children
     cancelLabel?: string;
     /**
      * Confirm handler. May return a promise — the dialog stays open and shows
-     * a loading state while it resolves, then auto-closes on success.
+     * a loading state while it resolves, then auto-closes on success. If the
+     * promise rejects the dialog stays open and re-enables; the rejection is
+     * reported via {@link ConfirmDialogProps.onError}.
      */
     onConfirm?: () => void | Promise<void>;
+    /**
+     * Fired when an async `onConfirm` rejects (or a sync one throws). The
+     * dialog stays open and re-enables so the user can retry or cancel — use
+     * this to surface the failure (toast, inline message). Without a handler
+     * the rejection is logged DEV-only (`console.error`) and swallowed in
+     * production; it never escapes as an unhandled promise rejection.
+     */
+    onError?: (error: unknown) => void;
     /** Fired when the user cancels (button, backdrop, or Escape). */
     onCancel?: () => void;
     /**

package/dist/primitives/Dialog/Dialog.svelte

@@ -6,6 +6,7 @@
   import { onDestroy, tick } from 'svelte';
   import { fade, scale } from 'svelte/transition';
   import { trapFocus, showDialogModal, closeDialogModal } from '../../utils/overlay';
+  import { composeHandlers } from '../../utils/compose-handlers';
   import { overlayStack, getOverlayMotion } from '../../utils';
   import Button from '../Button/Button.svelte';
   import type { DialogProps } from './index';
@@ -34,6 +35,16 @@
     unstyled: unstyledProp = false,
     slotClasses: slotClassesProp = {},
     preset,
+    // Pulled out of restProps so the `{...restProps}`-first spread (internal
+    // attributes win — see docs/COMPONENT-API-CONVENTIONS.md) can't clobber
+    // them, and so neither side loses: the behavioural handlers below are
+    // composed (internal first, consumer second) and the two ARIA attributes
+    // are merged, rather than one silently replacing the other.
+    onclick: onclickProp,
+    onkeydown: onkeydownProp,
+    onclose: oncloseProp,
+    'aria-labelledby': ariaLabelledby,
+    'aria-describedby': ariaDescribedby,
     ...restProps
   }: DialogProps = $props();
 
@@ -134,6 +145,14 @@
   const bodyId = `dialog-body-${uid}`;
   const overlayId = `dialog-${uid}`;
 
+  // A rendered `title` owns the labelling; without one, a consumer-supplied
+  // `aria-labelledby` (e.g. a heading inside `children`) is the fallback, so
+  // external labelling survives the restProps-first spread.
+  const labelledBy = $derived(titleId ?? ariaLabelledby);
+  // Merged, not replaced: a consumer's description is supplemental to the
+  // dialog's own body — internal id first, consumer id last (mirrors Input).
+  const describedBy = $derived([bodyId, ariaDescribedby].filter(Boolean).join(' ') || undefined);
+
   const variantProps: DialogVariants = $derived({ size, placement, intent });
   const styles = $derived(dialogVariants(variantProps));
   const slotClasses = $derived(
@@ -176,6 +195,12 @@
     if (closeOnBackdropClick) requestClose();
   }
 
+  // Native `close` event (ESC handled by the UA, form[method=dialog], .close()).
+  // Named rather than inline so it can be composed with a consumer `onclose`.
+  function handleNativeClose() {
+    if (open) requestClose();
+  }
+
   function handleOutroEnd() {
     closeDialogModal(dialogEl, previouslyFocused, releaseScrollLock);
     releaseScrollLock = undefined;
@@ -230,18 +255,16 @@
 
 {#if isVisible}
   <dialog
+    {...restProps}
     bind:this={dialogEl}
     class={unstyled ? (slotClasses?.dialog ?? '') : styles.dialog({ class: slotClasses?.dialog })}
-    onclick={handleBackdropClick}
-    onkeydown={handleKeydown}
-    onclose={() => {
-      if (open) requestClose();
-    }}
-    aria-labelledby={titleId}
-    aria-describedby={bodyId}
+    onclick={composeHandlers(handleBackdropClick, onclickProp)}
+    onkeydown={composeHandlers(handleKeydown, onkeydownProp)}
+    onclose={composeHandlers(handleNativeClose, oncloseProp)}
+    aria-labelledby={labelledBy}
+    aria-describedby={describedBy}
     aria-modal="true"
     data-state={open ? 'open' : 'closed'}
-    {...restProps}
   >
     {#if open}
       <div

package/dist/primitives/Drawer/Drawer.svelte

@@ -6,6 +6,7 @@
   import { onDestroy, tick } from 'svelte';
   import { fade, fly } from 'svelte/transition';
   import { trapFocus, showDialogModal, closeDialogModal } from '../../utils/overlay';
+  import { composeHandlers } from '../../utils/compose-handlers';
   import { overlayStack, getOverlayMotion } from '../../utils';
   import Button from '../Button/Button.svelte';
   import type { DrawerProps } from './index';
@@ -34,6 +35,15 @@
     unstyled: unstyledProp = false,
     slotClasses: slotClassesProp = {},
     preset,
+    // Pulled out of restProps so the `{...restProps}`-first spread (internal
+    // attributes win — see docs/COMPONENT-API-CONVENTIONS.md) can't clobber
+    // them, and so neither side loses: the behavioural handlers below are
+    // composed (internal first, consumer second) and the two ARIA attributes
+    // are merged, rather than one silently replacing the other. Mirrors Dialog.
+    onkeydown: onkeydownProp,
+    onclose: oncloseProp,
+    'aria-labelledby': ariaLabelledby,
+    'aria-describedby': ariaDescribedby,
     ...restProps
   }: DrawerProps = $props();
 
@@ -66,6 +76,14 @@
   const bodyId = `drawer-body-${uid}`;
   const overlayId = `drawer-${uid}`;
 
+  // A rendered `title` owns the labelling; without one, a consumer-supplied
+  // `aria-labelledby` (e.g. a heading inside `children`) is the fallback, so
+  // external labelling survives the restProps-first spread.
+  const labelledBy = $derived(titleId ?? ariaLabelledby);
+  // Merged, not replaced: a consumer's description is supplemental to the
+  // drawer's own body — internal id first, consumer id last (mirrors Input).
+  const describedBy = $derived([bodyId, ariaDescribedby].filter(Boolean).join(' ') || undefined);
+
   const variantProps: DrawerVariants = $derived({ placement, size, intent, accentEdge });
   const styles = $derived(drawerVariants(variantProps));
   const slotClasses = $derived(
@@ -159,6 +177,12 @@
     if (event.key === 'Tab') trapFocus(event, panelElement);
   }
 
+  // Native `close` event (ESC handled by the UA, form[method=dialog], .close()).
+  // Named rather than inline so it can be composed with a consumer `onclose`.
+  function handleNativeClose() {
+    if (open) requestClose();
+  }
+
   function handleOutroEnd() {
     closeDialogModal(dialogElement, previouslyFocused, releaseScrollLock);
     releaseScrollLock = undefined;
@@ -171,17 +195,15 @@
 
 {#if isVisible}
   <dialog
+    {...restProps}
     bind:this={dialogElement}
     class={unstyled ? (slotClasses?.dialog ?? '') : styles.dialog({ class: slotClasses?.dialog })}
-    onkeydown={handleKeydown}
-    onclose={() => {
-      if (open) requestClose();
-    }}
-    aria-labelledby={titleId}
-    aria-describedby={bodyId}
+    onkeydown={composeHandlers(handleKeydown, onkeydownProp)}
+    onclose={composeHandlers(handleNativeClose, oncloseProp)}
+    aria-labelledby={labelledBy}
+    aria-describedby={describedBy}
     aria-modal="true"
     data-state={open ? 'open' : 'closed'}
-    {...restProps}
   >
     {#if open}
       <div

package/dist/primitives/Input/Input.svelte

@@ -43,6 +43,7 @@
     persistVersion = 1,
     persistNamespace,
     onkeydown: userOnKeydown,
+    id: idProp,
     'aria-describedby': ariaDescribedby,
     ...restProps
   }: InputProps = $props();
@@ -118,9 +119,14 @@
   );
 
   // ARIA wiring is shared with every form primitive — see XC-2.
+  // A consumer-supplied `id` wins over the generated one: pairing an Input
+  // with an external `<label for>` is only possible if the id we are handed
+  // actually reaches the `<input>`. `$props.id()` may only appear as a
+  // top-level initializer, hence the two-step derive.
   const propsId = $props.id();
+  const fieldId = $derived(idProp ?? `input-${propsId}`);
   const ff = useFormField(() => ({
-    fieldId: `input-${propsId}`,
+    fieldId,
     helper,
     error,
     required,

package/dist/primitives/JourneyTimeline/journey-timeline.variants.js

@@ -111,13 +111,13 @@ export const journeyTimelineVariants = tv({
         },
         size: {
             sm: {
-                meta: 'text-[11px]',
+                meta: 'text-2xs',
                 marker: 'size-2.5',
                 node: 'gap-x-2.5',
                 card: '-mx-1.5 px-1.5 py-1.5',
                 title: 'text-xs',
-                subtitle: 'text-[11px]',
-                segment: 'text-[11px]',
+                subtitle: 'text-2xs',
+                segment: 'text-2xs',
                 content: 'pb-4',
                 detailContent: 'text-xs pt-2',
                 panel: 'p-3 text-xs'

package/dist/primitives/Menu/Menu.svelte

@@ -8,6 +8,7 @@
   import { getTierContext } from '../../utils/tier-context';
   const ChevronDownIcon = resolveIcon('chevronDown', ChevronDownIconDefault);
   import Popover from '../Popover/Popover.svelte';
+  import { popoverMotion } from '../Popover/popover.variants';
   import { setMenuContext, type MenuContext, type MenuRegistryItem } from './menu.context';
   import MenuItemComp from './MenuItem.svelte';
   import MenuSubmenu from './MenuSubmenu.svelte';
@@ -471,6 +472,12 @@
     only painted layer. Without this, the panel renders as two stacked
     surfaces (Popover wrapper + Menu content) and shows a near-empty box
     with double borders.
+
+    The stripped default ALSO carried the enter/exit motion, so the exact
+    fragment (`popoverMotion`) is re-applied via `class` — it survives
+    Popover's `unstyled` by design and animates the transparent wrapper,
+    which fades/scales the Menu chrome inside it. A Menu-level `unstyled`
+    strips it again; consumers rebuild on the panel's `data-state`.
   -->
   <Popover
     bind:open
@@ -479,6 +486,7 @@
     {usePortal}
     autoTrigger={false}
     unstyled
+    class={unstyled ? undefined : popoverMotion}
     syncMinWidth={contextTrigger ? false : syncWidth}
     offsetDistance={effectiveTier === 'commit' ? 8 : 4}
     trigger={contextTrigger ? undefined : triggerContent}

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

@@ -7,18 +7,9 @@ import type { Placement } from '../../utils/floating.js';
 import type { InteractiveTier } from '../../utils/tier-context.js';
 import type { MenuSlots } from './menu.variants.js';
 /**
- * @description Action menu (`role="menu"`) triggered by a button. Items are
- * verbs the user can invoke — Edit, Delete, Share, Export — and dispatch an
- * `onSelect` callback when activated. For picking a value from a list use
- * `Select` (or `Combobox` for searchable). Menu and Select are deliberately
- * disjoint: Menu's ARIA semantics, keyboard model (Tab through items, Enter
- * triggers), and visual chrome match the Action surface family; Select's
- * `role="listbox"` + arrow-navigation match the Form surface family.
- *
- * @tag action
- * @related Select
- * @related Combobox
- * @related Popover
+ * Menu-specific props. The catalog JSDoc (`@description`/`@tag`/`@related`)
+ * lives on `MenuProps` below — the interface docs-gen actually picks up —
+ * so it is not duplicated here.
  *
  * @example Items array with `onSelect` callbacks
  * ```svelte
@@ -172,7 +163,14 @@ export interface MenuSpecificProps<TItem extends MenuItemType = MenuItemType> {
     mint?: MintProp;
 }
 /**
- * @description Action menu triggered by a button with nested items, icons, separators, and keyboard navigation.
+ * @description Action menu (`role="menu"`) triggered by a button, with nested
+ * submenus, sections, icons, and separators. Items are verbs the user can
+ * invoke — Edit, Delete, Share, Export — and dispatch an `onSelect` callback
+ * when activated; Menu holds no selection state. For picking a value from a
+ * list use `Select` (or `Combobox` for searchable). Menu and Select are
+ * deliberately disjoint: Menu's `role="menu"`/`menuitem` semantics with
+ * arrow-key roving and Action-family chrome versus Select's `role="listbox"`
+ * value commitment with Form-family chrome.
  *
  * @tag action
  * @related Select

package/dist/primitives/Popover/Popover.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { untrack } from 'svelte';
   import { getBlocksConfig, resolveSlotClasses } from '../../provider';
-  import { useFloatingPanel, floatingPanelHidden } from '../../utils';
+  import { useFloatingPanel, floatingPanelHidden, maxTransitionDurationMs } from '../../utils';
   import { popoverVariants } from './popover.variants';
   import type { PopoverProps } from './index';
 
@@ -21,6 +21,9 @@
     autoTrigger = true,
     size = 'md',
 
+    transitionDuration,
+    transitionEasing,
+
     onOpenChange,
     onClickOutside: onClickOutsideProp,
     onEscape: onEscapeProp,
@@ -47,11 +50,64 @@
     resolveSlotClasses(blocksConfig, 'Popover', preset, { size }, slotClassesProp)
   );
 
+  // Per-instance motion overrides. Set the shared popover CSS variables inline
+  // only when a prop is provided, so the unset default keeps inheriting the
+  // reduced-motion-aware token (mirrors Tooltip's transitionDuration path).
+  const popoverDurationInline = $derived(
+    transitionDuration != null ? `${transitionDuration}ms` : undefined
+  );
+
   let internalTriggerElement = $state<HTMLElement | null>(null);
   let popoverElement = $state<HTMLElement | null>(null);
 
   const effectiveTriggerElement = $derived(triggerElement || internalTriggerElement);
 
+  // ── Exit-motion lag (ACC-3 rest) ───────────────────────────
+  //
+  // Closing used to tear three things down in one flush: `open` flips, the
+  // children block unmounts, and `useFloatingPanel` hides the panel. The CSS
+  // exit transition (see `popoverMotion` in popover.variants.ts) keeps the
+  // *panel element* painted via `allow-discrete`, but the children must
+  // outlive `open` or the panel fades out empty. `exiting` lags the teardown
+  // by the panel's actual computed transition duration — read from the live
+  // style so per-instance props, theme token overrides, and reduced motion all
+  // shorten it automatically. A zero duration (jsdom/node tests, browsers
+  // without the CSS, `unstyled` without rebuilt motion) tears down
+  // synchronously: exactly the pre-motion behaviour.
+  //
+  // `$effect.pre` matters: the flag must be `true` in the SAME flush that
+  // renders `open === false`, otherwise the children unmount one frame before
+  // the lag starts. The `prevOpenForExit` tracker (non-reactive, seeded via
+  // `untrack` like `prevPopoverMode` below) keeps the effect keyed on real
+  // transitions — without it, the `bind:this` assignment would re-run the
+  // effect on mount and flash a closed-by-default popover open for one lag.
+  const EXIT_MOTION_BUFFER_MS = 50;
+  let exiting = $state(false);
+  let exitTimer: ReturnType<typeof setTimeout> | undefined;
+  let prevOpenForExit = untrack(() => open);
+  $effect.pre(() => {
+    if (open === prevOpenForExit) return;
+    prevOpenForExit = open;
+    if (open) {
+      clearTimeout(exitTimer);
+      exiting = false;
+      return;
+    }
+    const ms = maxTransitionDurationMs(untrack(() => popoverElement));
+    if (ms <= 0) return;
+    exiting = true;
+    exitTimer = setTimeout(() => {
+      exiting = false;
+    }, ms + EXIT_MOTION_BUFFER_MS);
+  });
+
+  // While `exiting`, the panel is still fading: keep children mounted and (in
+  // the in-place modes) keep `display` un-hidden. `useFloatingPanel` stays on
+  // the raw `open` on purpose — `hidePopover()` fires immediately and the
+  // discrete transition carries the visual exit, so a re-open during the fade
+  // reverses smoothly instead of waiting out the lag.
+  const panelVisible = $derived(open || exiting);
+
   // ── Floating UI positioning + native show/hide ─────────────
   //
   // Delegated to the shared `useFloatingPanel` helper — the same positioning
@@ -291,6 +347,27 @@
     target?.focus();
   }
 
+  // Un-arm `dismissedByTrigger` at the start of the NEXT pointer gesture,
+  // wherever it lands. Registered as a one-shot capture listener when the
+  // guard arms: capture order (document before trigger) guarantees a stale
+  // flag is cleared before any new arm, and `once` keeps at most one listener
+  // pending. This closes the aborted-click hole (pointerdown on the trigger,
+  // pointer released elsewhere → no click ever consumed the flag → the next
+  // trigger click was swallowed once).
+  function disarmDismissedByTrigger() {
+    dismissedByTrigger = false;
+  }
+
+  // Unmount cleanup for the imperative leftovers: a pending exit-lag timer
+  // and a still-armed disarm listener. Dependency-free → runs once,
+  // teardown on destroy.
+  $effect(() => {
+    return () => {
+      clearTimeout(exitTimer);
+      document.removeEventListener('pointerdown', disarmDismissedByTrigger, true);
+    };
+  });
+
   function handleTriggerPointerDown() {
     // Arm the "this pointerdown already dismissed it" guard only in auto
     // mode, where the browser's light dismiss really closes the popover
@@ -298,7 +375,15 @@
     // re-opening it). In manual mode nothing light-dismisses — the click
     // itself must toggle-close, so arming the guard there left the trigger
     // unable to close its own popover.
-    if (open && popoverMode === 'auto') dismissedByTrigger = true;
+    if (open && popoverMode === 'auto') {
+      dismissedByTrigger = true;
+      // This event has already passed the document's capture phase, so the
+      // listener can only fire on a LATER pointerdown.
+      document.addEventListener('pointerdown', disarmDismissedByTrigger, {
+        capture: true,
+        once: true
+      });
+    }
   }
 
   function handleTriggerClick(event: MouseEvent) {
@@ -361,6 +446,20 @@
       drops over a modal dialog (Codeberg #23).
 -->
 
+<!--
+  `data-state` sits after `{...restProps}` like the other load-bearing
+  attributes: it drives the enter/exit motion CSS (popoverMotion) and is the
+  documented styling hook for consumers rebuilding motion under `unstyled`.
+  `{#if panelVisible}` (not `open`) keeps the children mounted while the exit
+  transition plays; `style:display` follows the same lagged flag so the
+  in-place modes can fade out before they hide.
+
+  `inert` while closed (GuidePanel's pattern): the exit-fading children are
+  still mounted and displayed, so without it a Tab right after dismiss would
+  focus into the visually dismissed panel and Enter could re-fire a consumer
+  action; pointer-events-none (popoverMotion) only covers mouse/touch. Also
+  drops the fading subtree from the a11y tree immediately.
+-->
 <div
   bind:this={popoverElement}
   class={popoverClasses}
@@ -370,12 +469,16 @@
   style:position={panel.strategy}
   style:inset="auto"
   style:margin="0"
-  style:display={floatingPanelHidden(panel, open) ? 'none' : null}
+  style:display={floatingPanelHidden(panel, panelVisible) ? 'none' : null}
+  style:--blocks-popover-duration={popoverDurationInline}
+  style:--blocks-popover-easing={transitionEasing}
+  data-state={open ? 'open' : 'closed'}
+  inert={!open || undefined}
   {role}
   aria-modal={ariaModal || undefined}
   {id}
 >
-  {#if open}
+  {#if panelVisible}
     {@render children()}
   {/if}
 </div>

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

@@ -70,6 +70,19 @@ export interface PopoverProps extends PopoverVariants, Omit<HTMLAttributes<HTMLD
     open?: boolean;
     /** When true (default), the trigger wrapper handles click and keyboard to toggle the popover. Set to `false` to manage `open` yourself. */
     autoTrigger?: boolean;
+    /**
+     * Override the enter/exit fade duration in ms. Defaults to the shared token
+     * `--blocks-popover-duration` (150ms; collapses to 1ms under
+     * `prefers-reduced-motion`).
+     */
+    transitionDuration?: number;
+    /**
+     * Override the enter/exit easing as a CSS `<easing-function>` (e.g.
+     * `'linear'`, `'ease-out'`, `'cubic-bezier(0.4,0,0.2,1)'`). Defaults to the
+     * token `--blocks-popover-easing`. A CSS string, not a JS easing fn, because
+     * the popover motion is a pure CSS transition.
+     */
+    transitionEasing?: string;
     /**
      * Whether the popover closes on Escape key. Default `true`.
      * Set to `false` for cases where Escape should be intercepted by an
@@ -98,7 +111,7 @@ export interface PopoverProps extends PopoverVariants, Omit<HTMLAttributes<HTMLD
     onEscape?: () => void;
     /** Extra classes merged onto the floating panel element. */
     class?: string;
-    /** Strip all default tv() classes. Combine with `class` or `slotClasses` for full custom styling. */
+    /** Strip all default tv() classes (including the enter/exit motion). Combine with `class` or `slotClasses` for full custom styling; the panel always carries `data-state="open" | "closed"`, so custom motion can rebuild on that hook (see `popoverMotion` in popover.variants.ts for the reference implementation). */
     unstyled?: boolean;
     /** Per-slot class overrides. Available slots: `base` (the floating panel). */
     slotClasses?: Partial<Record<'base', string>>;
@@ -111,4 +124,4 @@ export interface PopoverProps extends PopoverVariants, Omit<HTMLAttributes<HTMLD
     preset?: string;
 }
 export { default as Popover } from './Popover.svelte';
-export { type PopoverVariants, popoverVariants } from './popover.variants.js';
+export { type PopoverVariants, popoverMotion, popoverVariants } from './popover.variants.js';

package/dist/primitives/Popover/index.js

@@ -1,2 +1,2 @@
 export { default as Popover } from './Popover.svelte';
-export { popoverVariants } from './popover.variants.js';
+export { popoverMotion, popoverVariants } from './popover.variants.js';

package/dist/primitives/Popover/popover.variants.d.ts

@@ -1,4 +1,29 @@
 import { type VariantProps } from '../../utils/variants.js';
+/**
+ * CSS-native enter/exit motion for the floating panel (ACC-3 rest), keyed on
+ * the `data-state` attribute Popover always stamps. Kept as its own fragment
+ * because two call sites need exactly these classes: `popoverVariants.base`
+ * below, and Menu — which renders its inner Popover `unstyled` (to avoid a
+ * double surface) and re-applies the fragment via Popover's `class` prop.
+ *
+ * How the two halves work:
+ * - **Enter** — the panel un-hides via `showPopover()` (top layer) or a
+ *   `display` flip (in-place mode), so a plain transition has no before-state;
+ *   `starting:` (`@starting-style`) supplies it.
+ * - **Exit** — `hidePopover()` / a native light dismiss yank the panel to
+ *   `display: none` in the same style recalc that flips `data-state`;
+ *   `transition-discrete` (`transition-behavior: allow-discrete`) on
+ *   `display`/`overlay` keeps it painted (and in the top layer) until the
+ *   fade lands. Popover lags the children-teardown to match — see the
+ *   exit-motion block in Popover.svelte.
+ *
+ * Browsers without `@starting-style`/`allow-discrete` simply skip the motion
+ * and keep today's instant toggle. Duration/easing resolve through the
+ * `--blocks-popover-*` tokens (interaction.css), which reduced motion
+ * collapses to 1ms; `motion-reduce:duration-[1ms]` guards the inline
+ * per-instance override path, which can't see the media query.
+ */
+export declare const popoverMotion: string;
 export declare const popoverVariants: ((props?: import("../../utils/variants.js").TVProps<{
     size: {
         sm: string;