@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/Lightbox/Lightbox.test.tsx

@@ -1,8 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {Lightbox} from './Lightbox';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 // Mock showModal/close for jsdom
 beforeEach(() => {
@@ -16,6 +17,16 @@ beforeEach(() => {
   });
 });
 
+// useAnnounce mounts singleton live regions on <body>; reset between tests so
+// stale announcements from one test don't leak into the next.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
+
 describe('Lightbox', () => {
   it('renders as a dialog element', () => {
     render(
@@ -300,6 +311,116 @@ describe('Lightbox', () => {
     });
   });
 
+  describe('screen-reader announcements', () => {
+    const media = [
+      {src: '/a.jpg', alt: 'Image A', caption: 'First'},
+      {src: '/b.jpg', alt: 'Image B', caption: 'Second'},
+      {src: '/c.jpg', alt: 'Image C'},
+    ];
+
+    it('announces the new image and position when navigating next via button', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          defaultIndex={0}
+        />,
+      );
+      fireEvent.click(screen.getByLabelText('Next'));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Image B, 2 of 3');
+      });
+    });
+
+    it('announces the new image and position when navigating via arrow keys', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          defaultIndex={1}
+        />,
+      );
+      const dialog = document.querySelector('dialog')!;
+      fireEvent.keyDown(dialog, {key: 'ArrowRight'});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Image C, 3 of 3');
+      });
+    });
+
+    it('announces the new image and position when navigating prev', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          defaultIndex={2}
+        />,
+      );
+      fireEvent.click(screen.getByLabelText('Previous'));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Image B, 2 of 3');
+      });
+    });
+
+    it('falls back to a positional label when the image has no alt', async () => {
+      const unlabeled = [
+        {src: '/a.jpg', alt: 'Image A'},
+        {src: '/b.jpg', alt: ''},
+      ];
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={unlabeled}
+          defaultIndex={0}
+        />,
+      );
+      fireEvent.click(screen.getByLabelText('Next'));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Image 2 of 2');
+      });
+    });
+
+    it('does not announce on initial open', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          defaultIndex={1}
+        />,
+      );
+      // Allow any scheduled rAF to flush; nothing should have been announced.
+      await new Promise(resolve => requestAnimationFrame(() => resolve(null)));
+      // The dialog's aria-label already names the current image on open, so no
+      // live region is created (announce is never called).
+      expect(politeRegion()).toBeNull();
+    });
+
+    it('does not announce when the lightbox opens at a new index', async () => {
+      const {rerender} = render(
+        <Lightbox
+          isOpen={false}
+          onOpenChange={() => {}}
+          media={media}
+          index={0}
+        />,
+      );
+      rerender(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={2}
+        />,
+      );
+      await new Promise(resolve => requestAnimationFrame(() => resolve(null)));
+      expect(politeRegion()).toBeNull();
+    });
+  });
+
   describe('video support', () => {
     it('renders a video element when type is video', () => {
       const {container} = render(

package/src/Lightbox/Lightbox.tsx

@@ -19,6 +19,7 @@
 import {
   useCallback,
   useEffect,
+  useMemo,
   useRef,
   useState,
   type MouseEvent as ReactMouseEvent,
@@ -28,6 +29,7 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, typeScaleVars} from '../theme/tokens.stylex';
 import {Icon} from '../Icon';
 import {IconButton} from '../IconButton';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useScrollLock} from '../hooks/useScrollLock';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {mergeProps, mergeRefs} from '../utils';
@@ -306,7 +308,10 @@ export function Lightbox({
   const dragStartRef = useRef({x: 0, y: 0, panX: 0, panY: 0});
 
   // Resolve current media item
-  const mediaArray = Array.isArray(media) ? media : [media];
+  const mediaArray = useMemo(
+    () => (Array.isArray(media) ? media : [media]),
+    [media],
+  );
   const isGallery = mediaArray.length > 1;
   const currentItem =
     mediaArray.length > 0
@@ -329,6 +334,29 @@ export function Lightbox({
     setPan({x: 0, y: 0});
   }, [index, currentItem?.src]);
 
+  // Announce gallery navigation to screen readers. Moving between images only
+  // updates the visual counter, which is silent to assistive tech, so mirror
+  // each change in a polite live region ("<alt>, 3 of 12", or "Image 3 of 12"
+  // when the image has no alt). Announce only when the image changes during an
+  // already-open session — not on mount, not when opening (even at a new
+  // index, since the dialog's aria-label already names the current image), and
+  // not on close.
+  const announce = useAnnounce();
+  const prevIndexRef = useRef(index);
+  const wasOpenRef = useRef(isOpen);
+  useEffect(() => {
+    const indexChanged = prevIndexRef.current !== index;
+    const wasOpen = wasOpenRef.current;
+    prevIndexRef.current = index;
+    wasOpenRef.current = isOpen;
+    if (!indexChanged || !isOpen || !wasOpen) {
+      return;
+    }
+    const item = mediaArray[Math.min(index, mediaArray.length - 1)];
+    const position = `${index + 1} of ${mediaArray.length}`;
+    announce(item?.alt ? `${item.alt}, ${position}` : `Image ${position}`);
+  }, [index, isOpen, announce, mediaArray]);
+
   // Open/close dialog
   useIsomorphicLayoutEffect(() => {
     const dialog = dialogRef.current;

package/src/Markdown/Markdown.test.tsx

@@ -95,6 +95,29 @@ describe('Markdown', () => {
     expect(link.getAttribute('rel')).toBe('noopener noreferrer');
   });
 
+  it('renders a footer reference-style link as an anchor', () => {
+    // The XDS parser previously had no reference-definition support, so this
+    // rendered as literal `[the docs][docs]` text with the definition leaking
+    // as a paragraph. It now resolves to a real anchor.
+    render(
+      <Markdown>
+        {'See [the docs][docs] here.\n\n[docs]: https://example.com/docs\n'}
+      </Markdown>,
+    );
+    const link = screen.getByText('the docs');
+    expect(link.tagName).toBe('A');
+    expect(link.getAttribute('href')).toBe('https://example.com/docs');
+    // The definition line must not leak into the rendered output.
+    expect(screen.queryByText(/\[docs\]:/)).toBeNull();
+  });
+
+  it('renders a shortcut reference-style link as an anchor', () => {
+    render(<Markdown>{'See [the docs].\n\n[the docs]: /docs'}</Markdown>);
+    const link = screen.getByText('the docs');
+    expect(link.tagName).toBe('A');
+    expect(link.getAttribute('href')).toBe('/docs');
+  });
+
   it('does not add target="_blank" to relative links', () => {
     render(<Markdown>{'[internal](/page)'}</Markdown>);
     const link = screen.getByText('internal');

package/src/Markdown/Markdown.tsx

@@ -425,7 +425,14 @@ const streamingStyles = stylex.create({
   fadeIn: {
     opacity: 1,
     transitionProperty: 'opacity',
-    transitionDuration: durationVars['--duration-medium'],
+    // Collapse the entry fade to an instant swap under reduced motion. The
+    // 0s duration makes the @starting-style opacity jump non-animated (the
+    // media query can't nest inside @starting-style), mirroring the
+    // conditional-duration form in Spinner (Spinner.tsx).
+    transitionDuration: {
+      default: durationVars['--duration-medium'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
     transitionTimingFunction: easeVars['--ease-standard'],
     '@starting-style': {
       opacity: 0,
@@ -1049,12 +1056,7 @@ function renderBlock(
   switch (node.type) {
     case 'heading': {
       const level = Math.min(node.level + headingLevelStart - 1, 6) as
-        | 1
-        | 2
-        | 3
-        | 4
-        | 5
-        | 6;
+        1 | 2 | 3 | 4 | 5 | 6;
       const headingChildren = node.children.map((c, i) =>
         renderInline(
           c,

package/src/Markdown/incremental.test.ts

@@ -650,3 +650,39 @@ describe('streaming end-to-end: no raw syntax visible', () => {
     });
   });
 });
+
+describe('parseMarkdownIncremental link reference definitions', () => {
+  function firstLinkHref(blocks: BlockNode[]): string | undefined {
+    for (const block of blocks) {
+      if (block.type === 'paragraph') {
+        for (const node of block.children) {
+          if (node.type === 'link') {
+            return node.href;
+          }
+        }
+      }
+    }
+    return undefined;
+  }
+
+  it('resolves a footer reference streamed across chunks (matches full parse)', () => {
+    const text = 'See [the docs][d] here.\n\n[d]: https://example.com/d\n';
+    const {final} = simulateStreaming(text, 5);
+    expect(final).toEqual(parseMarkdown(text));
+    expect(firstLinkHref(final)).toBe('https://example.com/d');
+  });
+
+  it('re-resolves an already-settled reference once its definition arrives', () => {
+    const state = createIncrementalState();
+    // The reference paragraph settles (blank line) before the definition.
+    parseMarkdownIncremental('See [d] here.\n\n', state);
+    const before = parseMarkdownIncremental('See [d] here.\n\n[d', state);
+    expect(firstLinkHref(before)).toBeUndefined();
+    // Definition completes — the settled paragraph must pick up the link.
+    const after = parseMarkdownIncremental(
+      'See [d] here.\n\n[d]: /docs\n',
+      state,
+    );
+    expect(firstLinkHref(after)).toBe('/docs');
+  });
+});

package/src/Markdown/parser.perf.test.ts

@@ -69,6 +69,31 @@ function simulateStreamingIncremental(
   return parseMarkdownIncremental(fullText, state);
 }
 
+// A single wall-clock measurement is flaky when the whole suite runs in
+// parallel forks: scheduler contention can inflate a millisecond-scale
+// sample well past a tight budget (observed 30.9ms against the 20ms Small
+// budget). The fastest of a few runs approximates the un-contended cost —
+// a real regression raises the minimum too — so budgets stay tight without
+// flapping. The streaming budget tests below keep a single run: their
+// budgets carry 10x+ headroom, which contention cannot realistically eat.
+function measureBest<T>(
+  runs: number,
+  fn: () => T,
+): {elapsed: number; result: T} {
+  let elapsed = Infinity;
+  let result!: T;
+  for (let i = 0; i < runs; i++) {
+    const start = performance.now();
+    const r = fn();
+    const t = performance.now() - start;
+    if (t < elapsed) {
+      elapsed = t;
+      result = r;
+    }
+  }
+  return {elapsed, result};
+}
+
 describe('parseMarkdown performance', () => {
   const sizes = [
     {name: 'Small', paragraphs: 10, maxMs: 20},
@@ -93,9 +118,7 @@ describe('parseMarkdown performance', () => {
   for (const size of sizes) {
     it(`full re-parse ${size.name} (${size.paragraphs} paragraphs) under ${size.maxMs}ms`, () => {
       const text = generateAIResponse(size.paragraphs);
-      const start = performance.now();
-      const result = parseMarkdown(text);
-      const elapsed = performance.now() - start;
+      const {elapsed, result} = measureBest(3, () => parseMarkdown(text));
       console.log(
         `  ${size.name} full parse: ${elapsed.toFixed(2)}ms → ${result.length} blocks`,
       );
@@ -149,15 +172,14 @@ describe('parseMarkdown performance', () => {
     const text = generateAIResponse(200);
     const chunkSize = 50;
 
-    // Full re-parse timing
-    const fullStart = performance.now();
-    simulateStreamingFullReparse(text, chunkSize);
-    const fullElapsed = performance.now() - fullStart;
-
-    // Incremental timing
-    const incrStart = performance.now();
-    simulateStreamingIncremental(text, chunkSize);
-    const incrElapsed = performance.now() - incrStart;
+    // The assertion below compares a ratio of two measurements, so noise on
+    // either side can flip it — measure both as best-of-3.
+    const {elapsed: fullElapsed} = measureBest(3, () =>
+      simulateStreamingFullReparse(text, chunkSize),
+    );
+    const {elapsed: incrElapsed} = measureBest(3, () =>
+      simulateStreamingIncremental(text, chunkSize),
+    );
 
     const speedup = fullElapsed / incrElapsed;
     console.log(`\n  === Incremental vs Full Re-parse Speedup ===`);

package/src/Markdown/parser.test.ts

@@ -2,6 +2,7 @@
 
 import {describe, it, expect} from 'vitest';
 import {parseMarkdown, parseInline} from './parser';
+import type {InlineNode} from './parser';
 
 describe('parseInline', () => {
   it('parses plain text', () => {
@@ -946,3 +947,212 @@ describe('citation parsing', () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Link reference definitions
+// ---------------------------------------------------------------------------
+
+describe('link reference definitions', () => {
+  // Collect every link/image node across a block tree for concise assertions.
+  function collectLinks(
+    nodes: InlineNode[],
+  ): {type: string; href?: string; src?: string; text: string}[] {
+    const out: {type: string; href?: string; src?: string; text: string}[] = [];
+    const textOf = (inlineNodes: InlineNode[]): string =>
+      inlineNodes
+        .map(inline =>
+          inline.type === 'text'
+            ? inline.content
+            : 'children' in inline
+              ? textOf(inline.children)
+              : '',
+        )
+        .join('');
+    for (const node of nodes) {
+      if (node.type === 'link') {
+        out.push({type: 'link', href: node.href, text: textOf(node.children)});
+      } else if (node.type === 'image') {
+        out.push({type: 'image', src: node.src, text: node.alt});
+      } else if ('children' in node) {
+        out.push(...collectLinks(node.children));
+      }
+    }
+    return out;
+  }
+
+  function paragraphLinks(input: string) {
+    const blocks = parseMarkdown(input);
+    const links = blocks.flatMap(block =>
+      block.type === 'paragraph' ? collectLinks(block.children) : [],
+    );
+    return {blocks, links};
+  }
+
+  it('resolves a full reference `[text][label]` and drops the definition', () => {
+    const {blocks, links} = paragraphLinks(
+      'See [the docs][docs] here.\n\n[docs]: https://example.com/docs\n',
+    );
+    // Only the paragraph survives; the definition line produces no block.
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].type).toBe('paragraph');
+    expect(links).toEqual([
+      {type: 'link', href: 'https://example.com/docs', text: 'the docs'},
+    ]);
+  });
+
+  it('resolves a collapsed reference `[text][]`', () => {
+    const {links} = paragraphLinks(
+      'See [the docs][].\n\n[the docs]: https://example.com/docs',
+    );
+    expect(links).toEqual([
+      {type: 'link', href: 'https://example.com/docs', text: 'the docs'},
+    ]);
+  });
+
+  it('resolves a shortcut reference `[text]`', () => {
+    const {links} = paragraphLinks(
+      'See [the docs].\n\n[the docs]: https://example.com/docs',
+    );
+    expect(links).toEqual([
+      {type: 'link', href: 'https://example.com/docs', text: 'the docs'},
+    ]);
+  });
+
+  it('resolves a reference that appears before its definition', () => {
+    const {links} = paragraphLinks('[foo]\n\n[foo]: /bar');
+    expect(links).toEqual([{type: 'link', href: '/bar', text: 'foo'}]);
+  });
+
+  it('matches labels case-insensitively with collapsed whitespace', () => {
+    const {links} = paragraphLinks(
+      'See [The   Docs][DOCS].\n\n[docs]: https://example.com/d',
+    );
+    expect(links).toEqual([
+      {type: 'link', href: 'https://example.com/d', text: 'The   Docs'},
+    ]);
+  });
+
+  it('supports an angle-bracket destination and a title', () => {
+    const {links} = paragraphLinks(
+      'See [x].\n\n[x]: <https://example.com/x> "the title"',
+    );
+    expect(links).toEqual([
+      {type: 'link', href: 'https://example.com/x', text: 'x'},
+    ]);
+  });
+
+  it('absorbs a title on the line after a title-less definition', () => {
+    const {blocks, links} = paragraphLinks(
+      'See [x].\n\n[x]: https://example.com/x\n  "the title"\n',
+    );
+    // The continuation title line must not leak as its own paragraph.
+    expect(blocks).toHaveLength(1);
+    expect(links).toEqual([
+      {type: 'link', href: 'https://example.com/x', text: 'x'},
+    ]);
+  });
+
+  it('resolves an empty angle-bracket destination to an empty href', () => {
+    const {blocks, links} = paragraphLinks('[foo]\n\n[foo]: <>');
+    expect(blocks).toHaveLength(1);
+    expect(links).toEqual([{type: 'link', href: '', text: 'foo'}]);
+  });
+
+  it('recognizes a definition immediately after a heading (no blank line)', () => {
+    const {blocks, links} = paragraphLinks('# Title\n[x]: /url\n\n[x]');
+    expect(blocks.map(block => block.type)).toEqual(['heading', 'paragraph']);
+    expect(links).toEqual([{type: 'link', href: '/url', text: 'x'}]);
+  });
+
+  it('recognizes a definition immediately after a closed code fence', () => {
+    const {blocks, links} = paragraphLinks('```\ncode\n```\n[x]: /url\n\n[x]');
+    expect(blocks.map(block => block.type)).toEqual(['codeblock', 'paragraph']);
+    expect(links).toEqual([{type: 'link', href: '/url', text: 'x'}]);
+  });
+
+  it('uses the first definition when a label is defined twice', () => {
+    const {links} = paragraphLinks('[a]\n\n[a]: /first\n[a]: /second');
+    expect(links).toEqual([{type: 'link', href: '/first', text: 'a'}]);
+  });
+
+  it('resolves a blockquote-nested definition even with a top-level definition present', () => {
+    const blocks = parseMarkdown('[outer]: /o\n\n> [inner]\n>\n> [inner]: /i');
+    const quote = blocks.find(block => block.type === 'blockquote');
+    expect(quote?.type).toBe('blockquote');
+    if (quote != null && quote.type === 'blockquote') {
+      const links = quote.children.flatMap(block =>
+        block.type === 'paragraph' ? collectLinks(block.children) : [],
+      );
+      expect(links).toEqual([{type: 'link', href: '/i', text: 'inner'}]);
+    }
+  });
+
+  it('resolves a reference image `![alt][label]`', () => {
+    const {links} = paragraphLinks('![logo][l]\n\n[l]: /logo.png');
+    expect(links).toEqual([{type: 'image', src: '/logo.png', text: 'logo'}]);
+  });
+
+  it('does not treat a whitespace-only second label as collapsed', () => {
+    // `[foo][ ]` is a full reference to the empty (normalized) label and matches
+    // nothing; `[foo]` still resolves as a shortcut and `[ ]` stays literal.
+    const blocks = parseMarkdown('[foo][ ]\n\n[foo]: /f');
+    expect(blocks[0].type).toBe('paragraph');
+    if (blocks[0].type === 'paragraph') {
+      expect(collectLinks(blocks[0].children)).toEqual([
+        {type: 'link', href: '/f', text: 'foo'},
+      ]);
+      const literal = blocks[0].children
+        .map(node => (node.type === 'text' ? node.content : ''))
+        .join('');
+      expect(literal).toContain('[ ]');
+    }
+  });
+
+  it('leaves an unresolved reference as literal text', () => {
+    const {blocks, links} = paragraphLinks('See [the docs][missing].');
+    expect(links).toEqual([]);
+    expect(blocks[0].type).toBe('paragraph');
+    if (blocks[0].type === 'paragraph') {
+      expect(blocks[0].children).toContainEqual({
+        type: 'text',
+        content: 'See [the docs][missing].',
+      });
+    }
+  });
+
+  it('does not resolve a definition or reference inside a code fence', () => {
+    const blocks = parseMarkdown('```\n[x]\n[x]: /should-not-resolve\n```');
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].type).toBe('codeblock');
+    if (blocks[0].type === 'codeblock') {
+      expect(blocks[0].content).toBe('[x]\n[x]: /should-not-resolve');
+    }
+  });
+
+  it('does not treat a definition-shaped line as a definition mid-paragraph', () => {
+    // CommonMark: a definition cannot interrupt a paragraph.
+    const {blocks, links} = paragraphLinks('Foo\n[bar]: /baz');
+    expect(links).toEqual([]);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].type).toBe('paragraph');
+  });
+
+  it('leaves footnote markers and definitions untouched', () => {
+    const blocks = parseMarkdown(
+      'A claim.[^1]\n\n[^1]: https://example.com/note',
+    );
+    // No link nodes; the `[^1]` marker stays literal and `[^1]:` is not
+    // treated as a link reference definition (footnotes are out of scope).
+    const links = blocks.flatMap(block =>
+      block.type === 'paragraph' ? collectLinks(block.children) : [],
+    );
+    expect(links).toEqual([]);
+    expect(blocks).toHaveLength(2);
+  });
+
+  it('leaves ordinary bracketed text with no definition alone', () => {
+    const {links, blocks} = paragraphLinks('an array like [1, 2, 3] here');
+    expect(links).toEqual([]);
+    expect(blocks[0].type).toBe('paragraph');
+  });
+});