react-simplikit 0.0.53 → 0.2.0

package/dist/mobile/hooks/useSafeAreaInset/useSafeAreaInset.d.mts

@@ -0,0 +1,55 @@
+
+import { SafeAreaInset } from "../../utils/getSafeAreaInset/getSafeAreaInset.mjs";
+//#region src/mobile/hooks/useSafeAreaInset/useSafeAreaInset.d.ts
+/**
+ * @description
+ * `useSafeAreaInset` is a React hook that tracks safe area inset changes.
+ * It returns the safe area insets that automatically update when the screen
+ * orientation changes (e.g., portrait to landscape).
+ *
+ * Safe area insets account for device-specific UI elements:
+ * - **top**: Notch, Dynamic Island, or status bar
+ * - **bottom**: Home indicator on Face ID devices
+ * - **left/right**: Rounded corners in landscape mode
+ *
+ * @returns {SafeAreaInset} An object containing safe area insets for all four sides.
+ * - top `number` - Top safe area inset in pixels. Accounts for the notch, Dynamic Island, or status bar;
+ * - bottom `number` - Bottom safe area inset in pixels. Accounts for the home indicator on Face ID devices;
+ * - left `number` - Left safe area inset in pixels. Accounts for rounded corners in landscape mode;
+ * - right `number` - Right safe area inset in pixels. Accounts for rounded corners in landscape mode;
+ *
+ * @example
+ * function MyComponent() {
+ *   const safeArea = useSafeAreaInset();
+ *
+ *   return (
+ *     <div style={{
+ *       paddingTop: safeArea.top,
+ *       paddingBottom: safeArea.bottom,
+ *       paddingLeft: safeArea.left,
+ *       paddingRight: safeArea.right,
+ *     }}>
+ *       Content that respects safe areas
+ *     </div>
+ *   );
+ * }
+ *
+ * @example
+ * // Automatically updates when screen rotates
+ * function RotationAwareHeader() {
+ *   const { top, left, right } = useSafeAreaInset();
+ *
+ *   return (
+ *     <header style={{
+ *       paddingTop: top,
+ *       paddingLeft: left,
+ *       paddingRight: right,
+ *     }}>
+ *       Header content
+ *     </header>
+ *   );
+ * }
+ */
+declare function useSafeAreaInset(): SafeAreaInset;
+//#endregion
+export { useSafeAreaInset };

package/dist/mobile/hooks/useSafeAreaInset/useSafeAreaInset.mjs

@@ -0,0 +1,74 @@
+"use client";
+import { isServer } from "../../utils/isServer/isServer.mjs";
+import { getSafeAreaInset } from "../../utils/getSafeAreaInset/getSafeAreaInset.mjs";
+import { startTransition, useCallback, useEffect, useState } from "react";
+//#region src/mobile/hooks/useSafeAreaInset/useSafeAreaInset.ts
+/**
+* @description
+* `useSafeAreaInset` is a React hook that tracks safe area inset changes.
+* It returns the safe area insets that automatically update when the screen
+* orientation changes (e.g., portrait to landscape).
+*
+* Safe area insets account for device-specific UI elements:
+* - **top**: Notch, Dynamic Island, or status bar
+* - **bottom**: Home indicator on Face ID devices
+* - **left/right**: Rounded corners in landscape mode
+*
+* @returns {SafeAreaInset} An object containing safe area insets for all four sides.
+* - top `number` - Top safe area inset in pixels. Accounts for the notch, Dynamic Island, or status bar;
+* - bottom `number` - Bottom safe area inset in pixels. Accounts for the home indicator on Face ID devices;
+* - left `number` - Left safe area inset in pixels. Accounts for rounded corners in landscape mode;
+* - right `number` - Right safe area inset in pixels. Accounts for rounded corners in landscape mode;
+*
+* @example
+* function MyComponent() {
+*   const safeArea = useSafeAreaInset();
+*
+*   return (
+*     <div style={{
+*       paddingTop: safeArea.top,
+*       paddingBottom: safeArea.bottom,
+*       paddingLeft: safeArea.left,
+*       paddingRight: safeArea.right,
+*     }}>
+*       Content that respects safe areas
+*     </div>
+*   );
+* }
+*
+* @example
+* // Automatically updates when screen rotates
+* function RotationAwareHeader() {
+*   const { top, left, right } = useSafeAreaInset();
+*
+*   return (
+*     <header style={{
+*       paddingTop: top,
+*       paddingLeft: left,
+*       paddingRight: right,
+*     }}>
+*       Header content
+*     </header>
+*   );
+* }
+*/
+function useSafeAreaInset() {
+	const [inset, setInset] = useState(() => getSafeAreaInset());
+	const updateInset = useCallback(() => {
+		startTransition(() => {
+			setInset(getSafeAreaInset());
+		});
+	}, []);
+	useEffect(function handleOrientationChange() {
+		if (isServer()) return;
+		window.addEventListener("resize", updateInset);
+		window.addEventListener("orientationchange", updateInset);
+		return function cleanup() {
+			window.removeEventListener("resize", updateInset);
+			window.removeEventListener("orientationchange", updateInset);
+		};
+	}, [updateInset]);
+	return inset;
+}
+//#endregion
+export { useSafeAreaInset };

