# Markdown

A React component that renders markdown content with theme-aware typography (web only — built on `react-markdown` and `styled-components`).

## Installation

```bash
npm install @xsolla/xui-markdown
```

## Imports

```tsx
import { Markdown } from "@xsolla/xui-markdown";
```

## Quick start

```tsx
import * as React from "react";
import { Markdown } from "@xsolla/xui-markdown";

export default function QuickStart() {
  return <Markdown>{`# Hello\n\nThis is **bold** text.`}</Markdown>;
}
```

## API Reference

### `<Markdown>` (web only)

| Prop        | Type     | Default | Description                                                                                                   |
| ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `testID`    | `string` | —       | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |
| `children`  | `string` | —       | **Required.** Markdown source to render.                                                                      |
| `className` | `string` | —       | CSS class for the container.                                                                                  |

Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).

The component pulls heading and body fonts from the resolved theme (`theme.fonts.heading`, `theme.fonts.body`, falling back to `theme.fonts.primary`) and uses `theme.colors.content.primary`, `theme.colors.border.brand`, and `theme.colors.control.link.primary` for styling.

### Block spacing

Headings, paragraphs and images are spaced with **padding** (their margins are zeroed). The values come from `theme.sizing.markdown()`, which mirrors the Figma `markdown/{element}/padding-top|padding-bottom` tokens:

| Element | `padding-top` | `padding-bottom` |
| ------- | ------------- | ---------------- |
| `h1`    | 40px          | 8px              |
| `h2`    | 32px          | 8px              |
| `h3`    | 16px          | 8px              |
| `h4`    | 8px           | 8px              |
| `p`     | 0             | 16px             |
| `img`   | 0             | 24px             |

A paragraph inside a blockquote keeps `padding-bottom: 0`.

### Supported syntax

| Element          | Syntax                                  |
| ---------------- | --------------------------------------- |
| Headings (h1–h4) | `# text` … `#### text`                  |
| Bold             | `**text**`                              |
| Italic           | `*text*`                                |
| Link             | `[text](https://example.com)`           |
| Image            | `![alt](https://example.com/image.png)` |
| Inline code      | `` `code` ``                            |
| Code block       | ` ```language `                         |
| Blockquote       | `> quote`                               |
| Unordered list   | `- item`                                |
| Ordered list     | `1. item`                               |

## Examples

### Rich content

```tsx
import * as React from "react";
import { Markdown } from "@xsolla/xui-markdown";

export default function RichContent() {
  const content = `# Product documentation

## Getting started

1. Install the package
2. Configure your API keys
3. Initialise the SDK

> **Note:** keep keys out of source control.

\`\`\`javascript
import { SDK } from '@example/sdk';
const client = new SDK({ apiKey: process.env.API_KEY });
await client.initialize();
\`\`\`

Visit our [documentation](https://docs.example.com).`;

  return <Markdown>{content}</Markdown>;
}
```

### Live preview

```tsx
import * as React from "react";
import { Markdown } from "@xsolla/xui-markdown";

export default function LivePreview() {
  const [content, setContent] = React.useState("# Hello\n\nStart typing...");
  return (
    <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 16 }}>
      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
        style={{ height: 240, fontFamily: "monospace" }}
      />
      <div style={{ background: "#1a1a1a", padding: 16, borderRadius: 8 }}>
        <Markdown>{content}</Markdown>
      </div>
    </div>
  );
}
```

## Accessibility

- Headings produce a proper document outline.
- Links inherit the theme's link colour and underline on hover/focus.
- Provide alt text via standard markdown image syntax.
- Code blocks use semantic `<pre><code>` for screen readers.