@stellar-expert/ui-framework 1.9.0

package/interaction/spoiler.scss

@@ -0,0 +1,9 @@
+@use "../basic-styles/variables";
+
+.spoiler {
+  padding: 0.3em 0;
+
+  .spoiler-text {
+    border-bottom: 1px dotted;
+  }
+}

package/interaction/theme-selector.js

@@ -0,0 +1,11 @@
+import React from 'react'
+import {useTheme} from '../state/theme'
+
+export const ThemeSelector = React.memo(function ThemeSelector() {
+    const [theme, setTheme] = useTheme()
+    return <a href="#" onClick={() => setTheme(current => current === 'day' ? 'night' : 'day')}>
+        {theme === 'day' ?
+            <><i className="icon icon-night"/> Dark theme</> :
+            <><i className="icon icon-day"/> Light theme</>}
+    </a>
+})

package/ledger/ledger-entry-href-formatter.js

@@ -0,0 +1,22 @@
+import {getCurrentStellarNetwork} from '../state/stellar-network-hooks'
+
+/**
+ * @param {'account'|'asset'|'ledger'|'tx'|'op'|'offer'} type
+ * @param {String|Number} id
+ * @param {String} network?
+ * @return {String}
+ */
+export function formatExplorerLink(type, id, network = null) {
+    const segments = [
+        explorerFrontendOrigin !== window.origin ? explorerFrontendOrigin : '',
+        'explorer',
+        network || getCurrentStellarNetwork()
+    ]
+    if (type) {
+        segments.push(type)
+    }
+    if (id) {
+        segments.push(id)
+    }
+    return segments.join('/')
+}

package/ledger/ledger-entry-link.js

@@ -0,0 +1,59 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import {formatExplorerLink} from './ledger-entry-href-formatter'
+import {useStellarNetwork} from '../state/stellar-network-hooks'
+
+function LedgerEntryLink({type, id, network, children}) {
+    const globallySetNetwork = useStellarNetwork()
+    return <a href={formatExplorerLink(type, id, network || globallySetNetwork)} target="_blank">{children || id}</a>
+}
+
+export const TxLink = React.memo(function TxLink({tx, network, children}) {
+    return React.createElement(LedgerEntryLink, {type: 'tx', id: tx, network, children})
+})
+
+TxLink.propTypes = {
+    tx: PropTypes.string.isRequired,
+    network: PropTypes.string,
+    children: PropTypes.any
+}
+
+export const OpLink = React.memo(function OpLink({op, network, children}) {
+    return React.createElement(LedgerEntryLink, {type: 'op', id: op, network, children})
+})
+
+OpLink.propTypes = {
+    op: PropTypes.string.isRequired,
+    network: PropTypes.string,
+    children: PropTypes.any
+}
+
+export const LedgerLink = React.memo(function LedgerLink({sequence, network, children}) {
+    return React.createElement(LedgerEntryLink, {type: 'ledger', id: sequence, network, children})
+})
+
+LedgerLink.propTypes = {
+    sequence: PropTypes.number.isRequired,
+    network: PropTypes.string,
+    children: PropTypes.any
+}
+
+export const OfferLink = React.memo(function OfferLink({offer, network, children}) {
+    return React.createElement(LedgerEntryLink, {type: 'offer', id: offer, network, children})
+})
+
+OfferLink.propTypes = {
+    offer: PropTypes.string.isRequired,
+    network: PropTypes.string,
+    children: PropTypes.any
+}
+
+export const PoolLink = React.memo(function PoolLink({pool, network, children}) {
+    return React.createElement(LedgerEntryLink, {type: 'pool', id: pool, network, children})
+})
+
+PoolLink.propTypes = {
+    pool: PropTypes.string.isRequired,
+    network: PropTypes.string,
+    children: PropTypes.any
+}

package/meta/page-meta-tags.js

