@nikala-ui/docs 0.12.0

package/dist/vendor/hooks-src/create-battery.ts

@@ -0,0 +1,78 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface BatteryState {
+  /** Battery charge level ratio from 0.0 (empty) to 1.0 (full). */
+  level: number;
+  /** Whether the device battery is currently charging. */
+  charging: boolean;
+  /** Seconds remaining until fully charged (0 if already full or unknown). */
+  chargingTime: number;
+  /** Seconds remaining until fully discharged. */
+  dischargingTime: number;
+}
+
+export interface CreateBatteryReturn {
+  /** Signal accessor containing battery state metrics. */
+  battery: Accessor<BatteryState>;
+  /** Signal accessor indicating whether Battery Status API is supported in browser environment. */
+  isSupported: Accessor<boolean>;
+}
+
+const initialBatteryState: BatteryState = {
+  level: 1,
+  charging: true,
+  chargingTime: 0,
+  dischargingTime: Infinity,
+};
+
+/**
+ * SolidJS reactive primitive for observing device battery status, charge level, and charging metrics.
+ */
+export function createBattery(): CreateBatteryReturn {
+  const [battery, setBattery] = createSignal<BatteryState>(initialBatteryState);
+
+  const isSupported = (): boolean =>
+    typeof window !== "undefined" &&
+    typeof navigator !== "undefined" &&
+    "getBattery" in navigator;
+
+  let batteryManager: any = null;
+
+  const updateBatteryStatus = (): void => {
+    if (!batteryManager) return;
+    setBattery({
+      level: batteryManager.level ?? 1,
+      charging: Boolean(batteryManager.charging),
+      chargingTime: batteryManager.chargingTime ?? 0,
+      dischargingTime: batteryManager.dischargingTime ?? Infinity,
+    });
+  };
+
+  createEffect(() => {
+    if (!isSupported()) return;
+
+    (navigator as any).getBattery().then((manager: any) => {
+      batteryManager = manager;
+      updateBatteryStatus();
+
+      manager.addEventListener("levelchange", updateBatteryStatus);
+      manager.addEventListener("chargingchange", updateBatteryStatus);
+      manager.addEventListener("chargingtimechange", updateBatteryStatus);
+      manager.addEventListener("dischargingtimechange", updateBatteryStatus);
+    }).catch(() => {});
+
+    onCleanup(() => {
+      if (batteryManager) {
+        batteryManager.removeEventListener("levelchange", updateBatteryStatus);
+        batteryManager.removeEventListener("chargingchange", updateBatteryStatus);
+        batteryManager.removeEventListener("chargingtimechange", updateBatteryStatus);
+        batteryManager.removeEventListener("dischargingtimechange", updateBatteryStatus);
+      }
+    });
+  });
+
+  return {
+    battery,
+    isSupported,
+  };
+}

package/dist/vendor/hooks-src/create-chat-scroll.ts