package/dist/mobile/hooks/useScrollDirection/useScrollDirection.cjs

@@ -0,0 +1,79 @@
+"use client";
+const require_isServer = require("../../utils/isServer/isServer.cjs");
+let react = require("react");
+//#region src/mobile/hooks/useScrollDirection/useScrollDirection.ts
+/**
+* @description
+* `useScrollDirection` is a React hook that detects scroll direction.
+* It returns scroll direction (up/down) and current scroll position.
+* Throttled by default (50ms) for performance.
+*
+* @param {UseScrollDirectionOptions} [options] - Configuration options.
+* @param {number} [options.throttleMs=50] - Throttle interval in milliseconds.
+* @returns {ScrollDirectionState} Scroll direction state: `direction` (`'up' | 'down' | null`) and `position` (px).
+*
+* @example
+* function Header() {
+*   const { direction, position } = useScrollDirection();
+*
+*   // Hide header on scroll down
+*   const isHidden = direction === 'down' && position > 100;
+*
+*   return (
+*     <header className={isHidden ? 'hidden' : 'visible'}>
+*       My Header
+*     </header>
+*   );
+* }
+*/
+function useScrollDirection(options = {}) {
+	const { throttleMs = 50 } = options;
+	const [scrollInfo, setScrollInfo] = (0, react.useState)({
+		direction: null,
+		position: require_isServer.isServer() ? 0 : window.scrollY
+	});
+	const lastScrollYRef = (0, react.useRef)(require_isServer.isServer() ? 0 : window.scrollY);
+	const throttleTimerRef = (0, react.useRef)(null);
+	const updateScrollDirection = (0, react.useCallback)(({ currentScrollY, lastScrollY }) => {
+		if (currentScrollY > lastScrollY) {
+			setScrollInfo({
+				direction: "down",
+				position: currentScrollY
+			});
+			return;
+		}
+		if (currentScrollY < lastScrollY) {
+			setScrollInfo({
+				direction: "up",
+				position: currentScrollY
+			});
+			return;
+		}
+	}, []);
+	const startThrottle = (0, react.useCallback)(() => {
+		throttleTimerRef.current = setTimeout(function clearThrottle() {
+			throttleTimerRef.current = null;
+		}, throttleMs);
+	}, [throttleMs]);
+	(0, react.useEffect)(function handleScrollDirectionChange() {
+		function handleScroll() {
+			if (throttleTimerRef.current != null) return;
+			const currentScrollY = window.scrollY;
+			const lastScrollY = lastScrollYRef.current;
+			lastScrollYRef.current = currentScrollY;
+			startThrottle();
+			updateScrollDirection({
+				currentScrollY,
+				lastScrollY
+			});
+		}
+		window.addEventListener("scroll", handleScroll, { passive: true });
+		return function cleanup() {
+			window.removeEventListener("scroll", handleScroll);
+			if (throttleTimerRef.current != null) clearTimeout(throttleTimerRef.current);
+		};
+	}, [startThrottle, updateScrollDirection]);
+	return scrollInfo;
+}
+//#endregion
+exports.useScrollDirection = useScrollDirection;

package/dist/mobile/hooks/useScrollDirection/useScrollDirection.d.cts

