Gallery

1import { GalleryLightbox } from "./gallery-lightbox.js";
2import {
3  type GalleryImage,
4  type GalleryLabels,
5  type GalleryRenderImage,
6} from "./gallery-types.js";
7import { type LightboxState } from "./use-lightbox.js";
8
9export interface GalleryActiveLightboxProps {
10  /** All the images; the open one is shown */
11  images: GalleryImage[];
12  /** Every text, already merged with the defaults */
13  labels: GalleryLabels;
14  /** Draws the image in the lightbox */
15  renderImage: GalleryRenderImage;
16  /** Says which image is open and handles navigation, close and focus return */
17  lightbox: LightboxState;
18}
19
20/** The lightbox for the image that is open, and nothing while none is. */
21export const GalleryActiveLightbox = ({
22  images,
23  labels,
24  renderImage,
25  lightbox,
26}: GalleryActiveLightboxProps) => {
27  const { openIndex } = lightbox;
28  const image = openIndex === null ? undefined : images[openIndex];
29
30  return image && openIndex !== null ? (
31    <GalleryLightbox
32      image={image}
33      total={images.length}
34      index={openIndex}
35      labels={labels}
36      renderImage={renderImage}
37      onIndexChange={lightbox.changeIndex}
38      onClose={lightbox.close}
39      onCloseAutoFocus={lightbox.restoreFocus}
40    />
41  ) : null;
42};

1import { getClassName } from "@bht-component-registry/class-names";
2import { GalleryThumbnail } from "./gallery-thumbnail.js";
3import {
4  type GalleryBreakpoint,
5  type GalleryImage,
6  type GalleryLabels,
7  type GalleryRenderImage,
8} from "./gallery-types.js";
9import { thumbnailSizes } from "./masonry.js";
10import { type LightboxState } from "./use-lightbox.js";
11import styles from "./gallery.module.scss";
12
13export interface GalleryGridProps {
14  /** The images, in the order the list renders them */
15  images: GalleryImage[];
16  /** The resolved column count per breakpoint */
17  columns: Record<GalleryBreakpoint, number>;
18  /** Every text, already merged with the defaults */
19  labels: GalleryLabels;
20  /** Draws each thumbnail */
21  renderImage: GalleryRenderImage;
22  /** Opens the lightbox and registers each thumbnail for focus return */
23  lightbox: LightboxState;
24}
25
26/** The list of thumbnails, in `images[]` order. */
27export const GalleryGrid = ({
28  images,
29  columns,
30  labels,
31  renderImage,
32  lightbox,
33}: GalleryGridProps) => {
34  const [, getChildClass] = getClassName({ rootClass: "BHT__Gallery", styles });
35  const sizes = thumbnailSizes(columns);
36
37  return (
38    <ul role="list" className={getChildClass("list")}>
39      {images.map((image, index) => (
40        <GalleryThumbnail
41          key={`${image.src}:${index}`}
42          image={image}
43          index={index}
44          labels={labels}
45          renderImage={renderImage}
46          sizes={sizes}
47          onOpen={lightbox.open}
48          buttonRef={lightbox.registerThumbnail(index)}
49        />
50      ))}
51    </ul>
52  );
53};

1import { type GalleryLabels } from "./gallery-types.js";
2
3/** English defaults; pass `labels` to Gallery to translate any of them. */
4export const DEFAULT_LABELS: GalleryLabels = {
5  close: "Close",
6  previous: "Previous image",
7  next: "Next image",
8  image: "Image",
9  counter: "{current} of {total}",
10  loading: "Loading image",
11  unavailable: "Image unavailable",
12  failed: "This image could not be loaded.",
13};

