@alfadocs/ui-kit 1.44.0 → 1.45.0

package/dist/_chunks/use-ai-sparkle-CyQSRTCe.js

@@ -0,0 +1,103 @@
+import { useState as v, useEffect as _, useCallback as e } from "react";
+import { u as k } from "./use-prefers-reduced-motion-BMwIQRjB.js";
+const y = {
+  intro: 3200,
+  landed: 2800
+}, g = {
+  intro: "ds:animate-[ai-pill-shimmer_calc(var(--animation-duration)*6)_var(--ease-in-out)_1]",
+  working: "ds:animate-[ai-pill-shimmer_calc(var(--animation-duration)*6)_var(--ease-in-out)_infinite]",
+  landed: "ds:animate-[ai-pill-shimmer_calc(var(--animation-duration)*4)_var(--ease-out)_1]"
+}, S = {
+  intro: "ds:animate-[ai-comet-orbit_calc(var(--animation-duration)*7)_var(--ease-in-out)_1_both]",
+  working: "ds:animate-[ai-comet-orbit_calc(var(--animation-duration)*8)_linear_infinite]",
+  landed: "ds:animate-[ai-comet-orbit_calc(var(--animation-duration)*5)_var(--ease-out)_1_both]"
+}, w = {
+  intro: "ds:[--sparkle-base:8] ds:animate-[ai-sparkle-burst_calc(var(--animation-duration)*5)_var(--ease-in-out)_1_both]",
+  working: "ds:[--sparkle-base:0] ds:animate-[ai-sparkle-twinkle_calc(var(--animation-duration)*8)_var(--ease-in-out)_infinite]",
+  landed: "ds:[--sparkle-base:6] ds:animate-[ai-sparkle-burst_calc(var(--animation-duration)*5)_var(--ease-in-out)_1_both]"
+}, s = "ds:absolute ds:opacity-0 ds:text-[color:var(--ai-sparkle)] ds:fill-current ds:drop-shadow-[0_0_var(--spacing-2xs)_var(--ai-sparkle)] ds:[animation-delay:calc(var(--animation-duration)*(var(--sparkle-base)+var(--sparkle-stagger)))]", z = [
+  {
+    key: "start",
+    className: `${s} ds:[--sparkle-stagger:0] ds:size-3 ds:[inset-block-start:calc(var(--spacing-xs)*-1)] ds:[inset-inline-start:calc(var(--spacing-2xs)*-1)]`
+  },
+  {
+    key: "top",
+    className: `${s} ds:[--sparkle-stagger:0.5] ds:size-4 ds:[inset-block-start:calc(var(--spacing-sm)*-1)] ds:[inset-inline-start:40%]`
+  },
+  {
+    key: "end",
+    className: `${s} ds:[--sparkle-stagger:1] ds:size-3 ds:[inset-block-start:calc(var(--spacing-xs)*-1)] ds:[inset-inline-end:var(--spacing-md)]`
+  },
+  {
+    key: "side",
+    className: `${s} ds:[--sparkle-stagger:1.5] ds:size-2 ds:[inset-block-start:40%] ds:[inset-inline-end:calc(var(--spacing-sm)*-1)]`
+  },
+  {
+    key: "below",
+    className: `${s} ds:[--sparkle-stagger:2] ds:size-3 ds:[inset-block-end:calc(var(--spacing-xs)*-1)] ds:[inset-inline-start:25%]`
+  }
+], h = "ds:pointer-events-none ds:absolute ds:[inset-block-start:0] ds:[inset-inline-start:0] ds:opacity-0 ds:[offset-path:inset(0_round_var(--radius-full))] ds:[offset-rotate:0deg]", C = [
+  {
+    key: 1,
+    lag: "ds:[animation-delay:calc(var(--animation-duration)*0.2)]",
+    dot: "ds:size-2.5 ds:opacity-[var(--opacity-90)]"
+  },
+  {
+    key: 2,
+    lag: "ds:[animation-delay:calc(var(--animation-duration)*0.4)]",
+    dot: "ds:size-2 ds:opacity-[var(--opacity-70)]"
+  },
+  {
+    key: 3,
+    lag: "ds:[animation-delay:calc(var(--animation-duration)*0.6)]",
+    dot: "ds:size-2 ds:opacity-[var(--opacity-50)]"
+  },
+  {
+    key: 4,
+    lag: "ds:[animation-delay:calc(var(--animation-duration)*0.8)]",
+    dot: "ds:size-1.5 ds:opacity-[var(--opacity-30)]"
+  },
+  {
+    key: 5,
+    lag: "ds:[animation-delay:calc(var(--animation-duration)*1)]",
+    dot: "ds:size-1.5 ds:opacity-[var(--opacity-20)]"
+  },
+  {
+    key: 6,
+    lag: "ds:[animation-delay:calc(var(--animation-duration)*1.2)]",
+    dot: "ds:size-1 ds:opacity-[var(--opacity-10)]"
+  }
+];
+function A(o = {}) {
+  const { enabled: r = !0, reducedMotion: d = "auto" } = o, c = k(), n = d === "off" ? !1 : c, [a, i] = v(
+    r ? "intro" : null
+  );
+  _(() => {
+    if (a !== "intro" && a !== "landed") return;
+    const t = n ? 0 : y[a], p = window.setTimeout(() => i(null), t);
+    return () => window.clearTimeout(p);
+  }, [a, n]);
+  const l = e(() => i("working"), []), m = e(() => i("landed"), []), u = e(() => {
+    i((t) => t === "working" ? null : t);
+  }, []);
+  return {
+    state: a,
+    props: {
+      "data-ai-sparkle": a ?? void 0,
+      className: a ? g[a] : ""
+    },
+    start: l,
+    land: m,
+    reset: u
+  };
+}
+export {
+  w as B,
+  C,
+  z as S,
+  h as a,
+  S as b,
+  g as c,
+  A as u
+};
+//# sourceMappingURL=use-ai-sparkle-CyQSRTCe.js.map

