@djangocfg/ui-tools 2.1.400 → 2.1.404

package/README.md

@@ -79,9 +79,21 @@ Subpaths come in three flavors:
 | `@djangocfg/ui-tools/map` | `LazyMapContainer`, `LazyMapView`, plus light primitives (`MapMarker`, `MapPopup`, `MapCluster`, `MapSource`, `MapLayer`, `MapControls`, `MapProvider`, types) | The heavy MapLibre GL chunk (~800 KB) only loads when `LazyMapContainer` actually mounts. Markers and popups are thin `react-map-gl` wrappers — exported synchronously. |
 | `@djangocfg/ui-tools/markdown-message` | `MarkdownMessage`, `ChatMessageRow`, `ActionRow`, `extractTextFromChildren`, types | **SSR-safe.** The component itself is `'use client'`, but rendering produces plain HTML — Next.js will pre-render it on the server when imported from a Client Component. Use this when you want the markdown renderer without dragging in the full chat. |
 | `@djangocfg/ui-tools/<tool-name>` | One tool | `mermaid`, `speech-recognition`, `json-tree`, `pretty-code`, `openapi-viewer`, `json-form`, `lottie-player`, `video-player`, `image-viewer`, `cron-scheduler`, `gallery`, `tour`, `tree`, `file-icon`, `upload` |
+| `@djangocfg/ui-tools/json-form/full` | `JsonSchemaForm`, `ObjectFieldTemplate`, `evaluateDisabledWhen`, all widgets / templates / utils | Eager bundle. Use only for storybook / internal tooling that needs the template + util APIs at module scope. Production code should import `LazyJsonSchemaForm` from `/json-form` instead. |
 | `@djangocfg/ui-tools/styles` | Tailwind source CSS | |
 | `@djangocfg/ui-tools/dist.css` | Pre-compiled CSS | |
 
+### Code & data inspectors are always-dark by design
+
+`PrettyCode` and `JsonTree` render on a fixed dark surface (`#0d1117`)
+regardless of the host UI theme. Same convention as GitHub, VSCode,
+ChatGPT, Chrome DevTools. Syntax highlighting / typed-value coloring
+ship their own contrast model — mixing them with light UI surfaces
+flattens everything into low-contrast pastels.
+
+The chrome (border, padding, toolbars) still uses semantic UI tokens.
+Only the *content surface* is fixed. See per-tool READMEs for details.
+
 ---
 
 ## Lazy loading
