@godxjp/ui 31.10.3 → 31.11.1

package/dist/components/data-display/image.js

@@ -0,0 +1,502 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { mergeRefs } from "@react-aria/utils";
+import { Dialog as RacDialog, Modal, ModalOverlay } from "react-aria-components";
+import {
+  ChevronLeft,
+  ChevronRight,
+  Eye,
+  FlipHorizontal2,
+  FlipVertical2,
+  RotateCcw,
+  RotateCw,
+  Undo2,
+  X,
+  ZoomIn,
+  ZoomOut
+} from "lucide-react";
+import { useTranslation } from "../../i18n/use-translation.js";
+import { useOverlayPortalContainer } from "../../lib/overlay-portal.js";
+import { cn } from "../../lib/utils.js";
+import { useOverlayCloseFocus } from "../feedback/overlay-close-focus.js";
+const ImageGroupContext = React.createContext(null);
+const ImageGroupDisabledContext = React.createContext(false);
+const BASE_SCALE_RATIO = 1;
+const DEFAULT_SCALE_STEP = 0.5;
+const DEFAULT_MIN_SCALE = 1;
+const DEFAULT_MAX_SCALE = 50;
+const INITIAL_TRANSFORM = {
+  x: 0,
+  y: 0,
+  scale: 1,
+  rotate: 0,
+  flipX: false,
+  flipY: false
+};
+function toEntry(item) {
+  return typeof item === "string" ? { src: item, alt: "" } : { src: item.src, alt: item.alt ?? "" };
+}
+function useMergedState(controlled, initial, onChange) {
+  const [inner, setInner] = React.useState(initial);
+  const value = controlled ?? inner;
+  const set = React.useCallback(
+    (next) => {
+      if (Object.is(next, value)) return;
+      if (controlled === void 0) setInner(next);
+      onChange?.(next, value);
+    },
+    [controlled, onChange, value]
+  );
+  return [value, set];
+}
+function inDocumentOrder(entries) {
+  return [...entries].sort((a, b) => {
+    const na = a.node();
+    const nb = b.node();
+    if (!na || !nb) return 0;
+    return na.compareDocumentPosition(nb) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+  });
+}
+function isRtl(element) {
+  return element?.closest("[dir]")?.getAttribute("dir")?.toLowerCase() === "rtl";
+}
+function ImagePreviewDialog({
+  open,
+  onOpenChange,
+  items,
+  current,
+  onCurrentChange,
+  fallback,
+  scaleStep = DEFAULT_SCALE_STEP,
+  minScale = DEFAULT_MIN_SCALE,
+  maxScale = DEFAULT_MAX_SCALE
+}) {
+  const { t } = useTranslation();
+  const portalContainer = useOverlayPortalContainer();
+  useOverlayCloseFocus(open);
+  const sectionRef = React.useRef(null);
+  React.useEffect(() => {
+    const section = sectionRef.current;
+    if (open && section && !section.contains(document.activeElement)) {
+      section.focus({ preventScroll: true });
+    }
+  }, [open]);
+  const total = items.length;
+  const index = total === 0 ? 0 : Math.min(Math.max(current, 0), total - 1);
+  const entry = items[index];
+  const [transform, setTransform] = React.useState(INITIAL_TRANSFORM);
+  const [failedSrc, setFailedSrc] = React.useState(null);
+  const [dragging, setDragging] = React.useState(false);
+  const dragStart = React.useRef(null);
+  React.useEffect(() => {
+    setTransform(INITIAL_TRANSFORM);
+    setFailedSrc(null);
+  }, [index, open]);
+  const zoomBy = (ratio) => setTransform((prev) => {
+    const scale2 = Math.min(Math.max(prev.scale * ratio, minScale), maxScale);
+    return scale2 <= 1 ? { ...prev, scale: scale2, x: 0, y: 0 } : { ...prev, scale: scale2 };
+  });
+  const zoomIn = () => zoomBy(BASE_SCALE_RATIO + scaleStep);
+  const zoomOut = () => zoomBy(BASE_SCALE_RATIO / (BASE_SCALE_RATIO + scaleStep));
+  const hasPrev = index > 0;
+  const hasNext = index < total - 1;
+  const goPrev = () => hasPrev && onCurrentChange(index - 1);
+  const goNext = () => hasNext && onCurrentChange(index + 1);
+  const onKeyDown = (event) => {
+    if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
+    if (total < 2) return;
+    event.preventDefault();
+    const forward = event.key === "ArrowRight" !== isRtl(event.currentTarget);
+    if (forward) goNext();
+    else goPrev();
+  };
+  const onWheel = (event) => {
+    if (event.deltaY === 0) return;
+    if (event.deltaY < 0) zoomIn();
+    else zoomOut();
+  };
+  const onDoubleClick = () => {
+    if (transform.scale !== 1) setTransform((prev) => ({ ...prev, x: 0, y: 0, scale: 1 }));
+    else zoomIn();
+  };
+  const onPointerDown = (event) => {
+    if (event.button !== 0) return;
+    event.preventDefault();
+    event.currentTarget.setPointerCapture?.(event.pointerId);
+    dragStart.current = { px: event.clientX, py: event.clientY, x: transform.x, y: transform.y };
+    setDragging(true);
+  };
+  const onPointerMove = (event) => {
+    const start = dragStart.current;
+    if (!start) return;
+    setTransform((prev) => ({
+      ...prev,
+      x: start.x + event.clientX - start.px,
+      y: start.y + event.clientY - start.py
+    }));
+  };
+  const onPointerUp = () => {
+    if (!dragStart.current) return;
+    dragStart.current = null;
+    setDragging(false);
+    setTransform((prev) => prev.scale <= 1 ? { ...prev, x: 0, y: 0 } : prev);
+  };
+  const src = entry && failedSrc === entry.src && fallback ? fallback : entry?.src;
+  const { x, y, scale, rotate, flipX, flipY } = transform;
+  const imageTransform = `translate3d(${x}px, ${y}px, 0) scale3d(${flipX ? -scale : scale}, ${flipY ? -scale : scale}, 1) rotate(${rotate}deg)`;
+  const tools = [
+    {
+      key: "flipY",
+      label: t("dataDisplay.image.flipY"),
+      icon: /* @__PURE__ */ jsx(FlipVertical2, {}),
+      run: () => setTransform((p) => ({ ...p, flipY: !p.flipY }))
+    },
+    {
+      key: "flipX",
+      label: t("dataDisplay.image.flipX"),
+      icon: /* @__PURE__ */ jsx(FlipHorizontal2, {}),
+      run: () => setTransform((p) => ({ ...p, flipX: !p.flipX }))
+    },
+    {
+      key: "rotateLeft",
+      label: t("dataDisplay.image.rotateLeft"),
+      icon: /* @__PURE__ */ jsx(RotateCcw, {}),
+      run: () => setTransform((p) => ({ ...p, rotate: p.rotate - 90 }))
+    },
+    {
+      key: "rotateRight",
+      label: t("dataDisplay.image.rotateRight"),
+      icon: /* @__PURE__ */ jsx(RotateCw, {}),
+      run: () => setTransform((p) => ({ ...p, rotate: p.rotate + 90 }))
+    },
+    {
+      key: "zoomOut",
+      label: t("dataDisplay.image.zoomOut"),
+      icon: /* @__PURE__ */ jsx(ZoomOut, {}),
+      run: zoomOut,
+      off: scale <= minScale
+    },
+    {
+      key: "zoomIn",
+      label: t("dataDisplay.image.zoomIn"),
+      icon: /* @__PURE__ */ jsx(ZoomIn, {}),
+      run: zoomIn,
+      off: scale >= maxScale
+    },
+    {
+      key: "reset",
+      label: t("dataDisplay.image.reset"),
+      icon: /* @__PURE__ */ jsx(Undo2, {}),
+      run: () => setTransform(INITIAL_TRANSFORM)
+    }
+  ];
+  return /* @__PURE__ */ jsx(
+    ModalOverlay,
+    {
+      UNSTABLE_portalContainer: portalContainer,
+      isOpen: open,
+      onOpenChange,
+      isDismissable: false,
+      "data-slot": "image-preview-overlay",
+      className: "ui-image-preview-overlay",
+      children: /* @__PURE__ */ jsx(Modal, { className: "contents", children: /* @__PURE__ */ jsxs(
+        RacDialog,
+        {
+          "aria-label": t("dataDisplay.image.dialog"),
+          "data-slot": "image-preview",
+          className: "ui-image-preview",
+          render: (racProps) => {
+            const {
+              "data-rac": _rac,
+              ref: racRef,
+              ...rest
+            } = racProps;
+            return /* @__PURE__ */ jsx("section", { ...rest, ref: mergeRefs(racRef, sectionRef), onKeyDown });
+          },
+          children: [
+            /* @__PURE__ */ jsx(
+              "div",
+              {
+                className: "ui-image-preview-stage",
+                "data-dragging": dragging ? "" : void 0,
+                onWheel,
+                onClick: (event) => {
+                  if (event.target === event.currentTarget) onOpenChange(false);
+                },
+                children: src ? /* @__PURE__ */ jsx(
+                  "img",
+                  {
+                    "data-slot": "image-preview-img",
+                    className: "ui-image-preview-img",
+                    src,
+                    alt: entry?.alt ?? "",
+                    draggable: false,
+                    style: { transform: imageTransform },
+                    onError: () => entry && setFailedSrc(entry.src),
+                    onDoubleClick,
+                    onPointerDown,
+                    onPointerMove,
+                    onPointerUp,
+                    onPointerCancel: onPointerUp
+                  },
+                  index
+                ) : null
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                "data-slot": "image-preview-close",
+                className: "ui-image-preview-close ui-image-preview-button ui-focus-ring",
+                "aria-label": t("dataDisplay.image.close"),
+                onClick: () => onOpenChange(false),
+                children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
+              }
+            ),
+            total > 1 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  "data-slot": "image-preview-previous",
+                  className: "ui-image-preview-switch ui-image-preview-button ui-focus-ring",
+                  "data-direction": "previous",
+                  "aria-label": t("dataDisplay.image.previous"),
+                  disabled: !hasPrev,
+                  onClick: goPrev,
+                  children: /* @__PURE__ */ jsx(ChevronLeft, { "aria-hidden": "true" })
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  "data-slot": "image-preview-next",
+                  className: "ui-image-preview-switch ui-image-preview-button ui-focus-ring",
+                  "data-direction": "next",
+                  "aria-label": t("dataDisplay.image.next"),
+                  disabled: !hasNext,
+                  onClick: goNext,
+                  children: /* @__PURE__ */ jsx(ChevronRight, { "aria-hidden": "true" })
+                }
+              )
+            ] }) : null,
+            /* @__PURE__ */ jsxs("div", { className: "ui-image-preview-footer", children: [
+              total > 1 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    "data-slot": "image-preview-counter",
+                    className: "ui-image-preview-counter",
+                    "aria-hidden": "true",
+                    children: t("dataDisplay.image.counter", { current: index + 1, total })
+                  }
+                ),
+                /* @__PURE__ */ jsx("span", { className: "sr-only", "aria-live": "polite", children: t("dataDisplay.image.position", { current: index + 1, total }) })
+              ] }) : null,
+              /* @__PURE__ */ jsx(
+                "div",
+                {
+                  role: "group",
+                  "aria-label": t("dataDisplay.image.toolbar"),
+                  "data-slot": "image-preview-toolbar",
+                  className: "ui-image-preview-toolbar",
+                  children: tools.map((tool) => /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      type: "button",
+                      "data-action": tool.key,
+                      className: "ui-image-preview-button ui-focus-ring",
+                      "aria-label": tool.label,
+                      title: tool.label,
+                      disabled: tool.off,
+                      onClick: tool.run,
+                      children: /* @__PURE__ */ jsx("span", { className: "ui-image-preview-icon", "aria-hidden": "true", children: tool.icon })
+                    },
+                    tool.key
+                  ))
+                }
+              )
+            ] })
+          ]
+        }
+      ) })
+    }
+  );
+}
+function ImagePreviewGroup({
+  items,
+  fallback,
+  preview = true,
+  children
+}) {
+  const config = typeof preview === "object" ? preview : {};
+  const enabled = preview !== false;
+  const registry = React.useRef(/* @__PURE__ */ new Map());
+  const [version, setVersion] = React.useState(0);
+  const [visible, setVisible] = useMergedState(config.visible, false, config.onVisibleChange);
+  const [current, setCurrent] = useMergedState(config.current, 0, config.onChange);
+  const registered = React.useMemo(() => {
+    void version;
+    return inDocumentOrder(registry.current.values());
+  }, [version]);
+  const list = React.useMemo(
+    () => items ? items.map(toEntry) : registered,
+    [items, registered]
+  );
+  const latest = React.useRef({ items, setCurrent, setVisible });
+  latest.current = { items, setCurrent, setVisible };
+  const context = React.useMemo(
+    () => ({
+      register: (entry) => {
+        registry.current.set(entry.id, entry);
+        setVersion((v) => v + 1);
+        return () => {
+          registry.current.delete(entry.id);
+          setVersion((v) => v + 1);
+        };
+      },
+      open: (id) => {
+        const { items: explicit, setCurrent: select, setVisible: show } = latest.current;
+        const entry = registry.current.get(id);
+        const index = explicit ? explicit.map(toEntry).findIndex((item) => item.src === entry?.src) : inDocumentOrder(registry.current.values()).findIndex((item) => item.id === id);
+        select(Math.max(index, 0));
+        show(true);
+      }
+    }),
+    []
+  );
+  return /* @__PURE__ */ jsx(ImageGroupDisabledContext.Provider, { value: !enabled, children: /* @__PURE__ */ jsxs(ImageGroupContext.Provider, { value: enabled ? context : null, children: [
+    children,
+    enabled ? /* @__PURE__ */ jsx(
+      ImagePreviewDialog,
+      {
+        open: visible && list.length > 0,
+        onOpenChange: setVisible,
+        items: list,
+        current,
+        onCurrentChange: setCurrent,
+        fallback,
+        scaleStep: config.scaleStep,
+        minScale: config.minScale,
+        maxScale: config.maxScale
+      }
+    ) : null
+  ] }) });
+}
+const ImageRoot = React.forwardRef(function Image({ src, alt, fallback, placeholder, preview = true, className, onLoad, onError, ...imgProps }, ref) {
+  const { t } = useTranslation();
+  const group = React.useContext(ImageGroupContext);
+  const groupDisabled = React.useContext(ImageGroupDisabledContext);
+  const id = React.useId();
+  const wrapperRef = React.useRef(null);
+  const [load, setLoad] = React.useState({
+    src,
+    status: "loading"
+  });
+  const status = load.src === src ? load.status : "loading";
+  const setStatus = React.useCallback((next) => setLoad({ src, status: next }), [src]);
+  const imgRef = React.useRef(null);
+  const setImgRef = React.useCallback(
+    (node) => {
+      imgRef.current = node;
+      if (node?.complete && node.naturalWidth > 0) setStatus("loaded");
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref, setStatus]
+  );
+  const config = typeof preview === "object" ? preview : {};
+  const isError = status === "error";
+  const canPreview = preview !== false && !groupDisabled && !isError;
+  const previewSrc = config.src ?? src;
+  const inGroup = group != null && canPreview;
+  React.useLayoutEffect(() => {
+    if (!inGroup || !group) return void 0;
+    return group.register({ id, src: previewSrc, alt, node: () => wrapperRef.current });
+  }, [inGroup, group, id, previewSrc, alt]);
+  const [visible, setVisible] = useMergedState(config.visible, false, config.onVisibleChange);
+  const shownSrc = isError && fallback ? fallback : src;
+  const showPlaceholder = placeholder != null && placeholder !== false && status === "loading";
+  const picture = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "img",
+      {
+        ...imgProps,
+        ref: setImgRef,
+        "data-slot": "image-img",
+        className: "ui-image-img",
+        src: shownSrc,
+        alt,
+        onLoad: (event) => {
+          setStatus("loaded");
+          onLoad?.(event);
+        },
+        onError: (event) => {
+          setStatus("error");
+          onError?.(event);
+        }
+      }
+    ),
+    showPlaceholder ? /* @__PURE__ */ jsx("span", { "data-slot": "image-placeholder", className: "ui-image-placeholder", "aria-hidden": "true", children: placeholder === true ? null : placeholder }) : null
+  ] });
+  if (!canPreview) {
+    return /* @__PURE__ */ jsx(
+      "span",
+      {
+        ref: wrapperRef,
+        "data-slot": "image",
+        "data-status": status,
+        className: cn("ui-image", className),
+        children: picture
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(
+      "button",
+      {
+        ref: (node) => {
+          wrapperRef.current = node;
+        },
+        type: "button",
+        "data-slot": "image",
+        "data-status": status,
+        "data-preview": "",
+        className: cn("ui-image ui-focus-ring", className),
+        "aria-label": alt ? t("dataDisplay.image.previewLabel", { alt }) : t("dataDisplay.image.previewUnnamed"),
+        "aria-haspopup": "dialog",
+        onClick: () => inGroup && group ? group.open(id) : setVisible(true),
+        children: [
+          picture,
+          /* @__PURE__ */ jsx("span", { "data-slot": "image-mask", className: "ui-image-mask", "aria-hidden": "true", children: config.mask ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx(Eye, { className: "ui-image-mask-icon" }),
+            t("dataDisplay.image.preview")
+          ] }) })
+        ]
+      }
+    ),
+    inGroup ? null : /* @__PURE__ */ jsx(
+      ImagePreviewDialog,
+      {
+        open: visible,
+        onOpenChange: setVisible,
+        items: [{ src: previewSrc, alt }],
+        current: 0,
+        onCurrentChange: () => void 0,
+        fallback,
+        scaleStep: config.scaleStep,
+        minScale: config.minScale,
+        maxScale: config.maxScale
+      }
+    )
+  ] });
+});
+ImageRoot.displayName = "Image";
+const Image2 = Object.assign(ImageRoot, { PreviewGroup: ImagePreviewGroup });
+export {
+  Image2 as Image,
+  ImagePreviewGroup
+};

