@djangocfg/ui-tools 2.1.431 → 2.1.433

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

@@ -0,0 +1,46 @@
+'use client';
+
+/**
+ * MiddleEllipsis - Finder/Quick-Look-style middle truncation for filenames.
+ *
+ * macOS truncates a too-long filename in the MIDDLE so the start AND the
+ * extension stay readable ("screencapture-referee…very-long-name.png"),
+ * unlike a plain CSS `truncate` which clips the (most meaningful) extension.
+ *
+ * This is a CSS-only technique — no JS measurement, no ResizeObserver:
+ *   - The "head" span flex-shrinks and truncates with an end-ellipsis.
+ *   - The "tail" span is pinned (flex-shrink-0) and always shows the last
+ *     `tailChars` characters, which include the extension.
+ * When the name fits, the head shows in full and no ellipsis appears; when it
+ * overflows, the head clips while the tail (extension) is preserved.
+ */
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+interface MiddleEllipsisProps {
+  /** Full text to display. The container caps the width; CSS does the rest. */
+  text: string;
+  /**
+   * How many trailing characters to keep pinned (and thus always visible).
+   * Sized to comfortably cover an extension plus a little of the name tail.
+   */
+  tailChars?: number;
+  className?: string;
+}
+
+export function MiddleEllipsis({ text, tailChars = 8, className }: MiddleEllipsisProps) {
+  // Split so the tail keeps the extension visible. Guard against short names
+  // (where head/tail would overlap) by rendering them whole in the head.
+  const splitAt = Math.max(0, text.length - tailChars);
+  const head = text.slice(0, splitAt);
+  const tail = text.slice(splitAt);
+  const short = splitAt === 0;
+
+  return (
+    // `title` gives the full, lossless name on hover.
+    <span className={cn('flex min-w-0 items-center', className)} title={text}>
+      <span className="min-w-0 flex-1 truncate">{short ? text : head}</span>
+      {!short && <span className="flex-shrink-0 whitespace-pre">{tail}</span>}
+    </span>
+  );
+}

package/src/tools/media/ImageViewer/components/index.ts

@@ -5,3 +5,5 @@
 export { ImageViewer } from './ImageViewer';
 export { ImageToolbar } from './ImageToolbar';
 export { ImageInfo } from './ImageInfo';
+export { LightboxChrome } from './LightboxChrome';
+export { MiddleEllipsis } from './MiddleEllipsis';

package/src/tools/media/ImageViewer/hooks/index.ts

@@ -7,3 +7,6 @@ export type { UseImageTransformOptions, UseImageTransformReturn } from './useIma
 
 export { useImageLoading } from './useImageLoading';
 export type { UseImageLoadingOptions, UseImageLoadingReturn } from './useImageLoading';
+
+export { useIdleChrome } from './useIdleChrome';
+export type { UseIdleChromeReturn } from './useIdleChrome';

package/src/tools/media/ImageViewer/hooks/useIdleChrome.ts

