@nikala-ui/folio 0.13.0

package/dist/vendor/docs-src/components/ui/theme-toggle.tsx

@@ -0,0 +1,238 @@
+import { splitProps, type Component, For, Show, type JSX } from "solid-js";
+import { Sun, Moon, Monitor } from "lucide-solid";
+import {
+  useTheme,
+  type AccentColor,
+  type Radius,
+  type Theme,
+} from "../../providers/theme-provider";
+import {
+  runThemeTransition,
+  type ThemeEffect,
+} from "../../providers/theme-transitions";
+import { Button, type ButtonProps } from "./button";
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+} from "./dropdown-menu";
+import { cn } from "@/lib/cn";
+
+export interface ThemeToggleProps
+  extends Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
+  /** Display mode: "button" (direct 1-click toggle), "mini" (compact dropdown), "max" (full customizer panel). Defaults to "mini". */
+  mode?: "button" | "mini" | "max";
+  /** Transition animation effect when changing themes ("none", "circular", "fade") */
+  effect?: ThemeEffect;
+  /** Button visual style variant when rendered as a button or dropdown trigger */
+  variant?: ButtonProps["variant"];
+  /** Button size */
+  size?: ButtonProps["size"];
+  class?: string;
+}
+
+const ACCENT_OPTIONS: { name: AccentColor; label: string; color: string }[] = [
+  { name: "yellow", label: "Yellow", color: "bg-yellow-500" },
+  { name: "red", label: "Red", color: "bg-red-500" },
+  { name: "violet", label: "Violet", color: "bg-violet-500" },
+  { name: "sky", label: "Sky", color: "bg-sky-500" },
+  { name: "emerald", label: "Emerald", color: "bg-emerald-500" },
+  { name: "zinc", label: "Zinc", color: "bg-zinc-800 dark:bg-zinc-200" },
+];
+
+const RADIUS_OPTIONS: { value: Radius; label: string }[] = [
+  { value: "0", label: "0" },
+  { value: "0.3", label: "0.3" },
+  { value: "0.5", label: "0.5" },
+  { value: "0.75", label: "0.75" },
+  { value: "1.0", label: "1.0" },
+];
+
+/**
+ * Interactive UI theme switcher supporting button, mini (dropdown), and max (customizer panel) modes with View Transition animations.
+ */
+export const ThemeToggle: Component<ThemeToggleProps> = (props) => {
+  const [local, rest] = splitProps(props, ["mode", "effect", "variant", "size", "class"]);
+  const { theme, setTheme, accent, setAccent, radius, setRadius } = useTheme();
+
+  const mode = () => local.mode || "mini";
+  const effect = () => local.effect || "none";
+
+  /* Reactive accessor determining whether dark mode is active */
+  const isDarkMode = () => {
+    const currentTheme = theme();
+    if (currentTheme === "dark") return true;
+    if (currentTheme === "light") return false;
+    if (typeof window !== "undefined") {
+      return window.matchMedia("(prefers-color-scheme: dark)").matches;
+    }
+    return false;
+  };
+
+  const changeThemeWithEffect = (newTheme: Theme, e: MouseEvent) => {
+    runThemeTransition(effect(), e, () => {
+      setTheme(newTheme);
+    });
+  };
+
+  const handleToggleClick = (e: MouseEvent) => {
+    const nextTheme: Theme = isDarkMode() ? "light" : "dark";
+    changeThemeWithEffect(nextTheme, e);
+  };
+
+  return (
+    <Show
+      when={mode() !== "button"}
+      fallback={
+        /* Button Mode: Direct 1-click Dark/Light switcher without dropdown */
+        <Button
+          variant={local.variant || "ghost"}
+          size={local.size || "icon"}
+          onClick={handleToggleClick}
+          class={cn("relative cursor-pointer", local.class)}
+          aria-label="Toggle theme"
+          {...rest}
+        >
+          <Show
+            when={isDarkMode()}
+            fallback={<Sun class="h-4 w-4 text-foreground transition-transform" />}
+          >
+            <Moon class="h-4 w-4 text-foreground transition-transform" />
+          </Show>
+          <span class="sr-only">Toggle theme</span>
+        </Button>
+      }
+    >
+      <DropdownMenu placement="bottom-end">
+        <DropdownMenuTrigger
+          as={Button}
+          variant={local.variant || "ghost"}
+          size={local.size || "icon"}
+          class={cn("relative cursor-pointer", local.class)}
+          {...rest}
+        >
+          {/* Reactive Sun / Moon Icon Toggle */}
+          <Show
+            when={isDarkMode()}
+            fallback={<Sun class="h-4 w-4 text-foreground transition-transform" />}
+          >
+            <Moon class="h-4 w-4 text-foreground transition-transform" />
+          </Show>
+          <span class="sr-only">Toggle theme</span>
+        </DropdownMenuTrigger>
+
+        <Show
+          when={mode() === "max"}
+          fallback={
+            /* Mini Mode: Compact Dropdown */
+            <DropdownMenuContent>
+              <DropdownMenuItem onClick={(e: MouseEvent) => changeThemeWithEffect("light", e)}>
+                <Sun class="mr-2 h-4 w-4 text-muted-foreground" />
+                Light
+              </DropdownMenuItem>
+
+              <DropdownMenuItem onClick={(e: MouseEvent) => changeThemeWithEffect("dark", e)}>
+                <Moon class="mr-2 h-4 w-4 text-muted-foreground" />
+                Dark
+              </DropdownMenuItem>
+
+              <DropdownMenuItem onClick={(e: MouseEvent) => changeThemeWithEffect("system", e)}>
+                <Monitor class="mr-2 h-4 w-4 text-muted-foreground" />
+                System
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          }
+        >
+          {/* Max Mode: Full Theme Customizer Panel */}
+          <DropdownMenuContent class="w-64">
+            <div class="p-2 space-y-2">
+              <DropdownMenuGroup>
+                <DropdownMenuLabel class="px-0 pt-0 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                  Theme Mode
+                </DropdownMenuLabel>
+                <div class="grid grid-cols-3 gap-1 my-1.5">
+                  <Button
+                    variant={theme() === "light" ? "default" : "outline"}
+                    size="sm"
+                    onClick={(e: MouseEvent) => changeThemeWithEffect("light", e)}
+                    class="h-8 text-xs cursor-pointer"
+                  >
+                    Light
+                  </Button>
+                  <Button
+                    variant={theme() === "dark" ? "default" : "outline"}
+                    size="sm"
+                    onClick={(e: MouseEvent) => changeThemeWithEffect("dark", e)}
+                    class="h-8 text-xs cursor-pointer"
+                  >
+                    Dark
+                  </Button>
+                  <Button
+                    variant={theme() === "system" ? "default" : "outline"}
+                    size="sm"
+                    onClick={(e: MouseEvent) => changeThemeWithEffect("system", e)}
+                    class="h-8 text-xs cursor-pointer"
+                  >
+                    System
+                  </Button>
+                </div>
+              </DropdownMenuGroup>
+
+              <DropdownMenuSeparator class="my-2" />
+
+              <DropdownMenuGroup>
+                <DropdownMenuLabel class="px-0 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                  Brand Accent Color
+                </DropdownMenuLabel>
+                <div class="flex flex-wrap gap-1.5 my-1.5">
+                  <For each={ACCENT_OPTIONS}>
+                    {(opt) => (
+                      <button
+                        type="button"
+                        title={opt.label}
+                        onClick={() => setAccent(opt.name)}
+                        class={cn(
+                          "h-6 w-6 rounded-md transition-all cursor-pointer border border-border flex items-center justify-center",
+                          opt.color,
+                          accent() === opt.name
+                            ? "ring-2 ring-primary ring-offset-2 ring-offset-background scale-110"
+                            : "hover:scale-105"
+                        )}
+                      />
+                    )}
+                  </For>
+                </div>
+              </DropdownMenuGroup>
+
+              <DropdownMenuSeparator class="my-2" />
+
+              <DropdownMenuGroup>
+                <DropdownMenuLabel class="px-0 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                  Border Radius
+                </DropdownMenuLabel>
+                <div class="grid grid-cols-5 gap-1 my-1.5">
+                  <For each={RADIUS_OPTIONS}>
+                    {(r) => (
+                      <Button
+                        variant={radius() === r.value ? "default" : "outline"}
+                        size="sm"
+                        onClick={() => setRadius(r.value)}
+                        class="h-7 text-xs px-1 cursor-pointer"
+                      >
+                        {r.label}
+                      </Button>
+                    )}
+                  </For>
+                </div>
+              </DropdownMenuGroup>
+            </div>
+          </DropdownMenuContent>
+        </Show>
+      </DropdownMenu>
+    </Show>
+  );
+};

package/dist/vendor/docs-src/components/ui/tooltip.tsx

@@ -0,0 +1,41 @@
+import { splitProps, type Component, type ComponentProps } from "solid-js";
+import { Tooltip as KobalteTooltip } from "@kobalte/core/tooltip";
+import { cn } from "@/lib/cn";
+
+export const Tooltip = KobalteTooltip;
+
+export const TooltipTrigger = KobalteTooltip.Trigger;
+
+export const TooltipArrow: Component<ComponentProps<typeof KobalteTooltip.Arrow>> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+
+  return (
+    <KobalteTooltip.Arrow
+      size={8}
+      class={cn("fill-popover stroke-border", local.class)}
+      {...rest}
+    />
+  );
+};
+
+export interface TooltipContentProps extends ComponentProps<typeof KobalteTooltip.Content> {
+  class?: string;
+}
+
+export const TooltipContent: Component<TooltipContentProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class", "children"]);
+
+  return (
+    <KobalteTooltip.Portal>
+      <KobalteTooltip.Content
+        class={cn(
+          "z-50 rounded-md border border-border bg-popover px-3 py-1.5 text-xs text-popover-foreground shadow-md transition-all animate-in fade-in-0 zoom-in-95 data-closed:animate-out data-[closed]:fade-out-0 data-closed:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+          local.class
+        )}
+        {...rest}
+      >
+        {local.children}
+      </KobalteTooltip.Content>
+    </KobalteTooltip.Portal>
+  );
+};

package/dist/vendor/docs-src/hooks/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/docs-src/hooks/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/docs-src/hooks/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/docs-src/hooks/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/docs-src/hooks/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?.();
+      }
+    });
+  });
+}