@womp/kookie-ui 0.3.24 → 0.3.26

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

@@ -4,11 +4,21 @@ import { isResponsiveObject } from './is-responsive-object.js';
 
 import type { Responsive, Union } from '../props/prop-def.js';
 
+/**
+ * Membership test against a prop def's enum values. Callers that already hold a
+ * compiled prop def pass `propValueSet` for an O(1) lookup; the handful of call
+ * sites that build options inline fall back to scanning the array.
+ */
+function includesValue(propValues: string[] | readonly string[], propValueSet: ReadonlySet<string> | undefined, value: string): boolean {
+  return propValueSet !== undefined ? propValueSet.has(value) : propValues.includes(value);
+}
+
 interface GetResponsiveStylesOptions {
   className: string;
   customProperties: `--${string}`[];
   value: Responsive<Union> | Responsive<string> | undefined;
   propValues: string[] | readonly string[];
+  propValueSet?: ReadonlySet<string>;
   parseValue?: (value: string) => string | undefined;
 }
 
@@ -28,28 +38,25 @@ interface GetResponsiveClassNamesOptions {
   className: string;
   value: Responsive<Union> | Responsive<string> | undefined;
   propValues: string[] | readonly string[];
+  propValueSet?: ReadonlySet<string>;
   parseValue?: (value: string) => string | undefined;
 }
 
