@womp/kookie-ui 0.24.0 → 0.25.1

package/src/components/shell.tsx

@@ -27,8 +27,11 @@ import { useComposedRefs } from 'radix-ui/internal';
 import { PaneResizeContext } from './_internal/shell-resize.js';
 import { PaneHandle, PanelHandle } from './_internal/shell-handles.js';
 import { Sidebar } from './_internal/shell-sidebar.js';
+import type { SidebarPublicProps } from './_internal/shell-sidebar.js';
 import { Bottom } from './_internal/shell-bottom.js';
+import type { BottomPublicProps } from './_internal/shell-bottom.js';
 import { Inspector } from './_internal/shell-inspector.js';
+import type { InspectorPublicProps } from './_internal/shell-inspector.js';
 import { usePane, paneAttributes, usePresentationTable } from './_internal/shell-pane.js';
 import { splitHandles, useResizablePane } from './_internal/shell-resizable.js';
 import {
@@ -48,9 +51,9 @@ import { navigationRest, detailRest, toPaneValue, startAnchoredGrowth, withoutRe
 import { useShell, useSidebarMode } from './shell.context.js';
 import { useResponsivePresentation } from './shell.hooks.js';
 import { readBreakpoint } from '../hooks/use-breakpoint.js';
-import { useThemeSize } from '../helpers/theme-size.js';
+import { useThemeSize } from '../hooks/theme-size.js';
 import { PaneChromeScope, PaneFooter, PaneHeader, Scroll, ShellContentContext, ShellSizeContext } from './_internal/pane-chrome.js';
-import type { PaneSize } from './_internal/pane-chrome.js';
+import type { PaneSize, PaneHeaderProps, PaneFooterProps, ScrollProps } from './_internal/pane-chrome.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, PaneMode, PaneName, PaneTarget, ResponsivePresentation, SidebarMode } from './shell.types.js';
 
 /* ── Root ──────────────────────────────────────────────────────────────────── */
@@ -487,6 +490,7 @@ const Rail = React.forwardRef<HTMLDivElement, RailProps>((props, ref) => {
   return (
     <div
       {...domProps}
+      role={domProps.role ?? 'navigation'}
       id={pane.id}
       ref={composedRef}
       className={classNames('kui-ShellPane', 'kui-ShellRail', className)}
@@ -652,6 +656,7 @@ const Panel = React.forwardRef<HTMLDivElement, PanelPublicProps>((props, ref) =>
   return (
     <div
       {...withoutRemovedPaneProps(domProps)}
+      role={domProps.role ?? 'navigation'}
       id={pane.id}
       ref={composedRef}
       className={classNames('kui-ShellPane', 'kui-ShellPanel', className)}
@@ -806,4 +811,16 @@ export {
   type ResponsivePresentation,
   type PaneTarget,
   type TriggerAction,
+  type ShellRootProps as RootProps,
+  type ShellHeaderProps as HeaderProps,
+  type RailProps,
+  type PanelPublicProps as PanelProps,
+  type SidebarPublicProps as SidebarProps,
+  type ShellContentProps as ContentProps,
+  type InspectorPublicProps as InspectorProps,
+  type BottomPublicProps as BottomProps,
+  type TriggerProps,
+  type PaneHeaderProps,
+  type PaneFooterProps,
+  type ScrollProps,
 };

package/src/components/sidebar.css

@@ -198,18 +198,6 @@
   flex-shrink: 0;
 }
 
-/* Ensure submenu anchors also truncate */
-:where(.kui-ShellRailContent .kui-SidebarMenuSubContent .kui-SidebarMenuButton > *) {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  width: 100%;
-  min-width: 0;
-}
-
 /* Ensure icons remain visible at their token sizes in thin mode */
 /* stylelint-disable-next-line selector-max-type */
 :where(.kui-ShellRailContent .kui-SidebarMenuButton) :where(svg) {
@@ -316,53 +304,12 @@
   display: none !important;
 }
 
-/* Hide submenu chevrons and flatten sublists in rail */
+/* Hide submenu chevrons in rail */
 :where(.kui-ShellRailContent .kui-SidebarMenuSubTriggerIcon),
 :where(.kui-ShellRailContent .kui-BaseMenuSubTriggerIcon) {
   display: none !important;
 }
 
-:where(.kui-ShellRailContent .kui-SidebarMenuSubList),
-:where(.kui-ShellRailContent .kui-BaseMenuSubList) {
-  padding-left: 0 !important;
-  margin-left: 0 !important;
-  border-left: 0 !important;
-  border-top: 0 !important;
-  border-bottom: 0 !important;
-  margin-top: 0 !important;
-  margin-bottom: 0 !important;
-}
-
-/* Also remove any decorative rule on the submenu list in thin mode */
-:where(.kui-ShellRailContent .kui-SidebarMenuSubList::before),
-:where(.kui-ShellRailContent .kui-BaseMenuSubList::before) {
-  content: none !important;
-  display: none !important;
-}
-
-/* Ensure the Accordion content wrapper doesn't add indentation */
-:where(.kui-ShellRailContent .kui-SidebarMenuSubContent) {
-  padding-left: 0 !important;
-  margin-left: 0 !important;
-  border-left: 0 !important;
-  border-top: 1px solid var(--neutral-a6) !important;
-  border-bottom: 1px solid var(--neutral-a6) !important;
-  margin-top: var(--space-3) !important;
-  margin-bottom: var(--space-3) !important;
-  /* background-color: var(--accent-3); */
-}
-
-/* Remove vertical connector in thin mode */
-/* (intentionally no ::before) */
-
-/* Ensure submenu buttons also truncate */
-:where(.kui-ShellRailContent .kui-SidebarMenuSubContent .kui-SidebarMenuButton) {
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  max-width: 100%;
-}
-
 /* Panel Layout Styling (default) - inherits existing styles */
 
 /* Label truncation in expanded mode - prevents horizontal scrollbar on long names */
@@ -406,87 +353,6 @@
   }
 }
 
-/* Flex utilities for header/footer layouts */
-.kui-SidebarHeader:where(.kui-flex-row) {
-  flex-direction: row;
-}
-.kui-SidebarHeader:where(.kui-flex-col) {
-  flex-direction: column;
-}
-.kui-SidebarHeader:where(.kui-items-center) {
-  align-items: center;
-}
-.kui-SidebarHeader:where(.kui-items-start) {
-  align-items: flex-start;
-}
-.kui-SidebarHeader:where(.kui-items-end) {
-  align-items: flex-end;
-}
-.kui-SidebarHeader:where(.kui-justify-between) {
-  justify-content: space-between;
-}
-.kui-SidebarHeader:where(.kui-justify-center) {
-  justify-content: center;
-}
-.kui-SidebarHeader:where(.kui-justify-start) {
-  justify-content: flex-start;
-}
-.kui-SidebarHeader:where(.kui-justify-end) {
-  justify-content: flex-end;
-}
-.kui-SidebarHeader:where(.kui-gap-1) {
-  gap: var(--space-2);
-}
-.kui-SidebarHeader:where(.kui-gap-2) {
-  gap: var(--space-3);
-}
-.kui-SidebarHeader:where(.kui-gap-3) {
-  gap: var(--space-4);
-}
-.kui-SidebarHeader:where(.kui-gap-4) {
-  gap: var(--space-5);
-}
-
-.kui-SidebarFooter:where(.kui-flex-row) {
-  flex-direction: row;
-}
-.kui-SidebarFooter:where(.kui-flex-col) {
-  flex-direction: column;
-}
-.kui-SidebarFooter:where(.kui-items-center) {
-  align-items: center;
-}
-.kui-SidebarFooter:where(.kui-items-start) {
-  align-items: flex-start;
-}
-.kui-SidebarFooter:where(.kui-items-end) {
-  align-items: flex-end;
-}
-.kui-SidebarFooter:where(.kui-justify-between) {
-  justify-content: space-between;
-}
-.kui-SidebarFooter:where(.kui-justify-center) {
-  justify-content: center;
-}
-.kui-SidebarFooter:where(.kui-justify-start) {
-  justify-content: flex-start;
-}
-.kui-SidebarFooter:where(.kui-justify-end) {
-  justify-content: flex-end;
-}
-.kui-SidebarFooter:where(.kui-gap-1) {
-  gap: var(--space-2);
-}
-.kui-SidebarFooter:where(.kui-gap-2) {
-  gap: var(--space-3);
-}
-.kui-SidebarFooter:where(.kui-gap-3) {
-  gap: var(--space-4);
-}
-.kui-SidebarFooter:where(.kui-gap-4) {
-  gap: var(--space-5);
-}
-
 /* Header/Footer Menu Button Support */
 .kui-SidebarHeader :where(.kui-SidebarMenuButton),
 .kui-SidebarFooter :where(.kui-SidebarMenuButton) {

package/src/components/sidebar.tsx

@@ -11,7 +11,7 @@ import { Separator } from './separator.js';
 import { ThickChevronRightIcon } from './icons.js';
 import { Kbd } from './kbd.js';
 import { Chip } from './chip.js';
-import { useSidebarVisual } from './_internal/pane-chrome.js';
+import { ShellSizeContext, useSidebarVisual } from './_internal/pane-chrome.js';
 
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
 import type { ChipProps } from './chip.js';
@@ -56,45 +56,53 @@ interface SidebarMenuButtonProps extends React.ComponentPropsWithoutRef<'button'
   badge?: string | BadgeConfig;
 }
 
-// Extracted to module scope to avoid re-creation on every render
+// The name a component type goes by: a function, or the function inside forwardRef or memo.
+function componentName(type: unknown): string | undefined {
+  if (typeof type === 'function') {
+    const fn = type as { displayName?: string; name?: string };
+    return fn.displayName || fn.name;
+  }
+  if (type && typeof type === 'object') {
+    const wrapped = type as { displayName?: string; render?: unknown; type?: unknown };
+    return wrapped.displayName || componentName(wrapped.render) || componentName(wrapped.type);
+  }
+  return undefined;
+}
+
+function isIconElement(el: React.ReactElement<{ icon?: unknown }>): boolean {
+  if (el.type === 'svg') return true;
+  if (el.props?.icon) return true;
+  return componentName(el.type)?.includes('Icon') ?? false;
+}
+
+function isText(node: React.ReactNode): node is string | number {
+  return typeof node === 'string' || typeof node === 'number';
+}
+
+// Thin mode puts the row's icon in a wrapper that carries the hover and active tile. An icon is
+// an svg, a HugeiconsIcon, or a component named *Icon. Failing that, the first element ahead of
+// other content is taken as the icon (Lucide and other icon sets).
 function separateIconsAndLabels(node: React.ReactNode): { icons: React.ReactNode[]; labels: React.ReactNode[] } {
+  const children = React.Children.toArray(node);
   const icons: React.ReactNode[] = [];
   const labels: React.ReactNode[] = [];
 
-  React.Children.forEach(node, (child) => {
-    if (typeof child === 'string' || typeof child === 'number') {
-      labels.push(<span key={labels.length} className="kui-SidebarMenuLabel">{child}</span>);
-    } else if (React.isValidElement(child)) {
-      const el = child as React.ReactElement<any>;
-      if (el.type === 'svg' || (el.props && el.props.icon) || (typeof el.type === 'function' && ((el.type as any).displayName?.includes('Icon') || (el.type as any).name?.includes('Icon')))) {
-        icons.push(child);
-      } else {
-        labels.push(child);
-      }
-    } else if (child) {
-      labels.push(child);
-    }
-  });
+  for (const child of children) {
+    if (React.isValidElement<{ icon?: unknown }>(child) && isIconElement(child)) icons.push(child);
+    else labels.push(isText(child) ? <span key={labels.length} className="kui-SidebarMenuLabel">{child}</span> : child);
+  }
+
+  if (icons.length === 0 && children.length > 1 && React.isValidElement(children[0])) {
+    icons.push(children[0]);
+    labels.shift();
+  }
 
   return { icons, labels };
 }
 
+// Wraps the row's own text in a label span. Text inside the caller's elements is left alone.
 function wrapTextNodes(node: React.ReactNode): React.ReactNode {
-  if (typeof node === 'string' || typeof node === 'number') {
-    return <span className="kui-SidebarMenuLabel">{node}</span>;
-  }
-  if (Array.isArray(node)) {
-    return node.map((child, index) => <React.Fragment key={index}>{wrapTextNodes(child)}</React.Fragment>);
-  }
-  if (React.isValidElement(node)) {
-    const el = node as React.ReactElement<any>;
-    const className: string = (el.props && (el.props as any).className) || '';
-    const isAlreadyLabel = typeof el.type === 'string' && className.split(' ').includes('kui-SidebarMenuLabel');
-    if (isAlreadyLabel) return el;
-    const newChildren = wrapTextNodes((el.props as any)?.children);
-    return React.cloneElement(el, { ...(el.props as any) }, newChildren);
-  }
-  return node;
+  return React.Children.map(node, (child) => (isText(child) ? <span className="kui-SidebarMenuLabel">{child}</span> : child));
 }
 
 // Arrow Up and Down move between the visible buttons of the same sidebar, as a
@@ -117,68 +125,77 @@ function focusAdjacentSidebarButton(event: React.KeyboardEvent<HTMLElement>) {
 const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenuButtonProps>(
   ({ asChild = false, isActive = false, shortcut, badge, className, children, onKeyDown, ...props }, forwardedRef) => {
     const visual = useSidebarVisual();
-    const sidebarSize = visual?.size ?? '2';
+    // A pane with no scope (Inspector, Bottom) still takes the Shell's index.
+    const shellSize = React.useContext(ShellSizeContext);
+    const sidebarSize = visual?.size ?? shellSize;
     const isThinMode = visual?.presentation === 'thin';
 
     const Comp = asChild ? Slot : 'button';
 
-    // Enter and Space are left to the native button or link.
-    const handleKeyDown = React.useCallback(
-      (event: React.KeyboardEvent<HTMLButtonElement>) => {
-        focusAdjacentSidebarButton(event);
-        onKeyDown?.(event);
-      },
-      [onKeyDown],
-    );
-
-    // Memoize child processing to avoid re-traversal on every render
-    const processedChildren = React.useMemo(() => wrapTextNodes(children), [children]);
+    // Enter and Space are left to the native button or link. The caller's handler runs first,
+    // so it can preventDefault to keep the arrow keys for itself.
+    const handleKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
+      onKeyDown?.(event);
+      if (!event.defaultPrevented) focusAdjacentSidebarButton(event);
+    };
 
-    // For thin mode, separate icons into a wrapper for targeted background styling
-    const { icons, labels } = React.useMemo(
-      () => isThinMode ? separateIconsAndLabels(children) : { icons: [] as React.ReactNode[], labels: [] as React.ReactNode[] },
-      [isThinMode, children],
+    const extras = isThinMode ? null : (
+      <>
+        {badge && (
+          <div className="kui-SidebarMenuBadge">
+            {typeof badge === 'string' ? (
+              <Chip size={sidebarSize} variant="soft">
+                {badge}
+              </Chip>
+            ) : (
+              <Chip size={badge.size || sidebarSize} variant={badge.variant || 'soft'} color={badge.color} radius={badge.radius}>
+                {badge.content}
+              </Chip>
+            )}
+          </div>
+        )}
+        {shortcut && (
+          <div className="kui-BaseMenuShortcut kui-SidebarMenuShortcut">
+            <Kbd size={sidebarSize}>{shortcut}</Kbd>
+          </div>
+        )}
+      </>
     );
 
-    // When rendering asChild, Slot expects a single child element. We still want to
-    // append optional badge/shortcut inside that element so they render with Link.
-    const slottedChildren = React.useMemo(() => {
-      if (!asChild) return null;
-      try {
-        const onlyChild = React.Children.only(processedChildren as React.ReactElement<any>) as React.ReactElement<any>;
-        const originalInnerChildren = (onlyChild.props as any)?.children;
-        const enhancedInnerChildren = (
-          <>
-            {originalInnerChildren}
-            {badge && (
-              <div className="kui-SidebarMenuBadge">
-                {typeof badge === 'string' ? (
-                  <Chip size={sidebarSize} variant="soft">
-                    {badge}
-                  </Chip>
-                ) : (
-                  <Chip size={badge.size || sidebarSize} variant={badge.variant || 'soft'} color={badge.color} radius={badge.radius}>
-                    {badge.content}
-                  </Chip>
-                )}
-              </div>
-            )}
-            {shortcut && (
-              <div className="kui-BaseMenuShortcut kui-SidebarMenuShortcut">
-                <Kbd size={sidebarSize}>{shortcut}</Kbd>
-              </div>
-            )}
-          </>
-        );
-        return React.cloneElement(onlyChild, { ...(onlyChild.props as any) }, enhancedInnerChildren);
-      } catch {
-        // Fallback: if multiple children were passed incorrectly, just return processedChildren
-        return processedChildren as React.ReactNode;
+    const renderContent = (content: React.ReactNode): React.ReactNode => {
+      if (isThinMode) {
+        const { icons, labels } = separateIconsAndLabels(content);
+        if (icons.length > 0) {
+          return (
+            <>
+              <span className="kui-SidebarMenuIconWrapper">{icons}</span>
+              {labels}
+            </>
+          );
+        }
       }
-    }, [asChild, processedChildren, badge, shortcut, sidebarSize]);
+      return (
+        <>
+          {wrapTextNodes(content)}
+          {extras}
+        </>
+      );
+    };
+
+    // When rendering asChild, Slot expects a single child element. The row's content goes
+    // inside that element, so a Link gets the label, icon tile, badge and shortcut.
+    let body: React.ReactNode;
+    if (asChild && React.isValidElement<{ children?: React.ReactNode }>(children) && React.Children.count(children) === 1) {
+      body = React.cloneElement(children, undefined, renderContent(children.props.children));
+    } else if (asChild) {
+      body = children;
+    } else {
+      body = renderContent(children);
+    }
 
     return (
       <Comp
+        type={asChild ? undefined : 'button'}
         {...props}
         ref={forwardedRef}
         aria-current={isActive ? 'page' : undefined}
@@ -186,44 +203,7 @@ const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenuButtonP
         data-active={isActive || undefined}
         onKeyDown={handleKeyDown}
       >
-        {asChild ? (
-          slottedChildren
-        ) : isThinMode && icons.length > 0 ? (
-          <>
-            <span className="kui-SidebarMenuIconWrapper">{icons}</span>
-            {labels.map((label, index) => (
-              <React.Fragment key={index}>
-                {typeof label === 'string' || typeof label === 'number' ? (
-                  <span className="kui-SidebarMenuLabel">{label}</span>
-                ) : (
-                  label
-                )}
-              </React.Fragment>
-            ))}
-          </>
-        ) : (
-          <>
-            {processedChildren}
-            {badge && (
-              <div className="kui-SidebarMenuBadge">
-                {typeof badge === 'string' ? (
-                  <Chip size={sidebarSize} variant="soft">
-                    {badge}
-                  </Chip>
-                ) : (
-                  <Chip size={badge.size || sidebarSize} variant={badge.variant || 'soft'} color={badge.color} radius={badge.radius}>
-                    {badge.content}
-                  </Chip>
-                )}
-              </div>
-            )}
-            {shortcut && (
-              <div className="kui-BaseMenuShortcut kui-SidebarMenuShortcut">
-                <Kbd size={sidebarSize}>{shortcut}</Kbd>
-              </div>
-            )}
-          </>
-        )}
+        {body}
       </Comp>
     );
   },
@@ -319,77 +299,127 @@ SidebarMenuSubTrigger.displayName = 'Sidebar.MenuSubTrigger';
 
 interface SidebarMenuSubContentProps extends React.ComponentPropsWithoutRef<typeof Accordion.Content> {}
 
+// In a Rail a sub-menu is a dropdown. Each row becomes a menu item: a MenuButton hands the item
+// its props (onClick, disabled, active), and an asChild one hands it its link.
+function toDropdownItem(node: React.ReactNode, key: React.Key): React.ReactNode {
+  if (React.isValidElement<SidebarMenuButtonProps>(node) && node.type === SidebarMenuButton) {
+    // The badge and shortcut have no place in a dropdown row; `type` belongs to a button only.
+    const { asChild, isActive, shortcut, badge, type, children, ...rest } = node.props;
+    const itemProps = {
+      ...(rest as Omit<React.ComponentPropsWithoutRef<typeof DropdownMenu.Item>, 'color'>),
+      'data-active': isActive || undefined,
+      'aria-current': isActive ? ('page' as const) : undefined,
+    };
+    if (asChild && React.isValidElement(children) && React.Children.count(children) === 1) {
+      return (
+        <DropdownMenu.Item key={key} {...itemProps} asChild>
+          {children}
+        </DropdownMenu.Item>
+      );
+    }
+    return (
+      <DropdownMenu.Item key={key} {...itemProps}>
+        {children}
+      </DropdownMenu.Item>
+    );
+  }
+  if (React.isValidElement(node)) {
+    return (
+      <DropdownMenu.Item key={key} asChild>
+        {node}
+      </DropdownMenu.Item>
+    );
+  }
+  return <DropdownMenu.Item key={key}>{node}</DropdownMenu.Item>;
+}
+
+// The sub-list is a <ul>, so each row needs its own <li>. A MenuButton written straight into
+// MenuSubContent gets a MenuItem around it, rather than leaving an <a> or <button> in the list.
+function wrapBareMenuButtons(children: React.ReactNode): React.ReactNode {
+  return React.Children.map(children, (child, index) =>
+    React.isValidElement(child) && child.type === SidebarMenuButton ? (
+      <SidebarMenuItem key={child.key ?? index}>{child}</SidebarMenuItem>
+    ) : (
+      child
+    ),
+  );
+}
+
 const SidebarMenuSubContent = React.forwardRef<React.ElementRef<typeof Accordion.Content>, SidebarMenuSubContentProps>(({ className, children, ...props }, forwardedRef) => {
   const visual = useSidebarVisual();
   const mode = React.useContext(SidebarSubMenuModeContext);
 
   if (mode === 'dropdown') {
-    const unwrapMenuButton = (node: React.ReactNode): React.ReactNode => {
-      if (Array.isArray(node)) {
-        return node.map((n, i) => <React.Fragment key={i}>{unwrapMenuButton(n)}</React.Fragment>);
+    const items = React.Children.map(children, (child, index) => {
+      if (React.isValidElement<{ children?: React.ReactNode }>(child) && child.type === SidebarMenuItem) {
+        const rows = React.Children.toArray(child.props.children);
+        return toDropdownItem(rows.length === 1 ? rows[0] : rows, index);
       }
-      if (React.isValidElement(node)) {
-        const typeDisplay = (node.type as any)?.displayName;
-        if (typeDisplay === 'Sidebar.MenuButton') {
-          return (node.props as any)?.children;
-        }
-        const child = (node.props as any)?.children;
-        if (child !== undefined) {
-          return React.cloneElement(node as any, { ...(node.props as any), children: unwrapMenuButton(child) });
-        }
-      }
-      return node;
-    };
-
-    const normalized = React.Children.map(children as React.ReactNode, (child, index) => {
-      if (React.isValidElement(child) && (child.type as any)?.displayName === 'Sidebar.MenuItem') {
-        const itemChildren = (child.props as any)?.children;
-        const content = unwrapMenuButton(itemChildren);
-        return (
-          <DropdownMenu.Item key={index} asChild>
-            {content as any}
-          </DropdownMenu.Item>
-        );
-      }
-      // Fallback: wrap raw nodes too for consistent menu styling
-      return (
-        <DropdownMenu.Item key={index} asChild>
-          {unwrapMenuButton(child) as any}
-        </DropdownMenu.Item>
-      );
+      return toDropdownItem(child, index);
     });
 
     return (
-      <DropdownMenu.Content size={visual?.size} className={classNames(className)}>
-        <DropdownMenu.Group>{normalized}</DropdownMenu.Group>
+      <DropdownMenu.Content
+        {...(props as Omit<React.ComponentPropsWithoutRef<typeof DropdownMenu.Content>, 'color'>)}
+        ref={forwardedRef}
+        size={visual?.size}
+        className={classNames(className)}
+      >
+        <DropdownMenu.Group>{items}</DropdownMenu.Group>
       </DropdownMenu.Content>
     );
   }
 
   return (
     <Accordion.Content {...props} ref={forwardedRef} className={classNames('kui-SidebarMenuSubContent', className)}>
-      <ul className="kui-SidebarMenuSubList">{children}</ul>
+      <ul className="kui-SidebarMenuSubList">{wrapBareMenuButtons(children)}</ul>
     </Accordion.Content>
   );
 });
 SidebarMenuSubContent.displayName = 'Sidebar.MenuSubContent';
 
-// Group components. The label is plain text: no role, so it isn't announced as an empty group.
+// Group components. A group with a label is a named group; one without stays a plain div, so it
+// isn't announced as an empty group.
+type SidebarGroupContextValue = { labelId: string; setLabelId: (id: string | null) => void };
+const SidebarGroupContext = React.createContext<SidebarGroupContextValue | null>(null);
+
 interface SidebarGroupProps extends React.ComponentPropsWithoutRef<'div'> {}
 
-const SidebarGroup = React.forwardRef<HTMLDivElement, SidebarGroupProps>(({ className, ...props }, forwardedRef) => (
-  <div {...props} ref={forwardedRef} className={classNames('kui-BaseMenuGroup', 'kui-SidebarGroup', className)} />
-));
+const SidebarGroup = React.forwardRef<HTMLDivElement, SidebarGroupProps>(({ className, ...props }, forwardedRef) => {
+  const labelId = React.useId();
+  const [renderedLabelId, setLabelId] = React.useState<string | null>(null);
+  const context = React.useMemo(() => ({ labelId, setLabelId }), [labelId]);
+  return (
+    <SidebarGroupContext.Provider value={context}>
+      <div
+        role={renderedLabelId ? 'group' : undefined}
+        aria-labelledby={renderedLabelId ?? undefined}
+        {...props}
+        ref={forwardedRef}
+        className={classNames('kui-BaseMenuGroup', 'kui-SidebarGroup', className)}
+      />
+    </SidebarGroupContext.Provider>
+  );
+});
 SidebarGroup.displayName = 'Sidebar.Group';
 
 interface SidebarGroupLabelProps extends React.ComponentPropsWithoutRef<'div'> {
   asChild?: boolean;
 }
 
-const SidebarGroupLabel = React.forwardRef<HTMLDivElement, SidebarGroupLabelProps>(({ asChild = false, className, ...props }, forwardedRef) => {
+const SidebarGroupLabel = React.forwardRef<HTMLDivElement, SidebarGroupLabelProps>(({ asChild = false, className, id, ...props }, forwardedRef) => {
   const Comp = asChild ? Slot : 'div';
+  const group = React.useContext(SidebarGroupContext);
+  const labelId = id ?? group?.labelId;
+  const setLabelId = group?.setLabelId;
+
+  React.useEffect(() => {
+    if (!setLabelId || !labelId) return;
+    setLabelId(labelId);
+    return () => setLabelId(null);
+  }, [setLabelId, labelId]);
 
-  return <Comp {...props} ref={forwardedRef} className={classNames('kui-BaseMenuLabel', 'kui-SidebarGroupLabel', className)} />;
+  return <Comp {...props} id={labelId} ref={forwardedRef} className={classNames('kui-BaseMenuLabel', 'kui-SidebarGroupLabel', className)} />;
 });
 SidebarGroupLabel.displayName = 'Sidebar.GroupLabel';
 
@@ -455,6 +485,9 @@ const SidebarSearch = React.forwardRef<HTMLDivElement, SidebarSearchProps>(
     // Arrow key navigation within the popover (input ↔ results)
     const handlePopoverKeyDown = React.useCallback(
       (e: React.KeyboardEvent<HTMLDivElement>) => {
+        // A result row already moved focus with its own arrow handling (focusAdjacentSidebarButton
+        // scopes to this popover); moving again would skip a row.
+        if (e.defaultPrevented) return;
         const container = popoverRef.current;
         if (!container) return;