@vjdesigns/vjdesigns-ui 2.3.0 → 2.5.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 VJDesigns
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -82,6 +82,50 @@ export function SignupForm() {
 }
 ```
 
+### Next.js (App Router) and React Server Components
+
+The 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.
+
+Put the providers in a small client file of your own, and render it from the root layout:
+
+```tsx
+// app/providers.tsx
+"use client";
+import { LocaleProvider, ToastProvider } from "@vjdesigns/vjdesigns-ui";
+import es from "@vjdesigns/vjdesigns-ui/locales/es";
+import type { ReactNode } from "react";
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <LocaleProvider locale="es" messages={es}>
+      <ToastProvider>{children}</ToastProvider>
+    </LocaleProvider>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx (a Server Component)
+import "@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css";
+import { getLocaleDirection } from "@vjdesigns/vjdesigns-ui";
+import { Providers } from "./providers";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="es" dir={getLocaleDirection("es")}>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+Two rules of Server Components to keep in mind:
+
+- **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.
+- **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`, ...).
+
 ### 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.
@@ -778,4 +822,4 @@ See [RELEASING.md](RELEASING.md) for the full process, including how to update t
 
 ## License
 
-ISC
+[ISC](LICENSE) © 2026 VJDesigns. The Pro package (`pro/`) has its own commercial license.

package/dist/ai/llms-full.txt

@@ -1,4 +1,4 @@
-# @vjdesigns/vjdesigns-ui 2.2.0: full reference
+# @vjdesigns/vjdesigns-ui 2.4.0: full reference
 
 > Accessible React 19 component library: WCAG 2.2 AA verified (axe on every story, a contrast check on every color pair), 31 languages with right-to-left support, themeable with any brand color (auto-adjusted to stay accessible), tree-shakable, no runtime dependencies besides React.
 
@@ -83,6 +83,50 @@ export function SignupForm() {
 }
 ```
 
+### Next.js (App Router) and React Server Components
+
+The 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.
+
+Put the providers in a small client file of your own, and render it from the root layout:
+
+```tsx
+// app/providers.tsx
+"use client";
+import { LocaleProvider, ToastProvider } from "@vjdesigns/vjdesigns-ui";
+import es from "@vjdesigns/vjdesigns-ui/locales/es";
+import type { ReactNode } from "react";
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <LocaleProvider locale="es" messages={es}>
+      <ToastProvider>{children}</ToastProvider>
+    </LocaleProvider>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx (a Server Component)
+import "@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css";
+import { getLocaleDirection } from "@vjdesigns/vjdesigns-ui";
+import { Providers } from "./providers";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="es" dir={getLocaleDirection("es")}>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+Two rules of Server Components to keep in mind:
+
+- **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.
+- **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`, ...).
+
 ### 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.
@@ -607,8 +651,8 @@ import { Avatar } from "@vjdesigns/vjdesigns-ui";
 
 Category: data-display · Storybook: Data Display/Avatar
 
-A person's photo (`src`), with a fallback chain of image, initials (from
-`name`), then a user icon, so it always shows something. Supports a border,
+A person's photo (`src`), with a fallback chain of image, initials (from
+`name`), then a user icon, so it always shows something. Supports a border,
 a presence status dot, a highlight ring, and stacking in an `AvatarGroup`.
 
 ### Props
@@ -655,7 +699,7 @@ import { AvatarGroup } from "@vjdesigns/vjdesigns-ui";
 
 Category: data-display · Storybook: Data Display/Avatar
 
-Overlapping stack of avatars in a labelled `role="group"`. Avatars beyond
+Overlapping stack of avatars in a labelled `role="group"`. Avatars beyond
 `max` collapse into a "+N" surplus avatar with an accessible label.
 
 ### Props
