@lumen-dapps-kit/web3 0.1.0

package/src/components/TxStatus.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+import { cn, StatusBadge, PulseDot } from '@lumen-dapps-kit/ui';
+import type { TxState } from '../utils';
+import { truncateAddress } from '../utils';
+
+export interface TxStatusProps {
+  state: TxState;
+  /** Tx hash, when available. */
+  hash?: string;
+  /** Optional block explorer URL to link to. */
+  explorerUrl?: string;
+  /** Optional title (defaults from state). */
+  title?: string;
+  /** Confirmations seen so far. */
+  confirmations?: number;
+  /** Required confirmations target. */
+  requiredConfirmations?: number;
+  className?: string;
+}
+
+const COPY: Record<TxState, { title: string; tone: 'ok' | 'warn' | 'err' | 'data' | 'muted'; live: boolean }> = {
+  idle: { title: 'IDLE', tone: 'muted', live: false },
+  preparing: { title: 'PREPARING', tone: 'data', live: true },
+  'awaiting-signature': { title: 'AWAITING SIGNATURE', tone: 'warn', live: true },
+  pending: { title: 'PENDING', tone: 'data', live: true },
+  confirmed: { title: 'CONFIRMED', tone: 'ok', live: false },
+  failed: { title: 'FAILED', tone: 'err', live: false },
+  rejected: { title: 'REJECTED', tone: 'err', live: false },
+};
+
+/**
+ * TxStatus — transaction lifecycle indicator. Six canonical states, each
+ * with its own tone + dot/badge. Pair with wagmi's `useWaitForTransactionReceipt`
+ * to drive state, or any custom signer flow.
+ */
+export const TxStatus = ({
+  state,
+  hash,
+  explorerUrl,
+  title,
+  confirmations,
+  requiredConfirmations,
+  className,
+}: TxStatusProps) => {
+  const copy = COPY[state];
+  const label = title ?? copy.title;
+  const link =
+    hash && explorerUrl
+      ? `${explorerUrl.replace(/\/$/, '')}/tx/${hash}`
+      : undefined;
+
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-between hairline px-3 py-2.5',
+        className
+      )}
+    >
+      <div className="flex items-center gap-2.5">
+        {copy.live ? (
+          <PulseDot tone={copy.tone === 'muted' ? 'data' : copy.tone} />
+        ) : (
+          <StatusBadge tone={copy.tone} dot>
+            {''}
+          </StatusBadge>
+        )}
+        <span className="mono text-[11px] text-ink-900">{label}</span>
+      </div>
+      <div className="flex items-center gap-3 mono text-[10.5px] text-ink-700">
+        {typeof confirmations === 'number' &&
+          typeof requiredConfirmations === 'number' && (
+            <span className="tabular-nums">
+              {confirmations}/{requiredConfirmations} CONF
+            </span>
+          )}
+        {hash && (
+          link ? (
+            <a
+              href={link}
+              target="_blank"
+              rel="noreferrer"
+              className="text-ink-800 hover:text-white underline-offset-2 hover:underline"
+            >
+              {truncateAddress(hash, { head: 6, tail: 4 })}
+            </a>
+          ) : (
+            <span className="text-ink-800">
+              {truncateAddress(hash, { head: 6, tail: 4 })}
+            </span>
+          )
+        )}
+      </div>
+    </div>
+  );
+};

package/src/components/WalletPill.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { cn, Button } from '@lumen-dapps-kit/ui';
+import { truncateAddress } from '../utils';
+
+export interface WalletPillProps {
+  /** Address — undefined renders the connect CTA. */
+  address?: string;
+  /** Display name (ENS, etc). */
+  name?: string;
+  /** Active chain symbol shown after the address. */
+  chainSymbol?: string;
+  onConnect?: () => void;
+  /** When provided, the pill becomes a click target (opens an account drawer, etc).
+   *  When omitted, the pill defaults to click-to-copy. */
+  onClick?: () => void;
+  /** Loading state during connect/reconnect handshake. */
+  pending?: boolean;
+  className?: string;
+}
+
+/**
+ * WalletPill — top-right wallet affordance. Renders a CONNECT button when
+ * disconnected; a pill with truncated address (+ optional ENS, chain symbol)
+ * when connected. Wallet-library agnostic — pass state in via props.
+ */
+export const WalletPill = ({
+  address,
+  name,
+  chainSymbol,
+  onConnect,
+  onClick,
+  pending,
+  className,
+}: WalletPillProps) => {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = useCallback(async () => {
+    if (!address) return;
+    try {
+      await navigator.clipboard.writeText(address);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1200);
+    } catch {
+      /* noop */
+    }
+  }, [address]);
+
+  if (!address) {
+    return (
+      <Button
+        variant="primary"
+        size="sm"
+        onClick={onConnect}
+        disabled={pending}
+        className={cn(className)}
+      >
+        {pending ? 'CONNECTING…' : 'CONNECT WALLET'}
+      </Button>
+    );
+  }
+
+  const handleClick = onClick ?? handleCopy;
+  const label = copied ? 'COPIED' : name || truncateAddress(address);
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      title={address}
+      className={cn(
+        'flex items-center gap-2 px-3 h-8 hairline mono text-[11px] hover:bg-white/5 transition-colors',
+        className
+      )}
+    >
+      <span className="w-1.5 h-1.5 bg-white" aria-hidden="true" />
+      <span className="text-ink-900">{label}</span>
+      {chainSymbol && (
+        <>
+          <span className="text-ink-700">·</span>
+          <span className="text-ink-700">{chainSymbol}</span>
+        </>
+      )}
+    </button>
+  );
+};