@@ -0,0 +1,113 @@
+import { createSignal, createEffect, onCleanup, onMount, type Accessor } from "solid-js";
+
+export interface CreateChatScrollOptions {
+  /** Target scrollable container element or accessor */
+  target: HTMLElement | Accessor<HTMLElement | undefined>;
+  /** Dependency accessor (e.g. messages length or content signal) that triggers auto-scroll when changed */
+  trigger?: Accessor<any>;
+  /** Threshold in pixels from bottom to consider the container "at bottom". Defaults to 40. */
+  threshold?: number;
+  /** Whether auto-scroll is enabled. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Scroll behavior: "smooth" or "auto". Defaults to "smooth". */
+  behavior?: ScrollBehavior;
+}
+
+export interface CreateChatScrollReturn {
+  /** Accessor indicating whether the container is currently scrolled to the bottom */
+  isAtBottom: Accessor<boolean>;
+  /** Accessor indicating whether user has manually scrolled up away from bottom */
+  isScrolledUp: Accessor<boolean>;
+  /** Programmatically scroll container directly to the bottom */
+  scrollToBottom: (options?: { smooth?: boolean }) => void;
+}
+
+/**
+ * SolidJS reactive primitive for chat and streaming message auto-scrolling with user scroll detection.
+ *
+ * @param options Chat scroll configuration options.
+ */
+export function createChatScroll(options: CreateChatScrollOptions): CreateChatScrollReturn {
+  const [isAtBottom, setIsAtBottom] = createSignal<boolean>(true);
+  const isScrolledUp = () => !isAtBottom();
+
+  const getElement = (): HTMLElement | undefined => {
+    if (typeof options.target === "function") {
+      return (options.target as Accessor<HTMLElement | undefined>)();
+    }
+    return options.target;
+  };
+
+  const isEnabled = () => {
+    if (typeof options.enabled === "function") {
+      return (options.enabled as Accessor<boolean>)();
+    }
+    return options.enabled ?? true;
+  };
+
+  const threshold = options.threshold ?? 40;
+
+  const checkIfAtBottom = () => {
+    const el = getElement();
+    if (!el) return true;
+    const distanceToBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    return distanceToBottom <= threshold;
+  };
+
+  const scrollToBottom = (opts?: { smooth?: boolean }) => {
+    const el = getElement();
+    if (!el) return;
+
+    const useSmooth = opts?.smooth ?? (options.behavior === "smooth" || options.behavior === undefined);
+
+    el.scrollTo({
+      top: el.scrollHeight,
+      behavior: useSmooth ? "smooth" : "auto",
+    });
+    setIsAtBottom(true);
+  };
+
+  const handleScroll = () => {
+    const atBottom = checkIfAtBottom();
+    setIsAtBottom(atBottom);
+  };
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    const el = getElement();
+    if (el) {
+      el.addEventListener("scroll", handleScroll, { passive: true });
+      setIsAtBottom(checkIfAtBottom());
+    }
+  });
+
+  onCleanup(() => {
+    if (typeof window === "undefined") return;
+    const el = getElement();
+    if (el) {
+      el.removeEventListener("scroll", handleScroll);
+    }
+  });
+
+  // Watch trigger dependencies (e.g. messages length or stream tokens)
+  if (options.trigger) {
+    createEffect(() => {
+      // Track trigger dependency
+      options.trigger!();
+
+      if (isEnabled() && isAtBottom()) {
+        // Run after microtask/DOM paint
+        setTimeout(() => {
+          scrollToBottom({ smooth: true });
+        }, 10);
+      }
+    });
+  }
+
+  return {
+    isAtBottom,
+    isScrolledUp,
+    scrollToBottom,
+  };
+}

package/dist/vendor/hooks-src/create-click-outside.ts

@@ -0,0 +1,82 @@
+import { onMount, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateClickOutsideOptions {
+  /** Target HTML element or accessor returning the container element */
+  target:
+    | HTMLElement
+    | Accessor<HTMLElement | undefined>
+    | (HTMLElement | Accessor<HTMLElement | undefined>)[];
+  /** Callback fired when a click/pointer event occurs outside the target element(s) */
+  onInteractOutside: (event: MouseEvent | PointerEvent | TouchEvent) => void;
+  /** Whether the listener is active. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Optional element or accessor to ignore when checking outside clicks (e.g. trigger button) */
+  ignore?:
+    | HTMLElement
+    | Accessor<HTMLElement | undefined>
+    | (HTMLElement | Accessor<HTMLElement | undefined>)[];
+}
+
+/**
+ * SolidJS reactive primitive for detecting user interactions outside specified element(s).
+ *
+ * @param options Configuration options including target element(s), callback, and optional ignore elements.
+ */
+export function createClickOutside(options: CreateClickOutsideOptions): void {
+  const isEnabled = () => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  const getElement = (
+    el: HTMLElement | Accessor<HTMLElement | undefined> | undefined
+  ): HTMLElement | undefined => {
+    if (!el) return undefined;
+    if (typeof el === "function") {
+      return (el as Accessor<HTMLElement | undefined>)();
+    }
+    return el;
+  };
+
+  const getElements = (
+    targets:
+      | HTMLElement
+      | Accessor<HTMLElement | undefined>
+      | (HTMLElement | Accessor<HTMLElement | undefined>)[]
+      | undefined
+  ): HTMLElement[] => {
+    if (!targets) return [];
+    const list = Array.isArray(targets) ? targets : [targets];
+    return list.map(getElement).filter((e): e is HTMLElement => e !== undefined);
+  };
+
+  const handlePointerDown = (event: MouseEvent | PointerEvent | TouchEvent) => {
+    if (!isEnabled()) return;
+
+    const targetNode = event.target as Node | null;
+    if (!targetNode) return;
+
+    const mainElements = getElements(options.target);
+    if (mainElements.length === 0) return;
+
+    const isInsideTarget = mainElements.some((el) => el.contains(targetNode));
+    if (isInsideTarget) return;
+
+    const ignoreElements = getElements(options.ignore);
+    const isInsideIgnore = ignoreElements.some((el) => el.contains(targetNode));
+    if (isInsideIgnore) return;
+
+    options.onInteractOutside(event);
+  };
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    window.addEventListener("pointerdown", handlePointerDown, true);
+    onCleanup(() => {
+      window.removeEventListener("pointerdown", handlePointerDown, true);
+    });
+  });
+}

