@urbicon-ui/blocks 6.23.0 → 6.25.0

package/dist/primitives/Toast/Toaster.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { useBlocksI18n } from '../..';
+  import { untrack } from 'svelte';
   import { fly } from 'svelte/transition';
   import { getOverlayMotion } from '../../utils';
   import { toastVariants, type ToastVariants } from './toast.variants';
@@ -88,6 +89,42 @@
 
   const visibleToasts = $derived(toaster.toasts.slice(-max));
 
+  // Stranded-pause guard. A toast removed from under the cursor (e.g. its own
+  // close button) does not reliably fire `pointerout`, so `pointerInside` can
+  // stay stuck `true` and freeze every remaining timer — worst case a fresh
+  // toast is then born paused and never counts down. Rather than trust the flag,
+  // when the rendered stack SHRINKS we re-derive containment from the real cursor
+  // position. The cursor is tracked from the region's own bubbling pointer events
+  // (the container is `pointer-events-none`, so these fire only over a toast
+  // child, which is exactly when the coords matter).
+  let containerEl: HTMLElement | undefined;
+  let pointerX = 0;
+  let pointerY = 0;
+  let prevVisibleCount = 0;
+
+  function reconcilePointerInside() {
+    // Only a stranded `true` needs rescuing; SSR-safe — effects/handlers never
+    // run on the server, and `document` is guarded regardless.
+    if (typeof document === 'undefined' || !pointerInside || !containerEl) return;
+    const hit = document.elementFromPoint(pointerX, pointerY);
+    const toastEl = (hit?.closest('[data-toast-id]') ?? null) as HTMLElement | null;
+    // Inside only if the cursor sits over a toast that is (a) in THIS region and
+    // (b) still live — not the just-removed one, whose node lingers through its
+    // fly-out outro.
+    pointerInside =
+      !!toastEl &&
+      containerEl.contains(toastEl) &&
+      visibleToasts.some((t) => t.id === toastEl.dataset.toastId);
+  }
+
+  $effect(() => {
+    const count = visibleToasts.length;
+    untrack(() => {
+      if (count < prevVisibleCount) reconcilePointerInside();
+      prevVisibleCount = count;
+    });
+  });
+
   const styles = $derived(
     unstyled
       ? {
@@ -151,10 +188,19 @@
 </script>
 
 <div
+  bind:this={containerEl}
   class={[slot('container'), className].filter(Boolean).join(' ')}
   aria-live="polite"
   aria-relevant="additions removals"
-  onpointerover={() => (pointerInside = true)}
+  onpointerover={(e) => {
+    pointerX = e.clientX;
+    pointerY = e.clientY;
+    pointerInside = true;
+  }}
+  onpointermove={(e) => {
+    pointerX = e.clientX;
+    pointerY = e.clientY;
+  }}
   onpointerout={(e) => {
     if (leftRegion(e)) pointerInside = false;
   }}
@@ -166,7 +212,13 @@
 >
   {#each visibleToasts as toast (toast.id)}
     {@const IntentIcon = INTENT_ICON_MAP[toast.intent] ?? INTENT_ICON_MAP.neutral}
-    <div class={slot('toast', toast.intent)} role="alert" transition:fly={flyParams()}>
+    <div
+      class={slot('toast', toast.intent)}
+      role="alert"
+      aria-atomic="true"
+      data-toast-id={toast.id}
+      transition:fly={flyParams()}
+    >
       {#if toast.loading}
         <span class={slot('icon', toast.intent)}><Spinner size="sm" /></span>
       {:else}
@@ -216,13 +268,17 @@
       {/if}
 
       {#if toast.showProgress && Number.isFinite(toast.duration) && toast.duration > 0}
-        <!-- Duration comes from the toast itself (the real countdown), not a token.
-             `animation-play-state` tracks the store's paused flag so the bar freezes
-             with the timer on hover/focus and resumes in place — changing only the
+        <!-- The countdown animation lives in the `<style>` rule below (not inline)
+             so `@media (prefers-reduced-motion: reduce)` can reach it — an inline
+             `animation` shorthand is invisible to media queries. Only the real
+             per-toast duration is passed inline, as a custom property.
+             `animation-play-state` (also inline, bound to the store's paused flag)
+             freezes the bar with the timer on hover/focus and resumes it in place;
+             inline wins over the rule's implicit `running`, and toggling only the
              play-state never restarts the animation. -->
         <div
-          class={slot('progress', toast.intent)}
-          style="animation: blocks-toast-progress {toast.duration}ms linear forwards; animation-play-state: {toaster.paused
+          class={[slot('progress', toast.intent), 'blocks-toast-progress-bar']}
+          style="--toast-progress-duration: {toast.duration}ms; animation-play-state: {toaster.paused
             ? 'paused'
             : 'running'};"
         ></div>
@@ -240,4 +296,22 @@
       width: 0%;
     }
   }
+
+  /* The countdown bar animates via this class (not an inline `animation`) so the
+     reduced-motion query below can reach it; the per-toast duration arrives as
+     the `--toast-progress-duration` custom property. `:global` keeps it off
+     Svelte's scoping, consistent with the global keyframe above. */
+  :global(.blocks-toast-progress-bar) {
+    animation: blocks-toast-progress var(--toast-progress-duration) linear forwards;
+  }
+
+  /* A countdown bar carries no information once it can't animate, so under
+     reduced motion we hide it outright rather than leave it frozen. This mirrors
+     interaction.css collapsing the motion tokens; the auto-dismiss timing itself
+     is unaffected. */
+  @media (prefers-reduced-motion: reduce) {
+    :global(.blocks-toast-progress-bar) {
+      display: none;
+    }
+  }
 </style>

package/dist/primitives/Toggle/Toggle.svelte

@@ -29,6 +29,7 @@
     preset,
     withBorder = false,
     'aria-describedby': ariaDescribedby,
+    'aria-label': ariaLabel,
     ...restProps
   }: ToggleProps = $props();
 
@@ -110,7 +111,11 @@
       : styles.control({ class: slotClasses?.control })}
     for={ff.fieldId}
   >
+    <!-- aria-label: a visible `label` wins (stays undefined); with no label a
+         consumer-supplied aria-label is preferred over the generic i18n fallback
+         so external labelling survives the restProps-first spread. -->
     <input
+      {...restProps}
       id={ff.fieldId}
       type="checkbox"
       role="switch"
@@ -121,11 +126,10 @@
       {required}
       class="peer sr-only"
       aria-checked={checked}
-      aria-label={label ? undefined : bt('accessibility.toggle') || 'Toggle'}
+      aria-label={label ? undefined : (ariaLabel ?? (bt('accessibility.toggle') || 'Toggle'))}
       aria-describedby={describedBy}
       aria-invalid={ff.invalid ? 'true' : undefined}
       onchange={handleChange}
-      {...restProps}
     />
 
     <span

package/dist/primitives/Tooltip/tooltip.variants.js

@@ -26,7 +26,16 @@ export const tooltipVariants = tv({
             // guards the inline-override path (an inline duration bypasses the token that
             // reduced-motion collapses to 1ms). The default easing token resolves to
             // Tailwind's implicit transition curve, so the resting fade is unchanged.
-            'transition-opacity duration-[var(--blocks-tooltip-duration)] ease-[var(--blocks-tooltip-easing)]',
+            //
+            // display/overlay + `transition-discrete` and the `starting:` before-state
+            // are what make the fade actually PLAY in top-layer mode (same mechanism
+            // as popoverMotion): without them, showPopover() reveals the chip with no
+            // before-state (enter pops to opacity 1) and hidePopover() yanks it to
+            // display:none in the same recalc (exit never paints). Verified 2026-07-14
+            // — the original transition-opacity fade only ever ran in the rare
+            // in-dialog fallback, where visibility is purely opacity-driven.
+            'transition-[opacity,display,overlay] transition-discrete',
+            'duration-[var(--blocks-tooltip-duration)] ease-[var(--blocks-tooltip-easing)]',
             'motion-reduce:duration-[1ms]',
             'bg-surface-inverted text-text-inverted'
         ],
@@ -34,7 +43,9 @@ export const tooltipVariants = tv({
     },
     variants: {
         open: {
-            true: { base: 'opacity-100' },
+            // `starting:` supplies the @starting-style before-state for the frame
+            // showPopover() first renders the chip — the enter half of the fade.
+            true: { base: 'opacity-100 starting:opacity-0' },
             false: { base: 'opacity-0' }
         },
         intent: {

package/dist/style/foundation.css

@@ -53,10 +53,19 @@
   --color-warm-neutral-950: oklch(0.12 0.006 45);
 
   /* Darkened *-500 / *-600 / *-700 so text-on-primary (white) passes WCAG
-     AA (4.5:1) on the solid intent backgrounds. Previous values had
+     AA (4.5:1) on the solid intent backgrounds **in light mode**, where
+     --color-<intent> resolves to the -500/-600 shades. Previous values had
      L=0.65 which produced ~3:1 contrast — below AA. Warning keeps its
      yellow hue at L=0.75 because it pairs with text-on-surface (dark),
-     not white. */
+     not white.
+
+     Scope, measured (contrast.test.ts, 2026-07-14): this holds for light
+     mode only. In dark mode --color-<intent> resolves to the *lighter*
+     -400/-300/-200 shades while --color-text-on-primary stays white, so
+     every filled intent lands at 1.5–4.1:1. That is a semantic.css issue
+     (text-on-primary is not mode-aware), not something these ramps can fix
+     — see the KNOWN SHORTFALLS block in contrast.test.ts. Do not "fix" it
+     by lightening these ramps; that would break light mode instead. */
   --color-success-50: oklch(0.95 0.03 140);
   --color-success-100: oklch(0.9 0.05 140);
   --color-success-200: oklch(0.82 0.08 140);
@@ -101,13 +110,31 @@
   --color-info-200: oklch(0.84 0.075 220);
   --color-info-300: oklch(0.76 0.105 220);
   --color-info-400: oklch(0.66 0.13 220);
-  --color-info-500: oklch(0.55 0.14 220);
+  /* L=0.54, not 0.55: hue 220 is luminous enough that 0.55 measures 4.41:1
+     against text-on-primary (white) — below AA, despite the promise above.
+     0.54 is the smallest step that clears it (4.58:1) and keeps the ramp's
+     0.12 step down from info-400. Guarded by contrast.test.ts. */
+  --color-info-500: oklch(0.54 0.14 220);
   --color-info-600: oklch(0.48 0.13 220);
   --color-info-700: oklch(0.4 0.11 220);
   --color-info-800: oklch(0.32 0.09 220);
   --color-info-900: oklch(0.24 0.07 220);
   --color-info-950: oklch(0.16 0.05 220);
 
+  /* Sub-xs Type Scale — extends Tailwind's own `--text-*` namespace downwards.
+     Tailwind bottoms out at --text-xs (12px), but dense data marks (chart axis
+     labels, mini-calendar day cells, kbd hints) need 10–11px. Defining them here
+     rather than hardcoding `text-[11px]` at the call site is what makes those
+     sizes reachable by a consumer's own @theme override.
+
+     Deliberately size-only: NO paired `--text-*--line-height`. Tailwind emits
+     `line-height` for a scale entry only when the paired key exists, so adding
+     one would inject a line-height into every call site that today inherits it
+     from the cascade — a rendering change, not a refactor. Consumers who want
+     one can add the paired key in their own @theme; the utility picks it up. */
+  --text-2xs: 0.6875rem;
+  --text-3xs: 0.625rem;
+
   /* Border Radius Scale — physical sizes */
   --radius-xs: 0.125rem;
   --radius-sm: 0.25rem;

package/dist/style/interaction.css

@@ -98,8 +98,8 @@
      transitions, so they read these through the JS mirror in
      `utils/overlay-tokens.ts` (`getOverlayMotion`) — Svelte transitions need
      numeric input. Tooltip runs a deliberately faster CSS opacity fade off its
-     own `--blocks-tooltip-*` tokens below; Popover has no enter/exit motion yet
-     (ACC-3 follow-up).
+     own `--blocks-tooltip-*` tokens below; Popover (and Menu through it) runs a
+     CSS-native fade/scale off the `--blocks-popover-*` tokens below.
 
      Override globally with a `BlocksProvider` style block, or per instance via
      the component's `transitionDuration` / `transitionEasing` props.
@@ -130,6 +130,23 @@
   --blocks-tooltip-duration: var(--blocks-duration-fast);
   --blocks-tooltip-easing: var(--blocks-ease-confident);
 
+  /* === POPOVER MOTION TOKENS (ACC-3 rest) ===
+     The CSS-native enter/exit fade+scale for Popover (and Menu, which passes
+     the same motion fragment to its inner Popover). Anchored panels should
+     feel snappier than the 200ms modal overlays but calmer than an instant
+     toggle, so they share the tooltip's `fast`/`confident` pairing. Enter is
+     driven by `@starting-style` (the panel un-hides via `showPopover()`, so a
+     plain transition has no before-state); exit relies on
+     `transition-behavior: allow-discrete` on `display`/`overlay` to keep the
+     panel painted in the top layer while it fades. Both default through
+     `--blocks-duration-fast`, so `prefers-reduced-motion` below collapses them
+     to 1ms for free. Override globally here, or per instance via Popover's
+     `transitionDuration` / `transitionEasing` props (which set these inline +
+     carry a `motion-reduce` guard, since an inline duration can't see the
+     media query). */
+  --blocks-popover-duration: var(--blocks-duration-fast);
+  --blocks-popover-easing: var(--blocks-ease-confident);
+
   /* === COLLAPSE ANIMATION TOKENS (ACC-3) ===
      The CSS-driven grid-template-rows collapse shared by Accordion +
      Collapsible (and their chevron spin). Default to the normal/smooth

package/dist/style/semantic.css

@@ -54,8 +54,31 @@
   --color-text-tertiary: light-dark(var(--color-neutral-600), var(--color-neutral-300));
   --color-text-quaternary: light-dark(var(--color-neutral-500), var(--color-neutral-400));
   --color-text-disabled: light-dark(var(--color-neutral-300), var(--color-neutral-600));
+  /* The two on-colors below pair text with a *fill* rather than a surface.
+     Their fills are dark in light mode and light in dark mode, so the label
+     has to travel the opposite way — white, then near-black. They are
+     deliberately NOT aliased to one another (`text-on-primary: var(
+     --color-text-on-dark)`), even though they carry the same value today —
+     they answer to different fills and must stay independently overridable:
+
+       - text-on-dark is the partner of the avatar identity palette, whose 12
+         slots hold ONE lightness per mode (0.45 / 0.72) by construction.
+       - text-on-primary is the partner of the intent fills, whose ramps every
+         theme re-tunes, and which move again on hover/active.
+
+     Aliasing would couple them asymmetrically: a consumer re-tuning the avatar
+     palette's on-color would silently repaint every filled Button/Badge label.
+     Their equality is a consequence of both fill families straddling the same
+     lightness midpoint — not a definition. */
   --color-text-on-dark: light-dark(var(--color-neutral-0), var(--color-neutral-900));
-  --color-text-on-primary: var(--color-neutral-0);
+  /* Dark mode pairs the *lighter* -400/-500 intent fills with dark text (the
+     Material-3 `onPrimary` pattern). White here was unconditional until
+     2026-07-14, which put 125 of the 126 dark-mode intent fills under WCAG AA
+     — down to 1.51:1, and getting *worse* on press. The mode-aware branch
+     clears all 108 fills this token governs; `warning` is not one of them (it
+     pairs with text-on-surface and is still under AA in dark mode — see the
+     KNOWN SHORTFALLS block in style/contrast.test.ts, which guards all of it). */
+  --color-text-on-primary: light-dark(var(--color-neutral-0), var(--color-neutral-900));
   --color-text-on-surface: light-dark(var(--color-neutral-900), var(--color-neutral-100));
 
   /* === PRIMARY INTENT ===
@@ -152,6 +175,54 @@
   --color-chart-5: light-dark(var(--color-info-500), var(--color-info-400));
   --color-chart-6: light-dark(var(--color-danger-500), var(--color-danger-400));
 
+  /* === AVATAR IDENTITY PALETTE ===
+     An *unordered* identity palette: Avatar's `randomColor` hashes a name to a
+     fixed slot, so the same person always keeps the same hue. Deliberately NOT
+     the chart palette and NOT the intent tokens:
+
+       - chart-* only has 6 slots and derives from the intent ramps, so a brand
+         that retunes `secondary` would silently reshuffle people's identities.
+         Its dark values are the *-400 tints (L≈0.66) — light enough that white
+         initials drop to ~2.6:1, below AA. Charts colour marks; avatars carry
+         text on top, which is a different contrast contract.
+       - intent tokens are semantic (a person is not "danger").
+
+     Construction: a single lightness per mode, 12 hues at an even 30° spacing.
+     Because OKLCH lightness is perceptual, holding L constant means every slot
+     shares one guaranteed contrast partner — `--color-text-on-dark`, which
+     flips white → neutral-900 with the mode exactly as these fills flip dark →
+     light. So legibility is a property of the construction, not 12 separate
+     checks. Even spacing also beats the 15 hardcoded hex values this replaced,
+     which clustered (red/orange/amber/yellow within ~20°) and blurred when
+     avatars sat side by side.
+
+     L=0.45 (light) / L=0.72 (dark) mirror the foundation ramps' *-700 / *-300
+     steps, so the palette reads as part of the same chassis. Rebrand by
+     overriding these 12 tokens; the text partner follows automatically. */
+  --color-avatar-1: light-dark(oklch(0.45 0.13 25), oklch(0.72 0.12 25));
+  --color-avatar-2: light-dark(oklch(0.45 0.13 55), oklch(0.72 0.12 55));
+  --color-avatar-3: light-dark(oklch(0.45 0.13 85), oklch(0.72 0.12 85));
+  --color-avatar-4: light-dark(oklch(0.45 0.13 115), oklch(0.72 0.12 115));
+  --color-avatar-5: light-dark(oklch(0.45 0.13 145), oklch(0.72 0.12 145));
+  --color-avatar-6: light-dark(oklch(0.45 0.13 175), oklch(0.72 0.12 175));
+  --color-avatar-7: light-dark(oklch(0.45 0.13 205), oklch(0.72 0.12 205));
+  --color-avatar-8: light-dark(oklch(0.45 0.13 235), oklch(0.72 0.12 235));
+  --color-avatar-9: light-dark(oklch(0.45 0.13 265), oklch(0.72 0.12 265));
+  --color-avatar-10: light-dark(oklch(0.45 0.13 295), oklch(0.72 0.12 295));
+  --color-avatar-11: light-dark(oklch(0.45 0.13 325), oklch(0.72 0.12 325));
+  --color-avatar-12: light-dark(oklch(0.45 0.13 355), oklch(0.72 0.12 355));
+
+  /* === LIVE / "NOW" ACCENT ===
+     Single-purpose accent for live/now markers — the Calendar current-time
+     line and dot, and future live/recording indicators. Red is the
+     convention (Google Calendar et al.), but the *purpose* is not `danger`:
+     a now-line states "you are here", not "something is wrong", and the two
+     must stay independently themeable. Defaults ride the danger foundation
+     ramp, so dark mode and per-theme danger re-tunes flow through
+     automatically; override `--color-live` alone to restyle live indicators
+     without touching error styling. */
+  --color-live: light-dark(var(--color-danger-500), var(--color-danger-400));
+
   /* === BORDERS ===
      border-hairline is the quietest tier — structural
      trennlinien (row dividers, Card header/footer separators, inline

package/dist/style/themes/neutral.css

@@ -17,7 +17,16 @@
   --color-primary-200: oklch(0.84 0.008 240);
   --color-primary-300: oklch(0.76 0.01 240);
   --color-primary-400: oklch(0.65 0.012 240);
-  --color-primary-500: oklch(0.53 0.012 240);
+  /* L 0.58, not the 0.53 this ramp's spacing would suggest: primary-500 is the
+     dark-mode `--color-primary` fill, and dark mode carries dark text on it
+     (`--color-text-on-primary`). At 0.53 this grey measured 3.74:1 against
+     neutral-900 — the one intent fill in the whole system that missed AA after
+     the on-color became mode-aware, because a desaturated mid-grey is the
+     hardest case: no lightness clears AA against BOTH white and neutral-900
+     (proved in style/contrast.test.ts). 0.58 is the lowest step on this
+     ramp's 0.01 grid that clears it (4.59:1; the true crossing is 0.574 =
+     4.50:1, i.e. no margin at all). Monotonicity holds (0.65 > 0.58 > 0.43). */
+  --color-primary-500: oklch(0.58 0.012 240);
   --color-primary-600: oklch(0.43 0.012 240);
   --color-primary-700: oklch(0.36 0.01 240);
   --color-primary-800: oklch(0.29 0.008 240);

package/dist/style/themes/ocean.css

@@ -26,7 +26,11 @@
   --color-secondary-200: oklch(0.82 0.08 190);
   --color-secondary-300: oklch(0.74 0.11 190);
   --color-secondary-400: oklch(0.66 0.13 190);
-  --color-secondary-500: oklch(0.55 0.12 190);
+  /* L=0.54, not the foundation ramp's 0.55: at hue 190 (teal) the same
+     lightness measures 4.39:1 against text-on-primary (white) — below AA.
+     Lightness is not contrast-neutral across hues in OKLCH. Guarded by
+     contrast.test.ts. */
+  --color-secondary-500: oklch(0.54 0.12 190);
   --color-secondary-600: oklch(0.48 0.12 190);
   --color-secondary-700: oklch(0.4 0.1 190);
   --color-secondary-800: oklch(0.32 0.08 190);

package/dist/utils/compose-handlers.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `composeHandlers` — run a component's own DOM event handler *and* a
+ * consumer-supplied one that arrived through `restProps`.
+ *
+ * ## Why this exists
+ *
+ * The library's `restProps` contract (see docs/COMPONENT-API-CONVENTIONS.md)
+ * spreads `{...restProps}` **first**, so the component's own attributes win: a
+ * consumer can't silently cancel state the component owns. Applied naively to
+ * event handlers that rule would go too far in the other direction — a
+ * `restProps`-first spread makes the component's `onkeydown` clobber the
+ * *consumer's*, which is just the original bug pointed the other way.
+ *
+ * Neither side should lose. Handlers are additive by nature (the DOM itself
+ * allows many listeners per event), so the component destructures the handler
+ * out of `restProps` and composes it: **internal first, consumer second**.
+ *
+ * ## Ordering: internal first
+ *
+ * 1. The component's behaviour is then unconditional — it cannot be skipped by
+ *    a consumer handler that throws, which is exactly what "internal wins"
+ *    has to mean for a dismiss/focus-trap path.
+ * 2. The consumer observes the event *after* the component reacted, so
+ *    `event.defaultPrevented` tells them whether the component claimed it
+ *    (e.g. Dialog preventDefaults `Escape` when it closes on it).
+ *
+ * ## `preventDefault` is deliberately NOT a veto
+ *
+ * The consumer's handler runs after the internal one, so calling
+ * `event.preventDefault()` there cannot suppress the component's behaviour —
+ * by design. Overloading `preventDefault` as "also disable this component's
+ * dismissal" would re-create the silent-disable bug through a different door:
+ * `preventDefault` has an established DOM meaning (suppress the *browser's*
+ * default action), and a consumer calling it for that reason would lose
+ * dismissal without ever asking to. Opting out of a behaviour is spelled with
+ * the named, discoverable prop that already exists for it — `closeOnEscape`,
+ * `closeOnBackdropClick` — not with a magic event side-effect.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   let { onkeydown: onkeydownProp, ...restProps }: Props = $props();
+ *   function handleKeydown(event: KeyboardEvent) { ... }
+ * </script>
+ *
+ * <dialog {...restProps} onkeydown={composeHandlers(handleKeydown, onkeydownProp)}>
+ * ```
+ */
+/**
+ * Structural mirror of svelte/elements' internal `EventHandler` type, which is
+ * declared there but not exported. Matching the shape keeps the composed result
+ * assignable to the `on*` props of `HTMLAttributes` (`MouseEventHandler<T>`,
+ * `KeyboardEventHandler<T>`, …).
+ */
+type DomEventHandler<TEvent extends Event, TElement extends EventTarget> = (event: TEvent & {
+    currentTarget: EventTarget & TElement;
+}) => unknown;
+/**
+ * Combine an internal handler with an optional consumer handler from `restProps`.
+ *
+ * The internal handler always runs first and always runs; the consumer handler
+ * runs afterwards when present. See the module doc for the ordering and
+ * `preventDefault` rationale.
+ *
+ * @param internal The component's own handler. Runs first, unconditionally.
+ * @param consumer The consumer's handler from `restProps`. May be `null`/`undefined`.
+ * @returns A handler assignable to the element's `on*` attribute.
+ */
+export declare function composeHandlers<TEvent extends Event, TElement extends EventTarget = Element>(internal: (event: TEvent & {
+    currentTarget: EventTarget & TElement;
+}) => unknown, consumer: DomEventHandler<TEvent, TElement> | null | undefined): DomEventHandler<TEvent, TElement>;
+export {};

package/dist/utils/compose-handlers.js

@@ -0,0 +1,65 @@
+/**
+ * `composeHandlers` — run a component's own DOM event handler *and* a
+ * consumer-supplied one that arrived through `restProps`.
+ *
+ * ## Why this exists
+ *
+ * The library's `restProps` contract (see docs/COMPONENT-API-CONVENTIONS.md)
+ * spreads `{...restProps}` **first**, so the component's own attributes win: a
+ * consumer can't silently cancel state the component owns. Applied naively to
+ * event handlers that rule would go too far in the other direction — a
+ * `restProps`-first spread makes the component's `onkeydown` clobber the
+ * *consumer's*, which is just the original bug pointed the other way.
+ *
+ * Neither side should lose. Handlers are additive by nature (the DOM itself
+ * allows many listeners per event), so the component destructures the handler
+ * out of `restProps` and composes it: **internal first, consumer second**.
+ *
+ * ## Ordering: internal first
+ *
+ * 1. The component's behaviour is then unconditional — it cannot be skipped by
+ *    a consumer handler that throws, which is exactly what "internal wins"
+ *    has to mean for a dismiss/focus-trap path.
+ * 2. The consumer observes the event *after* the component reacted, so
+ *    `event.defaultPrevented` tells them whether the component claimed it
+ *    (e.g. Dialog preventDefaults `Escape` when it closes on it).
+ *
+ * ## `preventDefault` is deliberately NOT a veto
+ *
+ * The consumer's handler runs after the internal one, so calling
+ * `event.preventDefault()` there cannot suppress the component's behaviour —
+ * by design. Overloading `preventDefault` as "also disable this component's
+ * dismissal" would re-create the silent-disable bug through a different door:
+ * `preventDefault` has an established DOM meaning (suppress the *browser's*
+ * default action), and a consumer calling it for that reason would lose
+ * dismissal without ever asking to. Opting out of a behaviour is spelled with
+ * the named, discoverable prop that already exists for it — `closeOnEscape`,
+ * `closeOnBackdropClick` — not with a magic event side-effect.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   let { onkeydown: onkeydownProp, ...restProps }: Props = $props();
+ *   function handleKeydown(event: KeyboardEvent) { ... }
+ * </script>
+ *
+ * <dialog {...restProps} onkeydown={composeHandlers(handleKeydown, onkeydownProp)}>
+ * ```
+ */
+/**
+ * Combine an internal handler with an optional consumer handler from `restProps`.
+ *
+ * The internal handler always runs first and always runs; the consumer handler
+ * runs afterwards when present. See the module doc for the ordering and
+ * `preventDefault` rationale.
+ *
+ * @param internal The component's own handler. Runs first, unconditionally.
+ * @param consumer The consumer's handler from `restProps`. May be `null`/`undefined`.
+ * @returns A handler assignable to the element's `on*` attribute.
+ */
+export function composeHandlers(internal, consumer) {
+    return (event) => {
+        internal(event);
+        consumer?.(event);
+    };
+}

package/dist/utils/figma-token-export.js

@@ -123,7 +123,7 @@ const foundationColors = {
         '200': 'oklch(0.84 0.075 220)',
         '300': 'oklch(0.76 0.105 220)',
         '400': 'oklch(0.66 0.13 220)',
-        '500': 'oklch(0.55 0.14 220)',
+        '500': 'oklch(0.54 0.14 220)',
         '600': 'oklch(0.48 0.13 220)',
         '700': 'oklch(0.4 0.11 220)',
         '800': 'oklch(0.32 0.09 220)',