@xyo-network/xl1-react-transaction 1.16.23

package/package.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "http://json.schemastore.org/package.json",
+  "name": "@xyo-network/xl1-react-transaction",
+  "version": "1.16.23",
+  "description": "XYO Layer One API",
+  "homepage": "https://xylabs.com",
+  "bugs": {
+    "url": "git+https://github.com/xylabs/xyo-chain/issues",
+    "email": "support@xylabs.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xylabs/xyo-chain.git"
+  },
+  "license": "LGPL-3.0-only",
+  "author": {
+    "name": "XY Labs Development Team",
+    "email": "support@xylabs.com",
+    "url": "https://xylabs.com"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/browser/index.d.ts",
+        "source": "./src/index.ts",
+        "default": "./dist/browser/index.mjs"
+      },
+      "types": "./dist/browser/index.d.ts",
+      "source": "./src/index.ts",
+      "default": "./dist/browser/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "module": "./dist/browser/index.mjs",
+  "source": "./src/index.ts",
+  "types": "./dist/browser/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!**/*.bench.*",
+    "!**/*.spec.*",
+    "!**/*.test.*"
+  ],
+  "dependencies": {
+    "@mui/icons-material": "~7.3.5",
+    "@mui/material": "~7.3.5",
+    "@xylabs/sdk-js": "~5.0.39",
+    "@xyo-network/xl1-protocol": "~1.13.13"
+  },
+  "devDependencies": {
+    "@emotion/react": "~11.14.0",
+    "@emotion/styled": "~11.14.1",
+    "@storybook/react-vite": "~10.0.8",
+    "@types/react": "~19.2.6",
+    "@xylabs/ts-scripts-yarn3": "~7.2.8",
+    "@xylabs/tsconfig": "~7.2.8",
+    "@xylabs/tsconfig-dom": "~7.2.8",
+    "@xylabs/tsconfig-react": "~7.2.8",
+    "typescript": "~5.9.3"
+  },
+  "peerDependencies": {
+    "react": "~19.1.1"
+  },
+  "packageManager": "yarn@4.6.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "volta": {
+    "node": "22.5.1",
+    "yarn": "4.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/confirmation/components/TransactionStackProgress.stories.tsx

@@ -0,0 +1,56 @@
+import type { StoryFn } from '@storybook/react-vite'
+import { isUndefined } from '@xylabs/sdk-js'
+import { asBlockRange } from '@xyo-network/xl1-protocol'
+import React, { useEffect, useState } from 'react'
+
+import { TransactionStackProgress } from './TransactionStackProgress.tsx'
+
+export default {
+  title: 'transaction/stack/progress',
+  component: TransactionStackProgress,
+}
+
+const START_BLOCK = 100_001
+const END_BLOCK = 100_010
+
+const Template: StoryFn<typeof TransactionStackProgress> = args => <TransactionStackProgress {...args} />
+const TemplateWithChangingValues: StoryFn<typeof TransactionStackProgress> = (args) => {
+  const [currentBlockNumber, setCurrentBlockNumber] = useState<number>()
+  useEffect(() => {
+    const interval = setInterval(() => {
+      setCurrentBlockNumber((prev) => {
+        if (isUndefined(prev)) {
+          return START_BLOCK
+        }
+        if (prev >= END_BLOCK + 2) {
+          return START_BLOCK
+        }
+        return prev + 1
+      })
+    }, 1000)
+    return () => clearInterval(interval)
+  }, [])
+  return <TransactionStackProgress currentBlockNumber={currentBlockNumber} {...args} />
+}
+
+const Default = Template.bind({})
+Default.args = {}
+
+const WithValues = Template.bind({})
+WithValues.args = { currentBlockNumber: 100_003, blockRange: asBlockRange([START_BLOCK, END_BLOCK]) }
+
+const WithConfirmed = Template.bind({})
+WithConfirmed.args = {
+  currentBlockNumber: 100_004, blockRange: asBlockRange([START_BLOCK, END_BLOCK]), confirmedInBlock: 100_004,
+}
+
+const WithExpired = Template.bind({})
+WithExpired.args = { currentBlockNumber: END_BLOCK + 2, blockRange: asBlockRange([START_BLOCK, END_BLOCK]) }
+
+const WithChangingValues = TemplateWithChangingValues.bind({})
+WithChangingValues.args = { blockRange: asBlockRange([START_BLOCK, END_BLOCK]) }
+
+export {
+  Default, WithChangingValues, WithConfirmed, WithExpired,
+  WithValues,
+}

