@womp/kookie-ui 0.24.0 → 0.25.1

package/src/components/combobox.tsx

@@ -25,9 +25,10 @@ import { useCallbackRef, useComposedRefs, useControllableState, useLayoutEffect
 import { Command as CommandPrimitive, useCommandState } from 'cmdk';
 
 import { extractProps } from '../helpers/extract-props.js';
-import { useThemeSize } from '../helpers/theme-size.js';
+import { useThemeSize } from '../hooks/theme-size.js';
 import { comboboxRootPropDefs, comboboxTriggerPropDefs, comboboxContentPropDefs } from './combobox.props.js';
 import { ChevronDownIcon, ThickCheckIcon } from './icons.js';
+import { Spinner } from './spinner.js';
 import { Theme, useThemeContext } from './theme.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
 import * as Popover from './popover.js';
@@ -365,36 +366,25 @@ const ComboboxTrigger = React.forwardRef<ComboboxTriggerElement, ComboboxTrigger
   const handleKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
     onKeyDown?.(event);
     if (event.defaultPrevented || isBlocked || isDisabled) return;
-    if (event.key === 'ArrowDown') {
+    // Both arrows open the list, as on Select (APG select-only combobox).
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
       ctx.setOpen(true);
     }
   };
 
+  const loadingIcon = (
+    <span className="kui-SelectIcon kui-SelectLoadingIcon" aria-hidden="true">
+      <Spinner />
+    </span>
+  );
+
   const defaultContent = (
     <>
       <span className="kui-SelectTriggerInner">
         <span className="kui-ComboboxValue">{ctx.displayValue ?? ctx.value ?? placeholder ?? ctx.placeholder}</span>
       </span>
-      {loading ? (
-        <div className="kui-SelectIcon kui-SelectLoadingIcon" aria-hidden="true">
-          <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
-            <circle
-              cx="8"
-              cy="8"
-              r="7"
-              stroke="currentColor"
-              strokeWidth="2"
-              strokeLinecap="round"
-              strokeDasharray="32"
-              strokeDashoffset="32"
-              className="kui-SelectLoadingIconCircle"
-            />
-          </svg>
-        </div>
-      ) : (
-        <ChevronDownIcon className="kui-SelectIcon" />
-      )}
+      {loading ? loadingIcon : <ChevronDownIcon className="kui-SelectIcon" />}
     </>
   );
 
@@ -413,10 +403,11 @@ const ComboboxTrigger = React.forwardRef<ComboboxTriggerElement, ComboboxTrigger
         {...triggerProps}
         // eslint-disable-next-line jsx-a11y/role-has-required-aria-props -- Popover.Trigger (Slot) adds aria-expanded and aria-controls
         role="combobox"
-        aria-disabled={isDisabled || undefined}
-        aria-readonly={readOnly || undefined}
-        aria-invalid={error || undefined}
-        aria-busy={loading || undefined}
+        // The props win when set; otherwise a caller's own aria-* (a form library's aria-invalid) stays, as on Select.
+        aria-disabled={isDisabled || triggerProps['aria-disabled']}
+        aria-readonly={readOnly || triggerProps['aria-readonly']}
+        aria-invalid={error || triggerProps['aria-invalid']}
+        aria-busy={loading || triggerProps['aria-busy']}
         type={buttonType ?? 'button'}
         disabled={isDisabled}
         onClick={handleClick}
@@ -424,7 +415,15 @@ const ComboboxTrigger = React.forwardRef<ComboboxTriggerElement, ComboboxTrigger
         ref={composedRef}
         className={classNames('kui-reset', 'kui-SelectTrigger', 'kui-ComboboxTrigger', className)}
       >
-        {children ? requireReactElement(children) : defaultContent}
+        {/* Custom children replace the value and chevron; the spinner still shows while loading. */}
+        {children ? (
+          <>
+            {requireReactElement(children)}
+            {loading ? loadingIcon : null}
+          </>
+        ) : (
+          defaultContent
+        )}
       </button>
     </Popover.Trigger>
   );