1import { getClassName } from "@bht-component-registry/class-names";
2import { Button } from "@behivetech/atoms.button";
3import { ArrowLeftIcon, ArrowRightIcon } from "@behivetech/atoms.icon";
4import { type GalleryLabels, type LightboxSteps } from "./gallery-types.js";
5import styles from "./gallery-lightbox.module.scss";
6
7type Direction = "previous" | "next";
8
9const ENABLED: Record<Direction, (nav: LightboxSteps) => boolean> = {
10  previous: (nav) => nav.canGoPrevious,
11  next: (nav) => nav.canGoNext,
12};
13
14const STEP: Record<Direction, (nav: LightboxSteps) => () => void> = {
15  previous: (nav) => nav.goPrevious,
16  next: (nav) => nav.goNext,
17};
18
19const ICONS: Record<Direction, typeof ArrowLeftIcon> = {
20  previous: ArrowLeftIcon,
21  next: ArrowRightIcon,
22};
23
24export interface GalleryLightboxArrowProps {
25  /** Which way the button steps */
26  direction: Direction;
27  labels: GalleryLabels;
28  /** What the lightbox can step to; Previous is off on the first image, Next on the last */
29  nav: LightboxSteps;
30}
31
32/** A Previous or Next button of the lightbox. */
33export const GalleryLightboxArrow = ({
34  direction,
35  labels,
36  nav,
37}: GalleryLightboxArrowProps) => {
38  const [, getChildClass] = getClassName({
39    rootClass: "BHT__GalleryLightbox",
40    styles,
41  });
42  const Icon = ICONS[direction];
43
44  return (
45    <Button
46      className={getChildClass(direction)}
47      variant="secondary"
48      size="lg"
49      iconOnly
50      aria-label={labels[direction]}
51      disabled={!ENABLED[direction](nav)}
52      onClick={STEP[direction](nav)}
53    >
54      <Icon />
55    </Button>
56  );
57};

1import { useRef } from "react";
2import { getClassName } from "@bht-component-registry/class-names";
3import { GalleryLightboxArrow } from "./gallery-lightbox-arrow.js";
4import { GalleryLightboxStage } from "./gallery-lightbox-stage.js";
5import {
6  type GalleryImage,
7  type GalleryLabels,
8  type GalleryRenderImage,
9  type LightboxNavOptions,
10  type LightboxSteps,
11} from "./gallery-types.js";
12import { useStrandedFocus } from "./use-stranded-focus.js";
13import styles from "./gallery-lightbox.module.scss";
14
15// Previous and Next exist unless the image showing is the first or the last.
16const getSteps = ({
17  index,
18  total,
19  onIndexChange,
20}: LightboxNavOptions): LightboxSteps => ({
21  canGoPrevious: index > 0,
22  canGoNext: index < total - 1,
23  goPrevious: () => onIndexChange(index - 1),
24  goNext: () => onIndexChange(index + 1),
25});
26
27export interface GalleryLightboxBodyProps {
28  image: GalleryImage;
29  /** Its position in `images[]` */
30  index: number;
31  /** How many images there are */
32  total: number;
33  labels: GalleryLabels;
34  renderImage: GalleryRenderImage;
35  onIndexChange: (index: number) => void;
36  /** The id the dialog's `aria-describedby` points at */
37  captionId: string;
38}
39
40/** What sits inside the lightbox dialog: Previous, the image, Next and the caption. */
41export const GalleryLightboxBody = ({
42  image,
43  index,
44  total,
45  labels,
46  renderImage,
47  onIndexChange,
48  captionId,
49}: GalleryLightboxBodyProps) => {
50  const [rootClass, getChildClass] = getClassName({
51    rootClass: "BHT__GalleryLightbox",
52    styles,
53  });
54  const rootRef = useRef<HTMLDivElement | null>(null);
55  const nav = getSteps({ index, total, onIndexChange });
56
57  useStrandedFocus(rootRef, nav.canGoPrevious, nav.canGoNext);
58
59  return (
60    <div ref={rootRef} className={rootClass}>
61      <GalleryLightboxArrow direction="previous" labels={labels} nav={nav} />
62      <GalleryLightboxStage
63        image={image}
64        index={index}
65        labels={labels}
66        renderImage={renderImage}
67        canGoPrevious={nav.canGoPrevious}
68        canGoNext={nav.canGoNext}
69        onPrevious={nav.goPrevious}
70        onNext={nav.goNext}
71      />
72      <GalleryLightboxArrow direction="next" labels={labels} nav={nav} />
73      {image.caption && (
74        <p id={captionId} className={getChildClass("caption")}>
75          {image.caption}
76        </p>
77      )}
78    </div>
79  );
80};

1import { getClassName } from "@bht-component-registry/class-names";
2import { ImageIcon } from "@behivetech/atoms.icon";
3import { Spinner } from "@behivetech/atoms.spinner";
4import {
5  type GalleryImage,
6  type GalleryLabels,
7  type GalleryRenderImage,
8} from "./gallery-types.js";
9import { useImageStatus } from "./use-image-status.js";
10import { useSwipe } from "./use-swipe.js";
11import styles from "./gallery-lightbox-stage.module.scss";
12
13/** The `sizes` string for the lightbox image: it fills the viewport */
14export const LIGHTBOX_SIZES = "100vw";
15
16export interface GalleryLightboxStageProps {
17  image: GalleryImage;
18  /** Position in `images[]`; a new index mounts a fresh image */
19  index: number;
20  labels: GalleryLabels;
21  renderImage: GalleryRenderImage;
22  canGoPrevious: boolean;
23  canGoNext: boolean;
24  onPrevious: () => void;
25  onNext: () => void;
26}
27
28/**
29 * The lightbox's image area and swipe surface. While an image loads it shows a
30 * placeholder of the image's own shape and a spinner; a failed image shows a
31 * message. The image is keyed by `index`, so the previous bitmap is never left
32 * on screen under the next image's counter.
33 */
34export const GalleryLightboxStage = ({
35  image,
36  index,
37  labels,
38  renderImage,
39  canGoPrevious,
40  canGoNext,
41  onPrevious,
42  onNext,
43}: GalleryLightboxStageProps) => {
44  const [rootClass, getChildClass] = getClassName({
45    rootClass: "BHT__GalleryLightboxStage",
46    styles,
47  });
48  const { ref, status, handlers } = useImageStatus(`${index}:${image.src}`);
49  const { trackRef, handlers: swipeHandlers } = useSwipe({
50    canGoPrevious,
51    canGoNext,
52    onPrevious,
53    onNext,
54  });
55
56  return (
57    <div
58      className={rootClass}
59      aria-busy={status === "loading"}
60      {...swipeHandlers}
61    >
62      <div ref={trackRef} className={getChildClass("track")}>
63        <div
64          key={index}
65          ref={ref}
66          className={getChildClass("image")}
67          {...handlers}
68        >
69          {status === "loading" && (
70            // Holds the image's shape (contain, like the image) until it loads.
71            <svg
72              className={getChildClass("placeholder")}
73              viewBox={`0 0 ${image.width} ${image.height}`}
74              preserveAspectRatio="xMidYMid meet"
75              aria-hidden="true"
76              focusable="false"
77            >
78              <rect
79                className={getChildClass("placeholder-fill")}
80                width={image.width}
81                height={image.height}
82              />
83            </svg>
84          )}
85          {status === "error" ? (
86            <p className={getChildClass("failed")}>
87              <ImageIcon size="lg" />
88              {labels.failed}
89            </p>
90          ) : (
91            renderImage(image, { context: "lightbox", sizes: LIGHTBOX_SIZES })
92          )}
93        </div>
94        {status === "loading" && (
95          <Spinner
96            className={getChildClass("spinner")}
97            size="lg"
98            label={labels.loading}
99          />
100        )}
101      </div>
102    </div>
103  );
104};

