npm package: @john-avenue/ui
Description: Dark-mode-first React component library with 70+ components — inputs, charts, trading widgets, data tables, and more.
Author: John Avenue
Latest version: 0.3.5

# @john-avenue/ui

Dark-mode-first React component library with 75+ components — inputs, data display, charts, trading widgets, and layout primitives. Built with TypeScript, inline styles (zero CSS dependencies), and CSS custom properties for theming.

## Install

```bash
npm install @john-avenue/ui
# or
bun add @john-avenue/ui
# or
yarn add @john-avenue/ui
```

**Peer dependencies:** `react >= 18` and `react-dom >= 18`

## Quick Start

```tsx
import { JohnUIProvider, Btn, Inp, Modal } from '@john-avenue/ui';

function App() {
  return (
    <JohnUIProvider>
      <Btn v="primary" onClick={() => {}}>Click me</Btn>
      <Inp placeholder="Type something..." />
    </JohnUIProvider>
  );
}
```

`<JohnUIProvider>` injects the global CSS (keyframe animations, font imports, CSS custom properties) and sets the theme. Wrap your app once at the root.

## Theming

### Dark & Light Mode

```tsx
<JohnUIProvider mode="dark">  {/* default */}
<JohnUIProvider mode="light">
```

### Custom Token Overrides

```tsx
<JohnUIProvider tokens={{ p5: '#6366f1', bg0: '#0f0f14' }}>
```

### Using Tokens in Your Code

```tsx
import { tokens, c, mono, serif } from '@john-avenue/ui';

// tokens and c are the same object — c is shorthand
<div style={{ color: c.t1, background: c.bg1, fontFamily: mono }}>
  Hello
</div>
```

## Components

### Inputs & Controls

| Component | Description |
|-----------|-------------|
| `Btn` | Button with variants: `primary`, `secondary`, `ghost`, `danger` |
| `Inp` | Text input with size and state support |
| `Textarea` | Multi-line text input |
| `Toggle` | On/off toggle switch |
| `Checkbox` | Checkbox with label |
| `Radio` | Radio button with label |
| `Slider` | Range slider |
| `Select` | Single-value dropdown |
| `SearchSelect` | Searchable dropdown with filtering |
| `MultiSelect` | Multi-value select with tags |
| `TagInput` | Free-form tag entry |

### Data Display

| Component | Description |
|-----------|-------------|
| `Table` | Data table with sorting, selection, and row actions |
| `Tag` | Colored label chip |
| `Badge` | Status badge with count |
| `StatusDot` | Colored dot indicator |
| `ProgressBar` | Horizontal progress indicator |
| `Spinner` | Loading spinner |
| `Avatar` | User avatar with fallback initials |
| `Kbd` | Keyboard shortcut display |
| `Ticker` | Financial ticker with price and change |
| `PriceCell` | Price display with directional coloring |
| `PnLBadge` | Profit/loss badge |
| `StatCard` | Key metric card |

### Layout & Navigation

| Component | Description |
|-----------|-------------|
| `Tabs` | Horizontal tab bar |
| `SideTabs` | Vertical tab navigation |
| `CollapsibleSideTabs` | Collapsible sidebar navigation |
| `TabGroup` | Segmented control / button group tabs |
| `Accordion` | Expandable content sections |
| `Section` | Page section with heading |
| `Sub` | Subsection with lighter heading |
| `SectionDivider` | Horizontal divider with optional label |
| `PanelLayout` | Sidebar + content layout |
| `Toolbar` | Action bar with icon buttons |
| `GroupList` | Grouped list with sections |
| `Card` | Content card |
| `FlipCard` | Card with front/back flip |
| `CardGrid` | Responsive card grid |
| `Stepper` | Step indicator |
| `EmptyState` | Placeholder for empty content areas |
| `SettingRow` | Label + control row for settings pages |

### Overlays & Feedback

| Component | Description |
|-----------|-------------|
| `Modal` | Dialog overlay |
| `ConfirmModal` | Confirmation dialog with actions |
| `StepperModal` | Multi-step wizard modal |
| `Tooltip` | Hover tooltip |
| `HoverCard` | Rich hover popover |
| `DropdownMenu` | Context / dropdown menu |
| `CmdPalette` | Command palette (Cmd+K) |
| `Alert` | Inline alert banner |
| `ToastProvider` / `useToast` | Toast notification system |

