aegis-swap-widget 0.1.2 → 0.3.0

package/README.md

@@ -1,16 +1,17 @@
 # Aegis Swap Widget
 
-Embeddable React swap widget for Aegis direct pools. It does not import the private Aegis Engine SDK and does not use Uniswap widget packages.
+Embeddable React swap widget for Aegis direct pools. Import the component, import the CSS, and configure pools, wallet handoff, and host styling through props.
 
-The widget quotes the configured Uniswap v4 pool, handles ERC20 approval to Permit2, signs a Permit2 batch for the Aegis router, and submits the direct pool swap.
+The host app normally only renders `<AegisSwapWidget />`. Quoting, token approval, Permit2 signing, and swap submission are handled inside the widget.
 
 Typing in the Sell field creates an exact-input swap. Typing in the Buy field
 creates an exact-output swap. Active quotes refresh every five seconds while the
 amount is valid.
 
-On Ethereum mainnet, widget swaps apply a fixed 50 bps output-token fee to
-`0x8ea2C7de60ef1Cd4dcE64ea2DDDe2f99F0127eFC`. The widget does not apply this
-fee on other chains yet.
+Widget swaps apply an internal output-token fee per configured chain. The bundled
+Ethereum mainnet config carries a fixed 50 bps fee to
+`0x8ea2C7de60ef1Cd4dcE64ea2DDDe2f99F0127eFC`. A chain carries a fee only when its
+bundled config sets one; today only Ethereum mainnet is bundled.
 
 ## Install
 
@@ -18,6 +19,9 @@ fee on other chains yet.
 npm install aegis-swap-widget
 ```
 
+Peer dependencies (provided by the host app): `react >=18 <20`, `react-dom >=18 <20`,
+and `viem ^2`. The package is ESM-only and ships no runtime dependencies of its own.
+
 ## Basic Usage
 
 ```tsx
@@ -25,12 +29,7 @@ import { AegisSwapWidget } from 'aegis-swap-widget'
 import 'aegis-swap-widget/styles.css'
 
 export function Swap() {
-  return (
-    <AegisSwapWidget
-      theme="dark"
-      accentColor="#31d48a"
-    />
-  )
+  return <AegisSwapWidget />
 }
 ```
 
@@ -43,6 +42,32 @@ Token icons are hydrated from the same metadata table used by the Aegis website:
 `GlobalToken.iconURL` from the Aegis metadata GraphQL API. The default endpoint is
 `https://aegis.markets/graphql/meta`.
 
+## Headless Core
+
+Use the root import for the React widget and CSS. Use the `/core` entry when a
+host, backend-backed client, or future query layer needs the swap primitives
+without importing the widget UI:
+
+```ts
+import {
+  AEGIS_SWAP_MARKETS,
+  createSwapPublicClient,
+  fetchDirectSwapQuote,
+} from 'aegis-swap-widget/core'
+```
+
+The core entry exports chain and pool config helpers, quote fetching, calldata
+encoding, Permit2 helpers, wallet/provider utilities, metadata fetchers, and the
+pure transaction-progress helpers. It does not import the React widget or the
+package stylesheet.
+
+To render token icons with the widget's exact resolution order (config
+`iconUrl` → metadata endpoint → ICHI guess), use `resolveTokenIconUrl`:
+
+```ts
+import { resolveTokenIconUrl, fetchGlobalTokenMetadata } from 'aegis-swap-widget/core'
+```
+
 ## Appearance
 
 Hosts can choose the widget surface and brand accent at instantiation time:
