@qball-inc/react 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +109 -0
  2. package/package.json +10 -2
package/README.md ADDED
@@ -0,0 +1,109 @@
1
+ <p align="center">
2
+ <a href="https://qball-inc.github.io/qball-design-system/">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/QBall-Inc/qball-design-system/main/assets/qball-logo-handoff/qball-logo-dark.gif">
5
+ <img src="https://raw.githubusercontent.com/QBall-Inc/qball-design-system/main/assets/qball-logo-handoff/qball-logo-parchment.gif" alt="QBall Design System" width="180" height="180">
6
+ </picture>
7
+ </a>
8
+ </p>
9
+
10
+ <h1 align="center">@qball-inc/react</h1>
11
+
12
+ <p align="center">
13
+ The <b>React component library</b> of the QBall Design System — token-driven<br>
14
+ className wrappers over <a href="https://www.npmjs.com/package/@qball-inc/tokens">@qball-inc/tokens</a>. Accessible by default,<br>
15
+ light and dark from the same tokens. Dual ESM/CJS with TypeScript declarations.
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="https://www.npmjs.com/package/@qball-inc/react"><img src="https://img.shields.io/npm/v/@qball-inc/react?color=3F6B5B&label=npm" alt="npm version"></a>
20
+ <a href="https://github.com/QBall-Inc/qball-design-system/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@qball-inc/react?color=3F6B5B" alt="Apache-2.0 license"></a>
21
+ <a href="https://qball-inc.github.io/qball-design-system/"><img src="https://img.shields.io/badge/gallery-live-3F6B5B" alt="component gallery"></a>
22
+ </p>
23
+
24
+ ---
25
+
26
+ Every component is a **Strategy-2 className wrapper**: it applies the shipped
27
+ `@qball-inc/tokens` classes and emits **no CSS of its own**. So the React package is
28
+ the behavior and accessibility layer; the visual layer arrives entirely from the
29
+ token CSS you import.
30
+
31
+ ## Install
32
+
33
+ ```bash
34
+ pnpm add @qball-inc/react @qball-inc/tokens react react-dom
35
+ ```
36
+
37
+ The components are built on **Radix UI** primitives, declared as peer dependencies —
38
+ pnpm/npm install them alongside automatically (with a strict setup, add any your
39
+ bundler reports as missing). Two peers are **optional**, needed only for the one
40
+ component that uses them:
41
+
42
+ | Optional peer | Needed for |
43
+ | ----------------------- | ----------------------------------- |
44
+ | `@tanstack/react-table` | `DataTable` (its headless core) |
45
+ | `d3` | `Candlestick` (the D3 chart island) |
46
+
47
+ The icon system has **no** runtime icon-pack dependency — the marks are compiled to
48
+ our own inline SVGs at build time.
49
+
50
+ ## Wire the token CSS (required)
51
+
52
+ Because the components emit no CSS, you **must** import the `@qball-inc/tokens` layer
53
+ or everything renders unstyled. **Order matters.**
54
+
55
+ ```css
56
+ /* app.css */
57
+ @import "@qball-inc/tokens/colors-and-type.css"; /* tokens + .btn — REQUIRED, first */
58
+ @import "@qball-inc/tokens/components.css"; /* component layer — REQUIRED, second */
59
+ ```
60
+
61
+ ```tsx
62
+ // main.tsx
63
+ import "./app.css";
64
+ import { Button, Stat } from "@qball-inc/react";
65
+
66
+ export function App() {
67
+ return (
68
+ <main>
69
+ <Button variant="primary">Add to watchlist</Button>
70
+ <Stat label="AAPL" value="184.30" unit="USD" direction="up" delta="+8.4%" />
71
+ </main>
72
+ );
73
+ }
74
+ ```
75
+
76
+ Switch themes with `data-theme="light|dark"` on `<html>`. Full wiring guide
77
+ (Tailwind `@theme`, the `--font-display` override, `@source` scanning):
78
+ [docs/consumer-setup.md](https://github.com/QBall-Inc/qball-design-system/blob/main/docs/consumer-setup.md).
79
+
80
+ ## What's included
81
+
82
+ | Family | Components |
83
+ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
84
+ | **Primitives** | `Button` · `Input` · `Field` · `Select` · `Switch` · `Segmented` · `SecretInput` · `Search` |
85
+ | **Overlays** | `Modal` · `AlertModal` · `Toaster`/`toast` · `Callout` · `Skeleton` · `Spinner` · `EmptyStateFig`/`ErrorStateFig` |
86
+ | **Data display** | `Stat` · `Meter` · `Badge` · `Card` · `Divider` · `Tabs` · `Sparkline` · `Tooltip` · `Avatar`/`AvatarGroup` · `DataTable` · `Candlestick` |
87
+ | **App chrome** | `AppBar` · `UserMenu` · `ThemeToggle` · `Scrim` · `CommandDock` · `NotificationCenter` |
88
+ | **AI / domain** | `Terminal` · `Composer` · `useStreaming` · `GroundingFlag` · `MarkdownRenderer` · `ToolUseIndicator` · `DigestCard` |
89
+ | **Backgrounds** | `GridBg` · `AsciiBg` · `GlyphsBg` (+ the `useCanvas2D` driver) — SSR-safe animated `<canvas>` |
90
+ | **Icons** | `Icon` (dynamic registry) + per-icon named exports (tree-shakeable) + a nominative brand-mark track |
91
+ | **Media** | `MediaSlot` — a pure-React, SSR/static-safe display container (image / gif / video / embed-facade) |
92
+
93
+ All components are token-driven (no hardcoded color, no box-shadow), pair finance
94
+ color with a non-color cue, and honor `prefers-reduced-motion`. Browse every one in
95
+ the [live gallery](https://qball-inc.github.io/qball-design-system/).
96
+
97
+ ## Part of the QBall Design System
98
+
99
+ - **Tokens:** [`@qball-inc/tokens`](https://www.npmjs.com/package/@qball-inc/tokens) — the locked token layer this package paints with.
100
+ - **Gallery:** [live component contact-sheet](https://qball-inc.github.io/qball-design-system/) (light + dark).
101
+ - **Source + docs:** [QBall-Inc/qball-design-system](https://github.com/QBall-Inc/qball-design-system).
102
+
103
+ ## License
104
+
105
+ [Apache-2.0](https://github.com/QBall-Inc/qball-design-system/blob/main/LICENSE) ©
106
+ QBall Inc. The icon system's brand track ships a small set of **third-party brand
107
+ marks** for nominative identification only (e.g. a "Sign in with Google"
108
+ affordance) — see [MARKS.md](https://github.com/QBall-Inc/qball-design-system/blob/main/packages/react/MARKS.md).
109
+ These remain the trademarks of their respective owners.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qball-inc/react",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "QBall Design System React components — token-driven, framework-agnostic at the CSS layer. Dual ESM/CJS build with TypeScript declarations.",
5
5
  "keywords": [
6
6
  "react",
@@ -15,6 +15,14 @@
15
15
  "accessible-components"
16
16
  ],
17
17
  "license": "Apache-2.0",
18
+ "author": "QBall Inc",
19
+ "homepage": "https://qball-inc.github.io/qball-design-system/",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/QBall-Inc/qball-design-system.git",
23
+ "directory": "packages/react"
24
+ },
25
+ "bugs": "https://github.com/QBall-Inc/qball-design-system/issues",
18
26
  "private": false,
19
27
  "publishConfig": {
20
28
  "access": "public"
@@ -42,7 +50,7 @@
42
50
  "cmdk": "^1.1.1",
43
51
  "react-markdown": "^10.1.0",
44
52
  "sonner": "^1.7.4",
45
- "@qball-inc/tokens": "1.0.0"
53
+ "@qball-inc/tokens": "1.1.0"
46
54
  },
47
55
  "peerDependencies": {
48
56
  "@radix-ui/react-alert-dialog": ">=1.1.0",