package/src/confirmation/components/TransactionStackProgress.tsx

@@ -0,0 +1,83 @@
+import type { StackProps } from '@mui/material'
+import { LinearProgress, Stack } from '@mui/material'
+import { isDefined } from '@xylabs/sdk-js'
+import { type BlockRange } from '@xyo-network/xl1-protocol'
+import React, {
+  useLayoutEffect,
+  useMemo,
+  useRef, useState,
+} from 'react'
+
+import { BlockFormatters, getBlockProgress } from '../helpers/index.ts'
+import { useBlockRangeState } from '../hooks/index.ts'
+import { BlockConfirmationStats, BlockRangeEntryStack } from './support/index.ts'
+
+export interface TransactionStackProgressProps extends StackProps {
+  blockRange?: BlockRange
+  confirmedInBlock?: number
+  currentBlockNumber?: number
+}
+
+export const TransactionStackProgress: React.FC<TransactionStackProgressProps> = ({
+  blockRange, confirmedInBlock, currentBlockNumber, ...props
+}) => {
+  const blockPositionRefs = useRef<{ [blockNumber: number]: HTMLSpanElement | null }>({})
+  const progressElementRef = useRef<HTMLDivElement | null>(null)
+
+  const {
+    passedBlocks, progressColor, range, isConfirmed, isExpired,
+  } = useBlockRangeState(blockRange, confirmedInBlock, currentBlockNumber)
+
+  const blockFormatters = useMemo(() => new BlockFormatters({ confirmedInBlock, currentBlockNumber }), [confirmedInBlock, currentBlockNumber])
+
+  const [progressValue, setProgressValue] = useState(0)
+
+  useLayoutEffect(() => {
+    // prevent updates if the current block is past the confirmed block
+    if (isDefined(currentBlockNumber) && isDefined(confirmedInBlock) && currentBlockNumber > confirmedInBlock) {
+      return
+    }
+    const currentBlockNumberElement = isDefined(currentBlockNumber) ? blockPositionRefs.current[currentBlockNumber] : null
+    const progressElement = progressElementRef.current
+    // since we are relying on htmlElements, we have to use layout effect
+    // eslint-disable-next-line react-hooks-extra/no-direct-set-state-in-use-effect
+    setProgressValue(getBlockProgress(
+      currentBlockNumber,
+      currentBlockNumberElement,
+      progressElement,
+    ))
+  }, [currentBlockNumber])
+
+  return (
+    <Stack direction="row" {...props}>
+      <Stack width="100%" gap={1}>
+        <Stack>
+          <LinearProgress ref={progressElementRef} variant="determinate" value={isExpired ? 100 : progressValue} color={progressColor} />
+          <Stack direction="row" justifyContent="space-between">
+            {range.map((block) => {
+              const blockColor = blockFormatters.color(block)
+              const blockStatus = blockFormatters.confirmationStatus(block)
+              const formattedBlockNumber = blockFormatters.formatNumber(block)
+              return (
+                <BlockRangeEntryStack
+                  key={block}
+                  blockPositionRefs={blockPositionRefs}
+                  block={block}
+                  blockColor={blockColor}
+                  blockStatus={blockStatus}
+                  formattedBlockNumber={formattedBlockNumber}
+                />
+              )
+            })}
+          </Stack>
+        </Stack>
+        <BlockConfirmationStats
+          confirmed={isConfirmed}
+          currentBlockColor={isDefined(currentBlockNumber) ? blockFormatters.color(currentBlockNumber) : 'text.secondary'}
+          currentBlockNumberValue={isDefined(currentBlockNumber) ? new Intl.NumberFormat().format(currentBlockNumber) : 'N/A'}
+          passedBlocks={passedBlocks}
+        />
+      </Stack>
+    </Stack>
+  )
+}

