@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Markdown/parser.ts

@@ -24,7 +24,15 @@ export type InlineNode =
   | {type: 'citation'; sourceId: string}
   | {type: 'break'};
 
-export type BlockNode =
+export type BlockNode = BlockNodeKind & {
+  /**
+   * Where this block came from in the source, when parsed with the
+   * `sourceRanges` option. Top-level blocks only.
+   */
+  range?: SourceRange;
+};
+
+type BlockNodeKind =
   | {type: 'heading'; level: 1 | 2 | 3 | 4 | 5 | 6; children: InlineNode[]}
   | {type: 'paragraph'; children: InlineNode[]}
   | {type: 'codeblock'; language: string; content: string}
@@ -47,6 +55,17 @@ export type BlockNode =
   | {type: 'hr'}
   | {type: 'image'; src: string; alt: string};
 
+/**
+ * Where a block sits in the source string handed to `parseMarkdown`:
+ * `source.slice(start, end)` is the block, and `end` excludes the block's
+ * trailing blank lines.
+ *
+ * An object rather than a `[start, end]` tuple so a second way of addressing
+ * the same block — line numbers, once a consumer needs them — can be added as
+ * optional fields without breaking anyone.
+ */
+export type SourceRange = {readonly start: number; readonly end: number};
+
 export type ListItemNode = {checked?: boolean; children: BlockNode[]};
 export type TableCellNode = {children: InlineNode[]};
 export type TableAlignment = 'left' | 'center' | 'right' | null;
