@trading-game/design-intelligence-layer 0.14.0 → 0.15.0

package/AGENTS.md

@@ -57,7 +57,7 @@ cp node_modules/@trading-game/design-intelligence-layer/guides/rules/design-syst
 3. **Design principles and accessibility first** — every screen must reflect the 8 design principles and meet the accessibility standards (WCAG 2.1 AA). Run both checklists before shipping.
 4. **No separate installs** — do not install `lucide-react`, `tailwindcss`, or other bundled dependencies separately.
 5. **After a version bump** — re-copy the rules file into `.cursor/rules/`, check for stale local component copies, and align them with the package.
-6. **Blocks are playground-only** — Blocks (e.g. NavBar) appear in the playground's Blocks tab but are **not** exported from the package. Do not try to import them. To build a block pattern in a consuming project, compose it manually using package components and design tokens. See `guides/design-system-guide/trading-game-ds-guide.md` Section 8.5.
+6. **Blocks are first-class exports** — Blocks (Hero, Auth, FAQ, NavBar, HeaderNavigation, OpenPositions, Result) are exported from the package the same as primitives. Import them by name and pass data via props. See the `## Blocks` section below for the full catalog.
 
 ---
 
@@ -69,3 +69,142 @@ cp node_modules/@trading-game/design-intelligence-layer/guides/rules/design-syst
 - Personas: `node_modules/@trading-game/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md`
 - Brand voice: `node_modules/@trading-game/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md`
 - Full agent rules: `node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc`
+
+---
+
+## Blocks
+
+The package ships eight opinionated, composed blocks alongside the UI primitives. Each block is a single `import` away and accepts data via props. Variants are modeled as a `variant` / `layout` / `mode` prop on one block, not as separate components.
+
+### `HeroBlock`
+
+Marketing hero section with centred or split-column layout.
+
+```tsx
+import { HeroBlock } from "@trading-game/design-intelligence-layer"
+
+<HeroBlock
+  layout="centered"                                        // "centered" | "split"
+  tagline={{ label: "What's new", suffix: "v2.0" }}
+  heading="Solve your customer's main problem"
+  body="One or two sentences expanding on the value prop."
+  primaryCta={{ label: "Get started", onClick: ... }}
+  secondaryCta={{ label: "Learn more", onClick: ... }}    // split layout only
+/>
+```
+
+### `AuthBlock`
+
+Sign-in / sign-up form with OAuth providers, divider, email input, terms, and cross-link.
+
+```tsx
+import { AuthBlock } from "@trading-game/design-intelligence-layer"
+
+<AuthBlock
+  mode="sign-in"                                          // "sign-in" | "sign-up"
+  logoSrc="/path/to/brand-icon.svg"
+  providers={["google", "telegram", "x"]}                 // default: all three
+  onSubmit={({ email }) => { ... }}
+  crossLinkHref="/auth/signup"
+/>
+```
+
+### `FAQBlock`
+
+Eyebrow + heading + intro + accordion + optional "Need more help" card.
+
+```tsx
+import { FAQBlock } from "@trading-game/design-intelligence-layer"
+
+<FAQBlock
+  layout="desktop"                                        // "desktop" | "mobile"
+  items={[{ value: "q1", question: "...", answer: "..." }, ...]}
+  intro={<>Optional intro paragraph with a <Link>link</Link>.</>}
+  helpCard={{ title: "Need more help?", body: "...", ctaLabel: "Contact us" }}
+/>
+```
+
+### `NavBarBlock`
+
+Responsive marketing nav with brand mark, link buttons, sign-in/up CTAs, and an internal mobile drawer.
+
+```tsx
+import { NavBarBlock } from "@trading-game/design-intelligence-layer"
+
+<NavBarBlock
+  brand={{ fullLogoSrc: "...", iconLogoSrc: "...", alt: "Brand" }}
+  links={[{ label: "Products" }, { label: "Docs" }, ...]}
+  signIn={{ onClick: ... }}
+  signUp={{ onClick: ... }}
+/>
+```
+
+### `HeaderNavigationBlock`
+
+In-app trading header (back · badge · balance · history · action slot). History icon supports an overlaid count badge in `bg-primary`.
+
+```tsx
+import { HeaderNavigationBlock } from "@trading-game/design-intelligence-layer"
+
+<HeaderNavigationBlock
+  onBack={() => router.back()}
+  badge={{ label: "Demo", variant: "fill-warning" }}
+  balance={{ amount: "1000.00", currency: "USDT" }}
+  history={{ count: 5, onClick: openHistorySheet }}        // count 0 hides badge; >99 shows "99+"
+  actions={<SoundToggleButton />}
+/>
+```
+
+### `OpenPositionsBlock`
+
+Responsive Sheet (desktop) / Drawer (mobile) containing a list of game positions. Positions are a discriminated union by `kind`: `"rise-fall" | "swipe" | "box-o" | "digits"`.
+
+```tsx
+import { OpenPositionsBlock, Position } from "@trading-game/design-intelligence-layer"
+
+const positions: Position[] = [
+  { kind: "rise-fall", direction: "Rise", market: "Vol 100", duration: "30 minutes",
+    stake: "1.00 USDT", pnl: "+0.96 USDT", win: true },
+  ...
+]
+
+<OpenPositionsBlock
+  trigger={<Button variant="secondary">Active trades</Button>}
+  positions={positions}
+  sheetTitle="Positions"
+  onViewHistory={openHistoryPage}
+/>
+```
+
+### `ResultBlock`
+
+Universal win/loss result card with animated halo + thumb illustration + contract badge + duration badge + CTA. Thumb icons are bundled inside the package.
+
+```tsx
+import { ResultBlock } from "@trading-game/design-intelligence-layer"
+
+<ResultBlock
+  status="win"                                             // "win" | "loss"
+  amount="10,000.00"
+  currency="USDT"
+  contractLabel="Rise"
+  duration="2 hours"
+  pickedDigit={7}                                          // optional, for Digits contracts
+  ctaMode="next-round"                                     // "next-round" | "go-again" | "conversion"
+/>
+```
+
+### `ResultDialog`
+
+Fixed-width system dialog (title + body + two CTAs). Used for messages like "out of balance".
+
+```tsx
+import { ResultDialog } from "@trading-game/design-intelligence-layer"
+
+<ResultDialog
+  title="You're out of balance."
+  body="Deposit to keep playing or stay in demo mode."
+  primaryLabel="Deposit now"
+  secondaryLabel="Stay in demo"
+/>
+```

