Skip to content

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

TypeScript

fix(docsite): give MobileNavToggle preview a mobile AppShell (#4983) (#5042)

AK2192a2834f9d
diff --git a/.changeset/mobilenavtoggle-preview-simulated-mobile-appshell--k9pt.md b/.changeset/mobilenavtoggle-preview-simulated-mobile-appshell--k9pt.md
new file mode 100644
index 0000000000..d50e022bf7
--- /dev/null
+++ b/.changeset/mobilenavtoggle-preview-simulated-mobile-appshell--k9pt.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] MobileNavToggle preview simulates a mobile AppShell instead of an empty stage: new playground.appShellMobile for components that render nothing without AppShell mobile context (#4983)
+@AKnassa
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 6b002c23f2..423c9dee08 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -826,6 +826,7 @@ export interface ElementDescriptor {
export interface PlaygroundConfig {
defaults?: Record<string, unknown>;
overlay?: boolean;
+ appShellMobile?: boolean;
wrapper?: {
component: string;
props?: Record<string, unknown>;
diff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.ts
index 12ee0cb900..5b5fd06cfc 100644
--- a/apps/docsite/src/__tests__/component-preview-state.test.ts
+++ b/apps/docsite/src/__tests__/component-preview-state.test.ts
@@ -2,6 +2,7 @@
import {describe, expect, it, vi} from 'vitest';
import {
+ buildAppShellMobilePreviewContext,
buildInitialState,
buildRuntimePreviewState,
getMissingRequiredProps,
@@ -549,3 +550,35 @@ describe('hasInteractivePlayground', () => {
).toBe(true);
});
});
+
+// ── Simulated mobile AppShell context (#4983) ───────────────────────────────
+// MobileNavToggle reads AppShell mobile context and renders null when the
+// context says the viewport is not mobile (the default outside AppShell), so
+// its Properties preview was an empty stage. `playground.appShellMobile`
+// wraps the preview in a provider built from this value.
+describe('buildAppShellMobilePreviewContext', () => {
+ it('simulates an enabled mobile AppShell so context-gated components render', () => {
+ const value = buildAppShellMobilePreviewContext(false, () => {});
+ expect(value.isMobile).toBe(true);
+ expect(value.isMobileNavEnabled).toBe(true);
+ expect(value.isMobileNavOpen).toBe(false);
+ expect(value.hasAutoToggle).toBe(true);
+ });
+
+ it('wires toggle/open/close back to the provided open-state setter', () => {
+ const onOpenChange = vi.fn();
+
+ const closed = buildAppShellMobilePreviewContext(false, onOpenChange);
+ closed.toggleMobileNav();
+ expect(onOpenChange).toHaveBeenLastCalledWith(true);
+ closed.openMobileNav();
+ expect(onOpenChange).toHaveBeenLastCalledWith(true);
+ closed.closeMobileNav();
+ expect(onOpenChange).toHaveBeenLastCalledWith(false);
+
+ const open = buildAppShellMobilePreviewContext(true, onOpenChange);
+ expect(open.isMobileNavOpen).toBe(true);
+ open.toggleMobileNav();
+ expect(onOpenChange).toHaveBeenLastCalledWith(false);
+ });
+});
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 25719dc6e6..d63ef891dd 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -325,6 +325,18 @@ describe('componentRegistry', () => {
});
});
+ it('MobileNavToggle declares an appShellMobile playground so its preview is not empty (#4983)', () => {
+ const core = components['@astryxdesign/core'];
+ const toggle = core.find(c => c.name === 'MobileNavToggle');
+ expect(toggle).toBeDefined();
+ // The toggle reads AppShell mobile context and renders null without it;
+ // appShellMobile makes the preview provide a simulated mobile context.
+ expect(toggle!.playground?.appShellMobile).toBe(true);
+ // The drawer's overlay playground stays on the MobileNav entry only —
+ // the toggle renders inline and must not inherit the overlay placeholder.
+ expect(toggle!.playground?.overlay).toBeUndefined();
+ });
+
it('dialog-family components keep contained isInline previews, not overlay mode (#3657)', () => {
const core = components['@astryxdesign/core'];
for (const name of ['Dialog', 'AlertDialog', 'CommandPalette']) {
diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
index d2fbde32aa..981796309a 100644
--- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx
+++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
@@ -13,6 +13,7 @@ import {
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {getComponent, resolveValue} from './resolveElements';
+import {AppShellMobileContext} from '@astryxdesign/core/AppShell';
import {Button} from '@astryxdesign/core/Button';
import {Card} from '@astryxdesign/core/Card';
import {Center} from '@astryxdesign/core/Center';
@@ -22,6 +23,7 @@ import {Text} from '@astryxdesign/core/Text';
import {Code} from 'lucide-react';
import {ComponentPreviewTheme} from './ComponentPreviewTheme';
import {
+ buildAppShellMobilePreviewContext,
buildInitialState,
buildRuntimePreviewState,
getMissingRequiredProps,
@@ -75,6 +77,24 @@ class PreviewErrorBoundary extends Component<
}
}
+// Simulated mobile AppShell for `playground.appShellMobile` components:
+// they render null unless AppShell mobile context reports an enabled mobile
+// viewport, which the default context value outside AppShell never does
+// (#4983). Holds the drawer open state so the toggle stays interactive.
+function AppShellMobilePreviewProvider({children}: {children: ReactNode}) {
+ const [isMobileNavOpen, setIsMobileNavOpen] = useState(false);
+ const value = useMemo(
+ () =>
+ buildAppShellMobilePreviewContext(isMobileNavOpen, setIsMobileNavOpen),
+ [isMobileNavOpen],
+ );
+ return (
+ <AppShellMobileContext.Provider value={value}>
+ {children}
+ </AppShellMobileContext.Provider>
+ );
+}
+
function toIdentifierName(name: string): string {
return name
.split(/[^a-zA-Z0-9]+/)
@@ -362,7 +382,21 @@ export function InteractivePreviewStage({
}}>
<PreviewErrorBoundary
resetKeys={[Component, runtimeState, WrapperComponent]}>
- {renderPreview(createElement(Component, runtimeState))}
+ {playground?.appShellMobile === true ? (
+ <AppShellMobilePreviewProvider>
+ <VStack
+ gap={2}
+ style={{alignItems: 'center', textAlign: 'center'}}>
+ {renderPreview(createElement(Component, runtimeState))}
+ <Text type="supporting" color="secondary">
+ Simulated mobile AppShell — in an app this renders only
+ below the mobile breakpoint.
+ </Text>
+ </VStack>
+ </AppShellMobilePreviewProvider>
+ ) : (
+ renderPreview(createElement(Component, runtimeState))
+ )}
{isOverlayPreviewClosed(playground, state) && (
<VStack
gap={2}
diff --git a/apps/docsite/src/components/component-detail/interactiveState.ts b/apps/docsite/src/components/component-detail/interactiveState.ts
index 28edcea501..1cc07af4d2 100644
--- a/apps/docsite/src/components/component-detail/interactiveState.ts
+++ b/apps/docsite/src/components/component-detail/interactiveState.ts
@@ -5,9 +5,12 @@
* Keeps runtime-only defaults (callbacks, mock search sources, descriptor
* resolution) and preview-only controlled callbacks out of the generated JSON
* registries while preserving typed option values from parsed controls.
+ * Also builds the simulated AppShell mobile context for
+ * `playground.appShellMobile` previews.
*/
import {allSyntaxPresets} from '@astryxdesign/core/theme/syntax';
+import type {AppShellMobileContextValue} from '@astryxdesign/core/AppShell';
import {themeObjectsFull} from '../../generated/themeRegistry';
import {
coerceDefault,
@@ -230,6 +233,28 @@ export function isOverlayPreviewClosed(
return playground?.overlay === true && state.isOpen !== true;
}
+/**
+ * Context value for previews of components that read AppShell mobile context
+ * (`playground.appShellMobile`). MobileNavToggle renders null unless the
+ * context reports an enabled mobile viewport — the default value outside
+ * AppShell never does — so the preview simulates one, wiring the drawer open
+ * state back to the provided setter to keep the toggle interactive (#4983).
+ */
+export function buildAppShellMobilePreviewContext(
+ isMobileNavOpen: boolean,
+ onOpenChange: (isOpen: boolean) => void,
+): AppShellMobileContextValue {
+ return {
+ isMobile: true,
+ isMobileNavEnabled: true,
+ isMobileNavOpen,
+ toggleMobileNav: () => onOpenChange(!isMobileNavOpen),
+ openMobileNav: () => onOpenChange(true),
+ closeMobileNav: () => onOpenChange(false),
+ hasAutoToggle: true,
+ };
+}
+
export function getMissingRequiredProps(
knobs: KnobProp[],
state: Record<string, unknown>,
diff --git a/packages/cli/authoring/doctypes/base/type.ts b/packages/cli/authoring/doctypes/base/type.ts
index ae23938c5f..40be6870b3 100644
--- a/packages/cli/authoring/doctypes/base/type.ts
+++ b/packages/cli/authoring/doctypes/base/type.ts
@@ -117,6 +117,14 @@ export interface ComponentPlaygroundConfig {
* the component is visible on load and knobs stay usable, whereas a real
* top-layer modal makes the rest of the page inert (#3657). */
overlay?: boolean;
+ /** The component reads AppShell mobile context and renders nothing
+ * without it (e.g. `MobileNavToggle` returns null unless the context
+ * reports an enabled mobile viewport — the default value outside
+ * AppShell never does). The interactive preview provides a simulated
+ * mobile AppShell context so the stage is not an empty box, keeps the
+ * drawer open state interactive, and notes the simulation under the
+ * rendered component (#4983). */
+ appShellMobile?: boolean;
/** Required parent wrapper for sub-components that depend on a parent
* context provider (e.g. `Tab` calls `useTabListContext()` and throws
* standalone). The preview wraps the component in this parent before
diff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjs
index 4094c704f9..d73c9ab169 100644
--- a/packages/cli/authoring/doctypes/component/component.doc.mjs
+++ b/packages/cli/authoring/doctypes/component/component.doc.mjs
@@ -146,7 +146,7 @@ export const doc = {
name: 'playground',
type: 'ComponentPlaygroundConfig',
description:
- 'Interactive-preview config: initial prop `defaults`, `overlay` for modal-only components, and a `wrapper` for context-dependent sub-components.',
+ 'Interactive-preview config: initial prop `defaults`, `overlay` for modal-only components, `appShellMobile` for components gated on AppShell mobile context, and a `wrapper` for context-dependent sub-components.',
},
{
name: 'props',
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
index c91f14c9e2..6090f5cae4 100644
--- a/packages/core/src/MobileNav/MobileNav.doc.mjs
+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs
@@ -78,6 +78,13 @@ export const docs = {
name: 'MobileNavToggle',
displayName: 'Mobile Nav Toggle',
description: 'Hamburger button that opens/closes the mobile nav drawer. Reads open state from AppShell context automatically: does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
+ // The toggle renders null unless AppShell mobile context reports an
+ // enabled mobile viewport — the default context outside AppShell never
+ // does, so the Properties preview was an empty stage. appShellMobile
+ // has the preview simulate that context instead (#4983).
+ playground: {
+ appShellMobile: true,
+ },
props: [
{
name: 'children',