npm package: @sentio/ui-web3
Description: A Web3-focused UI component library for displaying blockchain transactions and address information.
Latest version: 0.1.0

# @sentio/ui-web3

A Web3-focused UI component library for displaying blockchain transactions and address information.

## Features

- 🔗 Full set of Web3 transaction components
- 💰 Display balance changes
- 🏷️ Address labels and name resolution
- 📊 Chain data visualization
- ♻️ Reuses styles and components from `@sentio/ui-core`

## Installation

```bash
pnpm add @sentio/ui-web3 @sentio/ui-core
```

Note: This package depends on `@sentio/ui-core` and re-exports all of its contents, so you can import everything from `@sentio/ui-web3` if preferred.

## Usage

```tsx
// Includes both ui-core and ui-web3 components
import { 
  Button,           // from ui-core
  BarLoading,       // from ui-core
  BalanceChanges,   // from ui-web3
  HexNumber,        // from ui-web3
  TransactionStatus // from ui-web3
} from '@sentio/ui-web3'

import '@sentio/ui-core/dist/style.css'

function TransactionView({ transaction, block }) {
  return (
    <div>
      <TransactionStatus status={transaction.status} />
      <BalanceChanges transaction={transaction} block={block} />
      <HexNumber data={transaction.hash} />
    </div>
  )
}
```

## Web3 Components

### Transaction Components
- `BalanceChanges` - Display balance changes in transactions
- `HexNumber` - Hex number/address display with link and copy
- `TransactionStatus` - Transaction status indicator
- `TransactionValue` - Transaction value display
- `AddressFrom` - Source address display
- `AddressTo` - Destination address display
- `TransactionLabel` - Transaction label component
- `TransactionColumns` - Transaction table columns
- `TransactionBrief` - Brief transaction summary
- `SimulatorInfo` - Transaction simulation information

### Call Trace Components
- `FlatCallTraceTree` - Flat call trace tree visualization
- `CallTreeNode` - Individual call tree node
- `LocationViewer` - Source code location viewer
- `LocationStatus` - Location status indicator
- `isLocationStatus()` - Check if value is a location status
- `ForwardDef` - Forward definition component

### Fund Flow Components
- `TransactionFundflow` - Transaction fund flow visualization
- `FundFlow` - Fund flow diagram
- `VizGraph` - Graphviz-based graph visualization
- `processDecodedCallTrace()` - Process decoded call traces
- `generateNodesAndEdges()` - Generate graph nodes and edges
- `exportSVG()` - Export fund flow as SVG
- `exportPNG()` - Export fund flow as PNG

### MEV Components
- `MevInfo` - MEV (Maximal Extractable Value) information display
- `MevType` - MEV type indicators
- `MevLink` - MEV-related links
- `SandwichTxns` - Sandwich attack transaction display
- `FlashbotIcon` - Flashbot icon component

### Simulator Components
- `NewSimulation` - Transaction simulation interface
- `FunctionParameter` - Function parameter input
- `FunctionSelect` - Function selector dropdown
- `AmountUnitSelect` - Amount unit selector (Wei, Gwei, Ether, etc.)
- `DisclosurePanel` - Collapsible panel for simulator
- `SimulatorProvider` - Simulator context provider
- `useSimulatorContext()` - Access simulator context
- `genCoefficient()` - Generate unit coefficient
- `getWeiAmount()` - Convert to Wei amount

### Editor Components
- `SourceStore` - Source code storage
- `SoliditySourceParser` - Solidity source parser
- `SentioDocumentSymbolProvider` - Document symbol provider for Monaco
- `SentioDefinitionProvider` - Go-to-definition provider
- `SentioHoverProvider` - Hover information provider
- `SentioImplementationProvider` - Implementation provider
- `SentioReferenceProvider` - Reference provider
- `SourceView` - Source code viewer
- `HoverContextWidget` - Hover context widget
- `SourceSymbols` - Source symbols display
- `SymbolIcons` - Symbol type icons
- `SourceTree` - Source tree navigation
- `setSolidityLanguage()` - Configure Solidity language
- `setSolidityProviders()` - Set Solidity providers
- `openCodeEditor()` - Open code in editor
- `sentioTheme` - Monaco editor theme
- `solidityLanguageConfig` - Solidity language configuration
- `solidityTokensProvider` - Solidity syntax tokens
- `moveLanguageConfig` - Move language configuration
- `moveTokenProvider` - Move language tokens

