@nikala-ui/docs 0.12.0

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

@@ -0,0 +1,129 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export type ScreenOrientationType =
+  | "portrait-primary"
+  | "portrait-secondary"
+  | "landscape-primary"
+  | "landscape-secondary"
+  | "portrait"
+  | "landscape"
+  | "unknown";
+
+export interface CreateOrientationOptions {
+  /** Callback fired when screen orientation changes. */
+  onChange?: (orientation: ScreenOrientationType, angle: number) => void;
+}
+
+export interface CreateOrientationReturn {
+  /** Signal indicating current orientation type. */
+  type: Accessor<ScreenOrientationType>;
+  /** Signal indicating current orientation angle in degrees (0, 90, 180, 270). */
+  angle: Accessor<number>;
+  /** Signal indicating if device screen is in portrait mode. */
+  isPortrait: Accessor<boolean>;
+  /** Signal indicating if device screen is in landscape mode. */
+  isLandscape: Accessor<boolean>;
+  /** Lock screen orientation if supported by device/browser. */
+  lock: (orientation: string) => Promise<void>;
+  /** Unlock screen orientation. */
+  unlock: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for observing mobile/desktop screen orientation and angle.
+ */
+export function createOrientation(
+  options: CreateOrientationOptions = {}
+): CreateOrientationReturn {
+  const [type, setType] = createSignal<ScreenOrientationType>("unknown");
+  const [angle, setAngle] = createSignal<number>(0);
+
+  const getOrientationState = (): { type: ScreenOrientationType; angle: number } => {
+    if (typeof window === "undefined") {
+      return { type: "unknown", angle: 0 };
+    }
+
+    if (window.screen?.orientation) {
+      return {
+        type: window.screen.orientation.type as ScreenOrientationType,
+        angle: window.screen.orientation.angle || 0,
+      };
+    }
+
+    /* Fallback for older browsers using window.orientation */
+    const legacyAngle = (window as unknown as { orientation?: number }).orientation ?? 0;
+    const isPortraitMode = Math.abs(legacyAngle) !== 90;
+    return {
+      type: isPortraitMode ? "portrait" : "landscape",
+      angle: Number(legacyAngle),
+    };
+  };
+
+  createEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const updateState = (): void => {
+      const state = getOrientationState();
+      setType(state.type);
+      setAngle(state.angle);
+      options.onChange?.(state.type, state.angle);
+    };
+
+    updateState();
+
+    if (window.screen?.orientation) {
+      window.screen.orientation.addEventListener("change", updateState);
+      onCleanup(() => {
+        window.screen.orientation.removeEventListener("change", updateState);
+      });
+    } else {
+      window.addEventListener("orientationchange", updateState);
+      window.addEventListener("resize", updateState);
+      onCleanup(() => {
+        window.removeEventListener("orientationchange", updateState);
+        window.removeEventListener("resize", updateState);
+      });
+    }
+  });
+
+  const isPortrait = (): boolean => {
+    const currentType = type();
+    return currentType.startsWith("portrait");
+  };
+
+  const isLandscape = (): boolean => {
+    const currentType = type();
+    return currentType.startsWith("landscape");
+  };
+
+  const lock = async (orientation: string): Promise<void> => {
+    if (typeof window !== "undefined" && window.screen?.orientation) {
+      const orientationApi = window.screen.orientation as unknown as {
+        lock?: (orient: string) => Promise<void>;
+      };
+      if (typeof orientationApi.lock === "function") {
+        await orientationApi.lock(orientation);
+      }
+    }
+  };
+
+  const unlock = (): void => {
+    if (typeof window !== "undefined" && window.screen?.orientation) {
+      const orientationApi = window.screen.orientation as unknown as {
+        unlock?: () => void;
+      };
+      if (typeof orientationApi.unlock === "function") {
+        orientationApi.unlock();
+      }
+    }
+  };
+
+  return {
+    type,
+    angle,
+    isPortrait,
+    isLandscape,
+    lock,
+    unlock,
+  };
+}

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

