react-simplikit 0.0.53 → 0.2.0

package/dist/mobile/hooks/useVisualViewport/useVisualViewport.mjs

@@ -0,0 +1,77 @@
+"use client";
+import { isServer } from "../../utils/isServer/isServer.mjs";
+import { startTransition, useCallback, useEffect, useState } from "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 = isServer() ? null : window.visualViewport;
+	const [viewport, setViewport] = useState(() => visualViewport != null ? getVisualViewportState(visualViewport) : null);
+	const updateViewportState = useCallback(() => {
+		startTransition(() => {
+			setViewport(window.visualViewport != null ? getVisualViewportState(window.visualViewport) : null);
+		});
+	}, []);
+	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
+export { useVisualViewport };

package/dist/mobile/utils/disableBodyScrollLock/disableBodyScrollLock.cjs

@@ -0,0 +1,55 @@
+"use client";
+const require_isServer = require("../isServer/isServer.cjs");
+//#region src/mobile/utils/disableBodyScrollLock/disableBodyScrollLock.ts
+/**
+* Data attribute key for storing scroll position
+*/
+const SCROLL_POSITION_ATTR = "data-simplikit-scroll-y";
+/**
+* @description
+* `disableBodyScrollLock` is a utility function that unlocks the body scroll.
+* It restores the scroll locked by `enableBodyScrollLock` and returns to the saved scroll position.
+*
+* Safe to call in SSR environment (no-op on server).
+* Safe to call even if not locked (no-op).
+*
+* @returns {void}
+*
+* @example
+* // When modal opens
+* enableBodyScrollLock();
+*
+* // When modal closes
+* disableBodyScrollLock();
+*/
+function disableBodyScrollLock() {
+	if (require_isServer.isServer()) return;
+	const savedScrollY = document.body.getAttribute(SCROLL_POSITION_ATTR);
+	if (savedScrollY == null) return;
+	removeScrollLockStyles();
+	restoreScrollPosition(savedScrollY);
+	clearSavedScrollPosition();
+}
+function removeScrollLockStyles() {
+	const { body } = document;
+	body.style.removeProperty("overflow");
+	body.style.removeProperty("position");
+	body.style.removeProperty("top");
+	body.style.removeProperty("left");
+	body.style.removeProperty("right");
+	body.style.removeProperty("bottom");
+}
+function restoreScrollPosition(savedScrollY) {
+	const scrollY = Number(savedScrollY);
+	if (Number.isNaN(scrollY)) {
+		console.warn("[react-simplikit] Invalid scroll position, defaulting to 0");
+		window.scrollTo(0, 0);
+		return;
+	}
+	window.scrollTo(0, scrollY);
+}
+function clearSavedScrollPosition() {
+	document.body.removeAttribute(SCROLL_POSITION_ATTR);
+}
+//#endregion
+exports.disableBodyScrollLock = disableBodyScrollLock;

package/dist/mobile/utils/disableBodyScrollLock/disableBodyScrollLock.d.cts

@@ -0,0 +1,22 @@
+
+//#region src/mobile/utils/disableBodyScrollLock/disableBodyScrollLock.d.ts
+/**
+ * @description
+ * `disableBodyScrollLock` is a utility function that unlocks the body scroll.
+ * It restores the scroll locked by `enableBodyScrollLock` and returns to the saved scroll position.
+ *
+ * Safe to call in SSR environment (no-op on server).
+ * Safe to call even if not locked (no-op).
+ *
+ * @returns {void}
+ *
+ * @example
+ * // When modal opens
+ * enableBodyScrollLock();
+ *
+ * // When modal closes
+ * disableBodyScrollLock();
+ */
+declare function disableBodyScrollLock(): void;
+//#endregion
+export { disableBodyScrollLock };

package/dist/mobile/utils/disableBodyScrollLock/disableBodyScrollLock.d.mts