@@ -55,7 +80,13 @@ Hosts can choose the widget surface and brand accent at instantiation time:
 />
 ```
 
-`theme` supports `dark` and `light`. `accentColor` accepts any CSS color value and is used for the CTA, selected pools, focus states, links, and swap controls. `accentTextColor` is optional and only needed when the accent color needs a different CTA text color for contrast.
+`theme` supports `dark`, `light`, or `auto` (which follows the host's `prefers-color-scheme`). `accentColor` accepts any CSS color value and is used for the CTA, selected pools, focus states, links, and swap controls. The widget auto-derives a readable CTA text color from `accentColor` — for hex, `rgb()`, and `hsl()` values everywhere, and for any CSS color (named, `oklch()`, …) in the browser. `accentTextColor` overrides that and is the deterministic choice when you want an exact CTA text color (or are rendering a named/`oklch()` accent during SSR).
+
+The default accent is neutral green. Pass `accentColor`, `accentTextColor`, `title`, `subtitle`, `className`, or `style` when the widget should blend into another product UI.
+
+The default palette is authored in OKLCH (tinted neutrals, a calmer accent). The
+full set of host-overridable CSS variables — color, motion, rail, and toast
+tokens — is documented in [DESIGN.md](./DESIGN.md).
 
 ## Configure Pools
 
@@ -86,24 +117,27 @@ export function Swap() {
 }
 ```
 
-Use `defaultPoolId` to choose which pool opens first. Use `targets` when a host wants a different pool order or subset:
+Use `defaultPoolId` to choose which pool opens first. Use `poolIds` when a host wants a different pool order or subset:
 
 ```tsx
 <AegisSwapWidget
   pools={pools}
   defaultPoolId="GRASS_USDC"
-  targets={['GRASS_USDC', 'WATER_USDC']}
+  poolIds={['GRASS_USDC', 'WATER_USDC']}
 />
 ```
 
 ## Fees
 
-The widget applies a fixed output-token fee only on Ethereum mainnet:
+The widget applies an internal output-token fee per chain. Each bundled chain config
+carries its own fee. Today only Ethereum mainnet is bundled:
 
 - Fee: `50` bps
 - Recipient: `0x8ea2C7de60ef1Cd4dcE64ea2DDDe2f99F0127eFC`
 
-This fee is internal to the widget and is not configured by host sites.
+This fee is internal to the widget and is not configured by host sites — host `chains`
+overrides cannot set or change it. Chains added later carry a fee only when their
+bundled config provides one.
 
 For custom assets, provide full pool and token metadata:
 
@@ -255,24 +289,291 @@ host connect modal creates the provider during the button click:
 If none of these props are supplied, the widget still checks `window.ethereum`
 automatically when it renders and again when the user clicks connect/swap.
 
