@astryxdesign/core 0.6.1 → 0.6.2

package/src/FileInput/FileInput.spec.md

@@ -0,0 +1,199 @@
+---
+schema_version: 3
+template_version: 4
+kind: component
+id: component:FileInput
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-14
+owners: [cixzhang, imdreamrunner]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/FileInput/FileInput.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:input-fields]
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# FileInput component contract
+
+## Intent
+
+FileInput presents a labelled file-selection field in compact input or dropzone
+form. This contract records its current consumer anatomy and approves separate theme
+ownership for the upload affordance that FileInput paints through Icon.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive public theming target; no existing target,
+  runtime default, DOM, prop, interaction, or accessibility behavior changes
+- Controlled/uncontrolled behavior: unchanged; FileInput remains controlled
+- Migration decision: `component:FileInput/DEC-1`
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The visible file-selection surface and its input/dropzone mode.
+- Whether, where, and at what default size the upload affordance appears.
+- Reflecting FileInput's mode on its locally owned theme targets.
+
+**Does not own / non-goals**
+
+- The upload artwork or Icon's base color, size, and accessibility semantics —
+  owned by `component:Icon`.
+- Label, description, clear-control, and validation-message presentation — owned
+  by `component:Field` and `component:FieldStatus`.
+- Loading-indicator presentation — owned by `component:Spinner`.
+- A new prop, variant, icon slot, or custom property.
+
+## Public concepts
+
+No consumer prop changes. The `file-input-icon` target gives themes a
+same-element seam for the Upload icon and reflects the existing `mode` axis. The
+existing `file-input` target remains on the visible selection surface and keeps
+its `mode` and `status` axes.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                  | Basis                                             | Review state                    |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------- |
+| FR1 | The visible selection surface carries `file-input` and reflects the existing `mode` and resolved status.                                                                                                             | Current source, public docs, and focused tests    | Verified current behavior       |
+| FR2 | When not loading, input mode renders an upload affordance at the small Icon size. Dropzone mode renders it at the medium Icon size only while no file is selected.                                                   | Current source and focused tests                  | Verified current behavior       |
+| FR3 | Icon owns the rendered glyph's base size, color, and accessibility semantics; FileInput owns the affordance's mode-dependent placement and default size.                                                             | Current composition and component boundaries      | Verified current composition    |
+| FR4 | The rendered upload affordance MUST carry `file-input-icon` with the existing `mode` reflected, so a theme can restyle the glyph box without structural selectors or changing every Icon that uses the same artwork. | Owner-approved target contract                    | Approved additive contract      |
+| FR5 | Adding the target MUST NOT change the default artwork, computed layout, interaction, file-selection behavior, accessible name, or decorative Icon semantics.                                                         | Compatibility policy and focused regression tests | Required compatibility behavior |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may change standard visual
+  properties such as the upload glyph's size or color through
+  `file-input-icon`; FileInput still owns whether and where the affordance renders.
+- **AV2 — Artwork.** Icon registry and future icon-slot decisions may change the
+  artwork without changing this CSS target's ownership of the painted glyph box.
+
+### Representative states
+
+| State                    | Required invariant                                                       | Allowed variation                       |
+| ------------------------ | ------------------------------------------------------------------------ | --------------------------------------- |
+| Input, empty or selected | Small upload affordance renders on the input surface when not loading.   | Files, placeholder, status, theme paint |
+| Dropzone, empty          | Medium upload affordance renders above the placeholder when not loading. | Drag state, placeholder, theme paint    |
+| Dropzone, selected       | File names replace the upload affordance.                                | File names and status                   |
+| Loading                  | Spinner replaces the upload affordance.                                  | Mode and loading presentation           |
+
+### Transformation and precedence order
+
+- **ORD1 — Content selection.** Resolve loading and selected-file state, choose
+  input or dropzone content, then render the mode-sized upload affordance only in
+  the states recorded by FR2.
+- **ORD2 — Theme composition.** Icon applies its base size and color, then the
+  same-element FileInput target participates in the existing theme layer and
+  standard Icon styling merge order.
+
+### Performance and resources
+
+- **PR1 — No new work.** The additive target performs no measurement, listener,
+  observer, state update, or additional render pass.
+
+## Accessibility contract
+
+The upload affordance remains decorative. The existing focusable file-selection
+trigger, label, description, required/invalid state, disabled explanation, and
+selection announcements remain unchanged.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                  | Representation authority                 | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- | -------------- | ------------------ |
+| Drop zone        | Presents the visible file-selection surface in input or dropzone form.              | Current source and public docs           | Prominent      | FR1                |
+| Upload icon      | Hints at the upload action and changes default size with the selected mode.         | Current source and owner-approved target | Supporting     | FR2, FR3, FR4      |
+| Shared feedback  | Uses Field, FieldStatus, and Spinner for labels, validation, and loading treatment. | Current shared composition               | Supporting     | FR5                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Label": {
+    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+  },
+  "Description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
+    }
+  },
+  "Drop zone": {"target": "file-input"},
+  "Upload icon": {"target": "file-input-icon"},
+  "Placeholder": {"inherits": "file-input"},
+  "File name display": {"inherits": "file-input"},
+  "Clear button": {
+    "delegatesTo": {
+      "owner": "component:Field",
+      "target": "input-clear-button"
+    }
+  },
+  "Spinner": {
+    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+  },
+  "Status message": {
+    "delegatesTo": {
+      "owner": "component:FieldStatus",
+      "target": "field-status"
+    }
+  }
+}
+```
+
+The `file-input-icon` disposition records the approved target state. Icon still
+owns the general `icon` target and base glyph semantics; FileInput's narrower
+target owns only this stable upload position and its existing mode distinction.
+
+## Family and system relationships
+
+- `family:input-fields` owns shared labelled-field and validation behavior.
+- `architecture:component-theming-surface` owns target qualification, anatomy
+  mapping, and the requirement that public targets sit on stable painted parts.
+- Field, FieldStatus, Icon, and Spinner retain their existing public target
+  contracts when composed by FileInput.
+
+## Verification map
+
+| Contract            | Verification                                                      | Representative states                              | Mutation or failure expectation                                                                             | Audit section             |
+| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR2            | `FileInput.test.tsx` rendering and target suites                  | Input/dropzone; empty/selected/loading             | Moving the root target or changing when/at what size the affordance renders breaks focused assertions.      | `audit:FileInput/theming` |
+| FR3, FR4, FR5       | `FileInput.test.tsx`, `themingTargets.test.ts`, probe-theme check | Both modes and same-element Icon target            | Missing the target, reflecting the wrong mode, or moving it off the glyph fails source/docs/probe coverage. | `audit:FileInput/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                     | Nine anatomy entries and two locally owned targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation.                             | `audit:FileInput/anatomy` |
+
+## Decision log
+
+### DEC-1 — Upload icon is stable FileInput theme anatomy
+
+**Reference:** `component:FileInput/DEC-1`
+**Decider:** cixzhang, 2026-09-14
+
+The upload icon is a stable, consumer-recognizable FileInput affordance whose
+mode-dependent placement and default size belong to FileInput. It receives the
+`file-input-icon` target on the same Icon element that paints the glyph, while
+Icon retains its general target and base glyph semantics.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or shared-component contracts. It links to their owners.

