@womp/kookie-ui 0.26.0 → 0.26.2

package/src/components/_internal/pane-band-context.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+
+type BandSize = '1' | '2' | '3' | '4';
+
+/**
+ * Set by `Shell.PaneHeader` and `Shell.PaneFooter` to their band size, and by `Shell.Scroll` to
+ * null (a scrolling list has no band). A `Theme asChild`, the root of every portalled surface
+ * (Popover, Dialog, Sheet, menus), sets null too, so a Toolbar in one does not take the Shell's
+ * step. `Shell.Root` clears it again. Unset (`undefined`) everywhere else.
+ *
+ * Its own module so Theme can reset it without bringing the Shell.
+ */
+const PaneBandSizeContext = React.createContext<BandSize | null | undefined>(undefined);
+
+export { PaneBandSizeContext };
+export type { BandSize };

package/src/components/_internal/pane-chrome.tsx

@@ -14,6 +14,7 @@ import classNames from 'classnames';
 
 import { ScrollArea } from '../scroll-area.js';
 import { ShellStoreContext } from './shell-store.js';
+import { PaneBandSizeContext, type BandSize } from './pane-band-context.js';
 
 type PaneSize = '1' | '2' | '3';
 
@@ -60,20 +61,12 @@ function useChromeClasses() {
   return ['kui-ShellPaneChrome', `kui-r-size-${size}`, `kui-menu-variant-${menuVariant}`];
 }
 
-type BandSize = '1' | '2' | '3' | '4';
-
 /**
  * The index a Toolbar in a pane's header or footer rests at when it states none: one step above
  * the Shell's, so the band reads as chrome over the rows (v2 BAND_STEP). 4 has no step above.
  */
 const BAND_STEP = { '1': '2', '2': '3', '3': '4', '4': '4' } as const satisfies Record<BandSize, BandSize>;
 
