@astryxdesign/core 0.1.0 → 0.1.1-canary.080d887

package/src/Icon/Icon.doc.mjs

@@ -7,6 +7,14 @@ export const docs = {
   displayName: 'Icon',
   category: 'Content',
   keywords: ["icon","svg","glyph","symbol","pictogram","graphic","vector"],
+  playground: {
+    // `icon` is required and its type can't be auto-generated, so the
+    // properties-tab preview showed "Missing: icon". Seed a valid semantic
+    // icon name so the interactive preview renders.
+    defaults: {
+      icon: 'search',
+    },
+  },
   props: [
     {
       name: 'icon',
@@ -17,7 +25,7 @@ export const docs = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: 'Color variant mapped to XDS icon color tokens.',
+      description: 'Color variant mapped to Astryx icon color tokens.',
       default: "'inherit'",
     },
     {
@@ -62,7 +70,7 @@ export const docsZh = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: '映射到 XDS 图标颜色令牌的颜色变体。',
+      description: '映射到 Astryx 图标颜色令牌的颜色变体。',
       default: "'inherit'",
     },
     {
@@ -96,7 +104,7 @@ export const docsZh = {
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
   description:
-    'Renders icons w/ XDS design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
+    'Renders icons w/ Astryx design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
   usage: {
     description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
     bestPractices: [
@@ -113,7 +121,7 @@ export const docsDense = {
   },
   propDescriptions: {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
-    color: 'Color variant mapped to XDS icon color tokens.',
+    color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
   },
 };

package/src/Item/Item.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across XDS. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
+      'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across Astryx. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
     bestPractices: [
       {guidance: true, description: 'Use named slots (startContent, label, description, endContent) for the common layout. These cover the 80% case.'},
       {guidance: true, description: 'Use density="compact" for menus and dense lists, "balanced" for standard rows, and "spacious" for roomier layouts.'},
@@ -104,7 +104,7 @@ export const docsZh = {
   ],
   usage: {
     description:
-      '通用项目原语，统一 XDS 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
+      '通用项目原语，统一 Astryx 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
     bestPractices: [
       {guidance: true, description: '使用命名插槽（startContent、label、description、endContent）处理常见布局。'},
       {guidance: true, description: '菜单和密集列表使用 density="compact"，标准行使用 "balanced"，宽松布局使用 "spacious"。'},

package/src/Kbd/Kbd.tsx

@@ -45,7 +45,7 @@ const styles = stylex.create({
     backgroundColor: colorVars['--color-neutral'],
     borderBottomWidth: '2px',
     borderBottomStyle: 'solid',
-    borderBottomColor: colorVars['--color-border'],
+    borderBottomColor: colorVars['--color-border-emphasized'],
     color: colorVars['--color-text-secondary'],
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-supporting-size'],
@@ -146,14 +146,7 @@ export interface KbdProps extends BaseProps<HTMLSpanElement> {
  * <Kbd keys="mod+k" />
  * ```
  */
-export function Kbd({
-  keys,
-  ref,
-  xstyle,
-  className,
-  style,
-  ...rest
-}: KbdProps) {
+export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
   const isMac = useSyncExternalStore(
     subscribeToPlatformChanges,
     detectMac,

package/src/Layer/useLayer.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
       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.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. 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.',
     },
   ],
   usage: {
@@ -95,6 +95,11 @@ export const docs = {
         description:
           'Build on higher-level components like Popover, HoverCard, and Tooltip for common overlay patterns.',
       },
+      {
+        guidance: true,
+        description:
+          'Rely on the Popover API top layer to escape ancestor clipping and stacking — render the layer inline (no portal) so it inherits the trigger\u2019s theme cascade and keeps a natural focus order. Use `as: "span"` when the layer must be valid inside inline contexts like a paragraph.',
+      },
       {
         guidance: false,
         description:
@@ -125,7 +130,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.',
+    render: 'renders popover element; pass placement/alignment or x/y. Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
   },
   usage: {
     description:

package/src/Layer/useLayer.tsx

@@ -79,6 +79,19 @@ export interface ContextRenderProps {
    * Merged after StyleX and anchor positioning styles.
    */
   style?: React.CSSProperties;
+  /**
+   * HTML tag to render the popover container as.
+   *
+   * Defaults to `'div'`. Pass `'span'` when the layer must render inline-safe
+   * markup — e.g. a `HoverCard` wrapping inline text inside a `<p>`. A `<span>`
+   * is phrasing content, so it stays put in the DOM tree instead of being
+   * reparented out of a paragraph by the HTML parser, which keeps server and
+   * client markup identical. The Popover API and CSS anchor positioning work
+   * the same on either tag.
+   *
+   * @default 'div'
+   */
+  as?: 'div' | 'span';
 }
 
 /**
@@ -369,6 +382,7 @@ export function useLayer(
         xstyle,
         className: extraClassName,
         style: extraStyle,
+        as: Container = 'div',
       } = props || {};
 
       // CSS anchor positioning (dynamic, not in StyleX)
@@ -383,15 +397,18 @@ export function useLayer(
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;
 
+      // Render as the requested tag. A `span` keeps the layer phrasing content
+      // so it is valid (and stays put on hydration) inside inline contexts like
+      // a `<p>`; `div` remains the default for block layers.
       return (
-        <div
+        <Container
           ref={popoverRefCallback}
           id={id}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
           style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}>
           {children}
-        </div>
+        </Container>
       );
     },
     [anchorId, id, lightDismiss, popoverRefCallback],

package/src/Layout/Layout.doc.mjs

@@ -29,7 +29,8 @@ export const docs = {
     {
       name: 'content',
       type: 'ReactNode',
-      description: 'Main content area (center).',
+      description:
+        'Main content area (center). Children passed to `<Layout>` render here too — `<Layout>{main}</Layout>` is shorthand for `<Layout content={main} />`.',
       slotElements: [
         {
           __element: 'LayoutContent',

package/src/Layout/Layout.tsx

@@ -157,6 +157,16 @@ export interface LayoutProps extends Omit<BaseProps, 'content'> {
    * Inline styles to apply to the root element.
    */
   style?: React.CSSProperties;
+
+  /**
+   * Children are a shorthand for the `content` slot:
+   * `<Layout>{main}</Layout>` is equivalent to `<Layout content={main} />`.
+   * The surrounding zones (`header`/`start`/`end`/`footer`) stay explicit
+   * props. If both `content` and `children` are provided, `content` wins.
+   * Accepting children keeps the natural `<Layout>…</Layout>` form from
+   * rendering a blank shell.
+   */
+  children?: ReactNode;
 }
 
 /**
@@ -222,6 +232,7 @@ function AreaProvider({
  * ```
  */
 export function Layout({
+  children,
   content,
   contentWidth,
   defaultHasDividers,
@@ -237,6 +248,9 @@ export function Layout({
   style,
 }: LayoutProps) {
   const isFill = height === 'fill';
+  // Children are a shorthand for the content slot; an explicit `content` prop
+  // wins when both are provided.
+  const resolvedContent = content ?? children;
 
   const dividerCtxValue = useMemo(
     () => (defaultHasDividers != null ? {defaultHasDividers} : null),
@@ -287,7 +301,7 @@ export function Layout({
             )}>
             <AreaProvider area="start">{start}</AreaProvider>
             <div {...stylex.props(...stackItem({size: 'fill'}))}>
-              <AreaProvider area="content">{content}</AreaProvider>
+              <AreaProvider area="content">{resolvedContent}</AreaProvider>
             </div>
             <AreaProvider area="end">{end}</AreaProvider>
           </div>

package/src/Layout/__tests__/childrenAsContent.test.tsx

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file childrenAsContent.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Verifies Layout renders children as a shorthand for the content slot
+ *   (so the natural `<Layout>…</Layout>` form never renders a blank shell), with
+ *   an explicit `content` prop taking precedence.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Layout} from '../Layout';
+import {LayoutContent} from '../LayoutContent';
+
+describe('Layout children-as-content', () => {
+  it('renders nested children in the content slot', () => {
+    render(
+      <Layout>
+        <LayoutContent>
+          <span data-testid="body">Body</span>
+        </LayoutContent>
+      </Layout>,
+    );
+    expect(screen.getByTestId('body')).toBeInTheDocument();
+  });
+
+  it('renders bare children (no LayoutContent wrapper) too', () => {
+    render(
+      <Layout>
+        <span data-testid="bare">Bare</span>
+      </Layout>,
+    );
+    expect(screen.getByTestId('bare')).toBeInTheDocument();
+  });
+
+  it('lets an explicit content prop win over children', () => {
+    render(
+      <Layout content={<span data-testid="slot">Slot</span>}>
+        <span data-testid="child">Child</span>
+      </Layout>,
+    );
+    expect(screen.getByTestId('slot')).toBeInTheDocument();
+    expect(screen.queryByTestId('child')).not.toBeInTheDocument();
+  });
+
+  it('still supports the canonical slot-only API', () => {
+    render(
+      <Layout
+        content={
+          <LayoutContent>
+            <span data-testid="canon">Canonical</span>
+          </LayoutContent>
+        }
+      />,
+    );
+    expect(screen.getByTestId('canon')).toBeInTheDocument();
+  });
+});

package/src/Lightbox/Lightbox.doc.mjs

@@ -30,7 +30,6 @@ export const docs = {
       name: 'index',
       type: 'number',
       description: 'Current index in gallery mode (when media is an array).',
-      default: '0',
     },
     {
       name: 'onIndexChange',
@@ -94,7 +93,6 @@ export const docsZh = {
       name: 'index',
       type: 'number',
       description: '画廊模式中当前索引。',
-      default: '0',
     },
     {
       name: 'onIndexChange',

package/src/Link/Link.doc.mjs

@@ -99,7 +99,7 @@ export const docs = {
       isHiddenFromOverview: true,
       displayName: 'Link Provider',
       description:
-        'Provider that sets the default link component for all XDS link-rendering components in the subtree. ' +
+        'Provider that sets the default link component for all Astryx link-rendering components in the subtree. ' +
         'Wrap your app root to replace native <a> elements with your framework router (Next.js Link, React Router Link, etc.).',
       props: [
         {
@@ -226,7 +226,7 @@ export const docsZh = {
       isHiddenFromOverview: true,
       displayName: 'Link Provider',
       description:
-        '为子树中所有 XDS 链接组件设置默认链接组件的 Provider。',
+        '为子树中所有 Astryx 链接组件设置默认链接组件的 Provider。',
       props: [
         {
           name: 'component',
@@ -310,7 +310,7 @@ export const docsDense = {
       isHiddenFromOverview: true,
       displayName: 'Link Provider',
       description:
-        'Provider setting default link component for all XDS links in subtree.',
+        'Provider setting default link component for all Astryx links in subtree.',
       propDescriptions: {
         component: 'Component for all link elements',
         children: 'Subtree',

package/src/Link/LinkProvider.doc.mjs

@@ -10,7 +10,7 @@ export const docs = {
   isHiddenFromOverview: true,
   keywords: ['link', 'provider', 'router', 'nextjs', 'client-side-routing'],
   usage: {
-    description: 'Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+    description: 'Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
   },
   props: [
     {name: 'component', type: 'LinkComponentType', required: true, description: 'Link component to use for all link elements in the subtree (e.g. Next.js Link).'},
@@ -20,9 +20,9 @@ export const docs = {
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+  description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
   usage: {
-    description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+    description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
   },
   propDescriptions: {
     component: 'link component for all link elements in subtree (e.g. Next.js Link)',

package/src/Markdown/Markdown.doc.mjs

@@ -75,6 +75,7 @@ export const docs = {
       type: 'number | string',
       description:
         'Max width for prose content (paragraphs, headings, lists, blockquotes). Tables and code blocks are unconstrained and can expand to the full container width. Use for readable line lengths in wide layouts.',
+      default: '680',
     },
     {
       name: 'contentAlign',
@@ -131,7 +132,7 @@ export const docs = {
   },
   usage: {
     description:
-      'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+      'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
@@ -245,6 +246,7 @@ export const docsZh = {
       type: 'number | string',
       description:
         '正文内容的最大宽度（段落、标题、列表、引用块）。表格和代码块不受限制，可扩展到完整容器宽度。用于在宽布局中保持可读行长。',
+      default: '680',
     },
     {
       name: 'contentAlign',
@@ -294,7 +296,7 @@ export const docsZh = {
   },
   usage: {
     description:
-      'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+      'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
@@ -306,10 +308,10 @@ export const docsZh = {
 
 export const docsDense = {
   description:
-    'Renders markdown string as XDS-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
+    'Renders markdown string as Astryx-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
   usage: {
     description:
-      'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+      'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },

package/src/Markdown/Markdown.test.tsx

@@ -22,9 +22,16 @@ describe('Markdown', () => {
     expect(screen.getByText('Heading 2').tagName).toBe('H2');
   });
 
-  it('renders paragraphs', () => {
+  it('renders paragraphs as block <div> (never <p>) for composition safety', () => {
     render(<Markdown>{'Hello world'}</Markdown>);
-    expect(screen.getByText('Hello world').tagName).toBe('P');
+    // Markdown paragraphs render as <div> so block-level inline content
+    // (images, custom inline components) never trips the phrasing-content
+    // trap that a <p> would impose. role="paragraph" re-exposes the paragraph
+    // role to assistive tech without the <p> hazard. Consumers who want a real
+    // <p> element can pass `components={{paragraph: 'p'}}`.
+    const para = screen.getByText('Hello world');
+    expect(para.tagName).toBe('DIV');
+    expect(para).toHaveAttribute('role', 'paragraph');
   });
 
   it('renders inline display without block wrappers', () => {
@@ -201,9 +208,7 @@ describe('Markdown', () => {
   });
 
   it('shows streaming cursor when isStreaming is true', () => {
-    const {container} = render(
-      <Markdown isStreaming>{'Hello'}</Markdown>,
-    );
+    const {container} = render(<Markdown isStreaming>{'Hello'}</Markdown>);
     // Streaming mode parses incrementally but no cursor element
     expect(container.querySelector('[role="document"]')).toBeInTheDocument();
   });
@@ -243,9 +248,7 @@ describe('Markdown', () => {
 
   it('sanitizes data: URLs in images', () => {
     const {container} = render(
-      <Markdown>
-        {'![xss](data:text/html,<script>alert(1)</script>)'}
-      </Markdown>,
+      <Markdown>{'![xss](data:text/html,<script>alert(1)</script>)'}</Markdown>,
     );
     const img = container.querySelector('img');
     expect(img).toBeNull();
@@ -435,9 +438,7 @@ describe('inlinePlugins', () => {
       },
     };
     const {container} = render(
-      <Markdown inlinePlugins={[plugin]}>
-        {'See TAG:important here'}
-      </Markdown>,
+      <Markdown inlinePlugins={[plugin]}>{'See TAG:important here'}</Markdown>,
     );
     const tag = container.querySelector('[data-testid="tag-match"]');
     expect(tag).toBeInTheDocument();
@@ -446,9 +447,7 @@ describe('inlinePlugins', () => {
 
   it('renders identically when no inlinePlugins are provided', () => {
     const withPlugins = render(
-      <Markdown inlinePlugins={[]}>
-        {'Hello **world** and `code`'}
-      </Markdown>,
+      <Markdown inlinePlugins={[]}>{'Hello **world** and `code`'}</Markdown>,
     );
     const withoutPlugins = render(
       <Markdown>{'Hello **world** and `code`'}</Markdown>,
@@ -481,9 +480,7 @@ describe('inlinePlugins', () => {
 
     it('renders bare https URLs as links when autolink="gfm"', () => {
       const {container} = render(
-        <Markdown autolink="gfm">
-          {'see https://example.com here'}
-        </Markdown>,
+        <Markdown autolink="gfm">{'see https://example.com here'}</Markdown>,
       );
       const link = container.querySelector('a');
       expect(link).not.toBeNull();
@@ -503,9 +500,7 @@ describe('inlinePlugins', () => {
 
     it('renders bare emails with mailto: href', () => {
       const {container} = render(
-        <Markdown autolink="gfm">
-          {'ping user@example.com please'}
-        </Markdown>,
+        <Markdown autolink="gfm">{'ping user@example.com please'}</Markdown>,
       );
       const link = container.querySelector('a');
       expect(link).not.toBeNull();
@@ -515,9 +510,7 @@ describe('inlinePlugins', () => {
 
     it('does not autolink URLs inside code spans', () => {
       const {container} = render(
-        <Markdown autolink="gfm">
-          {'try `https://example.com` here'}
-        </Markdown>,
+        <Markdown autolink="gfm">{'try `https://example.com` here'}</Markdown>,
       );
       expect(container.querySelector('a')).toBeNull();
       expect(container.querySelector('code')).not.toBeNull();
@@ -525,9 +518,7 @@ describe('inlinePlugins', () => {
 
     it('does not autolink URLs inside code blocks', () => {
       const {container} = render(
-        <Markdown autolink="gfm">
-          {'```\nhttps://example.com\n```'}
-        </Markdown>,
+        <Markdown autolink="gfm">{'```\nhttps://example.com\n```'}</Markdown>,
       );
       expect(container.querySelector('a')).toBeNull();
       expect(container.querySelector('pre')).not.toBeNull();

package/src/Markdown/Markdown.tsx

@@ -1113,9 +1113,19 @@ function renderBlock(
       if (ParagraphComp) {
         return <ParagraphComp key={index}>{paraChildren}</ParagraphComp>;
       }
+      // Markdown paragraphs render as <div>, not <p>: inline content can
+      // include block-level nodes (images, custom inline components), and a
+      // <p> would reparent them, desyncing SSR markup from the hydrated DOM.
+      // Block spacing comes from token-based StyleX margins, so the rendered
+      // appearance is unchanged. role="paragraph" re-exposes the paragraph
+      // role in the accessibility tree (a pure ARIA hint — it does not trigger
+      // the parser's block-child reparenting) so prose semantics are preserved
+      // without the <p> composition hazard. Consumers who want a real <p>
+      // element can still pass components={{paragraph: 'p'}}.
       return (
-        <p
+        <div
           key={index}
+          role="paragraph"
           {...stylex.props(
             spacing,
             contentWidthValue != null
@@ -1128,7 +1138,7 @@ function renderBlock(
             isLast && styles.noMarginBlockEnd,
           )}>
           {paraChildren}
-        </p>
+        </div>
       );
     }
     case 'codeblock': {
@@ -1487,7 +1497,7 @@ function renderBlock(
       const safeSrc = sanitizeUrl(node.src);
       if (safeSrc == null) {
         return (
-          <p
+          <div
             key={index}
             {...stylex.props(
               spacing,
@@ -1495,11 +1505,11 @@ function renderBlock(
               isLast && styles.noMarginBlockEnd,
             )}>
             [{node.alt}]
-          </p>
+          </div>
         );
       }
       return (
-        <p
+        <div
           key={index}
           {...stylex.props(
             spacing,
@@ -1507,7 +1517,7 @@ function renderBlock(
             isLast && styles.noMarginBlockEnd,
           )}>
           <img src={safeSrc} alt={node.alt} {...stylex.props(styles.image)} />
-        </p>
+        </div>
       );
     }
   }

package/src/MobileNav/MobileNav.doc.mjs

@@ -43,14 +43,14 @@ export const docs = {
           type: 'number',
           description:
             'Drawer width in pixels. Capped at 85vw to prevent overflow on small screens.',
-          default: '280',
+          default: '320',
         },
         {
           name: 'side',
-          type: "'start' | 'end'",
+          type: "'start' | 'end' | 'auto'",
           description:
-            'Which side the drawer slides from. Start is left in LTR, right in RTL.',
-          default: "'start'",
+            'Which side the drawer slides from. Start is left in LTR, right in RTL. Auto picks a side based on the trigger position.',
+          default: "'auto'",
         },
       ],
     },
@@ -124,14 +124,14 @@ export const docsZh = {
       type: 'number',
       description:
         '抽屉宽度（像素）。上限为 85vw 以防止在小屏幕上溢出。',
-      default: '280',
+      default: '320',
     },
     {
       name: 'side',
-      type: "'start' | 'end'",
+      type: "'start' | 'end' | 'auto'",
       description:
-        '抽屉滑出的方向。在 LTR 布局中 start 为左侧，在 RTL 布局中为右侧。',
-      default: "'start'",
+        '抽屉滑出的方向。在 LTR 布局中 start 为左侧，在 RTL 布局中为右侧。auto 根据触发元素的位置自动选择方向。',
+      default: "'auto'",
     },
   ],
   theming: {

package/src/MobileNav/MobileNav.tsx

@@ -363,8 +363,21 @@ export function MobileNav({
     return () => {
       if (closeTimeoutRef.current) {
         clearTimeout(closeTimeoutRef.current);
+        closeTimeoutRef.current = null;
       }
       document.documentElement.style.overflow = '';
+      // Close the native dialog on teardown if it's still open. Inside AppShell
+      // the drawer is mounted in an <Activity> that switches to mode="hidden"
+      // when the drawer closes; React then runs this cleanup (with a stale
+      // isOpen) instead of re-running the effect with isOpen=false, so the
+      // close branch above never fires. If we leave the <dialog> `open` here,
+      // showModal() is skipped on the next open (the dialog is already open in
+      // the hidden tree) and the drawer can never be re-opened. Closing it
+      // unconditionally on teardown keeps the native dialog state in sync so a
+      // subsequent open cleanly calls showModal() again.
+      if (dialog.open) {
+        dialog.close();
+      }
     };
   }, [isOpen, side]);