# Typography

A cross-platform text component with predefined style variants, themed colours, and product-context-aware sizing.

## Installation

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

## Imports

```tsx
import { Typography } from "@xsolla/xui-typography";
```

## Quick start

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

export default function QuickStart() {
  return <Typography variant="bodyMd">Hello world</Typography>;
}
```

## API Reference

### `<Typography>`

| 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`       | `ReactNode`                                               | -                        | Text content.                                                                                                                                                  |
| `variant`        | `VariantType`                                             | `"bodyMd"`               | Text style variant (see below).                                                                                                                                |
| `color`          | `ColorType \| string`                                     | `"inherit"`              | Themed colour token, or a custom CSS colour string.                                                                                                            |
| `align`          | `"left" \| "center" \| "right" \| "justify" \| "inherit"` | `"inherit"`              | Text alignment.                                                                                                                                                |
| `noWrap`         | `boolean`                                                 | `false`                  | Single-line truncation with ellipsis.                                                                                                                          |
| `marginTop`      | `number`                                                  | `0`                      | Top margin in pixels.                                                                                                                                          |
| `marginBottom`   | `number`                                                  | `0`                      | Bottom margin in pixels.                                                                                                                                       |
| `as`             | `ElementType`                                             | Auto-mapped for headings | HTML element to render (web only). Heading variants (h1-h5) automatically render as semantic HTML elements (`<h1>`-`<h5>`). Can be overridden for any variant. |
| `productContext` | `"b2c" \| "b2b"`                                          | -                        | Override the product context for this instance only.                                                                                                           |
| `aria-hidden`    | `boolean`                                                 | -                        | Hide from assistive technology.                                                                                                                                |
| `aria-live`      | `"polite" \| "assertive" \| "off"`                        | -                        | Live-region politeness.                                                                                                                                        |

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

#### `VariantType`

```ts
type VariantType =
  | "display"
  | "h1"
  | "h2"
  | "h3"
  | "h4"
  | "h5"
  | "bodyLg"
  | "bodyLgAccent"
  | "bodyLgParagraph"
  | "bodyMd"
  | "bodyMdAccent"
  | "bodyMdParagraph"
  | "bodySm"
  | "bodySmAccent"
  | "bodySmParagraph"
  | "bodyXs"
  | "bodyXsAccent"
  | "bodyXsParagraph"
  | "bodyXxs"
  | "bodyXxsAccent"
  | "bodyXxsParagraph";
```

`*Accent` variants use weight 500. `*Paragraph` variants use a relaxed line height suitable for long-form copy.

#### `ColorType`

```ts
type ColorType =
  | "inherit"
  | "primary"
  | "secondary"
  | "tertiary"
  | "brand"
  | "brandSecondary"
  | "success"
  | "warning"
  | "alert"
  | "neutral";
```

`color` also accepts any string (for example, a hex or CSS variable) for custom colours.

## Examples

### Headings

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

export default function Headings() {
  return (
    <div>
      <Typography variant="display">Display</Typography>
      <Typography variant="h1">Heading 1</Typography>
      <Typography variant="h2">Heading 2</Typography>
      <Typography variant="h3">Heading 3</Typography>
      <Typography variant="h4">Heading 4</Typography>
      <Typography variant="h5">Heading 5</Typography>
    </div>
  );
}
```

### Body and accent

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

export default function Body() {
  return (
    <div>
      <Typography variant="bodyLg">Large body</Typography>
      <Typography variant="bodyLgAccent">Large body accent</Typography>
      <Typography variant="bodyMd">Medium body (default)</Typography>
      <Typography variant="bodyMdParagraph">Medium body paragraph</Typography>
      <Typography variant="bodyXxs">Extra-extra-small body</Typography>
    </div>
  );
}
```

### Colours

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

export default function Colours() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 4 }}>
      <Typography color="primary">Primary</Typography>
      <Typography color="secondary">Secondary</Typography>
      <Typography color="tertiary">Tertiary</Typography>
      <Typography color="brand">Brand</Typography>
      <Typography color="success">Success</Typography>
      <Typography color="warning">Warning</Typography>
      <Typography color="alert">Alert</Typography>
    </div>
  );
}
```

### Truncation

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

export default function Truncation() {
  return (
    <div style={{ width: 200 }}>
      <Typography variant="bodyMd" noWrap>
        This long text will be truncated with an ellipsis.
      </Typography>
    </div>
  );
}
```

### Product context override

```tsx
import * as React from "react";
import { Typography } from "@xsolla/xui-typography";
import { XUIProvider } from "@xsolla/xui-core";

export default function ContextOverride() {
  return (
    <XUIProvider initialProductContext="b2b">
      <Typography variant="h1">Default (B2B from provider)</Typography>
      <Typography variant="h1" productContext="b2c">B2C override</Typography>
    </XUIProvider>
  );
}
```

### Semantic HTML

Heading variants automatically render as semantic HTML for accessibility and SEO:

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

export default function SemanticHeadings() {
  return (
    <article>
      <Typography variant="h1">Main Article Title</Typography>
      <Typography variant="bodyMdParagraph">
        This is the introduction paragraph.
      </Typography>

      <Typography variant="h2">Section Title</Typography>
      <Typography variant="bodyMdParagraph">
        This section contains important content.
      </Typography>

      <Typography variant="h3">Subsection</Typography>
      <Typography variant="bodyMd">Some additional details.</Typography>
    </article>
  );

  // Renders as:
  // <article>
  //   <h1 class="...">Main Article Title</h1>
  //   <p class="...">This is the introduction paragraph.</p>
  //   <h2 class="...">Section Title</h2>
  //   <p class="...">This section contains important content.</p>
  //   <h3 class="...">Subsection</h3>
  //   <span class="...">Some additional details.</span>
  // </article>
}
```

You can override the default element with the `as` prop:

```tsx
// Render h1 styling as a div instead of h1
<Typography variant="h1" as="div">
  Styled as heading but rendered as div
</Typography>
```

## Behaviour

- Resolved sizes, weights, and line heights come from the active product context. With no override, the provider's `initialProductContext` (defaulting to `b2b`) is used.
- The `Accent` family raises weight to 500; `Paragraph` family raises line height for readable long-form copy.
- `as` is web-only; on native platforms the rendered element is fixed.

## Accessibility

- Heading variants (`h1`-`h5`) automatically render as semantic HTML elements (`<h1>`-`<h5>`) for proper document structure and screen reader navigation.
- Use heading variants in document order to create a logical heading hierarchy.
- Body variants render as `<span>` by default; use the `as` prop to render as `<p>` for paragraph text or other semantic elements as needed.
- `aria-live` is available for live-region announcements when content updates dynamically.
- Avoid using `noWrap` on copy that the user must read in full; prefer wrapping or a tooltip for the truncated value.