@godxjp/ui 18.3.0 → 18.5.0

package/dist/components/layout/sidebar-link.d.ts

@@ -0,0 +1,43 @@
+import * as React from "react";
+import type { SidebarLinkComponentProp } from "../../props/components/layout.prop.js";
+/**
+ * Adapt a framework router `Link` to {@link SidebarLinkComponentProp} (gh#213) — a dependency-free
+ * factory, so `@godxjp/ui` still ships ZERO router/framework dependencies.
+ *
+ * It lives in its own module (imports only React + the prop types) so `@godxjp/ui/inertia` can build
+ * on it without pulling the whole Sidebar — and its Collapsible/Popover/Tooltip tree — into a
+ * form-only consumer's bundle.
+ *
+ * It normalizes only the two things that differ between routers:
+ * 1. **Which prop carries the destination** — `"href"` (Inertia, Next.js) or `"to"` (React Router,
+ *    TanStack Router).
+ * 2. **A row with no destination** — a disabled row must never mount a router link (Inertia and
+ *    React Router both require a string destination and would navigate to `""`); it falls back to an
+ *    inert `<a>` that keeps the canonical row class and `aria-disabled`. That fallback carries an
+ *    explicit `role="link"`: an `<a>` without `href` has NO implicit role, so a screen reader would
+ *    announce it as plain text and `aria-label` would be a prohibited attribute — which is exactly
+ *    how the icon-only collapsed rail (where the label lives on `aria-label`) would have lost the
+ *    name of every disabled row. Callers that supply their own role — the collapsed flyout's
+ *    `menuitem` — still win, because `rest` is spread after it.
+ *
+ * Everything else — the icon, the label, the badge, `data-active`/`aria-current`, the collapsed
+ * rail's `aria-label` — is composed by the LIBRARY and arrives as `children`. The consumer never
+ * reconstructs row markup, which is what makes the reported "every sidebar icon disappeared"
+ * regression impossible.
+ *
+ * @example
+ * ```tsx
+ * // React Router / TanStack Router — destination prop is `to`.
+ * import { Link } from "react-router-dom";
+ * const RouterLink = createSidebarLink(Link, "to");
+ * <Sidebar linkComponent={RouterLink} sections={sections} activeId={activeId} />
+ *
+ * // Inertia / Next.js — destination prop is `href` (the default).
+ * import { Link } from "@inertiajs/react";
+ * const InertiaLink = createSidebarLink(Link);
+ * ```
+ */
+export declare function createSidebarLink<P extends {
+    className?: string;
+    children?: React.ReactNode;
+}>(Link: React.ComponentType<P>, hrefProp?: "href" | "to"): SidebarLinkComponentProp;

package/dist/components/layout/sidebar-link.js

@@ -0,0 +1,13 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+function createSidebarLink(Link, hrefProp = "href") {
+  const Adapter = React.forwardRef(function SidebarLinkAdapter({ href, ...rest }, ref) {
+    if (!href) return /* @__PURE__ */ jsx("a", { ref, role: "link", ...rest });
+    const routed = { [hrefProp]: href, ...rest, ref };
+    return /* @__PURE__ */ jsx(Link, { ...routed });
+  });
+  return Adapter;
+}
+export {
+  createSidebarLink
+};

