@astryxdesign/core 0.4.7 → 0.5.0-canary.54bb922

package/src/Lightbox/Lightbox.tsx

@@ -12,6 +12,7 @@
  * - /packages/core/src/Lightbox/Lightbox.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Lightbox/Lightbox.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Lightbox/index.ts (exports if types change)
+ * - /packages/core/src/Layer/useLayerDismissal.ts (dismissal stack)
  * - /apps/storybook/stories/Lightbox.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Lightbox/ (showcase blocks)
  */
@@ -32,13 +33,16 @@ import {IconButton} from '../IconButton';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useScrollLock} from '../hooks/useScrollLock';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
-import {mergeProps, mergeRefs, rtlStyles} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {overlayPaddingReset} from '../Layout/padding.stylex';
+import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 /**
  * Media type for lightbox items.
  */
@@ -315,6 +319,7 @@ export function Lightbox({
 }: LightboxProps) {
   const t = useTranslator();
   const dialogRef = useRef<HTMLDialogElement>(null);
+  const mergedDialogRef = useMergedRefs(ref, dialogRef);
   const containerRef = useRef<HTMLDivElement>(null);
   const imageWrapperRef = useRef<HTMLDivElement>(null);
   const triggerElementRef = useRef<Element | null>(null);
@@ -416,13 +421,28 @@ export function Lightbox({
     onOpenChange(false);
   }, [onOpenChange]);
 
-  // Escape key
+  const {shouldDismissOnCloseRequest} = useLayerDismissal({
+    isActive: isOpen,
+    onDismiss: handleClose,
+  });
+
+  // The native `cancel` event is the browser's own close-watcher firing: an
+  // Android back gesture, or a close request the stack never saw a press for.
+  // Escape presses the stack owns never arrive here — it preventDefault()s
+  // those, which suppresses the close watcher.
+  //
+  // Always preventDefault so the browser cannot close a controlled <dialog>
+  // behind React's back, then answer with the stack's own rules: top-most
+  // only, and never while an IME composition is in progress.
   const handleCancel = useCallback(
     (e: React.SyntheticEvent) => {
       e.preventDefault();
+      if (!shouldDismissOnCloseRequest()) {
+        return;
+      }
       handleClose();
     },
-    [handleClose],
+    [handleClose, shouldDismissOnCloseRequest],
   );
 
   // Backdrop click. The layout container fills the whole transparent dialog,
@@ -583,7 +603,7 @@ export function Lightbox({
 
   return (
     <dialog
-      ref={mergeRefs(ref, dialogRef)}
+      ref={mergedDialogRef}
       onCancel={handleCancel}
       onClick={e => {
         handleBackdropClick(e);
@@ -601,112 +621,114 @@ export function Lightbox({
         style,
       )}
       {...props}>
-      <div ref={containerRef} {...stylex.props(styles.container)}>
-        {/* Close button */}
-        <IconButton
-          icon={<Icon icon="close" size="sm" color="inherit" />}
-          label={t('@astryx.lightbox.close')}
-          variant="ghost"
-          onClick={handleClose}
-          xstyle={[styles.closeButton, styles.controlButton]}
-        />
-
-        {/* Gallery nav: prev — stays mounted and is disabled at the start of
-            the range so pressing/arrowing to the boundary doesn't unmount the
-            focused control and drop focus to <body>. */}
-        {isGallery && (
+      <LayerDepthProvider>
+        <div ref={containerRef} {...stylex.props(styles.container)}>
+          {/* Close button */}
           <IconButton
-            icon={
-              <Icon
-                icon="chevronLeft"
-                size="sm"
-                color="inherit"
-                xstyle={rtlStyles.mirror}
-              />
-            }
-            label={t('@astryx.lightbox.previous')}
+            icon={<Icon icon="close" size="sm" color="inherit" />}
+            label={t('@astryx.lightbox.close')}
             variant="ghost"
-            isDisabled={!canPrev}
-            onClick={goToPrev}
-            xstyle={[styles.navButton, styles.navPrev, styles.controlButton]}
+            onClick={handleClose}
+            xstyle={[styles.closeButton, styles.controlButton]}
           />
-        )}
-
-        {/* Media + caption group (centered together) */}
-        <div {...stylex.props(styles.mediaGroup)}>
-          <div
-            ref={imageWrapperRef}
-            // The wrapper is a keyboard-operable zoom toggle when zoom is
-            // enabled: Enter/Space toggles, aria-pressed reflects state.
-            role={isZoomTarget ? 'button' : undefined}
-            tabIndex={isZoomTarget ? 0 : undefined}
-            aria-pressed={isZoomTarget ? isZoomed : undefined}
-            aria-label={isZoomTarget ? t('@astryx.lightbox.zoom') : undefined}
-            {...stylex.props(
-              styles.imageWrapper,
-              isZoomTarget && focusOutlineStyles.focusVisible,
-              !isVideo && hasZoom && !isZoomed && styles.imageWrapperZoomable,
-              !isVideo && isZoomed && styles.imageWrapperZoomed,
-              !isVideo && isDragging && styles.imageWrapperDragging,
-            )}
-            onDoubleClick={isVideo ? undefined : handleDoubleClick}
-            onKeyDown={isZoomTarget ? handleImageKeyDown : undefined}
-            onPointerDown={isVideo ? undefined : handlePointerDown}>
-            {isVideo ? (
-              <video
-                src={currentItem.src}
-                aria-label={currentItem.alt}
-                controls
-                autoPlay={hasAutoPlay}
-                {...stylex.props(styles.video)}
-              />
-            ) : (
-              <img
-                src={currentItem.src}
-                alt={currentItem.alt}
-                draggable={false}
-                {...stylex.props(
-                  styles.image,
-                  isDragging && styles.imageDragging,
-                  imageTransform != null &&
-                    dynamicStyles.imageTransform(imageTransform),
-                )}
-              />
-            )}
-          </div>
 
-          {currentItem.caption && (
-            <div {...stylex.props(styles.caption)}>{currentItem.caption}</div>
+          {/* Gallery nav: prev — stays mounted and is disabled at the start of
+            the range so pressing/arrowing to the boundary doesn't unmount the
+            focused control and drop focus to <body>. */}
+          {isGallery && (
+            <IconButton
+              icon={
+                <Icon
+                  icon="chevronLeft"
+                  size="sm"
+                  color="inherit"
+                  xstyle={rtlStyles.mirror}
+                />
+              }
+              label={t('@astryx.lightbox.previous')}
+              variant="ghost"
+              isDisabled={!canPrev}
+              onClick={goToPrev}
+              xstyle={[styles.navButton, styles.navPrev, styles.controlButton]}
+            />
           )}
-        </div>
 
-        {/* Gallery nav: next — see "prev" above; stays mounted and disabled at
+          {/* Media + caption group (centered together) */}
+          <div {...stylex.props(styles.mediaGroup)}>
+            <div
+              ref={imageWrapperRef}
+              // The wrapper is a keyboard-operable zoom toggle when zoom is
+              // enabled: Enter/Space toggles, aria-pressed reflects state.
+              role={isZoomTarget ? 'button' : undefined}
+              tabIndex={isZoomTarget ? 0 : undefined}
+              aria-pressed={isZoomTarget ? isZoomed : undefined}
+              aria-label={isZoomTarget ? t('@astryx.lightbox.zoom') : undefined}
+              {...stylex.props(
+                styles.imageWrapper,
+                isZoomTarget && focusOutlineStyles.focusVisible,
+                !isVideo && hasZoom && !isZoomed && styles.imageWrapperZoomable,
+                !isVideo && isZoomed && styles.imageWrapperZoomed,
+                !isVideo && isDragging && styles.imageWrapperDragging,
+              )}
+              onDoubleClick={isVideo ? undefined : handleDoubleClick}
+              onKeyDown={isZoomTarget ? handleImageKeyDown : undefined}
+              onPointerDown={isVideo ? undefined : handlePointerDown}>
+              {isVideo ? (
+                <video
+                  src={currentItem.src}
+                  aria-label={currentItem.alt}
+                  controls
+                  autoPlay={hasAutoPlay}
+                  {...stylex.props(styles.video)}
+                />
+              ) : (
+                <img
+                  src={currentItem.src}
+                  alt={currentItem.alt}
+                  draggable={false}
+                  {...stylex.props(
+                    styles.image,
+                    isDragging && styles.imageDragging,
+                    imageTransform != null &&
+                      dynamicStyles.imageTransform(imageTransform),
+                  )}
+                />
+              )}
+            </div>
+
+            {currentItem.caption && (
+              <div {...stylex.props(styles.caption)}>{currentItem.caption}</div>
+            )}
+          </div>
+
+          {/* Gallery nav: next — see "prev" above; stays mounted and disabled at
             the end of the range instead of unmounting. */}
-        {isGallery && (
-          <IconButton
-            icon={
-              <Icon
-                icon="chevronRight"
-                size="sm"
-                color="inherit"
-                xstyle={rtlStyles.mirror}
-              />
-            }
-            label={t('@astryx.lightbox.next')}
-            variant="ghost"
-            isDisabled={!canNext}
-            onClick={goToNext}
-            xstyle={[styles.navButton, styles.navNext, styles.controlButton]}
-          />
-        )}
+          {isGallery && (
+            <IconButton
+              icon={
+                <Icon
+                  icon="chevronRight"
+                  size="sm"
+                  color="inherit"
+                  xstyle={rtlStyles.mirror}
+                />
+              }
+              label={t('@astryx.lightbox.next')}
+              variant="ghost"
+              isDisabled={!canNext}
+              onClick={goToNext}
+              xstyle={[styles.navButton, styles.navNext, styles.controlButton]}
+            />
+          )}
 
-        {/* Gallery counter */}
-        {isGallery && mediaArray.length > 1 && (
-          <div {...stylex.props(styles.counter)}>
-            {index + 1} / {mediaArray.length}
-          </div>
-        )}
-      </div>
+          {/* Gallery counter */}
+          {isGallery && mediaArray.length > 1 && (
+            <div {...stylex.props(styles.counter)}>
+              {index + 1} / {mediaArray.length}
+            </div>
+          )}
+        </div>
+      </LayerDepthProvider>
     </dialog>
   );
 }

package/src/Link/Link.doc.mjs

@@ -78,6 +78,17 @@ export const docs = {
           description:
             'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".',
         },
+        {
+          name: 'download',
+          type: 'string | boolean',
+          description:
+            'Causes the browser to download the linked URL. A string specifies the suggested filename.',
+        },
+        {
+          name: 'referrerPolicy',
+          type: 'HTMLAttributeReferrerPolicy',
+          description: 'Referrer policy for the link.',
+        },
         {
           name: 'onClick',
           type: 'MouseEventHandler',
@@ -94,6 +105,34 @@ export const docs = {
           description: 'Applies base font sizing',
           default: 'false',
         },
+        {
+          name: 'size',
+          type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
+          description: 'Explicit font size override forwarded to Text.',
+        },
+        {
+          name: 'weight',
+          type: "'normal' | 'medium' | 'semibold' | 'bold'",
+          description: 'Font weight override forwarded to Text.',
+        },
+        {
+          name: 'color',
+          type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
+          description: 'Text color forwarded to Text.',
+          default: "'accent'",
+        },
+        {
+          name: 'display',
+          type: "'inline' | 'block'",
+          description: 'Display type for Text.',
+          default: "'inline'",
+        },
+        {
+          name: 'maxLines',
+          type: 'number',
+          description: 'Maximum lines before truncation.',
+          default: '0',
+        },
         {
           name: 'children',
           type: 'ReactNode',

package/src/Markdown/Markdown.doc.mjs

@@ -96,6 +96,11 @@ export const docs = {
       description:
         "Opt-in autolinking of bare URLs and emails. 'gfm' applies GitHub-Flavored Markdown autolink-literal rules: bare https?://..., www...., <scheme:url>, <email>, and user@host all become links. Trailing sentence punctuation and unbalanced trailing close-parens are excluded; matches inside code spans, code blocks, existing links, and image alt text are skipped. Default behavior (option unset) is unchanged.",
     },
+    {
+      name: 'components',
+      type: 'MarkdownComponents',
+      description: 'Custom React component overrides for rendered Markdown elements (code, inlineCode, link, heading, paragraph, image, blockquote, hr, citation).',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

package/src/Markdown/incremental.test.ts

@@ -131,12 +131,26 @@ describe('parseMarkdownIncremental', () => {
     expect(state.settledText).toBe('');
   });
 
-  it('unclosed fence keeps everything unsettled', () => {
+  it('settles what precedes an unclosed fence, and nothing inside it', () => {
     const state = createIncrementalState();
     const input =
       '# Title\n\n```python\ndef foo():\n    pass\n\n# still inside fence';
     parseMarkdownIncremental(input, state);
-    expect(state.settledBlocks).toHaveLength(0);
+    expect(state.settledText).toBe('# Title');
+    expect(state.settledBlocks).toHaveLength(1);
+  });
+
+  it('does not hold back lines inside an unclosed fence', () => {
+    const state = createIncrementalState();
+    const blocks = parseMarkdownIncremental(
+      'Intro\n\n```ts\ntype Id = string | number;',
+      state,
+    );
+    const code = blocks.find(block => block.type === 'codeblock');
+    expect(code).toMatchObject({
+      type: 'codeblock',
+      content: 'type Id = string | number;',
+    });
   });
 
   it('handles task list streaming', () => {

package/src/Markdown/index.ts

@@ -25,6 +25,7 @@ export {
 export type {
   BlockNode,
   InlineNode,
+  SourceRange,
   ListItemNode,
   TableCellNode,
   TableAlignment,

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

@@ -6,7 +6,7 @@ import {
   parseMarkdownIncremental,
   createIncrementalState,
 } from './parser';
-import type {BlockNode} from './parser';
+import type {BlockNode, ParseOptions} from './parser';
 
 function generateAIResponse(paragraphs: number): string {
   const sections: string[] = [];
@@ -69,6 +69,44 @@ function simulateStreamingIncremental(
   return parseMarkdownIncremental(fullText, state);
 }
 
+/**
+ * How many blocks each chunk of a streamed document had to build.
+ *
+ * A block the parser kept in its settled cache is handed back as the very same
+ * object, so a returned block that is not one of the previous chunk's is one
+ * this chunk built. That makes the cache countable without reaching into the
+ * parser's internals.
+ */
+function blocksBuiltPerChunk(
+  fullText: string,
+  chunkSize: number,
+  options?: ParseOptions,
+): number[] {
+  const state = createIncrementalState();
+  let previous: ReadonlySet<BlockNode> = new Set();
+  const built: number[] = [];
+  const step = (text: string) => {
+    const blocks =
+      options == null
+        ? parseMarkdownIncremental(text, state)
+        : parseMarkdownIncremental(text, state, options);
+    built.push(blocks.reduce((n, b) => (previous.has(b) ? n : n + 1), 0));
+    previous = new Set(blocks);
+  };
+  for (let i = chunkSize; i <= fullText.length; i += chunkSize) {
+    step(fullText.slice(0, i));
+  }
+  step(fullText);
+  return built;
+}
+
+const percentile = (values: number[], p: number): number => {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+};
+
+const sum = (values: number[]): number => values.reduce((a, b) => a + b, 0);
+
 // 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
@@ -204,3 +242,60 @@ describe('parseMarkdown performance', () => {
     expect(incrElapsed).toBeLessThanOrEqual(fullElapsed * 1.1);
   });
 });
+
+// What the incremental parser exists for is a cache, so these assert the cache:
+// integers that come out the same on a loaded CI box as on an idle laptop,
+// unlike the wall-clock budgets above.
+describe('parseMarkdownIncremental cache', () => {
+  it('builds a bounded number of blocks per chunk however long the document is', () => {
+    const chunkSize = 50;
+    const medians = [50, 200, 500].map(paragraphs =>
+      percentile(
+        blocksBuiltPerChunk(generateAIResponse(paragraphs), chunkSize),
+        0.5,
+      ),
+    );
+    console.log(
+      `  median blocks built per chunk (50/200/500 paragraphs): ${medians.join('/')}`,
+    );
+    // A chunk re-parses its unsettled tail, not the document — so the typical
+    // chunk's cost is a constant, and a 10x longer document does not move it.
+    expect(medians).toEqual([1, 1, 1]);
+  });
+
+  it('bounds the worst chunk, not just the typical one, at every document length', () => {
+    const chunkSize = 50;
+    const worst = [50, 200, 500].map(paragraphs =>
+      Math.max(
+        ...blocksBuiltPerChunk(generateAIResponse(paragraphs), chunkSize),
+      ),
+    );
+    console.log(
+      `  worst chunk's blocks built (50/200/500 paragraphs): ${worst.join('/')}`,
+    );
+    // A cache that dumps on a minority of chunks is flat at the median and at
+    // p95 while the total work is still quadratic: the blank-line path of
+    // #5378 hit ~1.4% of chunks on this fixture, and no percentile bound saw
+    // it. The worst chunk does, and each collapse costs more as the document
+    // grows — so this asserts the worst one, and that a 10x document does not
+    // move it. Deterministic: same fixture, same chunking, integers with no
+    // timing input.
+    expect(worst).toEqual([3, 3, 3]);
+  });
+
+  it('keeps the cache when source ranges are asked for', () => {
+    const text = generateAIResponse(200);
+    const chunkSize = 50;
+    const without = sum(blocksBuiltPerChunk(text, chunkSize));
+    const withRanges = sum(
+      blocksBuiltPerChunk(text, chunkSize, {sourceRanges: true}),
+    );
+    console.log(
+      `  blocks built streaming ${text.length} chars: ${without} without ranges, ${withRanges} with`,
+    );
+    // Stamping offsets must not cost a cache entry. An implementation that
+    // tracked positions by invalidating the settled cache each chunk would
+    // still pass any time budget generous enough not to flake; it fails here.
+    expect(withRanges).toBe(without);
+  });
+});

package/src/Markdown/parser.test.ts

@@ -1,8 +1,13 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {parseMarkdown, parseInline} from './parser';
-import type {InlineNode} from './parser';
+import {
+  createIncrementalState,
+  parseInline,
+  parseMarkdown,
+  parseMarkdownIncremental,
+} from './parser';
+import type {BlockNode, InlineNode} from './parser';
 
 describe('parseInline', () => {
   it('parses plain text', () => {
@@ -1209,3 +1214,141 @@ describe('link reference definitions', () => {
     expect(blocks[0].type).toBe('paragraph');
   });
 });
+
+describe('sourceRanges', () => {
+  const slice = (source: string, block: BlockNode) =>
+    block.range == null
+      ? null
+      : source.slice(block.range.start, block.range.end);
+
+  it('is off by default', () => {
+    const [block] = parseMarkdown('# Title');
+    expect(block.range).toBeUndefined();
+  });
+
+  it('addresses a block with named start and end offsets', () => {
+    const source = 'One.\n\nTwo.';
+    const [, second] = parseMarkdown(source, {sourceRanges: true});
+    expect(second.range).toEqual({start: 6, end: 10});
+  });
+
+  it('gives every top-level block the source it came from', () => {
+    const source = [
+      '# Title',
+      '',
+      'A paragraph that',
+      'wraps onto two lines.',
+      '',
+      '- one',
+      '- two',
+      '',
+      '```js',
+      'const x = 1;',
+      '```',
+      '',
+      '| a | b |',
+      '| --- | --- |',
+      '| 1 | 2 |',
+      '',
+      '> quoted',
+      '',
+      '---',
+    ].join('\n');
+    const blocks = parseMarkdown(source, {sourceRanges: true});
+    expect(blocks.map(b => slice(source, b))).toEqual([
+      '# Title',
+      'A paragraph that\nwraps onto two lines.',
+      '- one\n- two',
+      '```js\nconst x = 1;\n```',
+      '| a | b |\n| --- | --- |\n| 1 | 2 |',
+      '> quoted',
+      '---',
+    ]);
+  });
+
+  it('reports offsets into the input, not into the link-definition-stripped text', () => {
+    // The definition lines are removed before the block loop runs, so a naive
+    // offset would drift by their length for everything after them.
+    const source = [
+      '[ref]: https://example.com',
+      '',
+      'See [the docs][ref].',
+      '',
+      'Another paragraph.',
+    ].join('\n');
+    const blocks = parseMarkdown(source, {sourceRanges: true});
+    expect(blocks.map(b => slice(source, b))).toEqual([
+      'See [the docs][ref].',
+      'Another paragraph.',
+    ]);
+  });
+
+  it('reports absolute offsets when the document is parsed incrementally', () => {
+    const source = ['# Title', '', 'One.', '', 'Two.', '', 'Three.'].join('\n');
+    const state = createIncrementalState();
+    let blocks: BlockNode[] = [];
+    for (let end = 1; end <= source.length; end++) {
+      blocks = parseMarkdownIncremental(source.slice(0, end), state, {
+        sourceRanges: true,
+      });
+    }
+    expect(blocks.map(b => slice(source, b))).toEqual([
+      '# Title',
+      'One.',
+      'Two.',
+      'Three.',
+    ]);
+  });
+
+  it('keeps the blank lines an unterminated fence owns', () => {
+    // Mid-stream the closing fence has not arrived, and the blank lines are
+    // part of the code, not spacing between blocks.
+    const source = '```\ncode\n\n';
+    const [block] = parseMarkdown(source, {sourceRanges: true});
+    // The whole thing: the fence consumed those lines as code.
+    expect(slice(source, block)).toBe(source);
+  });
+
+  it('slices to something that re-parses to the same block', () => {
+    // The property a consumer actually needs, and the one that says the
+    // offsets are right: what the range points at is the block.
+    const check = (source: string) => {
+      for (const block of parseMarkdown(source, {sourceRanges: true})) {
+        const {range: _range, ...node} = block;
+        expect(parseMarkdown(slice(source, block)!)).toEqual([node]);
+      }
+    };
+    check('# Title\n\nA paragraph.\n\n- one\n- two\n\n> quoted');
+    // CRLF: the parser keeps the `\r` in its own content, so the range does
+    // too rather than slicing to text that parses differently.
+    check('# Title\r\n\r\nA paragraph.\r\n');
+  });
+
+  it('re-parses when the caller flips the option on an existing state', () => {
+    const source = 'One.\n\nTwo.\n\nThree.';
+    const state = createIncrementalState();
+    const without = parseMarkdownIncremental(source, state);
+    expect(without.every(b => b.range == null)).toBe(true);
+    const with_ = parseMarkdownIncremental(source, state, {
+      sourceRanges: true,
+    });
+    expect(with_.map(b => slice(source, b))).toEqual([
+      'One.',
+      'Two.',
+      'Three.',
+    ]);
+    const back = parseMarkdownIncremental(source, state);
+    expect(back.every(b => b.range == null)).toBe(true);
+  });
+
+  it('spans both halves of a list the incremental parser merged', () => {
+    const source = '1. one\n\n1. two';
+    const state = createIncrementalState();
+    parseMarkdownIncremental('1. one\n\n', state, {sourceRanges: true});
+    const blocks = parseMarkdownIncremental(source, state, {
+      sourceRanges: true,
+    });
+    expect(blocks).toHaveLength(1);
+    expect(slice(source, blocks[0])).toBe(source);
+  });
+});