[Feature] Document aspectRatio contraints

[colbyfayock]

Document the aspectRatio contraints wrt how and when it applies under the cldimage/config page

Per https://github.com/cloudinary-community/next-cloudinary/issues/352#issuecomment-2115636574

hey @\antoinerousseau as it stands, and i think i need to update the documentation to reflect this, aspectRatio doesn't get applied unless combined with a crop mode, for instance:

<CldImage
  src="examples/mario_hkgavf"
  width={2048}
  height={1600}
  aspectRatio="16:9"
  alt="mario"
  crop="fill"
/>

will give you:

https://res.cloudinary.com/colbycloud-examples/image/upload/c_fill,ar_16:9,w_3840,h_3000,g_auto/f_auto/q_auto/v1/examples/mario_hkgavf?_a=BAVFAaAO0

however that's not very useful because the width and the height prevent the aspect ratio from applying as a transformation

where aspectRatio really makes sense is when using the fill prop, such as:

<CldImage
  src="examples/mario_hkgavf"
  aspectRatio="16:9"
  fill
  alt="mario"
  crop="fill"
/>

which would give you this:

https://res.cloudinary.com/colbycloud-examples/image/upload/c_fill,ar_16:9,w_2048,g_auto/f_auto/q_auto/v1/examples/mario_hkgavf?_a=BAVFAaAO0

the issue is that width and height are required props for the component. this is a Next Image component requirement that's passed along to this component and it's required to prevent layout shift when applied to the <img tag in the DOM

but thats where the fill option comes in, which doesn't require a width and height, but then you control the size of the parent container which the image then "fills". this is a good use case for the aspectRatio prop in that regard

i'm open to feedback and ideas on this, as it's not outright intuitive with how that works. i'll create a ticket to update the docs to make this more clear to start

[ayan-joshi]

@colbyfayock where we need to add the document for aspectRatio , your explanation was on point it explains it very well

[colbyfayock]

seems like we may want to add aspectRatio to https://next.cloudinary.dev/cldimage/configuration#basic-transformations

create a new description for it similar to angle in that list

then add it there

[RaghavMangla]

when will hacktoberfest tags be added to issues

[colbyfayock]

@RaghavMangla the tag is on the entire repository, so any Issue marked with "help wanted" is game

[DevRish]

Hi @colbyfayock , I would like to work on this issue. Please assign it to me.

[colbyfayock]

sure thing, all yours!

[DevRish]

@colbyfayock
I have made the changes in the docs and raised a PR. Please review. Thanks!

[github-actions[bot]]

:tada: This issue has been resolved in version 6.14.2 :tada:

The release is available on:

• pnpm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket:

[github-actions[bot]]

:tada: This issue has been resolved in version 7.0.0-beta.3 :tada:

The release is available on:

• pnpm package (@beta dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: