@trustless-work/blocks 1.1.1 → 1.1.2

package/README.md

@@ -1,13 +1,22 @@
-<p align="center"> <img src="https://github.com/user-attachments/assets/5b182044-dceb-41f5-acf0-da22dea7c98a" alt="CLR-S (2)"> </p>
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/5b182044-dceb-41f5-acf0-da22dea7c98a" alt="Trustless Work Blocks" />
+</p>
 
-# Trustless Work <a href="https://www.npmjs.com/package/@trustless-work/blocks" target="_blank">React Library</a>
+# Trustless Work <a href="https://www.npmjs.com/package/@trustless-work/blocks" target="_blank">React Blocks</a>
 
-A production-ready set of React blocks for integrating Trustless Work's escrow and dispute resolution flows. It ships:
+Production‑ready React blocks for integrating Trustless Work's escrow and dispute resolution flows into your dApp.
 
-- UI blocks (cards/tables/dialogs/forms) to list and manage escrows
-- Providers for API config, wallet context, dialogs and amounts
+It includes:
+
+- UI blocks (cards, tables, dialogs, forms) to list and manage escrows
+- Providers for API config, wallet context, dialogs and amount calculations
 - TanStack Query hooks for fetching and mutating escrows
-- Wallet-kit helpers and error handling utilities
+- Wallet‑kit helpers and error handling utilities
+
+## Requirements
+
+- Node.js `>= 18.17`
+- React 18 / Next.js 13+ (App Router recommended)
 
 ## Installation
 
@@ -20,18 +29,21 @@ yarn add @trustless-work/blocks
 npx trustless-work init
 ```
 
-What init does:
+**What `init` does:**
 
 - Installs shadcn/ui components (prompted)
-- Installs required deps: @tanstack/react-query, @trustless-work/escrow, axios, zod, react-hook-form, @creit.tech/stellar-wallets-kit, react-day-picker, etc.
-- Creates .twblocks.json with your UI base alias (default: "@/components/ui")
-- Optionally wires providers into Next.js `app/layout.tsx`
+- Installs required deps: `@tanstack/react-query`, `@trustless-work/escrow`, `axios`, `zod`,
+  `react-hook-form`, `@creit.tech/stellar-wallets-kit`, `react-day-picker`, etc.
+- Creates `.twblocks.json` with your UI base alias (default: `"@/components/ui"`)
+- Optionally wires providers into your Next.js `app/layout.tsx`
 
-Environment:
+**Environment:**
 
-- Create `NEXT_PUBLIC_API_KEY` in your env. The library uses `TrustlessWorkProvider` with `development` base URL by default.
+- Create `NEXT_PUBLIC_API_KEY` in your env. The library uses `TrustlessWorkProvider` with the
+  `development` base URL by default.
 
-Tutorial at <a href="https://dapp.trustlesswork.com" target="_blank">backoffice's landing</a>
+> For a full walkthrough and screenshots, check the tutorial at
+> <a href="https://dapp.trustlesswork.com" target="_blank">the backoffice landing</a>.
 
 ## Quick Start
 
@@ -52,11 +64,8 @@ npx trustless-work add providers
 ```tsx
 // app/layout.tsx
 import { ReactQueryClientProvider } from "@/components/tw-blocks/providers/ReactQueryClientProvider";
