@nebutra/ui 0.1.0 → 0.2.1

package/dist/hooks/index.d.ts

@@ -0,0 +1,106 @@
+import { HTMLMotionProps } from 'framer-motion';
+import * as React from 'react';
+import { RefObject } from 'react';
+
+interface DwellHintProps extends Omit<HTMLMotionProps<"div">, "children" | "initial" | "animate" | "exit" | "transition"> {
+    /** Whether the hint is visible */
+    show: boolean;
+    /** The hint message to display */
+    message: string;
+    /** Optional icon to display before the message */
+    icon?: React.ReactNode;
+    /** Position of the hint relative to content (default: "bottom") */
+    position?: "top" | "bottom" | "center";
+}
+/**
+ * DwellHint - A contextual hint that appears when user dwells on content.
+ *
+ * Use with useScrollDwell hook to show helpful messages when users
+ * pause scrolling and appear to be reading content.
+ *
+ * @example
+ * const { hasTriggered } = useScrollDwell(sectionRef, { threshold: 1000 });
+ *
+ * <DwellHint
+ *   show={hasTriggered}
+ *   message="This is why production-ready matters."
+ *   icon={<Lightbulb className="w-4 h-4" />}
+ * />
+ */
+declare const DwellHint: React.ForwardRefExoticComponent<Omit<DwellHintProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Hook to detect media query matches
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery("(max-width: 768px)");
+ * const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+ * ```
+ */
+declare function useMediaQuery(query: string): boolean;
+
+/**
+ * Returns true if the user has enabled prefers-reduced-motion.
+ * Use this to disable animations, skip transitions, or simplify motion.
+ *
+ * Wraps framer-motion's `useReducedMotion` so callers don't need framer-motion
+ * as a direct import just for accessibility checks.
+ *
+ * @example
+ * const shouldReduce = useReducedMotion();
+ * const transition = shouldReduce ? { duration: 0 } : brandSpring.default;
+ */
+declare function useReducedMotion(): boolean;
+
+interface DwellConfig {
+    /** Time in ms before dwell is triggered (default: 800) */
+    threshold?: number;
+    /** Cooldown in ms between triggers (default: 5000) */
+    cooldown?: number;
+    /** Callback when dwell is detected */
+    onDwell?: () => void;
+    /** Only trigger when element is in viewport (default: true) */
+    requireVisible?: boolean;
+}
+interface DwellState {
+    /** Whether the user is currently dwelling */
+    isDwelling: boolean;
+    /** Progress toward trigger threshold (0-1) */
+    dwellProgress: number;
+    /** Whether dwell was triggered (resets after cooldown) */
+    hasTriggered: boolean;
+    /** Manually reset the triggered state */
+    reset: () => void;
+}
+/**
+ * useScrollDwell - Detects when a user pauses scrolling over an element.
+ *
+ * This hook monitors scroll activity and detects "dwell" behavior where
+ * the user stops scrolling for a specified duration. Useful for showing
+ * contextual hints, tooltips, or triggering animations when a user
+ * appears to be reading or studying content.
+ *
+ * @param ref - Reference to the element to monitor
+ * @param config - Configuration options
+ * @returns DwellState object with current dwell status
+ *
+ * @example
+ * function FeatureSection() {
+ *   const sectionRef = useRef<HTMLDivElement>(null);
+ *   const { isDwelling, hasTriggered } = useScrollDwell(sectionRef, {
+ *     threshold: 1000,
+ *     cooldown: 10000,
+ *     onDwell: () => console.log("User is reading this section"),
+ *   });
+ *
+ *   return (
+ *     <div ref={sectionRef}>
+ *       {hasTriggered && <DwellHint message="Take a closer look!" />}
+ *     </div>
+ *   );
+ * }
+ */
+declare function useScrollDwell(ref: RefObject<HTMLElement | null>, config?: DwellConfig): DwellState;
+
+export { type DwellConfig, DwellHint, type DwellHintProps, type DwellState, useMediaQuery, useReducedMotion, useScrollDwell };

package/dist/hooks/index.js

@@ -0,0 +1,182 @@
+"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 { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+// src/hooks/DwellHint.tsx
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+var DwellHint = React2.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(
+      motion.div,
+      {
+        ref,
+        className: cn(
+          "absolute left-1/2 -translate-x-1/2 z-10",
+          positionClasses[position],
+          className
+        ),
+        initial: {
+          opacity: 0,
+          y: position === "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: {
+          duration: 0.4,
+          ease: [0.34, 1.56, 0.64, 1]
+        },
+        ...props,
+        children: /* @__PURE__ */ jsxs(
+          "div",
+          {
+            className: cn(
+              "flex items-center gap-2 px-4 py-2.5",
+              "bg-background/95 backdrop-blur-md",
+              "border border-border/50 rounded-[var(--radius-lg)]",
+              "shadow-lg shadow-black/5",
+              "text-sm text-muted-foreground"
+            ),
+            children: [
+              icon && /* @__PURE__ */ jsx("span", { className: "text-primary/70 shrink-0", children: icon }),
+              /* @__PURE__ */ jsx("span", { children: message })
+            ]
+          }
+        )
+      }
+    ) });
+  }
+);
+DwellHint.displayName = "DwellHint";
+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;
+}
+function useReducedMotion() {
+  return useReducedMotion$1() ?? false;
+}
+function useScrollDwell(ref, config = {}) {
+  const { threshold = 800, cooldown = 5e3, onDwell, requireVisible = true } = config;
+  const [isDwelling, setIsDwelling] = useState(false);
+  const [dwellProgress, setDwellProgress] = useState(0);
+  const [hasTriggered, setHasTriggered] = useState(false);
+  const dwellTimerRef = useRef(null);
+  const progressIntervalRef = useRef(null);
+  const cooldownTimerRef = useRef(null);
+  const lastScrollTimeRef = useRef(Date.now());
+  const isInCooldownRef = useRef(false);
+  const clearTimers = useCallback(() => {
+    if (dwellTimerRef.current) {
+      clearTimeout(dwellTimerRef.current);
+      dwellTimerRef.current = null;
+    }
+    if (progressIntervalRef.current) {
+      clearInterval(progressIntervalRef.current);
+      progressIntervalRef.current = null;
+    }
+  }, []);
+  const reset = useCallback(() => {
+    setHasTriggered(false);
+    setIsDwelling(false);
+    setDwellProgress(0);
+    isInCooldownRef.current = false;
+    if (cooldownTimerRef.current) {
+      clearTimeout(cooldownTimerRef.current);
+      cooldownTimerRef.current = null;
+    }
+  }, []);
+  const isElementVisible = useCallback(() => {
+    if (!ref.current) return false;
+    const rect = ref.current.getBoundingClientRect();
+    const windowHeight = window.innerHeight;
+    const visibleHeight = Math.min(rect.bottom, windowHeight) - Math.max(rect.top, 0);
+    const elementHeight = rect.height;
+    return visibleHeight / elementHeight > 0.5;
+  }, [ref]);
+  const startDwellTimer = useCallback(() => {
+    if (isInCooldownRef.current || hasTriggered) return;
+    if (requireVisible && !isElementVisible()) return;
+    clearTimers();
+    const startTime = Date.now();
+    progressIntervalRef.current = setInterval(() => {
+      const elapsed = Date.now() - startTime;
+      const progress = Math.min(elapsed / threshold, 1);
+      setDwellProgress(progress);
+      if (progress >= 1) {
+        if (progressIntervalRef.current) clearInterval(progressIntervalRef.current);
+      }
+    }, 50);
+    dwellTimerRef.current = setTimeout(() => {
+      setIsDwelling(true);
+      setHasTriggered(true);
+      onDwell?.();
+      isInCooldownRef.current = true;
+      cooldownTimerRef.current = setTimeout(() => {
+        isInCooldownRef.current = false;
+        setHasTriggered(false);
+        setDwellProgress(0);
+      }, cooldown);
+    }, threshold);
+  }, [threshold, cooldown, onDwell, requireVisible, hasTriggered, isElementVisible, clearTimers]);
+  const handleScroll = useCallback(() => {
+    lastScrollTimeRef.current = Date.now();
+    setIsDwelling(false);
+    setDwellProgress(0);
+    clearTimers();
+    setTimeout(() => {
+      const timeSinceScroll = Date.now() - lastScrollTimeRef.current;
+      if (timeSinceScroll >= 100) {
+        startDwellTimer();
+      }
+    }, 100);
+  }, [clearTimers, startDwellTimer]);
+  useEffect(() => {
+    window.addEventListener("scroll", handleScroll, { passive: true });
+    if (requireVisible && isElementVisible()) {
+      startDwellTimer();
+    } else if (!requireVisible) {
+      startDwellTimer();
+    }
+    return () => {
+      window.removeEventListener("scroll", handleScroll);
+      clearTimers();
+      if (cooldownTimerRef.current) {
+        clearTimeout(cooldownTimerRef.current);
+      }
+    };
+  }, [handleScroll, startDwellTimer, requireVisible, isElementVisible, clearTimers]);
+  return {
+    isDwelling,
+    dwellProgress,
+    hasTriggered,
+    reset
+  };
+}
+
+export { DwellHint, useMediaQuery, useReducedMotion, useScrollDwell };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +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"]}

package/dist/icons/index.d.ts

@@ -0,0 +1,3 @@
+export { SiClerk as ClerkIcon, SiNextdotjs as NextjsIcon, SiPrisma as PrismaIcon, SiStripe as StripeIcon, SiSupabase as SupabaseIcon, SiTailwindcss as TailwindIcon } from '@icons-pack/react-simple-icons';
+export { Anthropic, Bilibili, Claude, ClaudeCode, Cursor, DeepSeek, Flux, Gemini, Github, Google, Grok, HuggingFace, LangChain, LangGraph, MCP, Meta, Midjourney, Mistral, N8n, Ollama, OpenAI, OpenClaw, Qwen, Railway, SiliconCloud, Smithery, Vercel } from '@lobehub/icons';
+export { Robot as Bot, Check, LoaderCircle as Loader2, Menu, Moon, Plus, MagnifyingGlass as Search, SettingsGear as Settings, Sparkles, Sun, Cross as X } from '@nebutra/icons';

package/dist/icons/index.js

@@ -0,0 +1,5 @@
+export { SiClerk as ClerkIcon, SiNextdotjs as NextjsIcon, SiPrisma as PrismaIcon, SiStripe as StripeIcon, SiSupabase as SupabaseIcon, SiTailwindcss as TailwindIcon } from '@icons-pack/react-simple-icons';
+export { Anthropic, Bilibili, Claude, ClaudeCode, Cursor, DeepSeek, Flux, Gemini, Github, Google, Grok, HuggingFace, LangChain, LangGraph, MCP, Meta, Midjourney, Mistral, N8n, Ollama, OpenAI, OpenClaw, Qwen, Railway, SiliconCloud, Smithery, Vercel } from '@lobehub/icons';
+export { Robot as Bot, Check, LoaderCircle as Loader2, Menu, Moon, Plus, MagnifyingGlass as Search, SettingsGear as Settings, Sparkles, Sun, Cross as X } from '@nebutra/icons';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/icons/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js","sourcesContent":[]}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { NebutraThemeProvider, NebutraThemeProviderProps, NebutraTokens, ThemeMode } from './theme/index.js';
+export { Anthropic, Claude, Gemini, Google, OpenAI } from '@lobehub/icons';
+export { Robot as Bot, Check, LoaderCircle as Loader2, Menu, Moon, Plus, MagnifyingGlass as Search, SettingsGear as Settings, Sparkles, Sun, Cross as X } from '@nebutra/icons';
+import 'react/jsx-runtime';
+import 'react';

package/dist/index.js

@@ -0,0 +1,31 @@
+"use client";
+import { ThemeProvider } from '@lobehub/ui';
+import { jsx } from 'react/jsx-runtime';
+import '@icons-pack/react-simple-icons';
+export { Anthropic, Claude, Gemini, Google, OpenAI } from '@lobehub/icons';
+export { Robot as Bot, Check, LoaderCircle as Loader2, Menu, Moon, Plus, MagnifyingGlass as Search, SettingsGear as Settings, Sparkles, Sun, Cross as X } from '@nebutra/icons';
+
+// src/theme/provider.tsx
+function NebutraThemeProvider({
+  children,
+  appearance = "auto",
+  defaultAppearance = "light"
+}) {
+  const resolvedAppearance = appearance === "auto" ? void 0 : appearance;
+  return /* @__PURE__ */ jsx(
+    ThemeProvider,
+    {
+      ...resolvedAppearance != null && { appearance: resolvedAppearance },
+      defaultAppearance,
+      customTheme: {
+        primaryColor: "blue",
+        neutralColor: "slate"
+      },
+      children
+    }
+  );
+}
+
+export { NebutraThemeProvider };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theme/provider.tsx"],"names":["LobeThemeProvider"],"mappings":";;;;;;;AAoCO,SAAS,oBAAA,CAAqB;AAAA,EACnC,QAAA;AAAA,EACA,UAAA,GAAa,MAAA;AAAA,EACb,iBAAA,GAAoB;AACtB,CAAA,EAA8B;AAC5B,EAAA,MAAM,kBAAA,GAAqB,UAAA,KAAe,MAAA,GAAS,MAAA,GAAY,UAAA;AAE/D,EAAA,uBACE,GAAA;AAAA,IAACA,aAAA;AAAA,IAAA;AAAA,MACE,GAAI,kBAAA,IAAsB,IAAA,IAAQ,EAAE,YAAY,kBAAA,EAAmB;AAAA,MACpE,iBAAA;AAAA,MACA,WAAA,EAAa;AAAA,QACX,YAAA,EAAc,MAAA;AAAA,QACd,YAAA,EAAc;AAAA,OAChB;AAAA,MAEC;AAAA;AAAA,GACH;AAEJ","file":"index.js","sourcesContent":["\"use client\";\n\n/**\n * Nebutra Theme Provider — Lobe UI integration bridge\n *\n * Wraps Lobe UI's ThemeProvider with Nebutra brand tokens.\n * This provider handles Lobe UI / Ant Design theming only.\n *\n * For app-level light/dark mode switching, use:\n *   import { ThemeProvider } from \"@nebutra/tokens\";\n *\n * For CSS-variable-based tokens (Tailwind, custom components), use:\n *   @import \"@nebutra/tokens/styles.css\";\n */\n\nimport { ThemeProvider as LobeThemeProvider } from \"@lobehub/ui\";\nimport type { ReactNode } from \"react\";\n\nexport interface NebutraThemeProviderProps {\n  children: ReactNode;\n  /** Force dark/light mode, or use system preference */\n  appearance?: \"dark\" | \"light\" | \"auto\";\n  /** Default theme mode when appearance is \"auto\" */\n  defaultAppearance?: \"dark\" | \"light\";\n}\n\n/**\n * Theme provider that wraps Lobe UI with Nebutra design tokens\n *\n * @example\n * ```tsx\n * <NebutraThemeProvider appearance=\"auto\">\n *   <App />\n * </NebutraThemeProvider>\n * ```\n */\nexport function NebutraThemeProvider({\n  children,\n  appearance = \"auto\",\n  defaultAppearance = \"light\",\n}: NebutraThemeProviderProps) {\n  const resolvedAppearance = appearance === \"auto\" ? undefined : appearance;\n\n  return (\n    <LobeThemeProvider\n      {...(resolvedAppearance != null && { appearance: resolvedAppearance })}\n      defaultAppearance={defaultAppearance}\n      customTheme={{\n        primaryColor: \"blue\",\n        neutralColor: \"slate\",\n      }}\n    >\n      {children}\n    </LobeThemeProvider>\n  );\n}\n\nexport default NebutraThemeProvider;\n"]}