aegis-swap-widget 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,200 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-06-08
+
+### Removed (breaking)
+- `targets` prop — use `poolIds` (identical `string[]` shape).
+- `markets` prop — use `pools`; `Object.values(markets)` migrates an existing map.
+- `defaultDirection` values `'intoTarget'` / `'outOfTarget'` — use `'buy'` / `'sell'`.
+
+### Changed (breaking)
+- Renamed `showApprovalModeControl` → `showApprovalMode`, pairing it with
+  `defaultApprovalMode`.
+
+### Migration
+- `targets={ids}` → `poolIds={ids}`
+- `markets={map}` → `pools={Object.values(map)}`
+- `defaultDirection="intoTarget"` → `defaultDirection="buy"`
+- `defaultDirection="outOfTarget"` → `defaultDirection="sell"`
+- `showApprovalModeControl={x}` → `showApprovalMode={x}`
+
+### Internal
+- Refactored the widget into a `useSwapController` hook (state, derivation, and
+  hook orchestration) over a thin presentational component, decomposed the swap
+  money path into pure `src/swap/` modules (`authorizePermit`,
+  `executeSwapTransaction`), and unified the host-callback emitters behind a
+  single `useChangeEmitter` primitive. No public behavior change.
+
+### Added
+- Toast notifications as an alternative transaction-status surface: new
+  `statusSurface` prop (`'rail'` default, `'toast'`, `'both'`, `'none'`) plus
+  `toastPosition`. One toast per swap attempt morphs loading → success/error in
+  place with the received amount and a View transaction action; wallet
+  rejections auto-dismiss after 4s, other errors after 8s. The root
+  `data-progress-state` attribute stays on for every surface.
+- `AegisSwapToaster` export: the toast viewport as a standalone component.
+  Mounting it anywhere takes over rendering from widget-provided toasters —
+  exactly one viewport per page — and owns `position`, `theme`/`accentColor`,
+  `duration`, `visibleToasts`, `closeButton`, `expand`, and `offset`. Toasts
+  stack with depth, expand on hover/focus, swipe-to-dismiss with momentum
+  (interruptible CSS transitions throughout), dismiss on Escape when focused,
+  pause their timers while hovered, mid-swipe, and in hidden tabs, and reduce
+  to fades under `prefers-reduced-motion`. Lifecycle morphs replay quiet icon
+  and text entrances in place, and terminal states tint the card border
+  (success whisper, error alarm) the way the progress rail recolors. The
+  viewport is hardened for arbitrary host pages: host `li`/text styling
+  cannot leak in, toasts hide in print, and the light theme keeps icon
+  contrast AA without overriding an explicit host accent.
+- `aegisToast` export: toast function for host apps sharing the same viewport —
+  `aegisToast()` / `.info` / `.success` / `.error` / `.loading` / `.dismiss` /
+  `.promise`, with upsert-by-id morphing. New public types
+  `AegisSwapToasterProps`, `AegisSwapStatusSurface`, `AegisToastAction`,
+  `AegisToastOptions`, `AegisToastPosition`, `AegisToastType`, and
+  `AegisToastPromiseMessage`/`AegisToastPromiseMessages`.
+- `onPoolChange` prop: fires with the active pool id whenever it changes —
+  user tab selection or a `poolIds` update that forces a fallback. Silent on
+  mount, so hosts only hear genuine transitions.
+- `resolveTokenIconUrl` export (plus the `TokenMetadataByAddress` type): the
+  widget's own icon-source order — config `iconUrl`, metadata service, ichi
+  naming guess — so hosts rendering their own token marks resolve identically.
+- `onStatusChange` prop: fires a lifecycle snapshot (`status`, `progress`, `txHash`,
+  `error`, `label`, rail geometry, and `walletPrompts`) on every transition, mirroring
+  the top progress rail — including errors and wallet rejections, which never appear
+  as a `status`. `walletPrompts.total/completed/active` exposes the SDK-owned provider
+  prompt plan for ERC20 approval, Permit2 authorization, and swap submission.
+- `AegisSwapProgressRail` export: the widget's animated top rail as a standalone
+  component hosts can mount on their own containers, themed via `--aegis-swap-accent`,
+  `--aegis-swap-danger`, and `--aegis-swap-success` (the rail CSS now carries literal
+  dark-theme fallbacks for use outside the widget root).
+- Host-tunable top rail tokens: `--aegis-rail-height`, `--aegis-rail-hold`, and
+  `--aegis-rail-fade` via the widget `style` prop. The success auto-reset reads the
+  computed hold/fade values so host-tuned terminal animations and status cleanup stay
+  synchronized.
+- The top rail now separates completion from activity: `completePct` tracks completed
+  wallet-provider prompts, while pending/mining shimmer always sweeps the full top
+  border instead of starting from the completed fill.
+- `networkOptions` prop plus `AegisSwapNetworkOption`/`AegisSwapNetworkIcon` types:
+  a display-only network menu list for previewing upcoming chains — non-selected
+  options render disabled by default with optional `status` text; a list without
+  the active chain gets it prepended; switching is not wired yet.
+- Public types `AegisSwapStatusSnapshot`, `AegisSwapWalletPromptProgress`,
+  `SubmitStatus`, `TransactionProgressState`, and the `isUserRejectedError` helper.
+
+### Changed
+- The branded header (`title`/`subtitle`) is now text-only: the Aegis logomark no longer
+  renders next to host-provided titles. Aegis attribution lives solely in the
+  "Powered by Aegis" footer.
+- The trade-details toggle no longer compensates ancestor scroll position when
+  expanding or collapsing; the panel expands in place.
+- Hover styles apply only on hover-capable devices (`@media (hover: hover)`), so taps
+  on touch screens no longer leave stuck hover states (raised tabs, rotated flip arrows).
+- The direction-flip arrows now spin when the direction actually flips (driven by a
+  `data-direction` attribute) instead of pre-playing the rotation on hover.
+- A busy CTA reads as working, not blocked: while approving/signing/submitting the
+  submit button keeps near-full opacity, shows a `progress` cursor, and runs a soft
+  sheen (`data-busy` attribute, motion-gated).
+- Status feedback eases in instead of popping: error/success lines and the explorer
+  link get a staggered fade-rise, and the success line opens with a self-drawing
+  check ("Swap complete · received ~…", previously an em dash).
+- Network-menu rows cascade in as the menu opens (30ms steps, reduced-motion safe),
+  and the menu's overlay shadow is re-tuned for the light theme.
+- Switching feels like one control: the pool tabs and the Exact/Max approval
+  segments glide a single active pill between options instead of cross-fading
+  two buttons, and the Sell/Buy token pills cross-fade when a switch retargets
+  them. New `--aegis-switch-dur`/`--aegis-spring` tokens (overridable via the
+  `style` prop) drive it; reduced-motion safe.
+- Concentric corner radii on nested chrome: pool tab rail, network menu, approval
+  segments, and the trade-details toggle now derive outer radius = inner + padding.
+- The trade-details panel sheds visual weight: approval segments and route actions
+  drop from 40px to 26px (keeping control-height touch targets via invisible
+  extensions), the route chip loses its divider hairlines and dead drop shadow, the
+  active pill is fill-only, and the setting rows tighten to 38px with unified 12px
+  labels.
+
+### Fixed
+- Keyboard focus no longer reshapes controls: the global `:focus-visible` rule forced
+  a 6px border-radius onto every focused element, visibly squaring the circular flip
+  button; the ring now follows each element's own radius.
+- The slippage input no longer triggers iOS Safari's focus auto-zoom (16px input font
+  on coarse pointers).
+- The network trigger's touch target is extended to ~44px without growing the chip.
+
+## [0.2.0] - 2026-06-05
+
+### Added
+- Premium embeddable swap surface with collapsible trade details, route chip, token icons,
+  Ethereum light/dark assets, and host-controlled execution details.
+- Exact-vs-max approval mode support, defaulting to exact approvals with Permit2 fallback.
+- Wallet, quote, allowance, balance, token icon, and submit hooks split out of the widget
+  entrypoint for a smaller public surface and easier testing.
+- Address, color, error, transaction progress, and widget view-state helpers with tests
+  organized under `tests/`.
+
+### Changed
+- The public widget entrypoint now delegates to focused widget modules instead of carrying
+  the entire implementation in `src/index.tsx`.
+- Quote and router encoding paths are hardened around calldata construction, stale quote
+  handling, and direct-pool route metadata.
+- Pool, wallet, metadata, and config inputs are normalized more defensively for host apps.
+- The default approval mode is `exact`; hosts can still opt into `max`.
+
+### Deprecated
+- `targets` remains available as a backwards-compatible alias for `poolIds` and will be
+  removed in `0.3.0`.
+
+## [0.1.3] - 2026-06-05
+
+### Added
+- Per-chain internal fee: `fee` field on `AegisSwapChainConfig`, so the output-token
+  fee applies to any bundled chain that sets one (mainnet keeps its 50 bps fee).
+- Package metadata (`license`, `repository`, `homepage`, `bugs`, `keywords`) and a
+  `LICENSE` file (MIT).
+- Test suite (Vitest) covering the quote/encoding money-path, formatting, and config
+  factories, plus a GitHub Actions CI workflow (typecheck + test + build).
+- `prepack` build hook and a `prepublishOnly` typecheck + test gate so published
+  tarballs always contain a fresh build.
+
+### Changed
+- `resolveWidgetFee` now reads the per-chain `fee` from the resolved chain config
+  instead of hardcoding Ethereum mainnet. Default mainnet behavior is unchanged.
+- Swap submission re-quotes immediately before building calldata so the on-chain
+  `amountOutMinimum`/`amountInMaximum` reflect the current price, not a stale quote.
+- After switching the wallet network, submission waits for the switch to settle and
+  continues the swap automatically instead of forcing a second click.
+- `viem` moved from `dependencies` to `peerDependencies` (it was already externalized
+  from the bundle).
+
+### Removed
+- `dist/` build artifacts are no longer committed to git (rebuilt on pack/publish).
+
+## [0.1.2] - 2026-06-04
+
+> Note: the published 0.1.2 tarball was cut before commit `31f01fa`
+> ("Round displayed token amounts"); that change first reaches consumers in the
+> next published version.
+
+### Added
+- Adjustable internal widget swap fee, fixed to Ethereum mainnet (50 bps).
+- Exact-output swaps and a 5-second quote refresh.
+- Per-chain Uniswap v4 contract config (`UNISWAP_V4_CONTRACTS_BY_CHAIN`).
+
+### Changed
+- Display token amounts are rounded (local only; not in the published 0.1.2 tarball).
+
+## [0.1.0] - 2026-06-04
+
+### Added
+- Initial embeddable direct-pool Aegis swap widget for WATER, WOOD, GRASS, and STONE.
+- Generic pool widget API; ERC-20 → Permit2 approval and Permit2 batch signing.
+
+[Unreleased]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.0...v0.1.2
+[0.1.0]: https://github.com/amplifi-liquidity/aegis-widget/releases/tag/v0.1.0

