@godxjp/ui 31.10.2 → 31.11.0

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;
+};

package/dist/props/registry.d.ts

@@ -4006,6 +4006,103 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly reason: "Escape hatch replacing a box's content; the box, connectors and keyboard stay the library's.";
         }];
     };
+    readonly ImagePreviewItemProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display.prop.ts";
+        readonly vocabulary: readonly [{
+            readonly field: "src";
+            readonly local: true;
+            readonly reason: "The native img src attribute.";
+        }, {
+            readonly field: "alt";
+            readonly local: true;
+            readonly reason: "The native img alt attribute.";
+        }];
+    };
+    readonly ImagePreviewConfigProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display.prop.ts";
+        readonly vocabulary: readonly ["OnOpenChangeProp", {
+            readonly field: "visible";
+            readonly local: true;
+            readonly reason: "antd Image `preview.visible`, kept verbatim — the component is a whole antd port.";
+        }, {
+            readonly field: "onVisibleChange";
+            readonly local: true;
+            readonly reason: "antd `preview.onVisibleChange(visible, prevVisible)`, kept verbatim.";
+        }, {
+            readonly field: "src";
+            readonly local: true;
+            readonly reason: "A different file for the preview than the page's.";
+        }, {
+            readonly field: "mask";
+            readonly local: true;
+            readonly reason: "antd's hover veil content over the thumbnail.";
+        }, {
+            readonly field: "scaleStep";
+            readonly local: true;
+            readonly reason: "antd zoom step (fraction added per zoom-in).";
+        }, {
+            readonly field: "minScale";
+            readonly local: true;
+            readonly reason: "antd lower zoom bound.";
+        }, {
+            readonly field: "maxScale";
+            readonly local: true;
+            readonly reason: "antd upper zoom bound.";
+        }];
+    };
+    readonly ImagePreviewGroupConfigProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display.prop.ts";
+        readonly vocabulary: readonly ["OnValueChangeProp", {
+            readonly field: "current";
+            readonly local: true;
+            readonly reason: "antd PreviewGroup `preview.current` (index on show), kept verbatim.";
+        }, {
+            readonly field: "onChange";
+            readonly local: true;
+            readonly reason: "antd PreviewGroup `preview.onChange(current, prevCurrent)`, kept verbatim.";
+        }];
+    };
+    readonly ImageProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display.prop.ts";
+        readonly vocabulary: readonly ["ClassNameProp", "PlaceholderProp", {
+            readonly field: "src";
+            readonly local: true;
+            readonly reason: "The native img src attribute.";
+        }, {
+            readonly field: "alt";
+            readonly local: true;
+            readonly reason: "The native img alt contract, made required so it cannot be forgotten.";
+        }, {
+            readonly field: "fallback";
+            readonly local: true;
+            readonly reason: "antd Image `fallback` — the src shown on error.";
+        }, {
+            readonly field: "preview";
+            readonly local: true;
+            readonly reason: "antd Image `preview: boolean | PreviewType` — opt-out or configure the preview.";
+        }];
+    };
+    readonly ImagePreviewGroupProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display.prop.ts";
+        readonly vocabulary: readonly ["ChildrenProp", {
+            readonly field: "items";
+            readonly local: true;
+            readonly reason: "antd PreviewGroup `items` — an explicit list.";
+        }, {
+            readonly field: "fallback";
+            readonly local: true;
+            readonly reason: "antd PreviewGroup `fallback`.";
+        }, {
+            readonly field: "preview";
+            readonly local: true;
+            readonly reason: "antd PreviewGroup `preview: boolean | { visible, current, onChange, … }`.";
+        }];
+    };
 };
 export type ComponentPropName = keyof typeof COMPONENT_PROP_REGISTRY;
 /** Forbidden duplicate concepts — use the canonical name on the left. */

package/dist/props/registry.js

@@ -4872,6 +4872,87 @@ const COMPONENT_PROP_REGISTRY = {
         reason: "Escape hatch replacing a box's content; the box, connectors and keyboard stay the library's."
       }
     ]
