-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
9 changed files
with
80 additions
and
26 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
# Architecture | ||
|
||
The UI for the wallet provider selector is made available through a [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) Custom elements are easy to integrate in just about any web project. Methods detailed in [Component API](./component-api.md) are provided to interact with the selector. | ||
|
||
## Reactivity | ||
|
||
The selector uses [Solid](https://www.solidjs.com/) for component logic and reactivity. Solid has a build-time compiler and no runtime, ideal for creating performant and compact shareable components. | ||
|
||
## Building the custom element | ||
|
||
Solid, like other popular component frameworks, is usually used to manipulate the DOM. To encapsualte the selector's logic into a custom element, the [`solid-element`](https://github.com/solidjs/solid/tree/main/packages/solid-element#readme) package is used. | ||
|
||
## Styles | ||
|
||
Styles for the selector are in the form of inline styles or `<style>` tags in the source. There doesn't seem to be a better solution for managing styles when building a custom element. | ||
|
||
Styling solutions usually have a tight integration with the build process and emit CSS assets or add code that inserts `<style>` tags into the `<header>`. In general, these approaches don't work with custom elements which are defined at run time: there's nothing to inject the styles into during the build process. Dedicated frameworks like Polymer and Stencil exist to overcome this issue, although they currently have fewer Github stars and seem to use more component complex abstractions. | ||
|
||
The selector uses a [CSS reset](https://github.com/sindresorhus/modern-normalize/blob/main/modern-normalize.css) that has been [adapted for custom elements](https://www.colorglare.com/css-resets-and-global-styles-in-web-components-c71fcea86dbd). | ||
|
||
Styles may break when using Portals. By default, they render elements directly into the body and outside of the influence of the styles defined within the custom element. | ||
|
||
The `DM Sans` font used by the selector is added to the document's `<head>` in a `<link>` tag and referenced in the CSS reset. Global fonts can be referenced within custom elements, although importing a font within a custom element [doesn't seem to be working](https://stackoverflow.com/q/78204762/1494725). | ||
|
||
## Components | ||
|
||
The selector is built with [Ark UI](https://ark-ui.com/) components. They're headless components, meaning they're functional, yet carry no styles and can be styled as needed. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
[Architecture](./architecture.md) | ||
|
||
[Selector API](./selector-api.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
# Selector API | ||
|
||
Interaction with the selector is done by means of custom events. The selector sets up event listeners when it mounts, and convenience methods are available to interact with the selector. | ||
|
||
For convenience, all the events are emitted to and listened from `window`. | ||
|
||
## Request flow | ||
|
||
Below is how third party code would interact with the selector. | ||
|
||
```mermaid | ||
sequenceDiagram | ||
Third party code->>Window: Register "select" event handler. | ||
Third party code->>Window: Register "cancel" event handler. | ||
Third party code->>Window: Emit "open" event.<br/>Event payload contains config.<br/>Config contains list of wallet providers. | ||
Window ->> Selector: Trigger "open" handler. | ||
Selector ->> Selector: Process user interaction. | ||
alt User makes selection | ||
Selector->>Window: Emit "select" event.<br/>Event payload contains provider ID. | ||
Window ->>Third party code: Trigger "select" handler. | ||
else Users cancels | ||
Selector->>Window: Emit "cancel" event. | ||
Window ->>Third party code: Trigger "cancel" handler. | ||
end | ||
``` | ||
|
||
For convenience, the `selectWalletProvider()` method is provided to perform the flow above. It takes care of setting up the necessary event handlers, returns the result as a `Promise` and cleans up the event handlers when done. | ||
|
||
## A note on Typescript | ||
|
||
The event names used by the selector are defined in [`selector-events.ts`](../src/selector-events.ts), which is necessary to satisfy the compiler. |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters