@urbicon-ui/blocks 6.21.1 → 6.21.2

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

@@ -1,5 +1,6 @@
 import type { Snippet } from 'svelte';
 import type { DialogIntent } from '../Dialog/index.js';
+import type { DialogSlots } from '../Dialog/dialog.variants.js';
 /**
  * Intent applied to the confirm button. Reuses the standard intent palette
  * via {@link DialogIntent} (with `neutral` mapped to `primary` for visual
@@ -88,5 +89,23 @@ export interface ConfirmDialogProps {
     transitionEasing?: (t: number) => number;
     /** Optional richer markup rendered below `description`. */
     children?: Snippet;
+    /** Extra classes merged onto the dialog element. Forwarded to {@link DialogProps.class}. */
+    class?: string;
+    /**
+     * Strip the underlying Dialog's default styles. Combine with `slotClasses`
+     * for a fully custom appearance. @default false
+     */
+    unstyled?: boolean;
+    /**
+     * Per-slot class overrides, forwarded to the underlying Dialog.
+     * Slots: dialog | backdrop | panel | content | header | title | body | footer.
+     */
+    slotClasses?: Partial<Record<DialogSlots, string>>;
+    /**
+     * Apply a named preset registered via `<BlocksProvider presets={{ Dialog: {...} }}>`.
+     * Resolved against the `Dialog` component key — ConfirmDialog shares the
+     * Dialog preset space instead of introducing a parallel one.
+     */
+    preset?: string;
 }
 export { default as ConfirmDialog } from './ConfirmDialog.svelte';

package/dist/primitives/Dialog/Dialog.svelte

@@ -26,6 +26,7 @@
     closeOnBackdropClick = true,
     closeOnEscape = true,
     hideCloseButton = false,
+    draggable = false,
     transitionDuration,
     transitionEasing,
     onClose,
@@ -70,6 +71,64 @@
 
   const structured = $derived(!!title);
 
+  // svelte-ignore state_referenced_locally
+  if (import.meta.env?.DEV && draggable && !title) {
+    console.warn(
+      '[Dialog] `draggable` needs a `title` — the header is the drag handle. Without a title no header renders, so dragging is a no-op.'
+    );
+  }
+
+  // Drag offset from the centred position (px). Only ever non-zero while
+  // `draggable` and the user has grabbed the header. Reset on each open so a
+  // reopened dialog always starts centred.
+  let dragX = $state(0);
+  let dragY = $state(0);
+
+  // Attachment wiring the header as a drag handle. Kept off the markup as an
+  // `{@attach}` (not inline `onpointer*`) so the static `<header>` doesn't trip
+  // the a11y "non-interactive element with handlers needs a role" rule, and so
+  // the listeners tear down cleanly when `draggable` flips off. Pointer capture
+  // keeps the drag alive when the cursor outruns the header; header buttons
+  // (close) are exempted so they still click.
+  function draggableHandle(node: HTMLElement) {
+    node.style.touchAction = 'none';
+    node.style.userSelect = 'none';
+    node.style.cursor = 'move';
+    let dragging = false;
+    let startX = 0;
+    let startY = 0;
+    const onDown = (event: PointerEvent) => {
+      if ((event.target as HTMLElement).closest('button')) return;
+      dragging = true;
+      startX = event.clientX - dragX;
+      startY = event.clientY - dragY;
+      node.setPointerCapture(event.pointerId);
+    };
+    const onMove = (event: PointerEvent) => {
+      if (!dragging) return;
+      dragX = event.clientX - startX;
+      dragY = event.clientY - startY;
+    };
+    const onUp = (event: PointerEvent) => {
+      if (!dragging) return;
+      dragging = false;
+      node.releasePointerCapture(event.pointerId);
+    };
+    node.addEventListener('pointerdown', onDown);
+    node.addEventListener('pointermove', onMove);
+    node.addEventListener('pointerup', onUp);
+    return () => {
+      node.removeEventListener('pointerdown', onDown);
+      node.removeEventListener('pointermove', onMove);
+      node.removeEventListener('pointerup', onUp);
+      // Undo the inline styles too, so toggling `draggable` off at runtime
+      // doesn't leave the header stuck with `cursor: move` / unselectable text.
+      node.style.touchAction = '';
+      node.style.userSelect = '';
+      node.style.cursor = '';
+    };
+  }
+
   const uid = $props.id();
   const titleId = $derived(title ? `dialog-title-${uid}` : undefined);
   const bodyId = `dialog-body-${uid}`;
