feat!: Replace Aspect Ratio component with utility classes and prop on Image

packages/css/src/components/aspect-ratio/README.md

@@ -4,17 +4,21 @@
 
 Aspect Ratio updates the height of an element with its width.
 
-These are the proportions we use:
+## Class names
 
-| keyword   | ratio |
-| :-------- | ----: |
-| `2x-wide` |  16:5 |
-| `x-wide`  |  16:9 |
-| `wide`    |   4:3 |
-| `square`  |   1:1 |
-| `tall`    |   3:4 |
-| `x-tall`  |  9:16 |
+Each available aspect ratio has an associated class name.
+The class can be applied to any component or element.
+
+| Class name                  | Example                                                                     |
+| :-------------------------- | :-------------------------------------------------------------------------- |
+| `ams-aspect-ratio--x-tall`  | <div className="ams-docs-token-example--space ams-aspect-ratio--x-tall" />  |
+| `ams-aspect-ratio--tall`    | <div className="ams-docs-token-example--space ams-aspect-ratio--tall" />    |
+| `ams-aspect-ratio--square`  | <div className="ams-docs-token-example--space ams-aspect-ratio--square" />  |
+| `ams-aspect-ratio--wide`    | <div className="ams-docs-token-example--space ams-aspect-ratio--wide" />    |
+| `ams-aspect-ratio--x-wide`  | <div className="ams-docs-token-example--space ams-aspect-ratio--x-wide" />  |
+| `ams-aspect-ratio--2x-wide` | <div className="ams-docs-token-example--space ams-aspect-ratio--2x-wide" /> |
 
 ## Guidelines
 
-- Use this component to constrain images, videos and other elements to one of the available aspect ratios.
+- Apply one of these classes to an image, video or other media content to constrain its dimensions to one of the available aspect ratios.
+- The default aspect ratio is 16:9.

packages/css/src/components/aspect-ratio/aspect-ratio.scss

@@ -4,30 +4,9 @@
  */
 
 .ams-aspect-ratio {
-  overflow: hidden;
-  position: relative;
-}
-
-.ams-aspect-ratio--x-tall {
-  aspect-ratio: var(--ams-aspect-ratio-x-tall);
-}
-
-.ams-aspect-ratio--tall {
-  aspect-ratio: var(--ams-aspect-ratio-tall);
-}
-
-.ams-aspect-ratio--square {
-  aspect-ratio: var(--ams-aspect-ratio-square);
-}
-
-.ams-aspect-ratio--wide {
-  aspect-ratio: var(--ams-aspect-ratio-wide);
-}
-
-.ams-aspect-ratio--x-wide {
-  aspect-ratio: var(--ams-aspect-ratio-x-wide);
-}
-
-.ams-aspect-ratio--2x-wide {
-  aspect-ratio: var(--ams-aspect-ratio-2x-wide);
+  @each $name in ("x-tall", "tall", "square", "wide", "x-wide", "2x-wide") {
+    &--#{$name} {
+      aspect-ratio: var(--ams-aspect-ratio-#{$name}) !important;
+    }
+  }
 }

packages/css/src/components/image/README.md

@@ -4,6 +4,12 @@
 
 Displays an image.
 
