@synerise/ds-image 0.1.5 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.0.0](https://github.com/Synerise/synerise-design/compare/@synerise/ds-image@0.2.0...@synerise/ds-image@2.0.0) (2026-08-26)
+
+**Note:** Version bump only for package @synerise/ds-image
+
+# [0.2.0](https://github.com/Synerise/synerise-design/compare/@synerise/ds-image@0.1.5...@synerise/ds-image@0.2.0) (2026-08-25)
+
+### Features
+
+- **image:** stack the preview through the DS overlay z-index ([573932c](https://github.com/Synerise/synerise-design/commit/573932c6197c4e9613265cb17f117326f5fb6a71))
+
 ## [0.1.5](https://github.com/Synerise/synerise-design/compare/@synerise/ds-image@0.1.4...@synerise/ds-image@0.1.5) (2026-08-18)
 
 **Note:** Version bump only for package @synerise/ds-image

package/CLAUDE.md

@@ -87,6 +87,13 @@ tables.
   `translate(50%,-50%)`), revealed on hover/focus-within. Its click stops propagation (so it never opens the preview)
   and blurs the button so the control doesn't linger via `:focus-within` after a
   click. *Empty* (no `src`): the grey placeholder.
+- **Overlay z-index** — resolved through `useResolvedOverlayZIndex` from `ds-core`,
+  the same path `ds-modal` / `ds-drawer` take: an explicit `zIndex` prop wins,
+  otherwise one step above the enclosing overlay (read from React context, since
+  every overlay portals to `body`), otherwise the `zindex-modal` token. The prop
+  is the escape hatch for a trigger that sits outside the DS scale — an app-level
+  surface pinned above `zindex-tooltip` needs it, because no DS token reaches
+  that high. `Gallery` forwards it to the preview it owns.
 - **Preview is controlled** — `open` / `images` / `index` / `onIndexChange` /
   `onClose`. Navigation (`‹ N of M ›`) shows only when `images.length > 1`; arrow
   keys page (with wrap-around). `useImagePreview` owns this state for non-gallery
@@ -142,4 +149,5 @@ tables.
 - `@synerise/ds-tooltip` — wraps the thumbnail delete button.
 - `@synerise/ds-utils` — `useFocusTrap`.
 - `react-intl` (peer) — control labels/tooltips via `useImageTexts`.
-- `@synerise/ds-core` (peer) — theme palette + `box-shadow-*` variables.
+- `@synerise/ds-core` (peer) — theme palette, `box-shadow-*` variables and
+  `useResolvedOverlayZIndex` (overlay stacking).

package/README.md

@@ -51,5 +51,67 @@ const Example = () => {
 };
 ```
 
-See the Storybook overview page for full props tables, behavior notes, and
+## API
+
+### Thumbnail
+
+| Property    | Description                                                                       | Type                             | Default   |
+| ----------- | --------------------------------------------------------------------------------- | -------------------------------- | --------- |
+| src         | Image source URL. Omit it to render the Empty state.                              | string                           | ---       |
+| alt         | Alternative text. Required for accessibility.                                     | string                           | ---       |
+| aspectRatio | Aspect ratio of the tile. `source` keeps the image's intrinsic ratio.             | '1:1' / '4:3' / '16:9' / 'source' | `'1:1'`   |
+| size        | Height token. `custom` defers to `height`.                                        | 'custom' / 'xxs' … 'xxl'         | `'m'`     |
+| height      | Explicit height in px, used when `size` is `custom`.                              | number                           | ---       |
+| background  | Tile backdrop.                                                                    | 'none' / 'subtle-grey'           | `'none'`  |
+| objectFit   | How the image fills the tile.                                                     | 'contain' / 'cover'              | `'contain'` |
+| loading     | Native loading hint.                                                              | 'lazy' / 'eager'                 | `'lazy'`  |
+| deletable   | Show a delete affordance on hover / focus.                                        | boolean                          | `false`   |
+| onDelete    | Called when the delete affordance is activated.                                   | () => void                       | ---       |
+| openZoom    | Render the tile as an interactive trigger (e.g. opens a preview).                 | boolean                          | `false`   |
+| onClick     | Click handler, fired for mouse and keyboard (Enter / Space) activation.           | (event: MouseEvent) => void      | ---       |
+| fallback    | Rendered when the image fails to load.                                            | React.ReactNode                  | broken-image box |
+| texts       | Override the delete tooltip / accessible label.                                   | Partial<ImageTexts>        | DS translations |
+| className   | Class applied to the tile.                                                        | string                           | ---       |
+
+Every value except `src`, `alt`, `onDelete` and `onClick` falls back to the
+enclosing `Gallery` before the default listed above.
+
+### Gallery
+
+| Property                                          | Description                                                   | Type                        | Default |
+| ------------------------------------------------- | ------------------------------------------------------------- | --------------------------- | ------- |
+| images                                            | Images rendered as thumbnails and paged through in the preview. | ImageSource[]             | ---     |
+| aspectRatio / size / height / background          | Applied to every thumbnail.                                   | see Thumbnail               | see Thumbnail |
+| objectFit / loading / fallback                    | Applied to every thumbnail.                                   | see Thumbnail               | see Thumbnail |
+| deletable                                         | Show a delete affordance on each thumbnail.                   | boolean                     | `false` |
+| onDelete                                          | Called with the index of the thumbnail whose delete fired.    | (index: number) => void     | ---     |
+| openZoom                                          | Whether clicking a thumbnail opens the preview.               | boolean                     | `true`  |
+| zoomable / zoomStep / maxZoom / initialZoom       | Forwarded to the preview it owns.                             | see ImagePreview            | see ImagePreview |
+| getContainer / zIndex                             | Forwarded to the preview it owns.                             | see ImagePreview            | see ImagePreview |
+| texts                                             | Override tooltips / accessible labels for thumbnails and the preview. | Partial<ImageTexts> | DS translations |
+| className                                         | Class applied to the gallery container.                       | string                      | ---     |
+
+### ImagePreview
+
+| Property       | Description                                                                                                                    | Type                        | Default          |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------- | ---------------- |
+| open           | Whether the viewer is visible.                                                                                                 | boolean                     | ---              |
+| images         | Images to page through. Navigation shows only when there is more than one.                                                     | ImageSource[]               | ---              |
+| index          | Controlled index of the currently shown image.                                                                                 | number                      | ---              |
+| onIndexChange  | Called when navigation (arrows / keyboard) requests a different image.                                                         | (index: number) => void     | ---              |
+| onClose        | Called on Escape, backdrop click and the close button.                                                                         | () => void                  | ---              |
+| zoomable       | Whether zoom and pan are enabled.                                                                                              | boolean                     | `true`           |
+| zoomStep       | Per-click zoom multiplier.                                                                                                     | number                      | `1.4`            |
+| maxZoom        | Maximum zoom relative to the image's natural size.                                                                             | number                      | `3`              |
+| initialZoom    | Where zoom starts.                                                                                                             | 'fit' / 'real-size'         | `'fit'`          |
+| closable       | Whether to render the close button and allow Escape to close.                                                                  | boolean                     | `true`           |
+| maskClosable   | Whether clicking the dimmed backdrop closes the viewer.                                                                        | boolean                     | `true`           |
+| zIndex         | z-index of the overlay. Omitted, it stacks one step above the enclosing modal / drawer. Set it to opt out of the DS stack.      | number                      | `zindex-modal`   |
+| fallback       | Rendered when an image fails to load (per-image override via `ImageSource.fallback`).                                          | React.ReactNode             | broken-image box |
+| getContainer   | Portal target.                                                                                                                 | () => HTMLElement           | `document.body`  |
+| destroyOnClose | Unmount the viewer (and reset zoom state) when closed.                                                                         | boolean                     | `false`          |
+| onZoom         | Called with the current scale whenever the zoom transform changes.                                                             | (scale: number) => void     | ---              |
+| texts          | Override the control tooltips / accessible labels.                                                                             | Partial<ImageTexts>   | DS translations  |
+
+See the Storybook overview page for behavior notes, live examples and
 accessibility guidance.

package/dist/Gallery/Gallery.d.ts

@@ -1,3 +1,3 @@
 import { GalleryProps } from './Gallery.types';
-declare const Gallery: ({ images, aspectRatio, size, height, background, objectFit, loading, fallback, deletable, onDelete, openZoom, zoomable, zoomStep, maxZoom, initialZoom, getContainer, texts, className, }: GalleryProps) => JSX.Element;
+declare const Gallery: ({ images, aspectRatio, size, height, background, objectFit, loading, fallback, deletable, onDelete, openZoom, zoomable, zoomStep, maxZoom, initialZoom, getContainer, zIndex, texts, className, }: GalleryProps) => JSX.Element;
 export default Gallery;

package/dist/Gallery/Gallery.js

@@ -21,6 +21,7 @@ const Gallery = ({
   maxZoom,
   initialZoom,
   getContainer,
+  zIndex,
   texts,
   className
 }) => {
@@ -37,7 +38,7 @@ const Gallery = ({
   }), [aspectRatio, size, height, background, objectFit, loading, fallback, texts]);
   return /* @__PURE__ */ jsxs(ImageGalleryContext.Provider, { value: contextValue, children: [
     /* @__PURE__ */ jsx(Container, { className, "data-testid": "image-gallery", children: images.map((image, imageIndex) => /* @__PURE__ */ jsx(Thumbnail, { src: image.src, alt: image.alt, fallback: image.fallback, deletable, onDelete: onDelete ? () => onDelete(imageIndex) : void 0, openZoom, onClick: openZoom ? () => setPreviewIndex(imageIndex) : void 0 }, `${image.src}-${imageIndex}`)) }),
-    openZoom && /* @__PURE__ */ jsx(ImagePreview, { open: previewIndex !== null, images, index: previewIndex ?? 0, onIndexChange: setPreviewIndex, onClose: () => setPreviewIndex(null), zoomable, zoomStep, maxZoom, initialZoom, fallback, getContainer, texts })
+    openZoom && /* @__PURE__ */ jsx(ImagePreview, { open: previewIndex !== null, images, index: previewIndex ?? 0, onIndexChange: setPreviewIndex, onClose: () => setPreviewIndex(null), zoomable, zoomStep, maxZoom, initialZoom, fallback, getContainer, zIndex, texts })
   ] });
 };
 export {

package/dist/Gallery/Gallery.types.d.ts

@@ -33,6 +33,8 @@ export type GalleryProps = {
     initialZoom?: InitialZoom;
     /** Preview pass-through — portal target. */
     getContainer?: () => HTMLElement;
+    /** Preview pass-through — z-index of the preview overlay. */
+    zIndex?: number;
     /** Override tooltip / accessible labels for thumbnails and the preview. */
     texts?: Partial<ImageTexts>;
     className?: string;

package/dist/Preview/ImagePreview.d.ts

@@ -1,4 +1,4 @@
 import { default as React } from 'react';
 import { ImagePreviewProps } from './ImagePreview.types';
-declare const ImagePreview: ({ open, images, index, onIndexChange, onClose, zoomable, zoomStep, maxZoom, initialZoom, closable, maskClosable, fallback, getContainer, destroyOnClose, onZoom, texts: textsProp, }: ImagePreviewProps) => React.ReactPortal | null;
+declare const ImagePreview: ({ open, images, index, onIndexChange, onClose, zoomable, zoomStep, maxZoom, initialZoom, closable, maskClosable, fallback, getContainer, destroyOnClose, onZoom, texts: textsProp, zIndex, }: ImagePreviewProps) => React.ReactPortal | null;
 export default ImagePreview;

package/dist/Preview/ImagePreview.js

@@ -2,6 +2,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { useRef, useState, useEffect, useCallback } from "react";
 import { createPortal } from "react-dom";
 import { TransformWrapper, TransformComponent } from "react-zoom-pan-pinch";
+import { useResolvedOverlayZIndex } from "@synerise/ds-core";
 import Icon, { ImageM, CloseM } from "@synerise/ds-icon";
 import { ToolbarGroup, ToolbarButton } from "@synerise/ds-toolbar";
 import { useFocusTrap } from "@synerise/ds-utils";
@@ -39,9 +40,11 @@ const ImagePreview = ({
   getContainer,
   destroyOnClose = false,
   onZoom,
-  texts: textsProp
+  texts: textsProp,
+  zIndex
 }) => {
   const texts = useImageTexts(textsProp);
+  const resolvedZIndex = useResolvedOverlayZIndex(zIndex);
   const overlayRef = useRef(null);
   const workingAreaRef = useRef(null);
   const transformRef = useRef(null);
@@ -178,7 +181,7 @@ const ImagePreview = ({
   const showDownload = !hasError && Boolean(currentSrc);
   const image = /* @__PURE__ */ jsx(Image, { ref: imgRef, src: currentSrc, alt: currentImage?.alt ?? "", onLoad: handleImageLoad, onError: handleError, onClick: stopPropagation, draggable: false, "data-testid": "image-preview-image" }, index);
   const content = hasError ? /* @__PURE__ */ jsx(Fallback, { onClick: stopPropagation, "data-testid": "image-preview-fallback", children: currentImage?.fallback ?? fallback ?? /* @__PURE__ */ jsx(FallbackBox, { children: /* @__PURE__ */ jsx(Icon, { component: /* @__PURE__ */ jsx(ImageM, {}) }) }) }) : image;
-  return createPortal(/* @__PURE__ */ jsxs(Overlay, { ref: overlayRef, role: "dialog", "aria-modal": true, "aria-label": currentImage?.alt, tabIndex: -1, $hidden: !open, onMouseDown: handleOverlayPointerDown, onClick: handleMaskClick, "data-testid": "image-preview", children: [
+  return createPortal(/* @__PURE__ */ jsxs(Overlay, { ref: overlayRef, role: "dialog", "aria-modal": true, "aria-label": currentImage?.alt, tabIndex: -1, $hidden: !open, $zIndex: resolvedZIndex, onMouseDown: handleOverlayPointerDown, onClick: handleMaskClick, "data-testid": "image-preview", children: [
     /* @__PURE__ */ jsx(ImageWrapper, { ref: workingAreaRef, children: zoomable && !hasError ? /* @__PURE__ */ jsx(TransformWrapper, { ref: transformRef, minScale: FIT_SCALE, maxScale, initialScale: FIT_SCALE, centerOnInit: true, doubleClick: {
       mode: "reset"
     }, wheel: {

package/dist/Preview/ImagePreview.styles.d.ts

@@ -1,6 +1,7 @@
 import { ThemeProps } from '@synerise/ds-core';
 export declare const Overlay: import('styled-components').StyledComponent<"div", any, ThemeProps & {
     $hidden?: boolean;
+    $zIndex: number;
 }, never>;
 export declare const ImageWrapper: import('styled-components').StyledComponent<"div", any, {}, never>;
 export declare const Image: import('styled-components').StyledComponent<"img", any, ThemeProps, never>;

package/dist/Preview/ImagePreview.styles.js

@@ -1,6 +1,5 @@
 import styled, { keyframes } from "styled-components";
 import { PREVIEW_PADDING } from "./ImagePreview.const.js";
-const OVERLAY_Z_INDEX = 1050;
 const imageFadeIn = /* @__PURE__ */ keyframes(["from{opacity:0;}to{opacity:1;}"]);
 const BACKDROP_ALPHA = "CC";
 const CONTROLS_INSET = 16;
@@ -8,7 +7,7 @@ const IMAGE_BORDER_RADIUS = 8;
 const Overlay = /* @__PURE__ */ styled.div.withConfig({
   displayName: "ImagePreviewstyles__Overlay",
   componentId: "sc-17aatff-0"
-})(["position:fixed;inset:0;z-index:", ";display:flex;align-items:center;justify-content:center;outline:none;background-color:", ";opacity:", ";visibility:", ";pointer-events:", ";transition:opacity 160ms ease,visibility 160ms ease;"], OVERLAY_Z_INDEX, (props) => `${props.theme.palette["grey-900"]}${BACKDROP_ALPHA}`, (props) => props.$hidden ? 0 : 1, (props) => props.$hidden ? "hidden" : "visible", (props) => props.$hidden ? "none" : "auto");
+})(["position:fixed;inset:0;z-index:", ";display:flex;align-items:center;justify-content:center;outline:none;background-color:", ";opacity:", ";visibility:", ";pointer-events:", ";transition:opacity 160ms ease,visibility 160ms ease;"], (props) => props.$zIndex, (props) => `${props.theme.palette["grey-900"]}${BACKDROP_ALPHA}`, (props) => props.$hidden ? 0 : 1, (props) => props.$hidden ? "hidden" : "visible", (props) => props.$hidden ? "none" : "auto");
 const ImageWrapper = /* @__PURE__ */ styled.div.withConfig({
   displayName: "ImagePreviewstyles__ImageWrapper",
   componentId: "sc-17aatff-1"

package/dist/Preview/ImagePreview.types.d.ts

@@ -30,6 +30,12 @@ export type ImagePreviewProps = {
     fallback?: ReactNode;
     /** Portal target. Defaults to `document.body`. */
     getContainer?: () => HTMLElement;
+    /**
+     * z-index of the overlay. Omit it and the preview stacks one step above the
+     * nearest enclosing modal/drawer, falling back to the `zindex-modal` token
+     * when nothing encloses it. Set it to opt out of that stack.
+     */
+    zIndex?: number;
     /** Unmount the viewer (and reset zoom state) when closed. Defaults to false. */
     destroyOnClose?: boolean;
     /** Called with the current scale whenever the zoom transform changes. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synerise/ds-image",
-  "version": "0.1.5",
+  "version": "2.0.0",
   "description": "Image UI Component for the Synerise Design System",
   "license": "ISC",
   "repository": "Synerise/synerise-design",
@@ -42,10 +42,10 @@
   ],
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@synerise/ds-icon": "^1.18.5",
-    "@synerise/ds-toolbar": "^1.1.67",
-    "@synerise/ds-tooltip": "^1.6.0",
-    "@synerise/ds-utils": "^1.10.2",
+    "@synerise/ds-icon": "^2.0.0",
+    "@synerise/ds-toolbar": "^2.0.0",
+    "@synerise/ds-tooltip": "^2.0.0",
+    "@synerise/ds-utils": "^2.0.0",
     "react-zoom-pan-pinch": "^3.6.1"
   },
   "peerDependencies": {
@@ -55,5 +55,5 @@
     "styled-components": "^5.3.3",
     "vitest": "4"
   },
-  "gitHead": "e1fece64a41fd18a78583ecb6c21ee00fe8c0759"
+  "gitHead": "033854a18f038079e9a16b0ff250f8401a2287c2"
 }