An open source design system that's fully customizable and agent ready
TypeScript
docs(core): document AspectRatio's sizing contract and add its anatomy (#4984)
Cindy Zhang079588550a41
diff --git a/.changeset/aspectratio-sizing-contract-docs.md b/.changeset/aspectratio-sizing-contract-docs.mdnew file mode 100644index 0000000000..4ef22dbd1f--- /dev/null+++ b/.changeset/aspectratio-sizing-contract-docs.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[docs] AspectRatio: document the sizing contract and add the missing anatomy. The box takes its width from its container and derives its height from the ratio, so constraining only the height clamps it off ratio (pass `width: 'auto'` alongside) and a shrink-to-fit parent collapses it to zero width. Both are now in the component JSDoc and in `bestPractices`, along with the single-child expectation: with `fit` set, every direct child is stretched to fill the box. The image-gallery example block now uses `var(--radius-element)` instead of a raw `8`.++@cixzhangdiff --git a/apps/storybook/stories/AspectRatio.stories.tsx b/apps/storybook/stories/AspectRatio.stories.tsxindex 21c4b7d6b4..d8362bfdfc 100644--- a/apps/storybook/stories/AspectRatio.stories.tsx+++ b/apps/storybook/stories/AspectRatio.stories.tsx@@ -4,6 +4,7 @@ import type {Meta, StoryObj} from '@storybook/react';import * as stylex from '@stylexjs/stylex';import {AspectRatio} from '@astryxdesign/core/AspectRatio';import {Grid} from '@astryxdesign/core/Grid';+import {HStack} from '@astryxdesign/core/Layout';import {Text} from '@astryxdesign/core/Text';import {Skeleton} from '@astryxdesign/core/Skeleton';import {@@ -45,16 +46,6 @@ const styles = stylex.create({alignItems: 'center',justifyContent: 'center',},- gradientPlaceholder: {- width: '100%',- height: '100%',- background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',- borderRadius: radiusVars['--radius-element'],- display: 'flex',- alignItems: 'center',- justifyContent: 'center',- color: 'white',- },gridItem: {overflow: 'hidden',},@@ -63,6 +54,24 @@ const styles = stylex.create({padding: spacingVars['--spacing-4'],backgroundColor: colorVars['--color-background-surface'],},+ narrowContainer: {+ maxWidth: 240,+ padding: spacingVars['--spacing-4'],+ backgroundColor: colorVars['--color-background-surface'],+ },+ // Sizing from the height rather than the container: release the width so+ // the ratio drives it. A height constraint on its own clamps the box and+ // the rendered ratio stops matching `ratio`.+ heightDriven: {+ height: 120,+ width: 'auto',+ },+ emptyChild: {+ width: '100%',+ height: '100%',+ backgroundColor: colorVars['--color-background-muted'],+ borderRadius: radiusVars['--radius-element'],+ },});const meta: Meta<typeof AspectRatio> = {@@ -175,7 +184,7 @@ export const Ultrawide21x9: Story = {21:9 - Ultrawide cinematic</Text><AspectRatio ratio={21 / 9}>- <div {...stylex.props(styles.gradientPlaceholder)}>+ <div {...stylex.props(styles.placeholder)}><Text type="label">Ultrawide 21:9</Text></div></AspectRatio>@@ -398,3 +407,81 @@ export const ImageGallery: Story = {</div>),};++export const HeightDriven: Story = {+ render: () => (+ <div {...stylex.props(styles.wideContainer)}>+ <Text type="supporting" xstyle={styles.sectionLabel}>+ Sized from a fixed height. The box takes its width from the container by+ default, so a height constraint needs `width: auto` beside it for the+ ratio to drive the width.+ </Text>+ <HStack gap={4} vAlign="start" wrap="wrap">+ {[+ {ratio: 1, label: '1:1'},+ {ratio: 4 / 3, label: '4:3'},+ {ratio: 16 / 9, label: '16:9'},+ ].map(({ratio, label}) => (+ <AspectRatio+ key={label}+ ratio={ratio}+ fit="cover"+ xstyle={styles.heightDriven}>+ <img+ {...stylex.props(styles.image)}+ src={PLACEHOLDER_IMAGE}+ alt={`${label} at a fixed height`}+ />+ </AspectRatio>+ ))}+ </HStack>+ </div>+ ),+};++export const NarrowContainer: Story = {+ render: () => (+ <div {...stylex.props(styles.narrowContainer)}>+ <Text type="supporting" xstyle={styles.sectionLabel}>+ 240px container+ </Text>+ <AspectRatio ratio={16 / 9} fit="cover">+ <img+ {...stylex.props(styles.image)}+ src={PLACEHOLDER_IMAGE}+ alt="16:9 in a narrow container"+ />+ </AspectRatio>+ </div>+ ),+};++export const EmptyAndLongContent: Story = {+ render: () => (+ <div {...stylex.props(styles.storyWrapper)}>+ <div {...stylex.props(styles.container)}>+ <Text type="supporting" xstyle={styles.sectionLabel}>+ Empty: no media, the box still holds its ratio+ </Text>+ <AspectRatio ratio={16 / 9}>+ <div {...stylex.props(styles.emptyChild)} />+ </AspectRatio>+ </div>+ <div {...stylex.props(styles.container)}>+ <Text type="supporting" xstyle={styles.sectionLabel}>+ Long content: the box clips rather than growing+ </Text>+ <AspectRatio ratio={16 / 9} fit="contain">+ <div {...stylex.props(styles.placeholder)}>+ <Text type="body">+ A caption long enough to run past the bottom edge of a 16:9 box,+ repeated so it cannot fit: the ratio is the contract and the+ container clips what does not fit inside it, rather than growing+ to accommodate the text and breaking the ratio it promised.+ </Text>+ </div>+ </AspectRatio>+ </div>+ </div>+ ),+};diff --git a/packages/cli/assets/templates/blocks/components/AspectRatio/AspectRatioImageGallery.tsx b/packages/cli/assets/templates/blocks/components/AspectRatio/AspectRatioImageGallery.tsxindex 3ea3206116..2f5b687e5e 100644--- a/packages/cli/assets/templates/blocks/components/AspectRatio/AspectRatioImageGallery.tsx+++ b/packages/cli/assets/templates/blocks/components/AspectRatio/AspectRatioImageGallery.tsx@@ -29,7 +29,7 @@ export default function AspectRatioImageGallery() {<imgsrc="/template-assets/illustrative-horizontal-1.png"alt={alt}- style={{borderRadius: 8}}+ style={{borderRadius: 'var(--radius-element)'}}/></AspectRatio>))}diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjsindex 0f10d6f53e..f22fc8739e 100644--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs@@ -9,13 +9,21 @@ export const docs = {keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],usage: {description:- 'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',+ 'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',bestPractices: [{guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},{guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},{guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},+ {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},+ {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},{guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},{guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},+ {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},+ {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},+ ],+ anatomy: [+ {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},+ {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},],},props: [@@ -68,13 +76,21 @@ export const docsZh = {displayName: 'Aspect Ratio',usage: {description:- 'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',+ 'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',bestPractices: [{guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},{guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},{guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},+ {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},+ {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},{guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},{guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},+ {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},+ {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},+ ],+ anatomy: [+ {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},+ {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},],},props: [@@ -110,13 +126,21 @@ export const docsDense = {description: 'maintains specific aspect ratio for children',usage: {description:- 'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',+ 'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',bestPractices: [{guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},{guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},{guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},+ {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},+ {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},{guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},{guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},+ {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},+ {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},+ ],+ anatomy: [+ {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},+ {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},],},propDescriptions: {diff --git a/packages/core/src/AspectRatio/AspectRatio.test.tsx b/packages/core/src/AspectRatio/AspectRatio.test.tsxindex 9605fb63a5..a791644405 100644--- a/packages/core/src/AspectRatio/AspectRatio.test.tsx+++ b/packages/core/src/AspectRatio/AspectRatio.test.tsx@@ -276,6 +276,36 @@ describe('AspectRatio', () => {});});+ describe('style merging', () => {+ it('keeps the consumer style and applies the ratio over it', () => {+ render(+ <AspectRatio+ ratio={16 / 9}+ data-testid="aspect-ratio"+ style={{opacity: 0.5, aspectRatio: '3 / 1'}}>+ <div>Content</div>+ </AspectRatio>,+ );+ const element = screen.getByTestId('aspect-ratio');+ expect(element.style.opacity).toBe('0.5');+ expect(element.style.aspectRatio).toBe(String(16 / 9));+ });++ it('keeps a consumer className beside the theme target', () => {+ render(+ <AspectRatio+ ratio={1}+ data-testid="aspect-ratio"+ className="consumer-class">+ <div>Content</div>+ </AspectRatio>,+ );+ const element = screen.getByTestId('aspect-ratio');+ expect(element).toHaveClass('consumer-class');+ expect(element).toHaveClass('astryx-aspect-ratio');+ });+ });+describe('reset.css fit baseline rules', () => {// The cover/contain child sizing ships as zero-specificity baseline// rules in reset.css keyed on the data-astryx-aspect-ratio-overridediff --git a/packages/core/src/AspectRatio/AspectRatio.tsx b/packages/core/src/AspectRatio/AspectRatio.tsxindex b0239238fb..cb7af17270 100644--- a/packages/core/src/AspectRatio/AspectRatio.tsx+++ b/packages/core/src/AspectRatio/AspectRatio.tsx@@ -94,6 +94,10 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {/*** Content to render inside the aspect ratio container.* The child element will be positioned absolutely to fill the container.+ *+ * Pass a single child. With `fit` set, every direct child is stretched to+ * fill the box, so a second child is laid out below the first and clipped+ * out of view; compose an overlay or caption inside one wrapper child.*/children: ReactNode;}@@ -145,6 +149,15 @@ const styles = stylex.create({* `ratio={1}` or an oval at other ratios. Both shapes respect the provided* `ratio`.*+ * Sizing: the box takes its width from its container and derives its height+ * from the ratio, so it needs an ancestor with a definite width. Two+ * consequences are worth knowing. Constraining only the height (`height` or+ * `maxHeight`) clamps the box without releasing the width, so the rendered+ * ratio no longer matches `ratio`; pass `width: 'auto'` alongside to size from+ * the height instead. And in a shrink-to-fit parent (`inline-flex`,+ * `width: fit-content`, a floated box) it contributes no intrinsic width and+ * collapses to zero.+ ** @example* ```* <AspectRatio ratio={16 / 9} fit="cover">