@womp/kookie-ui 0.26.1 → 0.26.3

package/src/components/context-menu.tsx

@@ -17,7 +17,8 @@ import {
   contextMenuCheckboxItemPropDefs,
   contextMenuRadioItemPropDefs,
 } from './context-menu.props.js';
-import { Theme, useThemeContext } from './theme.js';
+import { useThemeContext } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { ThickCheckIcon, ThickChevronRightIcon, ThickDotIcon } from './icons.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
@@ -133,7 +134,7 @@ const ContextMenuContent = React.forwardRef<ContextMenuContentElement, ContextMe
 
     return (
       <ContextMenuPrimitive.Portal container={container} forceMount={forceMount}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <ContextMenuPrimitive.Content
             data-accent-color={resolvedColor}
             alignOffset={getMenuAlignOffset(scalarSize)}
@@ -159,7 +160,7 @@ const ContextMenuContent = React.forwardRef<ContextMenuContentElement, ContextMe
               </ScrollArea>
             )}
           </ContextMenuPrimitive.Content>
-        </Theme>
+        </PortalTheme>
       </ContextMenuPrimitive.Portal>
     );
   },
@@ -419,7 +420,7 @@ const ContextMenuSubContent = React.forwardRef<
 
   return (
     <ContextMenuPrimitive.Portal container={container} forceMount={forceMount}>
-      <Theme asChild>
+      <PortalTheme asChild>
         <ContextMenuPrimitive.SubContent
           data-accent-color={color}
           alignOffset={getMenuAlignOffset(scalarSize)}
@@ -449,7 +450,7 @@ const ContextMenuSubContent = React.forwardRef<
             </ScrollArea>
           )}
         </ContextMenuPrimitive.SubContent>
-      </Theme>
+      </PortalTheme>
     </ContextMenuPrimitive.Portal>
   );
 });

package/src/components/dialog.tsx

@@ -5,7 +5,7 @@ import { Dialog as DialogPrimitive } from 'radix-ui';
 import { dialogContentPropDefs } from './dialog.props.js';
 import { Heading } from './heading.js';
 import { Text } from './text.js';
-import { Theme } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
@@ -48,7 +48,7 @@ const DialogContent = React.forwardRef<DialogContentElement, DialogContentProps>
 
   return (
     <DialogPrimitive.Portal container={container} forceMount={forceMount}>
-      <Theme asChild>
+      <PortalTheme asChild>
         <DialogPrimitive.Overlay className="kui-BaseDialogOverlay kui-DialogOverlay">
           <div className="kui-BaseDialogScroll kui-DialogScroll">
             <div className={`kui-BaseDialogScrollPadding kui-DialogScrollPadding ${alignClassName}`}>
@@ -67,7 +67,7 @@ const DialogContent = React.forwardRef<DialogContentElement, DialogContentProps>
             </div>
           </div>
         </DialogPrimitive.Overlay>
-      </Theme>
+      </PortalTheme>
     </DialogPrimitive.Portal>
   );
 });

package/src/components/dropdown-menu.tsx

@@ -13,7 +13,8 @@ import {
   dropdownMenuCheckboxItemPropDefs,
   dropdownMenuRadioItemPropDefs,
 } from './dropdown-menu.props.js';
-import { Theme, useThemeContext } from './theme.js';
+import { useThemeContext } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { ChevronDownIcon, ThickCheckIcon, ThickChevronLeftIcon, ThickChevronRightIcon, ThickDotIcon } from './icons.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
@@ -196,7 +197,7 @@ const DropdownMenuContent = React.forwardRef<DropdownMenuContentElement, Dropdow
 
     return (
       <DropdownMenuPrimitive.Portal container={container} forceMount={forceMount}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <DropdownMenuPrimitive.Content
             data-accent-color={resolvedColor}
             align="start"
@@ -227,7 +228,7 @@ const DropdownMenuContent = React.forwardRef<DropdownMenuContentElement, Dropdow
               </ScrollArea>
             )}
           </DropdownMenuPrimitive.Content>
-        </Theme>
+        </PortalTheme>
       </DropdownMenuPrimitive.Portal>
     );
   },
@@ -724,7 +725,7 @@ const CascadeSubContent = React.forwardRef<DropdownMenuSubContentElement, Dropdo
 
     return (
       <DropdownMenuPrimitive.Portal container={container} forceMount={forceMount}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <DropdownMenuPrimitive.SubContent
             data-accent-color={color}
             alignOffset={getMenuAlignOffset(scalarSize)}
@@ -754,7 +755,7 @@ const CascadeSubContent = React.forwardRef<DropdownMenuSubContentElement, Dropdo
               </ScrollArea>
             )}
           </DropdownMenuPrimitive.SubContent>
-        </Theme>
+        </PortalTheme>
       </DropdownMenuPrimitive.Portal>
     );
   },

package/src/components/popover.tsx

@@ -6,7 +6,7 @@ import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
 import { popoverContentPropDefs } from './popover.props.js';
-import { Theme } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 
 import type { PopoverContentOwnProps } from './popover.props.js';
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
@@ -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,52 +64,27 @@ 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}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <PopoverPrimitive.Content
             align="start"
             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>
-        </Theme>
+        </PortalTheme>
       </PopoverPrimitive.Portal>
     );
   },
@@ -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/select.tsx

@@ -13,7 +13,8 @@ import {
   selectTriggerPropDefs,
   selectContentPropDefs,
 } from './select.props.js';
-import { useThemeContext, Theme } from './theme.js';
+import { useThemeContext } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { useThumbSync } from '../hooks/use-thumb-sync.js';
 
 import type { GetPropDefTypes } from '../props/prop-def.js';
@@ -203,7 +204,7 @@ const SelectContent = React.forwardRef<SelectContentElement, SelectContentProps>
     const resolvedColor = color || themeContext.accentColor;
     return (
       <SelectPrimitive.Portal container={container}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <SelectPrimitive.Content
             data-accent-color={resolvedColor}
             sideOffset={4}
@@ -220,7 +221,7 @@ const SelectContent = React.forwardRef<SelectContentElement, SelectContentProps>
           >
             <SelectScrollArea>{children}</SelectScrollArea>
           </SelectPrimitive.Content>
-        </Theme>
+        </PortalTheme>
       </SelectPrimitive.Portal>
     );
   },

package/src/components/sheet.tsx

@@ -38,7 +38,7 @@ import { Dialog as DialogPrimitive } from 'radix-ui';
 
 import { dialogContentPropDefs } from './dialog.props.js';
 import type { DialogContentOwnProps } from './dialog.props.js';
-import { Theme } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { Heading } from './heading.js';
 import { Text } from './text.js';
 import { extractProps } from '../helpers/extract-props.js';
@@ -147,7 +147,7 @@ const Content = React.forwardRef<SheetContentElement, SheetContentProps>((allPro
   return (
     <DialogPrimitive.Portal container={container} forceMount={forceMount}>
       <SheetTitleCountContext.Provider value={titleCountRef}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <DialogPrimitive.Overlay className="kui-BaseDialogOverlay kui-DialogOverlay kui-SheetOverlay">
             <DialogPrimitive.Content
               {...contentProps}
@@ -157,7 +157,7 @@ const Content = React.forwardRef<SheetContentElement, SheetContentProps>((allPro
               aria-modal="true"
             />
           </DialogPrimitive.Overlay>
-        </Theme>
+        </PortalTheme>
       </SheetTitleCountContext.Provider>
     </DialogPrimitive.Portal>
   );

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/spinner.css

@@ -98,8 +98,23 @@
   }
 }
 
+/* A Spinner with children is one tree, loading or not. At rest it steps out of layout. */
+.kui-SpinnerHost:where(:not([data-loading])) {
+  display: contents;
+}
+
+.kui-SpinnerHost:where([data-loading]) {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.kui-SpinnerChildren {
+  display: contents;
+}
+
 /* Children of a Spinner keep their space but are not shown while it spins. A class, not an inline style. */
 .kui-SpinnerHiddenChildren {
-  display: contents;
   visibility: hidden;
 }

package/src/components/spinner.tsx

@@ -19,7 +19,8 @@ const Spinner = React.forwardRef<SpinnerElement, SpinnerProps>((props, forwarded
     spinnerPropDefs
   );
 
-  if (!loading) return children;
+  // Without children a Spinner is only the wheel, shown while loading.
+  if (children === undefined && !loading) return null;
 
   // Decorative unless named: a named spinner is a status message, an unnamed one is hidden.
   const named =
@@ -50,22 +51,22 @@ const Spinner = React.forwardRef<SpinnerElement, SpinnerProps>((props, forwarded
 
   if (children === undefined) return spinner;
 
+  // With children, one tree whether loading or not, so starting or stopping never remounts them
+  // (their state, focus and refs survive). At rest the host is `display: contents`; while loading
+  // it centres the wheel over the children, which keep their space but are hidden.
   return (
-    <Flex asChild position="relative" align="center" justify="center">
-      <span aria-busy="true">
-        {/**
-         * `display: contents` removes the content from the accessibility tree in some browsers,
-         * so we force remove it with `aria-hidden`
-         */}
-        <span aria-hidden className="kui-SpinnerHiddenChildren">
-          {children}
-        </span>
-
+    <span className="kui-SpinnerHost" data-loading={loading || undefined} aria-busy={loading || undefined}>
+      {/* `display: contents` removes the content from the accessibility tree in some browsers, so
+          while loading it is removed with `aria-hidden` too. */}
+      <span aria-hidden={loading || undefined} className={classNames('kui-SpinnerChildren', loading && 'kui-SpinnerHiddenChildren')}>
+        {children}
+      </span>
+      {loading ? (
         <Flex asChild align="center" justify="center" position="absolute" inset="0">
           <span>{spinner}</span>
         </Flex>
-      </span>
-    </Flex>
+      ) : null}
+    </span>
   );
 });
 Spinner.displayName = 'Spinner';

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,24 @@
  *                                                                                                 *
  ***************************************************************************************************/
 
-/* 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. Without one the
+   wrapper steps out of layout, and the field is the box. */
+.kui-TextAreaWrapper:where(:not([data-message])) {
+  display: contents;
+}
+
+.kui-TextAreaWrapper:where([data-message]) {
+  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,38 @@ 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>
+  );
+  // The wrapper is always there, so a message coming or going never moves the field in the tree:
+  // moving it would remount the input, dropping focus, the caret and an uncontrolled value. With
+  // no message it is `display: contents` and the field is the box the parent lays out; with one
+  // it holds the field and the message below it, 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>
-      {textAreaProps.errorMessage && (
+    <div className={classNames('kui-TextAreaWrapper', wrapped && ownClassName)} style={wrapped ? ownStyle : undefined} data-message={wrapped || undefined}>
+      {field}
+      {wrapped ? (
         <div id={errorId} className="kui-TextAreaErrorMessage" role="alert">
           {textAreaProps.errorMessage}
         </div>
-      )}
-    </>
+      ) : null}
+    </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,20 @@
 }
 
 /* Error message styling */
+/* With an error message, one box holds the field and the message below it. Without one the
+   wrapper steps out of layout, and the field is the box. */
+.kui-TextFieldWrapper:where(:not([data-message])) {
+  display: contents;
+}
+
+.kui-TextFieldWrapper:where([data-message]) {
+  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);