package/dist/vendor/hooks-src/create-clipboard.ts

@@ -0,0 +1,69 @@
+import { createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateClipboardOptions {
+  /** Time in milliseconds to maintain the copied state before resetting. Defaults to 2000ms. */
+  timeout?: number;
+}
+
+export interface CreateClipboardReturn {
+  /** Signal accessor indicating if content was recently copied */
+  copied: Accessor<boolean>;
+  /** Function to copy text to clipboard */
+  copy: (text: string) => Promise<boolean>;
+  /** Error state if clipboard write fails */
+  error: Accessor<Error | undefined>;
+}
+
+/**
+ * SolidJS reactive primitive for copying text to clipboard with automatic reset state.
+ *
+ * @param options Configuration options including copied status reset timeout duration.
+ */
+export function createClipboard(options: CreateClipboardOptions = {}): CreateClipboardReturn {
+  const timeoutDuration = options.timeout ?? 2000;
+  const [copied, setCopied] = createSignal(false);
+  const [error, setError] = createSignal<Error | undefined>(undefined);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const clearTimer = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const copy = async (text: string): Promise<boolean> => {
+    clearTimer();
+    setError(undefined);
+
+    try {
+      if (typeof window !== "undefined" && navigator.clipboard && navigator.clipboard.writeText) {
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+
+        timer = setTimeout(() => {
+          setCopied(false);
+        }, timeoutDuration);
+
+        return true;
+      }
+
+      throw new Error("Clipboard API not supported");
+    } catch (err) {
+      const copyError = err instanceof Error ? err : new Error(String(err));
+      setError(copyError);
+      setCopied(false);
+      return false;
+    }
+  };
+
+  onCleanup(() => {
+    clearTimer();
+  });
+
+  return {
+    copied,
+    copy,
+    error,
+  };
+}

package/dist/vendor/hooks-src/create-color-mode.ts

@@ -0,0 +1,115 @@
+import { createEffect, createSignal, onCleanup, onMount, type Accessor } from "solid-js";
+
+export type ColorMode = "light" | "dark" | "system";
+
+export interface CreateColorModeOptions {
+  /** Initial color mode fallback. Defaults to 'system'. */
+  initialValue?: ColorMode;
+  /** LocalStorage key for persisting color mode state. Defaults to 'nikala-color-mode'. */
+  storageKey?: string;
+  /** HTML attribute to apply dark mode class on document.documentElement. Defaults to 'class'. */
+  attribute?: string;
+}
+
+export interface CreateColorModeReturn {
+  /** Accessor for current active color mode ('light', 'dark', 'system') */
+  mode: Accessor<ColorMode>;
+  /** Function to update current color mode */
+  setMode: (mode: ColorMode) => void;
+  /** Function to toggle color mode between 'light' and 'dark' */
+  toggleColorMode: () => void;
+  /** Accessor indicating if current resolved mode is dark */
+  isDark: Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for managing dark/light color mode themes and system preferences.
+ *
+ * @param options Configuration options including storage key and initial mode.
+ */
+export function createColorMode(
+  options: CreateColorModeOptions = {}
+): CreateColorModeReturn {
+  const initialMode = options.initialValue ?? "system";
+  const storageKey = options.storageKey ?? "nikala-color-mode";
+  const attribute = options.attribute ?? "class";
+
+  const [mode, setModeSignal] = createSignal<ColorMode>(initialMode);
+  const [systemDark, setSystemDark] = createSignal(false);
+
+  const isDark = () => {
+    const currentMode = mode();
+    if (currentMode === "system") return systemDark();
+    return currentMode === "dark";
+  };
+
+  const applyTheme = (dark: boolean) => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    if (attribute === "class") {
+      if (dark) root.classList.add("dark");
+      else root.classList.remove("dark");
+    } else {
+      root.setAttribute(attribute, dark ? "dark" : "light");
+    }
+  };
+
+  const setMode = (newMode: ColorMode) => {
+    setModeSignal(newMode);
+    if (typeof window !== "undefined") {
+      try {
+        localStorage.setItem(storageKey, newMode);
+      } catch (e) {
+        console.warn(`[nikala-ui/hooks] Error setting color mode storage:`, e);
+      }
+    }
+  };
+
+  const toggleColorMode = () => {
+    const next = isDark() ? "light" : "dark";
+    setMode(next);
+  };
+
+  createEffect(() => {
+    applyTheme(isDark());
+  });
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    // Check system preference
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    setSystemDark(mediaQuery.matches);
+
+    const handleMediaChange = (e: MediaQueryListEvent) => {
+      setSystemDark(e.matches);
+    };
+
+    if (mediaQuery.addEventListener) {
+      mediaQuery.addEventListener("change", handleMediaChange);
+    }
+
+    // Check localStorage
+    try {
+      const stored = localStorage.getItem(storageKey) as ColorMode | null;
+      if (stored && ["light", "dark", "system"].includes(stored)) {
+        setModeSignal(stored);
+      }
+    } catch (e) {
+      console.warn(`[nikala-ui/hooks] Error reading color mode storage:`, e);
+    }
+
+    onCleanup(() => {
+      if (mediaQuery.removeEventListener) {
+        mediaQuery.removeEventListener("change", handleMediaChange);
+      }
+    });
+  });
+
+  return {
+    mode,
+    setMode,
+    toggleColorMode,
+    isDark,
+  };
+}

