@djangocfg/ui-core 2.1.556 → 2.1.558

package/src/components/navigation/tabs/index.tsx

@@ -8,7 +8,9 @@ import * as TabsPrimitive from '@radix-ui/react-tabs';
 import { useIsMobile } from '../../../hooks';
 import { useStoredValue, type StorageType } from '../../../hooks';
 import { useAppT } from '@djangocfg/i18n';
+import { useComposedRefs } from '../../../lib/compose-refs';
 import { cn } from '../../../lib/utils';
+import { useTabIndicator } from './use-tab-indicator';
 import { Button } from '../../forms/button';
 import { ScrollArea, ScrollBar } from '../../layout/scroll-area';
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '../../overlay/sheet';
@@ -210,43 +212,110 @@ Tabs.displayName = "Tabs"
 // Tabs variant context — lets TabsTrigger inherit variant from TabsList
 // ─────────────────────────────────────────────────────────────────────────
 
-type TabsVariant = 'default' | 'underline'
-const TabsVariantContext = React.createContext<TabsVariant>('default')
+type TabsVariant = 'default' | 'underline' | 'pill'
+/** Control height. `auto` picks `sm` on a phone and `md` elsewhere. */
+type TabsSize = 'sm' | 'md' | 'auto'
+
+const TabsVariantContext = React.createContext<{
+  variant: TabsVariant
+  size: Exclude<TabsSize, 'auto'>
+}>({ variant: 'default', size: 'md' })
 
 const TabsList = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.List>,
   React.ComponentPropsWithoutRef<typeof TabsPrimitive.List> & {
     /**
      * Visual variant.
-     * - `default` — pill/card style (bg-muted container)
-     * - `underline` — borderless, underline indicator on active tab
+     * - `default` — segmented control on a `bg-muted` track, rounded corners
+     * - `pill`    — the same control drawn as a capsule, with the active
+     *               indicator SLIDING between tabs instead of popping
+     * - `underline` — borderless, a rule under the active tab
      * @default 'default'
      */
     variant?: TabsVariant
     /**
-     * Full width mode - tabs will stretch equally to fill the container
+     * Control height.
+     * - `md`   — 36px, the desktop default
+     * - `sm`   — 28px, for a toolbar or a phone
+     * - `auto` — `sm` under the mobile breakpoint, `md` above it
+     *
+     * `auto` exists because consumers were already doing this by hand
+     * (`isSm ? 'h-7 p-0.5 gap-0.5' : 'h-9 p-0.5'` in a widget's own file),
+     * which puts a media query and a set of magic numbers in every caller.
+     * @default 'md'
+     */
+    size?: TabsSize
+    /**
+     * Stretch the tabs to fill their container.
+     *
+     * `'mobile'` does it only below the mobile breakpoint, which is the shape
+     * a toolbar actually wants: a switch that hugs its labels beside other
+     * controls on a desktop row, and spans the width once it is alone on a
+     * phone. Consumers were expressing this by setting `fullWidth` and then
+     * undoing it in CSS (`width: auto` plus a media query back to `100%`).
      * @default false
      */
-    fullWidth?: boolean
+    fullWidth?: boolean | 'mobile'
     /**
      * Enable horizontal scrolling when tabs overflow
      * @default false
      */
     scrollable?: boolean
   }