@@ -0,0 +1,40 @@
+
+//#region src/mobile/hooks/useScrollDirection/useScrollDirection.d.ts
+type ScrollDirection = 'up' | 'down' | null;
+type ScrollDirectionState = {
+  /** Current scroll direction */
+  direction: ScrollDirection;
+  /** Current scroll Y position (px) */
+  position: number;
+};
+type UseScrollDirectionOptions = {
+  /** Throttle interval (ms) - default: 50ms */
+  throttleMs?: number;
+};
+/**
+ * @description
+ * `useScrollDirection` is a React hook that detects scroll direction.
+ * It returns scroll direction (up/down) and current scroll position.
+ * Throttled by default (50ms) for performance.
+ *
+ * @param {UseScrollDirectionOptions} [options] - Configuration options.
+ * @param {number} [options.throttleMs=50] - Throttle interval in milliseconds.
+ * @returns {ScrollDirectionState} Scroll direction state: `direction` (`'up' | 'down' | null`) and `position` (px).
+ *
+ * @example
+ * function Header() {
+ *   const { direction, position } = useScrollDirection();
+ *
+ *   // Hide header on scroll down
+ *   const isHidden = direction === 'down' && position > 100;
+ *
+ *   return (
+ *     <header className={isHidden ? 'hidden' : 'visible'}>
+ *       My Header
+ *     </header>
+ *   );
+ * }
+ */
+declare function useScrollDirection(options?: UseScrollDirectionOptions): ScrollDirectionState;
+//#endregion
+export { useScrollDirection };

package/dist/mobile/hooks/useScrollDirection/useScrollDirection.d.mts

@@ -0,0 +1,40 @@
+
+//#region src/mobile/hooks/useScrollDirection/useScrollDirection.d.ts
+type ScrollDirection = 'up' | 'down' | null;
+type ScrollDirectionState = {
+  /** Current scroll direction */
+  direction: ScrollDirection;
+  /** Current scroll Y position (px) */
+  position: number;
+};
+type UseScrollDirectionOptions = {
+  /** Throttle interval (ms) - default: 50ms */
+  throttleMs?: number;
+};
+/**
+ * @description
+ * `useScrollDirection` is a React hook that detects scroll direction.
+ * It returns scroll direction (up/down) and current scroll position.
+ * Throttled by default (50ms) for performance.
+ *
+ * @param {UseScrollDirectionOptions} [options] - Configuration options.
+ * @param {number} [options.throttleMs=50] - Throttle interval in milliseconds.
+ * @returns {ScrollDirectionState} Scroll direction state: `direction` (`'up' | 'down' | null`) and `position` (px).
+ *
+ * @example
+ * function Header() {
+ *   const { direction, position } = useScrollDirection();
+ *
+ *   // Hide header on scroll down
+ *   const isHidden = direction === 'down' && position > 100;
+ *
+ *   return (
+ *     <header className={isHidden ? 'hidden' : 'visible'}>
+ *       My Header
+ *     </header>
+ *   );
+ * }
+ */
+declare function useScrollDirection(options?: UseScrollDirectionOptions): ScrollDirectionState;
+//#endregion
+export { useScrollDirection };

package/dist/mobile/hooks/useScrollDirection/useScrollDirection.mjs