package/dist/vendor/hooks-src/create-controllable-signal.ts

@@ -0,0 +1,56 @@
+import { createSignal, type Accessor } from "solid-js";
+
+export interface CreateControllableSignalOptions<T> {
+  /** Controlled value accessor or raw value */
+  value?: Accessor<T | undefined> | T;
+  /** Uncontrolled default initial value */
+  defaultValue?: T;
+  /** Callback fired whenever the value changes */
+  onChange?: (value: T) => void;
+}
+
+/**
+ * SolidJS reactive primitive for managing state supporting both controlled and uncontrolled modes.
+ *
+ * @param options Configuration options for value, defaultValue, and onChange callback.
+ * @returns A tuple containing [valueAccessor, setValueFunction].
+ */
+export function createControllableSignal<T>(
+  options: CreateControllableSignalOptions<T>
+): [Accessor<T | undefined>, (nextValue: T | ((prev: T | undefined) => T)) => void] {
+  const [internalValue, setInternalValue] = createSignal<T | undefined>(
+    options.defaultValue
+  );
+
+  const getValue = (): T | undefined => {
+    if (typeof options.value === "function") {
+      return (options.value as Accessor<T | undefined>)();
+    }
+    return options.value;
+  };
+
+  const isControlled = () => getValue() !== undefined;
+
+  const value = () => {
+    const controlledVal = getValue();
+    return controlledVal !== undefined ? controlledVal : internalValue();
+  };
+
+  const setValue = (nextValue: T | ((prev: T | undefined) => T)) => {
+    const current = value();
+    const resolvedNext =
+      typeof nextValue === "function"
+        ? (nextValue as (prev: T | undefined) => T)(current)
+        : nextValue;
+
+    if (!isControlled()) {
+      setInternalValue(resolvedNext as any);
+    }
+
+    if (typeof options.onChange === "function") {
+      options.onChange(resolvedNext);
+    }
+  };
+
+  return [value, setValue];
+}

package/dist/vendor/hooks-src/create-debounce.ts

