Type the custom dither prop in Astro image APIs

.changeset/cyan-berries-wear.md

@@ -0,0 +1,5 @@
+---
+"@sweetcorn/astro": minor
+---
+
+Adds proper types for the `dither` prop in Astro’s image APIs. Requires Astro 5.16.6 or higher.

.changeset/goofy-trains-joke.md

@@ -0,0 +1,9 @@
+---
+"@sweetcorn/astro": minor
+---
+
+Exports a type to help with typing code that interfaces with the `dither` prop:
+
+```ts
+import type { DitheringAlgorithm } from '@sweetcorn/astro';
+```

.github/workflows/ci.yml

@@ -31,3 +31,27 @@ jobs:
 
       - name: Run tests
         run: pnpm -r test
+
+  typecheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: 24.12.0
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Type check docs
+        run: pnpm %docs astro check

docs/package.json

@@ -13,12 +13,14 @@
 		"astro": "astro"
 	},
 	"dependencies": {
+		"@astrojs/check": "^0.9.6",
 		"@astrojs/starlight": "^0.37.1",
 		"@sweetcorn/astro": "workspace:*",
 		"astro": "^5.16.6",
 		"sharp": "^0.34.5",
 		"starlight-package-managers": "^0.11.1",
-		"starlight-theme-flexoki": "^0.2.1"
+		"starlight-theme-flexoki": "^0.2.1",
+		"typescript": "^5.9.3"
 	},
 	"private": true
 }

docs/src/components/AlgorithmDemo.astro

@@ -1,4 +1,5 @@
 ---
+import type { DitheringAlgorithm } from '@sweetcorn/astro';
 import { Image } from 'astro:assets';
 import diffusionKernels from '../../../packages/sweetcorn/src/diffusion-kernels.ts';
 import thresholdMaps from '../../../packages/sweetcorn/src/threshold-maps.json';
@@ -23,7 +24,7 @@ const algorithms = {
 				<code>
 					<small>{algorithm}</small>
 				</code>
-				<Image src={demo} alt="" dither={algorithm} />
+				<Image src={demo} alt="" dither={algorithm as DitheringAlgorithm} />
 			</li>
 		))
 	}

docs/src/content/docs/guides/astro.mdx

@@ -165,3 +165,36 @@ You can then use your custom diffusion kernels using the `dither` prop:
 ```
 
 See [“Error diffusion dithering”](/sweetcorn/guides/byo-algorithm/#error-diffusion-dithering) for more details.
+
+## Types
+
+### `DitheringAlgorithm` type
+
+```ts
+import type { DitheringAlgorithm } from '@sweetcorn/astro';
+```
+
+The `DitheringAlgorithm` type represents all valid algorithms that can be passed to the `dither` prop in Astro’s image APIs.
+It can be helpful when typing a component that accepts a dither algorithm as a prop:
+
+```astro {3,8}
+---
+// src/components/DitheredFigure.astro
+import type { DitheringAlgorithm } from '@sweetcorn/astro';
+import type { ImageMetadata } from 'astro';
+import { Image } from 'astro:assets';
+
+interface Props {
+	algorithm: DitheringAlgorithm;
+	image: ImageMetadata;
+}
+
+const { algorithm, image } = Astro.props;
+---
+
+<figure>
+	<Image src={image} alt="" dither={algorithm} />
+	<figcaption><slot /></figcaption>
+</figure>
+
+```

packages/astro/image-props.d.ts

@@ -0,0 +1,19 @@
+declare namespace Astro {
+	interface CustomImageProps {
+		/** Dither this image with the specified algorithm. Set to `false` to disable dithering. */
+		dither?:
+			| import('sweetcorn').DitheringAlgorithm
+			| false
+			| (keyof Sweetcorn.Astro extends never ? never : Sweetcorn.Astro['CustomAlgorithms']);
+	}
+}
+
+declare namespace Sweetcorn {
+	export interface Astro {
+		/**
+		 * We don’t define this here to allow us to later set it during Astro’s type generation based
+		 * on a user’s provided custom algorithms.
+		 */
+		// CustomAlgorithms: never;
+	}
+}

packages/astro/index.ts

@@ -1,6 +1,10 @@
+/// <reference types="./image-props.d.ts" />
+
 import type { AstroIntegration } from 'astro';
 import type { SweetcornImageConfig } from './types';
 
+export type DitheringAlgorithm = Exclude<Astro.CustomImageProps['dither'], false | undefined>;
+
 export default function sweetcornAstro<T extends string = never, D extends string = never>(
 	config: SweetcornImageConfig<T, D> = {}
 ) {
@@ -27,6 +31,29 @@ export default function sweetcornAstro<T extends string = never, D extends strin
 				const serviceUrl = new URL('./service.ts', import.meta.url);
 				addWatchFile(serviceUrl);
 			},
+
+			/**
+			 * Add the names of user-defined algorithms to the type for the `dither` prop.
+			 * These are merged into the `Sweetcorn.Astro` interface in `image-props.d.ts`.
+			 */
+			'astro:config:done'({ injectTypes }) {
+				const customAlgorithms = [
+					...Object.keys(config.customDiffusionKernels || {}),
+					...Object.keys(config.customThresholdMaps || {}),
+				];
+				if (customAlgorithms.length > 0) {
+					injectTypes({
+						filename: 'custom-algorithms.d.ts',
+						content:
+							'declare namespace Sweetcorn {\n' +
+							'	export interface Astro {\n' +
+							'		/** Custom dithering algorithms provided by the user. */\n' +
+							`		CustomAlgorithms: ${customAlgorithms.map((a) => JSON.stringify(a)).join(' | ')};\n` +
+							'	}\n' +
+							'}',
+					});
+				}
+			},
 		},
 	} satisfies AstroIntegration;
 }

packages/astro/package.json

@@ -23,7 +23,7 @@
 		"sharp": "^0.34.5"
 	},
 	"peerDependencies": {
-		"astro": "^5.16.5",
+		"astro": "^5.16.6",
 		"sharp": ">=0.33.0"
 	},
 	"publishConfig": {