@vjdesigns/vjdesigns-ui 2.0.0 → 2.1.0

package/dist/ai/llms-full.txt

@@ -1,4 +1,4 @@
-# @vjdesigns/vjdesigns-ui 1.5.0: full reference
+# @vjdesigns/vjdesigns-ui 2.0.0: full reference
 
 > Accessible React 19 component library: WCAG 2.2 AA verified (axe on every story, a contrast check on every color pair), 31 languages with right-to-left support, themeable with any brand color (auto-adjusted to stay accessible), tree-shakable, no runtime dependencies besides React.
 
@@ -12,500 +12,500 @@
 
 # Guide: Installation
 
-Install the package along with React and React DOM (version 18 or 19), which the components need in order to render:
-
-```bash
-npm install @vjdesigns/vjdesigns-ui react react-dom
-```
-
-If your project already uses React, you only need the first package:
-
-```bash
-npm install @vjdesigns/vjdesigns-ui
-```
-
-### Import the styles
-
-The component styles and shared design tokens ship as a separate stylesheet. Import it **once** at your app's entry point, or the components will render unstyled.
-
-**React:** in `main.tsx` (or `App.tsx`)
-
-```ts
-import "@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css";
-```
-
-**Angular:** add it to the `styles` array in `angular.json`
-
-```json
-"styles": [
-  "node_modules/@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css",
-  "src/styles.css"
-]
-```
-
-**Vue:** in `main.ts`
-
-```ts
-import "@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css";
+Install the package along with React and React DOM (version 18 or 19), which the components need in order to render:
+
+```bash
+npm install @vjdesigns/vjdesigns-ui react react-dom
+```
+
+If your project already uses React, you only need the first package:
+
+```bash
+npm install @vjdesigns/vjdesigns-ui
+```
+
+### Import the styles
+
+The component styles and shared design tokens ship as a separate stylesheet. Import it **once** at your app's entry point, or the components will render unstyled.
+
+**React:** in `main.tsx` (or `App.tsx`)
+
+```ts
+import "@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css";
+```
+
+**Angular:** add it to the `styles` array in `angular.json`
+
+```json
+"styles": [
+  "node_modules/@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css",
+  "src/styles.css"
+]
+```
+
+**Vue:** in `main.ts`
+
+```ts
+import "@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css";
 ```
 
 # Guide: Usage
 
-The components are built with React. You can use them directly in a React project. In Angular or Vue, you mount them inside a small wrapper component, as shown below.
-
-### React
-
-```tsx
-import { useState } from "react";
-import { Button, CheckBox } from "@vjdesigns/vjdesigns-ui";
-
-export function SignupForm() {
-  const [accepted, setAccepted] = useState(false);
-
-  return (
-    <form>
-      <CheckBox
-        label="Accept terms"
-        checked={accepted}
-        onCheckedChange={setAccepted}
-      />
-      <Button
-        variant="solid"
-        tone="primary"
-        size="md"
-        disabled={!accepted}
-        onClick={() => console.log("Submitted")}
-      >
-        Submit
-      </Button>
-    </form>
-  );
-}
-```
-
-### Angular
-
-Make a standalone wrapper that renders the React component into its host element. The wrapper uses `createElement`, so you don't need to change your JSX or TSX settings.
-
-```ts
-// vj-button.component.ts
-import {
-  AfterViewInit,
-  Component,
-  ElementRef,
-  EventEmitter,
-  Input,
-  OnChanges,
-  OnDestroy,
-  Output,
-  ViewChild,
-} from "@angular/core";
-import { createElement, type MouseEvent as ReactMouseEvent, type ReactElement } from "react";
-import { createRoot, Root } from "react-dom/client";
-import {
-  Button,
-  type ButtonProps,
-  type ButtonVariant,
-  type Size,
-  type Tone,
-} from "@vjdesigns/vjdesigns-ui";
-
-// Button has overloaded types (for `href` and `as`). Narrowing it here lets createElement type-check.
-const ReactButton = Button as (props: ButtonProps) => ReactElement;
-
-@Component({
-  selector: "vj-button",
-  standalone: true,
-  template: `<span #host></span>`,
-})
-export class VjButtonComponent implements AfterViewInit, OnChanges, OnDestroy {
-  @ViewChild("host", { static: true }) host!: ElementRef<HTMLElement>;
-
-  @Input() label = "";
-  @Input() variant: ButtonVariant = "solid";
-  @Input() tone: Tone = "primary";
-  @Input() size: Size = "md";
-  @Input() disabled = false;
-  @Output() clicked = new EventEmitter<MouseEvent>();
-
-  private root?: Root;
-
-  ngAfterViewInit() {
-    this.root = createRoot(this.host.nativeElement);
-    this.render();
-  }
-
-  ngOnChanges() {
-    this.render();
-  }
-
-  ngOnDestroy() {
-    this.root?.unmount();
-  }
-
-  private render() {
-    this.root?.render(
-      createElement(
-        ReactButton,
-        {
-          variant: this.variant,
-          tone: this.tone,
-          size: this.size,
-          disabled: this.disabled,
-          onClick: (event: ReactMouseEvent) => this.clicked.emit(event.nativeEvent),
-        },
-        this.label // the button's text is passed as children
-      )
-    );
-  }
-}
-```
-
-Import the wrapper wherever you need it:
-
-```ts
-// app.component.ts
-import { Component } from "@angular/core";
-import { VjButtonComponent } from "./vj-button.component";
-
-@Component({
-  selector: "app-root",
-  standalone: true,
-  imports: [VjButtonComponent],
-  template: `<vj-button label="Submit" tone="primary" (clicked)="onSubmit()" />`,
-})
-export class AppComponent {
-  onSubmit() {
-    console.log("Submitted");
-  }
-}
-```
-
-### Vue 3
-
-Make a wrapper component that mounts the React component when it loads and re-renders it whenever its props change.
-
-```vue
-<!-- VjButton.vue -->
-<script setup lang="ts">
-import { onBeforeUnmount, onMounted, ref, watch } from "vue";
-import { createElement, type MouseEvent as ReactMouseEvent, type ReactElement } from "react";
-import { createRoot, type Root } from "react-dom/client";
-import {
-  Button,
-  type ButtonProps,
-  type ButtonVariant,
-  type Size,
-  type Tone,
-} from "@vjdesigns/vjdesigns-ui";
-
-// Button has overloaded types (for `href` and `as`). Narrowing it here lets createElement type-check.
-const ReactButton = Button as (props: ButtonProps) => ReactElement;
-
-const props = withDefaults(
-  defineProps<{
-    label: string;
-    variant?: ButtonVariant;
-    tone?: Tone;
-    size?: Size;
-    disabled?: boolean;
-  }>(),
-  { variant: "solid", tone: "primary", size: "md", disabled: false }
-);
-
-const emit = defineEmits<{ click: [event: MouseEvent] }>();
-
-const host = ref<HTMLElement | null>(null);
-let root: Root | undefined;
-
-function render() {
-  root?.render(
-    createElement(
-      ReactButton,
-      {
-        variant: props.variant,
-        tone: props.tone,
-        size: props.size,
-        disabled: props.disabled,
-        onClick: (event: ReactMouseEvent) => emit("click", event.nativeEvent),
-      },
-      props.label // the button's text is passed as children
-    )
-  );
-}
-
-onMounted(() => {
-  root = createRoot(host.value!);
-  render();
-});
-
-watch(() => ({ ...props }), render);
-
-onBeforeUnmount(() => root?.unmount());
-</script>
-
-<template>
-  <span ref="host" />
-</template>
-```
-
-Use it like any other Vue component:
-
-```vue
-<script setup lang="ts">
-import VjButton from "./VjButton.vue";
-
-const onSubmit = () => console.log("Submitted");
-</script>
-
-<template>
-  <VjButton label="Submit" tone="primary" @click="onSubmit" />
-</template>
-```
-
+The components are built with React. You can use them directly in a React project. In Angular or Vue, you mount them inside a small wrapper component, as shown below.
+
+### React
+
+```tsx
+import { useState } from "react";
+import { Button, CheckBox } from "@vjdesigns/vjdesigns-ui";
+
+export function SignupForm() {
+  const [accepted, setAccepted] = useState(false);
+
+  return (
+    <form>
+      <CheckBox
+        label="Accept terms"
+        checked={accepted}
+        onCheckedChange={setAccepted}
+      />
+      <Button
+        variant="solid"
+        tone="primary"
+        size="md"
+        disabled={!accepted}
+        onClick={() => console.log("Submitted")}
+      >
+        Submit
+      </Button>
+    </form>
+  );
+}
+```
+
+### Angular
+
+Make a standalone wrapper that renders the React component into its host element. The wrapper uses `createElement`, so you don't need to change your JSX or TSX settings.
+
+```ts
+// vj-button.component.ts
+import {
+  AfterViewInit,
+  Component,
+  ElementRef,
+  EventEmitter,
+  Input,
+  OnChanges,
+  OnDestroy,
+  Output,
+  ViewChild,
+} from "@angular/core";
+import { createElement, type MouseEvent as ReactMouseEvent, type ReactElement } from "react";
+import { createRoot, Root } from "react-dom/client";
+import {
+  Button,
+  type ButtonProps,
+  type ButtonVariant,
+  type Size,
+  type Tone,
+} from "@vjdesigns/vjdesigns-ui";
+
+// Button has overloaded types (for `href` and `as`). Narrowing it here lets createElement type-check.
+const ReactButton = Button as (props: ButtonProps) => ReactElement;
+
+@Component({
+  selector: "vj-button",
+  standalone: true,
+  template: `<span #host></span>`,
+})
+export class VjButtonComponent implements AfterViewInit, OnChanges, OnDestroy {
+  @ViewChild("host", { static: true }) host!: ElementRef<HTMLElement>;
+
+  @Input() label = "";
+  @Input() variant: ButtonVariant = "solid";
+  @Input() tone: Tone = "primary";
+  @Input() size: Size = "md";
+  @Input() disabled = false;
+  @Output() clicked = new EventEmitter<MouseEvent>();
+
+  private root?: Root;
+
+  ngAfterViewInit() {
+    this.root = createRoot(this.host.nativeElement);
+    this.render();
+  }
+
+  ngOnChanges() {
+    this.render();
+  }
+
+  ngOnDestroy() {
+    this.root?.unmount();
+  }
+
+  private render() {
+    this.root?.render(
+      createElement(
+        ReactButton,
+        {
+          variant: this.variant,
+          tone: this.tone,
+          size: this.size,
+          disabled: this.disabled,
+          onClick: (event: ReactMouseEvent) => this.clicked.emit(event.nativeEvent),
+        },
+        this.label // the button's text is passed as children
+      )
+    );
+  }
+}
+```
+
+Import the wrapper wherever you need it:
+
+```ts
+// app.component.ts
+import { Component } from "@angular/core";
+import { VjButtonComponent } from "./vj-button.component";
+
+@Component({
+  selector: "app-root",
+  standalone: true,
+  imports: [VjButtonComponent],
+  template: `<vj-button label="Submit" tone="primary" (clicked)="onSubmit()" />`,
+})
+export class AppComponent {
+  onSubmit() {
+    console.log("Submitted");
+  }
+}
+```
+
+### Vue 3
+
+Make a wrapper component that mounts the React component when it loads and re-renders it whenever its props change.
+
+```vue
+<!-- VjButton.vue -->
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, ref, watch } from "vue";
+import { createElement, type MouseEvent as ReactMouseEvent, type ReactElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+  Button,
+  type ButtonProps,
+  type ButtonVariant,
+  type Size,
+  type Tone,
+} from "@vjdesigns/vjdesigns-ui";
+
+// Button has overloaded types (for `href` and `as`). Narrowing it here lets createElement type-check.
+const ReactButton = Button as (props: ButtonProps) => ReactElement;
+
+const props = withDefaults(
+  defineProps<{
+    label: string;
+    variant?: ButtonVariant;
+    tone?: Tone;
+    size?: Size;
+    disabled?: boolean;
+  }>(),
+  { variant: "solid", tone: "primary", size: "md", disabled: false }
+);
+
+const emit = defineEmits<{ click: [event: MouseEvent] }>();
+
+const host = ref<HTMLElement | null>(null);
+let root: Root | undefined;
+
+function render() {
+  root?.render(
+    createElement(
+      ReactButton,
+      {
+        variant: props.variant,
+        tone: props.tone,
+        size: props.size,
+        disabled: props.disabled,
+        onClick: (event: ReactMouseEvent) => emit("click", event.nativeEvent),
+      },
+      props.label // the button's text is passed as children
+    )
+  );
+}
+
+onMounted(() => {
+  root = createRoot(host.value!);
+  render();
+});
+
+watch(() => ({ ...props }), render);
+
+onBeforeUnmount(() => root?.unmount());
+</script>
+
+<template>
+  <span ref="host" />
+</template>
+```
+
+Use it like any other Vue component:
+
+```vue
+<script setup lang="ts">
+import VjButton from "./VjButton.vue";
+
+const onSubmit = () => console.log("Submitted");
+</script>
+
+<template>
+  <VjButton label="Submit" tone="primary" @click="onSubmit" />
+</template>
+```
+
 > **Tip:** Wrap `CheckBox` and any other component the same way. Pass its props into `createElement`, and send its callbacks back out as Angular outputs or Vue emits. For `CheckBox`, that means sending `onCheckedChange` back out.
 
 # Guide: Theming
 
-Wrap any part of your app in `Theme` to set the color mode, brand palette, and accent for everything inside it:
-
-```tsx
-import { Theme, Button } from "@vjdesigns/vjdesigns-ui";
-
-<Theme mode="dark" brand="purple" fill>
-  <Button>Dark, purple button</Button>
-</Theme>
-```
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `mode` | `"light" \| "dark"` | inherited | Color mode for everything inside. |
-| `brand` | `"black" \| "blue" \| "gold" \| "green" \| "purple"`, a hex color, or `{ light, dark }` | inherited | Brand palette for buttons, links, focus rings and indicators. |
-| `accent` | `"brand" | "lime"`, a hex color, or `{ light, dark }` | inherited (the brand's own) | The bright highlight on badges, switches, progress bars, sliders, steppers, and active navigation. |
-| `fill` | `boolean` | `false` | Paints the theme's background and text color on the wrapper. |
-
-Outside React (or to theme the whole page), set the attributes on `<html>` instead:
-
-```html
-<html data-theme="dark" data-brand="purple" data-accent="lime">
-```
-
-### Accent color
-
-The accent is the energetic highlight: badges, switches, progress bars, sliders, steppers, and the active link in the Navbar. By default it follows the brand, as a bright shade of the brand's own color, so it always fits:
-
-| Brand | Default accent |
-| --- | --- |
-| `blue` (default) | sky blue `#76c7ff` |
-| `purple` | lavender `#c0b0ff` |
-| `gold` | amber `#f5ad5f` |
-| `green` | mint `#72d4ad` |
-| `black` | lime `#c8f031` (black has no hue to build on) |
-| a custom hex | generated from that color |
-
-To choose a different one:
-
-```tsx
-<Theme accent="lime">…</Theme>      // the original bright yellow-green ("volt", its former name, still works)
-<Theme accent="#ff6b00">…</Theme>   // any color
-<Theme accent="brand">…</Theme>     // back to the brand's own, inside an area with another accent
-```
-
-Accents always carry dark text. A color too dark for that is lightened (same hue) just enough to meet WCAG AA, with a warning in development. An accent you set also holds inside nested brands. In CSS, `accentCss("name", "#ff6b00")` generates a `[data-accent="name"]` rule, like `brandCss` below.
-
-### Custom brand colors
-
-Pass any hex color as `brand` and a full palette is generated for both modes:
-
-```tsx
-<Theme brand="#e11d48">…</Theme>
-<Theme brand={{ light: "#4338ca", dark: "#f472b6" }}>…</Theme>
-```
-
-Every generated palette meets WCAG 2.2 AA. A single color is used exactly as given in the mode where it has enough contrast (dark colors in light mode, light colors in dark mode), and the other mode gets a matching shade of the same hue. If a color doesn't have enough contrast (for example, a mid-tone that fails in both modes), its lightness is shifted just enough to pass, and a warning is logged in development.
-
-To define a brand in CSS instead (for the whole page, applied before any JavaScript runs), generate a stylesheet rule with `brandCss`:
-
-```ts
-import { brandCss } from "@vjdesigns/vjdesigns-ui";
-
-brandCss("acme", "#e11d48"); // '[data-brand="acme"] { --brand-light-primary: … }'
-```
-
+Wrap any part of your app in `Theme` to set the color mode, brand palette, and accent for everything inside it:
+
+```tsx
+import { Theme, Button } from "@vjdesigns/vjdesigns-ui";
+
+<Theme mode="dark" brand="purple" fill>
+  <Button>Dark, purple button</Button>
+</Theme>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `"light" \| "dark"` | inherited | Color mode for everything inside. |
+| `brand` | `"black" \| "blue" \| "gold" \| "green" \| "purple"`, a hex color, or `{ light, dark }` | inherited | Brand palette for buttons, links, focus rings and indicators. |
+| `accent` | `"brand" | "lime"`, a hex color, or `{ light, dark }` | inherited (the brand's own) | The bright highlight on badges, switches, progress bars, sliders, steppers, and active navigation. |
+| `fill` | `boolean` | `false` | Paints the theme's background and text color on the wrapper. |
+
+Outside React (or to theme the whole page), set the attributes on `<html>` instead:
+
+```html
+<html data-theme="dark" data-brand="purple" data-accent="lime">
+```
+
+### Accent color
+
+The accent is the energetic highlight: badges, switches, progress bars, sliders, steppers, and the active link in the Navbar. By default it follows the brand, as a bright shade of the brand's own color, so it always fits:
+
+| Brand | Default accent |
+| --- | --- |
+| `blue` (default) | sky blue `#76c7ff` |
+| `purple` | lavender `#c0b0ff` |
+| `gold` | amber `#f5ad5f` |
+| `green` | mint `#72d4ad` |
+| `black` | lime `#c8f031` (black has no hue to build on) |
+| a custom hex | generated from that color |
+
+To choose a different one:
+
+```tsx
+<Theme accent="lime">…</Theme>      // the original bright yellow-green ("volt", its former name, still works)
+<Theme accent="#ff6b00">…</Theme>   // any color
+<Theme accent="brand">…</Theme>     // back to the brand's own, inside an area with another accent
+```
+
+Accents always carry dark text. A color too dark for that is lightened (same hue) just enough to meet WCAG AA, with a warning in development. An accent you set also holds inside nested brands. In CSS, `accentCss("name", "#ff6b00")` generates a `[data-accent="name"]` rule, like `brandCss` below.
+
+### Custom brand colors
+
+Pass any hex color as `brand` and a full palette is generated for both modes:
+
+```tsx
+<Theme brand="#e11d48">…</Theme>
+<Theme brand={{ light: "#4338ca", dark: "#f472b6" }}>…</Theme>
+```
+
+Every generated palette meets WCAG 2.2 AA. A single color is used exactly as given in the mode where it has enough contrast (dark colors in light mode, light colors in dark mode), and the other mode gets a matching shade of the same hue. If a color doesn't have enough contrast (for example, a mid-tone that fails in both modes), its lightness is shifted just enough to pass, and a warning is logged in development.
+
+To define a brand in CSS instead (for the whole page, applied before any JavaScript runs), generate a stylesheet rule with `brandCss`:
+
+```ts
+import { brandCss } from "@vjdesigns/vjdesigns-ui";
+
+brandCss("acme", "#e11d48"); // '[data-brand="acme"] { --brand-light-primary: … }'
+```
+
 Add the rule to your stylesheet and use `<html data-brand="acme">`. `createBrandPalette(color)` returns the generated colors as an object, if you need them directly.
 
 # Guide: Languages
 
