@wheelx/widget 0.0.5 → 0.0.6

package/README.md

@@ -1,143 +1,110 @@
 # `@wheelx/widget`
 
-WheelX swap / bridge widget extracted as a reusable package.
+Embeddable WheelX bridge and swap widget for Next.js applications.
 
-This package currently lives at the root of the `wheelx-kit-ui` repository.
+It packages the full widget flow behind a small integration surface:
 
-This package is designed for host applications that want to embed WheelX's
-bridge and swap experience with minimal setup while still keeping control over:
+- bridge and swap UI
+- wallet-ready provider wrapper
+- network and token restrictions
+- theme and style overrides
 
-- allowed source and destination networks
-- default selected tokens
-- token restrictions per chain
-- visual styles and typography
-
-## Installation
+## Quick Start
 
-Install from npm:
+### 1. Install From npm
 
 ```bash
-pnpm add @wheelx/widget
+pnpm add @wheelx/widget @rainbow-me/rainbowkit
 ```
 
-Install host-side wallet UI dependency:
+If your app does not already load RainbowKit styles, add this once in your app entry:
 
-```bash
-pnpm add @rainbow-me/rainbowkit
+```tsx
+import '@rainbow-me/rainbowkit/styles.css'
 ```
 
-Build the package locally when working on this repository:
+Minimal usage:
 
-```bash
-pnpm build
+```tsx
+'use client'
+
+import {
+  WheelxBridgeSwapWidget,
+  WheelxWidgetProvider
+} from '@wheelx/widget'
+
+export default function Page() {
+  return (
+    <WheelxWidgetProvider>
+      <WheelxBridgeSwapWidget />
+    </WheelxWidgetProvider>
+  )
+}
 ```
 
-## Local Demo
+Requirements:
 
-This repository includes a standalone Next.js demo in `demo/`.
+- `Next.js >= 15`
+- `React 19`
+- `react-dom 19`
+
+The widget currently depends on Next.js runtime APIs, so the host app should be Next.js-based.
 
-Install dependencies for the package and the demo from the repository root:
+### 2. Run From Source
+
+Clone the repository and install dependencies from the root:
 
 ```bash
 pnpm install
 ```
 
-`pnpm install` runs the package build automatically through `prepare`, so a fresh
-clone does not require a separate manual build before starting the demo.
-
-Run the demo:
+Start the local demo:
 
 ```bash
 pnpm demo:dev
 ```
 
-`pnpm demo:dev` also rebuilds the package first to keep `dist/` in sync with the
-current source tree.
-
 Build the demo:
 
 ```bash
 pnpm demo:build
 ```
 
-## Environment
-
-The package defaults to production endpoints:
+`pnpm demo:dev` rebuilds the package first, so the demo stays aligned with the current source tree.
 
-```bash
-NEXT_PUBLIC_API_URL=https://api.wheelx.fi
-NEXT_PUBLIC_APP_DOMAIN=https://wheelx.fi
-```
+## Theme Page
 
-If you want to override them locally, create:
+The repository includes a theme playground at:
 
 ```text
-.env.local
+/theme
 ```
 
-You can start from:
+It lets you:
 
-```text
-.env.example
-```
-
-## Requirements
+- preview the live widget
+- switch between presets
+- edit theme values
+- copy the generated config block
 
-- `Next.js >= 15`
-- `React 19`
-- `react-dom 19`
+This page is intended for visual review and handoff, not just internal testing.
 
-The widget currently depends on Next.js runtime APIs, so the host application
-should be Next.js-based.
+## Configuration
 
-If your host app does not already include RainbowKit styles, add this once in
-your root layout or global entry:
+The main config type is `WheelxWidgetConfig`.
 
 ```tsx
-import '@rainbow-me/rainbowkit/styles.css'
-```
-
-`WheelxWidgetProvider` already includes the wallet-related providers required by
-the widget. If your host application wants a wallet connect button, render your
-own UI in the host app, for example with RainbowKit's `ConnectButton`.
-
-## Quick Start
-
-The smallest working integration is:
-
-```tsx
-'use client'
-
-import {
-  WheelxBridgeSwapWidget,
-  WheelxWidgetProvider
-} from '@wheelx/widget'
-
-export default function Page() {
-  return (
-    <WheelxWidgetProvider>
-      <WheelxBridgeSwapWidget />
-    </WheelxWidgetProvider>
-  )
-}
+import type { WheelxWidgetConfig } from '@wheelx/widget'
 ```
 
