@astryxdesign/core 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -297,6 +297,11 @@
       "types": "./dist/IconButton/index.d.ts",
       "default": "./dist/IconButton/index.js"
     },
+    "./Indicator": {
+      "source": "./src/Indicator/index.ts",
+      "types": "./dist/Indicator/index.d.ts",
+      "default": "./dist/Indicator/index.js"
+    },
     "./InputGroup": {
       "source": "./src/InputGroup/index.ts",
       "types": "./dist/InputGroup/index.d.ts",
@@ -658,7 +663,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "rimraf": "^6.0.1",
-    "@astryxdesign/cli": "0.3.0"
+    "@astryxdesign/cli": "0.4.0"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AlertDialog/AlertDialog.doc.mjs

@@ -21,11 +21,21 @@ export const docs = {
   ],
   usage: {
     description:
-      'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nFor cases where you want to show an alert without managing open state, use the `useImperativeAlertDialog` hook: call `alert.show(options)` and render `alert.element` in your tree.',
+      'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nIt implements the WAI-ARIA APG [Alert Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): `role="alertdialog"`, a title linked by `aria-labelledby`, a consequence description linked by `aria-describedby`, focus moved into the dialog on open and returned to the trigger on close, and no dismissal by clicking outside. Escape cancels.\n\nFor cases where you want to show an alert without managing open state, use the `useImperativeAlertDialog` hook: call `alert.show(options)` and render `alert.element` in your tree.',
     bestPractices: [
       {guidance: true, description: 'Make the action button label specific: "Delete project" is better than "OK" or "Confirm".'},
       {guidance: true, description: 'Describe what will happen in the description so the user knows the consequences before confirming.'},
+      {guidance: true, description: 'Keep the cancel button first: it takes initial focus, so the least destructive choice is the one already selected when the dialog opens.'},
       {guidance: false, description: 'Use AlertDialog for non-destructive actions; use a standard Dialog instead.'},
+      {guidance: false, description: 'Rely on color alone to signal danger; the action label itself should say what will happen.'},
+      {guidance: false, description: 'Close the dialog from onAction before the work finishes; hold it open with isActionLoading and call onOpenChange(false) when the action settles.'},
+    ],
+    anatomy: [
+      {name: 'Title', required: true, description: 'The question being asked. Renders as a level-2 heading and labels the dialog via aria-labelledby.'},
+      {name: 'Description', required: true, description: 'What will happen if the user confirms. Linked to the dialog via aria-describedby.'},
+      {name: 'Cancel button', required: true, description: 'Ghost button that dismisses without acting. Takes initial focus, and Escape does the same thing.'},
+      {name: 'Action button', required: true, description: 'The confirming action. Destructive by default; shows a spinner while isActionLoading is set.'},
+      {name: 'Backdrop', required: true, description: 'Overlay behind the dialog that blocks page interaction. Clicking it does not dismiss.'},
     ],
   },
   // Intentionally a contained isInline preview, not playground.overlay: the
@@ -107,7 +117,7 @@ export const docs = {
       name: 'isInline',
       type: 'boolean',
       default: 'false',
-      description: 'Renders alert dialog content inline without modal behavior. For documentation previews and showcases only.',
+      description: 'Renders alert dialog content inline without modal behavior. For documentation previews and showcases only. Not being a modal, the inline path renders role="group" instead of role="alertdialog".',
     },
   ],
   components: [
@@ -125,11 +135,14 @@ export const docsDense = {
   description: 'Confirms destructive/irreversible action before it happens (delete, revoke access, discard unsaved changes).',
   usage: {
     description:
-      'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). To show w/o managing open state, use useImperativeAlertDialog hook: call alert.show(options) + render alert.element in tree.',
+      'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). Implements WAI-ARIA APG Alert Dialog pattern (https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): role="alertdialog", aria-labelledby title, aria-describedby description, focus into dialog on open + back to trigger on close, no outside-click dismissal, Escape cancels. To show w/o managing open state, use useImperativeAlertDialog hook: call alert.show(options) + render alert.element in tree.',
     bestPractices: [
       {guidance: true, description: 'Make action button label specific: "Delete project" > "OK"/"Confirm".'},
       {guidance: true, description: 'Describe consequences in description so user knows outcome before confirming.'},
+      {guidance: true, description: 'Keep cancel first: it takes initial focus, so least destructive choice is preselected.'},
       {guidance: false, description: 'Use AlertDialog for non-destructive actions; use standard Dialog instead.'},
+      {guidance: false, description: 'Rely on color alone for danger; the action label should say what happens.'},
+      {guidance: false, description: 'Close from onAction before work finishes; hold open w/ isActionLoading, call onOpenChange(false) when it settles.'},
     ],
   },
 };

package/src/AlertDialog/AlertDialog.test.tsx

@@ -10,8 +10,10 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {AlertDialog} from './AlertDialog';
+import {useImperativeAlertDialog} from './useImperativeAlertDialog';
 
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = vi.fn(function (
@@ -111,4 +113,209 @@ describe('AlertDialog', () => {
     render(<AlertDialog {...defaultProps} />);
     expect(screen.getByText('Cancel')).toBeInTheDocument();
   });
+
+  describe('keyboard', () => {
+    it('calls onOpenChange(false) on Escape', async () => {
+      const onOpenChange = vi.fn();
+      render(<AlertDialog {...defaultProps} onOpenChange={onOpenChange} />);
+      fireEvent.keyDown(screen.getByRole('alertdialog'), {key: 'Escape'});
+      await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(false));
+    });
+
+    it('does not call onAction on Escape', () => {
+      const onAction = vi.fn();
+      render(<AlertDialog {...defaultProps} onAction={onAction} />);
+      fireEvent.keyDown(screen.getByRole('alertdialog'), {key: 'Escape'});
+      expect(onAction).not.toHaveBeenCalled();
+    });
+
+    it('activates cancel with Enter', async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      render(<AlertDialog {...defaultProps} onOpenChange={onOpenChange} />);
+      screen.getByRole('button', {name: 'Cancel'}).focus();
+      await user.keyboard('{Enter}');
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+
+    it('activates the action button with Space', async () => {
+      const user = userEvent.setup();
+      const onAction = vi.fn();
+      render(<AlertDialog {...defaultProps} onAction={onAction} />);
+      screen.getByRole('button', {name: 'Delete'}).focus();
+      await user.keyboard(' ');
+      expect(onAction).toHaveBeenCalled();
+    });
+
+    it('reaches both buttons by Tab, cancel first', async () => {
+      const user = userEvent.setup();
+      render(<AlertDialog {...defaultProps} />);
+      const cancel = screen.getByRole('button', {name: 'Cancel'});
+      const action = screen.getByRole('button', {name: 'Delete'});
+      cancel.focus();
+      expect(cancel).toHaveFocus();
+      await user.tab();
+      expect(action).toHaveFocus();
+    });
+  });
+
+  describe('focus', () => {
+    it('marks cancel as the initial focus target', () => {
+      render(<AlertDialog {...defaultProps} />);
+      // Dialog focuses [data-autofocus] itself after showModal(), so the
+      // contract this component owns is which element carries the attribute.
+      expect(screen.getByRole('button', {name: 'Cancel'})).toHaveAttribute(
+        'data-autofocus',
+      );
+      expect(screen.getByRole('button', {name: 'Delete'})).not.toHaveAttribute(
+        'data-autofocus',
+      );
+    });
+
+    it('keeps the initial focus target on the least destructive action', () => {
+      render(<AlertDialog {...defaultProps} cancelLabel="Never mind" />);
+      expect(screen.getByRole('button', {name: 'Never mind'})).toHaveAttribute(
+        'data-autofocus',
+      );
+    });
+
+    it('returns focus to the trigger when it closes', async () => {
+      const trigger = document.createElement('button');
+      trigger.textContent = 'Open';
+      document.body.appendChild(trigger);
+      trigger.focus();
+
+      const {rerender} = render(<AlertDialog {...defaultProps} />);
+      rerender(<AlertDialog {...defaultProps} isOpen={false} />);
+
+      await waitFor(() => expect(trigger).toHaveFocus());
+      trigger.remove();
+    });
+
+    it('does not disable the cancel button while the action is loading', () => {
+      render(<AlertDialog {...defaultProps} isActionLoading />);
+      expect(screen.getByRole('button', {name: 'Cancel'})).toBeEnabled();
+    });
+  });
+
+  describe('aria', () => {
+    it('marks the action button busy while loading', () => {
+      render(<AlertDialog {...defaultProps} isActionLoading />);
+      expect(screen.getByRole('button', {name: /Delete/})).toHaveAttribute(
+        'aria-busy',
+        'true',
+      );
+    });
+
+    it('is a modal alertdialog', () => {
+      render(<AlertDialog {...defaultProps} />);
+      expect(screen.getByRole('alertdialog')).toHaveAttribute(
+        'aria-modal',
+        'true',
+      );
+    });
+
+    describe('the inline preview path', () => {
+      it('does not claim the alertdialog role', () => {
+        render(<AlertDialog {...defaultProps} isInline />);
+        expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+      });
+
+      it('exposes a named group instead, with no aria-modal', () => {
+        render(<AlertDialog {...defaultProps} isInline />);
+        const group = screen.getByRole('group', {name: 'Delete item?'});
+        expect(group).not.toHaveAttribute('aria-modal');
+        const describedBy = group.getAttribute('aria-describedby');
+        expect(describedBy).toBeTruthy();
+        expect(document.getElementById(describedBy!)).toHaveTextContent(
+          'This action cannot be undone.',
+        );
+      });
+    });
+  });
+});
+
+describe('useImperativeAlertDialog', () => {
+  const noop = () => {};
+
+  function Harness({onAction = noop}: {onAction?: () => unknown}) {
+    const alert = useImperativeAlertDialog();
+    return (
+      <>
+        <button
+          type="button"
+          onClick={() =>
+            alert.show({
+              title: 'Delete item?',
+              description: 'This action cannot be undone.',
+              actionLabel: 'Delete',
+              onAction,
+            })
+          }>
+          Open
+        </button>
+        <button type="button" onClick={alert.hide}>
+          Close it
+        </button>
+        <span data-testid="is-open">{String(alert.isOpen)}</span>
+        {alert.element}
+      </>
+    );
+  }
+
+  it('renders nothing until show is called', () => {
+    render(<Harness />);
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('shows the dialog with the given options', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+    expect(screen.getByText('Delete item?')).toBeInTheDocument();
+    expect(
+      screen.getByText('This action cannot be undone.'),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('true');
+  });
+
+  it('hides on hide()', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Close it'}));
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('closes when the dialog cancels', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Cancel'}));
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('forwards onAction and leaves closing to the caller', async () => {
+    const user = userEvent.setup();
+    const onAction = vi.fn();
+    render(<Harness onAction={onAction} />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Delete'}));
+    expect(onAction).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+  });
+
+  it('can be shown again after being hidden', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Close it'}));
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('true');
+  });
 });

package/src/AlertDialog/AlertDialog.tsx

@@ -39,7 +39,8 @@ export interface AlertDialogProps extends BaseProps<HTMLDialogElement> {
 
   /**
    * Renders alert dialog content inline without modal behavior.
-   * For documentation previews and showcases only.
+   * For documentation previews and showcases only. The inline path is not a
+   * modal, so it renders `role="group"` rather than `role="alertdialog"`.
    * @default false
    */
   isInline?: boolean;
@@ -100,9 +101,16 @@ export interface AlertDialogProps extends BaseProps<HTMLDialogElement> {
 /**
  * A confirmation dialog for destructive or irreversible actions.
  *
+ * Implements the WAI-ARIA APG Alert Dialog pattern:
+ * https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/
+ *
  * Uses `role="alertdialog"` and requires explicit user action to dismiss.
  * Cannot be dismissed by clicking outside. Escape key triggers cancel.
- * Initial focus goes to the cancel button (least destructive action).
+ * Initial focus goes to the cancel button (least destructive action), pinned
+ * with `data-autofocus` so it survives any change to the footer's order.
+ *
+ * The `isInline` preview path is not modal, so it renders `role="group"`
+ * instead — the alertdialog role would promise modality it does not have.
  *
  * @example
  * ```
@@ -153,7 +161,12 @@ export function AlertDialog({
       onOpenChange={onOpenChange}
       width={width}
       purpose="form"
-      role="alertdialog"
+      // `alertdialog` is a modal role: it promises an interruption the user
+      // has to deal with, a focus trap, and an inert page behind it. The
+      // inline path renders a plain always-present div with none of that, so
+      // the role would misdescribe it. `group` keeps the title and
+      // description associated with a container without claiming a dialog.
+      role={isInline ? 'group' : 'alertdialog'}
       aria-labelledby={titleId}
       aria-describedby={descriptionId}
       {...mergeProps(themeProps('alert-dialog'), {className, style})}
@@ -177,6 +190,11 @@ export function AlertDialog({
                 variant="ghost"
                 label={cancelLabel}
                 onClick={handleCancel}
+                // Dialog focuses [data-autofocus] itself after showModal(),
+                // because React's autoFocus runs during commit while the
+                // dialog is still invisible. Cancel is the least destructive
+                // choice, so it is the one that should be preselected.
+                data-autofocus
               />
               <Button
                 variant={actionVariant}

package/src/AppShell/AppShell.doc.mjs

@@ -14,8 +14,19 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Choose the right height: use "fill" for dashboards with internal scrolling and "auto" for pages that grow with content.'},
       {guidance: true, description: 'Set `contentPadding` based on content type: 4 for forms and settings, 0 for tables and dashboards.'},
+      {guidance: true, description: 'Give every nav slot an accessible name. AppShell renders TopNav and SideNav as separate navigation landmarks, and a screen reader lists them by name, so pass `label` to each one.'},
+      {guidance: true, description: 'Start the page heading inside `children`. AppShell owns the skip link, the banner landmark and the main landmark, but it renders no heading, so the first heading in the content area is the page h1.'},
       {guidance: false, description: "Nest one AppShell inside another; it's the outermost layout frame."},
       {guidance: false, description: 'Use for sub-page layouts; use Layout for content areas within AppShell.'},
+      {guidance: false, description: 'Add your own skip link or <main> element. AppShell already renders both, and a second main landmark makes the first ambiguous.'},
+    ],
+    anatomy: [
+      {name: 'Skip link', required: true, description: 'First focusable element on the page. Visually hidden until focused, then moves focus to the main content area.'},
+      {name: 'Banner', required: false, description: 'The banner slot, for system-wide announcements. Renders above the top nav, inside the banner landmark.'},
+      {name: 'Top navigation', required: false, description: 'The topNav slot, typically TopNav. Below the mobile breakpoint it becomes a compact bar carrying the nav toggle.'},
+      {name: 'Side navigation', required: false, description: 'The sideNav slot, typically SideNav. Inline above the breakpoint, moved into the mobile drawer below it.'},
+      {name: 'Main content', required: true, description: 'children, rendered in the main landmark. Scrolls internally when height is fill, and with the page when it is auto.'},
+      {name: 'Mobile nav drawer', required: false, description: 'Generated below the breakpoint from the nav slots unless mobileNav disables or replaces it. A modal dialog: it traps focus and returns focus to the toggle on close.'},
     ],
   },
   props: [

package/src/AppShell/AppShell.test.tsx

@@ -19,11 +19,13 @@ import {
   afterEach,
 } from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {AppShell} from './AppShell';
 import {InternationalizationProvider} from '../i18n';
 import {MobileNav} from '../MobileNav';
 import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
 import {TopNav, TopNavHeading, TopNavItem} from '../TopNav';
+import {useAppShellMobile} from './AppShellMobileContext';
 
 // jsdom doesn't implement showModal/close on <dialog>, so we mock them
 beforeAll(() => {
@@ -778,4 +780,141 @@ describe('AppShell', () => {
     expect(ref).toHaveBeenCalled();
     expect(ref.mock.calls[0][0]).toBe(screen.getByTestId('shell'));
   });
+  // ===========================================================================
+  // Keyboard operation
+  //
+  // The focus TRAP and focus RESTORE contracts of the drawer are native
+  // <dialog> behaviour and cannot be asserted here: jsdom has no dialog
+  // implementation, so this file shims showModal()/close() with an `open`
+  // attribute. Those two were verified in Chromium instead. What is asserted
+  // here is everything the shim can still prove: the keyboard path to each
+  // control, and the ARIA wiring between the toggle and the drawer.
+  // ===========================================================================
+
+  it('reaches the skip link with Tab and moves focus to main with Enter', async () => {
+    const user = userEvent.setup();
+    render(
+      <AppShell topNav={<TopNav label="Main navigation" />}>
+        <div>Content</div>
+      </AppShell>,
+    );
+
+    await user.tab();
+    const skipLink = screen.getByTestId('skip-to-content');
+    expect(skipLink).toHaveFocus();
+
+    await user.keyboard('{Enter}');
+    expect(screen.getByRole('main')).toHaveFocus();
+  });
+
+  it('opens the mobile drawer from the keyboard and points the toggle at it', async () => {
+    mockMql = createMockMatchMedia(true);
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+    const user = userEvent.setup();
+
+    render(
+      <AppShell sideNav={<TestSideNav />}>
+        <div>Content</div>
+      </AppShell>,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'Open navigation'});
+    expect(toggle).toHaveAttribute('aria-expanded', 'false');
+
+    toggle.focus();
+    await user.keyboard('{Enter}');
+
+    expect(toggle).toHaveAttribute('aria-expanded', 'true');
+    const drawer = screen.getByRole('dialog', {hidden: true});
+    // aria-controls has to name the drawer that actually opened, or a screen
+    // reader cannot follow the toggle to it.
+    expect(toggle.getAttribute('aria-controls')).toBe(drawer.id);
+    expect(drawer.id).toBeTruthy();
+  });
+
+  // ===========================================================================
+  // Banner landmark on the mobile top bar
+  // ===========================================================================
+
+  it('exposes the mobile top bar as a banner landmark in a sidenav-only layout', () => {
+    mockMql = createMockMatchMedia(true);
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+    render(
+      <AppShell sideNav={<TestSideNav />}>
+        <div>Content</div>
+      </AppShell>,
+    );
+
+    // Same landmark structure as the topNav layout: one banner region holding
+    // the top bar, whichever nav slots the page happens to fill.
+    expect(screen.getByRole('banner')).toBeInTheDocument();
+  });
+
+  it('renders exactly one banner landmark when a banner slot joins the mobile top bar', () => {
+    mockMql = createMockMatchMedia(true);
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+    render(
+      <AppShell banner={<div>Announcement</div>} sideNav={<TestSideNav />}>
+        <div>Content</div>
+      </AppShell>,
+    );
+
+    expect(screen.getAllByRole('banner')).toHaveLength(1);
+  });
+
+  // ===========================================================================
+  // useAppShellMobile
+  // ===========================================================================
+
+  function MobileProbe() {
+    const {isMobile, isMobileNavOpen, isMobileNavEnabled, mobileNavId} =
+      useAppShellMobile();
+    return (
+      <span data-testid="probe">
+        {JSON.stringify({
+          isMobile,
+          isMobileNavOpen,
+          isMobileNavEnabled,
+          hasId: mobileNavId != null,
+        })}
+      </span>
+    );
+  }
+
+  it('useAppShellMobile is inert outside an AppShell', () => {
+    render(<MobileProbe />);
+    expect(JSON.parse(screen.getByTestId('probe').textContent)).toEqual({
+      isMobile: false,
+      isMobileNavOpen: false,
+      isMobileNavEnabled: false,
+      hasId: false,
+    });
+  });
+
+  it('useAppShellMobile reports the shell mobile state and drawer id', async () => {
+    mockMql = createMockMatchMedia(true);
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+    const user = userEvent.setup();
+
+    render(
+      <AppShell sideNav={<TestSideNav />}>
+        <MobileProbe />
+      </AppShell>,
+    );
+
+    expect(JSON.parse(screen.getByTestId('probe').textContent)).toEqual({
+      isMobile: true,
+      isMobileNavOpen: false,
+      isMobileNavEnabled: true,
+      hasId: true,
+    });
+
+    await user.click(screen.getByRole('button', {name: 'Open navigation'}));
+
+    expect(
+      JSON.parse(screen.getByTestId('probe').textContent).isMobileNavOpen,
+    ).toBe(true);
+  });
 });

package/src/AppShell/AppShell.tsx

@@ -51,6 +51,7 @@ import type {AppShellMobileContextValue} from './AppShellMobileContext';
 import type {SpacingStep} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps, mergeRefs, isRenderable} from '../utils';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
 import {themeProps} from '../utils/themeProps';
@@ -217,7 +218,7 @@ export interface AppShellProps extends BaseProps<HTMLDivElement> {
    * <AppShell mobileNav={{ hasToggle: false }}>
    *   <MobileNavToggle />
    * </AppShell>
-   * <AppShell mobileNav={<MobileNav title="Menu">...</MobileNav>} />
+   * <AppShell mobileNav={<MobileNav header="Menu">...</MobileNav>} />
    * <AppShell mobileNav={false} />
    * ```
    */
@@ -409,8 +410,8 @@ const styles = stylex.create({
     flexShrink: 0,
     overflow: 'clip',
     position: 'sticky',
-    top: 'var(--appshell-header-height, 0px)',
-    height: 'calc(100dvh - var(--appshell-header-height, 0px))',
+    top: 'var(--_app-shell-header-height, 0px)',
+    height: 'calc(100dvh - var(--_app-shell-header-height, 0px))',
     // Ensure children (LayoutPanel → SideNav) fill the sticky container
     display: 'flex',
     flexDirection: 'column',
@@ -441,7 +442,7 @@ const styles = stylex.create({
  *   topNav={<TopNav label="Navigation" heading={<TopNavHeading heading="My App" />} />}
  *   sideNav={<SideNav>{navSections}</SideNav>}
  *   mobileNav={
- *     <MobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} title="My App">
+ *     <MobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} header="My App">
  *       {navSections}
  *     </MobileNav>
  *   }>
@@ -512,14 +513,19 @@ export function AppShell({
   const [uncontrolledMobileOpen, setUncontrolledMobileOpen] = useState(false);
   const isMobileNavOpen = mobileNavConfig?.isOpen ?? uncontrolledMobileOpen;
 
+  const mobileNavOnOpenChange = mobileNavConfig?.onOpenChange;
   const setMobileNavOpen = useCallback(
     (open: boolean) => {
       if (!mobileNavIsControlled) {
         setUncontrolledMobileOpen(open);
       }
-      mobileNavConfig?.onOpenChange?.(open);
+      mobileNavOnOpenChange?.(open);
     },
-    [mobileNavIsControlled, mobileNavConfig],
+    // Depend on the callback itself, not on the config object: the documented
+    // usage is an inline `mobileNav={{isOpen, onOpenChange}}` literal, which is
+    // a new object every render and would otherwise churn this callback and the
+    // context value memo built from it on every render of the shell.
+    [mobileNavIsControlled, mobileNavOnOpenChange],
   );
 
   // Move focus to the main content container when the skip link is activated.
@@ -577,7 +583,7 @@ export function AppShell({
 
     const updateHeight = () => {
       const height = headerEl.getBoundingClientRect().height;
-      shellEl.style.setProperty('--appshell-header-height', `${height}px`);
+      shellEl.style.setProperty('--_app-shell-header-height', `${height}px`);
     };
 
     observeResize(headerEl, () => updateHeight());
@@ -669,20 +675,19 @@ export function AppShell({
       </LayoutHeader>
     ) : undefined;
 
-  const headerContent =
-    headerInner != null ? (
-      <div
-        ref={headerRef}
-        // Top-level banner landmark for the header region (topNav + banner).
-        // Safe here: the wrapper is never nested inside main/nav/other landmarks.
-        role="banner"
-        {...mergeProps(
-          themeProps('app-shell-header', {variant}),
-          stylex.props(navAreaStyle, isAuto && styles.headerSticky),
-        )}>
-        {headerInner}
-      </div>
-    ) : undefined;
+  const headerContent = isRenderable(headerInner) ? (
+    <div
+      ref={headerRef}
+      // Top-level banner landmark for the header region (topNav + banner).
+      // Safe here: the wrapper is never nested inside main/nav/other landmarks.
+      role="banner"
+      {...mergeProps(
+        themeProps('app-shell-header', {variant}),
+        stylex.props(navAreaStyle, isAuto && styles.headerSticky),
+      )}>
+      {headerInner}
+    </div>
+  ) : undefined;
 
   // =========================================================================
   // Build sideNav content
@@ -760,6 +765,11 @@ export function AppShell({
   const autoMobileTopBar =
     shouldShowAutoToggle && !hasTopNav && hasSideNav ? (
       <div
+        // Banner landmark for the mobile top bar, so the sidenav-only layout
+        // exposes the same landmark structure as the topNav one. Only when
+        // there is no headerContent: a banner slot with no topNav renders both,
+        // and two sibling banner regions is worse than the one this restores.
+        role={headerContent == null ? 'banner' : undefined}
         {...mergeProps(
           themeProps('app-shell-header', {variant}),
           stylex.props(navAreaStyle, isAuto && styles.headerSticky),
@@ -805,7 +815,7 @@ export function AppShell({
         <a
           href={`#${MAIN_CONTENT_ID}`}
           onClick={handleSkipLinkClick}
-          {...stylex.props(styles.skipLink)}
+          {...focusOutlineProps.focusVisible(styles.skipLink)}
           data-testid="skip-to-content">
           {t('@astryx.appShell.skipToContent')}
         </a>