-Components have built-in text: button names like "Close" and "Next page", screen-reader announcements like "3 results available", validation messages, and date formats. Wrap your app in `LocaleProvider` to show all of it in another language:
-
-```tsx
-import { LocaleProvider } from "@vjdesigns/vjdesigns-ui";
-import es from "@vjdesigns/vjdesigns-ui/locales/es";
-
-<LocaleProvider locale="es" messages={es}>
-  <App />
-</LocaleProvider>
-```
-
-`LocaleProvider` sets:
-
-- **Built-in text** for every component, from `messages`.
-- **Dates and numbers** in the locale's format (`23/10/2026`, `1.234,5`), and plurals that follow the language's rules.
-- **Writing direction**: Arabic, Hebrew, Persian, and Urdu get `dir="rtl"`, and layouts and arrow keys mirror.
-- **`lang`** on its wrapper, so screen readers pronounce the text correctly. Popups (menus, dialogs, tooltips) keep the language of the area that opened them.
-
-Each locale is a separate import, so your app only downloads the languages it uses. Without a `LocaleProvider`, components use English text and the browser's date and number format.
-
-This library only translates its own built-in text. Text your app passes in, like `<Button>Save</Button>`, is your app's content: translate it with your app's i18n library (react-i18next, FormatJS, and so on).
-
-### What gets translated
-
-The language is never picked automatically from where the user lives or their browser settings. Your app chooses it by rendering a `LocaleProvider`. For example, with `<LocaleProvider locale="de" messages={de}>`:
-
-| | Translated? |
-| --- | --- |
-| Text your app passes in, like `<Button>Save</Button>` | No: your app translates it |
-| Built-in names, like "Close", "Next page", "Clear search" | Yes: "Schließen", "Nächste Seite", "Suche löschen" |
-| Screen-reader announcements, like "3 results available" | Yes: "3 Ergebnisse verfügbar" |
-| Validation messages, empty states, file-upload prompts | Yes |
-| Dates and numbers | Yes: "23.10.2026", "4,5" |
-
-To follow the user's browser language, pass it yourself: `locale={navigator.language}` together with the matching `messages` (see [Switching language at runtime](#switching-language-at-runtime)).
-
-### Bundled languages
-
-`ar` Arabic · `bn` Bengali · `cs` Czech · `da` Danish · `de` German · `el` Greek · `es` Spanish · `fa` Persian · `fi` Finnish · `fr` French · `he` Hebrew · `hi` Hindi · `hu` Hungarian · `id` Indonesian · `it` Italian · `ja` Japanese · `ko` Korean · `nb` Norwegian Bokmål · `nl` Dutch · `pl` Polish · `pt-BR` Portuguese (Brazil) · `ro` Romanian · `ru` Russian · `sv` Swedish · `th` Thai · `tr` Turkish · `uk` Ukrainian · `ur` Urdu · `vi` Vietnamese · `zh-Hans` Chinese (Simplified) · `zh-Hant` Chinese (Traditional), plus English (the default).
-
-The translations are machine-generated and haven't been reviewed by native speakers yet. If you find a wrong or awkward phrase, override it (below) and report it so the bundled locale can be fixed.
-
-### Changing a few strings
-
-Pass only the strings you want to change. Everything else falls back to the outer provider's language (English at the top):
-
-```tsx
-<LocaleProvider locale="en-GB" messages={{ pagination: { next: "Onwards" } }}>
-```
-
-Providers nest, so an inner provider can switch the language for one part of the page. Per-component props such as `clearLabel` or `labels` still win over the provider.
-
-### Other languages
-
-For a language that isn't bundled, write a complete messages object. TypeScript flags any missing string. Use English as the template:
-
-```ts
-import { en, plural, type Messages } from "@vjdesigns/vjdesigns-ui";
-
-const p = plural("sw");
-export const sw: Messages = {
-  ...en,
-  pagination: { ...en.pagination, next: "Ukurasa unaofuata", previous: "Ukurasa uliopita" },
-  searchInput: {
-    ...en.searchInput,
-    results: (count) => p(count, { "=0": "Hakuna matokeo", one: "Tokeo #", other: "Matokeo #" }),
-  },
-  // ...
-};
-```
-
-`plural(locale)` picks the right plural form for any language (`#` is the formatted number).
-
-### Switching language at runtime
-
-List the languages your app offers as loaders, so each one is downloaded only when picked:
-
-```tsx
-import { LocaleProvider, type Messages } from "@vjdesigns/vjdesigns-ui";
-
-const loaders: Record<string, () => Promise<{ default: Messages }>> = {
-  es: () => import("@vjdesigns/vjdesigns-ui/locales/es"),
-  fr: () => import("@vjdesigns/vjdesigns-ui/locales/fr"),
-  ar: () => import("@vjdesigns/vjdesigns-ui/locales/ar"),
-};
-
-function App({ lang }: { lang: string }) {
-  const [messages, setMessages] = useState<Messages>();
-  useEffect(() => {
-    const load = loaders[lang];
-    if (load) load().then((mod) => setMessages(mod.default));
-    else setMessages(undefined); // English
-  }, [lang]);
-  // Until a language loads, the previous one (or English) shows.
-  return <LocaleProvider locale={lang} messages={messages}>…</LocaleProvider>;
-}
-```
-
+Components have built-in text: button names like "Close" and "Next page", screen-reader announcements like "3 results available", validation messages, and date formats. Wrap your app in `LocaleProvider` to show all of it in another language:
+
+```tsx
+import { LocaleProvider } from "@vjdesigns/vjdesigns-ui";
+import es from "@vjdesigns/vjdesigns-ui/locales/es";
+
+<LocaleProvider locale="es" messages={es}>
+  <App />
+</LocaleProvider>
+```
+
+`LocaleProvider` sets:
+
+- **Built-in text** for every component, from `messages`.
+- **Dates and numbers** in the locale's format (`23/10/2026`, `1.234,5`), and plurals that follow the language's rules.
+- **Writing direction**: Arabic, Hebrew, Persian, and Urdu get `dir="rtl"`, and layouts and arrow keys mirror.
+- **`lang`** on its wrapper, so screen readers pronounce the text correctly. Popups (menus, dialogs, tooltips) keep the language of the area that opened them.
+
+Each locale is a separate import, so your app only downloads the languages it uses. Without a `LocaleProvider`, components use English text and the browser's date and number format.
+
+This library only translates its own built-in text. Text your app passes in, like `<Button>Save</Button>`, is your app's content: translate it with your app's i18n library (react-i18next, FormatJS, and so on).
+
+### What gets translated
+
+The language is never picked automatically from where the user lives or their browser settings. Your app chooses it by rendering a `LocaleProvider`. For example, with `<LocaleProvider locale="de" messages={de}>`:
+
+| | Translated? |
+| --- | --- |
+| Text your app passes in, like `<Button>Save</Button>` | No: your app translates it |
+| Built-in names, like "Close", "Next page", "Clear search" | Yes: "Schließen", "Nächste Seite", "Suche löschen" |
+| Screen-reader announcements, like "3 results available" | Yes: "3 Ergebnisse verfügbar" |
+| Validation messages, empty states, file-upload prompts | Yes |
+| Dates and numbers | Yes: "23.10.2026", "4,5" |
+
+To follow the user's browser language, pass it yourself: `locale={navigator.language}` together with the matching `messages` (see [Switching language at runtime](#switching-language-at-runtime)).
+
+### Bundled languages
+
+`ar` Arabic · `bn` Bengali · `cs` Czech · `da` Danish · `de` German · `el` Greek · `es` Spanish · `fa` Persian · `fi` Finnish · `fr` French · `he` Hebrew · `hi` Hindi · `hu` Hungarian · `id` Indonesian · `it` Italian · `ja` Japanese · `ko` Korean · `nb` Norwegian Bokmål · `nl` Dutch · `pl` Polish · `pt-BR` Portuguese (Brazil) · `ro` Romanian · `ru` Russian · `sv` Swedish · `th` Thai · `tr` Turkish · `uk` Ukrainian · `ur` Urdu · `vi` Vietnamese · `zh-Hans` Chinese (Simplified) · `zh-Hant` Chinese (Traditional), plus English (the default).
+
+The translations are machine-generated and haven't been reviewed by native speakers yet. If you find a wrong or awkward phrase, override it (below) and report it so the bundled locale can be fixed. (Working on the library itself? See [Translating built-in text](#translating-built-in-text).)
+
+### Changing a few strings
+
+Pass only the strings you want to change. Everything else falls back to the outer provider's language (English at the top):
+
+```tsx
+<LocaleProvider locale="en-GB" messages={{ pagination: { next: "Onwards" } }}>
+```
+
+Providers nest, so an inner provider can switch the language for one part of the page. Per-component props such as `clearLabel` or `labels` still win over the provider.
+
+### Other languages
+
+For a language that isn't bundled, write a complete messages object. TypeScript flags any missing string. Use English as the template:
+
+```ts
+import { en, plural, type Messages } from "@vjdesigns/vjdesigns-ui";
+
+const p = plural("sw");
+export const sw: Messages = {
+  ...en,
+  pagination: { ...en.pagination, next: "Ukurasa unaofuata", previous: "Ukurasa uliopita" },
+  searchInput: {
+    ...en.searchInput,
+    results: (count) => p(count, { "=0": "Hakuna matokeo", one: "Tokeo #", other: "Matokeo #" }),
+  },
+  // ...
+};
+```
+
+`plural(locale)` picks the right plural form for any language (`#` is the formatted number).
+
+### Switching language at runtime
+
+List the languages your app offers as loaders, so each one is downloaded only when picked:
+
+```tsx
+import { LocaleProvider, type Messages } from "@vjdesigns/vjdesigns-ui";
+
+const loaders: Record<string, () => Promise<{ default: Messages }>> = {
+  es: () => import("@vjdesigns/vjdesigns-ui/locales/es"),
+  fr: () => import("@vjdesigns/vjdesigns-ui/locales/fr"),
+  ar: () => import("@vjdesigns/vjdesigns-ui/locales/ar"),
+};
+
+function App({ lang }: { lang: string }) {
+  const [messages, setMessages] = useState<Messages>();
+  useEffect(() => {
+    const load = loaders[lang];
+    if (load) load().then((mod) => setMessages(mod.default));
+    else setMessages(undefined); // English
+  }, [lang]);
+  // Until a language loads, the previous one (or English) shows.
+  return <LocaleProvider locale={lang} messages={messages}>…</LocaleProvider>;
+}
+```
+
 For server rendering, also set `<html lang="…" dir="…">` on the page. `getLocaleDirection(locale)` returns `"ltr"` or `"rtl"`.
 
 # Guide: Form validation
 