@@ -0,0 +1,73 @@
+'use client';
+
+/**
+ * useIdleChrome - Auto-hides floating lightbox chrome when the pointer rests.
+ *
+ * macOS Quick Look / Preview hide their controls after a short idle period and
+ * bring them back on the slightest pointer movement. This hook tracks that
+ * "active" flag and gives back the pointer handlers to wire onto the canvas.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { CHROME_IDLE_MS } from '../utils';
+
+export interface UseIdleChromeReturn {
+  /** True while the chrome should be visible (recent pointer activity). */
+  active: boolean;
+  /** Pointer-move handler — call to mark activity (resets the idle timer). */
+  onActivity: () => void;
+  /** Pin the chrome open (e.g. while hovering a control) regardless of idle. */
+  setPinned: (pinned: boolean) => void;
+}
+
+export function useIdleChrome(enabled: boolean): UseIdleChromeReturn {
+  const [active, setActive] = useState(true);
+  const pinnedRef = useRef(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clear = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const schedule = useCallback(() => {
+    clear();
+    if (!enabled) return;
+    timerRef.current = setTimeout(() => {
+      if (!pinnedRef.current) setActive(false);
+    }, CHROME_IDLE_MS);
+  }, [clear, enabled]);
+
+  const onActivity = useCallback(() => {
+    setActive(true);
+    schedule();
+  }, [schedule]);
+
+  const setPinned = useCallback(
+    (pinned: boolean) => {
+      pinnedRef.current = pinned;
+      if (pinned) {
+        clear();
+        setActive(true);
+      } else {
+        schedule();
+      }
+    },
+    [clear, schedule],
+  );
+
+  // Start the idle countdown on mount; chrome shows briefly then fades.
+  useEffect(() => {
+    if (!enabled) {
+      setActive(true);
+      return;
+    }
+    schedule();
+    return clear;
+  }, [enabled, schedule, clear]);
+
+  return { active, onActivity, setPinned };
+}

package/src/tools/media/ImageViewer/types.ts

@@ -43,6 +43,16 @@ export interface ImageViewerProps {
   initialIndex?: number;
   /** Hide expand button when already in dialog */
   inDialog?: boolean;
+  /**
+   * Render the restrained macOS-grade fullscreen lightbox chrome instead of
+   * the embedded editing toolbar: a clean dark backdrop (no checkerboard),
+   * idle-fading floating controls (close + prev/next + status pill), and no
+   * rotate/flip slab. Intended for the click-to-expand image lightbox.
+   * Implies `inDialog`.
+   */
+  lightbox?: boolean;
+  /** Close request from the lightbox chrome (Esc / close button). */
+  onRequestClose?: () => void;
   /** Focus the viewer container on mount so its keyboard scope is active
    *  immediately (zoom/rotate/gallery hotkeys). Pair with `key={src}`
    *  upstream when the parent wants a fresh focus per source change. */

package/src/tools/media/ImageViewer/utils/constants.ts

@@ -40,6 +40,34 @@ export const MAX_ZOOM = 8;
 /** Pixels to pan per arrow-key press */
 export const KEYBOARD_PAN_STEP = 60;
 
+// =============================================================================
+// GESTURE SENSITIVITY (macOS-grade pinch / trackpad zoom)
+// =============================================================================
+//
+// react-zoom-pan-pinch computes the per-event wheel zoom magnitude as
+// `smoothStep * |event.deltaY|` (its `smooth` path), which means the scale
+// tracks the gesture 1:1 — a harder pinch / faster wheel moves more. The
+// library default `smoothStep` is `0.001`, which on a macOS trackpad
+// (whose pinch `deltaY` arrives as small ~±1–6 values with `ctrlKey=true`)
+// produces ~0.005 scale/frame — imperceptible, the "weak pinch" symptom.
+//
+// We raise it so a natural trackpad pinch reaches a meaningful zoom in a
+// single gesture while a mouse-wheel-with-ctrl notch (large |deltaY| ~100)
+// stays a sensible discrete step. The library clamps to min/max scale, so
+// the larger coefficient cannot overshoot the bounds.
+
+/** Wheel/trackpad-pinch zoom sensitivity. scaleΔ = WHEEL_SMOOTH_STEP * |deltaY|. */
+export const WHEEL_SMOOTH_STEP = 0.0055;
+
+/** Touch pinch sensitivity (two-finger pinch on touchscreens). */
+export const PINCH_STEP = 5;
+
+/** Double-click / double-tap zoom multiplier (fit ↔ zoomed toward the point). */
+export const DOUBLE_CLICK_STEP = 1.4;
+
+/** Idle delay (ms) before the lightbox chrome fades out when the pointer rests. */
+export const CHROME_IDLE_MS = 2200;
+
 /** Available zoom presets */
 export const ZOOM_PRESETS: readonly ZoomPreset[] = [
   { label: 'Fit', value: 'fit' },

package/src/tools/media/ImageViewer/utils/index.ts

@@ -12,6 +12,10 @@ export {
   MIN_ZOOM,
   MAX_ZOOM,
   KEYBOARD_PAN_STEP,
+  WHEEL_SMOOTH_STEP,
+  PINCH_STEP,
+  DOUBLE_CLICK_STEP,
+  CHROME_IDLE_MS,
   ZOOM_PRESETS,
   DEFAULT_TRANSFORM,
 } from './constants';

package/src/tools/media/VideoPlayer/VideoPlayer.tsx

@@ -12,8 +12,8 @@
  * iframe sources where the embed renders its own UI).
  */
 
-import { useCallback, useEffect, useMemo, useRef, type CSSProperties } from 'react';
-import { MediaController } from 'media-chrome/react';
+import { useEffect, useMemo, useRef, type CSSProperties } from 'react';
+import { MediaController, MediaGestureReceiver } from 'media-chrome/react';
 import { cn } from '@djangocfg/ui-core/lib';
 import './styles/video-player.css';
 
@@ -23,6 +23,7 @@ import { CanvasDispatcher } from './canvas/canvas-dispatcher';
 import {
   ControlsBar,
   PlayButton,
+  CenterPlay,
   SeekBar,
   Volume,
   PlaybackRate,
@@ -50,11 +51,20 @@ export function VideoPlayer({
     [source],
   );
 
-  const isIframe = normalized.type === 'iframe';
-  const isYouTube = normalized.type === 'youtube';
-  // For iframe embeds media-chrome cannot drive the inner player — hide the
-  // control bar to avoid a non-functional UI.
-  const showControls = controls && !isIframe;
+  // Provider embeds (YouTube / Vimeo) render their own native control set
+  // inside an opaque iframe. media-chrome can request play/pause but its
+  // `[mediapaused]` state desyncs from the real player, and YouTube's ToS
+  // chrome (title bar, branding tray, share/clock icons) bleeds through and
+  // CANNOT be hidden — so layering OUR controls on top produces a duplicate,
+  // jittery UI (two play affordances, two bottom bars). For these sources we
+  // let the native player own playback entirely: one coherent control set,
+  // native hover behaviour, zero duplication. Direct media (native `<video>`,
+  // HLS) is fully driven by media-chrome, so we keep OUR themed controls.
+  const isProviderEmbed =
+    normalized.type === 'iframe' ||
+    normalized.type === 'youtube' ||
+    normalized.type === 'vimeo';
+  const showControls = controls && !isProviderEmbed;
 
   // MediaController is a custom element; without `tabindex` it cannot take
   // focus, so its built-in keyboard shortcuts (space/arrows/f) never fire.
@@ -63,19 +73,6 @@ export function VideoPlayer({
   // fields we don't need to see.
   const controllerRef = useRef<HTMLElement | null>(null);
 
-  // Click-to-play overlay for YouTube — the underlying YT iframe is made
-  // `pointer-events: none` via CSS to suppress YouTube's own hover-state /
-  // UI (title bar, pause-screen, branding tray; ToS forbids hiding them,
-  // but we can make them inert). This overlay restores click-to-toggle
-  // by dispatching media-chrome request events the controller listens for.
-  const onYouTubeShieldClick = useCallback(() => {
-    const el = controllerRef.current;
-    if (!el) return;
-    const paused = el.hasAttribute('mediapaused');
-    const eventName = paused ? 'mediaplayrequest' : 'mediapauserequest';
-    el.dispatchEvent(new CustomEvent(eventName, { bubbles: true, composed: true }));
-  }, []);
-
   useEffect(() => {
     if (!autoFocus) return;
     const el = controllerRef.current;
@@ -100,28 +97,25 @@ export function VideoPlayer({
       style={aspectRatioStyle(aspectRatio)}
     >
       <CanvasDispatcher source={normalized} {...settings} />
-      {isYouTube && (
-        // Transparent click-shield over the YT iframe. The iframe itself
-        // is pointer-events:none (see video-player.css); this div absorbs
-        // pointer events and forwards a play/pause request to media-chrome,
-        // so users still get click-to-toggle without ever interacting with
-        // YouTube's own UI.
-        <div
-          className="vp-yt-click-shield"
-          onClick={onYouTubeShieldClick}
-          aria-hidden="true"
-        />
-      )}
+      {/* Click / tap anywhere on the video toggles play. media-chrome's
+          gesture receiver handles desktop click + mobile tap (and on touch
+          a tap also reveals/hides the controls). Only mounted for direct
+          media — provider embeds own their own click handling natively. */}
+      {showControls && <MediaGestureReceiver />}
       {children ??
         (showControls && (
-          <ControlsBar>
-            <PlayButton />
-            <SeekBar />
-            <Volume iconOnly />
-            <PlaybackRate />
-            <Pip />
-            <Fullscreen />
-          </ControlsBar>
+          <>
+            {/* Big centered play over the poster / paused frame. */}
+            <CenterPlay />
+            <ControlsBar>
+              <PlayButton />
+              <SeekBar />
+              <Volume iconOnly />
+              <PlaybackRate />
+              <Pip />
+              <Fullscreen />
+            </ControlsBar>
+          </>
         ))}
     </MediaController>
   );

package/src/tools/media/VideoPlayer/canvas/youtube-canvas.tsx

@@ -6,16 +6,18 @@
  * YouTube IFrame API and exposes an `HTMLVideoElement`-shaped surface
  * that media-chrome's `<MediaController>` drives.
  *
- * `youtube-video-element` already defaults the embed to `controls=0`,
- * `rel=0`, `iv_load_policy=3`, `modestbranding=1`. We extend that via
- * the `config` prop (serialized into `data-config`, merged into the
- * IFrame `playerVars`) to also suppress YouTube's keyboard handling
- * (`disablekb=1` — our controls own keyboard) and the in-player
- * close-captions toggle the element turns on by default.
+ * YouTube embeds render their OWN native control set inside the iframe,
+ * and YouTube's ToS chrome (title bar, branding tray, share/clock icons)
+ * cannot be hidden via player params. Trying to drive the embed with our
+ * own media-chrome controls layered on top produced a duplicate, jittery
+ * UI (two play buttons, two bottom bars) — see VideoPlayer.tsx. So for
+ * YouTube we let the native player own playback entirely: `controls=1`
+ * gives YouTube's standard hover-to-reveal controls with seek bar, time,
+ * volume and fullscreen — one coherent, familiar control set.
  *
- * NOTE: YouTube's ToS forbids fully hiding its branding — a small logo
- * and the pause-screen overlay remain by design. `modestbranding=1` is
- * the maximum allowed suppression.
+ * We still pass `rel=0`, `modestbranding=1`, `iv_load_policy=3` to trim
+ * end-screen suggestions, annotations and branding to the maximum the
+ * ToS allows.
  */
 
 import 'youtube-video-element';
@@ -33,10 +35,8 @@ export interface YouTubeCanvasProps extends VideoPlayerSettings {
  * https://developers.google.com/youtube/player_parameters
  */
 const YT_PLAYER_VARS = {
-  // We render our own media-chrome control bar — hide YouTube's.
-  controls: 0,
-  // Our keyboard shortcuts own the player; disable YouTube's.
-  disablekb: 1,
+  // YouTube's native controls own playback (no duplicate media-chrome bar).
+  controls: 1,
   // Minimise the YouTube logo chrome (max suppression allowed by ToS).
   modestbranding: 1,
   // Do not surface "More videos" / related-channel end-screen suggestions.

package/src/tools/media/VideoPlayer/parts/center-play.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import { MediaPlayButton } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ComponentProps } from 'react';
+
+export type CenterPlayProps = ComponentProps<typeof MediaPlayButton>;
+
+/**
+ * Big centered play affordance shown over the poster / paused frame
+ * (YouTube / Telegram style). A translucent dark disc with a white glyph so
+ * it stays legible on ANY poster — light or dark. It lives in media-chrome's
+ * `centered-chrome` slot and is faded out while playing via CSS (see
+ * `video-player.css` → `.vp-center-play`).
+ */
+export function CenterPlay({ className, ...props }: CenterPlayProps) {
+  return (
+    <MediaPlayButton
+      {...props}
+      slot="centered-chrome"
+      tabIndex={-1}
+      aria-hidden="true"
+      className={cn('vp-center-play', className)}
+    />
+  );
+}

package/src/tools/media/VideoPlayer/parts/index.ts

@@ -1,5 +1,7 @@
 export { PlayButton } from './play-button';
 export type { PlayButtonProps } from './play-button';
+export { CenterPlay } from './center-play';
+export type { CenterPlayProps } from './center-play';
 export { SeekBar } from './seek-bar';
 export type { SeekBarProps } from './seek-bar';
 export { Volume } from './volume';

package/src/tools/media/VideoPlayer/styles/video-player.css

@@ -33,7 +33,11 @@ media-controller {
   --media-range-track-background: color-mix(in oklab, white 28%, transparent);
   --media-range-track-border-radius: 9999px;
   --media-range-track-height: 4px;
-  --media-range-track-pointer-background: color-mix(in oklab, white 40%, transparent);
+  /* Pointer-fill (the lit rail from start → cursor on hover). The default
+     `white 40%` paints a muddy light bar over a bright video frame; keep
+     it barely above the base track so hover reads as a subtle highlight,
+     not a slab. */
+  --media-range-track-pointer-background: color-mix(in oklab, white 12%, transparent);
   --media-range-bar-color: var(--primary);
   --media-range-thumb-background: var(--primary);
   --media-range-thumb-border-radius: 9999px;
@@ -82,6 +86,57 @@ media-control-bar {
   background: transparent;
 }
 
+/*
+ * Big centered play affordance (YouTube / Telegram style). A translucent
+ * dark disc + white glyph so it reads on ANY poster, light or dark. Shown
+ * only while paused; fades out smoothly once playback starts. The
+ * `centered-chrome` slot is centered by media-chrome; we size the disc and
+ * scale the icon up via the play-button's `::part(button)`.
+ */
+.vp-center-play {
+  --media-control-background: rgb(0 0 0 / 0.55);
+  --media-control-hover-background: rgb(0 0 0 / 0.7);
+  width: 64px;
+  height: 64px;
+  padding: 0;
+  border-radius: 9999px;
+  color: rgb(255 255 255);
+  backdrop-filter: blur(2px);
+  box-shadow: 0 4px 16px rgb(0 0 0 / 0.35);
+  transition: opacity 0.2s ease, transform 0.2s ease;
+  cursor: pointer;
+}
+
+.vp-center-play svg {
+  width: 28px;
+  height: 28px;
+}
+
+/* Hide the big play once the video is actually playing. */
+media-controller:not([mediapaused]) .vp-center-play {
+  opacity: 0;
+  transform: scale(0.9);
+  pointer-events: none;
+}
+
+/* The gesture receiver catches click/tap anywhere on the video to toggle
+   play. It covers the whole frame (`inset: 0`) and must sit BELOW the
+   control bar / center play — otherwise it overlays those buttons and
+   swallows their clicks (the bug: clicking center-play did nothing while
+   the spacebar still worked). z-index:0 keeps it above the canvas but
+   under the controls, which we lift to z-index:2 below. */
+media-gesture-receiver {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+}
+
+/* Controls sit ABOVE the gesture receiver so their clicks land on them. */
+.vp-center-play,
+.video-player__control-bar {
+  z-index: 2;
+}
+
 /*
  * Suppress media-chrome's built-in tooltips. They are sticky elements
  * slotted under each control button's shadow root (exposed via
@@ -106,16 +161,32 @@ media-seek-backward-button::part(tooltip) {
 }
 
 /*
- * Auto-hide. media-chrome flags inactivity by setting `userinactive` on
- * the <media-controller>; it only does so while playback is running, and
- * removes it on mousemove / pause / focus. We fade the whole control bar
- * (controls + gradient scrim) together with a smooth opacity transition.
+ * Control-bar visibility — YouTube-style, exactly one play affordance.
+ *
+ * - PAUSED (incl. before first play): the big center-play owns the frame;
+ *   the bottom bar is hidden so there are never TWO play buttons at once.
+ * - PLAYING: center-play is gone (faded by the rule above); the bottom bar
+ *   reveals on hover / interaction and auto-hides after media-chrome flags
+ *   inactivity (`userinactive`, driven by `autohide` on <media-controller>),
+ *   so the frame stays clean while watching. It reappears on mousemove /
+ *   focus.
+ *
+ * media-chrome sets `userinactive` only while playback runs and removes it
+ * on mousemove / pause / focus. We fade the whole bar (controls + gradient
+ * scrim) together.
  */
 .video-player__control-bar {
   opacity: 1;
   transition: opacity 0.3s ease-out;
 }
 
+/* Hide the bar while paused — center-play is the sole control then. */
+media-controller[mediapaused] .video-player__control-bar {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* Auto-hide the bar after inactivity while playing. */
 media-controller[userinactive]:not([mediapaused]) .video-player__control-bar {
   opacity: 0;
   pointer-events: none;
@@ -129,8 +200,10 @@ media-controller[userinactive]:not([mediapaused]) .video-player__control-bar {
  * dark `rgb(31,31,31)` background — it shows as a stray empty
  * rectangle floating over the video.
  *
- * Hide the empty preview-box entirely; keep `current-box` and style
- * its time label as a compact popover chip.
+ * Both the empty `preview-box` and the `current-box` scrub chip are hidden
+ * (see the `::part` rules below) — without a thumbnails track neither
+ * carries useful content, and the elapsed time already shows in
+ * `<MediaTimeDisplay>`.
  */
 media-time-range {
   /* media-chrome's own preview/box vars — point them at our popover
@@ -168,54 +241,30 @@ media-time-range::part(preview-box) {
 }
 
 /*
- * YouTube iframe bleed-through suppression.
- *
- * YouTube's IFrame embed ToS requires showing some chrome that cannot be
- * hidden via player params: the title bar at the top, the large pause
- * button on the pause screen, and the bottom branding/share tray on
- * hover/pause. We can't remove them, but we CAN make them non-interactive
- * — so the user never triggers YouTube's hover-state, never gets a
- * "More videos" overlay, and clicks never reach the YT iframe.
- *
- * The <youtube-video> custom element renders an inner <iframe>; disable
- * pointer events on it (and on the wrapper itself, just in case the
- * element later swaps layout). The companion `.vp-yt-click-shield` div
- * inside <media-controller> absorbs clicks and converts them into
- * media-chrome play/pause requests — so click-to-toggle still works.
- *
- * Our control bar lives above the shield and re-enables pointer events
- * for the slot, so the controls stay clickable.
+ * `current-box` (the scrub-time chip) renders as a small white box ABOVE
+ * the rail at the pointer position. Without a thumbnails track it carries
+ * no useful preview, and the elapsed time already lives in
+ * `<MediaTimeDisplay>` — so it only ever shows as a stray white dash over
+ * the video. Hide it entirely, same as `preview-box`.
  */
-youtube-video,
-youtube-video iframe {
-  pointer-events: none;
-}
-
-.vp-yt-click-shield {
-  position: absolute;
-  inset: 0;
-  cursor: pointer;
-  background: transparent;
-  pointer-events: auto;
-  /* Sit above the iframe but below the slotted control bar. */
-  z-index: 1;
+media-time-range::part(current-box) {
+  display: none;
 }
 
-/* media-chrome slots its control surfaces directly under
-   <media-controller>; raise them above the click-shield and restore
-   pointer events so buttons remain interactive. */
-media-controller > media-control-bar,
-media-controller > [slot='centered-chrome'],
-media-controller > [slot='top-chrome'] {
-  z-index: 2;
+/*
+ * Provider embeds (YouTube / Vimeo) own their native controls.
+ *
+ * media-chrome cannot reliably drive an opaque provider iframe, and
+ * YouTube's ToS chrome (title bar, branding tray, share/clock icons)
+ * bleeds through and can't be hidden — layering OUR controls on top
+ * produced a duplicate, jittery UI. So we render NO media-chrome control
+ * surface for these sources (see `showControls` in VideoPlayer.tsx) and
+ * let the native player handle playback, hover-reveal and fullscreen.
+ *
+ * The provider iframe must stay fully interactive so its native controls
+ * work — so we explicitly DON'T disable pointer events here.
+ */
+youtube-video iframe,
+vimeo-video iframe {
   pointer-events: auto;
 }
-
-media-time-range::part(current-box) {
-  padding: 2px 6px;
-  border-radius: 6px;
-  background: var(--popover) !important;
-  color: var(--popover-foreground);
-  font-size: 11px;
-  box-shadow: 0 4px 12px color-mix(in oklab, var(--foreground) 18%, transparent);
-}