@vjdesigns/vjdesigns-ui 2.4.0 → 3.0.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.3.0: full reference
+# @vjdesigns/vjdesigns-ui 2.5.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
@@ -1233,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.
@@ -1246,11 +1291,16 @@ 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.
 - `ref`: `Ref<HTMLTableElement>`. Ref to the `<table role="grid">`.
+- `treegrid`: `boolean` (default false). Rows form a hierarchy (groups, a tree): the table becomes a `role="treegrid"` and each row takes the `level` and `expanded` from `getRowProps`.
+- `getRowProps`: `(row: T) => DataGridRowProps`. Per-row level, expanded state, and class name.
+- `renderRowDetail`: `(row: T) => ReactNode`. Content for a full-width row under a row (master-detail), or null for none. Its controls are outside the grid's arrow-key navigation: Tab from the row moves into them. A grid with detail rows doesn't virtualize, so pair it with `pageSize` for long lists.
+- `onRowsShown`: `(rows: readonly T[]) => void`. Called with the rows the grid shows, sorted, filtered, and paged, in display order, whenever they change (to copy a cell range, or export exactly what's on screen).
+- `onVisibleRangeChange`: `(range: { start: number; end: number }) => void`. Called with the range of shown rows (indexes into them, inclusive) that are rendered in view. With virtualization this follows scrolling, which is what "load more while scrolling" needs.
 
 ### Examples (Storybook stories)
 
@@ -1265,6 +1315,9 @@ 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.
+- Row Levels And Details: Extension points for hierarchical and master-detail grids: `treegrid` with `getRowProps` (each row's level and expanded state), and `renderRowDetail` (a full-width row under a row). DataGridPro builds its grouping, tree data, and details on these.
+- Rows Shown And Range: `onRowsShown` reports the rows on screen, sorted, filtered, and paged, in order; `onVisibleRangeChange` reports which of them are rendered in view. DataGridPro builds cell ranges and loading while scrolling on these.
 
 ## EmptyState
 
@@ -1385,19 +1438,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
@@ -1417,8 +1470,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.
@@ -1436,14 +1489,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.
@@ -1465,12 +1518,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.
@@ -1492,14 +1545,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.
@@ -1636,7 +1689,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.
@@ -1678,9 +1731,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.
@@ -1710,8 +1763,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.
@@ -1725,7 +1778,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.
@@ -2800,6 +2853,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
 
@@ -3197,7 +3251,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
@@ -3236,13 +3290,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.
@@ -3340,21 +3394,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
@@ -3911,6 +3965,7 @@ focusable, covering the segment) inside a `<label>`. `ref` points at the
 - Controlled
 - In Fieldset
 - Composition: Stats period
+- Right To Left: Right to left: the segments run from the right and the thumb sits under the selected one.
 
 ## Select
 
@@ -6735,9 +6790,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
@@ -6780,7 +6835,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
@@ -7943,6 +7998,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