An open source design system that's fully customizable and agent ready
TypeScript
feat(AspectRatio): add isCircle prop for circular containers (#2632)
Kenton Quatman254d52c1acad
diff --git a/apps/storybook/stories/AspectRatio.stories.tsx b/apps/storybook/stories/AspectRatio.stories.tsxindex a6260a72e3..ac3a6d63db 100644--- a/apps/storybook/stories/AspectRatio.stories.tsx+++ b/apps/storybook/stories/AspectRatio.stories.tsx@@ -75,6 +75,12 @@ const meta: Meta<typeof XDSAspectRatio> = {control: 'number',description: 'The aspect ratio as width/height (e.g., 16/9 = 1.777...)',},+ shape: {+ control: 'select',+ options: ['rectangle', 'ellipse'],+ description:+ 'Container shape. Both respect the ratio; "ellipse" clips to an oval (circle at 1:1).',+ },},};@@ -171,6 +177,48 @@ export const Ultrawide21x9: Story = {),};+export const EllipseCircle: Story = {+ args: {+ ratio: 1,+ shape: 'ellipse',+ },+ render: args => (+ <div {...stylex.props(styles.smallContainer)}>+ <XDSText type="supporting" xstyle={styles.sectionLabel}>+ Ellipse at 1:1 — a circle (avatars, profile images)+ </XDSText>+ <XDSAspectRatio {...args}>+ <img+ {...stylex.props(styles.image)}+ src={PLACEHOLDER_SQUARE}+ alt="Circular media"+ />+ </XDSAspectRatio>+ </div>+ ),+};++export const EllipseOval: Story = {+ args: {+ ratio: 16 / 9,+ shape: 'ellipse',+ },+ render: args => (+ <div {...stylex.props(styles.container)}>+ <XDSText type="supporting" xstyle={styles.sectionLabel}>+ Ellipse at 16:9 — an oval (respects the ratio)+ </XDSText>+ <XDSAspectRatio {...args}>+ <img+ {...stylex.props(styles.image)}+ src={PLACEHOLDER_IMAGE}+ alt="Oval media"+ />+ </XDSAspectRatio>+ </div>+ ),+};+export const WithPlaceholderSkeleton: Story = {render: () => (<div {...stylex.props(styles.storyWrapper)}>diff --git a/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.doc.mjs b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.doc.mjsnew file mode 100644index 0000000000..7e5aec73b1--- /dev/null+++ b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.doc.mjs@@ -0,0 +1,13 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'AspectRatio',+ name: 'AspectRatio — Circle Image',+ displayName: 'AspectRatio — Circle Image',+ description: 'Circular container via shape="ellipse" with ratio={1}, ideal for avatars and profile images.',+ isReady: true,+ aspectRatio: 1,+ componentsUsed: ['AspectRatio', 'Center'],+};diff --git a/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.tsx b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.tsxnew file mode 100644index 0000000000..5337ed276d--- /dev/null+++ b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.tsx@@ -0,0 +1,24 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {XDSAspectRatio} from '@xds/core/AspectRatio';+import {XDSCenter} from '@xds/core/Center';++export default function AspectRatioCircleImage() {+ return (+ <XDSCenter width={300}>+ <XDSAspectRatio ratio={1} shape="ellipse">+ <img+ src="https://lookaside.facebook.com/assets/xds_oss/light-home-square-1.png"+ alt="Circular image"+ style={{+ width: '100%',+ height: '100%',+ objectFit: 'cover',+ }}+ />+ </XDSAspectRatio>+ </XDSCenter>+ );+}diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjsindex b1efe62e48..6bc2c22c5e 100644--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs@@ -13,6 +13,7 @@ export const docs = {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 `shape="ellipse"` for circular/oval media like avatars; combine with `ratio={1}` for a perfect circle.'},{guidance: false, description: 'Use for general layout containers — use standard layout components instead.'},{guidance: false, description: 'Nest AspectRatio containers — one level is sufficient.'},],@@ -24,6 +25,12 @@ export const docs = {description: 'Aspect ratio as width/height (e.g. 16/9, 1).',required: true,},+ {+ name: 'shape',+ type: "'rectangle' | 'ellipse'",+ description: 'Container shape. Both respect the `ratio`. `ellipse` clips to an oval (a circle when `ratio={1}`).',+ default: "'rectangle'",+ },{name: 'children',type: 'ReactNode',@@ -40,12 +47,29 @@ export const docs = {playground: {defaults: {ratio: 16 / 9,- children: {__element: 'XDSCenter', props: {height: '100%'}, children: {__element: 'XDSText', props: {color: 'secondary'}, children: '16:9'}},+ shape: 'rectangle',+ // Fixed height + auto width lets the CSS `aspect-ratio` drive the box+ // width as the ratio knob changes (the component's base width is 100%,+ // which is why the preview was full-width regardless of the ratio).+ style: {+ height: 300,+ width: 'auto',+ backgroundColor: 'var(--color-background-blue)',+ },+ children: {+ __element: 'XDSCenter',+ props: {height: '100%'},+ children: {+ __element: 'XDSText',+ props: {color: 'primary'},+ children: 'Aspect Ratio',+ },+ },},},theming: {targets: [- {className: 'xds-aspect-ratio'},+ {className: 'xds-aspect-ratio', visualProps: ['shape']},],},};@@ -60,12 +84,14 @@ export const docsZh = {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 `shape="ellipse"` for circular/oval media like avatars; combine with `ratio={1}` for a perfect circle.'},{guidance: false, description: 'Use for general layout containers — use standard layout components instead.'},{guidance: false, description: 'Nest AspectRatio containers — one level is sufficient.'},],},props: [{name: 'ratio', type: 'number', description: '宽高比,以宽/高表示(例如 16/9、1)。', required: true},+ {name: 'shape', type: "'rectangle' | 'ellipse'", description: '容器形状,二者均遵循 `ratio`。`ellipse` 裁剪为椭圆(当 `ratio={1}` 时为圆形)。', default: "'rectangle'"},{name: 'children', type: 'ReactNode', description: '通过绝对定位填充容器的内容。', required: true},{name: 'xstyle',@@ -76,7 +102,7 @@ export const docsZh = {],theming: {targets: [- {className: 'xds-aspect-ratio'},+ {className: 'xds-aspect-ratio', visualProps: ['shape']},],},};@@ -90,12 +116,14 @@ export const docsDense = {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 `shape="ellipse"` for circular/oval media like avatars; combine with `ratio={1}` for a perfect circle.'},{guidance: false, description: 'Use for general layout containers — use standard layout components instead.'},{guidance: false, description: 'Nest AspectRatio containers — one level is sufficient.'},],},propDescriptions: {ratio: 'width/height ratio (e.g. 16/9, 1)',+ shape: "container shape: 'rectangle' (default) or 'ellipse'; both respect ratio",children: 'content positioned absolutely to fill container',xstyle: 'StyleX layout customization via stylex.create()',},diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.test.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.test.tsxindex 3574fc567b..6c6a905aa4 100644--- a/packages/core/src/AspectRatio/XDSAspectRatio.test.tsx+++ b/packages/core/src/AspectRatio/XDSAspectRatio.test.tsx@@ -82,6 +82,42 @@ describe('XDSAspectRatio', () => {expect(element.style.aspectRatio).toBe(String(ratio));});+ it('renders an ellipse that respects the ratio (circle at 1:1)', () => {+ render(+ <XDSAspectRatio ratio={1} shape="ellipse" data-testid="aspect-ratio">+ <div>Circle</div>+ </XDSAspectRatio>,+ );+ const element = screen.getByTestId('aspect-ratio');+ expect(element.style.aspectRatio).toBe('1');+ expect(element.className).toContain('ellipse');+ });++ it('ellipse respects a non-square ratio (oval)', () => {+ render(+ <XDSAspectRatio ratio={16 / 9} shape="ellipse" data-testid="aspect-ratio">+ <div>Oval</div>+ </XDSAspectRatio>,+ );+ const element = screen.getByTestId('aspect-ratio');+ // Ratio is preserved — the ellipse does not force 1:1.+ expect(element.style.aspectRatio).toBe(String(16 / 9));+ expect(element.className).toContain('ellipse');+ });++ it('defaults to the rectangle shape', () => {+ render(+ <XDSAspectRatio ratio={1} data-testid="aspect-ratio">+ <div>Rectangle by default</div>+ </XDSAspectRatio>,+ );+ const element = screen.getByTestId('aspect-ratio');+ expect(element.style.aspectRatio).toBe('1');+ expect(element.className).toContain('rectangle');+ // No ellipse border-radius when shape is the default rectangle+ expect(element.style.borderRadius).toBe('');+ });+it('forwards ref correctly', () => {const ref = vi.fn();render(diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.tsxindex aafd8f1fcd..3d88ab0031 100644--- a/packages/core/src/AspectRatio/XDSAspectRatio.tsx+++ b/packages/core/src/AspectRatio/XDSAspectRatio.tsx@@ -20,6 +20,14 @@ import * as stylex from '@stylexjs/stylex';import type {XDSBaseProps} from '../XDSBaseProps';import {xdsClassName, mergeProps} from '../utils';+/**+ * The shape of the aspect ratio container.+ * - `rectangle`: standard rectangular container (default).+ * - `ellipse`: clips the container to an ellipse. Combined with the `ratio`,+ * this renders a circle at `ratio={1}` and an oval at non-square ratios.+ */+export type XDSAspectRatioShape = 'rectangle' | 'ellipse';+export interface XDSAspectRatioProps extends XDSBaseProps<HTMLDivElement> {/** Ref forwarded to the root element */ref?: React.Ref<HTMLDivElement>;@@ -28,6 +36,24 @@ export interface XDSAspectRatioProps extends XDSBaseProps<HTMLDivElement> {*/ratio: number;+ /**+ * The shape of the container. Both shapes respect the provided `ratio`.+ * - `rectangle` (default): a standard rectangular container.+ * - `ellipse`: clips the container to an ellipse — a circle when `ratio={1}`,+ * or an oval at other ratios. Pair with a child that fills the container+ * (e.g. an image with `objectFit: 'cover'`).+ *+ * @default 'rectangle'+ *+ * @example+ * ```+ * <XDSAspectRatio ratio={1} shape="ellipse">+ * <img src="avatar.jpg" alt="" style={{objectFit: 'cover'}} />+ * </XDSAspectRatio>+ * ```+ */+ shape?: XDSAspectRatioShape;+/*** Content to render inside the aspect ratio container.* The child element will be positioned absolutely to fill the container.@@ -43,6 +69,11 @@ const styles = stylex.create({minHeight: 0,flexShrink: 0,},+ ellipse: {+ // 50% on both axes follows the box dimensions, so the clip respects the+ // ratio: a circle at 1:1 and an oval at non-square ratios.+ borderRadius: '50%',+ },child: {position: 'absolute',top: 0,@@ -59,15 +90,27 @@ const styles = stylex.create({* is positioned absolutely to fill the container, which is useful for images,* videos, embeds, and placeholders.*+ * Use `shape="ellipse"` to clip the container into an ellipse — a circle at+ * `ratio={1}` or an oval at other ratios. Both shapes respect the provided+ * `ratio`.+ ** @example* ```* <XDSAspectRatio ratio={16 / 9}>* <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />* </XDSAspectRatio>* ```+ *+ * @example+ * ```+ * <XDSAspectRatio ratio={1} shape="ellipse">+ * <img src="avatar.jpg" alt="" style={{objectFit: 'cover'}} />+ * </XDSAspectRatio>+ * ```*/export function XDSAspectRatio({ratio,+ shape = 'rectangle',children,xstyle,className,@@ -79,8 +122,12 @@ export function XDSAspectRatio({<divref={ref}{...mergeProps(- xdsClassName('aspect-ratio'),- stylex.props(styles.container, xstyle),+ xdsClassName('aspect-ratio', {shape}),+ stylex.props(+ styles.container,+ shape === 'ellipse' && styles.ellipse,+ xstyle,+ ),className,{...style, aspectRatio: ratio},)}diff --git a/packages/core/src/AspectRatio/index.ts b/packages/core/src/AspectRatio/index.tsindex ed0303d9a4..a273fc96e7 100644--- a/packages/core/src/AspectRatio/index.ts+++ b/packages/core/src/AspectRatio/index.ts@@ -12,4 +12,4 @@*/export {XDSAspectRatio} from './XDSAspectRatio';-export type {XDSAspectRatioProps} from './XDSAspectRatio';+export type {XDSAspectRatioProps, XDSAspectRatioShape} from './XDSAspectRatio';