How to build a Client UI - document ui-kit

[dckc]

There is a gap in our documentation on docs.agoric.com in that we don't sufficiently explain/walk-through how a developer is supposed to a) build a client UI and b) connect it to a smart contract they've build on the Agoric chain.

https://docs.agoric.com/guides/getting-started/contract-rpc.html exists but it's more conceptual and background context - which while important to the reader/developer isn't a step-by-step guide on how to actually build the client UI.

Dapp-offer-up is a functional example contract and client UI that our docs reference in 'Getting Started' section (https://docs.agoric.com/guides/getting-started/) of our docs and in the 'Smart Contract Basics' section (https://docs.agoric.com/guides/zoe/contract-walkthru.html). It stands to reason that it the 'how to build a client UI' guide uses same smart contract for continuity and consistency. It will be easier for the developer/reader to follow along.

This ticket tracks the effort to document the step-by-step process through which a developer builds client UI (using dapp offer up as an example) and connect it to the offer up smart contract for full end-to-end functionality.

Requirements:

• Must reference dapp-offer-up contract and tie in with 'Getting Started' and 'Smart Contract Basics' such that it reads in a cohesive and easy-to-follow manner
• Must include instructions around how to query an RPC node to get data from contract
• Must reference utilization of UI components to simplify the UI building experience for developers
• Must use UI Kit (if UI kit explainer is needed, this needs to be incorporated)
• Must be written in step-by-step sequential format that is easy to follow

Acceptance Criteria:

• To ensure the how-to guide achieves our goal of being easy-to-follow and digest for developers - we will request review of @kbennett2000 (and maybe others) to follow along to elicit feedback. Iterations may be needed in order for us learn and improve on this.
• This will need to succeed before pushing to production docs.agoric.com

User Story: As a Developer I should be able to read the docs and get 2 things:

1. Understanding of how to build a Client UI and make it interact with my deployed smart contract
2. Get a repo/bundle of a sample Client UI that I could use to create my own Client

ui-kit and the basics of writing a dapp must be fully documented.

---

earlier idea:

• reorg "Smart Wallet Dapp Architecture"?

Tasks

Beta Give feedback

1. Sam to propose how-to page structure

[dckc]

the smart wallet architecture page has a bunch of details that are kinda abstracted by ui-kit

[dckc]

#1035 is not merged.

[otoole-brendan]

Updated the ticket body with more context, approach and high level requirements. @samsiegart to provide how-to page structure based on his experience building client UIs.

[dckc]

The short "how to make an offer" video developed in #976 seems worth keeping.

I'd like to see

1. one that goes from a blank create-react-app skeleton to making queries.
2. explainer-how-to-make-an-offer.md and its video... maybe update it a bit to flow from the 1st one?

[samsiegart]

@dckc I hadn't seen that make-an-offer page before, that's good stuff. We're planning a full tutorial-style thing with multiple pages, starting from:

• Scaffold and harden the app (I'm going to use vite instead of CRA but similar deal)
• Set up wallet connection and read purses
• Use chainStorageWatcher to read the contract/vstorage
• Use the wallet connection to make an offer and handle the updates (will look pretty much like that make-an-offer page, maybe will replace it).

Each section would walk through with code snippets and shell commands so the user can build along, link to relevant docs that explain the concepts/components as they come up, and we'd have different branches in dapp-offer-up to serve as checkpoints for each section, with the last checkpoint being pretty much identical to dapp-offer-up@main. WDYT?

[dckc]

@dckc ... We're planning ...

• Scaffold and harden ...
• Set up wallet connection and read purses
• Use chainStorageWatcher to read the contract/vstorage
• Use the wallet connection to make an offer ...

... WDYT?

yes, that's very close to what I had in mind.

meanwhile, note https://docs.agoric.com/guides/getting-started/explainer-how-to-make-an-offer.html landed.

[dckc]

oh... re wallet connection before chainStorageWatcher... that seems a little awkward: won't most dapps want to show some stuff from the chain before users connect their wallet?

[samsiegart]

oh... re wallet connection before chainStorageWatcher... that seems a little awkward: won't most dapps want to show some stuff from the chain before users connect their wallet?

That's true, we might want to switch the order of things. After the AgoricProvider is added, you can get the chainStorageWatcher without connecting to the wallet. It's easy enough to show that the dapp can load some stuff before the user clicks "connect" though.

[dckc]

• Scaffold and harden the app (I'm going to use vite instead of CRA but similar deal)

ah... right.. dapp-offer-up started with vite

Agoric/dapp-offer-up@716e95c