@@ -0,0 +1,79 @@
+"use client";
+import { isServer } from "../../utils/isServer/isServer.mjs";
+import { useCallback, useEffect, useRef, useState } from "react";
+//#region src/mobile/hooks/useScrollDirection/useScrollDirection.ts
+/**
+* @description
+* `useScrollDirection` is a React hook that detects scroll direction.
+* It returns scroll direction (up/down) and current scroll position.
+* Throttled by default (50ms) for performance.
+*
+* @param {UseScrollDirectionOptions} [options] - Configuration options.
+* @param {number} [options.throttleMs=50] - Throttle interval in milliseconds.
+* @returns {ScrollDirectionState} Scroll direction state: `direction` (`'up' | 'down' | null`) and `position` (px).
+*
+* @example
+* function Header() {
+*   const { direction, position } = useScrollDirection();
+*
+*   // Hide header on scroll down
+*   const isHidden = direction === 'down' && position > 100;
+*
+*   return (
+*     <header className={isHidden ? 'hidden' : 'visible'}>
+*       My Header
+*     </header>
+*   );
+* }
+*/
+function useScrollDirection(options = {}) {
+	const { throttleMs = 50 } = options;
+	const [scrollInfo, setScrollInfo] = useState({
+		direction: null,
+		position: isServer() ? 0 : window.scrollY
+	});
+	const lastScrollYRef = useRef(isServer() ? 0 : window.scrollY);
+	const throttleTimerRef = useRef(null);
+	const updateScrollDirection = useCallback(({ currentScrollY, lastScrollY }) => {
+		if (currentScrollY > lastScrollY) {
+			setScrollInfo({
+				direction: "down",
+				position: currentScrollY
+			});
+			return;
+		}
+		if (currentScrollY < lastScrollY) {
+			setScrollInfo({
+				direction: "up",
+				position: currentScrollY
+			});
+			return;
+		}
+	}, []);
+	const startThrottle = useCallback(() => {
+		throttleTimerRef.current = setTimeout(function clearThrottle() {
+			throttleTimerRef.current = null;
+		}, throttleMs);
+	}, [throttleMs]);
+	useEffect(function handleScrollDirectionChange() {
+		function handleScroll() {
+			if (throttleTimerRef.current != null) return;
+			const currentScrollY = window.scrollY;
+			const lastScrollY = lastScrollYRef.current;
+			lastScrollYRef.current = currentScrollY;
+			startThrottle();
+			updateScrollDirection({
+				currentScrollY,
+				lastScrollY
+			});
+		}
+		window.addEventListener("scroll", handleScroll, { passive: true });
+		return function cleanup() {
+			window.removeEventListener("scroll", handleScroll);
+			if (throttleTimerRef.current != null) clearTimeout(throttleTimerRef.current);
+		};
+	}, [startThrottle, updateScrollDirection]);
+	return scrollInfo;
+}
+//#endregion
+export { useScrollDirection };

package/dist/mobile/hooks/useVisualViewport/useVisualViewport.cjs

@@ -0,0 +1,77 @@
+"use client";
+const require_isServer = require("../../utils/isServer/isServer.cjs");
+let react = require("react");
+//#region src/mobile/hooks/useVisualViewport/useVisualViewport.ts
+/**
+* @description
+* `useVisualViewport` is a React hook that tracks Visual Viewport changes.
+* It returns the actual visible area in mobile WebView, which changes when
+* the keyboard appears or the user zooms/scrolls.
+*
+* **Important:** `viewport` is `null` on SSR or in browsers that don't support Visual Viewport API.
+* Always check for null before accessing viewport properties.
+*
+* **Tip:** If you only need keyboard height, use `useKeyboardHeight()` instead
+* for a simpler API.
+*
+* @returns {{ viewport: VisualViewportState | null }} An object containing the Visual Viewport state.
+* - viewport `VisualViewportState | null` - Visual Viewport state object, or `null` if not supported (SSR or browsers without the Visual Viewport API);
+* - viewport.width `number` - Viewport width in pixels;
+* - viewport.height `number` - Viewport height in pixels;
+* - viewport.offsetLeft `number` - Viewport left offset in pixels from the layout viewport. Typically 0 unless horizontal scrolling or panning occurs;
+* - viewport.offsetTop `number` - Viewport top offset in pixels from the layout viewport. Becomes negative on iOS when the keyboard appears, so use `-offsetTop` for the keyboard height. Typically remains 0 on Android;
+* - viewport.scale `number` - Pinch-zoom scaling factor. 1.0 means no zoom, greater than 1.0 means zoomed in;
+*
+* @see {@link useKeyboardHeight} - Simpler hook for keyboard height only
+*
+* @example
+* function CustomLayout() {
+*   const { viewport } = useVisualViewport();
+*
+*   // Always check for null first
+*   if (!viewport) {
+*     return <div>Visual Viewport not supported</div>;
+*   }
+*
+*   const { width, height, offsetTop, scale } = viewport;
+*
+*   // Hide floating UI when user zooms in
+*   const showFloatingUI = scale <= 1.3;
+*
+*   return (
+*     <div style={{ height }}>
+*       {showFloatingUI && <FloatingButton />}
+*       Viewport-aware content
+*     </div>
+*   );
+* }
+*/
+function useVisualViewport() {
+	const visualViewport = require_isServer.isServer() ? null : window.visualViewport;
+	const [viewport, setViewport] = (0, react.useState)(() => visualViewport != null ? getVisualViewportState(visualViewport) : null);
+	const updateViewportState = (0, react.useCallback)(() => {
+		(0, react.startTransition)(() => {
+			setViewport(window.visualViewport != null ? getVisualViewportState(window.visualViewport) : null);
+		});
+	}, []);
+	(0, react.useEffect)(function handleVisualViewportChange() {
+		window.visualViewport?.addEventListener("resize", updateViewportState);
+		window.visualViewport?.addEventListener("scroll", updateViewportState);
+		return function cleanup() {
+			window.visualViewport?.removeEventListener("resize", updateViewportState);
+			window.visualViewport?.removeEventListener("scroll", updateViewportState);
+		};
+	}, [updateViewportState]);
+	return { viewport };
+}
+function getVisualViewportState(visualViewport) {
+	return {
+		width: visualViewport.width,
+		height: visualViewport.height,
+		offsetLeft: visualViewport.offsetLeft,
+		offsetTop: visualViewport.offsetTop,
+		scale: visualViewport.scale
+	};
+}
+//#endregion
+exports.useVisualViewport = useVisualViewport;