+## UI Integration
+
+Use `className` for host CSS selectors and `style` for one-off layout overrides or CSS variables:
+
+```tsx
+<AegisSwapWidget
+  className="partner-swap"
+  style={{ maxWidth: 520 }}
+  title="Swap"
+  subtitle="Aegis direct pools"
+  ariaLabel="Partner swap"
+/>
+```
+
+`accentColor`, `accentTextColor`, `title`, and `subtitle` are the intended props for making the widget fit a host surface without forking the component.
+
+## Transaction Status
+
+The widget paints swap progress on a rail along its own top edge — an accent
+sweep while pending/mining, solid green on success, solid red on errors
+(including wallet rejections), then a short hold and fade. The rail is the
+default of two built-in status surfaces; `statusSurface` switches to toast
+notifications, shows `'both'`, or `'none'` (see Toasts below). Hosts can tune
+the rail through the widget's `style` prop:
+
+```tsx
+<AegisSwapWidget
+  style={{
+    '--aegis-rail-height': '4px',
+    '--aegis-rail-hold': '1800ms',
+    '--aegis-rail-fade': '260ms'
+  }}
+/>
+```
+
+Use CSS time strings (`ms` or `s`) for `--aegis-rail-hold` and
+`--aegis-rail-fade`; the widget reads the computed tokens at runtime so the
+success auto-reset stays in sync with the host-tuned animation. Hosts can
+mirror that state outside the widget three ways:
+
+`onStatusChange` fires a snapshot on every lifecycle transition. `walletPrompts`
+is the SDK-owned provider-prompt plan: ERC20 approval, Permit2 authorization,
+and swap submission are counted from the current allowance/authorization reads.
+Use that for step copy or external rails instead of guessing from status names:
+
+```tsx
+<AegisSwapWidget
+  onStatusChange={({ status, progress, walletPrompts, txHash, error }) => {
+    // status:   'idle' | 'approving' | 'signing' | 'submitting' | 'success'
+    // progress: 'pending' | 'mining' | 'success' | 'error' | null (rail hidden)
+    // walletPrompts: { total, completed, active } // active is 1-based or null
+    // error:    user-facing message, e.g. "Request rejected."
+  }}
+/>
+```
+
+The rail separates step completion from activity: `completePct` fills the calm
+completed portion (for example 33.3% after one of three wallet prompts), while
+the pending/mining shimmer is always a full-width top-border sweep.
+
+Errors never appear in `status` (the submit machine resets to `'idle'`); read
+them from `progress === 'error'` plus `error`. For classifying the raw `Error`
+from `onError`, `isUserRejectedError` is exported.
+
+Success clears itself after confirming (by default a 3s hold plus the 420ms
+rail fade-out), the widget resets and emits a final
+`{ status: 'idle', progress: null }` snapshot. Errors persist until the
+user interacts with the widget again — the in-widget rail fades out visually,
+but the last snapshot and `data-progress-state` keep reporting `'error'`,
+matching the widget's own inline error message.
+
+`AegisSwapProgressRail` renders the animated rail standalone — mount it inside
+any `position: relative` container and feed it the snapshot's `progress`:
+
+```tsx
+import { useState } from 'react'
+import {
+  AegisSwapProgressRail,
+  AegisSwapWidget,
+  type AegisSwapStatusSnapshot
+} from 'aegis-swap-widget'
+import 'aegis-swap-widget/styles.css'
+
+export function CheckoutHeader() {
+  const [status, setStatus] = useState<AegisSwapStatusSnapshot | null>(null)
+
+  return (
+    <>
+      <AegisSwapWidget onStatusChange={setStatus} />
+
+      <header style={{ position: 'relative' }}>
+        <AegisSwapProgressRail
+          state={status?.progress ?? null}
+          label={status?.label ?? undefined}
+          completePct={status?.completePct ?? undefined}
+          activeWidthPct={status?.activeWidthPct ?? undefined}
+        />
+        My checkout
+      </header>
+    </>
+  )
+}
+```
+
+Driven from `progress` alone, the standalone rail uses simplified geometry — a
+full-width sweep while in flight, solid fill when terminal. Feed the snapshot's
+`completePct` and `activeWidthPct` to mirror the in-widget prompt-aware fill.
+Theme it by setting `--aegis-swap-accent` (plus
+`--aegis-swap-danger` and `--aegis-swap-success` for the terminal fills) on an
+ancestor. `--aegis-rail-height`, `--aegis-rail-hold`, and
+`--aegis-rail-fade` apply to the standalone rail as CSS too; only the in-widget
+auto-reset timer reads those motion tokens. The built-in color fallbacks are
+the dark-theme values, so light hosts should set them.
+
+For CSS-only hooks, the widget root mirrors the rail as
+`data-progress-state="pending | mining | success | error"`, so a host
+stylesheet can react without JavaScript. The attribute stays on for every
+`statusSurface`, including `'toast'` and `'none'`.
+
+## Toasts
+
+`statusSurface="toast"` replaces the rail with toast notifications; `'both'`
+shows rail and toasts, `'none'` neither. With `'toast'` or `'both'` the widget
+provides its own toast viewport — no extra setup:
+
+```tsx
+<AegisSwapWidget statusSurface="toast" toastPosition="bottom-right" />
+```
+
+One toast per swap attempt morphs through the lifecycle: a loading card
+follows the same wallet-prompt copy as the rail, then settles into success
+(received amount plus a View transaction link) or error in place. Wallet
+rejections auto-dismiss after 4s and other errors after 8s — the widget's
+inline error message and `data-progress-state` persist regardless. A retry
+withdraws the previous attempt's toast and starts a fresh one.
+
+Mounting `<AegisSwapToaster />` anywhere in the app takes over rendering from
+every widget-provided toaster — exactly one toast viewport exists per page —
+which is how hosts control placement and toast options:
+
+```tsx
+import { AegisSwapToaster, AegisSwapWidget } from 'aegis-swap-widget'
+import 'aegis-swap-widget/styles.css'
+
+<AegisSwapWidget statusSurface="toast" />
+<AegisSwapToaster position="top-right" theme="light" accentColor="#006adc" closeButton />
+```
+
+`AegisSwapToaster` props: `position` (`top`/`bottom` × `left`/`center`/`right`,
+default `'bottom-right'`), `theme`/`accentColor`/`accentTextColor` (the toaster
+portals to `document.body`, so widget-root accent variables do not reach it —
+pass these props or set `--aegis-swap-accent` and friends on `:root`),
+`duration` (auto-dismiss for info/success, default 5000ms), `visibleToasts`
+(default 3), `closeButton` (default `false` — swipe and auto-dismiss always
+work), `expand` (always-expanded list instead of the hover-expanded stack),
+`offset` (viewport inset, default 24px / 16px on small screens), `className`,
+and `style` (e.g. `'--aegis-swap-toast-z'`, `'--aegis-swap-toast-width'`).
+
+The toast system is the widget's own implementation, not a dependency: toasts
+stack with depth, hovering (or focusing) the stack expands it into a list,
+swiping toward the nearest viewport edge dismisses (momentum-based — a quick
+flick is enough), auto-dismiss timers pause while hovered, while swiping, and
+in hidden tabs, and `prefers-reduced-motion` reduces all motion to fades.
+
+`aegisToast` is exported so host apps can fire their own toasts through the
+same viewport — a plain function, no hooks or context:
+
+```tsx
+import { aegisToast } from 'aegis-swap-widget'
+
+aegisToast('Copied')                            // info
+aegisToast.success('Saved', { description: 'Order #1204' })
+aegisToast.error('Could not save', { duration: 8000 })
+
+const id = aegisToast.loading('Uploading…')     // sticky until updated
+aegisToast.success('Uploaded', { id })          // reusing an id morphs in place
+
+aegisToast.promise(save(), {
+  loading: 'Saving…',
+  success: (result) => `Saved ${result.name}`,
+  error: (reason) => (reason instanceof Error ? reason.message : 'Save failed')
+})
+```
+
+Every creator returns the toast id. Actions render as a new-tab link
+(`{ label, href }`) or a button (`{ label, onClick }`); acting on a toast
+dismisses it. `duration: Infinity` keeps a toast until dismissed;
+`dismissible: false` hides the close affordance and blocks swiping. One caveat
+shared with every module-store toast library: two bundled copies of the
+package keep two independent toast stores (and two viewports).
+
+## Motion
+
+Switching pools or the approval mode glides a single active pill between the
+options (iOS-segmented-control style), and the Sell/Buy token pills cross-fade
+when a switch retargets them. It is all CSS — no animation library — and every
+animation respects `prefers-reduced-motion` automatically.
+
+Hosts tune or disable the switch motion through CSS tokens on the `style` prop:
+
+```tsx
+<AegisSwapWidget
+  style={{
+    '--aegis-switch-dur': '180ms', // pill glide + token swap; '0ms' disables
+    '--aegis-spring': 'cubic-bezier(0.2, 0, 0, 1)' // switch easing
+  }}
+/>
+```
+
+## Migrating to 0.3.0
+
+0.3.0 removes the props that were deprecated in 0.2.x. The replacements are
+drop-in:
+
+| Removed | Use instead |
+| --- | --- |
+| `targets={[...]}` | `poolIds={[...]}` (same `string[]`) |
+| `markets={map}` | `pools={Object.values(map)}` |
+| `defaultDirection="intoTarget"` | `defaultDirection="buy"` |
+| `defaultDirection="outOfTarget"` | `defaultDirection="sell"` |
+| `showApprovalModeControl` | `showApprovalMode` |
+
+No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
+
 ## Props
 
 - `provider`: optional EIP-1193 provider. Defaults to auto-detected `window.ethereum`.
 - `account`: optional connected account from the host wallet UI.
 - `getProvider`: optional provider resolver for wallet libraries with async providers.
 - `onConnectWallet`: optional callback for opening the host wallet modal. It may return `{ provider, account }`.