package/dist/components/layout/sidebar.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
-import type { SidebarItemData, SidebarProp } from "../../props/components/layout.prop.js";
-export type { SidebarItemData, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, } from "../../props/components/layout.prop.js";
-type RenderItem = (item: SidebarItemData) => React.ReactNode;
+import type { SidebarItemData, SidebarLinkComponentProp, SidebarProp, SidebarRenderItemProp } from "../../props/components/layout.prop.js";
+export type { SidebarItemData, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, } from "../../props/components/layout.prop.js";
+type RenderItem = (item: SidebarItemData, rowProps: SidebarRenderItemProp) => React.ReactNode;
 type SidebarHeaderProps = React.HTMLAttributes<HTMLDivElement>;
 type SidebarSectionProps = {
     label?: string;
@@ -13,9 +13,46 @@ type SidebarItemProps = {
     active?: boolean;
     sub?: boolean;
     onActivate?: (id: string) => void;
+    /**
+     * Framework-router link element TYPE (gh#213). The row content stays library-composed — see
+     * {@link SidebarLinkProp}. Applied only when `item.href` is set.
+     */
+    linkComponent?: SidebarLinkComponentProp;
+    /**
+     * Radix-style element swap: the single child element (a router `<Link>`) BECOMES the row and the
+     * library injects its composed icon + label + badge as that element's children (gh#213). Use it
+     * when you compose `SidebarItem` by hand instead of passing `sections` + `linkComponent`.
+     */
+    asChild?: boolean;
+    /** @deprecated Use `linkComponent` / `asChild` — see {@link SidebarProp.renderItem}. */
     renderItem?: RenderItem;
 };
 export declare function SidebarHeader({ children, className, ...props }: SidebarHeaderProps): React.JSX.Element;
 export declare function SidebarSection({ label, collapsed, children, className, ...props }: SidebarSectionProps & React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
-export declare function SidebarItem({ item, active, sub, onActivate, renderItem, children, ...props }: SidebarItemProps & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick">): React.JSX.Element;
-export declare function Sidebar({ ariaLabel: ariaLabelCamel, activeId, onSelect, sections, product, onProductClick, brand, collapsed, children, renderItem, footer, "aria-label": ariaLabel, }: SidebarProp): React.JSX.Element;
+export declare function SidebarItem({ item, active, sub, onActivate, linkComponent: LinkComponent, asChild, renderItem, children, ...props }: SidebarItemProps & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick">): React.JSX.Element;
+export { createSidebarLink } from "./sidebar-link.js";
+/**
+ * Sidebar — data-driven vertical nav rail.
+ *
+ * ROUTER LINKS (gh#213): pass `linkComponent` and the LIBRARY keeps composing every row (icon slot,
+ * label, badge, active state, the icon-only collapsed rail and its tooltip name) — the consumer
+ * supplies only the link ELEMENT. Use {@link createSidebarLink} to adapt a router `Link`, or
+ * `SidebarItem asChild` when composing rows by hand. `renderItem` is DEPRECATED: it left row content
+ * to the consumer, so a `<Link>{item.label}</Link>` dropped every icon and badge.
+ *
+ * THEMING (gh#228): the row/label and the nav ICON read SEPARATE component tokens, so a service can
+ * match a canonical shell's darker 16px icons without page-local CSS and without re-tinting every
+ * muted text globally:
+ *
+ * - `--sidebar-nav-item-foreground` (row + label, incl. sub rows) · default `hsl(var(--muted-foreground))`
+ * - `--sidebar-nav-item-hover-foreground` · default `hsl(var(--foreground))`
+ * - `--sidebar-nav-item-disabled-foreground` · default = the resting row colour
+ * - `--sidebar-nav-icon-foreground` (`.sb-icon`, incl. the collapsed rail + group triggers) ·
+ *   default `currentColor` = the row colour
+ * - `--sidebar-nav-icon-{hover,active,disabled}-foreground` · each defaults to the base icon knob
+ *
+ * The active row keeps `--sidebar-item-active-background` / `--sidebar-item-active-foreground`.
+ * These are COLOUR knobs only — icon size stays `--sidebar-nav-icon-size` (16px) and row geometry
+ * stays `--sidebar-nav-item-height` / `-gap` / `-padding-x`.
+ */
+export declare function Sidebar({ ariaLabel: ariaLabelCamel, activeId, onSelect, sections, product, onProductClick, brand, collapsed, children, linkComponent, renderItem, footer, "aria-label": ariaLabel, }: SidebarProp): React.JSX.Element;

package/dist/components/layout/sidebar.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Slot } from "@radix-ui/react-slot";
 import { ChevronDown } from "lucide-react";
@@ -23,72 +23,91 @@ function SidebarSection({
     /* @__PURE__ */ jsx("div", { className: "sb-nav", children })
   ] });
 }
+function SidebarIcon({ icon: Icon }) {
+  return /* @__PURE__ */ jsx("span", { className: "sb-icon", children: Icon ? /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true" }) : null });
+}
+function SidebarRowContent({
+  item,
+  sub = false,
+  iconOnly = false
+}) {
+  if (iconOnly) return /* @__PURE__ */ jsx(SidebarIcon, { icon: item.icon });
+  const showBadge = item.badge !== void 0 && item.badge !== "";
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    !sub ? /* @__PURE__ */ jsx(SidebarIcon, { icon: item.icon }) : null,
+    /* @__PURE__ */ jsx("span", { className: "sb-label", children: item.label }),
+    showBadge ? /* @__PURE__ */ jsx("span", { className: "sb-badge", children: item.badge }) : null
+  ] });
+}
 function SidebarItem({
   item,
   active = false,
   sub = false,
   onActivate,
+  linkComponent: LinkComponent,
+  asChild = false,
   renderItem,
   children,
   ...props
 }) {
-  const Icon = item.icon;
-  const showBadge = item.badge !== void 0 && item.badge !== "";
   const disabled = item.disabled || props.disabled;
-  const custom = children ?? (renderItem ? renderItem(item) : void 0);
   const rowClass = cn("sb-nav-item", sub && "sb-nav-item--sub");
   const stateProps = {
     className: rowClass,
     "data-active": active ? "true" : void 0,
-    "aria-current": active ? "page" : void 0
+    "aria-current": active ? "page" : void 0,
+    "aria-disabled": disabled ? true : void 0
+  };
+  const content = /* @__PURE__ */ jsx(SidebarRowContent, { item, sub });
+  const activate = (event) => {
+    if (disabled) {
+      event.preventDefault();
+      return;
+    }
+    onActivate?.(item.id);
   };
+  if (asChild && React.isValidElement(children)) {
+    return /* @__PURE__ */ jsx(Slot, { ...stateProps, onClick: activate, children: React.cloneElement(children, void 0, content) });
+  }
+  const custom = children ?? (renderItem ? renderItem(item, { ...stateProps, children: content }) : void 0);
   if (custom !== void 0) {
-    return /* @__PURE__ */ jsx(Slot, { ...stateProps, "aria-disabled": disabled || void 0, children: custom });
+    return /* @__PURE__ */ jsx(Slot, { ...stateProps, children: custom });
+  }
+  if (LinkComponent && item.href) {
+    return /* @__PURE__ */ jsx(
+      LinkComponent,
+      {
+        ...stateProps,
+        href: disabled ? void 0 : item.href,
+        "aria-disabled": disabled || void 0,
+        onClick: activate,
+        children: content
+      }
+    );
   }
   if (item.href) {
-    return /* @__PURE__ */ jsxs(
+    return /* @__PURE__ */ jsx(
       "a",
       {
         ...props,
         href: disabled ? void 0 : item.href,
         ...stateProps,
         "aria-disabled": disabled || void 0,
-        onClick: (event) => {
-          if (disabled) event.preventDefault();
-          else onActivate?.(item.id);
-        },
-        children: [
-          !sub ? /* @__PURE__ */ jsx("span", { className: "sb-icon", children: /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true" }) }) : null,
-          /* @__PURE__ */ jsx("span", { className: "sb-label", children: item.label }),
-          showBadge ? /* @__PURE__ */ jsx("span", { className: "sb-badge", children: item.badge }) : null
-        ]
+        onClick: activate,
+        children: content
       }
     );
   }
-  return /* @__PURE__ */ jsxs(
-    "button",
-    {
-      type: "button",
-      ...stateProps,
-      "aria-disabled": disabled,
-      ...props,
-      onClick: () => {
-        if (disabled) return;
-        onActivate?.(item.id);
-      },
-      children: [
-        !sub ? /* @__PURE__ */ jsx("span", { className: "sb-icon", children: /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true" }) }) : null,
-        /* @__PURE__ */ jsx("span", { className: "sb-label", children: item.label }),
-        showBadge ? /* @__PURE__ */ jsx("span", { className: "sb-badge", children: item.badge }) : null
-      ]
-    }
+  return (
+    // ui-audit-disable-next-line no-raw-button — raw <button> is the correct element here.
+    /* @__PURE__ */ jsx("button", { type: "button", ...stateProps, "aria-disabled": disabled, ...props, onClick: activate, children: content })
   );
 }
 function isItemActive(item, activeId) {
   if (item.id === activeId) return true;
   return (item.children ?? []).some((child) => isItemActive(child, activeId));
 }
-function NavLeaf({ item, activeId, onSelect, sub = false, renderItem }) {
+function NavLeaf({ item, activeId, onSelect, sub = false, linkComponent, renderItem }) {
   const active = item.id === activeId;
   return /* @__PURE__ */ jsx(
     SidebarItem,
@@ -97,6 +116,7 @@ function NavLeaf({ item, activeId, onSelect, sub = false, renderItem }) {
       active,
       onActivate: onSelect,
       sub,
+      linkComponent,
       renderItem
     }
   );
@@ -105,6 +125,7 @@ function NavLeafsInGroup({
   children,
   activeId,
   onSelect,
+  linkComponent,
   renderItem
 }) {
   return children.map((child) => /* @__PURE__ */ jsx(
@@ -114,13 +135,13 @@ function NavLeafsInGroup({
       activeId,
       onSelect,
       sub: true,
+      linkComponent,
       renderItem
     },
     child.id
   ));
 }
-function NavGroup({ item, activeId, onSelect, renderItem }) {
-  const Icon = item.icon;
+function NavGroup({ item, activeId, onSelect, linkComponent, renderItem }) {
   const active = isItemActive(item, activeId);
   const children = item.children ?? [];
   const [open, setOpen] = React.useState(active);
@@ -134,18 +155,25 @@ function NavGroup({ item, activeId, onSelect, renderItem }) {
         className: "sb-nav-item sb-nav-group-trigger",
         "data-active": active ? "true" : void 0,
         children: [
-          /* @__PURE__ */ jsx("span", { className: "sb-icon", children: /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true" }) }),
-          /* @__PURE__ */ jsx("span", { className: "sb-label", children: item.label }),
+          /* @__PURE__ */ jsx(SidebarRowContent, { item }),
           /* @__PURE__ */ jsx(ChevronDown, { className: "sb-chevron", "aria-hidden": "true" })
         ]
       }
     ),
-    /* @__PURE__ */ jsx(CollapsibleContent, { children: /* @__PURE__ */ jsx("div", { className: "sb-nav-sub", children: children.length > 0 ? /* @__PURE__ */ jsx(NavLeafsInGroup, { activeId, onSelect, renderItem, children }) : null }) })
+    /* @__PURE__ */ jsx(CollapsibleContent, { children: /* @__PURE__ */ jsx("div", { className: "sb-nav-sub", children: children.length > 0 ? /* @__PURE__ */ jsx(
+      NavLeafsInGroup,
+      {
+        activeId,
+        onSelect,
+        linkComponent,
+        renderItem,
+        children
+      }
+    ) : null }) })
   ] });
 }
-function CollapsedRow({ item, activeId, onSelect }) {
+function CollapsedRow({ item, activeId, onSelect, linkComponent: LinkComponent }) {
   const [menuOpen, setMenuOpen] = React.useState(false);
-  const Icon = item.icon;
   const active = isItemActive(item, activeId);
   const children = item.children ?? [];
   const hasChildren = children.length > 0;
@@ -163,12 +191,31 @@ function CollapsedRow({ item, activeId, onSelect }) {
       onClick: () => {
         if (!hasChildren && !item.disabled) onSelect?.(item.id);
       },
-      children: /* @__PURE__ */ jsx("span", { className: "sb-icon", children: /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true" }) })
+      children: /* @__PURE__ */ jsx(SidebarIcon, { icon: item.icon })
     }
   );
+  const iconLink = LinkComponent && !hasChildren && item.href ? /* @__PURE__ */ jsx(
+    LinkComponent,
+    {
+      className: "sb-nav-item",
+      "data-active": active ? "true" : void 0,
+      "aria-current": active ? "page" : void 0,
+      "aria-disabled": item.disabled || void 0,
+      "aria-label": item.label,
+      href: item.disabled ? void 0 : item.href,
+      onClick: (event) => {
+        if (item.disabled) {
+          event.preventDefault();
+          return;
+        }
+        onSelect?.(item.id);
+      },
+      children: /* @__PURE__ */ jsx(SidebarRowContent, { item, iconOnly: true })
+    }
+  ) : null;
   if (!hasChildren) {
     return /* @__PURE__ */ jsxs(Tooltip, { children: [
-      /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: iconButton }),
+      /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: iconLink ?? iconButton }),
       /* @__PURE__ */ jsx(TooltipContent, { side: "right", children: item.label })
     ] });
   }
@@ -187,27 +234,45 @@ function CollapsedRow({ item, activeId, onSelect }) {
         className: "sb-flyout-pop",
         children: [
           /* @__PURE__ */ jsx("div", { className: "sb-flyout-title", children: item.label }),
-          children.map((child) => /* @__PURE__ */ jsx(
-            "button",
-            {
-              type: "button",
+          children.map((child) => {
+            const childActive = child.id === activeId;
+            const select = (event) => {
+              setMenuOpen(false);
+              if (child.disabled) {
+                event.preventDefault();
+                return;
+              }
+              onSelect?.(child.id);
+            };
+            const flyoutState = {
               role: "menuitem",
               className: "sb-nav-item",
-              "data-active": child.id === activeId ? "true" : void 0,
-              "aria-current": child.id === activeId ? "page" : void 0,
-              onClick: () => {
-                setMenuOpen(false);
-                if (!child.disabled) onSelect?.(child.id);
+              "data-active": childActive ? "true" : void 0,
+              "aria-current": childActive ? "page" : void 0,
+              "aria-disabled": child.disabled || void 0
+            };
+            return LinkComponent && child.href ? /* @__PURE__ */ jsx(
+              LinkComponent,
+              {
+                ...flyoutState,
+                href: child.disabled ? void 0 : child.href,
+                onClick: select,
+                children: /* @__PURE__ */ jsx(SidebarRowContent, { item: child, sub: true })
               },
-              children: /* @__PURE__ */ jsx("span", { className: "sb-label", children: child.label })
-            },
-            child.id
-          ))
+              child.id
+            ) : (
+              // A collapsed-rail flyout entry is a `menuitem`-styled nav row owning `.sb-nav-item`
+              // composition, not a <Button> — same contract as the leaf row above.
+              // ui-audit-disable-next-line no-raw-button
+              /* @__PURE__ */ jsx("button", { type: "button", ...flyoutState, onClick: select, children: /* @__PURE__ */ jsx(SidebarRowContent, { item: child, sub: true }) }, child.id)
+            );
+          })
         ]
       }
     )
   ] });
 }
+import { createSidebarLink } from "./sidebar-link.js";
 function Sidebar({
   ariaLabel: ariaLabelCamel,
   activeId,
@@ -218,6 +283,7 @@ function Sidebar({
   brand,
   collapsed = false,
   children,
+  linkComponent,
   renderItem,
   footer,
   "aria-label": ariaLabel
@@ -257,35 +323,53 @@ function Sidebar({
         meta
       ] });
     })() : null,
-    /* @__PURE__ */ jsx("nav", { className: "sb-nav-scroll", "aria-label": ariaLabel ?? ariaLabelCamel ?? t("layout.sidebar.ariaLabel"), children: children ?? resolvedSections.map((section, sectionIndex) => /* @__PURE__ */ jsx(
-      SidebarSection,
+    /* @__PURE__ */ jsx(
+      "nav",
       {
-        label: section.label,
-        collapsed,
-        children: section.items.map(
-          (item) => collapsed ? /* @__PURE__ */ jsx(CollapsedRow, { item, activeId, onSelect }, item.id) : item.children && item.children.length > 0 ? /* @__PURE__ */ jsx(
-            NavGroup,
-            {
-              item,
-              activeId,
-              onSelect,
-              renderItem
-            },
-            item.id
-          ) : /* @__PURE__ */ jsx(
-            NavLeaf,
-            {
-              item,
-              activeId,
-              onSelect,
-              renderItem
-            },
-            item.id
-          )
-        )
-      },
-      section.label ?? sectionIndex
-    )) }),
+        className: "sb-nav-scroll",
+        "aria-label": ariaLabel ?? ariaLabelCamel ?? t("layout.sidebar.ariaLabel"),
+        children: children ?? resolvedSections.map((section, sectionIndex) => /* @__PURE__ */ jsx(
+          SidebarSection,
+          {
+            label: section.label,
+            collapsed,
+            children: section.items.map(
+              (item) => collapsed ? /* @__PURE__ */ jsx(
+                CollapsedRow,
+                {
+                  item,
+                  activeId,
+                  onSelect,
+                  linkComponent
+                },
+                item.id
+              ) : item.children && item.children.length > 0 ? /* @__PURE__ */ jsx(
+                NavGroup,
+                {
+                  item,
+                  activeId,
+                  onSelect,
+                  linkComponent,
+                  renderItem
+                },
+                item.id
+              ) : /* @__PURE__ */ jsx(
+                NavLeaf,
+                {
+                  item,
+                  activeId,
+                  onSelect,
+                  linkComponent,
+                  renderItem
+                },
+                item.id
+              )
+            )
+          },
+          section.label ?? sectionIndex
+        ))
+      }
+    ),
     footer ? /* @__PURE__ */ jsx("div", { className: "sb-footer", children: footer }) : null
   ] });
 }
