<!-- 04_VISUAL/xwui/xwui-lib/xwui-lib-basic/src/text/XWUILiveText/XWUILiveText.md -->
# XWUILiveText

Visible text that is also a live region. The words stay on screen and, when `setText()` changes them later, assistive technology announces the change (a "Copied" note, an "N of M shown" count, a hover readout). It composes `XWUITypography` for the look (same `variant`, `weight`, `color`, `component`, `className` names as the page kits' `text()` helper, plus a `size` step of the type scale) and replaces the hidden `XWUIAnnounce` that used to sit beside such a label: `XWUIAnnounce` is visually hidden by design, `XWUILiveText` is the text people read.

The live region is a wrapper `div` around the typography run. It exists from the first render (empty when the text is empty), is never `aria-hidden`, and is never re-created: a text change, a `variant` change or a politeness change patches it in place.

## Basic Usage

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: An empty polite note that a Copy button fills with 'Copied' and clears again.
```

## Results count

```example
file: examples/ResultsCount.ts
html: examples/ResultsCount.html
title: Results count
description: A visible 'N of M shown' count: atomic, so the whole sentence is read on each change.
```

## Settled counter

```example
file: examples/SettledCounter.ts
html: examples/SettledCounter.html
title: Settled counter
description: A counter that ticks every 25 ms with settleMs 500: the reader hears the value at rest, not 40 numbers.
```

## Data

`text`: the words, plain text (a text node, never HTML). Setting it through `setText()`, `updateData({ text })` or the element's `data` goes through the rules below.

## Options

| Option | Default | What it does |
| --- | --- | --- |
| `politeness` | `'polite'` | `polite` (`role="status"`), `assertive` (`role="alert"`) or `off` (text stays, no announcement, no role). |
| `atomic` | `true` | `aria-atomic`: read the whole run on a change, not only the part that changed. |
| `relevant` | unset | `aria-relevant` (`additions`, `removals`, `text`, `all`, `additions text`). Unset leaves the browser default. |
| `dir` | `'auto'` | `auto` follows the first strong character (a note whose language changes reads right either way); `ltr`, `rtl`; `inherit` writes no `dir`. |
| `announceInitial` | `false` | Announce the text the component is created with. The region is created empty and the text is written 100 ms later, because a region that already holds text when it appears is not announced. |
| `dedupe` | `true` | Setting the text it already shows does nothing. `false` re-announces it (a silent zero-width mark alternates so the browser sees a change). |
| `settleMs` | `0` | Wait before a change is shown and announced; a newer text inside the window replaces it, and a burst that ends on the text already shown writes nothing. Capped at 10000. |
| `size` | unset | A step of the type scale: `xs`, `sm`, `base`, `lg`, `xl`, `2xl` (`--font-size-<size>`). |
| `variant`, `component`, `color`, `textColor`, `weight`, `align`, `italic`, `underline`, `strikethrough`, `noWrap`, `whiteSpace`, `textWrap`, `inline`, `case`, `letterSpacing`, `lineHeight`, `fontFamily`, `role`, `kashida*`, `className` | the kit defaults: `body`, `span`, `inherit` | Passed to `XWUITypography` unchanged (see its contract). `className` lands on the text run. `attrs`, `ariaLabel`, `ariaRole` and `srOnly` are not passed: the region owns the semantics. |

## Events and methods

`setText(next)` shows and announces `next`; `getText()` is the text last asked for (also while a settle window holds it back); `onAnnounce(handler)` fires when the text reaches the region and returns a disposer; `updateConfig(patch)`, `getElement()` (the live region), `destroy()` (clears the settle timer).

Headless: `createXWUILiveTextLogic(data, config)` with `request(text)` (returns `'noop' | 'commit' | 'defer'`), `commit()`, `getText()`, `isPending()`.

## Accessibility and RTL

The wrapper carries `role`, `aria-live`, `aria-atomic`, `aria-relevant` and `dir`; the run carries none of them. The classic live-region rule holds: the region is in the tree before its text changes. The first text is not announced unless `announceInitial` is on. Changes are announced once per `settleMs` window. There is no motion, no colour of its own and no physical property: it mirrors under a parent `dir="rtl"`, with `dir="auto"` choosing the run's direction from its content.

When to use which: `XWUILiveText` for text people read and that changes (`aria-live` on visible text); `XWUIAnnounce` for a message nobody sees (a screen-reader-only toast).

```api
```