Update docs

docs/selector-api.md

@@ -6,7 +6,9 @@ For consistency and practicality, all the events are emitted to and listened fro
 
 ## Loading the selector
 
-Before use, the selector needs to be registered as a custom element and insterted into the DOM. The `loadSelector()` helper function facilitates both these actions, ensuring the selector is properly registered and added to the page.
+Before use, the selector needs to be registered as a custom element and inserted into the DOM. The `loadSelector()` helper function facilitates both these actions, ensuring the selector is properly registered and added to the page.
+
+To remove the selector and all event listeners, use `cleanup()`.
 
 ## Events API
 
@@ -16,6 +18,8 @@ Events are used to interact with the selector.
 
 - **open** `"sats-connect_wallet-provider-selector_open"`: The selector will open and display the providers as configured using custom event's `details` property, which is expected to be of type [`Config`](../src/lib/utils.ts)
 - **close** `"sats-connect_wallet-provider-selector_close"`: The selector will close if open.
+- **wallet open** `"sats-connect_wallet-provider-selector_walletOpen"`: The third party interacting with the selector may optionally notify the selector when the user has their wallet open or visible. The selector will display a message indicating that an operation is in progress.
+- **wallet close** `"sats-connect_wallet-provider-selector_walletClose"`. The third party interacting with the selector may optionally notify when the user has closed their wallet or it is no longer visible. The selector will stop showing that an operation is in progress if it previously received a "wallet open" event.
 
 ### Emitted events
 
@@ -41,9 +45,20 @@ sequenceDiagram
         Selector->>Window: Emit "cancel" event.
         Window ->>Third party code: Trigger "cancel" handler.
     end
+    Third party code ->>Window: Emit "close" event.
+    Window ->> Selector: Trigger "close" handler.
+    Selector ->> Selector: Close
+
 ```
 
-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.
+Note that the selector must be explicitly closed when the user makes a selection. This allows for the display of a "wallet open" message to the user by the app integrating the selector.
+
+For convenience, the following methods are available to interact with the selector:
+
+- `selectWalletProvider()`: Opens the selector and returns a promise with the user's selection, or rejects if the user closes the selector.
+- `walletOpen()`: Informs the selector that the user's wallet is open. The selector will display a message to the user indicating that an operation is in progress.
+- `walletClose()`: Informs the selector the user's wallet is closed.
+- `close()`: Closes the selector.
 
 ## A note on Typescript