Support extending the image API props type

[delucis]

Changes

Adds an Astro.CustomImageProps interface that users can extend to support additional props in <Image>, <Picture>, and getImage(). Handling non-standard props is already supported in the Image Service API, there’s just no way to type them.

For example, with this PR, an image service that supports blurring images can add a custom blur prop:

// example.d.ts
declare namespace Astro {
  interface CustomImageProps {
    /** Apply a Gaussian blur with this radius to the image. */
    blur?: number;
  }
}

Notes:

• This is a single interface that extends all three APIs (<Image>, <Picture>, and getImage()). Maybe hypothetically someone only wants to extend one of these? But I feel like if you’re saying any of these APIs should behave differently, you may want to export specific wrapper components/functions instead of reusing Astro’s.
• getImage() uses a different type from the components, which doesn’t seem to share anything even though many of the properties overlap, so this required a separate change to the ImageTransform type.

Testing

Tested by patching node_modules in a project with a custom image service.

Docs

Includes a changeset and has an accompanying docs PR: withastro/docs#12897
/cc @withastro/maintainers-docs for feedback!

[changeset-bot]

🦋 Changeset detected

Latest commit: 7da3e3d

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed-hq]

CodSpeed Performance Report

Merging #15014 will not alter performance

_{Comparing chris/image-props (7da3e3d) with main (8cdaa00)¹}

Summary

✅ 6 untouched

Footnotes

1. No successful run was found on main (0d2adac) during the generation of this report, so 8cdaa00 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[codenomnom]

@delucis oh my, thank you! ❤️