-/**
- * Set by `Shell.PaneHeader` and `Shell.PaneFooter` to their band size, and by `Shell.Scroll` to
- * null (a scrolling list has no band). Unset (`undefined`) everywhere else.
- */
-const PaneBandSizeContext = React.createContext<BandSize | null | undefined>(undefined);
-
 function useBandSize(): BandSize {
   const visual = useSidebarVisual();
   const shellSize = React.useContext(ShellSizeContext);

package/src/components/_internal/shell-bottom.tsx

@@ -6,7 +6,7 @@ import { useComposedRefs } from 'radix-ui/internal';
 import { PaneResizeContext } from './shell-resize.js';
 import { BottomHandle, PaneHandle } from './shell-handles.js';
 import { usePane, paneAttributes, usePresentationTable } from './shell-pane.js';
-import { splitHandles, useResizablePane, type SizeChangeMeta } from './shell-resizable.js';
+import { splitHandles, useInitialPaneSize, useResizablePane, type SizeChangeMeta } from './shell-resizable.js';
 import { useInsetRegistration, warnOnce } from './shell-store.js';
 import { bottomAnchoredGrowth, detailRest, toPaneValue, withoutRemovedPaneProps } from './shell-rest.js';
 import { readBreakpoint } from '../../hooks/use-breakpoint.js';
@@ -124,6 +124,8 @@ export const Bottom = React.forwardRef<HTMLDivElement, BottomPublicProps>((props
     requestToggle: () => pane.toggle('toggle'),
   });
 
+  // The starting size is in the server HTML, so the pane does not jump on hydration.
+  const initialSize = useInitialPaneSize(size, defaultSize, minSize, maxSize);
   const { handles, content } = splitHandles(children, BottomHandle);
   const handle = resizable && pane.shown !== false && !pane.overlaying ? <PaneResizeContext.Provider value={resize}>{handles.length > 0 ? handles : <PaneHandle />}</PaneResizeContext.Provider> : null;
 
@@ -140,6 +142,7 @@ export const Bottom = React.forwardRef<HTMLDivElement, BottomPublicProps>((props
         {
           ...style,
           '--bottom-expanded-size': `${expandedSize}px`,
+          ...(initialSize ? { '--bottom-size': initialSize } : {}),
           '--bottom-min-size': `${minSize}px`,
           '--bottom-max-size': `${maxSize}px`,
         } as CSSPropertiesWithVars

package/src/components/popover.tsx

@@ -15,10 +15,6 @@ import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-p
 // Popover Content Context
 // ---------------------------------------------
 type PopoverContentContextValue = {
-  /** Ref to the Popover.Content DOM node */
-  contentRef: React.MutableRefObject<HTMLDivElement | null>;
-  /** Update content's toolbar offset variable and presence flag */
-  setToolbarOffset: (offsetPx: number) => void;
   /** Wire up aria-labelledby for toolbar title */
   setLabelId: (id: string | undefined) => void;
 };
@@ -68,33 +64,8 @@ const PopoverContent = React.forwardRef<PopoverContentElement, PopoverContentPro
       ...contentProps
     } = extractProps(props, popoverContentPropDefs);
 
-    // Manage refs (we need the DOM node to apply CSS variables)
-    const contentRef = React.useRef<HTMLDivElement>(null);
-    const combinedRef = React.useCallback(
-      (node: HTMLDivElement | null) => {
-        contentRef.current = node;
-        if (typeof forwardedRef === 'function') {
-          forwardedRef(node);
-        } else if (forwardedRef) {
-          (forwardedRef as React.MutableRefObject<HTMLDivElement | null>).current = node;
-        }
-      },
-      [forwardedRef],
-    );
-
     const [labelId, setLabelId] = React.useState<string | undefined>(undefined);
-
-    const setToolbarOffset = React.useCallback((offsetPx: number) => {
-      const el = contentRef.current;
-      if (!el) return;
-      if (offsetPx > 0) {
-        el.style.setProperty('--popover-toolbar-offset', `${offsetPx}px`);
-        el.setAttribute('data-has-toolbar', 'true');
-      } else {
-        el.style.removeProperty('--popover-toolbar-offset');
-        el.removeAttribute('data-has-toolbar');
-      }
-    }, []);
+    const contextValue = React.useMemo(() => ({ setLabelId }), []);
 
     return (
       <PopoverPrimitive.Portal container={container} forceMount={forceMount}>
@@ -104,12 +75,12 @@ const PopoverContent = React.forwardRef<PopoverContentElement, PopoverContentPro
             sideOffset={8}
             collisionPadding={10}
             {...contentProps}
-            ref={combinedRef}
+            ref={forwardedRef}
             // A Toolbar.Title names the panel; without one, the caller's own value stands.
             aria-labelledby={labelId ?? contentProps['aria-labelledby']}
             className={classNames('kui-PopperContent', 'kui-PopoverContent', className)}
           >
-            <PopoverContentContext.Provider value={React.useMemo(() => ({ contentRef, setToolbarOffset, setLabelId }), [setToolbarOffset])}>
+            <PopoverContentContext.Provider value={contextValue}>
               {props.children}
             </PopoverContentContext.Provider>
           </PopoverPrimitive.Content>
@@ -150,37 +121,12 @@ type PopoverToolbarProps = React.ComponentPropsWithoutRef<'div'>;
 
 const PopoverToolbarBase = React.forwardRef<PopoverToolbarElement, PopoverToolbarProps>(
   ({ className, children, ...props }, forwardedRef) => {
-    const ctx = usePopoverContentContext('Popover.Toolbar');
-
-    const localRef = React.useRef<HTMLDivElement | null>(null);
-    const setRefs = React.useCallback(
-      (node: HTMLDivElement | null) => {
-        localRef.current = node;
-        if (typeof forwardedRef === 'function') forwardedRef(node);
-        else if (forwardedRef)
-          (forwardedRef as React.MutableRefObject<HTMLDivElement | null>).current = node;
-      },
-      [forwardedRef],
-    );
-
-    React.useEffect(() => {
-      if (!ctx || !localRef.current) return;
-      const el = localRef.current;
-      const update = () => {
-        const height = el.getBoundingClientRect().height;
-        ctx.setToolbarOffset(height);
-      };
-      update();
-      const ro = new ResizeObserver(update);
-      ro.observe(el);
-      return () => {
-        ro.disconnect();
-        ctx.setToolbarOffset(0);
-      };
-    }, [ctx]);
+    // The toolbar is sticky in the content's own CSS, so it needs no measuring; this only warns
+    // when it is used outside Popover.Content.
+    usePopoverContentContext('Popover.Toolbar');
 
     return (
-      <div {...props} ref={setRefs} className={classNames('kui-PopoverToolbar', className)}>
+      <div {...props} ref={forwardedRef} className={classNames('kui-PopoverToolbar', className)}>
         {children}
       </div>
     );

package/src/components/scroll-area.tsx

@@ -4,7 +4,7 @@ import { ScrollArea as ScrollAreaPrimitive } from 'radix-ui';
 import { useComposedRefs } from 'radix-ui/internal';
 
 import { scrollAreaPropDefs } from './scroll-area.props.js';
-import { useScrollEdges } from '../hooks/use-scroll-edges.js';
+import { scrollableOverflow, useScrollEdges } from '../hooks/use-scroll-edges.js';
 import { useThumbSync } from '../hooks/use-thumb-sync.js';
 import { getSubtree } from '../helpers/get-subtree.js';
 import { extractProps } from '../helpers/extract-props.js';
@@ -38,7 +38,8 @@ function useFocusableWhileScrollable(element: HTMLDivElement | null, enabled: bo
     let frame = 0;
     const update = () => {
       frame = 0;
-      const scrollable = element.scrollHeight > element.clientHeight || element.scrollWidth > element.clientWidth;
+      const overflow = scrollableOverflow(element);
+      const scrollable = overflow.x > 0 || overflow.y > 0;
       if (scrollable) element.setAttribute('tabindex', '0');
       else element.removeAttribute('tabindex');
     };

package/src/components/select.css

@@ -194,7 +194,7 @@
  *                                                                                                 *
  ***************************************************************************************************/
 
-/* raised: the default. A field, as in v2: a flat soft fill with a faint edge, no shadow. */
+/* raised: the default. A field: the surface colour with --control-chrome, like a raised button. */
 
 .kui-SelectTrigger:where(.kui-variant-raised) {
   position: relative;

package/src/components/shell.css

@@ -253,12 +253,20 @@
     pointer-events: auto;
   }
   /* A Toolbar spans the row, and so may a cluster inside it. pointer-events inherits, so the
-     Toolbar passes clicks through and only its controls and groups take them back: the empty
-     stretch between them lets clicks reach the content. */
+     Toolbar and its layout boxes pass clicks through, and every interactive element in it takes
+     them back, with whatever it holds: the empty stretch between them lets clicks reach the
+     content. A group and a text field are painted boxes, so they keep their clicks too. */
   & > :where(.kui-Toolbar) {
     pointer-events: none;
   }
-  & > :where(.kui-Toolbar) :where(.kui-ToolbarGroup, .kui-BaseButton, .kui-TextFieldRoot, .kui-SelectTrigger, .kui-SegmentedControlRoot, [href], [tabindex]) {
+  /* The native controls are named by tag: any of them may sit in a Toolbar. */
+  /* stylelint-disable-next-line selector-max-type */
+  & > :where(.kui-Toolbar) :where(
+      button, a[href], input, select, textarea, label, summary, [tabindex], [contenteditable]:not([contenteditable='false']),
+      [role='button'], [role='link'], [role='checkbox'], [role='switch'], [role='radio'], [role='radiogroup'],
+      [role='slider'], [role='combobox'], [role='tab'], [role='tablist'], [role='menuitem'], [aria-haspopup],
+      .kui-ToolbarGroup, .kui-TextFieldRoot
+    ) {
     pointer-events: auto;
   }
 }

package/src/components/shell.tsx

@@ -33,7 +33,7 @@ import type { BottomPublicProps } from './_internal/shell-bottom.js';
 import { Inspector } from './_internal/shell-inspector.js';
 import type { InspectorPublicProps } from './_internal/shell-inspector.js';
 import { usePane, paneAttributes, usePresentationTable } from './_internal/shell-pane.js';
-import { splitHandles, useResizablePane } from './_internal/shell-resizable.js';
+import { splitHandles, useInitialPaneSize, useResizablePane } from './_internal/shell-resizable.js';
 import {
   FIXED_TABLE,
   ShellInsetContext,
@@ -54,6 +54,7 @@ import { readBreakpoint } from '../hooks/use-breakpoint.js';
 import { useThemeSize } from '../hooks/theme-size.js';
 import { PaneChromeScope, PaneFooter, PaneHeader, Scroll, ShellContentContext, ShellSizeContext } from './_internal/pane-chrome.js';
 import type { PaneSize, PaneHeaderProps, PaneFooterProps, ScrollProps } from './_internal/pane-chrome.js';
+import { PaneBandSizeContext } from './_internal/pane-band-context.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, PaneMode, PaneName, PaneTarget, ResponsivePresentation, SidebarMode } from './shell.types.js';
 
 /* ── Root ──────────────────────────────────────────────────────────────────── */
@@ -371,6 +372,8 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
       <ShellSizeContext.Provider value={size}>
       <ShellContentContext.Provider value={false}>
       <ShellInsetContext.Provider value={insetContext}>
+      {/* A Shell inside a portalled surface's Theme starts with no band, like any other. */}
+      <PaneBandSizeContext.Provider value={undefined}>
         {/* The Root is not a widget: it hears Escape bubbling up from the panes,
             after their own handlers, to close the overlays. */}
         {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions */}
@@ -391,6 +394,7 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
               the accessibility tree, so the scrim itself is hidden from it. */}
           <div className="kui-ShellScrim" aria-hidden onClick={closeOverlays} />
         </div>
+      </PaneBandSizeContext.Provider>
       </ShellInsetContext.Provider>
       </ShellContentContext.Provider>
       </ShellSizeContext.Provider>
@@ -650,6 +654,8 @@ const Panel = React.forwardRef<HTMLDivElement, PanelPublicProps>((props, ref) =>
     requestToggle: () => pane.toggle('toggle'),
   });
 
+  // The starting size is in the server HTML, so the pane does not jump on hydration.
+  const initialSize = useInitialPaneSize(size, defaultSize, minSize, maxSize);
   const { handles, content } = splitHandles(children, PanelHandle);
   const handle = resizable && pane.shown !== false && !pane.overlaying ? <PaneResizeContext.Provider value={resize}>{handles.length > 0 ? handles : <PaneHandle />}</PaneResizeContext.Provider> : null;
 
@@ -667,6 +673,7 @@ const Panel = React.forwardRef<HTMLDivElement, PanelPublicProps>((props, ref) =>
         {
           ...style,
           '--panel-expanded-size': `${expandedSize}px`,
+          ...(initialSize ? { '--panel-size': initialSize } : {}),
         } as CSSPropertiesWithVars
       }
     >

package/src/components/slider.tsx

@@ -140,6 +140,24 @@ const Slider = React.forwardRef<SliderElement, SliderProps>((ownProps, forwarded
     [snapToTicks, sortedTicks, snapKeyStep, snapToNearestTick, currentValue, onValueChange, isControlled],
   );
 
+  // Radix commits its own step value on a key press, before the snapped value comes back. So
+  // the commit snaps the same way the change did, and a key press that snaps back to where the
+  // handle was commits nothing.
+  const handleValueCommit = React.useCallback(
+    (newValue: number[]) => {
+      if (!onValueCommit) return;
+      if (!snapToTicks || sortedTicks.length === 0) {
+        onValueCommit(newValue);
+        return;
+      }
+      const keyboard = keyboardChangeRef.current;
+      const finalValue = newValue.map((v, i) => (keyboard && currentValue[i] !== undefined ? snapKeyStep(v, currentValue[i]) : snapToNearestTick(v)));
+      if (keyboard && finalValue.every((v, i) => v === currentValue[i])) return;
+      onValueCommit(finalValue);
+    },
+    [onValueCommit, snapToTicks, sortedTicks, snapKeyStep, snapToNearestTick, currentValue],
+  );
+
   // Cleanup timeout on unmount
   React.useEffect(() => {
     return () => {
@@ -170,7 +188,7 @@ const Slider = React.forwardRef<SliderElement, SliderProps>((ownProps, forwarded
           rootProps.onPointerDown?.(event);
         }}
         onValueChange={handleValueChange}
-        onValueCommit={onValueCommit}
+        onValueCommit={handleValueCommit}
         asChild={false}
         className={classNames('kui-SliderRoot', className)}
       >

package/src/components/text-area.css

@@ -354,7 +354,7 @@
  *                                                                                                 *
  ***************************************************************************************************/
 
-/* Raised variant: the default. A flat soft fill with a faint edge, as in v2. A field casts no shadow. */
+/* Raised variant: the default. The surface colour with --control-chrome, like a raised button. */
 .kui-TextAreaRoot:where(.kui-variant-raised) {
   --text-area-border-width: 1px;
   --v-selection-color: var(--focus-a5);
@@ -464,7 +464,19 @@
  *                                                                                                 *
  ***************************************************************************************************/
 
-/* A sibling of the root, below the box: it takes the field's type itself. */
+/* With an error message, one box holds the field and the message below it. */
+.kui-TextAreaWrapper {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+
+  /* A height given to the pair goes to the box, the message keeps its own. */
+  & > :where(.kui-TextAreaRoot) {
+    flex: 1 1 auto;
+  }
+}
+
+/* Below the box, outside its paint: it takes the field's type itself. */
 .kui-TextAreaErrorMessage {
   font-family: var(--default-font-family);
   font-weight: var(--font-weight-regular);

package/src/components/text-area.tsx

@@ -3,6 +3,7 @@ import classNames from 'classnames';
 
 import { textAreaPropDefs } from './text-area.props.js';
 import { extractProps } from '../helpers/extract-props.js';
+import { mergeStyles } from '../helpers/merge-styles.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
 
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
@@ -18,9 +19,12 @@ interface TextAreaProps
     TextAreaOwnProps {}
 
 const TextArea = React.forwardRef<TextAreaElement, TextAreaProps>((ownProps, forwardedRef) => {
-  const props = useThemeSizeProps(ownProps, textAreaPropDefs.size);
+  // The caller's className and style are kept apart from the size and variant classes: with an
+  // error message they go on the wrapper, which is then the one box the parent lays out.
+  const { className: ownClassName, style: ownStyle, ...themedProps } = useThemeSizeProps(ownProps, textAreaPropDefs.size);
   const { className, color, radius, style, ...textAreaProps } =
-    extractProps(props, textAreaPropDefs);
+    extractProps(themedProps, textAreaPropDefs);
+  const wrapped = Boolean(textAreaProps.errorMessage);
 
   // Generate unique IDs for accessibility
   const errorId = React.useId();
@@ -58,32 +62,36 @@ const TextArea = React.forwardRef<TextAreaElement, TextAreaProps>((ownProps, for
     ...nativeTextAreaProps
   } = textAreaProps;
 
-  // The message is a sibling of the painted root, so it sits below the box rather than inside it.
+  const field = (
+    <div
+      data-accent-color={color}
+      data-radius={radius}
+      className={classNames('kui-TextAreaRoot', className, !wrapped && ownClassName, {
+        // Not used by the library's CSS (invalid styling keys on aria-invalid); kept as a hook for app styles.
+        'kui-error': isInvalid,
+      })}
+      style={wrapped ? style : mergeStyles(style, ownStyle)}
+    >
+      <textarea
+        className="kui-reset kui-TextAreaInput"
+        ref={forwardedRef}
+        {...nativeTextAreaProps}
+        required={required || undefined}
+        {...ariaProps}
+      />
+    </div>
+  );
+  if (!wrapped) return field;
+
+  // With a message, one wrapper holds the box and the message below it, so the parent still
+  // lays out a single box and the caller's className and style size the pair.
   return (
-    <>
-      <div
-        data-accent-color={color}
-        data-radius={radius}
-        className={classNames('kui-TextAreaRoot', className, {
-          // Not used by the library's CSS (invalid styling keys on aria-invalid); kept as a hook for app styles.
-          'kui-error': isInvalid,
-        })}
-        style={style}
-      >
-        <textarea
-          className="kui-reset kui-TextAreaInput"
-          ref={forwardedRef}
-          {...nativeTextAreaProps}
-          required={required || undefined}
-          {...ariaProps}
-        />
+    <div className={classNames('kui-TextAreaWrapper', ownClassName)} style={ownStyle}>
+      {field}
+      <div id={errorId} className="kui-TextAreaErrorMessage" role="alert">
+        {textAreaProps.errorMessage}
       </div>
-      {textAreaProps.errorMessage && (
-        <div id={errorId} className="kui-TextAreaErrorMessage" role="alert">
-          {textAreaProps.errorMessage}
-        </div>
-      )}
-    </>
+    </div>
   );
 });
 

package/src/components/text-field.css

@@ -392,7 +392,7 @@
   }
 }
 
-/* raised: the default. A flat soft fill with a faint edge, as in v2. A field casts no shadow. */
+/* raised: the default. The surface colour with --control-chrome, like a raised button. */
 
 .kui-TextFieldRoot:where(.kui-variant-raised) {
   --text-field-selection-color: var(--focus-a5);
@@ -645,8 +645,15 @@
 }
 
 /* Error message styling */
+/* With an error message, one box holds the field and the message below it. */
+.kui-TextFieldWrapper {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
 .kui-TextFieldErrorMessage {
-  /* A sibling of the root, below the field: it takes the field's type itself. */
+  /* Below the field, outside its paint: it takes the field's type itself. */
   font-family: var(--default-font-family);
   font-weight: var(--font-weight-regular);
   color: var(--red-11);

package/src/components/text-field.tsx

@@ -3,10 +3,11 @@
 import * as React from 'react';
 import * as ReactDOM from 'react-dom';
 import classNames from 'classnames';
-import { composeEventHandlers, composeRefs } from 'radix-ui/internal';
+import { composeEventHandlers, composeRefs, useLayoutEffect } from 'radix-ui/internal';
 
 import { textFieldRootPropDefs, textFieldSlotPropDefs, type TextFieldSlotScrubProps } from './text-field.props.js';
 import { extractProps } from '../helpers/extract-props.js';
+import { mergeStyles } from '../helpers/merge-styles.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
 
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
@@ -31,9 +32,12 @@ const TextFieldContext = React.createContext<TextFieldContextValue | null>(null)
 const FOCUSABLE_IN_SLOT = 'button, a, input, select, textarea, label, [tabindex], [contenteditable]';
 
 const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>((ownProps, forwardedRef) => {
-  const props = useThemeSizeProps(ownProps, textFieldRootPropDefs.size);
+  // The caller's className and style are kept apart from the size and variant classes: with an
+  // error message they go on the wrapper, which is then the one box the parent lays out.
+  const { className: ownClassName, style: ownStyle, ...themedProps } = useThemeSizeProps(ownProps, textFieldRootPropDefs.size);
   const inputRef = React.useRef<HTMLInputElement>(null);
-  const { children, className, color, radius, style, ...inputProps } = extractProps(props, textFieldRootPropDefs);
+  const { children, className, color, radius, style, ...inputProps } = extractProps(themedProps, textFieldRootPropDefs);
+  const wrapped = Boolean(inputProps.errorMessage);
 
   // Generate unique IDs for accessibility
   const errorId = React.useId();
@@ -99,30 +103,34 @@ const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>
     } catch {}
   }, []);
 
-  // The message is a sibling of the painted root, so it sits below the field rather than inside it.
+  // A pointer-only hit-target redirect to the input; keyboard users reach the input directly.
+  const field = (
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions
+    <div
+      data-accent-color={color}
+      data-radius={radius}
+      style={wrapped ? style : mergeStyles(style, ownStyle)}
+      className={classNames('kui-TextFieldRoot', className, !wrapped && ownClassName, {
+        // Not used by the library's CSS (invalid styling keys on aria-invalid); kept as a hook for app styles.
+        'kui-error': isInvalid,
+      })}
+      onMouseDown={handleMouseDown}
+    >
+      <input {...nativeInputProps} required={required || undefined} {...ariaProps} ref={composeRefs(inputRef, forwardedRef)} className="kui-reset kui-TextFieldInput" />
+      <TextFieldContext.Provider value={contextValue}>{children}</TextFieldContext.Provider>
+    </div>
+  );
+  if (!wrapped) return field;
+
+  // With a message, one wrapper holds the field and the message below it, so the parent still
+  // lays out a single box and the caller's className and style size the pair.
   return (
-    <>
-      {/* A pointer-only hit-target redirect to the input; keyboard users reach the input directly. */}
-      {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions */}
-      <div
-        data-accent-color={color}
-        data-radius={radius}
-        style={style}
-        className={classNames('kui-TextFieldRoot', className, {
-          // Not used by the library's CSS (invalid styling keys on aria-invalid); kept as a hook for app styles.
-          'kui-error': isInvalid,
-        })}
-        onMouseDown={handleMouseDown}
-      >
-        <input {...nativeInputProps} required={required || undefined} {...ariaProps} ref={composeRefs(inputRef, forwardedRef)} className="kui-reset kui-TextFieldInput" />
-        <TextFieldContext.Provider value={contextValue}>{children}</TextFieldContext.Provider>
+    <div className={classNames('kui-TextFieldWrapper', ownClassName)} style={ownStyle}>
+      {field}
+      <div id={errorId} className="kui-TextFieldErrorMessage" role="alert">
+        {inputProps.errorMessage}
       </div>
-      {inputProps.errorMessage && (
-        <div id={errorId} className="kui-TextFieldErrorMessage" role="alert">
-          {inputProps.errorMessage}
-        </div>
-      )}
-    </>
+    </div>
   );
 });
 TextFieldRoot.displayName = 'TextField.Root';
@@ -151,13 +159,21 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
     textFieldSlotPropDefs,
   );
 
-  // The slot describes the input (see TextFieldRoot); a caller's own id is kept.
+  // A slot of text describes the input (see TextFieldRoot); a caller's own id is kept. A slot
+  // holding a control, such as a show-password button, does not: the input would be described
+  // by the button's name.
   const generatedId = React.useId();
   const slotId = slotProps.id ?? generatedId;
   const registerSlot = React.useContext(TextFieldContext)?.registerSlot;
-  React.useEffect(() => registerSlot?.(slotId), [registerSlot, slotId]);
-
   const slotRef = React.useRef<HTMLDivElement>(null);
+  // Unknown until the slot has rendered; it registers once it is known to hold only text.
+  const [holdsControl, setHoldsControl] = React.useState<boolean | null>(null);
+  useLayoutEffect(() => {
+    const next = Boolean(slotRef.current?.querySelector(FOCUSABLE_IN_SLOT));
+    setHoldsControl((prev) => (prev === next ? prev : next));
+  });
+  React.useEffect(() => (holdsControl === false ? registerSlot?.(slotId) : undefined), [registerSlot, slotId, holdsControl]);
+
   const [isScrubbing, setIsScrubbing] = React.useState(false);
   // Where the virtual cursor starts. Movement is written straight to the cursor element, so a
   // scrub does not re-render the slot on every mouse move.

package/src/components/theme.tsx

@@ -6,6 +6,7 @@ import { Direction, Slot } from 'radix-ui';
 
 import { getMatchingGrayColor } from '../helpers/get-matching-gray-color.js';
 import { ThemeSizeContext } from '../hooks/theme-size.js';
+import { PaneBandSizeContext } from './_internal/pane-band-context.js';
 import { usePropSyncedState } from '../hooks/use-prop-synced-state.js';
 import { themePropDefs } from './theme.props.js';
 
@@ -149,6 +150,7 @@ interface ThemeImplPrivateProps extends Partial<ThemeChangeHandlers> {
 }
 const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, forwardedRef) => {
   const context = React.useContext(ThemeContext);
+  const outerBand = React.useContext(PaneBandSizeContext);
   const {
     asChild,
     isRoot,
@@ -219,30 +221,34 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
         ],
       )}
     >
-      {/* Size travels on its own context as a bare string, so the components
-          that read it do not re-render when another theme value changes. */}
-      <ThemeSizeContext.Provider value={size}>
-        <Comp
-          data-is-root-theme={isRoot ? 'true' : 'false'}
-          data-accent-color={accentColor}
-          data-gray-color={resolvedGrayColor}
-          // for nested `Theme` background
-          data-has-background={hasBackground ? 'true' : 'false'}
-          data-radius={radius}
-          data-font-family={fontFamily}
-          data-heading-font-family={headingFontFamily}
-          ref={forwardedRef}
-          {...themeProps}
-          className={classNames(
-            'kui-theme',
-            {
-              light: appearance === 'light',
-              dark: appearance === 'dark',
-            },
-            themeProps.className,
-          )}
-        />
-      </ThemeSizeContext.Provider>
+      {/* A nested `Theme asChild` is the root of a portalled surface (Popover, Dialog, Sheet,
+          menus), which sits outside any Shell pane even though context flows into it. */}
+      <PaneBandSizeContext.Provider value={asChild && !isRoot ? null : outerBand}>
+        {/* Size travels on its own context as a bare string, so the components
+            that read it do not re-render when another theme value changes. */}
+        <ThemeSizeContext.Provider value={size}>
+          <Comp
+            data-is-root-theme={isRoot ? 'true' : 'false'}
+            data-accent-color={accentColor}
+            data-gray-color={resolvedGrayColor}
+            // for nested `Theme` background
+            data-has-background={hasBackground ? 'true' : 'false'}
+            data-radius={radius}
+            data-font-family={fontFamily}
+            data-heading-font-family={headingFontFamily}
+            ref={forwardedRef}
+            {...themeProps}
+            className={classNames(
+              'kui-theme',
+              {
+                light: appearance === 'light',
+                dark: appearance === 'dark',
+              },
+              themeProps.className,
+            )}
+          />
+        </ThemeSizeContext.Provider>
+      </PaneBandSizeContext.Provider>
     </ThemeContext.Provider>
   );
 });