-> **Front-end validation is not security.** It helps people fill in a form correctly, but anyone can turn off JavaScript or send requests straight to your server. Always validate again on the server. The format checks below (`isEmail`, `isIP`, …) are plain functions you can reuse there.
-
-`useFormValidation` checks a form when it's submitted, using the browser's own rules on each input (`required`, `type="email"`, `minLength`, `pattern`, `min` / `max`) plus any rules you add. Messages follow the current language.
-
-```tsx
-import {
-  useFormValidation, rules, ErrorSummary, Field, Input, PasswordInput, Button,
-} from "@vjdesigns/vjdesigns-ui";
-
-function SignUp() {
-  const form = useFormValidation({
-    rules: {
-      confirm: rules.matches("password", "The passwords don't match."),
-      serverIp: rules.ip(),                       // IPv4 or IPv6
-    },
-    // Runs only when everything is valid. Return the server's errors to show them on their fields.
-    onValid: async (values) => {
-      const response = await api.signUp(values);
-      return response.errors;                     // e.g. { username: "That username is taken." }
-    },
-  });
-
-  return (
-    <form {...form.formProps}>
-      <ErrorSummary ref={form.summaryRef} errors={form.errorList} />
-      <Field label="Email" required error={form.errors.email}>
-        <Input name="email" type="email" />
-      </Field>
-      <Field label="Password" required error={form.errors.password}>
-        <PasswordInput name="password" minLength={12} />
-      </Field>
-      <Field label="Confirm password" required error={form.errors.confirm}>
-        <PasswordInput name="confirm" />
-      </Field>
-      <Field label="Server IP" error={form.errors.serverIp}>
-        <Input name="serverIp" />
-      </Field>
-      <Button type="submit" loading={form.isSubmitting}>Create account</Button>
-    </form>
-  );
-}
-```
-
-How it behaves:
-
-- **On submit**, every field is checked. If anything is wrong, the `ErrorSummary` at the top lists the problems and takes focus, so screen readers announce it. Each item links to its field. Without a summary, focus goes to the first invalid field.
-- **Errors are keyed by the field's `name`.** Pass `form.errors.<name>` to each `Field`'s `error`.
-- **After a failed submit**, an error disappears as soon as the field is fixed (while typing), and a field is fully re-checked when you leave it. It doesn't nag while you're still typing.
-- **Server errors** (returned from `onValid`, or set with `form.setErrors({...})`) show on their fields and stay until that field is edited.
-- **Emails** must have a real domain (`name@example.com`). The browser's own check also accepts `name@localhost`.
-
-### Rules and format checks
-
-| Rule | Checks |
-| --- | --- |
-| `rules.required()` | Not empty (for controls without a native `required`) |
-| `rules.email()` | An email address in the usual format, with a top-level domain |
-| `rules.ip()` / `rules.ip({ version: 4 })` / `rules.ip({ version: 6 })` | An IPv4 or IPv6 address |
-| `rules.minLength(n)` / `rules.maxLength(n)` | Length in characters |
-| `rules.pattern(/regex/, "message")` | The whole value matches |
-| `rules.matches("otherField")` | Equals another field (confirm password) |
-| your own `(value, { values }) => message` | Anything else |
-
-Each rule takes an optional custom message. The checks behind them are exported for use anywhere, including your server:
-
-- `isEmail(value)`
-- `isIPv4(value)`: four numbers 0–255, no leading zeros
-- `isIPv6(value)`: including `::` shorthand and IPv4 tails like `::ffff:192.168.0.1`
+> **Front-end validation is not security.** It helps people fill in a form correctly, but anyone can turn off JavaScript or send requests straight to your server. Always validate again on the server. The format checks below (`isEmail`, `isIP`, …) are plain functions you can reuse there.
+
+`useFormValidation` checks a form when it's submitted, using the browser's own rules on each input (`required`, `type="email"`, `minLength`, `pattern`, `min` / `max`) plus any rules you add. Messages follow the current language.
+
+```tsx
+import {
+  useFormValidation, rules, ErrorSummary, Field, Input, PasswordInput, Button,
+} from "@vjdesigns/vjdesigns-ui";
+
+function SignUp() {
+  const form = useFormValidation({
+    rules: {
+      confirm: rules.matches("password", "The passwords don't match."),
+      serverIp: rules.ip(),                       // IPv4 or IPv6
+    },
+    // Runs only when everything is valid. Return the server's errors to show them on their fields.
+    onValid: async (values) => {
+      const response = await api.signUp(values);
+      return response.errors;                     // e.g. { username: "That username is taken." }
+    },
+  });
+
+  return (
+    <form {...form.formProps}>
+      <ErrorSummary ref={form.summaryRef} errors={form.errorList} />
+      <Field label="Email" required error={form.errors.email}>
+        <Input name="email" type="email" />
+      </Field>
+      <Field label="Password" required error={form.errors.password}>
+        <PasswordInput name="password" minLength={12} />
+      </Field>
+      <Field label="Confirm password" required error={form.errors.confirm}>
+        <PasswordInput name="confirm" />
+      </Field>
+      <Field label="Server IP" error={form.errors.serverIp}>
+        <Input name="serverIp" />
+      </Field>
+      <Button type="submit" loading={form.isSubmitting}>Create account</Button>
+    </form>
+  );
+}
+```
+
+How it behaves:
+
+- **On submit**, every field is checked. If anything is wrong, the `ErrorSummary` at the top lists the problems and takes focus, so screen readers announce it. Each item links to its field. Without a summary, focus goes to the first invalid field.
+- **Errors are keyed by the field's `name`.** Pass `form.errors.<name>` to each `Field`'s `error`.
+- **After a failed submit**, an error disappears as soon as the field is fixed (while typing), and a field is fully re-checked when you leave it. It doesn't nag while you're still typing.
+- **Server errors** (returned from `onValid`, or set with `form.setErrors({...})`) show on their fields and stay until that field is edited.
+- **Emails** must have a real domain (`name@example.com`). The browser's own check also accepts `name@localhost`.
+
+### Rules and format checks
+
+| Rule | Checks |
+| --- | --- |
+| `rules.required()` | Not empty (for controls without a native `required`) |
+| `rules.email()` | An email address in the usual format, with a top-level domain |
+| `rules.ip()` / `rules.ip({ version: 4 })` / `rules.ip({ version: 6 })` | An IPv4 or IPv6 address |
+| `rules.minLength(n)` / `rules.maxLength(n)` | Length in characters |
+| `rules.pattern(/regex/, "message")` | The whole value matches |
+| `rules.matches("otherField")` | Equals another field (confirm password) |
+| your own `(value, { values }) => message` | Anything else |
+
+Each rule takes an optional custom message. The checks behind them are exported for use anywhere, including your server:
+
+- `isEmail(value)`
+- `isIPv4(value)`: four numbers 0–255, no leading zeros
+- `isIPv6(value)`: including `::` shorthand and IPv4 tails like `::ffff:192.168.0.1`
 - `isIP(value, version?)`
 
 # Components