->(({ className, variant = 'default', fullWidth = false, scrollable = false, ...props }, ref) => {
+>(({ className, variant = 'default', size = 'md', fullWidth = false, scrollable = false, ...props }, ref) => {
   const isUnderline = variant === 'underline'
+  const isPill = variant === 'pill'
+  const isMobile = useIsMobile()
+  const resolvedSize = size === 'auto' ? (isMobile ? 'sm' : 'md') : size
+  const resolvedFullWidth = fullWidth === 'mobile' ? isMobile : fullWidth
+
+  // Only the pill variant animates its indicator. The default variant keeps a
+  // background on the active trigger, which cannot travel between two
+  // elements — moving it is the whole reason `pill` draws the indicator on the
+  // list instead.
+  const indicator = useTabIndicator<HTMLDivElement>()
+  // Both refs always compose: hooks cannot be called conditionally, and the
+  // indicator ref is inert for the variants that do not draw one.
+  const listRef = useComposedRefs(ref, indicator.ref)
+
+  // `md` keeps the 36px the default variant has always been: this size scale
+  // was added for `pill`, and a taller default would silently reflow every
+  // existing tab strip in every consumer.
+  const sizing = resolvedSize === 'sm'
+    ? { track: 'h-8 p-0.5', gap: 'gap-0.5', inset: '0.125rem' }
+    : { track: 'h-9 p-1', gap: 'gap-1', inset: '0.25rem' }
 
   const listCls = cn(
     isUnderline
       ? "inline-flex items-end gap-0 bg-transparent p-0 h-auto rounded-none"
-      : "inline-flex h-9 items-center justify-center rounded-[var(--radius)] bg-muted p-1 text-muted-foreground",
-    fullWidth && "w-full flex",
+      : cn(
+          "inline-flex items-center justify-center bg-muted text-muted-foreground",
+          sizing.track,
+          sizing.gap,
+          isPill ? "rounded-full" : "rounded-[var(--radius)]",
+          isPill && "tabs-sliding",
+        ),
+    resolvedFullWidth && "w-full flex",
     className
   )
 
   const list = (
-    <TabsPrimitive.List ref={ref} className={listCls} {...props} />
+    <TabsPrimitive.List
+      ref={listRef}
+      className={listCls}
+      // The pill is hidden until the first measurement lands, so it does not
+      // fly in from the left edge of the track on mount.
+      data-tab-indicator={isPill ? (indicator.ready ? 'ready' : 'idle') : undefined}
+      style={
+        isPill
+          ? ({
+              '--tab-indicator-inset': sizing.inset,
+              '--tab-indicator-radius': '9999px',
+            } as React.CSSProperties)
+          : undefined
+      }
+      {...props}
+    />
   )
 
   // For underline variant — native overflow-x-auto, full-width border via absolute element
@@ -265,8 +334,13 @@ const TabsList = React.forwardRef<
     </ScrollArea>
   ) : list
 
+  const contextValue = React.useMemo(
+    () => ({ variant, size: resolvedSize }),
+    [variant, resolvedSize]
+  )
+
   return (
-    <TabsVariantContext.Provider value={variant}>
+    <TabsVariantContext.Provider value={contextValue}>
       {wrapped}
     </TabsVariantContext.Provider>
   )
@@ -284,8 +358,10 @@ const TabsTrigger = React.forwardRef<
     key?: React.Key
   }
 >(({ className, flexEqual = false, ...props }, ref) => {
-  const variant = React.useContext(TabsVariantContext)
+  const { variant, size } = React.useContext(TabsVariantContext)
   const isUnderline = variant === 'underline'
+  const isPill = variant === 'pill'
+  const isSm = size === 'sm'
 
   return (
     <TabsPrimitive.Trigger
@@ -294,8 +370,8 @@ const TabsTrigger = React.forwardRef<
         isUnderline
           ? [
               "relative z-10 rounded-none bg-transparent shadow-none whitespace-nowrap",
-              "px-3 py-2.5 mb-[-1px]",
-              "text-sm font-medium text-muted-foreground/60",
+              isSm ? "px-2.5 py-2 text-xs" : "px-3 py-2.5 text-sm",
+              "font-medium text-muted-foreground/60",
               "border-b-2 border-transparent",
               "transition-all duration-150",
               "hover:text-foreground",
@@ -305,11 +381,20 @@ const TabsTrigger = React.forwardRef<
               "data-[state=active]:border-foreground data-[state=active]:shadow-none",
             ].join(" ")
           : [
-              "inline-flex items-center justify-center whitespace-nowrap rounded-[var(--radius-sm)] px-3 py-1",
-              "text-sm font-medium transition-all",
+              "inline-flex items-center justify-center gap-1.5 whitespace-nowrap",
+              isSm ? "px-2.5 text-xs" : "px-3 text-sm",
+              "h-full font-medium",
               "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
               "disabled:pointer-events-none disabled:opacity-50",
-              "data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow",
+              "data-[state=active]:text-foreground",
+              // The pill variant's indicator lives on the list and travels, so
+              // the trigger carries no background of its own — one would sit on
+              // top of the sliding pill and give the movement away. Colour is
+              // all that changes here, and it changes fast enough not to lag
+              // behind the pill.
+              isPill
+                ? "relative rounded-full bg-transparent transition-colors duration-150 hover:text-foreground/80 data-[state=active]:bg-transparent data-[state=active]:shadow-none"
+                : "rounded-[var(--radius-sm)] transition-all data-[state=active]:bg-background data-[state=active]:shadow",
             ].join(" "),
         flexEqual && "flex-1",
         className

package/src/components/navigation/tabs/use-tab-indicator.ts

@@ -0,0 +1,68 @@
+"use client"
+
+import * as React from 'react'
+
+/**
+ * Keeps the sliding indicator under the active tab.
+ *
+ * Measurement rather than arithmetic: tabs here carry real words ("All",
+ * "Deals", "Body type"), so they are never equal width and the CSS-only trick
+ * of a fixed `--step` per index drifts as soon as a label changes or a
+ * translation lands. The numbers go out as custom properties and `tabs.css`
+ * does the animating, so React never runs a frame of it.
+ *
+ * It re-measures on the three things that actually move a tab: the selection
+ * changing, the list resizing (a breakpoint, a sidebar opening), and a font
+ * finishing loading — that last one is the subtle one, since a fallback face
+ * lays out at a different width and the pill would otherwise keep a stale one.
+ *
+ * The selection is read from the DOM (`data-state`) rather than taken as an
+ * argument, because that is the one source both controlled and uncontrolled
+ * Tabs agree on — a `value` prop is absent in the uncontrolled case, and
+ * `defaultValue` goes stale the moment the reader clicks.
+ */
+export function useTabIndicator<T extends HTMLElement>() {
+  const ref = React.useRef<T | null>(null)
+  const [ready, setReady] = React.useState(false)
+
+  React.useLayoutEffect(() => {
+    const list = ref.current
+    if (!list) return
+
+    const measure = () => {
+      const tab = list.querySelector<HTMLElement>('[role="tab"][data-state="active"]')
+      if (!tab) return
+      list.style.setProperty('--tab-indicator-x', `${tab.offsetLeft}px`)
+      list.style.setProperty('--tab-indicator-w', `${tab.offsetWidth}px`)
+      setReady(true)
+    }
+
+    measure()
+
+    const resize = new ResizeObserver(measure)
+    resize.observe(list)
+    for (const tab of list.querySelectorAll('[role="tab"]')) resize.observe(tab)
+
+    // Radix flips `data-state` on the triggers; watching the attribute covers
+    // selection by click, by keyboard and by the parent changing `value`,
+    // without this hook needing to know which of the three happened.
+    const mutation = new MutationObserver(measure)
+    mutation.observe(list, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-state'],
+      childList: true,
+    })
+
+    // `document.fonts` is absent in older WebViews; the indicator is simply
+    // measured once there instead of re-measured after the swap.
+    document.fonts?.ready.then(measure).catch(() => {})
+
+    return () => {
+      resize.disconnect()
+      mutation.disconnect()
+    }
+  }, [])
+
+  return { ref, ready }
+}

package/src/components/overlay/drawer/index.tsx

@@ -6,18 +6,28 @@ import { Drawer as DrawerPrimitive } from 'vaul';
 import { cn } from '../../../lib/utils';
 import { useIsMobile } from '../../../hooks/media/useMobile';
 
-// Direction context lets <DrawerContent /> inherit the Root's direction without
-// callers having to pass it twice (a frequent rebase / refactor footgun).
-const DrawerDirectionContext = React.createContext<'bottom' | 'right' | 'left' | 'top' | undefined>(undefined);
+type DrawerDirection = 'bottom' | 'right' | 'left' | 'top';
+
+// Context lets <DrawerContent /> inherit what the Root was configured with,
+// without callers having to pass it twice (a frequent rebase / refactor
+// footgun). `snapPoints` matters to the content because the two own the panel's
+// geometry differently — see the note where it is read.
+const DrawerRootContext = React.createContext<{
+  direction?: DrawerDirection;
+  hasSnapPoints: boolean;
+}>({ hasSnapPoints: false });
 
 /** @internal — used by DrawerContent to inherit `direction` from the Root. */
-export const useDrawerDirection = () => React.useContext(DrawerDirectionContext);
+export const useDrawerDirection = () => React.useContext(DrawerRootContext).direction;
+
+/** @internal — true when the Root was given `snapPoints`. */
+const useDrawerHasSnapPoints = () => React.useContext(DrawerRootContext).hasSnapPoints;
 
 const Drawer = ({
   shouldScaleBackground,
   direction = 'bottom',
   ...props
-}: React.ComponentProps<typeof DrawerPrimitive.Root> & { direction?: 'bottom' | 'right' | 'left' | 'top' }) => {
+}: React.ComponentProps<typeof DrawerPrimitive.Root> & { direction?: DrawerDirection }) => {
   // vaul's body-scale animation is a mobile-bottom-sheet effect by design.
   // Applying it to side drawers (right/left) keeps the <body> transformed for
   // ~300ms during open, which on heavy pages stalls the main thread *before*
@@ -26,14 +36,40 @@ const Drawer = ({
   // Default to enabled only for bottom sheets; callers can still override.
   const resolvedScale = shouldScaleBackground ?? direction === 'bottom';
 
+  const hasSnapPoints = Boolean(props.snapPoints?.length);
+  const rootValue = React.useMemo(
+    () => ({ direction, hasSnapPoints }),
+    [direction, hasSnapPoints]
+  );
+
+  // Dim and blur the page from the FIRST snap point, not the last.
+  //
+  // vaul hides the overlay entirely below `fadeFromIndex`, which defaults to
+  // the last snap point — so a sheet resting at 0.5 sat over a page that was
+  // neither dimmed nor blurred (`opacity: 0` on the overlay, while its own
+  // `backdrop-filter: blur(5px)` and 60% scrim were already correct and simply
+  // never visible). That reads as a panel floating over live content rather
+  // than a sheet in front of it. A caller that wants the page to stay legible
+  // until the sheet is expanded can still pass its own index.
+  // vaul types `fadeFromIndex` as a discriminated union against `snapPoints`
+  // (`number` with them, `never` without), which no spread can satisfy
+  // conditionally — hence one assembled object and a single cast at the seam.
+  const rootProps = {
+    ...props,
+    ...(hasSnapPoints &&
+    (props as { fadeFromIndex?: number }).fadeFromIndex === undefined
+      ? { fadeFromIndex: 0 }
+      : null),
+  } as React.ComponentProps<typeof DrawerPrimitive.Root>;
+
   return (
-    <DrawerDirectionContext.Provider value={direction}>
+    <DrawerRootContext.Provider value={rootValue}>
       <DrawerPrimitive.Root
         shouldScaleBackground={resolvedScale}
         direction={direction}
-        {...props}
+        {...rootProps}
       />
-    </DrawerDirectionContext.Provider>
+    </DrawerRootContext.Provider>
   );
 };
 Drawer.displayName = "Drawer"
@@ -107,6 +143,19 @@ const directionStyles = {
   left: "inset-y-0 left-0 h-full border-r",
 } as const;
 
+// The snap-point variant of the above. A snapped panel is FULL height and vaul
+// slides it to the active point by transform, so the `max-h` and the top margin
+// that keep an auto-height sheet on screen are exactly wrong here: they shorten
+// the panel while vaul keeps translating by the full distance, and the sheet
+// lands past the bottom edge. Height comes from the height:100% below, never
+// from a preset.
+const snapDirectionStyles = {
+  bottom: "inset-x-0 bottom-0 h-full rounded-t-lg border-t",
+  top: "inset-x-0 top-0 h-full rounded-b-lg border-b",
+  right: "inset-y-0 right-0 h-full border-l",
+  left: "inset-y-0 left-0 h-full border-r",
+} as const;
+
 const toCssLength = (value: string | number | undefined): string | undefined => {
   if (value == null) return undefined;
   return typeof value === 'number' ? `${value}px` : value;
@@ -178,6 +227,7 @@ const DrawerContent = React.forwardRef<
   const isVertical = direction === 'bottom' || direction === 'top';
   const isMobile = useIsMobile();
   const resizeEnabled = resizable && (!resizableOnDesktopOnly || !isMobile);
+  const hasSnapPoints = useDrawerHasSnapPoints();
 
   const defaultMin = isVertical ? 200 : 280;
   const defaultMax = isVertical ? 800 : 960;
@@ -252,7 +302,12 @@ const DrawerContent = React.forwardRef<
   const rawWidth = !isVertical
     ? (currentPx != null ? `${currentPx}px` : (toCssLength(width) ?? horizontalSizePresets[size]))
     : undefined;
-  const rawHeight = isVertical
+  // With snap points the PANEL is full-height and vaul positions it by
+  // transform, reading back how far it may travel. A height of our own makes
+  // the two disagree: at snap point 0.4 vaul translated a 360px panel by 532px
+  // and pushed it entirely off the bottom of the screen — the drawer opened
+  // into nothing. So when the Root has snap points, the height is vaul's.
+  const rawHeight = isVertical && !hasSnapPoints
     ? (currentPx != null ? `${currentPx}px` : (toCssLength(height) ?? verticalSizePresets[size]))
     : undefined;
   const resolvedWidth = rawWidth ? `min(100vw, ${rawWidth})` : undefined;
@@ -273,13 +328,26 @@ const DrawerContent = React.forwardRef<
         aria-describedby={undefined}
         className={cn(
           "fixed z-500 flex flex-col bg-background",
-          directionStyles[direction],
+          hasSnapPoints ? snapDirectionStyles[direction] : directionStyles[direction],
           className
         )}
         style={{
-          transition: dragStateRef.current
-            ? 'none'
-            : 'transform 300ms cubic-bezier(0.32, 0.72, 0, 1)',
+          // With snap points vaul drives `transform` AND the transition that
+          // animates it, writing both to this element imperatively. A
+          // `transition` of ours in the style object is re-applied by React on
+          // every render and wipes that inline `transform` with it, so the
+          // sheet stays parked at its closed offset: measured
+          // `--snap-point-height: 415.5px` (correct) against `transform:
+          // translate3d(0, 831px, 0)` (fully off-screen). The resize handle's
+          // own animation is what this exists for, and resize does not apply
+          // to a snapped sheet.
+          ...(hasSnapPoints
+            ? null
+            : {
+                transition: dragStateRef.current
+                  ? 'none'
+                  : 'transform 300ms cubic-bezier(0.32, 0.72, 0, 1)',
+              }),
           ...(resolvedWidth ? { width: resolvedWidth } : {}),
           ...(resolvedHeight ? { height: resolvedHeight } : {}),
           ...style,
@@ -300,7 +368,26 @@ const DrawerContent = React.forwardRef<
             )}
           />
         )}
-        {isVertical && <div className="mx-auto mt-4 h-2 w-[100px] rounded-full bg-muted" />}
+        {/* Everything the reader can see lives inside this column when the
+            sheet is snapped: the panel itself extends past the bottom of the
+            window, so a footer pinned to the PANEL is pinned off-screen.
+            `.drawer-snap-viewport` is the visible slice; without snap points
+            there is no slice to take and the panel is the column. */}
+        <div className={hasSnapPoints ? "drawer-snap-viewport" : "contents"}>
+        {/* The grab handle. `bg-muted` is a SURFACE token — on a light theme it
+            is nearly the panel's own colour, so the handle read as a smudge.
+            `bg-border` is the token for a line drawn ON a surface and is the
+            one that keeps its contrast in both themes. Slimmer and narrower
+            than before, which is what the platform sheets use: the handle is an
+            affordance, not an element of the design.
+            `aria-hidden` because the drag it hints at is not a keyboard
+            affordance — Escape and the close button are. */}
+        {isVertical && (
+          <div
+            aria-hidden
+            className="mx-auto mt-3 h-1.5 w-10 shrink-0 rounded-full bg-border"
+          />
+        )}
         {/*
           Content padding lives HERE, not on each caller. `DialogContent` has
           its own; this did not, so every surface that renders as a Dialog on
@@ -316,10 +403,21 @@ const DrawerContent = React.forwardRef<
           It owns the SCROLL but never the height: `flex-1` here filled the
           panel and left the last row hundreds of pixels above the edge. Only
           the panel's own `max-h` decides how tall the drawer gets.
+
+          With snap points that reasoning inverts. The panel is full-height by
+          then and vaul slides it, so a scroller sized to its content would
+          leave the rest of the sheet empty and unscrollable — there `flex-1`
+          is what makes the body fill the snapped height.
         */}
-        <div className="min-h-0 overflow-y-auto overscroll-contain px-5 pb-[max(1.25rem,env(safe-area-inset-bottom))]">
+        <div
+          className={cn(
+            "min-h-0 overflow-y-auto overscroll-contain px-5 pb-[max(1.25rem,env(safe-area-inset-bottom))]",
+            hasSnapPoints && "flex-1"
+          )}
+        >
           {children}
         </div>
+        </div>
       </DrawerPrimitive.Content>
     </DrawerPortal>
   );

package/src/components/overlay/popover/index.tsx

@@ -15,7 +15,7 @@ const PopoverAnchor = PopoverPrimitive.Anchor
 const PopoverContent = React.forwardRef<
   React.ElementRef<typeof PopoverPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
->(({ className, align = "center", sideOffset = 4, forceMount, ...props }, ref) => (
+>(({ className, align = "center", sideOffset = 4, collisionPadding = 8, forceMount, ...props }, ref) => (
   // `forceMount` must reach BOTH halves, and that is the whole reason it is
   // destructured rather than swept up by `...props` (live 2026-08-15).
   //
@@ -44,8 +44,14 @@ const PopoverContent = React.forwardRef<
       aria-describedby={undefined}
       align={align}
       sideOffset={sideOffset}
+      // Radix defaults this to 0, which lets a popover that does not fit below
+      // its trigger flip above it and sit flush against the top edge of the
+      // window, first rows clipped by the viewport. The padding also feeds
+      // `--radix-popover-content-available-height`, which `.popover-panel`
+      // (in the class list below) caps the whole panel to.
+      collisionPadding={collisionPadding}
       className={cn(
-        "z-[1400] w-72 rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        "popover-panel z-[1400] w-72 rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className
       )}
       {...props}

package/src/components/overlay/side-panel/index.tsx

@@ -5,12 +5,16 @@
  *
  * Use for inspector panels, playgrounds, filters — anywhere you want a
  * slide-in surface that does NOT lock out the rest of the page. The
- * surrounding UI stays clickable and focusable; only Esc (optional) and
- * the close button dismiss the panel.
+ * surrounding UI stays clickable, focusable and scrollable.
+ *
+ * Esc, the close button and a click outside all dismiss it. Having no backdrop
+ * says the page stays usable; it does not say the click should do nothing —
+ * a reader who clicks beside the panel expects it to close, and with only Esc
+ * and a small `×` they had to hunt for the way out.
  *
  * Differences from the existing ``Drawer``:
  *   - ``modal={false}``  — no focus trap, no scroll-lock on <body>.
- *   - No backdrop overlay.
+ *   - No backdrop overlay (the page behind stays legible and live).
  *   - No ``shouldScaleBackground`` (vaul's iOS-style fancy scale looks
  *     wrong for side panels — reserved for bottom sheets).
  *   - Opinionated for ``right``/``left`` directions; vaul still drives
@@ -24,6 +28,7 @@ import * as React from 'react';
 import { Drawer as DrawerPrimitive } from 'vaul';
 import { X } from 'lucide-react';
 
+import { useComposedRefs } from '../../../lib/compose-refs';
 import { cn } from '../../../lib/utils';
 
 // ─── Root ─────────────────────────────────────────────────────────────────────
@@ -37,6 +42,20 @@ export interface SidePanelProps {
     /** Close when the user presses Escape. Default ``true``. Disable when
      *  the parent wants custom handling or Esc is bound to something else. */
     closeOnEsc?: boolean;
+    /**
+     * Close when the user clicks or taps outside the panel. Default ``true``.
+     *
+     * Having no backdrop is a statement about the PAGE — it stays readable and
+     * clickable — not about the click. Without this the only ways out were Esc
+     * and a small ``×``, so a reader who clicked beside the panel, as every
+     * other overlay has taught them to, got nothing and had to go hunting for
+     * the button.
+     *
+     * Turn it off for a panel the reader works ALONGSIDE — an inspector kept
+     * open while editing the page behind it, where a stray click on the canvas
+     * must not dismiss the thing they are reading from.
+     */
+    closeOnOutsideClick?: boolean;
 }
 
 const SidePanel: React.FC<SidePanelProps> & {
@@ -47,7 +66,11 @@ const SidePanel: React.FC<SidePanelProps> & {
     Body: typeof SidePanelBody;
     Footer: typeof SidePanelFooter;
     Close: typeof SidePanelClose;
-} = ({ open, onOpenChange, children, side = 'right', closeOnEsc = true }) => {
+} = ({ open, onOpenChange, children, side = 'right', closeOnEsc = true, closeOnOutsideClick = true }) => {
+    // The panel element, so the outside-click listener can ask "was this click
+    // inside?" — there is no backdrop to catch it for us.
+    const contentRef = React.useRef<HTMLDivElement | null>(null);
+
     // Esc handling: vaul's built-in closes on Esc only when modal=true.
     // We're non-modal, so we install our own listener — gated on ``open``
     // to avoid swallowing Esc globally while the panel is closed.
@@ -60,6 +83,46 @@ const SidePanel: React.FC<SidePanelProps> & {
         return () => window.removeEventListener('keydown', handler);
     }, [open, closeOnEsc, onOpenChange]);
 
+    // Outside-click handling, for the same reason Esc is handled here: with
+    // `modal={false}` vaul installs no dismissal of its own.
+    //
+    // `pointerdown` rather than `click`, so a press that begins outside closes
+    // even if the pointer travels onto the panel before release. The listener
+    // is added on a later task, otherwise the very click that OPENED the panel
+    // finishes propagating into it and closes it again immediately.
+    React.useEffect(() => {
+        if (!open || !closeOnOutsideClick) return;
+
+        let armed = false;
+        const arm = () => { armed = true; };
+        const id = window.setTimeout(arm, 0);
+
+        const handler = (event: PointerEvent) => {
+            if (!armed) return;
+            const target = event.target as Node | null;
+            if (!target || contentRef.current?.contains(target)) return;
+            // A click inside any overlay the panel itself opened — a Select's
+            // popover, a dialog — lands outside the panel in the DOM, because
+            // both are portalled to <body>. Closing on those would dismiss the
+            // panel the moment a reader picked a value in it.
+            if (
+                target instanceof Element &&
+                target.closest('[data-slot="popover-content"],[role="dialog"],[role="listbox"],[role="menu"]')
+            ) {
+                return;
+            }
+            onOpenChange(false);
+        };
+
+        document.addEventListener('pointerdown', handler, true);
+        return () => {
+            window.clearTimeout(id);
+            document.removeEventListener('pointerdown', handler, true);
+        };
+    }, [open, closeOnOutsideClick, onOpenChange]);
+
+    const contextValue = React.useMemo(() => ({ side, contentRef }), [side]);
+
     return (
         <DrawerPrimitive.Root
             open={open}
@@ -77,7 +140,7 @@ const SidePanel: React.FC<SidePanelProps> & {
             disablePreventScroll
             dismissible
         >
-            <SidePanelSideContext.Provider value={side}>
+            <SidePanelSideContext.Provider value={contextValue}>
                 {children}
             </SidePanelSideContext.Provider>
         </DrawerPrimitive.Root>
@@ -86,7 +149,10 @@ const SidePanel: React.FC<SidePanelProps> & {
 SidePanel.displayName = 'SidePanel';
 
 // Carries the side down to Content so it can place border + transform correctly.
-const SidePanelSideContext = React.createContext<'right' | 'left'>('right');
+const SidePanelSideContext = React.createContext<{
+    side: 'right' | 'left';
+    contentRef?: React.MutableRefObject<HTMLDivElement | null>;
+}>({ side: 'right' });
 
 // ─── Content ──────────────────────────────────────────────────────────────────
 
@@ -101,14 +167,17 @@ const SidePanelContent = React.forwardRef<
     React.ElementRef<typeof DrawerPrimitive.Content>,
     SidePanelContentProps
 >(({ className, children, width = '440px', style, ...props }, ref) => {
-    const side = React.useContext(SidePanelSideContext);
+    const { side, contentRef } = React.useContext(SidePanelSideContext);
+    // Both refs always compose: the caller's, and the panel's own, which the
+    // outside-click listener measures against.
+    const composedRef = useComposedRefs(ref, contentRef ?? null);
     const positioning =
         side === 'right' ? 'inset-y-0 right-0 border-l' : 'inset-y-0 left-0 border-r';
 
     return (
         <DrawerPrimitive.Portal>
             <DrawerPrimitive.Content
-                ref={ref}
+                ref={composedRef}
                 aria-describedby={undefined}
                 className={cn(
                     'fixed z-500 flex flex-col bg-background shadow-2xl shadow-black/20',