@@ -146,6 +158,8 @@ function Chat() {
 
 **What's wired by default:** desktop side-mode toggle (auto-hides on narrow screens), persisted dock prefs, two-step Escape, click-to-focus composer, mobile fullscreen with `dvh` heights, push-preview bubble for inbound messages while closed, **ChatGPT-style autoscroll** (sticky-to-bottom within 120 px, every user-send re-anchors the viewport), **bundled chat notification sounds** (sent/received/start/error/mention/notification, ~136KB inlined as `data:`-URLs inside the lazy chat chunk — zero host setup). Native hosts (cmdop_go / Tauri) pass `audio={{ silenced: true, onSoundEvent }}` to keep web silent while routing triggers to the backend.
 
+Need a fully custom input row (e.g. mention autocomplete via `MarkdownEditor`)? Pass `renderComposer={({ composer }) => <YourComposer composer={composer} />}` to `<ChatRoot>` — it replaces the default `<Composer>` while keeping autoscroll, JumpToLatest, and history behaviour. Story: `UI Tools / Chat / Mentions / Machine Mentions`.
+
 Drop `<VoiceComposerSlot />` from `@djangocfg/ui-tools/speech-recognition` into `composerToolbarEnd` for live mic-to-text — **zero props**, reads / writes the composer through `ComposerHandle` registered in chat context. Set `headerSlots={{ languagePicker: true }}` on `<ChatLauncher>` for a flag-button language picker (66 BCP-47 tags). Both auto-hide on Firefox / in-app browsers / missing `getUserMedia`. See [`SpeechRecognition`](#speech-recognition--quick-start) below.
 
 Full docs: [`Chat/README.md`](src/tools/Chat/README.md). Stories: `Tools/Chat/{Basic,Bubbles,ToolCalls,Personas,Launcher,Header,Audio & Actions,Voice composer}`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.400",
+  "version": "2.1.404",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -96,6 +96,11 @@
       "import": "./src/tools/JsonForm/lazy.tsx",
       "require": "./src/tools/JsonForm/lazy.tsx"
     },
+    "./json-form/full": {
+      "types": "./src/tools/JsonForm/index.ts",
+      "import": "./src/tools/JsonForm/index.ts",
+      "require": "./src/tools/JsonForm/index.ts"
+    },
     "./json-tree": {
       "types": "./src/tools/JsonTree/lazy.tsx",
       "import": "./src/tools/JsonTree/lazy.tsx",
@@ -154,8 +159,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.400",
-    "@djangocfg/ui-core": "^2.1.400",
+    "@djangocfg/i18n": "^2.1.404",
+    "@djangocfg/ui-core": "^2.1.404",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -209,9 +214,9 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.400",
-    "@djangocfg/typescript-config": "^2.1.400",
-    "@djangocfg/ui-core": "^2.1.400",
+    "@djangocfg/i18n": "^2.1.404",
+    "@djangocfg/typescript-config": "^2.1.404",
+    "@djangocfg/ui-core": "^2.1.404",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/JsonForm/JsonSchemaForm.tsx

@@ -17,7 +17,7 @@ import {
 import { JsonFormContext, JsonSchemaFormProps } from './types';
 import { normalizeFormData, validateSchema } from './utils';
 import {
-    CheckboxWidget, ColorWidget, NumberWidget, SelectWidget, SliderWidget, SwitchWidget, TextWidget
+    CheckboxWidget, ColorWidget, NumberWidget, SelectWidget, SliderWidget, SwitchWidget, TextareaWidget, TextWidget
 } from './widgets';
 
 /**
@@ -104,6 +104,7 @@ export function JsonSchemaForm<T = any>(props: JsonSchemaFormProps<T>) {
   const widgets: RegistryWidgetsType = useMemo(() => ({
     // Standard widget names (PascalCase) - used by RJSF internally
     TextWidget,
+    TextareaWidget,
     NumberWidget,
     CheckboxWidget,
     SelectWidget,
@@ -112,6 +113,7 @@ export function JsonSchemaForm<T = any>(props: JsonSchemaFormProps<T>) {
     SliderWidget,
     // Lowercase aliases - for uiSchema 'ui:widget' references
     text: TextWidget,
+    textarea: TextareaWidget,
     number: NumberWidget,
     checkbox: CheckboxWidget,
     select: SelectWidget,

package/src/tools/JsonForm/README.md

@@ -3,10 +3,20 @@
 Schema-driven forms on top of [react-jsonschema-form](https://github.com/rjsf-team/react-jsonschema-form) (RJSF) with `@djangocfg/ui` widgets, AJV8 validation, and a few custom extensions for compact playground-style UIs.
 
 ```tsx
-import { JsonSchemaForm } from '@djangocfg/ui-tools/json-form';
-// or, for code-splitting:
+// Lazy entry — what production code should import. Ships only the
+// component reference + a Suspense fallback; the ~300KB RJSF bundle
+// loads on first mount.
 import { LazyJsonSchemaForm } from '@djangocfg/ui-tools/json-form';
 
+// Full entry — eager bundle. Use only for storybook / internal
+// tooling that needs templates, widgets, or `evaluateDisabledWhen`
+// at module scope. Pulls RJSF synchronously, no code-splitting.
+import {
+  JsonSchemaForm,
+  ObjectFieldTemplate,
+  evaluateDisabledWhen,
+} from '@djangocfg/ui-tools/json-form/full';
+
 const schema = {
   type: 'object',
   properties: {

package/src/tools/JsonForm/widgets/TextareaWidget.tsx

@@ -0,0 +1,25 @@
+"use client"
+
+import React from 'react';
+
+import type { WidgetProps } from '@rjsf/utils';
+
+import { TextWidget } from './TextWidget';
+
+/**
+ * Multiline text widget for JSON Schema Form. Thin wrapper around
+ * `TextWidget` that pins `options.widget = 'textarea'` so the
+ * underlying renderer reaches the `<textarea>` branch.
+ *
+ * Registered under the `textarea` ui:widget alias — schemas can opt
+ * into multiline editing without setting `ui:options.widget`:
+ *
+ *     uiSchema = { description: { 'ui:widget': 'textarea' } }
+ *
+ * Honors all the same `ui:options` as `TextWidget` — most usefully
+ * `rows` (default `3`).
+ */
+export function TextareaWidget(props: WidgetProps) {
+  const options = { ...(props.options ?? {}), widget: 'textarea' };
+  return <TextWidget {...props} options={options} />;
+}

package/src/tools/JsonForm/widgets/index.ts

@@ -6,6 +6,7 @@
  */
 
 export { TextWidget } from './TextWidget';
+export { TextareaWidget } from './TextareaWidget';
 export { NumberWidget } from './NumberWidget';
 export { CheckboxWidget } from './CheckboxWidget';
 export { SelectWidget } from './SelectWidget';

package/src/tools/JsonTree/README.md

@@ -2,6 +2,18 @@
 
 Interactive JSON tree viewer with expand/collapse, copy, and download.
 
+## Why dark by default
+
+JsonTree renders on a fixed dark surface (`#0d1117`) regardless of
+the host UI theme — same convention as Chrome DevTools, Insomnia,
+Bruno, Postman. JSON inspectors carry their own data-typed palette
+(blue keys, green strings, orange numbers, red null) tuned for dark
+backgrounds; mixing it with light UI tokens flattens values into
+unreadable pastels.
+
+The palette is intentionally **not** a semantic token. See PrettyCode
+README for the same rationale.
+
 ## Structure
 
 ```

package/src/tools/PrettyCode/README.md

@@ -0,0 +1,81 @@
+# PrettyCode
+
+Syntax-highlighted code block. Prism-powered, dark-by-default surface.
+
+## Why dark by default
+
+PrettyCode renders on a fixed dark surface (`#0d1117` + `vsDark` palette)
+regardless of the host theme — the same convention as GitHub, VSCode,
+ChatGPT, Slack. Syntax highlighting ships its own contrast model
+(keyword / string / number / comment) that flattens to low-contrast
+pastels when forced onto a light UI surface.
+
+The surface is intentionally **not** a semantic token. Semantic tokens
+(`--primary`, `--accent`, `--card`) describe UI affordances; code
+display is data, not UI.
+
+## Structure
+
+```
+PrettyCode/
+├── PrettyCode.client.tsx       # Main component (Highlight + dark surface)
+├── registerPrismLanguages.ts   # Lazy-load extra grammars (bash, ruby, java, php)
+├── index.tsx                   # Public re-export
+└── lazy.tsx                    # Lazy-loaded export
+```
+
+## Usage
+
+```tsx
+import { PrettyCode } from '@djangocfg/ui-tools/code';
+
+<PrettyCode data={sourceCode} language="typescript" />
+
+// Inline snippet (used in markdown rendering)
+<PrettyCode data={`const x = 1`} language="ts" inline />
+
+// Capped at 50 visible lines, scrolls if longer
+<PrettyCode data={longBlob} language="json" maxLines={50} />
+
+// Chrome-less variant — embed inside another scroll container
+<PrettyCode data={src} language="bash" variant="plain" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `string \| object` | — | Code string. Objects are `JSON.stringify`d. |
+| `language` | `Language` | — | Prism language id. Unknown → plain text. |
+| `mode` | `'dark' \| 'light'` | `'dark'` | Palette override. Default is always dark (see "Why dark"). |
+| `inline` | `boolean` | `false` | Render as inline `<code>` (no card / toolbar). |
+| `variant` | `'card' \| 'plain'` | `'card'` | `plain` strips border, background, and toolbar. |
+| `isCompact` | `boolean` | `false` | 12px font instead of 14px. |
+| `maxLines` | `number` | `undefined` | When set, block scrolls past this many lines. |
+| `customBg` | `string` | — | Tailwind class to override the dark surface. |
+| `scrollIsolation` | `boolean` | `true` | Block scroll capture until clicked (long snippets). |
+| `className` | `string` | — | Extra classes on the wrapper. |
+
+## When to override `mode`
+
+Almost never. The dark default is correct for ~all cases. Pass
+`mode="light"` only for deliberate light-on-light renders (e.g. PDF
+export targeting a printed page). The surface falls back to
+`bg-card` semantic token in that mode.
+
+## Supported languages
+
+Out of the box: `javascript`, `typescript`, `python`, `json`, `css`,
+`markup` (html/xml), `sql`, `yaml`, `markdown`, `go`.
+
+Lazy-loaded on first use: `bash`/`shell`, `ruby`, `java`, `php`.
+Lazy load is tracked through `useEnsurePrismLanguages()` — the
+component re-renders once the grammar resolves.
+
+Unknown languages fall back to plain text (no highlighting, no error).
+
+## Storybook
+
+`UI Tools / Code / PrettyCode` — `Playground`, `TypeScript`, `Json`,
+`Python`, `Bash`, `Sql`, `Yaml`, `LongFileWithScroll`, `Inline`,
+`Compact`, `LightMode`, `PlainVariant`.