@particle-academy/react-fancy 4.8.1 → 4.9.0

package/README.md

@@ -166,6 +166,18 @@ npx vite build                      # Build demo app (verifies imports work)
 | Diagram | Entity-relationship diagram with draggable nodes and relation lines | [docs](docs/Diagram.md) |
 | ContentRenderer | Markdown/HTML content renderer | [docs](docs/ContentRenderer.md) |
 
+### Media Viewers
+
+Standalone, read-only viewers for displaying media files — drop one in anywhere, or use `<MediaViewer>` to pick the right one from a `mime`/`src` when you don't know the type ahead of time (e.g. showing a file from a tree). SVG renders through `ImageViewer`.
+
+| Component | Description | Docs |
+|-----------|-------------|------|
+| MediaViewer | Picks image/video/audio/PDF from `mime` (or `src`) + download fallback | [docs](docs/MediaViewer.md) |
+| ImageViewer | Fit-to-container image with zoom/pan and transparency checkerboard | [docs](docs/ImageViewer.md) |
+| VideoViewer | Native video controls, poster, fit | [docs](docs/VideoViewer.md) |
+| AudioViewer | Themed card around the native audio player | [docs](docs/AudioViewer.md) |
+| PdfViewer | Inline PDF via `<object>`/`<iframe>` with download fallback | [docs](docs/PdfViewer.md) |
+
 ### Human+ Primitives
 
 Components for surfaces where humans and AI agents trade control fluidly. Each promoted from the [`dreaming`](https://github.com/Particle-Academy/pa-ux-sandbox/tree/dreaming) sandbox after the API stabilized.
@@ -191,6 +203,7 @@ Components for surfaces where humans and AI agents trade control fluidly. Each p
 |--------|-------------|------|
 | Portal | `createPortal` wrapper with automatic dark mode propagation | [docs](docs/Portal.md) |
 | `cn()` | `clsx` + `tailwind-merge` for conditional class composition | [docs](docs/utilities.md) |
+| `resolveMediaType()` | Resolve `image`/`video`/`audio`/`pdf`/`unknown` from a `mime` and/or `src` | [docs](docs/MediaViewer.md) |
 | Hooks | useControllableState, useFloatingPosition, useOutsideClick, useEscapeKey, useFocusTrap, useAnimation, useId, usePanZoom | [docs](docs/hooks.md) |
 
 ## Customization

package/dist/index.cjs

@@ -13026,6 +13026,108 @@ TreeNavRoot.displayName = "TreeNav";
 var TreeNav = Object.assign(TreeNavRoot, {
   Node: TreeNode
 });
+
+// src/utils/media-type.ts
+var IMAGE_EXTS = /* @__PURE__ */ new Set([
+  "png",
+  "jpg",
+  "jpeg",
+  "jfif",
+  "pjpeg",
+  "gif",
+  "webp",
+  "avif",
+  "bmp",
+  "ico",
+  "cur",
+  "svg",
+  "svgz",
+  "apng",
+  "tif",
+  "tiff",
+  "heic",
+  "heif"
+]);
+var VIDEO_EXTS = /* @__PURE__ */ new Set([
+  "mp4",
+  "m4v",
+  "webm",
+  "ogv",
+  "ogm",
+  "mov",
+  "mkv",
+  "avi",
+  "wmv",
+  "flv",
+  "3gp",
+  "3g2",
+  "mpg",
+  "mpeg"
+]);
+var AUDIO_EXTS = /* @__PURE__ */ new Set([
+  "mp3",
+  "wav",
+  "wave",
+  "ogg",
+  "oga",
+  "m4a",
+  "m4b",
+  "aac",
+  "flac",
+  "opus",
+  "weba",
+  "mid",
+  "midi",
+  "aiff",
+  "aif"
+]);
+function mimeToKind(mime) {
+  const m = mime.toLowerCase().split(";")[0].trim();
+  if (!m) return "unknown";
+  if (m === "application/pdf" || m === "application/x-pdf") return "pdf";
+  if (m.startsWith("image/")) return "image";
+  if (m.startsWith("video/")) return "video";
+  if (m.startsWith("audio/")) return "audio";
+  if (m === "application/ogg") return "audio";
+  return "unknown";
+}
+function extToKind(ext) {
+  const e = ext.toLowerCase();
+  if (e === "pdf") return "pdf";
+  if (IMAGE_EXTS.has(e)) return "image";
+  if (VIDEO_EXTS.has(e)) return "video";
+  if (AUDIO_EXTS.has(e)) return "audio";
+  return "unknown";
+}
+function extFromSrc(src) {
+  const clean = src.split(/[?#]/, 1)[0];
+  const lastSeg = clean.split("/").pop() ?? "";
+  const dot = lastSeg.lastIndexOf(".");
+  if (dot <= 0 || dot === lastSeg.length - 1) return null;
+  return lastSeg.slice(dot + 1);
+}
+function mimeFromDataUri(src) {
+  if (!/^data:/i.test(src)) return null;
+  const header = src.slice(5).split(",", 1)[0];
+  const mt = header.split(";")[0].trim();
+  return mt || null;
+}
+function resolveMediaType({ mime, src }) {
+  if (mime) {
+    const k = mimeToKind(mime);
+    if (k !== "unknown") return k;
+  }
+  if (src) {
+    const dataMime = mimeFromDataUri(src);
+    if (dataMime) {
+      const k = mimeToKind(dataMime);
+      if (k !== "unknown") return k;
+    }
+    const ext = extFromSrc(src);
+    if (ext) return extToKind(ext);
+  }
+  return "unknown";
+}
 var CONFIDENCE_TIERS = [
   { min: 0.85, color: "#10b981", label: "high" },
   { min: 0.6, color: "#f59e0b", label: "medium" },
@@ -14298,6 +14400,446 @@ function caretRect(ta, start, end) {
   const y = taRect.top - parentRect.top + offsetY - ta.scrollTop;
   return { x, y };
 }
+var DEFAULT_VIEWPORT = { panX: 0, panY: 0, zoom: 1 };
+var fitClasses = {
+  contain: "h-full w-full object-contain",
+  cover: "h-full w-full object-cover",
+  none: "max-w-none object-none"
+};
+function clamp2(n, min, max) {
+  return Math.min(max, Math.max(min, n));
+}
+var ImageViewer = react.forwardRef(
+  ({
+    src,
+    alt = "",
+    fit = "contain",
+    zoomable = true,
+    pannable = true,
+    controls,
+    minZoom = 0.25,
+    maxZoom = 8,
+    checkerboard = true,
+    viewport,
+    defaultViewport,
+    onViewportChange,
+    onLoad,
+    onError,
+    className,
+    style
+  }, ref) => {
+    const containerRef = react.useRef(null);
+    const [status, setStatus] = react.useState("loading");
+    const isControlled = viewport !== void 0;
+    const [internal, setInternal] = react.useState(
+      defaultViewport ?? DEFAULT_VIEWPORT
+    );
+    const current = isControlled ? viewport : internal;
+    const currentRef = react.useRef(current);
+    currentRef.current = current;
+    const setViewport = react.useCallback(
+      (next) => {
+        const resolved = typeof next === "function" ? next(currentRef.current) : next;
+        if (!isControlled) setInternal(resolved);
+        onViewportChange?.(resolved);
+      },
+      [isControlled, onViewportChange]
+    );
+    const interactive = status === "loaded";
+    const { containerProps, isPanning } = usePanZoom({
+      viewport: current,
+      setViewport,
+      minZoom,
+      maxZoom,
+      pannable: pannable && interactive,
+      zoomable: zoomable && interactive,
+      containerRef
+    });
+    const zoomBy = react.useCallback(
+      (factor) => {
+        const el = containerRef.current;
+        if (!el) return;
+        const rect = el.getBoundingClientRect();
+        const cx = rect.width / 2;
+        const cy = rect.height / 2;
+        setViewport((prev) => {
+          const newZoom = clamp2(prev.zoom * factor, minZoom, maxZoom);
+          const ratio = newZoom / prev.zoom;
+          return {
+            zoom: newZoom,
+            panX: cx - (cx - prev.panX) * ratio,
+            panY: cy - (cy - prev.panY) * ratio
+          };
+        });
+      },
+      [setViewport, minZoom, maxZoom]
+    );
+    const reset = react.useCallback(() => setViewport(DEFAULT_VIEWPORT), [setViewport]);
+    const showControls = (controls ?? zoomable) && interactive;
+    const transform = `translate(${current.panX}px, ${current.panY}px) scale(${current.zoom})`;
+    return /* @__PURE__ */ jsxRuntime.jsxs(
+      "div",
+      {
+        ref,
+        "data-react-fancy-image-viewer": "",
+        className: cn(
+          "relative isolate overflow-hidden rounded-md select-none",
+          checkerboard ? "fancy-checkerboard" : "bg-zinc-100 dark:bg-zinc-900",
+          className
+        ),
+        style,
+        children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "div",
+            {
+              ref: containerRef,
+              "data-canvas-bg": "",
+              className: cn(
+                "absolute inset-0 flex items-center justify-center",
+                isPanning ? "cursor-grabbing" : pannable && interactive ? "cursor-grab" : ""
+              ),
+              style: {
+                transform,
+                transformOrigin: "0 0",
+                willChange: "transform",
+                touchAction: zoomable || pannable ? "none" : void 0
+              },
+              onDoubleClick: zoomable ? reset : void 0,
+              ...containerProps,
+              children: /* @__PURE__ */ jsxRuntime.jsx(
+                "img",
+                {
+                  src,
+                  alt,
+                  draggable: false,
+                  onLoad: () => {
+                    setStatus("loaded");
+                    onLoad?.();
+                  },
+                  onError: () => {
+                    setStatus("error");
+                    onError?.();
+                  },
+                  className: cn(
+                    "pointer-events-none block",
+                    status === "error" && "hidden",
+                    fitClasses[fit]
+                  )
+                }
+              )
+            }
+          ),
+          status === "error" && /* @__PURE__ */ jsxRuntime.jsxs(
+            "div",
+            {
+              "data-react-fancy-image-viewer-error": "",
+              className: "absolute inset-0 flex flex-col items-center justify-center gap-1 p-4 text-center text-sm text-zinc-500 dark:text-zinc-400",
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-medium", children: "Couldn't load image" }),
+                /* @__PURE__ */ jsxRuntime.jsx("span", { className: "max-w-full truncate text-xs opacity-70", children: alt || src })
+              ]
+            }
+          ),
+          showControls && /* @__PURE__ */ jsxRuntime.jsxs(
+            "div",
+            {
+              "data-react-fancy-image-viewer-controls": "",
+              className: "absolute bottom-2 right-2 flex items-center gap-0.5 rounded-md border border-zinc-200 bg-white/90 p-0.5 text-zinc-700 shadow-sm backdrop-blur dark:border-zinc-700 dark:bg-zinc-900/90 dark:text-zinc-200",
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "button",
+                  {
+                    type: "button",
+                    "aria-label": "Zoom out",
+                    onClick: () => zoomBy(1 / 1.25),
+                    className: "flex h-6 w-6 items-center justify-center rounded text-base leading-none hover:bg-zinc-100 dark:hover:bg-zinc-800",
+                    children: "\u2212"
+                  }
+                ),
+                /* @__PURE__ */ jsxRuntime.jsxs(
+                  "button",
+                  {
+                    type: "button",
+                    "aria-label": "Reset zoom",
+                    onClick: reset,
+                    className: "min-w-[3rem] rounded px-1 text-center text-xs tabular-nums hover:bg-zinc-100 dark:hover:bg-zinc-800",
+                    children: [
+                      Math.round(current.zoom * 100),
+                      "%"
+                    ]
+                  }
+                ),
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "button",
+                  {
+                    type: "button",
+                    "aria-label": "Zoom in",
+                    onClick: () => zoomBy(1.25),
+                    className: "flex h-6 w-6 items-center justify-center rounded text-base leading-none hover:bg-zinc-100 dark:hover:bg-zinc-800",
+                    children: "+"
+                  }
+                )
+              ]
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+ImageViewer.displayName = "ImageViewer";
+var VideoViewer = react.forwardRef(
+  ({
+    src,
+    poster,
+    controls = true,
+    autoPlay = false,
+    loop = false,
+    muted = false,
+    fit = "contain",
+    onError,
+    className,
+    style
+  }, ref) => {
+    const [errored, setErrored] = react.useState(false);
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        ref,
+        "data-react-fancy-video-viewer": "",
+        className: cn(
+          "relative flex items-center justify-center overflow-hidden rounded-md bg-black",
+          className
+        ),
+        style,
+        children: errored ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col items-center justify-center gap-1 p-4 text-center text-sm text-zinc-400", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-medium", children: "Couldn't load video" }),
+          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "max-w-full truncate text-xs opacity-70", children: src })
+        ] }) : /* @__PURE__ */ jsxRuntime.jsx(
+          "video",
+          {
+            src,
+            poster,
+            controls,
+            autoPlay,
+            loop,
+            muted,
+            playsInline: true,
+            onError: () => {
+              setErrored(true);
+              onError?.();
+            },
+            className: cn(
+              "max-h-full max-w-full",
+              fit === "cover" ? "h-full w-full object-cover" : "object-contain"
+            )
+          }
+        )
+      }
+    );
+  }
+);
+VideoViewer.displayName = "VideoViewer";
+var AudioViewer = react.forwardRef(
+  ({
+    src,
+    title,
+    controls = true,
+    autoPlay = false,
+    loop = false,
+    onError,
+    className,
+    style
+  }, ref) => {
+    const [errored, setErrored] = react.useState(false);
+    return /* @__PURE__ */ jsxRuntime.jsxs(
+      "div",
+      {
+        ref,
+        "data-react-fancy-audio-viewer": "",
+        className: cn(
+          "flex flex-col gap-2 rounded-lg border border-zinc-200 bg-white p-4 dark:border-zinc-700 dark:bg-zinc-900",
+          className
+        ),
+        style,
+        children: [
+          title && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "truncate text-sm font-medium text-zinc-700 dark:text-zinc-200", children: title }),
+          errored ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "text-sm text-zinc-500 dark:text-zinc-400", children: "Couldn't load audio." }) : /* @__PURE__ */ jsxRuntime.jsx(
+            "audio",
+            {
+              src,
+              controls,
+              autoPlay,
+              loop,
+              onError: () => {
+                setErrored(true);
+                onError?.();
+              },
+              className: "w-full"
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+AudioViewer.displayName = "AudioViewer";
+var PdfViewer = react.forwardRef(
+  ({ src, title = "PDF document", className, style }, ref) => {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        ref,
+        "data-react-fancy-pdf-viewer": "",
+        className: cn(
+          "relative h-full min-h-[20rem] w-full overflow-hidden rounded-md bg-zinc-100 dark:bg-zinc-900",
+          className
+        ),
+        style,
+        children: /* @__PURE__ */ jsxRuntime.jsxs("object", { data: src, type: "application/pdf", className: "h-full w-full", children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "iframe",
+            {
+              src,
+              title,
+              className: "h-full w-full border-0"
+            }
+          ),
+          /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex h-full flex-col items-center justify-center gap-2 p-4 text-center text-sm text-zinc-500 dark:text-zinc-400", children: [
+            /* @__PURE__ */ jsxRuntime.jsx("span", { children: "This browser can't display the PDF inline." }),
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "a",
+              {
+                href: src,
+                download: true,
+                className: "font-medium text-blue-600 hover:underline dark:text-blue-400",
+                children: "Download PDF"
+              }
+            )
+          ] })
+        ] })
+      }
+    );
+  }
+);
+PdfViewer.displayName = "PdfViewer";
+function basename(src) {
+  if (/^(data|blob):/i.test(src)) return null;
+  const seg = src.split(/[?#]/, 1)[0].split("/").pop();
+  return seg ? decodeURIComponent(seg) : null;
+}
+function MediaFallback({ src, mime, label, className }) {
+  const name = label || basename(src);
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      "data-react-fancy-media-fallback": "",
+      className: cn(
+        "flex flex-col items-center justify-center gap-2 rounded-lg border border-zinc-200 bg-white p-6 text-center dark:border-zinc-700 dark:bg-zinc-900",
+        className
+      ),
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-sm font-medium text-zinc-700 dark:text-zinc-200", children: "No preview available" }),
+        (name || mime) && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "max-w-full truncate text-xs text-zinc-500 dark:text-zinc-400", children: [
+          name,
+          name && mime ? " \xB7 " : "",
+          mime
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "a",
+          {
+            href: src,
+            download: name ?? void 0,
+            className: "text-xs font-medium text-blue-600 hover:underline dark:text-blue-400",
+            children: "Download"
+          }
+        )
+      ]
+    }
+  );
+}
+var MediaViewer = react.forwardRef(
+  ({
+    src,
+    mime,
+    alt,
+    kind,
+    imageProps,
+    videoProps,
+    audioProps,
+    pdfProps,
+    fallback,
+    onError,
+    className,
+    style
+  }, ref) => {
+    const resolved = kind ?? resolveMediaType({ mime, src });
+    switch (resolved) {
+      case "image":
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          ImageViewer,
+          {
+            ref,
+            src,
+            alt: alt ?? "",
+            onError,
+            className,
+            style,
+            ...imageProps
+          }
+        );
+      case "video":
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          VideoViewer,
+          {
+            ref,
+            src,
+            onError,
+            className,
+            style,
+            ...videoProps
+          }
+        );
+      case "audio":
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          AudioViewer,
+          {
+            ref,
+            src,
+            title: alt,
+            onError,
+            className,
+            style,
+            ...audioProps
+          }
+        );
+      case "pdf":
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          PdfViewer,
+          {
+            ref,
+            src,
+            title: alt,
+            className,
+            style,
+            ...pdfProps
+          }
+        );
+      default:
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            ref,
+            "data-react-fancy-media-viewer": "",
+            className,
+            style,
+            children: fallback ?? /* @__PURE__ */ jsxRuntime.jsx(MediaFallback, { src, mime, label: alt })
+          }
+        );
+    }
+  }
+);
+MediaViewer.displayName = "MediaViewer";
 
 exports.Accordion = Accordion;
 exports.AccordionPanel = AccordionPanel;
