@womp/kookie-ui 0.24.0 → 0.25.1

package/src/components/virtual-menu.tsx

@@ -3,6 +3,7 @@
 import * as React from 'react';
 import classNames from 'classnames';
 import { useVirtualizer } from '@tanstack/react-virtual';
+import { useLayoutEffect } from 'radix-ui/internal';
 import { useMenuContext, useMenuClose, getMenuItemHeight } from './_internal/menu-context.js';
 
 import type { MenuSize } from './_internal/menu-context.js';
@@ -55,37 +56,58 @@ interface VirtualMenuRenderItemProps<T> {
   'data-highlighted': true | undefined;
   /** Data attribute for event delegation */
   'data-index': number;
+  /** Number of items in the whole list, since only some rows are mounted */
+  'aria-setsize': number;
+  /** Position of this row in the whole list, from 1 */
+  'aria-posinset': number;
   /** Mouse enter handler */
   onMouseEnter: (e: React.MouseEvent<HTMLElement>) => void;
   /** Mouse leave handler */
-  onMouseLeave: () => void;
+  onMouseLeave: (e: React.MouseEvent<HTMLElement>) => void;
   /** Click handler */
   onClick: (e: React.MouseEvent<HTMLElement>) => void;
   /** Keyboard handler for Enter/Space activation */
   onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
 }
 
