# ImageViewer changelog

Read the complete [LICENSE](https://snowui.dev/LICENSE) for the installed version before use.

Reviewed against Chinese source SHA-256 `2a9d3c4c4062c19d3c0262c4163de228bb504c65a30f2a08dfb00125f272be21`. For version differences, check the installed package as well.

- 2026-09-21: Aligned the usage guide, source Prop table, and Site / AI reading entry. Documentation only; component behavior is unchanged.

- **ImageViewer-Docs.2026-05-25** Archived the historical changelog from the top of the source file. Record future changes in this document's Changelog; keep only responsibilities, current key architecture, and the document path at the top of the source.

<a id="v141-2026-07-05"></a>

### v1.4.1 (2026-07-05)

<a id="调整"></a>

#### Adjustments

- Changed the default `dismissMode` from `button` to `backdrop`: the close button is hidden by default, and clicking empty space outside the media closes the Viewer.
- Set `dismissMode="button"` explicitly when a visible close button is needed.

<a id="v140-2026-07-05"></a>

### v1.4.0 (2026-07-05)

<a id="新功能"></a>

#### New features

- Added `dismissMode="button|backdrop"`; the close interaction policy also determines whether the close button is shown.
- `button`: show the close button and keep the Viewer open on empty-space clicks; `backdrop`: hide the close button and close when empty space outside the media is clicked.

<a id="v131-2026-07-05"></a>

### v1.3.1 (2026-07-05)

<a id="调整-1"></a>

#### Adjustments

- Automatic-mode Viewers now elect a page-level owner. When multiple instances exist, only the first owner responds to events and renders the Portal.
- When a shared Viewer exists on the page, Image / ImageGroup without an explicit previewMode join it automatically; otherwise they fall back to a new window.
- The next registered Viewer takes over automatically after the owner unmounts.

<a id="v130-2026-07-05"></a>

### v1.3.0 (2026-07-05)

<a id="新功能-1"></a>

#### New features

- Previous, next, and close controls now use built-in Buttons by default, with `ArrowLineLeft`, `ArrowLineRight`, and SnowUI `Close` respectively.
- Built-in Buttons default to `size="md"`, `variant="gray"`, and `backgroundBlur={true}`; `parts.Button` configures them together.
- Explicit composition with children and `as="prev|next|close"` remains available.

<a id="v121-2026-03-15"></a>

### v1.2.1 (2026-03-15)

<a id="修复"></a>

#### Fixes

- **IV-Docs.1** Aligned the source header, documentation header, and changelog version at `v1.2.1`.
- **IV-Skeleton.1** Added a real loading-state Skeleton bridge for string image/video resources. A `Skeleton` overlay appears while switched media loads and exits on load completion or failure.
- **IV-Docs.2** Completed the ImageViewer usage documentation, including `previewMode="viewer" / "window" / "none"`, ImageGroup previewMode, `data-snowui-image-viewer-mode` and `data-snowui-image-viewer-scope` for native HTML / `resource-svelte` images, and examples for single-image, grouped, and fallback behavior.

<a id="v120-2026-03-12"></a>

### v1.2.0 (2026-03-12)

<a id="调整-2"></a>

#### Adjustments

- **IV-Adjust.16** Automatic mode now accepts DOM images: native HTML `<img data-snowui-image-viewer-mode="viewer" />` and `resource-svelte` root `<img data-snowui-image-viewer-mode="viewer" />` join the page-level ImageViewer directly.
- **IV-Adjust.17** Added `[data-snowui-image-viewer-scope]` grouping. Within a defined scope, DOM images form a previous/next list in DOM order.
- **IV-Adjust.18** Native HTML `<img data-snowui-image-viewer-mode="window" />` opens a new window directly in automatic mode instead of entering the Viewer.

<a id="v1124-2026-03-12"></a>

### v1.1.24 (2026-03-12)

<a id="调整-3"></a>

#### Adjustments

- **IV-Nav.24** Changed previous/next navigation from wraparound to stopping at the ends. The previous control is hidden and its key disabled on the first image; the next control and key are disabled on the last. Button and keyboard behavior agree.

<a id="v1123-2026-03-12"></a>

### v1.1.23 (2026-03-12)

<a id="调整-4"></a>

#### Adjustments

- **IV-Nav.23** Unified previous, next, and close behavior across automatic and manual modes. At this historical version, the first image wrapped to the last and the last to the first; buttons and keyboard matched.

<a id="v1122-2026-03-12"></a>

### v1.1.22 (2026-03-12)

<a id="调整-5"></a>

#### Adjustments

- **IV-Key.22** Removed Space as a next-image shortcut. Automatic mode retains only `S / D / ArrowRight / ArrowDown` for next.

<a id="v1121-2026-03-12"></a>

### v1.1.21 (2026-03-12)

<a id="调整-6"></a>

#### Adjustments

- **IV-Key.21** Expanded keyboard navigation in automatic mode: `A / W / ArrowUp` for previous and `S / D / Space / ArrowDown` for next, with `Escape` to close.

<a id="v1120-2026-03-12"></a>

### v1.1.20 (2026-03-12)

<a id="文档"></a>

#### Documentation

- **IV-Doc.20** Fully synchronized the current source logic and style structure into the documentation: automatic/manual modes, event bus, prefetching, root-level click-to-close, host context protocol, Portal mounting, and root/viewport/media/control style layers.

<a id="v1119-2026-03-12"></a>

### v1.1.19 (2026-03-12)

<a id="修复-1"></a>

#### Fixes

- **IV-Fix.1** Passed all three `Frame` capability switches explicitly and added `bind:element` to the Portal host, matching the existing Portal component contract.
- **IV-Fix.2** Removed page utility-class dependencies from the default close control and replaced them with the component's `snowui-image-viewer-default-close` style.
- **IV-Fix.3** Consolidated internal variable names, role-proxy selectors, and placeholder size units to resolve naming and styling rules in standards checks.

<a id="v1118-2026-03-11"></a>

### v1.1.18 (2026-03-11)

<a id="文档-1"></a>

#### Documentation

- **IV-Doc.18** Documented the interaction and layout requirements confirmed in this iteration: `10%` screen clearance on all four sides of media, `3%` clearance for controls, clicking empty space outside media to close, `Esc` to close, and left/right arrows to switch.

<a id="v1117-2026-03-11"></a>

### v1.1.17 (2026-03-11)

<a id="调整-7"></a>

#### Adjustments

- **IV-Adjust.17** Changed ImageViewer empty-space dismissal from a separate backdrop hit target to root click delegation, excluding only the media hit area and control layer. Moved the `10%` clearance from `padding` to `viewport inset: 10vh 10vw` so the media display area is constrained directly on all sides.

<a id="v1116-2026-03-11"></a>

### v1.1.16 (2026-03-11)

<a id="调整-8"></a>

#### Adjustments

- **IV-Adjust.16** Removed the outer `Frame` overlay root from ImageViewer, leaving a plain DOM overlay with `backdrop / viewport / controls` layers. The viewport uses `padding: 10vh 10vw` for hard clearance; the backdrop closes on empty space, and controls remain in their own clickable layer.

<a id="v114-2026-03-11"></a>

### v1.1.4 (2026-03-11)

<a id="文档-2"></a>

#### Documentation

- **IV-Doc.1** Completed this conversation's ImageViewer definition: one page-level Viewer as the primary path, automatic/manual modes, Image and ImageGroup integration, disable/fallback paths, button `as` usage, video behavior, and current performance implementation.

<a id="v115-2026-03-11"></a>

### v1.1.5 (2026-03-11)

<a id="调整-9"></a>

#### Adjustments

- **IV-Adjust.5** Made ImageViewer a fixed full-page overlay with a higher layer. Removed the gray background from the media shell; images and videos display at their maximum size within the available area.

<a id="v116-2026-03-11"></a>

### v1.1.6 (2026-03-11)

<a id="调整-10"></a>

#### Adjustments

- **IV-Adjust.6** Redefined preview layout as proportions of the screen edge: the maximum media display area stays `5%` from the edge, and controls stay `3%` from the edge, floating above the media.

<a id="v117-2026-03-11"></a>

### v1.1.7 (2026-03-11)

<a id="调整-11"></a>

#### Adjustments

- **IV-Adjust.7** Constrained the media area with uniform `5%` container padding on all sides and added clicking outside the media to close the Viewer.

<a id="v118-2026-03-11"></a>

### v1.1.8 (2026-03-11)

<a id="调整-12"></a>

#### Adjustments

- **IV-Adjust.8** Added `Esc` to close and left/right arrows to switch in the preview. Limited the close hit target to the background layer rather than the whole media container, so empty space around the media can close it.

<a id="v119-2026-03-11"></a>

### v1.1.9 (2026-03-11)

<a id="调整-13"></a>

#### Adjustments

- **IV-Adjust.9** Made the `5%` viewport frame a layout constraint that does not intercept pointer events. The media shell fills it, keeping media within the `5%` clearance while clicks outside media reliably close the Viewer.

<a id="v1110-2026-03-11"></a>

### v1.1.10 (2026-03-11)

<a id="调整-14"></a>

#### Adjustments

- **IV-Adjust.10** Increased media clearance from `5%` to `10%` and narrowed the no-dismiss hit target from the entire media shell to the media itself, fixing empty-space clicks that still failed to close.

<a id="v1111-2026-03-11"></a>

### v1.1.11 (2026-03-11)

<a id="调整-15"></a>

#### Adjustments

- **IV-Adjust.11** Made media itself fill the width and height of the `10%` safe frame, with `object-fit: contain` preserving aspect ratio. The `10%` screen clearance thus becomes a stable hard constraint instead of depending on natural media dimensions.

<a id="v1112-2026-03-11"></a>

### v1.1.12 (2026-03-11)

<a id="调整-16"></a>

#### Adjustments

- **IV-Adjust.12** Moved the `10%` clearance from the media node back to stage `padding` and restored a separate `media-hitbox`, retaining both stable clearance and click-to-close in empty space outside media.

<a id="v1113-2026-03-11"></a>

### v1.1.13 (2026-03-11)

<a id="调整-17"></a>

#### Adjustments

- **IV-Adjust.13** Following established modal/lightbox structure, separated dismissal and media layout into `backdrop` and `viewport` layers: the backdrop handles click-to-close, and the viewport handles `10%` clearance and centered media.

<a id="v1114-2026-03-11"></a>

### v1.1.14 (2026-03-11)

<a id="调整-18"></a>

#### Adjustments

- **IV-Adjust.14** Added `80vw / 80vh` viewport limits to the media shell, hit area, and media itself. Keeping at least `10%` space on all four sides no longer depends solely on parent layout; media dimensions are constrained directly.

<a id="v1115-2026-03-11"></a>

### v1.1.15 (2026-03-11)

<a id="调整-19"></a>

#### Adjustments

- **IV-Adjust.15** Portaled ImageViewer to `document.body` so ancestor `transform / filter / contain` cannot affect the overlay; `fixed` positioning and `10%` clearance now apply to the whole viewport.

<a id="v111-2026-03-11"></a>

### v1.1.1 (2026-03-11)

<a id="调整-20"></a>

#### Adjustments

- **IV-Adjust.2** Replaced the global Svelte store runtime dependency in page-level automatic mode with a browser event bus and Viewer-local state, reducing the risk of page crashes.

<a id="v112-2026-03-11"></a>

### v1.1.2 (2026-03-11)

<a id="调整-21"></a>

#### Adjustments

- **IV-Adjust.3** Automatic mode no longer copies the `items` array in an open request. Viewer consumes the stable list reference directly and lightly prefetches the previous and next string images.

<a id="v113-2026-03-11"></a>

### v1.1.3 (2026-03-11)

<a id="调整-22"></a>

#### Adjustments

- **IV-Adjust.4** Added a URL deduplication cache for adjacent-item prefetching, so one preview session never creates multiple prefetch loaders for the same string image.

<a id="v110-2026-03-10"></a>

### v1.1.0 (2026-03-10)

<a id="新功能-2"></a>

#### New features

- **IV-Feat.5** Added page-level automatic mode: when `open/items/index` are omitted, ImageViewer handles clicks on the page's Image and ImageGroup components automatically.

<a id="调整-23"></a>

#### Adjustments

- **IV-Adjust.1** When an automatic ImageViewer exists on the page, Image opens through it by default; otherwise Image falls back to opening a new window.

<a id="v102-2026-03-10"></a>

### v1.0.2 (2026-03-10)

<a id="新功能-3"></a>

#### New features

- **IV-Feat.4** Added string video resources; Viewer can preview mp4/webm/ogg/mov directly.
- **IV-Behavior.1** Videos in the preview auto-play by default, using `muted + playsinline + loop` to satisfy browser autoplay rules.

<a id="v101-2026-03-10"></a>

### v1.0.1 (2026-03-10)

<a id="修复-2"></a>

#### Fixes

- **IV-Fix.1** Fixed `resource-svelte` images not displaying at enlarged size in Viewer. The preview no longer passes incorrect percentage `width/height` props to the resource component; Viewer styles handle enlargement.

<a id="v100-2026-03-10"></a>

### v1.0.0 (2026-03-10)

<a id="新功能-4"></a>

#### New features

- **IV-Feat.1** Added the standalone ImageViewer component for image previews.
- **IV-Feat.2** Added the `prev / next / close` host composition protocol.
- **IV-Feat.3** Kept switching free of motion for immediate feedback when opening, switching, and closing images.

<a id="共享遮罩"></a>

### Shared backdrop

Choose appearance with `backdrop` and click-to-close behavior with `dismissMode`; they are independent. The default changed from the old theme background at 92% opacity to the same opaque backdrop as Dialog. The background override variable remains compatible. See backdrop for implementation boundaries.

[Component guide](https://snowui.dev/llms/en/components/image-viewer.md) · [Full reference](https://snowui.dev/llms/en/components/image-viewer/reference.md)