@@ -0,0 +1,22 @@
+
+//#region src/mobile/utils/disableBodyScrollLock/disableBodyScrollLock.d.ts
+/**
+ * @description
+ * `disableBodyScrollLock` is a utility function that unlocks the body scroll.
+ * It restores the scroll locked by `enableBodyScrollLock` and returns to the saved scroll position.
+ *
+ * Safe to call in SSR environment (no-op on server).
+ * Safe to call even if not locked (no-op).
+ *
+ * @returns {void}
+ *
+ * @example
+ * // When modal opens
+ * enableBodyScrollLock();
+ *
+ * // When modal closes
+ * disableBodyScrollLock();
+ */
+declare function disableBodyScrollLock(): void;
+//#endregion
+export { disableBodyScrollLock };

package/dist/mobile/utils/disableBodyScrollLock/disableBodyScrollLock.mjs

@@ -0,0 +1,55 @@
+"use client";
+import { isServer } from "../isServer/isServer.mjs";
+//#region src/mobile/utils/disableBodyScrollLock/disableBodyScrollLock.ts
+/**
+* Data attribute key for storing scroll position
+*/
+const SCROLL_POSITION_ATTR = "data-simplikit-scroll-y";
+/**
+* @description
+* `disableBodyScrollLock` is a utility function that unlocks the body scroll.
+* It restores the scroll locked by `enableBodyScrollLock` and returns to the saved scroll position.
+*
+* Safe to call in SSR environment (no-op on server).
+* Safe to call even if not locked (no-op).
+*
+* @returns {void}
+*
+* @example
+* // When modal opens
+* enableBodyScrollLock();
+*
+* // When modal closes
+* disableBodyScrollLock();
+*/
+function disableBodyScrollLock() {
+	if (isServer()) return;
+	const savedScrollY = document.body.getAttribute(SCROLL_POSITION_ATTR);
+	if (savedScrollY == null) return;
+	removeScrollLockStyles();
+	restoreScrollPosition(savedScrollY);
+	clearSavedScrollPosition();
+}
+function removeScrollLockStyles() {
+	const { body } = document;
+	body.style.removeProperty("overflow");
+	body.style.removeProperty("position");
+	body.style.removeProperty("top");
+	body.style.removeProperty("left");
+	body.style.removeProperty("right");
+	body.style.removeProperty("bottom");
+}
+function restoreScrollPosition(savedScrollY) {
+	const scrollY = Number(savedScrollY);
+	if (Number.isNaN(scrollY)) {
+		console.warn("[react-simplikit] Invalid scroll position, defaulting to 0");
+		window.scrollTo(0, 0);
+		return;
+	}
+	window.scrollTo(0, scrollY);
+}
+function clearSavedScrollPosition() {
+	document.body.removeAttribute(SCROLL_POSITION_ATTR);
+}
+//#endregion
+export { disableBodyScrollLock };

package/dist/mobile/utils/enableBodyScrollLock/enableBodyScrollLock.cjs

@@ -0,0 +1,49 @@
+"use client";
+const require_isServer = require("../isServer/isServer.cjs");
+//#region src/mobile/utils/enableBodyScrollLock/enableBodyScrollLock.ts
+/**
+* Data attribute key for storing scroll position
+*/
+const SCROLL_POSITION_ATTR = "data-simplikit-scroll-y";
+/**
+* @description
+* `enableBodyScrollLock` is a utility function that locks the body scroll.
+* It prevents the body from scrolling by applying fixed positioning.
+* This is useful when opening modals, drawers, or other overlay components.
+*
+* Safe to call in SSR environment (no-op on server).
+* Calling multiple times has no effect until unlocked.
+*
+* @returns {void}
+*
+* @example
+* // When modal opens
+* enableBodyScrollLock();
+*
+* // When modal closes
+* disableBodyScrollLock();
+*/
+function enableBodyScrollLock() {
+	if (require_isServer.isServer()) return;
+	if (isBodyScrollLocked()) return;
+	const scrollY = window.scrollY;
+	saveScrollPosition(scrollY);
+	applyScrollLockStyles(scrollY);
+}
+function isBodyScrollLocked() {
+	return document.body.getAttribute(SCROLL_POSITION_ATTR) != null;
+}
+function saveScrollPosition(scrollY) {
+	document.body.setAttribute(SCROLL_POSITION_ATTR, scrollY.toString());
+}
+function applyScrollLockStyles(scrollY) {
+	const { body } = document;
+	body.style.overflow = "hidden";
+	body.style.position = "fixed";
+	body.style.top = `-${scrollY}px`;
+	body.style.left = "0px";
+	body.style.right = "0px";
+	body.style.bottom = "0px";
+}
+//#endregion
+exports.enableBodyScrollLock = enableBodyScrollLock;