-## Basic Usage With Config
+Example:
 
 ```tsx
-'use client'
-
-import {
-  WheelxBridgeSwapWidget,
-  WheelxWidgetProvider,
-  type WheelxWidgetConfig
-} from '@wheelx/widget'
-
 const config: WheelxWidgetConfig = {
   mode: 'bridge-and-swap',
   networks: {
-    from: [1, 8453, 10],
-    to: [8453, 10, 137]
+    from: [1, 8453],
+    to: [8453, 137]
   },
   defaultTokens: {
     from: {
@@ -150,391 +117,288 @@ const config: WheelxWidgetConfig = {
       address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
       symbol: 'USDC'
     }
+  },
+  allowedTokens: {
+    from: [
+      {
+        chainId: 8453,
+        tokens: [
+          '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2'
+        ]
+      }
+    ]
+  },
+  styles: {
+    formContainer: {
+      backgroundColor: '#0f172a'
+    }
   }
 }
-
-export default function Page() {
-  return (
-    <WheelxWidgetProvider>
-      <WheelxBridgeSwapWidget config={config} />
-    </WheelxWidgetProvider>
-  )
-}
 ```
 
-## What The Widget Supports
+### Supported Options
 
-### 1. Bridge + Swap Mode
+#### `mode`
 
-Default mode:
+Controls the widget flow.
 
-```ts
-mode: 'bridge-and-swap'
-```
+- `bridge-and-swap`
+  Enables same-chain swaps, bridging, and cross-chain swaps.
+- `swap`
+  Restricts the widget to same-chain swaps.
 
-This allows:
-
-- same-chain swap
-- cross-chain bridge
-- cross-chain swap
-
-### 2. Swap-Only Mode
-
-```ts
-mode: 'swap'
-```
-
-Behavior:
+Notes:
 
-- the widget enforces same-chain selection
-- the token modal hides the left chain list
-- clicking `From` or `To` only shows tokens for the currently selected chain
-- initial token rendering is aligned to the configured chain before token data
-  finishes loading, so the widget does not flash the built-in Soneium/Base
-  defaults first
+- `bridge-and-swap` is the default.
+- In `swap` mode, the widget normalizes `networks.from` and `networks.to` to the shared chain set when both are provided.
 
-### 3. Network Restriction
+#### `networks`
 
-You can allow all networks, a single network, or a subset per side.
+Restricts the available chains for each side.
 
 ```ts
-networks: {
-  from: 'all',
-  to: [8453, 10]
+networks?: {
+  from?: 'all' | number | number[]
+  to?: 'all' | number | number[]
 }
 ```
 
-Accepted formats:
+Rules:
 
-- `'all'`
-- `number`
-- `number[]`
+- Omit a side or use `'all'` to allow every chain returned by the backend.
+- Use a single number to allow one chain.
+- Use an array to allow a subset of chains.
 
-### 4. Default Token Selection
+#### `defaultTokens`
 
-You can define the initial `from` and `to` token:
+Sets the initial token selection.
 
 ```ts
-defaultTokens: {
-  from: {
-    chainId: 8453,
-    address: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
-    symbol: 'USDT'
-  },
-  to: {
-    chainId: 8453,
-    address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
-    symbol: 'USDC'
+defaultTokens?: {
+  from?: {
+    chainId: number
+    address: string
+    symbol?: string
+  }
+  to?: {
+    chainId: number
+    address: string
+    symbol?: string
   }
 }
 ```
 
-Notes:
-
-- defaults are applied once during widget initialization
-- URL presets take precedence over `defaultTokens`
-- in swap-only mode, same-chain behavior is still enforced after defaults apply
-- if a default token falls outside `networks` or `allowedTokens`, the widget will
-  fall back to the nearest valid option
-
-### 5. Token Restriction Per Chain
+Rules:
 
