@urbicon-ui/blocks 6.21.1 → 6.21.3

package/dist/primitives/Toast/toast.store.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { ToastData, ToastInput, ToastShorthandOpts } from './index.js';
+import type { ToastData, ToastInput, ToastPromiseOptions, ToastShorthandOpts } from './index.js';
 import type { ToastPlacement } from './toast.variants.js';
 /**
  * Reactive store that manages the global toast queue.
@@ -24,6 +24,30 @@ declare class ToastStore {
     registerSubscriber(): () => void;
     /** Create a toast with full control over all options. Returns the toast ID for programmatic dismissal. */
     add(input: ToastInput): string;
+    /**
+     * Merge new fields into an existing toast in place — same id, same stack
+     * position — and reset its auto-dismiss timer to the new `duration`. No-op if
+     * the toast is gone. Backs `promise()`, which flips a pending toast to
+     * success/error without it sliding out and a new one flying in.
+     */
+    update(id: string, input: ToastInput): void;
+    /**
+     * Drive a toast through a promise's lifecycle (Sonner-style). Shows a
+     * persistent, non-dismissible spinner toast while pending, then flips it in
+     * place to success on resolve or danger on reject. `success`/`error` may be a
+     * plain title, a full {@link ToastInput}, or a function of the resolved value
+     * / rejection reason. Returns the toast id.
+     *
+     * @example
+     * ```ts
+     * toaster.promise(saveDraft(), {
+     *   loading: 'Saving…',
+     *   success: (draft) => `Saved “${draft.title}”`,
+     *   error: (e) => `Could not save: ${e.message}`
+     * });
+     * ```
+     */
+    promise<T>(promise: Promise<T>, opts: ToastPromiseOptions<T>): string;
     /** Remove a single toast by ID. Clears its auto-dismiss timer. */
     dismiss(id: string): void;
     /** Remove all toasts and cancel their timers. */

package/dist/primitives/Toast/toast.store.svelte.js

@@ -50,7 +50,10 @@ class ToastStore {
             description: input.description,
             duration: input.duration ?? 5000,
             dismissible: input.dismissible ?? true,
-            showProgress: input.showProgress ?? true
+            showProgress: input.showProgress ?? true,
+            action: input.action,
+            cancel: input.cancel,
+            loading: input.loading ?? false
         };
         this.toasts = [...this.toasts, toast];
         if (toast.duration > 0) {
@@ -58,6 +61,93 @@ class ToastStore {
         }
         return id;
     }
