Skip to content

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

TypeScript

fix(layer): append span position-try-fallbacks so centered layers don't clip at viewport edges (#3671) (#3674)

AK2d8ba8b87aaa
diff --git a/.changeset/layer-centered-span-fallbacks.md b/.changeset/layer-centered-span-fallbacks.md
new file mode 100644
index 0000000000..9e0dcfb85f
--- /dev/null
+++ b/.changeset/layer-centered-span-fallbacks.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Layer: centered layers near a viewport edge no longer render clipped (#3671). Flip fallbacks are a no-op for center alignment, so centered placements now append span-based `position-try-fallbacks` that slide the layer along its alignment axis.
+
+@AKnassa
diff --git a/packages/core/src/Layer/useLayer.doc.mjs b/packages/core/src/Layer/useLayer.doc.mjs
index 32bbdb540c..7d16b8190b 100644
--- a/packages/core/src/Layer/useLayer.doc.mjs
+++ b/packages/core/src/Layer/useLayer.doc.mjs
@@ -72,13 +72,14 @@ export const docs = {
{
name: 'id',
type: 'string',
- description: 'Unique ID for aria-describedby or other ARIA relationships.',
+ description:
+ 'Unique ID for aria-describedby or other ARIA relationships.',
},
{
name: 'render',
type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
description:
- 'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal.',
+ 'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
},
],
usage: {
@@ -130,7 +131,7 @@ export const docsDense = {
hide: 'hide layer.',
isOpen: 'whether layer is open.',
id: 'unique ARIA id.',
- render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring, which becomes yours). Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
+ render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring, which becomes yours). Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal. Viewport overflow: flips to opposite side; centered layers also slide along the alignment axis (span fallbacks).',
},
usage: {
description:
@@ -138,11 +139,13 @@ export const docsDense = {
bestPractices: [
{
guidance: true,
- description: 'Use context mode for trigger-anchored overlays; fixed mode for explicit coordinates.',
+ description:
+ 'Use context mode for trigger-anchored overlays; fixed mode for explicit coordinates.',
},
{
guidance: true,
- description: 'Build on Popover/HoverCard/Tooltip for common overlay patterns.',
+ description:
+ 'Build on Popover/HoverCard/Tooltip for common overlay patterns.',
},
{
guidance: true,
diff --git a/packages/core/src/Layer/useLayer.test.tsx b/packages/core/src/Layer/useLayer.test.tsx
index d808e87499..5608ac9783 100644
--- a/packages/core/src/Layer/useLayer.test.tsx
+++ b/packages/core/src/Layer/useLayer.test.tsx
@@ -12,7 +12,7 @@
import {describe, it, expect, vi, afterEach} from 'vitest';
import {render, act} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
-import {useLayer} from './useLayer';
+import {useLayer, getPositionTryFallbacks} from './useLayer';
import type {
LayerPlacement,
LayerAlignment,
@@ -33,6 +33,141 @@ function LayerHarness({
return <>{layer.render(<span>Layer content</span>, {x: 0, y: 0})}</>;
}
+/**
+ * Context-mode harness: renders a trigger plus the layer so tests can assert
+ * on the anchor-positioning styles applied to the popover element.
+ */
+function ContextLayerHarness({
+ placement,
+ alignment,
+}: {
+ placement?: LayerPlacement;
+ alignment?: LayerAlignment;
+}) {
+ const layer = useLayer({mode: 'context'});
+ return (
+ <>
+ <button type="button" ref={layer.ref}>
+ Trigger
+ </button>
+ {layer.render(<span>Layer content</span>, {placement, alignment})}
+ </>
+ );
+}
+
+describe('getPositionTryFallbacks (issue #3671)', () => {
+ const FLIPS = 'flip-block, flip-inline, flip-block flip-inline';
+
+ it('appends inline span fallbacks for centered above/below layers so inline overflow can resolve (flip-inline is a no-op on center)', () => {
+ expect(getPositionTryFallbacks('above', 'center')).toBe(
+ `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+ );
+ expect(getPositionTryFallbacks('below', 'center')).toBe(
+ `${FLIPS}, bottom span-left, bottom span-right, top span-left, top span-right`,
+ );
+ });
+
+ it('appends block span fallbacks for centered start/end layers so block overflow can resolve (flip-block is a no-op on center)', () => {
+ expect(getPositionTryFallbacks('start', 'center')).toBe(
+ `${FLIPS}, left span-top, left span-bottom, right span-top, right span-bottom`,
+ );
+ expect(getPositionTryFallbacks('end', 'center')).toBe(
+ `${FLIPS}, right span-top, right span-bottom, left span-top, left span-bottom`,
+ );
+ });
+
+ it('keeps flip-only fallbacks for non-centered alignments (flips already resolve overflow there)', () => {
+ const nonCentered: [LayerPlacement, LayerAlignment][] = [
+ ['above', 'start'],
+ ['above', 'end'],
+ ['below', 'start'],
+ ['below', 'end'],
+ ['start', 'start'],
+ ['start', 'end'],
+ ['end', 'start'],
+ ['end', 'end'],
+ ];
+ for (const [placement, alignment] of nonCentered) {
+ expect(getPositionTryFallbacks(placement, alignment)).toBe(FLIPS);
+ }
+ });
+
+ it('defaults to above/center when called without arguments (matches renderContext defaults)', () => {
+ expect(getPositionTryFallbacks()).toBe(
+ getPositionTryFallbacks('above', 'center'),
+ );
+ expect(getPositionTryFallbacks(undefined, undefined)).toBe(
+ `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+ );
+ });
+
+ it('produces well-formed, duplicate-free lists with flips first and axis-correct spans for every placement/alignment combo', () => {
+ const placements: LayerPlacement[] = ['above', 'below', 'start', 'end'];
+ const alignments: LayerAlignment[] = ['start', 'center', 'end'];
+ const spanPattern: Record<LayerPlacement, RegExp> = {
+ above: /^(top|bottom) span-(left|right)$/,
+ below: /^(top|bottom) span-(left|right)$/,
+ start: /^(left|right) span-(top|bottom)$/,
+ end: /^(left|right) span-(top|bottom)$/,
+ };
+
+ for (const placement of placements) {
+ for (const alignment of alignments) {
+ const list = getPositionTryFallbacks(placement, alignment);
+ const items = list.split(', ');
+
+ expect(items.slice(0, 3)).toEqual([
+ 'flip-block',
+ 'flip-inline',
+ 'flip-block flip-inline',
+ ]);
+ expect(new Set(items).size).toBe(items.length);
+ for (const item of items.slice(3)) {
+ expect(item).toMatch(spanPattern[placement]);
+ }
+ expect(items.length).toBe(alignment === 'center' ? 7 : 3);
+ }
+ }
+ });
+
+ it('updates the fallback list when placement/alignment props change on re-render', () => {
+ const {container, rerender} = render(
+ <ContextLayerHarness placement="above" alignment="center" />,
+ );
+ const layerEl = container.querySelector('[popover]') as HTMLElement;
+ expect(layerEl.style.positionTryFallbacks).toContain('top span-left');
+
+ rerender(<ContextLayerHarness placement="above" alignment="start" />);
+ expect(layerEl.style.positionTryFallbacks).toBe(FLIPS);
+
+ rerender(<ContextLayerHarness placement="start" alignment="center" />);
+ expect(layerEl.style.positionTryFallbacks).toBe(
+ `${FLIPS}, left span-top, left span-bottom, right span-top, right span-bottom`,
+ );
+ });
+
+ it('does not apply anchor fallbacks in fixed mode (manual coordinates)', () => {
+ function FixedHarness() {
+ const layer = useLayer({mode: 'fixed'});
+ return <>{layer.render(<span>Fixed content</span>, {x: 10, y: 20})}</>;
+ }
+ const {container} = render(<FixedHarness />);
+ const layerEl = container.querySelector('[popover]') as HTMLElement;
+ expect(layerEl.style.positionTryFallbacks ?? '').toBeFalsy();
+ expect(layerEl.style.left).toBe('10px');
+ expect(layerEl.style.top).toBe('20px');
+ });
+
+ it('applies span fallbacks to the rendered popover for the default (above/center) layer', () => {
+ const {container} = render(<ContextLayerHarness />);
+ const layerEl = container.querySelector('[popover]') as HTMLElement;
+ expect(layerEl).not.toBeNull();
+ expect(layerEl.style.positionTryFallbacks).toBe(
+ `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+ );
+ });
+});
+
describe('useLayer', () => {
const originalShowPopover = HTMLElement.prototype.showPopover;
const originalHidePopover = HTMLElement.prototype.hidePopover;
diff --git a/packages/core/src/Layer/useLayer.tsx b/packages/core/src/Layer/useLayer.tsx
index 3c74390dba..a45a7e3c3a 100644
--- a/packages/core/src/Layer/useLayer.tsx
+++ b/packages/core/src/Layer/useLayer.tsx
@@ -320,6 +320,36 @@ function getPositionArea(
return inline; // center
}
+/**
+ * Compute the `position-try-fallbacks` list for a placement/alignment pair.
+ *
+ * Flips alone cannot rescue a centered layer — flipping along the alignment
+ * axis maps center → center, so overflow on that axis renders clipped
+ * (#3671). Centered alignments therefore append span-based fallbacks letting
+ * the browser slide the layer along the alignment axis as a last resort
+ * (same-side spans first). Flips already resolve non-centered alignments.
+ */
+export function getPositionTryFallbacks(
+ placement: LayerPlacement = 'above',
+ alignment: LayerAlignment = 'center',
+): string {
+ const flips = 'flip-block, flip-inline, flip-block flip-inline';
+
+ if (alignment !== 'center') {
+ return flips;
+ }
+
+ if (placement === 'above' || placement === 'below') {
+ const [same, opposite] =
+ placement === 'above' ? ['top', 'bottom'] : ['bottom', 'top'];
+ return `${flips}, ${same} span-left, ${same} span-right, ${opposite} span-left, ${opposite} span-right`;
+ }
+
+ const [same, opposite] =
+ placement === 'start' ? ['left', 'right'] : ['right', 'left'];
+ return `${flips}, ${same} span-top, ${same} span-bottom, ${opposite} span-top, ${opposite} span-bottom`;
+}
+
/**
* Core layer hook that handles popover behavior and positioning.
*
@@ -512,8 +542,10 @@ export function useLayer(
: {
positionAnchor: anchorId,
positionArea: getPositionArea(placement, alignment),
- positionTryFallbacks:
- 'flip-block, flip-inline, flip-block flip-inline',
+ positionTryFallbacks: getPositionTryFallbacks(
+ placement,
+ alignment,
+ ),
};
const stylexResult = stylex.props(styles.base, xstyle);