package/src/FileInput/FileInput.test.tsx

@@ -119,6 +119,20 @@ describe('FileInput', () => {
     expect(screen.getByText('Drop here')).toBeInTheDocument();
   });
 
+  it.each([
+    {mode: 'input' as const, size: 'sm'},
+    {mode: 'dropzone' as const, size: 'md'},
+  ])('exposes the upload icon as a $mode theme target', ({mode, size}) => {
+    render(
+      <FileInput label="Upload" mode={mode} value={null} onChange={() => {}} />,
+    );
+
+    const icon = document.querySelector('.astryx-file-input-icon');
+    expect(icon).toHaveClass('astryx-icon');
+    expect(icon).toHaveAttribute('data-mode', mode);
+    expect(icon).toHaveAttribute('data-size', size);
+  });
+
   it('displays selected file name', () => {
     const file = createFile('report.pdf', 1024, 'application/pdf');
     render(<FileInput label="Document" value={file} onChange={() => {}} />);

package/src/FileInput/FileInput.tsx

@@ -5,7 +5,7 @@
 /**
  * @file FileInput.tsx
  * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
- * @output Exports FileInput component, FileInputProps, FileInputStatus
+ * @output Exports FileInput component, public types, and its root/icon theme targets
  * @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -707,7 +707,12 @@ export function FileInput({
     }
     return (
       <>
-        <Icon icon="arrowUp" size="md" color="secondary" />
+        <Icon
+          icon="arrowUp"
+          size="md"
+          color="secondary"
+          {...themeProps('file-input-icon', {mode})}
+        />
         <span {...stylex.props(styles.placeholderText)}>
           {isDragOver ? t('@astryx.fileInput.dropHint') : displayPlaceholder}
         </span>
@@ -728,7 +733,12 @@ export function FileInput({
     }
     return (
       <>
-        <Icon icon="arrowUp" size="sm" color="secondary" />
+        <Icon
+          icon="arrowUp"
+          size="sm"
+          color="secondary"
+          {...themeProps('file-input-icon', {mode})}
+        />
         <span
           {...stylex.props(
             hasFiles ? styles.fileNameText : styles.placeholderText,

package/src/Markdown/Markdown.doc.mjs

@@ -5,8 +5,7 @@ const anatomy = [
   {
     name: 'Document',
     required: true,
-    description:
-      'Root container for block or inline Markdown content.',
+    description: 'Root container for block or inline Markdown content.',
   },
   {
     name: 'Heading',
@@ -41,7 +40,8 @@ const anatomy = [
   {
     name: 'Table',
     required: false,
-    description: 'Scrollable table block rendered from Markdown rows and columns.',
+    description:
+      'Scrollable table block rendered from Markdown rows and columns.',
   },
   {
     name: 'Divider',
@@ -138,14 +138,14 @@ export const docs = {
       name: 'contentAlign',
       type: "'start' | 'center'",
       description:
-        "Alignment of prose content within the container when contentWidth is narrower than the available space.",
+        'Alignment of prose content within the container when contentWidth is narrower than the available space.',
       default: "'start'",
     },
     {
       name: 'inlinePlugins',
       type: 'MarkdownInlinePlugin[]',
       description:
-        'Transforms regex matches in parsed text nodes into custom inline React elements. Use for issue refs, diff refs, mentions, and other shorthand patterns. Inline code and fenced code blocks are unaffected.',
+        'Transforms regex matches in parsed text nodes into custom inline React elements. Use for prefixed identifiers, mentions, and other shorthand patterns. Inline code, fenced code blocks, and math are unaffected.',
     },
     {
       name: 'autolink',
@@ -156,7 +156,8 @@ export const docs = {
     {
       name: 'components',
       type: 'MarkdownComponents',
-      description: 'Custom React component overrides for rendered Markdown elements (code, inlineCode, link, heading, paragraph, image, blockquote, hr, citation).',
+      description:
+        'Custom React component overrides for rendered Markdown elements (code, inlineCode, math, link, heading, paragraph, image, blockquote, hr, citation). Providing math enables `$…$` inline and `$$…$$` display parsing and receives `{value, display}`; omit it when dollar text should stay literal.',
     },
     {
       name: 'xstyle',
@@ -184,7 +185,8 @@ export const docs = {
   ],
   playground: {
     defaults: {
-      children: '## Getting Started\n\nInstall the package:\n\n```bash\nnpm install @astryxdesign/core\n```\n\nThen import and use any component:\n\n```tsx\nimport {Button} from \'@astryxdesign/core/Button\';\n```\n\n**Bold**, *italic*, and `inline code` all work.',
+      children:
+        "## Getting Started\n\nInstall the package:\n\n```bash\nnpm install @astryxdesign/core\n```\n\nThen import and use any component:\n\n```tsx\nimport {Button} from '@astryxdesign/core/Button';\n```\n\n**Bold**, *italic*, and `inline code` all work.",
     },
   },
   theming: {
@@ -229,11 +231,41 @@ export const docs = {
     description:
       'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
-      { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
-      { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
-      { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
-      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
-      { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
+      {
+        guidance: true,
+        description:
+          'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use contentWidth to keep prose at a readable line length in wide layouts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide components.math only for documents that use dollar-delimited math. The renderer owns typesetting and accessible output; Astryx passes the expression as text and never executes raw HTML.',
+      },
+      {
+        guidance: true,
+        description:
+          'For direct parsing, use MathParseOptions and handle InlineNodeWithMath or BlockNodeWithMath. Incremental math parsing also uses createIncrementalState<true>() and IncrementalParseState<true>; default calls and ParseOptions annotations keep the legacy unions.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',
+      },
     ],
   },
   examples: [
@@ -259,23 +291,38 @@ import {Text} from '@astryxdesign/core/Text';
 `,
     },
     {
-      label: 'Inline Plugins',
+      label: 'Entity links',
       code: `
 import {Link} from '@astryxdesign/core/Link';
 
-const issuePlugins = [
+const entityPlugins = [
   {
     pattern: /\\b([A-Z][A-Z0-9]+-\\d+)\\b/g,
     render: (match, key) => (
-      <Link key={key} href={\`/issues/\${match[1]}\`}>
+      <Link key={key} href={\`/entities/\${match[1]}\`}>
         {match[0]}
       </Link>
     ),
   },
 ];
 
-<Markdown inlinePlugins={issuePlugins}>
-  {'Fixed PROJ-123. Inline code stays plain: \`PROJ-999\`.'}
+<Markdown inlinePlugins={entityPlugins}>
+  {'See DOC-2048. Inline code stays plain: \`DOC-9999\`.'}
+</Markdown>;
+`,
+    },
+    {
+      label: 'Math renderer',
+      code: `
+import {BlockMath, InlineMath} from 'react-katex';
+
+function MathExpression({value, display}) {
+  const Component = display === 'block' ? BlockMath : InlineMath;
+  return <Component math={value} />;
+}
+
+<Markdown components={{math: MathExpression}}>
+  {'Inline $x_1 + y$ and display math:\\n\\n$$\\n\\\\sum_i x_i\\n$$'}
 </Markdown>;
 `,
     },
@@ -315,8 +362,7 @@ export const docsZh = {
     {
       name: 'isStreaming',
       type: 'boolean',
-      description:
-        '启用流式模式，使用增量解析和淡入动画处理分块文本。',
+      description: '启用流式模式，使用增量解析和淡入动画处理分块文本。',
       default: 'false',
     },
     {
@@ -348,14 +394,14 @@ export const docsZh = {
       name: 'contentAlign',
       type: "'start' | 'center'",
       description:
-        "当 contentWidth 小于可用空间时，正文内容在容器内的对齐方式。",
+        '当 contentWidth 小于可用空间时，正文内容在容器内的对齐方式。',
       default: "'start'",
     },
     {
       name: 'inlinePlugins',
       type: 'MarkdownInlinePlugin[]',
       description:
-        '将已解析文本节点中的正则匹配转换为自定义内联 React 元素。适用于 issue 引用、diff 引用、用户提及等简写模式。内联代码和围栏代码块不受影响。',
+        '将已解析文本节点中的正则匹配转换为自定义内联 React 元素。适用于带前缀的标识符、用户提及等简写模式。内联代码、围栏代码块和数学表达式不受影响。',
     },
     {
       name: 'autolink',
@@ -363,6 +409,12 @@ export const docsZh = {
       description:
         "可选的裸 URL 和电子邮箱自动链接。设为 'gfm' 启用 GitHub Flavored Markdown 自动链接规则：裸 https?://、www.、<scheme:url>、<email> 以及 user@host 都会变成链接。末尾句末标点和不平衡的末尾右括号会被排除；代码块、现有链接和图片替代文本内部的匹配会被跳过。默认为关闭。",
     },
+    {
+      name: 'components',
+      type: 'MarkdownComponents',
+      description:
+        '用于覆盖 Markdown 渲染元素的自定义 React 组件（code、inlineCode、math、link、heading、paragraph、image、blockquote、hr、citation）。提供 math 会启用 `$…$` 行内数学和 `$$…$$` 块级数学解析，并接收 `{value, display}`；不提供时美元符号保持原样。',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -372,12 +424,14 @@ export const docsZh = {
     {
       name: 'className',
       type: 'string',
-      description: '根元素的 CSS 类名。建议使用 xstyle，className 适用于非 StyleX 系统集成。',
+      description:
+        '根元素的 CSS 类名。建议使用 xstyle，className 适用于非 StyleX 系统集成。',
     },
     {
       name: 'style',
       type: 'CSSProperties',
-      description: '根元素的内联样式。建议使用 xstyle，内联样式会绕过 StyleX 优化。',
+      description:
+        '根元素的内联样式。建议使用 xstyle，内联样式会绕过 StyleX 优化。',
     },
     {
       name: 'data-testid',
@@ -443,11 +497,41 @@ export const docsZh = {
     description:
       'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
-      { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
-      { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
-      { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
-      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
-      { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
+      {
+        guidance: true,
+        description:
+          'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use contentWidth to keep prose at a readable line length in wide layouts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide components.math only for documents that use dollar-delimited math. The renderer owns typesetting and accessible output; Astryx passes the expression as text and never executes raw HTML.',
+      },
+      {
+        guidance: true,
+        description:
+          'For direct parsing, use MathParseOptions and handle InlineNodeWithMath or BlockNodeWithMath. Incremental math parsing also uses createIncrementalState<true>() and IncrementalParseState<true>; default calls and ParseOptions annotations keep the legacy unions.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',
+      },
     ],
   },
 };
@@ -460,25 +544,66 @@ export const docsDense = {
     description:
       'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
-      { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
-      { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
-      { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns (issue refs, diff refs, mentions) instead of preprocessing the markdown string.' },
-      { guidance: true, description: 'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.' },
-      { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
+      {
+        guidance: true,
+        description:
+          'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use contentWidth to keep prose at a readable line length in wide layouts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide components.math only for documents that use dollar-delimited math; the renderer owns typesetting and accessible output.',
+      },
+      {
+        guidance: true,
+        description:
+          'Direct math parser calls use MathParseOptions and the explicit WithMath node unions; incremental calls also use createIncrementalState<true>() and IncrementalParseState<true>. Default calls keep the legacy unions.',
+      },
+      {
+        guidance: true,
+        description:
+          'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',
+      },
     ],
   },
   propDescriptions: {
     children: 'markdown string',
     density: "Block spacing. 'default'|'compact'. Default: 'default'.",
-    headingLevelStart: 'Maps # to this heading level (1-6). Clamped to h6. Default: 1.',
-    isStreaming: 'Incremental parse + fade-in for streamed chunks. Default: false.',
-    onLinkClick: '(href, event) => void|false. Return false prevents navigation.',
-    sources: 'Record<string, MarkdownSource>. Citation sources by ID. [id]/【id】 markers render as chips.',
-    citationStyle: "'label'|'number'. label=chip w/ title+icon, number=compact badge. Default: 'label'.",
-    contentWidth: 'number|string. Max width for prose (headings, paragraphs, lists). Tables/code unconstrained.',
-    contentAlign: "'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.",
-    inlinePlugins: 'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code.',
-    autolink: "'gfm'. Opt-in GFM autolinking: bare URLs (https?://, www.), <scheme:url>, <email>, user@host. Skips code, code blocks, existing links. Default: off.",
+    headingLevelStart:
+      'Maps # to this heading level (1-6). Clamped to h6. Default: 1.',
+    isStreaming:
+      'Incremental parse + fade-in for streamed chunks. Default: false.',
+    onLinkClick:
+      '(href, event) => void|false. Return false prevents navigation.',
+    sources:
+      'Record<string, MarkdownSource>. Citation sources by ID. [id]/【id】 markers render as chips.',
+    citationStyle:
+      "'label'|'number'. label=chip w/ title+icon, number=compact badge. Default: 'label'.",
+    contentWidth:
+      'number|string. Max width for prose (headings, paragraphs, lists). Tables/code unconstrained.',
+    contentAlign:
+      "'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.",
+    inlinePlugins:
+      'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code and math.',
+    autolink:
+      "'gfm'. Opt-in GFM autolinking: bare URLs (https?://, www.), <scheme:url>, <email>, user@host. Skips code, code blocks, existing links. Default: off.",
+    components:
+      'MarkdownComponents. Custom renderers; math({value, display}) opts into $…$/$$…$$ parsing. Renderer owns output and accessibility.',
     xstyle: 'stylex.create() for layout (margins, sizing).',
     className: 'CSS class. Prefer xstyle.',
     style: 'Inline styles. Prefer xstyle.',