diff --git a/.changeset/widget-react-dev-stack.md b/.changeset/widget-react-dev-stack.md new file mode 100644 index 0000000..529cf44 --- /dev/null +++ b/.changeset/widget-react-dev-stack.md @@ -0,0 +1,5 @@ +--- +'@usdh-kit/widget': patch +--- + +Align widget development React dependencies with the wallet stack used by the demo gallery. diff --git a/README.md b/README.md index e67f85e..a230529 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ TypeScript SDK for USDH on Hyperliquid. USDH is the native stablecoin on Hyperliquid, issued by Bridge and designed by Native Markets, with 50% of reserve revenue routed to the Hyperliquid Assistance Fund. `@usdh-kit/sdk` ships the retail-side plumbing (pair resolution, signing, transport) so apps and bots can convert into USDH without writing the Hyperliquid action layer themselves. `@usdh-kit/widget` is an embeddable React component on top of the SDK so dapps can drop in a swap form in a few lines. - **Source:** [github.com/sumfxn/usdh-kit](https://github.com/sumfxn/usdh-kit) +- **Builder gallery:** [`apps/demo`](./apps/demo) — SDK surfaces, live read-only market board, examples, and widget showcase. - **Issues:** [github.com/sumfxn/usdh-kit/issues](https://github.com/sumfxn/usdh-kit/issues) - **USDH:** [usdh.com](https://usdh.com) (issued by [Bridge](https://bridge.xyz), designed by [Native Markets](https://www.nativemarkets.com)) - **Hyperliquid:** [hyperliquid.xyz](https://hyperliquid.xyz) · [docs](https://hyperliquid.gitbook.io/hyperliquid-docs) diff --git a/apps/demo/README.md b/apps/demo/README.md index b3d016f..c229814 100644 --- a/apps/demo/README.md +++ b/apps/demo/README.md @@ -1,6 +1,8 @@ -# demo +# builder gallery -Public Next.js dApp showcasing usdh-kit. Wallet connection (wagmi + ConnectKit) and swap UI land in follow-up PRs; this is the scaffold. +Public Next.js app for the `usdh-kit` builder gallery. The first screen is a +reference console for USDH/HIP-4 builders: SDK surfaces, read-only market data, +example paths, and the embeddable swap widget. ## Run locally @@ -11,14 +13,31 @@ pnpm --filter @usdh-kit-apps/demo dev Then open http://localhost:3000. -## Stack +## Data policy -- Next.js 15 App Router + Turbopack -- Tailwind CSS -- React 19 +The gallery is safe by default: -## Roadmap +- live data is read-only and server-side +- live reads happen at request time, not during `next build` +- no `/exchange` calls are made for gallery data +- no wallet connection is required to render the page +- if Hyperliquid reads fail, the page falls back to sample data -- PR2: wagmi + ConnectKit wiring, kit-context hook -- PR3: swap UI (amount input, quote display, bridge + swap flow) -- PR4: design polish (typography, motion, error states) +The widget section remains interactive and uses the connected wallet only when a +user explicitly starts the widget flow. + +## Stack note + +The demo uses Next.js 15 backport releases with React 18. Next 15 was already in +the app before the gallery work; React 18 keeps the wallet stack aligned with +ConnectKit's published peer dependencies. + +## Validation + +```sh +pnpm --filter @usdh-kit-apps/demo typecheck +pnpm --filter @usdh-kit-apps/demo build +``` + +The root `pnpm build` and `pnpm typecheck` commands also include this app so the +public gallery cannot drift outside CI. diff --git a/apps/demo/next-env.d.ts b/apps/demo/next-env.d.ts index 1b3be08..830fb59 100644 --- a/apps/demo/next-env.d.ts +++ b/apps/demo/next-env.d.ts @@ -1,5 +1,6 @@ /// /// +/// // NOTE: This file should not be edited // see https://nextjs.org/docs/app/api-reference/config/typescript for more information. diff --git a/apps/demo/next.config.ts b/apps/demo/next.config.ts index ebb5252..d4b848c 100644 --- a/apps/demo/next.config.ts +++ b/apps/demo/next.config.ts @@ -8,9 +8,8 @@ const repoRoot = resolve(demoDir, '../..') const config: NextConfig = { reactStrictMode: true, - experimental: { - typedRoutes: true, - }, + typedRoutes: true, + outputFileTracingRoot: repoRoot, webpack: (webpackConfig) => { webpackConfig.resolve ??= {} webpackConfig.resolve.extensionAlias = { @@ -23,6 +22,7 @@ const config: NextConfig = { '@usdh-kit/sdk$': resolve(repoRoot, 'packages/sdk/src/index.ts'), '@usdh-kit/widget$': resolve(repoRoot, 'packages/widget/src/index.ts'), '@usdh-kit/widget/styles.css$': resolve(repoRoot, 'packages/widget/src/styles.css'), + 'pino-pretty': false, } return webpackConfig }, diff --git a/apps/demo/package.json b/apps/demo/package.json index 8a5edef..cd4fd82 100644 --- a/apps/demo/package.json +++ b/apps/demo/package.json @@ -14,16 +14,17 @@ "@usdh-kit/sdk": "workspace:*", "@usdh-kit/widget": "workspace:*", "connectkit": "1.8.2", - "next": "15.1.0", - "react": "19.0.0", - "react-dom": "19.0.0", + "lucide-react": "1.14.0", + "next": "15.5.18", + "react": "18.3.1", + "react-dom": "18.3.1", "viem": "2.21.55", "wagmi": "2.14.6" }, "devDependencies": { "@types/node": "22.10.2", - "@types/react": "19.0.1", - "@types/react-dom": "19.0.2", + "@types/react": "18.3.18", + "@types/react-dom": "18.3.5", "autoprefixer": "10.4.20", "postcss": "8.4.49", "tailwindcss": "3.4.17", diff --git a/apps/demo/src/app/globals.css b/apps/demo/src/app/globals.css index 2590280..d41fcda 100644 --- a/apps/demo/src/app/globals.css +++ b/apps/demo/src/app/globals.css @@ -8,14 +8,32 @@ html, body { - background: #ffffff; + background: #f7f7f6; color: #171717; } +html { + scroll-behavior: smooth; +} + +body { + text-rendering: optimizeLegibility; +} + +::selection { + background: #171717; + color: #ffffff; +} + @media (prefers-color-scheme: dark) { html, body { - background: #0a0a0a; + background: #080808; color: #f5f5f5; } + + ::selection { + background: #f5f5f5; + color: #080808; + } } diff --git a/apps/demo/src/app/layout.tsx b/apps/demo/src/app/layout.tsx index 0205759..04708a0 100644 --- a/apps/demo/src/app/layout.tsx +++ b/apps/demo/src/app/layout.tsx @@ -1,4 +1,4 @@ -import type { Metadata } from 'next' +import type { Metadata, Viewport } from 'next' import type { ReactNode } from 'react' import { Providers } from '../components/Providers' @@ -6,14 +6,19 @@ import './globals.css' import '../../../../packages/widget/src/styles.css' export const metadata: Metadata = { - title: 'usdh-kit demo', - description: 'Swap stables into USDH on Hyperliquid, end-to-end demo', + title: 'usdh-kit builder gallery', + description: 'SDK and widget reference gallery for USDH builders on Hyperliquid', +} + +export const viewport: Viewport = { + width: 'device-width', + initialScale: 1, } export default function RootLayout({ children }: { children: ReactNode }) { return ( - + {children} diff --git a/apps/demo/src/app/page.tsx b/apps/demo/src/app/page.tsx index cb78b94..f659da4 100644 --- a/apps/demo/src/app/page.tsx +++ b/apps/demo/src/app/page.tsx @@ -1,50 +1,521 @@ +import { + ArrowRight, + BookOpen, + Boxes, + Braces, + ChartNoAxesColumn, + CircleDot, + Coins, + ExternalLink, + GitBranch, + Landmark, + LineChart, + type LucideIcon, + Network, + PackageCheck, + Radar, + Route, + Terminal, + WalletCards, +} from 'lucide-react' + import { ConnectButton } from '../components/ConnectButton' import { SwapSection } from '../components/SwapSection' +import { type GalleryBookLevel, loadGallerySnapshot } from '../lib/gallery-data' -export default function Home() { - return ( -
-
-

- usdh-kit -

- -
-

- Swap stables into USDH on Hyperliquid. -

-
- -
-
- - - Yaugourt - - + +export const dynamic = 'force-dynamic' + +const surfaces: Array<{ + title: string + eyebrow: string + body: string + icon: LucideIcon +}> = [ + { + title: 'Discover USDH pairs', + eyebrow: 'Track 1', + body: 'Spot markets where USDH is base or quote, with live pair names and token orientation.', + icon: Radar, + }, + { + title: 'Read outcomes', + eyebrow: 'Track 2', + body: 'Experimental read-only outcome metadata, encoded side coins, books, and mids.', + icon: ChartNoAxesColumn, + }, + { + title: 'Trade USDH spots', + eyebrow: 'Track 3', + body: 'USDH-scoped order placement, cancellation, open orders, and status reads.', + icon: LineChart, + }, + { + title: 'Move through flows', + eyebrow: 'Track 4', + body: 'USDC -> USDH, USDH -> USDC, HyperEVM -> Core, and Core -> HyperEVM helpers.', + icon: Route, + }, +] + +const primitives: Array<{ + title: string + detail: string + icon: LucideIcon + code: string +}> = [ + { + title: 'Market discovery', + detail: 'Find USDH surfaces without hand-parsing Hyperliquid metadata.', + icon: Network, + code: "const pairs = await kit.listPairs({ quote: 'USDH' })", + }, + { + title: 'Quote and route', + detail: 'Preflight source-chain choice before asking users to sign anything.', + icon: GitBranch, + code: "const route = await kit.getRoute({ from: 'USDC', amount })", + }, + { + title: 'Outcome reads', + detail: 'Keep outcome support experimental and read-only until settlement is verified.', + icon: Boxes, + code: 'const markets = await kit.listOutcomeMarkets()', + }, + { + title: 'Targeted orders', + detail: 'Place and cancel orders only on USDH-bearing spot pairs.', + icon: Braces, + code: "await kit.placeOrder({ pair: 'USDH/USDC', side: 'sell', size: '25' })", + }, + { + title: 'Bridge and swap', + detail: 'Route, bridge when needed, then submit the HyperCore swap.', + icon: WalletCards, + code: "await kit.bridgeAndSwap({ from: 'USDC', amount })", + }, + { + title: 'Bridge out', + detail: 'Submit Core -> HyperEVM sendAsset and return a clear submitted state.', + icon: Landmark, + code: "await kit.bridgeFromCore({ asset: 'USDC', amount })", + }, +] + +const examples = [ + ['Node swap', 'Smallest CLI path for quote, route, bridge, swap.'], + ['Payment webhook', 'Convert received USDC into USDH after checkout settlement.'], + ['Treasury rebalance', 'Keep a USDH allocation above a configurable floor.'], + ['Builder gallery', 'Use these cards as the visual reference for new examples.'], +] as const + +export default async function Home() { + const snapshot = await loadGallerySnapshot() + const generatedAt = new Intl.DateTimeFormat('en', { + hour: '2-digit', + minute: '2-digit', + second: '2-digit', + timeZoneName: 'short', + }).format(new Date(snapshot.generatedAt)) + + return ( +
+
+ +
+ +
+ + +
+
+
+ + {snapshot.mode === 'live' ? 'Live mainnet read-only' : 'Sample data fallback'} +
+

+ USDH builder primitives for Hyperliquid. +

+

+ `usdh-kit` is the focused SDK and widget for builders who want to discover, route, + trade, and display USDH surfaces without becoming a generic Hyperliquid integration + team. +

+ +
+ +
+
+ SDK surface + {generatedAt} +
+
+ + + + +
+
+
+ +
+ +
+ {surfaces.map((surface) => ( + + ))} +
+
+ +
+
+ +
+ {snapshot.pairs.map((pair) => ( +
+
+
{pair.label}
+
+ {pair.name} / index {pair.index} +
+
+ + USDH {pair.role} + + {pair.mid} +
+ ))} +
+
+ +
+ +
+ + +
+
+ {snapshot.notes.join(' / ')} +
+
+
+ +
+
+ +
+ {snapshot.outcomes.map((outcome) => ( +
+
+
{outcome.name}
+
{outcome.coin}
+
+
+ + {outcome.sides[0]} + + + {outcome.sides[1]} + +
+
+ ))} +
+
+ +
+
+ + + + + +
+
+
+ +
+ +
+ +
+
+ +
+ +
+ {primitives.map((primitive) => ( + + ))} +
+
+ +
+ +
+ {examples.map(([title, body]) => ( +
+ +

{title}

+

+ {body} +

+
+ ))} +
+
+ +
+ Built by Sumfxn and Yaugourt for USDH builders. + release gated separately +
+
) } + +function StatusDot({ live }: { live: boolean }) { + return ( +