@womp/kookie-ui 0.22.1 → 0.24.0

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';
@@ -21,16 +20,48 @@ import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-p
 
 type SelectRootOwnProps = GetPropDefTypes<typeof selectRootPropDefs>;
 
-type SelectContextValue = SelectRootOwnProps;
+// Trigger and Content pass the size prop def as its own record. It is hoisted because
+// extractProps caches its compiled prop defs on the identity of each record it is given:
+// 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;
+}
 const SelectContext = React.createContext<SelectContextValue>({});
 
-interface SelectRootProps extends SelectPrimitive.SelectProps, SelectContextValue {}
+interface SelectRootProps extends SelectPrimitive.SelectProps, SelectRootOwnProps {}
 const SelectRoot: React.FC<SelectRootProps> = (props) => {
-  const { children, size: sizeProp, ...rootProps } = props;
+  const {
+    children,
+    size: sizeProp,
+    open: openProp,
+    defaultOpen,
+    onOpenChange,
+    ...rootProps
+  } = props;
   const size = useThemeSize(sizeProp, selectRootPropDefs.size);
+
+  // Root owns the open state and hands Radix a controlled `open`, so Content learns of a
+  // change in the same render Radix does. Radix's uncontrolled state reports changes from an
+  // effect, a render late, which would mount the open list once without its wrappers.
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen ?? false);
+  const open = openProp ?? uncontrolledOpen;
+  const handleOpenChange = React.useCallback(
+    (next: boolean) => {
+      setUncontrolledOpen(next);
+      onOpenChange?.(next);
+    },
+    [onOpenChange],
+  );
+
   return (
-    <SelectPrimitive.Root {...rootProps}>
-      <SelectContext.Provider value={React.useMemo(() => ({ size }), [size])}>
+    <SelectPrimitive.Root {...rootProps} open={open} onOpenChange={handleOpenChange}>
+      <SelectContext.Provider value={React.useMemo(() => ({ size, open }), [size, open])}>
         {children}
       </SelectContext.Provider>
     </SelectPrimitive.Root>
@@ -61,11 +92,10 @@ const SelectTrigger = React.forwardRef<SelectTriggerElement, SelectTriggerProps>
       // Pass size value from the context to generate styles
       { size: context?.size, ...props },
       // Pass size prop def to allow it to be extracted
-      { size: selectRootPropDefs.size },
+      selectSizePropDefs,
       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 {
@@ -85,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}
@@ -143,12 +192,26 @@ const SelectContent = React.forwardRef<SelectContentElement, SelectContentProps>
       // Pass size value from the context to generate styles
       { size: context?.size, ...props },
       // Pass size prop def to allow it to be extracted
-      { size: selectRootPropDefs.size },
+      selectSizePropDefs,
       selectContentPropDefs,
     );
     const themeContext = useThemeContext();
+
+    // While closed, Radix still renders Content's children, into a detached fragment: the
+    // items must exist for the trigger's value label, typeahead and the native form select.
+    // Nothing in that fragment is ever shown, so the theme wrapper and the scroll area, with
+    // its two resize observers, are left out until the list opens.
+    if (context.open === false && !contentProps.forceMount) {
+      return (
+        <SelectPrimitive.Portal container={container}>
+          <SelectPrimitive.Content {...contentProps} asChild={false} ref={forwardedRef}>
+            {children}
+          </SelectPrimitive.Content>
+        </SelectPrimitive.Portal>
+      );
+    }
+
     const resolvedColor = color || themeContext.accentColor;
-    const setThumbViewport = useThumbSync<HTMLDivElement>();
     return (
       <SelectPrimitive.Portal container={container}>
         <Theme asChild>
@@ -161,31 +224,12 @@ const SelectContent = React.forwardRef<SelectContentElement, SelectContentProps>
             className={classNames(
               'kui-PopperContent',
               'kui-BaseMenuContent',
-          'kui-variant-soft',
+              'kui-variant-soft',
               'kui-SelectContent',
               className,
             )}
           >
-            <ScrollAreaPrimitive.Root type="auto" className="kui-ScrollAreaRoot">
-              <SelectPrimitive.Viewport
-                asChild
-                className={classNames('kui-BaseMenuViewport', 'kui-SelectViewport')}
-              >
-                <ScrollAreaPrimitive.Viewport
-                  ref={setThumbViewport}
-                  className="kui-ScrollAreaViewport"
-                  style={{ overflowY: undefined }}
-                >
-                  {children}
-                </ScrollAreaPrimitive.Viewport>
-              </SelectPrimitive.Viewport>
-              <ScrollAreaPrimitive.Scrollbar
-                className="kui-ScrollAreaScrollbar"
-                orientation="vertical"
-              >
-                <ScrollAreaPrimitive.Thumb className="kui-ScrollAreaThumb" />
-              </ScrollAreaPrimitive.Scrollbar>
-            </ScrollAreaPrimitive.Root>
+            <SelectScrollArea>{children}</SelectScrollArea>
           </SelectPrimitive.Content>
         </Theme>
       </SelectPrimitive.Portal>
@@ -194,6 +238,30 @@ const SelectContent = React.forwardRef<SelectContentElement, SelectContentProps>
 );
 SelectContent.displayName = 'Select.Content';
 
+/** The open list's scroll area. Its own component so the thumb sync hook runs only while open. */
+function SelectScrollArea({ children }: { children: React.ReactNode }) {
+  const setThumbViewport = useThumbSync<HTMLDivElement>();
+  return (
+    <ScrollAreaPrimitive.Root type="auto" className="kui-ScrollAreaRoot">
+      <SelectPrimitive.Viewport
+        asChild
+        className={classNames('kui-BaseMenuViewport', 'kui-SelectViewport')}
+      >
+        <ScrollAreaPrimitive.Viewport
+          ref={setThumbViewport}
+          className="kui-ScrollAreaViewport"
+          style={{ overflowY: undefined }}
+        >
+          {children}
+        </ScrollAreaPrimitive.Viewport>
+      </SelectPrimitive.Viewport>
+      <ScrollAreaPrimitive.Scrollbar className="kui-ScrollAreaScrollbar" orientation="vertical">
+        <ScrollAreaPrimitive.Thumb className="kui-ScrollAreaThumb" />
+      </ScrollAreaPrimitive.Scrollbar>
+    </ScrollAreaPrimitive.Root>
+  );
+}
+
 type SelectItemElement = React.ElementRef<typeof SelectPrimitive.Item>;
 interface SelectItemProps
   extends ComponentPropsWithout<typeof SelectPrimitive.Item, RemovedProps> {}

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

@@ -88,6 +88,18 @@
   isolation: isolate;
 }
 
+/*
+ * Chromium (the only engine with -webkit-app-region) gives a scroller whose overscroll-behavior is
+ * not auto two composited layers even when its content fits: about 3 MB for a 1280x800 pane. There
+ * the Root's own overscroll-behavior already stops the chain, so the content does not need one.
+ * WebKit ignores an ancestor that is not user-scrollable, so it keeps `contain` above.
+ */
+@supports (-webkit-app-region: drag) {
+  .kui-ShellContent {
+    overscroll-behavior: auto;
+  }
+}
+
 /* ── Panes ─────────────────────────────────────────────────────────────────── */
 
 /*
@@ -212,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 ───────────────────────────────────────────── */
 
 /*
@@ -326,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);