@astryxdesign/core 0.1.1 → 0.1.2-canary.3893cd5

package/src/Layer/useLayer.tsx

@@ -23,6 +23,7 @@ import React, {
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
+import {addAnchorName, removeAnchorName} from './anchorName';
 import {typographyVars} from '../theme/tokens.stylex';
 
 const styles = stylex.create({
@@ -65,6 +66,12 @@ export type LayerAlignment = 'start' | 'center' | 'end';
 export interface ContextRenderProps {
   placement?: LayerPlacement;
   alignment?: LayerAlignment;
+  /**
+   * ARIA role applied to the popover container (e.g. `'tooltip'`). Lets
+   * consumers complete the ARIA pattern and gives test tooling a stable,
+   * non-hashed selector for the layer.
+   */
+  role?: string;
   /**
    * StyleX styles for the popover container.
    */
@@ -79,6 +86,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';
 }
 
 /**
@@ -311,16 +331,14 @@ export function useLayer(
   const ref: RefCallback<HTMLElement> | undefined =
     mode === 'context'
       ? (el: HTMLElement | null) => {
-          // Cleanup previous element
-          if (triggerRef.current) {
-            (
-              triggerRef.current.style as unknown as Record<string, string>
-            ).anchorName = '';
+          // Remove only THIS layer's anchor name from the previous element so
+          // other layers sharing the same trigger keep their anchors.
+          if (triggerRef.current && triggerRef.current !== el) {
+            removeAnchorName(triggerRef.current, anchorId);
           }
 
           if (el) {
-            (el.style as unknown as Record<string, string>).anchorName =
-              anchorId;
+            addAnchorName(el, anchorId);
           }
 
           triggerRef.current = el;
@@ -366,9 +384,11 @@ export function useLayer(
       const {
         placement = 'above',
         alignment = 'center',
+        role,
         xstyle,
         className: extraClassName,
         style: extraStyle,
+        as: Container = 'div',
       } = props || {};
 
       // CSS anchor positioning (dynamic, not in StyleX)
@@ -383,15 +403,19 @@ 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}
+          role={role}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
           style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}>
           {children}
-        </div>
+        </Container>
       );
     },
     [anchorId, id, lightDismiss, popoverRefCallback],

package/src/Layout/Layout.doc.mjs

@@ -30,7 +30,7 @@ export const docs = {
       name: 'content',
       type: 'ReactNode',
       description:
-        'Main content area (center). Children passed to `<Layout>` render here too — `<Layout>{main}</Layout>` is shorthand for `<Layout content={main} />`.',
+        '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/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.test.tsx

@@ -99,8 +99,8 @@ describe('Link', () => {
 
   it('renders with different color values', () => {
     const {rerender} = render(
-      <Link href="/test" color="active">
-        Active
+      <Link href="/test" color="accent">
+        Accent
       </Link>,
     );
     expect(screen.getByRole('link')).toBeInTheDocument();

package/src/Link/Link.tsx

@@ -117,7 +117,7 @@ const linkColorStyles = stylex.create({
   placeholder: {
     color: colorVars['--color-text-secondary'],
   },
-  active: {
+  accent: {
     color: colorVars['--color-text-accent'],
   },
   inherit: {
@@ -216,7 +216,7 @@ export interface LinkProps extends BaseProps<
   weight?: TextWeight;
   /**
    * Text color. Forwarded to Text.
-   * @default 'active'
+   * @default 'accent'
    */
   color?: TextColor;
   /**
@@ -264,7 +264,7 @@ export function Link({
   type = 'body',
   size,
   weight,
-  color = 'active',
+  color = 'accent',
   display = 'inline',
   maxLines = 0,
   children,

package/src/Link/LinkProvider.tsx

@@ -23,6 +23,7 @@
  * - /packages/core/src/Link/index.ts
  * - /packages/core/src/Link/Link.doc.mjs
  * - /packages/cli/templates/blocks/components/Link/ (showcase blocks)
+ * - /packages/cli/templates/blocks/components/LinkProvider/ (example blocks)
  */
 
 import {useMemo, type ReactNode} from 'react';

package/src/List/List.doc.mjs

@@ -61,6 +61,13 @@ export const docs = {
       description: "List marker style. 'decimal' renders an <ol> element instead of <ul>.",
       default: "'none'",
     },
+    {
+      name: 'start',
+      type: 'number',
+      description:
+        "Starting number for ordered lists (listStyle='decimal'). Sets the CSS counter to begin at this value.",
+      default: '1',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

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',
@@ -245,6 +246,7 @@ export const docsZh = {
       type: 'number | string',
       description:
         '正文内容的最大宽度（段落、标题、列表、引用块）。表格和代码块不受限制，可扩展到完整容器宽度。用于在宽布局中保持可读行长。',
+      default: '680',
     },
     {
       name: 'contentAlign',

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

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/OverflowList/OverflowList.doc.mjs

@@ -18,6 +18,23 @@ export const docs = {
     'clamp',
     'responsive',
   ],
+  playground: {
+    // children is required; without seeded items the properties-tab preview
+    // renders an empty list. Provide a few items so the preview is meaningful.
+    // `observeParent` measures the (full-width) preview container instead of
+    // the list's own collapsed content box, so the row shows all items rather
+    // than collapsing to one.
+    defaults: {
+      behavior: 'observeParent',
+      children: [
+        {__element: 'Button', props: {label: 'Overview', variant: 'secondary'}},
+        {__element: 'Button', props: {label: 'Activity', variant: 'secondary'}},
+        {__element: 'Button', props: {label: 'Settings', variant: 'secondary'}},
+        {__element: 'Button', props: {label: 'Members', variant: 'secondary'}},
+        {__element: 'Button', props: {label: 'Billing', variant: 'secondary'}},
+      ],
+    },
+  },
   props: [
     {
       name: 'children',