@vvedantb/ui 0.5.3 → 0.6.0

package/shell/src/Sidebar.tsx

@@ -0,0 +1,78 @@
+import { SidebarChromeParts } from "./SidebarChrome";
+import { SidebarIconTooltip } from "./SidebarIconTooltip";
+import {
+  AccountAvatar,
+  AccountBadge,
+  AccountContent,
+  AccountLabel,
+  AccountMenu,
+  AccountSeparator,
+  AccountTrigger,
+} from "./SidebarAccountMenu";
+import { Panel, PanelActions, PanelClose, PanelHeader, PanelTitle } from "./SidebarPanel";
+import { Rail, RailBody, RailFooter, RailHeader, RailItem, RailSeparator } from "./SidebarRail";
+
+export type {
+  SidebarAsideProps,
+  SidebarBackdropProps,
+  SidebarMobileActionsProps,
+  SidebarMobileHeaderProps,
+  SidebarMobileMenuButtonProps,
+  SidebarMobileTitleProps,
+  SidebarResizeHandlePartProps,
+  SidebarRootProps,
+} from "./SidebarChrome";
+export type {
+  SidebarRailBodyProps,
+  SidebarRailFooterProps,
+  SidebarRailHeaderProps,
+  SidebarRailItemProps,
+  SidebarRailRootProps,
+  SidebarRailSeparatorProps,
+} from "./SidebarRail";
+export type {
+  SidebarPanelActionsProps,
+  SidebarPanelCloseProps,
+  SidebarPanelHeaderProps,
+  SidebarPanelRootProps,
+  SidebarPanelTitleProps,
+} from "./SidebarPanel";
+export type {
+  SidebarAccountAvatarProps,
+  SidebarAccountBadgeProps,
+  SidebarAccountContentProps,
+  SidebarAccountLabelProps,
+  SidebarAccountMenuRootProps,
+  SidebarAccountSeparatorProps,
+  SidebarAccountTriggerProps,
+} from "./SidebarAccountMenu";
+
+/**
+ * Composable sidebar parts. `Sidebar.Root` holds the drawer and layout state;
+ * the chrome, rail, panel and account parts read it. See the README
+ * "Composable parts" section for a full shell.
+ */
+export const Sidebar = {
+  ...SidebarChromeParts,
+  Rail,
+  RailHeader,
+  RailBody,
+  RailFooter,
+  /** Alias of `RailFooter`. */
+  Footer: RailFooter,
+  RailItem,
+  RailSeparator,
+  Tooltip: SidebarIconTooltip,
+  Panel,
+  PanelHeader,
+  PanelTitle,
+  PanelActions,
+  PanelClose,
+  AccountMenu,
+  AccountTrigger,
+  AccountAvatar,
+  AccountContent,
+  AccountLabel,
+  AccountSeparator,
+  AccountBadge,
+};

package/shell/src/SidebarAccountMenu.tsx