@@ -293,5 +377,6 @@ export {
   Sidebar,
   SidebarHeader,
   SidebarItem,
-  SidebarSection
+  SidebarSection,
+  createSidebarLink
 };

package/dist/components/navigation/app-setting-picker.js

@@ -63,7 +63,7 @@ const ARIA_KEY = {
 };
 const BRAND_NONE = "__app__";
 const AppSettingPicker = React.forwardRef(
-  function AppSettingPicker2({ kind, appearance, className, disabled, id, name, value, onValueChange }, ref) {
+  function AppSettingPicker2({ kind, appearance, compact = false, className, disabled, id, name, value, onValueChange }, ref) {
     const resolvedAppearance = appearance ?? (kind === "locale" ? "icon" : "labeled");
     const ctx = useOptionalAppContext();
     const { t, locale, fallbackLocale } = useTranslation();
@@ -121,6 +121,8 @@ const AppSettingPicker = React.forwardRef(
     const unbound = current === void 0 || !handleChange;
     const Icon = ICON[kind];
     const iconOnly = resolvedAppearance === "icon";
+    const inline = resolvedAppearance === "inline";
+    const isCompact = compact && !inline;
     return /* @__PURE__ */ jsxs(
       Select,
       {
@@ -135,9 +137,9 @@ const AppSettingPicker = React.forwardRef(
             {
               ref,
               id,
-              showIndicator: !iconOnly,
+              showIndicator: !iconOnly && !inline,
               className: cn(
-                iconOnly ? (
+                inline ? "ui-app-setting-picker-inline h-auto min-h-0 w-auto rounded-none border-0 bg-transparent p-0 shadow-none" : iconOnly ? (
                   // Structurally icon-only: drop the owned width + value spacing and square the box to
                   // the density-aware --control-height tap target, centring the icon.
                   "w-[length:var(--control-height)] justify-center ps-0 pe-0"
@@ -147,16 +149,25 @@ const AppSettingPicker = React.forwardRef(
                   // `w-full` — so a labeled picker dropped into a narrow topbar no longer stretches to
                   // fill the bar (gh#165). A form field that wants a full-width control passes
                   // `className="w-full"`, which wins over `w-auto`.
-                  cn("w-auto max-w-full", TRIGGER_WIDTH[kind])
+                  // `compact` drops the per-kind width entirely so the trigger hugs its value.
+                  cn("w-auto max-w-full", !isCompact && TRIGGER_WIDTH[kind])
                 ),
+                // Compact re-tiers the box through tokens (--app-setting-picker-compact-*); the height
+                // still comes from the official --control-height-sm tier, never a literal. The gap is a
+                // utility (not the class rule) so it beats SelectTrigger's own `gap-2`.
+                isCompact && "ui-app-setting-picker-compact gap-[length:var(--app-setting-picker-compact-gap)]",
                 className
               ),
               "aria-label": t(ARIA_KEY[kind]),
               children: [
-                /* @__PURE__ */ jsx(
+                inline ? null : /* @__PURE__ */ jsx(
                   Icon,
                   {
-                    className: cn("size-4 shrink-0 opacity-70", !iconOnly && "me-2"),
+                    className: cn(
+                      "size-4 shrink-0 opacity-70",
+                      // Compact relies on the trigger's tokenized flex gap instead of an icon margin.
+                      !iconOnly && !isCompact && "me-2"
+                    ),
                     "aria-hidden": "true"
                   }
                 ),

package/dist/components/navigation/filter-bar.d.ts

@@ -1,4 +1,13 @@
 import type { ToolbarGroupProp, ToolbarProp } from "../../props/components/navigation.prop.js";
-export type { ToolbarGroupProp, ToolbarGroupProp as ToolbarGroupProps, ToolbarProp, ToolbarProp as ToolbarProps, } from "../../props/components/navigation.prop.js";
-export declare function Toolbar({ onClear, hasActiveFilters, sticky, className, children, }: ToolbarProp): import("react").JSX.Element;
-export declare function ToolbarGroup({ label, className, children }: ToolbarGroupProp): import("react").JSX.Element;
+export type { FilterBarOverflowProp, ToolbarGroupProp, ToolbarGroupProp as ToolbarGroupProps, ToolbarGroupProp as FilterBarGroupProp, ToolbarGroupProp as FilterBarGroupProps, ToolbarProp, ToolbarProp as ToolbarProps, ToolbarProp as FilterBarProp, ToolbarProp as FilterBarProps, } from "../../props/components/navigation.prop.js";
+export declare function Toolbar({ onClear, hasActiveFilters, sticky, overflow, className, children, }: ToolbarProp): import("react").JSX.Element;
+export declare function ToolbarGroup({ label, controlId, className, children }: ToolbarGroupProp): import("react").JSX.Element;
+/**
+ * Canonical list-page filter strip.
+ *
+ * `Toolbar` remains available for backwards compatibility. `FilterBar` is the
+ * public domain-neutral name used by application design specifications.
+ */
+export declare const FilterBar: typeof Toolbar;
+/** Labelled control group for {@link FilterBar}. */
+export declare const FilterBarGroup: typeof ToolbarGroup;

package/dist/components/navigation/filter-bar.js

@@ -9,6 +9,7 @@ function Toolbar({
   onClear,
   hasActiveFilters = true,
   sticky = false,
+  overflow = "wrap",
   className,
   children
 }) {
@@ -18,6 +19,7 @@ function Toolbar({
     {
       role: "toolbar",
       "aria-label": t("navigation.toolbar.ariaLabel"),
+      "data-overflow": overflow,
       className: cn("ui-toolbar", sticky && "ui-toolbar-sticky", className),
       children: [
         children,
@@ -29,7 +31,7 @@ function Toolbar({
     }
   );
 }
-function ToolbarGroup({ label, className, children }) {
+function ToolbarGroup({ label, controlId, className, children }) {
   const labelId = useId();
   return /* @__PURE__ */ jsxs(
     "div",
@@ -38,13 +40,17 @@ function ToolbarGroup({ label, className, children }) {
       "aria-labelledby": label ? labelId : void 0,
       className: cn("ui-stack-xs ui-toolbar-group", className),
       children: [
-        label ? /* @__PURE__ */ jsx("div", { id: labelId, className: "ui-toolbar-label", children: label }) : null,
+        label ? controlId ? /* @__PURE__ */ jsx("label", { id: labelId, htmlFor: controlId, className: "ui-toolbar-label", children: label }) : /* @__PURE__ */ jsx("div", { id: labelId, className: "ui-toolbar-label", children: label }) : null,
         children
       ]
     }
   );
 }
+const FilterBar = Toolbar;
+const FilterBarGroup = ToolbarGroup;
 export {
+  FilterBar,
+  FilterBarGroup,
   Toolbar,
   ToolbarGroup
 };

package/dist/components/navigation/index.d.ts

@@ -4,8 +4,8 @@ export { Pagination, PaginationContent, PaginationItem, PaginationLink, Paginati
 export { Menubar, MenubarCheckboxItem, MenubarContent, MenubarItem, MenubarLabel, MenubarMenu, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, } from "./menubar.js";
 export { NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, } from "./navigation-menu.js";
 export { Steps } from "./steps.js";
-export { Toolbar, ToolbarGroup } from "./filter-bar.js";
-export type { ToolbarGroupProps, ToolbarProps } from "./filter-bar.js";
+export { FilterBar, FilterBarGroup, Toolbar, ToolbarGroup } from "./filter-bar.js";
+export type { FilterBarGroupProp, FilterBarGroupProps, FilterBarProp, FilterBarProps, ToolbarGroupProps, ToolbarProps, } from "./filter-bar.js";
 export { AppSettingPicker } from "./app-setting-picker.js";
 export type { AppSettingPickerProp, AppSettingPickerProps, AppSettingKind, } from "./app-setting-picker.js";
 export type { BreadcrumbItemProp as BreadcrumbItem } from "../../props/vocabulary/navigation.prop.js";

package/dist/components/navigation/index.js

@@ -51,7 +51,7 @@ import {
   NavigationMenuViewport
 } from "./navigation-menu.js";
 import { Steps } from "./steps.js";
-import { Toolbar, ToolbarGroup } from "./filter-bar.js";
+import { FilterBar, FilterBarGroup, Toolbar, ToolbarGroup } from "./filter-bar.js";
 import { AppSettingPicker } from "./app-setting-picker.js";
 import {
   DropdownMenu,
@@ -101,6 +101,8 @@ export {
   DropdownMenuSubContent,
   DropdownMenuSubTrigger,
   DropdownMenuTrigger,
+  FilterBar,
+  FilterBarGroup,
   Menubar,
   MenubarCheckboxItem,
   MenubarContent,