@@ -0,0 +1,229 @@
+import {useEffect} from 'react'
+import isEqual from 'react-fast-compare'
+
+const {origin} = window.location
+const domain = origin.replace(/https?:\/\//, '')
+
+const metaProps = {
+    serviceTitle: '',
+    description: '',
+    facebookImage: '',
+    twitterImage: '',
+    twitterUsername: ''
+}
+
+/**
+ * Initialize default meta properties for the application
+ * @param {{serviceTitle: String, description: String, facebookImage: String, twitterImage: String, twitterUsername: String}} appMetaProps
+ */
+export function initMeta(appMetaProps) {
+    Object.assign(metaProps, appMetaProps)
+}
+
+function formatPageTitle(title) {
+    if (!title)
+        return metaProps.serviceTitle
+    if (title.includes(metaProps.serviceTitle))
+        return title
+    return `${title} ${metaProps.serviceTitle}`
+}
+
+function generateCanonicalLink(params, canonicalUrl) {
+    return {
+        tag: 'link',
+        locator: 'rel',
+        tags: [
+            {name: 'canonical', content: canonicalUrl, attribute: 'href'}
+        ]
+    }
+}
+
+function generateDescriptionMeta({description}) {
+    return {
+        locator: 'name',
+        tags: [
+            {name: 'description', content: description || metaProps.description}
+        ]
+    }
+}
+
+function generateTwitterMeta({description, title, twitterImage}) {
+    return {
+        locator: 'name',
+        tags: [
+            {name: 'twitter:card', content: 'summary_large_image'},
+            {name: 'twitter:site', content: metaProps.twitterUsername},
+            {name: 'twitter:title', content: formatPageTitle(title)},
+            {name: 'twitter:description', content: description || metaProps.description},
+            {name: 'twitter:image:src', content: twitterImage || metaProps.twitterImage}
+        ]
+    }
+}
+
+function generateOpenGraphMeta({description, title, facebookImage}, canonicalUrl) {
+    let tags = [
+        {name: 'og:title', content: formatPageTitle(title)},
+        {name: 'og:url', content: canonicalUrl},
+        {name: 'og:site_name', content: formatPageTitle(metaProps.serviceTitle)},
+        {name: 'og:description', content: description || metaProps.description},
+        {name: 'og:type', content: 'website'}
+    ]
+    if (facebookImage) {
+        tags.push({name: 'og:image', content: facebookImage})
+    } else {
+        tags.push({name: 'og:image', content: metaProps.facebookImage})
+        /*tags = tags.concat([
+            {name: 'og:image', content: metaProps.facebookImage},
+            {name: 'og:image:width', content: 1200},
+            {name: 'og:image:height', content: 630}])*/
+    }
+    return {
+        locator: 'property',
+        tags
+    }
+}
+
+function generateItemPropSchema({description, title, image}) {
+    return {
+        locator: 'itemprop',
+        tags: [
+            {name: 'name', content: title},
+            {name: 'description', content: description || metaProps.description},
+            {name: 'image', content: image || metaProps.facebookImage}
+        ]
+    }
+}
+
+function generateLdJsonSchema({title}) {
+    return {
+        tag: 'script',
+        locator: 'type',
+        tags: [
+            {
+                name: 'application/ld+json',
+                content: JSON.stringify({
+                    '@context': 'http://schema.org',
+                    '@type': 'WebSite',
+                    'name': domain,
+                    'alternateName': title,
+                    'url': origin
+                })
+            }
+        ]
+    }
+}
+
+/**
+ * @param {MetaTagReplacement} replacement
+ */
+function replaceMetaTags(replacement) {
+    const {tag, tags, locator} = replacement
+    const selector = tag || 'meta'
+    tags.forEach(tagSettings => {
+        let tag = document.querySelector(`${selector}[${locator}="${tagSettings.name}"]`)
+        if (!tag) {
+            tag = createTag(selector)
+            tag.setAttribute(locator, tagSettings.name)
+        }
+        if (selector === 'meta') {
+            tag.content = tagSettings.content
+        } else if (tagSettings.attribute) {
+            tag[tagSettings.attribute] = tagSettings.content
+        } else {
+            tag.innerText = tagSettings.content
+        }
+    })
+}
+
+function createTag(tagName, props) {
+    let tag = document.createElement(tagName)
+    for (let key in props) {
+        tag[key] = props[key]
+    }
+    document.head.appendChild(tag)
+    return tag
+}
+
+function removeTag(selector) {
+    let tag = document.querySelector(selector)
+    if (tag) {
+        tag.parentElement.removeChild(tag)
+    }
+}
+
+let pageMeta = {}
+
+const tagReplacerPipeline = [generateCanonicalLink, generateDescriptionMeta, generateOpenGraphMeta, generateTwitterMeta, generateLdJsonSchema] // generateItemPropSchema
+
+/**
+ * Update page metadata tags
+ * @param {PageMeta} meta - Page metadata
+ */
+export function setPageMetadata(meta) {
+    if (isEqual(pageMeta, meta))
+        return
+    const canonicalUrl = origin + location.pathname// + location.search
+    document.title = formatPageTitle(meta.title)
+    for (const replacer of tagReplacerPipeline) {
+        replaceMetaTags(replacer(meta, canonicalUrl))
+    }
+    if (meta.customMeta) {
+        replaceMetaTags(meta.customMeta)
+    }
+    pageMeta = meta
+}
+
+/**
+ * Reset page metadata tags to their default values
+ * @param {PageMeta} meta - Page metadata
+ */
+export function resetPageMetadata(meta) {
+    setPageMetadata({
+        title: metaProps.serviceTitle,
+        description: metaProps.description,
+        twitterImage: metaProps.twitterImage,
+        facebookImage: metaProps.facebookImage
+    })
+    //TODO: add logic to cleanup custom page meta tags on page unload
+}
+
+/*export function setPageNoIndex(noIndex) {
+    if (!noIndex) {
+        removeTag('meta[name=robots]')
+    } else {
+        replaceMetaTags({
+            locator: 'name',
+            tags: [
+                {name: 'robots', content: 'noindex,nofollow'}
+            ]
+        })
+    }
+}*/
+
+/**
+ * React hook for setting page metadata
+ * @param {PageMeta} meta - Page metadata
+ * @param {*[]} dependencies
+ */
+export function usePageMetadata(meta, dependencies = []) {
+    useEffect(() => {
+        setPageMetadata(meta)
+        return () => resetPageMetadata(meta)
+    }, [JSON.stringify(meta), ...dependencies])
+}
+
+/**
+ * @typedef {Object} PageMeta
+ * @property {String} title - Page title
+ * @property {String} description - Contents description
+ * @property {String} [twitterImage] - Twitter image url
+ * @property {String} [facebookImage] - Facebook image url
+ * @property {MetaTagReplacement} [customMeta] - Custom metadata tags
+ */
+
+/**
+ * @typedef {Object} MetaTagReplacement
+ * @property {String} [tag] - Tag name to search for ("meta" by default)
+ * @property {String} locator - Tag attribute to match
+ * @property {{name: String, content: String, [attribute]: String}[]} tags - Tag properties to set
+ */

package/module/dynamic-module.js

@@ -0,0 +1,48 @@
+import React, {useEffect, useState} from 'react'
+import PropTypes from 'prop-types'
+import {withErrorBoundary} from '../errors/error-boundary'
+
+const loadedModules = new Map()
+
+export const DynamicModule = withErrorBoundary(
+    /**
+     * Dynamically loadable module
+     * @param {Function} load - Dynamic load function, e.g. ()=>import('./dynamic_module_import')
+     * @param {String} module - Module unique name for aching purpose
+     * @param {*} [otherProps]
+     * @constructor
+     */
+    function DynamicModule({load, module, ...otherProps}) {
+        const [error, setError] = useState(undefined)
+        const key = module || load
+
+        useEffect(() => {
+            if (loadedModules.get(key))
+                return //skip if module is already loaded
+            load()
+                .then(dynamicModule => {
+                    //use default export for ES modules or top-level export for CJS
+                    if (dynamicModule.__esModule) {
+                        dynamicModule = dynamicModule.default
+                    }
+                    //add to cache
+                    loadedModules.set(key, dynamicModule)
+                    setError(null)
+                })
+                .catch(error => {
+                    error.message = 'Failed to load module. ' + error.message
+                    setError(error)
+                })
+        }, [module || load])
+        if (error)
+            throw error
+        const resolvedModule = loadedModules.get(key)
+        if (!resolvedModule)
+            return <div className="loader"/>
+        return React.createElement(resolvedModule, otherProps)
+    })
+
+DynamicModule.propTypes = {
+    load: PropTypes.func.isRequired,
+    module: PropTypes.string
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@stellar-expert/ui-framework",
+  "version": "1.9.0",
+  "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": "^10.0.1",
+    "@stellar/stellar-sdk": "^11.1.0",
+    "@stellar-expert/asset-descriptor": "^1.3.0",
+    "@stellar-expert/claimable-balance-utils": "^1.4.1",
+    "@stellar-expert/client-cache": "github:stellar-expert/client-cache",
+    "@stellar-expert/formatter": "^2.3.0",
+    "@stellar-expert/navigation": "github:stellar-expert/navigation#v1.0.2",
+    "@stellar-expert/tx-meta-effects-parser": "5.0.0-beta10",
+    "classnames": ">=2",
+    "prop-types": ">=15",
+    "qrcode.react": "^3.1.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-datetime-picker": "5.5.2",
+    "react-day-picker": "8.8.2",
+    "react-copy-to-clipboard": "^5.1.0",
+    "react-timeago": "^7.1.0"
+  }
+}

package/state/on-screen-hooks.js

@@ -0,0 +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
+}

package/state/page-visibility-helpers.js

@@ -0,0 +1,17 @@
+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)
+    }
+}

package/state/page-visibility-hooks.js

@@ -0,0 +1,12 @@
+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
+}

package/state/screen-orientation-hooks.js

@@ -0,0 +1,16 @@
+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
+}

package/state/state-hooks.js

@@ -0,0 +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)
+}

package/state/stellar-network-hooks.js

@@ -0,0 +1,45 @@
+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
+}

package/state/theme.js

@@ -0,0 +1,29 @@
+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
+        })
+    }]
+}