@nikala-ui/docs 0.12.0

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

@@ -0,0 +1,129 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export type ScrollDirection = "up" | "down" | "left" | "right" | "none";
+
+export interface CreateScrollPositionOptions {
+  /** Target element to observe scroll events on. Defaults to window. */
+  target?: HTMLElement | Window | Accessor<HTMLElement | Window | undefined>;
+}
+
+export interface CreateScrollPositionReturn {
+  /** Accessor for horizontal scroll position (scrollLeft / pageXOffset) */
+  x: Accessor<number>;
+  /** Accessor for vertical scroll position (scrollTop / pageYOffset) */
+  y: Accessor<number>;
+  /** Accessor indicating if element is actively scrolling */
+  isScrolling: Accessor<boolean>;
+  /** Accessor for current scroll direction ('up', 'down', 'left', 'right', 'none') */
+  direction: Accessor<ScrollDirection>;
+  /** Accessor indicating if scroll is at top (y <= 0) */
+  isAtTop: Accessor<boolean>;
+  /** Accessor indicating if scroll is at bottom of container */
+  isAtBottom: Accessor<boolean>;
+  /** Function to programmatically scroll target element */
+  scrollTo: (options: ScrollToOptions) => void;
+}
+
+/**
+ * SolidJS reactive primitive for tracking target element or window scroll position and scroll metrics.
+ *
+ * @param options Configuration options including target element.
+ */
+export function createScrollPosition(
+  options: CreateScrollPositionOptions = {}
+): CreateScrollPositionReturn {
+  const [x, setX] = createSignal(0);
+  const [y, setY] = createSignal(0);
+  const [isScrolling, setIsScrolling] = createSignal(false);
+  const [direction, setDirection] = createSignal<ScrollDirection>("none");
+  const [isAtTop, setIsAtTop] = createSignal(true);
+  const [isAtBottom, setIsAtBottom] = createSignal(false);
+
+  let scrollTimeout: ReturnType<typeof setTimeout> | undefined;
+  let lastX = 0;
+  let lastY = 0;
+
+  const getTarget = (): HTMLElement | Window | undefined => {
+    if (typeof window === "undefined") return undefined;
+    if (!options.target) return window;
+    if (typeof options.target === "function") {
+      return (options.target as Accessor<HTMLElement | Window | undefined>)();
+    }
+    return options.target;
+  };
+
+  const updateScroll = () => {
+    const target = getTarget();
+    if (!target) return;
+
+    let currentX = 0;
+    let currentY = 0;
+    let maxScrollY = 0;
+
+    if (target === window) {
+      currentX = window.scrollX || window.pageXOffset;
+      currentY = window.scrollY || window.pageYOffset;
+      maxScrollY = document.documentElement.scrollHeight - window.innerHeight;
+    } else {
+      const el = target as HTMLElement;
+      currentX = el.scrollLeft;
+      currentY = el.scrollTop;
+      maxScrollY = el.scrollHeight - el.clientHeight;
+    }
+
+    // Determine direction
+    const deltaX = currentX - lastX;
+    const deltaY = currentY - lastY;
+
+    if (Math.abs(deltaY) > Math.abs(deltaX)) {
+      if (deltaY > 0) setDirection("down");
+      else if (deltaY < 0) setDirection("up");
+    } else if (Math.abs(deltaX) > 0) {
+      if (deltaX > 0) setDirection("right");
+      else if (deltaX < 0) setDirection("left");
+    }
+
+    lastX = currentX;
+    lastY = currentY;
+
+    setX(currentX);
+    setY(currentY);
+    setIsAtTop(currentY <= 0);
+    setIsAtBottom(maxScrollY > 0 && currentY >= maxScrollY - 1);
+    setIsScrolling(true);
+
+    if (scrollTimeout) clearTimeout(scrollTimeout);
+    scrollTimeout = setTimeout(() => {
+      setIsScrolling(false);
+    }, 150);
+  };
+
+  createEffect(() => {
+    const target = getTarget();
+    if (!target) return;
+
+    updateScroll();
+
+    target.addEventListener("scroll", updateScroll, { passive: true });
+    onCleanup(() => {
+      target.removeEventListener("scroll", updateScroll);
+      if (scrollTimeout) clearTimeout(scrollTimeout);
+    });
+  });
+
+  const scrollTo = (scrollOptions: ScrollToOptions) => {
+    const target = getTarget();
+    if (!target) return;
+    target.scrollTo(scrollOptions);
+  };
+
+  return {
+    x,
+    y,
+    isScrolling,
+    direction,
+    isAtTop,
+    isAtBottom,
+    scrollTo,
+  };
+}

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