-function getResponsiveClassNames({
-  allowArbitraryValues,
-  value,
-  className,
-  propValues,
-  parseValue = (value) => value,
-}: GetResponsiveClassNamesOptions): string | undefined {
-  const classNames: string[] = [];
-
+function getResponsiveClassNames({ allowArbitraryValues, value, className, propValues, propValueSet, parseValue = (value) => value }: GetResponsiveClassNamesOptions): string | undefined {
   if (!value) {
     return undefined;
   }
 
-  if (typeof value === 'string' && propValues.includes(value)) {
-    return getBaseClassName(className, value, parseValue);
+  if (typeof value === 'string') {
+    if (includesValue(propValues, propValueSet, value)) {
+      return getBaseClassName(className, value, parseValue);
+    }
+    return allowArbitraryValues ? className : undefined;
   }
 
   if (isResponsiveObject(value)) {
     const object = value;
+    const classNames: string[] = [];
 
     for (const bp in object) {
       // Make sure we are not iterating over keys that aren't breakpoints
@@ -60,7 +67,7 @@ function getResponsiveClassNames({
       const value = object[bp];
 
       if (value !== undefined) {
-        if (propValues.includes(value)) {
+        if (includesValue(propValues, propValueSet, value)) {
           const baseClassName = getBaseClassName(className, value, parseValue);
           const bpClassName = bp === 'initial' ? baseClassName : `${bp}:${baseClassName}`;
           classNames.push(bpClassName);
@@ -71,7 +78,7 @@ function getResponsiveClassNames({
       }
     }
 
-    return classNames.join(' ');
+    return classNames.length > 0 ? classNames.join(' ') : '';
   }
 
   if (allowArbitraryValues) {
@@ -79,11 +86,7 @@ function getResponsiveClassNames({
   }
 }
 
-function getBaseClassName(
-  className: string,
-  value: string,
-  parseValue: (value: string) => string | undefined
-): string {
+function getBaseClassName(className: string, value: string, parseValue: (value: string) => string | undefined): string {
   const delimiter = className ? '-' : '';
   const matchedValue = parseValue(value);
   const isNegative = matchedValue?.startsWith('-');
@@ -96,24 +99,25 @@ interface GetResponsiveCustomPropertiesOptions {
   customProperties: `--${string}`[];
   value: Responsive<Union> | Responsive<string> | undefined;
   propValues: string[] | readonly string[];
+  propValueSet?: ReadonlySet<string>;
   parseValue?: (value: string) => string | undefined;
 }
 
-function getResponsiveCustomProperties({
-  customProperties,
-  value,
-  propValues,
-  parseValue = (value) => value,
-}: GetResponsiveCustomPropertiesOptions) {
-  let styles: Record<string, string | undefined> = {};
-
+function getResponsiveCustomProperties({ customProperties, value, propValues, propValueSet, parseValue = (value) => value }: GetResponsiveCustomPropertiesOptions) {
   // Don't generate custom properties if the value is not arbitrary
-  if (!value || (typeof value === 'string' && propValues.includes(value))) {
+  if (!value || (typeof value === 'string' && includesValue(propValues, propValueSet, value))) {
     return undefined;
   }
 
+  let styles: Record<string, string | undefined> | undefined;
+
   if (typeof value === 'string') {
-    styles = Object.fromEntries(customProperties.map((prop) => [prop, value]));
+    const parsed = parseValue(value);
+    styles = {};
+    for (const customProperty of customProperties) {
+      styles[customProperty] = parsed;
+    }
+    return styles;
   }
 
   if (isResponsiveObject(value)) {
@@ -128,25 +132,20 @@ function getResponsiveCustomProperties({
       const value = object[bp];
 
       // Don't generate a custom property if the value is not arbitrary
-      if (propValues.includes(value)) {
+      if (value === undefined || includesValue(propValues, propValueSet, value)) {
         continue;
       }
 
+      const parsed = parseValue(value);
+      styles ??= {};
       for (const customProperty of customProperties) {
         const bpProperty = bp === 'initial' ? customProperty : `${customProperty}-${bp}`;
-        styles[bpProperty] = value;
+        styles[bpProperty] = parsed;
       }
     }
   }
 
-  for (const key in styles) {
-    const value = styles[key];
-    if (value !== undefined) {
-      styles[key] = parseValue(value);
-    }
-  }
-
-  return styles;
+  return styles ?? {};
 }
 
 export { getResponsiveStyles, getResponsiveCustomProperties, getResponsiveClassNames };

package/src/helpers/use-deprecation-warning.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+
+const PANEL_BACKGROUND_MESSAGE = 'Warning: The `panelBackground` prop is deprecated and will be removed in a future version. Use `material` prop instead.';
+
+const warned = new Set<string>();
+
+function warnOnce(message: string) {
+  if (warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+
+/**
+ * Warns, in development only, that `panelBackground` is deprecated.
+ *
+ * The `process.env.NODE_ENV` check is a compile-time constant, so a production
+ * bundle minifies the effect body away to an empty function instead of reading
+ * props and formatting a message per mounted component. The message is also
+ * logged once per session rather than once per component instance.
+ */
+export function useDeprecatedPanelBackgroundWarning(panelBackground: unknown) {
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    if (panelBackground !== undefined) warnOnce(PANEL_BACKGROUND_MESSAGE);
+  }, [panelBackground]);
+}

package/src/hooks/use-body-pointer-events-cleanup.ts

@@ -16,6 +16,20 @@ export function useBodyPointerEventsCleanup() {
 
     cleanupInstalled = true;
 
+    // Deferred cleanups are tracked so unmount can cancel the ones still
+    // queued. A timer that outlives the document reaches for `document.body`
+    // after it is gone; under jsdom that surfaces as an unhandled
+    // ReferenceError attributed to whichever test happened to be running.
+    const pending = new Set<ReturnType<typeof setTimeout>>();
+
+    const defer = (fn: () => void, delay: number) => {
+      const id = setTimeout(() => {
+        pending.delete(id);
+        fn();
+      }, delay);
+      pending.add(id);
+    };
+
     const hasOpenModal = (): boolean => {
       // Check for open dialogs/alertdialogs
       const hasDialogs = Boolean(
@@ -64,20 +78,20 @@ export function useBodyPointerEventsCleanup() {
         )
       ) {
         // Clicked outside any modal - force cleanup after a short delay
-        setTimeout(forceCleanup, 100);
+        defer(forceCleanup, 100);
       }
     };
 
     // Force cleanup on ESC key
     const onEscapeKey = (event: KeyboardEvent) => {
       if (event.key === 'Escape') {
-        setTimeout(forceCleanup, 200);
+        defer(forceCleanup, 200);
       }
     };
 
     // Safe cleanup on other interactions
     const onInteraction = () => {
-      setTimeout(safeCleanup, 50);
+      defer(safeCleanup, 50);
     };
 
     // Install global listeners
@@ -89,7 +103,7 @@ export function useBodyPointerEventsCleanup() {
 
     // Watch for DOM changes that might indicate overlay removal
     const observer = new MutationObserver(() => {
-      setTimeout(safeCleanup, 0);
+      defer(safeCleanup, 0);
     });
     observer.observe(document.body, { childList: true, subtree: true, attributes: true });
 
@@ -102,11 +116,27 @@ export function useBodyPointerEventsCleanup() {
     }, 1000);
 
     // Initial cleanup
-    setTimeout(safeCleanup, 100);
+    defer(safeCleanup, 100);
 
-    // Cleanup function (keep listeners for app lifetime)
+    // Tear everything down together. The observer is the important one: it
+    // fires while React unmounts the tree, so leaving it connected keeps
+    // queueing work against a document that is about to go away. Releasing the
+    // latch lets a later mount reinstall.
     return () => {
       clearInterval(intervalId);
+
+      pending.forEach(clearTimeout);
+      pending.clear();
+
+      observer.disconnect();
+
+      document.removeEventListener('click', onDocumentClick, true);
+      document.removeEventListener('keydown', onEscapeKey, true);
+      document.removeEventListener('pointerup', onInteraction, true);
+      document.removeEventListener('transitionend', onInteraction, true);
+      document.removeEventListener('animationend', onInteraction, true);
+
+      cleanupInstalled = false;
     };
   }, []);
 }

package/src/hooks/use-breakpoint.ts

@@ -3,61 +3,102 @@
 import * as React from 'react';
 import { _BREAKPOINTS, type Breakpoint } from '../components/shell.types.js';
 
+const QUERIES = Object.entries(_BREAKPOINTS) as Array<[Breakpoint, string]>;
+
+type Listener = () => void;
+
 /**
- * Hook to get the current breakpoint based on window width.
- * Returns 'initial' on the server and during initial hydration.
- * Uses shared breakpoint values from shell.types.js.
+ * One set of `MediaQueryList`s and one set of listeners for the whole
+ * application. Every component that asks for the breakpoint used to create and
+ * subscribe to its own copy of all five queries.
  */
-export function useBreakpoint(): { breakpoint: Breakpoint; ready: boolean } {
-  const [currentBp, setCurrentBp] = React.useState<Breakpoint>('initial');
-  const [ready, setReady] = React.useState(false);
-
-  React.useEffect(() => {
-    if (typeof window === 'undefined') return;
-
-    const queries = Object.entries(_BREAKPOINTS) as [keyof typeof _BREAKPOINTS, string][];
-    const mqls = queries.map(([k, q]) => [k, window.matchMedia(q)] as const);
-
-    // Accept optional event param to satisfy MediaQueryList listener signature
-    const compute = (_e?: MediaQueryListEvent) => {
-      // Highest matched wins
-      const matched = mqls.filter(([, m]) => m.matches).map(([k]) => k);
-      const next = (matched[matched.length - 1] as Breakpoint | undefined) ?? 'initial';
-      setCurrentBp(next);
-      setReady(true);
-    };
-
-    compute();
-    const cleanups: Array<() => void> = [];
-    mqls.forEach(([, m]) => {
-      const mm = m as MediaQueryList & {
-        addEventListener?: (type: 'change', listener: (e: MediaQueryListEvent) => void) => void;
-        removeEventListener?: (type: 'change', listener: (e: MediaQueryListEvent) => void) => void;
-        addListener?: (listener: (e: MediaQueryListEvent) => void) => void;
-        removeListener?: (listener: (e: MediaQueryListEvent) => void) => void;
-      };
-      if (typeof mm.addEventListener === 'function' && typeof mm.removeEventListener === 'function') {
-        mm.addEventListener('change', compute);
-        cleanups.push(() => mm.removeEventListener?.('change', compute));
-      } else if (typeof mm.addListener === 'function' && typeof mm.removeListener === 'function') {
-        mm.addListener(compute);
-        cleanups.push(() => mm.removeListener?.(compute));
-      }
-    });
-
-    return () => {
-      cleanups.forEach((fn) => {
-        try {
-          fn();
-        } catch (e) {
-          // MediaQueryList cleanup can fail in edge cases (e.g., already removed)
-          if (process.env.NODE_ENV !== 'production') {
-            console.warn('[useBreakpoint] MediaQueryList cleanup warning:', e);
-          }
+let mediaQueryLists: Array<[Breakpoint, MediaQueryList]> | null = null;
+const listeners = new Set<Listener>();
+let cachedBreakpoint: Breakpoint | null = null;
+
+function getMediaQueryLists() {
+  mediaQueryLists ??= QUERIES.map(([name, query]) => [name, window.matchMedia(query)] as [Breakpoint, MediaQueryList]);
+  return mediaQueryLists;
+}
+
+function computeBreakpoint(): Breakpoint {
+  // The largest matching query wins; `_BREAKPOINTS` is ordered smallest first.
+  let matched: Breakpoint = 'initial';
+  for (const [name, mql] of getMediaQueryLists()) {
+    if (mql.matches) matched = name;
+  }
+  return matched;
+}
+
+function handleChange() {
+  const next = computeBreakpoint();
+  if (next === cachedBreakpoint) return;
+  cachedBreakpoint = next;
+  listeners.forEach((listener) => listener());
+}
+
+function subscribe(listener: Listener) {
+  if (typeof window === 'undefined') return () => {};
+
+  if (listeners.size === 0) {
+    cachedBreakpoint = computeBreakpoint();
+    for (const [, mql] of getMediaQueryLists()) {
+      // Safari below 14 only has the deprecated listener API.
+      if (typeof mql.addEventListener === 'function') mql.addEventListener('change', handleChange);
+      else mql.addListener?.(handleChange);
+    }
+  }
+
+  listeners.add(listener);
+
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size > 0) return;
+
+    for (const [, mql] of getMediaQueryLists()) {
+      try {
+        if (typeof mql.removeEventListener === 'function') mql.removeEventListener('change', handleChange);
+        else mql.removeListener?.(handleChange);
+      } catch (error) {
+        // Removal can throw in edge cases, e.g. the list was already torn down.
+        if (process.env.NODE_ENV !== 'production') {
+          console.warn('[useBreakpoint] MediaQueryList cleanup warning:', error);
         }
-      });
-    };
-  }, []);
+      }
+    }
+    cachedBreakpoint = null;
+  };
+}
+
+/**
+ * `getSnapshot` must return a referentially stable value between changes, so it
+ * reads the cache that `handleChange` maintains rather than recomputing.
+ */
+function getSnapshot(): Breakpoint {
+  if (typeof window === 'undefined') return 'initial';
+  cachedBreakpoint ??= computeBreakpoint();
+  return cachedBreakpoint;
+}
+
+function getServerSnapshot(): Breakpoint {
+  return 'initial';
+}
+
+const getReadySnapshot = () => true;
+const getReadyServerSnapshot = () => false;
+
+/**
+ * The current breakpoint, and whether it has been resolved against a real
+ * viewport yet (`false` on the server and during hydration).
+ *
+ * Reads through `useSyncExternalStore` rather than settling into state from an
+ * effect. On a client render the very first pass already has the real
+ * breakpoint, instead of rendering the whole shell at `initial` and correcting
+ * it after the browser has painted.
+ */
+export function useBreakpoint(): { breakpoint: Breakpoint; ready: boolean } {
+  const breakpoint = React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const ready = React.useSyncExternalStore(subscribe, getReadySnapshot, getReadyServerSnapshot);
 
-  return { breakpoint: currentBp, ready };
+  return React.useMemo(() => ({ breakpoint, ready }), [breakpoint, ready]);
 }

package/src/hooks/use-prop-synced-state.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/**
+ * State that tracks a prop but can also be set imperatively — the shape `Theme`
+ * needs, where a prop sets the value and `ThemePanel` can change it at runtime.
+ *
+ * Adjusts state during render rather than syncing in a `useEffect`. An effect
+ * would commit one render carrying the *old* value and schedule a second one,
+ * which for a provider means every consumer renders twice and the browser can
+ * paint the stale value in between.
+ *
+ * @see https://react.dev/reference/react/useState#storing-information-from-previous-renders
+ */
+export function usePropSyncedState<T>(propValue: T) {
+  const [value, setValue] = React.useState(propValue);
+  const [previousPropValue, setPreviousPropValue] = React.useState(propValue);
+
+  if (!Object.is(propValue, previousPropValue)) {
+    setPreviousPropValue(propValue);
+    setValue(propValue);
+  }
+
+  return [value, setValue] as const;
+}

package/src/styles/tokens/blur.css

@@ -16,6 +16,34 @@
 
 [data-blur='none'] {
   --blur-factor: 0;
+
+  /*
+   * `backdrop-filter: blur(0px)` is not free. The browser still snapshots the
+   * backdrop, runs the filter and composites the result, so a zeroed blur
+   * factor alone costs as much per frame as a full blur. Only switching the
+   * property off entirely actually skips that work, so disable the filters
+   * rather than relying on the factor.
+   */
+  --backdrop-filter-components-enabled: none;
+  --backdrop-filter-panel-enabled: none;
+  --backdrop-filter-dialog-enabled: none;
+}
+
+/*
+ * Readers who have asked their OS to reduce transparency get the same
+ * treatment: no translucency to see, and none of the compositing cost.
+ */
+@media (prefers-reduced-transparency: reduce) {
+  /*
+   * Deliberately not wrapped in `:where()`: this has to outrank the enabled
+   * values in tokens/constants.css, and a media query adds no specificity of
+   * its own.
+   */
+  .radix-themes {
+    --backdrop-filter-components-enabled: none;
+    --backdrop-filter-panel-enabled: none;
+    --backdrop-filter-dialog-enabled: none;
+  }
 }
 
 [data-blur='small'] {

package/src/styles/tokens/color.css

@@ -149,9 +149,9 @@
     --color-panel: var(--color-panel-translucent);
     --color-surface: var(--color-surface-translucent);
     --color-dialog: var(--color-dialog-translucent);
-    --backdrop-filter-panel: blur(var(--backdrop-blur-panel));
-    --backdrop-filter-components: blur(var(--backdrop-blur-components));
-    --backdrop-filter-dialog: blur(var(--backdrop-blur-dialog));
+    --backdrop-filter-panel: var(--backdrop-filter-panel-enabled);
+    --backdrop-filter-components: var(--backdrop-filter-components-enabled);
+    --backdrop-filter-dialog: var(--backdrop-filter-dialog-enabled);
     /* Material system for component backgrounds */
     --material-blend: 60%;
     --material-alpha: 1;

package/src/styles/tokens/constants.css

@@ -10,6 +10,17 @@
   --backdrop-blur-panel: var(--blur-5);
   --backdrop-blur-dialog: var(--blur-6);
 
+  /*
+   * The filter a translucent surface uses when blur is enabled. Everything that
+   * opts into a backdrop filter reads one of these rather than writing
+   * `blur(...)` itself, so `[data-blur='none']` and
+   * `prefers-reduced-transparency` can switch the property off entirely — see
+   * tokens/blur.css.
+   */
+  --backdrop-filter-components-enabled: blur(var(--backdrop-blur-components));
+  --backdrop-filter-panel-enabled: blur(var(--backdrop-blur-panel));
+  --backdrop-filter-dialog-enabled: blur(var(--backdrop-blur-dialog));
+
   /* Surface background opacity constants - using new opacity tokens */
   --surface-opacity-light: var(--opacity-5);
   --surface-opacity-heavy: var(--opacity-6);