@womp/kookie-ui 0.23.0 → 0.24.0

package/src/components/segmented-control.tsx

@@ -1,10 +1,9 @@
 'use client';
 
-import { warnDeprecated } from '../helpers/warn-deprecated.js';
 import * as React from 'react';
 import classNames from 'classnames';
 import { ToggleGroup as ToggleGroupPrimitive } from 'radix-ui';
-import { useControllableState } from 'radix-ui/internal';
+import { useComposedRefs, useControllableState } from 'radix-ui/internal';
 
 import { segmentedControlRootPropDefs } from './segmented-control.props.js';
 import { extractProps } from '../helpers/extract-props.js';
@@ -23,6 +22,8 @@ interface SegmentedControlRootProps
   onValueChange?(value: string): void;
 }
 
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? React.useEffect : React.useLayoutEffect;
+
 const SegmentedControlRoot = React.forwardRef<HTMLDivElement, SegmentedControlRootProps>(
   (ownProps, forwardedRef) => {
     const props = useThemeSizeProps(ownProps, segmentedControlRootPropDefs.size);
@@ -33,6 +34,7 @@ const SegmentedControlRoot = React.forwardRef<HTMLDivElement, SegmentedControlRo
       value: valueProp,
       defaultValue: defaultValueProp,
       onValueChange: onValueChangeProp,
+      style,
       ...rootProps
     } = extractProps(props, segmentedControlRootPropDefs);
 
@@ -42,11 +44,39 @@ const SegmentedControlRoot = React.forwardRef<HTMLDivElement, SegmentedControlRo
       defaultProp: defaultValueProp ?? '',
     });
 