@@ -0,0 +1,90 @@
+import { onCleanup, type Accessor } from "solid-js";
+
+export interface DebounceThrottleReturn<T extends (...args: any[]) => any> {
+  (...args: Parameters<T>): void;
+  clear: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for debouncing function execution.
+ *
+ * @param fn Function to debounce.
+ * @param delay Delay in milliseconds (number or accessor).
+ */
+export function createDebounce<T extends (...args: any[]) => any>(
+  fn: T,
+  delay: number | Accessor<number>
+): DebounceThrottleReturn<T> {
+  const getDelay = (): number => (typeof delay === "function" ? delay() : delay);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const clear = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const debounced = (...args: Parameters<T>) => {
+    clear();
+    timer = setTimeout(() => {
+      fn(...args);
+    }, getDelay());
+  };
+
+  debounced.clear = clear;
+
+  onCleanup(() => {
+    clear();
+  });
+
+  return debounced;
+}
+
+/**
+ * SolidJS reactive primitive for throttling function execution.
+ *
+ * @param fn Function to throttle.
+ * @param delay Interval in milliseconds (number or accessor).
+ */
+export function createThrottle<T extends (...args: any[]) => any>(
+  fn: T,
+  delay: number | Accessor<number>
+): DebounceThrottleReturn<T> {
+  const getDelay = (): number => (typeof delay === "function" ? delay() : delay);
+  let lastCall = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const clear = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const throttled = (...args: Parameters<T>) => {
+    const now = Date.now();
+    const interval = getDelay();
+    const remaining = interval - (now - lastCall);
+
+    if (remaining <= 0) {
+      clear();
+      lastCall = now;
+      fn(...args);
+    } else if (!timer) {
+      timer = setTimeout(() => {
+        lastCall = Date.now();
+        timer = undefined;
+        fn(...args);
+      }, remaining);
+    }
+  };
+
+  throttled.clear = clear;
+
+  onCleanup(() => {
+    clear();
+  });
+
+  return throttled;
+}

package/dist/vendor/hooks-src/create-disclosure.ts

@@ -0,0 +1,82 @@
+import { createSignal, type Accessor } from "solid-js";
+
+export interface CreateDisclosureOptions {
+  /** Uncontrolled initial open state. Defaults to false. */
+  defaultIsOpen?: boolean;
+  /** Controlled open state accessor */
+  isOpen?: boolean | Accessor<boolean | undefined>;
+  /** Callback triggered when state transitions to open */
+  onOpen?: () => void;
+  /** Callback triggered when state transitions to closed */
+  onClose?: () => void;
+  /** Callback triggered whenever open state changes */
+  onChange?: (isOpen: boolean) => void;
+}
+
+export interface CreateDisclosureReturn {
+  /** Signal accessor indicating if disclosure is open */
+  isOpen: Accessor<boolean>;
+  /** Function to open the disclosure */
+  open: () => void;
+  /** Function to close the disclosure */
+  close: () => void;
+  /** Function to toggle the disclosure open state */
+  toggle: () => void;
+  /** Setter function to programmatically set open state */
+  setOpen: (open: boolean) => void;
+}
+
+/**
+ * SolidJS reactive primitive for managing boolean disclosure (open/close) state with controlled and uncontrolled support.
+ *
+ * @param options Configuration options including initial state and callbacks.
+ */
+export function createDisclosure(options: CreateDisclosureOptions = {}): CreateDisclosureReturn {
+  const [internalOpen, setInternalOpen] = createSignal<boolean>(
+    options.defaultIsOpen ?? false
+  );
+
+  const isControlled = () => {
+    if (typeof options.isOpen === "function") {
+      return options.isOpen() !== undefined;
+    }
+    return options.isOpen !== undefined;
+  };
+
+  const isOpen = (): boolean => {
+    if (typeof options.isOpen === "function") {
+      const val = options.isOpen();
+      return val !== undefined ? val : internalOpen();
+    }
+    return options.isOpen !== undefined ? options.isOpen : internalOpen();
+  };
+
+  const setOpenState = (nextState: boolean) => {
+    const currentState = isOpen();
+    if (currentState === nextState) return;
+
+    if (!isControlled()) {
+      setInternalOpen(nextState);
+    }
+
+    options.onChange?.(nextState);
+
+    if (nextState) {
+      options.onOpen?.();
+    } else {
+      options.onClose?.();
+    }
+  };
+
+  const open = () => setOpenState(true);
+  const close = () => setOpenState(false);
+  const toggle = () => setOpenState(!isOpen());
+
+  return {
+    isOpen,
+    open,
+    close,
+    toggle,
+    setOpen: setOpenState,
+  };
+}