@@ -78,11 +97,28 @@ export type ParseOptions = {
    * suffix is not rejected (Astryx accepts any plausible TLD shape).
    */
   autolink?: 'gfm';
+  /**
+   * When true, every top-level block carries a `range` — the offsets it
+   * occupies in the string passed in. Lets a consumer that still holds the
+   * source slice the original markdown for a block instead of reconstructing
+   * it from the parsed node (or from the rendered DOM). Off by default: the
+   * field is absent unless asked for, so nothing that compares nodes changes.
+   *
+   * Blocks nested inside a list item or a blockquote do not carry one.
+   */
+  sourceRanges?: boolean;
 };
 
 type ResolvedOptions = {
   readonly sourceIds: ReadonlySet<string> | undefined;
   readonly autolink: 'gfm' | undefined;
+  readonly sourceRanges?: boolean;
+  /**
+   * Offset of this parse's input within the document the ranges are reported
+   * against. Internal only — the incremental parser parses slices and needs
+   * their blocks' ranges to come out absolute.
+   */
+  readonly baseOffset?: number;
   /**
    * Link reference definitions (`[label]: url`) collected from the whole
    * document, keyed by normalized label. Internal only — populated by the
@@ -109,7 +145,11 @@ function resolveOptions(
     return {sourceIds: arg as ReadonlySet<string>, autolink: undefined};
   }
   const opts = arg as ParseOptions;
-  return {sourceIds: opts.sourceIds, autolink: opts.autolink};
+  return {
+    sourceIds: opts.sourceIds,
+    autolink: opts.autolink,
+    sourceRanges: opts.sourceRanges,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -174,6 +214,11 @@ function matchLinkDefinition(
 function extractLinkDefinitions(input: string): {
   defs: ReadonlyMap<string, string>;
   cleaned: string;
+  /**
+   * For each line of `cleaned`, the line of `input` it came from. Undefined
+   * when nothing was stripped and the two are the same text.
+   */
+  lineMap?: number[];
 } {
   const lines = input.split('\n');
   const defs = new Map<string, string>();
@@ -235,8 +280,14 @@ function extractLinkDefinitions(input: string): {
   if (defs.size === 0) {
     return {defs, cleaned: input};
   }
-  const cleaned = lines.filter((_, index) => keep[index]).join('\n');
-  return {defs, cleaned};
+  const lineMap: number[] = [];
+  for (let index = 0; index < lines.length; index++) {
+    if (keep[index]) {
+      lineMap.push(index);
+    }
+  }
+  const cleaned = lineMap.map(index => lines[index]).join('\n');
+  return {defs, cleaned, lineMap};
 }
 
 /** Order-independent signature of a link-definition set, for cache checks. */
@@ -318,7 +369,7 @@ function matchReferenceImage(
       const rawLabel = text.slice(altClose + 2, labelClose);
       const label = rawLabel === '' ? alt : rawLabel;
       const src = linkDefs.get(normalizeLinkLabel(label));
-      if (src != null) {
+      if (src != null && isSafeUrl(src)) {
         return {node: {type: 'image', src, alt}, end: labelClose + 1};
       }
       // No match — fall back to a shortcut `![alt]`.
@@ -328,7 +379,7 @@ function matchReferenceImage(
     return null;
   }
   const src = linkDefs.get(normalizeLinkLabel(alt));
-  if (src == null) {
+  if (src == null || !isSafeUrl(src)) {
     return null;
   }
   return {node: {type: 'image', src, alt}, end: altClose + 1};
@@ -1042,6 +1093,16 @@ function isTableSeparator(line: string): boolean {
   return nonEmpty.length > 0 && nonEmpty.every(cell => /^:?-+:?$/.test(cell));
 }
 
+/**
+ * The same options for content parsed out of an enclosing block. Ranges are a
+ * top-level contract: a list item's or a blockquote's children are parsed from
+ * text the caller reassembled (markers and `>` prefixes stripped), so an
+ * offset into it would not address the document.
+ */
+function nested(opts: ResolvedOptions): ResolvedOptions {
+  return opts.sourceRanges ? {...opts, sourceRanges: false} : opts;
+}
+
 /**
  * Returns true when a line could start a new block — used to stop paragraph
  * continuation.  Every regex here uses bounded or single-class quantifiers
@@ -1213,7 +1274,7 @@ function parseList(
       itemText += '\n' + deindented.join('\n');
     }
 
-    items.push({checked, children: parseMarkdownImpl(itemText, opts)});
+    items.push({checked, children: parseMarkdownImpl(itemText, nested(opts))});
 
     // CommonMark loose list: blank line(s) between items of the same style
     // and indent still form one list. Skip the blanks and continue if the
@@ -1274,7 +1335,7 @@ function parseMarkdownImpl(
   // definitions win on conflict, matching CommonMark's first-definition-wins
   // in document order; locally-nested definitions still resolve within this
   // parse.
-  const {defs, cleaned} = extractLinkDefinitions(input);
+  const {defs, cleaned, lineMap} = extractLinkDefinitions(input);
   const inherited = baseOpts.linkDefs;
   let linkDefs: ReadonlyMap<string, string> | undefined;
   if (defs.size === 0) {
@@ -1288,9 +1349,25 @@ function parseMarkdownImpl(
     linkDefs != null ? {...baseOpts, linkDefs} : baseOpts;
   const lines = cleaned.split('\n');
   const blocks: BlockNode[] = [];
+  // The line each block started on, parallel to `blocks`. Only collected when
+  // ranges were asked for; a block's end is resolved after the loop, since the
+  // branch that produced it has already moved `index` past whatever it read.
+  const blockStartLines: number[] | null = opts.sourceRanges ? [] : null;
+  // Set only by a block that consumes blank lines as content, where the
+  // positional end derivation would trim them away.
+  const blockEndLines: (number | undefined)[] | null = opts.sourceRanges
+    ? []
+    : null;
+  let blockStartLine = 0;
+  const pushBlock = (node: BlockNode, endLine?: number) => {
+    blocks.push(node);
+    blockStartLines?.push(blockStartLine);
+    blockEndLines?.push(endLine);
+  };
   let index = 0;
 
   while (index < lines.length) {
+    blockStartLine = index;
     const line = lines[index];
     if (line.trim() === '') {
       index++;
@@ -1309,14 +1386,20 @@ function parseMarkdownImpl(
         index++;
       }
       index++; // skip closing fence
-      blocks.push({type: 'codeblock', language, content: codeLines.join('\n')});
+      // A fence owns its blank lines, and an unterminated one (mid-stream)
+      // can end on them, so it states its own end rather than letting the
+      // positional derivation trim them off.
+      pushBlock(
+        {type: 'codeblock', language, content: codeLines.join('\n')},
+        Math.min(index, lines.length) - 1,
+      );
       continue;
     }
 
     // --- Heading ---
     const headingMatch = line.match(/^(#{1,6}) +(.*)/);
     if (headingMatch) {
-      blocks.push({
+      pushBlock({
         type: 'heading',
         level: headingMatch[1].length as 1 | 2 | 3 | 4 | 5 | 6,
         children: parseInlineEntry(headingMatch[2], opts),
@@ -1327,15 +1410,21 @@ function parseMarkdownImpl(
 
     // --- HR (must precede list check to handle `- - -`, `* * *`, `_ _ _`) ---
     if (isHorizontalRule(line)) {
-      blocks.push({type: 'hr'});
+      pushBlock({type: 'hr'});
       index++;
       continue;
     }
 
     // --- Standalone image ---
+    // An unsafe src falls through to the paragraph path and renders as
+    // literal text, the same rule the inline image path applies.
     const imageMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)/);
-    if (imageMatch && line.trim() === imageMatch[0]) {
-      blocks.push({type: 'image', alt: imageMatch[1], src: imageMatch[2]});
+    if (
+      imageMatch &&
+      line.trim() === imageMatch[0] &&
+      isSafeUrl(imageMatch[2])
+    ) {
+      pushBlock({type: 'image', alt: imageMatch[1], src: imageMatch[2]});
       index++;
       continue;
     }
@@ -1347,7 +1436,7 @@ function parseMarkdownImpl(
       isTableSeparator(lines[index + 1])
     ) {
       const tableResult = parseTable(lines, index, opts);
-      blocks.push(tableResult.node);
+      pushBlock(tableResult.node);
       index = tableResult.nextIndex;
       continue;
     }
@@ -1362,9 +1451,9 @@ function parseMarkdownImpl(
         quoteLines.push(lines[index].replace(/^> ?/, ''));
         index++;
       }
-      blocks.push({
+      pushBlock({
         type: 'blockquote',
-        children: parseMarkdownImpl(quoteLines.join('\n'), opts),
+        children: parseMarkdownImpl(quoteLines.join('\n'), nested(opts)),
       });
       continue;
     }
@@ -1372,7 +1461,7 @@ function parseMarkdownImpl(
     // --- Unordered list ---
     if (/^ {0,9}[-*+] /.test(line)) {
       const listResult = parseList(lines, index, false, opts);
-      blocks.push(listResult.node);
+      pushBlock(listResult.node);
       index = listResult.nextIndex;
       continue;
     }
@@ -1380,7 +1469,7 @@ function parseMarkdownImpl(
     // --- Ordered list ---
     if (/^ {0,9}\d+[.)] /.test(line)) {
       const listResult = parseList(lines, index, true, opts);
-      blocks.push(listResult.node);
+      pushBlock(listResult.node);
       index = listResult.nextIndex;
       continue;
     }
@@ -1396,14 +1485,76 @@ function parseMarkdownImpl(
       paraLines.push(lines[index]);
       index++;
     }
-    blocks.push({
+    pushBlock({
       type: 'paragraph',
       children: parseInlineEntry(paraLines.join('\n'), opts),
     });
   }
+  if (blockStartLines != null) {
+    stampSourceRanges(
+      blocks,
+      blockStartLines,
+      blockEndLines ?? [],
+      lines,
+      lineMap,
+      input,
+      opts,
+    );
+  }
   return blocks;
 }
 
+/**
+ * Give each block the offsets it occupies in the original input.
+ *
+ * Blocks are contiguous and in source order, so a block runs from its own
+ * first line to the line before the next block starts, minus the blank lines
+ * between them. Offsets are computed against the *input*, not the text the
+ * block loop saw: link reference definitions are stripped before parsing, and
+ * `lineMap` says which input line each surviving line came from.
+ */
+function stampSourceRanges(
+  blocks: BlockNode[],
+  blockStartLines: number[],
+  blockEndLines: (number | undefined)[],
+  lines: string[],
+  lineMap: number[] | undefined,
+  input: string,
+  opts: ResolvedOptions,
+): void {
+  const base = opts.baseOffset ?? 0;
+  // Offset of the first character of every line of the input.
+  const inputLineStarts = [0];
+  for (let i = 0; i < input.length; i++) {
+    if (input[i] === '\n') {
+      inputLineStarts.push(i + 1);
+    }
+  }
+  // Stripping removes whole lines and never edits one, so a parsed line's
+  // length is its input line's length.
+  const lineStart = (line: number): number =>
+    base + inputLineStarts[lineMap != null ? lineMap[line] : line];
+
+  for (let i = 0; i < blocks.length; i++) {
+    const startLine = blockStartLines[i];
+    let endLine = blockEndLines[i];
+    if (endLine == null) {
+      const nextStart =
+        i + 1 < blocks.length ? blockStartLines[i + 1] : lines.length;
+      endLine = nextStart - 1;
+      while (endLine > startLine && lines[endLine].trim() === '') {
+        endLine--;
+      }
+    }
+    // Exactly the block's own lines, verbatim — a CRLF document's trailing
+    // `\r` included, since the parser reads it as part of the line too and a
+    // range that dropped it would slice to something that re-parses
+    // differently.
+    const end = lineStart(endLine) + lines[endLine].length;
+    blocks[i] = {...blocks[i], range: {start: lineStart(startLine), end}};
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Incremental parsing
 // ---------------------------------------------------------------------------
@@ -1420,6 +1571,12 @@ export interface IncrementalState {
    * with newly-arriving content.
    */
   autolink?: 'gfm';
+  /**
+   * The `sourceRanges` option the cached `settledBlocks` were parsed with.
+   * Flipping it invalidates them the same way `autolink` does: they either
+   * lack the ranges the caller now asks for, or carry ones it did not.
+   */
+  sourceRanges?: boolean;
   /**
    * Signature of the link reference definitions the cached `settledBlocks`
    * were parsed with. Definitions are document-global and typically arrive
@@ -1435,12 +1592,26 @@ export function createIncrementalState(): IncrementalState {
 
 /**
  * Find the line-index of the last blank line that is NOT inside a fenced code
- * block.  Returns -1 when nothing is settled (unclosed fence or no blank line).
+ * block, and report whether a fence is still open at the end of the input.
+ * Returns -1 when nothing is settled.
+ *
+ * This index must never move backwards as more of the document arrives. The
+ * caller's cache is keyed on the settled text staying a prefix of what it was,
+ * so a boundary that retracts by one line costs a re-parse of every block in
+ * the document. Two things used to retract it: a blank last line, which is
+ * just the newline the stream has written so far and stops being blank as soon
+ * as the next chunk appends to it; and an open fence, which used to collapse
+ * the boundary to -1 even though the content before the fence opened cannot be
+ * changed by anything typed inside it.
  */
-function findSettledBoundary(lines: string[]): number {
+function findSettledBoundary(lines: string[]): {
+  boundary: number;
+  openFence: boolean;
+} {
   let inFence = false;
   let fenceMarker = '';
   let lastBoundary = -1;
+  let boundaryBeforeFence = -1;
 
   for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
     const line = lines[lineIndex];
@@ -1451,6 +1622,7 @@ function findSettledBoundary(lines: string[]): number {
       if (!inFence) {
         inFence = true;
         fenceMarker = fenceMatch[1];
+        boundaryBeforeFence = lastBoundary;
       } else if (
         fenceMatch[1].startsWith(fenceMarker[0]) &&
         fenceMatch[1].length >= fenceMarker.length
@@ -1460,12 +1632,20 @@ function findSettledBoundary(lines: string[]): number {
       }
     }
 
-    if (!inFence && line.trim() === '' && lineIndex > 0) {
+    if (
+      !inFence &&
+      line.trim() === '' &&
+      lineIndex > 0 &&
+      lineIndex < lines.length - 1
+    ) {
       lastBoundary = lineIndex;
     }
   }
 
-  return inFence ? -1 : lastBoundary;
+  return {
+    boundary: inFence ? boundaryBeforeFence : lastBoundary,
+    openFence: inFence,
+  };
 }
 
 /**
@@ -1689,6 +1869,15 @@ function trimUnsettledStructural(text: string): string {
   return lines.join('\n');
 }
 
+/**
+ * The same options, for parsing a slice that starts at `offset` of the
+ * document — so the slice's blocks report ranges into the whole document
+ * rather than into the slice.
+ */
+function atOffset(opts: ResolvedOptions, offset: number): ResolvedOptions {
+  return opts.sourceRanges ? {...opts, baseOffset: offset} : opts;
+}
+
 /**
  * Concatenate freshly-parsed delta blocks with previously-settled blocks,
  * merging adjacent same-style lists into a single loose list. The boundary
@@ -1718,6 +1907,11 @@ function mergeSettledBlocks(
       delimiter: prevLast.delimiter,
       loose: true,
       items: [...prevLast.items, ...deltaFirst.items],
+      // One list now, so one range: from where the first half started to
+      // where the second half ended.
+      ...(prevLast.range != null && deltaFirst.range != null
+        ? {range: {start: prevLast.range.start, end: deltaFirst.range.end}}
+        : null),
     };
     return [...prev.slice(0, -1), merged, ...delta.slice(1)];
   }
@@ -1740,15 +1934,19 @@ export function parseMarkdownIncremental(
   arg?: ReadonlySet<string> | ParseOptions,
 ): BlockNode[] {
   const opts = resolveOptions(arg);
-  // Invalidate cache when the autolink option flips — cached settled blocks
-  // were parsed with the previous setting and would otherwise be reused
-  // unchanged.
-  if (state.autolink !== opts.autolink) {
+  // Invalidate cache when the autolink or sourceRanges option flips — cached
+  // settled blocks were parsed with the previous setting and would otherwise
+  // be reused unchanged.
+  if (
+    state.autolink !== opts.autolink ||
+    Boolean(state.sourceRanges) !== Boolean(opts.sourceRanges)
+  ) {
     state.prevInput = '';
     state.settledText = '';
     state.settledBlocks = [];
     state.settledUpTo = 0;
     state.autolink = opts.autolink;
+    state.sourceRanges = opts.sourceRanges;
   }
   if (input === '') {
     state.prevInput = '';
@@ -1776,17 +1974,23 @@ export function parseMarkdownIncremental(
     linkDefs.size > 0 ? {...opts, linkDefs} : opts;
 
   const lines = input.split('\n');
-  const boundary = findSettledBoundary(lines);
+  const {boundary, openFence} = findSettledBoundary(lines);
 
   if (boundary < 0) {
-    // Inside an unclosed fence or no blank-line boundary — full re-parse
+    // Nothing settled yet — no blank line, or a fence opened before the first
+    // one — so there is no prefix to keep and the whole input is re-parsed.
     state.prevInput = input;
     return parseMarkdownImpl(input, parseOpts);
   }
 
   const settledText = lines.slice(0, boundary).join('\n');
   const unsettledRaw = lines.slice(boundary).join('\n').trim();
-  const unsettledText = trimUnsettledStructural(unsettledRaw);
+  // Structural trimming holds back lines that look like an incomplete list or
+  // table, which inside a fence is ordinary code: a TypeScript union or a `- `
+  // would disappear from the code block as it streams.
+  const unsettledText = openFence
+    ? unsettledRaw
+    : trimUnsettledStructural(unsettledRaw);
 
   let settledBlocks: BlockNode[];
 
@@ -1799,15 +2003,32 @@ export function parseMarkdownIncremental(
   ) {
     // Settled portion grew — parse only the new delta
     const delta = settledText.slice(state.settledText.length);
-    const deltaBlocks = parseMarkdownImpl(delta, parseOpts);
+    const deltaBlocks = parseMarkdownImpl(
+      delta,
+      atOffset(parseOpts, state.settledText.length),
+    );
     settledBlocks = mergeSettledBlocks(state.settledBlocks, deltaBlocks);
   } else {
     // Content before the boundary changed — full re-parse of settled portion
     settledBlocks = parseMarkdownImpl(settledText, parseOpts);
   }
 
+  // The unsettled tail is trimmed before parsing, so its offset in the
+  // document is where that trimmed text actually starts — not the boundary,
+  // which is a line index. If it somehow can't be located, parse it without
+  // ranges rather than report wrong ones. Only worth searching for when
+  // ranges were asked for: this runs on every streamed chunk.
+  const unsettledStart =
+    unsettledText && opts.sourceRanges
+      ? input.indexOf(unsettledText, settledText.length)
+      : -1;
   const unsettledBlocks = unsettledText
-    ? parseMarkdownImpl(unsettledText, parseOpts)
+    ? parseMarkdownImpl(
+        unsettledText,
+        unsettledStart >= 0
+          ? atOffset(parseOpts, unsettledStart)
+          : nested(parseOpts),
+      )
     : [];
 
   state.settledText = settledText;

package/src/MetadataList/MetadataList.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MetadataList} from './MetadataList';
 import {MetadataListItem} from './MetadataListItem';
@@ -223,3 +223,76 @@ describe('MetadataListItem', () => {
     expect(wrapper?.querySelector('dd')).toBeInTheDocument();
   });
 });
+
+describe('MetadataListItem pass-through props', () => {
+  it('forwards pass-through props to the item element', () => {
+    render(
+      <MetadataList>
+        <MetadataListItem
+          label="Owner"
+          aria-label="Owner field"
+          id="owner"
+          data-source="crm"
+          data-testid="item">
+          Alice
+        </MetadataListItem>
+      </MetadataList>,
+    );
+    const item = screen.getByTestId('item-label');
+    expect(item).toHaveAttribute('aria-label', 'Owner field');
+    expect(item).toHaveAttribute('id', 'owner');
+    expect(item).toHaveAttribute('data-source', 'crm');
+  });
+
+  it('forwards pass-through props in the stacked layout', () => {
+    render(
+      <MetadataList orientation="horizontal">
+        <MetadataListItem label="Owner" id="owner-stacked" data-testid="item">
+          Alice
+        </MetadataListItem>
+      </MetadataList>,
+    );
+    expect(screen.getByTestId('item')).toHaveAttribute('id', 'owner-stacked');
+  });
+});
+
+describe('MetadataListItem pass-through target', () => {
+  it('lands pass-through props on the <dt> in the inline layout, where the ref also goes', () => {
+    const handleClick = vi.fn();
+    render(
+      <MetadataList>
+        <MetadataListItem
+          label="Owner"
+          onClick={handleClick}
+          data-testid="item">
+          Alice
+        </MetadataListItem>
+      </MetadataList>,
+    );
+
+    const label = screen.getByTestId('item-label');
+    expect(label.tagName).toBe('DT');
+    fireEvent.click(label);
+    expect(handleClick).toHaveBeenCalledOnce();
+
+    fireEvent.click(screen.getByTestId('item-value'));
+    expect(handleClick).toHaveBeenCalledOnce();
+  });
+
+  it('lands them on the wrapper in the stacked layout, so both halves are covered', () => {
+    const handleClick = vi.fn();
+    render(
+      <MetadataList orientation="horizontal">
+        <MetadataListItem
+          label="Owner"
+          onClick={handleClick}
+          data-testid="item">
+          Alice
+        </MetadataListItem>
+      </MetadataList>,
+    );
+
+    fireEvent.click(screen.getByText('Alice'));
+    expect(handleClick).toHaveBeenCalledOnce();
+  });
+});

package/src/MetadataList/MetadataListItem.tsx

@@ -144,6 +144,7 @@ export function MetadataListItem({
   style,
   'data-testid': testId,
   ref,
+  ...rest
 }: MetadataListItemProps) {
   const ctx = use(MetadataListContext);
   const labelPosition = ctx?.labelConfig.position ?? 'start';
@@ -170,7 +171,8 @@ export function MetadataListItem({
           stylex.props(styles.stackedWrapper, xstyle),
           className,
           style,
-        )}>
+        )}
+        {...rest}>
         <dt {...stylex.props(styles.stackedLabel)}>{labelContent}</dt>
         <dd {...stylex.props(styles.stackedValue)}>{children}</dd>
       </div>
@@ -188,7 +190,8 @@ export function MetadataListItem({
           stylex.props(styles.label, xstyle),
           className,
           style,
-        )}>
+        )}
+        {...rest}>
         {labelContent}
       </dt>
       <dd