first commit

docs/ui/react/react-ui/src/i18n/plural/plural.md

@@ -0,0 +1,66 @@
+# `<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.