feat(core): Implements an aspect ratio component

apps/tester/src/settings.tsx

@@ -25,6 +25,7 @@ export type Fixture = {
   alterVariants?: UIVariant[];
   alterColors?: UIColor[];
   alterStates?: UIState[];
+  waitTime?: number;
   renderJoyElement: ElementRenderer;
   renderTjElement: ElementRenderer;
 };
@@ -63,6 +64,7 @@ export function testEach(
     alterVariants,
     alterColors,
     alterStates,
+    waitTime,
     renderJoyElement,
     renderTjElement,
   } of fixtures) {
@@ -112,6 +114,9 @@ export function testEach(
                     </div>
                   </App>,
                 );
+                if (waitTime) {
+                  await sleep(waitTime);
+                }
                 if (state === 'hover') {
                   await page.getByTestId(elementTestId).hover();
                 } else if (state === 'focus-visible') {
@@ -153,6 +158,9 @@ export function testEach(
                     </div>
                   </App>,
                 );
+                if (waitTime) {
+                  await sleep(waitTime);
+                }
                 if (state === 'hover') {
                   await page.getByTestId(elementTestId).hover();
                 } else if (state === 'focus-visible') {

apps/tester/tests/06-aspect-ratio.spec.tsx

@@ -0,0 +1,88 @@
+import { AspectRatio as JoyAspectRatio } from '@mui/joy';
+import { AspectRatio as TJAspectRatio } from 'tailwind-joy/components';
+
+import type { Fixture } from '@/settings';
+import { testEach } from '@/settings';
+
+const containerClassName =
+  'flex h-[200px] w-[400px] items-center justify-center p-2';
+
+const fixtures: Fixture[] = [
+  {
+    title: 'basics',
+    alterSizes: ['md'],
+    alterColors: ['primary'],
+    renderJoyElement({ testId, size, variant, color }) {
+      return (
+        <JoyAspectRatio data-testid={testId} sx={{ width: 300 }}>
+          <div>Lorem ipsum</div>
+        </JoyAspectRatio>
+      );
+    },
+    renderTjElement({ testId, size, variant, color }) {
+      return (
+        <TJAspectRatio data-testid={testId} className="w-[300px]">
+          <div>Lorem ipsum</div>
+        </TJAspectRatio>
+      );
+    },
+  },
+  {
+    title: 'ratio',
+    alterSizes: ['md'],
+    alterColors: ['primary'],
+    renderJoyElement({ testId, size, variant, color }) {
+      return (
+        <JoyAspectRatio data-testid={testId} ratio="3/2" sx={{ width: 300 }}>
+          <div>Lorem ipsum</div>
+        </JoyAspectRatio>
+      );
+    },
+    renderTjElement({ testId, size, variant, color }) {
+      return (
+        <TJAspectRatio data-testid={testId} ratio="3/2" className="w-[300px]">
+          <div>Lorem ipsum</div>
+        </TJAspectRatio>
+      );
+    },
+  },
+  {
+    title: 'objectFit',
+    alterSizes: ['md'],
+    alterColors: ['primary'],
+    waitTime: 3000,
+    renderJoyElement({ testId, size, variant, color }) {
+      return (
+        <JoyAspectRatio
+          data-testid={testId}
+          objectFit="contain"
+          sx={{ width: 300 }}
+        >
+          <img
+            src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
+            alt="A beautiful landscape."
+          />
+        </JoyAspectRatio>
+      );
+    },
+    renderTjElement({ testId, size, variant, color }) {
+      return (
+        <TJAspectRatio
+          data-testid={testId}
+          objectFit="contain"
+          className="w-[300px]"
+        >
+          <img
+            src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
+            alt="A beautiful landscape."
+          />
+        </TJAspectRatio>
+      );
+    },
+  },
+];
+
+testEach(fixtures, {
+  containerClassName,
+  viewport: { width: 500, height: 500 },
+});

apps/website/docs/apis/06-aspect-ratio.md

@@ -0,0 +1,110 @@
+---
+sidebar_position: 6
+title: <AspectRatio />
+---
+
+# AspectRatio API
+
+<AvailableFrom version="0.5.0" />
+
+API reference docs for the React AspectRatio component.
+Learn about the props of this exported module.
+
+## Demos
+
+:::tip
+
+For examples and details on the usage of this React component, visit the component demo pages:
+
+- [AspectRatio](../components/aspect-ratio)
+
+:::
+
+## Import
+
+```tsx
+import { AspectRatio } from 'tailwind-joy/components';
+```
+
+## Props
+
+:::info
+
+The `ref` is forwarded to the root element.
+
+:::
+
+### `className`
+
+Class name applied to the root element.
+
+- Type: `string`
+
+### `color`
+
+The color of the component.
+
+- Type: `'primary' | 'neutral' | 'danger' | 'success' | 'warning'`
+- Default: `'neutral'`
+
+### `component`
+
+The component used for the root node.
+
+- Type: `keyof JSX.IntrinsicElements`
+- Default: `'div'`
+
+### `flex`
+
+By default, the AspectRatio will maintain the aspect ratio of its content.
+Set this prop to `true` when the container is a flex row and you want the AspectRatio to fill the height of its container.
+
+- Type: `boolean`
+- Default: `false`
+
+### `maxHeight`
+
+The maximum calculated height of the element (not the CSS height).
+
+- Type: `number | string`
+
+### `minHeight`
+
+The minimum calculated height of the element (not the CSS height).
+
+- Type: `number | string`
+
+### `objectFit`
+
+The CSS object-fit value of the first-child.
+
+- Type: `'-moz-initial' | 'contain' | 'cover' | 'fill' | 'inherit' | 'initial' | 'none' | 'revert-layer' | 'revert' | 'scale-down' | 'unset'`
+- Default: `'cover'`
+
+### `ratio`
+
+The aspect-ratio of the element.
+The current implementation uses padding instead of the CSS aspect-ratio.
+
+- Type: `number | string`
+- Default: `'16/9'`
+
+### `slotProps`
+
+The props used for each slot inside.
+
+- Type:
+  ```tsx
+  {
+    root?: ComponentProps<'div'>;
+    content?: ComponentProps<'div'>;
+  }
+  ```
+- Default: `{}`
+
+### `variant`
+
+The variant of the component.
+
+- Type: `'solid' | 'soft' | 'outlined' | 'plain'`
+- Default: `'soft'`