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.mdnew file mode 100644index 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)+@AKnassadiff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex 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.tsindex 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.tsindex 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.tsxindex 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({}}><PreviewErrorBoundaryresetKeys={[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) && (<VStackgap={2}diff --git a/apps/docsite/src/components/component-detail/interactiveState.ts b/apps/docsite/src/components/component-detail/interactiveState.tsindex 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.tsindex 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 beforediff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjsindex 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.mjsindex 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',