astro-image-zoom 0.1.0-beta.2 → 0.1.0-beta.4

package/ImageZoom.astro

@@ -4,8 +4,6 @@
  * Medium-style zoom overlay with accessibility and performance features
  */
 
-// Global stylesheet: selectors are prefixed and live in @layer astro-image-zoom
-import "./zoom.css";
 import { wrapImages } from "./wrapImages";
 
 export interface Props {
@@ -107,6 +105,12 @@ const wrapperClasses = ["astro-image-zoom-wrapper", className]
 
 // Wrap the slot's images in accessible links
 const slotContent = wrapImages(await Astro.slots.render("default"));
+
+// The element only groups its content and must not add a box. Its own declarative shadow root says
+// so, with no stylesheet on the page: any rule of the site, layered or not, wins over :host. A string,
+// since Astro would take <slot> for its own
+const shadowRoot =
+  '<template shadowrootmode="open"><style>:host { display: contents; }</style><slot></slot></template>';
 ---
 
 <astro-image-zoom
@@ -122,7 +126,7 @@ const slotContent = wrapImages(await Astro.slots.render("default"));
   data-caption-position={captionPosition}
   style={variables || undefined}
 >
-  <Fragment set:html={slotContent} />
+  <Fragment set:html={shadowRoot + slotContent} />
 </astro-image-zoom>
 
 <script>
@@ -134,6 +138,15 @@ const slotContent = wrapImages(await Astro.slots.render("default"));
     private zoom: Zoom | null = null;
 
     connectedCallback() {
+      // The browser attaches the declarative shadow root while parsing, but not in pages parsed
+      // with DOMParser, as the client router of Astro does: attach it from the template then
+      if (!this.shadowRoot) {
+        const template = this.querySelector<HTMLTemplateElement>(":scope > template[shadowrootmode]");
+        if (template) {
+          this.attachShadow({ mode: "open" }).append(template.content.cloneNode(true));
+          template.remove();
+        }
+      }
       this.zoom = new Zoom(this);
     }
 

package/README.md

@@ -1,5 +1,7 @@
 # astro-image-zoom
 
+[![npm version](https://img.shields.io/npm/v/astro-image-zoom/beta)](https://www.npmjs.com/package/astro-image-zoom)
+
 Medium-style image zoom for Astro: a click grows each image from its place on the page to fill the
 screen, and the images of a gallery become a carousel you can swipe.
 
@@ -9,7 +11,9 @@ screen, and the images of a gallery become a carousel you can swipe.
 ## Features
 
 - **Zoom from the page**: FLIP animations with CSS transforms and `clip-path`, from the thumbnail to
-  the full image and back, crops included.
+  the full image and back, crops included: the `object-fit` and `object-position` of the thumbnail,
+  and thumbnail files cropped to another shape, such as Astro's `<Image width height>`. A file
+  stretched to another shape with `object-fit: fill` animates as with `cover`.
 - **Accessible**: a native modal `<dialog>` that traps and restores focus, keyboard navigation,
   labelled controls, reduced motion and forced colors.
 - **Galleries**: a native scroll-snap carousel with touch and touchpad swipes, arrow keys, buttons and
@@ -62,17 +66,19 @@ const fullSize = await getImage({ src: photo, width: 1920 });
 
 ### Which image the zoom shows
 
-The zoom opens, in this order:
-
-1. The URL in `data-zoom-src`, if the image has it.
-2. The `href` of a link around the image (`<a href="…" data-zoom>`).
-3. The image's own `src`.
-
-Plain images work out of the box: `<img src="/photo.jpg">` opens that same file, at full size.
-
-> **Warning: resized images look blurry when zoomed.** If the image on the page is a smaller
-> version (a thumbnail, or Astro's `<Image width={400}>`, which generates a 400 px file), the zoom
-> enlarges that small file. Add `data-zoom-src` with the full-size version, as shown in
+- **An image on its own** opens the URL in its `data-zoom-src`, or its own `src` without it. Plain
+  images work out of the box: `<img src="/photo.jpg">` opens that same file, at full size.
+- **An image inside a link with `data-zoom`** (`<a href="…" data-zoom>`) opens the `href` of the
+  link. Put `data-zoom-caption` (or `title`) on the link: the image inside gives only its `alt`, and
+  its own `data-zoom-src` and `data-zoom-caption` are ignored. See
+  [Gallery with Links](#gallery-with-links).
+- **An image inside any other link** is left alone: the link keeps working as a link (a card, a
+  logo) and the image is not part of the gallery.
+
+> **Resized images barely grow when zoomed.** The zoom shows each image at most at its real size,
+> never enlarged. If the image on the page is a smaller version (a thumbnail, or Astro's
+> `<Image width={400}>`, which generates a 400 px file), the zoom opens that small file and it
+> stays small. Add `data-zoom-src` with the full-size version, as shown in
 > [High-Resolution Images](#high-resolution-images) and
 > [Using with Astro Assets](#using-with-astro-assets-optimized-images).
 
@@ -219,10 +225,6 @@ You can override the default styles using CSS variables:
   --zoom-caption-font-size: 13px;
   --zoom-color-scheme: light dark; /* set "dark" or "light" to follow your own theme toggle */
   --zoom-caption-radius: 6px;
-
-  /* Focus ring drawn on the image when its link has keyboard focus */
-  --zoom-focus-outline: 3px solid rebeccapurple; /* default: 2px solid currentColor */
-  --zoom-focus-offset: 3px; /* use a negative value if a parent with overflow: hidden clips it */
 }
 ```
 
@@ -262,30 +264,49 @@ astro-image-zoom-overlay::part(caption) {
 | `nav`, `prev`, `next` | The arrows (`nav` matches both) |
 | `counter` | The position in the gallery |
 
-The component loads its own stylesheet, so you don't need to import `zoom.css` yourself. Import
-`astro-image-zoom/zoom.css` directly only if you use `ZoomClass` without the `<ImageZoom>` component.
+#### Your page
 
-#### Cascade layer
+How your images look on the page is up to your site: the component doesn't style them, not even
+their focus ring. It only wraps each image in a link, so it opens with the keyboard and, without
+JavaScript, links to the full-size image:
 
-The styles for the images on your page (the zoom cursor and the focus ring) live in the
-`astro-image-zoom` [cascade layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
-Any unlayered CSS on your page overrides them, with no specificity tricks or `!important`.
+```html
+<a href="/full-size.jpg" data-zoom-generated aria-label="Enlarge image: A red car">
+  <img src="/photo.jpg" alt="A red car" />
+</a>
+```
 
-If your site uses its own layers, add `astro-image-zoom` to your layer order so you decide what wins.
-Declare the order before any stylesheet loads (for example, in an inline `<style>` at the top of
-`<head>`), because the first time a layer appears fixes its position:
+The link is inline and unstyled, so it never changes your layout, and it gets your site's link
+styles, focus ring included. If your images are `display: block`, the outline of an inline link
+doesn't wrap them: depending on the browser it is invisible or spans the whole line. Draw your
+focus ring on the image instead, in your own style:
 
-```html
-<style is:inline>
-  @layer reset, base, astro-image-zoom, components;
-</style>
+```css
+a[data-zoom-generated]:focus-visible {
+  outline: none;
+}
+
+a[data-zoom-generated]:focus-visible img {
+  outline: 2px solid green; /* your focus ring */
+  outline-offset: 3px; /* negative if a parent with overflow: hidden clips it */
+}
+```
+
+A zoom cursor, if you want one, is also yours to add:
+
+```css
+a[data-zoom-generated] img {
+  cursor: zoom-in;
+}
 ```
 
-With this order your reset can't break the zoom cursor or the focus ring, and your `components`
-layer can still customize them. Class names (`.astro-image-zoom-*`) are prefixed, so the styles don't
-clash with the rest of your site.
+The component adds no stylesheet to your page. `<astro-image-zoom>` groups the images without
+adding a box of its own (`display: contents`), from its own
+[declarative shadow root](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#declaratively_with_html),
+so it works without JavaScript and any rule of your site wins over it, cascade layers included.
 
-To style the images of one gallery on the page, pass a class:
+To style one gallery, pass a class. It can style the images, or lay out the gallery on the element
+itself:
 
 ```astro
 <ImageZoom class="custom-zoom">
@@ -294,6 +315,11 @@ To style the images of one gallery on the page, pass a class:
 
 <style>
   /* Global: the wrapper is rendered by the component, outside the scope of your page */
+  :global(.custom-zoom) {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+  }
+
   :global(.custom-zoom img) {
     border-radius: 8px;
   }
@@ -318,7 +344,8 @@ To style the images of one gallery on the page, pass a class:
 
 - A native modal `<dialog>`: focus moves to the close button, stays inside while it is open and
   returns to the image when it closes.
-- Each image becomes a link, reachable with the keyboard, with a visible focus ring.
+- Each image becomes a link, reachable with the keyboard. Its focus ring is the one of your site;
+  see [Your page](#your-page) to draw it on the image.
 - Labelled buttons; the caption is announced when the image changes.
 - Reduced motion turns the animations off; forced colors (Windows high contrast) keep the controls
   visible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-image-zoom",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Medium-style image zoom for Astro: accessible, animated from the page, with swipeable galleries",
   "type": "module",
   "author": "Antonio (https://antoniohg.com)",
@@ -10,7 +10,7 @@
     "url": "git+https://github.com/antoniohg/astro-image-zoom.git",
     "directory": "packages/astro-image-zoom"
   },
-  "homepage": "https://github.com/antoniohg/astro-image-zoom#readme",
+  "homepage": "https://antoniohg.com/astro-image-zoom/",
   "bugs": {
     "url": "https://github.com/antoniohg/astro-image-zoom/issues"
   },
@@ -25,8 +25,7 @@
   ],
   "exports": {
     ".": "./index.js",
-    "./ImageZoom.astro": "./ImageZoom.astro",
-    "./zoom.css": "./zoom.css"
+    "./ImageZoom.astro": "./ImageZoom.astro"
   },
   "files": [
     "index.js",
@@ -35,7 +34,6 @@
     "overlay.css",
     "env.d.ts",
     "wrapImages.ts",
-    "zoom.css",
     "README.md"
   ],
   "peerDependencies": {
@@ -48,6 +46,7 @@
     "vitest": "5.0.1"
   },
   "scripts": {
+    "check": "astro check",
     "test": "vitest run",
     "test:e2e": "playwright test -c e2e/playwright.config.ts"
   }

package/zoom.ts

@@ -3,7 +3,6 @@
  * Medium-style zoom with accessibility and performance optimizations
  */
 
-/// <reference path="./env.d.ts" />
 import overlayStyles from './overlay.css?inline';
 
 interface ZoomImage {
@@ -135,6 +134,15 @@ function getOverlay(): HTMLDialogElement {
 // A box on the screen, such as the one getBoundingClientRect() returns
 type Box = Pick<DOMRect, 'left' | 'top' | 'width' | 'height'>;
 
+// How a thumbnail draws its file inside its box: the computed object-fit and object-position of the
+// <img>, and the size of the file
+export interface ThumbnailFit {
+  objectFit: string;
+  objectPosition: string;
+  naturalWidth: number;
+  naturalHeight: number;
+}
+
 interface FlipTransform {
   x: number;
   y: number;
@@ -142,23 +150,91 @@ interface FlipTransform {
   clipPath: string;
 }
 
-/**
- * The FLIP transform that lays an element with the `final` box over the `source` box: the
- * translation between their centers, the scale that makes it cover the source box, and the
- * clip-path (in the element's own, unscaled pixels) that trims what overflows it. A thumbnail
- * cropped with object-fit: cover so grows into the whole image.
- */
-export function flipTransform(source: Box, final: Box): FlipTransform {
-  // Cover the source box, as object-fit: cover does
-  const scale = Math.max(source.width / final.width, source.height / final.height);
+function thumbnailFit(img: HTMLImageElement): ThumbnailFit {
+  const { objectFit, objectPosition } = getComputedStyle(img);
+  return { objectFit, objectPosition, naturalWidth: img.naturalWidth, naturalHeight: img.naturalHeight };
+}
 
-  const x = source.left + source.width / 2 - (final.left + final.width / 2);
-  const y = source.top + source.height / 2 - (final.top + final.height / 2);
+// Where object-position puts the drawn file along one axis, given the free space of the box
+// (negative when the file overflows it). Browsers compute it as a percentage of that space, a
+// length in px, or calc() of both: "right 10px" is calc(100% - 10px). Anything else, or nothing,
+// centers the file, the default
+function positionOffset(value: string | undefined, free: number): number {
+  const percent = /(-?[\d.]+)%/.exec(value ?? '');
+  const pixels = /([+-]?)\s*(-?[\d.]+)px/.exec(value ?? '');
+  if (!percent && !pixels) return free / 2;
+
+  const offset =
+    (percent ? (free * Number(percent[1])) / 100 : 0) +
+    (pixels ? Number(pixels[2]) * (pixels[1] === '-' ? -1 : 1) : 0);
+  return Number.isFinite(offset) ? offset : free / 2;
+}
 
-  // What overflows the source box once scaled, on each side, back in unscaled pixels
-  const insetX = (final.width * scale - source.width) / 2 / scale;
-  const insetY = (final.height * scale - source.height) / 2 / scale;
-  const clipPath = `inset(${insetY}px ${insetX}px ${insetY}px ${insetX}px)`;
+// The box where a thumbnail draws its file on the screen, which object-fit can make smaller than
+// its box (contain) or bigger (cover, none). Without a fit, or with fill, it is the box itself.
+// fill also stretches a file of another shape, which one uniform scale cannot follow: such a
+// thumbnail animates as with cover
+function drawnBox(source: Box, fit?: ThumbnailFit): Box {
+  if (!fit || !fit.naturalWidth || !fit.naturalHeight) return source;
+
+  const widthRatio = source.width / fit.naturalWidth;
+  const heightRatio = source.height / fit.naturalHeight;
+  const scales: Record<string, number> = {
+    contain: Math.min(widthRatio, heightRatio),
+    cover: Math.max(widthRatio, heightRatio),
+    none: 1,
+    'scale-down': Math.min(1, widthRatio, heightRatio),
+  };
+  const scale = scales[fit.objectFit];
+  if (scale === undefined) return source;
+
+  const width = fit.naturalWidth * scale;
+  const height = fit.naturalHeight * scale;
+  // One value per axis; a calc() has spaces of its own
+  const [positionX, positionY] = fit.objectPosition.match(/calc\([^)]*\)|\S+/g) ?? [];
+  return {
+    left: source.left + positionOffset(positionX, source.width - width),
+    top: source.top + positionOffset(positionY, source.height - height),
+    width,
+    height,
+  };
+}
+
+/**
+ * The FLIP transform that lays the zoomed image, with the `final` box, over its thumbnail, with the
+ * `source` box: the translation between their centers, the scale, and the clip-path (in the
+ * image's own, unscaled pixels) that trims what the thumbnail does not show.
+ *
+ * `fit` tells how the thumbnail draws its file (object-fit, object-position). That file may also be
+ * cropped from the full image already, as Astro's <Image> does with a width and a height of another
+ * shape: it is taken as a centered crop, so the scale matches what the thumbnail really shows.
+ * Without `fit`, the image covers the source box, as object-fit: cover does.
+ */
+export function flipTransform(source: Box, final: Box, fit?: ThumbnailFit): FlipTransform {
+  const drawn = drawnBox(source, fit);
+
+  // The whole image around the drawn file, at the same scale, taking the file as a centered crop
+  const imageRatio = final.width / final.height;
+  const drawnRatio = drawn.width / drawn.height;
+  const width = imageRatio > drawnRatio ? drawn.height * imageRatio : drawn.width;
+  const height = width / imageRatio;
+  const left = drawn.left + (drawn.width - width) / 2;
+  const top = drawn.top + (drawn.height - height) / 2;
+  const scale = width / final.width;
+
+  const x = left + width / 2 - (final.left + final.width / 2);
+  const y = top + height / 2 - (final.top + final.height / 2);
+
+  // Only what the thumbnail shows stays visible: the drawn file, cut to the box of the thumbnail
+  const visibleLeft = Math.max(drawn.left, source.left);
+  const visibleTop = Math.max(drawn.top, source.top);
+  const visibleRight = Math.min(drawn.left + drawn.width, source.left + source.width);
+  const visibleBottom = Math.min(drawn.top + drawn.height, source.top + source.height);
+  const insetTop = (visibleTop - top) / scale;
+  const insetRight = (left + width - visibleRight) / scale;
+  const insetBottom = (top + height - visibleBottom) / scale;
+  const insetLeft = (visibleLeft - left) / scale;
+  const clipPath = `inset(${insetTop}px ${insetRight}px ${insetBottom}px ${insetLeft}px)`;
 
   return { x, y, scale, clipPath };
 }
@@ -234,10 +310,10 @@ class Zoom {
     this.setupEventListeners();
   }
 
+  // Only the links the component generated and those the site marks with data-zoom: any other link
+  // with an image (a card, a logo) keeps navigating
   private collectImages(): void {
-    const links = this.wrapper.querySelectorAll<HTMLAnchorElement>(
-      'a[data-zoom-generated], a[data-zoom], a:has(img)'
-    );
+    const links = this.wrapper.querySelectorAll<HTMLAnchorElement>('a[data-zoom-generated], a[data-zoom]');
 
     this.state.images = Array.from(links)
       .map((anchor) => {
@@ -249,7 +325,7 @@ class Zoom {
           element: anchor
         };
       })
-      .filter(({ src }) => src && src !== window.location.origin + '/' && src !== 'about:blank');
+      .filter(({ src }) => src);
   }
 
   private setupEventListeners(): void {
@@ -326,6 +402,7 @@ class Zoom {
     // Get source image and position
     const sourceImg = this.state.images[index].element.querySelector('img')!;
     const sourceRect = sourceImg.getBoundingClientRect();
+    const sourceFit = thumbnailFit(sourceImg);
 
     this.buildSlides();
     this.renderActive(index);
@@ -378,7 +455,7 @@ class Zoom {
 
     // FLIP Animation
     const finalRect = this.imageElement.getBoundingClientRect();
-    const transform = flipTransform(sourceRect, finalRect);
+    const transform = flipTransform(sourceRect, finalRect, sourceFit);
 
     // Set CSS variables for animation
     this.setAnimationVariables(transform);
@@ -450,7 +527,7 @@ class Zoom {
     const targetRect = sourceImg.getBoundingClientRect();
 
     // Calculate transform for closing animation
-    const transform = flipTransform(targetRect, startRect);
+    const transform = flipTransform(targetRect, startRect, thumbnailFit(sourceImg));
 
     // Set CSS variables for closing animation
     this.setAnimationVariables(transform);

package/zoom.css

@@ -1,36 +0,0 @@
-/*
- * astro-image-zoom page styles: the images on the page, not the zoom overlay.
- *
- * The overlay lives in a shadow root and brings its own styles (overlay.css), so no CSS of
- * the page can reach it. Style it with the --zoom-* custom properties or with ::part().
- *
- * These page styles live in the `astro-image-zoom` cascade layer, so any unlayered CSS on the page
- * overrides them without specificity fights. To control their priority among your own layers,
- * name the layer in your layer order, e.g. `@layer reset, astro-image-zoom, components;`.
- */
-@layer astro-image-zoom {
-  /* The element only groups its content, it must not add a box */
-  astro-image-zoom {
-    display: contents;
-  }
-
-  /* Links wrapping images: the image is the click target */
-  .astro-image-zoom-wrapper a img {
-    cursor: zoom-in;
-  }
-
-  /*
-   * Focus ring on the image, not on the generated link: the link is inline, so when the image
-   * is display: block its outline does not wrap the image. Customize it with
-   * --zoom-focus-outline and --zoom-focus-offset (a negative offset draws it inside the image,
-   * useful when a parent with overflow: hidden would clip it).
-   */
-  .astro-image-zoom-wrapper a[data-zoom-generated]:focus-visible {
-    outline: none;
-
-    img {
-      outline: var(--zoom-focus-outline, 2px solid currentColor);
-      outline-offset: var(--zoom-focus-offset, 3px);
-    }
-  }
-}