@djangocfg/ui-tools 2.1.210 → 2.1.213

package/src/components/FloatingToolbar/actions/CopyAction.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import React from 'react';
+import { CopyButton } from '@djangocfg/ui-core/components';
+
+interface CopyActionProps {
+  value: string;
+  title?: string;
+}
+
+const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
+
+export const CopyAction: React.FC<CopyActionProps> = ({ value, title = 'Copy' }) => (
+  <CopyButton
+    value={value}
+    variant="ghost"
+    size="icon"
+    className={BUTTON_CLASS}
+    iconClassName="h-3 w-3"
+    title={title}
+  />
+);

package/src/components/FloatingToolbar/actions/DownloadAction.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import { Download } from 'lucide-react';
+import React from 'react';
+
+import { Button } from '@djangocfg/ui-core/components';
+
+interface DownloadActionProps {
+  value: string;
+  filename?: string;
+  mimeType?: string;
+  title?: string;
+}
+
+const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
+
+export const DownloadAction: React.FC<DownloadActionProps> = ({
+  value,
+  filename = 'download.txt',
+  mimeType = 'text/plain',
+  title = 'Download',
+}) => {
+  const handleDownload = () => {
+    const blob = new Blob([value], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={handleDownload}
+      className={BUTTON_CLASS}
+      title={title}
+    >
+      <Download className="h-3 w-3" />
+    </Button>
+  );
+};

package/src/components/FloatingToolbar/actions/ExpandAction.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { ChevronDown, ChevronUp } from 'lucide-react';
+import React from 'react';
+
+import { Button } from '@djangocfg/ui-core/components';
+
+interface ExpandActionProps {
+  isExpanded: boolean;
+  onToggle: () => void;
+}
+
+const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
+
+export const ExpandAction: React.FC<ExpandActionProps> = ({ isExpanded, onToggle }) => (
+  <Button
+    variant="ghost"
+    size="icon"
+    onClick={onToggle}
+    className={BUTTON_CLASS}
+    title={isExpanded ? 'Collapse All' : 'Expand All'}
+  >
+    {isExpanded ? <ChevronUp className="h-3 w-3" /> : <ChevronDown className="h-3 w-3" />}
+  </Button>
+);

package/src/components/FloatingToolbar/actions/FullscreenAction.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { Maximize2, Minimize2 } from 'lucide-react';
+import React from 'react';
+
+import { Button } from '@djangocfg/ui-core/components';
+
+interface FullscreenActionProps {
+  isFullscreen?: boolean;
+  onToggle: () => void;
+  title?: string;
+}
+
+const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
+
+export const FullscreenAction: React.FC<FullscreenActionProps> = ({
+  isFullscreen = false,
+  onToggle,
+  title,
+}) => (
+  <Button
+    variant="ghost"
+    size="icon"
+    onClick={onToggle}
+    className={BUTTON_CLASS}
+    title={title ?? (isFullscreen ? 'Exit fullscreen' : 'Fullscreen')}
+  >
+    {isFullscreen ? <Minimize2 className="h-3 w-3" /> : <Maximize2 className="h-3 w-3" />}
+  </Button>
+);

package/src/components/FloatingToolbar/actions/index.ts

@@ -0,0 +1,4 @@
+export { CopyAction } from './CopyAction';
+export { DownloadAction } from './DownloadAction';
+export { ExpandAction } from './ExpandAction';
+export { FullscreenAction } from './FullscreenAction';

package/src/components/FloatingToolbar/hooks/useElementCorner.ts

@@ -0,0 +1,84 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+interface Corner {
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+/**
+ * Tracks the top-right corner of a referenced element in viewport coordinates.
+ * Returns { top, right } in px — ready for `position: fixed` toolbar placement.
+ *
+ * Uses `visualViewport` for accurate viewport width — correctly handles:
+ * - DevTools panel open (docked left/right/bottom)
+ * - Browser zoom
+ * - Mobile virtual keyboard / pinch-zoom
+ * - Scrollbars
+ *
+ * Falls back to `document.documentElement.clientWidth` (excludes scrollbars,
+ * matches `position: fixed` coordinate space) when visualViewport is unavailable.
+ *
+ * Updates on:
+ * - Any ancestor scroll (capture phase)
+ * - visualViewport resize/scroll
+ * - ResizeObserver on the element itself
+ */
+export function useElementCorner(ref: React.RefObject<HTMLElement | null>) {
+  const [corner, setCorner] = useState<Corner | null>(null);
+  const updateRef = useRef<() => void>(() => {});
+
+  updateRef.current = () => {
+    if (!ref.current) return;
+    const rect = ref.current.getBoundingClientRect();
+
+    // `position: fixed` is relative to the layout viewport (document.documentElement.clientWidth),
+    // NOT window.innerWidth (which includes scrollbar gutter).
+    // visualViewport.width is the visible area — same as layout viewport when no zoom/keyboard.
+    const viewportWidth =
+      window.visualViewport?.width ?? document.documentElement.clientWidth;
+
+    setCorner({
+      top: rect.top,
+      right: viewportWidth - rect.right,
+      bottom: rect.bottom,
+    });
+  };
+
+  useEffect(() => {
+    const handler = () => updateRef.current();
+
+    handler();
+
+    // Element size changes
+    const ro = new ResizeObserver(handler);
+    if (ref.current) ro.observe(ref.current);
+
+    // Any ancestor scroll (capture catches all, including overflow:auto containers)
+    window.addEventListener('scroll', handler, { capture: true, passive: true });
+
+    // visualViewport handles: DevTools resize, browser zoom, mobile keyboard
+    const vv = window.visualViewport;
+    if (vv) {
+      vv.addEventListener('resize', handler);
+      vv.addEventListener('scroll', handler);
+    } else {
+      window.addEventListener('resize', handler, { passive: true });
+    }
+
+    return () => {
+      ro.disconnect();
+      window.removeEventListener('scroll', handler, { capture: true });
+      if (vv) {
+        vv.removeEventListener('resize', handler);
+        vv.removeEventListener('scroll', handler);
+      } else {
+        window.removeEventListener('resize', handler);
+      }
+    };
+  }, [ref]);
+
+  return corner;
+}

package/src/components/FloatingToolbar/hooks/useScrollIsolation.ts

@@ -0,0 +1,62 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+
+const UNLOCKED_CLASS = 'scroll-unlocked';
+
+/**
+ * Scroll isolation — prevents the container from capturing wheel scroll
+ * until the user explicitly clicks inside it (like Google Maps).
+ *
+ * Locked (overlay visible): wheel events on container scroll the PAGE.
+ * Unlocked: normal scroll inside the container.
+ *
+ * Unlock: click anywhere inside the container.
+ * Re-lock: click outside the container.
+ *
+ * When unlocked, adds `scroll-unlocked` class to the container element
+ * so it can be styled (e.g. focus ring) via CSS.
+ */
+export function useScrollIsolation(
+  ref: React.RefObject<HTMLElement | null>,
+  enabled: boolean,
+) {
+  const [locked, setLocked] = useState(true);
+
+  const unlock = useCallback(() => setLocked(false), []);
+
+  // Re-lock when clicking outside the container
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleDocClick = (e: MouseEvent) => {
+      const el = ref.current;
+      if (!el) return;
+      if (!el.contains(e.target as Node)) {
+        setLocked(true);
+      }
+    };
+
+    document.addEventListener('click', handleDocClick, true);
+    return () => document.removeEventListener('click', handleDocClick, true);
+  }, [enabled, ref]);
+
+  // Toggle class on container to allow CSS-driven focus ring
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !enabled) return;
+    if (locked) {
+      el.classList.remove(UNLOCKED_CLASS);
+    } else {
+      el.classList.add(UNLOCKED_CLASS);
+    }
+    return () => el.classList.remove(UNLOCKED_CLASS);
+  }, [locked, enabled, ref]);
+
+  // Reset to locked when feature toggled on
+  useEffect(() => {
+    if (enabled) setLocked(true);
+  }, [enabled]);
+
+  return { locked, unlock };
+}

