@nebutra/ui 0.2.1 → 0.2.2

package/dist/hooks/index.d.ts

@@ -1,8 +1,9 @@
-import { HTMLMotionProps } from 'framer-motion';
 import * as React from 'react';
 import { RefObject } from 'react';
+import { HTMLMotionProps } from 'framer-motion';
 
-interface DwellHintProps extends Omit<HTMLMotionProps<"div">, "children" | "initial" | "animate" | "exit" | "transition"> {
+type DwellHintPosition = "top" | "bottom" | "center";
+interface DwellHintProps extends Omit<HTMLMotionProps<"div">, "children" | "initial" | "animate" | "exit" | "transition" | "position"> {
     /** Whether the hint is visible */
     show: boolean;
     /** The hint message to display */
@@ -10,27 +11,73 @@ interface DwellHintProps extends Omit<HTMLMotionProps<"div">, "children" | "init
     /** Optional icon to display before the message */
     icon?: React.ReactNode;
     /** Position of the hint relative to content (default: "bottom") */
-    position?: "top" | "bottom" | "center";
+    position?: DwellHintPosition;
 }
+declare const DwellHint: React.ForwardRefExoticComponent<Omit<DwellHintProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
 /**
- * DwellHint - A contextual hint that appears when user dwells on content.
+ * Debounced Refresh Hook
  *
- * Use with useScrollDwell hook to show helpful messages when users
- * pause scrolling and appear to be reading content.
+ * Wraps usehooks-ts (already a workspace dependency) so the rest of the
+ * monorepo gets a single canonical debounced hook surface:
+ * - cancellable
+ * - configurable delay
+ * - leading / trailing modes
+ */
+type DebouncedRefreshResult = {
+    schedule: () => void;
+    cancel: () => void;
+    isPending: () => boolean;
+    flush: () => void;
+};
+/**
+ * 防抖刷新 Hook
+ *
+ * 用于限制频繁触发的刷新操作
+ *
+ * @param callback - 要执行的回调函数
+ * @param delay - 延迟时间 (毫秒)
+ * @returns 控制对象 { schedule, cancel, isPending, flush }
  *
  * @example
- * const { hasTriggered } = useScrollDwell(sectionRef, { threshold: 1000 });
+ * const { schedule, cancel } = useDebouncedRefresh(() => {
+ *   refetch();
+ * }, 400);
  *
- * <DwellHint
- *   show={hasTriggered}
- *   message="This is why production-ready matters."
- *   icon={<Lightbulb className="w-4 h-4" />}
- * />
+ * // 在数据变化时调用
+ * useEffect(() => {
+ *   schedule();
+ * }, [data]);
  */
-declare const DwellHint: React.ForwardRefExoticComponent<Omit<DwellHintProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare function useDebouncedRefresh(callback: () => void, delay?: number): DebouncedRefreshResult;
+/**
+ * 防抖值 Hook
+ *
+ * Thin wrapper over usehooks-ts useDebounceValue so consumers can import
+ * the canonical hook from @nebutra/ui/hooks alongside useDebouncedRefresh.
+ *
+ * @param value - 要防抖的值
+ * @param delay - 延迟时间 (毫秒)
+ * @returns 防抖后的值
+ *
+ * @example
+ * const [searchTerm, setSearchTerm] = useState("");
+ * const debouncedSearch = useDebouncedValue(searchTerm, 300);
+ *
+ * useEffect(() => {
+ *   if (debouncedSearch) {
+ *     performSearch(debouncedSearch);
+ *   }
+ * }, [debouncedSearch]);
+ */
+declare function useDebouncedValue<T>(value: T, delay?: number): T;
 
 /**
- * Hook to detect media query matches
+ * Hook to detect media query matches.
+ *
+ * Delegates to usehooks-ts `useMediaQuery` with `initializeWithValue: false`
+ * so the initial render always returns `false` — SSR-safe, matching the
+ * previous hand-rolled behaviour (no `window` access during SSR/hydration).
  *
  * @example
  * ```tsx
@@ -103,4 +150,4 @@ interface DwellState {
  */
 declare function useScrollDwell(ref: RefObject<HTMLElement | null>, config?: DwellConfig): DwellState;
 
-export { type DwellConfig, DwellHint, type DwellHintProps, type DwellState, useMediaQuery, useReducedMotion, useScrollDwell };
+export { type DwellConfig, DwellHint, type DwellHintProps, type DwellState, useDebouncedRefresh, useDebouncedValue, useMediaQuery, useReducedMotion, useScrollDwell };

package/dist/hooks/index.js

@@ -1,39 +1,42 @@
 "use client";
-import { AnimatePresence, motion, useReducedMotion as useReducedMotion$1 } from 'framer-motion';
-import * as React2 from 'react';
-import { useState, useRef, useCallback, useEffect } from 'react';
+import * as React from 'react';
+import { useRef, useEffect, useCallback, useState } from 'react';
+import { useReducedMotion, AnimatePresence, motion } from 'framer-motion';
 import { clsx } from 'clsx';
 import { twMerge } from 'tailwind-merge';
 import { jsx, jsxs } from 'react/jsx-runtime';
+import { useDebounceCallback, useDebounceValue, useMediaQuery as useMediaQuery$1 } from 'usehooks-ts';
 
 // src/hooks/DwellHint.tsx
 function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
-var DwellHint = React2.forwardRef(
+var POSITION_CLASSES = {
+  top: "top-0 -translate-y-full mb-2",
+  bottom: "bottom-0 translate-y-full mt-2",
+  center: "top-1/2 -translate-y-1/2"
+};
+var DwellHint = React.forwardRef(
   ({ show, message, icon, position = "bottom", className, ...props }, ref) => {
-    const positionClasses = {
-      top: "top-0 -translate-y-full mb-2",
-      bottom: "bottom-0 translate-y-full mt-2",
-      center: "top-1/2 -translate-y-1/2"
-    };
-    return /* @__PURE__ */ jsx(AnimatePresence, { children: show && /* @__PURE__ */ jsx(
+    const shouldReduceMotion = useReducedMotion();
+    const resolvedPosition = position ?? "bottom";
+    return /* @__PURE__ */ jsx(AnimatePresence, { initial: !shouldReduceMotion, children: show && /* @__PURE__ */ jsx(
       motion.div,
       {
         ref,
         className: cn(
           "absolute left-1/2 -translate-x-1/2 z-10",
-          positionClasses[position],
+          POSITION_CLASSES[resolvedPosition],
           className
         ),
-        initial: {
+        initial: shouldReduceMotion ? { opacity: 1 } : {
           opacity: 0,
-          y: position === "top" ? -10 : 10,
+          y: resolvedPosition === "top" ? -10 : 10,
           scale: 0.95
         },
-        animate: { opacity: 1, y: 0, scale: 1 },
-        exit: { opacity: 0, y: position === "top" ? -5 : 5, scale: 0.98 },
-        transition: {
+        animate: shouldReduceMotion ? { opacity: 1 } : { opacity: 1, y: 0, scale: 1 },
+        exit: shouldReduceMotion ? { opacity: 0 } : { opacity: 0, y: resolvedPosition === "top" ? -5 : 5, scale: 0.98 },
+        transition: shouldReduceMotion ? { duration: 0 } : {
           duration: 0.4,
           ease: [0.34, 1.56, 0.64, 1]
         },
@@ -59,25 +62,44 @@ var DwellHint = React2.forwardRef(
   }
 );
 DwellHint.displayName = "DwellHint";
+function useDebouncedRefresh(callback, delay = 400) {
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  const debounced = useDebounceCallback(
+    () => {
+      callbackRef.current();
+    },
+    delay,
+    { leading: false, trailing: true }
+  );
+  const schedule = useCallback(() => {
+    debounced();
+  }, [debounced]);
+  const cancel = useCallback(() => {
+    debounced.cancel();
+  }, [debounced]);
+  const isPending = useCallback(() => {
+    return debounced.isPending();
+  }, [debounced]);
+  const flush = useCallback(() => {
+    debounced.flush();
+  }, [debounced]);
+  useEffect(() => cancel, [cancel]);
+  return { schedule, cancel, isPending, flush };
+}
+function useDebouncedValue(value, delay = 500) {
+  const [debouncedValue] = useDebounceValue(value, delay);
+  return debouncedValue;
+}
 function useMediaQuery(query) {
-  const [matches, setMatches] = React2.useState(false);
-  React2.useEffect(() => {
-    const media = window.matchMedia(query);
-    if (media.matches !== matches) {
-      setMatches(media.matches);
-    }
-    const listener = (event) => {
-      setMatches(event.matches);
-    };
-    media.addEventListener("change", listener);
-    return () => {
-      media.removeEventListener("change", listener);
-    };
-  }, [matches, query]);
-  return matches;
+  return useMediaQuery$1(query, { initializeWithValue: false });
 }
-function useReducedMotion() {
-  return useReducedMotion$1() ?? false;
+
+// src/hooks/use-reduced-motion.ts
+function useReducedMotion2() {
+  return useReducedMotion() ?? false;
 }
 function useScrollDwell(ref, config = {}) {
   const { threshold = 800, cooldown = 5e3, onDwell, requireVisible = true } = config;
@@ -177,6 +199,6 @@ function useScrollDwell(ref, config = {}) {
   };
 }
 
-export { DwellHint, useMediaQuery, useReducedMotion, useScrollDwell };
+export { DwellHint, useDebouncedRefresh, useDebouncedValue, useMediaQuery, useReducedMotion2 as useReducedMotion, useScrollDwell };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/cn.ts","../../src/hooks/DwellHint.tsx","../../src/hooks/use-media-query.ts","../../src/hooks/use-reduced-motion.ts","../../src/hooks/useScrollDwell.ts"],"names":["React","useFramerReducedMotion","useState","useEffect"],"mappings":"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","file":"index.js","sourcesContent":["import { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n","\"use client\";\n\nimport { AnimatePresence, type HTMLMotionProps, motion } from \"framer-motion\";\nimport * as React from \"react\";\nimport { cn } from \"../utils/cn\";\n\nexport interface DwellHintProps\n  extends Omit<HTMLMotionProps<\"div\">, \"children\" | \"initial\" | \"animate\" | \"exit\" | \"transition\"> {\n  /** Whether the hint is visible */\n  show: boolean;\n  /** The hint message to display */\n  message: string;\n  /** Optional icon to display before the message */\n  icon?: React.ReactNode;\n  /** Position of the hint relative to content (default: \"bottom\") */\n  position?: \"top\" | \"bottom\" | \"center\";\n}\n\n/**\n * DwellHint - A contextual hint that appears when user dwells on content.\n *\n * Use with useScrollDwell hook to show helpful messages when users\n * pause scrolling and appear to be reading content.\n *\n * @example\n * const { hasTriggered } = useScrollDwell(sectionRef, { threshold: 1000 });\n *\n * <DwellHint\n *   show={hasTriggered}\n *   message=\"This is why production-ready matters.\"\n *   icon={<Lightbulb className=\"w-4 h-4\" />}\n * />\n */\nexport const DwellHint = React.forwardRef<HTMLDivElement, DwellHintProps>(\n  ({ show, message, icon, position = \"bottom\", className, ...props }, ref) => {\n    const positionClasses = {\n      top: \"top-0 -translate-y-full mb-2\",\n      bottom: \"bottom-0 translate-y-full mt-2\",\n      center: \"top-1/2 -translate-y-1/2\",\n    };\n\n    return (\n      <AnimatePresence>\n        {show && (\n          <motion.div\n            ref={ref}\n            className={cn(\n              \"absolute left-1/2 -translate-x-1/2 z-10\",\n              positionClasses[position],\n              className,\n            )}\n            initial={{\n              opacity: 0,\n              y: position === \"top\" ? -10 : 10,\n              scale: 0.95,\n            }}\n            animate={{ opacity: 1, y: 0, scale: 1 }}\n            exit={{ opacity: 0, y: position === \"top\" ? -5 : 5, scale: 0.98 }}\n            transition={{\n              duration: 0.4,\n              ease: [0.34, 1.56, 0.64, 1],\n            }}\n            {...props}\n          >\n            <div\n              className={cn(\n                \"flex items-center gap-2 px-4 py-2.5\",\n                \"bg-background/95 backdrop-blur-md\",\n                \"border border-border/50 rounded-[var(--radius-lg)]\",\n                \"shadow-lg shadow-black/5\",\n                \"text-sm text-muted-foreground\",\n              )}\n            >\n              {icon && <span className=\"text-primary/70 shrink-0\">{icon}</span>}\n              <span>{message}</span>\n            </div>\n          </motion.div>\n        )}\n      </AnimatePresence>\n    );\n  },\n);\n\nDwellHint.displayName = \"DwellHint\";\n","import * as React from \"react\";\n\n/**\n * Hook to detect media query matches\n *\n * @example\n * ```tsx\n * const isMobile = useMediaQuery(\"(max-width: 768px)\");\n * const prefersDark = useMediaQuery(\"(prefers-color-scheme: dark)\");\n * ```\n */\nexport function useMediaQuery(query: string): boolean {\n  const [matches, setMatches] = React.useState(false);\n\n  React.useEffect(() => {\n    const media = window.matchMedia(query);\n\n    // Set initial value\n    if (media.matches !== matches) {\n      setMatches(media.matches);\n    }\n\n    // Create listener\n    const listener = (event: MediaQueryListEvent) => {\n      setMatches(event.matches);\n    };\n\n    // Add listener\n    media.addEventListener(\"change\", listener);\n\n    // Cleanup\n    return () => {\n      media.removeEventListener(\"change\", listener);\n    };\n  }, [matches, query]);\n\n  return matches;\n}\n","\"use client\";\n\nimport { useReducedMotion as useFramerReducedMotion } from \"framer-motion\";\n\n/**\n * Returns true if the user has enabled prefers-reduced-motion.\n * Use this to disable animations, skip transitions, or simplify motion.\n *\n * Wraps framer-motion's `useReducedMotion` so callers don't need framer-motion\n * as a direct import just for accessibility checks.\n *\n * @example\n * const shouldReduce = useReducedMotion();\n * const transition = shouldReduce ? { duration: 0 } : brandSpring.default;\n */\nexport function useReducedMotion(): boolean {\n  return useFramerReducedMotion() ?? false;\n}\n","\"use client\";\n\nimport { type RefObject, useCallback, useEffect, useRef, useState } from \"react\";\n\nexport interface DwellConfig {\n  /** Time in ms before dwell is triggered (default: 800) */\n  threshold?: number;\n  /** Cooldown in ms between triggers (default: 5000) */\n  cooldown?: number;\n  /** Callback when dwell is detected */\n  onDwell?: () => void;\n  /** Only trigger when element is in viewport (default: true) */\n  requireVisible?: boolean;\n}\n\nexport interface DwellState {\n  /** Whether the user is currently dwelling */\n  isDwelling: boolean;\n  /** Progress toward trigger threshold (0-1) */\n  dwellProgress: number;\n  /** Whether dwell was triggered (resets after cooldown) */\n  hasTriggered: boolean;\n  /** Manually reset the triggered state */\n  reset: () => void;\n}\n\n/**\n * useScrollDwell - Detects when a user pauses scrolling over an element.\n *\n * This hook monitors scroll activity and detects \"dwell\" behavior where\n * the user stops scrolling for a specified duration. Useful for showing\n * contextual hints, tooltips, or triggering animations when a user\n * appears to be reading or studying content.\n *\n * @param ref - Reference to the element to monitor\n * @param config - Configuration options\n * @returns DwellState object with current dwell status\n *\n * @example\n * function FeatureSection() {\n *   const sectionRef = useRef<HTMLDivElement>(null);\n *   const { isDwelling, hasTriggered } = useScrollDwell(sectionRef, {\n *     threshold: 1000,\n *     cooldown: 10000,\n *     onDwell: () => console.log(\"User is reading this section\"),\n *   });\n *\n *   return (\n *     <div ref={sectionRef}>\n *       {hasTriggered && <DwellHint message=\"Take a closer look!\" />}\n *     </div>\n *   );\n * }\n */\nexport function useScrollDwell(\n  ref: RefObject<HTMLElement | null>,\n  config: DwellConfig = {},\n): DwellState {\n  const { threshold = 800, cooldown = 5000, onDwell, requireVisible = true } = config;\n\n  const [isDwelling, setIsDwelling] = useState(false);\n  const [dwellProgress, setDwellProgress] = useState(0);\n  const [hasTriggered, setHasTriggered] = useState(false);\n\n  const dwellTimerRef = useRef<NodeJS.Timeout | null>(null);\n  const progressIntervalRef = useRef<NodeJS.Timeout | null>(null);\n  const cooldownTimerRef = useRef<NodeJS.Timeout | null>(null);\n  const lastScrollTimeRef = useRef<number>(Date.now());\n  const isInCooldownRef = useRef(false);\n\n  const clearTimers = useCallback(() => {\n    if (dwellTimerRef.current) {\n      clearTimeout(dwellTimerRef.current);\n      dwellTimerRef.current = null;\n    }\n    if (progressIntervalRef.current) {\n      clearInterval(progressIntervalRef.current);\n      progressIntervalRef.current = null;\n    }\n  }, []);\n\n  const reset = useCallback(() => {\n    setHasTriggered(false);\n    setIsDwelling(false);\n    setDwellProgress(0);\n    isInCooldownRef.current = false;\n    if (cooldownTimerRef.current) {\n      clearTimeout(cooldownTimerRef.current);\n      cooldownTimerRef.current = null;\n    }\n  }, []);\n\n  const isElementVisible = useCallback(() => {\n    if (!ref.current) return false;\n    const rect = ref.current.getBoundingClientRect();\n    const windowHeight = window.innerHeight;\n\n    // Element is visible if at least 50% is in viewport\n    const visibleHeight = Math.min(rect.bottom, windowHeight) - Math.max(rect.top, 0);\n    const elementHeight = rect.height;\n\n    return visibleHeight / elementHeight > 0.5;\n  }, [ref]);\n\n  const startDwellTimer = useCallback(() => {\n    if (isInCooldownRef.current || hasTriggered) return;\n    if (requireVisible && !isElementVisible()) return;\n\n    clearTimers();\n\n    // Start progress tracking\n    const startTime = Date.now();\n    progressIntervalRef.current = setInterval(() => {\n      const elapsed = Date.now() - startTime;\n      const progress = Math.min(elapsed / threshold, 1);\n      setDwellProgress(progress);\n\n      if (progress >= 1) {\n        if (progressIntervalRef.current) clearInterval(progressIntervalRef.current);\n      }\n    }, 50);\n\n    // Set up dwell trigger\n    dwellTimerRef.current = setTimeout(() => {\n      setIsDwelling(true);\n      setHasTriggered(true);\n      onDwell?.();\n\n      // Start cooldown\n      isInCooldownRef.current = true;\n      cooldownTimerRef.current = setTimeout(() => {\n        isInCooldownRef.current = false;\n        setHasTriggered(false);\n        setDwellProgress(0);\n      }, cooldown);\n    }, threshold);\n  }, [threshold, cooldown, onDwell, requireVisible, hasTriggered, isElementVisible, clearTimers]);\n\n  const handleScroll = useCallback(() => {\n    lastScrollTimeRef.current = Date.now();\n    setIsDwelling(false);\n    setDwellProgress(0);\n    clearTimers();\n\n    // Restart dwell detection after a short delay\n    setTimeout(() => {\n      const timeSinceScroll = Date.now() - lastScrollTimeRef.current;\n      if (timeSinceScroll >= 100) {\n        startDwellTimer();\n      }\n    }, 100);\n  }, [clearTimers, startDwellTimer]);\n\n  useEffect(() => {\n    window.addEventListener(\"scroll\", handleScroll, { passive: true });\n\n    // Start initial dwell timer if element is already visible\n    if (requireVisible && isElementVisible()) {\n      startDwellTimer();\n    } else if (!requireVisible) {\n      startDwellTimer();\n    }\n\n    return () => {\n      window.removeEventListener(\"scroll\", handleScroll);\n      clearTimers();\n      if (cooldownTimerRef.current) {\n        clearTimeout(cooldownTimerRef.current);\n      }\n    };\n  }, [handleScroll, startDwellTimer, requireVisible, isElementVisible, clearTimers]);\n\n  return {\n    isDwelling,\n    dwellProgress,\n    hasTriggered,\n    reset,\n  };\n}\n\nexport default useScrollDwell;\n"]}
+{"version":3,"sources":["../../src/utils/cn.ts","../../src/hooks/DwellHint.tsx","../../src/hooks/use-debounced-refresh.ts","../../src/hooks/use-media-query.ts","../../src/hooks/use-reduced-motion.ts","../../src/hooks/useScrollDwell.ts"],"names":["useMediaQueryBase","useReducedMotion","useRef","useCallback","useEffect"],"mappings":"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","file":"index.js","sourcesContent":["import { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n","\"use client\";\n\nimport * as React from \"react\";\nimport {\n  AnimatePresence,\n  type HTMLMotionProps,\n  motion,\n  useReducedMotion,\n} from \"../shared/animation/motion\";\nimport { cn } from \"../utils/cn\";\n\nexport type DwellHintPosition = \"top\" | \"bottom\" | \"center\";\n\nexport interface DwellHintProps\n  extends Omit<\n    HTMLMotionProps<\"div\">,\n    \"children\" | \"initial\" | \"animate\" | \"exit\" | \"transition\" | \"position\"\n  > {\n  /** Whether the hint is visible */\n  show: boolean;\n  /** The hint message to display */\n  message: string;\n  /** Optional icon to display before the message */\n  icon?: React.ReactNode;\n  /** Position of the hint relative to content (default: \"bottom\") */\n  position?: DwellHintPosition;\n}\n\n/**\n * DwellHint - A contextual hint that appears when user dwells on content.\n *\n * Use with useScrollDwell hook to show helpful messages when users\n * pause scrolling and appear to be reading content.\n *\n * @example\n * const { hasTriggered } = useScrollDwell(sectionRef, { threshold: 1000 });\n *\n * <DwellHint\n *   show={hasTriggered}\n *   message=\"This is why production-ready matters.\"\n *   icon={<Lightbulb className=\"w-4 h-4\" />}\n * />\n */\nconst POSITION_CLASSES: Record<DwellHintPosition, string> = {\n  top: \"top-0 -translate-y-full mb-2\",\n  bottom: \"bottom-0 translate-y-full mt-2\",\n  center: \"top-1/2 -translate-y-1/2\",\n};\n\nexport const DwellHint = React.forwardRef<HTMLDivElement, DwellHintProps>(\n  ({ show, message, icon, position = \"bottom\", className, ...props }, ref) => {\n    const shouldReduceMotion = useReducedMotion();\n    // Narrow after destructure: HTMLMotionProps intersections can widen\n    // `position` to `any` under tsup DTS emit, which then fails TS7053.\n    const resolvedPosition: DwellHintPosition = position ?? \"bottom\";\n\n    return (\n      <AnimatePresence initial={!shouldReduceMotion}>\n        {show && (\n          <motion.div\n            ref={ref}\n            className={cn(\n              \"absolute left-1/2 -translate-x-1/2 z-10\",\n              POSITION_CLASSES[resolvedPosition],\n              className,\n            )}\n            initial={\n              shouldReduceMotion\n                ? { opacity: 1 }\n                : {\n                    opacity: 0,\n                    y: resolvedPosition === \"top\" ? -10 : 10,\n                    scale: 0.95,\n                  }\n            }\n            animate={shouldReduceMotion ? { opacity: 1 } : { opacity: 1, y: 0, scale: 1 }}\n            exit={\n              shouldReduceMotion\n                ? { opacity: 0 }\n                : { opacity: 0, y: resolvedPosition === \"top\" ? -5 : 5, scale: 0.98 }\n            }\n            transition={\n              shouldReduceMotion\n                ? { duration: 0 }\n                : {\n                    duration: 0.4,\n                    ease: [0.34, 1.56, 0.64, 1],\n                  }\n            }\n            {...props}\n          >\n            <div\n              className={cn(\n                \"flex items-center gap-2 px-4 py-2.5\",\n                \"bg-background/95 backdrop-blur-md\",\n                \"border border-border/50 rounded-[var(--radius-lg)]\",\n                \"shadow-lg shadow-black/5\",\n                \"text-sm text-muted-foreground\",\n              )}\n            >\n              {icon && <span className=\"text-primary/70 shrink-0\">{icon}</span>}\n              <span>{message}</span>\n            </div>\n          </motion.div>\n        )}\n      </AnimatePresence>\n    );\n  },\n);\n\nDwellHint.displayName = \"DwellHint\";\n","/**\n * Debounced Refresh Hook\n *\n * Wraps usehooks-ts (already a workspace dependency) so the rest of the\n * monorepo gets a single canonical debounced hook surface:\n * - cancellable\n * - configurable delay\n * - leading / trailing modes\n */\n\nimport { useCallback, useEffect, useRef } from \"react\";\nimport { useDebounceCallback, useDebounceValue } from \"usehooks-ts\";\n\ntype DebouncedRefreshResult = {\n  schedule: () => void;\n  cancel: () => void;\n  isPending: () => boolean;\n  flush: () => void;\n};\n\n/**\n * 防抖刷新 Hook\n *\n * 用于限制频繁触发的刷新操作\n *\n * @param callback - 要执行的回调函数\n * @param delay - 延迟时间 (毫秒)\n * @returns 控制对象 { schedule, cancel, isPending, flush }\n *\n * @example\n * const { schedule, cancel } = useDebouncedRefresh(() => {\n *   refetch();\n * }, 400);\n *\n * // 在数据变化时调用\n * useEffect(() => {\n *   schedule();\n * }, [data]);\n */\nexport function useDebouncedRefresh(callback: () => void, delay = 400): DebouncedRefreshResult {\n  const callbackRef = useRef(callback);\n\n  // 保持回调引用最新\n  useEffect(() => {\n    callbackRef.current = callback;\n  }, [callback]);\n\n  // 使用 usehooks-ts 的 useDebounceCallback\n  const debounced = useDebounceCallback(\n    () => {\n      callbackRef.current();\n    },\n    delay,\n    { leading: false, trailing: true },\n  );\n\n  const schedule = useCallback(() => {\n    debounced();\n  }, [debounced]);\n\n  const cancel = useCallback(() => {\n    debounced.cancel();\n  }, [debounced]);\n\n  const isPending = useCallback(() => {\n    return debounced.isPending();\n  }, [debounced]);\n\n  const flush = useCallback(() => {\n    debounced.flush();\n  }, [debounced]);\n\n  // 组件卸载时取消\n  useEffect(() => cancel, [cancel]);\n\n  return { schedule, cancel, isPending, flush };\n}\n\n/**\n * 防抖值 Hook\n *\n * Thin wrapper over usehooks-ts useDebounceValue so consumers can import\n * the canonical hook from @nebutra/ui/hooks alongside useDebouncedRefresh.\n *\n * @param value - 要防抖的值\n * @param delay - 延迟时间 (毫秒)\n * @returns 防抖后的值\n *\n * @example\n * const [searchTerm, setSearchTerm] = useState(\"\");\n * const debouncedSearch = useDebouncedValue(searchTerm, 300);\n *\n * useEffect(() => {\n *   if (debouncedSearch) {\n *     performSearch(debouncedSearch);\n *   }\n * }, [debouncedSearch]);\n */\nexport function useDebouncedValue<T>(value: T, delay = 500): T {\n  const [debouncedValue] = useDebounceValue(value, delay);\n  return debouncedValue;\n}\n","import { useMediaQuery as useMediaQueryBase } from \"usehooks-ts\";\n\n/**\n * Hook to detect media query matches.\n *\n * Delegates to usehooks-ts `useMediaQuery` with `initializeWithValue: false`\n * so the initial render always returns `false` — SSR-safe, matching the\n * previous hand-rolled behaviour (no `window` access during SSR/hydration).\n *\n * @example\n * ```tsx\n * const isMobile = useMediaQuery(\"(max-width: 768px)\");\n * const prefersDark = useMediaQuery(\"(prefers-color-scheme: dark)\");\n * ```\n */\nexport function useMediaQuery(query: string): boolean {\n  return useMediaQueryBase(query, { initializeWithValue: false });\n}\n","\"use client\";\n\nimport { useReducedMotion as useSharedReducedMotion } from \"../shared/animation/motion\";\n\n/**\n * Returns true if the user has enabled prefers-reduced-motion.\n * Use this to disable animations, skip transitions, or simplify motion.\n *\n * Wraps framer-motion's `useReducedMotion` so callers don't need framer-motion\n * as a direct import just for accessibility checks.\n *\n * @example\n * const shouldReduce = useReducedMotion();\n * const transition = shouldReduce ? { duration: 0 } : brandSpring.default;\n */\nexport function useReducedMotion(): boolean {\n  return useSharedReducedMotion() ?? false;\n}\n","\"use client\";\n\nimport { type RefObject, useCallback, useEffect, useRef, useState } from \"react\";\n\nexport interface DwellConfig {\n  /** Time in ms before dwell is triggered (default: 800) */\n  threshold?: number;\n  /** Cooldown in ms between triggers (default: 5000) */\n  cooldown?: number;\n  /** Callback when dwell is detected */\n  onDwell?: () => void;\n  /** Only trigger when element is in viewport (default: true) */\n  requireVisible?: boolean;\n}\n\nexport interface DwellState {\n  /** Whether the user is currently dwelling */\n  isDwelling: boolean;\n  /** Progress toward trigger threshold (0-1) */\n  dwellProgress: number;\n  /** Whether dwell was triggered (resets after cooldown) */\n  hasTriggered: boolean;\n  /** Manually reset the triggered state */\n  reset: () => void;\n}\n\n/**\n * useScrollDwell - Detects when a user pauses scrolling over an element.\n *\n * This hook monitors scroll activity and detects \"dwell\" behavior where\n * the user stops scrolling for a specified duration. Useful for showing\n * contextual hints, tooltips, or triggering animations when a user\n * appears to be reading or studying content.\n *\n * @param ref - Reference to the element to monitor\n * @param config - Configuration options\n * @returns DwellState object with current dwell status\n *\n * @example\n * function FeatureSection() {\n *   const sectionRef = useRef<HTMLDivElement>(null);\n *   const { isDwelling, hasTriggered } = useScrollDwell(sectionRef, {\n *     threshold: 1000,\n *     cooldown: 10000,\n *     onDwell: () => console.log(\"User is reading this section\"),\n *   });\n *\n *   return (\n *     <div ref={sectionRef}>\n *       {hasTriggered && <DwellHint message=\"Take a closer look!\" />}\n *     </div>\n *   );\n * }\n */\nexport function useScrollDwell(\n  ref: RefObject<HTMLElement | null>,\n  config: DwellConfig = {},\n): DwellState {\n  const { threshold = 800, cooldown = 5000, onDwell, requireVisible = true } = config;\n\n  const [isDwelling, setIsDwelling] = useState(false);\n  const [dwellProgress, setDwellProgress] = useState(0);\n  const [hasTriggered, setHasTriggered] = useState(false);\n\n  const dwellTimerRef = useRef<NodeJS.Timeout | null>(null);\n  const progressIntervalRef = useRef<NodeJS.Timeout | null>(null);\n  const cooldownTimerRef = useRef<NodeJS.Timeout | null>(null);\n  const lastScrollTimeRef = useRef<number>(Date.now());\n  const isInCooldownRef = useRef(false);\n\n  const clearTimers = useCallback(() => {\n    if (dwellTimerRef.current) {\n      clearTimeout(dwellTimerRef.current);\n      dwellTimerRef.current = null;\n    }\n    if (progressIntervalRef.current) {\n      clearInterval(progressIntervalRef.current);\n      progressIntervalRef.current = null;\n    }\n  }, []);\n\n  const reset = useCallback(() => {\n    setHasTriggered(false);\n    setIsDwelling(false);\n    setDwellProgress(0);\n    isInCooldownRef.current = false;\n    if (cooldownTimerRef.current) {\n      clearTimeout(cooldownTimerRef.current);\n      cooldownTimerRef.current = null;\n    }\n  }, []);\n\n  const isElementVisible = useCallback(() => {\n    if (!ref.current) return false;\n    const rect = ref.current.getBoundingClientRect();\n    const windowHeight = window.innerHeight;\n\n    // Element is visible if at least 50% is in viewport\n    const visibleHeight = Math.min(rect.bottom, windowHeight) - Math.max(rect.top, 0);\n    const elementHeight = rect.height;\n\n    return visibleHeight / elementHeight > 0.5;\n  }, [ref]);\n\n  const startDwellTimer = useCallback(() => {\n    if (isInCooldownRef.current || hasTriggered) return;\n    if (requireVisible && !isElementVisible()) return;\n\n    clearTimers();\n\n    // Start progress tracking\n    const startTime = Date.now();\n    progressIntervalRef.current = setInterval(() => {\n      const elapsed = Date.now() - startTime;\n      const progress = Math.min(elapsed / threshold, 1);\n      setDwellProgress(progress);\n\n      if (progress >= 1) {\n        if (progressIntervalRef.current) clearInterval(progressIntervalRef.current);\n      }\n    }, 50);\n\n    // Set up dwell trigger\n    dwellTimerRef.current = setTimeout(() => {\n      setIsDwelling(true);\n      setHasTriggered(true);\n      onDwell?.();\n\n      // Start cooldown\n      isInCooldownRef.current = true;\n      cooldownTimerRef.current = setTimeout(() => {\n        isInCooldownRef.current = false;\n        setHasTriggered(false);\n        setDwellProgress(0);\n      }, cooldown);\n    }, threshold);\n  }, [threshold, cooldown, onDwell, requireVisible, hasTriggered, isElementVisible, clearTimers]);\n\n  const handleScroll = useCallback(() => {\n    lastScrollTimeRef.current = Date.now();\n    setIsDwelling(false);\n    setDwellProgress(0);\n    clearTimers();\n\n    // Restart dwell detection after a short delay\n    setTimeout(() => {\n      const timeSinceScroll = Date.now() - lastScrollTimeRef.current;\n      if (timeSinceScroll >= 100) {\n        startDwellTimer();\n      }\n    }, 100);\n  }, [clearTimers, startDwellTimer]);\n\n  useEffect(() => {\n    window.addEventListener(\"scroll\", handleScroll, { passive: true });\n\n    // Start initial dwell timer if element is already visible\n    if (requireVisible && isElementVisible()) {\n      startDwellTimer();\n    } else if (!requireVisible) {\n      startDwellTimer();\n    }\n\n    return () => {\n      window.removeEventListener(\"scroll\", handleScroll);\n      clearTimers();\n      if (cooldownTimerRef.current) {\n        clearTimeout(cooldownTimerRef.current);\n      }\n    };\n  }, [handleScroll, startDwellTimer, requireVisible, isElementVisible, clearTimers]);\n\n  return {\n    isDwelling,\n    dwellProgress,\n    hasTriggered,\n    reset,\n  };\n}\n\nexport default useScrollDwell;\n"]}

package/dist/index-CKLIGfiU.d.ts

@@ -0,0 +1,19 @@
+declare const cssTransition: {
+    readonly color: "transition-colors duration-micro ease-out motion-reduce:transition-none";
+    readonly background: "transition-colors duration-micro ease-out motion-reduce:transition-none";
+    readonly border: "transition-colors duration-micro ease-out motion-reduce:transition-none";
+    readonly shadow: "transition-shadow duration-flow ease-out motion-reduce:transition-none";
+    readonly opacity: "transition-opacity duration-micro ease-out motion-reduce:transition-none";
+    readonly transform: "transition-transform duration-flow ease-out motion-reduce:transition-none";
+};
+declare const interactiveCssTransition = "transition-[color,background-color,border-color,box-shadow,opacity,transform] duration-flow ease-out motion-reduce:transition-none";
+type CssTransition = keyof typeof cssTransition;
+
+type index_CssTransition = CssTransition;
+declare const index_cssTransition: typeof cssTransition;
+declare const index_interactiveCssTransition: typeof interactiveCssTransition;
+declare namespace index {
+  export { type index_CssTransition as CssTransition, index_cssTransition as cssTransition, index_interactiveCssTransition as interactiveCssTransition };
+}
+
+export { type CssTransition as C, interactiveCssTransition as a, cssTransition as c, index as i };

package/dist/index-Dg4jRJV2.d.ts

@@ -0,0 +1,57 @@
+import { AnimatePresence, HTMLMotionProps, LayoutGroup, LazyMotion, MotionConfig, MotionProps, MotionStyle, MotionValue, Transition, Variants, animate, domAnimation, m, motion, useAnimationFrame, useInView, useMotionTemplate, useMotionValue, useReducedMotion, useScroll, useSpring, useTransform, useVelocity } from 'framer-motion';
+import { A as AnimatedCard, a as AnimatedDrawer, b as AnimatedList, c as AnimatedModal, d as AnimatedPopover, e as AnimationDuration, f as AnimationTransition, F as FadeIn, P as PageTransition, S as ScaleIn, g as SlideIn, h as animatedList, i as animatedListItem, j as animationDistances, k as animationDurations, l as animationEasings, m as animationSprings, n as animationTransitions, o as drawerSurface, p as fadeIn, q as modalSurface, r as pageTransition, s as popoverSurface, t as reducedMotionVariants, u as scaleIn, v as slideIn } from './tokens-EAC6uPem.js';
+
+declare const index_AnimatePresence: typeof AnimatePresence;
+declare const index_AnimatedCard: typeof AnimatedCard;
+declare const index_AnimatedDrawer: typeof AnimatedDrawer;
+declare const index_AnimatedList: typeof AnimatedList;
+declare const index_AnimatedModal: typeof AnimatedModal;
+declare const index_AnimatedPopover: typeof AnimatedPopover;
+declare const index_AnimationDuration: typeof AnimationDuration;
+declare const index_AnimationTransition: typeof AnimationTransition;
+declare const index_FadeIn: typeof FadeIn;
+declare const index_HTMLMotionProps: typeof HTMLMotionProps;
+declare const index_LayoutGroup: typeof LayoutGroup;
+declare const index_LazyMotion: typeof LazyMotion;
+declare const index_MotionConfig: typeof MotionConfig;
+declare const index_MotionProps: typeof MotionProps;
+declare const index_MotionStyle: typeof MotionStyle;
+declare const index_MotionValue: typeof MotionValue;
+declare const index_PageTransition: typeof PageTransition;
+declare const index_ScaleIn: typeof ScaleIn;
+declare const index_SlideIn: typeof SlideIn;
+declare const index_Transition: typeof Transition;
+declare const index_Variants: typeof Variants;
+declare const index_animate: typeof animate;
+declare const index_animatedList: typeof animatedList;
+declare const index_animatedListItem: typeof animatedListItem;
+declare const index_animationDistances: typeof animationDistances;
+declare const index_animationDurations: typeof animationDurations;
+declare const index_animationEasings: typeof animationEasings;
+declare const index_animationSprings: typeof animationSprings;
+declare const index_animationTransitions: typeof animationTransitions;
+declare const index_domAnimation: typeof domAnimation;
+declare const index_drawerSurface: typeof drawerSurface;
+declare const index_fadeIn: typeof fadeIn;
+declare const index_m: typeof m;
+declare const index_modalSurface: typeof modalSurface;
+declare const index_motion: typeof motion;
+declare const index_pageTransition: typeof pageTransition;
+declare const index_popoverSurface: typeof popoverSurface;
+declare const index_reducedMotionVariants: typeof reducedMotionVariants;
+declare const index_scaleIn: typeof scaleIn;
+declare const index_slideIn: typeof slideIn;
+declare const index_useAnimationFrame: typeof useAnimationFrame;
+declare const index_useInView: typeof useInView;
+declare const index_useMotionTemplate: typeof useMotionTemplate;
+declare const index_useMotionValue: typeof useMotionValue;
+declare const index_useReducedMotion: typeof useReducedMotion;
+declare const index_useScroll: typeof useScroll;
+declare const index_useSpring: typeof useSpring;
+declare const index_useTransform: typeof useTransform;
+declare const index_useVelocity: typeof useVelocity;
+declare namespace index {
+  export { index_AnimatePresence as AnimatePresence, index_AnimatedCard as AnimatedCard, index_AnimatedDrawer as AnimatedDrawer, index_AnimatedList as AnimatedList, index_AnimatedModal as AnimatedModal, index_AnimatedPopover as AnimatedPopover, index_AnimationDuration as AnimationDuration, index_AnimationTransition as AnimationTransition, index_FadeIn as FadeIn, index_HTMLMotionProps as HTMLMotionProps, index_LayoutGroup as LayoutGroup, index_LazyMotion as LazyMotion, index_MotionConfig as MotionConfig, index_MotionProps as MotionProps, index_MotionStyle as MotionStyle, index_MotionValue as MotionValue, index_PageTransition as PageTransition, index_ScaleIn as ScaleIn, index_SlideIn as SlideIn, index_Transition as Transition, index_Variants as Variants, index_animate as animate, index_animatedList as animatedList, index_animatedListItem as animatedListItem, index_animationDistances as animationDistances, index_animationDurations as animationDurations, index_animationEasings as animationEasings, index_animationSprings as animationSprings, index_animationTransitions as animationTransitions, index_domAnimation as domAnimation, index_drawerSurface as drawerSurface, index_fadeIn as fadeIn, index_m as m, index_modalSurface as modalSurface, index_motion as motion, index_pageTransition as pageTransition, index_popoverSurface as popoverSurface, index_reducedMotionVariants as reducedMotionVariants, index_scaleIn as scaleIn, index_slideIn as slideIn, index_useAnimationFrame as useAnimationFrame, index_useInView as useInView, index_useMotionTemplate as useMotionTemplate, index_useMotionValue as useMotionValue, index_useReducedMotion as useReducedMotion, index_useScroll as useScroll, index_useSpring as useSpring, index_useTransform as useTransform, index_useVelocity as useVelocity };
+}
+
+export { index as i };

package/dist/layout/index.d.ts

@@ -22,6 +22,10 @@ interface AppShellProps {
     defaultCollapsed?: boolean;
     /** Fires whenever the collapsed state changes (both controlled + uncontrolled). */
     onCollapsedChange?: (collapsed: boolean) => void;
+    /** Render the desktop sidebar as a floating overlay (absolute, z-40) instead of
+     *  an in-flow rail that compresses main — for full-bleed builder routes that
+     *  drive their own toggle. When collapsed to 0 width it's simply invisible. */
+    overlay?: boolean;
     /** Height in pixels of the sticky header row. Defaults to 48. */
     headerHeight?: number;
     /** Override the default container styles applied to `<main>`. */
@@ -52,7 +56,7 @@ interface AppShellProps {
  * </AppShell>
  * ```
  */
-declare function AppShell({ sidebar, header, children, sidebarWidth, sidebarCollapsedWidth, collapsed, defaultCollapsed, onCollapsedChange, headerHeight, contentClassName, className, }: AppShellProps): react_jsx_runtime.JSX.Element;
+declare function AppShell({ sidebar, header, children, sidebarWidth, sidebarCollapsedWidth, collapsed, defaultCollapsed, onCollapsedChange, headerHeight, contentClassName, className, overlay, }: AppShellProps): react_jsx_runtime.JSX.Element;
 
 interface CardProps {
     children: React__default.ReactNode;