### Web3 Utilities & Hooks
- `useAddressTag()` - Fetch address tag information
- `usePrice()` - Fetch token price information
- `useFallbackName()` - Get fallback contract name
- `parseUri()` - Parse debug URIs
- `trackEvent()` - Track analytics events
- `setTrackingHandler()` - Set custom tracking handler
- `getNativeToken()` - Get native token for chain
- Transaction helper utilities
- EtherLink components and utilities
- Transaction context providers

### Types & Interfaces
- Transaction types (`SimulationData`, `BlockOverride`, `StateOverride`)
- Transfer types (`TransferItem`)
- MEV types (`MevData`, `Token`, `Trader`, `Revenue`, `ArbitrageResult`, `SandwichResult`, `SandwichTx`)
- Simulator types (`SimulationFormType`, `Contract`, `AbiFunction`, `AbiInput`, `FunctionParam`, `AccessListItem`, `StateOverrideItem`, `SourceOverrideItem`, `Simulation`, `SimulateTransactionRequest`, `SimulateTransactionResponse`, `AmountUnit`, `SimulationFormState`, `ContractSelectType`)
- Editor types (`TextOccurrence`, `TreeNode`, `PreviewLocation`, `FetchAndCompileResponse`, `CompilerType`, `SymbolKind`)

### Re-exported from @sentio/ui-core
All components and utilities from `@sentio/ui-core` are re-exported, including:
- Common components (Button, Dialog, Tooltip, Loading, Input, Select, Switch, etc.)
- Table components (ResizeTable, Icons)
- Menu components (PopupMenuButton, MenuItem, SubMenuButton)
- Tree components (FlatTree)
- Utilities (useMobile, useBoolean, classNames, number formatting)

## Using ui-core alone

If your project doesn't need Web3 functionality, you can install and use just `@sentio/ui-core`:

```bash
pnpm add @sentio/ui-core
```

```tsx
import { Button, BaseDialog, BarLoading } from '@sentio/ui-core'
import '@sentio/ui-core/dist/style.css'
```

## Architecture

```
@sentio/ui-web3
    ↓ depends on & re-exports
@sentio/ui-core
    ↓ provides
Core components + styles
```

Users can:
1. Install only `@sentio/ui-core` — get core UI components.
2. Install `@sentio/ui-web3` — automatically includes `ui-core` plus Web3 components.

## Development

### Component Development with Ladle

This package uses [Ladle](https://ladle.dev/) for component development and testing. Ladle provides a fast, lightweight alternative to Storybook for developing React components in isolation.

#### Prerequisites

Make sure you have dependencies installed:

```bash
pnpm install
```

#### Starting the Development Server

To start the Ladle development server:

```bash
pnpm ladle serve
```

This will:
- Start a local development server (typically at `http://localhost:61000`)
- Watch for changes in your component stories
- Provide hot module replacement for fast development
- Display all your Web3 and core component stories in an interactive UI

#### Writing Stories

Stories are located alongside components with the `.stories.tsx` extension. For example:

```tsx
// src/transaction/HexNumber.stories.tsx
import type { Story } from '@ladle/react'
import { HexNumber } from './HexNumber'

export const Default: Story = () => (
  <HexNumber data="0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" />
)

export const WithCopy: Story = () => (
  <HexNumber 
    data="0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" 
    enableCopy 
  />
)
```

#### Available Story Examples

Check out existing stories in the `src/` directory:
- `src/transaction/HexNumber.stories.tsx` - Hex number display examples
- `src/transaction/BalanceChanges.stories.tsx` - Balance changes visualization
- `src/transaction/TransactionComponents.stories.tsx` - Transaction component examples
- `src/transaction/SimulatorInfo.stories.tsx` - Simulator info examples
- `src/transaction/TransactionBrief.stories.tsx` - Transaction brief display
- `src/transaction/calltrace/FlatCallTrace.stories.tsx` - Call trace examples
- `src/transaction/fundflow/NewFundflow.stories.tsx` - Fund flow visualization
- `src/simulator/NewSimulation.stories.tsx` - Transaction simulator
- `src/mev/MevInfo.stories.tsx` - MEV information display
- `src/editor/Editor.stories.tsx` - Code editor examples
- And more...

#### Building for Production

To build the package:

```bash
pnpm build
```

This will:
1. Build CSS with Tailwind (`pnpm build:css`)
2. Build JavaScript/TypeScript with tsup (`pnpm build:js`)

#### Watch Mode for Development

If you're developing this package alongside another package:

```bash
pnpm dev
```

This runs both CSS and JS builds in watch mode concurrently.

#### Testing with Real Data

Many Web3 components require blockchain data. When developing stories:
- Use mock data structures that match the expected interfaces
- Consider using real transaction hashes for testing (see existing stories)
- The simulator components can work with test ABIs and contracts
- Call trace and fund flow components accept decoded transaction data