@vjdesigns/vjdesigns-ui 2.0.0 → 2.1.0

package/README.md

@@ -1,724 +1,781 @@
-# vjdesigns-ui
-
-An accessible React component library from VJ Designs, built to meet WCAG 2.2 AA. It covers buttons, form controls, layout, navigation, overlays, feedback and data display, with light and dark modes and five brand palettes.
-
-📚 **Live docs and Storybook:** [component.vjdesigns.org](https://component.vjdesigns.org)
-📦 **npm:** [@vjdesigns/vjdesigns-ui](https://www.npmjs.com/package/@vjdesigns/vjdesigns-ui)
-
----
-
-## 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";
-```
-
----
-
-## 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>
-```
-
-> **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.
-
----
-
-## 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: … }'
-```
-
-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.
-
----
-
-## 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>;
-}
-```
-
-For server rendering, also set `<html lang="…" dir="…">` on the page. `getLocaleDirection(locale)` returns `"ltr"` or `"rtl"`.
-
----
-
-## 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`
-- `isIP(value, version?)`
-
----
-
-## Hooks
-
-Tested hooks for everyday UI work, exported from the package root (`import { useDisclosure } from "@vjdesigns/vjdesigns-ui"`). All are safe in server rendering and tree-shakable: each costs only itself, mostly well under 1 KB. Live demos are in Storybook under Hooks.
-
-| Hook | What it does |
-| --- | --- |
-| `useDisclosure(initial?)` | Open/closed state with stable `open`, `close`, `toggle` handlers (for Modal, Drawer, Popover) |
-| `useToggle(values?)` | Cycles through values: a boolean, or a list like `["list", "grid"]` |
-| `usePrevious(value)` | The value from before its last change |
-| `useDebouncedValue(value, ms)` | The value, updated after it stops changing (search as you type) |
-| `useDebouncedCallback(fn, ms)` | A function that runs once after calls stop, with `cancel` and `flush` |
-| `useThrottledCallback(fn, ms)` | A function that runs at most once per interval (scroll, resize) |
-| `useInterval(fn, ms \| null)` / `useTimeout(fn, ms \| null)` | Timers that always call the latest function; `null` pauses |
-| `useLocalStorage(key, default)` / `useSessionStorage` | State saved in storage, synced across components and tabs, and never throws when storage is blocked |
-| `useClipboard()` | `copy(text)` with a `copied` flag, and a fallback when the Clipboard API is blocked |
-| `useHotkeys([[keys, fn]])` | Page shortcuts. `mod` is ⌘ or Ctrl. Plain keys don't fire while typing. `getHotkeyHandler` does the same for one element |
-| `useEventListener(type, fn, target?)` | An event listener that always calls the latest handler |
-| `useClickOutside(fn)` | Calls `fn` on a press or focus move outside the element |
-| `useIntersection(options)` | Whether an element is in view (lazy loading, entrance effects) |
-| `useElementSize()` | An element's size as it resizes |
-| `useVirtualizer(options)` | Renders only the visible items of a long list (what `VirtualList` uses), with variable heights and `scrollToIndex` |
-| `useMediaQuery(query)` / `useResponsiveValue(value)` | A synced media query, or a responsive value resolved for the viewport |
-| `useHydrated()` | False during server rendering, true after (avoids hydration mismatches) |
-| `useReducedMotion()` / `useColorScheme()` | The user's motion and color-scheme preferences |
-| `useOnline()` / `useDocumentVisibility()` / `useViewportSize()` | Connection, tab visibility, and viewport size |
-| `useControllableState`, `useFormValidation`, `useFocusTrap`, `useScrollLock`, … | The building blocks the components use, for your own components |
-
----
-
-## AI assistants
-
-The package ships documentation written for AI coding assistants, generated from the source on every build, so it always matches the version you have installed:
-
-| File | What it is |
-| --- | --- |
-| `@vjdesigns/vjdesigns-ui/llms.txt` | A short index in the [llms.txt](https://llmstxt.org) format: setup essentials and one line per component |
-| `@vjdesigns/vjdesigns-ui/llms-full.txt` | The full reference in one file: guides, and every component's props (type, default, description), subcomponents, and examples |
-| `@vjdesigns/vjdesigns-ui/registry.json` | The same, as structured JSON |
-
-The files are in `node_modules/@vjdesigns/vjdesigns-ui/dist/ai/`. Point your assistant's rules or context at `llms-full.txt`.
-
-### MCP server
-
-For assistants that support the [Model Context Protocol](https://modelcontextprotocol.io), the package includes a small MCP server with four tools:
-
-- `list_components`
-- `get_component`, for exact props
-- `search_docs`
-- `get_guide`
-
-It reads the docs of your installed version and needs no network access.
-
-Claude Code:
-
-```bash
-claude mcp add vjdesigns-ui -- npx -p @vjdesigns/vjdesigns-ui vjdesigns-ui-mcp
-```
-
-Cursor (`.cursor/mcp.json`), Claude Desktop, and other clients (VS Code's `.vscode/mcp.json` uses `"servers"` instead of `"mcpServers"`):
-
-```json
-{
-  "mcpServers": {
-    "vjdesigns-ui": {
-      "command": "npx",
-      "args": ["-p", "@vjdesigns/vjdesigns-ui", "vjdesigns-ui-mcp"]
-    }
-  }
-}
-```
-
----
-
-## Components
-
-Every component below is exported from the package root. Full prop docs and live examples are in [Storybook](https://component.vjdesigns.org).
-
-| Category | Components |
-| --- | --- |
-| **Primitives** | Button, IconButton, ButtonGroup, Icon, Kbd, Typography |
-| **Layout** | Box, Container, Divider, Flex, Grid, ResizablePanels, ScrollArea, Stack |
-| **Forms** | CheckBox, CheckBoxGroup, ColorPicker, Combobox, DatePicker, DateRangePicker, DateTimePicker, Field, FileUpload, Input, NumberInput, PasswordInput, PinInput, Radio, Rating, SearchInput, SegmentedControl, Select, Slider, Switch, TagInput, Textarea, TimePicker, ToggleGroup |
-| **Navigation** | Breadcrumbs, ContextMenu, Link, Menu, Navbar, Pagination, Sidebar, SkipLink, Stepper, Tabs |
-| **Overlays** | CommandPalette, Drawer, HoverCard, Modal, Popover, Tooltip |
-| **Feedback** | Alert, Banner, ErrorSummary, Progress, Skeleton, Spinner, Toast |
-| **Data display** | Accordion, Avatar, Badge, Card, Carousel, Chip, CodeBlock, DataGrid, EmptyState, Image, List, Stat, Table, Timeline, TreeView, VirtualList |
-| **Utilities** | Portal, Theme, VisuallyHidden |
-
-### Button
-
-```tsx
-<Button variant="solid" tone="primary">Save</Button>
-<Button variant="outline" tone="danger" startIcon={<TrashIcon />}>Delete</Button>
-<Button href="/pricing" variant="link">See pricing</Button>
-<Button loading loadingText="Saving…">Save</Button>
-```
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `children` | `ReactNode` | — | The visible label. |
-| `variant` | `"solid" \| "soft" \| "outline" \| "ghost" \| "link" \| "inverse"` | `"solid"` | Visual style. |
-| `tone` | `"neutral" \| "primary" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Semantic color. |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height, padding and type size. |
-| `radius` | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "pill"` | `"pill"` | Corner rounding. |
-| `startIcon` / `endIcon` | `ReactNode` | — | Decorative icon before or after the label. Hidden from screen readers. |
-| `loading` | `boolean` | `false` | Shows a spinner, sets `aria-busy` and ignores clicks. |
-| `loadingText` | `ReactNode` | — | Label shown next to the spinner while loading. |
-| `fullWidth` | `boolean` | `false` | Stretches the button to fill its container. |
-| `compact` | `boolean` | `false` | Tighter side padding for short labels like "OK". |
-| `disabled` | `boolean` | `false` | Disables the button. |
-| `href` | `string` | — | Renders the button as an `<a>` link with the same styling. |
-| `as` | `ElementType` | — | Renders as your own component, such as a React Router or Next.js `Link`. |
-
-Also accepts all standard `<button>` attributes (or `<a>` attributes when `href` is set), such as `onClick` and `type`.
-
-For icon-only buttons, use `IconButton`. `aria-label` is required:
-
-```tsx
-<IconButton aria-label="Close" variant="ghost"><CloseIcon /></IconButton>
-```
-
-To group related buttons, use `ButtonGroup`. It passes `variant`, `tone`, `size`, `radius` and `disabled` down to every button inside.
-
-### CheckBox
-
-```tsx
-<CheckBox label="Email me updates" description="About once a month." />
-<CheckBox label="Remember me" labelPosition="start" defaultChecked />
-```
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `label` | `ReactNode` | — | Visible label. Clicking it toggles the box. Without it, pass `aria-label`. |
-| `description` | `ReactNode` | — | Supporting text below the label, linked with `aria-describedby`. |
-| `checked` | `boolean` | — | Checked state (controlled). |
-| `defaultChecked` | `boolean` | — | Initial checked state (uncontrolled). |
-| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state when the user toggles the box. |
-| `indeterminate` | `boolean` | `false` | Shows a "mixed" dash, for a "select all" box whose options are partly checked. |
-| `labelPosition` | `"start" \| "end"` | `"end"` | Puts the label before (`start`) or after (`end`) the box. |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Box and text size. |
-| `tone` | `Tone` | `"primary"` | Fill color when checked. |
-| `invalid` | `boolean` | `false` | Danger styling plus `aria-invalid`. |
-| `readOnly` | `boolean` | `false` | Keeps the box focusable but prevents toggling. |
-
-Also accepts native `<input type="checkbox">` attributes, such as `name`, `required` and `disabled`.
-
-To manage several options as one `string[]` value, use `CheckBoxGroup`:
-
-```tsx
-<CheckBoxGroup label="Toppings" defaultValue={["cheese"]} onValueChange={setToppings}>
-  <CheckBox value="cheese" label="Cheese" />
-  <CheckBox value="peppers" label="Peppers" />
-</CheckBoxGroup>
-```
-
----
-
-## Pro
-
-Everything above is free. `@vjdesigns/vjdesigns-ui-pro` is a commercial add-on for teams that need more from their data grids:
-
-- **DataGridPro:** everything `DataGrid` does, plus resizable columns (pointer and keyboard), saved column layouts, and columns pinned to either edge.
-- **CSV export:** export exactly what a grid shows, safe to open in a spreadsheet.
-- **Charts:** accessible `BarChart` and `LineChart`: keyboard-navigable points with spoken values, a data table view, color-blind-safe series colors, and High Contrast support.
-- **Account forms:** ready-made sign-in, sign-up, forgot-password, reset-password, and verification-code forms that you connect to your own backend, with validation, autofill, passkey support, and safe error messages built in.
-- **Figma kit:** a plugin that creates the library's variables (brands, light and dark themes, spacing, type) and shadow styles in Figma, generated from the same tokens as the code, plus W3C design token files.
-
-It uses the same tokens, themes, languages, and accessibility standard as the free package.
-
----
-
-## Development
-
-```bash
-npm run storybook        # run Storybook locally at http://localhost:6006
-npm run build            # type-check and build the library to dist/
-npm run build-storybook  # build a static Storybook site
-```
-
-Components live under `src/components/<category>/<Name>/`, with each component's implementation, CSS module and Storybook stories kept together. Shared design tokens live in `src/styles/tokens.css`. The build bundles all styles into `dist/vjdesigns-ui.css`.
-
-### Releasing
-
-```bash
-npm whoami               # check you're logged in (if not: npm login)
-npm run build
-npm version patch        # or minor / major
-npm publish
-git push --follow-tags
-```
-
-See [RELEASING.md](RELEASING.md) for the full process, including how to update the projects that use the library and fixes for common errors.
-
----
-
-## Access to the production Storybook
-
-1. Go to [component.vjdesigns.org](https://component.vjdesigns.org/).
-2. Enter your email in the Cloudflare prompt to receive a 6-digit access code.
-
-<img width="1917" height="927" alt="Cloudflare access prompt for component.vjdesigns.org" src="https://github.com/user-attachments/assets/bfe58737-52d2-4bf3-b7f7-72ba5ee54969" />
-
----
-
-## License
-
-ISC
+# vjdesigns-ui
+
+An accessible React component library from VJ Designs, built to meet WCAG 2.2 AA. It covers buttons, form controls, layout, navigation, overlays, feedback and data display, with light and dark modes and five brand palettes.
+
+📚 **Live docs and Storybook:** [component.vjdesigns.org](https://component.vjdesigns.org)
+📦 **npm:** [@vjdesigns/vjdesigns-ui](https://www.npmjs.com/package/@vjdesigns/vjdesigns-ui)
+
+---
+
+## 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";
+```
+
+---
+
+## 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>
+```
+
+> **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.
+
+---
+
+## 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: … }'
+```
+
+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.
+
+---
+
+## 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. (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"`.
+
+---
+
+## 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`
+- `isIP(value, version?)`
+
+---
+
+## Hooks
+
+Tested hooks for everyday UI work, exported from the package root (`import { useDisclosure } from "@vjdesigns/vjdesigns-ui"`). All are safe in server rendering and tree-shakable: each costs only itself, mostly well under 1 KB. Live demos are in Storybook under Hooks.
+
+| Hook | What it does |
+| --- | --- |
+| `useDisclosure(initial?)` | Open/closed state with stable `open`, `close`, `toggle` handlers (for Modal, Drawer, Popover) |
+| `useToggle(values?)` | Cycles through values: a boolean, or a list like `["list", "grid"]` |
+| `usePrevious(value)` | The value from before its last change |
+| `useDebouncedValue(value, ms)` | The value, updated after it stops changing (search as you type) |
+| `useDebouncedCallback(fn, ms)` | A function that runs once after calls stop, with `cancel` and `flush` |
+| `useThrottledCallback(fn, ms)` | A function that runs at most once per interval (scroll, resize) |
+| `useInterval(fn, ms \| null)` / `useTimeout(fn, ms \| null)` | Timers that always call the latest function; `null` pauses |
+| `useLocalStorage(key, default)` / `useSessionStorage` | State saved in storage, synced across components and tabs, and never throws when storage is blocked |
+| `useClipboard()` | `copy(text)` with a `copied` flag, and a fallback when the Clipboard API is blocked |
+| `useHotkeys([[keys, fn]])` | Page shortcuts. `mod` is ⌘ or Ctrl. Plain keys don't fire while typing. `getHotkeyHandler` does the same for one element |
+| `useEventListener(type, fn, target?)` | An event listener that always calls the latest handler |
+| `useClickOutside(fn)` | Calls `fn` on a press or focus move outside the element |
+| `useIntersection(options)` | Whether an element is in view (lazy loading, entrance effects) |
+| `useElementSize()` | An element's size as it resizes |
+| `useVirtualizer(options)` | Renders only the visible items of a long list (what `VirtualList` uses), with variable heights and `scrollToIndex` |
+| `useMediaQuery(query)` / `useResponsiveValue(value)` | A synced media query, or a responsive value resolved for the viewport |
+| `useHydrated()` | False during server rendering, true after (avoids hydration mismatches) |
+| `useReducedMotion()` / `useColorScheme()` | The user's motion and color-scheme preferences |
+| `useOnline()` / `useDocumentVisibility()` / `useViewportSize()` | Connection, tab visibility, and viewport size |
+| `useControllableState`, `useFormValidation`, `useFocusTrap`, `useScrollLock`, … | The building blocks the components use, for your own components |
+
+---
+
+## AI assistants
+
+The package ships documentation written for AI coding assistants, generated from the source on every build, so it always matches the version you have installed:
+
+| File | What it is |
+| --- | --- |
+| `@vjdesigns/vjdesigns-ui/llms.txt` | A short index in the [llms.txt](https://llmstxt.org) format: setup essentials and one line per component |
+| `@vjdesigns/vjdesigns-ui/llms-full.txt` | The full reference in one file: guides, and every component's props (type, default, description), subcomponents, and examples |
+| `@vjdesigns/vjdesigns-ui/registry.json` | The same, as structured JSON |
+
+The files are in `node_modules/@vjdesigns/vjdesigns-ui/dist/ai/`. Point your assistant's rules or context at `llms-full.txt`.
+
+### MCP server
+
+For assistants that support the [Model Context Protocol](https://modelcontextprotocol.io), the package includes a small MCP server with four tools:
+
+- `list_components`
+- `get_component`, for exact props
+- `search_docs`
+- `get_guide`
+
+It reads the docs of your installed version and needs no network access.
+
+Claude Code:
+
+```bash
+claude mcp add vjdesigns-ui -- npx -p @vjdesigns/vjdesigns-ui vjdesigns-ui-mcp
+```
+
+Cursor (`.cursor/mcp.json`), Claude Desktop, and other clients (VS Code's `.vscode/mcp.json` uses `"servers"` instead of `"mcpServers"`):
+
+```json
+{
+  "mcpServers": {
+    "vjdesigns-ui": {
+      "command": "npx",
+      "args": ["-p", "@vjdesigns/vjdesigns-ui", "vjdesigns-ui-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Components
+
+Every component below is exported from the package root. Full prop docs and live examples are in [Storybook](https://component.vjdesigns.org).
+
+| Category | Components |
+| --- | --- |
+| **Primitives** | Button, IconButton, ButtonGroup, Icon, Kbd, Typography |
+| **Layout** | Box, Container, Divider, Flex, Grid, ResizablePanels, ScrollArea, Stack |
+| **Forms** | CheckBox, CheckBoxGroup, ColorPicker, Combobox, DatePicker, DateRangePicker, DateTimePicker, Field, FileUpload, Input, NumberInput, PasswordInput, PinInput, Radio, Rating, SearchInput, SegmentedControl, Select, Slider, Switch, TagInput, Textarea, TimePicker, ToggleGroup |
+| **Navigation** | Breadcrumbs, ContextMenu, Link, Menu, Navbar, Pagination, Sidebar, SkipLink, Stepper, Tabs |
+| **Overlays** | CommandPalette, Drawer, HoverCard, Modal, Popover, Tooltip |
+| **Feedback** | Alert, Banner, ErrorSummary, Progress, Skeleton, Spinner, Toast |
+| **Data display** | Accordion, Avatar, Badge, Card, Carousel, Chat, Chip, CodeBlock, DataGrid, EmptyState, Image, List, Stat, Table, Timeline, TreeView, VirtualList |
+| **Utilities** | Portal, Theme, VisuallyHidden |
+
+### Button
+
+```tsx
+<Button variant="solid" tone="primary">Save</Button>
+<Button variant="outline" tone="danger" startIcon={<TrashIcon />}>Delete</Button>
+<Button href="/pricing" variant="link">See pricing</Button>
+<Button loading loadingText="Saving…">Save</Button>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | The visible label. |
+| `variant` | `"solid" \| "soft" \| "outline" \| "ghost" \| "link" \| "inverse"` | `"solid"` | Visual style. |
+| `tone` | `"neutral" \| "primary" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Semantic color. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height, padding and type size. |
+| `radius` | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "pill"` | `"pill"` | Corner rounding. |
+| `startIcon` / `endIcon` | `ReactNode` | — | Decorative icon before or after the label. Hidden from screen readers. |
+| `loading` | `boolean` | `false` | Shows a spinner, sets `aria-busy` and ignores clicks. |
+| `loadingText` | `ReactNode` | — | Label shown next to the spinner while loading. |
+| `fullWidth` | `boolean` | `false` | Stretches the button to fill its container. |
+| `compact` | `boolean` | `false` | Tighter side padding for short labels like "OK". |
+| `disabled` | `boolean` | `false` | Disables the button. |
+| `href` | `string` | — | Renders the button as an `<a>` link with the same styling. |
+| `as` | `ElementType` | — | Renders as your own component, such as a React Router or Next.js `Link`. |
+
+Also accepts all standard `<button>` attributes (or `<a>` attributes when `href` is set), such as `onClick` and `type`.
+
+For icon-only buttons, use `IconButton`. `aria-label` is required:
+
+```tsx
+<IconButton aria-label="Close" variant="ghost"><CloseIcon /></IconButton>
+```
+
+To group related buttons, use `ButtonGroup`. It passes `variant`, `tone`, `size`, `radius` and `disabled` down to every button inside.
+
+### CheckBox
+
+```tsx
+<CheckBox label="Email me updates" description="About once a month." />
+<CheckBox label="Remember me" labelPosition="start" defaultChecked />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | — | Visible label. Clicking it toggles the box. Without it, pass `aria-label`. |
+| `description` | `ReactNode` | — | Supporting text below the label, linked with `aria-describedby`. |
+| `checked` | `boolean` | — | Checked state (controlled). |
+| `defaultChecked` | `boolean` | — | Initial checked state (uncontrolled). |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state when the user toggles the box. |
+| `indeterminate` | `boolean` | `false` | Shows a "mixed" dash, for a "select all" box whose options are partly checked. |
+| `labelPosition` | `"start" \| "end"` | `"end"` | Puts the label before (`start`) or after (`end`) the box. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Box and text size. |
+| `tone` | `Tone` | `"primary"` | Fill color when checked. |
+| `invalid` | `boolean` | `false` | Danger styling plus `aria-invalid`. |
+| `readOnly` | `boolean` | `false` | Keeps the box focusable but prevents toggling. |
+
+Also accepts native `<input type="checkbox">` attributes, such as `name`, `required` and `disabled`.
+
+To manage several options as one `string[]` value, use `CheckBoxGroup`:
+
+```tsx
+<CheckBoxGroup label="Toppings" defaultValue={["cheese"]} onValueChange={setToppings}>
+  <CheckBox value="cheese" label="Cheese" />
+  <CheckBox value="peppers" label="Peppers" />
+</CheckBoxGroup>
+```
+
+---
+
+## Pro
+
+Everything above is free. `@vjdesigns/vjdesigns-ui-pro` is a commercial add-on for teams that need more from their data grids:
+
+- **DataGridPro:** everything `DataGrid` does, plus resizable columns (pointer and keyboard), saved column layouts, and columns pinned to either edge.
+- **CSV export:** export exactly what a grid shows, safe to open in a spreadsheet.
+- **Charts:** accessible `BarChart` and `LineChart`: keyboard-navigable points with spoken values, a data table view, color-blind-safe series colors, and High Contrast support.
+- **Account forms:** ready-made sign-in, sign-up, forgot-password, reset-password, and verification-code forms that you connect to your own backend, with validation, autofill, passkey support, and safe error messages built in.
+- **Figma kit:** a plugin that creates the library's variables (brands, light and dark themes, spacing, type) and shadow styles in Figma, generated from the same tokens as the code, plus W3C design token files.
+
+It uses the same tokens, themes, languages, and accessibility standard as the free package.
+
+---
+
+## Development
+
+```bash
+npm run storybook        # run Storybook locally at http://localhost:6006
+npm run build            # type-check and build the library to dist/
+npm run build-storybook  # build a static Storybook site
+```
+
+Components live under `src/components/<category>/<Name>/`, with each component's implementation, CSS module and Storybook stories kept together. Shared design tokens live in `src/styles/tokens.css`. The build bundles all styles into `dist/vjdesigns-ui.css`.
+
+### Translating built-in text
+
+You write each built-in message once, in English, and a script translates it into every bundled language with the Claude API.
+
+**1. Edit the English.** Add, reword, or remove the message in [`src/i18n/en.ts`](src/i18n/en.ts). For a new message, also add it to the `Messages` type in [`src/i18n/types.ts`](src/i18n/types.ts) with a short comment saying where it appears. The translator reads that comment, so it helps to name the screen or the control.
+
+```ts
+// src/i18n/types.ts
+chat: {
+  /** Button that stops a reply while it streams. */
+  stop: string;
+};
+
+// src/i18n/en.ts
+chat: {
+  stop: "Stop response",
+},
+```
+
+**2. Translate.**
+
+```bash
+npm run i18n:translate
+```
+
+The script finds the English messages that are new or reworded since the last run, translates only those into all 31 locales, and removes keys English no longer has. Then it runs `check-locales.mjs` and the type-check. It never touches messages you didn't change, so hand-corrected translations are kept.
+
+**3. Review and commit.** Look over `git diff src/i18n`, then commit the locale files together with `src/i18n/en.snapshot.json`. The snapshot records which English text has been translated. It's how the next run knows what changed, so commit it with the translations.
+
+**Setup (once).** Run `npm install`. The script uses `@anthropic-ai/sdk`, a dev dependency that the published package doesn't include. You also need a Claude API key from [platform.claude.com](https://platform.claude.com), set in your shell:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...        # macOS, Linux, Git Bash
+$env:ANTHROPIC_API_KEY = "sk-ant-..."      # PowerShell
+```
+
+Don't commit the key or put it in a `.env` file that ships with the library. The script only runs on your machine, and the translations ship as plain files, so the library never calls the API at runtime. Each run sends only the changed messages, so a typical run costs a few cents.
+
+**Options**
+
+| Command | What it does |
+| --- | --- |
+| `npm run i18n:translate -- --dry-run` | Lists what would be translated in each locale, without calling the API |
+| `npm run i18n:translate -- --locales de,fr` | Translates only these locales (the snapshot isn't updated, so a later full run still covers the rest) |
+| `npm run i18n:translate -- --accept` | Records the current English as translated without translating, for edits that don't change the meaning (a typo or punctuation fix) |
+| `npm run i18n:translate -- --concurrency 1` | Translates one locale at a time, if you hit rate limits (default: 4) |
+| `npm run i18n:translate -- --effort medium` | Uses less model effort, which is cheaper and faster (default: `high`) |
+| `npm run i18n:translate -- --skip-checks` | Skips the locale check and type-check afterwards |
+
+**If English changes without a translation run**, `node scripts/check-locales.mjs` fails and names the messages, so other languages can't silently keep the old meaning. Run `npm run i18n:translate`, or use `--accept` if the change doesn't affect translations.
+
+**Adding a language.** Copy an existing locale file to `src/i18n/locales/<code>.ts`, keep its header (the imports and the `p` and `n` helpers, with the new code), and empty the messages object: `export const messages: Messages = {};`. Then run `npm run i18n:translate -- --locales <code>`. It translates every message the new file is missing. The build picks up the new file automatically (`@vjdesigns/vjdesigns-ui/locales/<code>`). Add the language to [Bundled languages](#bundled-languages) too.
+
+**How it works.** The script ([`scripts/translate-locales.mjs`](scripts/translate-locales.mjs)) reads the catalogs as TypeScript source and sends Claude each message's English source, its type and comment from `types.ts`, the locale's current translation if there is one, and the locale's existing translations in the same section, so terminology stays consistent. Claude returns TypeScript for each message. Plurals go through the locale's `p()` helper with that language's own plural forms (Russian has four, Arabic six). The script checks that every answer is valid TypeScript of the right kind (text, a function with the same parameters, or an array of the same length), asks again once for any that aren't, then writes the answers into the locale files in English order. Messages that still fail are listed and left unchanged, and the snapshot isn't updated, so re-running retries them.
+
+The translations are machine-made. Corrections from native speakers are welcome: edit the locale file directly. The script won't overwrite your fix unless the English for that message changes.
+
+### Releasing
+
+```bash
+npm whoami               # check you're logged in (if not: npm login)
+npm run build
+npm version patch        # or minor / major
+npm publish
+git push --follow-tags
+```
+
+See [RELEASING.md](RELEASING.md) for the full process, including how to update the projects that use the library and fixes for common errors.
+
+---
+
+## Access to the production Storybook
+
+1. Go to [component.vjdesigns.org](https://component.vjdesigns.org/).
+2. Enter your email in the Cloudflare prompt to receive a 6-digit access code.
+
+<img width="1917" height="927" alt="Cloudflare access prompt for component.vjdesigns.org" src="https://github.com/user-attachments/assets/bfe58737-52d2-4bf3-b7f7-72ba5ee54969" />
+
+---
+
+## License
+
+ISC