# `<Plural>`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Selects one of the supplied children based on the CLDR plural rule for `value` against the active locale, through the `plural` formatter plugin. English collapses zero into `other`; Arabic distinguishes `zero`/`one`/`two`/`few`/`many`/`other`; Russian and Polish have language-specific buckets. The `other` slot is REQUIRED — every locale's CLDR ruleset has at least an `other` category, and TypeScript enforces that the consumer supplies it.

## Features

- TypeScript-enforced `other` slot.
- Optional `zero`, `one`, `two`, `few`, `many` slots — fall through to `other` when the active locale doesn't use the category OR the consumer didn't supply it.
- Children are arbitrary React nodes — strings, fragments, or composed primitives.

## Usage: Basic Example

```tsx
import { Plural, FormattedNumber } from "@suaveplan/react-ui";

<Plural
    value={count}
    one={<><FormattedNumber value={count} /> item</>}
    other={<><FormattedNumber value={count} /> items</>}
/>
```

## Usage: Advanced Example

A multi-category switch that renders correctly across English, Russian, and Arabic:

```tsx
<Plural
    value={n}
    one={<>{n} файл</>}
    few={<>{n} файла</>}
    many={<>{n} файлов</>}
    other={<>{n} файла</>}
/>
```

Combining with `<FormattedMessage>` for a fully translated phrase:

```tsx
<Plural
    value={unread}
    zero={<FormattedMessage i18nKey="inbox.empty" />}
    one={<FormattedMessage i18nKey="inbox.one" values={{ count: unread }} />}
    other={<FormattedMessage i18nKey="inbox.other" values={{ count: unread }} />}
/>
```

## API Reference

### `<Plural value other zero? one? two? few? many?>`

- `value: number` — selector.
- `other: ReactNode` — required.
- `zero | one | two | few | many?: ReactNode` — optional category slots.

Returns the React node for the selected category, falling back to `other` if a more specific category was not supplied.

## Implementation Notes

- The CLDR ruleset comes from `@suaveplan/i18n-icu-parser`'s `PluralizationEngine`. New locales pick up their categories automatically through that engine; this component does not maintain its own plural-rule table.
- For ICU `{count, plural, …}` messages stored in the catalog, prefer `<FormattedMessage>` with a `count` prop; this component is for inline composition where the categories' rendered children are React node compositions rather than translation keys.