[PLAN] Create a streaming widget

[L03TJ3]

[PLAN] Create a streaming widget

Parent issue: #26

Required states, flows, and behaviors

• Wallet connection states:
  • Custodial fixture flow and injected EIP-1193 flow are both supported.
  • Connected/disconnected and wrong-chain states are handled before write actions.
• Streams tab behaviors:
  • Create/update flow via setFlowrate (setStream behavior) for active outgoing stream setup.
  • Active streams list (incoming/outgoing/all toggle) and historical stream list/pagination.
  • Empty, loading, error, and success states for list/read/write operations.
• Pool memberships tab behaviors:
  • List GDA pool memberships and per-pool connected status.
  • Claim incoming distributions and reflect pending/success/error states.
• Balances tab behaviors:
  • Show Super Token balance for selected token.
  • Show SUP reserve data only on Base (hide/disabled state on non-Base chains).
• Single-widget composition:
  • Use WidgetTabs to segment the above features inside one widget shell.
  • Keep GoodWalletV2 visual direction (spacing/typography/colors/effects) through goodWalletV2Preset + widget-local components.

Execution plan

1. Scope + references mapping

   • Parent scope: [Feature]: Create a streaming widget #26 (this issue is planning only, no implementation execution).
   • GoodWidget references:
     • packages/ui/src/components/WidgetTabs.tsx (tab container behavior)
     • packages/citizen-claim-widget/src/CitizenClaimWidget.tsx (current widget/adaptor structure)
     • packages/citizen-claim-widget/src/adapter.ts (state/actions adapter pattern)
     • examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidget.stories.tsx (custodial/injected story flow)
     • tests/widgets/citizen-claim-widget/* (widget smoke testing convention)
   • GoodSDKs references:
     • packages/streaming-sdk/README.md
     • packages/streaming-sdk/src/streaming-sdk.ts
     • packages/streaming-sdk/src/gda-sdk.ts
     • packages/streaming-sdk/src/types.ts
     • apps/demo-streaming-app/src/App.tsx (functional flow reference only)
   • GoodWalletV2 design references:
     • src/sections/Swap/SwapView.tsx
     • src/sections/Swap/components/* (amount/token/route layout patterns)
     • src/sections/Home/components/ActivityHistory/ActivityHistory.tsx
     • src/sections/Home/components/ActivityHistory/ActivityHistoryItem.tsx
   • Superfluid visual references from parent issue screenshots:
     • Active stream(s) overview image:
       • https://github.com/user-attachments/assets/bd7cd510-9e40-41bd-8fd7-f5709915ff91
     • Creating/updating stream image:
       • https://github.com/user-attachments/assets/faa35f05-ddf0-44ce-8f10-29ef266222d5

2. Package and dependency setup

   • Create new widget package: packages/streaming-widget (not packages/ui, since feature-specific).
   • Add package dependency on @goodsdks/streaming-sdk and existing GoodWidget packages:
     • @goodwidget/core
     • @goodwidget/ui
     • @goodwidget/embed
   • Export component + element/register entries matching existing widget packaging conventions.

3. Runtime architecture

   • Implement StreamingWidget.tsx as provider-wrapped shell.
   • Implement adapter.ts to encapsulate data fetch + mutations:
     • stream write/read methods
     • GDA membership/distribution methods
     • balance/reserve reads
   • Keep wallet/provider and environment handling at adapter boundary.

4. Component mapping (new widget-local components vs reusable UI)

   • Widget-local (in packages/streaming-widget/src):
     • StreamingWidgetShell
     • StreamingSetFlowForm
     • StreamOverviewCard
     • StreamHistoryList
     • PoolMembershipList
     • PoolClaimRow
     • BalanceSummaryCard
   • Promote to packages/ui only if proven cross-widget reusable in at least one existing widget (otherwise keep local).

5. UI design translation (from issue [Feature]: Create a streaming widget #26 references)

   • Streams tab: active overview and history layout
     • Use card-based list rows with token icon/symbol, counterparty address (shortened/ENS if available), flow rate, status badge, streamed total, start timestamp, and row action control.
     • Provide top-level segment filters for All, Incoming, and Outgoing before list content.
     • Support list states with matching structure: loading skeleton rows, empty state message with icon, and retry-capable error state.
   • Stream create/update UX
     • Use a dedicated create/update surface (inline panel, modal, or drawer) with explicit title (Create Stream / Update Stream).
     • Include fields for token selection, recipient address, flow rate input, and rate period selector.
     • Include a computed preview block for expected outgoing amount and affordability feedback before submission.
     • Include clear primary/secondary actions and inline validation/error messaging.
     • Show explicit tx lifecycle feedback (pending/success/failure) after submission.
   • Pool memberships tab
     • Render memberships as list cards including pool identity, membership state, claimable amount, and claim action.
     • Claim action must expose disabled/loading/success/error states in-row.
     • Provide deterministic empty/error states consistent with Streams tab styling.
   • Balances tab
     • Render a summary card for Super Token balance as primary value.
     • Render SUP reserve as a separate section only on Base; on non-Base chains show hidden or explicit disabled state with explanatory helper copy.
     • Include network context indicator and manual refresh affordance.
   • Global styling and interaction direction
     • Match GoodWalletV2 patterns for spacing, typography hierarchy, card density, and visual emphasis by applying goodWalletV2Preset token/theme primitives.
     • Follow ActivityHistory-style list readability and Swap-style form affordances.
     • Keep transitions between loading/content/action-result states smooth and consistent across all tabs.

6. Storybook + Playwright plan

   • Add stories under examples/storybook/src/stories/streaming-widget/:
     • injected wallet scenario
     • custodial fixture scenario
     • empty/error/loading states for each tab
   • Add Playwright smoke tests under tests/widgets/streaming-widget/:
     • tab navigation + key states
     • create/update flow happy path and failure path
     • pool claim action state changes
     • balance/reserve visibility by chain
   • Include widget-state screenshots in tests/widgets/streaming-widget/test-results/.

7. Validation and rollout

   • Run project build/lint + targeted storybook/playwright checks for the new widget flow.
   • Keep implementation changes scoped to streaming widget and related story/test wiring only.

acceptance criteria

• A new sub-issue plan exists without modifying parent issue body content.
• Planned implementation introduces packages/streaming-widget using @goodsdks/streaming-sdk.
• Plan explicitly covers:
  • set stream/create-update behavior
  • active + historical stream views
  • GDA pool memberships + claim action
  • SUP + reserve balance behavior (Base-only for reserve)
  • wallet support for custodial + injected providers
• Plan maps concrete references from GoodWidget, GoodSDKs, and GoodWalletV2.
• Plan includes translated UI instructions from issue [Feature]: Create a streaming widget #26 image references.
• Plan includes storybook and Playwright coverage expectations aligned with repository conventions.

human-reviewer checklist

• Sub-issue title follows [PLAN] ... format.
• Description starts with [PLAN] ....
• Parent issue [Feature]: Create a streaming widget #26 is linked.
• Required sections are present (states/flows, execution plan, acceptance criteria, human-reviewer checklist).
• Reference files from all requested repositories are explicitly mapped.
• UI reference screenshots from [Feature]: Create a streaming widget #26 are translated into written implementation guidance.
• Component placement rationale (widget-local vs packages/ui) is explicit.
• Plan is implementation-ready but does not execute code changes yet.

[edehvictor]

Hello @L03TJ3, can I work on this. I'm an active contributor in the GoodDollar ecosystem. Can kindly know the tier.

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: This may be caused by a repository ruleset violation. See granting bypass permissions for the agent, or please contact support if the issue persists. (Request id: B818:58F48:10C9B38:127E40F:6A0C2DFA)

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: This may be caused by a repository ruleset violation. See granting bypass permissions for the agent, or please contact support if the issue persists. (Request id: B818:58F48:10D2D97:1288033:6A0C2E57)