@leavepulse/ui 0.43.4 → 0.44.0

package/dist/composables/useField.js

@@ -0,0 +1,45 @@
+import { provide, useId, computed, inject } from "vue";
+const LP_FIELD = /* @__PURE__ */ Symbol.for("lp-field");
+function provideField(context) {
+  provide(LP_FIELD, context);
+}
+function useField() {
+  return inject(LP_FIELD, null);
+}
+function fieldMessageId(id) {
+  return `${id}-message`;
+}
+function useFieldControl(own) {
+  const outer = useField();
+  const generated = useId();
+  return computed(() => {
+    const state = own();
+    if (state.wrapped) {
+      const id = state.id ?? generated;
+      return {
+        id,
+        labelId: void 0,
+        describedBy: state.hasMessage ? fieldMessageId(id) : void 0,
+        invalid: !!state.invalid,
+        required: !!state.required,
+        disabled: !!state.disabled
+      };
+    }
+    const field = outer?.value;
+    return {
+      id: state.id ?? field?.id,
+      labelId: field?.labelId,
+      describedBy: field?.describedBy,
+      invalid: !!state.invalid || !!field?.invalid,
+      required: !!state.required || !!field?.required,
+      disabled: !!state.disabled || !!field?.disabled
+    };
+  });
+}
+export {
+  LP_FIELD,
+  fieldMessageId,
+  provideField,
+  useField,
+  useFieldControl
+};

package/dist/composables/useFormDraft.d.ts

@@ -24,9 +24,16 @@ export interface UseFormDraftOptions<T> {
     disabled?: MaybeRefOrGetter<boolean>;
 }
 export interface UseFormDraft<T> {
-    /** A draft was found for this key, and has not been restored or discarded. */
+    /**
+     * A draft was found for this key, and has not been restored or discarded.
+     * Only a draft found on reading counts: the writes this composable makes as
+     * the user types never raise it. While it is up, automatic writes are held
+     * back, so the draft on offer cannot be overwritten by the form's own state
+     * (an async load of the record, or typing past the banner) before the user
+     * has answered.
+     */
     hasDraft: Ref<boolean>;
-    /** When that draft was written, ISO-8601, or `null` when there is none. */
+    /** When the found draft was written, ISO-8601, or `null` when there is none. */
     savedAt: Ref<string | null>;
     /**
      * The stored value, or `null`. Reading does not apply it — the caller decides
@@ -35,7 +42,7 @@ export interface UseFormDraft<T> {
     read: () => T | null;
     /** Forget the draft. Call after applying it, and after a successful save. */
     discard: () => void;
-    /** Write now, ignoring `dirty`. For "save and come back to this later". */
+    /** Write now, ignoring `dirty` and a pending draft. For "save and come back to this later". */
     save: () => void;
 }
 /**

package/dist/composables/useFormDraft.js

@@ -16,6 +16,11 @@ function useFormDraft(options) {
   function currentKey() {
     return String(toValue(options.key) || "").trim();
   }
+  function fresh(parsed) {
+    if (!parsed || parsed.version !== ENVELOPE_VERSION) return false;
+    if (maxAge <= 0) return true;
+    return !(Date.now() - Date.parse(parsed.savedAt) > maxAge);
+  }
   function read() {
     const store = storage();
     const key = currentKey();
@@ -29,17 +34,10 @@ function useFormDraft(options) {
     if (!raw) return null;
     try {
       const parsed = JSON.parse(raw);
-      if (!parsed || parsed.version !== ENVELOPE_VERSION) {
+      if (!fresh(parsed)) {
         discard();
         return null;
       }
-      if (maxAge > 0) {
-        const age = Date.now() - Date.parse(parsed.savedAt);
-        if (age > maxAge) {
-          discard();
-          return null;
-        }
-      }
       return parsed.value;
     } catch {
       discard();
@@ -50,21 +48,18 @@ function useFormDraft(options) {
     const store = storage();
     const key = currentKey();
     if (!store || !key) return;
-    const stamp = (/* @__PURE__ */ new Date()).toISOString();
     try {
       store.setItem(
         key,
         JSON.stringify({
           version: ENVELOPE_VERSION,
-          savedAt: stamp,
+          savedAt: (/* @__PURE__ */ new Date()).toISOString(),
           value
         })
       );
     } catch {
       return;
     }