package/src/confirmation/components/index.ts

@@ -0,0 +1 @@
+export * from './TransactionStackProgress.tsx'

package/src/confirmation/components/support/BlockConfirmationStats.tsx

@@ -0,0 +1,43 @@
+import { CheckCircleOutline } from '@mui/icons-material'
+import {
+  Grow, Stack, Typography,
+} from '@mui/material'
+import { isDefined } from '@xylabs/sdk-js'
+import React from 'react'
+
+export interface BlockConfirmationStatsProps {
+  confirmed?: boolean
+  currentBlockColor?: string
+  currentBlockNumberValue?: string
+  passedBlocks?: number[]
+}
+
+export const BlockConfirmationStats: React.FC<BlockConfirmationStatsProps> = ({
+  confirmed, currentBlockColor, currentBlockNumberValue, passedBlocks,
+}) => {
+  return (
+    <Stack>
+      <Typography
+        variant="caption"
+        color={currentBlockColor}
+        sx={{
+          display: 'inline-flex', alignItems: 'center', gap: 0.5,
+        }}
+      >
+        Current Block:
+        {' '}
+        {currentBlockNumberValue}
+        {' '}
+        <Grow in={confirmed}>
+          <CheckCircleOutline sx={{ width: '0.8em', height: '0.8em' }} color="success" />
+        </Grow>
+      </Typography>
+      <Typography variant="caption" color="warning.light" sx={{ opacity: 0.75 }}>
+        Passed Blocks:
+        {' '}
+        {isDefined(passedBlocks) && passedBlocks.length > 0 ? passedBlocks.map(block => new Intl.NumberFormat().format(block)).join(', ') : 'N/A'}
+      </Typography>
+
+    </Stack>
+  )
+}

package/src/confirmation/components/support/BlockRangeEntryStack.tsx

@@ -0,0 +1,64 @@
+import type { BoxProps, StackProps } from '@mui/material'
+import {
+  Box, Stack, styled, Tooltip, Typography,
+} from '@mui/material'
+import React from 'react'
+
+import type { BlockConfirmationStatus } from '../../helpers/index.ts'
+
+export interface BlockRangeEntryStackProps extends StackProps {
+  block: number
+  blockColor: string
+  blockPositionRefs: React.RefObject<{ [blockNumber: number]: HTMLSpanElement | null }>
+  blockStatus: BlockConfirmationStatus | undefined
+  formattedBlockNumber: string
+}
+
+export const BlockRangeEntryStack: React.FC<BlockRangeEntryStackProps> = ({
+  blockPositionRefs, block, blockColor, blockStatus, formattedBlockNumber, sx, ...props
+}) => {
+  return (
+    <Stack
+      ref={(ref) => { blockPositionRefs.current[block] = ref }}
+      key={block}
+      sx={{ position: 'relative', ...sx }}
+      {...props}
+    >
+      <Box
+        component="span"
+        sx={{
+          display: 'flex', position: 'relative', width: '100%', height: 5,
+        }}
+      >
+        <StyledBlockNumberIndicator component="span" sx={{ backgroundColor: blockColor }} />
+      </Box>
+      <Tooltip
+        title={`Block: ${new Intl.NumberFormat().format(block)} (${blockStatus})`}
+        placement="top"
+        arrow
+      >
+        <Typography
+          variant="caption"
+          sx={{
+            color: blockColor,
+            cursor: 'pointer',
+            opacity: blockStatus === 'missed' ? 0.75 : 1,
+          }}
+        >
+          {formattedBlockNumber}
+        </Typography>
+      </Tooltip>
+    </Stack>
+  )
+}
+
+export const StyledBlockNumberIndicator = styled(Box, { name: 'StyledBlockNumberIndicator' })<BoxProps>(({ theme }) => {
+  return theme.unstable_sx({
+    position: 'absolute',
+    left: 'calc(50% - 1px)',
+    transform: 'calc(translateX(-50%) - 1px)',
+    height: 3,
+    width: '1px',
+    backgroundColor: 'primary.main',
+  })
+})