1import { getClassName } from "@bht-component-registry/class-names";
2import { type GalleryLabels } from "./gallery-types.js";
3import styles from "./gallery-lightbox.module.scss";
4
5export interface GalleryLightboxTitleProps {
6  /** Its position in `images[]` */
7  index: number;
8  /** How many images there are */
9  total: number;
10  labels: GalleryLabels;
11}
12
13/**
14 * The dialog title: a polite live region reading "Image 4 of 12", so each
15 * change is announced.
16 */
17export const GalleryLightboxTitle = ({
18  index,
19  total,
20  labels,
21}: GalleryLightboxTitleProps) => {
22  const [, getChildClass] = getClassName({
23    rootClass: "BHT__GalleryLightbox",
24    styles,
25  });
26  const counter = labels.counter
27    .replace("{current}", String(index + 1))
28    .replace("{total}", String(total));
29
30  return (
31    <span aria-live="polite">
32      <span className={getChildClass("visually-hidden")}>{labels.image}</span>{" "}
33      {counter}
34    </span>
35  );
36};

1import { useId, type KeyboardEvent } from "react";
2import { Modal } from "@behivetech/atoms.modal";
3import {
4  type GalleryImage,
5  type GalleryLabels,
6  type GalleryRenderImage,
7  type LightboxNavOptions,
8} from "./gallery-types.js";
9import { GalleryLightboxBody } from "./gallery-lightbox-body.js";
10import { GalleryLightboxTitle } from "./gallery-lightbox-title.js";
11
12// Where each navigation key goes, given the current and last index.
13const KEY_TARGETS: Record<string, (index: number, last: number) => number> = {
14  ArrowLeft: (index) => index - 1,
15  ArrowRight: (index) => index + 1,
16  Home: () => 0,
17  End: (_index, last) => last,
18};
19
20// The dialog's keydown handler: the target is clamped so it never wraps.
21const getKeyHandler =
22  ({ index, total, onIndexChange }: LightboxNavOptions) =>
23  (event: KeyboardEvent<HTMLDivElement>) => {
24    const last = total - 1;
25    const target = KEY_TARGETS[event.key]?.(index, last);
26
27    if (target !== undefined) {
28      event.preventDefault();
29      onIndexChange(Math.min(Math.max(target, 0), last));
30    }
31  };
32
33export interface GalleryLightboxProps {
34  /** The image showing */
35  image: GalleryImage;
36  /** Its position in `images[]` */
37  index: number;
38  /** How many images there are */
39  total: number;
40  labels: GalleryLabels;
41  renderImage: GalleryRenderImage;
42  onIndexChange: (index: number) => void;
43  onClose: () => void;
44  onCloseAutoFocus: (event: Event) => void;
45}
46
47/**
48 * The lightbox: a fullscreen `Modal` with a counter title, Close, the current
49 * image with its caption, and Previous and Next. It does not wrap: Previous is
50 * disabled on the first image and Next on the last. Arrow keys, Home and End
51 * navigate from anywhere in the dialog; a swipe on the image does the same.
52 */
53export const GalleryLightbox = ({
54  image,
55  index,
56  total,
57  labels,
58  renderImage,
59  onIndexChange,
60  onClose,
61  onCloseAutoFocus,
62}: GalleryLightboxProps) => {
63  const captionId = useId();
64  const handleKeyDown = getKeyHandler({ index, total, onIndexChange });
65  const title = (
66    <GalleryLightboxTitle index={index} total={total} labels={labels} />
67  );
68
69  return (
70    <Modal
71      size="fullscreen"
72      closeLabel={labels.close}
73      title={title}
74      onClose={onClose}
75      onCloseAutoFocus={onCloseAutoFocus}
76      onKeyDown={handleKeyDown}
77      aria-describedby={image.caption ? captionId : undefined}
78    >
79      <GalleryLightboxBody
80        image={image}
81        index={index}
82        total={total}
83        labels={labels}
84        renderImage={renderImage}
85        onIndexChange={onIndexChange}
86        captionId={captionId}
87      />
88    </Modal>
89  );
90};

1import { type Ref } from "react";
2import { getClassName } from "@bht-component-registry/class-names";
3import { ImageIcon } from "@behivetech/atoms.icon";
4import {
5  type GalleryImage,
6  type GalleryLabels,
7  type GalleryRenderImage,
8} from "./gallery-types.js";
9import { rowSpan } from "./masonry.js";
10import { useImageStatus } from "./use-image-status.js";
11import styles from "./gallery-thumbnail.module.scss";
12
13export interface GalleryThumbnailProps {
14  image: GalleryImage;
15  /** Position in `images[]`, passed back to `onOpen` */
16  index: number;
17  labels: GalleryLabels;
18  renderImage: GalleryRenderImage;
19  /** The `sizes` string handed to `renderImage` */
20  sizes: string;
21  onOpen: (index: number) => void;
22  /** Lets Gallery return focus here when the lightbox closes */
23  buttonRef: Ref<HTMLButtonElement>;
24}
25
26/**
27 * One grid tile: a button named by the image alt that opens the lightbox. Its
28 * row span comes from the image's ratio, so it is the right height before the
29 * image loads.
30 */
31export const GalleryThumbnail = ({
32  image,
33  index,
34  labels,
35  renderImage,
36  sizes,
37  onOpen,
38  buttonRef,
39}: GalleryThumbnailProps) => {
40  const { ref, status, handlers } = useImageStatus(image.src);
41  const isError = status === "error";
42  const [rootClass, getChildClass] = getClassName({
43    rootClass: "BHT__GalleryThumbnail",
44    modifiers: { [`span-${rowSpan(image)}`]: true },
45    styles,
46  });
47
48  return (
49    <li className={rootClass}>
50      <button
51        ref={buttonRef}
52        type="button"
53        className={getChildClass("button")}
54        aria-haspopup="dialog"
55        // A failed tile shows its own text; the name carries it (WCAG 2.5.3).
56        aria-label={isError ? `${image.alt}, ${labels.unavailable}` : image.alt}
57        onClick={() => onOpen(index)}
58      >
59        <span ref={ref} className={getChildClass("media")} {...handlers}>
60          {isError ? (
61            <span className={getChildClass("unavailable")}>
62              <ImageIcon size="lg" />
63              {labels.unavailable}
64            </span>
65          ) : (
66            renderImage(image, { context: "thumbnail", sizes })
67          )}
68        </span>
69      </button>
70    </li>
71  );
72};

1import { type ReactNode } from "react";
2
3/**
4 * One image in the grid and the lightbox. A tile keeps the image's ratio up to
5 * about 3:1 (height over width): the row span is capped at 150 rows, so a taller
6 * image is cropped to that height in its thumbnail (`object-fit: cover`). The
7 * lightbox always shows the whole image.
8 */
9export interface GalleryImage {
10  /** Image URL */
11  src: string;
12  /** Required: names the thumbnail button and the lightbox image */
13  alt: string;
14  /** Intrinsic width in px; with `height` it fixes the tile's shape before the image loads */
15  width: number;
16  /** Intrinsic height in px. Past about 3 times the width the thumbnail crops the image */
17  height: number;
18  /** Shown under the image in the lightbox only; never over a thumbnail */
19  caption?: string;
20}
21
22/** The breakpoints `columns` is set for: below 48rem, from 48rem, from 64rem. */
23export type GalleryBreakpoint = "xs" | "md" | "lg";
24
25/** Column counts per breakpoint: `xs` below 48rem, `md` from 48rem, `lg` from 64rem */
26export type GalleryColumnsConfig = Partial<Record<GalleryBreakpoint, number>>;
27
28/** A column count for every width, or a count per breakpoint. */
29export type GalleryColumns = number | GalleryColumnsConfig;
30
31export interface GalleryRenderImageOptions {
32  /** Where the image is drawn */
33  context: "thumbnail" | "lightbox";
34  /** A ready-made `sizes` string for that context, to pass to `next/image` */
35  sizes: string;
36}
37
38/** Draws an image; an app passes `next/image` here. */
39export type GalleryRenderImage = (
40  image: GalleryImage,
41  options: GalleryRenderImageOptions,
42) => ReactNode;
43
44/** Every text the gallery shows or announces, so an app can translate them. */
45export interface GalleryLabels {
46  /** Lightbox close button name */
47  close: string;
48  /** Lightbox previous button name */
49  previous: string;
50  /** Lightbox next button name */
51  next: string;
52  /** Visually hidden word before the counter, so the dialog reads "Image 4 of 12" */
53  image: string;
54  /** Counter text; `{current}` and `{total}` are replaced */
55  counter: string;
56  /** Spinner name while the lightbox image loads */
57  loading: string;
58  /** Text on a thumbnail whose image failed */
59  unavailable: string;
60  /** Text in the lightbox when the image failed */
61  failed: string;
62}
63
64/** What the lightbox needs to step between images. */
65export interface LightboxNavOptions {
66  /** The image showing */
67  index: number;
68  /** How many images there are */
69  total: number;
70  /** Called with the index to show next */
71  onIndexChange: (index: number) => void;
72}
73
74/** What the lightbox can step to from the image showing; it does not wrap. */
75export interface LightboxSteps {
76  /** False on the first image */
77  canGoPrevious: boolean;
78  /** False on the last image */
79  canGoNext: boolean;
80  /** Shows the previous image */
81  goPrevious: () => void;
82  /** Shows the next image */
83  goNext: () => void;
84}

