@nikala-ui/folio 0.13.0

package/dist/vendor/docs-src/hooks/create-keybindings.ts

@@ -0,0 +1,148 @@
+import { onMount, onCleanup, type Accessor } from "solid-js";
+
+export interface KeybindingDefinition {
+  /** Key combination string, e.g. "meta+k", "ctrl+k", "Escape", "Shift+Enter" */
+  key: string | string[];
+  /** Callback handler invoked when the key combination is triggered */
+  handler: (event: KeyboardEvent) => void;
+  /** Whether to prevent default browser action. Defaults to false. */
+  preventDefault?: boolean;
+  /** Whether to stop event propagation. Defaults to false. */
+  stopPropagation?: boolean;
+}
+
+export interface CreateKeybindingsOptions {
+  /** Event target to attach listener to. Defaults to window. */
+  target?: HTMLElement | Window | Accessor<HTMLElement | Window | undefined>;
+  /** Event type: "keydown" (default) or "keyup" */
+  eventType?: "keydown" | "keyup";
+  /** Whether keybinding listeners are active. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+}
+
+/**
+ * Normalizes key string into standardized combination signature (e.g. "ctrl+meta+k").
+ */
+function normalizeKeyCombination(keyStr: string): string {
+  const parts = keyStr.toLowerCase().split("+").map((p) => p.trim());
+  const modifiers = new Set<string>();
+  let mainKey = "";
+
+  for (const part of parts) {
+    if (part === "meta" || part === "cmd" || part === "command" || part === "⌘") {
+      modifiers.add("meta");
+    } else if (part === "ctrl" || part === "control") {
+      modifiers.add("ctrl");
+    } else if (part === "alt" || part === "option" || part === "⌥") {
+      modifiers.add("alt");
+    } else if (part === "shift" || part === "⇧") {
+      modifiers.add("shift");
+    } else {
+      mainKey = part;
+    }
+  }
+
+  const sortedMods = Array.from(modifiers).sort();
+  return [...sortedMods, mainKey].join("+");
+}
+
+/**
+ * Checks if a KeyboardEvent matches a normalized key combination.
+ */
+function isEventMatch(event: KeyboardEvent, targetCombination: string): boolean {
+  const modifiers = new Set<string>();
+  if (event.metaKey) modifiers.add("meta");
+  if (event.ctrlKey) modifiers.add("ctrl");
+  if (event.altKey) modifiers.add("alt");
+  if (event.shiftKey) modifiers.add("shift");
+
+  const mainKey = event.key.toLowerCase();
+  const eventCombination = [...Array.from(modifiers).sort(), mainKey].join("+");
+
+  return eventCombination === targetCombination;
+}
+
+/**
+ * SolidJS reactive primitive for listening to single or multiple keyboard shortcuts.
+ *
+ * @param bindings Array of keybinding definitions or single definition object.
+ * @param options Configuration options including target, event type, and enabled state.
+ */
+export function createKeybindings(
+  bindings: KeybindingDefinition | KeybindingDefinition[],
+  options: CreateKeybindingsOptions = {}
+): void {
+  const bindingList = Array.isArray(bindings) ? bindings : [bindings];
+
+  const isEnabled = () => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  const getTargetElement = (): HTMLElement | Window | undefined => {
+    if (!options.target) {
+      return typeof window !== "undefined" ? window : undefined;
+    }
+    if (typeof options.target === "function") {
+      return (options.target as Accessor<HTMLElement | Window | undefined>)();
+    }
+    return options.target;
+  };
+
+  const handleKeyboardEvent = (event: KeyboardEvent) => {
+    if (!isEnabled()) return;
+
+    for (const binding of bindingList) {
+      const keys = Array.isArray(binding.key) ? binding.key : [binding.key];
+
+      for (const keyCombo of keys) {
+        const normalizedCombo = normalizeKeyCombination(keyCombo);
+
+        if (isEventMatch(event, normalizedCombo)) {
+          if (binding.preventDefault) {
+            event.preventDefault();
+          }
+          if (binding.stopPropagation) {
+            event.stopPropagation();
+          }
+          binding.handler(event);
+          break;
+        }
+      }
+    }
+  };
+
+  onMount(() => {
+    const target = getTargetElement();
+    if (!target) return;
+
+    const eventType = options.eventType || "keydown";
+    target.addEventListener(eventType, handleKeyboardEvent as EventListener);
+
+    onCleanup(() => {
+      target.removeEventListener(eventType, handleKeyboardEvent as EventListener);
+    });
+  });
+}
+
+/**
+ * SolidJS primitive specialized for handling Escape key presses.
+ *
+ * @param handler Callback invoked when Escape key is pressed.
+ * @param options Keybindings options.
+ */
+export function createEscapeKey(
+  handler: (event: KeyboardEvent) => void,
+  options: CreateKeybindingsOptions = {}
+): void {
+  createKeybindings(
+    {
+      key: "Escape",
+      handler,
+      preventDefault: true,
+    },
+    options
+  );
+}

package/dist/vendor/docs-src/hooks/create-lock-scroll.ts

@@ -0,0 +1,97 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateLockScrollOptions {
+  /** Target element to lock scroll for. Defaults to document.body. */
+  target?: HTMLElement | Accessor<HTMLElement | undefined>;
+  /** Initial lock state. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+}
+
+export interface CreateLockScrollReturn {
+  /** Accessor indicating whether scroll is currently locked */
+  isLocked: Accessor<boolean>;
+  /** Setter function to programmatically lock or unlock scroll */
+  setLocked: (locked: boolean) => void;
+}
+
+/**
+ * SolidJS reactive primitive for locking target element (or document.body) scroll.
+ *
+ * @param options Configuration options including target element and initial enabled state.
+ */
+export function createLockScroll(options: CreateLockScrollOptions = {}): CreateLockScrollReturn {
+  const [internalLocked, setInternalLocked] = createSignal(false);
+
+  const getTarget = (): HTMLElement | undefined => {
+    if (typeof window === "undefined") return undefined;
+
+    if (!options.target) {
+      return document.body;
+    }
+    if (typeof options.target === "function") {
+      return (options.target as Accessor<HTMLElement | undefined>)();
+    }
+    return options.target;
+  };
+
+  const isEnabled = (): boolean => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  let originalOverflow: string | undefined;
+
+  const applyLock = (element: HTMLElement) => {
+    if (originalOverflow === undefined) {
+      originalOverflow = element.style.overflow;
+    }
+    element.style.overflow = "hidden";
+    setInternalLocked(true);
+  };
+
+  const removeLock = (element: HTMLElement) => {
+    if (originalOverflow !== undefined) {
+      element.style.overflow = originalOverflow;
+      originalOverflow = undefined;
+    } else {
+      element.style.overflow = "";
+    }
+    setInternalLocked(false);
+  };
+
+  createEffect(() => {
+    const el = getTarget();
+    if (!el) return;
+
+    if (isEnabled()) {
+      applyLock(el);
+    } else {
+      removeLock(el);
+    }
+  });
+
+  onCleanup(() => {
+    const el = getTarget();
+    if (el) {
+      removeLock(el);
+    }
+  });
+
+  const setLocked = (locked: boolean) => {
+    const el = getTarget();
+    if (!el) return;
+
+    if (locked) {
+      applyLock(el);
+    } else {
+      removeLock(el);
+    }
+  };
+
+  return {
+    isLocked: internalLocked,
+    setLocked,
+  };
+}

package/dist/vendor/docs-src/hooks/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/docs-src/hooks/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/docs-src/lib/cn.ts

@@ -0,0 +1,9 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Combines multiple class names and resolves Tailwind CSS conflicts.
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/dist/vendor/docs-src/providers/theme-provider.tsx

@@ -0,0 +1,203 @@
+import {
+  createContext,
+  createEffect,
+  createSignal,
+  onCleanup,
+  onMount,
+  useContext,
+  type ParentComponent,
+  type Accessor,
+} from "solid-js";
+import {
+  getAccentCssVariables,
+  isDocsAccentColor,
+  type DocsAccentColor,
+} from "../theme-accent.js";
+
+export type Theme = "light" | "dark" | "system";
+export type AccentColor = DocsAccentColor;
+export type Radius = "0" | "0.3" | "0.5" | "0.75" | "1.0";
+
+export interface ThemeProviderProps {
+  /** Initial default theme mode if no saved preference is found in localStorage */
+  defaultTheme?: Theme;
+  /** Initial default accent color override if needed */
+  defaultAccent?: AccentColor;
+  /** Initial default border radius override if needed */
+  defaultRadius?: Radius;
+  /** Key used to store theme preferences in localStorage */
+  storageKey?: string;
+}
+
+interface ThemeProviderContextValue {
+  theme: Accessor<Theme>;
+  setTheme: (theme: Theme) => void;
+  accent: Accessor<AccentColor | undefined>;
+  setAccent: (accent: AccentColor) => void;
+  radius: Accessor<Radius | undefined>;
+  setRadius: (radius: Radius) => void;
+}
+
+const ThemeProviderContext = createContext<ThemeProviderContextValue>();
+
+/**
+ * Context provider managing application theme state (light/dark/system), accent colors, and border radius.
+ */
+export const ThemeProvider: ParentComponent<ThemeProviderProps> = (props) => {
+  const storageKey = props.storageKey || "nikala-theme";
+  const defaultTheme = props.defaultTheme || "system";
+
+  // Safely read saved values from localStorage without forcing unnecessary fallbacks
+  const getInitialTheme = (): Theme => {
+    if (typeof window === "undefined") return defaultTheme;
+    try {
+      const saved = localStorage.getItem(`${storageKey}-mode`);
+      if (saved === "light" || saved === "dark" || saved === "system") return saved;
+    } catch { }
+    return defaultTheme;
+  };
+
+  const getInitialAccent = (): AccentColor | undefined => {
+    if (typeof window === "undefined") return props.defaultAccent;
+    try {
+      const saved = localStorage.getItem(`${storageKey}-accent`);
+      if (isDocsAccentColor(saved)) return saved;
+    } catch { }
+    return props.defaultAccent;
+  };
+
+  const getInitialRadius = (): Radius | undefined => {
+    if (typeof window === "undefined") return props.defaultRadius;
+    try {
+      const saved = localStorage.getItem(`${storageKey}-radius`);
+      if (saved) return saved as Radius;
+    } catch { }
+    return props.defaultRadius;
+  };
+
+  const [theme, setThemeSignal] = createSignal<Theme>(getInitialTheme());
+  const [accent, setAccentSignal] = createSignal<AccentColor | undefined>(getInitialAccent());
+  const [radius, setRadiusSignal] = createSignal<Radius | undefined>(getInitialRadius());
+
+  // Applies classes and CSS custom properties when custom overrides are explicitly set
+  const applyTheme = (
+    targetTheme: Theme,
+    currentAccent: AccentColor | undefined,
+    currentRadius: Radius | undefined
+  ) => {
+    if (typeof window === "undefined") return;
+
+    const root = document.documentElement;
+    root.classList.remove("light", "dark");
+
+    let resolvedDark = false;
+    if (targetTheme === "system") {
+      resolvedDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+      root.classList.add(resolvedDark ? "dark" : "light");
+    } else {
+      resolvedDark = targetTheme === "dark";
+      root.classList.add(targetTheme);
+    }
+    root.style.colorScheme = resolvedDark ? "dark" : "light";
+
+    // Override --primary CSS variables ONLY if explicitly chosen
+    if (currentAccent && isDocsAccentColor(currentAccent)) {
+      const accentTokens = getAccentCssVariables(currentAccent, resolvedDark);
+      root.style.setProperty("--primary", accentTokens.primary);
+      root.style.setProperty("--primary-foreground", accentTokens.foreground);
+    } else {
+      root.style.removeProperty("--primary");
+      root.style.removeProperty("--primary-foreground");
+    }
+
+    // Override --radius CSS variable ONLY if explicitly chosen
+    if (currentRadius) {
+      root.style.setProperty("--radius", `${currentRadius}rem`);
+    } else {
+      root.style.removeProperty("--radius");
+    }
+  };
+
+  // Reactively apply theme updates and store preferences in localStorage
+  createEffect(() => {
+    const t = theme();
+    const a = accent();
+    const r = radius();
+
+    applyTheme(t, a, r);
+
+    if (typeof window !== "undefined") {
+      try {
+        localStorage.setItem(`${storageKey}-mode`, t);
+        if (a) localStorage.setItem(`${storageKey}-accent`, a);
+        else localStorage.removeItem(`${storageKey}-accent`);
+        if (r) localStorage.setItem(`${storageKey}-radius`, r);
+        else localStorage.removeItem(`${storageKey}-radius`);
+      } catch { }
+    }
+  });
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+
+    const handleSystemChange = (e: MediaQueryListEvent) => {
+      if (theme() === "system") {
+        const root = document.documentElement;
+        root.classList.remove("light", "dark");
+        root.classList.add(e.matches ? "dark" : "light");
+        root.style.colorScheme = e.matches ? "dark" : "light";
+
+        const currentAccent = accent();
+        if (currentAccent && isDocsAccentColor(currentAccent)) {
+          const accentTokens = getAccentCssVariables(currentAccent, e.matches);
+          root.style.setProperty("--primary", accentTokens.primary);
+          root.style.setProperty("--primary-foreground", accentTokens.foreground);
+        }
+      }
+    };
+
+    if (mediaQuery.addEventListener) {
+      mediaQuery.addEventListener("change", handleSystemChange);
+    } else if ("addListener" in mediaQuery) {
+      (mediaQuery as any).addListener(handleSystemChange);
+    }
+
+    onCleanup(() => {
+      if (mediaQuery.removeEventListener) {
+        mediaQuery.removeEventListener("change", handleSystemChange);
+      } else if ("removeListener" in mediaQuery) {
+        (mediaQuery as any).removeListener(handleSystemChange);
+      }
+    });
+  });
+
+  const value: ThemeProviderContextValue = {
+    theme,
+    setTheme: (newTheme: Theme) => setThemeSignal(newTheme),
+    accent,
+    setAccent: (newAccent: AccentColor) => setAccentSignal(newAccent),
+    radius,
+    setRadius: (newRadius: Radius) => setRadiusSignal(newRadius),
+  };
+
+  return (
+    <ThemeProviderContext.Provider value={value}>
+      {props.children}
+    </ThemeProviderContext.Provider>
+  );
+};
+
+/**
+ * Accesses Nikala UI theme state, accent colors, border radius, and update functions.
+ */
+export function useTheme(): ThemeProviderContextValue {
+  const context = useContext(ThemeProviderContext);
+  if (!context) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return context;
+}
+
+export { ThemeScript, type ThemeScriptProps } from "./theme-script";