package/src/confirmation/components/support/index.ts

@@ -0,0 +1,2 @@
+export * from './BlockConfirmationStats.tsx'
+export * from './BlockRangeEntryStack.tsx'

package/src/confirmation/helpers/BlockFormatters.ts

@@ -0,0 +1,52 @@
+import { isDefined } from '@xylabs/sdk-js'
+
+export type BlockConfirmationStatus = 'confirmed' | 'missed' | 'pending'
+
+type BlockFormattersParams = {
+  confirmedInBlock: number | undefined
+  currentBlockNumber: number | undefined
+}
+
+export class BlockFormatters {
+  private readonly params: BlockFormattersParams
+
+  constructor(params: BlockFormattersParams) {
+    this.params = params
+  }
+
+  color(blockNumber: number): string {
+    const { currentBlockNumber, confirmedInBlock } = this.params
+    if (blockNumber === currentBlockNumber) {
+      return isDefined(confirmedInBlock) && confirmedInBlock === blockNumber ? 'success.dark' : 'text'
+    }
+    const status = this.confirmationStatus(blockNumber)
+    switch (status) {
+      case 'confirmed': {
+        return 'success.dark'
+      }
+      case 'missed': {
+        return 'warning.light'
+      }
+      case 'pending': {
+        return 'text.secondary'
+      }
+      default: {
+        return 'text.secondary'
+      }
+    }
+  }
+
+  confirmationStatus(blockNumber: number): BlockConfirmationStatus | undefined {
+    const { currentBlockNumber, confirmedInBlock } = this.params
+    if (isDefined(currentBlockNumber)) {
+      if (isDefined(confirmedInBlock) && blockNumber === confirmedInBlock) {
+        return 'confirmed'
+      }
+      return currentBlockNumber > blockNumber ? 'missed' : 'pending'
+    }
+  }
+
+  formatNumber(blockNumber: number) {
+    return blockNumber.toString().length <= 5 ? new Intl.NumberFormat().format(blockNumber) : `${blockNumber.toString().slice(-2)}`
+  }
+}

package/src/confirmation/helpers/blockProgressColor.ts

@@ -0,0 +1,15 @@
+import type { LinearProgressProps } from '@mui/material'
+import { isDefined } from '@xylabs/sdk-js'
+
+export const blockProgressColor = (
+  confirmedInBlock: number | undefined,
+  isExpired: boolean | undefined,
+): LinearProgressProps['color'] => {
+  if (isDefined(confirmedInBlock)) {
+    return 'success'
+  }
+  if (isExpired) {
+    return 'error'
+  }
+  return 'primary'
+}

package/src/confirmation/helpers/createFilledRange.ts

@@ -0,0 +1,20 @@
+import { isUndefined } from '@xylabs/sdk-js'
+
+export const createFilledRange = (range?: [number, number]): number[] => {
+  if (isUndefined(range)) {
+    return []
+  }
+  const [start, end] = range
+  if (end < start) {
+    console.warn('Invalid range: end is less than start')
+    return []
+  }
+
+  const result: number[] = []
+
+  for (let i = start; i <= end; i++) {
+    result.push(i)
+  }
+
+  return result
+}

package/src/confirmation/helpers/getBlockProgress.ts

