@stellar-expert/ui-framework 1.16.8 → 1.19.0

package/package.json

@@ -1,40 +1,71 @@
-{
-  "name": "@stellar-expert/ui-framework",
-  "version": "1.16.8",
-  "description": "StellarExpert shared UI components library",
-  "main": "index.js",
-  "module": "./index.js",
-  "sideEffects": [
-    "*.scss"
-  ],
-  "keywords": [
-    "StellarExpert",
-    "UI"
-  ],
-  "author": "orbitlens <orbit@stellar.expert>",
-  "license": "MIT",
-  "peerDependencies": {
-    "@stellar/stellar-base": "^14.0.0",
-    "@stellar/stellar-sdk": "^14.0.0",
-    "@stellar-expert/asset-descriptor": "^1.5.0",
-    "@stellar-expert/claimable-balance-utils": "^1.4.1",
-    "@stellar-expert/client-cache": "^1.1.0",
-    "@stellar-expert/contract-wasm-interface-parser": "^3.2.0",
-    "@stellar-expert/formatter": "^3.0.0",
-    "@stellar-expert/navigation": "^1.1.0",
-    "@stellar-expert/tx-meta-effects-parser": "^8.3.3",
-    "classnames": ">=2",
-    "prop-types": ">=15",
-    "qrcode.react": "^4.2.0",
-    "react": ">=17",
-    "react-dom": ">=17",
-    "react-fast-compare": ">=3",
-    "throttle-debounce": ">=5.0.0"
-  },
-  "dependencies": {
-    "highlight.js": "^11.8.0",
-    "history": "^4.10.1",
-    "react-copy-to-clipboard": "^5.1.0",
-    "react-timeago": "^7.2.0"
-  }
-}
+{
+  "name": "@stellar-expert/ui-framework",
+  "version": "1.19.0",
+  "description": "StellarExpert shared UI components library",
+  "main": "index.js",
+  "module": "./index.js",
+  "types": "index.d.ts",
+  "sideEffects": [
+    "*.scss"
+  ],
+  "keywords": [
+    "StellarExpert",
+    "UI"
+  ],
+  "author": "orbitlens <orbit@stellar.expert>",
+  "license": "MIT",
+  "peerDependencies": {
+    "@stellar/stellar-base": "^15.0.0",
+    "@stellar/stellar-sdk": "^15.0.1",
+    "@stellar-expert/asset-descriptor": "^1.5.0",
+    "@stellar-expert/claimable-balance-utils": "^1.4.1",
+    "@stellar-expert/client-cache": "^1.1.0",
+    "@stellar-expert/contract-wasm-interface-parser": "^4.0.0",
+    "@stellar-expert/formatter": "^3.0.0",
+    "@stellar-expert/navigation": "^1.1.0",
+    "@stellar-expert/tx-meta-effects-parser": "^8.3.3",
+    "classnames": ">=2",
+    "deepmerge": "^4.3.1",
+    "prop-types": ">=15",
+    "qrcode.react": "^4.2.0",
+    "react": ">=17 <18.0.0",
+    "react-dom": ">=17 <18.0.0",
+    "react-fast-compare": ">=3",
+    "throttle-debounce": ">=5.0.0"
+  },
+  "dependencies": {
+    "highlight.js": "^11.8.0",
+    "history": "^4.10.1",
+    "react-copy-to-clipboard": "^5.1.0",
+    "react-timeago": "^7.2.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "index.scss",
+    ".npmrc",
+    "account/*",
+    "api/*",
+    "asset/*",
+    "basic-styles/*",
+    "claimable-balance/*",
+    "contract/*",
+    "controls/*",
+    "date/*",
+    "dex/*",
+    "directory/*",
+    "effect/*",
+    "errors/*",
+    "filter/*",
+    "fonts/*",
+    "horizon/*",
+    "interaction/*",
+    "ledger/*",
+    "meta/*",
+    "module/*",
+    "state/*",
+    "stellar/*",
+    "toast/*",
+    "tx/*"
+  ]
+}

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
+        })
+    }]
 }