@nikala-ui/docs 0.12.0

package/dist/vendor/hooks-src/create-event-source.ts

@@ -0,0 +1,126 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export type EventSourceStatus = "CONNECTING" | "OPEN" | "CLOSED";
+
+export interface CreateEventSourceOptions {
+  /** Event names to listen to on the EventSource. Defaults to ['message']. */
+  events?: string[];
+  /** Include credentials in CORS requests. */
+  withCredentials?: boolean;
+  /** Whether to open connection immediately. Defaults to true. */
+  immediate?: boolean;
+  /** Callback fired when connection is opened. */
+  onOpen?: (event: Event) => void;
+  /** Callback fired when message event is received. */
+  onMessage?: (event: MessageEvent) => void;
+  /** Callback fired when error occurs. */
+  onError?: (event: Event) => void;
+}
+
+export interface CreateEventSourceReturn<T = unknown> {
+  /** Signal accessor containing latest received SSE event data (parsed if JSON). */
+  data: Accessor<T | null>;
+  /** Signal accessor containing current EventSource status. */
+  status: Accessor<EventSourceStatus>;
+  /** Signal accessor containing last raw MessageEvent. */
+  event: Accessor<MessageEvent | null>;
+  /** Open or reconnect EventSource stream. */
+  open: () => void;
+  /** Close active EventSource stream. */
+  close: () => void;
+  /** Signal accessor indicating whether EventSource is supported in browser environment. */
+  isSupported: Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for subscribing to Server-Sent Events (SSE) streams.
+ */
+export function createEventSource<T = unknown>(
+  url: string | Accessor<string>,
+  options: CreateEventSourceOptions = {}
+): CreateEventSourceReturn<T> {
+  const [data, setData] = createSignal<T | null>(null);
+  const [event, setEvent] = createSignal<MessageEvent | null>(null);
+  const [status, setStatus] = createSignal<EventSourceStatus>("CLOSED");
+
+  const getUrl = (): string => (typeof url === "function" ? url() : url);
+
+  const isSupported = (): boolean =>
+    typeof window !== "undefined" && "EventSource" in window;
+
+  let es: EventSource | null = null;
+
+  const close = (): void => {
+    if (es) {
+      es.close();
+      es = null;
+      setStatus("CLOSED");
+    }
+  };
+
+  const open = (): void => {
+    if (!isSupported()) return;
+
+    close();
+
+    setStatus("CONNECTING");
+
+    try {
+      const source = new EventSource(getUrl(), {
+        withCredentials: options.withCredentials,
+      });
+      es = source;
+
+      source.onopen = (e) => {
+        setStatus("OPEN");
+        options.onOpen?.(e);
+      };
+
+      source.onerror = (e) => {
+        if (source.readyState === EventSource.CLOSED) {
+          setStatus("CLOSED");
+        } else if (source.readyState === EventSource.CONNECTING) {
+          setStatus("CONNECTING");
+        }
+        options.onError?.(e);
+      };
+
+      const eventList = options.events ?? ["message"];
+      eventList.forEach((eventName) => {
+        source.addEventListener(eventName, (e) => {
+          const msgEvt = e as MessageEvent;
+          setEvent(() => msgEvt);
+          try {
+            const parsed = JSON.parse(msgEvt.data);
+            setData(() => parsed);
+          } catch {
+            setData(() => msgEvt.data as unknown as T);
+          }
+          options.onMessage?.(msgEvt);
+        });
+      });
+    } catch {
+      setStatus("CLOSED");
+      es = null;
+    }
+  };
+
+  createEffect(() => {
+    if (options.immediate ?? true) {
+      open();
+    }
+
+    onCleanup(() => {
+      close();
+    });
+  });
+
+  return {
+    data,
+    status,
+    event,
+    open,
+    close,
+    isSupported,
+  };
+}

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

@@ -0,0 +1,52 @@
+import { createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateFaviconOptions {
+  /** Favicon rel attribute value. Defaults to 'icon'. */
+  rel?: string;
+  /** Favicon image mime-type format (e.g., 'image/x-icon', 'image/svg+xml', 'image/png'). */
+  type?: string;
+  /** Whether to restore original favicon on component unmount. Defaults to true. */
+  restoreOnUnmount?: boolean;
+}
+
+/**
+ * SolidJS reactive primitive for dynamically updating browser favicon element.
+ */
+export function createFavicon(
+  href: string | Accessor<string>,
+  options: CreateFaviconOptions = {}
+): void {
+  const getHref = (): string => (typeof href === "function" ? href() : href);
+
+  createEffect(() => {
+    if (typeof document === "undefined") return;
+
+    const rel = options.rel ?? "icon";
+    let linkElement: HTMLLinkElement | null = document.querySelector(
+      `link[rel*="${rel}"]`
+    );
+
+    const originalHref = linkElement ? linkElement.href : "";
+
+    if (!linkElement) {
+      linkElement = document.createElement("link");
+      linkElement.rel = rel;
+      if (options.type) linkElement.type = options.type;
+      document.head.appendChild(linkElement);
+    }
+
+    const newHref = getHref();
+    if (newHref) {
+      linkElement.href = newHref;
+      if (options.type) linkElement.type = options.type;
+    }
+
+    onCleanup(() => {
+      if (typeof document !== "undefined" && (options.restoreOnUnmount ?? true) && linkElement) {
+        if (originalHref) {
+          linkElement.href = originalHref;
+        }
+      }
+    });
+  });
+}

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

@@ -0,0 +1,93 @@
+import { createSignal, createEffect, type Accessor } from "solid-js";
+
+export interface CreateFetchOptions<T> extends RequestInit {
+  /** Whether the request should be refetched automatically on window focus. Defaults to false. */
+  refetchOnFocus?: boolean;
+  /** Custom transform function to process raw JSON / text response into required shape. */
+  transform?: (data: unknown) => T;
+  /** Whether the initial request should execute immediately. Defaults to true. */
+  immediate?: boolean;
+}
+
+export interface CreateFetchReturn<T> {
+  /** Signal containing fetched data. */
+  data: Accessor<T | null>;
+  /** Signal indicating whether request is loading. */
+  isLoading: Accessor<boolean>;
+  /** Signal containing request error if fetch failed. */
+  error: Accessor<Error | null>;
+  /** Imperative function to refetch data manually. */
+  refetch: () => Promise<void>;
+  /** Abort ongoing HTTP request. */
+  abort: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for handling HTTP fetch requests, loading states, errors, and manual refetching.
+ */
+export function createFetch<T = unknown>(
+  url: string | Accessor<string>,
+  options: CreateFetchOptions<T> = {}
+): CreateFetchReturn<T> {
+  const [data, setData] = createSignal<T | null>(null);
+  const [isLoading, setIsLoading] = createSignal(options.immediate ?? true);
+  const [error, setError] = createSignal<Error | null>(null);
+
+  let controller: AbortController | null = null;
+
+  const getUrl = (): string => {
+    return typeof url === "function" ? url() : url;
+  };
+
+  const abort = (): void => {
+    if (controller) {
+      controller.abort();
+      controller = null;
+    }
+  };
+
+  const executeFetch = async (): Promise<void> => {
+    if (typeof window === "undefined") return;
+
+    abort();
+    controller = new AbortController();
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const response = await fetch(getUrl(), {
+        ...options,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`);
+      }
+
+      const raw = await response.json();
+      const result = options.transform ? options.transform(raw) : (raw as T);
+
+      setData(() => result);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  createEffect(() => {
+    if (options.immediate ?? true) {
+      executeFetch();
+    }
+  });
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: executeFetch,
+    abort,
+  };
+}

package/dist/vendor/hooks-src/create-focus-trap.ts

@@ -0,0 +1,94 @@
+import { createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateFocusTrapOptions {
+  /** Whether focus trap is actively enabled. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Whether to return focus to previously focused element on cleanup. Defaults to true. */
+  returnFocusOnDeactivate?: boolean;
+}
+
+const FOCUSABLE_SELECTOR =
+  'a[href], area[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), iframe, object, embed, [tabindex]:not([tabindex="-1"]), [contenteditable]';
+
+/**
+ * SolidJS reactive primitive for trapping keyboard focus inside target container element.
+ *
+ * @param target Target element or accessor returning HTML element.
+ * @param options Configuration options for focus trap behavior.
+ */
+export function createFocusTrap(
+  target: HTMLElement | Accessor<HTMLElement | undefined>,
+  options: CreateFocusTrapOptions = {}
+): 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" || !isEnabled()) return;
+
+    const container = getTarget();
+    if (!container) return;
+
+    const previousActiveElement = document.activeElement as HTMLElement | null;
+
+    const getFocusableElements = (): HTMLElement[] => {
+      return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+        (el) => el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0
+      );
+    };
+
+    const focusable = getFocusableElements();
+    if (focusable.length > 0) {
+      focusable[0].focus();
+    } else {
+      container.focus();
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Tab") return;
+
+      const elements = getFocusableElements();
+      if (elements.length === 0) {
+        event.preventDefault();
+        return;
+      }
+
+      const firstElement = elements[0];
+      const lastElement = elements[elements.length - 1];
+      const activeElement = document.activeElement;
+
+      if (event.shiftKey) {
+        if (activeElement === firstElement || !container.contains(activeElement)) {
+          event.preventDefault();
+          lastElement.focus();
+        }
+      } else {
+        if (activeElement === lastElement || !container.contains(activeElement)) {
+          event.preventDefault();
+          firstElement.focus();
+        }
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+
+    onCleanup(() => {
+      document.removeEventListener("keydown", handleKeyDown);
+
+      if (options.returnFocusOnDeactivate !== false && previousActiveElement) {
+        previousActiveElement.focus?.();
+      }
+    });
+  });
+}

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

@@ -0,0 +1,200 @@
+import { createSignal, createMemo, type Accessor } from "solid-js";
+
+export type FormErrors<T> = Partial<Record<keyof T, string>>;
+export type FormTouched<T> = Partial<Record<keyof T, boolean>>;
+export type ValidateOn = "change" | "blur" | "submit";
+
+export type FormInputEvent = Event & {
+  currentTarget:
+    | HTMLInputElement
+    | HTMLTextAreaElement
+    | HTMLSelectElement;
+};
+
+export interface CreateFormOptions<T extends Record<string, any>> {
+  /** Initial form field values object */
+  initialValues: T;
+  /** Custom validation function returning error messages object */
+  validate?: (values: T) => FormErrors<T> | Promise<FormErrors<T>>;
+  /** Event that triggers validation. Defaults to "change". */
+  validateOn?: ValidateOn;
+  /** Submit handler callback invoked when validation succeeds */
+  onSubmit?: (values: T) => void | Promise<void>;
+}
+
+export interface CreateFormReturn<T extends Record<string, any>> {
+  /** Accessor for current form field values */
+  values: Accessor<T>;
+  /** Accessor for form field validation error messages */
+  errors: Accessor<FormErrors<T>>;
+  /** Accessor for form field touched states */
+  touched: Accessor<FormTouched<T>>;
+  /** Accessor indicating if form is currently submitting */
+  isSubmitting: Accessor<boolean>;
+  /** Accessor containing an exception thrown by onSubmit, if any */
+  submitError: Accessor<unknown>;
+  /** Accessor indicating if form has zero validation errors */
+  isValid: Accessor<boolean>;
+  /** Accessor indicating if form values differ from initial values */
+  isDirty: Accessor<boolean>;
+  /** Update specific form field value */
+  setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void;
+  /** Set specific form field validation error */
+  setFieldError: <K extends keyof T>(field: K, error: string | undefined) => void;
+  /** Set specific form field touched state */
+  setFieldTouched: <K extends keyof T>(field: K, isTouched?: boolean) => void;
+  /** Input change event listener helper factory function */
+  handleChange: <K extends keyof T>(field: K) => (e: FormInputEvent) => void;
+  /** Input blur event listener helper factory function */
+  handleBlur: <K extends keyof T>(field: K) => () => void;
+  /** Form onSubmit event handler */
+  handleSubmit: (e?: Event) => Promise<void>;
+  /** Reset form values, errors, and touched states to initial values */
+  resetForm: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for managing form field state, validation, errors, and submission.
+ *
+ * @param options Form configuration options including initialValues and validate function.
+ */
+export function createForm<T extends Record<string, any>>(
+  options: CreateFormOptions<T>
+): CreateFormReturn<T> {
+  const initialValues = { ...options.initialValues };
+
+  const [values, setValues] = createSignal<T>({ ...initialValues });
+  const [errors, setErrors] = createSignal<FormErrors<T>>({});
+  const [touched, setTouched] = createSignal<FormTouched<T>>({});
+  const [isSubmitting, setIsSubmitting] = createSignal(false);
+  const [submitError, setSubmitError] = createSignal<unknown>();
+  const validateOn = options.validateOn ?? "change";
+  let validationSequence = 0;
+
+  const isDirty = createMemo(() => {
+    const current = values();
+    return Object.keys(initialValues).some((key) => current[key] !== initialValues[key]);
+  });
+
+  const isValid = createMemo(() => {
+    const errs = errors();
+    return Object.keys(errs).length === 0;
+  });
+
+  const runValidation = async (currentValues: T): Promise<FormErrors<T>> => {
+    const sequence = ++validationSequence;
+    if (!options.validate) {
+      setErrors(() => ({}));
+      return {};
+    }
+
+    const result = await options.validate(currentValues);
+    const newErrors = result || {};
+    // Ignore stale async validations that finished after a newer request.
+    if (sequence === validationSequence) {
+      setErrors(() => newErrors);
+    }
+    return newErrors;
+  };
+
+  const setFieldValue = <K extends keyof T>(field: K, value: T[K]) => {
+    const next = { ...values(), [field]: value };
+    setValues(() => next);
+    if (validateOn === "change") {
+      void runValidation(next);
+    }
+  };
+
+  const setFieldError = <K extends keyof T>(field: K, error: string | undefined) => {
+    setErrors((prev) => {
+      const next = { ...prev };
+      if (error) next[field] = error;
+      else delete next[field];
+      return next;
+    });
+  };
+
+  const setFieldTouched = <K extends keyof T>(field: K, isTouched = true) => {
+    setTouched((prev) => ({ ...prev, [field]: isTouched }));
+  };
+
+  const handleChange = <K extends keyof T>(field: K) => {
+    return (e: FormInputEvent) => {
+      const target = e.currentTarget;
+      let value: unknown = target.value;
+
+      if (
+        "checked" in target &&
+        ((target as HTMLInputElement).type === "checkbox" ||
+          (target as HTMLInputElement).type === "radio")
+      ) {
+        value = (target as HTMLInputElement).checked;
+      } else if ("selectedOptions" in target && target.multiple) {
+        value = Array.from(target.selectedOptions, (option) => option.value);
+      }
+
+      setFieldValue(field, value as T[K]);
+    };
+  };
+
+  const handleBlur = <K extends keyof T>(field: K) => {
+    return () => {
+      setFieldTouched(field, true);
+      if (validateOn === "blur") {
+        void runValidation(values());
+      }
+    };
+  };
+
+  const handleSubmit = async (e?: Event) => {
+    e?.preventDefault();
+    setIsSubmitting(true);
+    setSubmitError(undefined);
+
+    // Mark all fields as touched on submit
+    const allTouched = Object.keys(values()).reduce((acc, key) => {
+      acc[key as keyof T] = true;
+      return acc;
+    }, {} as FormTouched<T>);
+    setTouched(() => allTouched);
+
+    try {
+      const validationErrors = await runValidation(values());
+      if (Object.keys(validationErrors).length === 0 && options.onSubmit) {
+        try {
+          await options.onSubmit(values());
+        } catch (error) {
+          setSubmitError(() => error);
+        }
+      }
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  const resetForm = () => {
+    setValues(() => ({ ...initialValues }));
+    setErrors(() => ({}));
+    setTouched(() => ({}));
+    setIsSubmitting(false);
+    setSubmitError(undefined);
+    validationSequence += 1;
+  };
+
+  return {
+    values,
+    errors,
+    touched,
+    isSubmitting,
+    submitError,
+    isValid,
+    isDirty,
+    setFieldValue,
+    setFieldError,
+    setFieldTouched,
+    handleChange,
+    handleBlur,
+    handleSubmit,
+    resetForm,
+  };
+}

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

@@ -0,0 +1,105 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateFullscreenOptions {
+  /** Target element accessor or reference. Defaults to document.documentElement. */
+  target?: HTMLElement | Accessor<HTMLElement | undefined>;
+  /** Callback fired when entering fullscreen mode. */
+  onEnter?: () => void;
+  /** Callback fired when exiting fullscreen mode. */
+  onExit?: () => void;
+  /** Callback fired when fullscreen request fails. */
+  onError?: (err: Event) => void;
+}
+
+export interface CreateFullscreenReturn {
+  /** Signal indicating whether fullscreen mode is currently active. */
+  isFullscreen: Accessor<boolean>;
+  /** Request full screen mode for target element. */
+  enter: () => Promise<void>;
+  /** Exit full screen mode. */
+  exit: () => Promise<void>;
+  /** Toggle full screen mode. */
+  toggle: () => Promise<void>;
+}
+
+/**
+ * SolidJS reactive primitive for requesting and monitoring element fullscreen status.
+ */
+export function createFullscreen(
+  options: CreateFullscreenOptions = {}
+): CreateFullscreenReturn {
+  const [isFullscreen, setIsFullscreen] = createSignal(false);
+
+  const getTarget = (): HTMLElement | undefined => {
+    if (typeof document === "undefined") return undefined;
+    if (typeof options.target === "function") {
+      return options.target() ?? document.documentElement;
+    }
+    return options.target ?? document.documentElement;
+  };
+
+  const updateStatus = (): void => {
+    if (typeof document === "undefined") return;
+    const activeEl = document.fullscreenElement;
+    const isTargetFullscreen = Boolean(activeEl && activeEl === getTarget());
+    setIsFullscreen(isTargetFullscreen);
+  };
+
+  const enter = async (): Promise<void> => {
+    if (typeof window === "undefined") return;
+    const el = getTarget();
+    if (el?.requestFullscreen) {
+      await el.requestFullscreen();
+    }
+  };
+
+  const exit = async (): Promise<void> => {
+    if (typeof document === "undefined") return;
+    if (document.fullscreenElement && document.exitFullscreen) {
+      await document.exitFullscreen();
+    }
+  };
+
+  const toggle = async (): Promise<void> => {
+    if (isFullscreen()) {
+      await exit();
+    } else {
+      await enter();
+    }
+  };
+
+  createEffect(() => {
+    if (typeof document === "undefined") return;
+
+    const handleFullscreenChange = (): void => {
+      const activeEl = document.fullscreenElement;
+      const isTarget = Boolean(activeEl && activeEl === getTarget());
+      setIsFullscreen(isTarget);
+
+      if (isTarget) {
+        options.onEnter?.();
+      } else {
+        options.onExit?.();
+      }
+    };
+
+    const handleFullscreenError = (err: Event): void => {
+      options.onError?.(err);
+    };
+
+    document.addEventListener("fullscreenchange", handleFullscreenChange);
+    document.addEventListener("fullscreenerror", handleFullscreenError);
+
+    onCleanup(() => {
+      document.removeEventListener("fullscreenchange", handleFullscreenChange);
+      document.removeEventListener("fullscreenerror", handleFullscreenError);
+    });
+  });
+
+  return {
+    isFullscreen,
+    enter,
+    exit,
+    toggle,
+  };
+}