@@ -0,0 +1,208 @@
+import { createSignal, createMemo, type Accessor } from "solid-js";
+
+export interface CreatePaginationOptions {
+  /** Total number of items across all pages, or total count. */
+  count?: number | Accessor<number>;
+  /** Explicit total number of pages. If provided, overrides count / pageSize calculation. */
+  totalPages?: number | Accessor<number>;
+  /** Controlled active page number (1-indexed). */
+  page?: number | Accessor<number>;
+  /** Default active page number for uncontrolled state. Defaults to 1. */
+  defaultPage?: number;
+  /** Number of items per page. Defaults to 10. */
+  pageSize?: number | Accessor<number>;
+  /** Number of sibling page buttons visible on each side of the current active page. Defaults to 1. */
+  siblingCount?: number | Accessor<number>;
+  /** Number of boundary pages visible at the beginning and end. Defaults to 1. */
+  boundaries?: number | Accessor<number>;
+  /** Callback fired whenever the active page changes. */
+  onChange?: (page: number) => void;
+}
+
+export interface CreatePaginationReturn {
+  /** Accessor returning the current active page number (1-indexed). */
+  page: Accessor<number>;
+  /** Accessor returning the calculated total number of pages. */
+  totalPages: Accessor<number>;
+  /** Accessor returning the active page size. */
+  pageSize: Accessor<number>;
+  /** Accessor returning an array of page numbers and "ellipsis" strings. */
+  range: Accessor<(number | "ellipsis")[]>;
+  /** Function to programmatically change to a specific page number. */
+  setPage: (page: number) => void;
+  /** Function to navigate to the next page. */
+  next: () => void;
+  /** Function to navigate to the previous page. */
+  previous: () => void;
+  /** Function to navigate to the first page (1). */
+  first: () => void;
+  /** Function to navigate to the last page (totalPages). */
+  last: () => void;
+  /** Accessor indicating whether a next page exists. */
+  hasNext: Accessor<boolean>;
+  /** Accessor indicating whether a previous page exists. */
+  hasPrevious: Accessor<boolean>;
+  /** 1-based start index of items on the current page (e.g. 1 for page 1 with pageSize 10). */
+  startIndex: Accessor<number>;
+  /** 1-based end index of items on the current page (e.g. 10 for page 1 with pageSize 10). */
+  endIndex: Accessor<number>;
+}
+
+/**
+ * SolidJS reactive primitive for computing pagination state, dynamic page range with ellipses, and navigation helpers.
+ *
+ * @param options Pagination configuration options.
+ */
+export function createPagination(options: CreatePaginationOptions = {}): CreatePaginationReturn {
+  const getCount = () => {
+    const raw = typeof options.count === "function" ? options.count() : options.count ?? 0;
+    return Math.max(0, raw);
+  };
+
+  const getPageSize = () => {
+    const raw = typeof options.pageSize === "function" ? options.pageSize() : options.pageSize ?? 10;
+    return Math.max(1, raw);
+  };
+
+  const getExplicitTotalPages = () => {
+    const raw = typeof options.totalPages === "function" ? options.totalPages() : options.totalPages;
+    return raw !== undefined ? Math.max(1, raw) : undefined;
+  };
+
+  const getSiblingCount = () => {
+    const raw = typeof options.siblingCount === "function" ? options.siblingCount() : options.siblingCount ?? 1;
+    return Math.max(0, raw);
+  };
+
+  const getBoundaries = () => {
+    const raw = typeof options.boundaries === "function" ? options.boundaries() : options.boundaries ?? 1;
+    return Math.max(0, raw);
+  };
+
+  const [internalPage, setInternalPage] = createSignal<number>(Math.max(1, options.defaultPage ?? 1));
+
+  const totalPages = createMemo<number>(() => {
+    const explicit = getExplicitTotalPages();
+    if (explicit !== undefined) {
+      return Math.max(1, explicit);
+    }
+    const count = getCount();
+    const size = getPageSize();
+    return Math.max(1, Math.ceil(count / size));
+  });
+
+  const rawPage = () => {
+    if (typeof options.page === "function") {
+      return options.page();
+    }
+    if (typeof options.page === "number") {
+      return options.page;
+    }
+    return internalPage();
+  };
+
+  const page = createMemo<number>(() => {
+    const p = rawPage();
+    const max = totalPages();
+    if (p < 1) return 1;
+    if (p > max) return max;
+    return p;
+  });
+
+  const setPage = (nextPage: number) => {
+    const max = totalPages();
+    const clamped = Math.max(1, Math.min(nextPage, max));
+    if (typeof options.page !== "function" && typeof options.page !== "number") {
+      setInternalPage(clamped);
+    }
+    options.onChange?.(clamped);
+  };
+
+  const next = () => setPage(page() + 1);
+  const previous = () => setPage(page() - 1);
+  const first = () => setPage(1);
+  const last = () => setPage(totalPages());
+
+  const hasNext = createMemo(() => page() < totalPages());
+  const hasPrevious = createMemo(() => page() > 1);
+
+  const startIndex = createMemo(() => {
+    const count = getCount();
+    if (count === 0 && getExplicitTotalPages() === undefined) return 0;
+    return (page() - 1) * getPageSize() + 1;
+  });
+
+  const endIndex = createMemo(() => {
+    const count = getCount();
+    const calculated = page() * getPageSize();
+    if (count > 0) {
+      return Math.min(calculated, count);
+    }
+    return calculated;
+  });
+
+  const range = createMemo<(number | "ellipsis")[]>(() => {
+    const total = totalPages();
+    const current = page();
+    const siblings = getSiblingCount();
+    const boundaries = getBoundaries();
+
+    if (total <= 1) {
+      return [1];
+    }
+
+    const pagesSet = new Set<number>();
+
+    // 1. Boundary pages at the start
+    for (let i = 1; i <= Math.min(boundaries, total); i++) {
+      pagesSet.add(i);
+    }
+
+    // 2. Sibling pages around current page
+    const leftSibling = Math.max(1, current - siblings);
+    const rightSibling = Math.min(total, current + siblings);
+    for (let i = leftSibling; i <= rightSibling; i++) {
+      pagesSet.add(i);
+    }
+
+    // 3. Boundary pages at the end
+    for (let i = Math.max(1, total - boundaries + 1); i <= total; i++) {
+      pagesSet.add(i);
+    }
+
+    const sortedPages = Array.from(pagesSet).sort((a, b) => a - b);
+    const result: (number | "ellipsis")[] = [];
+
+    for (let i = 0; i < sortedPages.length; i++) {
+      const currentPageNum = sortedPages[i];
+      if (i > 0) {
+        const prevPageNum = sortedPages[i - 1];
+        const gap = currentPageNum - prevPageNum;
+        if (gap === 2) {
+          result.push(prevPageNum + 1);
+        } else if (gap > 2) {
+          result.push("ellipsis");
+        }
+      }
+      result.push(currentPageNum);
+    }
+
+    return result;
+  });
+
+  return {
+    page,
+    totalPages,
+    pageSize: getPageSize,
+    range,
+    setPage,
+    next,
+    previous,
+    first,
+    last,
+    hasNext,
+    hasPrevious,
+    startIndex,
+    endIndex,
+  };
+}

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

