<div align="center">

![@djangocfg/ui-tools](https://raw.githubusercontent.com/markolofsen/assets/main/libs/djangocfg/ui-tools.webp)

</div>

# @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
```

```css
/* your app's globals.css — Tailwind v4 must scan this package's sources */
@import "@djangocfg/ui-core/styles/full";
@import "@djangocfg/ui-tools/styles";   /* ← add this */
```

Without the styles import, Tailwind never sees this package's classes and tools render partially unstyled.

Wrap your app in `<UiProviders>` 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';

<JsonTree data={response} compactHeader />
<LogViewer entries={logs} />
<DiffViewer oldCode={a} newCode={b} language="ts" view="split" />
<CronScheduler value={cron} onChange={setCron} />
```

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.