+  },
+  ImagePreviewItemProp: {
+    group: "data-display",
+    file: "components/data-display.prop.ts",
+    vocabulary: [
+      { field: "src", local: true, reason: "The native img src attribute." },
+      { field: "alt", local: true, reason: "The native img alt attribute." }
+    ]
+  },
+  ImagePreviewConfigProp: {
+    group: "data-display",
+    file: "components/data-display.prop.ts",
+    vocabulary: [
+      "OnOpenChangeProp",
+      {
+        field: "visible",
+        local: true,
+        reason: "antd Image `preview.visible`, kept verbatim \u2014 the component is a whole antd port."
+      },
+      {
+        field: "onVisibleChange",
+        local: true,
+        reason: "antd `preview.onVisibleChange(visible, prevVisible)`, kept verbatim."
+      },
+      { field: "src", local: true, reason: "A different file for the preview than the page's." },
+      { field: "mask", local: true, reason: "antd's hover veil content over the thumbnail." },
+      { field: "scaleStep", local: true, reason: "antd zoom step (fraction added per zoom-in)." },
+      { field: "minScale", local: true, reason: "antd lower zoom bound." },
+      { field: "maxScale", local: true, reason: "antd upper zoom bound." }
+    ]
+  },
+  ImagePreviewGroupConfigProp: {
+    group: "data-display",
+    file: "components/data-display.prop.ts",
+    vocabulary: [
+      "OnValueChangeProp",
+      {
+        field: "current",
+        local: true,
+        reason: "antd PreviewGroup `preview.current` (index on show), kept verbatim."
+      },
+      {
+        field: "onChange",
+        local: true,
+        reason: "antd PreviewGroup `preview.onChange(current, prevCurrent)`, kept verbatim."
+      }
+    ]
+  },
+  ImageProp: {
+    group: "data-display",
+    file: "components/data-display.prop.ts",
+    vocabulary: [
+      "ClassNameProp",
+      "PlaceholderProp",
+      { field: "src", local: true, reason: "The native img src attribute." },
+      {
+        field: "alt",
+        local: true,
+        reason: "The native img alt contract, made required so it cannot be forgotten."
+      },
+      { field: "fallback", local: true, reason: "antd Image `fallback` \u2014 the src shown on error." },
+      {
+        field: "preview",
+        local: true,
+        reason: "antd Image `preview: boolean | PreviewType` \u2014 opt-out or configure the preview."
+      }
+    ]
+  },
+  ImagePreviewGroupProp: {
+    group: "data-display",
+    file: "components/data-display.prop.ts",
+    vocabulary: [
+      "ChildrenProp",
+      { field: "items", local: true, reason: "antd PreviewGroup `items` \u2014 an explicit list." },
+      { field: "fallback", local: true, reason: "antd PreviewGroup `fallback`." },
+      {
+        field: "preview",
+        local: true,
+        reason: "antd PreviewGroup `preview: boolean | { visible, current, onChange, \u2026 }`."
+      }
+    ]
   }
 };
 const PROP_ALIASES_FORBIDDEN = {

package/dist/styles/data-display-layout.css

@@ -2655,3 +2655,206 @@
     }
   }
 }
