@nikala-ui/docs 0.12.0

package/dist/vendor/hooks-src/create-app-updater.ts

@@ -0,0 +1,272 @@
+import { createSignal, onMount, type Accessor } from "solid-js";
+import { isTauriEnvironment } from "./create-tauri-window";
+
+export type UpdaterStatus =
+  | "idle"
+  | "checking"
+  | "available"
+  | "up-to-date"
+  | "downloading"
+  | "downloaded"
+  | "error";
+
+export interface UpdateManifestInfo {
+  version: string;
+  currentVersion?: string;
+  date?: string;
+  body?: string;
+}
+
+export interface UpdateProgressInfo {
+  downloaded: number;
+  total: number;
+  percentage: number;
+}
+
+export interface CreateAppUpdaterOptions {
+  /** Automatically check for updates on mount. Defaults to false. */
+  autoCheck?: boolean;
+  /** Current application version fallback if not detected. */
+  currentVersion?: string;
+  /** Callback fired when an update is available. */
+  onUpdateAvailable?: (info: UpdateManifestInfo) => void;
+  /** Callback fired when download finishes. */
+  onDownloadFinished?: () => void;
+  /** Callback fired on update check or download error. */
+  onError?: (error: Error | string) => void;
+}
+
+export interface CreateAppUpdaterReturn {
+  /** Current lifecycle status of the updater. */
+  status: Accessor<UpdaterStatus>;
+  /** Update metadata (new version, release notes, release date). */
+  updateInfo: Accessor<UpdateManifestInfo | null>;
+  /** Download progress (bytes downloaded, total bytes, percentage). */
+  progress: Accessor<UpdateProgressInfo>;
+  /** Error message if an operation failed. */
+  error: Accessor<string | null>;
+  /** Whether an update is currently being checked or downloaded. */
+  isLoading: Accessor<boolean>;
+  /** Check update endpoint for a new release. */
+  checkForUpdates: () => Promise<boolean>;
+  /** Download and install the available update. */
+  downloadAndInstall: () => Promise<void>;
+  /** Restart application to apply the downloaded update. */
+  relaunch: () => Promise<void>;
+  /** Dismiss current update prompt or clear error state. */
+  dismiss: () => void;
+  /** Simulate an update cycle in web / playground preview environments. */
+  simulateUpdate: (mockInfo?: Partial<UpdateManifestInfo>) => void;
+}
+
+/**
+ * SolidJS reactive primitive for controlling and observing Tauri v2 application updates.
+ * Integrates with @tauri-apps/plugin-updater with full web simulation support.
+ */
+export function createAppUpdater(
+  options: CreateAppUpdaterOptions = {}
+): CreateAppUpdaterReturn {
+  const [status, setStatus] = createSignal<UpdaterStatus>("idle");
+  const [updateInfo, setUpdateInfo] = createSignal<UpdateManifestInfo | null>(null);
+  const [progress, setProgress] = createSignal<UpdateProgressInfo>({
+    downloaded: 0,
+    total: 0,
+    percentage: 0,
+  });
+  const [error, setError] = createSignal<string | null>(null);
+
+  let activeTauriUpdate: any = null;
+  let simulatedTimer: any = null;
+
+  const getTauriUpdaterPlugin = async () => {
+    if (typeof window === "undefined") return null;
+    try {
+      if ((window as any).__TAURI__?.updater) {
+        return (window as any).__TAURI__.updater;
+      }
+      const moduleName = "@tauri-apps/plugin-updater";
+      // @ts-ignore - Optional runtime dependency in Tauri apps
+      const plugin = await import(/* @vite-ignore */ moduleName).catch(() => null);
+      return plugin;
+    } catch {
+      return null;
+    }
+  };
+
+  const getTauriProcessPlugin = async () => {
+    if (typeof window === "undefined") return null;
+    try {
+      if ((window as any).__TAURI__?.process) {
+        return (window as any).__TAURI__.process;
+      }
+      const moduleName = "@tauri-apps/plugin-process";
+      // @ts-ignore - Optional runtime dependency in Tauri apps
+      const plugin = await import(/* @vite-ignore */ moduleName).catch(() => null);
+      return plugin;
+    } catch {
+      return null;
+    }
+  };
+
+  const checkForUpdates = async (): Promise<boolean> => {
+    setStatus("checking");
+    setError(null);
+
+    if (isTauriEnvironment()) {
+      try {
+        const updaterPlugin = await getTauriUpdaterPlugin();
+        if (updaterPlugin?.check) {
+          const update = await updaterPlugin.check();
+          if (update?.available) {
+            activeTauriUpdate = update;
+            const info: UpdateManifestInfo = {
+              version: update.version,
+              currentVersion: update.currentVersion || options.currentVersion || "v1.0.0",
+              date: update.date,
+              body: update.body || "Bug fixes and performance enhancements.",
+            };
+            setUpdateInfo(info);
+            setStatus("available");
+            options.onUpdateAvailable?.(info);
+            return true;
+          } else {
+            setStatus("up-to-date");
+            return false;
+          }
+        }
+      } catch (err: any) {
+        const errMsg = err?.message || String(err);
+        setError(errMsg);
+        setStatus("error");
+        options.onError?.(errMsg);
+        return false;
+      }
+    }
+
+    // In web preview / non-tauri mode, simulate checking
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    setStatus("up-to-date");
+    return false;
+  };
+
+  const downloadAndInstall = async (): Promise<void> => {
+    if (status() !== "available" && status() !== "error") return;
+    setStatus("downloading");
+    setError(null);
+    setProgress({ downloaded: 0, total: 100, percentage: 0 });
+
+    if (isTauriEnvironment() && activeTauriUpdate?.downloadAndInstall) {
+      try {
+        let downloadedBytes = 0;
+        let contentLength = 0;
+
+        await activeTauriUpdate.downloadAndInstall((event: any) => {
+          if (event.event === "Started") {
+            contentLength = event.data?.contentLength || 100;
+          } else if (event.event === "Progress") {
+            downloadedBytes += event.data?.chunkLength || 0;
+            const pct = contentLength > 0 ? Math.min(100, Math.round((downloadedBytes / contentLength) * 100)) : 50;
+            setProgress({
+              downloaded: downloadedBytes,
+              total: contentLength,
+              percentage: pct,
+            });
+          } else if (event.event === "Finished") {
+            setProgress({
+              downloaded: contentLength,
+              total: contentLength,
+              percentage: 100,
+            });
+          }
+        });
+
+        setStatus("downloaded");
+        options.onDownloadFinished?.();
+        return;
+      } catch (err: any) {
+        const errMsg = err?.message || String(err);
+        setError(errMsg);
+        setStatus("error");
+        options.onError?.(errMsg);
+        return;
+      }
+    }
+
+    // Web simulation mode with smooth progress step
+    let currentPct = 0;
+    simulatedTimer = setInterval(() => {
+      currentPct += 15;
+      if (currentPct >= 100) {
+        clearInterval(simulatedTimer);
+        setProgress({ downloaded: 45.8 * 1024 * 1024, total: 45.8 * 1024 * 1024, percentage: 100 });
+        setStatus("downloaded");
+        options.onDownloadFinished?.();
+      } else {
+        const downloaded = (45.8 * 1024 * 1024 * currentPct) / 100;
+        setProgress({ downloaded, total: 45.8 * 1024 * 1024, percentage: currentPct });
+      }
+    }, 250);
+  };
+
+  const relaunch = async (): Promise<void> => {
+    if (isTauriEnvironment()) {
+      try {
+        const processPlugin = await getTauriProcessPlugin();
+        if (processPlugin?.relaunch) {
+          await processPlugin.relaunch();
+          return;
+        }
+      } catch {
+        // Fallback
+      }
+    }
+
+    if (typeof window !== "undefined") {
+      window.location.reload();
+    }
+  };
+
+  const dismiss = (): void => {
+    if (simulatedTimer) clearInterval(simulatedTimer);
+    setStatus("idle");
+    setError(null);
+  };
+
+  const simulateUpdate = (mockInfo?: Partial<UpdateManifestInfo>): void => {
+    if (simulatedTimer) clearInterval(simulatedTimer);
+    const info: UpdateManifestInfo = {
+      version: mockInfo?.version || "v1.2.0",
+      currentVersion: mockInfo?.currentVersion || options.currentVersion || "v1.0.0",
+      date: mockInfo?.date || new Date().toISOString().split("T")[0],
+      body:
+        mockInfo?.body ||
+        "### What's New in v1.2.0\n- Added native Window Titlebar tabs\n- Enhanced Tauri v2 capability security\n- Optimized SolidJS signal reactivity\n- Fixed titlebar drag region jitter on Linux",
+    };
+    setUpdateInfo(info);
+    setStatus("available");
+    setError(null);
+    setProgress({ downloaded: 0, total: 100, percentage: 0 });
+    options.onUpdateAvailable?.(info);
+  };
+
+  onMount(() => {
+    if (options.autoCheck) {
+      checkForUpdates();
+    }
+  });
+
+  const isLoading = () => status() === "checking" || status() === "downloading";
+
+  return {
+    status,
+    updateInfo,
+    progress,
+    error,
+    isLoading,
+    checkForUpdates,
+    downloadAndInstall,
+    relaunch,
+    dismiss,
+    simulateUpdate,
+  };
+}

