@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

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', () => {
@@ -182,6 +189,17 @@ describe('Markdown', () => {
     expect(document.querySelectorAll('td')).toHaveLength(2);
   });
 
+  it('makes the table scroll wrapper keyboard-focusable', () => {
+    render(<Markdown>{'| A | B |\n| --- | --- |\n| 1 | 2 |'}</Markdown>);
+    const table = document.querySelector('table');
+    expect(table).toBeInTheDocument();
+    // The GFM table's outer overflow wrapper is keyboard-focusable so keyboard
+    // users can horizontally scroll a wide table.
+    const wrapper = table!.closest('[role="region"][tabindex="0"]');
+    expect(wrapper).toBeTruthy();
+    expect(wrapper).toHaveAttribute('aria-label', 'Table');
+  });
+
   it('renders horizontal rules', () => {
     render(<Markdown>{'---'}</Markdown>);
     expect(document.querySelector('hr')).toBeInTheDocument();
@@ -201,9 +219,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 +259,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 +449,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 +458,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 +491,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 +511,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 +521,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 +529,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': {
@@ -1389,6 +1399,11 @@ function renderBlock(
       return (
         <div
           key={index}
+          // Keyboard-focusable so keyboard users can scroll a horizontally
+          // overflowing GFM table.
+          tabIndex={0}
+          role="region"
+          aria-label="Table"
           {...stylex.props(
             styles.tableWrapper,
             spacing,
@@ -1487,7 +1502,7 @@ function renderBlock(
       const safeSrc = sanitizeUrl(node.src);
       if (safeSrc == null) {
         return (
-          <p
+          <div
             key={index}
             {...stylex.props(
               spacing,
@@ -1495,11 +1510,11 @@ function renderBlock(
               isLast && styles.noMarginBlockEnd,
             )}>
             [{node.alt}]
-          </p>
+          </div>
         );
       }
       return (
-        <p
+        <div
           key={index}
           {...stylex.props(
             spacing,
@@ -1507,7 +1522,7 @@ function renderBlock(
             isLast && styles.noMarginBlockEnd,
           )}>
           <img src={safeSrc} alt={node.alt} {...stylex.props(styles.image)} />
-        </p>
+        </div>
       );
     }
   }

package/src/MetadataList/MetadataListItem.doc.mjs

@@ -8,6 +8,10 @@ export const docs = {
   displayName: 'Metadata List Item',
   isHiddenFromOverview: true,
   description: 'A single labeled metadata value within an MetadataList.',
+  playground: {
+    defaults: {label: 'Status', children: 'Active'},
+    wrapper: {component: 'MetadataList'},
+  },
   props: [
     {
       name: 'children',

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]);
 

package/src/MobileNav/MobileNavReopen.test.tsx

@@ -0,0 +1,118 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavReopen.test.tsx
+ * @input Uses vitest, @testing-library/react, AppShell + SideNav
+ * @output Regression test for mobile hamburger nav re-open after close
+ * @position Testing; validates the OOTB AppShell mobile drawer toggle cycle
+ *
+ * Repro for: mobile hamburger nav can be opened and closed once, but cannot
+ * be re-opened after closing.
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  beforeEach,
+  afterEach,
+} from 'vitest';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import {AppShell} from '../AppShell/AppShell';
+import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
+
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal =
+    HTMLDialogElement.prototype.showModal ||
+    function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+    };
+  HTMLDialogElement.prototype.close =
+    HTMLDialogElement.prototype.close ||
+    function (this: HTMLDialogElement) {
+      this.removeAttribute('open');
+    };
+});
+
+class MockResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+vi.stubGlobal('ResizeObserver', MockResizeObserver);
+
+function createMockMatchMedia(matches: boolean) {
+  return {
+    matches,
+    media: '',
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  };
+}
+
+beforeEach(() => {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue(createMockMatchMedia(true)),
+  );
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function TestShell() {
+  return (
+    <AppShell
+      sideNav={
+        <SideNav>
+          <SideNavSection title="Test" isHeaderHidden>
+            <SideNavItem label="Home" />
+          </SideNavSection>
+        </SideNav>
+      }
+      mobileNav={{breakpoint: 'md'}}>
+      <div>Content</div>
+    </AppShell>
+  );
+}
+
+describe('Mobile nav re-open after close (uncontrolled OOTB)', () => {
+  it('can be opened, closed, then opened again', () => {
+    vi.useFakeTimers();
+    try {
+      render(<TestShell />);
+
+      const getDialog = () => screen.getAllByRole('dialog', {hidden: true})[0];
+      const openToggle = () =>
+        screen.getByRole('button', {name: /open navigation/i});
+
+      // 1. Open
+      fireEvent.click(openToggle());
+      expect(getDialog()).toHaveAttribute('open');
+
+      // 2. Close via the drawer's close button
+      fireEvent.click(screen.getByRole('button', {name: /close navigation/i}));
+      // Flush the delayed dialog.close() (slide-out transition)
+      act(() => {
+        vi.advanceTimersByTime(300);
+      });
+      expect(getDialog()).not.toHaveAttribute('open');
+
+      // 3. Open AGAIN — this is the bug: it should re-open
+      fireEvent.click(openToggle());
+      act(() => {
+        vi.advanceTimersByTime(300);
+      });
+      expect(getDialog()).toHaveAttribute('open');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/MoreMenu/MoreMenu.doc.mjs

@@ -46,14 +46,7 @@ export const docs = {
       type: 'boolean',
       description: 'Whether the menu trigger is disabled.',
       default: 'false',
-    },
-    {
-      name: 'hasAutoFocus',
-      type: 'boolean',
-      description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases or documentation previews.',
-      default: 'true',
-    },
-    {
+    },    {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
@@ -126,14 +119,7 @@ export const docsZh = {
       type: 'boolean',
       description: '菜单触发器是否禁用。',
       default: 'false',
-    },
-    {
-      name: 'hasAutoFocus',
-      type: 'boolean',
-      description: '菜单打开时是否自动聚焦第一个菜单项。内联展示或文档预览设为 false。',
-      default: 'true',
-    },
-    {
+    },    {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
@@ -176,7 +162,6 @@ export const docsDense = {
     size: 'Trigger button size.',
     icon: 'Override default three-dot icon. Accepts any ReactNode.',
     isDisabled: 'Whether menu trigger disabled.',
-    hasAutoFocus: 'Auto-focus first item on open; false for showcases.',
     xstyle:
       'StyleX styles for layout customization (margins, positioning, sizing). Must be stylex.create() value.',
   },

package/src/MoreMenu/MoreMenu.tsx

@@ -81,13 +81,6 @@ export interface MoreMenuProps extends Pick<
    */
   onOpenChange?: (isOpen: boolean) => void;
 
-  /**
-   * Whether to auto-focus the first menu item when the menu opens.
-   * Set to `false` for inline showcases or documentation previews.
-   * @default true
-   */
-  hasAutoFocus?: boolean;
-
   /** Test ID for testing frameworks. */
   'data-testid'?: string;
 }
@@ -116,7 +109,6 @@ export function MoreMenu({
   isDisabled = false,
   isMenuOpen,
   onOpenChange,
-  hasAutoFocus,
   xstyle,
   className: classNameProp,
   style,
@@ -149,7 +141,6 @@ export function MoreMenu({
       }}
       items={items}
       hasChevron={false}
-      hasAutoFocus={hasAutoFocus}
       data-testid={testId}
     />
   );

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -112,6 +112,12 @@ export const docs = {
           type: 'boolean',
           description: 'Disables the selector.',
         },
+        {
+          name: 'disabledMessage',
+          type: 'string',
+          description:
+            'Explains why the selector is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled MultiSelector in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        },
         {
           name: 'isLabelHidden',
           type: 'boolean',
@@ -189,6 +195,11 @@ export const docs = {
         guidance: false,
         description: 'Show more than ~20 options without enabling search.',
       },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
@@ -217,6 +228,8 @@ export const docsZh = {
         hasSearch: '是否显示用于过滤选项的搜索输入。',
         searchPlaceholder: '搜索输入的占位文本。',
         isDisabled: '禁用选择器。',
+        disabledMessage:
+          '解释选择器被禁用的原因。与 isDisabled 一起使用时，悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持触发器可聚焦（仍无法激活）。请使用此属性，而不是用 Tooltip 包裹被禁用的选择器。',
         isLabelHidden: '视觉上隐藏标签同时保持其可访问性。',
         description: '标签下方显示的辅助文本。',
         isOptional: '将字段标记为可选。',
@@ -261,6 +274,11 @@ export const docsZh = {
         guidance: false,
         description: 'Show more than ~20 options without enabling search.',
       },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
@@ -301,6 +319,11 @@ export const docsDense = {
         guidance: false,
         description: 'Show more than ~20 options without enabling search.',
       },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   components: [
@@ -324,6 +347,8 @@ export const docsDense = {
         hasSearch: 'show search input',
         searchPlaceholder: 'search placeholder',
         isDisabled: 'disables selector',
+        disabledMessage:
+          'why disabled; w/ isDisabled shows tooltip on hover/focus, trigger stays focusable via aria-disabled; use instead of Tooltip wrapper',
         isLabelHidden: 'visually hides label',
         description: 'helper text below label',
         isOptional: 'marks optional',