-You can restrict selectable tokens by chain.
+- `chainId` and `address` identify the token.
+- `symbol` is optional and can help disambiguate token lookup.
+- Defaults are applied during widget initialization.
+- If a configured default is not valid under `networks` or `allowedTokens`, the widget falls back to the nearest valid option.
 
-The widget will use the intersection of:
+#### `allowedTokens`
 
-- tokens returned by the backend API
-- tokens declared in `allowedTokens`
-
-If you configure a token address that does not exist in the API response, it is
-silently ignored.
+Restricts selectable tokens by chain.
 
 ```ts
-allowedTokens: {
-  from: [
-    {
-      chainId: 8453,
-      tokens: [
-        '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
-        '0x0000000000000000000000000000000000000000'
-      ]
-    }
-  ],
-  to: [
-    {
-      chainId: 8453,
-      tokens: ['0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913']
-    }
-  ]
+allowedTokens?: {
+  from?: Array<{
+    chainId: number
+    tokens: string[]
+  }>
+  to?: Array<{
+    chainId: number
+    tokens: string[]
+  }>
 }
 ```
 
-Important behavior:
+Rules:
 
-- restrictions are chain-scoped
-- if you only configure chain `8453`, other allowed chains remain unrestricted
-- address comparison is case-insensitive
+- Restrictions are chain-scoped.
+- Only chains explicitly listed in `allowedTokens` are restricted.
+- Chains that are not listed remain unrestricted.
+- Token addresses are normalized to lowercase internally.
+- Invalid or empty addresses are ignored.
 
-### 6. Built-In Branding
+#### `styles`
 
-The widget includes a fixed `Powered by WheelX.fi` footer link inside the card.
+Overrides widget appearance with style objects.
 
