@neveranyart/weaver 1.0.15 → 1.0.17

package/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write # Required for OIDC
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Corepack enable
+        run: corepack enable
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+          cache: "yarn"
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Publish package
+        run: npm publish

package/README.md

@@ -1,9 +1,11 @@
-# `@neveranyart/weaver`
+# Weaver
 
 **WIP DOCS**
 
 An in-house core package by neveranyart for making performant, interactive React CSR.
 
+<sub>Almost feels like a framework, but it's not.</sub>
+
 ![neverany branding](https://github.com/user-attachments/assets/8c09234f-d592-4adc-8ab1-284b1fca3f7c)
 
 ## Introduction
@@ -11,6 +13,21 @@ This package is published as an in-depth on `neverany` technicals. It is not int
 
 But, most components and tools are built with flexibility in mind, providing a balance between abstraction and verbose.
 
+> [!INFO]
+> `React v19+` is required.
+
+## Installation
+NPM:
+```
+npm i @neveranyart/weaver
+```
+
+Yarn:
+```
+yarn add @neveranyart/weaver
+```
+
+
 ## Documentations
 1. [Routing](https://github.com/neveranyart/weaver/blob/main/docs/ROUTING.md)
 2. Hooks

package/dist/hooks.d.mts

@@ -1,9 +1,42 @@
 import { RefObject } from 'react';
 import { OrthographicCamera, PerspectiveCamera } from 'three';
 
-declare function useBreakpoints(breakpoints?: number[] | null): number;
+/**
+ * A screen size hook to change components when media-query isn't viable. For example, swap out
+ * components when screen gets too small, changing layout of a 3D scene to match the size.
+ *
+ * The value passed in must be sorted in ascending order.
+ *
+ * The hooks return where the screen size belong inbetween, for example:
+ *
+ * ```
+ * Input:   " 640 768 1024 1280 1536 "
+ *           |   |   |    |    |    |
+ * Returns:  0   1   2    3    4    5
+ * ```
+ *
+ * @param breakpoints Default value is TailwindCSS's screen sizes:
+ * `[640, 768, 1024, 1280, 1536]`
+ *
+ * @returns A number from `0` to `breakpoints.length + 1` depends on screen sizes.
+ */
+declare function useBreakpoints(breakpoints?: number[]): number;
 
+/**
+ * Effect to run once on mount/unmount, ignore all cautions.
+ *
+ * Strict mode still make this effect runs twice, but never by a state change.
+ *
+ * Used for initialization, clean up.
+ */
 declare function useEffectOnce(callback: React.EffectCallback): void;
+/**
+ * Effect to run once on mount/unmount, ignore all cautions.
+ *
+ * Strict mode still make this effect runs twice, but never by a state change.
+ *
+ * Used for initialization, clean up.
+ */
 declare function useLayoutEffectOnce(callback: React.EffectCallback): void;
 
 interface HookOptions$1 {
@@ -16,32 +49,61 @@ interface HookOptions$1 {
      */
     intersectOn?: RefObject<HTMLOrSVGElement | null>;
 }
-declare const scrollCallbackReason: {
-    readonly Resize: "resize";
-    readonly Scroll: "scroll";
-    readonly Initialize: "initialize";
-};
-type ScrollCallbackReason = (typeof scrollCallbackReason)[keyof typeof scrollCallbackReason];
-type Callback$2 = (latest: number, reason: ScrollCallbackReason) => void;
-declare function useLenisCallback(callback: Callback$2, options?: HookOptions$1): void;
+type ScrollCallbackReason$1 = 'resize' | 'scroll' | 'initialize';
+/**
+ * A lenis scroll hook.
+ *
+ * This hook calls many time and repeated. Update states inside this hook carefully to avoid performance issues.
+ */
+declare function useLenisCallback(callback: (latest: number, reason: ScrollCallbackReason$1) => void, options?: HookOptions$1): void;
 
-interface MousePositionValues {
-    x: number;
-    y: number;
-}
 interface HookOptions {
-    normalized?: boolean;
+    /**
+     * Hook will report when first initialized without waiting for scroll event to actually happens.
+     */
+    initialCall?: boolean;
+    /**
+     * Set an element to only call when the element is actually entering the viewport (with 25% `rootMargin`).
+     */
+    intersectOn?: RefObject<HTMLOrSVGElement | null>;
 }
-type Callback$1 = (latest: MousePositionValues) => void;
-declare function useMouseCallback(callback: Callback$1, options?: HookOptions): void;
+type ScrollCallbackReason = 'resize' | 'scroll' | 'initialize';
+/**
+ * A DOM scroll hook.
+ *
+ * This hook calls many time and repeated. Update states inside this hook carefully to avoid performance issues.
+ *
+ * For manipulating elements matches closely with the actual scroll offet, consider use `lenis` and utilize `useLenisCallback`.
+ */
+declare function useMouseCallback(callback: (latest: number, reason: ScrollCallbackReason) => void, options?: HookOptions): void;
 
-declare function useNavigateAnchor(onNavigate?: () => void): (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => void;
+/**
+ * A hook to replace `<Link>` from `react-router`, attach the function to
+ * `onClick` event of an anchor tag to overwrites its behavior.
+ *
+ * Example usage:
+ * ```tsx
+ * const navigator = useNavigateAnchor();
+ *
+ * return (
+ *   <a href="/" onClick={navigator}>
+ *     Navigate
+ *   </a>
+ * );
+ * ```
+ *
+ * @param onNavigate Calls when a navigation event happens.
+ * @param onSameRoute Calls when user is on the same route, no navigation happens.
+ * @returns
+ */
+declare function useNavigateAnchor(onNavigate?: () => void, onSameRoute?: () => void): (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => void;
 
 /**
- * A simple Orbit hook.
+ * A simple Orbit hook for ResizeObserver and IntersectionObserver.
  *
  * @param target HTML element ref to attach to.
  * @param events Specify which events should the orbit tracks.
+ * @param rootMargin Adjust `rootMargin` option for `IntersectionObserver`.
  */
 declare function useOrbit(options: {
     target?: RefObject<HTMLElement | null>;
@@ -52,15 +114,16 @@ declare function useOrbit(options: {
     rootMargin?: string;
 }): void;
 
-declare function useRawParams(prefix: string, limit?: number): (string | undefined)[];
-
-declare function useRouteNormalizer(options: {
-    autoReplace: boolean;
-}): {
-    pathname: string;
-    normalizer: (input: string) => string;
-};
+/**
+ * Routing hook. This hook updates and splits pathname on location change.
+ *
+ * Great for creating custom routes on the fly under the same parent `Pipeline`.
+ */
+declare function useRawParams(): (string | undefined)[];
 
+/**
+ * A state-based screen hook. It will change its state on resize.
+ */
 declare function useScreen(): {
     width: number;
     height: number;
@@ -71,13 +134,19 @@ interface ScreenCallbackValues {
     height: number;
 }
 type Callback = (props: ScreenCallbackValues) => void;
+/**
+ * A callback-based screen hook. Recommended.
+ */
 declare function useScreenCallback(callback: Callback, options?: {
     initialCall?: boolean;
 }): void;
 
+/**
+ * Get current threejs viewport with the actual current.
+ */
 declare function useViewport(customCamera?: OrthographicCamera | PerspectiveCamera): {
     width: number;
     height: number;
 };
 
-export { useBreakpoints, useEffectOnce, useLayoutEffectOnce, useLenisCallback, useMouseCallback, useNavigateAnchor, useOrbit, useRawParams, useRouteNormalizer, useScreen, useScreenCallback, useViewport };
+export { useBreakpoints, useEffectOnce, useLayoutEffectOnce, useLenisCallback, useMouseCallback, useNavigateAnchor, useOrbit, useRawParams, useScreen, useScreenCallback, useViewport };

package/dist/hooks.d.ts

@@ -1,9 +1,42 @@
 import { RefObject } from 'react';
 import { OrthographicCamera, PerspectiveCamera } from 'three';
 
-declare function useBreakpoints(breakpoints?: number[] | null): number;
+/**
+ * A screen size hook to change components when media-query isn't viable. For example, swap out
+ * components when screen gets too small, changing layout of a 3D scene to match the size.
+ *
+ * The value passed in must be sorted in ascending order.
+ *
+ * The hooks return where the screen size belong inbetween, for example:
+ *
+ * ```
+ * Input:   " 640 768 1024 1280 1536 "
+ *           |   |   |    |    |    |
+ * Returns:  0   1   2    3    4    5
+ * ```
+ *
+ * @param breakpoints Default value is TailwindCSS's screen sizes:
+ * `[640, 768, 1024, 1280, 1536]`
+ *
+ * @returns A number from `0` to `breakpoints.length + 1` depends on screen sizes.
+ */
+declare function useBreakpoints(breakpoints?: number[]): number;
 
+/**
+ * Effect to run once on mount/unmount, ignore all cautions.
+ *
+ * Strict mode still make this effect runs twice, but never by a state change.
+ *
+ * Used for initialization, clean up.
+ */
 declare function useEffectOnce(callback: React.EffectCallback): void;
+/**
+ * Effect to run once on mount/unmount, ignore all cautions.
+ *
+ * Strict mode still make this effect runs twice, but never by a state change.
+ *
+ * Used for initialization, clean up.
+ */
 declare function useLayoutEffectOnce(callback: React.EffectCallback): void;
 
 interface HookOptions$1 {
@@ -16,32 +49,61 @@ interface HookOptions$1 {
      */
     intersectOn?: RefObject<HTMLOrSVGElement | null>;
 }
-declare const scrollCallbackReason: {
-    readonly Resize: "resize";
-    readonly Scroll: "scroll";
-    readonly Initialize: "initialize";
-};
-type ScrollCallbackReason = (typeof scrollCallbackReason)[keyof typeof scrollCallbackReason];
-type Callback$2 = (latest: number, reason: ScrollCallbackReason) => void;
-declare function useLenisCallback(callback: Callback$2, options?: HookOptions$1): void;
+type ScrollCallbackReason$1 = 'resize' | 'scroll' | 'initialize';
+/**
+ * A lenis scroll hook.
+ *
+ * This hook calls many time and repeated. Update states inside this hook carefully to avoid performance issues.
+ */
+declare function useLenisCallback(callback: (latest: number, reason: ScrollCallbackReason$1) => void, options?: HookOptions$1): void;
 
-interface MousePositionValues {
-    x: number;
-    y: number;
-}
 interface HookOptions {
-    normalized?: boolean;
+    /**
+     * Hook will report when first initialized without waiting for scroll event to actually happens.
+     */
+    initialCall?: boolean;
+    /**
+     * Set an element to only call when the element is actually entering the viewport (with 25% `rootMargin`).
+     */
+    intersectOn?: RefObject<HTMLOrSVGElement | null>;
 }
-type Callback$1 = (latest: MousePositionValues) => void;
-declare function useMouseCallback(callback: Callback$1, options?: HookOptions): void;
+type ScrollCallbackReason = 'resize' | 'scroll' | 'initialize';
+/**
+ * A DOM scroll hook.
+ *
+ * This hook calls many time and repeated. Update states inside this hook carefully to avoid performance issues.
+ *
+ * For manipulating elements matches closely with the actual scroll offet, consider use `lenis` and utilize `useLenisCallback`.
+ */
+declare function useMouseCallback(callback: (latest: number, reason: ScrollCallbackReason) => void, options?: HookOptions): void;
 
-declare function useNavigateAnchor(onNavigate?: () => void): (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => void;
+/**
+ * A hook to replace `<Link>` from `react-router`, attach the function to
+ * `onClick` event of an anchor tag to overwrites its behavior.
+ *
+ * Example usage:
+ * ```tsx
+ * const navigator = useNavigateAnchor();
+ *
+ * return (
+ *   <a href="/" onClick={navigator}>
+ *     Navigate
+ *   </a>
+ * );
+ * ```
+ *
+ * @param onNavigate Calls when a navigation event happens.
+ * @param onSameRoute Calls when user is on the same route, no navigation happens.
+ * @returns
+ */
+declare function useNavigateAnchor(onNavigate?: () => void, onSameRoute?: () => void): (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => void;
 
 /**
- * A simple Orbit hook.
+ * A simple Orbit hook for ResizeObserver and IntersectionObserver.
  *
  * @param target HTML element ref to attach to.
  * @param events Specify which events should the orbit tracks.
+ * @param rootMargin Adjust `rootMargin` option for `IntersectionObserver`.
  */
 declare function useOrbit(options: {
     target?: RefObject<HTMLElement | null>;
@@ -52,15 +114,16 @@ declare function useOrbit(options: {
     rootMargin?: string;
 }): void;
 
-declare function useRawParams(prefix: string, limit?: number): (string | undefined)[];
-
-declare function useRouteNormalizer(options: {
-    autoReplace: boolean;
-}): {
-    pathname: string;
-    normalizer: (input: string) => string;
-};
+/**
+ * Routing hook. This hook updates and splits pathname on location change.
+ *
+ * Great for creating custom routes on the fly under the same parent `Pipeline`.
+ */
+declare function useRawParams(): (string | undefined)[];
 
+/**
+ * A state-based screen hook. It will change its state on resize.
+ */
 declare function useScreen(): {
     width: number;
     height: number;
@@ -71,13 +134,19 @@ interface ScreenCallbackValues {
     height: number;
 }
 type Callback = (props: ScreenCallbackValues) => void;
+/**
+ * A callback-based screen hook. Recommended.
+ */
 declare function useScreenCallback(callback: Callback, options?: {
     initialCall?: boolean;
 }): void;
 
+/**
+ * Get current threejs viewport with the actual current.
+ */
 declare function useViewport(customCamera?: OrthographicCamera | PerspectiveCamera): {
     width: number;
     height: number;
 };
 
-export { useBreakpoints, useEffectOnce, useLayoutEffectOnce, useLenisCallback, useMouseCallback, useNavigateAnchor, useOrbit, useRawParams, useRouteNormalizer, useScreen, useScreenCallback, useViewport };
+export { useBreakpoints, useEffectOnce, useLayoutEffectOnce, useLenisCallback, useMouseCallback, useNavigateAnchor, useOrbit, useRawParams, useScreen, useScreenCallback, useViewport };