+    // The indicator is sized and placed from the item count and the selected index, written
+    // as custom properties. They are read from the children on render, so the server markup
+    // is right, then corrected from the DOM, which also sees items inside fragments or
+    // wrapper components.
+    const rootRef = React.useRef<HTMLDivElement>(null);
+    const composedRef = useComposedRefs(forwardedRef, rootRef);
+    const items = React.Children.toArray(children).filter(React.isValidElement);
+    const renderedCount = items.length;
+    const renderedIndex = Math.max(
+      0,
+      items.findIndex((child) => (child.props as { value?: unknown }).value === value),
+    );
+    useIsomorphicLayoutEffect(() => {
+      const root = rootRef.current;
+      if (!root) return;
+      const domItems = Array.from(root.querySelectorAll(':scope > .kui-SegmentedControlItem'));
+      const index = domItems.findIndex((item) => item.getAttribute('data-state') === 'on');
+      root.style.setProperty('--segmented-control-count', String(domItems.length || 1));
+      root.style.setProperty('--segmented-control-index', String(Math.max(0, index)));
+    });
+
     return (
       <ToggleGroupPrimitive.Root
         data-disabled={props.disabled || undefined}
         data-radius={radius}
-        ref={forwardedRef}
+        ref={composedRef}
+        style={
+          {
+            '--segmented-control-count': renderedCount || 1,
+            '--segmented-control-index': renderedIndex,
+            ...style,
+          } as React.CSSProperties
+        }
         className={classNames('kui-SegmentedControlRoot', className)}
         onValueChange={(value) => {
           if (value) {
@@ -70,6 +100,8 @@ SegmentedControlRoot.displayName = 'SegmentedControl.Root';
 
 interface SegmentedControlItemOwnProps {
   value: string;
+  /** When true, this segment can't be selected. */
+  disabled?: boolean;
   /** When true, applies fixed square width for icon-only segments */
   iconOnly?: boolean;
 }
@@ -77,7 +109,7 @@ interface SegmentedControlItemOwnProps {
 interface SegmentedControlItemProps
   extends ComponentPropsWithout<
       typeof ToggleGroupPrimitive.Item,
-      RemovedProps | 'disabled' | 'type' | 'value'
+      RemovedProps | 'type' | 'value'
     >,
     SegmentedControlItemOwnProps {}
 
@@ -88,7 +120,6 @@ const SegmentedControlItem = React.forwardRef<HTMLButtonElement, SegmentedContro
       className={classNames('kui-reset', 'kui-SegmentedControlItem', className)}
       data-icon-only={iconOnly || undefined}
       {...props}
-      disabled={false}
       asChild={false}
     >
       <span className="kui-SegmentedControlItemSeparator" />

package/src/components/select.tsx

@@ -1,6 +1,5 @@
 'use client';
 
-import { warnDeprecated } from '../helpers/warn-deprecated.js';
 import * as React from 'react';
 import classNames from 'classnames';
 import { Select as SelectPrimitive, ScrollArea as ScrollAreaPrimitive } from 'radix-ui';
@@ -26,6 +25,9 @@ type SelectRootOwnProps = GetPropDefTypes<typeof selectRootPropDefs>;
 // a literal written at the call site would be a new object, and a recompile, every render.
 const selectSizePropDefs = { size: selectRootPropDefs.size };
 
+// Keys that open the list from the trigger, as in Radix.
+const OPEN_KEYS = [' ', 'Enter', 'ArrowUp', 'ArrowDown'];
+
 interface SelectContextValue extends SelectRootOwnProps {
   /** Whether the list is open. Undefined when Content is rendered outside a Kookie Select.Root. */
   open?: boolean;
@@ -94,7 +96,6 @@ const SelectTrigger = React.forwardRef<SelectTriggerElement, SelectTriggerProps>
       selectTriggerPropDefs,
     );
 
-
     // The props win when set; otherwise a caller's own aria-* (a form library's aria-invalid)
     // stays, so both paths reach the accessibility tree and the CSS, as on TextField.
     const {
@@ -114,9 +115,28 @@ const SelectTrigger = React.forwardRef<SelectTriggerElement, SelectTriggerProps>
       [isInvalid, ariaInvalid, loading, ariaBusy, disabled, ariaDisabled, readOnly, ariaReadOnly],
     );
 
+    // Read-only and loading triggers stay focusable but do not open or take typeahead,
+    // as on Combobox. Radix skips its own handler when the event is default-prevented.
+    const isBlocked = Boolean(readOnly || loading);
+    const blockedHandlers = isBlocked
+      ? {
+          onPointerDown: (event: React.PointerEvent<HTMLButtonElement>) => event.preventDefault(),
+          onClick: (event: React.MouseEvent<HTMLButtonElement>) => {
+            event.preventDefault();
+            event.currentTarget.focus();
+          },
+          onKeyDown: (event: React.KeyboardEvent<HTMLButtonElement>) => {
+            const isModifierKey = event.ctrlKey || event.altKey || event.metaKey;
+            if (OPEN_KEYS.includes(event.key) || (!isModifierKey && event.key.length === 1)) {
+              event.preventDefault();
+            }
+          },
+        }
+      : undefined;
+
     return (
       // `disabled` goes to Radix, which merges it with Root's and sets the native attribute.
-      <SelectPrimitive.Trigger asChild disabled={disabled}>
+      <SelectPrimitive.Trigger asChild disabled={disabled} {...blockedHandlers}>
         <button
           data-accent-color={color}
           data-radius={radius}

package/src/components/separator.tsx

@@ -12,7 +12,19 @@ type SeparatorOwnProps = GetPropDefTypes<typeof separatorPropDefs>;
 interface SeparatorProps extends ComponentPropsWithout<'span', RemovedProps>, SeparatorOwnProps {}
 const Separator = React.forwardRef<SeparatorElement, SeparatorProps>((props, forwardedRef) => {
   const { className, color, decorative, ...separatorProps } = extractProps(props, separatorPropDefs);
-  return <span data-accent-color={color} role={decorative ? undefined : 'separator'} {...separatorProps} ref={forwardedRef} className={classNames('kui-Separator', className)} />;
+  // A responsive orientation announces the one it starts with.
+  const orientation =
+    typeof props.orientation === 'object' ? props.orientation.initial : props.orientation;
+  return (
+    <span
+      data-accent-color={color}
+      role={decorative ? undefined : 'separator'}
+      aria-orientation={!decorative && orientation === 'vertical' ? 'vertical' : undefined}
+      {...separatorProps}
+      ref={forwardedRef}
+      className={classNames('kui-Separator', className)}
+    />
+  );
 });
 Separator.displayName = 'Separator';
 

package/src/components/sheet.css

@@ -7,7 +7,6 @@
   height: 100vh;
   max-height: 100vh;
   margin: 0 !important;
-  border-radius: 0 !important;
   will-change: transform;
 }
 
@@ -19,8 +18,10 @@
   }
 }
 
-/* Logical side anchoring (RTL-aware via logical inset) */
-:where(.kui-SheetContent[data-side='start']) {
+/* Logical side anchoring (RTL-aware via logical inset). The two corners on the panel's own
+   edge are square; the two facing the page keep the size's overlay corner. The class sits
+   outside :where() so these corners outrank the size radius in base-dialog.css. */
+.kui-SheetContent:where([data-side='start']) {
   inset-block: 0 !important;
   inset-inline-start: 0 !important;
   margin: 0 !important;
@@ -29,7 +30,7 @@
   /* iOS safe area for home indicator */
   padding-bottom: env(safe-area-inset-bottom, 0px);
 }
-:where(.kui-SheetContent[data-side='end']) {
+.kui-SheetContent:where([data-side='end']) {
   inset-block: 0 !important;
   inset-inline-end: 0 !important;
   margin: 0 !important;
@@ -38,7 +39,7 @@
   /* iOS safe area for home indicator */
   padding-bottom: env(safe-area-inset-bottom, 0px);
 }
-:where(.kui-SheetContent[data-side='top']) {
+.kui-SheetContent:where([data-side='top']) {
   inset-block-start: 0 !important;
   inset-inline: 0 !important;
   width: auto;
@@ -48,7 +49,7 @@
   border-start-start-radius: 0;
   border-start-end-radius: 0;
 }
-:where(.kui-SheetContent[data-side='bottom']) {
+.kui-SheetContent:where([data-side='bottom']) {
   inset-block-end: 0 !important;
   inset-inline: 0 !important;
   width: auto;

package/src/components/sheet.tsx

@@ -15,6 +15,7 @@
  * - Sizing: reuses Dialog content prop defs (width/min/max/height/size). Size follows the
  *   Theme size; start/end sheets cap at the size's overlay width unless maxWidth is set.
  * - A11y: provide an accessible name via `Sheet.Title` or `aria-label` on `Sheet.Content`.
+ *   Radix owns the focus trap, initial focus and the return of focus to the trigger.
  *
  * Example
  * <Sheet.Root>
@@ -71,15 +72,12 @@ Root.displayName = 'Sheet.Root';
 /** Element type for `Sheet.Trigger`. */
 type SheetTriggerElement = React.ElementRef<typeof DialogPrimitive.Trigger>;
 /** Props for `Sheet.Trigger` (expects a single element child). */
-interface SheetTriggerProps
-  extends ComponentPropsWithout<typeof DialogPrimitive.Trigger, RemovedProps> {}
-const Trigger = React.forwardRef<SheetTriggerElement, SheetTriggerProps>(
-  ({ children, ...props }, ref) => (
-    <DialogPrimitive.Trigger {...props} ref={ref} asChild>
-      {requireReactElement(children)}
-    </DialogPrimitive.Trigger>
-  ),
-);
+interface SheetTriggerProps extends ComponentPropsWithout<typeof DialogPrimitive.Trigger, RemovedProps> {}
+const Trigger = React.forwardRef<SheetTriggerElement, SheetTriggerProps>(({ children, ...props }, ref) => (
+  <DialogPrimitive.Trigger {...props} ref={ref} asChild>
+    {requireReactElement(children)}
+  </DialogPrimitive.Trigger>
+));
 Trigger.displayName = 'Sheet.Trigger';
 
 // Content
@@ -88,16 +86,14 @@ Trigger.displayName = 'Sheet.Trigger';
 // Built once at module scope: `extractProps` memoises on the identity of the
 // prop def objects it is handed, so rebuilding these per render would recompile
 // them every time a sheet renders.
-const {
-  align: _alignPropDef,
-  ...dialogPropDefsForSheet
-} = dialogContentPropDefs;
+const { align: _alignPropDef, ...dialogPropDefsForSheet } = dialogContentPropDefs;
 const sheetPropDefs = dialogPropDefsForSheet;
 
+/** Counts the Sheet.Title elements mounted inside a Sheet.Content, for the dev-only name check. */
+const SheetTitleCountContext = React.createContext<React.MutableRefObject<number> | null>(null);
+
 type SheetContentElement = React.ElementRef<typeof DialogPrimitive.Content>;
-interface SheetContentProps
-  extends ComponentPropsWithout<typeof DialogPrimitive.Content, RemovedProps>,
-    DialogContentOwnProps {
+interface SheetContentProps extends ComponentPropsWithout<typeof DialogPrimitive.Content, RemovedProps>, DialogContentOwnProps {
   /** Side where the Sheet should appear. `left`/`right` alias to `start`/`end`. */
   side?: SheetSide;
   /** Optional DOM container to portal into. Defaults to `document.body`. */
@@ -109,166 +105,103 @@ interface SheetContentProps
  * forwards dialog sizing props. Provide an accessible name via `Sheet.Title`
  * or `aria-label`.
  */
-const Content = React.forwardRef<SheetContentElement, SheetContentProps>(
-  (allProps, forwardedRef) => {
-    const {
-      side = 'start',
-      forceMount,
-      container,
-      className,
-      ...ownProps
-    } = allProps;
-    const restProps = useThemeSizeProps(ownProps, sheetPropDefs.size);
-    const normalizedSideMap: Record<SheetSide, 'start' | 'end' | 'top' | 'bottom'> = {
-      left: 'start',
-      right: 'end',
-      start: 'start',
-      end: 'end',
-      top: 'top',
-      bottom: 'bottom',
-    };
-    const normalizedSide = normalizedSideMap[side];
-    // Size/width/height class names come from the dialog defs — see `sheetPropDefs`.
-    const { className: extractedClassName, ...contentProps } = extractProps(
-      restProps,
-      sheetPropDefs,
-    );
-
-    // Dev-only a11y guard: ensure label is provided via Title or aria-label
-    if (process.env.NODE_ENV !== 'production') {
-      const children = (contentProps as any).children as React.ReactNode;
-      const hasAriaLabel = typeof (contentProps as any)['aria-label'] === 'string';
-      let hasTitle = false;
-      if (children) {
-        for (const child of React.Children.toArray(children)) {
-          if (React.isValidElement(child) && child.type === Title) {
-            hasTitle = true;
-            break;
-          }
-        }
+const Content = React.forwardRef<SheetContentElement, SheetContentProps>((allProps, forwardedRef) => {
+  const { side = 'start', forceMount, container, className, ...ownProps } = allProps;
+  const restProps = useThemeSizeProps(ownProps, sheetPropDefs.size);
+  const normalizedSideMap: Record<SheetSide, 'start' | 'end' | 'top' | 'bottom'> = {
+    left: 'start',
+    right: 'end',
+    start: 'start',
+    end: 'end',
+    top: 'top',
+    bottom: 'bottom',
+  };
+  const normalizedSide = normalizedSideMap[side];
+  // Size/width/height class names come from the dialog defs — see `sheetPropDefs`.
+  const { className: extractedClassName, ...contentProps } = extractProps(restProps, sheetPropDefs);
+
+  // Dev-only a11y guard: the panel needs a name. A Sheet.Title anywhere inside counts it
+  // in a layout effect, which runs before this ref is attached, so nesting doesn't matter.
+  const titleCountRef = React.useRef(0);
+  const combinedRef = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      if (typeof forwardedRef === 'function') {
+        forwardedRef(node);
+      } else if (forwardedRef) {
+        forwardedRef.current = node;
       }
-      if (!hasTitle && !hasAriaLabel) {
-        console.warn(
-          'Sheet.Content: Missing accessible name. Include Sheet.Title as a child or provide aria-label.',
-        );
-      }
-    }
-
-    // Focus management and stuck pointer-events cleanup like Dialog
-    const contentRef = React.useRef<HTMLDivElement>(null);
-    const combinedRef = React.useMemo(
-      () => (node: HTMLDivElement | null) => {
-        contentRef.current = node;
-        if (typeof forwardedRef === 'function') {
-          forwardedRef(node);
-        } else if (forwardedRef) {
-          (forwardedRef as React.MutableRefObject<HTMLDivElement | null>).current = node;
-        }
-      },
-      [forwardedRef],
-    );
-
-    useBodyPointerEventsCleanup();
-
-    React.useEffect(() => {
-      if (typeof window === 'undefined') return;
-      const content = contentRef.current;
-      if (!content) return;
-
-      const focusableElements = content.querySelectorAll(
-        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
-      );
-
-      if (focusableElements.length === 0) return;
-
-      const firstElement = focusableElements[0] as HTMLElement;
-      const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
-
-      const handleKeyDown = (event: KeyboardEvent) => {
-        if (event.key === 'Tab') {
-          if (event.shiftKey) {
-            if (document.activeElement === firstElement) {
-              event.preventDefault();
-              lastElement.focus();
-            }
-          } else if (document.activeElement === lastElement) {
-            event.preventDefault();
-            firstElement.focus();
-          }
+      if (process.env.NODE_ENV !== 'production' && node) {
+        const hasName = titleCountRef.current > 0 || Boolean(node.getAttribute('aria-label')) || Boolean(node.getAttribute('aria-labelledby'));
+        if (!hasName) {
+          console.warn('Sheet.Content: Missing accessible name. Include Sheet.Title inside it or provide aria-label.');
         }
-      };
-
-      content.addEventListener('keydown', handleKeyDown);
-      firstElement.focus();
+      }
+    },
+    [forwardedRef],
+  );
 
-      return () => {
-        content.removeEventListener('keydown', handleKeyDown);
-      };
-    }, []);
+  useBodyPointerEventsCleanup();
 
-    return (
-      <DialogPrimitive.Portal container={container} forceMount={forceMount}>
+  return (
+    <DialogPrimitive.Portal container={container} forceMount={forceMount}>
+      <SheetTitleCountContext.Provider value={titleCountRef}>
         <Theme asChild>
           <DialogPrimitive.Overlay className="kui-BaseDialogOverlay kui-DialogOverlay kui-SheetOverlay">
             <DialogPrimitive.Content
               {...contentProps}
               ref={combinedRef}
-              className={classNames(
-                'kui-BaseDialogContent',
-                'kui-SheetContent',
-                className,
-                extractedClassName,
-              )}
+              className={classNames('kui-BaseDialogContent', 'kui-SheetContent', className, extractedClassName)}
               data-side={normalizedSide}
-              tabIndex={-1}
-              role="dialog"
               aria-modal="true"
             />
           </DialogPrimitive.Overlay>
         </Theme>
-      </DialogPrimitive.Portal>
-    );
-  },
-);
+      </SheetTitleCountContext.Provider>
+    </DialogPrimitive.Portal>
+  );
+});
 Content.displayName = 'Sheet.Content';
 
 // Title - renders as Heading with sensible defaults
 type SheetTitleElement = React.ElementRef<typeof Heading>;
 type SheetTitleProps = HeadingProps;
 /** Accessible title for the Sheet. Renders as Heading with sensible defaults. */
-const Title = React.forwardRef<SheetTitleElement, SheetTitleProps>(
-  ({ size = '4', weight = 'medium', ...props }, ref) => (
+const Title = React.forwardRef<SheetTitleElement, SheetTitleProps>(({ size = '4', weight = 'medium', ...props }, ref) => {
+  const titleCountRef = React.useContext(SheetTitleCountContext);
+  React.useLayoutEffect(() => {
+    if (!titleCountRef) return;
+    titleCountRef.current += 1;
+    return () => {
+      titleCountRef.current -= 1;
+    };
+  }, [titleCountRef]);
+  return (
     <DialogPrimitive.Title asChild>
       <Heading ref={ref} size={size} weight={weight} {...props} />
     </DialogPrimitive.Title>
-  ),
-);
+  );
+});
 Title.displayName = 'Sheet.Title';
 
 // Description - renders as Text with sensible defaults
 type SheetDescriptionElement = React.ElementRef<typeof Text>;
 type SheetDescriptionProps = React.ComponentPropsWithoutRef<typeof Text>;
 /** Supplementary description text for Sheet content. Renders as Text with sensible defaults. */
-const Description = React.forwardRef<SheetDescriptionElement, SheetDescriptionProps>(
-  ({ size = '2', emphasis = 'medium', ...rest }, ref) => (
-    <DialogPrimitive.Description asChild>
-      <Text ref={ref} size={size} emphasis={emphasis} {...rest} />
-    </DialogPrimitive.Description>
-  ),
-);
+const Description = React.forwardRef<SheetDescriptionElement, SheetDescriptionProps>(({ size = '2', emphasis = 'medium', ...rest }, ref) => (
+  <DialogPrimitive.Description asChild>
+    <Text ref={ref} size={size} emphasis={emphasis} {...rest} />
+  </DialogPrimitive.Description>
+));
 Description.displayName = 'Sheet.Description';
 
 type SheetCloseElement = React.ElementRef<typeof DialogPrimitive.Close>;
-interface SheetCloseProps
-  extends ComponentPropsWithout<typeof DialogPrimitive.Close, RemovedProps> {}
+interface SheetCloseProps extends ComponentPropsWithout<typeof DialogPrimitive.Close, RemovedProps> {}
 /** Close button for the Sheet. Expects a single element child rendered via `asChild`. */
-const Close = React.forwardRef<SheetCloseElement, SheetCloseProps>(
-  ({ children, ...props }, ref) => (
-    <DialogPrimitive.Close {...props} ref={ref} asChild>
-      {requireReactElement(children)}
-    </DialogPrimitive.Close>
-  ),
-);
+const Close = React.forwardRef<SheetCloseElement, SheetCloseProps>(({ children, ...props }, ref) => (
+  <DialogPrimitive.Close {...props} ref={ref} asChild>
+    {requireReactElement(children)}
+  </DialogPrimitive.Close>
+));
 Close.displayName = 'Sheet.Close';
 
 export { Root, Trigger, Content, Title, Description, Close };

package/src/components/shell.css

@@ -224,6 +224,16 @@
   min-height: 0;
 }
 
+/*
+ * In the content it is the page's scroller. The content becomes a column that does not scroll
+ * itself, so a floating header beside the Scroll stays pinned while the page scrolls under it.
+ */
+.kui-ShellContent:has(> .kui-ShellScroll) {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
 /* ── Floating header and footer ───────────────────────────────────────────── */
 
 /*
@@ -338,6 +348,10 @@
   --scroll-fade-end: var(--kui-pane-inset-end);
   --scrollarea-scrollbar-vertical-margin-bottom: calc(var(--space-2) + var(--kui-pane-inset-end));
 }
+/* A link target or a focused control scrolls into view clear of the floating rows, not under them. */
+.kui-ShellScroll > .kui-ScrollAreaViewport {
+  scroll-padding-block: var(--kui-pane-inset-start, 0px) var(--kui-pane-inset-end, 0px);
+}
 .kui-ShellScroll > .kui-ScrollAreaViewport > * {
   padding-top: var(--kui-pane-inset-start, 0px);
   padding-bottom: var(--kui-pane-inset-end, 0px);

package/src/components/shell.tsx

@@ -22,6 +22,7 @@
 
 import * as React from 'react';
 import classNames from 'classnames';
+import { Slot } from 'radix-ui';
 import { useComposedRefs } from 'radix-ui/internal';
 import { PaneResizeContext } from './_internal/shell-resize.js';
 import { PaneHandle, PanelHandle } from './_internal/shell-handles.js';
@@ -48,7 +49,7 @@ 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 { PaneChromeScope, PaneFooter, PaneHeader, Scroll, ShellSizeContext } from './_internal/pane-chrome.js';
+import { PaneChromeScope, PaneFooter, PaneHeader, Scroll, ShellContentContext, ShellSizeContext } from './_internal/pane-chrome.js';
 import type { PaneSize } from './_internal/pane-chrome.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, PaneMode, PaneName, PaneTarget, ResponsivePresentation, SidebarMode } from './shell.types.js';
 
@@ -365,6 +366,7 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
   return (
     <ShellStoreContext.Provider value={store}>
       <ShellSizeContext.Provider value={size}>
+      <ShellContentContext.Provider value={false}>
       <ShellInsetContext.Provider value={insetContext}>
         {/* The Root is not a widget: it hears Escape bubbling up from the panes,
             after their own handlers, to close the overlays. */}
@@ -387,6 +389,7 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
           <div className="kui-ShellScrim" aria-hidden onClick={closeOverlays} />
         </div>
       </ShellInsetContext.Provider>
+      </ShellContentContext.Provider>
       </ShellSizeContext.Provider>
     </ShellStoreContext.Provider>
   );
@@ -679,9 +682,17 @@ interface ShellContentProps extends React.ComponentPropsWithoutRef<'main'> {
   inset?: boolean;
 }
 
-const Content = React.forwardRef<HTMLElement, ShellContentProps>(({ className, inset, ...props }, ref) => {
+/**
+ * The work area. It scrolls as it is; with a `Shell.Scroll` child it becomes a column and the
+ * Scroll scrolls instead, so a `Shell.PaneHeader float` beside it stays pinned over the page.
+ */
+const Content = React.forwardRef<HTMLElement, ShellContentProps>(({ className, inset, children, ...props }, ref) => {
   useInsetRegistration('content', inset);
-  return <main {...props} ref={ref} className={classNames('kui-ShellContent', className)} data-inset={inset || undefined} />;
+  return (
+    <main {...props} ref={ref} className={classNames('kui-ShellContent', className)} data-inset={inset || undefined}>
+      <ShellContentContext.Provider value={true}>{children}</ShellContentContext.Provider>
+    </main>
+  );
 });
 Content.displayName = 'Shell.Content';
 
@@ -692,6 +703,12 @@ type TriggerAction = 'toggle' | 'expand' | 'collapse';
 interface TriggerProps extends React.ComponentPropsWithoutRef<'button'> {
   target: PaneTarget;
   action?: TriggerAction;
+  /**
+   * Renders the single child in place of the trigger's own button, with the trigger's click,
+   * `aria-controls`, `aria-expanded` and data attributes merged onto it. Use it to make a
+   * `Button` the trigger: `<Shell.Trigger asChild><Button iconOnly aria-label="Toggle sidebar">…</Button></Shell.Trigger>`.
+   */
+  asChild?: boolean;
   /**
    * Whether to show a preview of the target pane on hover while it is closed
    * and not an overlay. Defaults to false.
@@ -706,9 +723,10 @@ interface TriggerProps extends React.ComponentPropsWithoutRef<'button'> {
  * A button that drives a pane by name, through the registry. It sets
  * `aria-controls` and `aria-expanded` (left off while an untouched pane
  * cannot know its state yet), renders `type="button"`, and runs the
- * consumer's `onClick` first: calling `preventDefault()` there cancels it.
+ * consumer's `onClick` first: calling `preventDefault()` there cancels it. With `asChild` the
+ * child is the button, and its own `type` stands.
  */
-const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ target, action = 'toggle', peekOnHover, onClick, onMouseEnter, onMouseLeave, children, ...props }, ref) => {
+const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ target, action = 'toggle', peekOnHover, asChild = false, onClick, onMouseEnter, onMouseLeave, children, ...props }, ref) => {
   const store = useShellStore('Shell.Trigger');
   React.useEffect(() => {
     if (target === 'left') warnOnce('Shell.Trigger target="left" is deprecated and is removed in 1.0. Use target="rail".');
@@ -742,10 +760,13 @@ const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ target, act
     if (peekOnHover && store.peek === name) setShellPeek(store, null);
   };
 
+  const Comp = asChild ? Slot.Root : 'button';
   return (
-    <button
+    <Comp
       // A button's default type is `submit`. Stated before the spread, so a consumer's own wins.
-      type="button"
+      // An asChild child states its own (Button already says `button`; a link has none), so the
+      // key is left off rather than passed as undefined.
+      {...(!asChild && { type: 'button' as const })}
       aria-controls={entry?.id}
       aria-expanded={shown}
       {...props}
@@ -757,7 +778,7 @@ const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ target, act
       data-shell-action={action}
     >
       {children}
-    </button>
+    </Comp>
   );
 });
 Trigger.displayName = 'Shell.Trigger';