@stellar-expert/ui-framework 1.16.7 → 1.17.0

package/interaction/accordion.js

@@ -1,36 +1,44 @@
-import React, {useCallback, useEffect, useState} from 'react'
-import cn from 'classnames'
-import './accordion.scss'
-
-/**
- * Group of collapsible panels
- * @param {{key: String, title: String|JSX.Element, content:*}[]} options - Accordion options
- * @param {String} [collapsedSymbol] - Prefix to show for collapsed panels
- * @param {String} [expandedSymbol] - Prefix to show for expanded panel
- */
-export function Accordion({options, collapsedSymbol = '+', expandedSymbol = '-', ...otherProps}) {
-    const [selectedOption, setSelectedOption] = useState()
-    useEffect(() => {
-        const firstOption = options[0]
-        setSelectedOption(firstOption.key || firstOption.title)
-    }, [options])
-    const changeSelected = useCallback(e => setSelectedOption(e.currentTarget.dataset.key), [options])
-    return <div className="accordion" {...otherProps}>
-        {options.map(({key, title, content}) => {
-            const expanded = key ?
-                selectedOption === key :
-                selectedOption === title
-            return <div key={key || title} className={cn('option', {expanded})}>
-                <div className="accordion-header" data-collapsed={collapsedSymbol} data-expanded={expandedSymbol} data-key={key || title}
-                     onClick={changeSelected}>
-                    {title || key}
-                </div>
-                <div className="accordion-collapse">
-                    <div className="accordion-body">
-                        {content}
-                    </div>
-                </div>
-            </div>
-        })}
-    </div>
+import React, {useCallback, useEffect, useState} from 'react'
+import cn from 'classnames'
+import './accordion.scss'
+
+/**
+ * @typedef {Object} AccordionOption
+ * @property {string} [key] - Unique key for the panel (falls back to title)
+ * @property {string|JSX.Element} title - Panel header content
+ * @property {*} content - Panel body content
+ */
+
+/**
+ * Group of collapsible panels where only one panel is expanded at a time
+ * @param {Object} props
+ * @param {AccordionOption[]} props.options - Accordion panel definitions
+ * @param {string} [props.collapsedSymbol='+'] - Prefix shown for collapsed panels
+ * @param {string} [props.expandedSymbol='-'] - Prefix shown for the expanded panel
+ */
+export function Accordion({options, collapsedSymbol = '+', expandedSymbol = '-', ...otherProps}) {
+    const [selectedOption, setSelectedOption] = useState()
+    useEffect(() => {
+        const firstOption = options[0]
+        setSelectedOption(firstOption.key || firstOption.title)
+    }, [options])
+    const changeSelected = useCallback(e => setSelectedOption(e.currentTarget.dataset.key), [options])
+    return <div className="accordion" {...otherProps}>
+        {options.map(({key, title, content}) => {
+            const expanded = key ?
+                selectedOption === key :
+                selectedOption === title
+            return <div key={key || title} className={cn('option', {expanded})}>
+                <div className="accordion-header" data-collapsed={collapsedSymbol} data-expanded={expandedSymbol} data-key={key || title}
+                     onClick={changeSelected}>
+                    {title || key}
+                </div>
+                <div className="accordion-collapse">
+                    <div className="accordion-body">
+                        {content}
+                    </div>
+                </div>
+            </div>
+        })}
+    </div>
 }

package/interaction/autofocus.js

@@ -1,9 +1,13 @@
-export function useAutoFocusRef(inputRef) {
-    if (!inputRef)
-        return
-    setTimeout(() => {
-        if (document.body.contains(inputRef)) {
-            inputRef.focus()
-        }
-    }, 200)
-}
+/**
+ * Auto-focuses the given DOM element after a short delay (ref callback)
+ * @param {HTMLElement} inputRef - DOM element to focus
+ */
+export function useAutoFocusRef(inputRef) {
+    if (!inputRef)
+        return
+    setTimeout(() => {
+        if (document.body.contains(inputRef)) {
+            inputRef.focus()
+        }
+    }, 200)
+}

package/interaction/block-select.js

@@ -1,54 +1,65 @@
-import React from 'react'
-import PropTypes from 'prop-types'
-import cn from 'classnames'
-import './block-select.scss'
-
-function select(target) {
-    //handle textarea and inputs
-    if (target.nodeName.match(/^(INPUT|TEXTAREA)$/i)) {
-        target.focus()
-        target.select()
-        return
-    }
-    //handle selection inside text elements
-    const range = document.createRange()
-    range.selectNodeContents(target)
-    const sel = window.getSelection()
-    if (typeof sel.setBaseAndExtent === 'function') {
-        // Safari
-        sel.setBaseAndExtent(target, 0, target, 1)
-    }
-    sel.removeAllRanges()
-    sel.addRange(range)
-}
-
-export const BlockSelect = React.memo(function BlockSelect({as = 'span', children, title, className, wrap, inline, style, ...op}) {
-    const props = {
-        className: cn('block-select', className),
-        onFocus: e => select(e.target),
-        tabIndex: '-1',
-        style,
-        title,
-        ...op
-    }
-    if (wrap) {
-        props.style = {...props.style, whiteSpace: 'normal', overflow: 'visible'}
-    }
-    if (wrap === false) {
-        props.style = {...props.style, whiteSpace: 'nowrap', overflow: 'hidden'}
-    }
-    if (inline) {
-        props.style = {...props.style, display: 'inline'}
-    }
-    return React.createElement(as, props, children)
-})
-
-BlockSelect.propTypes = {
-    children: PropTypes.any.isRequired,
-    title: PropTypes.string,
-    className: PropTypes.string,
-    style: PropTypes.object,
-    wrap: PropTypes.bool,
-    inline: PropTypes.bool,
-    as: PropTypes.string
+import React from 'react'
+import PropTypes from 'prop-types'
+import cn from 'classnames'
+import './block-select.scss'
+
+function select(target) {
+    //handle textarea and inputs
+    if (target.nodeName.match(/^(INPUT|TEXTAREA)$/i)) {
+        target.focus()
+        target.select()
+        return
+    }
+    //handle selection inside text elements
+    const range = document.createRange()
+    range.selectNodeContents(target)
+    const sel = window.getSelection()
+    if (typeof sel.setBaseAndExtent === 'function') {
+        // Safari
+        sel.setBaseAndExtent(target, 0, target, 1)
+    }
+    sel.removeAllRanges()
+    sel.addRange(range)
+}
+
+/**
+ * Block that selects all its text content on focus/click
+ * @param {Object} props
+ * @param {string} [props.as='span'] - HTML tag to render
+ * @param {*} props.children - Content to display
+ * @param {string} [props.title] - HTML title attribute
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {boolean} [props.wrap] - Enable text wrapping (true) or disable it (false)
+ * @param {boolean} [props.inline] - Force inline display
+ * @param {Object} [props.style] - Inline styles
+ */
+export const BlockSelect = React.memo(function BlockSelect({as = 'span', children, title, className, wrap, inline, style, ...op}) {
+    const props = {
+        className: cn('block-select', className),
+        onFocus: e => select(e.target),
+        tabIndex: '-1',
+        style,
+        title,
+        ...op
+    }
+    if (wrap) {
+        props.style = {...props.style, whiteSpace: 'normal', overflow: 'visible'}
+    }
+    if (wrap === false) {
+        props.style = {...props.style, whiteSpace: 'nowrap', overflow: 'hidden'}
+    }
+    if (inline) {
+        props.style = {...props.style, display: 'inline'}
+    }
+    return React.createElement(as, props, children)
+})
+
+BlockSelect.propTypes = {
+    children: PropTypes.any.isRequired,
+    title: PropTypes.string,
+    className: PropTypes.string,
+    style: PropTypes.object,
+    wrap: PropTypes.bool,
+    inline: PropTypes.bool,
+    as: PropTypes.string
 }

package/interaction/block-select.scss

@@ -1,22 +1,22 @@
-.block-select {
-  display: inline-block;
-  width: auto;
-  overflow: auto;
-  text-overflow: ellipsis;
-  vertical-align: bottom;
-
-  &:focus {
-    outline: none;
-  }
-
-  &textarea {
-    width: 100%;
-    height: 7em;
-    margin: 0;
-    resize: vertical;
-
-    &.code {
-      font-family: $font-face-mono;
-    }
-  }
+.block-select {
+  display: inline-block;
+  width: auto;
+  overflow: auto;
+  text-overflow: ellipsis;
+  vertical-align: bottom;
+
+  &:focus {
+    outline: none;
+  }
+
+  &textarea {
+    width: 100%;
+    height: 7em;
+    margin: 0;
+    resize: vertical;
+
+    &.code {
+      font-family: $font-face-mono;
+    }
+  }
 }

package/interaction/copy-to-clipboard.js

@@ -1,19 +1,26 @@
-import React from 'react'
-import PropTypes from 'prop-types'
-import {CopyToClipboard as Copy} from 'react-copy-to-clipboard'
-
-export const CopyToClipboard = React.memo(function CopyToClipboard({text, children, title}) {
-    return <Copy text={text}>
-        {children ? children : <a href="#" className="icon-copy active-icon" title={title}/>}
-    </Copy>
-})
-
-CopyToClipboard.defaultProps = {
-    title: 'Copy to clipboard'
-}
-
-CopyToClipboard.propTypes = {
-    text: PropTypes.string.isRequired,
-    title: PropTypes.string,
-    children: PropTypes.any
+import React from 'react'
+import PropTypes from 'prop-types'
+import {CopyToClipboard as Copy} from 'react-copy-to-clipboard'
+
+/**
+ * Copy-to-clipboard wrapper; shows a default copy icon if no children are provided
+ * @param {Object} props
+ * @param {string} props.text - Text to copy to clipboard
+ * @param {*} [props.children] - Custom trigger element (defaults to a copy icon)
+ * @param {string} [props.title='Copy to clipboard'] - Tooltip text
+ */
+export const CopyToClipboard = React.memo(function CopyToClipboard({text, children, title}) {
+    return <Copy text={text}>
+        {children ? children : <a href="#" className="icon-copy active-icon" title={title}/>}
+    </Copy>
+})
+
+CopyToClipboard.defaultProps = {
+    title: 'Copy to clipboard'
+}
+
+CopyToClipboard.propTypes = {
+    text: PropTypes.string.isRequired,
+    title: PropTypes.string,
+    children: PropTypes.any
 }

package/interaction/inline-progress.js

@@ -1,16 +1,21 @@
-import React, {useEffect, useRef, useState} from 'react'
-import PropTypes from 'prop-types'
-
-export const InlineProgress = React.memo(function InlineProgress({dots = 5}) {
-    const [progress, setProgress] = useState(0),
-        intervalRef = useRef(0)
-    useEffect(() => {
-        intervalRef.current = setInterval(() => setProgress(p => ++p), 500)
-        return () => clearInterval(intervalRef.current)
-    }, [])
-    return <span>{'.'.repeat(progress % (dots + 1))}</span>
-})
-
-InlineProgress.propTypes = {
-    dots: PropTypes.number
+import React, {useEffect, useRef, useState} from 'react'
+import PropTypes from 'prop-types'
+
+/**
+ * Animated inline progress indicator that cycles through dots
+ * @param {Object} props
+ * @param {number} [props.dots=5] - Maximum number of dots to display
+ */
+export const InlineProgress = React.memo(function InlineProgress({dots = 5}) {
+    const [progress, setProgress] = useState(0),
+        intervalRef = useRef(0)
+    useEffect(() => {
+        intervalRef.current = setInterval(() => setProgress(p => ++p), 500)
+        return () => clearInterval(intervalRef.current)
+    }, [])
+    return <span>{'.'.repeat(progress % (dots + 1))}</span>
+})
+
+InlineProgress.propTypes = {
+    dots: PropTypes.number
 }

package/interaction/qr-code.js

@@ -1,35 +1,35 @@
-import React, {useMemo, useRef} from 'react'
-import {QRCodeCanvas} from 'qrcode.react'
-
-/**
- * QrCode renderer
- * @param {String} value - Value to encode
- * @param {String} [caption] - Additional caption under QR code
- * @param {Number} [size] - Width|height fo the rendered QR code image
- * @param {String} [embeddedImage] - Optional logo to render in the center of QR code
- * @param {Number} [embeddedSize] - Embedded logo size (by default 10% of QR code size)
- * @return {JSX.Element}
- */
-export const QrCode = React.memo(function QrCode({value, caption, size = 320, embeddedImage, embeddedSize}) {
-    const foreground = useMemo(() => getComputedStyle(document.documentElement).getPropertyValue('--color-primary'))
-    const containerRef = useRef()
-    return <div className="text-center" ref={containerRef}>
-        <QRCodeCanvas value={value} size={256} level="Q" includeMargin imageSettings={embedImage(embeddedImage, embeddedSize, size)}
-            fgColor={foreground} style={{width: size + 'px', height: size + 'px', display: 'block', margin: 'auto'}}/>
-        {!!caption && <div className="text-small dimmed condensed word-break">{caption}</div>}
-    </div>
-})
-
-function embedImage(src, size, qrSize) {
-    if (!src)
-        return undefined
-    if (!size) {
-        size = qrSize * 0.1
-    }
-    return {
-        src,
-        height: size,
-        width: size,
-        excavate: true
-    }
+import React, {useMemo, useRef} from 'react'
+import {QRCodeCanvas} from 'qrcode.react'
+
+/**
+ * QrCode renderer
+ * @param {string} value - Value to encode
+ * @param {string} [caption] - Additional caption under QR code
+ * @param {number} [size] - Width|height fo the rendered QR code image
+ * @param {string} [embeddedImage] - Optional logo to render in the center of QR code
+ * @param {number} [embeddedSize] - Embedded logo size (by default 10% of QR code size)
+ * @return {JSX.Element}
+ */
+export const QrCode = React.memo(function QrCode({value, caption, size = 320, embeddedImage, embeddedSize}) {
+    const foreground = useMemo(() => getComputedStyle(document.documentElement).getPropertyValue('--color-primary'))
+    const containerRef = useRef()
+    return <div className="text-center" ref={containerRef}>
+        <QRCodeCanvas value={value} size={256} level="Q" includeMargin imageSettings={embedImage(embeddedImage, embeddedSize, size)}
+            fgColor={foreground} style={{width: size + 'px', height: size + 'px', display: 'block', margin: 'auto'}}/>
+        {!!caption && <div className="text-small dimmed condensed word-break">{caption}</div>}
+    </div>
+})
+
+function embedImage(src, size, qrSize) {
+    if (!src)
+        return undefined
+    if (!size) {
+        size = qrSize * 0.1
+    }
+    return {
+        src,
+        height: size,
+        width: size,
+        excavate: true
+    }
 }

package/interaction/responsive.js

@@ -1,21 +1,21 @@
-import {useState, useEffect} from 'react'
-import {throttle} from 'throttle-debounce'
-
-/**
- * Measures window client width
- * @return {Number}
- */
-export function useWindowWidth() {
-    const [width, setWidth] = useState(window.innerWidth)
-
-    const onResize = throttle(100, function () {
-        setWidth(window.innerWidth)
-    })
-
-    useEffect(() => {
-        window.addEventListener('resize', onResize)
-        return () => window.removeEventListener('resize', onResize)
-    }, [])
-
-    return width
+import {useState, useEffect} from 'react'
+import {throttle} from 'throttle-debounce'
+
+/**
+ * Measures window client width
+ * @return {number}
+ */
+export function useWindowWidth() {
+    const [width, setWidth] = useState(window.innerWidth)
+
+    const onResize = throttle(100, function () {
+        setWidth(window.innerWidth)
+    })
+
+    useEffect(() => {
+        window.addEventListener('resize', onResize)
+        return () => window.removeEventListener('resize', onResize)
+    }, [])
+
+    return width
 }

package/interaction/spoiler.js

@@ -1,40 +1,53 @@
-import React, {useCallback, useEffect, useState} from 'react'
-import PropTypes from 'prop-types'
-import cn from 'classnames'
-import './spoiler.scss'
-
-export const Spoiler = React.memo(function Spoiler({expanded, showMore = 'Show more', showLess = 'Show less', onChange, className, micro, style, active, children}) {
-    const [expandedState, setExpandedState] = useState(expanded || false)
-    useEffect(() => {
-        setExpandedState(expanded)
-    }, [expanded])
-
-    const toggle = useCallback(() => {
-        setExpandedState(prevState => {
-            const newState = !prevState
-            setExpandedState(newState)
-            onChange && onChange({expanded: newState})
-        })
-    }, [onChange])
-
-    const text = expandedState ? showLess : showMore
-    return <>
-        <span className={cn('spoiler', className)}>
-            <a href="#" className={!active ? 'dimmed' : undefined} title={micro ? text : undefined} style={style} onClick={toggle}>
-                {!micro && <span className="spoiler-text">{text}</span>}
-                <i className={`icon ${expandedState ? 'icon-less' : 'icon-more'}`}/>
-            </a>
-        </span>
-        {expandedState ? children : null}
-    </>
-})
-
-Spoiler.propTypes = {
-    expanded: PropTypes.bool,
-    micro: PropTypes.bool,
-    onChange: PropTypes.func,
-    showMore: PropTypes.string,
-    showLess: PropTypes.string,
-    active: PropTypes.bool,
-    style: PropTypes.object
+import React, {useCallback, useEffect, useState} from 'react'
+import PropTypes from 'prop-types'
+import cn from 'classnames'
+import './spoiler.scss'
+
+/**
+ * Expandable/collapsible content toggle
+ * @param {Object} props
+ * @param {boolean} [props.expanded] - Whether the content is initially expanded
+ * @param {string} [props.showMore='Show more'] - Label for the expand action
+ * @param {string} [props.showLess='Show less'] - Label for the collapse action
+ * @param {function({expanded: boolean}): void} [props.onChange] - Callback invoked on toggle
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {boolean} [props.micro] - Show only an icon without text label
+ * @param {Object} [props.style] - Inline styles
+ * @param {boolean} [props.active] - Highlight the toggle link
+ * @param {*} [props.children] - Content revealed when expanded
+ */
+export const Spoiler = React.memo(function Spoiler({expanded, showMore = 'Show more', showLess = 'Show less', onChange, className, micro, style, active, children}) {
+    const [expandedState, setExpandedState] = useState(expanded || false)
+    useEffect(() => {
+        setExpandedState(expanded)
+    }, [expanded])
+
+    const toggle = useCallback(() => {
+        setExpandedState(prevState => {
+            const newState = !prevState
+            setExpandedState(newState)
+            onChange && onChange({expanded: newState})
+        })
+    }, [onChange])
+
+    const text = expandedState ? showLess : showMore
+    return <>
+        <span className={cn('spoiler', className)}>
+            <a href="#" className={!active ? 'dimmed' : undefined} title={micro ? text : undefined} style={style} onClick={toggle}>
+                {!micro && <span className="spoiler-text">{text}</span>}
+                <i className={`icon ${expandedState ? 'icon-less' : 'icon-more'}`}/>
+            </a>
+        </span>
+        {expandedState ? children : null}
+    </>
+})
+
+Spoiler.propTypes = {
+    expanded: PropTypes.bool,
+    micro: PropTypes.bool,
+    onChange: PropTypes.func,
+    showMore: PropTypes.string,
+    showLess: PropTypes.string,
+    active: PropTypes.bool,
+    style: PropTypes.object
 }

package/interaction/spoiler.scss

@@ -1,7 +1,7 @@
-.spoiler {
-  padding: 0.3em 0;
-
-  .spoiler-text {
-    border-bottom: 1px dotted;
-  }
+.spoiler {
+  padding: 0.3em 0;
+
+  .spoiler-text {
+    border-bottom: 1px dotted;
+  }
 }

package/interaction/theme-selector.js

@@ -1,11 +1,14 @@
-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>
+import React from 'react'
+import {useTheme} from '../state/theme'
+
+/**
+ * Theme toggle button that switches between day (light) and night (dark) themes
+ */
+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

@@ -1,10 +1,11 @@
 import {getCurrentStellarNetwork} from '../state/stellar-network-hooks'
 
 /**
+ * Build URL path to StellarExpert explorer page for given ledger entry
  * @param {'account'|'asset'|'ledger'|'tx'|'op'|'offer'|'contract'|'liquidity-pool'|'claimable-balance'} type
- * @param {String|Number} id
- * @param {String} [network]
- * @return {String}
+ * @param {string|number} id
+ * @param {string} [network]
+ * @return {string}
  */
 export function formatExplorerLink(type, id, network = null) {
     if (typeof window.explorerLinkFormatter === 'function') {