package/src/components/FloatingToolbar/index.tsx

@@ -0,0 +1,131 @@
+'use client';
+
+import React, { useState } from 'react';
+
+import './FloatingToolbar.css';
+import { useElementCorner } from './hooks/useElementCorner';
+import { useScrollIsolation } from './hooks/useScrollIsolation';
+
+export interface FloatingToolbarProps {
+  /** Ref to the container element the toolbar anchors to */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Action buttons to render (right side) */
+  children: React.ReactNode;
+  /** Optional label shown left of the buttons (e.g. language badge) */
+  label?: React.ReactNode;
+  /** Where to anchor relative to the container (default: bottom-right) */
+  position?: 'top-right' | 'bottom-right';
+  /** Offset from the edge in px (default: 8) */
+  offset?: number;
+  /** z-index (default: 30) */
+  zIndex?: number;
+  /**
+   * Block wheel scroll inside the container until user clicks into it.
+   * Re-locks when mouse leaves. Like Google Maps scroll isolation.
+   * @default true
+   */
+  scrollIsolation?: boolean;
+}
+
+const MIN_HEIGHT = 40; // minimum container height to show toolbar
+
+export const FloatingToolbar: React.FC<FloatingToolbarProps> = ({
+  containerRef,
+  children,
+  label,
+  position = 'bottom-right',
+  offset = 8,
+  zIndex = 30,
+  scrollIsolation = true,
+}) => {
+  const corner = useElementCorner(containerRef);
+  const { locked, unlock } = useScrollIsolation(containerRef, scrollIsolation);
+  const [overlayHovered, setOverlayHovered] = useState(false);
+
+  // Overlay always renders (even before corner is measured) — it's position:absolute
+  // inside the container so it works immediately on mount.
+  // It absorbs wheel events (pointer-events cover the container) so the page scrolls normally.
+  // Click anywhere inside unlocks it; click outside re-locks it.
+  const overlay =
+    scrollIsolation && locked ? (
+      <div
+        onClick={unlock}
+        onMouseEnter={() => setOverlayHovered(true)}
+        onMouseLeave={() => setOverlayHovered(false)}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          zIndex: zIndex - 1,
+          cursor: 'pointer',
+          background: overlayHovered ? 'rgba(0,0,0,0.04)' : 'transparent',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          transition: 'background 150ms',
+        }}
+      >
+        {overlayHovered && (
+          <span style={{
+            fontSize: '0.75rem',
+            padding: '0.25rem 0.625rem',
+            borderRadius: '9999px',
+            background: 'rgba(0,0,0,0.55)',
+            color: '#fff',
+            pointerEvents: 'none',
+            userSelect: 'none',
+          }}>
+            Click to scroll
+          </span>
+        )}
+      </div>
+    ) : null;
+
+  // Toolbar is position:fixed and needs measured coords — skip until ready
+  let toolbar: React.ReactNode = null;
+  if (corner) {
+    const { top, right, bottom } = corner;
+    const viewportHeight = window.visualViewport?.height ?? document.documentElement.clientHeight;
+
+    const inView = bottom > 0 && top < viewportHeight && bottom - top >= MIN_HEIGHT;
+
+    if (inView) {
+      const style: React.CSSProperties = {
+        position: 'fixed',
+        right: right + offset,
+        zIndex,
+      };
+
+      if (position === 'bottom-right') {
+        const clampedBottom = Math.min(bottom - offset, viewportHeight - offset);
+        style.bottom = viewportHeight - clampedBottom;
+      } else {
+        if (top >= 0) {
+          style.top = top + offset;
+        } else {
+          // top of block scrolled above viewport — hide toolbar
+        }
+      }
+
+      if (style.bottom !== undefined || style.top !== undefined) {
+        toolbar = (
+          <div className="flex items-center gap-1" style={style}>
+            {label && (
+              <>
+                {label}
+                <div className="w-px h-4 bg-border/50 mx-0.5" />
+              </>
+            )}
+            {children}
+          </div>
+        );
+      }
+    }
+  }
+
+  return (
+    <>
+      {overlay}
+      {toolbar}
+    </>
+  );
+};