package/dist/components/data-display/index.d.ts

@@ -59,3 +59,5 @@ export { Welcome } from "./welcome.js";
 export type { WelcomeProp, WelcomeProps, WelcomeVariantProp } from "./welcome.js";
 export { ThoughtChain, ThoughtChainItem } from "./thought-chain.js";
 export type { ThoughtChainProp, ThoughtChainProps, ThoughtChainItemsProp, ThoughtChainItemProp, ThoughtChainItemProps, ThoughtChainStatusProp, ThoughtChainLineProp, ThoughtChainVariantProp, } from "./thought-chain.js";
+export { Image, ImagePreviewGroup } from "./image.js";
+export type { ImagePreviewConfigProp, ImagePreviewGroupConfigProp, ImagePreviewGroupProp, ImagePreviewGroupProps, ImagePreviewItemProp, ImageProp, ImageProps, } from "./image.js";

package/dist/components/data-display/index.js

@@ -63,6 +63,7 @@ import { Tree } from "./tree.js";
 import { OrgChart } from "./org-chart.js";
 import { Welcome } from "./welcome.js";
 import { ThoughtChain, ThoughtChainItem } from "./thought-chain.js";
+import { Image, ImagePreviewGroup } from "./image.js";
 export {
   Accordion,
   AccordionContent,
@@ -101,6 +102,8 @@ export {
   HoverCard,
   HoverCardContent,
   HoverCardTrigger,
+  Image,
+  ImagePreviewGroup,
   Legend,
   ListRow,
   Marquee,

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "31.10.3",
+  "version": "31.11.1",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/i18n/messages/en.json

@@ -384,6 +384,25 @@
       "statusDone": "Completed: ",
       "statusCurrent": "Current: ",
       "statusPending": "Upcoming: "
+    },
+    "image": {
+      "preview": "Preview",
+      "previewLabel": "Preview: {alt}",
+      "previewUnnamed": "Preview image",
+      "dialog": "Image preview",
+      "close": "Close preview",
+      "previous": "Previous image",
+      "next": "Next image",
+      "counter": "{current} / {total}",
+      "position": "Image {current} of {total}",
+      "toolbar": "Image tools",
+      "flipX": "Flip horizontally",
+      "flipY": "Flip vertically",
+      "rotateLeft": "Rotate left",
+      "rotateRight": "Rotate right",
+      "zoomIn": "Zoom in",
+      "zoomOut": "Zoom out",
+      "reset": "Reset"
     }
   },
   "ui": {

package/dist/i18n/messages/ja.json

@@ -377,6 +377,25 @@
       "statusDone": "完了: ",
       "statusCurrent": "現在: ",
       "statusPending": "予定: "
+    },
+    "image": {
+      "preview": "プレビュー",
+      "previewLabel": "プレビュー: {alt}",
+      "previewUnnamed": "画像をプレビュー",
+      "dialog": "画像プレビュー",
+      "close": "プレビューを閉じる",
+      "previous": "前の画像",
+      "next": "次の画像",
+      "counter": "{current} / {total}",
+      "position": "{total} 枚中 {current} 枚目",
+      "toolbar": "画像ツール",
+      "flipX": "左右反転",
+      "flipY": "上下反転",
+      "rotateLeft": "左に回転",
+      "rotateRight": "右に回転",
+      "zoomIn": "拡大",
+      "zoomOut": "縮小",
+      "reset": "リセット"
     }
   },
   "ui": {

package/dist/i18n/messages/vi.json

@@ -378,6 +378,25 @@
       "statusDone": "Đã xong: ",
       "statusCurrent": "Hiện tại: ",
       "statusPending": "Sắp tới: "
+    },
+    "image": {
+      "preview": "Xem",
+      "previewLabel": "Xem ảnh: {alt}",
+      "previewUnnamed": "Xem ảnh",
+      "dialog": "Xem ảnh",
+      "close": "Đóng xem ảnh",
+      "previous": "Ảnh trước",
+      "next": "Ảnh sau",
+      "counter": "{current} / {total}",
+      "position": "Ảnh {current} trên {total}",
+      "toolbar": "Công cụ ảnh",
+      "flipX": "Lật ngang",
+      "flipY": "Lật dọc",
+      "rotateLeft": "Xoay trái",
+      "rotateRight": "Xoay phải",
+      "zoomIn": "Phóng to",
+      "zoomOut": "Thu nhỏ",
+      "reset": "Đặt lại"
     }
   },
   "ui": {

package/dist/props/components/data-display.prop.d.ts

@@ -1195,3 +1195,76 @@ export type OrgChartProp = {
     className?: ClassNameProp;
     id?: IdProp;
 };
+/**
+ * @see ImagePreviewGroup — one picture of a group's `items`. A plain string is its `src` (antd
+ * `PreviewGroup items: string[] | { src, … }[]`).
+ */
+export type ImagePreviewItemProp = string | {
+    src: string;
+    alt?: string;
+};
+/**
+ * @see Image — the object form of `preview` (antd `Image preview: PreviewType`).
+ *
+ * `visible` / `onVisibleChange(visible, prevVisible)` keep antd's names on purpose: the whole
+ * component is a port of antd `Image`, and a Markdown renderer ported from an antd screen passes
+ * these through unchanged.
+ */
+export type ImagePreviewConfigProp = {
+    /** Controlled: is the preview open. */
+    visible?: boolean;
+    /** Called with the next and the previous open state (antd order). */
+    onVisibleChange?: (visible: boolean, prevVisible: boolean) => void;
+    /** A different (usually larger) file to show in the preview than the one on the page. */
+    src?: string;
+    /** Replaces the hover/focus veil's content (default: an eye + "Preview"). */
+    mask?: React.ReactNode;
+    /** Zoom factor per step, as a fraction: `0.5` means ×1.5 per zoom-in. Default `0.5`. */
+    scaleStep?: number;
+    /** Smallest zoom. Default `1`. */
+    minScale?: number;
+    /** Largest zoom. Default `50`. */
+    maxScale?: number;
+};
+/** @see ImagePreviewGroup — the group's `preview` object (antd `PreviewGroup preview`). */
+export type ImagePreviewGroupConfigProp = Omit<ImagePreviewConfigProp, "src" | "mask"> & {
+    /** Controlled: index of the picture on show. */
+    current?: number;
+    /** Called with the next and the previous index (antd order). */
+    onChange?: (current: number, prevCurrent: number) => void;
+};
+/**
+ * @see Image — a picture that opens large in a full-viewport preview (antd `Image`): zoom, rotate,
+ * flip, and — inside an `ImagePreviewGroup` — prev/next across every picture of the group.
+ */
+export type ImageProp = Omit<React.ImgHTMLAttributes<HTMLImageElement>, "alt" | "placeholder"> & {
+    /** Image URL. */
+    src: string;
+    /**
+     * Required, as on `Thumbnail`: `""` is a decision, a missing `alt` an omission (WCAG 1.1.1). It
+     * also names the preview trigger ("Preview: {alt}").
+     */
+    alt: string;
+    /** Shown instead when `src` fails to load. A failed picture does not open a preview (antd). */
+    fallback?: string;
+    /** Painted over the frame until the picture loads. `true` = the plain muted block. */
+    placeholder?: React.ReactNode | boolean;
+    /** `false` = a plain picture, not clickable, not in its group. Default `true`. */
+    preview?: boolean | ImagePreviewConfigProp;
+    className?: ClassNameProp;
+};
+/**
+ * @see ImagePreviewGroup — pages the preview across a set of pictures (antd `Image.PreviewGroup`).
+ *
+ * Every `Image` rendered anywhere under it joins the group in DOCUMENT order, however deep — so a
+ * Markdown renderer's `img` override is enough to make a whole article one gallery.
+ */
+export type ImagePreviewGroupProp = {
+    /** An explicit list instead of the pictures rendered under the group. */
+    items?: readonly ImagePreviewItemProp[];
+    /** Shown in the preview instead of a picture that fails to load. */
+    fallback?: string;
+    /** `false` turns the whole group's previews off; an object controls it (antd shape). */
+    preview?: boolean | ImagePreviewGroupConfigProp;
+    children?: React.ReactNode;
+};