@@ -0,0 +1,22 @@
+import { isUndefined, isUndefinedOrNull } from '@xylabs/sdk-js'
+
+export const getBlockProgress = (
+  currentBlockNumber: number | undefined,
+  currentBlockRef: HTMLSpanElement | null,
+  progressElementRef: HTMLDivElement | null,
+) => {
+  if (isUndefined(currentBlockNumber) || isUndefinedOrNull(currentBlockRef) || isUndefinedOrNull(progressElementRef)) {
+    return 0
+  }
+
+  const currentBlockOffsetLeft = currentBlockRef.offsetLeft
+  const currentBlockOffsetWidth = currentBlockRef.clientWidth / 2
+  const currentBlockCenterOffsetLeft = currentBlockOffsetLeft + currentBlockOffsetWidth
+  const parentOffsetLeft = progressElementRef.offsetLeft
+  const parentWidth = progressElementRef.clientWidth
+
+  const relativePosition = currentBlockCenterOffsetLeft - parentOffsetLeft
+  const progress = (relativePosition / parentWidth) * 100
+
+  return Math.min(Math.max(progress, 0), 100)
+}

package/src/confirmation/helpers/index.ts

@@ -0,0 +1,6 @@
+export * from './BlockFormatters.ts'
+export * from './blockProgressColor.ts'
+export * from './createFilledRange.ts'
+export * from './getBlockProgress.ts'
+export * from './isCurrentBlockPassedRange.ts'
+export * from './passedBlocksInRange.ts'

package/src/confirmation/helpers/isCurrentBlockPassedRange.ts

@@ -0,0 +1,13 @@
+import { isDefined } from '@xylabs/sdk-js'
+import type { BlockRange } from '@xyo-network/xl1-protocol'
+
+export const isCurrentBlockPassedRange = (
+  blockRange: BlockRange | undefined,
+  currentBlockNumber: number | undefined,
+) => {
+  if (!isDefined(blockRange) || !isDefined(currentBlockNumber)) {
+    return false
+  }
+  const [, end] = blockRange
+  return currentBlockNumber > end
+}

package/src/confirmation/helpers/passedBlocksInRange.ts

@@ -0,0 +1,12 @@
+import { isDefined } from '@xylabs/sdk-js'
+
+export const passedBlocksInRange = (
+  range: number[] | undefined,
+  currentBlockNumber: number | undefined,
+) => {
+  if (!isDefined(currentBlockNumber) || !isDefined(range)) {
+    return []
+  }
+  const [start] = range
+  return range.filter(block => block < currentBlockNumber && block >= start)
+}

package/src/confirmation/hooks/index.ts

@@ -0,0 +1 @@
+export * from './useBlockRangeState.ts'

package/src/confirmation/hooks/useBlockRangeState.ts

@@ -0,0 +1,27 @@
+import { isDefined } from '@xylabs/sdk-js'
+import type { BlockRange } from '@xyo-network/xl1-protocol'
+import { useMemo } from 'react'
+
+import {
+  blockProgressColor, createFilledRange, isCurrentBlockPassedRange, passedBlocksInRange,
+} from '../helpers/index.ts'
+
+export const useBlockRangeState = (
+  blockRange: BlockRange | undefined,
+  confirmedInBlock: number | undefined,
+  currentBlockNumber?: number | undefined,
+) => {
+  const range = useMemo(() => createFilledRange((blockRange)), [blockRange])
+
+  const isExpired = useMemo(() => isCurrentBlockPassedRange(blockRange, currentBlockNumber), [blockRange, currentBlockNumber])
+
+  const passedBlocks = useMemo(() => passedBlocksInRange(range, currentBlockNumber), [currentBlockNumber, range])
+
+  const progressColor = useMemo(() => blockProgressColor(confirmedInBlock, isExpired), [confirmedInBlock, isExpired])
+
+  const isConfirmed = isDefined(confirmedInBlock)
+
+  return {
+    isConfirmed, isExpired, passedBlocks, progressColor, range,
+  }
+}

package/src/confirmation/index.ts

@@ -0,0 +1,3 @@
+export * from './components/index.ts'
+export * from './helpers/index.ts'
+export * from './hooks/index.ts'

package/src/index.ts

@@ -0,0 +1 @@
+export * from './confirmation/index.ts'