package/src/styles/index.css

@@ -3,3 +3,4 @@
  * Scan tool components for Tailwind class detection
  */
 @source "../**/*.{ts,tsx}";
+

package/src/tools/AudioPlayer/components/HybridCompactPlayer.tsx

@@ -120,7 +120,7 @@ function HybridCompactPlayerInner({ title, waveformMode, showTimer, buttonSize,
     <div className={cn('flex items-center gap-2 w-full', className)}>
       {/* Play / Pause */}
       <Button
-        variant="outline"
+        variant="ghost"
         size="icon"
         className={cn(BUTTON_SIZE[buttonSize], 'flex-shrink-0')}
         onClick={controls.togglePlay}

package/src/tools/AudioPlayer/components/HybridWaveform.tsx

@@ -184,24 +184,24 @@ export const HybridWaveform = memo(function HybridWaveform({
 
     ctx.clearRect(0, 0, width, canvasHeight);
 
-    // Draw buffered regions
+    // Draw progress bar
+    const progress = state.duration > 0 ? state.currentTime / state.duration : 0;
+    const progressWidth = width * progress;
+
+    // Background track
+    ctx.fillStyle = resolvedWaveColor;
+    ctx.fillRect(0, canvasHeight / 2 - 2 * dpr, width, 4 * dpr);
+
+    // Buffered region (thin strip at bottom)
     if (state.buffered && state.duration > 0) {
       ctx.fillStyle = resolvedBufferedColor;
       for (let i = 0; i < state.buffered.length; i++) {
         const start = (state.buffered.start(i) / state.duration) * width;
         const end = (state.buffered.end(i) / state.duration) * width;
-        ctx.fillRect(start, 0, end - start, canvasHeight);
+        ctx.fillRect(start, canvasHeight - 2 * dpr, end - start, 2 * dpr);
       }
     }
 
-    // Draw progress bar
-    const progress = state.duration > 0 ? state.currentTime / state.duration : 0;
-    const progressWidth = width * progress;
-
-    // Background
-    ctx.fillStyle = resolvedWaveColor;
-    ctx.fillRect(0, canvasHeight / 2 - 2 * dpr, width, 4 * dpr);
-
     // Progress
     ctx.fillStyle = resolvedProgressColor;
     ctx.fillRect(0, canvasHeight / 2 - 2 * dpr, progressWidth, 4 * dpr);

package/src/tools/JsonTree/JsonTree.story.tsx

@@ -103,6 +103,7 @@ export const Interactive = () => {
           maxAutoExpandDepth,
           showExpandControls,
           showActionButtons,
+          className: 'h-full',
         }}
       />
     </div>
@@ -129,12 +130,12 @@ export const DeepNesting = () => (
 
 export const CollapsedByDefault = () => (
   <div className="max-w-2xl h-96">
-    <JsonTree data={apiResponse} config={{ maxAutoExpandDepth: 0 }} />
+    <JsonTree data={apiResponse} config={{ maxAutoExpandDepth: 0, className: 'h-full' }} />
   </div>
 );
 
 export const WithMaxDepth = () => (
   <div className="max-w-2xl h-96">
-    <JsonTree data={apiResponse} config={{ maxAutoExpandDepth: 2 }} />
+    <JsonTree data={apiResponse} config={{ maxAutoExpandDepth: 2, className: 'h-full' }} />
   </div>
 );

package/src/tools/JsonTree/README.md

@@ -0,0 +1,60 @@
+# JsonTree
+
+Interactive JSON tree viewer with expand/collapse, copy, and download.
+
+## Structure
+
+```
+JsonTree/
+├── index.tsx                   # Main component (thin orchestrator)
+├── types.ts                    # Types, interfaces, mode presets
+├── hooks/
+│   ├── useElementCorner.ts     # Tracks element's viewport top-right corner for fixed toolbar
+│   └── useJsonExpand.ts        # Expand/collapse state + shouldExpandNodeInitially logic
+├── components/
+│   ├── JsonToolbar.tsx         # Floating icon buttons (expand, copy, download)
+│   └── JsonContent.tsx         # JSONTree wrapper with theme, getItemString, postprocessValue
+├── lazy.tsx                    # Lazy-loaded export
+├── JsonTree.story.tsx          # Storybook stories
+└── README.md
+```
+
+## Usage
+
+```tsx
+import JsonTree from '@djangocfg/ui-tools/JsonTree';
+
+<JsonTree data={myObject} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `unknown` | — | JSON data to display |
+| `mode` | `'full' \| 'compact' \| 'inline'` | `'full'` | Display mode |
+| `title` | `string` | — | Optional title (full mode only) |
+| `config` | `JsonTreeConfig` | `{}` | Fine-grained config overrides |
+| `jsonTreeProps` | `Partial<CommonExternalProps>` | `{}` | Pass-through to react-json-tree |
+
+## Config options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `maxAutoExpandDepth` | `2` | Auto-expand depth (0 = collapsed by default) |
+| `maxAutoExpandArrayItems` | `10` | Arrays ≤ N items are auto-expanded |
+| `maxAutoExpandObjectKeys` | `5` | Objects ≤ N keys are auto-expanded |
+| `maxStringLength` | `200` | Truncate long strings |
+| `collectionLimit` | `50` | Max items rendered per collection |
+| `showCollectionInfo` | `true` | Show `(N keys)` / `(N items)` labels |
+| `showExpandControls` | `true` (full) | Show expand/collapse button |
+| `showActionButtons` | `true` (full) | Show copy/download buttons |
+| `preserveKeyOrder` | `true` | Preserve object key insertion order |
+
+## Toolbar positioning
+
+The toolbar uses `position: fixed` with coordinates from `useElementCorner` (via `getBoundingClientRect`).
+This works correctly in any scroll context — inline, in panels, modals, or full-page — because:
+- Fixed positioning ignores all ancestor `overflow` settings
+- Coordinates are recalculated on every scroll (capture phase) and resize via `ResizeObserver`
+- Toolbar visually follows the block's top-right corner as the page scrolls

package/src/tools/JsonTree/components/JsonContent.tsx

@@ -0,0 +1,98 @@
+'use client';
+
+import React from 'react';
+import { CommonExternalProps, JSONTree } from 'react-json-tree';
+
+const JSON_TREE_THEME = {
+  scheme: 'djangocfg-dark',
+  base00: 'transparent',
+  base01: '#1a1a1a',
+  base02: '#2a2a2a',
+  base03: '#6b7280',
+  base04: '#9ca3af',
+  base05: '#e5e7eb',
+  base06: '#f3f4f6',
+  base07: '#ffffff',
+  base08: '#ef4444', // null, undefined
+  base09: '#f97316', // numbers
+  base0A: '#eab308', // strings
+  base0B: '#22c55e', // booleans
+  base0C: '#06b6d4', // dates, regex
+  base0D: '#3b82f6', // keys
+  base0E: '#a855f7', // functions
+  base0F: '#f43f5e', // deprecations
+};
+
+interface JsonContentProps {
+  data: unknown;
+  renderKey: number;
+  title?: string;
+  showTitle: boolean;
+  padding: string;
+  collectionLimit: number;
+  preserveKeyOrder: boolean;
+  showCollectionInfo: boolean;
+  maxStringLength: number;
+  shouldExpandNodeInitially: (keyPath: readonly (string | number)[], nodeData: unknown, level: number) => boolean;
+  jsonTreeProps?: Partial<CommonExternalProps>;
+}
+
+export const JsonContent: React.FC<JsonContentProps> = ({
+  data,
+  renderKey,
+  title,
+  showTitle,
+  padding,
+  collectionLimit,
+  preserveKeyOrder,
+  showCollectionInfo,
+  maxStringLength,
+  shouldExpandNodeInitially,
+  jsonTreeProps = {},
+}) => {
+  const getItemString = showCollectionInfo
+    ? (nodeType: string, nodeData: unknown) => {
+        if (nodeType === 'Array') {
+          const length = Array.isArray(nodeData) ? nodeData.length : 0;
+          return length > 0 ? <span className="text-muted-foreground text-sm">({length} items)</span> : null;
+        }
+        if (nodeType === 'Object') {
+          const keys = nodeData && typeof nodeData === 'object' ? Object.keys(nodeData) : [];
+          return keys.length > 0 ? <span className="text-muted-foreground text-sm">({keys.length} keys)</span> : null;
+        }
+        return null;
+      }
+    : () => null;
+
+  const postprocessValue = (value: unknown) => {
+    if (typeof value === 'string' && value.length > maxStringLength) {
+      return value.substring(0, maxStringLength) + '... (truncated)';
+    }
+    return value;
+  };
+
+  const isCustomNode = (value: unknown) =>
+    typeof value === 'string' && (value.startsWith('http://') || value.startsWith('https://'));
+
+  return (
+    <div className={`overflow-auto h-full ${padding}`}>
+      {showTitle && title && (
+        <h6 className="text-sm font-semibold text-foreground mb-2">{title}</h6>
+      )}
+      <JSONTree
+        key={renderKey}
+        data={data}
+        theme={JSON_TREE_THEME}
+        invertTheme={false}
+        hideRoot={true}
+        shouldExpandNodeInitially={shouldExpandNodeInitially}
+        getItemString={getItemString}
+        postprocessValue={postprocessValue}
+        isCustomNode={isCustomNode}
+        collectionLimit={collectionLimit}
+        sortObjectKeys={!preserveKeyOrder}
+        {...jsonTreeProps}
+      />
+    </div>
+  );
+};