@@ -0,0 +1,91 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export type PermissionNameType =
+  | "geolocation"
+  | "notifications"
+  | "persistent-storage"
+  | "push"
+  | "screen-wake-lock"
+  | "clipboard-read"
+  | "clipboard-write"
+  | "camera"
+  | "microphone"
+  | (string & {});
+
+export type PermissionStatusState = "granted" | "denied" | "prompt" | "unknown";
+
+export interface CreatePermissionOptions {
+  /** Permission descriptor or name to query. */
+  name: PermissionNameType;
+}
+
+export interface CreatePermissionReturn {
+  /** Signal accessor containing current permission status ('granted', 'denied', 'prompt', 'unknown'). */
+  state: Accessor<PermissionStatusState>;
+  /** Signal accessor indicating whether Permissions API is supported in browser environment. */
+  isSupported: Accessor<boolean>;
+  /** Imperative function to re-query permission status manually. */
+  query: () => Promise<PermissionStatusState>;
+}
+
+/**
+ * SolidJS reactive primitive for querying and observing browser permission status changes.
+ */
+export function createPermission(
+  options: PermissionNameType | CreatePermissionOptions
+): CreatePermissionReturn {
+  const [state, setState] = createSignal<PermissionStatusState>("unknown");
+
+  const permissionName = typeof options === "string" ? options : options.name;
+
+  const isSupported = (): boolean =>
+    typeof window !== "undefined" &&
+    typeof navigator !== "undefined" &&
+    "permissions" in navigator;
+
+  let permissionStatus: PermissionStatus | null = null;
+
+  const query = async (): Promise<PermissionStatusState> => {
+    if (!isSupported()) {
+      setState("unknown");
+      return "unknown";
+    }
+
+    try {
+      const status = await navigator.permissions.query({
+        name: permissionName as PermissionName,
+      });
+
+      permissionStatus = status;
+      const currentState = status.state as PermissionStatusState;
+      setState(currentState);
+
+      status.onchange = () => {
+        setState(status.state as PermissionStatusState);
+      };
+
+      return currentState;
+    } catch {
+      setState("unknown");
+      return "unknown";
+    }
+  };
+
+  createEffect(() => {
+    if (!isSupported()) return;
+
+    query();
+
+    onCleanup(() => {
+      if (permissionStatus) {
+        permissionStatus.onchange = null;
+      }
+    });
+  });
+
+  return {
+    state,
+    isSupported,
+    query,
+  };
+}

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

@@ -0,0 +1,21 @@
+import { createEffect, createSignal, type Accessor } from "solid-js";
+
+/**
+ * SolidJS reactive primitive for tracking previous value of a signal accessor.
+ *
+ * @param source Target reactive signal accessor to observe.
+ */
+export function createPrevious<T>(source: Accessor<T>): Accessor<T | undefined> {
+  const [previous, setPrevious] = createSignal<T | undefined>(undefined);
+  let current: T = source();
+
+  createEffect(() => {
+    const next = source();
+    if (current !== next) {
+      setPrevious(() => current);
+      current = next;
+    }
+  });
+
+  return previous;
+}

package/dist/vendor/hooks-src/create-resize-observer.ts

@@ -0,0 +1,89 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateResizeObserverOptions extends ResizeObserverOptions {
+  /** Whether the observer is active. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for observing element size changes via ResizeObserver.
+ *
+ * @param target Target element or accessor returning HTML element.
+ * @param callback Observer callback invoked on element resize events.
+ * @param options ResizeObserver options (box, enabled).
+ */
+export function createResizeObserver(
+  target: HTMLElement | Accessor<HTMLElement | undefined>,
+  callback: ResizeObserverCallback,
+  options: CreateResizeObserverOptions = {}
+): void {
+  const getTarget = (): HTMLElement | undefined => {
+    if (typeof target === "function") {
+      return (target as Accessor<HTMLElement | undefined>)();
+    }
+    return target;
+  };
+
+  const isEnabled = (): boolean => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  createEffect(() => {
+    if (typeof window === "undefined" || !window.ResizeObserver) {
+      return;
+    }
+
+    if (!isEnabled()) return;
+
+    const el = getTarget();
+    if (!el) return;
+
+    const observer = new ResizeObserver(callback);
+    observer.observe(el, { box: options.box });
+
+    onCleanup(() => {
+      observer.disconnect();
+    });
+  });
+}
+
+export interface CreateElementSizeReturn {
+  /** Accessor for element width in pixels */
+  width: Accessor<number>;
+  /** Accessor for element height in pixels */
+  height: Accessor<number>;
+}
+
+/**
+ * SolidJS reactive primitive returning width and height accessors for a target HTML element.
+ *
+ * @param target Target element or accessor returning HTML element.
+ * @param options ResizeObserver options.
+ */
+export function createElementSize(
+  target: HTMLElement | Accessor<HTMLElement | undefined>,
+  options: CreateResizeObserverOptions = {}
+): CreateElementSizeReturn {
+  const [width, setWidth] = createSignal(0);
+  const [height, setHeight] = createSignal(0);
+
+  createResizeObserver(
+    target,
+    (entries) => {
+      const entry = entries[0];
+      if (entry) {
+        setWidth(entry.contentRect.width);
+        setHeight(entry.contentRect.height);
+      }
+    },
+    options
+  );
+
+  return {
+    width,
+    height,
+  };
+}

package/dist/vendor/hooks-src/create-scroll-into-view.ts

@@ -0,0 +1,57 @@
+import { createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateScrollIntoViewOptions extends ScrollIntoViewOptions {
+  /** Whether the element should scroll into view automatically. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Delay in milliseconds before executing scrollIntoView. Defaults to 0. */
+  delay?: number;
+}
+
+/**
+ * SolidJS reactive primitive for scrolling a target element into view smooth or auto behavior.
+ */
+export function createScrollIntoView(
+  target: HTMLElement | Accessor<HTMLElement | null | undefined> | null | undefined,
+  options: CreateScrollIntoViewOptions = {}
+): void {
+  const getTarget = (): HTMLElement | null | undefined => {
+    if (typeof target === "function") {
+      return target();
+    }
+    return target;
+  };
+
+  const isEnabled = (): boolean => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  createEffect(() => {
+    if (!isEnabled()) return;
+
+    const el = getTarget();
+    if (!el || typeof window === "undefined") return;
+
+    const scrollOptions: ScrollIntoViewOptions = {
+      behavior: options.behavior ?? "smooth",
+      block: options.block ?? "nearest",
+      inline: options.inline ?? "nearest",
+    };
+
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    if (options.delay && options.delay > 0) {
+      timer = setTimeout(() => {
+        el.scrollIntoView(scrollOptions);
+      }, options.delay);
+    } else {
+      el.scrollIntoView(scrollOptions);
+    }
+
+    onCleanup(() => {
+      if (timer) clearTimeout(timer);
+    });
+  });
+}