package/dist/mobile/hooks/useVisualViewport/useVisualViewport.d.cts

@@ -0,0 +1,89 @@
+
+//#region src/mobile/hooks/useVisualViewport/useVisualViewport.d.ts
+type VisualViewportState = {
+  /** Viewport width (px) */
+  width: number;
+  /** Viewport height (px) */
+  height: number;
+  /**
+   * Viewport left offset (px) from the layout viewport
+   *
+   * Typically 0 unless horizontal scrolling or panning occurs
+   */
+  offsetLeft: number;
+  /**
+   * Viewport top offset (px) from the layout viewport
+   *
+   * On iOS: Becomes negative when keyboard appears (e.g., -300px means 300px keyboard height)
+   * On Android: Typically remains 0
+   *
+   * Use `-offsetTop` to get accurate keyboard height on iOS
+   */
+  offsetTop: number;
+  /**
+   * Pinch-zoom scaling factor
+   *
+   * - 1.0 = no zoom (default)
+   * - > 1.0 = zoomed in
+   * - < 1.0 = zoomed out (rare, depends on viewport settings)
+   *
+   * @example
+   * ```tsx
+   * const { viewport } = useVisualViewport();
+   * if (viewport && viewport.scale > 1.3) {
+   *   // Hide floating UI when user zooms in
+   *   setShowFloatingButton(false);
+   * }
+   * ```
+   */
+  scale: number;
+};
+/**
+ * @description
+ * `useVisualViewport` is a React hook that tracks Visual Viewport changes.
+ * It returns the actual visible area in mobile WebView, which changes when
+ * the keyboard appears or the user zooms/scrolls.
+ *
+ * **Important:** `viewport` is `null` on SSR or in browsers that don't support Visual Viewport API.
+ * Always check for null before accessing viewport properties.
+ *
+ * **Tip:** If you only need keyboard height, use `useKeyboardHeight()` instead
+ * for a simpler API.
+ *
+ * @returns {{ viewport: VisualViewportState | null }} An object containing the Visual Viewport state.
+ * - viewport `VisualViewportState | null` - Visual Viewport state object, or `null` if not supported (SSR or browsers without the Visual Viewport API);
+ * - viewport.width `number` - Viewport width in pixels;
+ * - viewport.height `number` - Viewport height in pixels;
+ * - viewport.offsetLeft `number` - Viewport left offset in pixels from the layout viewport. Typically 0 unless horizontal scrolling or panning occurs;
+ * - viewport.offsetTop `number` - Viewport top offset in pixels from the layout viewport. Becomes negative on iOS when the keyboard appears, so use `-offsetTop` for the keyboard height. Typically remains 0 on Android;
+ * - viewport.scale `number` - Pinch-zoom scaling factor. 1.0 means no zoom, greater than 1.0 means zoomed in;
+ *
+ * @see {@link useKeyboardHeight} - Simpler hook for keyboard height only
+ *
+ * @example
+ * function CustomLayout() {
+ *   const { viewport } = useVisualViewport();
+ *
+ *   // Always check for null first
+ *   if (!viewport) {
+ *     return <div>Visual Viewport not supported</div>;
+ *   }
+ *
+ *   const { width, height, offsetTop, scale } = viewport;
+ *
+ *   // Hide floating UI when user zooms in
+ *   const showFloatingUI = scale <= 1.3;
+ *
+ *   return (
+ *     <div style={{ height }}>
+ *       {showFloatingUI && <FloatingButton />}
+ *       Viewport-aware content
+ *     </div>
+ *   );
+ * }
+ */
+declare function useVisualViewport(): {
+  viewport: VisualViewportState | null;
+};
+//#endregion
+export { useVisualViewport };

