@stellar-expert/ui-framework 1.16.8 → 1.17.0

package/state/on-screen-hooks.js

@@ -1,23 +1,23 @@
-import {useEffect, useState} from 'react'
-
-//TODO consider using a single instance of an IntersectionObserver to track all changes instead of creating many instances
-
-/**
- * Hook for determining the visibility of the element inside the scroll context using the Intersection Observer API
- * @param {MutableRefObject<Element>} root - Scroll parent ref
- * @param {String} [rootMargin] - Visibility margin, in pixels or percents (default 0)
- * @returns {Boolean} - Whether an element is visible or not
- */
-export function useOnScreen(root, rootMargin) {
-    const [isVisible, setVisibility] = useState(false)
-
-    useEffect(() => {
-        if (!root.current)
-            return
-        const observer = new IntersectionObserver(([entry]) => setVisibility(entry.isIntersecting), {rootMargin})
-        observer.observe(root.current)
-        return () => observer.disconnect()
-    }, [root.current])
-
-    return isVisible
+import {useEffect, useState} from 'react'
+
+//TODO consider using a single instance of an IntersectionObserver to track all changes instead of creating many instances
+
+/**
+ * Hook for determining the visibility of the element inside the scroll context using the Intersection Observer API
+ * @param {MutableRefObject<Element>} root - Scroll parent ref
+ * @param {string} [rootMargin] - Visibility margin, in pixels or percents (default 0)
+ * @returns {boolean} - Whether an element is visible or not
+ */
+export function useOnScreen(root, rootMargin) {
+    const [isVisible, setVisibility] = useState(false)
+
+    useEffect(() => {
+        if (!root.current)
+            return
+        const observer = new IntersectionObserver(([entry]) => setVisibility(entry.isIntersecting), {rootMargin})
+        observer.observe(root.current)
+        return () => observer.disconnect()
+    }, [root.current])
+
+    return isVisible
 }

package/state/page-visibility-helpers.js

@@ -1,17 +1,30 @@
-export const isDocumentVisibilitySupported = 'hidden' in document
-
-export function isDocumentVisible() {
-    if (!isDocumentVisibilitySupported) return true
-    return !document.hidden
-}
-
-export function addVisibilityChangeListener(listener) {
-    function wrappedListener() {
-        listener(isDocumentVisible())
-    }
-
-    document.addEventListener('visibilitychange', wrappedListener)
-    return function () {
-        document.removeEventListener('visibilitychange', wrappedListener)
-    }
+/**
+ * Whether the Page Visibility API is supported by the browser
+ * @type {boolean}
+ */
+export const isDocumentVisibilitySupported = 'hidden' in document
+
+/**
+ * Check whether the document is currently visible (tab is active)
+ * @return {boolean}
+ */
+export function isDocumentVisible() {
+    if (!isDocumentVisibilitySupported) return true
+    return !document.hidden
+}
+
+/**
+ * Register a listener for document visibility changes
+ * @param {function(boolean): void} listener - Callback invoked with `true` when visible, `false` when hidden
+ * @return {function(): void} Unsubscribe function
+ */
+export function addVisibilityChangeListener(listener) {
+    function wrappedListener() {
+        listener(isDocumentVisible())
+    }
+
+    document.addEventListener('visibilitychange', wrappedListener)
+    return function () {
+        document.removeEventListener('visibilitychange', wrappedListener)
+    }
 }

package/state/page-visibility-hooks.js

@@ -1,12 +1,14 @@
-import {useState, useEffect} from 'react'
-import {isDocumentVisible, addVisibilityChangeListener, isDocumentVisibilitySupported} from './page-visibility-helpers'
-
-/**
- * @returns {Boolean} - True if the page is currently visible or false otherwise
- */
-export function usePageVisibility() {
-    const [visible, setVisible] = useState(isDocumentVisible)
-    if (!isDocumentVisibilitySupported || !document.addEventListener) return true
-    useEffect(()=>addVisibilityChangeListener(() => setVisible(isDocumentVisible())))
-    return visible
+import {useState, useEffect} from 'react'
+import {isDocumentVisible, addVisibilityChangeListener, isDocumentVisibilitySupported} from './page-visibility-helpers'
+
+/**
+ * Hook that tracks whether the current browser tab/page is visible
+ * @returns {boolean} - True if the page is currently visible or false otherwise
+ */
+export function usePageVisibility() {
+    const [visible, setVisible] = useState(isDocumentVisible)
+    if (!isDocumentVisibilitySupported || !document.addEventListener)
+        return true
+    useEffect(() => addVisibilityChangeListener(() => setVisible(isDocumentVisible())))
+    return visible
 }

package/state/screen-orientation-hooks.js

@@ -1,16 +1,20 @@
-import {useState, useEffect} from 'react'
-
-export function useScreenOrientation() {
-    const [orientation, setOrientation] = useState(window.screen.orientation.type)
-
-    function onChange() {
-        setOrientation(window.screen.orientation.type)
-    }
-
-    useEffect(() => {
-        window.addEventListener('orientationchange', onChange)
-        return () => window.removeEventListener('orientationchange', onChange)
-    }, [])
-
-    return orientation
+import {useState, useEffect} from 'react'
+
+/**
+ * React hook that tracks and returns the current screen orientation type
+ * @return {OrientationType} Screen orientation (e.g., "portrait-primary", "landscape-primary")
+ */
+export function useScreenOrientation() {
+    const [orientation, setOrientation] = useState(window.screen.orientation.type)
+
+    function onChange() {
+        setOrientation(window.screen.orientation.type)
+    }
+
+    useEffect(() => {
+        window.addEventListener('orientationchange', onChange)
+        return () => window.removeEventListener('orientationchange', onChange)
+    }, [])
+
+    return orientation
 }

package/state/state-hooks.js

@@ -1,77 +1,77 @@
-import {useState, useEffect, useRef} from 'react'
-import isEqual from 'react-fast-compare'
-
-function ensureDependencies(dependencies) {
-    if (!(dependencies instanceof Array))
-        throw new Error('Parameter dependencies is required for useDependantState hook')
-}
-
-/**
- * React hook that automatically re-inits state when one of the dependencies changed
- * @param {Function|any} stateInitializer
- * @param {Array} dependencies
- * @param {Function} [finalizer]
- * @returns {[Object, Function]}
- */
-export function useDependantState(stateInitializer, dependencies, finalizer) {
-    //ensureDependencies(dependencies)
-    const [state, updateState] = useState(function () {
-        return typeof stateInitializer === 'function' ? stateInitializer(dependencies) : stateInitializer
-    })
-    //pin dependencies object to invoke effect update only if dependencies changed
-    const pinnedDeps = useRef(dependencies)
-    let dependenciesChanged = !isEqual(dependencies, pinnedDeps.current)
-    //check that dependencies really changed
-    if (dependenciesChanged) {
-        pinnedDeps.current = dependencies
-    }
-
-    //effect invokes the initializer each time dependencies changed
-    useEffect(function () {
-        //check that dependencies really changed
-        if (dependenciesChanged) {
-            //re-initialize state when any of the dependencies changed
-            updateState(typeof stateInitializer === 'function' ? stateInitializer(dependencies, state) : stateInitializer)
-        }
-        return finalizer || undefined
-    }, pinnedDeps.current)
-
-    return [state, function (newState) {
-        //use deep compare - as React used to in good old times
-        updateState(current => {
-            if (typeof newState === 'function') {
-                newState = newState(current)
-            }
-            if (isEqual(current, newState)) return current
-            return newState
-        })
-    }]
-}
-
-/**
- * Simple force update hook.
- * @return {Function}
- */
-export function useForceUpdate() {
-    const [, updateNonce] = useState(0)
-    return function () {
-        updateNonce(nonce => nonce + 1)
-    }
-}
-
-/**
- * React hook that automatically reacts on dependency changes using deep comparison
- * @param {Function} effect
- * @param {Array} dependencies
- */
-export function useDeepEffect(effect, dependencies) {
-    ensureDependencies(dependencies)
-    //pin dependencies object to invoke effect update only if dependencies changed
-    const pinnedDeps = useRef([])
-    //check that dependencies really changed
-    if (!isEqual(dependencies, pinnedDeps.current)) {
-        pinnedDeps.current = dependencies
-    }
-    //effect invokes the initializer each time dependencies changed
-    useEffect(effect, pinnedDeps.current)
+import {useState, useEffect, useRef} from 'react'
+import isEqual from 'react-fast-compare'
+
+function ensureDependencies(dependencies) {
+    if (!(dependencies instanceof Array))
+        throw new Error('Parameter dependencies is required for useDependantState hook')
+}
+
+/**
+ * React hook that automatically re-inits state when one of the dependencies changed
+ * @param {function|any} stateInitializer
+ * @param {Array} dependencies
+ * @param {function} [finalizer]
+ * @returns {[Object, function]}
+ */
+export function useDependantState(stateInitializer, dependencies, finalizer) {
+    //ensureDependencies(dependencies)
+    const [state, updateState] = useState(function () {
+        return typeof stateInitializer === 'function' ? stateInitializer(dependencies) : stateInitializer
+    })
+    //pin dependencies object to invoke effect update only if dependencies changed
+    const pinnedDeps = useRef(dependencies)
+    let dependenciesChanged = !isEqual(dependencies, pinnedDeps.current)
+    //check that dependencies really changed
+    if (dependenciesChanged) {
+        pinnedDeps.current = dependencies
+    }
+
+    //effect invokes the initializer each time dependencies changed
+    useEffect(function () {
+        //check that dependencies really changed
+        if (dependenciesChanged) {
+            //re-initialize state when any of the dependencies changed
+            updateState(typeof stateInitializer === 'function' ? stateInitializer(dependencies, state) : stateInitializer)
+        }
+        return finalizer || undefined
+    }, pinnedDeps.current)
+
+    return [state, function (newState) {
+        //use deep compare - as React used to in good old times
+        updateState(current => {
+            if (typeof newState === 'function') {
+                newState = newState(current)
+            }
+            if (isEqual(current, newState)) return current
+            return newState
+        })
+    }]
+}
+
+/**
+ * Simple force update hook.
+ * @return {function}
+ */
+export function useForceUpdate() {
+    const [, updateNonce] = useState(0)
+    return function () {
+        updateNonce(nonce => nonce + 1)
+    }
+}
+
+/**
+ * React hook that automatically reacts on dependency changes using deep comparison
+ * @param {function} effect
+ * @param {Array} dependencies
+ */
+export function useDeepEffect(effect, dependencies) {
+    ensureDependencies(dependencies)
+    //pin dependencies object to invoke effect update only if dependencies changed
+    const pinnedDeps = useRef([])
+    //check that dependencies really changed
+    if (!isEqual(dependencies, pinnedDeps.current)) {
+        pinnedDeps.current = dependencies
+    }
+    //effect invokes the initializer each time dependencies changed
+    useEffect(effect, pinnedDeps.current)
 }

package/state/stellar-network-hooks.js

@@ -1,45 +1,57 @@
-import {useState, useEffect} from 'react'
-
-const listeners = []
-let currentNetwork = 'public'
-
-setStellarNetwork(currentNetwork)
-
-function removeListener(callback) {
-    const idx = listeners.indexOf(callback)
-    if (~idx) listeners.splice(idx, 1)
-}
-
-export function getCurrentStellarNetwork() {
-    return currentNetwork
-}
-
-/**
- * Set current Stellar network.
- * @param {'testnet'|'public'} network
- */
-export function setStellarNetwork(network) {
-    if (currentNetwork === network) return
-    currentNetwork = network
-    for (const listener of listeners) {
-        listener(network)
-    }
-}
-
-export function subscribeToStellarNetworkChange(onChange) {
-    removeListener(onChange)
-    listeners.push(onChange)
-}
-
-/**
- * React hook for reacting on Stellar network changes.
- * @return {'testnet'|'public'}
- */
-export function useStellarNetwork() {
-    const [state, updateState] = useState(currentNetwork)
-    useEffect(() => {
-        subscribeToStellarNetworkChange(updateState)
-        return () => removeListener(updateState)
-    }, [])
-    return state
+import {useState, useEffect} from 'react'
+
+/**
+ * @typedef {'public'|'testnet'} StellarNetwork
+ */
+
+const listeners = []
+let currentNetwork = 'public'
+
+setStellarNetwork(currentNetwork)
+
+function removeListener(callback) {
+    const idx = listeners.indexOf(callback)
+    if (~idx) listeners.splice(idx, 1)
+}
+
+/**
+ * Get current Stellar network identifier
+ * @return {StellarNetwork}
+ */
+export function getCurrentStellarNetwork() {
+    return currentNetwork
+}
+
+/**
+ * Set current Stellar network
+ * @param {StellarNetwork} network
+ */
+export function setStellarNetwork(network) {
+    if (currentNetwork === network) return
+    currentNetwork = network
+    for (const listener of listeners) {
+        listener(network)
+    }
+}
+
+/**
+ * Subscribe to Stellar network change events
+ * @param {function(StellarNetwork): void} onChange - Callback invoked when the network changes
+ */
+export function subscribeToStellarNetworkChange(onChange) {
+    removeListener(onChange)
+    listeners.push(onChange)
+}
+
+/**
+ * React hook that returns the current Stellar network and re-renders on network changes
+ * @return {StellarNetwork}
+ */
+export function useStellarNetwork() {
+    const [state, updateState] = useState(currentNetwork)
+    useEffect(() => {
+        subscribeToStellarNetworkChange(updateState)
+        return () => removeListener(updateState)
+    }, [])
+    return state
 }

package/state/theme.js

@@ -1,29 +1,30 @@
-import {useState} from 'react'
-
-function setGlobalTheme(theme) {
-    localStorage.setItem('preferred-color-theme', theme)
-    document.documentElement.attributes['data-theme'].value = theme
-}
-
-const preferredTheme = localStorage.getItem('preferred-color-theme')
-if (preferredTheme) {
-    setGlobalTheme(preferredTheme)
-} else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
-    setGlobalTheme('night')
-}
-
-/**
- * @returns {[colorTheme: String, setTheme: Function]}
- */
-export function useTheme() {
-    const [theme, setTheme] = useState(localStorage.getItem('preferred-color-theme') || 'day')
-    return [theme, function (newTheme) {
-        setTheme(current => {
-            if (typeof newTheme === 'function') {
-                newTheme = newTheme(current)
-            }
-            setGlobalTheme(newTheme)
-            return newTheme
-        })
-    }]
+import {useState} from 'react'
+
+function setGlobalTheme(theme) {
+    localStorage.setItem('preferred-color-theme', theme)
+    document.documentElement.attributes['data-theme'].value = theme
+}
+
+const preferredTheme = localStorage.getItem('preferred-color-theme')
+if (preferredTheme) {
+    setGlobalTheme(preferredTheme)
+} else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+    setGlobalTheme('night')
+}
+
+/**
+ * Hook that manages the current color theme (day/night) with localStorage persistence
+ * @returns {[colorTheme: string, setTheme: function]}
+ */
+export function useTheme() {
+    const [theme, setTheme] = useState(localStorage.getItem('preferred-color-theme') || 'day')
+    return [theme, function (newTheme) {
+        setTheme(current => {
+            if (typeof newTheme === 'function') {
+                newTheme = newTheme(current)
+            }
+            setGlobalTheme(newTheme)
+            return newTheme
+        })
+    }]
 }