# @djangocfg/ui-tools
Heavy, lazy-loaded React components for admin, devtools, and dashboards. Pairs with [`@djangocfg/ui-core`](../ui-core) (primitives + theme tokens).
Every tool is `React.lazy` by default — import what you use, pay only its bundle cost.
## Install
```bash
pnpm add @djangocfg/ui-tools @djangocfg/ui-core
```
Wrap your app in `` from `@djangocfg/ui-core` once at the root (gives Tooltip/Dialog/Toast context to every tool).
## Catalogue
| Group | Tools |
|---|---|
| `chat/` | ChatLauncher, MessageList, Composer, SuggestedPrompts |
| `data/` | DataGrid · DataTable · JsonTree · Kanban · Listbox · Masonry · Timeline · Tree |
| `dev/code/` | PrettyCode · DiffViewer · MarkdownMessage |
| `dev/api/` | OpenapiViewer · ApiRefTable · RequestViewer |
| `dev/ops/` | LogViewer · EnvTable |
| `dev/` (top) | Mermaid · Map |
| `forms/` | CodeEditor (Monaco) · JsonEditor · JsonForm · MarkdownEditor · NotionEditor · FileUpload · Uploader |
| `input/` | Combobox · CronScheduler (+ CronPreview) · Scroller · Sortable · SpeechRecognition |
| `media/` | AudioPlayer · VideoPlayer · ImageViewer · LottiePlayer · Gallery |
| `overlay/` | ResponsiveDialog · ScrollSpy · SelectionToolbar · Tour |
| `visual/charts/` | Gauge · ActivityGraph · CommitGraph · Sparkline |
| `visual/indicators/` | StatusIndicator · Fps · Rating |
| `visual/design/` | ColorPicker · ColorPalette · FileIcon |
| `visual/` (top) | Marquee · QRCode |
Sub-grouping is internal — public imports stay flat.
## Usage
```tsx
import { JsonTree, LogViewer, DiffViewer, CronScheduler } from '@djangocfg/ui-tools';
```
Subpath imports avoid loading siblings:
```tsx
import { JsonTree } from '@djangocfg/ui-tools/json-tree';
import { LogViewer } from '@djangocfg/ui-tools/log-viewer';
```
## Theming
All tools render through `@djangocfg/ui-core` semantic tokens (`bg-card`, `text-foreground`, `border-border`, status surfaces) — they adapt automatically to light/dark and to the theme presets in ui-core.
Two intentional exceptions, both opt-in via prop:
- **`PrettyCode`** — fixed dark surface regardless of UI theme. Code blocks ship their own contrast model (GitHub/VSCode/ChatGPT convention); mixing with light UI produces low-contrast pastel renders. Override via `mode="light"`.
- **`DiffViewer`** — adaptive; uses `themes.github` on light, `themes.vsDark` on dark via `useResolvedTheme()`.
Canvas/SVG components (charts, viz) sample theme colors via `useThemeColor`/`alpha` from `@djangocfg/ui-core/styles/palette` — never `color-mix`/`oklch` strings (Canvas2D rejects them).
## Lazy loading
Every tool's default export is `React.lazy`-wrapped; initial bundle stays small. Heaviest:
Mermaid ~800KB · Monaco CodeEditor ~550KB · PrettyCode (shiki) ~500KB · OpenapiViewer ~400KB · JsonForm ~300KB · AudioPlayer (WaveSurfer) ~200KB · LottiePlayer ~200KB · NotionEditor (TipTap) ~200KB · VideoPlayer (media-chrome) ~150KB · JsonTree ~100KB · ImageViewer ~50KB · CronScheduler ~15KB.
Works in Next.js, Vite, Wails, CRA — no framework lock-in.
## Build discipline
After any `src/` change, **run `pnpm build`** before considering the change done — consumers pick up `dist/` via `pnpm sync:cfg`; a stale `dist/` ships old code silently. See [`CLAUDE.md`](./CLAUDE.md) for details.
```bash
pnpm build # rebuild dist/ (tsup)
pnpm check # tsc --noEmit
```
## Requirements
- React 18 or 19
- `@djangocfg/ui-core` (peer)
- Tailwind CSS v4 (host imports `@djangocfg/ui-core/styles`)
## License
MIT — © djangocfg.