package/dist/vendor/hooks-src/create-audio-video.ts

@@ -0,0 +1,444 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+import { createControllableSignal } from "./create-controllable-signal";
+
+export interface CreateAudioOptions {
+  /** Controlled playing state. */
+  playing?: boolean | Accessor<boolean | undefined>;
+  /** Uncontrolled default playing state. Defaults to false. */
+  defaultPlaying?: boolean;
+  /** Controlled muted state. */
+  muted?: boolean | Accessor<boolean | undefined>;
+  /** Uncontrolled default muted state. Defaults to false. */
+  defaultMuted?: boolean;
+  /** Initial volume level between 0.0 and 1.0. Defaults to 1.0. */
+  volume?: number;
+  /** Whether the audio should loop upon finishing. Defaults to false. */
+  loop?: boolean;
+  /** Whether the audio should start playing automatically. Defaults to false. */
+  autoplay?: boolean;
+  /** Playback speed rate. Defaults to 1.0. */
+  playbackRate?: number;
+  /** Callback fired when playing state changes. */
+  onPlayingChange?: (playing: boolean) => void;
+  /** Callback fired when muted state changes. */
+  onMutedChange?: (muted: boolean) => void;
+  /** Callback fired when audio finishes playing. */
+  onEnded?: () => void;
+  /** Callback fired when audio playback encounters an error. */
+  onError?: (err: Event) => void;
+}
+
+export interface CreateAudioReturn {
+  /** Signal indicating if audio is currently playing. */
+  isPlaying: Accessor<boolean>;
+  /** Signal indicating current playback time in seconds. */
+  currentTime: Accessor<number>;
+  /** Signal indicating total duration in seconds. */
+  duration: Accessor<number>;
+  /** Signal indicating volume level (0.0 to 1.0). */
+  volume: Accessor<number>;
+  /** Signal indicating if audio is muted. */
+  isMuted: Accessor<boolean>;
+  /** Signal indicating if audio source is loaded and ready. */
+  isReady: Accessor<boolean>;
+  /** Play audio. */
+  play: () => Promise<void>;
+  /** Pause audio. */
+  pause: () => void;
+  /** Toggle play/pause state. */
+  toggle: () => void;
+  /** Seek to specified time in seconds. */
+  seek: (time: number) => void;
+  /** Set volume level between 0.0 and 1.0. */
+  setVolume: (vol: number) => void;
+  /** Toggle audio mute status. */
+  toggleMute: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for controlling audio playback state with controlled/uncontrolled signal support.
+ */
+export function createAudio(
+  src: string | Accessor<string>,
+  options: CreateAudioOptions = {}
+): CreateAudioReturn {
+  const playingAccessor = (): boolean | undefined => {
+    if (typeof options.playing === "function") {
+      return options.playing();
+    }
+    return options.playing;
+  };
+
+  const mutedAccessor = (): boolean | undefined => {
+    if (typeof options.muted === "function") {
+      return options.muted();
+    }
+    return options.muted;
+  };
+
+  const [isPlayingVal, setIsPlayingVal] = createControllableSignal<boolean>({
+    value: playingAccessor,
+    defaultValue: options.defaultPlaying ?? false,
+    onChange: options.onPlayingChange,
+  });
+
+  const [isMutedVal, setIsMutedVal] = createControllableSignal<boolean>({
+    value: mutedAccessor,
+    defaultValue: options.defaultMuted ?? false,
+    onChange: options.onMutedChange,
+  });
+
+  const [audioEl, setAudioEl] = createSignal<HTMLAudioElement | null>(null);
+  const [currentTime, setCurrentTime] = createSignal(0);
+  const [duration, setDuration] = createSignal(0);
+  const [volume, setVolumeSignal] = createSignal(options.volume ?? 1.0);
+  const [isReady, setIsReady] = createSignal(false);
+
+  const isPlaying = (): boolean => Boolean(isPlayingVal());
+  const isMuted = (): boolean => Boolean(isMutedVal());
+
+  const getSrc = (): string => {
+    return typeof src === "function" ? src() : src;
+  };
+
+  /* Initialize Audio instance */
+  createEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const audio = new Audio(getSrc());
+    setAudioEl(audio);
+
+    const handleLoadedMetadata = (): void => {
+      setDuration(audio.duration || 0);
+      setIsReady(true);
+    };
+
+    const handleTimeUpdate = (): void => {
+      setCurrentTime(audio.currentTime || 0);
+    };
+
+    const handlePlay = (): void => setIsPlayingVal(true);
+    const handlePause = (): void => setIsPlayingVal(false);
+    const handleEnded = (): void => {
+      setIsPlayingVal(false);
+      options.onEnded?.();
+    };
+
+    const handleError = (e: Event): void => {
+      setIsReady(false);
+      options.onError?.(e);
+    };
+
+    audio.addEventListener("loadedmetadata", handleLoadedMetadata);
+    audio.addEventListener("timeupdate", handleTimeUpdate);
+    audio.addEventListener("play", handlePlay);
+    audio.addEventListener("pause", handlePause);
+    audio.addEventListener("ended", handleEnded);
+    audio.addEventListener("error", handleError);
+
+    onCleanup(() => {
+      audio.pause();
+      audio.removeEventListener("loadedmetadata", handleLoadedMetadata);
+      audio.removeEventListener("timeupdate", handleTimeUpdate);
+      audio.removeEventListener("play", handlePlay);
+      audio.removeEventListener("pause", handlePause);
+      audio.removeEventListener("ended", handleEnded);
+      audio.removeEventListener("error", handleError);
+      setAudioEl(null);
+    });
+  });
+
+  /* Sync properties with audio element */
+  createEffect(() => {
+    const audio = audioEl();
+    if (!audio) return;
+
+    audio.volume = volume();
+    audio.muted = isMuted();
+    audio.loop = options.loop ?? false;
+    audio.autoplay = options.autoplay ?? false;
+    if (options.playbackRate) {
+      audio.playbackRate = options.playbackRate;
+    }
+  });
+
+  /* Sync controlled playing state with HTMLAudioElement */
+  createEffect(() => {
+    const audio = audioEl();
+    const shouldPlay = isPlaying();
+    if (!audio) return;
+    if (shouldPlay && audio.paused) {
+      audio.play().catch(() => setIsPlayingVal(false));
+    } else if (!shouldPlay && !audio.paused) {
+      audio.pause();
+    }
+  });
+
+  const play = async (): Promise<void> => {
+    setIsPlayingVal(true);
+    const audio = audioEl();
+    if (audio) await audio.play();
+  };
+
+  const pause = (): void => {
+    setIsPlayingVal(false);
+    const audio = audioEl();
+    if (audio) audio.pause();
+  };
+
+  const toggle = (): void => {
+    if (isPlaying()) {
+      pause();
+    } else {
+      play();
+    }
+  };
+
+  const seek = (time: number): void => {
+    const audio = audioEl();
+    if (audio) {
+      audio.currentTime = Math.max(0, Math.min(time, duration()));
+      setCurrentTime(audio.currentTime);
+    }
+  };
+
+  const setVolume = (vol: number): void => {
+    const clamped = Math.max(0, Math.min(vol, 1.0));
+    setVolumeSignal(clamped);
+    const audio = audioEl();
+    if (audio) {
+      audio.volume = clamped;
+    }
+  };
+
+  const toggleMute = (): void => {
+    const nextMuted = !isMuted();
+    setIsMutedVal(nextMuted);
+    const audio = audioEl();
+    if (audio) {
+      audio.muted = nextMuted;
+    }
+  };
+
+  return {
+    isPlaying,
+    currentTime,
+    duration,
+    volume,
+    isMuted,
+    isReady,
+    play,
+    pause,
+    toggle,
+    seek,
+    setVolume,
+    toggleMute,
+  };
+}
+
+export interface CreateVideoOptions {
+  /** Controlled playing state. */
+  playing?: boolean | Accessor<boolean | undefined>;
+  /** Uncontrolled default playing state. Defaults to false. */
+  defaultPlaying?: boolean;
+  /** Controlled muted state. */
+  muted?: boolean | Accessor<boolean | undefined>;
+  /** Uncontrolled default muted state. Defaults to false. */
+  defaultMuted?: boolean;
+  /** Initial volume level between 0.0 and 1.0. Defaults to 1.0. */
+  volume?: number;
+  /** Whether video should loop upon finishing. Defaults to false. */
+  loop?: boolean;
+  /** Callback fired when playing state changes. */
+  onPlayingChange?: (playing: boolean) => void;
+  /** Callback fired when muted state changes. */
+  onMutedChange?: (muted: boolean) => void;
+  /** Callback fired when video playback finishes. */
+  onEnded?: () => void;
+}
+
+export interface CreateVideoReturn {
+  /** Ref callback function to bind to HTMLVideoElement. */
+  setVideoRef: (el: HTMLVideoElement | null) => void;
+  /** Signal indicating if video is playing. */
+  isPlaying: Accessor<boolean>;
+  /** Signal indicating current playback time in seconds. */
+  currentTime: Accessor<number>;
+  /** Signal indicating total video duration in seconds. */
+  duration: Accessor<number>;
+  /** Signal indicating volume level (0.0 to 1.0). */
+  volume: Accessor<number>;
+  /** Signal indicating if video is muted. */
+  isMuted: Accessor<boolean>;
+  /** Play video. */
+  play: () => Promise<void>;
+  /** Pause video. */
+  pause: () => void;
+  /** Toggle play/pause. */
+  toggle: () => void;
+  /** Seek to time position. */
+  seek: (time: number) => void;
+  /** Set volume level. */
+  setVolume: (vol: number) => void;
+  /** Toggle mute status. */
+  toggleMute: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for controlling media element video playback with controlled/uncontrolled signal support.
+ */
+export function createVideo(
+  options: CreateVideoOptions = {}
+): CreateVideoReturn {
+  const [videoEl, setVideoEl] = createSignal<HTMLVideoElement | null>(null);
+
+  const playingAccessor = (): boolean | undefined => {
+    if (typeof options.playing === "function") {
+      return options.playing();
+    }
+    return options.playing;
+  };
+
+  const mutedAccessor = (): boolean | undefined => {
+    if (typeof options.muted === "function") {
+      return options.muted();
+    }
+    return options.muted;
+  };
+
+  const [isPlayingVal, setIsPlayingVal] = createControllableSignal<boolean>({
+    value: playingAccessor,
+    defaultValue: options.defaultPlaying ?? false,
+    onChange: options.onPlayingChange,
+  });
+
+  const [isMutedVal, setIsMutedVal] = createControllableSignal<boolean>({
+    value: mutedAccessor,
+    defaultValue: options.defaultMuted ?? false,
+    onChange: options.onMutedChange,
+  });
+
+  const [currentTime, setCurrentTime] = createSignal(0);
+  const [duration, setDuration] = createSignal(0);
+  const [volume, setVolumeSignal] = createSignal(options.volume ?? 1.0);
+
+  const isPlaying = (): boolean => Boolean(isPlayingVal());
+  const isMuted = (): boolean => Boolean(isMutedVal());
+
+  createEffect(() => {
+    const el = videoEl();
+    if (!el) return;
+
+    el.volume = volume();
+    el.muted = isMuted();
+    el.loop = options.loop ?? false;
+
+    const handleLoadedMetadata = (): void => {
+      setDuration(el.duration || 0);
+    };
+    const handleTimeUpdate = (): void => {
+      setCurrentTime(el.currentTime || 0);
+    };
+    const handlePlay = (): void => setIsPlayingVal(true);
+    const handlePause = (): void => setIsPlayingVal(false);
+    const handleEnded = (): void => {
+      setIsPlayingVal(false);
+      options.onEnded?.();
+    };
+
+    el.addEventListener("loadedmetadata", handleLoadedMetadata);
+    el.addEventListener("timeupdate", handleTimeUpdate);
+    el.addEventListener("play", handlePlay);
+    el.addEventListener("pause", handlePause);
+    el.addEventListener("ended", handleEnded);
+
+    onCleanup(() => {
+      el.removeEventListener("loadedmetadata", handleLoadedMetadata);
+      el.removeEventListener("timeupdate", handleTimeUpdate);
+      el.removeEventListener("play", handlePlay);
+      el.removeEventListener("pause", handlePause);
+      el.removeEventListener("ended", handleEnded);
+    });
+  });
+
+  /* Sync controlled playing state with video HTML element */
+  createEffect(() => {
+    const el = videoEl();
+    const shouldPlay = isPlaying();
+    if (!el) return;
+    if (shouldPlay && el.paused) {
+      el.play().catch(() => setIsPlayingVal(false));
+    } else if (!shouldPlay && !el.paused) {
+      el.pause();
+    }
+  });
+
+  /* Sync controlled muted state with video HTML element */
+  createEffect(() => {
+    const el = videoEl();
+    if (el) {
+      el.muted = isMuted();
+    }
+  });
+
+  const play = async (): Promise<void> => {
+    setIsPlayingVal(true);
+    const el = videoEl();
+    if (el) await el.play();
+  };
+
+  const pause = (): void => {
+    setIsPlayingVal(false);
+    const el = videoEl();
+    if (el) el.pause();
+  };
+
+  const toggle = (): void => {
+    if (isPlaying()) {
+      pause();
+    } else {
+      play();
+    }
+  };
+
+  const seek = (time: number): void => {
+    const el = videoEl();
+    if (el) {
+      el.currentTime = Math.max(0, Math.min(time, duration()));
+      setCurrentTime(el.currentTime);
+    }
+  };
+
+  const setVolume = (vol: number): void => {
+    const clamped = Math.max(0, Math.min(vol, 1.0));
+    setVolumeSignal(clamped);
+    const el = videoEl();
+    if (el) {
+      el.volume = clamped;
+    }
+  };
+
+  const toggleMute = (): void => {
+    const nextMuted = !isMuted();
+    setIsMutedVal(nextMuted);
+    const el = videoEl();
+    if (el) {
+      el.muted = nextMuted;
+    }
+  };
+
+  return {
+    setVideoRef: setVideoEl,
+    isPlaying,
+    currentTime,
+    duration,
+    volume,
+    isMuted,
+    play,
+    pause,
+    toggle,
+    seek,
+    setVolume,
+    toggleMute,
+  };
+}