-interface VirtualMenuProps<T> {
+/** How rows are drawn: one of `itemLabel` or `renderItem` is required. */
+type VirtualMenuRowProps<T> =
+  | {
+      /**
+       * Simple label accessor for basic text items.
+       * Can be a property key or a function.
+       * @example
+       * itemLabel="name"
+       * itemLabel={(item) => item.name}
+       */
+      itemLabel: keyof T | ((item: T) => React.ReactNode);
+      renderItem?: undefined;
+    }
+  | {
+      itemLabel?: undefined;
+      /**
+       * Custom component for rendering items.
+       * Must be memoized (React.memo) for optimal performance.
+       * @example
+       * const MyItem = React.memo(({ item, ...props }) => (
+       *   <VirtualMenu.Item {...props}>{item.name}</VirtualMenu.Item>
+       * ));
+       * <VirtualMenu items={items} renderItem={MyItem} />
+       */
+      renderItem: React.ComponentType<VirtualMenuRenderItemProps<T>>;
+    };
+
+/** Attributes of the list element that pass through, such as `id`, `aria-labelledby` or `data-*`. */
+type VirtualMenuDivProps = Omit<
+  React.ComponentPropsWithoutRef<'div'>,
+  'children' | 'onSelect' | 'role' | 'tabIndex' | 'aria-activedescendant'
+>;
+
+type VirtualMenuProps<T> = VirtualMenuDivProps & VirtualMenuRowProps<T> & VirtualMenuOwnProps<T>;
+
+interface VirtualMenuOwnProps<T> {
   /** Array of items to render */
   items: T[];
-  /**
-   * Simple label accessor for basic text items.
-   * Can be a property key or a function.
-   * @example
-   * itemLabel="name"
-   * itemLabel={(item) => item.name}
-   */
-  itemLabel?: keyof T | ((item: T) => React.ReactNode);
-  /**
-   * Custom component for rendering items.
-   * Must be memoized (React.memo) for optimal performance.
-   * @example
-   * const MyItem = React.memo(({ item, ...props }) => (
-   *   <VirtualMenu.Item {...props}>{item.name}</VirtualMenu.Item>
-   * ));
-   * <VirtualMenu items={items} renderItem={MyItem} />
-   */
-  renderItem?: React.ComponentType<VirtualMenuRenderItemProps<T>>;
   /**
    * Menu size - controls item height.
    * Automatically inherited from parent DropdownMenu.Content/ContextMenu.Content.
@@ -104,18 +126,24 @@ interface VirtualMenuProps<T> {
   overscan?: number;
   /** Callback when an item is selected */
   onSelect?: (item: T, index: number) => void;
-  /** Additional class name */
-  className?: string;
-  /** Additional styles */
-  style?: React.CSSProperties;
-  /** Accessible label for the menu */
-  'aria-label'?: string;
 }
 
 // ============================================================================
 // Internal Memoized Item Component
 // ============================================================================
 
+/**
+ * Rows get a new style object every render, so style is compared by the two values the
+ * list sets. Every other prop is compared shallowly, so aria-*, data-* and handlers update.
+ */
+function areRowPropsEqual<P extends { style?: React.CSSProperties }>(prev: P, next: P) {
+  if (prev.style?.height !== next.style?.height) return false;
+  if (prev.style?.transform !== next.style?.transform) return false;
+  const prevKeys = Object.keys(prev) as (keyof P)[];
+  if (prevKeys.length !== Object.keys(next).length) return false;
+  return prevKeys.every((key) => key === 'style' || Object.is(prev[key], next[key]));
+}
+
 interface SimpleItemProps {
   label: React.ReactNode;
   isHighlighted: boolean;
@@ -124,8 +152,10 @@ interface SimpleItemProps {
   tabIndex: number;
   'data-highlighted': true | undefined;
   'data-index': number;
+  'aria-setsize': number;
+  'aria-posinset': number;
   onMouseEnter: (e: React.MouseEvent<HTMLElement>) => void;
-  onMouseLeave: () => void;
+  onMouseLeave: (e: React.MouseEvent<HTMLElement>) => void;
   onClick: (e: React.MouseEvent<HTMLElement>) => void;
   onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
 }
@@ -139,6 +169,8 @@ const SimpleItem = React.memo(
     tabIndex,
     'data-highlighted': dataHighlighted,
     'data-index': dataIndex,
+    'aria-setsize': setSize,
+    'aria-posinset': posInSet,
     onMouseEnter,
     onMouseLeave,
     onClick,
@@ -153,6 +185,8 @@ const SimpleItem = React.memo(
         tabIndex={tabIndex}
         data-highlighted={dataHighlighted}
         data-index={dataIndex}
+        aria-setsize={setSize}
+        aria-posinset={posInSet}
         onMouseEnter={onMouseEnter}
         onMouseLeave={onMouseLeave}
         onClick={onClick}
@@ -162,17 +196,7 @@ const SimpleItem = React.memo(
       </div>
     );
   },
-  (prev, next) => {
-    // Custom comparison - only re-render if these change
-    if (prev.label !== next.label) return false;
-    if (prev['data-highlighted'] !== next['data-highlighted']) return false;
-    if (prev.style.height !== next.style.height) return false;
-    if (prev.style.transform !== next.style.transform) return false;
-    if (prev.tabIndex !== next.tabIndex) return false;
-    if (prev.id !== next.id) return false;
-    // Event handlers are stable, skip comparison
-    return true;
-  },
+  areRowPropsEqual,
 );
 
 // ============================================================================
@@ -189,7 +213,7 @@ function useMeasuredRowHeight(
   size: MenuSize | undefined,
 ) {
   const [height, setHeight] = React.useState<number | undefined>(undefined);
-  React.useLayoutEffect(() => {
+  useLayoutEffect(() => {
     const root = rootRef.current;
     if (!enabled || !root) return;
     const probe = document.createElement('div');
@@ -216,7 +240,9 @@ function VirtualMenuRootInner<T>(
     onSelect,
     className,
     style,
-    'aria-label': ariaLabel,
+    onKeyDown,
+    onFocus,
+    ...rootProps
   }: VirtualMenuProps<T>,
   forwardedRef: React.ForwardedRef<HTMLDivElement>,
 ) {
@@ -287,7 +313,7 @@ function VirtualMenuRootInner<T>(
   const virtualItems = virtualizer.getVirtualItems();
 
   // Re-measure cached rows when the resolved row height changes.
-  React.useLayoutEffect(() => {
+  useLayoutEffect(() => {
     virtualizer.measure();
   }, [virtualizer, estimatedItemSize]);
 
@@ -307,6 +333,10 @@ function VirtualMenuRootInner<T>(
   }, [isInsideMenu]);
 
   // Refs for stable handler references
+  const onKeyDownRef = React.useRef(onKeyDown);
+  const onFocusRef = React.useRef(onFocus);
+  onKeyDownRef.current = onKeyDown;
+  onFocusRef.current = onFocus;
   const itemsRef = React.useRef(items);
   const onSelectRef = React.useRef(onSelect);
   const closeMenuRef = React.useRef(closeMenu);
@@ -341,7 +371,11 @@ function VirtualMenuRootInner<T>(
     if (index != null) selectIndex(Number(index));
   }, [selectIndex]);
 
-  const noop = React.useCallback(() => {}, []);
+  // Leaving a row clears its highlight, as a Radix item does on pointer leave.
+  const handleItemMouseLeave = React.useCallback((e: React.MouseEvent<HTMLElement>) => {
+    const index = Number(e.currentTarget.dataset.index);
+    setHighlightedIndex((current) => (current === index ? -1 : current));
+  }, []);
 
   // Item-level keyboard handler for Enter/Space activation (satisfies a11y lint rule)
   const handleItemKeyDown = React.useCallback((e: React.KeyboardEvent<HTMLElement>) => {
@@ -354,7 +388,9 @@ function VirtualMenuRootInner<T>(
   }, [selectIndex]);
 
   // Keyboard navigation
-  const handleKeyDown = React.useCallback((e: React.KeyboardEvent) => {
+  const handleKeyDown = React.useCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
+    onKeyDownRef.current?.(e);
+    if (e.defaultPrevented) return;
     const currentItems = itemsRef.current;
     const currentHighlightedIndex = highlightedIndexRef.current;
 
@@ -395,19 +431,27 @@ function VirtualMenuRootInner<T>(
         break;
       }
       case 'Tab': {
-        e.preventDefault();
+        // Inside a menu, Tab does not leave it. On its own, the list is one tab stop.
+        if (isInsideMenu) e.preventDefault();
         break;
       }
       case 'Escape': {
         // Inside a menu, the menu handles Escape and returns focus to its trigger.
-        if (!isInsideMenu) (e.currentTarget as HTMLElement).blur();
+        if (!isInsideMenu) e.currentTarget.blur();
         break;
       }
+      default: {
+        // The parent menu's typeahead would move focus off the list onto one of its items.
+        if (isInsideMenu && e.key.length === 1 && !e.ctrlKey && !e.altKey && !e.metaKey) {
+          e.stopPropagation();
+        }
+      }
     }
   }, [selectIndex, isInsideMenu]);
 
   // Keyboard focus on the list highlights the first row when none is highlighted.
   const handleFocus = React.useCallback((e: React.FocusEvent<HTMLDivElement>) => {
+    onFocusRef.current?.(e);
     if (e.target !== e.currentTarget) return;
     if (highlightedIndexRef.current < 0 && itemsRef.current.length > 0) setHighlightedIndex(0);
   }, []);
@@ -440,14 +484,19 @@ function VirtualMenuRootInner<T>(
 
   return (
     <div
+      {...rootProps}
       ref={setRootRef}
       role={isInsideMenu ? 'group' : 'menu'}
-      aria-label={ariaLabel}
       aria-activedescendant={safeHighlightedIndex >= 0 ? getItemId(safeHighlightedIndex) : undefined}
       tabIndex={0}
       onKeyDown={handleKeyDown}
       onFocus={handleFocus}
-      className={classNames('kui-VirtualMenuRoot', className)}
+      className={classNames(
+        'kui-VirtualMenuRoot',
+        // On its own, the list draws menu rows at its own size (virtual-menu.css).
+        !isInsideMenu && `kui-r-size-${sizeProp ?? '2'}`,
+        className,
+      )}
       style={rootStyle}
     >
       <div className="kui-VirtualMenuViewport" style={viewportStyle}>
@@ -465,11 +514,14 @@ function VirtualMenuRootInner<T>(
             id: getItemId(index),
             isHighlighted,
             style: itemStyle,
-            tabIndex: isHighlighted ? 0 : -1,
+            // The list holds focus and points aria-activedescendant at the row, so it is the only tab stop.
+            tabIndex: -1,
             'data-highlighted': isHighlighted ? true as const : undefined,
             'data-index': index,
+            'aria-setsize': items.length,
+            'aria-posinset': index + 1,
             onMouseEnter: handleItemMouseEnter,
-            onMouseLeave: noop,
+            onMouseLeave: handleItemMouseLeave,
             onClick: handleItemClick,
             onKeyDown: handleItemKeyDown,
           };
@@ -533,19 +585,8 @@ const VirtualMenuItemInner = React.forwardRef<HTMLDivElement, VirtualMenuItemPro
 
 VirtualMenuItemInner.displayName = 'VirtualMenu.Item';
 
-// Memoized with custom comparison
-const VirtualMenuItem = React.memo(VirtualMenuItemInner, (prevProps, nextProps) => {
-  const prevStyle = prevProps.style as React.CSSProperties | undefined;
-  const nextStyle = nextProps.style as React.CSSProperties | undefined;
-  if (prevStyle?.height !== nextStyle?.height) return false;
-  if (prevStyle?.transform !== nextStyle?.transform) return false;
-  if (prevProps['data-highlighted'] !== nextProps['data-highlighted']) return false;
-  if (prevProps.tabIndex !== nextProps.tabIndex) return false;
-  if (prevProps.id !== nextProps.id) return false;
-  if (prevProps.className !== nextProps.className) return false;
-  if (prevProps.children !== nextProps.children) return false;
-  return true;
-});
+// Style is compared by height and transform; every other prop shallowly.
+const VirtualMenuItem = React.memo(VirtualMenuItemInner, areRowPropsEqual);
 
 // ============================================================================
 // Exports

package/src/helpers/get-margin-styles.ts

@@ -7,21 +7,19 @@ import type { MarginProps } from '../props/margin.props.js';
 const marginValues = marginPropDefs.m.values;
 const marginValueSet: ReadonlySet<string> = new Set(marginValues);
 
-// Static table so the common case — a component with no margin props at all —
+// Built once from the prop defs, so the custom properties are the ones the
+// stylesheet reads. The common case, a component with no margin props at all,
 // is seven property reads and nothing else.
+const MARGIN_KEYS = ['m', 'mx', 'my', 'mt', 'mr', 'mb', 'ml'] as const;
 const MARGIN_PROPS: ReadonlyArray<{
   key: keyof MarginProps;
   className: string;
   customProperties: `--${string}`[];
-}> = [
-  { key: 'm', className: 'kui-r-m', customProperties: ['--margin'] },
-  { key: 'mx', className: 'kui-r-mx', customProperties: ['--margin-left', '--margin-right'] },
-  { key: 'my', className: 'kui-r-my', customProperties: ['--margin-top', '--margin-bottom'] },
-  { key: 'mt', className: 'kui-r-mt', customProperties: ['--margin-top'] },
-  { key: 'mr', className: 'kui-r-mr', customProperties: ['--margin-right'] },
-  { key: 'mb', className: 'kui-r-mb', customProperties: ['--margin-bottom'] },
-  { key: 'ml', className: 'kui-r-ml', customProperties: ['--margin-left'] },
-];
+}> = MARGIN_KEYS.map((key) => ({
+  key,
+  className: marginPropDefs[key].className,
+  customProperties: [...marginPropDefs[key].customProperties] as `--${string}`[],
+}));
 
 export function getMarginStyles(props: MarginProps) {
   let classes: string[] | undefined;

package/src/helpers/index.ts

@@ -14,3 +14,6 @@ export * from './merge-styles.js';
 export * from './normalize-to-px.js';
 export * from './require-react-element.js';
 export * from './theme-size.js';
+// The context and its hooks are client code. The server-safe build keeps this import external, so
+// `/helpers` shares the one context the components read and stays loadable from a server component.
+export { ThemeSizeContext, useThemeSize, useThemeSizeProps } from '../hooks/theme-size.js';

package/src/helpers/theme-size.ts

@@ -1,26 +1,16 @@
-'use client';
-
-import * as React from 'react';
+/**
+ * The pure half of the theme size: the type, the default and the clamp. Server-safe.
+ *
+ * The context and the hooks that read it live in `hooks/theme-size.ts`, a client module, so there
+ * is one `ThemeSizeContext` and importing `/helpers` from a server component does not call
+ * `createContext`.
+ */
 
 type ThemeSize = '1' | '2' | '3' | '4';
 
 /** The rest of the 1-4 index when no Theme states a size. */
 const THEME_SIZE_DEFAULT: ThemeSize = '2';
 
-/**
- * The app-wide size index, provided by `Theme` beside `ThemeContext`.
- *
- * It is its own context, holding one string, so a component that only needs
- * the size does not re-render when the accent colour or appearance changes.
- */
-const ThemeSizeContext = React.createContext<ThemeSize>(THEME_SIZE_DEFAULT);
-ThemeSizeContext.displayName = 'ThemeSizeContext';
-
-interface SizePropDef {
-  values: readonly string[];
-  default?: string;
-}
-
 /**
  * Maps the theme size onto a component's own range: the value itself when the
  * component has it, otherwise the nearest end of the range (`4` on a 1-3 scale
@@ -41,33 +31,5 @@ function clampSize(size: ThemeSize, values: readonly string[]): string {
   return nearest;
 }
 
-/**
- * The size a component on the 1-4 index takes: what the caller said, else the
- * nearest Theme's size, mapped into the component's range.
- */
-function useThemeSize<V>(explicit: V | undefined, propDef: SizePropDef): V {
-  const themeSize = React.useContext(ThemeSizeContext);
-  if (explicit !== undefined) return explicit;
-  // The clamped value is one of `propDef.values`, which is what `V` ranges over.
-  return clampSize(themeSize, propDef.values) as V;
-}
-
-/**
- * Fills `size` from the nearest Theme when the caller left it unset, so the
- * result can go straight into `extractProps`. An explicit size, responsive
- * object included, wins.
- *
- * Returns the same props object when there is nothing to fill: when a size is
- * set, or when the theme size resolves to the prop def's own default (the
- * common case, a Theme with no size), so `extractProps` applies it as before.
- */
-function useThemeSizeProps<P extends { size?: unknown }>(props: P, propDef: SizePropDef): P {
-  const themeSize = React.useContext(ThemeSizeContext);
-  if (props.size !== undefined) return props;
-  const size = clampSize(themeSize, propDef.values);
-  if (size === propDef.default) return props;
-  return { ...props, size };
-}
-
-export { ThemeSizeContext, THEME_SIZE_DEFAULT, clampSize, useThemeSize, useThemeSizeProps };
+export { THEME_SIZE_DEFAULT, clampSize };
 export type { ThemeSize };

package/src/hooks/theme-size.ts

@@ -0,0 +1,50 @@
+'use client';
+
+import * as React from 'react';
+
+import { THEME_SIZE_DEFAULT, clampSize } from '../helpers/theme-size.js';
+import type { ThemeSize } from '../helpers/theme-size.js';
+
+/**
+ * The app-wide size index, provided by `Theme` beside `ThemeContext`.
+ *
+ * It is its own context, holding one string, so a component that only needs
+ * the size does not re-render when the accent colour or appearance changes.
+ */
+const ThemeSizeContext = React.createContext<ThemeSize>(THEME_SIZE_DEFAULT);
+ThemeSizeContext.displayName = 'ThemeSizeContext';
+
+interface SizePropDef {
+  values: readonly string[];
+  default?: string;
+}
+
+/**
+ * The size a component on the 1-4 index takes: what the caller said, else the
+ * nearest Theme's size, mapped into the component's range.
+ */
+function useThemeSize<V>(explicit: V | undefined, propDef: SizePropDef): V {
+  const themeSize = React.useContext(ThemeSizeContext);
+  if (explicit !== undefined) return explicit;
+  // The clamped value is one of `propDef.values`, which is what `V` ranges over.
+  return clampSize(themeSize, propDef.values) as V;
+}
+
+/**
+ * Fills `size` from the nearest Theme when the caller left it unset, so the
+ * result can go straight into `extractProps`. An explicit size, responsive
+ * object included, wins.
+ *
+ * Returns the same props object when there is nothing to fill: when a size is
+ * set, or when the theme size resolves to the prop def's own default (the
+ * common case, a Theme with no size), so `extractProps` applies it as before.
+ */
+function useThemeSizeProps<P extends { size?: unknown }>(props: P, propDef: SizePropDef): P {
+  const themeSize = React.useContext(ThemeSizeContext);
+  if (props.size !== undefined) return props;
+  const size = clampSize(themeSize, propDef.values);
+  if (size === propDef.default) return props;
+  return { ...props, size };
+}
+
+export { ThemeSizeContext, useThemeSize, useThemeSizeProps };

package/src/hooks/use-appearance.ts

@@ -26,12 +26,15 @@ function emit() {
   for (const listener of listeners) listener();
 }
 
+// The last choice made on this page, for when storage is blocked and cannot hold it.
+let pageChoice: AppearanceChoice = 'system';
+
 function readChoice(): AppearanceChoice {
   try {
     const value = globalThis.localStorage?.getItem(APPEARANCE_STORAGE_KEY);
     return value === 'light' || value === 'dark' ? value : 'system';
   } catch {
-    return 'system';
+    return pageChoice;
   }
 }
 
@@ -67,34 +70,44 @@ function getSnapshot() {
 
 const serverSnapshot = { choice: 'system' as AppearanceChoice, resolved: 'light' as ResolvedAppearance };
 
+// With no stored choice, follow the system as it changes.
+function onSystemChange() {
+  if (readChoice() === 'system') {
+    stamp(systemAppearance());
+    emit();
+  }
+}
+
+// Another tab changed the choice.
+function onStorage(event: StorageEvent) {
+  if (event.key !== APPEARANCE_STORAGE_KEY) return;
+  const choice = readChoice();
+  stamp(choice === 'system' ? systemAppearance() : choice);
+  emit();
+}
+
+let media: MediaQueryList | null = null;
+
+// One set of window listeners for every subscriber, so one change stamps `<html>` once.
 function subscribe(listener: () => void) {
+  if (listeners.size === 0) {
+    media = window.matchMedia('(prefers-color-scheme: dark)');
+    media.addEventListener('change', onSystemChange);
+    window.addEventListener('storage', onStorage);
+  }
   listeners.add(listener);
-  const media = window.matchMedia('(prefers-color-scheme: dark)');
-  // With no stored choice, follow the system as it changes.
-  const onSystemChange = () => {
-    if (readChoice() === 'system') {
-      stamp(systemAppearance());
-      emit();
-    }
-  };
-  // Another tab changed the choice.
-  const onStorage = (event: StorageEvent) => {
-    if (event.key !== APPEARANCE_STORAGE_KEY) return;
-    const choice = readChoice();
-    stamp(choice === 'system' ? systemAppearance() : choice);
-    emit();
-  };
-  media.addEventListener('change', onSystemChange);
-  window.addEventListener('storage', onStorage);
   return () => {
     listeners.delete(listener);
-    media.removeEventListener('change', onSystemChange);
+    if (listeners.size > 0) return;
+    media?.removeEventListener('change', onSystemChange);
+    media = null;
     window.removeEventListener('storage', onStorage);
   };
 }
 
 /** Applies a choice to `<html>` and stores it. The change applies even if storage is blocked. */
 function setAppearance(choice: AppearanceChoice) {
+  pageChoice = choice;
   try {
     if (choice === 'system') localStorage.removeItem(APPEARANCE_STORAGE_KEY);
     else localStorage.setItem(APPEARANCE_STORAGE_KEY, choice);