package/dist/mobile/utils/enableBodyScrollLock/enableBodyScrollLock.d.cts

@@ -0,0 +1,23 @@
+
+//#region src/mobile/utils/enableBodyScrollLock/enableBodyScrollLock.d.ts
+/**
+ * @description
+ * `enableBodyScrollLock` is a utility function that locks the body scroll.
+ * It prevents the body from scrolling by applying fixed positioning.
+ * This is useful when opening modals, drawers, or other overlay components.
+ *
+ * Safe to call in SSR environment (no-op on server).
+ * Calling multiple times has no effect until unlocked.
+ *
+ * @returns {void}
+ *
+ * @example
+ * // When modal opens
+ * enableBodyScrollLock();
+ *
+ * // When modal closes
+ * disableBodyScrollLock();
+ */
+declare function enableBodyScrollLock(): void;
+//#endregion
+export { enableBodyScrollLock };

package/dist/mobile/utils/enableBodyScrollLock/enableBodyScrollLock.d.mts

@@ -0,0 +1,23 @@
+
+//#region src/mobile/utils/enableBodyScrollLock/enableBodyScrollLock.d.ts
+/**
+ * @description
+ * `enableBodyScrollLock` is a utility function that locks the body scroll.
+ * It prevents the body from scrolling by applying fixed positioning.
+ * This is useful when opening modals, drawers, or other overlay components.
+ *
+ * Safe to call in SSR environment (no-op on server).
+ * Calling multiple times has no effect until unlocked.
+ *
+ * @returns {void}
+ *
+ * @example
+ * // When modal opens
+ * enableBodyScrollLock();
+ *
+ * // When modal closes
+ * disableBodyScrollLock();
+ */
+declare function enableBodyScrollLock(): void;
+//#endregion
+export { enableBodyScrollLock };

package/dist/mobile/utils/enableBodyScrollLock/enableBodyScrollLock.mjs

@@ -0,0 +1,49 @@
+"use client";
+import { isServer } from "../isServer/isServer.mjs";
+//#region src/mobile/utils/enableBodyScrollLock/enableBodyScrollLock.ts
+/**
+* Data attribute key for storing scroll position
+*/
+const SCROLL_POSITION_ATTR = "data-simplikit-scroll-y";
+/**
+* @description
+* `enableBodyScrollLock` is a utility function that locks the body scroll.
+* It prevents the body from scrolling by applying fixed positioning.
+* This is useful when opening modals, drawers, or other overlay components.
+*
+* Safe to call in SSR environment (no-op on server).
+* Calling multiple times has no effect until unlocked.
+*
+* @returns {void}
+*
+* @example
+* // When modal opens
+* enableBodyScrollLock();
+*
+* // When modal closes
+* disableBodyScrollLock();
+*/
+function enableBodyScrollLock() {
+	if (isServer()) return;
+	if (isBodyScrollLocked()) return;
+	const scrollY = window.scrollY;
+	saveScrollPosition(scrollY);
+	applyScrollLockStyles(scrollY);
+}
+function isBodyScrollLocked() {
+	return document.body.getAttribute(SCROLL_POSITION_ATTR) != null;
+}
+function saveScrollPosition(scrollY) {
+	document.body.setAttribute(SCROLL_POSITION_ATTR, scrollY.toString());
+}
+function applyScrollLockStyles(scrollY) {
+	const { body } = document;
+	body.style.overflow = "hidden";
+	body.style.position = "fixed";
+	body.style.top = `-${scrollY}px`;
+	body.style.left = "0px";
+	body.style.right = "0px";
+	body.style.bottom = "0px";
+}
+//#endregion
+export { enableBodyScrollLock };