-This branding is built into the widget and is not exposed as a configuration
-option.
-
-## Customization
-
-The widget does not currently support render overrides for internal components.
-Customization is done through the `styles` field using Chakra-style props.
-
-```tsx
-const config: WheelxWidgetConfig = {
-  styles: {
-    formContainer: {
-      bg: '#FFFFFF',
-      borderRadius: '24px',
-      boxShadow: '0 12px 36px rgba(0, 0, 0, 0.12)'
-    },
-    primaryButton: {
-      borderRadius: '999px'
-    },
-    formTitleText: {
-      color: '#7C2D12',
-      fontFamily: 'Georgia, serif',
-      fontWeight: 900
-    }
-  }
-}
+```ts
+styles?: WidgetStyleOverrides
 ```
 
-## Style Slots
+All supported style keys are listed below.
 
-### Container Slots
+##### Form
 
 - `formContainer`
-- `sectionContainer`
-- `tokenSelector`
-- `recipientBadge`
-- `amountInputContainer`
-- `tokenModalContent`
-- `tokenModalChainPanel`
-- `tokenModalTokenPanel`
-- `quoteInfoContainer`
-- `quoteTooltipContent`
-- `quoteInfoCard`
-- `txStateCard`
-- `txStateRouteContainer`
-- `txStateSummaryContainer`
-- `txStateTokenCard`
-
-### Typography Slots
-
+  Main widget shell.
 - `formTitleText`
+  Main title text.
+- `formFooterText`
+  Footer text such as `Powered by WheelX.fi`.
+- `sectionContainer`
+  Form sections such as `From` and `To`.
 - `sectionLabelText`
+  Section labels.
+- `tokenSelector`
+  Token selector surface.
 - `tokenPrimaryText`
+  Token symbol and main token text.
 - `tokenSecondaryText`
+  Chain name and secondary token text.
+- `tokenIconBadge`
+  Small network badge attached to token icons.
 - `balanceText`
+  Balance text near token inputs.
+- `recipientBadge`
+  Recipient address badge on the `To` side.
+- `amountInputContainer`
+  Numeric input shell.
 - `amountInputText`
+  Numeric input text.
 - `amountUsdText`
-- `primaryButtonText`
-- `tokenModalTitleText`
-- `tokenModalSectionLabelText`
-- `tokenModalChainText`
-- `tokenModalTokenPrimaryText`
-- `tokenModalTokenSecondaryText`
-- `tokenModalCategoryTabText`
-- `slippageTitleText`
-- `slippageDescriptionText`
-- `slippageButtonText`
-- `quoteInfoLabel`
-- `quoteInfoValue`
-- `txStateLabel`
-- `txStateValue`
-
-### Button / State Slots
-
+  USD amount text below or beside token inputs.
 - `primaryButton`
+  Main action button surface.
 - `primaryButtonLoading`
+  Main action button while loading.
 - `primaryButtonWarning`
+  Main action button in warning state.
+- `primaryButtonText`
+  Main action button text.
 - `quickHalfButton`
+  `50%` quick action button.
 - `quickMaxButton`
-- `slippageSettingsTrigger`
-- `slippageAutoButton`
-- `slippageCustomInput`
-- `txStatePrimaryButton`
-- `quoteInfoFreeBadge`
+  `Max` quick action button.
 
-### Token Modal Slots
+##### Token Modal
 
+- `tokenModalContent`
+  Modal container.
+- `tokenModalTitleText`
+  Modal title.
 - `tokenModalSearchInput`
+  Search input.
+- `tokenModalChainPanel`
+  Left chain list panel.
+- `tokenModalTokenPanel`
+  Right token list panel.
+- `tokenModalSectionLabelText`
+  Section labels such as `Popular` or `Prediction`.
 - `tokenModalChainRow`
+  Chain row base style.
 - `tokenModalChainRowHover`
+  Chain row hover state.
 - `tokenModalChainRowActive`
+  Chain row active state.
+- `tokenModalChainText`
+  Chain row text.
 - `tokenModalChainsWithAssetsRow`
+  `Chains with assets` row.
 - `tokenModalChainsWithAssetsRowActive`
+  Active state for `Chains with assets`.
 - `tokenModalTokenRow`
+  Token row base style.
 - `tokenModalTokenRowHover`
+  Token row hover state.
+- `tokenModalTokenPrimaryText`
+  Token row main text.
+- `tokenModalTokenSecondaryText`
+  Token row secondary text.
 - `tokenModalCategoryTab`
+  Category tabs such as `All`, `AI`, `Liked`, `Searched`.
 - `tokenModalCategoryTabActive`
+  Active category tab.
+- `tokenModalCategoryTabText`
+  Category tab text.
 
-### Status Slots
-
-- `txStateStatusLink`
-- `txStateStatusError`
-- `txStateStatusWarning`
-- `txStateStatusProgress`
-
-## Common Integration Examples
-
-### Swap Only On Base
-
-```ts
-const config: WheelxWidgetConfig = {
-  mode: 'swap',
-  networks: {
-    from: 8453,
-    to: 8453
-  }
-}
-```
-
-### Restrict From/To To Different Network Sets
-
-```ts
-const config: WheelxWidgetConfig = {
-  networks: {
-    from: [1, 8453],
-    to: [10, 137, 8453]
-  }
-}
-```
-
-### Restrict Only One Chain's Tokens
-
-```ts
-const config: WheelxWidgetConfig = {
-  networks: {
-    from: [1, 8453],
-    to: [1, 8453]
-  },
-  allowedTokens: {
-    from: [
-      {
-        chainId: 8453,
-        tokens: [
-          '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2'
-        ]
-      }
-    ]
-  }
-}
-```
-
-Behavior:
-
-- Base `from` tokens are restricted to the configured list
-- Ethereum `from` tokens remain available
-
-### Visual Theming
-
-```ts
-const config: WheelxWidgetConfig = {
-  styles: {
-    formContainer: {
-      bg: '#FFF7ED',
-      border: '3px solid',
-      borderColor: '#EA580C'
-    },
-    tokenSelector: {
-      bg: '#DCFCE7',
-      border: '2px solid',
-      borderColor: '#16A34A'
-    },
-    primaryButton: {
-      bg: 'linear-gradient(90deg, #111827 0%, #1E3A8A 100%)',
-      color: '#FFFFFF'
-    },
-    tokenModalTokenRowHover: {
-      bg: '#DBEAFE'
-    }
-  }
-}
-```
-
-## API Reference
-
-### `WheelxWidgetProvider`
+##### Different Address Dialog
 
-Wrap the widget with this provider once at the host app integration point.
+- `differentAddressDialogContent`
+  Dialog container.
+- `differentAddressDialogTitleText`
+  Dialog title.
+- `differentAddressDialogInput`
+  Address input.
+- `differentAddressDialogCancelButton`
+  Cancel button.
+- `differentAddressDialogSaveButton`
+  Save button.
+- `differentAddressDialogCloseButton`
+  Close button in the top-right corner.
 
-```tsx
-<WheelxWidgetProvider>
-  <WheelxBridgeSwapWidget />
-</WheelxWidgetProvider>
-```
+##### Slippage
 
-### `WheelxBridgeSwapWidget`
+- `slippageSettingsTrigger`
+  Trigger button in the form header.
+- `slippagePopoverContent`
+  Slippage popover container.
+- `slippageAutoButton`
+  `Auto` slippage button.
+- `slippageCustomInput`
+  Custom slippage input.
+- `slippageTitleText`
+  Popover title.
+- `slippageDescriptionText`
+  Popover helper text.
+- `slippageButtonText`
+  Text inside slippage buttons.
 
-Props:
+##### Quote And Tooltip
 
-```ts
-interface WheelxBridgeSwapWidgetProps {
-  config?: WheelxWidgetConfig
-}
-```
+- `quoteInfoContainer`
+  Quote summary wrapper.
+- `quoteTooltipContent`
+  Tooltip container for quote details.
+- `quoteInfoCard`
+  Quote detail cards.
+- `quoteInfoLabel`
+  Quote labels such as `Price Impact` or `Slippage`.
+- `quoteInfoValue`
+  Quote values.
+- `quoteInfoFreeBadge`
+  `Free` badge styling.
 
-### `WheelxWidgetConfig`
+##### Transaction State
 
-```ts
-interface WheelxWidgetConfig {
-  mode?: 'bridge-and-swap' | 'swap'
-  networks?: {
-    from?: 'all' | number | number[]
-    to?: 'all' | number | number[]
-  }
-  defaultTokens?: {
-    from?: {
-      chainId: number
-      address: string
-      symbol?: string
-    }
-    to?: {
-      chainId: number
-      address: string
-      symbol?: string
-    }
-  }
-  allowedTokens?: {
-    from?: Array<{
-      chainId: number
-      tokens: string[]
-    }>
-    to?: Array<{
-      chainId: number
-      tokens: string[]
-    }>
-  }
-  styles?: WidgetStyleOverrides
-}
-```
+- `txStateCard`
+  Shared base style for transaction state cards.
+- `txStateRouteContainer`
+  Route summary card.
+- `txStateSummaryContainer`
+  Date, time, and recipient summary card.
+- `txStateTokenCard`
+  Token amount cards.
+- `txStateLabel`
+  Labels in the transaction state view.
+- `txStateValue`
+  Values in the transaction state view.
+- `txStatePrimaryButton`
+  Main action button in the transaction state view.
+- `txStateStatusLink`
+  Success link text.
+- `txStateStatusError`
+  Error status text.
+- `txStateStatusWarning`
+  Warning status text.
+- `txStateStatusProgress`
+  In-progress status text.
 
-## Demo
+## Environment
 
-This repository includes a local Next.js demo in:
+By default, the widget uses the production API.
 
-```text
-demo/
+```bash
+NEXT_PUBLIC_API_URL=https://api.wheelx.fi
+NEXT_PUBLIC_APP_DOMAIN=https://wheelx.fi
 ```
 
-Install and run it with:
+For wallet connections, set:
 
 ```bash
-pnpm --dir demo install
-pnpm --dir demo dev
+NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=...
 ```
 
-The demo uses the package through:
-
-```text
-@wheelx/widget -> file:..
-```
+If you are running locally, place overrides in `.env.local`.