@@ -1,5 +1,5 @@
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
-import { Button } from "../../src/ui/button";
+import { Button, type ButtonProps } from "../../src/ui/button";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -17,7 +17,7 @@ export type SidebarAccountMenuProps = {
   name: string;
   /** When set, the label shows the name and email on two lines. */
   email?: string;
-  /** Always use the two-line label layout, even without `email`. Default `false`. */
+  /** Legacy (still supported): always use the two-line label layout, even without `email`. Default `false`. */
   stackedLabel?: boolean;
   /** Avatar image. Without it the avatar shows up to two initials of `name`. */
   imageUrl?: string;
@@ -31,14 +31,14 @@ export type SidebarAccountMenuProps = {
   /** Merged onto the menu content after `w-56`. */
   contentClassName?: string;
   /**
-   * Unread dot over the trigger's top-right corner, a sibling of the trigger in
+   * Legacy (still supported): unread dot over the trigger's top-right corner, a sibling of the trigger in
    * a `relative` wrapper. `true` shows it, `false` keeps it mounted at zero
    * opacity so it fades out. Omitted: no wrapper and no dot.
    */
   badge?: boolean;
-  /** Spread onto the trigger `Button` after the defaults (overrides `title`, `aria-label`, …). `className` merges last. */
+  /** Legacy (still supported): spread onto the trigger `Button` after the defaults (overrides `title`, `aria-label`, …). `className` merges last. */
   triggerProps?: Omit<ComponentPropsWithoutRef<typeof Button>, "children" | "asChild">;
-  /** Spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`. Use `contentClassName` for classes. */
+  /** Legacy (still supported): spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`. Use `contentClassName` for classes. */
   contentProps?: Omit<
     ContentProps,
     "children" | "className" | "align" | "side" | "sideOffset" | "collisionPadding"
@@ -47,35 +47,7 @@ export type SidebarAccountMenuProps = {
   children?: ReactNode;
 };
 
-function AccountAvatar({ src, name, className }: { src?: string; name: string; className: string }) {
-  if (src) {
-    return (
-      <img
-        src={src}
-        alt=""
-        className={cn(className, "rounded-full object-cover outline outline-1 -outline-offset-1 outline-separator")}
-      />
-    );
-  }
-  const initials = name
-    .split(/\s+/)
-    .filter(Boolean)
-    .slice(0, 2)
-    .map((part) => part[0]?.toUpperCase() ?? "")
-    .join("");
-  return (
-    <span
-      className={cn(
-        "flex items-center justify-center rounded-full bg-surface-tertiary text-[10px] font-medium text-foreground outline outline-1 -outline-offset-1 outline-separator",
-        className,
-      )}
-    >
-      {initials || "?"}
-    </span>
-  );
-}
-
-/** Account menu on a rail tile: avatar trigger, identity label, then the app's items. */
+/** Account menu on a rail tile: avatar trigger, identity label, then the app's items. Composed from `Sidebar.Account*` parts. */
 export function SidebarAccountMenu({
   name,
   email,
@@ -91,66 +63,186 @@ export function SidebarAccountMenu({
   contentProps,
   children,
 }: SidebarAccountMenuProps) {
-  const menu = (
-    <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <Button
-          type="button"
-          variant="ghost"
-          title={name}
-          aria-label={`Account menu for ${name}`}
-          {...triggerProps}
-          className={cn(
-            railTileClass,
-            "h-11 w-11 p-0",
-            railTileStateClass(false),
-            triggerProps?.className,
-          )}
-        >
-          <AccountAvatar src={imageUrl} name={name} className="h-7 w-7" />
-        </Button>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent
+  return (
+    <AccountMenu badge={badge}>
+      <AccountTrigger {...triggerProps} userName={name} imageUrl={imageUrl} />
+      <AccountContent
         {...contentProps}
         align={align}
         side={side}
         sideOffset={sideOffset}
         collisionPadding={collisionPadding}
-        className={cn("w-56", contentClassName)}
+        className={contentClassName}
       >
-        <DropdownMenuLabel className="flex items-center gap-2 font-normal normal-case tracking-normal">
-          <AccountAvatar src={imageUrl} name={name} className="h-6 w-6 shrink-0" />
-          {stackedLabel || email ? (
-            <span className="min-w-0">
-              <span className="block truncate text-sm font-medium text-foreground">{name}</span>
-              {email ? <span className={accountEmailClass}>{email}</span> : null}
-            </span>
-          ) : (
-            <span className="truncate text-sm font-medium text-foreground">{name}</span>
-          )}
-        </DropdownMenuLabel>
-        <DropdownMenuSeparator />
+        <AccountLabel userName={name} email={email} imageUrl={imageUrl} stacked={stackedLabel} />
+        <AccountSeparator />
         {children}
-      </DropdownMenuContent>
-    </DropdownMenu>
+      </AccountContent>
+    </AccountMenu>
   );
+}
+
+export type SidebarAccountMenuRootProps = ComponentPropsWithoutRef<typeof DropdownMenu> & {
+  /**
+   * Unread dot over the trigger's top-right corner (`AccountBadge`), a sibling
+   * of the trigger in a `relative` wrapper. `true` shows it, `false` keeps it
+   * mounted at zero opacity so it fades out. Omitted: no wrapper and no dot.
+   */
+  badge?: boolean;
+};
+
+/** Dropdown menu root. Holds `AccountTrigger` and `AccountContent`. */
+export function AccountMenu({ badge, ...props }: SidebarAccountMenuRootProps) {
+  const menu = <DropdownMenu {...props} />;
   if (badge === undefined) return menu;
   // Sibling of the trigger, so its opacity and press scale do not reach the dot.
   return (
     <div className="relative">
       {menu}
-      <span
-        aria-hidden="true"
-        data-account-badge=""
-        className={cn(
-          "pointer-events-none absolute right-0 top-0 h-2.5 w-2.5 rounded-full border-2 border-background bg-danger transition-opacity duration-150 ease-out",
-          badge ? "opacity-100" : "opacity-0",
-        )}
-      />
+      <AccountBadge visible={badge} />
     </div>
   );
 }
 
+export type SidebarAccountBadgeProps = Omit<ComponentPropsWithoutRef<"span">, "children"> & {
+  /** `false` keeps the dot mounted at zero opacity so it fades out. Default `true`. */
+  visible?: boolean;
+};
+
+/** Unread dot for the top-right corner of a `relative` parent. */
+export function AccountBadge({ visible = true, className, ...props }: SidebarAccountBadgeProps) {
+  return (
+    <span
+      aria-hidden="true"
+      data-account-badge=""
+      {...props}
+      className={cn(
+        "pointer-events-none absolute right-0 top-0 h-2.5 w-2.5 rounded-full border-2 border-background bg-danger transition-opacity duration-150 ease-out",
+        visible ? "opacity-100" : "opacity-0",
+        className,
+      )}
+    />
+  );
+}
+
+export type SidebarAccountAvatarProps = {
+  userName: string;
+  /** Without it the avatar shows up to two initials of `userName`. */
+  imageUrl?: string;
+  /** Size classes, for example `h-7 w-7`. */
+  className?: string;
+};
+
+/** Round avatar image, or up to two initials of `userName`. */
+export function AccountAvatar({ imageUrl, userName, className }: SidebarAccountAvatarProps) {
+  if (imageUrl) {
+    return (
+      <img
+        src={imageUrl}
+        alt=""
+        className={cn(className, "rounded-full object-cover outline outline-1 -outline-offset-1 outline-separator")}
+      />
+    );
+  }
+  const initials = userName
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase() ?? "")
+    .join("");
+  return (
+    <span
+      className={cn(
+        "flex items-center justify-center rounded-full bg-surface-tertiary text-[10px] font-medium text-foreground outline outline-1 -outline-offset-1 outline-separator",
+        className,
+      )}
+    >
+      {initials || "?"}
+    </span>
+  );
+}
+
+export type SidebarAccountTriggerProps = Omit<ButtonProps, "asChild"> & {
+  /** Default `title` and `aria-label`, and the avatar initials. Native `name` goes to the button. */
+  userName: string;
+  imageUrl?: string;
+};
+
+/** Rail-tile-sized avatar button that opens the menu. Children replace the avatar. */
+export function AccountTrigger({ userName, imageUrl, className, children, ...props }: SidebarAccountTriggerProps) {
+  return (
+    <DropdownMenuTrigger asChild>
+      <Button
+        type="button"
+        variant="ghost"
+        title={userName}
+        aria-label={`Account menu for ${userName}`}
+        {...props}
+        className={cn(railTileClass, "h-11 w-11 p-0", railTileStateClass(false), className)}
+      >
+        {children ?? <AccountAvatar imageUrl={imageUrl} userName={userName} className="h-7 w-7" />}
+      </Button>
+    </DropdownMenuTrigger>
+  );
+}
+
+export type SidebarAccountContentProps = ContentProps;
+
+/** Menu content. Defaults: `align="center"`, `side="right"`, `sideOffset={8}`, `w-56`. */
+export function AccountContent({
+  align = "center",
+  side = "right",
+  sideOffset = 8,
+  className,
+  ...props
+}: SidebarAccountContentProps) {
+  return (
+    <DropdownMenuContent
+      {...props}
+      align={align}
+      side={side}
+      sideOffset={sideOffset}
+      className={cn("w-56", className)}
+    />
+  );
+}
+
+export type SidebarAccountLabelProps = Omit<ComponentPropsWithoutRef<typeof DropdownMenuLabel>, "children"> & {
+  userName: string;
+  /** Shown under the name. */
+  email?: string;
+  imageUrl?: string;
+  /** Two-line layout even without `email`. Default `false`. */
+  stacked?: boolean;
+};
+
+/** Identity label: small avatar, name and optional email. Follow it with `AccountSeparator`. */
+export function AccountLabel({ userName, email, imageUrl, stacked = false, className, ...props }: SidebarAccountLabelProps) {
+  return (
+    <DropdownMenuLabel
+      {...props}
+      className={cn("flex items-center gap-2 font-normal normal-case tracking-normal", className)}
+    >
+      <AccountAvatar imageUrl={imageUrl} userName={userName} className="h-6 w-6 shrink-0" />
+      {stacked || email ? (
+        <span className="min-w-0">
+          <span className="block truncate text-sm font-medium text-foreground">{userName}</span>
+          {email ? <span className={accountEmailClass}>{email}</span> : null}
+        </span>
+      ) : (
+        <span className="truncate text-sm font-medium text-foreground">{userName}</span>
+      )}
+    </DropdownMenuLabel>
+  );
+}
+
+export type SidebarAccountSeparatorProps = ComponentPropsWithoutRef<typeof DropdownMenuSeparator>;
+
+/** Separator between the label and the items. */
+export function AccountSeparator(props: SidebarAccountSeparatorProps) {
+  return <DropdownMenuSeparator {...props} />;
+}
+
 export type SidebarAccountMenuPlaceholderProps = { className?: string };
 
 /** Tile-sized placeholder while the account loads. */

package/shell/src/SidebarChrome.tsx

@@ -0,0 +1,295 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  type ComponentProps,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
+import { AnimatePresence, motion, type HTMLMotionProps, type PanInfo } from "motion/react";
+import { IconMenu2 } from "@tabler/icons-react";
+import { Button, type ButtonProps } from "../../src/ui/button";
+import { motionEase, motionTiming } from "../../src/motion/presets";
+import { cn } from "../../src/utils/cn";
+import { mobileMenuButtonClass } from "./app-shell-classes";
+import { SidebarResizeHandle, useSidebarResizeContext, type SidebarResizeHandleProps } from "./SidebarResize";
+
+type SidebarContextValue = {
+  isDesktop: boolean;
+  mobileOpen: boolean;
+  onMobileOpenChange: (open: boolean) => void;
+  collapsed: boolean;
+  panelHidden: boolean;
+  drawerId: string;
+};
+
+const SidebarContext = createContext<SidebarContextValue | null>(null);
+
+/** The nearest `Sidebar.Root`, or `null`. */
+export function useOptionalSidebar(): SidebarContextValue | null {
+  return useContext(SidebarContext);
+}
+
+function useSidebar(part: string): SidebarContextValue {
+  const sidebar = useContext(SidebarContext);
+  if (!sidebar) throw new Error(`Sidebar.${part} must be inside Sidebar.Root`);
+  return sidebar;
+}
+
+export type SidebarRootProps = {
+  /** From the app's desktop media query (for example `(min-width: 768px)`). */
+  isDesktop: boolean;
+  /** Mobile drawer state. Owned by the app (which also closes it on route change). */
+  mobileOpen: boolean;
+  onMobileOpenChange: (open: boolean) => void;
+  /** Desktop: show only the rail. `Sidebar.Panel` hides itself (`md:hidden`). Default `false`. */
+  collapsed?: boolean;
+  /** The current section has no panel: rail-wide on every viewport, `Sidebar.Panel` renders nothing. Default `false`. */
+  panelHidden?: boolean;
+  /** `id` of the drawer (`Sidebar.Aside`), used by the menu button `aria-controls`. Default from `useId`. */
+  id?: string;
+  children?: ReactNode;
+};
+
+/** Sidebar state for the other parts. Renders no DOM. Closes the drawer when the desktop breakpoint is reached. */
+function Root({
+  isDesktop,
+  mobileOpen,
+  onMobileOpenChange,
+  collapsed = false,
+  panelHidden = false,
+  id,
+  children,
+}: SidebarRootProps) {
+  const autoId = useId();
+
+  // Reaching the desktop breakpoint closes the drawer, so it does not reopen
+  // on the way back down. Runs on breakpoint change only.
+  useEffect(() => {
+    if (isDesktop && mobileOpen) onMobileOpenChange(false);
+  }, [isDesktop]);
+
+  return (
+    <SidebarContext.Provider
+      value={{ isDesktop, mobileOpen, onMobileOpenChange, collapsed, panelHidden, drawerId: id ?? autoId }}
+    >
+      {children}
+    </SidebarContext.Provider>
+  );
+}
+
+function closeOnEscape(sidebar: SidebarContextValue, event: KeyboardEvent) {
+  if (event.key === "Escape" && !sidebar.isDesktop && sidebar.mobileOpen) {
+    sidebar.onMobileOpenChange(false);
+  }
+}
+
+export type SidebarMobileHeaderProps = ComponentProps<"header">;
+
+/**
+ * Fixed header below `md`. Escape inside it closes the drawer. Three columns
+ * keep the title centred and stop it overlapping the actions: it truncates instead.
+ */
+function MobileHeader({ className, onKeyDown, ...props }: SidebarMobileHeaderProps) {
+  const sidebar = useSidebar("MobileHeader");
+  return (
+    <header
+      {...props}
+      onKeyDown={(event) => {
+        onKeyDown?.(event);
+        closeOnEscape(sidebar, event);
+      }}
+      className={cn(
+        "fixed inset-x-0 top-0 z-30 grid h-[var(--app-shell-mobile-header-height)] grid-cols-[minmax(max-content,1fr)_minmax(0,auto)_minmax(max-content,1fr)] items-center gap-2 bg-surface px-3 pt-[env(safe-area-inset-top,0px)] pl-[max(0.75rem,env(safe-area-inset-left))] pr-[max(0.75rem,env(safe-area-inset-right))] md:hidden",
+        className,
+      )}
+    />
+  );
+}
+
+const defaultMobileMenuIcon = () => <IconMenu2 size={20} />;
+
+export type SidebarMobileMenuButtonProps = Omit<ButtonProps, "children"> & {
+  /** `aria-label`. Default `"Open navigation menu"`. */
+  label?: string;
+  /** Icon for the drawer state. Default a 20px menu icon. */
+  icon?: (open: boolean) => ReactNode;
+};
+
+/** Opens the drawer. */
+function MobileMenuButton({
+  label = "Open navigation menu",
+  icon = defaultMobileMenuIcon,
+  className,
+  onClick,
+  ...props
+}: SidebarMobileMenuButtonProps) {
+  const sidebar = useSidebar("MobileMenuButton");
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="icon"
+      {...props}
+      onClick={(event) => {
+        onClick?.(event);
+        sidebar.onMobileOpenChange(true);
+      }}
+      aria-label={label}
+      aria-expanded={sidebar.mobileOpen}
+      aria-controls={sidebar.drawerId}
+      className={cn(mobileMenuButtonClass, "justify-self-start", className)}
+    >
+      {icon(sidebar.mobileOpen)}
+    </Button>
+  );
+}
+
+export type SidebarMobileTitleProps = ComponentProps<"h1">;
+
+/** Centred title in the mobile header. Without children, an empty `<span>` keeps the middle column. */
+function MobileTitle({ className, children, ...props }: SidebarMobileTitleProps) {
+  if (!children) return <span aria-hidden="true" />;
+  return (
+    <h1
+      {...props}
+      className={cn(
+        "pointer-events-none min-w-0 truncate text-center text-base font-semibold leading-tight tracking-tight text-foreground",
+        className,
+      )}
+    >
+      {children}
+    </h1>
+  );
+}
+
+export type SidebarMobileActionsProps = ComponentProps<"div">;
+
+/** Trailing actions in the mobile header. Without children, a menu-button-sized spacer keeps the title centred. */
+function MobileActions({ className, children, ...props }: SidebarMobileActionsProps) {
+  if (!children) {
+    return <div {...props} className={cn("h-11 w-11 shrink-0 justify-self-end", className)} aria-hidden="true" />;
+  }
+  return (
+    <div
+      data-app-sidebar-mobile-actions=""
+      {...props}
+      className={cn("flex shrink-0 items-center justify-self-end gap-2", className)}
+    >
+      {children}
+    </div>
+  );
+}
+
+export type SidebarBackdropProps = Omit<HTMLMotionProps<"button">, "children"> & {
+  /** `aria-label`. Default `"Close navigation"`. */
+  label?: string;
+};
+
+/** Drawer backdrop below `md`; a click closes the drawer. Fades in and out. */
+function Backdrop({ label = "Close navigation", className, onClick, ...props }: SidebarBackdropProps) {
+  const sidebar = useSidebar("Backdrop");
+  return (
+    <AnimatePresence initial={false}>
+      {sidebar.mobileOpen && !sidebar.isDesktop ? (
+        <motion.button
+          type="button"
+          aria-label={label}
+          {...props}
+          className={cn("fixed inset-0 z-40 bg-backdrop/80 md:hidden", className)}
+          onClick={(event) => {
+            onClick?.(event);
+            sidebar.onMobileOpenChange(false);
+          }}
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          exit={{ opacity: 0 }}
+          transition={{ duration: motionTiming.sidebar, ease: motionEase }}
+        />
+      ) : null}
+    </AnimatePresence>
+  );
+}
+
+export type SidebarAsideProps = HTMLMotionProps<"aside">;
+
+/**
+ * The `<aside>`: fixed on desktop, a swipe-to-close drawer below it. Width
+ * reads the `--app-shell-*` variables. `id` overrides the Root drawer id
+ * (keep them equal so `aria-controls` points here).
+ */
+function Aside({ id, className, onKeyDown, children, ...props }: SidebarAsideProps) {
+  const sidebar = useSidebar("Aside");
+  const resize = useSidebarResizeContext();
+  const { isDesktop, mobileOpen, collapsed, panelHidden } = sidebar;
+
+  const handleDrawerDragEnd = (_event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => {
+    if (isDesktop || !mobileOpen) return;
+    if (info.offset.x < -72 || info.velocity.x < -500) {
+      sidebar.onMobileOpenChange(false);
+    }
+  };
+
+  return (
+    <motion.aside
+      id={id ?? sidebar.drawerId}
+      data-sidebar-layout={isDesktop ? "desktop" : "drawer"}
+      {...props}
+      inert={!isDesktop && !mobileOpen}
+      onKeyDown={(event) => {
+        onKeyDown?.(event);
+        closeOnEscape(sidebar, event);
+      }}
+      className={cn(
+        "fixed inset-y-0 left-0 z-50 flex bg-background pb-[env(safe-area-inset-bottom,0px)] pt-[env(safe-area-inset-top,0px)] md:py-0",
+        panelHidden
+          ? "w-[var(--app-shell-rail-width)]"
+          : "w-[min(var(--app-shell-sidebar-width),calc(100vw-1.5rem))]",
+        collapsed || panelHidden
+          ? "md:w-[var(--app-shell-rail-width)]"
+          : "md:w-[var(--app-shell-sidebar-width)]",
+        !resize?.isResizing &&
+          "md:transition-[width] md:[transition-duration:280ms] md:[transition-timing-function:cubic-bezier(0.22,1,0.36,1)]",
+        className,
+      )}
+      initial={false}
+      animate={{ x: isDesktop || mobileOpen ? 0 : "-100%" }}
+      transition={{ duration: motionTiming.sidebar, ease: motionEase }}
+      drag={!isDesktop && mobileOpen ? "x" : false}
+      dragDirectionLock
+      dragConstraints={{ left: 0, right: 0 }}
+      dragElastic={{ left: 0.45, right: 0.08 }}
+      onDragEnd={handleDrawerDragEnd}
+    >
+      {children}
+    </motion.aside>
+  );
+}
+
+export type SidebarResizeHandlePartProps = SidebarResizeHandleProps;
+
+/**
+ * `SidebarResizeHandle` inside a resizable `AppShell`. Under a `Sidebar.Root`
+ * it shows only on desktop while the panel shows (not collapsed or hidden).
+ * Place it inside `Sidebar.Aside`.
+ */
+function ResizeHandle(props: SidebarResizeHandlePartProps) {
+  const sidebar = useOptionalSidebar();
+  const resize = useSidebarResizeContext();
+  const show =
+    resize !== null &&
+    (sidebar === null || (sidebar.isDesktop && !sidebar.collapsed && !sidebar.panelHidden));
+  return show ? <SidebarResizeHandle {...props} /> : null;
+}
+
+export const SidebarChromeParts = {
+  Root,
+  MobileHeader,
+  MobileMenuButton,
+  MobileTitle,
+  MobileActions,
+  Backdrop,
+  Aside,
+  ResizeHandle,
+};

package/shell/src/SidebarHeader.tsx

@@ -1,5 +1,7 @@
 import type { ReactNode } from "react";
+import { sidebarHeaderRowClass } from "./app-shell-classes";
 import { cn } from "./cn.js";
+import { PanelActions, PanelTitle } from "./SidebarPanel";
 
 export type SidebarHeaderProps = {
   title: string;
@@ -7,15 +9,12 @@ export type SidebarHeaderProps = {
   className?: string;
 };
 
+/** Header row: a title and optional trailing actions. Inside a panel, compose `Sidebar.PanelHeader` instead. */
 export function SidebarHeader({ title, trailing, className }: SidebarHeaderProps) {
   return (
-    <div className={cn("flex h-11 items-center gap-1 pl-3 pr-1", className)}>
-      <h2 className="min-w-0 flex-1 truncate text-left text-base font-semibold leading-none tracking-tight text-foreground">
-        {title}
-      </h2>
-      {trailing ? (
-        <div className="flex items-center justify-end gap-0.5">{trailing}</div>
-      ) : null}
+    <div className={cn(sidebarHeaderRowClass, className)}>
+      <PanelTitle>{title}</PanelTitle>
+      {trailing ? <PanelActions>{trailing}</PanelActions> : null}
     </div>
   );
 }