+
+@layer components {
+
+  .ui-image {
+    position: relative;
+    display: inline-block;
+    max-inline-size: 100%;
+    padding: 0;
+    border: 0;
+    border-radius: var(--image-radius, var(--radius));
+    background: none;
+    color: inherit;
+    font: inherit;
+    line-height: 0;
+    vertical-align: middle;
+  }
+
+  .ui-image[data-preview] {
+    cursor: zoom-in;
+  }
+
+  .ui-image-img {
+    display: block;
+    max-inline-size: 100%;
+    block-size: auto;
+    border-radius: inherit;
+  }
+
+  .ui-image-placeholder {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-items: center;
+    border-radius: inherit;
+    background: hsl(var(--muted));
+    color: hsl(var(--muted-foreground));
+  }
+
+  .ui-image-mask {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--image-mask-gap);
+    border-radius: inherit;
+    background: var(--image-mask-background, var(--overlay-background));
+    color: var(--image-mask-foreground, hsl(var(--background)));
+    font-size: var(--font-size-sm, var(--font-size-base));
+    line-height: var(--line-height-normal, 1.5);
+    opacity: 0;
+    transition: opacity var(--duration-fast) var(--ease-standard);
+    pointer-events: none;
+  }
+
+  .ui-image-mask-icon {
+    inline-size: var(--image-preview-icon-size);
+    block-size: var(--image-preview-icon-size);
+  }
+
+  .ui-image:hover .ui-image-mask,
+  .ui-image:focus-visible .ui-image-mask {
+    opacity: 1;
+  }
+
+  .ui-image-preview-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: var(--overlay-z-index);
+    background-color: var(--image-preview-background, var(--overlay-background));
+  }
+
+  .ui-image-preview {
+    position: fixed;
+    inset: 0;
+    z-index: var(--overlay-z-index);
+    color: var(--image-preview-foreground, hsl(var(--background)));
+    outline: none;
+  }
+
+  .ui-image-preview-stage {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+    padding: calc(var(--image-preview-button-size) + var(--image-preview-inset) * 2);
+  }
+
+  .ui-image-preview-img {
+    max-inline-size: 100%;
+    max-block-size: 100%;
+    object-fit: contain;
+    cursor: grab;
+    user-select: none;
+    touch-action: none;
+    transition: transform var(--duration-base) var(--ease-standard);
+  }
+
+  .ui-image-preview-stage[data-dragging] .ui-image-preview-img {
+    cursor: grabbing;
+    transition: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ui-image-preview-img,
+    .ui-image-mask {
+      transition: none;
+    }
+  }
+
+  .ui-image-preview-button {
+    display: inline-grid;
+    place-items: center;
+    inline-size: var(--image-preview-button-size);
+    block-size: var(--image-preview-button-size);
+    padding: 0;
+    border: 0;
+    border-radius: var(--radius-pill);
+    background: color-mix(
+      in srgb,
+      currentColor var(--image-preview-button-background-alpha),
+      transparent
+    );
+    color: inherit;
+    cursor: pointer;
+    transition: background-color var(--duration-fast) var(--ease-standard);
+  }
+
+  .ui-image-preview-button:hover:not(:disabled) {
+    background: color-mix(
+      in srgb,
+      currentColor var(--image-preview-button-hover-background-alpha),
+      transparent
+    );
+  }
+
+  .ui-image-preview-button:disabled {
+    opacity: var(--disabled-opacity, 0.5);
+    cursor: not-allowed;
+  }
+
+  .ui-image-preview-button svg {
+    inline-size: var(--image-preview-icon-size);
+    block-size: var(--image-preview-icon-size);
+  }
+
+  .ui-image-preview-close {
+    position: absolute;
+    inset-block-start: var(--image-preview-inset);
+    inset-inline-end: var(--image-preview-inset);
+  }
+
+  .ui-image-preview-switch {
+    position: absolute;
+    inset-block-start: 50%;
+    transform: translateY(-50%);
+  }
+
+  .ui-image-preview-switch[data-direction="previous"] {
+    inset-inline-start: var(--image-preview-inset);
+  }
+
+  .ui-image-preview-switch[data-direction="next"] {
+    inset-inline-end: var(--image-preview-inset);
+  }
+
+  [dir="rtl"] .ui-image-preview-switch svg {
+    transform: scaleX(-1);
+  }
+
+  .ui-image-preview-footer {
+    position: absolute;
+    inset-inline: 0;
+    inset-block-end: var(--image-preview-inset);
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--image-preview-gap);
+    pointer-events: none;
+  }
+
+  .ui-image-preview-footer > * {
+    pointer-events: auto;
+  }
+
+  .ui-image-preview-counter {
+    font-size: var(--font-size-sm, var(--font-size-base));
+    font-variant-numeric: tabular-nums;
+  }
+
+  .ui-image-preview-toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: var(--image-preview-gap);
+  }
+
+  .ui-image-preview-icon {
+    display: contents;
+  }
+}

package/dist/styles/layers.json

@@ -1,5 +1,5 @@
 {
-  "version": "31.10.2",
+  "version": "31.11.0",
   "generatedBy": "scripts/gen-style-layers.mjs — do not edit by hand; run `pnpm gen:style-layers`",
   "base": "base.css",
   "fonts": "fonts.css",
@@ -575,6 +575,11 @@
         "icon-layout.css"
       ]
     },
+    "Image": {
+      "layers": [
+        "data-display-layout.css"
+      ]
+    },
     "InfiniteQueryState": {
       "layers": [
         "layout.css",

package/dist/tokens/base.css

@@ -39,6 +39,7 @@
 @import "./components/tree.css";
 @import "./components/thought-chain.css";
 @import "./components/org-chart.css";
+@import "./components/image.css";
 @import "./components/welcome.css";
 @import "./components/actions.css";
 @import "./components/attachments.css";

package/dist/tokens/components/image.css

@@ -0,0 +1,19 @@
+
+
+:root {
+
+  --image-mask-background: initial;
+  --image-mask-foreground: initial;
+  --image-mask-gap: var(--space-1);
+  --image-radius: initial;
+
+  --image-preview-background: initial;
+  --image-preview-foreground: initial;
+  --image-preview-inset: var(--space-4);
+  --image-preview-gap: var(--space-2);
+
+  --image-preview-button-size: 2.5rem;
+  --image-preview-button-background-alpha: 10%;
+  --image-preview-button-hover-background-alpha: 20%;
+  --image-preview-icon-size: var(--icon-size-lg);
+}

package/docs/FRAME-COVERAGE-REPORT.md

@@ -3,8 +3,8 @@
 > Generated by `scripts/frame-coverage.mjs` (issue #163). Do not edit by hand — run `pnpm check:frame-coverage`.
 > Standard: [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md). A missing dimension is **UNTESTED**, never a pass.
 
-- Public components: **177**
-- With ≥1 frame: **153** · zero-frame: **24**
+- Public components: **178**
+- With ≥1 frame: **154** · zero-frame: **24**
 - Fully covered (every contract axis declared): **0**
 
 ## UNTESTED — no `/frame/**` route
@@ -212,6 +212,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Actions | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | ThoughtChain | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | OrgChart | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Image | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Attachments | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | Marquee | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Masonry | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |