@vjdesigns/vjdesigns-ui 2.3.0 → 2.5.0

package/dist/ai/registry.json

@@ -1,6 +1,6 @@
 {
   "name": "@vjdesigns/vjdesigns-ui",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "summary": "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.",
   "install": "npm install @vjdesigns/vjdesigns-ui",
   "stylesheet": "@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css",
@@ -22,7 +22,7 @@
     {
       "id": "usage",
       "title": "Usage",
-      "markdown": "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.\n\n### React\n\n```tsx\nimport { useState } from \"react\";\nimport { Button, CheckBox } from \"@vjdesigns/vjdesigns-ui\";\n\nexport function SignupForm() {\n  const [accepted, setAccepted] = useState(false);\n\n  return (\n    <form>\n      <CheckBox\n        label=\"Accept terms\"\n        checked={accepted}\n        onCheckedChange={setAccepted}\n      />\n      <Button\n        variant=\"solid\"\n        tone=\"primary\"\n        size=\"md\"\n        disabled={!accepted}\n        onClick={() => console.log(\"Submitted\")}\n      >\n        Submit\n      </Button>\n    </form>\n  );\n}\n```\n\n### Angular\n\nMake 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.\n\n```ts\n// vj-button.component.ts\nimport {\n  AfterViewInit,\n  Component,\n  ElementRef,\n  EventEmitter,\n  Input,\n  OnChanges,\n  OnDestroy,\n  Output,\n  ViewChild,\n} from \"@angular/core\";\nimport { createElement, type MouseEvent as ReactMouseEvent, type ReactElement } from \"react\";\nimport { createRoot, Root } from \"react-dom/client\";\nimport {\n  Button,\n  type ButtonProps,\n  type ButtonVariant,\n  type Size,\n  type Tone,\n} from \"@vjdesigns/vjdesigns-ui\";\n\n// Button has overloaded types (for `href` and `as`). Narrowing it here lets createElement type-check.\nconst ReactButton = Button as (props: ButtonProps) => ReactElement;\n\n@Component({\n  selector: \"vj-button\",\n  standalone: true,\n  template: `<span #host></span>`,\n})\nexport class VjButtonComponent implements AfterViewInit, OnChanges, OnDestroy {\n  @ViewChild(\"host\", { static: true }) host!: ElementRef<HTMLElement>;\n\n  @Input() label = \"\";\n  @Input() variant: ButtonVariant = \"solid\";\n  @Input() tone: Tone = \"primary\";\n  @Input() size: Size = \"md\";\n  @Input() disabled = false;\n  @Output() clicked = new EventEmitter<MouseEvent>();\n\n  private root?: Root;\n\n  ngAfterViewInit() {\n    this.root = createRoot(this.host.nativeElement);\n    this.render();\n  }\n\n  ngOnChanges() {\n    this.render();\n  }\n\n  ngOnDestroy() {\n    this.root?.unmount();\n  }\n\n  private render() {\n    this.root?.render(\n      createElement(\n        ReactButton,\n        {\n          variant: this.variant,\n          tone: this.tone,\n          size: this.size,\n          disabled: this.disabled,\n          onClick: (event: ReactMouseEvent) => this.clicked.emit(event.nativeEvent),\n        },\n        this.label // the button's text is passed as children\n      )\n    );\n  }\n}\n```\n\nImport the wrapper wherever you need it:\n\n```ts\n// app.component.ts\nimport { Component } from \"@angular/core\";\nimport { VjButtonComponent } from \"./vj-button.component\";\n\n@Component({\n  selector: \"app-root\",\n  standalone: true,\n  imports: [VjButtonComponent],\n  template: `<vj-button label=\"Submit\" tone=\"primary\" (clicked)=\"onSubmit()\" />`,\n})\nexport class AppComponent {\n  onSubmit() {\n    console.log(\"Submitted\");\n  }\n}\n```\n\n### Vue 3\n\nMake a wrapper component that mounts the React component when it loads and re-renders it whenever its props change.\n\n```vue\n<!-- VjButton.vue -->\n<script setup lang=\"ts\">\nimport { onBeforeUnmount, onMounted, ref, watch } from \"vue\";\nimport { createElement, type MouseEvent as ReactMouseEvent, type ReactElement } from \"react\";\nimport { createRoot, type Root } from \"react-dom/client\";\nimport {\n  Button,\n  type ButtonProps,\n  type ButtonVariant,\n  type Size,\n  type Tone,\n} from \"@vjdesigns/vjdesigns-ui\";\n\n// Button has overloaded types (for `href` and `as`). Narrowing it here lets createElement type-check.\nconst ReactButton = Button as (props: ButtonProps) => ReactElement;\n\nconst props = withDefaults(\n  defineProps<{\n    label: string;\n    variant?: ButtonVariant;\n    tone?: Tone;\n    size?: Size;\n    disabled?: boolean;\n  }>(),\n  { variant: \"solid\", tone: \"primary\", size: \"md\", disabled: false }\n);\n\nconst emit = defineEmits<{ click: [event: MouseEvent] }>();\n\nconst host = ref<HTMLElement | null>(null);\nlet root: Root | undefined;\n\nfunction render() {\n  root?.render(\n    createElement(\n      ReactButton,\n      {\n        variant: props.variant,\n        tone: props.tone,\n        size: props.size,\n        disabled: props.disabled,\n        onClick: (event: ReactMouseEvent) => emit(\"click\", event.nativeEvent),\n      },\n      props.label // the button's text is passed as children\n    )\n  );\n}\n\nonMounted(() => {\n  root = createRoot(host.value!);\n  render();\n});\n\nwatch(() => ({ ...props }), render);\n\nonBeforeUnmount(() => root?.unmount());\n</script>\n\n<template>\n  <span ref=\"host\" />\n</template>\n```\n\nUse it like any other Vue component:\n\n```vue\n<script setup lang=\"ts\">\nimport VjButton from \"./VjButton.vue\";\n\nconst onSubmit = () => console.log(\"Submitted\");\n</script>\n\n<template>\n  <VjButton label=\"Submit\" tone=\"primary\" @click=\"onSubmit\" />\n</template>\n```\n\n> **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."
+      "markdown": "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.\n\n### React\n\n```tsx\nimport { useState } from \"react\";\nimport { Button, CheckBox } from \"@vjdesigns/vjdesigns-ui\";\n\nexport function SignupForm() {\n  const [accepted, setAccepted] = useState(false);\n\n  return (\n    <form>\n      <CheckBox\n        label=\"Accept terms\"\n        checked={accepted}\n        onCheckedChange={setAccepted}\n      />\n      <Button\n        variant=\"solid\"\n        tone=\"primary\"\n        size=\"md\"\n        disabled={!accepted}\n        onClick={() => console.log(\"Submitted\")}\n      >\n        Submit\n      </Button>\n    </form>\n  );\n}\n```\n\n### Next.js (App Router) and React Server Components\n\nThe library works in Server Components. Interactive components (anything with state, effects, or context: `Button`, `DataGrid`, `Modal`, ...) are marked `\"use client\"`, so you can render them from a Server Component like any client component. Utilities (`cx`, `sortRows`, `createBrandPalette`, `getLocaleDirection`, ...) and the locale catalogs have no directive, so you can call or read them on the server too. Every component also renders on the server for the first paint.\n\nPut the providers in a small client file of your own, and render it from the root layout:\n\n```tsx\n// app/providers.tsx\n\"use client\";\nimport { LocaleProvider, ToastProvider } from \"@vjdesigns/vjdesigns-ui\";\nimport es from \"@vjdesigns/vjdesigns-ui/locales/es\";\nimport type { ReactNode } from \"react\";\n\nexport function Providers({ children }: { children: ReactNode }) {\n  return (\n    <LocaleProvider locale=\"es\" messages={es}>\n      <ToastProvider>{children}</ToastProvider>\n    </LocaleProvider>\n  );\n}\n```\n\n```tsx\n// app/layout.tsx (a Server Component)\nimport \"@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css\";\nimport { getLocaleDirection } from \"@vjdesigns/vjdesigns-ui\";\nimport { Providers } from \"./providers\";\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <html lang=\"es\" dir={getLocaleDirection(\"es\")}>\n      <body>\n        <Providers>{children}</Providers>\n      </body>\n    </html>\n  );\n}\n```\n\nTwo rules of Server Components to keep in mind:\n\n- **Functions can't be passed from a Server Component to a client one.** That includes event handlers (`onClick`), DataGrid columns with `cell` or `value` functions, and the locale catalogs themselves (their plural messages are functions, which is why `LocaleProvider` goes in the client providers file above). Render those components from your own `\"use client\"` file.\n- **Compound parts can't be reached with a dot from a Server Component** (`Tabs.List`, `Menu.Item`): Next.js reports \"You cannot dot into a client module\". Use them inside a `\"use client\"` file, or use the named exports where they exist (`CardHeader`, `CardBody`, `NavbarBrand`, ...).\n\n### Angular\n\nMake 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.\n\n```ts\n// vj-button.component.ts\nimport {\n  AfterViewInit,\n  Component,\n  ElementRef,\n  EventEmitter,\n  Input,\n  OnChanges,\n  OnDestroy,\n  Output,\n  ViewChild,\n} from \"@angular/core\";\nimport { createElement, type MouseEvent as ReactMouseEvent, type ReactElement } from \"react\";\nimport { createRoot, Root } from \"react-dom/client\";\nimport {\n  Button,\n  type ButtonProps,\n  type ButtonVariant,\n  type Size,\n  type Tone,\n} from \"@vjdesigns/vjdesigns-ui\";\n\n// Button has overloaded types (for `href` and `as`). Narrowing it here lets createElement type-check.\nconst ReactButton = Button as (props: ButtonProps) => ReactElement;\n\n@Component({\n  selector: \"vj-button\",\n  standalone: true,\n  template: `<span #host></span>`,\n})\nexport class VjButtonComponent implements AfterViewInit, OnChanges, OnDestroy {\n  @ViewChild(\"host\", { static: true }) host!: ElementRef<HTMLElement>;\n\n  @Input() label = \"\";\n  @Input() variant: ButtonVariant = \"solid\";\n  @Input() tone: Tone = \"primary\";\n  @Input() size: Size = \"md\";\n  @Input() disabled = false;\n  @Output() clicked = new EventEmitter<MouseEvent>();\n\n  private root?: Root;\n\n  ngAfterViewInit() {\n    this.root = createRoot(this.host.nativeElement);\n    this.render();\n  }\n\n  ngOnChanges() {\n    this.render();\n  }\n\n  ngOnDestroy() {\n    this.root?.unmount();\n  }\n\n  private render() {\n    this.root?.render(\n      createElement(\n        ReactButton,\n        {\n          variant: this.variant,\n          tone: this.tone,\n          size: this.size,\n          disabled: this.disabled,\n          onClick: (event: ReactMouseEvent) => this.clicked.emit(event.nativeEvent),\n        },\n        this.label // the button's text is passed as children\n      )\n    );\n  }\n}\n```\n\nImport the wrapper wherever you need it:\n\n```ts\n// app.component.ts\nimport { Component } from \"@angular/core\";\nimport { VjButtonComponent } from \"./vj-button.component\";\n\n@Component({\n  selector: \"app-root\",\n  standalone: true,\n  imports: [VjButtonComponent],\n  template: `<vj-button label=\"Submit\" tone=\"primary\" (clicked)=\"onSubmit()\" />`,\n})\nexport class AppComponent {\n  onSubmit() {\n    console.log(\"Submitted\");\n  }\n}\n```\n\n### Vue 3\n\nMake a wrapper component that mounts the React component when it loads and re-renders it whenever its props change.\n\n```vue\n<!-- VjButton.vue -->\n<script setup lang=\"ts\">\nimport { onBeforeUnmount, onMounted, ref, watch } from \"vue\";\nimport { createElement, type MouseEvent as ReactMouseEvent, type ReactElement } from \"react\";\nimport { createRoot, type Root } from \"react-dom/client\";\nimport {\n  Button,\n  type ButtonProps,\n  type ButtonVariant,\n  type Size,\n  type Tone,\n} from \"@vjdesigns/vjdesigns-ui\";\n\n// Button has overloaded types (for `href` and `as`). Narrowing it here lets createElement type-check.\nconst ReactButton = Button as (props: ButtonProps) => ReactElement;\n\nconst props = withDefaults(\n  defineProps<{\n    label: string;\n    variant?: ButtonVariant;\n    tone?: Tone;\n    size?: Size;\n    disabled?: boolean;\n  }>(),\n  { variant: \"solid\", tone: \"primary\", size: \"md\", disabled: false }\n);\n\nconst emit = defineEmits<{ click: [event: MouseEvent] }>();\n\nconst host = ref<HTMLElement | null>(null);\nlet root: Root | undefined;\n\nfunction render() {\n  root?.render(\n    createElement(\n      ReactButton,\n      {\n        variant: props.variant,\n        tone: props.tone,\n        size: props.size,\n        disabled: props.disabled,\n        onClick: (event: ReactMouseEvent) => emit(\"click\", event.nativeEvent),\n      },\n      props.label // the button's text is passed as children\n    )\n  );\n}\n\nonMounted(() => {\n  root = createRoot(host.value!);\n  render();\n});\n\nwatch(() => ({ ...props }), render);\n\nonBeforeUnmount(() => root?.unmount());\n</script>\n\n<template>\n  <span ref=\"host\" />\n</template>\n```\n\nUse it like any other Vue component:\n\n```vue\n<script setup lang=\"ts\">\nimport VjButton from \"./VjButton.vue\";\n\nconst onSubmit = () => console.log(\"Submitted\");\n</script>\n\n<template>\n  <VjButton label=\"Submit\" tone=\"primary\" @click=\"onSubmit\" />\n</template>\n```\n\n> **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."
     },
     {
       "id": "theming",
@@ -325,7 +325,7 @@
       "category": "data-display",
       "folder": "Avatar",
       "import": "import { Avatar } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "A person's photo (`src`), with a fallback chain of image, initials (from\r\n`name`), then a user icon, so it always shows something. Supports a border,\r\na presence status dot, a highlight ring, and stacking in an `AvatarGroup`.",
+      "description": "A person's photo (`src`), with a fallback chain of image, initials (from\n`name`), then a user icon, so it always shows something. Supports a border,\na presence status dot, a highlight ring, and stacking in an `AvatarGroup`.",
       "nativeElement": "span",
       "props": [
         {
@@ -338,7 +338,7 @@
           "name": "alt",
           "type": "string",
           "required": false,
-          "description": "Text alternative for the image. Used as the accessible name (falls back to\r\n`name`). Pass `alt=\"\"` with no `name` to make the avatar decorative."
+          "description": "Text alternative for the image. Used as the accessible name (falls back to\n`name`). Pass `alt=\"\"` with no `name` to make the avatar decorative."
         },
         {
           "name": "name",
@@ -392,13 +392,13 @@
           "name": "bordered",
           "type": "boolean",
           "required": false,
-          "description": "Draws a border around the avatar, e.g. to set a photo apart from a busy\r\nbackground or a cover image. Decorative. Its color is the\r\n`--avatar-border-color` CSS variable (default `--color-border-strong`);\r\nset it to `var(--color-surface)` for a light frame on a photo banner."
+          "description": "Draws a border around the avatar, e.g. to set a photo apart from a busy\nbackground or a cover image. Decorative. Its color is the\n`--avatar-border-color` CSS variable (default `--color-border-strong`);\nset it to `var(--color-surface)` for a light frame on a photo banner."
         },
         {
           "name": "ring",
           "type": "boolean",
           "required": false,
-          "description": "Highlight ring (e.g. the active player). Visual only: also convey the\r\nstate in text nearby or in `aria-label`."
+          "description": "Highlight ring (e.g. the active player). Visual only: also convey the\nstate in text nearby or in `aria-label`."
         },
         {
           "name": "ringTone",
@@ -410,7 +410,7 @@
           "name": "decorative",
           "type": "boolean",
           "required": false,
-          "description": "Hide the avatar from assistive technology. Use when the person's name is\r\nalready visible next to the avatar."
+          "description": "Hide the avatar from assistive technology. Use when the person's name is\nalready visible next to the avatar."
         },
         {
           "name": "icon",
@@ -497,7 +497,7 @@
       "category": "data-display",
       "folder": "Avatar",
       "import": "import { AvatarGroup } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "Overlapping stack of avatars in a labelled `role=\"group\"`. Avatars beyond\r\n`max` collapse into a \"+N\" surplus avatar with an accessible label.",
+      "description": "Overlapping stack of avatars in a labelled `role=\"group\"`. Avatars beyond\n`max` collapse into a \"+N\" surplus avatar with an accessible label.",
       "nativeElement": "div",
       "props": [
         {
@@ -687,6 +687,10 @@
           "name": "In text",
           "description": ""
         },
+        {
+          "name": "Inverse",
+          "description": "`inverse` swaps the solid colors, for a badge on a solid tone surface: a solid Navbar, a Banner, a primary card."
+        },
         {
           "name": "On surfaces (both themes)",
           "description": ""
@@ -2175,6 +2179,13 @@
           "required": false,
           "description": "Rows per page. Shows a footer with the range and `Pagination`. Without it, every row shows."
         },
+        {
+          "name": "virtualize",
+          "type": "boolean | \"auto\"",
+          "required": false,
+          "default": "\"auto\"",
+          "description": "Render only the rows in view (plus a few above and below), so grids of\n100,000+ rows scroll, sort, filter, and select without delay. `\"auto\"`\nturns it on when more than 100 rows show at once. While it's on, the body\nscrolls inside the grid (its height is `maxHeight`, 70% of the window by\ndefault) and the table uses fixed layout unless you set `layout`, so\ncolumns keep their widths while you scroll; give columns a `width` to\nsize them. Screen readers still get the full count (`aria-rowcount`)\nand each row's position (`aria-rowindex`)."
+        },
         {
           "name": "page",
           "type": "number",
@@ -2265,7 +2276,7 @@
           "name": "layout",
           "type": "\"auto\" | \"fixed\"",
           "required": false,
-          "default": "\"auto\"",
+          "default": "\"auto\" (\"fixed\" while virtualized)",
           "description": "Table layout. `fixed` makes column widths exact (content wraps or clips\ninstead of widening a column)."
         },
         {
@@ -2339,6 +2350,10 @@
         {
           "name": "Extending Columns",
           "description": "Extending columns: `headerEnd` adds content after a header's label,\noutside its sort button (here a column menu button), and `className` /\n`style` reach every cell of a column. Controls marked\n`data-grid-secondary` don't steal the header's focus: the sort button\nstays its target, and F2 then Tab reaches them."
+        },
+        {
+          "name": "Large data (100,000 rows)",
+          "description": "100,000 rows with sorting, search, and selection. Only the rows in view\n(plus a few above and below) are in the page, so scrolling, sorting,\nfiltering, and selecting stay instant at any size. Screen readers still\nhear the full count (`aria-rowcount`) and each row's position."
         }
       ]
     },
@@ -2725,7 +2740,7 @@
       "category": "data-display",
       "folder": "List",
       "import": "import { List } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "A semantic list (`<ul>` or `<ol>`) with styled markers and rich items.\r\n\r\nEvery variant draws its own markers, so the browser's markers are removed\r\nwith CSS; `role=\"list\"` is added so Safari and VoiceOver keep announcing\r\nthe list and its item count.\r\n\r\nThis is a list, not a listbox: items are not selectable options and there\r\nis no roving focus. Interactive items (`List.ItemButton`, `List.ItemLink`)\r\nare ordinary Tab stops. For choosing among options, use a Listbox,\r\nCombobox, or Select instead.\r\n\r\nGrouping: put a `List.Subheader` (a real heading by default) before each\r\nlist and point the list at it with `aria-labelledby`, so screen readers\r\nannounce \"Account, list, 3 items\".",
+      "description": "A semantic list (`<ul>` or `<ol>`) with styled markers and rich items.\n\nEvery variant draws its own markers, so the browser's markers are removed\nwith CSS; `role=\"list\"` is added so Safari and VoiceOver keep announcing\nthe list and its item count.\n\nThis is a list, not a listbox: items are not selectable options and there\nis no roving focus. Interactive items (`List.ItemButton`, `List.ItemLink`)\nare ordinary Tab stops. For choosing among options, use a Listbox,\nCombobox, or Select instead.\n\nGrouping: put a `List.Subheader` (a real heading by default) before each\nlist and point the list at it with `aria-labelledby`, so screen readers\nannounce \"Account, list, 3 items\".",
       "nativeElement": "ol",
       "props": [
         {
@@ -2759,13 +2774,13 @@
           "name": "spacing",
           "type": "Space",
           "required": false,
-          "description": "Space between items, as a `--space-*` step. For `plain`, `bulleted`, and\r\n`numbered` it is the gap between items; for `divided` and `card` (where\r\na gap would break the dividers) it is each item's block padding.\r\nDefaults to a step that scales with `size`."
+          "description": "Space between items, as a `--space-*` step. For `plain`, `bulleted`, and\n`numbered` it is the gap between items; for `divided` and `card` (where\na gap would break the dividers) it is each item's block padding.\nDefaults to a step that scales with `size`."
         },
         {
           "name": "marker",
           "type": "ReactNode",
           "required": false,
-          "description": "A custom marker for every item, such as `<CheckIcon />` for a feature\r\nlist. Replaces the variant's dot or number. Decorative: hidden from\r\nassistive technology, so the item text must carry the meaning."
+          "description": "A custom marker for every item, such as `<CheckIcon />` for a feature\nlist. Replaces the variant's dot or number. Decorative: hidden from\nassistive technology, so the item text must carry the meaning."
         },
         {
           "name": "start",
@@ -2791,7 +2806,7 @@
         {
           "name": "List.Item",
           "exportedAs": "ListItem",
-          "description": "A static list item (`<li>`) with optional `start`, `title`, `description`,\r\n`meta`, and `end` slots, or plain `children`. For a clickable row, use\r\n`List.ItemButton` or `List.ItemLink`.",
+          "description": "A static list item (`<li>`) with optional `start`, `title`, `description`,\n`meta`, and `end` slots, or plain `children`. For a clickable row, use\n`List.ItemButton` or `List.ItemLink`.",
           "nativeElement": "li",
           "props": [
             {
@@ -2822,20 +2837,20 @@
               "name": "end",
               "type": "ReactNode",
               "required": false,
-              "description": "Trailing content: actions (`IconButton`, `Switch`), `Badge`s, or a\r\nchevron. On `ItemButton` and `ItemLink` these stay independently\r\nclickable and focusable; they sit above the stretched main action."
+              "description": "Trailing content: actions (`IconButton`, `Switch`), `Badge`s, or a\nchevron. On `ItemButton` and `ItemLink` these stay independently\nclickable and focusable; they sit above the stretched main action."
             },
             {
               "name": "marker",
               "type": "ReactNode",
               "required": false,
-              "description": "Overrides the list's marker for this item. `undefined` inherits the\r\nlist's marker; `false` removes the marker. Decorative and hidden from\r\nassistive technology."
+              "description": "Overrides the list's marker for this item. `undefined` inherits the\nlist's marker; `false` removes the marker. Decorative and hidden from\nassistive technology."
             },
             {
               "name": "selected",
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Highlights the item with a tinted fill and a leading bar (shape plus\r\ncolor). Also sets `aria-current` (`\"page\"` on links, `\"true\"` otherwise)\r\nso the state is announced, not only seen."
+              "description": "Highlights the item with a tinted fill and a leading bar (shape plus\ncolor). Also sets `aria-current` (`\"page\"` on links, `\"true\"` otherwise)\nso the state is announced, not only seen."
             },
             {
               "name": "current",
@@ -2854,7 +2869,7 @@
         {
           "name": "List.ItemButton",
           "exportedAs": "ListItemButton",
-          "description": "A list item whose main area is a real `<button>`. The button wraps the\r\ntitle (or `children` when there is no title) and its hit area is\r\nstretched over the whole row, so the row is clickable, while `end`\r\nactions sit above it and stay independently clickable. Never nest\r\ninteractive elements in `title` or `description`.\r\n\r\n`className` and `style` go on the row `<li>`; `ref`, `onClick`, `type`,\r\n`aria-*`, and every other prop go on the `<button>`. The description and\r\nmeta become the button's accessible description.",
+          "description": "A list item whose main area is a real `<button>`. The button wraps the\ntitle (or `children` when there is no title) and its hit area is\nstretched over the whole row, so the row is clickable, while `end`\nactions sit above it and stay independently clickable. Never nest\ninteractive elements in `title` or `description`.\n\n`className` and `style` go on the row `<li>`; `ref`, `onClick`, `type`,\n`aria-*`, and every other prop go on the `<button>`. The description and\nmeta become the button's accessible description.",
           "nativeElement": "button",
           "props": [
             {
@@ -2885,20 +2900,20 @@
               "name": "end",
               "type": "ReactNode",
               "required": false,
-              "description": "Trailing content: actions (`IconButton`, `Switch`), `Badge`s, or a\r\nchevron. On `ItemButton` and `ItemLink` these stay independently\r\nclickable and focusable; they sit above the stretched main action."
+              "description": "Trailing content: actions (`IconButton`, `Switch`), `Badge`s, or a\nchevron. On `ItemButton` and `ItemLink` these stay independently\nclickable and focusable; they sit above the stretched main action."
             },
             {
               "name": "marker",
               "type": "ReactNode",
               "required": false,
-              "description": "Overrides the list's marker for this item. `undefined` inherits the\r\nlist's marker; `false` removes the marker. Decorative and hidden from\r\nassistive technology."
+              "description": "Overrides the list's marker for this item. `undefined` inherits the\nlist's marker; `false` removes the marker. Decorative and hidden from\nassistive technology."
             },
             {
               "name": "selected",
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Highlights the item with a tinted fill and a leading bar (shape plus\r\ncolor). Also sets `aria-current` (`\"page\"` on links, `\"true\"` otherwise)\r\nso the state is announced, not only seen."
+              "description": "Highlights the item with a tinted fill and a leading bar (shape plus\ncolor). Also sets `aria-current` (`\"page\"` on links, `\"true\"` otherwise)\nso the state is announced, not only seen."
             },
             {
               "name": "current",
@@ -2942,7 +2957,7 @@
         {
           "name": "List.ItemLink",
           "exportedAs": "ListItemLink",
-          "description": "A list item whose main area is a real `<a>`, stretched over the whole row\r\nlike `List.ItemButton`. `selected` sets `aria-current=\"page\"` (override\r\nwith `current`). When `disabled`, the link loses its `href` and is marked\r\n`aria-disabled`, so it can't be followed or focused.\r\n\r\n`className` and `style` go on the row `<li>`; everything else, including\r\n`ref` and `href`, goes on the `<a>`.",
+          "description": "A list item whose main area is a real `<a>`, stretched over the whole row\nlike `List.ItemButton`. `selected` sets `aria-current=\"page\"` (override\nwith `current`). When `disabled`, the link loses its `href` and is marked\n`aria-disabled`, so it can't be followed or focused.\n\n`className` and `style` go on the row `<li>`; everything else, including\n`ref` and `href`, goes on the `<a>`.",
           "nativeElement": "a",
           "props": [
             {
@@ -2973,20 +2988,20 @@
               "name": "end",
               "type": "ReactNode",
               "required": false,
-              "description": "Trailing content: actions (`IconButton`, `Switch`), `Badge`s, or a\r\nchevron. On `ItemButton` and `ItemLink` these stay independently\r\nclickable and focusable; they sit above the stretched main action."
+              "description": "Trailing content: actions (`IconButton`, `Switch`), `Badge`s, or a\nchevron. On `ItemButton` and `ItemLink` these stay independently\nclickable and focusable; they sit above the stretched main action."
             },
             {
               "name": "marker",
               "type": "ReactNode",
               "required": false,
-              "description": "Overrides the list's marker for this item. `undefined` inherits the\r\nlist's marker; `false` removes the marker. Decorative and hidden from\r\nassistive technology."
+              "description": "Overrides the list's marker for this item. `undefined` inherits the\nlist's marker; `false` removes the marker. Decorative and hidden from\nassistive technology."
             },
             {
               "name": "selected",
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Highlights the item with a tinted fill and a leading bar (shape plus\r\ncolor). Also sets `aria-current` (`\"page\"` on links, `\"true\"` otherwise)\r\nso the state is announced, not only seen."
+              "description": "Highlights the item with a tinted fill and a leading bar (shape plus\ncolor). Also sets `aria-current` (`\"page\"` on links, `\"true\"` otherwise)\nso the state is announced, not only seen."
             },
             {
               "name": "current",
@@ -3030,7 +3045,7 @@
         {
           "name": "List.Subheader",
           "exportedAs": "ListSubheader",
-          "description": "An uppercase label for a group of items. Render it before (outside) a\r\n`List`, give it an `id`, and pass that id to the list's\r\n`aria-labelledby`. It must not go inside the `<ul>`, where it would be\r\ncounted as an item.\r\n\r\n```tsx\r\n<List.Subheader id=\"acct\">Account</List.Subheader>\r\n<List aria-labelledby=\"acct\">...</List>\r\n```",
+          "description": "An uppercase label for a group of items. Render it before (outside) a\n`List`, give it an `id`, and pass that id to the list's\n`aria-labelledby`. It must not go inside the `<ul>`, where it would be\ncounted as an item.\n\n```tsx\n<List.Subheader id=\"acct\">Account</List.Subheader>\n<List aria-labelledby=\"acct\">...</List>\n```",
           "nativeElement": "h3",
           "props": [
             {
@@ -3038,7 +3053,7 @@
               "type": "ListSubheaderElement",
               "required": false,
               "default": "\"h3\"",
-              "description": "Element to render. A heading (default `h3`) so grouped lists show up in\r\nthe screen reader's headings list; pick the level that fits the page\r\noutline, or `div` when a heading would be out of place."
+              "description": "Element to render. A heading (default `h3`) so grouped lists show up in\nthe screen reader's headings list; pick the level that fits the page\noutline, or `div` when a heading would be out of place."
             },
             {
               "name": "size",
@@ -3413,7 +3428,7 @@
           "type": "string | number",
           "required": false,
           "default": "\"var(--container-xs)\" when `stickyHeader`, otherwise none",
-          "description": "Maximum height of the scroll container (any CSS length). Rows past it\r\nscroll vertically."
+          "description": "Maximum height of the scroll container (any CSS length). Rows past it\nscroll vertically."
         },
         {
           "name": "stickyFirstColumn",
@@ -3455,7 +3470,7 @@
           "type": "boolean",
           "required": false,
           "default": "false",
-          "description": "Shows a spinner over the table, dims the body, and sets `aria-busy` on\r\nthe `<table>`. Keep previous rows rendered so the layout doesn't jump."
+          "description": "Shows a spinner over the table, dims the body, and sets `aria-busy` on\nthe `<table>`. Keep previous rows rendered so the layout doesn't jump."
         },
         {
           "name": "loadingLabel",
@@ -3468,14 +3483,14 @@
           "name": "stackBelow",
           "type": "TableStackBreakpoint",
           "required": false,
-          "description": "Turns rows into stacked cards below this viewport width, labelling each\r\nvalue with its column header (`data-label`). While stacked, every part\r\ngets an explicit ARIA table role (`table`, `rowgroup`, `row`,\r\n`columnheader`, `cell`), because some browsers drop native table\r\nsemantics when CSS changes a table's `display`. The header row is\r\nvisually hidden but stays in the accessibility tree."
+          "description": "Turns rows into stacked cards below this viewport width, labelling each\nvalue with its column header (`data-label`). While stacked, every part\ngets an explicit ARIA table role (`table`, `rowgroup`, `row`,\n`columnheader`, `cell`), because some browsers drop native table\nsemantics when CSS changes a table's `display`. The header row is\nvisually hidden but stays in the accessibility tree."
         },
         {
           "name": "scrollLabel",
           "type": "string",
           "required": false,
           "default": "\"Scrollable table\"",
-          "description": "Accessible name for the scroll region, used when the table overflows and\r\nhas no `Table.Caption`, `aria-label`, or `aria-labelledby`."
+          "description": "Accessible name for the scroll region, used when the table overflows and\nhas no `Table.Caption`, `aria-label`, or `aria-labelledby`."
         },
         {
           "name": "className",
@@ -3500,7 +3515,7 @@
         {
           "name": "Table.Caption",
           "exportedAs": "TableCaption",
-          "description": "The table's title (`<caption>`). It names the table and, when the table\r\nscrolls, its scroll region. Strongly recommended on every table.",
+          "description": "The table's title (`<caption>`). It names the table and, when the table\nscrolls, its scroll region. Strongly recommended on every table.",
           "nativeElement": "caption",
           "props": []
         },
@@ -3536,14 +3551,14 @@
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Shows the row as selected. Visual only: `aria-selected` is not valid on\r\nrows of a plain `<table>` (only inside `role=\"grid\"` / `treegrid`), so the\r\nselected state is conveyed to assistive technology by the row's checked\r\n`Table.SelectCell` checkbox. Pair the two."
+              "description": "Shows the row as selected. Visual only: `aria-selected` is not valid on\nrows of a plain `<table>` (only inside `role=\"grid\"` / `treegrid`), so the\nselected state is conveyed to assistive technology by the row's checked\n`Table.SelectCell` checkbox. Pair the two."
             }
           ]
         },
         {
           "name": "Table.HeaderCell",
           "exportedAs": "TableHeaderCell",
-          "description": "A header cell (`<th>`). With `sortable`, the whole cell is a real\r\n`<button>` and the header carries `aria-sort` while it is the sorted column.\r\nThe sort icon shows the direction by shape (up arrow, down arrow, or a\r\nneutral double arrow), not by color alone.",
+          "description": "A header cell (`<th>`). With `sortable`, the whole cell is a real\n`<button>` and the header carries `aria-sort` while it is the sorted column.\nThe sort icon shows the direction by shape (up arrow, down arrow, or a\nneutral double arrow), not by color alone.",
           "nativeElement": "th",
           "props": [
             {
@@ -3565,7 +3580,7 @@
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Keeps content on one line and cuts it off with an ellipsis. Works best\r\nwith `layout=\"fixed\"` or a `width`. String content also gets a `title`\r\ntooltip; screen readers always read the full text."
+              "description": "Keeps content on one line and cuts it off with an ellipsis. Works best\nwith `layout=\"fixed\"` or a `width`. String content also gets a `title`\ntooltip; screen readers always read the full text."
             },
             {
               "name": "width",
@@ -3577,7 +3592,7 @@
               "name": "scope",
               "type": "\"col\" | \"row\" | \"colgroup\" | \"rowgroup\"",
               "required": false,
-              "description": "Which cells this header labels. @default \"col\" in `Table.Head` and\r\n`Table.Foot`, \"row\" in `Table.Body` (use a header cell for each row's\r\nkey column, such as a player's name)"
+              "description": "Which cells this header labels. @default \"col\" in `Table.Head` and\n`Table.Foot`, \"row\" in `Table.Body` (use a header cell for each row's\nkey column, such as a player's name)"
             },
             {
               "name": "sortable",
@@ -3597,7 +3612,7 @@
               "name": "onSort",
               "type": "(nextDirection: TableSortDirection) => void",
               "required": false,
-              "description": "Called when the sort button is pressed, with the suggested next direction\r\n(`ascending` from none or descending, `descending` from ascending)."
+              "description": "Called when the sort button is pressed, with the suggested next direction\n(`ascending` from none or descending, `descending` from ascending)."
             }
           ]
         },
@@ -3626,7 +3641,7 @@
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Keeps content on one line and cuts it off with an ellipsis. Works best\r\nwith `layout=\"fixed\"` or a `width`. String content also gets a `title`\r\ntooltip; screen readers always read the full text."
+              "description": "Keeps content on one line and cuts it off with an ellipsis. Works best\nwith `layout=\"fixed\"` or a `width`. String content also gets a `title`\ntooltip; screen readers always read the full text."
             },
             {
               "name": "width",
@@ -3638,14 +3653,14 @@
               "name": "label",
               "type": "string",
               "required": false,
-              "description": "Column label shown beside the value when rows are stacked (`stackBelow`).\r\nDefaults to the matching header cell's text."
+              "description": "Column label shown beside the value when rows are stacked (`stackBelow`).\nDefaults to the matching header cell's text."
             }
           ]
         },
         {
           "name": "Table.SelectCell",
           "exportedAs": "TableSelectCell",
-          "description": "A data cell holding the row's selection checkbox. Pair with `selected` on\r\nthe `Table.Row`. Give it a `rowLabel` (or `checkboxLabel`) so each\r\ncheckbox has a unique accessible name.",
+          "description": "A data cell holding the row's selection checkbox. Pair with `selected` on\nthe `Table.Row`. Give it a `rowLabel` (or `checkboxLabel`) so each\ncheckbox has a unique accessible name.",
           "nativeElement": "td",
           "props": [
             {
@@ -3664,7 +3679,7 @@
               "name": "rowLabel",
               "type": "string",
               "required": false,
-              "description": "Readable name of the row, used for the checkbox's accessible name:\r\n\"Select row {rowLabel}\". Ignored when `checkboxLabel` is set."
+              "description": "Readable name of the row, used for the checkbox's accessible name:\n\"Select row {rowLabel}\". Ignored when `checkboxLabel` is set."
             },
             {
               "name": "checkboxLabel",
@@ -3684,7 +3699,7 @@
         {
           "name": "Table.SelectAllCell",
           "exportedAs": "TableSelectAllCell",
-          "description": "A header cell (`<th scope=\"col\">`) with a \"select all\" checkbox. Shows the\r\nmixed state (`aria-checked=\"mixed\"`) when some rows are selected.",
+          "description": "A header cell (`<th scope=\"col\">`) with a \"select all\" checkbox. Shows the\nmixed state (`aria-checked=\"mixed\"`) when some rows are selected.",
           "nativeElement": "th",
           "props": [
             {
@@ -6919,7 +6934,7 @@
         },
         {
           "name": "Basic Single",
-          "description": "Type to filter, ArrowDown to highlight, Enter to choose. The input shows the\r\nchosen label. Escape closes the list; a second Escape undoes typed text,\r\ngoing back to the chosen label (the selection is kept)."
+          "description": "Type to filter, ArrowDown to highlight, Enter to choose. The input shows the\nchosen label. Escape closes the list; a second Escape undoes typed text,\ngoing back to the chosen label (the selection is kept)."
         },
         {
           "name": "Results Announcement",
@@ -6927,7 +6942,7 @@
         },
         {
           "name": "Multiple",
-          "description": "`multiple`: selections become removable chips before the input. Enter\r\ntoggles the highlighted option and keeps the list open; Backspace on an\r\nempty input removes the last chip."
+          "description": "`multiple`: selections become removable chips before the input. Enter\ntoggles the highlighted option and keeps the list open; Backspace on an\nempty input removes the last chip."
         },
         {
           "name": "With Groups",
@@ -6947,7 +6962,7 @@
         },
         {
           "name": "Async",
-          "description": "Server-side filtering: `filter={false}` shows `options` as given, `loading`\r\nshows a spinner row, and `emptyMessage` a status row when nothing matches."
+          "description": "Server-side filtering: `filter={false}` shows `options` as given, `loading`\nshows a spinner row, and `emptyMessage` a status row when nothing matches."
         },
         {
           "name": "Creatable",
@@ -6975,7 +6990,7 @@
         },
         {
           "name": "In Modal",
-          "description": "Inside a Modal the list is a child layer: Escape closes only the list.\r\nWith the chosen label unchanged, the next Escape reaches the Modal and\r\ncloses it (the selection isn't silently cleared)."
+          "description": "Inside a Modal the list is a child layer: Escape closes only the list.\nWith the chosen label unchanged, the next Escape reaches the Modal and\ncloses it (the selection isn't silently cleared)."
         },
         {
           "name": "Assign Players To Team",
@@ -6991,7 +7006,11 @@
         },
         {
           "name": "Form submit, reset, and custom values",
-          "description": "Form behavior: Enter submits what is shown (cleared text submits no team),\r\na form reset restores the default, and re-entering a custom tag that's\r\nalready chosen doesn't remove it."
+          "description": "Form behavior: Enter submits what is shown (cleared text submits no team),\na form reset restores the default, and re-entering a custom tag that's\nalready chosen doesn't remove it."
+        },
+        {
+          "name": "Long list (10,000 options)",
+          "description": "10,000 options. Only the options in view are in the page (plus the\nhighlighted one), so opening, scrolling, and typing stay instant. Each\noption carries its position in the full list (`aria-setsize`,\n`aria-posinset`), so screen readers still hear \"10,000 of 10,000\".\nLists with groups always render in full."
         }
       ]
     },
@@ -8253,7 +8272,7 @@
       "category": "forms",
       "folder": "FileUpload",
       "import": "import { FileUpload } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "File picker with drag and drop, validation, and a file list.\r\n`FileUpload.List` is the standalone list for custom layouts.",
+      "description": "File picker with drag and drop, validation, and a file list.\n`FileUpload.List` is the standalone list for custom layouts.",
       "nativeElement": "div",
       "props": [
         {
@@ -8352,7 +8371,7 @@
           "type": "Size",
           "required": false,
           "default": "\"md\"",
-          "description": "`sm`: compact inline row. `md`: standard dropzone. `lg`: hero dropzone.\r\nInherits from a surrounding `Field`."
+          "description": "`sm`: compact inline row. `md`: standard dropzone. `lg`: hero dropzone.\nInherits from a surrounding `Field`."
         },
         {
           "name": "variant",
@@ -8365,7 +8384,7 @@
           "name": "children",
           "type": "ReactNode | ((state: FileUploadRenderState) => ReactNode)",
           "required": false,
-          "description": "Replaces the prompt and hint inside the dropzone. A function receives\r\n`{ dragging, disabled, openPicker }`. The Browse button is always rendered."
+          "description": "Replaces the prompt and hint inside the dropzone. A function receives\n`{ dragging, disabled, openPicker }`. The Browse button is always rendered."
         },
         {
           "name": "prompt",
@@ -8378,7 +8397,7 @@
           "name": "hint",
           "type": "ReactNode",
           "required": false,
-          "description": "Hint under the prompt. Defaults to text built from `accept`, `maxSize`,\r\nand `maxFiles` (e.g. \"PNG, JPG up to 5 MB each. Up to 3 files.\"). Pass\r\n`null` to hide. It is wired to the Browse button with `aria-describedby`."
+          "description": "Hint under the prompt. Defaults to text built from `accept`, `maxSize`,\nand `maxFiles` (e.g. \"PNG, JPG up to 5 MB each. Up to 3 files.\"). Pass\n`null` to hide. It is wired to the Browse button with `aria-describedby`."
         },
         {
           "name": "browseLabel",
@@ -8437,7 +8456,7 @@
         {
           "name": "FileUpload.List",
           "exportedAs": "FileUploadList",
-          "description": "The list of selected files: icon or image thumbnail, name (truncated, full\r\nname on hover and focus), formatted size, optional upload progress and\r\nstatus, and a remove button per file. `FileUpload` renders one for you;\r\nuse `FileUpload.List` directly for custom layouts.\r\n\r\nAfter a removal, focus moves to the next item's remove button (or the\r\nprevious one), then to `focusFallback` when the list becomes empty.\r\nUpload completions and failures are announced in a polite live region.",
+          "description": "The list of selected files: icon or image thumbnail, name (truncated, full\nname on hover and focus), formatted size, optional upload progress and\nstatus, and a remove button per file. `FileUpload` renders one for you;\nuse `FileUpload.List` directly for custom layouts.\n\nAfter a removal, focus moves to the next item's remove button (or the\nprevious one), then to `focusFallback` when the list becomes empty.\nUpload completions and failures are announced in a polite live region.",
           "nativeElement": "ul",
           "props": [
             {
@@ -8490,7 +8509,7 @@
               "name": "focusFallback",
               "type": "() => HTMLElement | null | undefined",
               "required": false,
-              "description": "Element to focus after the last file is removed (for example the Browse\r\nbutton). Otherwise focus moves to the next item's remove button, or the\r\nprevious one when the last item was removed."
+              "description": "Element to focus after the last file is removed (for example the Browse\nbutton). Otherwise focus moves to the next item's remove button, or the\nprevious one when the last item was removed."
             },
             {
               "name": "size",
@@ -8750,7 +8769,7 @@
       "category": "forms",
       "folder": "NumberInput",
       "import": "import { NumberInput } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "A numeric text field following the WAI-ARIA spinbutton pattern. The\r\n`<input>` itself is the spinbutton: it takes focus, exposes\r\n`aria-valuenow`/`min`/`max`/`valuetext`, and handles ArrowUp/Down,\r\nPageUp/Down, Home/End, and Enter. Stepper buttons are pointer\r\nconveniences (press and hold to repeat) and stay out of the tab order.\r\n\r\nShows a formatted value (`Intl.NumberFormat`) when not focused and the\r\nplain editable number while focused; parses locale input (group\r\nseparators, decimal comma). Built on `Input`, so size, variant, radius,\r\naddons, and `Field` wiring match every other text field.\r\n\r\n```tsx\r\n<Field label=\"Weight\">\r\n  <NumberInput min={0} step={2.5} endAddon=\"kg\" defaultValue={60} />\r\n</Field>\r\n```",
+      "description": "A numeric text field following the WAI-ARIA spinbutton pattern. The\n`<input>` itself is the spinbutton: it takes focus, exposes\n`aria-valuenow`/`min`/`max`/`valuetext`, and handles ArrowUp/Down,\nPageUp/Down, Home/End, and Enter. Stepper buttons are pointer\nconveniences (press and hold to repeat) and stay out of the tab order.\n\nShows a formatted value (`Intl.NumberFormat`) when not focused and the\nplain editable number while focused; parses locale input (group\nseparators, decimal comma). Built on `Input`, so size, variant, radius,\naddons, and `Field` wiring match every other text field.\n\n```tsx\n<Field label=\"Weight\">\n  <NumberInput min={0} step={2.5} endAddon=\"kg\" defaultValue={60} />\n</Field>\n```",
       "nativeElement": "input",
       "props": [
         {
@@ -8917,7 +8936,7 @@
           "name": "precision",
           "type": "number",
           "required": false,
-          "description": "Fixed number of decimal places. Committed values are rounded to it and\r\nthe display shows exactly this many digits (unless `formatOptions` says\r\notherwise). When omitted, the step's decimals are used for stepping."
+          "description": "Fixed number of decimal places. Committed values are rounded to it and\nthe display shows exactly this many digits (unless `formatOptions` says\notherwise). When omitted, the step's decimals are used for stepping."
         },
         {
           "name": "clampOnBlur",
@@ -8944,7 +8963,7 @@
           "name": "formatOptions",
           "type": "Intl.NumberFormatOptions",
           "required": false,
-          "description": "`Intl.NumberFormat` options for the value shown while the field is not\r\nfocused (e.g. `{ style: \"currency\", currency: \"USD\" }` or\r\n`{ style: \"unit\", unit: \"percent\" }`). While focused the field shows the\r\nplain editable number. Note `style: \"percent\"` shows 0.45 as \"45%\";\r\nuse `style: \"unit\", unit: \"percent\"` to show 45 as \"45%\"."
+          "description": "`Intl.NumberFormat` options for the value shown while the field is not\nfocused (e.g. `{ style: \"currency\", currency: \"USD\" }` or\n`{ style: \"unit\", unit: \"percent\" }`). While focused the field shows the\nplain editable number. Note `style: \"percent\"` shows 0.45 as \"45%\";\nuse `style: \"unit\", unit: \"percent\"` to show 45 as \"45%\"."
         },
         {
           "name": "locale",
@@ -15312,7 +15331,7 @@
       "category": "navigation",
       "folder": "Navbar",
       "import": "import { Navbar } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "The top header of an app or site. Renders a `<header>` (a `banner`\r\nlandmark when it isn't inside `main`, `article`, `aside`, `nav`, or\r\n`section`) with brand, navigation, and actions. Below `collapseBelow`\r\nthe navigation moves into a modal drawer opened by a menu button.\r\n\r\n```tsx\r\n<Navbar>\r\n  <Navbar.Brand href=\"/\">Hoops</Navbar.Brand>\r\n  <Navbar.Nav>\r\n    <Navbar.Link href=\"/\" active>Home</Navbar.Link>\r\n    <Navbar.Link href=\"/teams\">Teams</Navbar.Link>\r\n  </Navbar.Nav>\r\n  <Navbar.Actions>\r\n    <Button size=\"sm\">Sign in</Button>\r\n  </Navbar.Actions>\r\n</Navbar>\r\n```",
+      "description": "The top header of an app or site. Renders a `<header>` (a `banner`\nlandmark when it isn't inside `main`, `article`, `aside`, `nav`, or\n`section`) with brand, navigation, and actions. Below `collapseBelow`\nthe navigation moves into a modal drawer opened by a menu button.\n\n```tsx\n<Navbar>\n  <Navbar.Brand href=\"/\">Hoops</Navbar.Brand>\n  <Navbar.Nav>\n    <Navbar.Link href=\"/\" active>Home</Navbar.Link>\n    <Navbar.Link href=\"/teams\">Teams</Navbar.Link>\n  </Navbar.Nav>\n  <Navbar.Actions>\n    <Button size=\"sm\">Sign in</Button>\n  </Navbar.Actions>\n</Navbar>\n```",
       "nativeElement": "header",
       "props": [
         {
@@ -15347,7 +15366,7 @@
           "type": "boolean",
           "required": false,
           "default": "true",
-          "description": "Keeps focused and scrolled-to content clear of a `sticky` or `fixed`\r\nbar (WCAG 2.4.11): while mounted, sets `scroll-padding-top` on the bar's\r\nscroll container to the bar's height, and restores it on unmount. Set\r\n`false` to manage it yourself, e.g. `html { scroll-padding-top:\r\nvar(--header-height) }` (the md bar's height). Inside the bar,\r\n`--navbar-height` holds its height."
+          "description": "Keeps focused and scrolled-to content clear of a `sticky` or `fixed`\nbar (WCAG 2.4.11): while mounted, sets `scroll-padding-top` on the bar's\nscroll container to the bar's height, and restores it on unmount. Set\n`false` to manage it yourself, e.g. `html { scroll-padding-top:\nvar(--header-height) }` (the md bar's height). Inside the bar,\n`--navbar-height` holds its height."
         },
         {
           "name": "bordered",
@@ -15368,14 +15387,14 @@
           "type": "boolean",
           "required": false,
           "default": "false",
-          "description": "Shows the soft shadow only once the window has scrolled (a passive,\r\nframe-throttled listener). A `transparent` bar also fills with the\r\nsurface color so links stay readable over content."
+          "description": "Shows the soft shadow only once the window has scrolled (a passive,\nframe-throttled listener). A `transparent` bar also fills with the\nsurface color so links stay readable over content."
         },
         {
           "name": "contained",
           "type": "boolean",
           "required": false,
           "default": "true",
-          "description": "Centers the content in a max-width `Container` with responsive gutters.\r\nWhen `false`, the content spans the full width (gutters are kept). To\r\ncompose your own layout instead, set `contained={false}`."
+          "description": "Centers the content in a max-width `Container` with responsive gutters.\nWhen `false`, the content spans the full width (gutters are kept). To\ncompose your own layout instead, set `contained={false}`."
         },
         {
           "name": "maxWidth",
@@ -15389,7 +15408,7 @@
           "type": "NavbarCollapseBreakpoint",
           "required": false,
           "default": "\"md\"",
-          "description": "Below this breakpoint (sm 640px, md 768px, lg 1024px), `Navbar.Nav`\r\nis hidden and a menu button opens the links in a drawer instead."
+          "description": "Below this breakpoint (sm 640px, md 768px, lg 1024px), `Navbar.Nav`\nis hidden and a menu button opens the links in a drawer instead."
         },
         {
           "name": "open",
@@ -15436,7 +15455,7 @@
           "type": "NavbarActiveTone",
           "required": false,
           "default": "\"accent\"",
-          "description": "Color of the active link's pill and indicator bar, in the bar and the\r\nmobile menu: `accent` (the theme's accent), `primary` (the brand color), or\r\n`neutral`. The `solid` variant always marks the active link with the\r\non-primary color."
+          "description": "Color of the active link's pill and indicator bar, in the bar and the\nmobile menu: `accent` (the theme's accent), `primary` (the brand color), or\n`neutral`. The `solid` variant always marks the active link with the\non-primary color."
         }
       ],
       "subcomponents": [
@@ -15449,7 +15468,7 @@
               "name": "as",
               "type": "C",
               "required": false,
-              "description": "Component or element to render. Defaults to `a` when `href` is set,\r\notherwise `div`. Pass a router link (e.g. React Router or Next.js `Link`)\r\nand its props (such as `to`) are accepted; it must forward `className`\r\nand ARIA props to its `<a>`."
+              "description": "Component or element to render. Defaults to `a` when `href` is set,\notherwise `div`. Pass a router link (e.g. React Router or Next.js `Link`)\nand its props (such as `to`) are accepted; it must forward `className`\nand ARIA props to its `<a>`."
             },
             {
               "name": "children",
@@ -15462,7 +15481,7 @@
         {
           "name": "Navbar.Nav",
           "exportedAs": "NavbarNav",
-          "description": "The primary links: a `<nav>` landmark around a `<ul>`. Above the\r\n`collapseBelow` breakpoint they sit in the bar; below it they are hidden\r\n(`display: none`) and the same links render vertically in a drawer that the\r\nmenu button opens. Only one copy is ever exposed to assistive technology.\r\n\r\nOther props go on the inline `<nav>` only. The drawer copy gets the same\r\n`aria-label` / `aria-labelledby`.",
+          "description": "The primary links: a `<nav>` landmark around a `<ul>`. Above the\n`collapseBelow` breakpoint they sit in the bar; below it they are hidden\n(`display: none`) and the same links render vertically in a drawer that the\nmenu button opens. Only one copy is ever exposed to assistive technology.\n\nOther props go on the inline `<nav>` only. The drawer copy gets the same\n`aria-label` / `aria-labelledby`.",
           "nativeElement": "nav",
           "props": [
             {
@@ -15476,14 +15495,14 @@
               "type": "NavbarNavAlign",
               "required": false,
               "default": "\"start\"",
-              "description": "Where the links sit in the bar, between the brand and the actions:\r\n`start` (next to the brand; left in left-to-right layouts), `center`,\r\nor `end` (next to the actions; right in left-to-right layouts). Logical,\r\nso it flips in right-to-left layouts. The mobile drawer always lists\r\nthem vertically."
+              "description": "Where the links sit in the bar, between the brand and the actions:\n`start` (next to the brand; left in left-to-right layouts), `center`,\nor `end` (next to the actions; right in left-to-right layouts). Logical,\nso it flips in right-to-left layouts. The mobile drawer always lists\nthem vertically."
             },
             {
               "name": "gap",
               "type": "Responsive<Space>",
               "required": false,
               "default": "1",
-              "description": "Space between the links in the bar, as a spacing step (`4` is\r\n`--space-4`, 16px). Accepts one value or one per breakpoint, e.g.\r\n`{ base: 2, xl: 6 }`. The mobile drawer keeps its own vertical spacing."
+              "description": "Space between the links in the bar, as a spacing step (`4` is\n`--space-4`, 16px). Accepts one value or one per breakpoint, e.g.\n`{ base: 2, xl: 6 }`. The mobile drawer keeps its own vertical spacing."
             },
             {
               "name": "aria-label",
@@ -15497,7 +15516,7 @@
         {
           "name": "Navbar.Item",
           "exportedAs": "NavbarItem",
-          "description": "A list item in `Navbar.Nav`. `Navbar.Link` adds its own `<li>`, so you\r\nonly need this to wrap something else, to put props on the `<li>`, or to\r\nshow an item only in the bar or only in the drawer (`showIn`). A `ref`\r\nattaches to the bar's copy.",
+          "description": "A list item in `Navbar.Nav`. `Navbar.Link` adds its own `<li>`, so you\nonly need this to wrap something else, to put props on the `<li>`, or to\nshow an item only in the bar or only in the drawer (`showIn`). A `ref`\nattaches to the bar's copy.",
           "nativeElement": "li",
           "props": [
             {
@@ -15511,27 +15530,27 @@
               "type": "NavbarItemShowIn",
               "required": false,
               "default": "\"both\"",
-              "description": "Where the item appears. `Navbar.Nav` renders its children twice (in the\r\nbar and in the drawer), so a stateful child (a Menu, a toggle) is\r\nmounted twice and its drawer copy resets each time the drawer opens.\r\nShow such an item in one place only, or put it in `Navbar.Actions`."
+              "description": "Where the item appears. `Navbar.Nav` renders its children twice (in the\nbar and in the drawer), so a stateful child (a Menu, a toggle) is\nmounted twice and its drawer copy resets each time the drawer opens.\nShow such an item in one place only, or put it in `Navbar.Actions`."
             }
           ]
         },
         {
           "name": "Navbar.Link",
           "exportedAs": "NavbarLink",
-          "description": "A primary navigation link. Wraps itself in an `<li>` unless it's already\r\ninside `Navbar.Item`. In the mobile drawer, clicking it closes the drawer\r\n(even if a router prevents the default navigation).\r\n\r\nIt renders once in the bar and once in the drawer (only one is ever\r\nexposed), so don't give it an `id`. A `ref` attaches to the bar's copy.",
+          "description": "A primary navigation link. Wraps itself in an `<li>` unless it's already\ninside `Navbar.Item`. In the mobile drawer, clicking it closes the drawer\n(even if a router prevents the default navigation).\n\nIt renders once in the bar and once in the drawer (only one is ever\nexposed), so don't give it an `id`. A `ref` attaches to the bar's copy.",
           "props": [
             {
               "name": "as",
               "type": "C",
               "required": false,
-              "description": "Component or element to render. Defaults to `a`. Pass a router link\r\n(e.g. React Router or Next.js `Link`) and its props (such as `to`) are\r\naccepted and typed. It must forward `className`, `onClick`, and ARIA\r\nprops to its `<a>`."
+              "description": "Component or element to render. Defaults to `a`. Pass a router link\n(e.g. React Router or Next.js `Link`) and its props (such as `to`) are\naccepted and typed. It must forward `className`, `onClick`, and ARIA\nprops to its `<a>`."
             },
             {
               "name": "active",
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Marks the link as the current page: sets `aria-current=\"page\"` and shows\r\na filled pill with an indicator bar, so the state never relies on color\r\nalone."
+              "description": "Marks the link as the current page: sets `aria-current=\"page\"` and shows\na filled pill with an indicator bar, so the state never relies on color\nalone."
             },
             {
               "name": "icon",
@@ -15539,6 +15558,24 @@
               "required": false,
               "description": "Decorative icon before the label. Hidden from assistive technology."
             },
+            {
+              "name": "badge",
+              "type": "NavbarBadgeValue",
+              "required": false,
+              "description": "A count (rendered with `Badge` `count`, capped at 99+, hidden at 0) or a\nshort text such as \"New\", after the label. It's part of the link's name\n(\"Messages 3\"), in the bar and the mobile menu."
+            },
+            {
+              "name": "badgeLabel",
+              "type": "string",
+              "required": false,
+              "description": "Screen-reader text for the badge, e.g. \"3 unread messages\". Replaces the visible badge text in the accessible name."
+            },
+            {
+              "name": "badgeTone",
+              "type": "Tone",
+              "required": false,
+              "description": "Badge color. By default `accent`, except in the `solid` bar, where the\nbadge takes the bar's own colors swapped (a `Badge` `variant=\"inverse\"`)\nso it stands out from the bar in both themes. Setting it always gives a\nsolid badge in that tone."
+            },
             {
               "name": "children",
               "type": "ReactNode",
@@ -15547,6 +15584,83 @@
             }
           ]
         },
+        {
+          "name": "Navbar.Group",
+          "exportedAs": "NavbarGroup",
+          "description": "A group of links under one button, following the WAI-ARIA disclosure\nnavigation pattern (not a `menu`): the button has `aria-expanded`, and the\nlinks stay ordinary links in the Tab order.\n\n- In the bar: the button opens a dropdown below it. Escape closes it and\n  returns focus to the button; so do a press outside, Tab moving focus out\n  of the group, and activating a link. Opening one group closes the others.\n- In the mobile menu: an expandable section with the links indented below.",
+          "nativeElement": "li",
+          "props": [
+            {
+              "name": "label",
+              "type": "ReactNode",
+              "required": true,
+              "description": "The group button's visible label, and its accessible name."
+            },
+            {
+              "name": "icon",
+              "type": "ReactNode",
+              "required": false,
+              "description": "Decorative icon before the label."
+            },
+            {
+              "name": "children",
+              "type": "ReactNode",
+              "required": false,
+              "description": "The group's `Navbar.Link`s."
+            },
+            {
+              "name": "active",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "One of the group's links is the current page. The button then shows the\nactive look (it doesn't set `aria-current`; the link does), and the\ngroup starts open in the mobile menu."
+            },
+            {
+              "name": "badge",
+              "type": "NavbarBadgeValue",
+              "required": false,
+              "description": "A count or short text on the group button, like `Navbar.Link`'s `badge`."
+            },
+            {
+              "name": "badgeLabel",
+              "type": "string",
+              "required": false,
+              "description": "Screen-reader text for the badge."
+            },
+            {
+              "name": "badgeTone",
+              "type": "Tone",
+              "required": false,
+              "description": "Badge color. Same default as `Navbar.Link`'s `badgeTone` (inverse on the solid bar)."
+            },
+            {
+              "name": "open",
+              "type": "boolean",
+              "required": false,
+              "description": "Controlled open state of the dropdown in the bar."
+            },
+            {
+              "name": "defaultOpen",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Initial open state of the dropdown when uncontrolled."
+            },
+            {
+              "name": "onOpenChange",
+              "type": "(open: boolean) => void",
+              "required": false,
+              "description": "Called with the next open state of the dropdown in the bar."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Disables the group button."
+            }
+          ]
+        },
         {
           "name": "Navbar.Actions",
           "exportedAs": "NavbarActions",
@@ -15596,9 +15710,29 @@
           "name": "Active Link",
           "description": "`active` sets `aria-current=\"page\"` and draws an accent-tinted pill with an\r\nindicator bar, so the current page is marked by shape as well as color.\r\nLinks can carry a decorative `icon`."
         },
+        {
+          "name": "Link Badges",
+          "description": "`badge` on `Navbar.Link` (and `Navbar.Group`) shows a count or short text\r\nafter the label, in the bar and the mobile menu. `badgeLabel` gives screen\r\nreaders the full meaning (\"Messages, 3 unread messages\"). On the solid bar,\r\na badge without a `badgeTone` swaps the bar's colors (`Badge`\r\n`variant=\"inverse\"`), so it stands out in both themes."
+        },
+        {
+          "name": "Link Groups",
+          "description": "`Navbar.Group` puts links under one button (the WAI-ARIA disclosure\r\nnavigation pattern, not a menu). The button opens a dropdown; Escape, a\r\npress outside, Tab moving out, or choosing a link closes it, and opening\r\none group closes the other. `active` marks the group holding the current page."
+        },
+        {
+          "name": "Link group, last on the page",
+          "description": "A group as the last focusable thing on the page: Tab past its last link\r\nleaves the page, and the dropdown still closes. A press on the panel's\r\npadding (nothing focusable) keeps it open."
+        },
+        {
+          "name": "Link Groups Mobile",
+          "description": "In the mobile menu, a group is an expandable section; the one holding the current page starts open."
+        },
+        {
+          "name": "Link Groups Right To Left",
+          "description": "Right-to-left: the dropdown lines up with the button's right edge."
+        },
         {
           "name": "Mobile",
-          "description": "On a phone-sized viewport the links collapse into a menu button\r\n(\"Open menu\", with `aria-expanded` and `aria-controls`) that opens them\r\nin a drawer. The inline nav is `display: none`, so only one \"Main\"\r\nnavigation is ever exposed. Choosing a link closes the drawer."
+          "description": ""
         },
         {
           "name": "Mobile Solid",
@@ -18625,19 +18759,19 @@
       "category": "overlays",
       "folder": "Tooltip",
       "import": "import { Tooltip } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "A short, non-interactive label or description that appears on hover and on\r\nkeyboard focus. Follows the WAI-ARIA tooltip pattern and WCAG 1.4.13: it\r\ncan be dismissed with Escape, the pointer can move onto it, and it stays\r\nopen until the pointer or focus leaves. Use `Popover` for interactive content.",
+      "description": "A short, non-interactive label or description that appears on hover and on\nkeyboard focus. Follows the WAI-ARIA tooltip pattern and WCAG 1.4.13: it\ncan be dismissed with Escape, the pointer can move onto it, and it stays\nopen until the pointer or focus leaves. Use `Popover` for interactive content.",
       "props": [
         {
           "name": "children",
           "type": "ReactElement",
           "required": true,
-          "description": "The trigger: exactly one focusable element (a `Button`, `IconButton`,\r\nlink, or input) that accepts a `ref`, event handlers, and `aria-*` props.\r\nIts existing handlers, ref, and `aria-describedby` / `aria-labelledby` are kept.\r\n\r\nDisabled elements fire no pointer or focus events, so a `disabled` button\r\nnever shows a tooltip. Don't wrap it in a focusable `<span>`; use\r\n`aria-disabled=\"true\"` on the button instead (and ignore its clicks), so\r\nit stays focusable and the tooltip can explain why it's unavailable."
+          "description": "The trigger: exactly one focusable element (a `Button`, `IconButton`,\nlink, or input) that accepts a `ref`, event handlers, and `aria-*` props.\nIts existing handlers, ref, and `aria-describedby` / `aria-labelledby` are kept.\n\nDisabled elements fire no pointer or focus events, so a `disabled` button\nnever shows a tooltip. Don't wrap it in a focusable `<span>`; use\n`aria-disabled=\"true\"` on the button instead (and ignore its clicks), so\nit stays focusable and the tooltip can explain why it's unavailable."
         },
         {
           "name": "content",
           "type": "ReactNode",
           "required": true,
-          "description": "Short, plain text describing or naming the trigger. Never put interactive\r\ncontent (links, buttons, inputs) here: a tooltip can't receive focus.\r\nUse a Popover for that. A dev-mode warning fires if focusable content is found."
+          "description": "Short, plain text describing or naming the trigger. Never put interactive\ncontent (links, buttons, inputs) here: a tooltip can't receive focus.\nUse a Popover for that. A dev-mode warning fires if focusable content is found."
         },
         {
           "name": "shortcut",
@@ -18650,7 +18784,7 @@
           "type": "TooltipPlacement",
           "required": false,
           "default": "\"top\"",
-          "description": "Preferred side and alignment, or a logical `start` / `end` side that\r\nfollows the text direction. Flips to the opposite side when there isn't\r\nroom."
+          "description": "Preferred side and alignment, or a logical `start` / `end` side that\nfollows the text direction. Flips to the opposite side when there isn't\nroom."
         },
         {
           "name": "offset",
@@ -18791,7 +18925,7 @@
       "category": "overlays",
       "folder": "Tooltip",
       "import": "import { TooltipProvider } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "Optional. Sets shared timing for the tooltips inside it. Tooltips work\r\nwithout a provider, using the defaults.",
+      "description": "Optional. Sets shared timing for the tooltips inside it. Tooltips work\nwithout a provider, using the defaults.",
       "props": [
         {
           "name": "delay",
@@ -18812,7 +18946,7 @@
           "type": "number",
           "required": false,
           "default": "300",
-          "description": "After a tooltip closes, other tooltips open instantly (no `delay`) for this\r\nmany ms, so scanning across a toolbar feels immediate. `0` turns it off."
+          "description": "After a tooltip closes, other tooltips open instantly (no `delay`) for this\nmany ms, so scanning across a toolbar feels immediate. `0` turns it off."
         },
         {
           "name": "children",
@@ -20451,6 +20585,12 @@
       "description": "A `keydown` handler for one element (an editor, a list): pass it to\n`onKeyDown`. Same shortcut format as `useHotkeys`; shortcuts fire while\ntyping in that element.\n\n```tsx\n<Textarea onKeyDown={getHotkeyHandler([[\"mod+enter\", send]])} />\n```",
       "module": "hooks/index.ts"
     },
+    {
+      "name": "withExtraItems",
+      "signature": "withExtraItems(virtualizer: Virtualizer, extra: readonly number[]): VirtualItem[]",
+      "description": "The window's items plus extra indices that must stay rendered even when\nscrolled out of view (a focused row, a highlighted option), in order.\nRender spacers between non-adjacent items from their `start` / `end`.",
+      "module": "hooks/index.ts"
+    },
     {
       "name": "cx",
       "signature": "cx(...classes: Array<string | false | null | undefined>): string",