package/dist/mobile/hooks/useVisualViewport/useVisualViewport.d.mts

@@ -0,0 +1,89 @@
+
+//#region src/mobile/hooks/useVisualViewport/useVisualViewport.d.ts
+type VisualViewportState = {
+  /** Viewport width (px) */
+  width: number;
+  /** Viewport height (px) */
+  height: number;
+  /**
+   * Viewport left offset (px) from the layout viewport
+   *
+   * Typically 0 unless horizontal scrolling or panning occurs
+   */
+  offsetLeft: number;
+  /**
+   * Viewport top offset (px) from the layout viewport
+   *
+   * On iOS: Becomes negative when keyboard appears (e.g., -300px means 300px keyboard height)
+   * On Android: Typically remains 0
+   *
+   * Use `-offsetTop` to get accurate keyboard height on iOS
+   */
+  offsetTop: number;
+  /**
+   * Pinch-zoom scaling factor
+   *
+   * - 1.0 = no zoom (default)
+   * - > 1.0 = zoomed in
+   * - < 1.0 = zoomed out (rare, depends on viewport settings)
+   *
+   * @example
+   * ```tsx
+   * const { viewport } = useVisualViewport();
+   * if (viewport && viewport.scale > 1.3) {
+   *   // Hide floating UI when user zooms in
+   *   setShowFloatingButton(false);
+   * }
+   * ```
+   */
+  scale: number;
+};
+/**
+ * @description
+ * `useVisualViewport` is a React hook that tracks Visual Viewport changes.
+ * It returns the actual visible area in mobile WebView, which changes when
+ * the keyboard appears or the user zooms/scrolls.
+ *
+ * **Important:** `viewport` is `null` on SSR or in browsers that don't support Visual Viewport API.
+ * Always check for null before accessing viewport properties.
+ *
+ * **Tip:** If you only need keyboard height, use `useKeyboardHeight()` instead
+ * for a simpler API.
+ *
+ * @returns {{ viewport: VisualViewportState | null }} An object containing the Visual Viewport state.
+ * - viewport `VisualViewportState | null` - Visual Viewport state object, or `null` if not supported (SSR or browsers without the Visual Viewport API);
+ * - viewport.width `number` - Viewport width in pixels;
+ * - viewport.height `number` - Viewport height in pixels;
+ * - viewport.offsetLeft `number` - Viewport left offset in pixels from the layout viewport. Typically 0 unless horizontal scrolling or panning occurs;
+ * - viewport.offsetTop `number` - Viewport top offset in pixels from the layout viewport. Becomes negative on iOS when the keyboard appears, so use `-offsetTop` for the keyboard height. Typically remains 0 on Android;
+ * - viewport.scale `number` - Pinch-zoom scaling factor. 1.0 means no zoom, greater than 1.0 means zoomed in;
+ *
+ * @see {@link useKeyboardHeight} - Simpler hook for keyboard height only
+ *
+ * @example
+ * function CustomLayout() {
+ *   const { viewport } = useVisualViewport();
+ *
+ *   // Always check for null first
+ *   if (!viewport) {
+ *     return <div>Visual Viewport not supported</div>;
+ *   }
+ *
+ *   const { width, height, offsetTop, scale } = viewport;
+ *
+ *   // Hide floating UI when user zooms in
+ *   const showFloatingUI = scale <= 1.3;
+ *
+ *   return (
+ *     <div style={{ height }}>
+ *       {showFloatingUI && <FloatingButton />}
+ *       Viewport-aware content
+ *     </div>
+ *   );
+ * }
+ */
+declare function useVisualViewport(): {
+  viewport: VisualViewportState | null;
+};
+//#endregion
+export { useVisualViewport };