@urbicon-ui/blocks 6.21.1 → 6.21.3

package/dist/primitives/Input/input.variants.d.ts

@@ -2,7 +2,7 @@ import { type SlotNames, type VariantProps } from '../../utils/variants.js';
 export declare const inputVariants: ((props?: {
     tier?: "commit" | "modify" | undefined;
     variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-    size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+    size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
     intent?: "default" | "success" | "warning" | "danger" | undefined;
     disabled?: boolean | undefined;
     readonly?: boolean | undefined;
@@ -16,7 +16,7 @@ export declare const inputVariants: ((props?: {
     wrapper: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         intent?: "default" | "success" | "warning" | "danger" | undefined;
         disabled?: boolean | undefined;
         readonly?: boolean | undefined;
@@ -32,7 +32,7 @@ export declare const inputVariants: ((props?: {
     container: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         intent?: "default" | "success" | "warning" | "danger" | undefined;
         disabled?: boolean | undefined;
         readonly?: boolean | undefined;
@@ -48,7 +48,7 @@ export declare const inputVariants: ((props?: {
     base: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         intent?: "default" | "success" | "warning" | "danger" | undefined;
         disabled?: boolean | undefined;
         readonly?: boolean | undefined;
@@ -64,7 +64,7 @@ export declare const inputVariants: ((props?: {
     label: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         intent?: "default" | "success" | "warning" | "danger" | undefined;
         disabled?: boolean | undefined;
         readonly?: boolean | undefined;
@@ -80,7 +80,7 @@ export declare const inputVariants: ((props?: {
     message: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         intent?: "default" | "success" | "warning" | "danger" | undefined;
         disabled?: boolean | undefined;
         readonly?: boolean | undefined;
@@ -96,7 +96,7 @@ export declare const inputVariants: ((props?: {
     iconContainer: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         intent?: "default" | "success" | "warning" | "danger" | undefined;
         disabled?: boolean | undefined;
         readonly?: boolean | undefined;
@@ -112,7 +112,7 @@ export declare const inputVariants: ((props?: {
     iconButton: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         intent?: "default" | "success" | "warning" | "danger" | undefined;
         disabled?: boolean | undefined;
         readonly?: boolean | undefined;
@@ -128,7 +128,7 @@ export declare const inputVariants: ((props?: {
     iconDecoration: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         intent?: "default" | "success" | "warning" | "danger" | undefined;
         disabled?: boolean | undefined;
         readonly?: boolean | undefined;

package/dist/primitives/Menu/Menu.svelte

@@ -1,4 +1,5 @@
 <script lang="ts" generics="TItem extends MenuItemType = MenuItemType">
+  import { tick } from 'svelte';
   import { useBlocksI18n } from '../..';
   import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { Button, menuVariants, type MenuVariants } from '..';
@@ -27,11 +28,13 @@
     disabled = false,
     loading = false,
     open = $bindable(false),
+    onOpenChange,
     id: idProp,
     placement = 'bottom-start',
     syncWidth = true,
     usePortal = true,
     customTrigger,
+    contextTrigger,
     customItem,
     customHeader,
     customFooter,
@@ -71,6 +74,31 @@
   let openSubMenus = $state<Set<string>>(new Set());
   const childrenMode = $derived(!!children);
 
+  // ── Context-menu (right-click) anchoring ───────────────────────────────
+  // A context menu has no trigger button — it opens at the cursor. Floating UI
+  // anchors to an element, not a point, so a 0×0 fixed-position element is
+  // parked at the click coordinates and handed to Popover as the trigger.
+  let cursorAnchor = $state<HTMLElement>();
+  let contextX = $state(0);
+  let contextY = $state(0);
+
+  async function handleContextMenu(event: MouseEvent) {
+    if (disabled || loading) return;
+    // Suppress the native browser menu and anchor ours at the cursor.
+    event.preventDefault();
+    contextX = event.clientX;
+    contextY = event.clientY;
+    // Re-open at the new spot even if it was already open elsewhere: close and
+    // let Popover tear down (await tick) before reopening, so it re-reads the
+    // moved anchor rect. A synchronous setOpen(false)+setOpen(true) batches into
+    // no net change and would strand the menu at the previous cursor position.
+    if (open) {
+      setOpen(false);
+      await tick();
+    }
+    setOpen(true);
+  }
+
   // Map of declarative MenuItems by id — populated via the context's
   // `registerItem` / `unregisterItem` hooks. Used to debug + (in future)
   // power type-ahead search; the keyboard model itself walks DOM-focusable
@@ -127,13 +155,25 @@
   }
 
   // ── Open / close lifecycle ─────────────────────────────────────────────
+  // Single mutation point for internally-driven open changes, so
+  // `onOpenChange` fires exactly once per transition. Popover-owned dismiss
+  // paths (outside click) mutate `open` via `bind:open` instead and report
+  // through the forwarded Popover `onOpenChange` — the Escape path can't
+  // double-fire because `handlePanelKeydown` calls `preventDefault()`,
+  // which Popover's document-level Escape listener honors.
+  function setOpen(next: boolean) {
+    if (open === next) return;
+    open = next;
+    onOpenChange?.(next);
+  }
+
   function toggle() {
     if (disabled || loading) return;
-    open = !open;
+    setOpen(!open);
   }
 
   function dismiss() {
-    open = false;
+    setOpen(false);
     triggerRef?.focus();
   }
 
@@ -363,6 +403,26 @@
     .join(' ')}
   {...restProps}
 >
+  {#if contextTrigger}
+    <!-- Right-click target. `display: contents` drops the wrapper from layout so
+         the consumer's own element controls sizing; the contextmenu event still
+         bubbles to the handler. -->
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div class="contents" oncontextmenu={handleContextMenu}>
+      {@render contextTrigger()}
+    </div>
+    <!-- 0×0 anchor parked at the cursor for Popover to position the menu against. -->
+    <div
+      bind:this={cursorAnchor}
+      aria-hidden="true"
+      style:position="fixed"
+      style:left="{contextX}px"
+      style:top="{contextY}px"
+      style:width="0"
+      style:height="0"
+    ></div>
+  {/if}
+
   {#snippet triggerContent()}
     {#if customTrigger}
       {@render customTrigger(toggle, open, dismiss)}
@@ -414,13 +474,15 @@
   -->
   <Popover
     bind:open
+    onOpenChange={(o) => onOpenChange?.(o)}
     placement={placement as import('../../utils/floating').Placement}
     {usePortal}
     autoTrigger={false}
     unstyled
-    syncMinWidth={syncWidth}
+    syncMinWidth={contextTrigger ? false : syncWidth}
     offsetDistance={effectiveTier === 'commit' ? 8 : 4}
-    trigger={triggerContent}
+    trigger={contextTrigger ? undefined : triggerContent}
+    triggerElement={contextTrigger ? cursorAnchor : undefined}
   >
     <div
       bind:this={panelRef}

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

@@ -119,6 +119,12 @@ export interface MenuSpecificProps<TItem extends MenuItemType = MenuItemType> {
      * @default false
      */
     open?: boolean;
+    /**
+     * Fires when the menu opens or closes from user interaction (trigger
+     * click, item activation, Escape, Tab-out, outside click). Receives the
+     * new open state. Not called when the consumer writes `bind:open` directly.
+     */
+    onOpenChange?: (open: boolean) => void;
     /**
      * Button variant applied to the default trigger button.
      * @default 'outlined'
@@ -252,6 +258,25 @@ export interface MenuCustomSlots<TItem extends MenuItemType = MenuItemType> {
      * `aria-expanded={open}` + `aria-haspopup="menu"` for ARIA correctness.
      */
     customTrigger?: Snippet<[() => void, boolean, () => void]>;
+    /**
+     * Turn the menu into a **context menu**: instead of a trigger button, the
+     * snippet you pass becomes a right-click target. A `contextmenu` (right-click
+     * or long-press) on it opens the menu at the cursor position — the native
+     * browser context menu is suppressed. Keyboard navigation, dismissal and
+     * item selection behave exactly as in the dropdown menu; on dismiss, focus
+     * returns to wherever it was. Mutually exclusive with `customTrigger`/the
+     * default trigger button (when set, no trigger button renders).
+     *
+     * @example
+     * ```svelte
+     * <Menu {items} contextTrigger>
+     *   {#snippet contextTrigger()}
+     *     <div class="rounded-modify border border-border-subtle p-8">Right-click me</div>
+     *   {/snippet}
+     * </Menu>
+     * ```
+     */
+    contextTrigger?: Snippet;
     /**
      * Custom per-item content. **Render visible content only** — the outer
      * `role="menuitem"` button is provided by Menu and handles the click /

package/dist/primitives/Pagination/Pagination.svelte

@@ -34,6 +34,7 @@
     nextIcon,
     firstIcon,
     lastIcon,
+    renderItem,
     itemsPerPage = 10,
     totalItems,
     startItem,
@@ -323,19 +324,33 @@
 
       {#if showNumbers}
         {#each visiblePageNumbers as page (page)}
-          <PaginationItem
-            {size}
-            {variant}
-            {intent}
-            {tier}
-            {page}
-            active={page === currentPage}
-            disabled={disabled || loading}
-            onPageClick={goToPage(page)}
-            {mint}
-          >
-            {page}
-          </PaginationItem>
+          {#if renderItem}
+            {@render renderItem({
+              page,
+              active: page === currentPage,
+              disabled: disabled || loading,
+              size,
+              variant,
+              intent,
+              tier,
+              mint,
+              select: goToPage(page)
+            })}
+          {:else}
+            <PaginationItem
+              {size}
+              {variant}
+              {intent}
+              {tier}
+              {page}
+              active={page === currentPage}
+              disabled={disabled || loading}
+              onPageClick={goToPage(page)}
+              {mint}
+            >
+              {page}
+            </PaginationItem>
+          {/if}
         {/each}
       {/if}
 

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

@@ -10,6 +10,33 @@ export interface PaginationPageItem {
     active?: boolean;
     disabled?: boolean;
 }
+/**
+ * Context handed to the `renderItem` snippet for a single numbered page button.
+ * Bundles the page number, its active/disabled state, the style props forwarded
+ * from the Pagination (so a custom item stays visually consistent), and a
+ * `select` callback that changes the page (guarded against disabled / no-op /
+ * out-of-range internally).
+ */
+export interface PaginationItemContext {
+    /** The 1-based page number this item represents. */
+    page: number;
+    /** Whether this item is the currently active page. */
+    active: boolean;
+    /** Whether the item is inert (component `disabled` or `loading`). */
+    disabled: boolean;
+    /** Button size forwarded from the Pagination props. */
+    size: 'sm' | 'md' | 'lg';
+    /** Button variant forwarded from the Pagination props. */
+    variant: 'outlined' | 'filled' | 'ghost';
+    /** Semantic intent forwarded from the Pagination props. */
+    intent: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
+    /** Semantic radius tier forwarded from the Pagination props. */
+    tier?: InteractiveTier;
+    /** Micro-interaction preset forwarded from the Pagination props. */
+    mint: MintProp;
+    /** Navigate to this page. No-op when disabled, already active, or out of range. */
+    select: () => void;
+}
 /**
  * @description Navigation control for paged data sets.
  * Supports multiple layouts, intents, button variants, and configurable ellipsis behaviour.
@@ -69,6 +96,23 @@ export interface PaginationProps extends Omit<PaginationVariants, 'disabled' | '
     firstIcon?: Snippet;
     /** Custom icon rendered inside the "Last" button. */
     lastIcon?: Snippet;
+    /**
+     * Render each numbered page button yourself. Receives a {@link PaginationItemContext}
+     * with the page number, its active/disabled state, the forwarded style props
+     * (size, variant, intent, tier, mint) and a `select` callback. Only affects the
+     * numbered page buttons in the default layout — prev/next/first/last keep their
+     * own icon snippets, and the ellipsis is unaffected.
+     *
+     * @example
+     * ```svelte
+     * <Pagination {currentPage} {totalPages} {onPageChange}>
+     *   {#snippet renderItem({ page, active, disabled, select })}
+     *     <button class:active onclick={select} {disabled}>{page}</button>
+     *   {/snippet}
+     * </Pagination>
+     * ```
+     */
+    renderItem?: Snippet<[PaginationItemContext]>;
     /** Items shown per page. Used by the table layout to compute "Showing X to Y of Z". */
     itemsPerPage?: number;
     /** Total number of items across all pages. Used by the table layout info text. */

package/dist/primitives/Popover/Popover.svelte

@@ -184,7 +184,7 @@
         }
 
         if (!wasTrigger) {
-          effectiveTriggerElement?.focus();
+          focusTrigger();
         }
       }
     }
@@ -209,11 +209,17 @@
     // intentionally consume Escape.
     function handleEscape(e: KeyboardEvent) {
       if (e.key !== 'Escape' || e.defaultPrevented) return;
+      // Re-check `open` (like the auto-mode toggle handler does): the
+      // listener teardown is deferred to the next effect flush, so a
+      // consumer handler earlier in this same dispatch may already have
+      // closed via `bind:open` — without this guard we'd report a second,
+      // transition-less onOpenChange(false) + onEscape and steal focus.
+      if (!open) return;
       e.preventDefault();
       open = false;
       onOpenChange?.(false);
       onEscapeProp?.();
-      effectiveTriggerElement?.focus();
+      focusTrigger();
     }
     document.addEventListener('keydown', handleEscape);
     return () => document.removeEventListener('keydown', handleEscape);
@@ -231,6 +237,10 @@
       if (!target) return;
       if (popoverElement?.contains(target)) return;
       if (effectiveTriggerElement?.contains(target)) return;
+      // Same deferred-teardown re-check as handleEscape above: a consumer
+      // capture-phase pointerdown handler may have closed via `bind:open`
+      // within this dispatch — don't report a second close.
+      if (!open) return;
       open = false;
       onOpenChange?.(false);
       onClickOutsideProp?.();
@@ -266,8 +276,29 @@
 
   // ── Trigger handlers ───────────────────────────────────────
 
+  // Restore focus to the trigger after a dismiss. The snippet trigger is
+  // wrapped in a plain (non-focusable) div — `focus()` on it is a spec no-op —
+  // so target the interactive descendant instead (same query as the
+  // aria-expanded effect). An external `triggerElement` is the consumer's
+  // real control: focus it directly.
+  function focusTrigger() {
+    const target =
+      triggerElement ??
+      internalTriggerElement?.querySelector<HTMLElement>(
+        'button, a[href], [role="button"], [tabindex]'
+      ) ??
+      internalTriggerElement;
+    target?.focus();
+  }
+
   function handleTriggerPointerDown() {
-    if (open) dismissedByTrigger = true;
+    // Arm the "this pointerdown already dismissed it" guard only in auto
+    // mode, where the browser's light dismiss really closes the popover
+    // between pointerdown and click (the guard stops that click from
+    // 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;
   }
 
   function handleTriggerClick(event: MouseEvent) {

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

@@ -4,8 +4,8 @@ import type { Placement } from '../../utils/floating.js';
 import type { PopoverVariants } from './popover.variants.js';
 /**
  * @description Floating panel anchored to a trigger element. Uses the native Popover API
- * for top-layer rendering, light dismiss, and Escape handling. Floating UI provides
- * precise positioning with automatic flip, shift, and optional width syncing.
+ * for top-layer rendering, light dismiss, and Escape handling. The library's built-in
+ * positioning engine provides automatic flip, shift, and optional width syncing.
  *
  * @tag overlay
  * @related Tooltip
@@ -45,7 +45,7 @@ export interface PopoverProps extends PopoverVariants, Omit<HTMLAttributes<HTMLD
     trigger?: Snippet;
     /** External trigger element ref. Use instead of the `trigger` snippet when the trigger lives outside the Popover tree. Supports `bind:triggerElement`. */
     triggerElement?: HTMLElement;
-    /** Where the popover appears relative to the trigger. All Floating UI `Placement` values are supported. */
+    /** Where the popover appears relative to the trigger. All standard `Placement` values (side plus optional `-start`/`-end` alignment) are supported. */
     placement?: Placement;
     /** Gap in px between the trigger edge and the popover. */
     offsetDistance?: number;

package/dist/primitives/RadioGroup/RadioGroup.svelte

@@ -46,7 +46,7 @@
   // ARIA wiring is shared with every form primitive — see XC-2.
   const ff = useFormField(() => ({
     fieldId: groupId,
-    hint: helper,
+    helper,
     error,
     required,
     disabled
@@ -174,9 +174,9 @@
     >
       {error}
     </div>
-  {:else if ff.hintId}
+  {:else if ff.helperId}
     <div
-      id={ff.hintId}
+      id={ff.helperId}
       class={unstyled
         ? (slotClasses?.message ?? '')
         : styles.message({ class: slotClasses?.message })}

package/dist/primitives/Select/Select.svelte

@@ -38,6 +38,7 @@
     mint = 'none',
     onValueChange,
     open = $bindable(false),
+    onOpenChange,
     usePortal = true,
     syncWidth = true,
     customTrigger,
@@ -101,7 +102,7 @@
   const labelId = $derived(label ? `${uid}-label` : undefined);
   const ff = useFormField(() => ({
     fieldId: uid,
-    hint: helper,
+    helper,
     error,
     required,
     disabled
@@ -235,12 +236,21 @@
     syncWidth: () => syncWidth
   });
 
+  // Single mutation point for internally-driven open changes, so
+  // `onOpenChange` fires exactly once per transition (and never when the
+  // consumer writes `bind:open` directly).
+  function setOpen(next: boolean) {
+    if (open === next) return;
+    open = next;
+    onOpenChange?.(next);
+  }
+
   function toggle() {
     if (disabled) return;
     // Pointer-driven open (trigger onclick). Mark modality so the open effect
     // doesn't pre-highlight the first row for a mouse/touch user.
     if (!open) openedViaKeyboard = false;
-    open = !open;
+    setOpen(!open);
     if (!open) activeIndex = -1;
   }
 
@@ -271,7 +281,7 @@
       dispatchValueChange?.(nextValue);
     }
     if (effectiveCloseOnSelect) {
-      open = false;
+      setOpen(false);
       activeIndex = -1;
       focusTrigger();
     }
@@ -297,7 +307,7 @@
   //                  explicitly intent to focus elsewhere)
   function dismissByEscape() {
     if (!closeOnEscape) return false;
-    open = false;
+    setOpen(false);
     activeIndex = -1;
     onEscape?.();
     return true;
@@ -319,7 +329,7 @@
         event.preventDefault();
         if (!open) {
           openedViaKeyboard = true;
-          open = true;
+          setOpen(true);
         } else {
           activeIndex = activeIndex < enabledOptions.length - 1 ? activeIndex + 1 : 0;
         }
@@ -328,7 +338,7 @@
         event.preventDefault();
         if (!open) {
           openedViaKeyboard = true;
-          open = true;
+          setOpen(true);
         } else {
           activeIndex = activeIndex > 0 ? activeIndex - 1 : enabledOptions.length - 1;
         }
@@ -338,7 +348,7 @@
         event.preventDefault();
         if (!open) {
           openedViaKeyboard = true;
-          open = true;
+          setOpen(true);
         } else if (activeIndex >= 0 && activeIndex < enabledOptions.length) {
           selectOption(enabledOptions[activeIndex]);
         }
@@ -353,7 +363,7 @@
         // Tab leaves the widget — close (focus moves on via the default tab),
         // independent of closeOnEscape/closeOnClickOutside.
         if (open) {
-          open = false;
+          setOpen(false);
           activeIndex = -1;
         }
         break;
@@ -382,7 +392,7 @@
       !listboxRef.contains(target)
     ) {
       if (!closeOnClickOutside) return;
-      open = false;
+      setOpen(false);
       activeIndex = -1;
       onClickOutside?.();
     }
@@ -725,9 +735,9 @@
     >
       {error}
     </div>
-  {:else if ff.hintId}
+  {:else if ff.helperId}
     <div
-      id={ff.hintId}
+      id={ff.helperId}
       class={unstyled
         ? (slotClasses?.message ?? '')
         : styles.message({ class: slotClasses?.message })}

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

@@ -164,6 +164,13 @@ interface SelectBaseProps<T extends SelectValue = string> extends Omit<SelectVar
      * the Select wrapper). @default false
      */
     open?: boolean;
+    /**
+     * Fires when the listbox opens or closes from user interaction (trigger
+     * click, keyboard, selection, Escape, Tab-out, outside click). Receives the
+     * new open state — use it e.g. to lazy-load options on first open. Not
+     * called when the consumer writes `bind:open` directly.
+     */
+    onOpenChange?: (open: boolean) => void;
     /**
      * When true, the listbox is rendered into the browser top layer via the native
      * `popover` API, so it cannot be clipped by `overflow: auto` ancestors. When