@@ -124,6 +183,19 @@
     previouslyFocused = null;
   }
 
+  // Reset the drag offset whenever the dialog opens so a reopened dialog always
+  // starts centred — keyed on `open`, not the `open && !isVisible` transition.
+  // Reopening *during* the close outro (isVisible still true) must still recentre;
+  // the old transition-guarded reset silently skipped that case, restoring the
+  // stale drag position. `open` is constant during a drag, so this never fights
+  // the pointer handlers.
+  $effect(() => {
+    if (open) {
+      dragX = 0;
+      dragY = 0;
+    }
+  });
+
   $effect(() => {
     if (open && !isVisible) {
       isVisible = true;
@@ -191,6 +263,7 @@
           : styles.panel({ class: [slotClasses?.panel, className] })}
         data-intent={intent}
         role="document"
+        style:translate={dragX !== 0 || dragY !== 0 ? `${dragX}px ${dragY}px` : undefined}
         transition:scale={{
           duration: motion.enterDuration,
           easing: motion.easing,
@@ -204,6 +277,7 @@
             class={unstyled
               ? (slotClasses?.header ?? '')
               : styles.header({ class: slotClasses?.header })}
+            {@attach draggable ? draggableHandle : undefined}
           >
             <h2
               class={unstyled

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

@@ -27,7 +27,7 @@ import type { DialogSlots, DialogVariants } from './dialog.variants.js';
  * </Dialog>
  * ```
  */
-export interface DialogProps extends Omit<HTMLDialogAttributes, 'children' | 'open'> {
+export interface DialogProps extends Omit<HTMLDialogAttributes, 'children' | 'open' | 'draggable'> {
     /** Controls whether the dialog is visible. Supports bind:open. */
     open?: boolean;
     /** Dialog body content. When `title` is omitted the content fills the entire panel. */
@@ -52,6 +52,17 @@ export interface DialogProps extends Omit<HTMLDialogAttributes, 'children' | 'op
     closeOnBackdropClick?: boolean;
     /** Whether pressing Escape dismisses the dialog. @default true */
     closeOnEscape?: boolean;
+    /**
+     * Let the user reposition the dialog by dragging its header. Off by default.
+     * The structured header (rendered when `title` is set) becomes the drag
+     * handle; the close button and any header controls stay clickable, and the
+     * offset resets each time the dialog reopens. Most useful for a dialog the
+     * user may want to shove aside to see the content behind it. Requires a
+     * `title` — without a header there is nothing to grab. Overrides the native
+     * HTML `draggable` attribute, which has no meaningful use on a dialog.
+     * @default false
+     */
+    draggable?: boolean;
     /**
      * Hides the built-in close button. Only takes effect when `title` is
      * also set — the close button only renders in the structured (titled)

package/dist/primitives/Drawer/Drawer.svelte

@@ -23,6 +23,7 @@
     placement = 'right',
     size = 'md',
     intent = 'neutral',
+    accentEdge = false,
     onClose,
     hideCloseButton = false,
     closeOnBackdropClick = true,
@@ -65,7 +66,7 @@
   const bodyId = `drawer-body-${uid}`;
   const overlayId = `drawer-${uid}`;
 
-  const variantProps: DrawerVariants = $derived({ placement, size, intent });
+  const variantProps: DrawerVariants = $derived({ placement, size, intent, accentEdge });
   const styles = $derived(drawerVariants(variantProps));
   const slotClasses = $derived(
     resolveSlotClasses(blocksConfig, 'Drawer', preset, variantProps, slotClassesProp)

package/dist/primitives/Drawer/drawer.variants.d.ts

@@ -3,11 +3,13 @@ export declare const drawerVariants: ((props?: {
     placement?: "top" | "right" | "bottom" | "left" | undefined;
     size?: "sm" | "md" | "lg" | "xl" | "full" | undefined;
     intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
+    accentEdge?: boolean | undefined;
 } | undefined) => {
     dialog: (props?: ({
         placement?: "top" | "right" | "bottom" | "left" | undefined;
         size?: "sm" | "md" | "lg" | "xl" | "full" | undefined;
         intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
+        accentEdge?: boolean | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
@@ -15,6 +17,7 @@ export declare const drawerVariants: ((props?: {
         placement?: "top" | "right" | "bottom" | "left" | undefined;
         size?: "sm" | "md" | "lg" | "xl" | "full" | undefined;
         intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
+        accentEdge?: boolean | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
@@ -22,6 +25,7 @@ export declare const drawerVariants: ((props?: {
         placement?: "top" | "right" | "bottom" | "left" | undefined;
         size?: "sm" | "md" | "lg" | "xl" | "full" | undefined;
         intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
+        accentEdge?: boolean | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
@@ -29,6 +33,7 @@ export declare const drawerVariants: ((props?: {
         placement?: "top" | "right" | "bottom" | "left" | undefined;
         size?: "sm" | "md" | "lg" | "xl" | "full" | undefined;
         intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
+        accentEdge?: boolean | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
@@ -36,6 +41,7 @@ export declare const drawerVariants: ((props?: {
         placement?: "top" | "right" | "bottom" | "left" | undefined;
         size?: "sm" | "md" | "lg" | "xl" | "full" | undefined;
         intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
+        accentEdge?: boolean | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
@@ -43,6 +49,7 @@ export declare const drawerVariants: ((props?: {
         placement?: "top" | "right" | "bottom" | "left" | undefined;
         size?: "sm" | "md" | "lg" | "xl" | "full" | undefined;
         intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
+        accentEdge?: boolean | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
@@ -50,6 +57,7 @@ export declare const drawerVariants: ((props?: {
         placement?: "top" | "right" | "bottom" | "left" | undefined;
         size?: "sm" | "md" | "lg" | "xl" | "full" | undefined;
         intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
+        accentEdge?: boolean | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;

package/dist/primitives/Drawer/drawer.variants.js

@@ -53,13 +53,24 @@ export const drawerVariants = tv({
             xl: {},
             full: {}
         },
+        // Semantic purpose. By default the Drawer paints no accent (symmetry with
+        // Dialog — intent is surfaced only as `data-intent` for consumer hooks).
+        // Each value additionally parks its colour in `--drawer-accent`, consumed
+        // *only* when `accentEdge` is on (see the accentEdge×placement compounds).
         intent: {
-            neutral: {},
-            primary: {},
-            secondary: {},
-            success: {},
-            warning: {},
-            danger: {}
+            neutral: { panel: '[--drawer-accent:var(--color-border-strong)]' },
+            primary: { panel: '[--drawer-accent:var(--color-primary)]' },
+            secondary: { panel: '[--drawer-accent:var(--color-secondary)]' },
+            success: { panel: '[--drawer-accent:var(--color-success)]' },
+            warning: { panel: '[--drawer-accent:var(--color-warning)]' },
+            danger: { panel: '[--drawer-accent:var(--color-danger)]' }
+        },
+        // Opt-in edge accent (DRW-1 completion). Off by default so the Drawer keeps
+        // Dialog symmetry; on, the docked (viewport-facing) edge is thickened to 2px
+        // and tinted in the intent colour via the placement compounds below.
+        accentEdge: {
+            true: {},
+            false: {}
         }
     },
     compoundVariants: [
@@ -84,13 +95,37 @@ export const drawerVariants = tv({
         { placement: 'bottom', size: 'md', class: { panel: 'h-72' } },
         { placement: 'bottom', size: 'lg', class: { panel: 'h-96' } },
         { placement: 'bottom', size: 'xl', class: { panel: 'h-[32rem]' } },
-        { placement: 'bottom', size: 'full', class: { panel: 'h-full' } }
-        // Intent accent borders removed — for symmetry with Dialog.
-        // Intent is conveyed at the call site via icon + heading color.
+        { placement: 'bottom', size: 'full', class: { panel: 'h-full' } },
+        // Edge accent (opt-in via `accentEdge`). The tinted 2px border lands on the
+        // *inner* edge — the one facing the viewport — so it reads as a coloured seam
+        // between the drawer and the page, never a floating outline. Placement picks
+        // the physical side; the colour comes from `--drawer-accent` (intent axis).
+        // Default (no accentEdge) leaves the panel exactly as before — Dialog symmetry.
+        {
+            accentEdge: true,
+            placement: 'left',
+            class: { panel: 'border-r-2 [border-right-color:var(--drawer-accent)]' }
+        },
+        {
+            accentEdge: true,
+            placement: 'right',
+            class: { panel: 'border-l-2 [border-left-color:var(--drawer-accent)]' }
+        },
+        {
+            accentEdge: true,
+            placement: 'top',
+            class: { panel: 'border-b-2 [border-bottom-color:var(--drawer-accent)]' }
+        },
+        {
+            accentEdge: true,
+            placement: 'bottom',
+            class: { panel: 'border-t-2 [border-top-color:var(--drawer-accent)]' }
+        }
     ],
     defaultVariants: {
         placement: 'right',
         size: 'md',
-        intent: 'neutral'
+        intent: 'neutral',
+        accentEdge: false
     }
 });

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

@@ -37,13 +37,22 @@ export interface DrawerProps extends Omit<HTMLDialogAttributes, 'children' | 'op
     /** Width (for left/right) or height (for top/bottom) of the drawer panel. @default 'md' */
     size?: DrawerVariants['size'];
     /**
-     * Semantic purpose marker (mirrors Dialog). After the Lighter-Refactor,
-     * the Drawer itself no longer paints an accent border — the value is
-     * exposed on the panel as `data-intent="…"` so consumers can hook
-     * presets, CSS overrides, or icon/title color via their own snippets.
+     * Semantic purpose marker (mirrors Dialog). By default the Drawer paints no
+     * accent border — the value is exposed on the panel as `data-intent="…"` so
+     * consumers can hook presets, CSS overrides, or icon/title color via their own
+     * snippets. Set {@link accentEdge} to also tint the docked edge in this colour.
      * @default 'neutral'
      */
     intent?: DrawerVariants['intent'];
+    /**
+     * Tint the panel's docked (viewport-facing) edge with a 2px accent border in
+     * the {@link intent} colour — `border-right` for `left`, `border-left` for
+     * `right`, `border-bottom` for `top`, `border-top` for `bottom`. Off by
+     * default, keeping symmetry with Dialog; opt in for a coloured seam that ties
+     * the drawer to a semantic purpose (e.g. a `danger` confirm drawer).
+     * @default false
+     */
+    accentEdge?: DrawerVariants['accentEdge'];
     /** Fires when the drawer is dismissed via Escape, backdrop click, or close button. */
     onClose?: () => void;
     /** Hides the built-in close button in the header. @default false */

package/dist/primitives/FormField/FormField.svelte

@@ -4,7 +4,7 @@
 
   let {
     label,
-    hint,
+    helper,
     error,
     required = false,
     disabled = false,
@@ -20,7 +20,7 @@
   // `useFormField` / XC-2 for the contract.
   const ff = useFormField(() => ({
     fieldId: idProp ?? `field-${propsId}`,
-    hint,
+    helper,
     error,
     required,
     disabled
@@ -59,12 +59,12 @@
     >
       {error}
     </div>
-  {:else if ff.hintId}
+  {:else if ff.helperId}
     <div
-      id={ff.hintId}
-      class={['text-text-tertiary text-xs', slotClasses.hint].filter(Boolean).join(' ')}
+      id={ff.helperId}
+      class={['text-text-tertiary text-xs', slotClasses.helper].filter(Boolean).join(' ')}
     >
-      {hint}
+      {helper}
     </div>
   {/if}
 </div>

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

@@ -17,7 +17,7 @@ import type { HTMLAttributes } from 'svelte/elements';
  *
  * @example
  * ```svelte
- * <FormField label="Document" required error={fileError} hint="PDF, JPG, PNG — max 10 MB">
+ * <FormField label="Document" required error={fileError} helper="PDF, JPG, PNG — max 10 MB">
  *   {#snippet children({ id, describedBy, invalid })}
  *     <FileUpload {id} aria-describedby={describedBy} aria-invalid={invalid} bind:files />
  *   {/snippet}
@@ -27,8 +27,12 @@ import type { HTMLAttributes } from 'svelte/elements';
 export interface FormFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
     /** Label rendered above the control. Auto-linked to the slot via the generated `id`. */
     label?: string;
-    /** Helper text shown below the control. Hidden when `error` is present. */
-    hint?: string;
+    /**
+     * Helper text shown below the control. Hidden when `error` is present.
+     * Named `helper` to match the built-in helper prop of the form primitives
+     * (Input, Select, Toggle, …) — one vocabulary across the API seam.
+     */
+    helper?: string;
     /**
      * Error message shown below the control. Replaces the helper text and
      * propagates `invalid: true` to the slot for ARIA wiring.
@@ -54,8 +58,13 @@ export interface FormFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'ch
     class?: string;
     /**
      * Per-slot class overrides.
+     *
+     * FormField has no `tv()` config (it is a bare layout wrapper), so this
+     * key union is a hand-maintained literal instead of the usual
+     * `SlotNames<typeof xVariants>` derivation — keep it in sync with the
+     * elements rendered in `FormField.svelte`.
      */
-    slotClasses?: Partial<Record<'wrapper' | 'label' | 'message' | 'hint', string>>;
+    slotClasses?: Partial<Record<'wrapper' | 'label' | 'message' | 'helper', string>>;
     /**
      * Snippet receiving wiring metadata (`id`, `describedBy`, `invalid`,
      * `required`, `disabled`). The wrapped control should spread or apply

package/dist/primitives/Input/Input.svelte

@@ -42,6 +42,7 @@
     persistDebounceMs = 300,
     persistVersion = 1,
     persistNamespace,
+    onkeydown: userOnKeydown,
     ...restProps
   }: InputProps = $props();
 
@@ -119,7 +120,7 @@
   const propsId = $props.id();
   const ff = useFormField(() => ({
     fieldId: `input-${propsId}`,
-    hint: helper,
+    helper,
     error,
     required,
     disabled
@@ -147,11 +148,14 @@
     if (!disabled && onRightIconClick) onRightIconClick();
   }
 
-  function handleKeydown(event: KeyboardEvent) {
+  function handleKeydown(event: KeyboardEvent & { currentTarget: EventTarget & HTMLInputElement }) {
     if (event.key === 'Escape' && shouldShowClear) {
       event.preventDefault();
       handleClear();
     }
+    // Forward the consumer's onkeydown (NumberInput's Arrow-step, etc.) — Input's
+    // own handler is hardcoded on the element, so without this it would swallow it.
+    userOnKeydown?.(event);
   }
 
   $effect(() => {
@@ -280,9 +284,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/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 /