@@ -14305,6 +14847,7 @@ exports.AccordionPanelContent = AccordionPanelContent;
 exports.AccordionPanelSection = AccordionPanelSection;
 exports.AccordionPanelTrigger = AccordionPanelTrigger;
 exports.Action = Action;
+exports.AudioViewer = AudioViewer;
 exports.Autocomplete = Autocomplete;
 exports.Avatar = Avatar;
 exports.Badge = Badge;
@@ -14341,10 +14884,12 @@ exports.Form = Form;
 exports.FormProvider = FormProvider;
 exports.Heading = Heading;
 exports.Icon = Icon;
+exports.ImageViewer = ImageViewer;
 exports.Input = Input;
 exports.InputTag = InputTag;
 exports.Kanban = Kanban;
 exports.MagicWand = MagicWand;
+exports.MediaViewer = MediaViewer;
 exports.Menu = Menu2;
 exports.MobileMenu = MobileMenu;
 exports.Modal = Modal;
@@ -14353,6 +14898,7 @@ exports.MultiSwitch = MultiSwitch;
 exports.Navbar = Navbar;
 exports.OtpInput = OtpInput;
 exports.Pagination = Pagination;
+exports.PdfViewer = PdfViewer;
 exports.Pillbox = Pillbox;
 exports.Popover = Popover;
 exports.Portal = Portal;
@@ -14379,6 +14925,7 @@ exports.Timeline = Timeline;
 exports.Toast = Toast;
 exports.Tooltip = Tooltip;
 exports.TreeNav = TreeNav;
+exports.VideoViewer = VideoViewer;
 exports.applyTone = applyTone;
 exports.cn = cn;
 exports.configureIcons = configureIcons;
@@ -14393,6 +14940,7 @@ exports.registerIconAddendum = registerIconAddendum;
 exports.registerIconSet = registerIconSet;
 exports.registerIcons = registerIcons;
 exports.resolve = resolve;
+exports.resolveMediaType = resolveMediaType;
 exports.sanitizeHref = sanitizeHref;
 exports.sanitizeHtml = sanitizeHtml;
 exports.search = search;