@urbicon-ui/blocks 6.21.0 → 6.21.2

package/dist/primitives/Drawer/Drawer.svelte

@@ -3,14 +3,9 @@
   import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { resolveIcon } from '../../icons';
   import CloseIconDefault from '../../icons/CloseIcon.svelte';
-  import { onDestroy } from 'svelte';
+  import { onDestroy, tick } from 'svelte';
   import { fade, fly } from 'svelte/transition';
-  import {
-    trapFocus,
-    showDialogModal,
-    closeDialogModal,
-    unlockBodyScroll
-  } from '../../utils/overlay';
+  import { trapFocus, showDialogModal, closeDialogModal } from '../../utils/overlay';
   import { overlayStack, getOverlayMotion } from '../../utils';
   import Button from '../Button/Button.svelte';
   import type { DrawerProps } from './index';
@@ -28,6 +23,7 @@
     placement = 'right',
     size = 'md',
     intent = 'neutral',
+    accentEdge = false,
     onClose,
     hideCloseButton = false,
     closeOnBackdropClick = true,
@@ -61,13 +57,16 @@
   let panelElement = $state<HTMLElement>();
   let isVisible = $state(false);
   let previouslyFocused: HTMLElement | null = null;
+  // Release for the body-scroll lock this instance holds while modal — set by
+  // showDialogModal, idempotent, so both teardown paths below may call it.
+  let releaseScrollLock: (() => void) | undefined;
 
   const uid = $props.id();
   const titleId = $derived(title ? `drawer-title-${uid}` : undefined);
   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)
@@ -122,7 +121,15 @@
     if (open && !isVisible) {
       isVisible = true;
       previouslyFocused = document.activeElement as HTMLElement;
-      showDialogModal(dialogElement, panelElement);
+      // Defer until the `{#if isVisible}` block has rendered so `bind:this` has
+      // assigned dialogElement/panelElement — showDialogModal captures the refs
+      // by value, so promoting before the bind would silently no-op (never modal).
+      // The guard covers same-flush teardown: if the component unmounts before
+      // the tick resolves, bind:this has nulled dialogElement and onDestroy has
+      // already run — a lock taken now could never be released.
+      tick().then(() => {
+        if (dialogElement) releaseScrollLock = showDialogModal(dialogElement, panelElement);
+      });
     }
   });
 
@@ -132,7 +139,11 @@
   });
 
   onDestroy(() => {
-    unlockBodyScroll();
+    // Safety net for destroy-while-open, where no outro runs. Releasing is
+    // idempotent and scoped to this instance's own lock, so a regular close
+    // (already released in handleOutroEnd) or a never-opened instance make
+    // this a no-op — it can never free another overlay's lock.
+    releaseScrollLock?.();
   });
 
   function handleBackdropDirectClick() {
@@ -149,7 +160,8 @@
   }
 
   function handleOutroEnd() {
-    closeDialogModal(dialogElement, previouslyFocused);
+    closeDialogModal(dialogElement, previouslyFocused, releaseScrollLock);
+    releaseScrollLock = undefined;
     isVisible = false;
     previouslyFocused = null;
   }

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

@@ -1,95 +1,68 @@
 import { type SlotNames, type VariantProps } from '../../utils/variants.js';
-export declare const drawerVariants: (props?: import("../../utils/variants.js").TVProps<{
-    placement: {
-        left: {
-            dialog: string;
-            panel: string;
-        };
-        right: {
-            dialog: string;
-            panel: string;
-        };
-        top: {
-            dialog: string;
-            panel: string;
-        };
-        bottom: {
-            dialog: string;
-            panel: string;
-        };
-    };
-    size: {
-        sm: {};
-        md: {};
-        lg: {};
-        xl: {};
-        full: {};
-    };
-    intent: {
-        neutral: {};
-        primary: {};
-        secondary: {};
-        success: {};
-        warning: {};
-        danger: {};
-    };
-}> | undefined) => {
+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 | 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;
+        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;
     backdrop: (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 | 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;
+        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;
     panel: (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 | 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;
+        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;
     header: (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 | 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;
+        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;
     title: (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 | 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;
+        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;
     body: (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 | 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;
+        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;
     footer: (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 | 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;
+        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;
+}) & {
+    readonly config: import("../../utils/variants.js").TVConfig;
 };
 export type DrawerVariants = VariantProps<typeof drawerVariants>;
 /** Slot names derived from the `tv()` config above — single source of truth for `slotClasses`. */

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 })}