@reclack/walletkit 0.1.1 → 0.2.0

package/README.md

@@ -125,12 +125,9 @@ this package, so the tag and its attributes autocomplete without a wrapper.
 | `chain-id` | number | none | Require this chain, switching the wallet if needed |
 | `intent` | `address`, `balance`, comma separated | `address` | What to return |
 | `keep-alive` | present or absent | absent | Stay connected after resolving |
-| `theme-mode` | `light`, `dark`, `system` | `system` | Which palette to wear |
-| `brand` | `#rrggbb` | Reclack's | Your colour, worn by the primary action |
-| `radius` | CSS length | `10px` | Corner radius |
-| `font` | CSS font stack | inherited | Type |
 | `asset-base` | URL path | `/images/` | Where the wallet logos are served from |
 | `api-url` | URL | Reclack's | A different deployment, such as a sandbox |
+| `theme` | `WalletKitTheme`, as a property | none | Colours, radius and type. See [Theming](#theming) |
 
 ### Properties
 
@@ -164,6 +161,39 @@ by setting any `--rkw-` token on the element.
 `variant="modal"` is a native `<dialog>`, so focus trapping, Esc to close, an
 inert background and a backdrop all come from the browser.
 
+## The network picker
+
+The chain something settles on, as a second element. A checkout asks which
+chain before it asks which wallet, and a form collecting a settlement address
+asks which chain without connecting anything at all.
+
+```html
+<reclack-network
+  networks="base,polygon,ethereum,solana"
+  value="base"
+  asset-base="/wallets/"
+></reclack-network>
+```
+
+```js
+document.querySelector('reclack-network')
+  .addEventListener('change', (event) => {
+    console.log(event.detail.network)   // 'polygon'
+  })
+```
+
+| Attribute | Values | Default | What it does |
+| --- | --- | --- | --- |
+| `networks` | comma separated names | none | The chains to choose between |
+| `value` | one of them | the first | The chain chosen, and settable |
+| `disabled` | present or absent | absent | Stops it while something is in flight |
+| `label` | text | `Network` | Empty renders no label at all |
+| `asset-base` | URL path | `/images/` | Where the chain marks are served from |
+
+It carries the same theme attributes as the picker, and `element.value` reads
+and writes the choice. Chain artwork ships in `assets/` beside the wallet
+artwork; a chain with no mark shows its initial rather than a broken image.
+
 ## The kit
 
 The element makes its own kit, and you never have to touch one. Reach for the
@@ -288,6 +318,35 @@ createWalletKit({
 })
 ```
 
+On the element, set it as a property:
+
+```ts
+element.theme = { mode: 'dark', brand: '#ff6600', radius: '14px' }
+```
+
+### Theme attributes
+
+A nested object will not fit in an attribute, so the four values a plain HTML
+page is most likely to want have one each. They build the same theme:
+
+| Attribute | Theme field | Values | Default |
+| --- | --- | --- | --- |
+| `theme-mode` | `mode` | `light`, `dark`, `system` | `system` |
+| `brand` | `brand` | `#rrggbb` | Reclack's |
+| `radius` | `radius` | CSS length | `10px` |
+| `font` | `fontFamily` | CSS font stack | inherited |
+
+```html
+<reclack-connect theme-mode="dark" brand="#ff6600" radius="14px"></reclack-connect>
+```
+
+**A theme wins over all four.** Setting the `theme` property, or sharing a kit
+that already carries a theme, makes these attributes ignored and uses the
+theme whole. That is deliberate: a checkout that themed its kit should not
+have to theme every picker inside it as well.
+
+### Following the reader's system
+
 The resolved mode and the tokens are part of the state you are already
 subscribed to, so the picker follows the reader's system without a second
 listener:

package/dist/element/element.d.ts

@@ -68,6 +68,14 @@ export declare class ReclackConnectElement extends HTMLElement {
     /** Hands this element a kit to share instead of the one it would make. */
     useKit(kit: WalletKit): void;
 }
+/**
+ * Puts the stylesheet in the shadow root.
+ *
+ * One constructed sheet shared by every instance, so a page with several
+ * pickers parses the CSS once. A `<style>` element where that is not
+ * supported, which costs a parse per element and is correct everywhere.
+ */
+export declare function adoptStyles(root: ShadowRoot): void;
 /** Registers the element, once, under its own name. */
 export declare function defineWalletElement(tagName?: string): void;
 export interface ConnectWalletOptions extends ConnectRequest {

package/dist/element/index.d.ts

@@ -2,3 +2,4 @@ export type { ReclackConnectAttributes, ReclackConnectProps, } from './attribute
 export { ATTRIBUTES, attributesOf, EVENTS } from './props.js';
 export type { ConnectProps } from './props.js';
 export { connectWallet, defineWalletElement, ReclackConnectElement, type ConnectWalletOptions, } from './element.js';
+export { defineNetworkElement, ReclackNetworkElement, } from './network-element.js';

package/dist/element/network-element.d.ts

@@ -0,0 +1,24 @@
+import type { WalletKitTheme } from '@reclack/walletkit';
+/**
+ * The chain picker, as an element of its own.
+ *
+ * Separate from `<reclack-connect>` because the two answer different
+ * questions and a page often wants one without the other: a checkout asks
+ * which chain before it asks which wallet, and a dashboard form asks which
+ * chain an address is for without connecting anything at all.
+ */
+export declare class ReclackNetworkElement extends HTMLElement {
+    #private;
+    static tagName: string;
+    static get observedAttributes(): string[];
+    constructor();
+    /** The full theme, for anything an attribute cannot hold. */
+    set theme(theme: WalletKitTheme | undefined);
+    /** The chain currently chosen, which is also settable. */
+    get value(): string;
+    set value(network: string);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+}
+export declare function defineNetworkElement(tagName?: string): void;

package/dist/element/ui/assets.d.ts

@@ -3,5 +3,7 @@ export declare function AssetProvider({ base, children, }: {
     base: string;
     children: ComponentChildren;
 }): import("preact").JSX.Element;
+/** Where this element serves its artwork from, for anything drawing a mark. */
+export declare function useAssetBase(): string;
 /** The artwork for a wallet, or nothing where this package carries none. */
 export declare function useWalletLogo(): (id: string) => string | undefined;

package/dist/element/ui/network-select.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The chain something settles on.
+ *
+ * A closed trigger rather than a stacked list: the number of payable chains
+ * grows with every deployment, and a list that grows without bound pushes
+ * whatever follows it below the fold.
+ *
+ * A combobox over a button and a listbox rather than a native `<select>`,
+ * which cannot carry a chain mark or a search field.
+ */
+export declare function NetworkSelect({ networks, value, disabled, label, onChange, }: {
+    networks: string[];
+    value: string;
+    disabled?: boolean;
+    label?: string;
+    onChange: (network: string) => void;
+}): import("preact").JSX.Element;