1import { useMemo, type HTMLAttributes } from "react";
2import { getClassName } from "@bht-component-registry/class-names";
3import { GalleryActiveLightbox } from "./gallery-active-lightbox.js";
4import { GalleryGrid } from "./gallery-grid.js";
5import { DEFAULT_LABELS } from "./gallery-labels.js";
6import {
7  type GalleryColumns,
8  type GalleryImage,
9  type GalleryLabels,
10  type GalleryRenderImage,
11} from "./gallery-types.js";
12import { DEFAULT_COLUMNS, resolveColumns } from "./masonry.js";
13import { useLightbox } from "./use-lightbox.js";
14import styles from "./gallery.module.scss";
15
16export interface GalleryProps extends Omit<
17  HTMLAttributes<HTMLDivElement>,
18  "children"
19> {
20  /** Additional class names to merge with the component root element */
21  className?: string;
22  /** The images, in the order the grid, Tab and the lightbox follow. An empty array renders nothing */
23  images: GalleryImage[];
24  /**
25   * Columns: a number for every width, or `{ xs, md, lg }` for below 48rem, from
26   * 48rem and from 64rem (any you omit keep the default). Up to 8. Defaults to
27   * `{ xs: 2, md: 3, lg: 4 }`.
28   */
29  columns?: GalleryColumns;
30  /**
31   * Draws each image, so an app can pass `next/image`. Receives the image and
32   * `{ context: "thumbnail" | "lightbox", sizes }`. Defaults to a lazy `<img>`.
33   * Render a plain `<img>` (or a component that renders one): the grid fills
34   * the tile with it.
35   */
36  renderImage?: GalleryRenderImage;
37  /** Called with `true` and the opened index when the lightbox opens, and with `false` and the index showing when it closes */
38  onOpenChange?: (open: boolean, index: number) => void;
39  /** Replaces any of the built-in English texts, for translation */
40  labels?: Partial<GalleryLabels>;
41}
42
43// One root modifier per breakpoint (`xs-2`, `md-3`, `lg-4`), which the
44// stylesheet turns into the grid template.
45const columnModifiers = (counts: Record<string, number>) =>
46  Object.fromEntries(
47    Object.entries(counts).map(([breakpoint, count]) => [
48      `${breakpoint}-${count}`,
49      true,
50    ]),
51  );
52
53const defaultRenderImage: GalleryRenderImage = (image, { context }) => (
54  <img
55    src={image.src}
56    alt={image.alt}
57    width={image.width}
58    height={image.height}
59    loading={context === "thumbnail" ? "lazy" : "eager"}
60    decoding="async"
61  />
62);
63
64/**
65 * A responsive masonry image grid that opens a swipeable, keyboard-navigable
66 * lightbox. It is one list in `images[]` order, so Tab, reading and lightbox
67 * order agree; tiles keep each image's ratio and captions show in the lightbox
68 * only. Built on `Modal`.
69 */
70export const Gallery = ({
71  className,
72  images,
73  columns = DEFAULT_COLUMNS,
74  renderImage = defaultRenderImage,
75  onOpenChange,
76  labels,
77  ...rest
78}: GalleryProps) => {
79  const counts = resolveColumns(columns);
80  const [rootClass] = getClassName({
81    className,
82    rootClass: "BHT__Gallery",
83    modifiers: columnModifiers(counts),
84    styles,
85  });
86  const lightbox = useLightbox({ onOpenChange });
87  const mergedLabels = useMemo(
88    () => ({ ...DEFAULT_LABELS, ...labels }),
89    [labels],
90  );
91  const parts = { images, labels: mergedLabels, renderImage, lightbox };
92
93  return images.length > 0 ? (
94    <div {...rest} className={rootClass}>
95      <GalleryGrid {...parts} columns={counts} />
96      <GalleryActiveLightbox {...parts} />
97    </div>
98  ) : null;
99};

