@vjdesigns/vjdesigns-ui 2.2.0 → 2.4.0

package/dist/ai/llms-full.txt

@@ -1,4 +1,4 @@
-# @vjdesigns/vjdesigns-ui 2.1.0: full reference
+# @vjdesigns/vjdesigns-ui 2.3.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.
 
@@ -607,9 +607,9 @@ import { Avatar } from "@vjdesigns/vjdesigns-ui";
 
 Category: data-display · Storybook: Data Display/Avatar
 
-A person's picture, with a fallback chain of image, initials, then a user
-icon. Supports a presence status dot, a highlight ring, and stacking in an
-`AvatarGroup`.
+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
 
@@ -623,6 +623,7 @@ icon. Supports a presence status dot, a highlight ring, and stacking in an
 - `colorFromName`: `boolean`. Pick the fallback tone from a hash of `name`, so lists are colorful but stable.
 - `status`: `AvatarStatus`. Presence dot at the bottom-end corner. Also appended to the accessible name, e.g. "Dana Hernandez (online)".
 - `statusLabel`: `string`. Text for the status in the accessible name. Defaults to the status value ("online", "away", ...).
+- `bordered`: `boolean`. Draws a border around the avatar, e.g. to set a photo apart from a busy background or a cover image. Decorative. Its color is the `--avatar-border-color` CSS variable (default `--color-border-strong`); set it to `var(--color-surface)` for a light frame on a photo banner.
 - `ring`: `boolean`. Highlight ring (e.g. the active player). Visual only: also convey the state in text nearby or in `aria-label`.
 - `ringTone`: `Tone`. Color of the highlight ring. Uses the tone's `--color-*-border` token.
 - `decorative`: `boolean`. Hide the avatar from assistive technology. Use when the person's name is already visible next to the avatar.
@@ -633,7 +634,7 @@ icon. Supports a presence status dot, a highlight ring, and stacking in an
 
 ### Examples (Storybook stories)
 
-- Playground
+- Playground: A photo by default. Pick "None" under `src` to see initials (from `name`), and clear `name` too for the icon.
 - Sizes
 - Shapes
 - Image vs initials vs icon
@@ -642,6 +643,7 @@ icon. Supports a presence status dot, a highlight ring, and stacking in an
 - Color from name (team list)
 - Status
 - Ring (active player)
+- Bordered: `bordered` draws a border on a single avatar: for a photo, initials, or the icon. Change its color with the `--avatar-border-color` CSS variable, e.g. a light frame on a cover image (profile header). It stacks with the highlight ring and inside a group.
 - AvatarGroup
 - With name (decorative)
 - Both themes