package/src/index.ts

@@ -0,0 +1,22 @@
+export {
+  AddressDisplay,
+  type AddressDisplayProps,
+} from './components/AddressDisplay';
+export { WalletPill, type WalletPillProps } from './components/WalletPill';
+export { NetworkStatus, type NetworkStatusProps } from './components/NetworkStatus';
+export {
+  ChainSelector,
+  type ChainSelectorProps,
+} from './components/ChainSelector';
+export { GasIndicator, type GasIndicatorProps } from './components/GasIndicator';
+export { TxStatus, type TxStatusProps } from './components/TxStatus';
+export { AmountDisplay, type AmountDisplayProps } from './components/AmountDisplay';
+
+export {
+  truncateAddress,
+  formatGwei,
+  formatUnits,
+  type TxState,
+  type ChainBrief,
+  type TruncateAddressOpts,
+} from './utils';

package/src/utils.ts

@@ -0,0 +1,88 @@
+/**
+ * Chain-agnostic formatting helpers. No wallet library required.
+ */
+
+export interface TruncateAddressOpts {
+  /** Characters to show after the 0x prefix. */
+  head?: number;
+  /** Characters to show at the tail. */
+  tail?: number;
+  /** Separator. Defaults "…". */
+  sep?: string;
+}
+
+/**
+ * truncateAddress("0x7F3a2bC9...9C2e") -> "0x7F3a…9C2e"
+ * Works for EVM (0x-prefixed) and any other string-based addressing scheme.
+ */
+export const truncateAddress = (
+  address: string,
+  { head = 4, tail = 4, sep = '…' }: TruncateAddressOpts = {}
+): string => {
+  if (!address) return '';
+  const hasPrefix = address.startsWith('0x');
+  const prefix = hasPrefix ? '0x' : '';
+  const body = hasPrefix ? address.slice(2) : address;
+  if (body.length <= head + tail) return address;
+  return `${prefix}${body.slice(0, head)}${sep}${body.slice(-tail)}`;
+};
+
+/**
+ * Format wei (bigint or string) as a gwei value with a fixed number of decimals.
+ */
+export const formatGwei = (
+  wei: bigint | string | number,
+  decimals = 2
+): string => {
+  const n = typeof wei === 'bigint' ? Number(wei) : Number(wei);
+  const gwei = n / 1e9;
+  return gwei.toLocaleString('en-US', {
+    minimumFractionDigits: 0,
+    maximumFractionDigits: decimals,
+  });
+};
+
+/**
+ * Format a base-unit bigint as a human-readable token amount.
+ * formatUnits(1500000000000000000n, 18) -> "1.5"
+ */
+export const formatUnits = (
+  value: bigint | string,
+  decimals: number,
+  displayDecimals = 4
+): string => {
+  const v = typeof value === 'string' ? BigInt(value) : value;
+  const negative = v < 0n;
+  const abs = negative ? -v : v;
+  const base = 10n ** BigInt(decimals);
+  const whole = abs / base;
+  const frac = abs % base;
+  const fracStr = frac
+    .toString()
+    .padStart(decimals, '0')
+    .slice(0, displayDecimals)
+    .replace(/0+$/, '');
+  const out = fracStr ? `${whole}.${fracStr}` : `${whole}`;
+  return negative ? `-${out}` : out;
+};
+
+export type TxState =
+  | 'idle'
+  | 'preparing'
+  | 'awaiting-signature'
+  | 'pending'
+  | 'confirmed'
+  | 'failed'
+  | 'rejected';
+
+export interface ChainBrief {
+  id: number | string;
+  /** Short label, e.g. "ETH", "BASE", "SOL". */
+  symbol: string;
+  /** Full name, e.g. "Ethereum Mainnet". */
+  name: string;
+  /** Optional accent color (hex). */
+  color?: string;
+  /** True if this chain is a testnet. */
+  testnet?: boolean;
+}