@@ -927,6 +927,77 @@ view, so keyboard and screen reader users only reach what is shown.
 - Controlled Edge Cases: Controlled: the viewport only moves when the parent accepts the new index. A parent that ignores `onIndexChange` keeps the slide (and dots) in place, and an out-of-range `index` is reported back clamped.
 - Resize Keeps Slide: After a resize the same slide stays in view (slide widths change, so scroll is realigned).
 
+## Chat
+
+import { Chat } from "@vjdesigns/vjdesigns-ui";
+
+Category: data-display · Storybook: Data Display/Chat
+
+A chat interface for an AI assistant (or a person), with no backend of its
+own: `onSend` connects it to any API and can stream the reply. Includes a
+scrolling conversation that follows new messages, an auto-growing message
+box (Enter sends, Shift+Enter adds a line), Stop and Retry, copy buttons,
+suggested prompts, and screen reader announcements of each reply.
+
+```tsx
+<Chat
+  style={{ blockSize: 560 }}
+  onSend={async function* (text, { messages, signal }) {
+    const res = await fetch("/api/chat", {
+      method: "POST",
+      body: JSON.stringify({ messages }),
+      signal,
+    });
+    yield* readTextStream(res);
+  }}
+/>
+```
+
+### Props
+
+- `messages`: `ChatMessage[]`. Controlled conversation.
+- `defaultMessages`: `ChatMessage[]`. Initial conversation when uncontrolled.
+- `onMessagesChange`: `(messages: ChatMessage[]) => void`. Called with the whole conversation whenever it changes (new messages, every streamed chunk, status changes).
+- `onSend`: `( text: string, context: ChatSendContext, ) => ChatSendResult | Promise<ChatSendResult>`. Connects the Chat to your backend. Called with the user's text when they send a message (or retry). Return the reply as a string, stream it as an `AsyncIterable<string>`, or return nothing and add it yourself through controlled `messages`. Throwing (or rejecting) turns the reply into an error with a Retry button.
+- `onStop`: `() => void`. Called when the user stops a reply, after its `signal` is aborted.
+- `onError`: `(error: unknown) => void`. Called with whatever `onSend` threw, for logging. The user sees `labels.error` (or the message's `error`).
+- `draft`: `string`. Controlled text of the message box.
+- `defaultDraft`: `string`. Initial text of the message box when uncontrolled.
+- `onDraftChange`: `(draft: string) => void`. Called with the message box text on every edit.
+- `suggestions`: `string[]`. Prompts offered as buttons while the conversation is empty. Pressing one sends it.
+- `emptyState`: `ReactNode`. Shown while the conversation is empty, above the suggestions. Defaults to a short greeting (`labels.emptyTitle`).
+- `renderContent`: `(message: ChatMessage) => ReactNode`. Renders a message's content, e.g. through your Markdown renderer. Defaults to plain text with line breaks kept. Never render unsanitized HTML from a model or a user.
+- `assistantName`: `string`. Name of the assistant, read to screen readers ("Coach said:"). Defaults to `labels.assistant`.
+- `assistantAvatar`: `ReactNode`. Shown beside assistant messages (e.g. an `Avatar` or `Icon`). Decorative: hidden from assistive technology.
+- `userAvatar`: `ReactNode`. Shown beside user messages. Decorative: hidden from assistive technology.
+- `copyable`: `boolean` (default true). Show a Copy button under finished assistant messages.
+- `disclaimer`: `ReactNode`. Small print under the message box, e.g. "AI can make mistakes."
+- `placeholder`: `string`. Placeholder of the message box. Defaults to `labels.placeholder`.
+- `maxLength`: `number`. Maximum length of a message, in characters. Shows a counter near the limit.
+- `disabled`: `boolean`. Disables the message box and the suggestions.
+- `labels`: `Partial<ChatLabels>`. Overrides for the built-in text.
+- Plus every native `<section>` attribute (className, style, id, aria-*, data-*, event handlers), spread onto the root.
+
+### Examples (Storybook stories)
+
+- Playground
+- Send And Stream: Type a message and press Enter: it is sent, and the streamed reply is announced when done.
+- Shift Enter Adds Line: Shift+Enter adds a line instead of sending.
+- String Reply: `onSend` can return the whole reply as a string (or a promise of one).
+- With Suggestions: While the conversation is empty, `emptyState` and `suggestions` show. Pressing a suggestion sends it.
+- With Avatars: Avatars beside each speaker. They're decorative; the speaker is read from hidden text.
+- Long Conversation: A long conversation. Scroll up, and a button jumps back to the latest message.
+- Long Content: A long unbroken string (a URL, say) wraps instead of overflowing the bubble.
+- Error And Retry: When `onSend` throws, the reply shows an error with a Retry button. This backend fails the first time.
+- Stop Streaming: While a reply streams, the send button becomes Stop (Escape in the message box works too).
+- Disabled
+- With Max Length: `maxLength` limits a message and shows a counter near the limit.
+- System Messages: System messages (joins, handoffs, context notes) are centered notes.
+- Custom Rendering: `renderContent` renders messages your way, e.g. through a Markdown renderer. This one turns `**bold**` into `<strong>` and keeps paragraphs. Never render unsanitized HTML from a model.
+- Controlled: Controlled: the parent owns the messages, so it can save, clear, or seed them. Here, `onSend` returns nothing and the parent adds the reply itself (the way a WebSocket or a human agent would).
+- Connecting ABackend: How to connect a real backend: stream server-sent events from your API route with `readEventStream`, passing `signal` so Stop cancels the request. ```tsx import { Chat, readEventStream } from "@vjdesigns/vjdesigns-ui"; <Chat onSend={async function* (_text, { messages, signal }) { const res = await fetch("/api/chat", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ messages: messages.map(({ role, content }) => ({ role, content })), }), signal, }); if (!res.ok) throw new Error(`Chat request failed: ${res.status}`); for await (const data of readEventStream(res)) { if (data === "[DONE]") break; yield JSON.parse(data).text ?? ""; } }} /> ``` Keep API keys on your server: the browser should call your own route, which calls the model provider. This story fakes the server with an in-memory event stream.
+- Right To Left: Right-to-left: user messages sit on the inline end, which is the left in RTL.
+
 ## Chip
 
 import { Chip } from "@vjdesigns/vjdesigns-ui";