package/DESIGN.md

@@ -0,0 +1,77 @@
+# Design tokens
+
+The widget themes through CSS custom properties on the `.aegis-swap-widget` root
+(and the toast viewport). This file is the reference for the **public** tokens —
+the ones a host may override and depend on. Set them inline via the `style` prop,
+in a stylesheet on an ancestor, or per-toaster via `AegisSwapToaster`.
+
+Renaming or removing anything in the tables below is a breaking (major) change.
+Tokens prefixed `--aegis-_*` are internal and may change without notice.
+
+## Color
+
+The default palette is authored in **OKLCH**: neutrals are tinted toward the
+brand hue (~165) so the surface reads as one family, each step's lightness is
+matched to keep text contrast (subtle/muted stay ≥ 4.5:1 on the panel for 12px
+text), and no neutral is pure black or white. Derived accent tints
+(`--aegis-swap-accent-soft/-line/-glow/-ring`) are computed with
+`color-mix(in srgb, …)`, so a host can override `--aegis-swap-accent` with **any**
+CSS color (hex, `rgb()`, `oklch()`, …) and the whole accent system recomputes.
+
+| Token | Role |
+| --- | --- |
+| `--aegis-swap-accent` | CTA, selected pool, focus ring, links. Host's primary knob. |
+| `--aegis-swap-accent-text` | Text on the accent CTA. Auto-derived from `accentColor`; override with `accentTextColor`. |
+| `--aegis-swap-success` | Terminal success fill (rail, toast). |
+| `--aegis-swap-danger` | Error fill and inline error text. |
+| `--aegis-swap-bg` / `--aegis-swap-panel` / `--aegis-swap-panel-raised` / `--aegis-swap-panel-soft` | Surface ramp, darkest → most raised. |
+| `--aegis-swap-text` / `--aegis-swap-muted` / `--aegis-swap-subtle` | Text ramp, primary → tertiary. |
+| `--aegis-swap-border` / `--aegis-swap-border-strong` | Hairline and emphasized borders. |
+| `--aegis-swap-font-family` | Font family; the widget does **not** inherit the host font by default. |
+
+`theme="light"` swaps the surface/text/border/danger ramp; `accent`/`success`
+carry across both themes. `theme="auto"` follows `prefers-color-scheme`.
+
+## Motion
+
+All motion is CSS and respects `prefers-reduced-motion` automatically.
+
+| Token | Default | Role |
+| --- | --- | --- |
+| `--aegis-switch-dur` | `260ms` | Segmented-pill glide and Sell/Buy token swap. `0ms` disables. |
+| `--aegis-spring` | `cubic-bezier(0.22, 1, 0.36, 1)` | Easing for interactive state changes. |
+| `--aegis-ease` | `cubic-bezier(0.2, 0, 0, 1)` | Easing for entrances and transitions. |
+
+The pool-tab/approval-segment open is intentionally slower than the close
+(enter-slow, exit-fast); that asymmetry is by design, not a value to "correct".
+
+## Progress rail
+
+| Token | Default | Role |
+| --- | --- | --- |
+| `--aegis-rail-height` | `3px` | Rail thickness. |
+| `--aegis-rail-hold` | `3000ms` | How long the terminal state holds before fading. |
+| `--aegis-rail-fade` | `420ms` | Terminal fade-out duration. |
+
+`--aegis-rail-hold` / `--aegis-rail-fade` must be CSS time strings (`ms`/`s`):
+the widget reads the computed values at runtime to keep the success auto-reset in
+sync with the host-tuned animation. These also apply to the standalone
+`AegisSwapProgressRail`.
+
+## Toasts
+
+The toast viewport portals to `document.body`, so widget-root variables do **not**
+reach it — set these on `:root` or pass `AegisSwapToaster` props.
+
+| Token | Role |
+| --- | --- |
+| `--aegis-swap-toast-z` | Stacking context for the viewport. |
+| `--aegis-swap-toast-width` | Toast card width. |
+| `--aegis-swap-toast-offset-x` / `--aegis-swap-toast-offset-y` | Viewport inset from the chosen corner. |
+
+## Internal tokens
+
+`--aegis-r-sm/-md/-lg` (radii), `--aegis-seg-*` (segment chrome),
+`--aegis-swap-shell`, and any `--aegis-_*` primitive are internal implementation
+details. They are not part of the supported theming surface and may change
+between minor versions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aegis Swap Widget contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.