[Plan] Build packages/savings-widget: SDK integration, UI mapping, and execution checklist

[sirpy]

Plan: Build GoodWidget packages/savings-widget package

Context & Goals

This issue tracks the initial creation of packages/savings-widget in GoodWidget, enabling a GoodDollar savings experience:

• Integrates with @gooddollar/savings-sdk (logic: see GoodSDKs/packages/savings-sdks)
• Follows the flows and UI/UX of the existing web component (GoodSDKs/packages/savings-widget), reimplemented as a React app/widget
• Designs any missing UI using GoodWalletV2 Swap section’s design language (GoodWalletV2/src/sections/Swap)
• Uses and extends local packages/ui components as much as possible

---

1. Reference: Key Files & Features

A. GoodSDKs/packages/savings-widget (Web Component Implementation)

• src/GooddollarSavingsWidget.ts:
  Core UI, flows, and state management (deposit, withdraw tabs, provider connection, display of savings balances, tab switching, deposit/withdraw input forms, success/error/loading UI)
• README.md:
  Shows main flows, required props (web3Provider, connectWallet action)
• Uses Lit/LitElement, but the UI state shows:
  • Tabbed interface: Deposit/Withdraw
  • Onboarding: Wallet connect
  • Shows user balance, accepts user input/amount
  • Executes deposit/withdraw using SDK, provides visual feedback (pending/success/error)
  • Uses a compact card/container with themeable styling, responsive design, and clear feedback

B. GoodDollar/GoodWalletV2/src/sections/Swap/ (Design System/Composites)

• SwapView.tsx, SwapOverlay.tsx:
  Shows multi-step workflow, modal/sheet design, styled input, token selectors, confirmation slider, and various feedback mechanisms.
• Component patterns:
  • Asset (token) select box
  • Amount input box
  • Multi-step panel or overlay (with back/close)
  • Loading and error overlays/toasts
• CSS - shows padding, layout, responsive design tokens.

C. GoodWidget/packages/ui (Reusable Primitives)

• src/index.ts:
  Reusable Card, Button, Spinner, Toast, Drawer, Icon, Input, Select, Dialog, theme presets, ActionSheet, TokenInput, etc.
• src/theme.ts, src/presets.ts:
  Theming tokens mapped to GoodWalletV2, brand-compliant by default.

---

2. Imports & Implementation Guidance

• All GoodDollar org packages may be locally imported via monorepo/workspace references (even if private/unpublished).
• Strict: No copy-pasting code—import and compose only!
• Use live SDK APIs (@gooddollar/savings-sdk) for protocol logic.

---

3. New Component & Flow Mapping

Core Widget Structure

• SavingsWidgetContainer (main panel/card, themed)
• DepositTab (deposit flow)
• WithdrawTab (withdraw flow)
• WalletConnectPrompt (if !provider)
• AmountInput (reuse if present, extend if not; see Swap/AmountInputBox)
• TokenSelect (reuse if present, otherwise create; see Swap/AssetSelectBox)
• ActionButton (import from ui)
• Feedback/Toast (import from ui)
• Spinner/LoadingState (import from ui)
• Success/Error/EmptyState panels (compose with Card/Text/Icon from ui)
• Storybook for all primitives/extensions

Component Placement

• If primitive is generic/reusable: Add to packages/ui
• If specific to savings-widget: Add to packages/savings-widget

---

4. Required Flows, States, and Behaviors

• On mount, widget fetches savings data for connected user (via SDK)
• Shows onboarding if provider/wallet is not connected
• Deposit flow:
  • Enter amount
  • Confirm and sign via provider
  • Shows pending/error/success states
• Withdraw flow:
  • Enter amount (only up to balance)
  • Confirm/sign/pending/success error
• General:
  • Responsive styling (card layout)
  • All async states use skeleton/spinner
  • All errors handled with feedback (Toast/Alert)
  • Reuse design tokens/components for all UI

---

5. Execution Plan

1. Scaffold packages/savings-widget structure (index/entry, Card container, hooks)
2. Add peer/local dependency on @gooddollar/savings-sdk
3. Map minimal viable UI by recreating Lit webcomponent flows in React using local primitives
4. Compose new flows by reusing primitives from packages/ui
5. For missing UI, spec & build components based on GoodWalletV2 Swap section (add to ui if reusable)
6. Ensure provider/wallet logic is passed as props for host integration (mirroring webcomponent)
7. Write Storybook coverage for every new primitive
8. Document all public types/props
9. Add tests (unit + flows)
10. Provide example usage at package root

---

6. Acceptance Criteria

• Widget builds with all flows working (deposit, withdraw, onboarding)
• All UI state flows are mapped from reference webcomponent
• Protocol logic fully wired via imported @gooddollar/savings-sdk
• No org code copied; only import/reuse
• All new primitives in packages/ui if reusable
• UI components match brand/design tokens (theme/preset)
• Storybook and tests complete
• Usage/demo included

---

7. Human-Reviewer Checklist

• No code copy from org packages—check imports!
• All required UI feedback flows present
• Theme and design tokens are respected
• Documentation/story/test coverage complete

---

This plan is based only on the first page of code search results. For full reference, see:

• GoodSDKs/packages/savings-widget
• GoodWalletV2/src/sections/Swap
• GoodWidget/packages/ui