+## Design
+
+Every Image must display in one of the [available aspect ratios](https://designsystem.amsterdam/?path=/docs/brand-design-tokens-aspect-ratio--docs).
+The default is 16:9.
+If the intrinsic dimensions of the source do not match an aspect ratio, the image will get cropped to cover the intended area without distorting its appearance.
+
 ## Guidelines
 
 - Do not forget to include a description of the image in the `alt` attribute.
@@ -15,7 +21,6 @@ Displays an image.
   For example, provide small, medium, and large variants for various screen sizes.
   This prevents unnecessary downloading of large files.
   Do this especially for the main image of a page, where the difference between sizes on a narrow and wide screen is most significant.
-- Ensure that the aspect ratio of the image is supported by the [Aspect Ratio](/docs/components-layout-aspect-ratio--docs) component.
 
 ## Relevant WCAG requirements
 

packages/css/src/components/image/image.scss

@@ -4,17 +4,17 @@
  */
 
 .ams-image {
+  aspect-ratio: var(--ams-image-aspect-ratio);
   block-size: auto; /* [1] */
   font-style: italic; /* [3] */
+  inline-size: fit-content;
   max-inline-size: 100%; /* [1] */
+  object-fit: cover; /* [4] */
   vertical-align: middle; /* [2] */
-
-  &--cover {
-    object-fit: cover;
-  }
 }
 
 // [1] Allow for fluid image sizing while maintaining aspect ratio governed by inline/block size attributes
 // [2] Remove ‘phantom’ white space
 // [3] Italicise alt text to visually offset it from surrounding copy
 // Source: https://x.com/csswizardry/status/1717841334462005661
+// [4] Crop the image to maintain a supported aspect ratio

packages/react/src/Column/Column.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react'
 import { createRef } from 'react'
 import { Column, columnGapSizes } from './Column'
-import { crossAlignOptionsForColumn, mainAlignOptions } from '../common/layout'
+import { crossAlignOptionsForColumn, mainAlignOptions } from '../common/types'
 import '@testing-library/jest-dom'
 
 describe('Column', () => {

packages/react/src/Column/Column.tsx

@@ -6,7 +6,7 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { HTMLAttributes, PropsWithChildren } from 'react'
-import type { CrossAlignForColumn, MainAlign } from '../common/layout'
+import type { CrossAlignForColumn, MainAlign } from '../common/types'
 
 export const columnGapSizes = ['none', 'extra-small', 'small', 'large', 'extra-large'] as const
 

packages/react/src/Image/Image.test.tsx

@@ -1,6 +1,7 @@
 import { render } from '@testing-library/react'
 import { createRef } from 'react'
 import { Image } from './Image'
+import { aspectRatioOptions } from '../common/types'
 import '@testing-library/jest-dom'
 
 describe('Image', () => {
@@ -26,16 +27,17 @@ describe('Image', () => {
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('extra')
-    expect(component).toHaveClass('ams-image')
+    expect(component).toHaveClass('ams-image extra')
   })
 
-  it('renders a class name to display the image as large as its container', () => {
-    const { container } = render(<Image cover />)
+  aspectRatioOptions.forEach((aspectRatio) => {
+    it(`renders class names to display the image in the ${aspectRatio} aspect ratio`, () => {
+      const { container } = render(<Image aspectRatio={aspectRatio} />)
 
-    const component = container.querySelector(':only-child')
+      const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-image--cover')
+      expect(component).toHaveClass(`ams-aspect-ratio--${aspectRatio}`)
+    })
   })
 
   it('supports ForwardRef in React', () => {

packages/react/src/Image/Image.tsx

@@ -6,15 +6,17 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, ImgHTMLAttributes } from 'react'
+import { AspectRatioProps } from '../common/types'
 
-export type ImageProps = {
-  /** Whether to display the image exactly as large as its container. This will clip the image if necessary. */
-  cover?: boolean
-} & ImgHTMLAttributes<HTMLImageElement>
+export type ImageProps = AspectRatioProps & ImgHTMLAttributes<HTMLImageElement>
 
 export const Image = forwardRef(
-  ({ className, cover = false, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
-    <img {...restProps} ref={ref} className={clsx('ams-image', cover && 'ams-image--cover', className)} />
+  ({ aspectRatio, className, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
+    <img
+      {...restProps}
+      ref={ref}
+      className={clsx('ams-image', aspectRatio && `ams-aspect-ratio--${aspectRatio}`, className)}
+    />
   ),
 )
 

packages/react/src/ImageSlider/ImageSlider.tsx

@@ -11,13 +11,9 @@ import { ImageSliderControls } from './ImageSliderControls'
 import { ImageSliderItem } from './ImageSliderItem'
 import { ImageSliderScroller } from './ImageSliderScroller'
 import { ImageSliderThumbnails } from './ImageSliderThumbnails'
-import { Ratio } from '../AspectRatio'
 import { Image, ImageProps } from '../Image/Image'
 
-export type ImageSliderImageProps = ImageProps & {
-  /** Specify the aspect ratio to use for the images. */
-  aspectRatio: Ratio
-}
+export type ImageSliderImageProps = ImageProps
 
 export type ImageSliderProps = {
   /** Display buttons to navigate to the previous or next image. */

packages/react/src/Row/Row.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react'
 import { createRef } from 'react'
 import { Row, rowGapSizes } from './Row'
-import { crossAlignOptions, mainAlignOptions } from '../common/layout'
+import { crossAlignOptions, mainAlignOptions } from '../common/types'
 import '@testing-library/jest-dom'
 
 describe('Row', () => {

packages/react/src/Row/Row.tsx

@@ -6,7 +6,7 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { HTMLAttributes, PropsWithChildren } from 'react'
-import type { CrossAlign, MainAlign } from '../common/layout'
+import type { CrossAlign, MainAlign } from '../common/types'
 
 export const rowGapSizes = ['none', 'extra-small', 'small', 'large', 'extra-large'] as const
 

packages/react/src/Switch/Switch.test.tsx

@@ -92,7 +92,7 @@ describe('Switch', () => {
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-switch', 'extra')
+    expect(component).toHaveClass('ams-switch extra')
   })
 
   it('is able to pass a React ref', () => {

packages/react/src/common/layout.ts → packages/react/src/common/types.ts

@@ -1,3 +1,9 @@
+export const aspectRatioOptions = ['x-tall', 'tall', 'square', 'wide', 'x-wide', '2x-wide'] as const
+export type AspectRatioProps = {
+  /** The aspect ratio to display media content in. */
+  aspectRatio?: (typeof aspectRatioOptions)[number]
+}
+
 export const crossAlignOptions = ['start', 'center', 'baseline', 'end'] as const
 export type CrossAlign = (typeof crossAlignOptions)[number]
 

packages/react/src/index.ts

@@ -46,7 +46,6 @@ export * from './Switch'
 export * from './Spotlight'
 export * from './Card'
 export * from './Alert'
-export * from './AspectRatio'
 export * from './Footer'
 export * from './PageMenu'
 export * from './TopTaskLink'

proprietary/tokens/README.md

@@ -82,7 +82,7 @@ Examples:
 :root {
   --ams-color-primary-red: #ec0000;
   --ams-space-md: 1rem;
-  --ams-proportion-wide: 4/3;
+  --ams-aspect-ratio-wide: 4/3;
   --ams-border-width-lg: 0.1875rem;
 }
 ```

proprietary/tokens/src/brand/ams/proportion.tokens.json → proprietary/tokens/src/brand/ams/aspect-ratio.tokens.json

@@ -1,6 +1,6 @@
 {
   "ams": {
-    "proportion": {
+    "aspect-ratio": {
       "x-tall": { "value": "9 / 16" },
       "tall": { "value": "3 / 4" },
       "square": { "value": "1 / 1" },

proprietary/tokens/src/components/ams/avatar.tokens.json

@@ -1,7 +1,7 @@
 {
   "ams": {
     "avatar": {
-      "aspect-ratio": { "value": "{ams.proportion.square}" },
+      "aspect-ratio": { "value": "{ams.aspect-ratio.square}" },
       "font-family": { "value": "{ams.text.font-family}" },
       "font-size": { "value": "{ams.text.level.6.font-size}" },
       "font-weight": { "value": "{ams.text.font-weight.normal}" },

proprietary/tokens/src/components/ams/image.tokens.json

@@ -0,0 +1,7 @@
+{
+  "ams": {
+    "image": {
+      "aspect-ratio": { "value": "{ams.aspect-ratio.x-wide}" }
+    }
+  }
+}