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.mdnew file mode 100644index 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.++@AKnassadiff --git a/packages/core/src/Layer/useLayer.doc.mjs b/packages/core/src/Layer/useLayer.doc.mjsindex 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.tsxindex 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.tsxindex 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);