Skip to content

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

TypeScript

fix(Field): contain input stacking locally below the AppShell header (#5693)

Talha Rizwan53b874af00ef
diff --git a/.changeset/keep-the-sticky-appshell-header-above-field-inpu-s4g6.md b/.changeset/keep-the-sticky-appshell-header-above-field-inpu-s4g6.md
new file mode 100644
index 0000000000..3b3bad1193
--- /dev/null
+++ b/.changeset/keep-the-sticky-appshell-header-above-field-inpu-s4g6.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Field inputs no longer paint above the sticky AppShell header while scrolling (#5689). Field now contains its local stacking layers (the input surface's z-index and the attached status layer) behind an `isolation: isolate` boundary on the field surface, so they cannot compete with page-level stacking; the AppShell header keeps its normal stacking level.
+@Cypher-Aura-19
diff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsx
index 15577711e3..7e19d57712 100644
--- a/apps/storybook/stories/AppShell.stories.tsx
+++ b/apps/storybook/stories/AppShell.stories.tsx
@@ -18,6 +18,8 @@ import {
SideNavSection,
} from '@astryxdesign/core/SideNav';
import {useMediaQuery} from '@astryxdesign/core/hooks';
+import {TextArea} from '@astryxdesign/core/TextArea';
+import {TextInput} from '@astryxdesign/core/TextInput';
import * as stylex from '@stylexjs/stylex';
import {
HomeIcon,
@@ -53,6 +55,11 @@ const styles = stylex.create({
flexDirection: 'column' as const,
gap: 16,
},
+ fieldStack: {
+ display: 'flex',
+ flexDirection: 'column' as const,
+ gap: 32,
+ },
});
// =============================================================================
@@ -458,6 +465,36 @@ export const AutoHeight: Story = {
),
};
+/**
+ * Auto height mode with Field-based inputs. Scroll the inputs under the
+ * sticky header — the header must stay above the input surfaces. Field
+ * contains its local stacking layers at its own surface (AST-027), so the
+ * header needs no escalated z-index: the detached variant's input wrapper
+ * z-index is local to the field and cannot compete with page-level stacking.
+ */
+export const AutoHeightWithFields: Story = {
+ render: () => (
+ <AppShell contentPadding={6} topNav={<AppTopNav />} height="auto">
+ <div {...stylex.props(styles.fieldStack)}>
+ <TextArea label="Question" value="" onChange={() => {}} />
+ <TextArea
+ label="Detached question"
+ statusVariant="detached"
+ value=""
+ onChange={() => {}}
+ />
+ <TextInput
+ label="Detached name"
+ statusVariant="detached"
+ value=""
+ onChange={() => {}}
+ />
+ <MockContent paragraphs={20} />
+ </div>
+ </AppShell>
+ ),
+};
+
/**
* Controlled collapse with external state.
*
diff --git a/packages/core/src/AppShell/AppShell.test.tsx b/packages/core/src/AppShell/AppShell.test.tsx
index bee1e3852f..48e2218c9f 100644
--- a/packages/core/src/AppShell/AppShell.test.tsx
+++ b/packages/core/src/AppShell/AppShell.test.tsx
@@ -26,6 +26,7 @@ import {InternationalizationProvider} from '../i18n';
import {MobileNav} from '../MobileNav';
import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
import {TopNav, TopNavHeading, TopNavItem} from '../TopNav';
+import {TextInput} from '../TextInput';
import {useAppShellMobile} from './AppShellMobileContext';
import {Theme, defineTheme} from '../theme';
@@ -706,6 +707,41 @@ describe('AppShell', () => {
// Sticky navigation in auto mode
// ===========================================================================
+ // A Field input wrapper carries a local z-index (it paints above the
+ // attached status message box via a negative-margin overlap), so without a
+ // component-owned isolation boundary it competes with page-level stacking —
+ // a field scrolled underneath the sticky header then paints over it (#5689).
+ // The fix is local containment: the Field root isolates the wrapper's local
+ // layer, so the header needs no escalated z-index to stay above it. This
+ // asserts that ownership boundary — the field's painted surface is an
+ // isolated stacking context — not a comparison between two page-level
+ // z-index values.
+ it('contains Field input stacking locally so the sticky header needs no escalated z-index in auto mode', () => {
+ render(
+ <AppShell height="auto" topNav={<div>Nav</div>}>
+ <TextInput
+ label="Name"
+ statusVariant="detached"
+ value=""
+ onChange={() => {}}
+ />
+ </AppShell>,
+ );
+ const header = screen.getByRole('banner');
+ const inputWrapper = screen.getByRole('textbox').parentElement!;
+ // The detached variant renders the input wrapper outside Field's isolated
+ // attached-status wrapper, so the Field root must own the boundary.
+ const fieldRoot = inputWrapper.parentElement!;
+ expect(inputWrapper).toBeTruthy();
+ expect(getComputedStyle(header).position).toBe('sticky');
+ // The header stays at its normal local stacking level — no escalation.
+ expect(Number(getComputedStyle(header).zIndex)).toBe(1);
+ expect(getComputedStyle(inputWrapper).position).toBe('relative');
+ // Field's local layers cannot escape into page-level stacking: the root
+ // establishes an isolation boundary around the input wrapper's z-index.
+ expect(getComputedStyle(fieldRoot).isolation).toBe('isolate');
+ });
+
it('wraps header in sticky container in auto mode', () => {
render(
<AppShell
diff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsx
index fd470489af..9c5e6006ea 100644
--- a/packages/core/src/AppShell/AppShell.tsx
+++ b/packages/core/src/AppShell/AppShell.tsx
@@ -395,7 +395,10 @@ const styles = stylex.create({
height: spacingVars['--spacing-12'],
paddingInline: spacingVars['--spacing-2'],
},
- // Sticky header for auto height mode
+ // Sticky header for auto height mode. The header stays at its local
+ // stacking level — Field-owned input surfaces contain their own local
+ // z-index layers (AST-027), so no escalated page-level value is needed
+ // for the header to paint above scrolled content.
headerSticky: {
position: 'sticky',
top: 0,
diff --git a/packages/core/src/Field/Field.test.tsx b/packages/core/src/Field/Field.test.tsx
index 4b1523880c..9fb7d8a608 100644
--- a/packages/core/src/Field/Field.test.tsx
+++ b/packages/core/src/Field/Field.test.tsx
@@ -538,4 +538,46 @@ describe('Field', () => {
expect(labelWrapper.querySelector('label')).not.toBeNull();
});
});
+
+ describe('local stacking ownership', () => {
+ // Input wrappers paint their surface above the attached status message
+ // box through a local z-index, so that layer must be contained by a
+ // Field-owned isolation boundary. Otherwise a detached or tooltip field
+ // — whose input wrapper renders outside the attached-status wrapper —
+ // competes with page-level stacking (AppShell sticky header, later
+ // siblings) and can paint over unrelated chrome (#5689).
+ it.each(['attached', 'detached', 'tooltip'] as const)(
+ 'isolates the field surface for the %s status variant',
+ variant => {
+ render(
+ <Field
+ label="Name"
+ inputID="name-input"
+ status={{type: 'error', message: 'Required'}}
+ statusVariant={variant}
+ data-testid="field">
+ <input id="name-input" data-testid="control" />
+ </Field>,
+ );
+ const field = screen.getByTestId('field');
+ // The Field root is the isolation owner: it stays at its normal
+ // parent paint level (it carries no positioning or z-index of its
+ // own) while containing every local layer — the input wrapper's 1
+ // and the attached status -1.
+ expect(getComputedStyle(field).isolation).toBe('isolate');
+ // Unpositioned and unranked — the owner never competes itself.
+ expect(getComputedStyle(field).zIndex).toBe('');
+ },
+ );
+
+ it('keeps a custom control without status isolated too', () => {
+ render(
+ <Field label="Name" inputID="name-input" data-testid="field">
+ <input id="name-input" data-testid="control" />
+ </Field>,
+ );
+ const field = screen.getByTestId('field');
+ expect(getComputedStyle(field).isolation).toBe('isolate');
+ });
+ });
});
diff --git a/packages/core/src/Field/Field.tsx b/packages/core/src/Field/Field.tsx
index c71f6383b5..07d0a593c4 100644
--- a/packages/core/src/Field/Field.tsx
+++ b/packages/core/src/Field/Field.tsx
@@ -35,6 +35,12 @@ const styles = stylex.create({
container: {
display: 'flex',
flexDirection: 'column',
+ // The Field root owns the local stacking boundary (AST-027): the input
+ // wrapper's z-index (1, above the attached status box) and the attached
+ // status layer (-1) order parts inside this surface only. Without this,
+ // detached/tooltip fields — whose input wrapper renders outside the
+ // attached-status wrapper — compete with page-level stacking (#5689).
+ isolation: 'isolate',
},
containerGap: {
gap: spacingVars['--spacing-1'],