Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Popover): make theming popover.borderRadius actually change the radius (#5162)

Cindy Zhange1079ca567ce
diff --git a/.changeset/popover-radius-reaches-surface.md b/.changeset/popover-radius-reaches-surface.md
new file mode 100644
index 0000000000..d3e0965e23
--- /dev/null
+++ b/.changeset/popover-radius-reaches-surface.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Popover: theming `popover.borderRadius` now changes the rendered radius. The `astryx-popover` target moves onto the popup surface — the box that paints background, radius and elevation — and `usePopover` reads the registered `--_popover-radius` there instead of hardcoding `--radius-container`. Content padding moves with it, so a themed `padding` still replaces the default instead of nesting inside it.
+
+@cixzhang
diff --git a/.github/scripts/visual-gate/lib/probe-theme.mjs b/.github/scripts/visual-gate/lib/probe-theme.mjs
index c39a774d26..7ed597579c 100644
--- a/.github/scripts/visual-gate/lib/probe-theme.mjs
+++ b/.github/scripts/visual-gate/lib/probe-theme.mjs
@@ -70,6 +70,15 @@ export function unionValues(type, aliases = {}) {
return named && named.length > 1 ? named : [];
}
+/**
+ * Non-colour properties whose ownership must be visible in the probe capture.
+ * The colours prove that a target is reachable; these values prove that the
+ * target sits on the element that paints the documented property.
+ */
+const PROPERTY_PROBES = {
+ popover: {borderRadius: '32px'},
+};
+
/**
* Build the probe theme's `components` map.
*
@@ -89,12 +98,17 @@ export function buildProbeComponents(targets, propsByComponent, aliases = {}) {
const styles = (components[target.key] ??= {});
if (!styles.base) {
- styles.base = paint(`${target.key}`);
+ styles.base = {
+ ...paint(`${target.key}`),
+ ...(PROPERTY_PROBES[target.key] ?? {}),
+ };
selectors += 1;
}
for (const prop of target.props) {
- const declared = propsByComponent[target.component]?.find(entry => entry.name === prop);
+ const declared = propsByComponent[target.component]?.find(
+ entry => entry.name === prop,
+ );
const values = unionValues(declared?.type, aliases);
if (values.length === 0) {
skipped.push({
@@ -121,7 +135,10 @@ export function buildProbeComponents(targets, propsByComponent, aliases = {}) {
}
}
- return {components, coverage: {targets: Object.keys(components).length, selectors, skipped}};
+ return {
+ components,
+ coverage: {targets: Object.keys(components).length, selectors, skipped},
+ };
}
/**
diff --git a/.github/scripts/visual-gate/lib/probe-theme.test.mjs b/.github/scripts/visual-gate/lib/probe-theme.test.mjs
index 15fa8b68e7..1750cbc307 100644
--- a/.github/scripts/visual-gate/lib/probe-theme.test.mjs
+++ b/.github/scripts/visual-gate/lib/probe-theme.test.mjs
@@ -10,7 +10,10 @@ describe('unionValues', () => {
});
it('resolves a named alias, so a doc that says `size: AvatarSize` is still probed', () => {
- expect(unionValues('AvatarSize', {AvatarSize: ['sm', 'lg']})).toEqual(['sm', 'lg']);
+ expect(unionValues('AvatarSize', {AvatarSize: ['sm', 'lg']})).toEqual([
+ 'sm',
+ 'lg',
+ ]);
});
it('ignores a single-literal type — that is a constant, not a variant axis', () => {
@@ -29,7 +32,9 @@ describe('probeColor', () => {
});
it('gives different selectors different colours, so two targets that collapse into one element show it', () => {
- expect(probeColor('badge.base')).not.toBe(probeColor('badge.variant:error'));
+ expect(probeColor('badge.base')).not.toBe(
+ probeColor('badge.variant:error'),
+ );
});
it('honours a pinned lightness, so text stays readable against its own fill', () => {
@@ -40,7 +45,12 @@ describe('probeColor', () => {
describe('buildProbeComponents', () => {
const targets = [
{key: 'badge', component: 'Badge', props: ['variant'], states: []},
- {key: 'switch', component: 'Switch', props: [], states: ['checked', 'disabled']},
+ {
+ key: 'switch',
+ component: 'Switch',
+ props: [],
+ states: ['checked', 'disabled'],
+ },
];
const props = {Badge: [{name: 'variant', type: "'info' | 'error'"}]};
@@ -53,17 +63,35 @@ describe('buildProbeComponents', () => {
it('expands a variant prop into one selector per documented value', () => {
const {components} = buildProbeComponents(targets, props);
- expect(Object.keys(components.badge).sort()).toEqual(['base', 'variant:error', 'variant:info']);
+ expect(Object.keys(components.badge).sort()).toEqual([
+ 'base',
+ 'variant:error',
+ 'variant:info',
+ ]);
});
it('covers every declared state', () => {
const {components} = buildProbeComponents(targets, props);
- expect(Object.keys(components.switch).sort()).toEqual(['base', 'checked', 'disabled']);
+ expect(Object.keys(components.switch).sort()).toEqual([
+ 'base',
+ 'checked',
+ 'disabled',
+ ]);
});
it('paints text and background differently, so an invisible-text regression is still visible', () => {
const {components} = buildProbeComponents(targets, props);
- expect(components.badge.base.color).not.toBe(components.badge.base.backgroundColor);
+ expect(components.badge.base.color).not.toBe(
+ components.badge.base.backgroundColor,
+ );
+ });
+
+ it('gives Popover a radius probe so the painted surface ownership is visible', () => {
+ const {components} = buildProbeComponents(
+ [{key: 'popover', component: 'Popover', props: [], states: []}],
+ {},
+ );
+ expect(components.popover.base.borderRadius).toBe('32px');
});
it('reports a visual prop it cannot enumerate instead of dropping it silently', () => {
@@ -72,7 +100,11 @@ describe('buildProbeComponents', () => {
{Stack: []},
);
expect(coverage.skipped).toEqual([
- {key: 'stack', prop: 'gap', reason: expect.stringContaining('not a documented prop')},
+ {
+ key: 'stack',
+ prop: 'gap',
+ reason: expect.stringContaining('not a documented prop'),
+ },
]);
});
@@ -82,6 +114,8 @@ describe('buildProbeComponents', () => {
});
it('is deterministic — same docs, same theme, so regeneration is a no-op diff', () => {
- expect(buildProbeComponents(targets, props)).toEqual(buildProbeComponents(targets, props));
+ expect(buildProbeComponents(targets, props)).toEqual(
+ buildProbeComponents(targets, props),
+ );
});
});
diff --git a/apps/storybook/stories/ProbeTheme.stories.tsx b/apps/storybook/stories/ProbeTheme.stories.tsx
index 5547b0dc70..de32471d03 100644
--- a/apps/storybook/stories/ProbeTheme.stories.tsx
+++ b/apps/storybook/stories/ProbeTheme.stories.tsx
@@ -15,6 +15,7 @@ import type {Meta, StoryObj} from '@storybook/react';
import * as stylex from '@stylexjs/stylex';
import {Badge} from '@astryxdesign/core/Badge';
import {Button} from '@astryxdesign/core/Button';
+import {Popover} from '@astryxdesign/core/Popover';
import {Card} from '@astryxdesign/core/Card';
import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
import {CodeBlock} from '@astryxdesign/core/CodeBlock';
@@ -143,6 +144,16 @@ function ComponentSpecimen() {
<Badge label="Warning" variant="warning" />
<Badge label="Error" variant="error" />
</div>
+ <Popover
+ isOpen
+ hasAutoFocus={false}
+ hasCloseButton={false}
+ hasLightDismiss={false}
+ label="Popover radius probe"
+ width={240}
+ content={<Text type="body">Painted Popover surface</Text>}>
+ <Button label="Popover radius probe" />
+ </Popover>
</Stack>
);
}
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index 6c7d090be6..87c54719c1 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -136,7 +136,7 @@ export const docs = {
{className: 'astryx-popover-surface'},
],
vars: [
- {name: '--_popover-radius', description: 'Border radius of the popover', default: 'var(--radius-element)', private: true},
+ {name: '--_popover-radius', description: 'Border radius of the popover surface', default: 'var(--radius-container)', private: true},
],
derived: [
{property: 'borderRadius', vars: ['--_popover-radius']},
@@ -281,7 +281,7 @@ export const docsZh = {
{className: 'astryx-popover-surface'},
],
vars: [
- {name: '--_popover-radius', description: 'Border radius of the popover', default: 'var(--radius-element)', private: true},
+ {name: '--_popover-radius', description: 'Border radius of the popover surface', default: 'var(--radius-container)', private: true},
],
derived: [
{property: 'borderRadius', vars: ['--_popover-radius']},
diff --git a/packages/core/src/Popover/Popover.test.tsx b/packages/core/src/Popover/Popover.test.tsx
index 8a31f53769..4d86b654ef 100644
--- a/packages/core/src/Popover/Popover.test.tsx
+++ b/packages/core/src/Popover/Popover.test.tsx
@@ -500,4 +500,28 @@ describe('Popover', () => {
expect(trigger).toHaveFocus();
});
});
+
+ it('puts the theme target and styling escape hatches on the popup surface', () => {
+ render(
+ <Popover
+ isOpen
+ content={<span data-testid="content">Popover content</span>}
+ label="Test popover"
+ data-testid="popover"
+ className="consumer-popover"
+ style={{padding: 0}}>
+ <button type="button">Open</button>
+ </Popover>,
+ );
+
+ const target = document.querySelector('.astryx-popover');
+ expect(target).not.toBeNull();
+ // The surface paints background, radius and elevation; a target on the
+ // content box inside it would style a box that paints nothing.
+ expect(target).toHaveClass('astryx-popover-surface');
+ expect(target).toHaveClass('consumer-popover');
+ expect(target).toHaveStyle({padding: '0'});
+ expect(target).toContainElement(screen.getByTestId('content'));
+ expect(screen.getByTestId('popover')).not.toHaveClass('consumer-popover');
+ });
});
diff --git a/packages/core/src/Popover/Popover.tsx b/packages/core/src/Popover/Popover.tsx
index ba082561fd..9a760a7851 100644
--- a/packages/core/src/Popover/Popover.tsx
+++ b/packages/core/src/Popover/Popover.tsx
@@ -25,7 +25,6 @@ import React, {
} from 'react';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
-import {mergeProps} from '../utils';
import {devWarn} from '../utils/devWarning';
import type {BaseProps} from '../BaseProps';
import {usePopover} from './usePopover';
@@ -33,7 +32,6 @@ import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import {spacingVars} from '../theme/tokens.stylex';
import {InteractiveRoleContext} from '../InteractiveRoleContext/InteractiveRoleContext';
-import {themeProps} from '../utils/themeProps';
// =============================================================================
// Helpers
@@ -243,7 +241,8 @@ const styles = stylex.create({
anchorWrapper: {
display: 'inline-flex',
},
- // Visual styles for the inner content container
+ // Content padding, applied to the popup surface so a theme's `padding`
+ // replaces it instead of nesting inside it.
contentPadding: {
paddingBlockStart: spacingVars['--spacing-3'],
paddingBlockEnd: spacingVars['--spacing-3'],
@@ -340,6 +339,13 @@ export function Popover({
hasCloseButton,
closeButtonLabel,
hasAutoFocus,
+ // The surface is the box that paints background, radius and elevation, so
+ // it is the element the `popover` theme target has to sit on — a target on
+ // the content div inside it styles a box that paints nothing.
+ surfaceTarget: 'popover',
+ xstyle: [styles.contentPadding, xstyle],
+ className,
+ style,
onShow: handlePopoverShow,
onHide: handlePopoverHide,
});
@@ -503,24 +509,12 @@ export function Popover({
if (anchorRef && children == null) {
return (
<>
- {popover.render(
- <div
- data-testid={testId}
- {...mergeProps(
- themeProps('popover'),
- stylex.props(styles.contentPadding, xstyle),
- className,
- style,
- )}>
- {content}
- </div>,
- {
- placement,
- alignment,
- offset: spacingVars['--spacing-1'],
- xstyle: [popoverXstyle, layerAnimations[placement]],
- },
- )}
+ {popover.render(<div data-testid={testId}>{content}</div>, {
+ placement,
+ alignment,
+ offset: spacingVars['--spacing-1'],
+ xstyle: [popoverXstyle, layerAnimations[placement]],
+ })}
</>
);
}
@@ -540,24 +534,12 @@ export function Popover({
return (
<>
{children(triggerProps)}
- {popover.render(
- <div
- data-testid={testId}
- {...mergeProps(
- themeProps('popover'),
- stylex.props(styles.contentPadding, xstyle),
- className,
- style,
- )}>
- {content}
- </div>,
- {
- placement,
- alignment,
- offset: spacingVars['--spacing-1'],
- xstyle: [popoverXstyle, layerAnimations[placement]],
- },
- )}
+ {popover.render(<div data-testid={testId}>{content}</div>, {
+ placement,
+ alignment,
+ offset: spacingVars['--spacing-1'],
+ xstyle: [popoverXstyle, layerAnimations[placement]],
+ })}
</>
);
}
@@ -570,24 +552,12 @@ export function Popover({
{children}
</div>
</InteractiveRoleContext>
- {popover.render(
- <div
- data-testid={testId}
- {...mergeProps(
- themeProps('popover'),
- stylex.props(styles.contentPadding, xstyle),
- className,
- style,
- )}>
- {content}
- </div>,
- {
- placement,
- alignment,
- offset: spacingVars['--spacing-1'],
- xstyle: [popoverXstyle, layerAnimations[placement]],
- },
- )}
+ {popover.render(<div data-testid={testId}>{content}</div>, {
+ placement,
+ alignment,
+ offset: spacingVars['--spacing-1'],
+ xstyle: [popoverXstyle, layerAnimations[placement]],
+ })}
</>
);
}
diff --git a/packages/core/src/Popover/usePopover.tsx b/packages/core/src/Popover/usePopover.tsx
index d332a1c3f5..6aaae1941e 100644
--- a/packages/core/src/Popover/usePopover.tsx
+++ b/packages/core/src/Popover/usePopover.tsx
@@ -41,7 +41,8 @@ const styles = stylex.create({
// Consumers that need a raw positioned layer should use useLayer instead.
surface: {
backgroundColor: colorVars['--color-background-popover'],
- borderRadius: radiusVars['--radius-container'],
+ '--_popover-radius': radiusVars['--radius-container'],
+ borderRadius: 'var(--_popover-radius)',
boxShadow: shadowVars['--shadow-low'],
},
// Focus trap container
@@ -111,6 +112,16 @@ export interface UsePopoverOptions {
*/
xstyle?: StyleXStyles;
+ /**
+ * Additional class name applied to the painted popover surface.
+ */
+ className?: string;
+
+ /**
+ * Inline styles applied to the painted popover surface.
+ */
+ style?: React.CSSProperties;
+
/**
* Whether clicking outside should dismiss the popover.
* @default true
@@ -334,6 +345,8 @@ function usePopoverImplementation(
onShow,
onHide,
xstyle,
+ className,
+ style,
hasLightDismiss = true,
hasEscapeDismiss = true,
hasAutoFocus = true,
@@ -459,6 +472,8 @@ function usePopoverImplementation(
hasSurface && styles.surface,
xstyle,
),
+ className,
+ style,
)}>
{children}
{hasCloseButton && (
@@ -484,6 +499,8 @@ function usePopoverImplementation(
hasCloseButton,
hasSurface,
surfaceTarget,
+ className,
+ style,
closeButtonLabel,
contentRef,
dialogLabel,
diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.ts
index 1bbe9681a2..ab3d06fe5e 100644
--- a/packages/core/src/theme/derivedVarRegistry.test.ts
+++ b/packages/core/src/theme/derivedVarRegistry.test.ts
@@ -464,3 +464,51 @@ describe('getDerivedVars', () => {
}
});
});
+
+// ---------------------------------------------------------------------------
+// Read check: a registered var nothing reads is a dead theming knob
+// ---------------------------------------------------------------------------
+
+/**
+ * Every source file under packages/core/src, concatenated once.
+ *
+ * `--_popover-radius` shipped documented and registered while `usePopover`
+ * hardcoded its radius, so `popover: {borderRadius}` set a var no element ever
+ * read. Sync between source, docs and registry cannot catch that: the three
+ * agreed with each other, and none of them required a reader.
+ */
+function readAllSource(dir: string): string {
+ let out = '';
+ for (const entry of readdirSync(dir, {withFileTypes: true})) {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ out += readAllSource(path);
+ } else if (
+ (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx')) &&
+ !entry.name.includes('.test.') &&
+ !entry.name.endsWith('.d.ts')
+ ) {
+ out += readFileSync(path, 'utf-8');
+ }
+ }
+ return out;
+}
+
+describe('registered derived vars are read by component styles', () => {
+ const source = readAllSource(SRC_DIR);
+
+ for (const [component, entries] of Object.entries(derivedVarRegistry)) {
+ for (const varName of entries.flatMap(e => e.vars ?? [])) {
+ it(`${component}: ${varName} is read via var()`, () => {
+ expect(
+ source.includes(`var(${varName})`) ||
+ source.includes(`var(${varName},`),
+ `${varName} is registered as the derived var for a CSS property on ` +
+ `\`${component}\`, but no component reads it. A theme setting that ` +
+ `property would write a var nothing consumes. Read it in the ` +
+ `element's StyleX styles, or drop the derived entry.`,
+ ).toBe(true);
+ });
+ }
+ }
+});
diff --git a/packages/themes/probe/src/probeTheme.ts b/packages/themes/probe/src/probeTheme.ts
index f3fdaa9090..7b13ef022d 100644
--- a/packages/themes/probe/src/probeTheme.ts
+++ b/packages/themes/probe/src/probeTheme.ts
@@ -6,7 +6,7 @@
// test fixture. Regenerate with: pnpm visual:probe-theme
//
// defineTheme takes six things and this covers all six:
-// components 268 targets, 865 selectors (generated from the docs)
+// components 270 targets, 875 selectors (generated from the docs)
// tokens custom properties, read back off the themed element
// icons every registry entry swapped for a marked glyph
// indicators check / radio / checkbox swapped — the swap that reaches furthest
@@ -751,6 +751,30 @@ export const probeTheme = defineTheme({
borderColor: 'hsl(165.5 85% 25%)',
outlineColor: 'hsl(95.4 85% 25%)',
},
+ 'elevation:none': {
+ backgroundColor: 'hsl(183.6 78% 61%)',
+ color: 'hsl(321.2 75% 12%)',
+ borderColor: 'hsl(237.3 75% 25%)',
+ outlineColor: 'hsl(349.9 78% 25%)',
+ },
+ 'elevation:low': {
+ backgroundColor: 'hsl(9.2 89% 58%)',
+ color: 'hsl(179.3 77% 12%)',
+ borderColor: 'hsl(153.4 84% 25%)',
+ outlineColor: 'hsl(275.8 88% 25%)',
+ },
+ 'elevation:med': {
+ backgroundColor: 'hsl(224.1 86% 58%)',
+ color: 'hsl(274.7 91% 12%)',
+ borderColor: 'hsl(93.4 78% 25%)',
+ outlineColor: 'hsl(336.8 88% 25%)',
+ },
+ 'elevation:high': {
+ backgroundColor: 'hsl(120.8 81% 58%)',
+ color: 'hsl(263.8 84% 12%)',
+ borderColor: 'hsl(89.5 88% 25%)',
+ outlineColor: 'hsl(270.6 77% 25%)',
+ },
},
'button-group': {
base: {
@@ -917,6 +941,30 @@ export const probeTheme = defineTheme({
borderColor: 'hsl(101.8 74% 25%)',
outlineColor: 'hsl(86.2 75% 25%)',
},
+ 'elevation:none': {
+ backgroundColor: 'hsl(115.9 71% 47%)',
+ color: 'hsl(344.1 76% 12%)',
+ borderColor: 'hsl(180.4 81% 25%)',
+ outlineColor: 'hsl(143.0 88% 25%)',
+ },
+ 'elevation:low': {
+ backgroundColor: 'hsl(143.0 86% 61%)',
+ color: 'hsl(176.0 70% 12%)',
+ borderColor: 'hsl(325.6 92% 25%)',
+ outlineColor: 'hsl(204.8 77% 25%)',
+ },
+ 'elevation:med': {
+ backgroundColor: 'hsl(288.0 88% 61%)',
+ color: 'hsl(270.0 72% 12%)',
+ borderColor: 'hsl(326.0 92% 25%)',
+ outlineColor: 'hsl(143.9 76% 25%)',
+ },
+ 'elevation:high': {
+ backgroundColor: 'hsl(178.7 92% 50%)',
+ color: 'hsl(209.1 94% 12%)',
+ borderColor: 'hsl(328.2 94% 25%)',
+ outlineColor: 'hsl(117.5 91% 25%)',
+ },
},
carousel: {
base: {
@@ -3370,6 +3418,7 @@ export const probeTheme = defineTheme({
color: 'hsl(119.2 86% 12%)',
borderColor: 'hsl(133.6 85% 25%)',
outlineColor: 'hsl(1.2 82% 25%)',
+ borderRadius: '32px',
},
},
'popover-surface': {
@@ -4980,6 +5029,22 @@ export const probeTheme = defineTheme({
outlineColor: 'hsl(137.9 93% 25%)',
},
},
+ 'text-area-control': {
+ base: {
+ backgroundColor: 'hsl(146.4 82% 50%)',
+ color: 'hsl(192.4 83% 12%)',
+ borderColor: 'hsl(21.0 81% 25%)',
+ outlineColor: 'hsl(45.7 87% 25%)',
+ },
+ },
+ 'text-area-counter': {
+ base: {
+ backgroundColor: 'hsl(29.0 93% 46%)',
+ color: 'hsl(345.2 87% 12%)',
+ borderColor: 'hsl(130.6 70% 25%)',
+ outlineColor: 'hsl(75.8 90% 25%)',
+ },
+ },
'text-input': {
base: {
backgroundColor: 'hsl(73.7 86% 45%)',