@@ -774,7 +773,7 @@ const ComboboxItem = React.forwardRef<ComboboxItemElement, ComboboxItemProps>(
     const searchKeywords = text ? (keywords ? [text, ...keywords] : [text]) : keywords;
     // cmdk stores keywords only when `value` changes. Remount the cmdk item when
     // they change so a new label or keyword list is picked up.
-    const keywordsKey = searchKeywords ? searchKeywords.join('') : '';
+    const keywordsKey = searchKeywords ? searchKeywords.join('\u0000') : '';
 
     const isDisabled = disabled ?? rootDisabled ?? false;
 

package/src/components/context-menu.tsx

@@ -5,7 +5,6 @@
 'use client';
 
 import * as React from 'react';
-import { VirtualMenu } from './virtual-menu.js';
 import classNames from 'classnames';
 import { ContextMenu as ContextMenuPrimitive, Slot } from 'radix-ui';
 import { useCallbackRef } from 'radix-ui/internal';
@@ -21,9 +20,15 @@ import {
 import { Theme, useThemeContext } from './theme.js';
 import { ThickCheckIcon, ThickChevronRightIcon, ThickDotIcon } from './icons.js';
 import { extractProps } from '../helpers/extract-props.js';
-import { useThemeSizeProps } from '../helpers/theme-size.js';
+import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
-import { MenuCloseProvider, MenuProvider } from './_internal/menu-context.js';
+import {
+  MenuCloseProvider,
+  MenuGroupLabelProvider,
+  MenuProvider,
+  useMenuGroupLabelId,
+  useMenuGroupLabelledBy,
+} from './_internal/menu-context.js';
 import {
   MenuShortcut,
   getMenuAlignOffset,
@@ -165,14 +170,18 @@ type ContextMenuLabelElement = React.ElementRef<typeof ContextMenuPrimitive.Labe
 interface ContextMenuLabelProps
   extends ComponentPropsWithout<typeof ContextMenuPrimitive.Label, RemovedProps> {}
 const ContextMenuLabel = React.forwardRef<ContextMenuLabelElement, ContextMenuLabelProps>(
-  ({ className, ...props }, forwardedRef) => (
-    <ContextMenuPrimitive.Label
-      {...props}
-      asChild={false}
-      ref={forwardedRef}
-      className={classNames('kui-BaseMenuLabel', 'kui-ContextMenuLabel', className)}
-    />
-  ),
+  ({ className, id: idProp, ...props }, forwardedRef) => {
+    const id = useMenuGroupLabelId(idProp);
+    return (
+      <ContextMenuPrimitive.Label
+        {...props}
+        id={id}
+        asChild={false}
+        ref={forwardedRef}
+        className={classNames('kui-BaseMenuLabel', 'kui-ContextMenuLabel', className)}
+      />
+    );
+  },
 );
 ContextMenuLabel.displayName = 'ContextMenu.Label';
 
@@ -210,14 +219,20 @@ type ContextMenuGroupElement = React.ElementRef<typeof ContextMenuPrimitive.Grou
 interface ContextMenuGroupProps
   extends ComponentPropsWithout<typeof ContextMenuPrimitive.Group, RemovedProps> {}
 const ContextMenuGroup = React.forwardRef<ContextMenuGroupElement, ContextMenuGroupProps>(
-  ({ className, ...props }, forwardedRef) => (
-    <ContextMenuPrimitive.Group
-      {...props}
-      asChild={false}
-      ref={forwardedRef}
-      className={classNames('kui-BaseMenuGroup', 'kui-ContextMenuGroup', className)}
-    />
-  ),
+  ({ className, 'aria-labelledby': ariaLabelledBy, ...props }, forwardedRef) => {
+    const [labelledBy, setLabelId] = useMenuGroupLabelledBy(ariaLabelledBy);
+    return (
+      <MenuGroupLabelProvider value={setLabelId}>
+        <ContextMenuPrimitive.Group
+          aria-labelledby={labelledBy}
+          {...props}
+          asChild={false}
+          ref={forwardedRef}
+          className={classNames('kui-BaseMenuGroup', 'kui-ContextMenuGroup', className)}
+        />
+      </MenuGroupLabelProvider>
+    );
+  },
 );
 ContextMenuGroup.displayName = 'ContextMenu.Group';
 
@@ -227,14 +242,20 @@ interface ContextMenuRadioGroupProps
 const ContextMenuRadioGroup = React.forwardRef<
   ContextMenuRadioGroupElement,
   ContextMenuRadioGroupProps
->(({ className, ...props }, forwardedRef) => (
-  <ContextMenuPrimitive.RadioGroup
-    {...props}
-    asChild={false}
-    ref={forwardedRef}
-    className={classNames('kui-BaseMenuRadioGroup', 'kui-ContextMenuRadioGroup', className)}
-  />
-));
+>(({ className, 'aria-labelledby': ariaLabelledBy, ...props }, forwardedRef) => {
+  const [labelledBy, setLabelId] = useMenuGroupLabelledBy(ariaLabelledBy);
+  return (
+    <MenuGroupLabelProvider value={setLabelId}>
+      <ContextMenuPrimitive.RadioGroup
+        aria-labelledby={labelledBy}
+        {...props}
+        asChild={false}
+        ref={forwardedRef}
+        className={classNames('kui-BaseMenuRadioGroup', 'kui-ContextMenuRadioGroup', className)}
+      />
+    </MenuGroupLabelProvider>
+  );
+});
 ContextMenuRadioGroup.displayName = 'ContextMenu.RadioGroup';
 
 type ContextMenuRadioItemElement = React.ElementRef<typeof ContextMenuPrimitive.RadioItem>;
@@ -464,7 +485,6 @@ export {
   ContextMenuSubTrigger as SubTrigger,
   ContextMenuSubContent as SubContent,
   ContextMenuSeparator as Separator,
-  VirtualMenu as Virtual,
 };
 
 export type {

package/src/components/dialog.tsx

@@ -7,7 +7,7 @@ import { Heading } from './heading.js';
 import { Text } from './text.js';
 import { Theme } from './theme.js';
 import { extractProps } from '../helpers/extract-props.js';
-import { useThemeSizeProps } from '../helpers/theme-size.js';
+import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
 import { useBodyPointerEventsCleanup } from '../hooks/use-body-pointer-events-cleanup.js';
 

package/src/components/dropdown-menu.css

@@ -98,9 +98,3 @@
   margin-inline-start: calc(-2px * var(--scale));
   margin-inline-end: 0;
 }
-
-/***************************************************************************************************
- *                                                                                                 *
- * DRILL-DOWN ANIMATIONS                                                                           *
- *                                                                                                 *
- ***************************************************************************************************/

package/src/components/dropdown-menu.tsx

@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { VirtualMenu } from './virtual-menu.js';
 import classNames from 'classnames';
 import { DropdownMenu as DropdownMenuPrimitive, Slot } from 'radix-ui';
 import { useCallbackRef } from 'radix-ui/internal';
@@ -17,19 +16,24 @@ import {
 import { Theme, useThemeContext } from './theme.js';
 import { ChevronDownIcon, ThickCheckIcon, ThickChevronLeftIcon, ThickChevronRightIcon, ThickDotIcon } from './icons.js';
 import { extractProps } from '../helpers/extract-props.js';
-import { useThemeSizeProps } from '../helpers/theme-size.js';
+import { useThemeSizeProps } from '../hooks/theme-size.js';
 import {
   DrillDownLevelContext,
   DrillDownRoot,
   SubContext,
   useCreateDrillDownStore,
-  useDrillDownDirection,
   useDrillDownStore,
   usePanelPosition,
   useStackEntry,
   useSubContext,
 } from './_internal/dropdown-menu-drill-down.js';
-import { MenuCloseProvider, MenuProvider } from './_internal/menu-context.js';
+import {
+  MenuCloseProvider,
+  MenuGroupLabelProvider,
+  MenuProvider,
+  useMenuGroupLabelId,
+  useMenuGroupLabelledBy,
+} from './_internal/menu-context.js';
 import {
   MenuShortcut,
   getMenuAlignOffset,
@@ -234,11 +238,14 @@ type DropdownMenuLabelElement = React.ElementRef<typeof DropdownMenuPrimitive.La
 interface DropdownMenuLabelProps
   extends ComponentPropsWithout<typeof DropdownMenuPrimitive.Label, RemovedProps> {}
 const DropdownMenuLabel = React.forwardRef<DropdownMenuLabelElement, DropdownMenuLabelProps>(
-  ({ className, ...props }, forwardedRef) => {
-    if (!React.useContext(DrillDownLevelContext)) return null;
+  ({ className, id: idProp, ...props }, forwardedRef) => {
+    const isLevelVisible = React.useContext(DrillDownLevelContext);
+    const id = useMenuGroupLabelId(idProp, isLevelVisible);
+    if (!isLevelVisible) return null;
     return (
       <DropdownMenuPrimitive.Label
         {...props}
+        id={id}
         asChild={false}
         ref={forwardedRef}
         className={classNames('kui-BaseMenuLabel', 'kui-DropdownMenuLabel', className)}
@@ -284,14 +291,22 @@ type DropdownMenuGroupElement = React.ElementRef<typeof DropdownMenuPrimitive.Gr
 interface DropdownMenuGroupProps
   extends ComponentPropsWithout<typeof DropdownMenuPrimitive.Group, RemovedProps> {}
 const DropdownMenuGroup = React.forwardRef<DropdownMenuGroupElement, DropdownMenuGroupProps>(
-  ({ className, ...props }, forwardedRef) => (
-    <DropdownMenuPrimitive.Group
-      {...props}
-      asChild={false}
-      ref={forwardedRef}
-      className={classNames('kui-BaseMenuGroup', 'kui-DropdownMenuGroup', className)}
-    />
-  ),
+  ({ className, 'aria-labelledby': ariaLabelledBy, ...props }, forwardedRef) => {
+    const [labelledBy, setLabelId] = useMenuGroupLabelledBy(ariaLabelledBy);
+    // A drill-down level that is not on screen keeps its groups only to hold the open path.
+    const isLevelVisible = React.useContext(DrillDownLevelContext);
+    return (
+      <MenuGroupLabelProvider value={setLabelId}>
+        <DropdownMenuPrimitive.Group
+          {...(isLevelVisible ? { 'aria-labelledby': labelledBy } : { role: 'none' })}
+          {...props}
+          asChild={false}
+          ref={forwardedRef}
+          className={classNames('kui-BaseMenuGroup', 'kui-DropdownMenuGroup', className)}
+        />
+      </MenuGroupLabelProvider>
+    );
+  },
 );
 DropdownMenuGroup.displayName = 'DropdownMenu.Group';
 
@@ -301,14 +316,21 @@ interface DropdownMenuRadioGroupProps
 const DropdownMenuRadioGroup = React.forwardRef<
   DropdownMenuRadioGroupElement,
   DropdownMenuRadioGroupProps
->(({ className, ...props }, forwardedRef) => (
-  <DropdownMenuPrimitive.RadioGroup
-    {...props}
-    asChild={false}
-    ref={forwardedRef}
-    className={classNames('kui-BaseMenuRadioGroup', 'kui-DropdownMenuRadioGroup', className)}
-  />
-));
+>(({ className, 'aria-labelledby': ariaLabelledBy, ...props }, forwardedRef) => {
+  const [labelledBy, setLabelId] = useMenuGroupLabelledBy(ariaLabelledBy);
+  const isLevelVisible = React.useContext(DrillDownLevelContext);
+  return (
+    <MenuGroupLabelProvider value={setLabelId}>
+      <DropdownMenuPrimitive.RadioGroup
+        {...(isLevelVisible ? { 'aria-labelledby': labelledBy } : { role: 'none' })}
+        {...props}
+        asChild={false}
+        ref={forwardedRef}
+        className={classNames('kui-BaseMenuRadioGroup', 'kui-DropdownMenuRadioGroup', className)}
+      />
+    </MenuGroupLabelProvider>
+  );
+});
 DropdownMenuRadioGroup.displayName = 'DropdownMenu.RadioGroup';
 
 type DropdownMenuRadioItemElement = React.ElementRef<typeof DropdownMenuPrimitive.RadioItem>;
@@ -412,28 +434,44 @@ const DropdownMenuSub: React.FC<DropdownMenuSubProps> = ({
   const subContextValue = React.useMemo(() => ({ id, label }), [id, label]);
   const isOpenInDrillDown = usePanelPosition(drillDownStore, id) !== 'closed';
 
-  // Drill-down: `open` and `defaultOpen` drive the stack; the stack drives
-  // `onOpenChange`. A controlled `open` is applied when it changes.
+  const handleOpenChange = useCallbackRef(onOpenChange);
+  const isControlled = open !== undefined;
+
+  // Drill-down, controlled: navigating asks `onOpenChange` and leaves the stack to `open`.
+  React.useLayoutEffect(() => {
+    if (!drillDownStore || !isControlled) return;
+    drillDownStore.setController(id, handleOpenChange);
+    return () => drillDownStore.setController(id, null);
+  }, [drillDownStore, isControlled, id, handleOpenChange]);
+
   React.useLayoutEffect(() => {
     if (!drillDownStore || open === undefined) return;
-    if (open && !drillDownStore.isOpen(id)) drillDownStore.push(id, null);
-    else if (!open && drillDownStore.isOpen(id)) drillDownStore.close(id);
+    if (open && !drillDownStore.isOpen(id)) drillDownStore.open(id, drillDownStore.takePendingModality(id));
+    else if (!open && drillDownStore.isOpen(id)) drillDownStore.close(id, drillDownStore.takePendingModality(id));
   }, [drillDownStore, open, id]);
 
-  const defaultOpenRef = React.useRef(defaultOpen);
+  // A `defaultOpen` push on mount is the starting state, not a change to report.
+  const defaultOpenRef = React.useRef(open === undefined && Boolean(defaultOpen));
   React.useLayoutEffect(() => {
-    if (drillDownStore && defaultOpenRef.current && open === undefined) drillDownStore.push(id, null);
+    if (drillDownStore && defaultOpenRef.current) drillDownStore.open(id);
+    else defaultOpenRef.current = false;
     // Only on mount, like an uncontrolled default.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  const handleOpenChange = useCallbackRef(onOpenChange);
+  // Uncontrolled, the stack drives `onOpenChange`. Controlled, it reports only a close
+  // the `open` prop did not ask for, such as a parent level closing.
   const wasOpenRef = React.useRef(isOpenInDrillDown);
   React.useEffect(() => {
     if (!drillDownStore || wasOpenRef.current === isOpenInDrillDown) return;
     wasOpenRef.current = isOpenInDrillDown;
+    if (isOpenInDrillDown && defaultOpenRef.current) {
+      defaultOpenRef.current = false;
+      return;
+    }
+    if (open !== undefined && open === isOpenInDrillDown) return;
     handleOpenChange(isOpenInDrillDown);
-  }, [drillDownStore, isOpenInDrillDown, handleOpenChange]);
+  }, [drillDownStore, isOpenInDrillDown, handleOpenChange, open]);
 
   // Radix Sub stays mounted in both behaviors so switching behavior does not
   // remount the subtree. It only renders context; in drill-down its trigger
@@ -483,8 +521,8 @@ const DropdownMenuSubTrigger = React.forwardRef<
     };
 
     return (
+      // The row navigates within the same menu, so it announces no popup.
       <DropdownMenuPrimitive.Item
-        aria-haspopup="menu"
         {...subTriggerProps}
         data-drill-down-trigger={subContext.id}
         data-drill-down-name={subTriggerProps.textValue}
@@ -737,7 +775,6 @@ const DrillDownPanel = React.forwardRef<DropdownMenuSubContentElement, DrillDown
   ({ store, sub, ...props }, forwardedRef) => {
     const position = usePanelPosition(store, sub.id);
     const entry = useStackEntry(store, sub.id);
-    const direction = useDrillDownDirection(position === 'top' ? store : null);
 
     if (position === 'closed') return null;
 
@@ -763,7 +800,6 @@ const DrillDownPanel = React.forwardRef<DropdownMenuSubContentElement, DrillDown
         ref={forwardedRef}
         data-drill-down-panel={sub.id}
         data-drill-down-active={isTop ? true : undefined}
-        data-animation-direction={isTop ? (direction ?? undefined) : undefined}
         className={classNames('kui-DropdownMenuDrillDownPanel', className)}
       >
         {isTop && (
@@ -772,7 +808,9 @@ const DrillDownPanel = React.forwardRef<DropdownMenuSubContentElement, DrillDown
             <DropdownMenuPrimitive.Separator className="kui-BaseMenuSeparator kui-DropdownMenuSeparator" />
           </>
         )}
-        <DrillDownLevelContext.Provider value={isTop}>{children}</DrillDownLevelContext.Provider>
+        <MenuGroupLabelProvider value={null}>
+          <DrillDownLevelContext.Provider value={isTop}>{children}</DrillDownLevelContext.Provider>
+        </MenuGroupLabelProvider>
       </div>
     );
   },
@@ -808,7 +846,6 @@ export {
   DropdownMenuSubTrigger as SubTrigger,
   DropdownMenuSubContent as SubContent,
   DropdownMenuSeparator as Separator,
-  VirtualMenu as Virtual,
 };
 
 export type {

package/src/components/heading.props.tsx

@@ -14,7 +14,7 @@ const as = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as const;
 const sizes = ['1', '2', '3', '4', '5', '6', '7', '8', '9'] as const;
 
 const headingPropDefs = {
-  as: { type: 'enum', values: as, default: 'h1' },
+  as: { type: 'enum', values: as, default: 'h2' },
   ...asChildPropDef,
   size: {
     type: 'enum',

package/src/components/heading.tsx

@@ -7,11 +7,11 @@ import { extractProps } from '../helpers/extract-props.js';
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
 import type { GetPropDefTypes } from '../props/prop-def.js';
 
-type HeadingElement = React.ElementRef<'h1'>;
+type HeadingElement = React.ElementRef<'h2'>;
 type HeadingOwnProps = GetPropDefTypes<typeof headingPropDefs>;
 interface CommonHeadingProps extends HeadingOwnProps {}
-type HeadingH1Props = { as?: 'h1' } & ComponentPropsWithout<'h1', RemovedProps>;
-type HeadingH2Props = { as: 'h2' } & ComponentPropsWithout<'h2', RemovedProps>;
+type HeadingH1Props = { as: 'h1' } & ComponentPropsWithout<'h1', RemovedProps>;
+type HeadingH2Props = { as?: 'h2' } & ComponentPropsWithout<'h2', RemovedProps>;
 type HeadingH3Props = { as: 'h3' } & ComponentPropsWithout<'h3', RemovedProps>;
 type HeadingH4Props = { as: 'h4' } & ComponentPropsWithout<'h4', RemovedProps>;
 type HeadingH5Props = { as: 'h5' } & ComponentPropsWithout<'h5', RemovedProps>;
@@ -27,7 +27,7 @@ const Heading = React.memo(
       children,
       className,
       asChild,
-      as: Tag = 'h1',
+      as: Tag = 'h2',
       color,
       ...headingProps
     } = extractProps(props, headingPropDefs);

package/src/components/image.css

@@ -12,6 +12,11 @@
   background-color: var(--neutral-a3);
 }
 
+/* Native width and height attributes give the ratio; the height follows the width when it shrinks */
+:where(.kui-Image[width][height]) {
+  height: auto;
+}
+
 .kui-Image:where([data-status='loaded']) {
   background-color: transparent;
 }

package/src/components/image.tsx

@@ -16,21 +16,45 @@ type ImageElement = React.ElementRef<'img'>;
 type ImageOwnProps = GetPropDefTypes<typeof imagePropDefs>;
 type ImageStatus = 'loading' | 'loaded' | 'error';
 
-interface ImageProps extends ComponentPropsWithout<'img', RemovedProps | 'width' | 'height' | 'src' | 'alt'>, WidthProps, HeightProps, ImageOwnProps {
+interface ImageProps
+  extends ComponentPropsWithout<'img', RemovedProps | 'width' | 'height' | 'src' | 'alt'>,
+    Omit<WidthProps, 'width'>,
+    Omit<HeightProps, 'height'>,
+    ImageOwnProps {
   src: string;
   /** Required. Pass `""` for a decorative picture. */
   alt: string;
+  /**
+   * A number is the picture's intrinsic width in pixels, written as the `width` attribute, so the
+   * browser reserves its box before it loads. A string or responsive object sets the CSS width.
+   */
+  width?: WidthProps['width'] | number;
+  /** A number is the intrinsic height attribute; a string or responsive object sets the CSS height. */
+  height?: HeightProps['height'] | number;
 }
 
 /**
  * A plain `<img>` that loads lazily, fills its box by `fit` and takes the theme's corner.
  * One element and no wrapper: `width`, `height`, `className` and `style` all land on the
- * `<img>` itself.
+ * `<img>` itself. Numeric `width` and `height` are the native attributes, which reserve the box.
  *
  * Until it loads it rests on a quiet neutral fill, which is also what stays if it fails.
  */
 const Image = React.forwardRef<ImageElement, ImageProps>((props, forwardedRef) => {
-  const { className, alt, radius, loading = 'lazy', decoding = 'async', onLoad, onError, ...imageProps } = extractProps(props, imagePropDefs, widthPropDefs, heightPropDefs);
+  // Numbers are the native attributes, which give the browser an aspect ratio before load.
+  const { width, height, ...layoutProps } = props;
+  const widthAttribute = typeof width === 'number' ? width : undefined;
+  const heightAttribute = typeof height === 'number' ? height : undefined;
+  const { className, alt, radius, loading = 'lazy', decoding = 'async', onLoad, onError, ...imageProps } = extractProps(
+    {
+      ...layoutProps,
+      width: typeof width === 'number' ? undefined : width,
+      height: typeof height === 'number' ? undefined : height,
+    },
+    imagePropDefs,
+    widthPropDefs,
+    heightPropDefs,
+  );
 
   const [status, setStatus] = React.useState<ImageStatus>('loading');
   const ref = React.useRef<HTMLImageElement>(null);
@@ -47,6 +71,8 @@ const Image = React.forwardRef<ImageElement, ImageProps>((props, forwardedRef) =
   return (
     <img
       {...imageProps}
+      width={widthAttribute}
+      height={heightAttribute}
       ref={setRefs}
       alt={alt}
       loading={loading}

package/src/components/index.tsx

@@ -68,7 +68,7 @@ export {
   type ToolbarSlotProps,
   type ToolbarFillProps,
 } from './toolbar.js';
-export { Tooltip, type TooltipProps } from './tooltip.js';
+export { Tooltip, TooltipProvider, type TooltipProps, type TooltipProviderProps } from './tooltip.js';
 export { VirtualMenu, type VirtualMenuProps, type VirtualMenuItemProps, type VirtualMenuRenderItemProps } from './virtual-menu.js';
 export { VisuallyHidden, type VisuallyHiddenProps } from './visually-hidden.js';
 export * as Sidebar from './sidebar.js';

package/src/components/kbd.css

@@ -22,11 +22,12 @@
   word-spacing: var(--raised-word-spacing);
   border-radius: var(--radius-control-2);
   
-  /* No size prop: the size-1 box */
-  font-size: var(--font-size-1);
-  line-height: var(--line-height-1);
-  letter-spacing: var(--letter-spacing-1);
-  padding: var(--space-2) var(--space-3);
+  /* No size prop: the key follows the text around it, a step smaller, in the size-1 box's
+     proportions. In 14px text that is the size-1 box (12px type, 4px by 8px padding). */
+  font-size: 0.85em;
+  line-height: calc(16 / 12);
+  letter-spacing: 0;
+  padding: calc(4em / 12) calc(8em / 12);
 
   /* Make sure that the height is not stretched in a Flex/Grid layout */
   height: fit-content;

package/src/components/link.css

@@ -81,11 +81,7 @@
   }
 }
 
-/* all focused states underline */
-
-.kui-Link:where(:focus-visible) {
-  text-decoration-line: none;
-}
+/* Focus keeps the link's own underline setting; the focus outline marks focus. */
 
 /* Enhancement – hide underline for when Link's only child is a Code where underline is hard to see */
 .kui-Link:where(:has(.kui-Code:not(.kui-variant-ghost):only-child)) {