@djangocfg/ui-tools 2.1.402 → 2.1.407

package/README.md

@@ -32,7 +32,7 @@ Sixteen tools, each one lazy-loaded so it doesn't ship until used. Bundle size i
 | `LottiePlayer` | ~200KB | Lottie animation player |
 | `Chat` | ~150KB | Streaming chat (SSE + tool calls + attachments). [README](src/tools/Chat/README.md) |
 | `SpeechRecognition` | ~40KB | Mic capture + STT with pluggable engines (Web Speech / HTTP / WS). [README](src/tools/SpeechRecognition/README.md) |
-| `VideoPlayer` | ~150KB | Vidstack-based pro player |
+| `VideoPlayer` | ~12KB core | media-chrome player — YouTube / Vimeo / HLS / MP4 in one composable shell. [README](src/tools/VideoPlayer/README.md) |
 | `MarkdownMessage` | ~120KB | Read-only chat-tuned markdown. **SSR-safe** — use as a Client Component, the result is server-rendered. [README](src/components/markdown/MarkdownMessage/README.md) |
 | `JsonTree` | ~100KB | JSON visualization (full/compact/inline modes) |
 | `AudioPlayer` | ~80KB | WebView-safe waveform player |
@@ -78,10 +78,23 @@ Subpaths come in three flavors:
 | `@djangocfg/ui-tools/markdown-editor` | `LazyMarkdownEditor`, `mentionPresets`, types | TipTap + ProseMirror (~200 KB) only loads via the lazy wrapper. |
 | `@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/video-player` | `VideoPlayer` (+ `LazyVideoPlayer` alias), `parseEmbedUrl`, composable parts (`PlayButton`, `SeekBar`, `Volume`, `ControlsBar`, …), per-engine canvases, types | media-chrome shell — YouTube / Vimeo / HLS / MP4 / iframe behind one API. Provider engines (`youtube-video-element`, `hls-video-element`, …) are imported only by the matching canvas, so unused engines tree-shake. [README](src/tools/VideoPlayer/README.md) |
 | `@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 +159,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.402",
+  "version": "2.1.407",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -159,8 +159,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.402",
-    "@djangocfg/ui-core": "^2.1.402",
+    "@djangocfg/i18n": "^2.1.407",
+    "@djangocfg/ui-core": "^2.1.407",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -183,9 +183,10 @@
     "@tiptap/react": "^3.20.1",
     "@tiptap/starter-kit": "^3.20.1",
     "@tiptap/suggestion": "^3.20.1",
-    "@vidstack/react": "next",
     "@wavesurfer/react": "^1.0.12",
+    "hls-video-element": "^1.5.11",
     "maplibre-gl": "^4.7.1",
+    "media-chrome": "^4.19.0",
     "media-icons": "next",
     "mermaid": "^11.12.0",
     "monaco-editor": "^0.55.1",
@@ -205,8 +206,9 @@
     "remark-emoji": "^5.0.2",
     "remark-gfm": "4.0.1",
     "remark-smartypants": "^3.0.2",
-    "vidstack": "next",
-    "wavesurfer.js": "^7.12.1"
+    "vimeo-video-element": "^1.7.2",
+    "wavesurfer.js": "^7.12.1",
+    "youtube-video-element": "^1.9.0"
   },
   "optionalDependencies": {
     "@mapbox/mapbox-gl-draw": "^1.4.3",
@@ -214,9 +216,9 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.402",
-    "@djangocfg/typescript-config": "^2.1.402",
-    "@djangocfg/ui-core": "^2.1.402",
+    "@djangocfg/i18n": "^2.1.407",
+    "@djangocfg/typescript-config": "^2.1.407",
+    "@djangocfg/ui-core": "^2.1.407",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/AudioPlayer/lazy.tsx

@@ -3,39 +3,25 @@
 /**
  * `@djangocfg/ui-tools/audio-player` subpath entrypoint.
  *
- * `LazyPlayer` is the only heavy export — it dynamically imports the full
- * `Player` tree (PlayerShell + Layout + Cover + Waveform + Controls + audio
- * decoding helpers). Everything else listed here is light:
- *   - types are erased,
- *   - the Zustand store, context hooks, and selectors carry no UI,
- *   - the slot components (`Cover`, `Title`, `PlayButton`, `Waveform`, …)
- *     are presentational React components that read from PlayerContext —
- *     they only become meaningful inside a `<PlayerProvider>` (which only
- *     exists inside `LazyPlayer` once loaded).
+ * `LazyPlayer` is exported as a direct (synchronous) alias of `Player`. We
+ * intentionally avoid `React.lazy` + `import('./Player')` here: under bundlers
+ * that pre-bundle subpath entries (Vite optimizeDeps in Next.js/Vite/SB), the
+ * dynamic import creates a second chunk that re-instantiates the React
+ * Contexts (AudioRefCtx/ControlsCtx/MetaCtx/StateCtx/LevelsCtx). The slot
+ * components and selector hooks re-exported below would then read from a
+ * different context instance than `<PlayerProvider>` writes to, which made
+ * `usePlayerAudio` throw "must be used inside <PlayerProvider>".
  *
- * Consumers building a fully custom layout: render `<LazyPlayer>` once to
- * get the provider, then arrange slot components inside via render-children
- * pattern, or use the bare `Player` re-exported from the root barrel.
+ * Heavy audio-decoding work (peaks, AudioContext) already happens lazily at
+ * runtime via effects inside `PlayerProvider`/`PlayerShell` — there is no
+ * benefit to splitting the React shell behind a second chunk.
  */
 
-import { createLazyComponent } from '../../components';
-import type { PlayerProps } from './types';
-
 // ============================================================================
-// Lazy heavy component
+// Player component (synchronous; previously lazy — see note above)
 // ============================================================================
 
-export const LazyPlayer = createLazyComponent<PlayerProps>(
-  () => import('./Player').then((mod) => ({ default: mod.Player })),
-  {
-    displayName: 'LazyAudioPlayer',
-    fallback: (
-      <div className="rounded-lg border border-border/60 bg-card px-4 py-6 text-sm text-muted-foreground">
-        Loading audio player…
-      </div>
-    ),
-  },
-);
+export { Player, Player as LazyPlayer } from './Player';
 
 // ============================================================================
 // Light surface — types, store, context, slot components, hooks

package/src/tools/ImageViewer/components/ImageViewer.tsx

@@ -196,13 +196,21 @@ export function ImageViewer({
           wrapperClass="!w-full !h-full cursor-grab active:cursor-grabbing"
           contentClass="!w-full !h-full flex items-center justify-center"
         >
-          <div className="relative">
+          {/*
+            Fill the TransformComponent content box so the children's
+            `max-w-full / max-h-full` resolve against the actual viewport
+            instead of the image's natural box. Without `w-full h-full`
+            this wrapper shrink-fits the image, which collapses the
+            max-* constraints and renders the image at intrinsic size —
+            visible as cropping / half-height in tall containers.
+          */}
+          <div className="relative w-full h-full flex items-center justify-center">
             {useProgressiveLoading && lqip && !isFullyLoaded && (
               <img
                 src={lqip}
                 alt=""
                 aria-hidden="true"
-                className="absolute inset-0 max-w-full max-h-full object-contain select-none"
+                className="absolute max-w-full max-h-full object-contain select-none"
                 style={{ transform: transformStyle, filter: 'blur(20px)', transition: 'opacity 0.3s ease-out', opacity: isFullyLoaded ? 0 : 1 }}
                 draggable={false}
               />

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`.