package/dist/mobile/utils/getKeyboardHeight/getKeyboardHeight.cjs

@@ -0,0 +1,35 @@
+"use client";
+const require_isServer = require("../isServer/isServer.cjs");
+//#region src/mobile/utils/getKeyboardHeight/getKeyboardHeight.ts
+/**
+* @description
+* `getKeyboardHeight` is a utility function that returns the current on-screen keyboard height in pixels.
+*
+* This function uses the Visual Viewport API to calculate the keyboard height.
+* It assumes a modern environment where Visual Viewport is supported
+* (Safari / WKWebView 14+, Chrome / Android WebView 80+).
+*
+* The keyboard height is computed as:
+*   `window.innerHeight - visualViewport.height - visualViewport.offsetTop`
+*
+* The subtraction of `offsetTop` is required to correctly handle iOS behavior
+* where the visual viewport may shift vertically when the keyboard appears.
+*
+* @returns {number} The keyboard height in pixels. Returns 0 if the keyboard is not visible.
+*
+* @example
+* const height = getKeyboardHeight();
+*
+* if (height > 0) {
+*   footer.style.paddingBottom = `${height}px`;
+* }
+*/
+function getKeyboardHeight() {
+	if (require_isServer.isServer()) return 0;
+	const visualViewport = window.visualViewport;
+	if (visualViewport == null) return 0;
+	const height = window.innerHeight - visualViewport.height - visualViewport.offsetTop;
+	return Math.max(0, height);
+}
+//#endregion
+exports.getKeyboardHeight = getKeyboardHeight;

package/dist/mobile/utils/getKeyboardHeight/getKeyboardHeight.d.cts

@@ -0,0 +1,28 @@
+
+//#region src/mobile/utils/getKeyboardHeight/getKeyboardHeight.d.ts
+/**
+ * @description
+ * `getKeyboardHeight` is a utility function that returns the current on-screen keyboard height in pixels.
+ *
+ * This function uses the Visual Viewport API to calculate the keyboard height.
+ * It assumes a modern environment where Visual Viewport is supported
+ * (Safari / WKWebView 14+, Chrome / Android WebView 80+).
+ *
+ * The keyboard height is computed as:
+ *   `window.innerHeight - visualViewport.height - visualViewport.offsetTop`
+ *
+ * The subtraction of `offsetTop` is required to correctly handle iOS behavior
+ * where the visual viewport may shift vertically when the keyboard appears.
+ *
+ * @returns {number} The keyboard height in pixels. Returns 0 if the keyboard is not visible.
+ *
+ * @example
+ * const height = getKeyboardHeight();
+ *
+ * if (height > 0) {
+ *   footer.style.paddingBottom = `${height}px`;
+ * }
+ */
+declare function getKeyboardHeight(): number;
+//#endregion
+export { getKeyboardHeight };

package/dist/mobile/utils/getKeyboardHeight/getKeyboardHeight.d.mts

@@ -0,0 +1,28 @@
+
+//#region src/mobile/utils/getKeyboardHeight/getKeyboardHeight.d.ts
+/**
+ * @description
+ * `getKeyboardHeight` is a utility function that returns the current on-screen keyboard height in pixels.
+ *
+ * This function uses the Visual Viewport API to calculate the keyboard height.
+ * It assumes a modern environment where Visual Viewport is supported
+ * (Safari / WKWebView 14+, Chrome / Android WebView 80+).
+ *
+ * The keyboard height is computed as:
+ *   `window.innerHeight - visualViewport.height - visualViewport.offsetTop`
+ *
+ * The subtraction of `offsetTop` is required to correctly handle iOS behavior
+ * where the visual viewport may shift vertically when the keyboard appears.
+ *
+ * @returns {number} The keyboard height in pixels. Returns 0 if the keyboard is not visible.
+ *
+ * @example
+ * const height = getKeyboardHeight();
+ *
+ * if (height > 0) {
+ *   footer.style.paddingBottom = `${height}px`;
+ * }
+ */
+declare function getKeyboardHeight(): number;
+//#endregion
+export { getKeyboardHeight };