+- `onSubmitted`: `(hash, swap?)` fired when the swap transaction is sent. `swap` carries mode, token symbols, amounts, and fee for analytics.
+- `onSuccess`: `({ hash, explorerUrl, swap? })` fired when the receipt confirms.
+- `onError`: `(error)` fired on approval/swap failures (after the widget shows its own message).
+- `onQuote`: `(quote)` fired on every quote refresh.
+- `onStatusChange`: `(snapshot)` fired on every lifecycle transition with what the top progress rail shows (see Transaction Status).
+- `onPoolChange`: `(poolId)` fired when the active pool changes — user selection or a `poolIds` update that forces a fallback. Silent on mount.
 - `chainId`: active chain id. Defaults to Ethereum mainnet.
 - `chains`: optional chain config overrides or additional chain configs, including per-chain `v4Contracts`.
-- `pools`: direct pool configs to render and swap against.
+- `networkOptions`: optional display-only entries for the network menu (`{ id, name, icon?, selected?, disabled?, status? }`). The active entry is resolved by explicit `selected: true`, else by `id` matching the active chain id, else by `name`; a list without the active chain gets it prepended so the trigger never misreports the chain in use. Non-selected options render disabled by default with optional `status` text (e.g. "Coming soon"); `icon` is `'ethereum' | 'base'`. Clicking the enabled option only closes the menu (disabled options ignore clicks) — switching is not wired yet.
+- `pools`: direct pool configs to render and swap against. This is the canonical config path.
 - `defaultPoolId`: initial pool id when `pools` is provided.