package/dist/agent-catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "1.44.0",
+  "packageVersion": "1.45.0",
   "components": [
     {
       "kind": "component",

package/dist/components/ai-sparkle/ai-sparkle.d.ts

@@ -0,0 +1,24 @@
+import { type AiSparkleState } from '../../hooks/use-ai-sparkle';
+export type { AiSparkleState };
+export interface AiSparkleProps {
+    /**
+     * The current phase, from `useAiSparkle`. Renders nothing when `null` —
+     * callers don't need to guard the mount themselves.
+     */
+    state: AiSparkleState | null;
+}
+/**
+ * The AI pill's comet + burst sparkle: a comet with a six-dot tail riding
+ * the host's rounded outline, plus five staggered stars that burst (intro,
+ * landed) or twinkle (working) around it.
+ *
+ * Purely decorative (`aria-hidden`) and stateless — pass the `state` from
+ * `useAiSparkle`. The shimmer layer (a light sweep across the host itself)
+ * is not part of this component: it needs no extra DOM, so it travels as
+ * a class string on `useAiSparkle(...).props.className` instead. Position
+ * this component's host with `relative` (or `absolute`) sizing that matches
+ * the surface the sparkle decorates — it fills `inset-0` of its offset
+ * parent via the comet's `offset-path`.
+ */
+export declare const AiSparkle: import("react").ForwardRefExoticComponent<AiSparkleProps & import("react").RefAttributes<HTMLSpanElement>>;
+//# sourceMappingURL=ai-sparkle.d.ts.map

package/dist/components/ai-sparkle/index.d.ts

@@ -0,0 +1,3 @@
+export { AiSparkle, type AiSparkleProps } from './ai-sparkle';
+export type { AiSparkleState } from '../../hooks/use-ai-sparkle';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/ai-sparkle/index.js

@@ -0,0 +1,5 @@
+import { A as e } from "../../_chunks/ai-sparkle-DXeP_6a0.js";
+export {
+  e as AiSparkle
+};
+//# sourceMappingURL=index.js.map

package/dist/components/index.d.ts

@@ -1,5 +1,5 @@
-export { usePrefersReducedMotion, useMediaQuery, useScrollToFirstError, useLocale, useTheme, resolveTheme, themeClassList, THEME_CLASS, THEME_STORAGE_KEY, ACCESSIBILITY_STORAGE_KEY, useSigningSession, useZoomDrilldown, ZOOM_DRILLDOWN_TRANSITION_CLASS, } from '../hooks';
-export type { LocaleDir, UseLocaleReturn, UseScrollToFirstErrorOptions, ThemePreference, AccessibilityPreference, ResolvedTheme, UseThemeReturn, SigningField, SigningFieldBase, UseSigningSessionReturn, UseZoomDrilldownOptions, UseZoomDrilldownReturn, } from '../hooks';
+export { usePrefersReducedMotion, useMediaQuery, useScrollToFirstError, useLocale, useTheme, resolveTheme, themeClassList, THEME_CLASS, THEME_STORAGE_KEY, ACCESSIBILITY_STORAGE_KEY, useSigningSession, useZoomDrilldown, ZOOM_DRILLDOWN_TRANSITION_CLASS, useAiSparkle, } from '../hooks';
+export type { LocaleDir, UseLocaleReturn, UseScrollToFirstErrorOptions, ThemePreference, AccessibilityPreference, ResolvedTheme, UseThemeReturn, SigningField, SigningFieldBase, UseSigningSessionReturn, UseZoomDrilldownOptions, UseZoomDrilldownReturn, AiSparkleState, UseAiSparkleOptions, UseAiSparkleReturn, } from '../hooks';
 export * from './button';
 export * from './button-group';
 export * from './floating-action-button';
@@ -161,6 +161,7 @@ export * from './unit-converter';
 export * from './visually-hidden';
 export * from './chart';
 export * from './ai-prompt-input';
+export * from './ai-sparkle';
 export * from './audio-recorder';
 export * from './audio-visualiser';
 export * from './chat-container';

package/dist/components/notes-panel/index.js

@@ -1,4 +1,4 @@
-import { N as a } from "../../_chunks/notes-panel-CY4KmDo-.js";
+import { N as a } from "../../_chunks/notes-panel-Dkk9QPPX.js";
 export {
   a as NotesPanel
 };

package/dist/components/rich-text-editor/index.js

@@ -1,4 +1,4 @@
-import { R as a, r as e, w as i } from "../../_chunks/rich-text-editor-BYE6kK4u.js";
+import { R as a, r as e, w as i } from "../../_chunks/rich-text-editor-BrAvNajV.js";
 export {
   a as RichTextEditor,
   e as richTextEditorAgent,

package/dist/hooks/index.d.ts

@@ -30,4 +30,5 @@ export { usePresenceTransition, type PresencePhase, type UsePresenceTransitionOp
 export { useListReflow, REFLOW_ROW_CLASS, type UseListReflowOptions, type UseListReflowReturn, } from './use-list-reflow';
 export { useClampOverflow } from './use-clamp-overflow';
 export { useScrollOverflow, type UseScrollOverflowReturn, } from './use-scroll-overflow';
+export { useAiSparkle, SHIMMER_CLASS as AI_SPARKLE_SHIMMER_CLASS, COMET_CLASS as AI_SPARKLE_COMET_CLASS, BURST_CLASS as AI_SPARKLE_BURST_CLASS, SPARKLE_GLYPHS as AI_SPARKLE_GLYPHS, COMET_TAIL as AI_SPARKLE_COMET_TAIL, COMET_WRAPPER_CLASS as AI_SPARKLE_COMET_WRAPPER_CLASS, type AiSparkleState, type UseAiSparkleOptions, type UseAiSparkleProps, type UseAiSparkleReturn, } from './use-ai-sparkle';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.js

@@ -1,40 +1,41 @@
-import { u as h } from "../_chunks/use-prefers-reduced-motion-BMwIQRjB.js";
-import { u as y } from "../_chunks/use-media-query-CcAx5SMM.js";
-import { Z as D, u as R, a as _, b as F } from "../_chunks/use-zoom-drilldown-qCX34w9I.js";
-import { u as g } from "../_chunks/use-count-up-BLLetaZ8.js";
-import { u as k } from "../_chunks/use-locale-BkCIHujH.js";
-import { A as M, T as V, a as W, r as H, t as N, u as Y } from "../_chunks/use-theme-CAuo6EYT.js";
-import { u as q } from "../_chunks/use-controllable-state-BiY4xTzM.js";
-import { u as G } from "../_chunks/use-copy-to-clipboard-Cyfc_dlv.js";
+import { u as R } from "../_chunks/use-prefers-reduced-motion-BMwIQRjB.js";
+import { u as I } from "../_chunks/use-media-query-CcAx5SMM.js";
+import { Z as h, u as v, a as y, b as w } from "../_chunks/use-zoom-drilldown-qCX34w9I.js";
+import { u as K } from "../_chunks/use-count-up-BLLetaZ8.js";
+import { u as M } from "../_chunks/use-locale-BkCIHujH.js";
+import { A as k, T as H, a as W, r as B, t as V, u as Y } from "../_chunks/use-theme-CAuo6EYT.js";
+import { u as N } from "../_chunks/use-controllable-state-BiY4xTzM.js";
+import { u as Z } from "../_chunks/use-copy-to-clipboard-Cyfc_dlv.js";
 import { u as j } from "../_chunks/use-debounced-callback-BisrB-Fq.js";
-import { useState as b, useRef as x, useEffect as E } from "react";
+import { useState as A, useRef as S, useEffect as E } from "react";
 import { u as Q, a as J } from "../_chunks/use-direction-Dp8h70PP.js";
 import { u as $ } from "../_chunks/use-persistent-state-nZwZAnE9.js";
 import { u as te } from "../_chunks/use-isomorphic-layout-effect-BGfaCOP1.js";
-import { u as oe, a as ue } from "../_chunks/use-scroll-overflow-UbLrUfBo.js";
+import { u as oe, a as se } from "../_chunks/use-scroll-overflow-UbLrUfBo.js";
 import { c as ne, u as ae } from "../_chunks/use-priority-overflow-c9SjxZkZ.js";
 import { u as ce } from "../_chunks/use-web-otp-D_utzp6S.js";
 import { u as fe } from "../_chunks/use-visual-viewport-pin-ChurOsHM.js";
 import { u as de } from "../_chunks/use-edge-resize-BHesP0kg.js";
-import { u as xe } from "../_chunks/use-countdown-Yd6ts0_a.js";
-import { u as be } from "../_chunks/use-check-animation--I3cS00X.js";
-import { R as Te, u as Ce, a as Le } from "../_chunks/use-list-reflow-Cw43nxw5.js";
-import { u as Oe } from "../_chunks/use-presence-transition-cDwWUXV-.js";
-import { u as ve } from "../_chunks/use-clamp-overflow-DQE2kwZ9.js";
-function C(e, o) {
-  const [t, i] = b(e), u = x(null);
+import { u as Se } from "../_chunks/use-countdown-Yd6ts0_a.js";
+import { u as Ae } from "../_chunks/use-check-animation--I3cS00X.js";
+import { R as Le, u as _e, a as Ce } from "../_chunks/use-list-reflow-Cw43nxw5.js";
+import { u as be } from "../_chunks/use-presence-transition-cDwWUXV-.js";
+import { u as Oe } from "../_chunks/use-clamp-overflow-DQE2kwZ9.js";
+import { B as Pe, b as he, C as ve, a as ye, S as we, c as De, u as Ke } from "../_chunks/use-ai-sparkle-CyQSRTCe.js";
+function _(e, o) {
+  const [t, i] = A(e), s = S(null);
   return E(() => {
     if (o <= 0) {
-      u.current !== null && (clearTimeout(u.current), u.current = null), i(e);
+      s.current !== null && (clearTimeout(s.current), s.current = null), i(e);
       return;
     }
     const n = setTimeout(() => {
-      i(e), u.current = null;
+      i(e), s.current = null;
     }, o);
-    return u.current = n, () => clearTimeout(n);
+    return s.current = n, () => clearTimeout(n);
   }, [e, o]), t;
 }
-const S = [
+const x = [
   "a[href]",
   "button:not([disabled])",
   'input:not([disabled]):not([type="hidden"])',
@@ -47,7 +48,7 @@ const S = [
 ].join(",");
 function p(e) {
   return Array.from(
-    e.querySelectorAll(S)
+    e.querySelectorAll(x)
   ).filter((o) => {
     if (o.hidden) return !1;
     let t = o;
@@ -58,75 +59,82 @@ function p(e) {
     return !0;
   });
 }
-function L(e, o = {}) {
-  const { enabled: t = !0, autoFocus: i = !0, restoreFocus: u = !0 } = o, n = x(null);
+function C(e, o = {}) {
+  const { enabled: t = !0, autoFocus: i = !0, restoreFocus: s = !0 } = o, n = S(null);
   E(() => {
     if (!t) return;
     const a = e.current;
     if (!a) return;
     if (n.current = typeof document < "u" && document.activeElement instanceof HTMLElement ? document.activeElement : null, i) {
-      const s = p(a)[0] ?? (a.tabIndex >= -1 ? a : null);
-      s == null || s.focus();
+      const u = p(a)[0] ?? (a.tabIndex >= -1 ? a : null);
+      u == null || u.focus();
     }
     function f(r) {
       if (r.key !== "Tab") return;
-      const s = e.current;
-      if (!s) return;
-      const c = p(s);
+      const u = e.current;
+      if (!u) return;
+      const c = p(u);
       if (c.length === 0) {
         r.preventDefault();
         return;
       }
       const m = c[0], d = c[c.length - 1], l = document.activeElement;
-      r.shiftKey ? (l === m || !s.contains(l)) && (r.preventDefault(), d.focus()) : (l === d || !s.contains(l)) && (r.preventDefault(), m.focus());
+      r.shiftKey ? (l === m || !u.contains(l)) && (r.preventDefault(), d.focus()) : (l === d || !u.contains(l)) && (r.preventDefault(), m.focus());
     }
     return a.addEventListener("keydown", f), () => {
-      if (a.removeEventListener("keydown", f), u && n.current) {
+      if (a.removeEventListener("keydown", f), s && n.current) {
         const r = n.current;
         requestAnimationFrame(() => {
           r.isConnected && r.focus();
         });
       }
     };
-  }, [t, i, u, e]);
+  }, [t, i, s, e]);
 }
 export {
-  M as ACCESSIBILITY_STORAGE_KEY,
-  Te as REFLOW_ROW_CLASS,
-  V as THEME_CLASS,
+  k as ACCESSIBILITY_STORAGE_KEY,
+  Pe as AI_SPARKLE_BURST_CLASS,
+  he as AI_SPARKLE_COMET_CLASS,
+  ve as AI_SPARKLE_COMET_TAIL,
+  ye as AI_SPARKLE_COMET_WRAPPER_CLASS,
+  we as AI_SPARKLE_GLYPHS,
+  De as AI_SPARKLE_SHIMMER_CLASS,
+  Le as REFLOW_ROW_CLASS,
+  H as THEME_CLASS,
   W as THEME_STORAGE_KEY,
-  D as ZOOM_DRILLDOWN_TRANSITION_CLASS,
+  h as ZOOM_DRILLDOWN_TRANSITION_CLASS,
   ne as computePriorityLayout,
-  H as resolveTheme,
-  N as themeClassList,
-  be as useCheckAnimation,
-  ve as useClampOverflow,
-  q as useControllableState,
-  G as useCopyToClipboard,
-  g as useCountUp,
-  xe as useCountdown,
+  B as resolveTheme,
+  V as themeClassList,
+  Ke as useAiSparkle,
+  Ae as useCheckAnimation,
+  Oe as useClampOverflow,
+  N as useControllableState,
+  Z as useCopyToClipboard,
+  K as useCountUp,
+  Se as useCountdown,
   j as useDebouncedCallback,
-  C as useDebouncedValue,
+  _ as useDebouncedValue,
   Q as useDirection,
   J as useDocumentDirection,
   de as useEdgeResize,
-  Ce as useExitTransition,
-  L as useFocusTrap,
+  _e as useExitTransition,
+  C as useFocusTrap,
   te as useIsomorphicLayoutEffect,
-  Le as useListReflow,
-  k as useLocale,
-  y as useMediaQuery,
+  Ce as useListReflow,
+  M as useLocale,
+  I as useMediaQuery,
   oe as useOverflowCollapse,
   $ as usePersistentState,
-  h as usePrefersReducedMotion,
-  Oe as usePresenceTransition,
+  R as usePrefersReducedMotion,
+  be as usePresenceTransition,
   ae as usePriorityOverflow,
-  ue as useScrollOverflow,
-  R as useScrollToFirstError,
-  _ as useSigningSession,
+  se as useScrollOverflow,
+  v as useScrollToFirstError,
+  y as useSigningSession,
   Y as useTheme,
   fe as useVisualViewportPin,
   ce as useWebOtp,
-  F as useZoomDrilldown
+  w as useZoomDrilldown
 };
 //# sourceMappingURL=index.js.map

package/dist/hooks/use-ai-sparkle.d.ts

@@ -0,0 +1,109 @@
+/** Where the sparkle is: on first show, while an action runs, as it lands. */
+export type AiSparkleState = 'intro' | 'working' | 'landed';
+export declare const SHIMMER_CLASS: Record<AiSparkleState, string>;
+export declare const COMET_CLASS: Record<AiSparkleState, string>;
+export declare const BURST_CLASS: Record<AiSparkleState, string>;
+export declare const SPARKLE_GLYPHS: readonly [{
+    readonly key: "start";
+    readonly className: "ds:absolute ds:opacity-0 ds:text-[color:var(--ai-sparkle)] ds:fill-current ds:drop-shadow-[0_0_var(--spacing-2xs)_var(--ai-sparkle)] ds:[animation-delay:calc(var(--animation-duration)*(var(--sparkle-base)+var(--sparkle-stagger)))] ds:[--sparkle-stagger:0] ds:size-3 ds:[inset-block-start:calc(var(--spacing-xs)*-1)] ds:[inset-inline-start:calc(var(--spacing-2xs)*-1)]";
+}, {
+    readonly key: "top";
+    readonly className: "ds:absolute ds:opacity-0 ds:text-[color:var(--ai-sparkle)] ds:fill-current ds:drop-shadow-[0_0_var(--spacing-2xs)_var(--ai-sparkle)] ds:[animation-delay:calc(var(--animation-duration)*(var(--sparkle-base)+var(--sparkle-stagger)))] ds:[--sparkle-stagger:0.5] ds:size-4 ds:[inset-block-start:calc(var(--spacing-sm)*-1)] ds:[inset-inline-start:40%]";
+}, {
+    readonly key: "end";
+    readonly className: "ds:absolute ds:opacity-0 ds:text-[color:var(--ai-sparkle)] ds:fill-current ds:drop-shadow-[0_0_var(--spacing-2xs)_var(--ai-sparkle)] ds:[animation-delay:calc(var(--animation-duration)*(var(--sparkle-base)+var(--sparkle-stagger)))] ds:[--sparkle-stagger:1] ds:size-3 ds:[inset-block-start:calc(var(--spacing-xs)*-1)] ds:[inset-inline-end:var(--spacing-md)]";
+}, {
+    readonly key: "side";
+    readonly className: "ds:absolute ds:opacity-0 ds:text-[color:var(--ai-sparkle)] ds:fill-current ds:drop-shadow-[0_0_var(--spacing-2xs)_var(--ai-sparkle)] ds:[animation-delay:calc(var(--animation-duration)*(var(--sparkle-base)+var(--sparkle-stagger)))] ds:[--sparkle-stagger:1.5] ds:size-2 ds:[inset-block-start:40%] ds:[inset-inline-end:calc(var(--spacing-sm)*-1)]";
+}, {
+    readonly key: "below";
+    readonly className: "ds:absolute ds:opacity-0 ds:text-[color:var(--ai-sparkle)] ds:fill-current ds:drop-shadow-[0_0_var(--spacing-2xs)_var(--ai-sparkle)] ds:[animation-delay:calc(var(--animation-duration)*(var(--sparkle-base)+var(--sparkle-stagger)))] ds:[--sparkle-stagger:2] ds:size-3 ds:[inset-block-end:calc(var(--spacing-xs)*-1)] ds:[inset-inline-start:25%]";
+}];
+export declare const COMET_WRAPPER_CLASS = "ds:pointer-events-none ds:absolute ds:[inset-block-start:0] ds:[inset-inline-start:0] ds:opacity-0 ds:[offset-path:inset(0_round_var(--radius-full))] ds:[offset-rotate:0deg]";
+export declare const COMET_TAIL: readonly [{
+    readonly key: 1;
+    readonly lag: "ds:[animation-delay:calc(var(--animation-duration)*0.2)]";
+    readonly dot: "ds:size-2.5 ds:opacity-[var(--opacity-90)]";
+}, {
+    readonly key: 2;
+    readonly lag: "ds:[animation-delay:calc(var(--animation-duration)*0.4)]";
+    readonly dot: "ds:size-2 ds:opacity-[var(--opacity-70)]";
+}, {
+    readonly key: 3;
+    readonly lag: "ds:[animation-delay:calc(var(--animation-duration)*0.6)]";
+    readonly dot: "ds:size-2 ds:opacity-[var(--opacity-50)]";
+}, {
+    readonly key: 4;
+    readonly lag: "ds:[animation-delay:calc(var(--animation-duration)*0.8)]";
+    readonly dot: "ds:size-1.5 ds:opacity-[var(--opacity-30)]";
+}, {
+    readonly key: 5;
+    readonly lag: "ds:[animation-delay:calc(var(--animation-duration)*1)]";
+    readonly dot: "ds:size-1.5 ds:opacity-[var(--opacity-20)]";
+}, {
+    readonly key: 6;
+    readonly lag: "ds:[animation-delay:calc(var(--animation-duration)*1.2)]";
+    readonly dot: "ds:size-1 ds:opacity-[var(--opacity-10)]";
+}];
+export interface UseAiSparkleOptions {
+    /**
+     * Whether the sparkle is available at all. Read once, at mount, to seed
+     * the initial `'intro'` phase — matches how the RichTextEditor's
+     * `aiSparkle` prop only ever gated the very first render. Default `true`.
+     */
+    enabled?: boolean;
+    /**
+     * `'auto'` (default) reads `prefers-reduced-motion` via
+     * `usePrefersReducedMotion`. `'off'` forces full motion regardless of the
+     * OS preference — useful for a story that wants to show the animated
+     * states side by side with a reduced one.
+     */
+    reducedMotion?: 'auto' | 'off';
+}
+export interface UseAiSparkleProps {
+    /** Spread (or picked) onto the host element as a pure styling hook. */
+    'data-ai-sparkle': AiSparkleState | undefined;
+    /**
+     * The shimmer animation class for the current state — empty when at rest.
+     * Layer it over the host's own base positioning classes; the comet and
+     * burst layers need real DOM and live in the `AiSparkle` component instead.
+     */
+    className: string;
+}
+export interface UseAiSparkleReturn {
+    /** `null` at rest — nothing to render for the comet/burst layers either. */
+    state: AiSparkleState | null;
+    props: UseAiSparkleProps;
+    /** An AI action started: swap to the looping `'working'` phase. */
+    start: () => void;
+    /** An action's result landed: swap to the one-off `'landed'` phase. */
+    land: () => void;
+    /**
+     * Settle after an action ends. Clears back to rest only when still
+     * `'working'` (the action errored or was cancelled before `land()`);
+     * leaves `'landed'` alone so the one-off animation gets to play out.
+     */
+    reset: () => void;
+}
+/**
+ * Drives the AI-pill sparkle: lit on first show, looping while an action
+ * runs, and a one-off flourish as the result lands.
+ *
+ * The hook owns the state machine and the timing only — it paints nothing.
+ * `props['data-ai-sparkle']` is a plain styling hook for the host element;
+ * `props.className` carries the shimmer layer's animation class from the
+ * same lookup table the RichTextEditor's pill originally inlined. The
+ * comet and burst layers need actual DOM (a tail of dots, five staggered
+ * glyphs), so they live in the sibling `AiSparkle` component, keyed off the
+ * same `state`.
+ *
+ * Both `intro` and `landed` are one-off: this hook clears them back to
+ * `null` on a timer sized to the comet's lap plus the burst and its
+ * stagger, at the default 200ms `--animation-duration`. Under reduced
+ * motion (`prefers-reduced-motion` or `reducedMotion: 'auto'`'s system
+ * read) the CSS animations already collapse to 0ms, so the clear fires at
+ * the next tick instead of waiting out the full lap — the pill still gets
+ * its `data-ai-sparkle` attribute for a moment, but nothing visibly moves.
+ */
+export declare function useAiSparkle(options?: UseAiSparkleOptions): UseAiSparkleReturn;
+//# sourceMappingURL=use-ai-sparkle.d.ts.map