package/dist/mobile/utils/getKeyboardHeight/getKeyboardHeight.mjs

@@ -0,0 +1,35 @@
+"use client";
+import { isServer } from "../isServer/isServer.mjs";
+//#region src/mobile/utils/getKeyboardHeight/getKeyboardHeight.ts
+/**
+* @description
+* `getKeyboardHeight` is a utility function that returns the current on-screen keyboard height in pixels.
+*
+* This function uses the Visual Viewport API to calculate the keyboard height.
+* It assumes a modern environment where Visual Viewport is supported
+* (Safari / WKWebView 14+, Chrome / Android WebView 80+).
+*
+* The keyboard height is computed as:
+*   `window.innerHeight - visualViewport.height - visualViewport.offsetTop`
+*
+* The subtraction of `offsetTop` is required to correctly handle iOS behavior
+* where the visual viewport may shift vertically when the keyboard appears.
+*
+* @returns {number} The keyboard height in pixels. Returns 0 if the keyboard is not visible.
+*
+* @example
+* const height = getKeyboardHeight();
+*
+* if (height > 0) {
+*   footer.style.paddingBottom = `${height}px`;
+* }
+*/
+function getKeyboardHeight() {
+	if (isServer()) return 0;
+	const visualViewport = window.visualViewport;
+	if (visualViewport == null) return 0;
+	const height = window.innerHeight - visualViewport.height - visualViewport.offsetTop;
+	return Math.max(0, height);
+}
+//#endregion
+export { getKeyboardHeight };

package/dist/mobile/utils/getSafeAreaInset/getSafeAreaInset.cjs

@@ -0,0 +1,58 @@
+"use client";
+const require_isServer = require("../isServer/isServer.cjs");
+//#region src/mobile/utils/getSafeAreaInset/getSafeAreaInset.ts
+/**
+* @description
+* `getSafeAreaInset` is a utility function that returns all safe area insets in pixels as an object.
+*
+* This function reads the CSS `env(safe-area-inset-*)` values by creating
+* a temporary DOM element and reading its computed style.
+*
+* 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
+*
+* Typical values (iPhone with Face ID, portrait mode):
+* - top: 47-59px (notch/Dynamic Island)
+* - bottom: 34px (home indicator)
+* - left/right: 0px
+*
+* @returns {SafeAreaInset} Object containing safe area insets for all four sides, or all 0 if not available.
+* - top `number` - Top safe area inset in pixels;
+* - bottom `number` - Bottom safe area inset in pixels;
+* - left `number` - Left safe area inset in pixels;
+* - right `number` - Right safe area inset in pixels;
+*
+* @example
+* const { top, bottom, left, right } = getSafeAreaInset();
+*
+* header.style.paddingTop = `${top}px`;
+* footer.style.paddingBottom = `${bottom}px`;
+*/
+function getSafeAreaInset() {
+	if (require_isServer.isServer()) return {
+		top: 0,
+		bottom: 0,
+		left: 0,
+		right: 0
+	};
+	const div = document.createElement("div");
+	div.style.position = "fixed";
+	div.style.setProperty("padding-top", "env(safe-area-inset-top)");
+	div.style.setProperty("padding-bottom", "env(safe-area-inset-bottom)");
+	div.style.setProperty("padding-left", "env(safe-area-inset-left)");
+	div.style.setProperty("padding-right", "env(safe-area-inset-right)");
+	document.body.appendChild(div);
+	const computedStyle = window.getComputedStyle(div);
+	const inset = {
+		top: parseFloat(computedStyle.getPropertyValue("padding-top")) || 0,
+		bottom: parseFloat(computedStyle.getPropertyValue("padding-bottom")) || 0,
+		left: parseFloat(computedStyle.getPropertyValue("padding-left")) || 0,
+		right: parseFloat(computedStyle.getPropertyValue("padding-right")) || 0
+	};
+	document.body.removeChild(div);
+	return inset;
+}
+//#endregion
+exports.getSafeAreaInset = getSafeAreaInset;

