@nikala-ui/hooks 0.11.0 → 0.12.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Giorgi Magradze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO QUALITY AND FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,116 +1,161 @@
 # @nikala-ui/hooks
 
-Reactive SolidJS state primitives and custom hooks for **Nikala UI**.
-
-Honoring the iconic Georgian painter **Niko Pirosmani (Nikala)**.
-
-Official Documentation & Interactive Demos: [nikala.dev](https://nikala.dev)
-
----
-
-## Overview
-
-This package provides reusable, fine-grained reactive primitives designed natively for SolidJS applications. It simplifies managing complex component state such as controlled and uncontrolled inputs, state synchronization, browser APIs, and reactive event callbacks.
-
----
-
-## Core Features & Available Hooks
-
-- **`createControllableSignal`** — SolidJS reactive primitive for managing state supporting both controlled and uncontrolled modes with a unified setter API.
-- **`createClickOutside`** — SolidJS reactive primitive for detecting user interactions outside specified element(s) or refs.
-- **`createClipboard`** — SolidJS reactive primitive for copying text to clipboard with automatic status reset.
-- **`createKeybindings` / `createEscapeKey`** — SolidJS reactive primitives for listening to keyboard shortcuts, key combinations, and Escape key presses.
-- **`createLockScroll`** — SolidJS reactive primitive for locking body or container scrolling when overlays are active.
-- **`createDisclosure`** — SolidJS reactive primitive for managing boolean open/close state with toggle, open, and close helpers.
-- **`createMediaQuery` / `createBreakpoint`** — SolidJS reactive primitives for tracking CSS media queries and responsive Tailwind breakpoints.
-- **`createDebounce` / `createThrottle`** — SolidJS reactive primitives for debouncing and throttling rate-limited function execution.
-- **`createIntersectionObserver` / `createInView`** — SolidJS reactive primitives for detecting element viewport visibility and scroll animation triggers.
-- **`createTimer` / `createCountdown`** — SolidJS reactive primitives for recurring interval ticks and formatted countdown timers.
-- **`createResizeObserver` / `createElementSize`** — SolidJS reactive primitives for tracking element width and height dimensions dynamically.
-- **`createWindowSize`** — SolidJS reactive primitive for tracking window viewport inner width and height.
-- **`createScrollPosition`** — SolidJS reactive primitive for tracking scroll position, scroll direction, and top/bottom container status.
-- **`createFocusTrap`** — SolidJS reactive primitive for trapping keyboard focus inside target container element for accessibility (WCAG).
-- **`createMousePosition`** — SolidJS reactive primitive for tracking global and element-relative mouse pointer coordinates.
-- **`createLongPress`** — SolidJS reactive primitive for detecting long press / hold touch and pointer interactions.
-- **`createHover`** — SolidJS reactive primitive for tracking element hover state with entrance/exit delays.
-- **`createLocalStorage` / `createSessionStorage`** — SolidJS reactive primitives for Web Storage state synchronization across tabs.
-- **`createPrevious`** — SolidJS reactive primitive for tracking previous value of a signal accessor.
-- **`createNetworkStatus` / `createOnline`** — SolidJS reactive primitives for tracking browser network connectivity and connection quality metrics.
-- **`createColorMode`** — SolidJS reactive primitive for managing dark/light themes and system preferences.
-- **`createForm`** — SolidJS reactive primitive for form state management, field validation, errors, and submission.
-- **`createInputMask`** — SolidJS reactive primitive for input value masking (phone numbers, credit cards, dates).
-- **`createIdle`** — SolidJS reactive primitive for detecting user inactivity with customizable timeout and activity events.
-- **`createActiveElement`** — SolidJS reactive primitive for tracking the currently focused DOM element.
-- **`createInfiniteScroll`** — SolidJS reactive primitive for infinite scrolling data fetching and threshold triggers.
-- **`createFullscreen`** — SolidJS reactive primitive for toggling and observing Fullscreen API state.
-- **`createAudio` / `createVideo`** — SolidJS reactive primitives for media playback, volume, duration, and control tracking.
-- **`createOrientation`** — SolidJS reactive primitive for observing device screen orientation and angle.
-- **`createUndoRedo`** — SolidJS reactive primitive for managing state history, undo/redo stacks, and reset capabilities.
-- **`createFetch`** — SolidJS reactive primitive for reactive HTTP data fetching, loading states, and error handling.
-- **`createGeolocation`** — SolidJS reactive primitive for tracking device GPS coordinates and location errors.
-- **`createPermission`** — SolidJS reactive primitive for querying and observing browser permission status changes.
-- **`createBattery`** — SolidJS reactive primitive for observing device battery charge level and charging status.
-- **`createWebNotification`** — SolidJS reactive primitive for sending browser desktop notifications and managing permissions.
-- **`createWebSocket`** — SolidJS reactive primitive for WebSocket client connections, auto-reconnections, and message passing.
-- **`createDocumentTitle`** — SolidJS reactive primitive for managing document title dynamically with unmount restoration.
-- **`createFavicon`** — SolidJS reactive primitive for dynamically updating browser favicon link element.
-- **`createEventSource`** — SolidJS reactive primitive for subscribing to Server-Sent Events (SSE) streams.
-- **Native SolidJS Reactivity** — Zero-dependency, fine-grained reactivity built directly on SolidJS signals.
-- **TypeScript First** — Fully typed options, getters, and return tuple interfaces.
-
----
-
-## Installation & Usage
-
-Install the hooks package via your preferred package manager:
+Reactive SolidJS primitives for browser state, events, media APIs, storage, forms, and application behavior.
+
+Nikala UI follows a pure copy-paste ownership model. This package is the source distribution used by the registry and documentation tooling. Application developers add hooks with `@nikala-ui/cli`, which copies the source into their own project.
+
+Documentation and interactive examples: [nikala.dev](https://nikala.dev)
+
+## Add a hook to an application
+
+Initialize Nikala UI if the project has not been configured yet, then add the required hook:
 
 ```bash
-bun add @nikala-ui/hooks
-# or
-npm install @nikala-ui/hooks
+bunx @nikala-ui/cli init
+bunx @nikala-ui/cli add --hook create-clipboard
+```
+
+The CLI copies the selected source into `src/hooks/` and rewrites its local imports. The application owns the copied file and does not add `@nikala-ui/hooks` as a runtime dependency.
+
+## Usage
+
+Import the copied source from the project's local hooks directory:
+
+```tsx
+import { createControllableSignal } from "@/hooks/create-controllable-signal";
+
+const [value, setValue] = createControllableSignal({
+  defaultValue: "initial value",
+});
 ```
 
-Import hooks directly into your SolidJS components:
+The copied primitive uses SolidJS accessors and setters so updates remain fine-grained and reactive.
+
+## Available primitives
+
+The package currently exports the following source modules:
+
+### State and interaction
+
+- `createControllableSignal`
+- `createDisclosure`
+- `createPrevious`
+- `createUndoRedo`
+- `createPagination`
+- `createForm`
+- `createInputMask`
+- `createDebounce`
+- `createHover`
+- `createLongPress`
+- `createKeybindings`
+- `createGlobalShortcut`
+- `createClickOutside`
+- `createFocusTrap`
+- `createLockScroll`
+
+### Browser and viewport APIs
+
+- `createActiveElement`
+- `createWindowSize`
+- `createMousePosition`
+- `createMediaQuery`
+- `createResizeObserver`
+- `createIntersectionObserver`
+- `createScrollPosition`
+- `createScrollIntoView`
+- `createInfiniteScroll`
+- `createOrientation`
+- `createFullscreen`
+- `createNetworkStatus`
+- `createPermission`
+- `createGeolocation`
+- `createBattery`
+
+### Storage, media, and communication
+
+- `createStorage`, including local and session storage helpers
+- `createClipboard`
+- `createColorMode`
+- `createDocumentTitle`
+- `createFavicon`
+- `createWebNotification`
+- `createWebSocket`
+- `createEventSource`
+- `createAudioVideo`, which provides audio and video helpers
+- `createTauriWindow`
+- `createAppUpdater`
+- `createChatScroll`
+- `createDocumentTabs`
+- `createTimer`
+- `createIdle`
+- `createFetch`
+- `createDropZone`
+
+### Editor integration
+
+- `createTiptapEditor`
+
+The public exports are defined in [`src/index.ts`](./src/index.ts). The source filenames use kebab-case and can also be copied individually by the CLI.
+
+## Examples
+
+### Controllable and uncontrolled state
 
 ```tsx
-import { createControllableSignal } from "@nikala-ui/hooks";
+import { createControllableSignal } from "@/hooks/create-controllable-signal";
 
 const [value, setValue] = createControllableSignal({
-  defaultValue: "Uncontrolled Initial State",
+  defaultValue: 0,
+  onChange: (nextValue) => console.log(nextValue),
 });
+
+setValue((previousValue) => (previousValue ?? 0) + 1);
 ```
 
-### Form validation and submission
+### Clipboard state
 
-`createForm` supports change-, blur-, and submit-time validation, typed checkbox/select event values, stale async validation protection, and submit error state:
+```tsx
+import { createClipboard } from "@/hooks/create-clipboard";
+
+const clipboard = createClipboard();
+
+await clipboard.copy("Copied text");
+```
+
+### Form state
 
 ```tsx
+import { createForm } from "@/hooks/create-form";
+
 const form = createForm({
-  initialValues: { email: "", marketing: false },
+  initialValues: { email: "" },
   validateOn: "blur",
-  validate: (values) => ({
-    ...(!values.email.includes("@") && { email: "Enter a valid email." }),
-  }),
+  validate: (values) =>
+    values.email.includes("@") ? {} : { email: "Enter a valid email." },
   onSubmit: async (values) => saveProfile(values),
 });
-
-<Form onSubmit={form.handleSubmit} loading={form.isSubmitting()}>
-  <Input
-    value={form.values().email}
-    onInput={form.handleChange("email")}
-    onBlur={form.handleBlur("email")}
-  />
-  <FormMessage form={form} name="email" />
-  {form.submitError() && <p>Could not save changes.</p>}
-</Form>
 ```
 
----
+`createForm` exposes accessors for values, errors, touched state, submission state, and validity, together with field update and event-handler helpers.
 
-## Documentation & Links
+## SSR and browser APIs
 
-- Repository: [github.com/nikala-ui/ui](https://github.com/nikala-ui/ui)
-- Hooks Documentation: [nikala.dev/docs/hooks](https://nikala.dev/docs/hooks)
+Primitives that access `window`, `document`, browser events, or browser-only APIs are designed for SolidJS applications and guard browser operations for server-rendered environments. Browser-dependent behavior should still be used from the appropriate client lifecycle in an SSR application.
+
+## Related packages
+
+- `@nikala-ui/cli` copies selected hook sources into an application.
+- `@nikala-ui/core` contains the internal registry manifests and source metadata.
+- `@nikala-ui/docs` bundles source snapshots so generated documentation projects can own their local hooks.
+
+## Package development
+
+Typecheck the package from the monorepo root or from this directory:
+
+```bash
+cd packages/hooks
+bunx tsc --noEmit
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nikala-ui/hooks",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Reactive SolidJS primitives and primitives for Nikala UI",
   "type": "module",
   "main": "./src/index.ts",
@@ -23,5 +23,26 @@
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"
+  },
+  "dependencies": {
+    "@tiptap/core": "^3.31.0",
+    "@tiptap/extension-character-count": "^3.31.0",
+    "@tiptap/extension-highlight": "^3.31.0",
+    "@tiptap/extension-image": "^3.31.0",
+    "@tiptap/extension-link": "^3.31.0",
+    "@tiptap/extension-placeholder": "^3.31.0",
+    "@tiptap/extension-subscript": "^3.31.0",
+    "@tiptap/extension-superscript": "^3.31.0",
+    "@tiptap/extension-table": "^3.31.0",
+    "@tiptap/extension-table-cell": "^3.31.0",
+    "@tiptap/extension-table-header": "^3.31.0",
+    "@tiptap/extension-table-row": "^3.31.0",
+    "@tiptap/extension-task-item": "^3.31.0",
+    "@tiptap/extension-task-list": "^3.31.0",
+    "@tiptap/extension-text-align": "^3.31.0",
+    "@tiptap/extension-typography": "^3.31.0",
+    "@tiptap/extension-underline": "^3.31.0",
+    "@tiptap/starter-kit": "^3.31.0",
+    "tiptap-markdown": "^0.9.0"
   }
 }

package/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,
+  };
+}