### Charts

All charts are **pure SVG** — no chart library dependencies.

| Component | Description |
|-----------|-------------|
| `LineChart` | Multi-series line chart |
| `AreaChart` | Filled area chart |
| `BarChart` | Vertical / horizontal bar chart |
| `Histogram` | Distribution histogram |
| `ScatterPlot` | Scatter plot with optional regression |
| `MiniSparkline` | Inline sparkline |
| `CandlestickChart` | OHLC candlestick chart |
| `DepthChart` | Order book depth visualization |
| `SpreadChart` | Bid-ask spread over time |
| `Heatmap` | Color-coded grid |
| `CorrelationMatrix` | Pairwise correlation grid |
| `PortfolioHeatmap` | Treemap-style portfolio view |

Chart building blocks (`ChartContainer`, `Axis`, `Crosshair`, `ChartTooltip`, `Legend`, `Overlay`) are also exported for custom compositions.

### Trading & Financial

| Component | Description |
|-----------|-------------|
| `OrderBook` | Bid/ask order book display |
| `OrderEntry` | Order entry form |
| `PairOrderPanel` | Paired order entry (buy + sell) |
| `TradeBlotter` | Recent trades list |
| `PositionRow` | Open position display |
| `LadderRow` | Price ladder row |
| `SpreadIndicator` | Bid-ask spread gauge |
| `ZScoreMeter` | Z-score visualization |
| `BalanceBar` | Balance distribution bar |
| `RiskGauge` | Risk level gauge |
| `PairCard` | Trading pair analytics card |

### Misc

| Component | Description |
|-----------|-------------|
| `Logo` | John UI logo mark |
| `ChevronArrow` | Animated chevron icon |

## Sizing

Most components accept a `sz` prop using a 1–4 numeric scale:

| Value | Label | Use case |
|-------|-------|----------|
| `1` | Compact | Dense tables, toolbars |
| `2` | Default | Standard UI |
| `3` | Comfortable | Forms, settings |
| `4` | Spacious | Hero sections |

```tsx
<Btn sz={1}>Compact</Btn>
<Inp sz={3} placeholder="Comfortable" />
```

## Design Tokens

Tokens are CSS custom properties scoped under `--john-*`. Access them via the `tokens` (or `c`) export:

### Colors
- `p5` — Primary purple
- `p3` — Light purple
- `p7` — Dark purple
- `green`, `red`, `amber`, `blue`, `cyan`, `orange`, `yellow`, `teal`, `lime`, `pink` — Semantic accents

### Surfaces & Backgrounds
- `bg0` through `bg3` — Background layers (darkest to lightest)
- `s1`, `s2`, `s3` — Surface overlays (increasing opacity)

### Borders
- `b1`, `b2`, `b3` — Border opacity levels (glass-like borders)

### Text
- `t1` — Primary text (93% white)
- `t2` — Secondary text (55%)
- `t3` — Tertiary text (30%)
- `t4` — Disabled text (12%)

### Purple Alpha
- `pa1` through `pa7` — Purple at increasing opacities (focus rings, hover states)

### Fonts
- `mono` — `'JetBrains Mono', monospace` — data, prices, code
- `serif` — `'DM Serif Display', serif` — display headings

## Styling

All components use **inline styles** — there are no CSS files, CSS modules, or utility classes. This means:

- Zero CSS specificity conflicts
- Works in any React setup (Next.js, Vite, CRA, Remix)
- No build tool configuration needed
- Easily overridable via the `style` prop on any component

## Utility Exports

```tsx
import {
  isGrouped, flatOpts, gv, gl,           // Select option helpers
  linearScale, niceScale, timeAxisTicks,  // Chart math
  formatCompact, formatCurrency,          // Number formatting
  formatPercent, formatPrice,
  extent, domainWithPadding, downsample,  // Data helpers
  chartSeriesColors,                      // Default chart palette
} from '@john-avenue/ui';
```

## TypeScript

Fully typed. Every component exports its props interface:

```tsx
import type { BtnProps, InpProps, TableProps, Column } from '@john-avenue/ui';
```

## Browser Support

Modern browsers (Chrome, Firefox, Safari, Edge). Requires CSS custom properties support.

## License

[MIT](./LICENSE)