@@ -709,6 +711,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
@@ -5450,22 +5453,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
@@ -5503,12 +5506,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.
@@ -5521,9 +5524,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.
@@ -5534,18 +5537,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`.
@@ -5565,7 +5597,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.

package/dist/ai/llms.txt

@@ -19,7 +19,7 @@
 ## Data-display
 
 - [Accordion](llms-full.txt#accordion): A vertically stacked set of headings that each reveal a section of content.
-- [Avatar](llms-full.txt#avatar): A person's picture, with a fallback chain of image, initials, then a user icon.
+- [Avatar](llms-full.txt#avatar): A person's photo (`src`), with a fallback chain of image, initials (from `name`), then a user icon, so it always shows something.
 - [AvatarGroup](llms-full.txt#avatargroup): Overlapping stack of avatars in a labelled `role="group"`.
 - [Badge](llms-full.txt#badge): A small, non-interactive status or label pill.
 - [BadgeAnchor](llms-full.txt#badgeanchor): Pins a count, dot, or short label to a corner of its child.

package/dist/ai/registry.json

@@ -1,6 +1,6 @@
 {
   "name": "@vjdesigns/vjdesigns-ui",
-  "version": "2.1.0",
+  "version": "2.3.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",
@@ -325,7 +325,7 @@
       "category": "data-display",
       "folder": "Avatar",
       "import": "import { Avatar } from \"@vjdesigns/vjdesigns-ui\";",
-      "description": "A person's picture, with a fallback chain of image, initials, then a user\r\nicon. Supports a presence status dot, a highlight ring, and stacking in an\r\n`AvatarGroup`.",
+      "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`.",
       "nativeElement": "span",
       "props": [
         {
@@ -388,6 +388,12 @@
           "required": false,
           "description": "Text for the status in the accessible name. Defaults to the status value (\"online\", \"away\", ...)."
         },
+        {
+          "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."
+        },
         {
           "name": "ring",
           "type": "boolean",
@@ -430,7 +436,7 @@
       "stories": [
         {
           "name": "Playground",
-          "description": ""
+          "description": "A photo by default. Pick \"None\" under `src` to see initials (from `name`), and clear `name` too for the icon."
         },
         {
           "name": "Sizes",
@@ -464,6 +470,10 @@
           "name": "Ring (active player)",
           "description": ""
         },
+        {
+          "name": "Bordered",
+          "description": "`bordered` draws a border on a single avatar: for a photo, initials, or\r\nthe icon. Change its color with the `--avatar-border-color` CSS variable,\r\ne.g. a light frame on a cover image (profile header). It stacks with the\r\nhighlight ring and inside a group."
+        },
         {
           "name": "AvatarGroup",
           "description": ""
@@ -677,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": ""
@@ -15302,7 +15316,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": [
         {
@@ -15337,7 +15351,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",
@@ -15358,14 +15372,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",
@@ -15379,7 +15393,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",
@@ -15426,7 +15440,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": [
@@ -15439,7 +15453,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",
@@ -15452,7 +15466,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": [
             {
@@ -15466,14 +15480,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",
@@ -15487,7 +15501,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": [
             {
@@ -15501,27 +15515,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",
@@ -15529,6 +15543,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",
@@ -15537,6 +15569,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",
@@ -15586,9 +15695,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",

package/dist/components/data-display/Avatar/Avatar.cjs.js

@@ -1 +1 @@
-const e=require("../../utilities/LocaleProvider/LocaleProvider.cjs.js"),t=require("../../../utils/cx.cjs.js"),n=require("../../primitives/Icon/icons.cjs.js"),r=require("./Avatar.module.css.cjs.js");let i=require("react"),a=require("react/jsx-runtime");function o(e){let t=Intl.Segmenter;return t?Array.from(new t(void 0,{granularity:`grapheme`}).segment(e),e=>e.segment):Array.from(e)}var s=/[\p{L}\p{N}]/u;function c(e){let t=o(e).find(e=>s.test(e));return t?t.toLocaleUpperCase():``}function l(e){if(!e)return``;let t=e.trim().split(/\s+/u).filter(e=>s.test(e));if(t.length===0)return``;let n=c(t[0]);return t.length===1?n:n+c(t[t.length-1])}var u=Object.freeze([`primary`,`accent`,`success`,`info`,`neutral`]);function d(e){let t=5381;for(let n of e.trim().toLocaleLowerCase())t=(t<<5)+t+(n.codePointAt(0)??0)|0;return u[Math.abs(t)%u.length]}var f={xs:r.default.xs,sm:r.default.sm,md:r.default.md,lg:r.default.lg,xl:r.default.xl,"2xl":r.default.size2xl},p={circle:r.default.circle,rounded:r.default.rounded,square:r.default.square},m={soft:r.default.soft,solid:r.default.solid},h={neutral:r.default.toneNeutral,primary:r.default.tonePrimary,accent:r.default.toneAccent,success:r.default.toneSuccess,warning:r.default.toneWarning,danger:r.default.toneDanger,info:r.default.toneInfo},g={neutral:r.default.ringNeutral,primary:r.default.ringPrimary,accent:r.default.ringAccent,success:r.default.ringSuccess,warning:r.default.ringWarning,danger:r.default.ringDanger,info:r.default.ringInfo},_={online:r.default.statusOnline,away:r.default.statusAway,busy:r.default.statusBusy,offline:r.default.statusOffline},v={sm:r.default.spacingSm,md:r.default.spacingMd,lg:r.default.spacingLg},y=(0,i.createContext)(null);function b({src:o,alt:s,name:c,size:u,shape:v,tone:b=`neutral`,variant:x=`soft`,colorFromName:S=!1,status:C,statusLabel:w,ring:T=!1,ringTone:E=`accent`,decorative:D=!1,icon:O,imgProps:ee,onImageStatusChange:te,className:k,"aria-label":A,"aria-labelledby":j,...M}){let N=e.useMessages(),P=(0,i.useContext)(y),ne=P?.size??u??`md`,re=v??P?.shape??`circle`,[F,I]=(0,i.useState)(null),L=o?F?.src===o?F.status:`loading`:void 0,R=e=>{!o||F?.src===o&&F.status===e||(I({src:o,status:e}),te?.(e))},{onLoad:z,onError:B,className:V,ref:H,...U}=ee??{},W=e=>{e&&e.complete&&F?.src!==o&&R(e.naturalWidth>0?`loaded`:`error`),typeof H==`function`?H(e):H&&(H.current=e)},G=e=>{R(`loaded`),z?.(e)},K=e=>{R(`error`),B?.(e)},q=l(c),J=S&&c?.trim()?d(c):b,Y=!!o&&L!==`error`,X=D||s===``&&!c,Z=s||c?.trim()||N.avatar.fallbackName,Q=C?w??N.avatar.status[C]:void 0,ie=Q?`${Z} (${Q})`:Z,ae=X&&!Q?{"aria-hidden":!0}:X?{role:`img`,"aria-label":Q}:{role:`img`,"aria-label":j?A:A===void 0?ie:(e=>Q?`${e} (${Q})`:e)(A),"aria-labelledby":j},$;return $=Y?(0,a.jsx)(`img`,{...U,ref:W,src:o,alt:``,className:t.cx(r.default.image,L===`loaded`&&r.default.imageLoaded,V),onLoad:G,onError:K}):q?(0,a.jsx)(`span`,{className:r.default.initials,children:q}):O??(0,a.jsx)(n.UserIcon,{className:r.default.icon}),(0,a.jsxs)(`span`,{...M,...ae,"data-status":C,"data-image-status":L,className:t.cx(r.default.root,f[ne],p[re],m[x],h[J],P&&r.default.inGroup,T&&r.default.ring,T&&g[E],k),children:[(0,a.jsx)(`span`,{className:r.default.face,children:$}),C&&(0,a.jsx)(`span`,{className:t.cx(r.default.status,_[C]),"aria-hidden":`true`})]})}function x({size:n=`md`,shape:o,max:s,spacing:c=`md`,surplusLabel:l,renderSurplus:u,className:d,children:m,...h}){let g=e.useMessages(),_=l??g.avatar.surplus,b=i.Children.toArray(m).filter(i.isValidElement),x=s!==void 0&&s>=0&&s<b.length?Math.floor(s):b.length,S=b.slice(0,x),C=b.slice(x),w=C.length;return(0,a.jsx)(y.Provider,{value:{size:n,shape:o},children:(0,a.jsxs)(`div`,{role:`group`,...h,className:t.cx(r.default.group,f[n],v[c],d),children:[S,w>0&&(u?u(w,C):(0,a.jsx)(`span`,{role:`img`,"aria-label":_(w),className:t.cx(r.default.root,f[n],p[o??`circle`],r.default.soft,r.default.toneNeutral,r.default.inGroup),children:(0,a.jsx)(`span`,{className:r.default.face,children:(0,a.jsxs)(`span`,{className:t.cx(r.default.initials,r.default.surplus),"aria-hidden":`true`,children:[`+`,w]})})}))]})})}exports.Avatar=b,exports.AvatarGroup=x,exports.avatarNameTones=u,exports.avatarToneFromName=d,exports.getInitials=l;
+const e=require("../../utilities/LocaleProvider/LocaleProvider.cjs.js"),t=require("../../../utils/cx.cjs.js"),n=require("../../primitives/Icon/icons.cjs.js"),r=require("./Avatar.module.css.cjs.js");let i=require("react"),a=require("react/jsx-runtime");function o(e){let t=Intl.Segmenter;return t?Array.from(new t(void 0,{granularity:`grapheme`}).segment(e),e=>e.segment):Array.from(e)}var s=/[\p{L}\p{N}]/u;function c(e){let t=o(e).find(e=>s.test(e));return t?t.toLocaleUpperCase():``}function l(e){if(!e)return``;let t=e.trim().split(/\s+/u).filter(e=>s.test(e));if(t.length===0)return``;let n=c(t[0]);return t.length===1?n:n+c(t[t.length-1])}var u=Object.freeze([`primary`,`accent`,`success`,`info`,`neutral`]);function d(e){let t=5381;for(let n of e.trim().toLocaleLowerCase())t=(t<<5)+t+(n.codePointAt(0)??0)|0;return u[Math.abs(t)%u.length]}var f={xs:r.default.xs,sm:r.default.sm,md:r.default.md,lg:r.default.lg,xl:r.default.xl,"2xl":r.default.size2xl},p={circle:r.default.circle,rounded:r.default.rounded,square:r.default.square},m={soft:r.default.soft,solid:r.default.solid},h={neutral:r.default.toneNeutral,primary:r.default.tonePrimary,accent:r.default.toneAccent,success:r.default.toneSuccess,warning:r.default.toneWarning,danger:r.default.toneDanger,info:r.default.toneInfo},g={neutral:r.default.ringNeutral,primary:r.default.ringPrimary,accent:r.default.ringAccent,success:r.default.ringSuccess,warning:r.default.ringWarning,danger:r.default.ringDanger,info:r.default.ringInfo},_={online:r.default.statusOnline,away:r.default.statusAway,busy:r.default.statusBusy,offline:r.default.statusOffline},v={sm:r.default.spacingSm,md:r.default.spacingMd,lg:r.default.spacingLg},y=(0,i.createContext)(null);function b({src:o,alt:s,name:c,size:u,shape:v,tone:b=`neutral`,variant:x=`soft`,colorFromName:S=!1,status:C,statusLabel:w,bordered:T=!1,ring:E=!1,ringTone:D=`accent`,decorative:ee=!1,icon:te,imgProps:O,onImageStatusChange:k,className:A,"aria-label":j,"aria-labelledby":M,...N}){let P=e.useMessages(),F=(0,i.useContext)(y),ne=F?.size??u??`md`,re=v??F?.shape??`circle`,[I,L]=(0,i.useState)(null),R=o?I?.src===o?I.status:`loading`:void 0,z=e=>{!o||I?.src===o&&I.status===e||(L({src:o,status:e}),k?.(e))},{onLoad:B,onError:V,className:H,ref:U,...W}=O??{},G=e=>{e&&e.complete&&I?.src!==o&&z(e.naturalWidth>0?`loaded`:`error`),typeof U==`function`?U(e):U&&(U.current=e)},K=e=>{z(`loaded`),B?.(e)},q=e=>{z(`error`),V?.(e)},J=l(c),Y=S&&c?.trim()?d(c):b,ie=!!o&&R!==`error`,X=ee||s===``&&!c,Z=s||c?.trim()||P.avatar.fallbackName,Q=C?w??P.avatar.status[C]:void 0,ae=Q?`${Z} (${Q})`:Z,oe=X&&!Q?{"aria-hidden":!0}:X?{role:`img`,"aria-label":Q}:{role:`img`,"aria-label":M?j:j===void 0?ae:(e=>Q?`${e} (${Q})`:e)(j),"aria-labelledby":M},$;return $=ie?(0,a.jsx)(`img`,{...W,ref:G,src:o,alt:``,className:t.cx(r.default.image,R===`loaded`&&r.default.imageLoaded,H),onLoad:K,onError:q}):J?(0,a.jsx)(`span`,{className:r.default.initials,children:J}):te??(0,a.jsx)(n.UserIcon,{className:r.default.icon}),(0,a.jsxs)(`span`,{...N,...oe,"data-status":C,"data-image-status":R,className:t.cx(r.default.root,f[ne],p[re],m[x],h[Y],F&&r.default.inGroup,T&&r.default.bordered,E&&r.default.ring,E&&g[D],A),children:[(0,a.jsx)(`span`,{className:r.default.face,children:$}),C&&(0,a.jsx)(`span`,{className:t.cx(r.default.status,_[C]),"aria-hidden":`true`})]})}function x({size:n=`md`,shape:o,max:s,spacing:c=`md`,surplusLabel:l,renderSurplus:u,className:d,children:m,...h}){let g=e.useMessages(),_=l??g.avatar.surplus,b=i.Children.toArray(m).filter(i.isValidElement),x=s!==void 0&&s>=0&&s<b.length?Math.floor(s):b.length,S=b.slice(0,x),C=b.slice(x),w=C.length;return(0,a.jsx)(y.Provider,{value:{size:n,shape:o},children:(0,a.jsxs)(`div`,{role:`group`,...h,className:t.cx(r.default.group,f[n],v[c],d),children:[S,w>0&&(u?u(w,C):(0,a.jsx)(`span`,{role:`img`,"aria-label":_(w),className:t.cx(r.default.root,f[n],p[o??`circle`],r.default.soft,r.default.toneNeutral,r.default.inGroup),children:(0,a.jsx)(`span`,{className:r.default.face,children:(0,a.jsxs)(`span`,{className:t.cx(r.default.initials,r.default.surplus),"aria-hidden":`true`,children:[`+`,w]})})}))]})})}exports.Avatar=b,exports.AvatarGroup=x,exports.avatarNameTones=u,exports.avatarToneFromName=d,exports.getInitials=l;

package/dist/components/data-display/Avatar/Avatar.d.ts

@@ -54,6 +54,13 @@ export interface AvatarProps extends Omit<ComponentPropsWithRef<"span">, "childr
     status?: AvatarStatus;
     /** Text for the status in the accessible name. Defaults to the status value ("online", "away", ...). */
     statusLabel?: string;
+    /**
+     * Draws a border around the avatar, e.g. to set a photo apart from a busy
+     * background or a cover image. Decorative. Its color is the
+     * `--avatar-border-color` CSS variable (default `--color-border-strong`);
+     * set it to `var(--color-surface)` for a light frame on a photo banner.
+     */
+    bordered?: boolean;
     /**
      * Highlight ring (e.g. the active player). Visual only: also convey the
      * state in text nearby or in `aria-label`.
@@ -74,11 +81,11 @@ export interface AvatarProps extends Omit<ComponentPropsWithRef<"span">, "childr
     onImageStatusChange?: (status: AvatarImageStatus) => void;
 }
 /**
- * A person's picture, with a fallback chain of image, initials, then a user
- * icon. Supports a presence status dot, a highlight ring, and stacking in an
- * `AvatarGroup`.
+ * 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`.
  */
-export declare function Avatar({ src, alt, name, size, shape, tone, variant, colorFromName, status, statusLabel, ring, ringTone, decorative, icon, imgProps, onImageStatusChange, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...rest }: AvatarProps): import("react").JSX.Element;
+export declare function Avatar({ src, alt, name, size, shape, tone, variant, colorFromName, status, statusLabel, bordered, ring, ringTone, decorative, icon, imgProps, onImageStatusChange, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...rest }: AvatarProps): import("react").JSX.Element;
 type AvatarGroupName = {
     /** Accessible name for the group, e.g. "Starting lineup". */
     "aria-label": string;