1import {
2  type GalleryBreakpoint,
3  type GalleryColumns,
4  type GalleryImage,
5} from "./gallery-types.js";
6
7/** Columns per breakpoint when `columns` is not given. */
8export const DEFAULT_COLUMNS: Record<GalleryBreakpoint, number> = {
9  xs: 2,
10  md: 3,
11  lg: 4,
12};
13
14/** Most columns the stylesheet has a class for. */
15export const MAX_COLUMNS = 8;
16
17/**
18 * Grid rows per column width (gallery.module.scss derives the row height from
19 * it). More rows per column means a tile's height is closer to its image's
20 * ratio, at the price of a bigger span number.
21 */
22export const ROWS_PER_COLUMN = 48;
23
24/**
25 * Rows added to every span to cover the vertical gap (a margin on the tile) at
26 * typical column widths, so tile height stays within a few px of the ratio.
27 */
28export const GAP_ROWS = 2.4;
29
30/** Tallest and flattest tile the stylesheet has a span class for. */
31export const MAX_SPAN = 150;
32
33/**
34 * Resolves the `columns` prop to a whole count per breakpoint. A number applies
35 * everywhere; an object overrides the defaults per breakpoint.
36 */
37export const resolveColumns = (
38  columns: GalleryColumns,
39): Record<GalleryBreakpoint, number> => {
40  const requested =
41    typeof columns === "number"
42      ? { xs: columns, md: columns, lg: columns }
43      : { ...DEFAULT_COLUMNS, ...columns };
44
45  return Object.fromEntries(
46    Object.entries(requested).map(([breakpoint, count]) => [
47      breakpoint,
48      Math.min(MAX_COLUMNS, Math.max(1, Math.floor(count) || 1)),
49    ]),
50  ) as Record<GalleryBreakpoint, number>;
51};
52
53/**
54 * How many grid rows a tile spans, from its image's height over width. Tiles of
55 * different ratios then stack into columns with the grid's own auto-placement,
56 * while the DOM stays in `images[]` order.
57 */
58export const rowSpan = ({ width, height }: GalleryImage): number =>
59  Math.min(
60    MAX_SPAN,
61    Math.max(1, Math.round((height / width) * ROWS_PER_COLUMN + GAP_ROWS)),
62  );
63
64/**
65 * The `sizes` string for a thumbnail, from the columns it will sit in (the
66 * gutter is ignored, so it errs a little large).
67 */
68export const thumbnailSizes = (
69  columns: Record<GalleryBreakpoint, number>,
70): string => {
71  const share = (count: number) => `${Math.round(100 / count)}vw`;
72
73  return [
74    `(min-width: 64rem) ${share(columns.lg)}`,
75    `(min-width: 48rem) ${share(columns.md)}`,
76    share(columns.xs),
77  ].join(", ");
78};