@@ -0,0 +1,106 @@
+import { createSignal, onMount, onCleanup, type Accessor } from "solid-js";
+
+export type StorageType = "local" | "session";
+
+/**
+ * Helper to safely read item from Web Storage.
+ */
+function readStorage<T>(key: string, storage: Storage | undefined, fallback: T): T {
+  if (!storage) return fallback;
+  try {
+    const item = storage.getItem(key);
+    return item !== null ? JSON.parse(item) : fallback;
+  } catch (error) {
+    console.warn(`[nikala-ui/hooks] Error reading storage key "${key}":`, error);
+    return fallback;
+  }
+}
+
+/**
+ * SolidJS reactive primitive for Web Storage (localStorage / sessionStorage) synchronization.
+ *
+ * @param key Storage key name.
+ * @param initialValue Default initial value if key doesn't exist.
+ * @param type Storage type: "local" (default) or "session".
+ */
+export function createStorage<T>(
+  key: string,
+  initialValue: T | Accessor<T>,
+  type: StorageType = "local"
+): [value: Accessor<T>, setValue: (val: T | ((prev: T) => T)) => void, remove: () => void] {
+  const getStorage = (): Storage | undefined => {
+    if (typeof window === "undefined") return undefined;
+    return type === "local" ? window.localStorage : window.sessionStorage;
+  };
+
+  const getFallback = (): T => (typeof initialValue === "function" ? (initialValue as Accessor<T>)() : initialValue);
+
+  const [value, setInternalValue] = createSignal<T>(getFallback());
+
+  const setValue = (val: T | ((prev: T) => T)) => {
+    const storage = getStorage();
+    const currentValue = value();
+    const nextValue = typeof val === "function" ? (val as (prev: T) => T)(currentValue) : val;
+
+    setInternalValue(() => nextValue);
+
+    if (storage) {
+      try {
+        storage.setItem(key, JSON.stringify(nextValue));
+      } catch (error) {
+        console.warn(`[nikala-ui/hooks] Error setting storage key "${key}":`, error);
+      }
+    }
+  };
+
+  const remove = () => {
+    const storage = getStorage();
+    setInternalValue(() => getFallback());
+    if (storage) {
+      storage.removeItem(key);
+    }
+  };
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    const storage = getStorage();
+    if (storage) {
+      const stored = readStorage<T>(key, storage, getFallback());
+      setInternalValue(() => stored);
+    }
+
+    const handleStorageChange = (event: StorageEvent) => {
+      if (event.key === key) {
+        setInternalValue(() => (event.newValue !== null ? JSON.parse(event.newValue) : getFallback()));
+      }
+    };
+
+    window.addEventListener("storage", handleStorageChange);
+    onCleanup(() => {
+      window.removeEventListener("storage", handleStorageChange);
+    });
+  });
+
+  return [value, setValue, remove];
+}
+
+/**
+ * SolidJS reactive primitive for localStorage synchronization across components and browser tabs.
+ */
+export function createLocalStorage<T>(
+  key: string,
+  initialValue: T | Accessor<T>
+): [value: Accessor<T>, setValue: (val: T | ((prev: T) => T)) => void, remove: () => void] {
+  return createStorage<T>(key, initialValue, "local");
+}
+
+/**
+ * SolidJS reactive primitive for sessionStorage synchronization.
+ */
+export function createSessionStorage<T>(
+  key: string,
+  initialValue: T | Accessor<T>
+): [value: Accessor<T>, setValue: (val: T | ((prev: T) => T)) => void, remove: () => void] {
+  return createStorage<T>(key, initialValue, "session");
+}