dither-image

1"use client"
2 
3/**
4 * `DitherImage` — compound figure that applies a CSS-only Bayer dither effect
5 * to an image via the `dither-plugin` Tailwind utility. Safari-compatible (no
6 * SVG filters), fully static (no JS runtime cost), and respects all the
7 * plugin's tunable CSS custom properties as typed props.
8 *
9 * ## Installation
10 *
11 * ```bash
12 * bun add dither-plugin
13 * # or: npm install dither-plugin
14 * # or: pnpm add dither-plugin
15 * # or: yarn add dither-plugin
16 * ```
17 *
18 * Then register the plugin in your Tailwind v4 stylesheet (alongside
19 * `tailwindcss`):
20 *
21 * ```css
22 * @import "tailwindcss";
23 * @import "dither-plugin";
24 * ```
25 *
26 * ## Usage
27 *
28 * ```tsx
29 * <DitherImage>
30 *   <DitherImageFrame aspectRatio="square" size="md">
31 *     <DitherImageContent
32 *       src="/images/apple-wallpaper.jpg"
33 *       alt="Apple wallpaper"
34 *       fill
35 *       sizes="(min-width: 768px) 33vw, 100vw"
36 *     />
37 *   </DitherImageFrame>
38 *   <DitherImageCaption>Apple wallpaper, dithered</DitherImageCaption>
39 * </DitherImage>
40 * ```
41 *
42 * Partial dither (masked clean layer + optional `invertOnDark`):
43 *
44 * ```tsx
45 * <DitherImageReveal className="size-72 overflow-hidden rounded-xl">
46 *   <DitherImageFrame invertOnDark size="lg" aspectRatio="square">
47 *     <DitherImageContent src="/photo.jpg" alt="" fill sizes="288px" />
48 *   </DitherImageFrame>
49 *   <DitherImageOverlay src="/photo.jpg" alt="" fill sizes="288px" from={0} to={65} />
50 * </DitherImageReveal>
51 * ```
52 *
53 * ## Notes
54 *
55 * - The dither class must live on a **wrapper** around the image. The plugin
56 *   paints the dot matrix via a `::after` pseudo-element, which `<img>` /
57 *   `<video>` elements do not render.
58 * - The wrapper applies `filter: grayscale() brightness() blur() contrast()`
59 *   to all children. Render captions / overlay text **outside** the
60 *   `DitherImageFrame` (as `DitherImageCaption` does) so they stay crisp.
61 * - `background: #000` ships from the plugin to give the `screen` blend-mode
62 *   something to lift against. Override with an inline background if needed.
63 *
64 * @see https://github.com/flornkm/dither-plugin
65 */
66import {
67  createContext,
68  forwardRef,
69  useContext,
70  type ComponentProps,
71  type CSSProperties,
72  type HTMLAttributes,
73} from "react"
74import Image, { type ImageProps } from "next/image"
75 
76import { cn } from "@/lib/utils"
77 
78/** Cell size of the underlying dither matrix — maps to plugin `--dither-cell-*` theme tokens. */
79// … truncated