Skip to content

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

TypeScript

feat(popover): padding prop on Popover and usePopover (#6683)

Christopher Chedeaued2e54e560d7
diff --git a/.changeset/popover-surface-padding.md b/.changeset/popover-surface-padding.md
new file mode 100644
index 0000000000..d5eda847fb
--- /dev/null
+++ b/.changeset/popover-surface-padding.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Popover and usePopover take a `padding` prop on the spacing scale (matching Card and Stack). `padding={0}` paints a flush surface for content that owns its own edges, such as a list of rows or a header with a rule; the default rung (3) is unchanged.
+
+@vjeux
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index 6d00229ee5..846f528782 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -89,6 +89,13 @@ export const docs = {
'Width of the popover container. The layer still caps to the viewport with alignment-aware safe-area gutters before scrolling long content.',
default: "'auto'",
},
+ {
+ name: 'padding',
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+ description:
+ 'Inner padding of the popover surface on the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10), matching the padding prop on Card and Stack. Pass 0 for a flush surface when the content owns its own edges, such as a list of rows or a header with a rule, and pad the content itself. The padding sits on the painted popover target, so a theme padding on that target replaces it.',
+ default: '3',
+ },
{
name: 'label',
type: 'string',
@@ -151,6 +158,31 @@ export const docs = {
],
},
],
+ examples: [
+ {
+ label: 'Flush surface for a list of rows',
+ code: `<Popover
+ label="Recent files"
+ padding={0}
+ content={
+ <List>
+ <ListItem label="Quarterly report.pdf" />
+ <ListItem label="Roadmap.key" />
+ </List>
+ }>
+ <Button label="Recent" variant="secondary" />
+</Popover>`,
+ },
+ {
+ label: 'Roomier surface for a form',
+ code: `<Popover
+ label="Save search"
+ padding={4}
+ content={<SaveSearchForm />}>
+ <Button label="Save search" variant="secondary" />
+</Popover>`,
+ },
+ ],
playground: {
defaults: {
content: {
@@ -312,6 +344,13 @@ export const docsZh = {
'弹出框容器的宽度。弹出层仍会限制在视口和安全区域留白内,长内容再滚动。',
default: "'auto'",
},
+ {
+ name: 'padding',
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+ description:
+ '弹出框表面的内边距,使用间距刻度(0、0.5、1、1.5、2、3、4、5、6、8、10),与 Card 和 Stack 的 padding 属性一致。当内容自行管理边缘(如行列表或带分隔线的标题)时传入 0 使表面无内边距,并由内容自行设置内边距。',
+ default: '3',
+ },
{
name: 'label',
type: 'string',
diff --git a/packages/core/src/Popover/Popover.spec.md b/packages/core/src/Popover/Popover.spec.md
index f8797bc897..799c11613a 100644
--- a/packages/core/src/Popover/Popover.spec.md
+++ b/packages/core/src/Popover/Popover.spec.md
@@ -51,6 +51,9 @@ remain unchanged. Consumer syntax and complete signatures remain owned by
`Popover.doc.mjs` and `usePopover.doc.mjs`. The canonical `popover` target and
the deprecated `popover-surface` compatibility alias remain supported together.
+DEC-4 below (pending owner review) adds one public concept: the surface padding
+rung, so a caller whose content owns its own edges can ask for a flush surface.
+
## Compatibility and migration
- Released default preserved: `yes`
@@ -114,16 +117,17 @@ surface, not the Layer entry point. There is no installable
## Public concepts
-| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid or unsupported behavior |
-| ------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Trigger composition | Wrapped trigger, render-prop trigger, or referenced anchor | Supplies the anchor and the control that opens or closes the standard component | Popover | Wrapped trigger when children are supplied | `component:Popover` | Current public behavior | A referenced or wrapped anchor without a button or button role warns in development and receives no trigger handler; it does not throw. |
-| Visibility ownership | Uncontrolled or externally controlled | Chooses whether Popover stores visibility or synchronizes to caller state | Popover | Uncontrolled | `component:Popover` | Current public behavior | Controlled changes are synchronized through show/hide; dismissal requests are reported to the caller rather than redefining the external source of truth. |
-| Popup semantics | Dialog or neutral wrapper | Exposes dialog semantics or lets child menu/listbox semantics own the popup | Popover and hook | Dialog | `component:Popover` | Current public behavior | A dialog without a label warns in development. Neutral mode omits dialog role and modal semantics. |
-| Focus entry | Automatic or caller-preserved | Focuses genuine caller content, falls back to the labeled dialog surface when none exists, or preserves current focus | Popover and hook | Automatic | `component:Popover` | Current public behavior | The injected fallback close control is excluded from initial-focus candidates and reveals only when reached sequentially. |
-| Dismissal | Outside/Escape enabled or disabled within native constraints | Controls light dismiss and explicit Escape participation | Popover and hook | Both enabled | `component:Popover`; `family:overlay-dismissal` owns Escape/platform-close ordering | Current public behavior | Disabling Escape alone cannot override the native Escape behavior of an auto popover; explicit-dismiss behavior requires light dismiss to be disabled too. |
-| Surface treatment | Default surface or caller-owned treatment | Applies the shared painted surface and optional consumer styling | Popover and hook | Default surface | `component:Popover` | Current public behavior | Custom styling does not change lifecycle, focus, or dismissal semantics. |
-| Surface target ownership | Shared baseline or component-specific refinement | Assigns `popover` as the broad surface owner and lets a composed component add its own target on that same element | Popover and hook | `popover` baseline; no component-specific refinement | `component:Popover`; the composed component owns its refinement target | Current compatibility contract | `popover-surface` is compatibility output, not a new target for consumers or a second anatomy owner. |
-| Placement and fit | Logical placement/alignment plus preferred width | Positions the anchor surface and constrains it to available space | Popover and hook renderer | Below/start; Popover matches trigger minimum width when no width is supplied | `component:Popover` above `architecture:layer-runtime` | Current public behavior | Preferred width and trigger matching remain capped by viewport and safe-area availability. |
+| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid or unsupported behavior |
+| ------------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Trigger composition | Wrapped trigger, render-prop trigger, or referenced anchor | Supplies the anchor and the control that opens or closes the standard component | Popover | Wrapped trigger when children are supplied | `component:Popover` | Current public behavior | A referenced or wrapped anchor without a button or button role warns in development and receives no trigger handler; it does not throw. |
+| Visibility ownership | Uncontrolled or externally controlled | Chooses whether Popover stores visibility or synchronizes to caller state | Popover | Uncontrolled | `component:Popover` | Current public behavior | Controlled changes are synchronized through show/hide; dismissal requests are reported to the caller rather than redefining the external source of truth. |
+| Popup semantics | Dialog or neutral wrapper | Exposes dialog semantics or lets child menu/listbox semantics own the popup | Popover and hook | Dialog | `component:Popover` | Current public behavior | A dialog without a label warns in development. Neutral mode omits dialog role and modal semantics. |
+| Focus entry | Automatic or caller-preserved | Focuses genuine caller content, falls back to the labeled dialog surface when none exists, or preserves current focus | Popover and hook | Automatic | `component:Popover` | Current public behavior | The injected fallback close control is excluded from initial-focus candidates and reveals only when reached sequentially. |
+| Dismissal | Outside/Escape enabled or disabled within native constraints | Controls light dismiss and explicit Escape participation | Popover and hook | Both enabled | `component:Popover`; `family:overlay-dismissal` owns Escape/platform-close ordering | Current public behavior | Disabling Escape alone cannot override the native Escape behavior of an auto popover; explicit-dismiss behavior requires light dismiss to be disabled too. |
+| Surface treatment | Default surface or caller-owned treatment | Applies the shared painted surface and optional consumer styling | Popover and hook | Default surface | `component:Popover` | Current public behavior | Custom styling does not change lifecycle, focus, or dismissal semantics. |
+| Surface padding | A spacing-scale step, `0` through `10` | Sets the inset the painted surface keeps around caller content; `0` is a flush surface for content that owns its own edges | Popover and hook | Popover: step 3; hook: none | `component:Popover` | Pending owner review (DEC-4) | The rung lands on the painted surface, so a theme's `padding` on the `popover` target replaces it rather than nesting; consumer `xstyle` merges after it. |
+| Surface target ownership | Shared baseline or component-specific refinement | Assigns `popover` as the broad surface owner and lets a composed component add its own target on that same element | Popover and hook | `popover` baseline; no component-specific refinement | `component:Popover`; the composed component owns its refinement target | Current compatibility contract | `popover-surface` is compatibility output, not a new target for consumers or a second anatomy owner. |
+| Placement and fit | Logical placement/alignment plus preferred width | Positions the anchor surface and constrains it to available space | Popover and hook renderer | Below/start; Popover matches trigger minimum width when no width is supplied | `component:Popover` above `architecture:layer-runtime` | Current public behavior | Preferred width and trigger matching remain capped by viewport and safe-area availability. |
### Public `usePopover` semantic inputs
@@ -139,6 +143,7 @@ table owns their semantic effect.
| Fallback close control and label | Included; “Close popover” | Appends an end-of-trap close control for each rendered surface. | When omitted, the hook does not synthesize another close affordance. |
| Popup role, label, and modality | Dialog, modal, no implicit label | Stamps semantics on the painted surface for its rendered lifetime. | Neutral role suppresses dialog and modal semantics. Missing dialog label warns in development rather than throwing. |
| Default surface | Enabled | Applies the shared background, radius, and elevation treatment while rendered. | Turning it off delegates painting to caller content but does not turn `usePopover` into a different lifecycle primitive. |
+| Surface padding | None | Applies one spacing-scale rung on every edge of the painted surface while rendered. `Popover` passes its own default of 3; a direct hook composition paints no padding unless it asks for a rung. | The rung is not a container-protocol enrollment: the surface publishes no edge geometry to its content. |
| Optional component surface target | No component-specific refinement | Adds a component-owned refinement target beside the canonical `popover` target on the same rendered surface. New direct hook consumers provide and document one only when they need distinct theme reachability. | `surfaceTarget` does not create another surface or owner. Do not pass or depend on deprecated `popover-surface`. |
### Public `usePopover` semantic outputs
@@ -170,15 +175,16 @@ table owns their semantic effect.
## Behavioral and layout contract
-| ID | Invariant | Basis | Acceptance and implementation state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| FR1 | Popover and public `usePopover` expose one visibility lifecycle with canonical show, hide, and toggle operations. Every opening path inherits same-gesture reopen protection without changing public signatures. | Current public package surface, `architecture:layer-runtime/INV7`, and owner approval on 2026-09-07 | Accepted; implemented and covered by focused Popover-family tests |
-| FR2 | Popover derives semantic focus entry identically across activation modalities: first genuine caller content, then labeled dialog-surface fallback. The injected close control is excluded. Shared interaction modality controls focus indication, not destination. | PR #5373, `architecture:interaction-modality`, and owner approval on 2026-09-07 | Accepted; implemented and covered by Popover focus tests |
-| FR3 | The preferred surface size is capped to logical viewport and safe-area availability before overflow is enabled. | PR #5373, current source, tests, and Storybook fixtures | Verified in unit/style evidence; real rendered viewport evidence remains a gap |
-| FR4 | Popover enables internal scrolling only after measured overflow exceeds the current tolerance. Fitting content does not become a scroll container. | PR #5373 and current tests | Verified current behavior |
-| FR5 | Overflow signals while open coalesce into at most one measurement per animation frame, and Popover owns no measurement observers while closed. | PR #5373 and current tests | Verified current resource behavior |
-| FR6 | Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part. | Current source, docs target inventory, and tests | Accepted anatomy; stale consumer anatomy corrected by this contract |
-| FR7 | The painted surface has one broad canonical target, `popover`. `popover-surface` remains a deprecated compatibility alias on that same part; composed components may add one authoritative component-specific refinement target. | Owner direction on 2026-08-31 plus current target inventory | Accepted compatibility contract; both canonical and deprecated paths remain supported and covered |
+| ID | Invariant | Basis | Acceptance and implementation state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| FR1 | Popover and public `usePopover` expose one visibility lifecycle with canonical show, hide, and toggle operations. Every opening path inherits same-gesture reopen protection without changing public signatures. | Current public package surface, `architecture:layer-runtime/INV7`, and owner approval on 2026-09-07 | Accepted; implemented and covered by focused Popover-family tests |
+| FR2 | Popover derives semantic focus entry identically across activation modalities: first genuine caller content, then labeled dialog-surface fallback. The injected close control is excluded. Shared interaction modality controls focus indication, not destination. | PR #5373, `architecture:interaction-modality`, and owner approval on 2026-09-07 | Accepted; implemented and covered by Popover focus tests |
+| FR3 | The preferred surface size is capped to logical viewport and safe-area availability before overflow is enabled. | PR #5373, current source, tests, and Storybook fixtures | Verified in unit/style evidence; real rendered viewport evidence remains a gap |
+| FR4 | Popover enables internal scrolling only after measured overflow exceeds the current tolerance. Fitting content does not become a scroll container. | PR #5373 and current tests | Verified current behavior |
+| FR5 | Overflow signals while open coalesce into at most one measurement per animation frame, and Popover owns no measurement observers while closed. | PR #5373 and current tests | Verified current resource behavior |
+| FR6 | Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part. | Current source, docs target inventory, and tests | Accepted anatomy; stale consumer anatomy corrected by this contract |
+| FR7 | The painted surface has one broad canonical target, `popover`. `popover-surface` remains a deprecated compatibility alias on that same part; composed components may add one authoritative component-specific refinement target. | Owner direction on 2026-08-31 plus current target inventory | Accepted compatibility contract; both canonical and deprecated paths remain supported and covered |
+| FR8 | The surface padding is one spacing-scale rung applied on the painted surface. Popover defaults to step 3 (the released inset); `0` paints a flush surface; a direct `usePopover` composition paints none unless it asks for a rung. The rung sits where a theme's `padding` on the `popover` target replaces it. | PR #6683 and its Popover tests; `architecture:container-padding/INV8` (padding alone does not enroll) | Pending owner review (DEC-4); implemented and covered by the Popover surface-padding suite |
### Allowed variation
@@ -188,9 +194,10 @@ table owns their semantic effect.
- **AV2 — Popup semantics.** Dialog mode may focus the dialog container;
role-neutral popups let their child role and content focus model remain
exposed.
-- **AV3 — Surface treatment.** The hook may omit its default paint or add a
- component-owned refinement target while preserving the canonical `popover`
- ownership, lifecycle, focus containment, and dismissal model.
+- **AV3 — Surface treatment.** The hook may omit its default paint, change the
+ surface padding rung, or add a component-owned refinement target while
+ preserving the canonical `popover` ownership, lifecycle, focus containment,
+ and dismissal model.
- **AV4 — Placement.** Logical placement, alignment, preferred width, and
available viewport size may change geometry without changing the fit and
overflow precedence below.
@@ -336,6 +343,7 @@ removal.
| Public boundary, FR1 | `Popover.test.tsx` compile-time public-surface assertions plus package/barrel inspection | Unchanged public signatures and same-gesture rejection across Popover-family openings | A public type changes or a same-gesture request reaches visibility state. | `audit:Popover/api` |
| FR2, AR2–AR4 | `Popover.test.tsx` focus/role suites and `useFocusTrap.test.tsx` container-entry suites | Pointer, keyboard/AT-style, read-only, neutral role, no autofocus, controlled, Tab/Shift+Tab, Escape, focus return | Changing semantic destination by modality, selecting fallback close initially, losing shared indication, or allowing focus escape fails assertions. | `audit:Popover/accessibility` |
| FR3, FR4 | `Popover.test.tsx` sizing/overflow suites; `Popover.stories.tsx` real-viewport scenarios for manual/browser evidence | Explicit width, trigger matching, all alignments, fitting and overflowing content | Removing a cap, reversing width precedence, or always enabling scroll fails emitted-style or overflow assertions. | `audit:Popover/layout` |
+| FR8 | `Popover.test.tsx` surface-padding suite | Default rung, `0`, an explicit rung, a direct hook composition with and without a rung | A default other than step 3, a rung landing on a box inside the surface, or the hook painting a rung it was not given fails the suite. | `audit:Popover/theming` |
| FR5 | `Popover.test.tsx` scheduling and observer-lifecycle suites | Closed, opened, repeated signals, cleanup | Constructing observers while closed or measuring more than once per pending frame fails lifecycle assertions. | `audit:Popover/resources` |
| FR6, FR7 and theming anatomy | `Popover.test.tsx`, `Popover.doc.mjs`, `usePopover.doc.mjs`, `astryx theme targets Popover --json`, and `scripts/check-knowledge.mjs` | One real surface with canonical `popover`; deprecated alias on that element; composed-component refinements | A fake anatomy part, loss of compatibility output, missing deprecation metadata, or an active target without a real owner fails review or validation. | `audit:Popover/theming` |
| AR5 | `Popover.stories.tsx` manual-AT fixture and PR #5373 test record | Read-only dialog manual-AT fixture; no recorded NVDA/VoiceOver announcement result | A fixture without recorded AT/browser observations cannot be cited as announcement proof. | `audit:Popover/at-evidence` |
@@ -424,3 +432,29 @@ This file does not duplicate consumer signatures, prop tables, examples,
implementation steps, shared layer algorithms, or family dismissal rules. It
links to their owners and records only Popover-specific semantics, boundaries,
and invariants.
+
+### DEC-4 — Surface padding is a spacing-scale rung on the painted surface
+
+**Reference:** `component:Popover/DEC-4`
+
+**Decider:** pending owner review (proposed in PR #6683)
+
+The surface padding becomes a public concept: `Popover` takes `padding` on the
+shared spacing scale (`0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10`, the same
+shape `Card`, `Stack`, `LayoutContent` and `LayoutPanel` use), defaulting to the
+released step 3; `usePopover` takes the same option and paints no padding unless
+given one, which is the hook's released behavior. `0` is a flush surface for
+content that owns its own edges — a list of rows whose hover paint reaches the
+edge, a header row with a bottom rule.
+
+The rung is applied on the painted surface, not on a wrapper inside it, so a
+theme's `padding` on the `popover` target keeps replacing it instead of nesting
+(the placement DEC-2 already fixed for the surface). This does not enroll Popover
+in the container padding protocol: the surface publishes no edge geometry to its
+content (`architecture:container-padding/INV8`).
+
+Rejected: a `'none'` string beside the rungs. The nearest existing vocabulary
+spells the flush case as `0` on the numeric scale, and a second spelling of the
+same value would leave two ways to write one state. Also rejected: moving the
+padding onto an inner content wrapper a consumer class can replace — that turns
+the released theming placement back into a nested box.
diff --git a/packages/core/src/Popover/Popover.test.tsx b/packages/core/src/Popover/Popover.test.tsx
index 93ce1f4031..15f13498ad 100644
--- a/packages/core/src/Popover/Popover.test.tsx
+++ b/packages/core/src/Popover/Popover.test.tsx
@@ -958,6 +958,85 @@ describe('Popover', () => {
});
});
+ describe('surface padding', () => {
+ // StyleX's dev runtime names the style object a class came from
+ // ("padding__paddingStyles.3"), which is the padding rung the surface
+ // was handed.
+ function paddingRungOf(surface: Element | null): string | null {
+ const match = surface?.className.match(
+ /padding__paddingStyles\.([\d.]+)/,
+ );
+ return match ? match[1] : null;
+ }
+
+ it('paints the spacing-3 rung by default, unchanged', () => {
+ render(
+ <Popover isOpen content={<span>Content</span>} label="Test">
+ <button type="button">Open</button>
+ </Popover>,
+ );
+ const surface = document.querySelector('.astryx-popover');
+ expect(paddingRungOf(surface)).toBe('3');
+ expect(surface?.className).not.toContain('contentPadding');
+ });
+
+ it('paints no padding on a flush surface (padding={0})', () => {
+ render(
+ <Popover
+ isOpen
+ padding={0}
+ content={<span data-testid="content">Content</span>}
+ label="Test">
+ <button type="button">Open</button>
+ </Popover>,
+ );
+ const surface = document.querySelector('.astryx-popover');
+ // The rung lands on the painted surface itself, not a wrapper inside
+ // it, so the content reaches the surface edge.
+ expect(surface).toContainElement(screen.getByTestId('content'));
+ expect(paddingRungOf(surface)).toBe('0');
+ });
+
+ it('paints the requested rung', () => {
+ render(
+ <Popover isOpen padding={4} content={<span>Content</span>} label="Test">
+ <button type="button">Open</button>
+ </Popover>,
+ );
+ const surface = document.querySelector('.astryx-popover');
+ expect(paddingRungOf(surface)).toBe('4');
+ });
+
+ it('lets a direct usePopover consumer opt into a rung, and paints none by default', () => {
+ function Direct({padding}: {padding?: 0 | 2}) {
+ const popover = usePopover({dialogLabel: 'Direct', padding});
+ return (
+ <>
+ <button
+ ref={popover.triggerRef}
+ type="button"
+ onClick={popover.toggle}
+ {...popover.triggerProps}>
+ Open
+ </button>
+ {popover.render(<span>Direct content</span>)}
+ </>
+ );
+ }
+ const {unmount} = render(<Direct />);
+ fireEvent.click(screen.getByRole('button', {name: 'Open'}));
+ expect(paddingRungOf(document.querySelector('.astryx-popover'))).toBe(
+ null,
+ );
+ unmount();
+ render(<Direct padding={2} />);
+ fireEvent.click(screen.getByRole('button', {name: 'Open'}));
+ expect(paddingRungOf(document.querySelector('.astryx-popover'))).toBe(
+ '2',
+ );
+ });
+ });
+
it('puts the theme target and styling escape hatches on the popup surface', () => {
render(
<Popover
diff --git a/packages/core/src/Popover/Popover.tsx b/packages/core/src/Popover/Popover.tsx
index 475103e685..b4692b21d5 100644
--- a/packages/core/src/Popover/Popover.tsx
+++ b/packages/core/src/Popover/Popover.tsx
@@ -33,6 +33,7 @@ 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 type {SpacingStep} from '../utils/types';
// =============================================================================
// Helpers
@@ -168,6 +169,21 @@ export interface PopoverProps extends Pick<
*/
width?: number | string;
+ /**
+ * Inner padding of the popover surface, using the spacing scale.
+ * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
+ * Matches the `padding` prop on `Card` and `Stack`.
+ *
+ * Pass `0` for a flush surface when the content owns its own edges — a
+ * list of rows whose hover paint reaches the edge, or a header row with a
+ * bottom rule — and pad the content itself.
+ *
+ * The padding sits on the painted surface (the `popover` theme target), so
+ * a theme's `padding` on that target replaces it rather than nesting.
+ * @default 3
+ */
+ padding?: SpacingStep;
+
/**
* Accessible label for the popover dialog.
* Recommended for accessibility when `role` is `'dialog'`.
@@ -310,14 +326,6 @@ const styles = stylex.create({
overflow: 'auto',
overscrollBehavior: 'contain',
},
- // 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'],
- paddingInlineStart: spacingVars['--spacing-3'],
- paddingInlineEnd: spacingVars['--spacing-3'],
- },
customWidth: (width: string | number) => ({
width: typeof width === 'number' ? `${width}px` : width,
}),
@@ -386,6 +394,7 @@ export function Popover({
onOpenChange,
isEnabled = true,
width,
+ padding = 3,
label,
role = 'dialog',
isModal,
@@ -425,8 +434,10 @@ export function Popover({
// 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',
+ // Surface padding is a usePopover option so it lands on that same box,
+ // where a theme's `padding` replaces it instead of nesting inside it.
+ padding,
xstyle: [
- styles.contentPadding,
styles.surfaceViewportFit,
hasOverflow && styles.surfaceScrollable,
xstyle,
diff --git a/packages/core/src/Popover/usePopover.doc.mjs b/packages/core/src/Popover/usePopover.doc.mjs
index dadd4da8fe..917b7f259a 100644
--- a/packages/core/src/Popover/usePopover.doc.mjs
+++ b/packages/core/src/Popover/usePopover.doc.mjs
@@ -93,6 +93,12 @@ export const docs = {
'Whether to apply the default popover surface background, radius, and shadow.',
default: 'true',
},
+ {
+ name: 'padding',
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+ description:
+ 'Inner padding of the painted surface on the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Omit it and the hook paints no padding of its own; Popover passes 3 by default and 0 for a flush surface.',
+ },
{
name: 'surfaceTarget',
type: 'string',
@@ -213,6 +219,7 @@ export const docsDense = {
role: 'content wrapper ARIA role; "none" for listbox/menu popups.',
isModal: 'whether a dialog-role popover is modal (aria-modal).',
hasSurface: 'apply default surface background/radius/shadow.',
+ padding: 'spacing-scale padding on the painted surface; omit for none.',
surfaceTarget:
'optional owned refinement target; document it and do not use deprecated popover-surface.',
},
diff --git a/packages/core/src/Popover/usePopover.tsx b/packages/core/src/Popover/usePopover.tsx
index fa4fafdc4a..f7cbb94cf3 100644
--- a/packages/core/src/Popover/usePopover.tsx
+++ b/packages/core/src/Popover/usePopover.tsx
@@ -35,6 +35,8 @@ import {useDevWarning} from '../hooks/useDevWarning';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {mergeProps} from '../utils/mergeProps';
import {themeProps} from '../utils/themeProps';
+import {paddingStyles} from '../Layout/padding.stylex';
+import type {SpacingStep} from '../utils/types';
import {stableClassName} from '../naming';
const FALLBACK_CLOSE_SELECTOR = '[data-astryx-popover-fallback-close]';
@@ -229,6 +231,22 @@ export interface UsePopoverOptions {
*/
hasSurface?: boolean;
+ /**
+ * Inner padding of the painted surface, using the spacing scale.
+ * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
+ * `0` paints a flush surface for content that owns its own edges (a list of
+ * rows, a header with a rule). Matches the `padding` prop on `Card`,
+ * `Stack` and `Popover`.
+ *
+ * Applied to the surface itself — the box that paints background, radius
+ * and elevation — so a theme's `padding` on the `popover` target replaces
+ * it instead of nesting inside it. `xstyle` merges after it.
+ *
+ * Omit it and the surface paints no padding of its own (the hook's
+ * historical behavior; `Popover` passes its own default).
+ */
+ padding?: SpacingStep;
+
/**
* Theme-target name stamped on the popup SURFACE — the element that paints
* the background, radius and elevation — without the `astryx-` prefix
@@ -374,6 +392,7 @@ function usePopoverImplementation(
hasEscapeDismiss = true,
hasAutoFocus = true,
hasSurface = true,
+ padding,
surfaceTarget,
hasCloseButton = true,
closeButtonLabel: closeButtonLabelFromProps,
@@ -507,6 +526,7 @@ function usePopoverImplementation(
focusOutlineProps.focusVisible(
styles.contentWrapper,
hasSurface && styles.surface,
+ padding != null && paddingStyles[padding],
xstyle,
),
className,
@@ -536,6 +556,7 @@ function usePopoverImplementation(
layer,
hasCloseButton,
hasSurface,
+ padding,
surfaceTarget,
className,
style,