docs: update connect docs (#619)

Co-authored-by: janniks <[email protected]>

.github/mlc_config.json

@@ -24,10 +24,6 @@
     {
       "pattern": "identity.foundation"
     },
-    {
-      "pattern": "learn-the-basics",
-      "comment": "// todo: remove once https://github.com/hirosystems/docs/pull/616 is merged"
-    },
     {
       "pattern": "stackoverflow.com/questions/tagged/stacks\\-blockchain\\+or\\+clarity\\-lang",
       "comment": "// Returns a 403 sometimes"

docs/stacks.js/connect.mdx

@@ -3,44 +3,37 @@ import TabItem from '@theme/TabItem';
 
 # Stacks Connect
 
-<div className="gap-3 flex flex-wrap mb-6">
+<div className="gap-3 flex flex-wrap mb-8">
   <a
-    className="inline-block bg-neutral-200 hover:bg-neutral-100 rounded-md text-sm text-neutral-700 px-2 py-1 hover:text-neutral-700 hover:no-underline transition-colors"
+    className="inline-block rounded-md text-sm px-2 py-1 border border-solid border-neutral-200 bg-neutral-100 text-neutral-700 hover:text-neutral-800 hover:no-underline dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-400 dark:hover:text-neutral-300"
     href="https://connect.stacks.js.org"
   >Stacks Connect Reference <span className="i-radix-icons-link-2 align-text-bottom text-lg"></span></a>
-  <a
-    className="inline-block bg-violet-300 hover:bg-violet-200 rounded-md text-sm text-violet-800 px-2 py-1 hover:text-violet-800 hover:no-underline transition-colors"
-    href="https://discord.com/channels/621759717756370964/1022879438515486791"
-  >Discord Support <span className="i-bi-discord align-text-bottom text-lg"></span></a>
 </div>
 
 Stacks Connect is a frontend library that allows developers to build Stacks-ready web applications.
 
-What are the main things you can do with Stacks Connect?
-
-- 📸 Prompt a user to sign transactions with their Stacks wallet
-- 🛂 Provide the web-app with the user's Stacks and Bitcoin addresses
-
-## Start from a template with Stacks Connect included
-
-Get started [from a frontend template](/stacksjs-starters), by running the following command:
+<div className='flex justify-center mt-8 mb-10'>
+  <div className="p-4 pb-0 min-w-72 rounded-lg border border-solid border-neutral-200 bg-neutral-100 dark:border-neutral-700 dark:bg-neutral-800">
+    <h3 className='text-lg flex gap-1 items-center'><span className="i-radix-icons-lightning-bolt"/>Quick start!</h3>
+    ```sh
+    npm create stacks
+    ```
+  </div>
+</div>
 
-```sh
-npm create stacks
-```
+What are the main use-cases of Stacks Connect?
 
-After you have your project set up, you can start using Stacks Connect. Jump ahead to [Interacting with the wallet](#3-interacting-with-the-wallet) to see more code examples.
+- Prompt a user to sign transactions with their Stacks wallet
+- Provide the web-app with the user's Stacks and Bitcoin addresses
 
 ---
 
-## Manually add Stacks Connect to your project
+## Add Stacks Connect to your project
 
 ### 1. Add the dependency
 
 Add the `@stacks/connect` dependency to your project using your favorite package manager.
 
-
-
 <Tabs><TabItem value="npm" label="npm">
 ```sh
 npm install @stacks/connect
@@ -75,6 +68,8 @@ export const userSession = new UserSession({ appConfig }); // we will use this e
 Connecting the wallet is a very simple form of authentication.
 This process gives the web-app information about a wallet account (selected by the user).
 
+![Connect Modal](/img/stacks-connect-modal.png)
+
 The snippet below lets your web-app trigger the wallet to open and _authenticate_ an account.
 If no wallet is installed, an informational modal will be displayed in the web-app.
 
@@ -193,10 +188,11 @@ const myPostCondition = makeStandardSTXPostCondition(
   postConditions: [ myPostCondition ],
 // ...
 ```
+:::note
+For more examples on constructing different kinds of post-conditions read the [Post-Conditions Guide of Stacks.js](https://github.com/hirosystems/stacks.js/tree/main/packages/transactions#post-conditions).
+:::
 
-> For more examples on constructing different kinds of post-conditions read the [Post-Conditions Guide of Stacks.js](https://github.com/hirosystems/stacks.js/tree/main/packages/transactions#post-conditions).
-
-##### Post-Condition Modes
+#### Post-Condition Modes
 
 If post-conditions `postConditions: [ ... ]` are specified, they will ALWAYS be checked by blockchain nodes.
 If ANY conditions fails, the transaction will fail.
@@ -206,3 +202,20 @@ The _Post-Condition Mode_ only relates to transfers of assets, which were not sp
 - `PostConditionMode.Deny` will fail the transaction if any unspecified assets are transferred
 - `PostConditionMode.Allow` will allow unspecified assets to be transferred
 - In both cases, all `postConditions` will be checked
+
+---
+
+## Manual
+
+The following methods show the Connect modal (to select a wallet) and do a certain action:
+
+- [`showConnect`](https://connect.stacks.js.org/functions/_stacks_connect.showConnect) to request account info
+- [`showSTXTransfer`](https://connect.stacks.js.org/functions/_stacks_connect.showSTXTransfer) to send an STX transfer
+- [`showContractCall`](https://connect.stacks.js.org/functions/_stacks_connect.showContractCall) to call a deployed Clarity contract
+- [`showContractDeploy`](https://connect.stacks.js.org/functions/_stacks_connect.showContractDeploy) to deploy a new Clarity contract
+- [`showSignTransaction`](https://connect.stacks.js.org/functions/_stacks_connect.showSignTransaction) to sign an arbitrary Stacks transaction
+- [`showProfileUpdate`](https://connect.stacks.js.org/functions/_stacks_connect.showProfileUpdate) to update a BNS profile
+- [`showSignMessage`](https://connect.stacks.js.org/functions/_stacks_connect.showSignMessage) to sign a message
+- [`showSignStructuredMessage`](https://connect.stacks.js.org/functions/_stacks_connect.showSignStructuredMessage) to sign a structured message
+- [`showPsbt`](https://connect.stacks.js.org/functions/_stacks_connect.showPsbt) to sign a Bitcoin PSBT
+- [`disconnect`](https://connect.stacks.js.org/functions/_stacks_connect.disconnect) to clear the currently selected wallet (and allow choosing again next `showXyz`)

docs/stacks.js/faq.md

@@ -12,9 +12,9 @@ In addition, the Stacks blockchain supports an "allow" or "deny" mode for evalua
 
 Post-conditions are less a part of Clarity (the language), but more a part of transactions.
 Users could send the otherwise-identical transaction (Example: contract-call, executing a function on the blockchain) with OR without different post-conditions, in allow OR deny mode.
-The PCs are managed by the user/wallet/app that's creating the tx; so they are a bit different from the other "safety" features of clarity (Example: asserts, try, https://book.clarity-lang.org/ch06-00-control-flow.html)
+The PCs are managed by the user/wallet/app that's creating the tx; so they are a bit different from the other "safety" features of clarity — for example [`asserts` and `try`](https://book.clarity-lang.org/ch06-00-control-flow.html).
 
 ### How to fix the BigInt support when using Stacks.js?
 
 BigInt support is available in most modern browsers, but some bundlers try to optimize them incorrectly. If you are targeting browsers that are too outdated, building an application with Stacks.js dependencies might fail.
-To solve this set your project `browserslist` to the following [package.json](https://github.com/hirosystems/stacks.js-starters/blob/efb93261b59494f4eb34a7cb5db5d82a84bd3b7c/templates/template-react/package.json#L34-L40).
+To solve this set your project `browserslist` to [this package.json](https://github.com/hirosystems/stacks.js-starters/blob/efb93261b59494f4eb34a7cb5db5d82a84bd3b7c/templates/template-react/package.json#L34-L40).

docs/stacks.js/includes/_stacks.js-starters-note.mdx

@@ -3,5 +3,5 @@
   <a class="text-neutral-500 dark:text-neutral-100" href="https://docs.hiro.so/stacksjs-starters">
     Stacks.js Starters
   </a>
-  , which come with Stacks Connect pre-installed 🌐
+  , which come with Stacks Connect pre-installed
 </div>

docs/stacks.js/index.md

@@ -1,26 +1,29 @@
 # Stacks.js Overview
 
-<div className="gap-3 flex flex-wrap mb-6">
+<div className="gap-3 flex flex-wrap mb-2">
   <a
-    className="inline-block bg-neutral-200 hover:bg-neutral-100 rounded-md text-sm text-neutral-700 px-2 py-1 hover:text-neutral-700 hover:no-underline transition-colors"
-    href="https://stacks.js.org"
-  >Stacks.js Reference <span className="i-radix-icons-link-2 align-text-bottom text-lg"></span></a>
+    className="inline-block rounded-md text-sm px-2 py-1 border border-solid border-neutral-200 bg-neutral-100 text-neutral-700 hover:text-neutral-800 hover:no-underline dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-400 dark:hover:text-neutral-300"
+    href="https://www.hiro.so/search?query=Stacks.js"
+  >Blogposts <span className="i-radix-icons-file-text align-text-bottom text-lg"></span></a>
   <a
-    className="inline-block bg-neutral-200 hover:bg-neutral-100 rounded-md text-sm text-neutral-700 px-2 py-1 hover:text-neutral-700 hover:no-underline transition-colors"
-    href="https://connect.stacks.js.org"
-  >Stacks Connect Reference <span className="i-radix-icons-link-2 align-text-bottom text-lg"></span></a>
+    className="inline-block rounded-md text-sm px-2 py-1 border border-solid border-neutral-200 bg-neutral-100 text-neutral-700 hover:text-neutral-800 hover:no-underline dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-400 dark:hover:text-neutral-300"
+    href="https://www.youtube.com/watch?v=SGrbeoCSHs0"
+  >Videos <span className="i-bi-person-video align-text-bottom text-lg"></span></a>
   <a
-    className="inline-block bg-violet-300 hover:bg-violet-200 rounded-md text-sm text-violet-800 px-2 py-1 hover:text-violet-800 hover:no-underline transition-colors"
+    className="inline-block rounded-md text-sm px-2 py-1 border border-solid border-neutral-200 bg-neutral-100 text-neutral-700 hover:text-neutral-800 hover:no-underline dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-400 dark:hover:text-neutral-300"
     href="https://discord.com/channels/621759717756370964/1022879438515486791"
   >Discord Support <span className="i-bi-discord align-text-bottom text-lg"></span></a>
+</div>
+
+<div className="gap-3 flex flex-wrap mb-8">
   <a
-    className="inline-block bg-cyan-300 hover:bg-cyan-200 rounded-md text-sm text-cyan-800 px-2 py-1 hover:text-cyan-800 hover:no-underline transition-colors"
-    href="https://www.hiro.so/search?query=Stacks.js"
-  >Blogposts <span className="i-radix-icons-file-text align-text-bottom text-lg"></span></a>
+    className="inline-block rounded-md text-sm px-2 py-1 border border-solid border-neutral-200 bg-neutral-100 text-neutral-700 hover:text-neutral-800 hover:no-underline dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-400 dark:hover:text-neutral-300"
+    href="https://stacks.js.org"
+  >Stacks.js Reference <span className="i-radix-icons-link-2 align-text-bottom text-lg"></span></a>
   <a
-    className="inline-block bg-blue-300 hover:bg-blue-200 rounded-md text-sm text-blue-800 px-2 py-1 hover:text-blue-800 hover:no-underline transition-colors"
-    href="https://www.youtube.com/watch?v=SGrbeoCSHs0"
-  >Videos <span className="i-bi-person-video align-text-bottom text-lg"></span></a>
+    className="inline-block rounded-md text-sm px-2 py-1 border border-solid border-neutral-200 bg-neutral-100 text-neutral-700 hover:text-neutral-800 hover:no-underline dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-400 dark:hover:text-neutral-300"
+    href="https://connect.stacks.js.org"
+  >Stacks Connect Reference <span className="i-radix-icons-link-2 align-text-bottom text-lg"></span></a>
 </div>
 
 Stacks.js is an SDK for building on the Stacks blockchain.

docs/stacks.js/learn-the-basics.md → docs/stacks.js/learn-the-basics.mdx

@@ -1,8 +1,11 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Learning the Stacks.js Basics
 
-<div class="bg-neutral-200 rounded-lg text-sm text-neutral-700 p-3">Looking to building Stacks-ready web applications? [Read more on Stacks Connect](/stacks.js/connect)</div>
+<p class="p-3 rounded-lg bg-neutral-100 text-neutral-500 dark:bg-neutral-800 dark:text-neutral-400">Looking to build a Stacks-ready web application? <a class="text-neutral-600 hover:text-neutral-700 dark:text-neutral-300 dark:hover:text-neutral-200" href="/stacks.js/connect">Read more on Stacks Connect</a></p>
 
-<div class="mb-9"></div>
+<div class="mb-16"></div>
 
 To introduce the different functionality offered by Stacks.js, we'll walk through a few examples and concepts important to building on the Stacks blockchain.
 
@@ -31,8 +34,8 @@ const network = new StacksMainnet({ url: 'https://www.mystacksnode.com/' });
 
 ## Accounts and Addresses
 
-:::info Connect 🌐
-For web apps, you can request the user's address via Stacks Connect. [Read more](https://connect.stacks.js.org/modules/_stacks_connect#quotconnectquot-aka-authentication-showconnect)
+:::info Connect
+For web applications, you can request the user's address via Stacks Connect. [Read more](/stacks.js/connect)
 :::
 
 Stacks.js uses the concept of an "account" to represent a user's identity on the blockchain. An account is identified by a unique address. The address is derived from the account's public key, which is derived from the account's private key.
@@ -60,8 +63,7 @@ const testnetAddress = getStxAddress({ account, transactionVersion: TransactionV
 
 The following shows how to create a simple transaction (STX transfer) using Stacks.js in different environments.
 
-### Using Connect 🌐
-
+<Tabs><TabItem value="connect" label="Using Connect">
 ```js
 import { openSTXTransfer } from '@stacks/connect';
 import { StacksTestnet } from '@stacks/network';
@@ -78,9 +80,7 @@ openSTXTransfer({
   onCancel: () => console.log('User canceled'),
 });
 ```
-
-### Using a private key 🔑
-
+</TabItem><TabItem value="private" label="Using a private key">
 For full manual transaction signing, we need to provide the sender's private key.
 Treat the private key as a secret and never expose it to the public!
 
@@ -94,19 +94,15 @@ const tx = await makeSTXTokenTransfer({
   senderKey: 'c3a2d3...0b1c2', // private key (typically derived from a mnemonic)
 });
 ```
-
-<!-- todo -->
-<!-- [Read more](./installing.md) about transaction signing with Stacks.js. -->
+</TabItem></Tabs>
 
 ## Anchor Mode / Block Type
 
 In the examples above, we used `AnchorMode.Any` to indicate that the transaction can be "mined" in different ways.
 Stacks has two types of blocks: microblocks and (anchor) blocks.
 
 - **Microblocks** (off-chain) are faster, but less reliable. Microblocks can be confirmed quickly but are not final until the microblock is included in an anchor block.
-- **Anchor Blocks** (on-chain) are the normal Stacks block. They are slower, but more reliable. Anchor blocks are final and cannot be reverted.
-
-<!-- todo: Read more about how decentralized blocks work -->
+- **Anchor Blocks** (on-chain) are the normal Stacks blocks. They are slower, but more reliable. Anchor blocks are final and cannot be reverted.
 
 ```js
 // AnchorMode options
@@ -118,15 +114,13 @@ anchorMode: "offChainOnly" | "onChainOnly" | "any",
 In Stacks, transactions can have "post conditions".
 These are additional security to ensure the transaction was executed as expected.
 
-Post conditions can't say anything about the end-state after a transaction, but they can verify that certain things happened during the transaction.
-
-More precisely, post conditions can verify that:
+More precisely, adding post conditions to a transaction can ensure that:
 
 - STX tokens were transferred from an address
 - FTs/NFTs we transferred from an address
 
 :::caution
-Post conditions aren't perfect and can't always guarantee the receival of FTs/NFTs, since they only check senders.
+Post conditions aren't perfect. They can't say anything about the end-state after a transaction. So, they can't guarantee the receival of FTs/NFTs, since they only check for sending.
 :::
 
 An example adding a post condition (of an address sending 1000 uSTX).
@@ -142,7 +136,7 @@ const tx = await makeContractCall({
 });
 ```
 
-### Post Condition "Mode"
+### Post Condition **Mode**
 
 _...aka "allow transfer of unspecified assets?"_
 
@@ -159,9 +153,9 @@ By default, transactions are set to `Deny` mode for additional security.
 
 ## Broadcasting
 
-:::info Connect 🌐
-For web apps via Stacks Connect, the users' wallet will broadcast the transaction and return a txid.
-[Read more](https://connect.stacks.js.org/modules/_stacks_connect)
+:::info Connect
+For web applications, the users' wallet can broadcast transactions created via Stacks Connect.
+[Read more](/stacks.js/connect)
 :::
 
 A finalized transaction can be broadcasted to the network or serialized (to a byte representation) using Stacks.js.

docusaurus.config.js

@@ -1,4 +1,4 @@
-const lightCodeTheme = require('prism-react-renderer').github;
+const lightCodeTheme = require('./src/theme/hiro-light-code.js');
 const darkCodeTheme = require('./src/theme/hiro-dark-code.js');
 
 // With JSDoc @type annotations, IDEs can provide config autocompletion

src/css/custom.css

@@ -93,11 +93,12 @@
   --ifm-heading-font-weight: var(--ifm-font-weight-normal);
   --ifm-button-font-weight: var(--ifm-font-weight-semibold);
 
-  --ifm-global-radius: 2px;
+  --ifm-global-radius: 4px;
   --ifm-code-border-radius: 5px;
   --ifm-global-shadow-lw: 0 1px 2px 0 rgba(0, 0, 0, 0.07);
-  --ifm-code-font-size: 81.25%;
+
   --ifm-alert-border-left-width: 0px;
+  --ifm-alert-padding-vertical: 10px;
 
   --ifm-tabs-padding-vertical: 4px;
   --ifm-tabs-padding-horizontal: 8px;
@@ -502,7 +503,11 @@ a.menu__link.menu__link--sublist.menu__link--sublist-caret::after {
 }
 
 .tabs-container .margin-top--md {
-  margin-top: 0 !important;
+  margin-top: 10px !important;
+}
+
+.tabs-container .tabs__item {
+  border-bottom-width: 2px;
 }
 
 /* CONTENT MARKDOWN ELEMENTS ================================================ */

src/theme/hiro-dark-code.js

@@ -19,7 +19,7 @@ module.exports = {
     {
       types: ['builtin', 'changed', 'keyword', 'interpolation-punctuation'],
       style: {
-        color: '#BC812E',
+        color: '#D69B47',
       },
     },
     {