+    /**
+     * Merge new fields into an existing toast in place — same id, same stack
+     * position — and reset its auto-dismiss timer to the new `duration`. No-op if
+     * the toast is gone. Backs `promise()`, which flips a pending toast to
+     * success/error without it sliding out and a new one flying in.
+     */
+    update(id, input) {
+        const idx = this.toasts.findIndex((t) => t.id === id);
+        if (idx === -1)
+            return;
+        const next = { ...this.toasts[idx], ...input };
+        this.toasts = [...this.toasts.slice(0, idx), next, ...this.toasts.slice(idx + 1)];
+        const timer = this.timers.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(id);
+        }
+        if (next.duration > 0) {
+            this.timers.set(id, setTimeout(() => this.dismiss(id), next.duration));
+        }
+    }
+    /**
+     * Drive a toast through a promise's lifecycle (Sonner-style). Shows a
+     * persistent, non-dismissible spinner toast while pending, then flips it in
+     * place to success on resolve or danger on reject. `success`/`error` may be a
+     * plain title, a full {@link ToastInput}, or a function of the resolved value
+     * / rejection reason. Returns the toast id.
+     *
+     * @example
+     * ```ts
+     * toaster.promise(saveDraft(), {
+     *   loading: 'Saving…',
+     *   success: (draft) => `Saved “${draft.title}”`,
+     *   error: (e) => `Could not save: ${e.message}`
+     * });
+     * ```
+     */
+    promise(promise, opts) {
+        const loadingInput = typeof opts.loading === 'string' ? { title: opts.loading } : opts.loading;
+        const id = this.add({
+            intent: 'neutral',
+            ...loadingInput,
+            loading: true,
+            duration: 0,
+            dismissible: false,
+            showProgress: false
+        });
+        // Shared settle fields: leave the spinner/persistent/non-dismissible state
+        // and become a normal auto-dismissing toast. `description: undefined` clears
+        // the loading description unless the success/error config sets its own.
+        const settled = {
+            loading: false,
+            duration: 5000,
+            dismissible: true,
+            showProgress: true
+        };
+        // A throwing user formatter must not turn into an unhandled rejection on the
+        // internal `.then`; fall back to a bare settled toast (still flips out of the
+        // loading state) and dev-warn instead.
+        const resolveMessage = (fn, arg, label) => {
+            let out;
+            try {
+                out = typeof fn === 'function' ? fn(arg) : fn;
+            }
+            catch (err) {
+                if (import.meta.env?.DEV)
+                    console.warn(`[Toast] promise ${label} formatter threw:`, err);
+            }
+            return typeof out === 'string' ? { title: out } : out;
+        };
+        promise.then((value) => {
+            this.update(id, {
+                intent: 'success',
+                description: undefined,
+                ...settled,
+                ...resolveMessage(opts.success, value, 'success')
+            });
+        }, (reason) => {
+            this.update(id, {
+                intent: 'danger',
+                description: undefined,
+                ...settled,
+                ...resolveMessage(opts.error, reason, 'error')
+            });
+        });
+        return id;
+    }
     /** Remove a single toast by ID. Clears its auto-dismiss timer. */
     dismiss(id) {
         const timer = this.timers.get(id);

package/dist/primitives/Toast/toast.variants.d.ts

@@ -39,6 +39,24 @@ export declare const toastVariants: ((props?: {
     } & {
         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;
+    actions: (props?: ({
+        intent?: "primary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
+        placement?: "bottom-right" | "top-right" | "bottom-left" | "top-left" | "top-center" | "bottom-center" | 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;
+    actionButton: (props?: ({
+        intent?: "primary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
+        placement?: "bottom-right" | "top-right" | "bottom-left" | "top-left" | "top-center" | "bottom-center" | 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;
+    cancelButton: (props?: ({
+        intent?: "primary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
+        placement?: "bottom-right" | "top-right" | "bottom-left" | "top-left" | "top-center" | "bottom-center" | 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;
     dismissButton: (props?: ({
         intent?: "primary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
         placement?: "bottom-right" | "top-right" | "bottom-left" | "top-left" | "top-center" | "bottom-center" | undefined;

package/dist/primitives/Toast/toast.variants.js

@@ -16,6 +16,21 @@ export const toastVariants = tv({
         content: 'flex-1 min-w-0',
         title: 'font-semibold text-sm leading-tight',
         description: 'text-sm mt-0.5 opacity-80',
+        // Action row (Sonner-style). Intent-neutral, prominent primary + quiet
+        // cancel — the toast's intent already reads through the icon/progress, so
+        // the buttons stay contrast-based rather than intent-coloured.
+        actions: 'flex items-center gap-2 mt-2.5',
+        // tier: modify — small interactive sub-elements on a contain surface.
+        actionButton: [
+            'rounded-modify px-2.5 py-1 text-xs font-medium',
+            'bg-text-primary/10 hover:bg-text-primary/20 text-text-primary',
+            'transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-current/40'
+        ],
+        cancelButton: [
+            'rounded-modify px-2.5 py-1 text-xs font-medium',
+            'text-text-secondary hover:text-text-primary',
+            'transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-current/40'
+        ],
         // tier: modify — small interactive sub-element on a contain surface.
         dismissButton: [
             'shrink-0 rounded-modify p-1',

package/dist/primitives/Toggle/Toggle.svelte

@@ -11,6 +11,7 @@
     checked = $bindable(false),
     label,
     helper,
+    error,
     tier,
     size = 'md',
     intent = 'primary',
@@ -35,7 +36,8 @@
   const id = $derived(idProp ?? propsId);
   const ff = useFormField(() => ({
     fieldId: id,
-    hint: helper,
+    helper,
+    error,
     required,
     disabled
   }));
@@ -61,6 +63,7 @@
     appearance,
     checked,
     disabled,
+    error: !!error,
     withBorder
   });
 
@@ -111,6 +114,7 @@
       aria-checked={checked}
       aria-label={label ? undefined : bt('accessibility.toggle') || 'Toggle'}
       aria-describedby={ff.describedBy}
+      aria-invalid={ff.invalid ? 'true' : undefined}
       onchange={handleChange}
       {...restProps}
     />
@@ -135,9 +139,19 @@
     {/if}
   </label>
 
-  {#if ff.hintId}
+  {#if ff.errorId}
+    <div
+      id={ff.errorId}
+      class={unstyled
+        ? (slotClasses?.message ?? '')
+        : styles.message({ class: slotClasses?.message })}
+      role="alert"
+    >
+      {error}
+    </div>
+  {:else if ff.helperId}
     <div
-      id={ff.hintId}
+      id={ff.helperId}
       class={unstyled
         ? (slotClasses?.message ?? '')
         : styles.message({ class: slotClasses?.message })}

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

@@ -24,13 +24,19 @@ import type { ToggleSlots, ToggleVariants } from './toggle.variants.js';
  * />
  * ```
  */
-export interface ToggleProps extends Omit<ToggleVariants, 'checked'>, Omit<HTMLInputAttributes, 'type' | 'size' | 'checked' | 'class' | 'children'> {
+export interface ToggleProps extends Omit<ToggleVariants, 'checked' | 'error'>, Omit<HTMLInputAttributes, 'type' | 'size' | 'checked' | 'class' | 'children'> {
     /** Current on/off state. Supports two-way binding via `bind:checked`. */
     checked?: boolean;
     /** Text label displayed to the right of the toggle track. */
     label?: string;
-    /** Hint text shown below the control. Useful for explaining side-effects of the toggle. */
+    /** Helper text shown below the control. Hidden when `error` is set. Useful for explaining side-effects of the toggle. */
     helper?: string;
+    /**
+     * Error message shown below the control. Replaces `helper`, flags the
+     * hidden input `aria-invalid`, and marks the unchecked track with the
+     * danger colour — e.g. for a consent toggle that must be switched on.
+     */
+    error?: string;
     /** Prevent interaction and dim the control. */
     disabled?: boolean;
     /** Mark the native input as required for form validation. */

package/dist/primitives/Toggle/toggle.variants.d.ts

@@ -6,6 +6,7 @@ export declare const toggleVariants: ((props?: {
     appearance?: "default" | "dot" | undefined;
     checked?: boolean | undefined;
     disabled?: boolean | undefined;
+    error?: boolean | undefined;
     withBorder?: boolean | undefined;
 } | undefined) => {
     wrapper: (props?: ({
@@ -15,6 +16,7 @@ export declare const toggleVariants: ((props?: {
         appearance?: "default" | "dot" | undefined;
         checked?: boolean | undefined;
         disabled?: boolean | undefined;
+        error?: boolean | undefined;
         withBorder?: 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;
@@ -26,6 +28,7 @@ export declare const toggleVariants: ((props?: {
         appearance?: "default" | "dot" | undefined;
         checked?: boolean | undefined;
         disabled?: boolean | undefined;
+        error?: boolean | undefined;
         withBorder?: 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;
@@ -37,6 +40,7 @@ export declare const toggleVariants: ((props?: {
         appearance?: "default" | "dot" | undefined;
         checked?: boolean | undefined;
         disabled?: boolean | undefined;
+        error?: boolean | undefined;
         withBorder?: 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;
@@ -48,6 +52,7 @@ export declare const toggleVariants: ((props?: {
         appearance?: "default" | "dot" | undefined;
         checked?: boolean | undefined;
         disabled?: boolean | undefined;
+        error?: boolean | undefined;
         withBorder?: 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;
@@ -59,6 +64,7 @@ export declare const toggleVariants: ((props?: {
         appearance?: "default" | "dot" | undefined;
         checked?: boolean | undefined;
         disabled?: boolean | undefined;
+        error?: boolean | undefined;
         withBorder?: 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;
@@ -70,6 +76,7 @@ export declare const toggleVariants: ((props?: {
         appearance?: "default" | "dot" | undefined;
         checked?: boolean | undefined;
         disabled?: boolean | undefined;
+        error?: boolean | undefined;
         withBorder?: 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;

package/dist/primitives/Toggle/toggle.variants.js

@@ -86,6 +86,11 @@ export const toggleVariants = tv({
                 control: 'opacity-50 cursor-not-allowed pointer-events-none'
             }
         },
+        error: {
+            true: {
+                message: 'text-danger'
+            }
+        },
         withBorder: {
             true: {},
             false: {}
@@ -153,6 +158,19 @@ export const toggleVariants = tv({
             intent: 'neutral',
             class: { track: 'bg-neutral border-neutral' }
         },
+        // ── Error state: danger boundary on the unchecked track (Switch-Pill) ──
+        // Mirrors Checkbox ("error overrides unchecked border"): the off state
+        // carries the danger mark, the on state keeps its intent colour — an
+        // error on a boolean control usually means "must be switched on".
+        // The dot-appearance twin lives at the END of the compound list so it
+        // folds over the dot-unchecked `border-border-default` (order is
+        // semantic — later compounds win conflicting buckets).
+        {
+            appearance: 'default',
+            error: true,
+            checked: false,
+            class: { track: 'border-danger peer-focus-visible:ring-danger/40' }
+        },
         // ── Thumb translation per size when checked (Switch-Pill only) ──
         { appearance: 'default', checked: true, size: 'xs', class: { thumb: 'translate-x-4' } },
         { appearance: 'default', checked: true, size: 'sm', class: { thumb: 'translate-x-5' } },
@@ -212,6 +230,13 @@ export const toggleVariants = tv({
             checked: true,
             intent: 'neutral',
             class: { track: 'border-neutral bg-neutral' }
+        },
+        // ── Error state, dot appearance (must fold over dot-unchecked border) ──
+        {
+            appearance: 'dot',
+            error: true,
+            checked: false,
+            class: { track: 'border-danger' }
         }
     ],
     defaultVariants: {
@@ -221,6 +246,7 @@ export const toggleVariants = tv({
         appearance: 'default',
         checked: false,
         disabled: false,
+        error: false,
         withBorder: false
     }
 });

package/dist/primitives/Toolbar/toolbar.variants.d.ts

@@ -1,15 +1,15 @@
 import { type SlotNames, type VariantProps } from '../../utils/variants.js';
 export declare const toolbarVariants: ((props?: {
-    variant?: "ghost" | "elevated" | "outlined" | "quiet" | undefined;
+    variant?: "ghost" | "quiet" | "elevated" | "outlined" | undefined;
     orientation?: "horizontal" | "vertical" | undefined;
-    gap?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
-    padding?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+    gap?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+    padding?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
 } | undefined) => {
     base: (props?: ({
-        variant?: "ghost" | "elevated" | "outlined" | "quiet" | undefined;
+        variant?: "ghost" | "quiet" | "elevated" | "outlined" | undefined;
         orientation?: "horizontal" | "vertical" | undefined;
-        gap?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
-        padding?: "sm" | "md" | "lg" | "xl" | "xs" | undefined;
+        gap?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        padding?: "sm" | "md" | "lg" | "xs" | "xl" | 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/Tooltip/Tooltip.svelte

@@ -25,7 +25,8 @@
     transitionEasing,
     disabled = false,
     arrow = true,
-    onVisibleChange,
+    open = $bindable(false),
+    onOpenChange,
     class: className,
     unstyled: unstyledProp = false,
     slotClasses: slotClassesProp = {},
@@ -43,7 +44,6 @@
     transitionDuration != null ? `${transitionDuration}ms` : undefined
   );
 
-  let visible = $state(false);
   let triggerElement = $state<HTMLElement>();
   let tooltipElement = $state<HTMLElement>();
   let arrowElement = $state<HTMLElement>();
@@ -52,7 +52,7 @@
   const propsId = $props.id();
   const tooltipId = `tooltip-${propsId}`;
 
-  const variantProps: VariantProps<typeof tooltipVariants> = $derived({ visible, intent, size });
+  const variantProps: VariantProps<typeof tooltipVariants> = $derived({ open, intent, size });
   const styles = $derived(tooltipVariants(variantProps));
   const slotClasses = $derived(
     resolveSlotClasses(blocksConfig, 'Tooltip', preset, variantProps, slotClassesProp)
@@ -60,16 +60,38 @@
 
   // Inside an open modal <dialog>, a popover shown via showPopover() forms a
   // second top-layer element WebKit won't render above the dialog (Codeberg
-  // #23). Evaluated while `visible` so the check runs once the dialog is
+  // #23). Evaluated while `open` so the check runs once the dialog is
   // already modal; the tooltip then renders in place (position:fixed + the
-  // opacity `visible` variant + pointer-events-none) within the dialog's own
+  // opacity `open` variant + pointer-events-none) within the dialog's own
   // top-layer subtree, no showPopover() needed.
-  const topLayer = $derived(visible ? !isAnchoredInModalDialog(triggerElement) : true);
+  const topLayer = $derived(open ? !isAnchoredInModalDialog(triggerElement) : true);
 
   let showTimeout: number;
   let hideTimeout: number;
   let cleanup: (() => void) | undefined = undefined;
 
+  // Clear pending show/hide timers on unmount — a hover followed by a
+  // teardown within `showDelay` (route change, {#if} removal) would
+  // otherwise fire setOpen after destroy: a write to the destroyed
+  // $bindable plus a ghost onOpenChange(true) for a tooltip that no
+  // longer exists. Dependency-free effect → runs once, teardown on destroy.
+  $effect(() => {
+    return () => {
+      clearTimeout(showTimeout);
+      clearTimeout(hideTimeout);
+    };
+  });
+
+  // Single mutation point for interaction-driven changes, so `onOpenChange`
+  // fires exactly once per transition. The no-change guard keeps a re-hover
+  // during the hide delay quiet (open never flipped). Consumer writes via
+  // `bind:open` bypass this on purpose — they don't re-announce themselves.
+  function setOpen(next: boolean) {
+    if (open === next) return;
+    open = next;
+    onOpenChange?.(next);
+  }
+
   function show() {
     if (disabled) return;
     clearTimeout(hideTimeout);
@@ -80,24 +102,21 @@
       // call would briefly flash the tooltip before the effect tears it
       // back down.
       if (disabled) return;
-      visible = true;
-      onVisibleChange?.(true);
+      setOpen(true);
     }, showDelay);
   }
 
   function hide() {
     clearTimeout(showTimeout);
     hideTimeout = window.setTimeout(() => {
-      visible = false;
-      onVisibleChange?.(false);
+      setOpen(false);
     }, hideDelay);
   }
 
   function handleKeydown(e: KeyboardEvent) {
-    if (e.key === 'Escape' && visible) {
+    if (e.key === 'Escape' && open) {
       clearTimeout(showTimeout);
-      visible = false;
-      onVisibleChange?.(false);
+      setOpen(false);
     }
   }
 
@@ -156,7 +175,7 @@
       });
   }
 
-  // Drive native popover state from `visible`. `popover="manual"` puts the
+  // Drive native popover state from `open`. `popover="manual"` puts the
   // element in the browser top layer when shown, so the tooltip is never
   // clipped by ancestor `overflow` (e.g. Toolbar). We deliberately avoid
   // `popover="auto"` here — auto would dismiss the tooltip on any outside
@@ -170,13 +189,13 @@
   $effect(() => {
     if (!triggerElement || !tooltipElement) return;
 
-    const shouldShow = !disabled && visible && !!label;
+    const shouldShow = !disabled && open && !!label;
 
     if (!shouldShow) {
-      // Force-clear `visible` so a stale show timeout that fired right
+      // Force-clear `open` so a stale show timeout that fired right
       // before `disabled` flipped doesn't immediately re-trigger this
       // effect into the show branch on the next mouse event.
-      if (disabled && visible) visible = false;
+      if (disabled && open) setOpen(false);
       cleanup?.();
       cleanup = undefined;
       if (tooltipElement.matches(':popover-open')) {
@@ -219,15 +238,22 @@
 </script>
 
 <!-- svelte-ignore a11y_no_static_element_interactions -->
+<!--
+  focusin/focusout (not focus/blur): the wrapper span is never focusable
+  itself — the actual trigger is the consumer's child element. focus/blur
+  don't bubble, so a keyboard focus on the child never reached the wrapper
+  and the tooltip silently skipped its WCAG 1.4.13 focus-open path;
+  focusin/focusout bubble and cover any focusable descendant.
+-->
 <span
   class="inline-flex"
   bind:this={triggerElement}
   onmouseenter={show}
   onmouseleave={hide}
-  onfocus={show}
-  onblur={hide}
+  onfocusin={show}
+  onfocusout={hide}
   onkeydown={handleKeydown}
-  aria-describedby={!disabled && label && visible ? tooltipId : undefined}
+  aria-describedby={!disabled && label && open ? tooltipId : undefined}
 >
   {@render children()}
 </span>
@@ -239,7 +265,7 @@
   the arrow node existed). In top-layer mode the `popover="manual"` attribute
   hides it via the UA stylesheet until `showPopover()` is called; inside a
   modal dialog (`topLayer === false`) the attribute is dropped and the
-  `visible` opacity variant drives visibility instead (Codeberg #23).
+  `open` opacity variant drives visibility instead (Codeberg #23).
 
   Load-bearing attributes (`popover`, `style`, `role`, `id`) intentionally
   follow `{...restProps}` so a consumer-supplied `popover="auto"`, custom

package/dist/primitives/Tooltip/Tooltip.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { TooltipProps } from './index.js';
-declare const Tooltip: import("svelte").Component<TooltipProps, {}, "">;
+declare const Tooltip: import("svelte").Component<TooltipProps, {}, "open">;
 type Tooltip = ReturnType<typeof Tooltip>;
 export default Tooltip;

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

@@ -4,7 +4,7 @@ import type { Placement } from '../../utils/floating.js';
 import type { TooltipSlots, TooltipVariants } from './tooltip.variants.js';
 /**
  * @description Contextual overlay that displays brief, supplementary text on hover or focus.
- * Built with Floating UI for precise positioning and accessibility support.
+ * Built on the library's own positioning engine for precise placement and accessibility support.
  *
  * @tag display
  * @related Popover
@@ -22,6 +22,22 @@ import type { TooltipSlots, TooltipVariants } from './tooltip.variants.js';
  *   <Button variant="ghost" size="sm" onclick={handleCopy}>Copy</Button>
  * </Tooltip>
  * ```
+ *
+ * @example Controlled mode — programmatic "Copied!" feedback via `bind:open`
+ * ```svelte
+ * <script lang="ts">
+ *   let copied = $state(false);
+ *   async function copy() {
+ *     await navigator.clipboard.writeText(text);
+ *     copied = true;
+ *     setTimeout(() => (copied = false), 1500);
+ *   }
+ * </script>
+ *
+ * <Tooltip label="Copied!" bind:open={copied}>
+ *   <Button onclick={copy}>Copy</Button>
+ * </Tooltip>
+ * ```
  */
 export interface TooltipProps extends TooltipVariants, Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
     /** Text displayed inside the tooltip bubble. */
@@ -52,8 +68,20 @@ export interface TooltipProps extends TooltipVariants, Omit<HTMLAttributes<HTMLD
     arrow?: boolean;
     /** Prevent the tooltip from appearing regardless of hover/focus. @default false */
     disabled?: boolean;
-    /** Fires when tooltip visibility changes (hover in/out, Escape key). */
-    onVisibleChange?: (visible: boolean) => void;
+    /**
+     * Controls tooltip visibility. Supports `bind:open` for programmatic
+     * display (e.g. a transient "Copied!" confirmation). Hover/focus keep
+     * driving the state in parallel — the delays apply only to those
+     * interaction paths, a `bind:open` write takes effect immediately.
+     * @default false
+     */
+    open?: boolean;
+    /**
+     * Fires when the tooltip opens or closes from user interaction (hover
+     * in/out, focus/blur, Escape). Receives the new open state. Not called
+     * when the consumer writes `bind:open` directly.
+     */
+    onOpenChange?: (open: boolean) => void;
     /** Remove default tv classes; only consumer classes apply. */
     unstyled?: boolean;
     /** Per-slot class overrides merged with (or replacing, when unstyled) tv styles. */