1import {
2  useEffect,
3  useRef,
4  useState,
5  type ReactEventHandler,
6  type RefObject,
7} from "react";
8
9/** Where an image is: still loading, shown, or failed. */
10export type ImageStatus = "loading" | "loaded" | "error";
11
12interface ImageStatusResult {
13  /** Attach to the element that contains the rendered `<img>` */
14  ref: RefObject<HTMLDivElement | null>;
15  status: ImageStatus;
16  /** Spread on the same element: load and error do not bubble, so React's capture phase catches them */
17  handlers: {
18    onLoadCapture: ReactEventHandler;
19    onErrorCapture: ReactEventHandler;
20  };
21}
22
23/**
24 * Tracks whether the `<img>` inside a wrapper has loaded or failed, whatever
25 * component drew it (the default `<img>` or an app's `next/image`). `resetKey`
26 * names the image: a new key starts again at `loading`. An image that finished
27 * before hydration fires no event, so a new key also reads `complete`.
28 */
29export const useImageStatus = (resetKey: string): ImageStatusResult => {
30  const ref = useRef<HTMLDivElement | null>(null);
31  const [result, setResult] = useState<{ key: string; status: ImageStatus }>({
32    key: resetKey,
33    status: "loading",
34  });
35  const status = result.key === resetKey ? result.status : "loading";
36
37  useEffect(() => {
38    const img = ref.current?.querySelector("img");
39
40    // An image that settled before React attached fires no event later, so a
41    // finished image with no pixels (a 404 under SSR) is an error now.
42    if (img?.complete) {
43      setResult({
44        key: resetKey,
45        status: img.naturalWidth > 0 ? "loaded" : "error",
46      });
47    }
48  }, [resetKey]);
49
50  return {
51    ref,
52    status,
53    handlers: {
54      onLoadCapture: () => setResult({ key: resetKey, status: "loaded" }),
55      onErrorCapture: () => setResult({ key: resetKey, status: "error" }),
56    },
57  };
58};

1import { useRef, useState } from "react";
2
3interface UseLightboxOptions {
4  /** Called with `true` and the opened index, and with `false` and the index showing when it closes */
5  onOpenChange?: (open: boolean, index: number) => void;
6}
7
8/**
9 * Open state for the gallery lightbox, and where focus goes when it closes: the
10 * thumbnail of the image showing at that moment, not the one first opened,
11 * scrolled into view.
12 */
13export const useLightbox = ({ onOpenChange }: UseLightboxOptions) => {
14  const [openIndex, setOpenIndex] = useState<number | null>(null);
15  const thumbnails = useRef<(HTMLButtonElement | null)[]>([]);
16  // The image showing, kept outside state so the close handlers read the latest.
17  const shownIndex = useRef(0);
18
19  const open = (index: number) => {
20    shownIndex.current = index;
21    setOpenIndex(index);
22    onOpenChange?.(true, index);
23  };
24
25  const changeIndex = (index: number) => {
26    shownIndex.current = index;
27    setOpenIndex(index);
28  };
29
30  const close = () => {
31    setOpenIndex(null);
32    onOpenChange?.(false, shownIndex.current);
33  };
34
35  const restoreFocus = (event: Event) => {
36    const thumbnail = thumbnails.current[shownIndex.current];
37
38    event.preventDefault();
39    thumbnail?.focus();
40    thumbnail?.scrollIntoView?.({ block: "nearest" });
41  };
42
43  const registerThumbnail =
44    (index: number) => (element: HTMLButtonElement | null) => {
45      thumbnails.current[index] = element;
46    };
47
48  return {
49    openIndex,
50    open,
51    changeIndex,
52    close,
53    restoreFocus,
54    registerThumbnail,
55  };
56};
57
58/** What `useLightbox` returns, for the components that read or drive it. */
59export type LightboxState = ReturnType<typeof useLightbox>;