@@ -711,6 +755,7 @@ Renders a `<span>` with no role. For counts, pass `label` (e.g.
 - Counts
 - Anchored
 - In text
+- Inverse: `inverse` swaps the solid colors, for a badge on a solid tone surface: a solid Navbar, a Banner, a primary card.
 - On surfaces (both themes)
 
 ## BadgeAnchor
@@ -1232,6 +1277,7 @@ real `<table role="grid">` with `aria-sort`, `aria-selected`,
 - `onSelectedChange`: `(selected: DataGridRowId[]) => void`. Called with the next selected ids.
 - `isRowSelectable`: `(row: T) => boolean`. Rows that can't be selected (their checkbox is disabled).
 - `pageSize`: `number`. Rows per page. Shows a footer with the range and `Pagination`. Without it, every row shows.
+- `virtualize`: `boolean | "auto"` (default "auto"). Render only the rows in view (plus a few above and below), so grids of 100,000+ rows scroll, sort, filter, and select without delay. `"auto"` turns it on when more than 100 rows show at once. While it's on, the body scrolls inside the grid (its height is `maxHeight`, 70% of the window by default) and the table uses fixed layout unless you set `layout`, so columns keep their widths while you scroll; give columns a `width` to size them. Screen readers still get the full count (`aria-rowcount`) and each row's position (`aria-rowindex`).
 - `page`: `number`. Current page, starting at 1 (controlled).
 - `defaultPage`: `number` (default 1). Initial page when uncontrolled.
 - `onPageChange`: `(page: number) => void`. Called with the next page.
@@ -1245,7 +1291,7 @@ real `<table role="grid">` with `aria-sort`, `aria-selected`,
 - `hoverable`: `boolean` (default true). Highlight rows under the pointer.
 - `stickyHeader`: `boolean` (default true). Keep the header row visible while scrolling.
 - `maxHeight`: `CSSProperties["maxHeight"]`. Maximum height of the scrolling body (CSS length, or px as a number).
-- `layout`: `"auto" | "fixed"` (default "auto"). Table layout. `fixed` makes column widths exact (content wraps or clips instead of widening a column).
+- `layout`: `"auto" | "fixed"` (default "auto" ("fixed" while virtualized)). Table layout. `fixed` makes column widths exact (content wraps or clips instead of widening a column).
 - `tableStyle`: `CSSProperties`. Style for the `<table>` (for example a total width when columns are resized).
 - `className`: `string`. Class name for the outer frame.
 - `style`: `CSSProperties`. Style for the outer frame.
@@ -1264,6 +1310,7 @@ real `<table role="grid">` with `aria-sort`, `aria-selected`,
 - Sticky Header: A long list in a fixed-height area, with the header kept in view.
 - Right To Left: In right-to-left layouts the columns mirror and ArrowRight moves toward the start.
 - Extending Columns: Extending columns: `headerEnd` adds content after a header's label, outside its sort button (here a column menu button), and `className` / `style` reach every cell of a column. Controls marked `data-grid-secondary` don't steal the header's focus: the sort button stays its target, and F2 then Tab reaches them.
+- Large data (100,000 rows): 100,000 rows with sorting, search, and selection. Only the rows in view (plus a few above and below) are in the page, so scrolling, sorting, filtering, and selecting stay instant at any size. Screen readers still hear the full count (`aria-rowcount`) and each row's position.
 
 ## EmptyState
 
@@ -1384,19 +1431,19 @@ import { List } from "@vjdesigns/vjdesigns-ui";
 
 Category: data-display · Storybook: Data Display/List
 
-A semantic list (`<ul>` or `<ol>`) with styled markers and rich items.
-
-Every variant draws its own markers, so the browser's markers are removed
-with CSS; `role="list"` is added so Safari and VoiceOver keep announcing
-the list and its item count.
-
-This is a list, not a listbox: items are not selectable options and there
-is no roving focus. Interactive items (`List.ItemButton`, `List.ItemLink`)
-are ordinary Tab stops. For choosing among options, use a Listbox,
-Combobox, or Select instead.
-
-Grouping: put a `List.Subheader` (a real heading by default) before each
-list and point the list at it with `aria-labelledby`, so screen readers
+A semantic list (`<ul>` or `<ol>`) with styled markers and rich items.
+
+Every variant draws its own markers, so the browser's markers are removed
+with CSS; `role="list"` is added so Safari and VoiceOver keep announcing
+the list and its item count.
+
+This is a list, not a listbox: items are not selectable options and there
+is no roving focus. Interactive items (`List.ItemButton`, `List.ItemLink`)
+are ordinary Tab stops. For choosing among options, use a Listbox,
+Combobox, or Select instead.
+
+Grouping: put a `List.Subheader` (a real heading by default) before each
+list and point the list at it with `aria-labelledby`, so screen readers
 announce "Account, list, 3 items".
 
 ### Props
@@ -1416,8 +1463,8 @@ announce "Account, list, 3 items".
 
 Also exported as `ListItem`.
 
-A static list item (`<li>`) with optional `start`, `title`, `description`,
-`meta`, and `end` slots, or plain `children`. For a clickable row, use
+A static list item (`<li>`) with optional `start`, `title`, `description`,
+`meta`, and `end` slots, or plain `children`. For a clickable row, use
 `List.ItemButton` or `List.ItemLink`.
 
 - `start`: `ReactNode`. Leading visual: an `Avatar`, an `Icon`, or a thumbnail.
@@ -1435,14 +1482,14 @@ A static list item (`<li>`) with optional `start`, `title`, `description`,
 
 Also exported as `ListItemButton`.
 
-A list item whose main area is a real `<button>`. The button wraps the
-title (or `children` when there is no title) and its hit area is
-stretched over the whole row, so the row is clickable, while `end`
-actions sit above it and stay independently clickable. Never nest
-interactive elements in `title` or `description`.
-
-`className` and `style` go on the row `<li>`; `ref`, `onClick`, `type`,
-`aria-*`, and every other prop go on the `<button>`. The description and
+A list item whose main area is a real `<button>`. The button wraps the
+title (or `children` when there is no title) and its hit area is
+stretched over the whole row, so the row is clickable, while `end`
+actions sit above it and stay independently clickable. Never nest
+interactive elements in `title` or `description`.
+
+`className` and `style` go on the row `<li>`; `ref`, `onClick`, `type`,
+`aria-*`, and every other prop go on the `<button>`. The description and
 meta become the button's accessible description.
 
 - `start`: `ReactNode`. Leading visual: an `Avatar`, an `Icon`, or a thumbnail.
@@ -1464,12 +1511,12 @@ meta become the button's accessible description.
 
 Also exported as `ListItemLink`.
 
-A list item whose main area is a real `<a>`, stretched over the whole row
-like `List.ItemButton`. `selected` sets `aria-current="page"` (override
-with `current`). When `disabled`, the link loses its `href` and is marked
-`aria-disabled`, so it can't be followed or focused.
-
-`className` and `style` go on the row `<li>`; everything else, including
+A list item whose main area is a real `<a>`, stretched over the whole row
+like `List.ItemButton`. `selected` sets `aria-current="page"` (override
+with `current`). When `disabled`, the link loses its `href` and is marked
+`aria-disabled`, so it can't be followed or focused.
+
+`className` and `style` go on the row `<li>`; everything else, including
 `ref` and `href`, goes on the `<a>`.
 
 - `start`: `ReactNode`. Leading visual: an `Avatar`, an `Icon`, or a thumbnail.
@@ -1491,14 +1538,14 @@ with `current`). When `disabled`, the link loses its `href` and is marked
 
 Also exported as `ListSubheader`.
 
-An uppercase label for a group of items. Render it before (outside) a
-`List`, give it an `id`, and pass that id to the list's
-`aria-labelledby`. It must not go inside the `<ul>`, where it would be
-counted as an item.
-
-```tsx
-<List.Subheader id="acct">Account</List.Subheader>
-<List aria-labelledby="acct">...</List>
+An uppercase label for a group of items. Render it before (outside) a
+`List`, give it an `id`, and pass that id to the list's
+`aria-labelledby`. It must not go inside the `<ul>`, where it would be
+counted as an item.
+
+```tsx
+<List.Subheader id="acct">Account</List.Subheader>
+<List aria-labelledby="acct">...</List>
 ```
 
 - `as`: `ListSubheaderElement` (default "h3"). Element to render. A heading (default `h3`) so grouped lists show up in the screen reader's headings list; pick the level that fits the page outline, or `div` when a heading would be out of place.
@@ -1635,7 +1682,7 @@ Semantic data table. See `TableRoot` docs above; parts are attached as `Table.*`
 
 Also exported as `TableCaption`.
 
-The table's title (`<caption>`). It names the table and, when the table
+The table's title (`<caption>`). It names the table and, when the table
 scrolls, its scroll region. Strongly recommended on every table.
 
 - Plus every native `<caption>` attribute.
@@ -1677,9 +1724,9 @@ A table row (`<tr>`).
 
 Also exported as `TableHeaderCell`.
 
-A header cell (`<th>`). With `sortable`, the whole cell is a real
-`<button>` and the header carries `aria-sort` while it is the sorted column.
-The sort icon shows the direction by shape (up arrow, down arrow, or a
+A header cell (`<th>`). With `sortable`, the whole cell is a real
+`<button>` and the header carries `aria-sort` while it is the sorted column.
+The sort icon shows the direction by shape (up arrow, down arrow, or a
 neutral double arrow), not by color alone.
 
 - `align`: `TableCellAlign` (default "start" ("end" when `numeric`)). Horizontal alignment.
@@ -1709,8 +1756,8 @@ A data cell (`<td>`).
 
 Also exported as `TableSelectCell`.
 
-A data cell holding the row's selection checkbox. Pair with `selected` on
-the `Table.Row`. Give it a `rowLabel` (or `checkboxLabel`) so each
+A data cell holding the row's selection checkbox. Pair with `selected` on
+the `Table.Row`. Give it a `rowLabel` (or `checkboxLabel`) so each
 checkbox has a unique accessible name.
 
 - `checked`: `boolean` (required). Whether the row is selected.
@@ -1724,7 +1771,7 @@ checkbox has a unique accessible name.
 
 Also exported as `TableSelectAllCell`.
 
-A header cell (`<th scope="col">`) with a "select all" checkbox. Shows the
+A header cell (`<th scope="col">`) with a "select all" checkbox. Shows the
 mixed state (`aria-checked="mixed"`) when some rows are selected.
 
 - `checked`: `boolean` (required). Whether every row is selected.
@@ -2799,6 +2846,7 @@ and size are wired automatically, as with `Input`.
 - Required: `required` blocks native form submission until an option is chosen (`setCustomValidity` on the text input).
 - Clear On Escape: `clearOnEscape`: once the text matches the selection, Escape also clears the selection.
 - Form submit, reset, and custom values: Form behavior: Enter submits what is shown (cleared text submits no team), a form reset restores the default, and re-entering a custom tag that's already chosen doesn't remove it.
+- Long list (10,000 options): 10,000 options. Only the options in view are in the page (plus the highlighted one), so opening, scrolling, and typing stay instant. Each option carries its position in the full list (`aria-setsize`, `aria-posinset`), so screen readers still hear "10,000 of 10,000". Lists with groups always render in full.
 
 ## DatePicker
 
@@ -3196,7 +3244,7 @@ import { FileUpload } from "@vjdesigns/vjdesigns-ui";
 
 Category: forms · Storybook: Forms/FileUpload
 
-File picker with drag and drop, validation, and a file list.
+File picker with drag and drop, validation, and a file list.
 `FileUpload.List` is the standalone list for custom layouts.
 
 ### Props
@@ -3235,13 +3283,13 @@ File picker with drag and drop, validation, and a file list.
 
 Also exported as `FileUploadList`.
 
-The list of selected files: icon or image thumbnail, name (truncated, full
-name on hover and focus), formatted size, optional upload progress and
-status, and a remove button per file. `FileUpload` renders one for you;
-use `FileUpload.List` directly for custom layouts.
-
-After a removal, focus moves to the next item's remove button (or the
-previous one), then to `focusFallback` when the list becomes empty.
+The list of selected files: icon or image thumbnail, name (truncated, full
+name on hover and focus), formatted size, optional upload progress and
+status, and a remove button per file. `FileUpload` renders one for you;
+use `FileUpload.List` directly for custom layouts.
+
+After a removal, focus moves to the next item's remove button (or the
+previous one), then to `focusFallback` when the list becomes empty.
 Upload completions and failures are announced in a polite live region.
 
 - `files`: `File[]` (required). The files to show.
@@ -3339,21 +3387,21 @@ import { NumberInput } from "@vjdesigns/vjdesigns-ui";
 
 Category: forms · Storybook: Forms/NumberInput
 
-A numeric text field following the WAI-ARIA spinbutton pattern. The
-`<input>` itself is the spinbutton: it takes focus, exposes
-`aria-valuenow`/`min`/`max`/`valuetext`, and handles ArrowUp/Down,
-PageUp/Down, Home/End, and Enter. Stepper buttons are pointer
-conveniences (press and hold to repeat) and stay out of the tab order.
-
-Shows a formatted value (`Intl.NumberFormat`) when not focused and the
-plain editable number while focused; parses locale input (group
-separators, decimal comma). Built on `Input`, so size, variant, radius,
-addons, and `Field` wiring match every other text field.
-
-```tsx
-<Field label="Weight">
-  <NumberInput min={0} step={2.5} endAddon="kg" defaultValue={60} />
-</Field>
+A numeric text field following the WAI-ARIA spinbutton pattern. The
+`<input>` itself is the spinbutton: it takes focus, exposes
+`aria-valuenow`/`min`/`max`/`valuetext`, and handles ArrowUp/Down,
+PageUp/Down, Home/End, and Enter. Stepper buttons are pointer
+conveniences (press and hold to repeat) and stay out of the tab order.
+
+Shows a formatted value (`Intl.NumberFormat`) when not focused and the
+plain editable number while focused; parses locale input (group
+separators, decimal comma). Built on `Input`, so size, variant, radius,
+addons, and `Field` wiring match every other text field.
+
+```tsx
+<Field label="Weight">
+  <NumberInput min={0} step={2.5} endAddon="kg" defaultValue={60} />
+</Field>
 ```
 
 ### Props
@@ -5452,22 +5500,22 @@ import { Navbar } from "@vjdesigns/vjdesigns-ui";
 
 Category: navigation · Storybook: Navigation/Navbar
 
-The top header of an app or site. Renders a `<header>` (a `banner`
-landmark when it isn't inside `main`, `article`, `aside`, `nav`, or
-`section`) with brand, navigation, and actions. Below `collapseBelow`
-the navigation moves into a modal drawer opened by a menu button.
-
-```tsx
-<Navbar>
-  <Navbar.Brand href="/">Hoops</Navbar.Brand>
-  <Navbar.Nav>
-    <Navbar.Link href="/" active>Home</Navbar.Link>
-    <Navbar.Link href="/teams">Teams</Navbar.Link>
-  </Navbar.Nav>
-  <Navbar.Actions>
-    <Button size="sm">Sign in</Button>
-  </Navbar.Actions>
-</Navbar>
+The top header of an app or site. Renders a `<header>` (a `banner`
+landmark when it isn't inside `main`, `article`, `aside`, `nav`, or
+`section`) with brand, navigation, and actions. Below `collapseBelow`
+the navigation moves into a modal drawer opened by a menu button.
+
+```tsx
+<Navbar>
+  <Navbar.Brand href="/">Hoops</Navbar.Brand>
+  <Navbar.Nav>
+    <Navbar.Link href="/" active>Home</Navbar.Link>
+    <Navbar.Link href="/teams">Teams</Navbar.Link>
+  </Navbar.Nav>
+  <Navbar.Actions>
+    <Button size="sm">Sign in</Button>
+  </Navbar.Actions>
+</Navbar>
 ```
 
 ### Props
@@ -5505,12 +5553,12 @@ The logo or product name at the start of the bar, usually a link home.
 
 Also exported as `NavbarNav`.
 
-The primary links: a `<nav>` landmark around a `<ul>`. Above the
-`collapseBelow` breakpoint they sit in the bar; below it they are hidden
-(`display: none`) and the same links render vertically in a drawer that the
-menu button opens. Only one copy is ever exposed to assistive technology.
-
-Other props go on the inline `<nav>` only. The drawer copy gets the same
+The primary links: a `<nav>` landmark around a `<ul>`. Above the
+`collapseBelow` breakpoint they sit in the bar; below it they are hidden
+(`display: none`) and the same links render vertically in a drawer that the
+menu button opens. Only one copy is ever exposed to assistive technology.
+
+Other props go on the inline `<nav>` only. The drawer copy gets the same
 `aria-label` / `aria-labelledby`.
 
 - `children`: `ReactNode`. `Navbar.Link`s (each is wrapped in an `<li>` for you) and/or `Navbar.Item`s.
@@ -5523,9 +5571,9 @@ Other props go on the inline `<nav>` only. The drawer copy gets the same
 
 Also exported as `NavbarItem`.
 
-A list item in `Navbar.Nav`. `Navbar.Link` adds its own `<li>`, so you
-only need this to wrap something else, to put props on the `<li>`, or to
-show an item only in the bar or only in the drawer (`showIn`). A `ref`
+A list item in `Navbar.Nav`. `Navbar.Link` adds its own `<li>`, so you
+only need this to wrap something else, to put props on the `<li>`, or to
+show an item only in the bar or only in the drawer (`showIn`). A `ref`
 attaches to the bar's copy.
 
 - `children`: `ReactNode`. A `Navbar.Link`, or any other control (e.g. a `Button`) that belongs in the list.
@@ -5536,18 +5584,47 @@ attaches to the bar's copy.
 
 Also exported as `NavbarLink`.
 
-A primary navigation link. Wraps itself in an `<li>` unless it's already
-inside `Navbar.Item`. In the mobile drawer, clicking it closes the drawer
-(even if a router prevents the default navigation).
-
-It renders once in the bar and once in the drawer (only one is ever
+A primary navigation link. Wraps itself in an `<li>` unless it's already
+inside `Navbar.Item`. In the mobile drawer, clicking it closes the drawer
+(even if a router prevents the default navigation).
+
+It renders once in the bar and once in the drawer (only one is ever
 exposed), so don't give it an `id`. A `ref` attaches to the bar's copy.
 
 - `as`: `C`. Component or element to render. Defaults to `a`. Pass a router link (e.g. React Router or Next.js `Link`) and its props (such as `to`) are accepted and typed. It must forward `className`, `onClick`, and ARIA props to its `<a>`.
 - `active`: `boolean` (default false). Marks the link as the current page: sets `aria-current="page"` and shows a filled pill with an indicator bar, so the state never relies on color alone.
 - `icon`: `ReactNode`. Decorative icon before the label. Hidden from assistive technology.
+- `badge`: `NavbarBadgeValue`. A count (rendered with `Badge` `count`, capped at 99+, hidden at 0) or a short text such as "New", after the label. It's part of the link's name ("Messages 3"), in the bar and the mobile menu.
+- `badgeLabel`: `string`. Screen-reader text for the badge, e.g. "3 unread messages". Replaces the visible badge text in the accessible name.
+- `badgeTone`: `Tone`. Badge color. By default `accent`, except in the `solid` bar, where the badge takes the bar's own colors swapped (a `Badge` `variant="inverse"`) so it stands out from the bar in both themes. Setting it always gives a solid badge in that tone.
 - `children`: `ReactNode`. The visible label.
 
+### Navbar.Group
+
+Also exported as `NavbarGroup`.
+
+A group of links under one button, following the WAI-ARIA disclosure
+navigation pattern (not a `menu`): the button has `aria-expanded`, and the
+links stay ordinary links in the Tab order.
+
+- In the bar: the button opens a dropdown below it. Escape closes it and
+  returns focus to the button; so do a press outside, Tab moving focus out
+  of the group, and activating a link. Opening one group closes the others.
+- In the mobile menu: an expandable section with the links indented below.
+
+- `label`: `ReactNode` (required). The group button's visible label, and its accessible name.
+- `icon`: `ReactNode`. Decorative icon before the label.
+- `children`: `ReactNode`. The group's `Navbar.Link`s.
+- `active`: `boolean` (default false). One of the group's links is the current page. The button then shows the active look (it doesn't set `aria-current`; the link does), and the group starts open in the mobile menu.
+- `badge`: `NavbarBadgeValue`. A count or short text on the group button, like `Navbar.Link`'s `badge`.
+- `badgeLabel`: `string`. Screen-reader text for the badge.
+- `badgeTone`: `Tone`. Badge color. Same default as `Navbar.Link`'s `badgeTone` (inverse on the solid bar).
+- `open`: `boolean`. Controlled open state of the dropdown in the bar.
+- `defaultOpen`: `boolean` (default false). Initial open state of the dropdown when uncontrolled.
+- `onOpenChange`: `(open: boolean) => void`. Called with the next open state of the dropdown in the bar.
+- `disabled`: `boolean` (default false). Disables the group button.
+- Plus every native `<li>` attribute.
+
 ### Navbar.Actions
 
 Also exported as `NavbarActions`.
@@ -5567,7 +5644,12 @@ The end of the bar: actions that stay visible at every width, before the menu bu
 - Sizes: `sm` 56px, `md` 64px, `lg` 80px tall. Links and the menu button scale with it.
 - With Actions: The actions area holds anything that should stay visible at every width.
 - Active Link: `active` sets `aria-current="page"` and draws an accent-tinted pill with an indicator bar, so the current page is marked by shape as well as color. Links can carry a decorative `icon`.
-- Mobile: On a phone-sized viewport the links collapse into a menu button ("Open menu", with `aria-expanded` and `aria-controls`) that opens them in a drawer. The inline nav is `display: none`, so only one "Main" navigation is ever exposed. Choosing a link closes the drawer.
+- Link Badges: `badge` on `Navbar.Link` (and `Navbar.Group`) shows a count or short text after the label, in the bar and the mobile menu. `badgeLabel` gives screen readers the full meaning ("Messages, 3 unread messages"). On the solid bar, a badge without a `badgeTone` swaps the bar's colors (`Badge` `variant="inverse"`), so it stands out in both themes.
+- Link Groups: `Navbar.Group` puts links under one button (the WAI-ARIA disclosure navigation pattern, not a menu). The button opens a dropdown; Escape, a press outside, Tab moving out, or choosing a link closes it, and opening one group closes the other. `active` marks the group holding the current page.
+- Link group, last on the page: A group as the last focusable thing on the page: Tab past its last link leaves the page, and the dropdown still closes. A press on the panel's padding (nothing focusable) keeps it open.
+- Link Groups Mobile: In the mobile menu, a group is an expandable section; the one holding the current page starts open.
+- Link Groups Right To Left: Right-to-left: the dropdown lines up with the button's right edge.
+- Mobile
 - Mobile Solid: The solid bar on a phone, with the menu sliding in from the start edge.
 - Router Links: Pass a router link component with `as` (on `Navbar.Link` and `Navbar.Brand`); its own props, such as `to`, are typed. Track the current route yourself and set `active` on the matching link.
 - Sticky on a long page: `position="sticky"` (the default) with `elevateOnScroll`: the soft shadow appears once the page scrolls. Scroll the canvas to see it.
@@ -6700,9 +6782,9 @@ import { Tooltip } from "@vjdesigns/vjdesigns-ui";
 
 Category: overlays · Storybook: Overlays/Tooltip
 
-A short, non-interactive label or description that appears on hover and on
-keyboard focus. Follows the WAI-ARIA tooltip pattern and WCAG 1.4.13: it
-can be dismissed with Escape, the pointer can move onto it, and it stays
+A short, non-interactive label or description that appears on hover and on
+keyboard focus. Follows the WAI-ARIA tooltip pattern and WCAG 1.4.13: it
+can be dismissed with Escape, the pointer can move onto it, and it stays
 open until the pointer or focus leaves. Use `Popover` for interactive content.
 
 ### Props
@@ -6745,7 +6827,7 @@ import { TooltipProvider } from "@vjdesigns/vjdesigns-ui";
 
 Category: overlays · Storybook: Overlays/Tooltip
 
-Optional. Sets shared timing for the tooltips inside it. Tooltips work
+Optional. Sets shared timing for the tooltips inside it. Tooltips work
 without a provider, using the defaults.
 
 ### Props
@@ -7908,6 +7990,16 @@ typing in that element.
 <Textarea onKeyDown={getHotkeyHandler([["mod+enter", send]])} />
 ```
 
+## withExtraItems
+
+```ts
+withExtraItems(virtualizer: Virtualizer, extra: readonly number[]): VirtualItem[]
+```
+
+The window's items plus extra indices that must stay rendered even when
+scrolled out of view (a focused row, a highlighted option), in order.
+Render spacers between non-adjacent items from their `start` / `end`.
+
 ## cx
 
 ```ts