-- `targets`: optional pool id order/subset.
-- `defaultDirection`: `intoTarget` for USDC to target, or `outOfTarget` for target to USDC.
-- `markets`: advanced override for normalized pool/router/quoter config.
-- `rpcUrls`: optional RPC fallback list for the active chain.
+- `poolIds`: optional pool id order/subset. Use this when the host wants to hide pools or control ordering.
+- `defaultDirection`: `buy` (counter token into the pool token) or `sell` (pool token into the counter token). Defaults to `buy`.
+- `defaultSlippagePercent`: number (canonical) or numeric string, in percent. Defaults to `1`.
+- `rpcUrls`: RPC fallback list for the active chain, or a `{ [chainId]: string[] }` map for multichain hosts.
 - `metadataEndpoint`: optional metadata GraphQL endpoint for `GlobalToken.iconURL` token icons. Set to `null` to disable.
-- `theme`: `dark` or `light`. Defaults to `dark`.
-- `accentColor`: CSS accent color for the CTA, selected pools, focus states, links, and swap controls.
+- `className`: optional class for host layout and styling hooks.
+- `style`: optional root style object, useful for host layout constraints or CSS variables.
+- `title`: optional widget heading. Empty by default (compact topbar, no header row).
+- `subtitle`: optional header eyebrow. Defaults to empty. Pass a string to show it.
+- `ariaLabel`: optional accessible label for the widget region.
+- `theme`: `dark`, `light`, or `auto` (follows `prefers-color-scheme`). Defaults to `dark`.
+- `accentColor`: CSS accent color for the CTA, selected pools, focus states, links, and swap controls. When set without `accentTextColor`, the widget derives a readable CTA text color automatically (see Appearance for supported color formats).
 - `accentTextColor`: optional CTA text color for contrast with the chosen accent.