-    hasDraft.value = true;
-    savedAt.value = stamp;
   }
   function discard() {
     const store = storage();
@@ -97,7 +92,7 @@ function useFormDraft(options) {
       if (!raw) return;
       try {
         const parsed = JSON.parse(raw);
-        if (parsed?.version !== ENVELOPE_VERSION) return;
+        if (!fresh(parsed)) return;
         hasDraft.value = true;
         savedAt.value = parsed.savedAt;
       } catch {
@@ -108,7 +103,7 @@ function useFormDraft(options) {
   watch(
     () => [toValue(options.value), toValue(options.dirty), toValue(options.disabled)],
     ([value, dirty, disabled]) => {
-      if (disabled) return;
+      if (disabled || hasDraft.value) return;
       if (options.dirty !== void 0 && !dirty) return;
       write(value);
     },

package/dist/composables/useHotkeys.d.ts

@@ -16,6 +16,16 @@ export interface HotkeyBinding {
      * something there — Escape, and the palette the user reaches from anywhere.
      */
     allowInInput?: boolean;
+    /**
+     * Runs even while an overlay owns the keyboard. By default a binding declared
+     * outside the topmost modal stays quiet while that modal is open, and an
+     * Escape binding declared outside the topmost dismissable layer (dialog,
+     * popover, menu) leaves Escape to that layer, so a page-level shortcut can
+     * neither act behind a dialog nor stop the dialog from closing.
+     */
+    overLayers?: boolean;
+    /** Set `false` to ignore auto-repeat while the key is held. */
+    repeat?: boolean;
     /**
      * How the key reference lists this binding while it is mounted. Bindings
      * without it still work, they just stay out of `activeShortcuts`.
@@ -57,11 +67,17 @@ export interface ShortcutGroup {
  * used to pick a label.
  */
 export declare const isAppleKeyboard: boolean;
+/**
+ * `isAppleKeyboard` for render paths: false until mounted, so the server and
+ * the hydrating client print the same label and the client switches after.
+ */
+export declare function useAppleKeyboard(): import("vue").Ref<boolean, boolean>;
 /**
  * The symbol to print for a modifier on this platform. Bindings treat Ctrl and
  * Meta as one modifier, so only the label may differ — never the binding.
  */
-export declare function appleModifierLabel(key: string): string;
+export declare function appleModifierLabel(key: string, apple?: boolean): string;
+export declare function matchesHotkey(event: KeyboardEvent, binding: HotkeyBinding): boolean;
 /**
  * Bind a list of hotkeys for as long as the calling component is mounted.
  *

package/dist/composables/useHotkeys.js

@@ -1,7 +1,13 @@
-import { shallowReactive, computed, toValue, onMounted, onBeforeUnmount } from "vue";
+import { shallowReactive, computed, toValue, getCurrentInstance, onMounted, onBeforeUnmount, ref } from "vue";
+import { topModalElement } from "../components/modalDepth.js";
 const isAppleKeyboard = typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/.test(navigator.platform || "");
-function appleModifierLabel(key) {
-  if (!isAppleKeyboard) return key;
+function useAppleKeyboard() {
+  const apple = ref(false);
+  onMounted(() => apple.value = isAppleKeyboard);
+  return apple;
+}
+function appleModifierLabel(key, apple = isAppleKeyboard) {
+  if (!apple) return key;
   if (key === "Ctrl") return "⌘";
   if (key === "Alt") return "⌥";
   return key;
@@ -24,33 +30,57 @@ function isTextEntry(target) {
   }
   return false;
 }
-function matches(event, binding) {
+const MODIFIER_KEYS = /* @__PURE__ */ new Set(["control", "meta", "shift", "alt"]);
+function matchesHotkey(event, binding) {
+  const key = binding.key.toLowerCase();
   const ctrlHeld = event.ctrlKey || event.metaKey;
-  if (ctrlHeld !== Boolean(binding.ctrl)) return false;
-  if (event.shiftKey !== Boolean(binding.shift)) return false;
-  if (event.altKey !== Boolean(binding.alt)) return false;
-  return event.key.toLowerCase() === binding.key.toLowerCase() || binding.code !== void 0 && event.code === binding.code;
+  const wantsCtrl = Boolean(binding.ctrl) || key === "control" || key === "meta";
+  if (ctrlHeld !== wantsCtrl) return false;
+  const symbol = key.length === 1 && key.toLowerCase() === key.toUpperCase();
+  const shiftFree = key === "shift" || binding.shift === void 0 && symbol;
+  if (!shiftFree && event.shiftKey !== Boolean(binding.shift)) return false;
+  if (key !== "alt" && event.altKey !== Boolean(binding.alt)) return false;
+  if (MODIFIER_KEYS.has(key)) return event.key.toLowerCase() === key;
+  return event.key.toLowerCase() === key || binding.code !== void 0 && event.code === binding.code;
 }
-const mounted = shallowReactive(/* @__PURE__ */ new Set());
-let mountOrder = 0;
-let listening = false;
+const STATE_KEY = /* @__PURE__ */ Symbol.for("@leavepulse/ui:hotkeys");
+const g = globalThis;
+const state = g[STATE_KEY] ??= {
+  mounted: shallowReactive(/* @__PURE__ */ new Set()),
+  order: 0,
+  listening: false
+};
+const mounted = state.mounted;
 function inScope(target, scope) {
   const el = toValue(scope);
   if (!el) return true;
   const node = target instanceof Node ? target : null;
   return !!node && (el === node || el.contains(node));
 }
+function topLayer() {
+  const layers = document.querySelectorAll("[data-dismissable-layer]");
+  return layers[layers.length - 1] ?? null;
+}
+function insideOf(entry, layer) {
+  const scope = toValue(entry.scope);
+  const node = scope ?? entry.host();
+  return !!node && layer.contains(node);
+}
 function onKeydown(event) {
-  if (event.isComposing) return;
+  if (event.isComposing || event.defaultPrevented) return;
   const inTextEntry = isTextEntry(event.target);
+  const blocker = event.key === "Escape" ? topLayer() : topModalElement();
   const entries = [...mounted].sort(
     (a, b) => Number(toValue(b.priority) || 0) - Number(toValue(a.priority) || 0) || b.order - a.order
   );
   for (const entry of entries) {
     if (toValue(entry.enabled) === false || !inScope(event.target, entry.scope)) continue;
+    const covered = !!blocker && !insideOf(entry, blocker);
     for (const binding of entry.read()) {
       if (inTextEntry && !binding.allowInInput) continue;
-      if (!matches(event, binding)) continue;
+      if (event.repeat && binding.repeat === false) continue;
+      if (covered && !binding.overLayers) continue;
+      if (!matchesHotkey(event, binding)) continue;
       if (binding.handler(event) === false) continue;
       event.preventDefault();
       return;
@@ -58,25 +88,30 @@ function onKeydown(event) {
   }
 }
 function useHotkeys(bindings, options = {}) {
+  const instance = getCurrentInstance();
   const entry = {
     read: () => toValue(bindings),
     scope: options.scope,
     enabled: options.enabled,
     priority: options.priority,
-    order: ++mountOrder
+    order: ++state.order,
+    host: () => {
+      const el = instance?.vnode.el;
+      return el instanceof Node ? el : null;
+    }
   };
   onMounted(() => {
     mounted.add(entry);
-    if (!listening) {
+    if (!state.listening) {
       window.addEventListener("keydown", onKeydown);
-      listening = true;
+      state.listening = true;
     }
   });
   onBeforeUnmount(() => {
     mounted.delete(entry);
-    if (!mounted.size && listening) {
+    if (!mounted.size && state.listening) {
       window.removeEventListener("keydown", onKeydown);
-      listening = false;
+      state.listening = false;
     }
   });
 }
@@ -128,6 +163,8 @@ export {
   activeShortcuts,
   appleModifierLabel,
   isAppleKeyboard,
+  matchesHotkey,
   mergeShortcutGroups,
+  useAppleKeyboard,
   useHotkeys
 };

package/dist/composables/useInputFilter.d.ts

@@ -5,9 +5,26 @@ export interface UseInputFilterOptions {
     /** RegExp/string the full value must match to be valid. Validation only. */
     pattern?: MaybeRefOrGetter<RegExp | string | undefined>;
 }
+/**
+ * Anchor a pattern to the whole string, like HTML's `pattern` attribute. The
+ * source is wrapped, never edited: anchors the caller wrote stay valid inside
+ * the group, while trimming a trailing `$` broke an escaped `\$` into an
+ * unterminated group.
+ */
+export declare function anchorPattern(p: RegExp | string): RegExp;
+/**
+ * `text` with every disallowed character removed, and where `caret` lands once
+ * the characters before it that were removed are gone.
+ */
+export declare function stripDisallowed(text: string, charRe: RegExp, caret?: number): {
+    text: string;
+    caret: number;
+};
 export declare function useInputFilter(options?: UseInputFilterOptions): {
     isInvalid: (value: string | undefined) => boolean;
     onBeforeInput: (event: InputEvent) => void;
+    onInput: (event: Event) => void;
+    onCompositionEnd: (event: CompositionEvent) => void;
     onPaste: (event: ClipboardEvent) => void;
     patternRe: import("vue").ComputedRef<RegExp | undefined>;
     restrict: import("vue").ComputedRef<RegExp | undefined>;

package/dist/composables/useInputFilter.js

@@ -1,23 +1,38 @@
 import { computed, toValue } from "vue";
-function toAnchored(p) {
-  if (p instanceof RegExp) {
-    const src = p.source.replace(/^\^/, "").replace(/\$$/, "");
-    return new RegExp(`^(?:${src})$`, p.flags.replace(/[gy]/g, ""));
-  }
+function anchorPattern(p) {
+  if (p instanceof RegExp) return new RegExp(`^(?:${p.source})$`, p.flags.replace(/[gy]/g, ""));
   return new RegExp(`^(?:${p})$`);
 }
-function allAllowed(text, charRe) {
+function charTester(charRe) {
   const re = new RegExp(charRe.source, charRe.flags.replace(/[gy]/g, ""));
+  return (ch) => re.test(ch);
+}
+function allAllowed(text, charRe) {
+  const ok = charTester(charRe);
   for (const ch of text) {
-    if (!re.test(ch)) return false;
+    if (!ok(ch)) return false;
   }
   return true;
 }
+function stripDisallowed(text, charRe, caret = text.length) {
+  const ok = charTester(charRe);
+  let kept = "";
+  let at = 0;
+  let offset = 0;
+  for (const ch of text) {
+    if (ok(ch)) {
+      kept += ch;
+      if (offset < caret) at += ch.length;
+    }
+    offset += ch.length;
+  }
+  return { text: kept, caret: at };
+}
 function useInputFilter(options = {}) {
   const restrict = computed(() => toValue(options.restrict));
   const patternRe = computed(() => {
     const p = toValue(options.pattern);
-    return p === void 0 ? void 0 : toAnchored(p);
+    return p === void 0 ? void 0 : anchorPattern(p);
   });
   function isInvalid(value) {
     const re = patternRe.value;
@@ -27,18 +42,40 @@ function useInputFilter(options = {}) {
   function onBeforeInput(event) {
     const re = restrict.value;
     if (!re || event.isComposing) return;
-    const data = event.data;
+    const data = event.data ?? event.dataTransfer?.getData("text") ?? null;
     if (data == null) return;
     if (!allAllowed(data, re)) event.preventDefault();
   }
+  function sanitize(target) {
+    const re = restrict.value;
+    if (!re) return false;
+    if (!(target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement)) return false;
+    const { text, caret } = stripDisallowed(target.value, re, target.selectionStart ?? target.value.length);
+    if (text === target.value) return false;
+    target.value = text;
+    try {
+      target.setSelectionRange(caret, caret);
+    } catch {
+    }
+    return true;
+  }
+  function onInput(event) {
+    if (event.isComposing) return;
+    sanitize(event.target);
+  }
+  function onCompositionEnd(event) {
+    if (sanitize(event.target)) event.target?.dispatchEvent(new Event("input", { bubbles: true }));
+  }
   function onPaste(event) {
     const re = restrict.value;
     if (!re) return;
     const text = event.clipboardData?.getData("text") ?? "";
     if (text && !allAllowed(text, re)) event.preventDefault();
   }
-  return { isInvalid, onBeforeInput, onPaste, patternRe, restrict };
+  return { isInvalid, onBeforeInput, onInput, onCompositionEnd, onPaste, patternRe, restrict };
 }
 export {
+  anchorPattern,
+  stripDisallowed,
   useInputFilter
 };

package/dist/composables/useLpConfig.d.ts

@@ -0,0 +1,24 @@
+import { type App, type Component, type ComputedRef, type InjectionKey, type MaybeRefOrGetter } from "vue";
+export type LabelScope = Record<string, string>;
+export interface LpConfig {
+    /** Component rendered for internal links (RouterLink, NuxtLink). Plain `<a>` when unset. */
+    linkComponent?: Component | string;
+    /** Text overrides by scope: `{ lightbox: { previous: "Back" } }`. */
+    labels?: Partial<Record<string, Partial<LabelScope>>>;
+}
+export declare const LP_CONFIG: InjectionKey<MaybeRefOrGetter<LpConfig>>;
+/** Provide kit configuration to every component below the caller. */
+export declare function provideLpConfig(config: MaybeRefOrGetter<LpConfig>): void;
+/** Install the configuration app-wide: `app.use(lpConfig({ ... }))`. */
+export declare function lpConfig(config: MaybeRefOrGetter<LpConfig>): {
+    install: (app: App) => void;
+};
+export declare function mergeConfig(outer: LpConfig, inner: LpConfig): LpConfig;
+export declare function useLpConfig(): ComputedRef<LpConfig>;
+/**
+ * The labels a component renders: its own `labels` prop over the configured
+ * scope over its defaults.
+ */
+export declare function useLabels<T extends LabelScope>(scope: string, defaults: T, own?: () => Partial<T> | undefined): ComputedRef<T>;
+/** The link component to render for an internal destination. */
+export declare function useLinkComponent(): ComputedRef<Component | string>;

package/dist/composables/useLpConfig.js

@@ -0,0 +1,44 @@
+import { computed, inject, provide, toValue } from "vue";
+const LP_CONFIG = /* @__PURE__ */ Symbol.for("lp-config");
+function provideLpConfig(config) {
+  provide(LP_CONFIG, layered(inject(LP_CONFIG, {}), config));
+}
+function lpConfig(config) {
+  return {
+    install: (app) => {
+      const outer = app.runWithContext(() => inject(LP_CONFIG, {}));
+      app.provide(LP_CONFIG, layered(outer, config));
+    }
+  };
+}
+function layered(outer, inner) {
+  return () => mergeConfig(toValue(outer), toValue(inner));
+}
+function mergeConfig(outer, inner) {
+  const labels = { ...outer.labels };
+  for (const [scope, values] of Object.entries(inner.labels ?? {})) {
+    labels[scope] = { ...labels[scope], ...values };
+  }
+  return { ...outer, ...inner, linkComponent: inner.linkComponent ?? outer.linkComponent, labels };
+}
+function useLpConfig() {
+  const config = inject(LP_CONFIG, {});
+  return computed(() => toValue(config));
+}
+function useLabels(scope, defaults, own) {
+  const config = useLpConfig();
+  return computed(() => ({ ...defaults, ...config.value.labels?.[scope], ...own?.() }));
+}
+function useLinkComponent() {
+  const config = useLpConfig();
+  return computed(() => config.value.linkComponent ?? "a");
+}
+export {
+  LP_CONFIG,
+  lpConfig,
+  mergeConfig,
+  provideLpConfig,
+  useLabels,
+  useLinkComponent,
+  useLpConfig
+};

package/dist/composables/useRovingFocus.js

@@ -1,4 +1,5 @@
 import { ref, computed, toValue, watch } from "vue";
+const NON_TEXT_INPUTS = /* @__PURE__ */ new Set(["checkbox", "radio", "button", "submit", "reset", "range", "color", "file", "image"]);
 const TYPEAHEAD_RESET_MS = 700;
 function useRovingFocus(items, options = {}) {
   const {
@@ -69,7 +70,13 @@ function useRovingFocus(items, options = {}) {
       }
     }
   }
+  function isTextEntry(target) {
+    if (!(target instanceof HTMLElement)) return false;
+    if (target.isContentEditable || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) return true;
+    return target instanceof HTMLInputElement && !NON_TEXT_INPUTS.has(target.type);
+  }
   function onKeydown(event) {
+    if (event.isComposing || isTextEntry(event.target)) return;
     const vertical = orientation === "vertical" || orientation === "both";
     const horizontal = orientation === "horizontal" || orientation === "both";
     switch (event.key) {

package/dist/composables/useTilt.d.ts

@@ -1,4 +1,4 @@
-import { type ComputedRef, type CSSProperties, type Ref } from "vue";
+import { type ComputedRef, type CSSProperties, type MaybeRefOrGetter, type Ref } from "vue";
 export interface UseTiltOptions {
     /** Max rotation toward the pointer, in degrees (per axis). Default 10. */
     max?: number;
@@ -20,4 +20,4 @@ export interface UseTilt {
     /** True while the pointer is over the element (drives lift/scale). */
     active: Ref<boolean>;
 }
-export declare function useTilt(options?: UseTiltOptions): UseTilt;
+export declare function useTilt(source?: MaybeRefOrGetter<UseTiltOptions>): UseTilt;

package/dist/composables/useTilt.js

@@ -1,9 +1,7 @@
 import { useReducedMotion } from "motion-v";
-import { ref, computed } from "vue";
-function useTilt(options = {}) {
-  const max = options.max ?? 10;
-  const lift = options.lift ?? 8;
-  const scale = options.scale ?? 1.03;
+import { computed, toValue, ref } from "vue";
+function useTilt(source = {}) {
+  const options = computed(() => toValue(source));
   const reduceMotion = useReducedMotion();
   const active = ref(false);
   const nx = ref(0);
@@ -28,6 +26,7 @@ function useTilt(options = {}) {
     if (reduceMotion.value) {
       return { transition: "transform 0.2s ease" };
     }
+    const { max = 10, lift = 8, scale = 1.03 } = options.value;
     const rx = active.value ? -ny.value * max : 0;
     const ry = active.value ? nx.value * max : 0;
     const z = active.value ? lift : 0;
@@ -39,7 +38,7 @@ function useTilt(options = {}) {
     };
   });
   const glareStyle = computed(() => {
-    if (!options.glare || reduceMotion.value || !active.value) {
+    if (!options.value.glare || reduceMotion.value || !active.value) {
       return { opacity: 0 };
     }
     const px = (nx.value + 1) * 50;

package/dist/composables/useToast.d.ts

@@ -7,6 +7,9 @@ export interface ToastAction {
 }
 export interface ToastItem {
     id: number;
+    /** Bumped when a toast with the same `key` replaces this one in place. */
+    rev: number;
+    key?: string;
     title?: string;
     message: string;
     variant: ToastVariant;
@@ -18,12 +21,28 @@ export interface ToastItem {
     onClick?: () => void | Promise<void>;
 }
 export interface ToastOptions {
+    /**
+     * A toast with the same key replaces the one on screen instead of stacking
+     * beside it: "Saved" ten times is one toast, and a progress toast can turn
+     * into its result.
+     */
+    key?: string;
     title?: string;
     duration?: number;
     actions?: ToastAction[];
     onClick?: () => void | Promise<void>;
 }
 declare function push(variant: ToastVariant, message: string, options?: ToastOptions): number;
+export interface ToastPromiseMessages<T> {
+    loading: string;
+    success: string | ((value: T) => string);
+    error: string | ((error: unknown) => string);
+}
+/**
+ * One toast that follows a promise: a persistent "loading" toast that turns
+ * into the success or error toast when it settles. Returns the promise itself.
+ */
+declare function promise<T>(task: Promise<T>, messages: ToastPromiseMessages<T>, options?: ToastOptions): Promise<T>;
 declare function dismiss(id: number): void;
 declare function clear(): void;
 export declare function useToast(): {
@@ -33,6 +52,7 @@ export declare function useToast(): {
     success: (message: string, o?: ToastOptions) => number;
     warning: (message: string, o?: ToastOptions) => number;
     error: (message: string, o?: ToastOptions) => number;
+    promise: typeof promise;
     /** Low-level push for bridges (e.g. @leavepulse/ui-sdk apiError). */
     push: typeof push;
     dismiss: typeof dismiss;

package/dist/composables/useToast.js

@@ -6,10 +6,10 @@ const g = globalThis;
 const state = g[STATE_KEY] ??= { queue: reactive([]), nextId: 0 };
 const queue = state.queue;
 function push(variant, message, options = {}) {
-  const id = state.nextId++;
+  if (typeof window === "undefined") return -1;
   const duration = options.duration ?? DEFAULT_DURATION;
-  const item = {
-    id,
+  const fields = {
+    key: options.key,
     title: options.title,
     message,
     variant,
@@ -18,11 +18,34 @@ function push(variant, message, options = {}) {
     actions: options.actions,
     onClick: options.onClick
   };
+  const same = options.key === void 0 ? -1 : queue.findIndex((t) => t.key === options.key);
+  const existing = queue[same];
+  if (existing) {
+    queue.splice(same, 1, { ...fields, id: existing.id, rev: existing.rev + 1 });
+    return existing.id;
+  }
+  const id = state.nextId++;
   const overflow = queue.length - (MAX_ACTIVE - 1);
   if (overflow > 0) queue.splice(0, overflow);
-  queue.push(item);
+  queue.push({ ...fields, id, rev: 0 });
   return id;
 }
+let promiseKey = 0;
+function promise(task, messages, options = {}) {
+  const key = options.key ?? `@leavepulse/ui:promise-${promiseKey++}`;
+  push("info", messages.loading, { ...options, key, duration: 0, actions: void 0 });
+  task.then(
+    (value) => {
+      const text = typeof messages.success === "function" ? messages.success(value) : messages.success;
+      push("success", text, { ...options, key });
+    },
+    (error) => {
+      const text = typeof messages.error === "function" ? messages.error(error) : messages.error;
+      push("error", text, { ...options, key });
+    }
+  );
+  return task;
+}
 function dismiss(id) {
   const i = queue.findIndex((t) => t.id === id);
   if (i !== -1) queue.splice(i, 1);
@@ -38,6 +61,7 @@ function useToast() {
     success: (message, o) => push("success", message, o),
     warning: (message, o) => push("warning", message, o),
     error: (message, o) => push("error", message, o),
+    promise,
     /** Low-level push for bridges (e.g. @leavepulse/ui-sdk apiError). */
     push,
     dismiss,