shelving 1.323.2 → 1.323.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -22119,6 +22119,9 @@ Props for `Image` — an `src`, optional `alt` text, plus space and width varian
22119
22119
  - Import: `import { Image } from "shelving/ui";`
22120
22120
 
22121
22121
  Image block — renders an `<img>` with space and width variants applied.
22122
+ - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
22123
+ - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
22124
+ - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
22122
22125
 
22123
22126
  ## Signatures
22124
22127
 
package/docs/ui/Image.md CHANGED
@@ -4,6 +4,9 @@
4
4
  - Import: `import { Image } from "shelving/ui";`
5
5
 
6
6
  Image block — renders an `<img>` with space and width variants applied.
7
+ - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
8
+ - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
9
+ - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
7
10
 
8
11
  ## Signatures
9
12
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.323.2",
3
+ "version": "1.323.3",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -13,6 +13,9 @@ export interface ImageProps extends SpaceVariants, WidthVariants, ClassProps {
13
13
  }
14
14
  /**
15
15
  * Image block — renders an `<img>` with space and width variants applied.
16
+ * - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
17
+ * - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
18
+ * - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
16
19
  *
17
20
  * @kind component
18
21
  * @example <Image src="/logo.png" alt="Logo" width="narrow" />
package/ui/block/Image.js CHANGED
@@ -5,12 +5,29 @@ import IMAGE_CSS from "./Image.module.css";
5
5
  const IMAGE_CLASS = getModuleClass(IMAGE_CSS, "image");
6
6
  /**
7
7
  * Image block — renders an `<img>` with space and width variants applied.
8
+ * - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
9
+ * - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
10
+ * - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
8
11
  *
9
12
  * @kind component
10
13
  * @example <Image src="/logo.png" alt="Logo" width="narrow" />
11
14
  * @see https://shelving.cc/ui/Image
12
15
  */
13
16
  export function Image({ src, alt, className, ...props }) {
14
- return (_jsx("img", { src: src, alt: alt, className: getClass(IMAGE_CLASS, //
17
+ return (_jsx("img", { src: src, alt: alt, loading: "lazy", ref: _refImage, onLoad: _onImageLoad, onError: _onImageDone, onAnimationEnd: _onImageDone, className: getClass(IMAGE_CLASS, //
15
18
  getBlockClass(props), className) }));
16
19
  }
20
+ /** Show an image that loaded before it mounted (from the cache, or before hydration) at once, with no fade. */
21
+ function _refImage(img) {
22
+ if (img?.complete && !img.dataset.loaded)
23
+ img.dataset.loaded = "done";
24
+ }
25
+ /** Fade the image in when it loads. */
26
+ function _onImageLoad({ currentTarget }) {
27
+ if (!currentTarget.dataset.loaded)
28
+ currentTarget.dataset.loaded = "fade";
29
+ }
30
+ /** End the fade, or show an image that failed to load. */
31
+ function _onImageDone({ currentTarget }) {
32
+ currentTarget.dataset.loaded = "done";
33
+ }
@@ -1,5 +1,6 @@
1
1
  @import url("../style/layers.css");
2
2
  @import url("../style/Space.module.css");
3
+ @import url("../style/Duration.module.css");
3
4
 
4
5
  @layer components {
5
6
  .image,
@@ -13,4 +14,30 @@
13
14
  object-position: center center;
14
15
  object-fit: cover; /* Don't distort when resized. */
15
16
  }
17
+
18
+ /* Hidden until it loads, then it fades in once. Only with scripts on: without them, `data-loaded` is never set. */
19
+ @media (scripting: enabled) {
20
+ .image:not([data-loaded]) {
21
+ opacity: 0;
22
+ }
23
+ }
24
+
25
+ /* The fade is an animation only while `data-loaded="fade"`, so no opacity animation stays on the image after it. WebKit keeps a layer after an opacity animation, and that layer flickers during a view transition. */
26
+ .image[data-loaded="fade"] {
27
+ animation-name: image-fade;
28
+ animation-duration: var(--image-fade-duration, var(--duration-normal));
29
+ animation-timing-function: ease-out;
30
+ }
31
+ }
32
+
33
+ @keyframes image-fade {
34
+ from {
35
+ opacity: 0;
36
+ }
37
+ }
38
+
39
+ @media (prefers-reduced-motion: reduce) {
40
+ .image[data-loaded="fade"] {
41
+ animation-name: none;
42
+ }
16
43
  }
@@ -1,4 +1,4 @@
1
- import type { ReactElement } from "react";
1
+ import type { AnimationEvent, ReactElement, SyntheticEvent } from "react";
2
2
  import { getBlockClass } from "../style/Block.js";
3
3
  import type { SpaceVariants } from "../style/Space.js";
4
4
  import type { WidthVariants } from "../style/Width.js";
@@ -20,6 +20,9 @@ export interface ImageProps extends SpaceVariants, WidthVariants, ClassProps {
20
20
 
21
21
  /**
22
22
  * Image block — renders an `<img>` with space and width variants applied.
23
+ * - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
24
+ * - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
25
+ * - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
23
26
  *
24
27
  * @kind component
25
28
  * @example <Image src="/logo.png" alt="Logo" width="narrow" />
@@ -30,6 +33,11 @@ export function Image({ src, alt, className, ...props }: ImageProps): ReactEleme
30
33
  <img
31
34
  src={src}
32
35
  alt={alt}
36
+ loading="lazy"
37
+ ref={_refImage}
38
+ onLoad={_onImageLoad}
39
+ onError={_onImageDone}
40
+ onAnimationEnd={_onImageDone}
33
41
  className={getClass(
34
42
  IMAGE_CLASS, //
35
43
  getBlockClass(props),
@@ -38,3 +46,18 @@ export function Image({ src, alt, className, ...props }: ImageProps): ReactEleme
38
46
  />
39
47
  );
40
48
  }
49
+
50
+ /** Show an image that loaded before it mounted (from the cache, or before hydration) at once, with no fade. */
51
+ function _refImage(img: HTMLImageElement | null): void {
52
+ if (img?.complete && !img.dataset.loaded) img.dataset.loaded = "done";
53
+ }
54
+
55
+ /** Fade the image in when it loads. */
56
+ function _onImageLoad({ currentTarget }: SyntheticEvent<HTMLImageElement>): void {
57
+ if (!currentTarget.dataset.loaded) currentTarget.dataset.loaded = "fade";
58
+ }
59
+
60
+ /** End the fade, or show an image that failed to load. */
61
+ function _onImageDone({ currentTarget }: SyntheticEvent<HTMLImageElement> | AnimationEvent<HTMLImageElement>): void {
62
+ currentTarget.dataset.loaded = "done";
63
+ }