+- `showPoolLink`: whether to render the direct-pool link when the active chain provides `poolExplorerUrl`.
+- `defaultApprovalMode`: `exact` approves only the current quote spend by default; `max` opts into the old unlimited ERC-20 to Permit2 approval behavior.
+- `showApprovalMode`: whether the details drawer exposes the Exact/Max approval toggle. Defaults to `true`.
+- `showExecutionDetails`: whether to render the collapsible settings drawer for slippage, approval mode, and route. Defaults to `true`.
+- `defaultExecutionDetailsOpen`: whether that settings drawer starts expanded. Defaults to `false`.
+- `statusSurface`: where transaction status is surfaced — `'rail'` (default), `'toast'`, `'both'`, or `'none'`. The root `data-progress-state` attribute stays on regardless (see Toasts).
+- `toastPosition`: viewport corner for the widget-provided toaster. Defaults to `'bottom-right'`; ignored once a host mounts `<AegisSwapToaster />`.
+
+The widget intentionally does not inherit the host font; set the
+`--aegis-swap-font-family` CSS variable (via `style` or a stylesheet) to match
+the host typography.
+
+### With wagmi
+
+The widget consumes the host's wallet instead of bundling its own connect UI.
+From a wagmi app, derive the EIP-1193 provider from the active connector:
+
+```tsx
+import { useAccount } from 'wagmi'
+
+function Swap() {
+  const { address, connector } = useAccount()
+  return (
+    <AegisSwapWidget
+      account={address}
+      getProvider={async () => (await connector?.getProvider()) ?? null}
+      onConnectWallet={openConnectModal}
+    />
+  )
+}
+```
 
 ## Default Markets
 
@@ -287,9 +588,30 @@ These use the Aegis mainnet router `0x00581261a1200956ea05d1810fF28ffd66D8E254`
 and the Ethereum entry in `UNISWAP_V4_CONTRACTS_BY_CHAIN` for Permit2 and the
 public Uniswap v4 Quoter.
 
+## License
+
+MIT.
+
 ## Local Demo
 
 ```bash
-npm install
+npm ci
 npm run dev
 ```
+
+## Releasing
+
+Maintainer release flow (publishes to npm). `dist/` is not committed — the `prepack`
+hook rebuilds it on every `npm pack`/`npm publish`, and `prepublishOnly` runs the
+typecheck + test gate.
+
+```bash
+git switch main && git pull
+npm ci
+npm run typecheck && npm run test && npm run build
+# Move CHANGELOG [Unreleased] entries under the new version heading.
+npm version minor            # e.g. 0.2.1 -> 0.3.0 for a breaking 0.x release; commits and tags vX.Y.Z
+git push origin main --follow-tags
+npm publish --access public  # prepublishOnly gate + prepack build run automatically
+npm view aegis-swap-widget version
+```

package/dist/abis.d.ts

@@ -72,6 +72,24 @@ export declare const AEGIS_ROUTER_ABI: readonly [{
     readonly outputs: readonly [];
 }];
 export declare const PERMIT2_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint160";
+    }, {
+        readonly name: "expiration";
+        readonly type: "uint48";
+    }];
+    readonly outputs: readonly [];
+}, {
     readonly type: "function";
     readonly name: "allowance";
     readonly stateMutability: "view";
@@ -185,4 +203,3 @@ export declare const UNISWAP_V4_QUOTER_ABI: readonly [{
         readonly type: "uint256";
     }];
 }];
-//# sourceMappingURL=abis.d.ts.map

package/dist/address.d.ts

@@ -0,0 +1,5 @@
+import type { Address, Hex } from 'viem';
+export declare function addressKey(address: Address | null | undefined): string;
+export declare function sameAddress(a: Address, b: Address): boolean;
+export declare function sameOptionalAddress(a: Address | null, b: Address | null): boolean;
+export declare function samePoolId(a: Hex, b: Hex): boolean;