package/README.md

@@ -159,15 +159,24 @@ npm install react react-dom tailwindcss
 
 ## Blocks
 
-Blocks are pre-composed UI patterns built from design system primitives. They are demonstrated in the **Blocks** tab of the development playground and are **not** exported from the npm package — import the underlying components directly if you need to use them.
+Blocks are opinionated, composed UI patterns built from design system primitives — **exported from the package the same as primitives**. Import them by name and pass data via props. Variants (`layout` / `mode` / `status`) live on a single block, not separate components.
+
+```tsx
+import { HeroBlock, ResultBlock, OpenPositionsBlock } from "@trading-game/design-intelligence-layer"
+```
 
 | Block | Variants | Description |
 |---|---|---|
-| NavBar | Desktop, Mobile (closed), Mobile (open) | Landing page top navigation bar. Logo + ghost nav links (Products, Use Cases, Docs, Blog, FAQ) + Sign in / Sign up CTAs. |
-| Hero | Type 1 (Desktop + Mobile), Type 2 | Landing page hero sections. Type 1: tagline pill + heading + body + CTAs left, image right (responsive). Type 2: centred single-column, tagline pill + heading + body + primary CTA with arrow icon, no image. |
-| Sheet Open Positions | Active (Rise-Fall, Swipe, Box-O, Digits), Empty, Edge cases (1 item, 30 items) | Right-side sheet (desktop) / bottom drawer (mobile) listing open trading positions. Each row shows bet name + stake (left) and PnL + market·duration (right). The drawer hugs its content with `max-h-[80vh]`; long lists scroll internally with header and footer pinned. |
-| Header navigation | — | Product app top header bar. Back navigation button left, account balance + Demo badge centre, history and sound action buttons right. |
-| Result | Win · continuing, Loss · continuing, End of demo, Out of balance, On a roll | Fixed-width (320 px) end-of-round result card. Thumb-up/down SVG with subtle radial halo + idle motion; `Bust.` / `Called it.` title becomes `You won!` / `You lost!`; amount headline; contract + duration `standard` Badge pills; primary + (optionally) secondary CTA. Out-of-balance and on-a-roll are dialog-style variants with no icon — just title + body + 2 CTAs. |
+| `HeroBlock` | `layout: "centered" \| "split"` | Marketing hero section. Centred = single-column, no image; split = two-column with image. Tagline pill, heading, body, primary + optional secondary CTA. |
+| `AuthBlock` | `mode: "sign-in" \| "sign-up"` | Auth form — logo lockup, OAuth provider buttons (Google, Telegram, X), divider, email input, terms, primary CTA, footer cross-link. |
+| `FAQBlock` | `layout: "desktop" \| "mobile"` | Eyebrow + heading + intro + accordion + optional "Need more help" card. Items passed as `{ value, question, answer }[]`. |
+| `NavBarBlock` | — (internal mobile-menu state) | Responsive marketing nav — brand logos, link buttons, Sign in / Sign up CTAs, hamburger drawer on mobile. |
+| `HeaderNavigationBlock` | — | In-app trading header. Back · badge · balance · optional history button with `history.count` numeric badge (`bg-primary`; ≥99 → `99+`) · actions slot. |
+| `OpenPositionsBlock` | `Position` discriminated union (`rise-fall` / `swipe` / `box-o` / `digits`) | Responsive Sheet (desktop) / Drawer (mobile) listing open positions. Consumer-provided trigger; default empty state. |
+| `ResultBlock` | `status: "win" \| "loss"`, `ctaMode: "next-round" \| "go-again" \| "conversion"` | Win/loss result card. Animated halo + thumb illustration (bundled inline) + contract badge + duration badge + CTA. |
+| `ResultDialog` | — | Fixed-width system dialog (title + body + two CTAs). For messages like "out of balance" or "on a roll". |
+
+See [`AGENTS.md`](./AGENTS.md#blocks) for full usage examples per block.
 
 ---