package/dist/mobile/utils/getSafeAreaInset/getSafeAreaInset.d.cts

@@ -0,0 +1,44 @@
+
+//#region src/mobile/utils/getSafeAreaInset/getSafeAreaInset.d.ts
+type SafeAreaInset = {
+  /** Top safe area inset in pixels (notch, Dynamic Island, or status bar) */
+  top: number;
+  /** Bottom safe area inset in pixels (home indicator on Face ID devices) */
+  bottom: number;
+  /** Left safe area inset in pixels (rounded corners in landscape mode) */
+  left: number;
+  /** Right safe area inset in pixels (rounded corners in landscape mode) */
+  right: number;
+};
+/**
+ * @description
+ * `getSafeAreaInset` is a utility function that returns all safe area insets in pixels as an object.
+ *
+ * This function reads the CSS `env(safe-area-inset-*)` values by creating
+ * a temporary DOM element and reading its computed style.
+ *
+ * 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
+ *
+ * Typical values (iPhone with Face ID, portrait mode):
+ * - top: 47-59px (notch/Dynamic Island)
+ * - bottom: 34px (home indicator)
+ * - left/right: 0px
+ *
+ * @returns {SafeAreaInset} Object containing safe area insets for all four sides, or all 0 if not available.
+ * - top `number` - Top safe area inset in pixels;
+ * - bottom `number` - Bottom safe area inset in pixels;
+ * - left `number` - Left safe area inset in pixels;
+ * - right `number` - Right safe area inset in pixels;
+ *
+ * @example
+ * const { top, bottom, left, right } = getSafeAreaInset();
+ *
+ * header.style.paddingTop = `${top}px`;
+ * footer.style.paddingBottom = `${bottom}px`;
+ */
+declare function getSafeAreaInset(): SafeAreaInset;
+//#endregion
+export { SafeAreaInset, getSafeAreaInset };

package/dist/mobile/utils/getSafeAreaInset/getSafeAreaInset.d.mts

@@ -0,0 +1,44 @@
+
+//#region src/mobile/utils/getSafeAreaInset/getSafeAreaInset.d.ts
+type SafeAreaInset = {
+  /** Top safe area inset in pixels (notch, Dynamic Island, or status bar) */
+  top: number;
+  /** Bottom safe area inset in pixels (home indicator on Face ID devices) */
+  bottom: number;
+  /** Left safe area inset in pixels (rounded corners in landscape mode) */
+  left: number;
+  /** Right safe area inset in pixels (rounded corners in landscape mode) */
+  right: number;
+};
+/**
+ * @description
+ * `getSafeAreaInset` is a utility function that returns all safe area insets in pixels as an object.
+ *
+ * This function reads the CSS `env(safe-area-inset-*)` values by creating
+ * a temporary DOM element and reading its computed style.
+ *
+ * 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
+ *
+ * Typical values (iPhone with Face ID, portrait mode):
+ * - top: 47-59px (notch/Dynamic Island)
+ * - bottom: 34px (home indicator)
+ * - left/right: 0px
+ *
+ * @returns {SafeAreaInset} Object containing safe area insets for all four sides, or all 0 if not available.
+ * - top `number` - Top safe area inset in pixels;
+ * - bottom `number` - Bottom safe area inset in pixels;
+ * - left `number` - Left safe area inset in pixels;
+ * - right `number` - Right safe area inset in pixels;
+ *
+ * @example
+ * const { top, bottom, left, right } = getSafeAreaInset();
+ *
+ * header.style.paddingTop = `${top}px`;
+ * footer.style.paddingBottom = `${bottom}px`;
+ */
+declare function getSafeAreaInset(): SafeAreaInset;
+//#endregion
+export { SafeAreaInset, getSafeAreaInset };