-import {
-  TrustlessWorkProvider,
-  ReactQueryClientProvider,
-  EscrowProvider,
-} from "@/components/tw-blocks/providers/TrustlessWork";
+import { TrustlessWorkProvider } from "@/components/tw-blocks/providers/TrustlessWork";
+import { EscrowProvider } from "@/components/tw-blocks/providers/EscrowProvider";
 import { WalletProvider } from "@/components/tw-blocks/wallet-kit/WalletProvider";
 
 export default function RootLayout({
@@ -173,34 +182,48 @@ export function DeployButton({ address }: { address: string }) {
 
 ## Available Blocks
 
-In order to see all of them, just run this script:
-
-```shell
+To discover all available blocks, run:
 
+```bash
 npx trustless-work list
+```
+
+### Scaffold top‑level groups
 
-# Scaffold top-level groups
+```bash
 npx trustless-work add providers
 npx trustless-work add wallet-kit
 npx trustless-work add handle-errors
 npx trustless-work add helpers
 npx trustless-work add tanstack
 npx trustless-work add escrows
+```
+
+### Escrows by role
 
-# Escrows by role
+```bash
 npx trustless-work add escrows/escrows-by-role
 npx trustless-work add escrows/escrows-by-role/table
 npx trustless-work add escrows/escrows-by-role/cards
+```
+
+### Escrows by signer
 
-# Escrows by signer
+```bash
 npx trustless-work add escrows/escrows-by-signer
 npx trustless-work add escrows/escrows-by-signer/table
 npx trustless-work add escrows/escrows-by-signer/cards
+```
+
+### Escrow details (optional standalone)
 
-# Escrow details (optional standalone)
+```bash
 npx trustless-work add escrows/details
+```
+
+### Single‑release flows
 
-# Single-release flows
+```bash
 npx trustless-work add escrows/single-release
 npx trustless-work add escrows/single-release/initialize-escrow
 npx trustless-work add escrows/single-release/approve-milestone
@@ -212,13 +235,13 @@ npx trustless-work add escrows/single-release/resolve-dispute
 npx trustless-work add escrows/single-release/update-escrow
 ```
 
-### Escrows
+### Escrows UI summary
 
-- Cards and tables to browse escrows (by role or by signer) with filters, pagination, and sort
+- Cards and tables to browse escrows (by role or by signer) with filters, pagination, and sorting
 - Detail dialog with actions gated by roles and escrow flags
-- Dialogs/forms for single-release lifecycle (initialize, fund, approve, change status, release, dispute, resolve, update)
+- Dialogs/forms for the single‑release lifecycle (initialize, fund, approve, change status, release, dispute, resolve, update)
 
-Using cards (by role):
+**Using cards (by role):**
 
 ```tsx
 import { EscrowDialogsProvider } from "@/components/tw-blocks/providers/EscrowDialogsProvider";
@@ -233,14 +256,23 @@ export default function Screen() {
 }
 ```
 
+## Configuration Checklist
+
 Make sure to:
 
-1. Set `NEXT_PUBLIC_API_KEY` and run the app against the correct environment (the provider defaults to `development`).
-2. Configure your UI base imports. CLI uses `.twblocks.json` `uiBase` to replace `__UI_BASE__`. If your UI alias differs, pass `--ui-base`:
+1. **Set `NEXT_PUBLIC_API_KEY`** and run the app against the correct environment (the provider defaults to `development`).
+2. **Configure your UI base imports.** The CLI uses `.twblocks.json` `uiBase` to replace `__UI_BASE__`.  
+   If your UI alias differs, pass `--ui-base`:
+
    ```bash
    npx trustless-work add escrows/escrows-by-role/cards --ui-base "@/components/ui"
    ```
-3. Wrap your app with all providers in the order: `ReactQueryClientProvider` → `TrustlessWorkProvider` → `WalletProvider` → `EscrowProvider`.
+
+3. **Wrap your app with all providers** in this order:
+
+   ```text
+   ReactQueryClientProvider → TrustlessWorkProvider → WalletProvider → EscrowProvider
+   ```
 
 ## Best Practices
 
@@ -283,11 +315,11 @@ Make sure to:
 
 ## Contributing
 
-We welcome contributions! Please read our contributing guidelines before submitting pull requests.
+We welcome contributions! Please open an issue or pull request in the repository and make sure to follow any existing contributing guidelines.
 
 ## License
 
-MIT License - see LICENSE file for details
+MIT License – see the `LICENSE` file for details.
 
 # Maintainers | [Telegram](https://t.me/+kmr8tGegxLU0NTA5)