@womp/kookie-ui 0.3.25 → 0.4.0

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

@@ -1,35 +1,30 @@
-/* Inter, JetBrains Mono, and Playfair Display from Google Fonts */
+/***************************************************************************************************
+ *                                                                                                 *
+ * KOOKIE UI WEBFONTS — OPT-IN                                                                     *
+ *                                                                                                 *
+ * Kookie UI's core stylesheet ships no webfonts; it defaults to system stacks so that importing   *
+ * the library costs zero network requests. Import this file alongside it to get Kookie's own      *
+ * typefaces:                                                                                      *
+ *                                                                                                 *
+ *   import '@womp/kookie-ui/styles.css';                                                          *
+ *   import '@womp/kookie-ui/fonts.css';                                                           *
+ *                                                                                                 *
+ * This costs three render-blocking requests to Google Fonts. If you already load fonts yourself   *
+ * (`next/font`, a self-hosted @font-face, a CDN), skip this file and point the stacks at your     *
+ * own faces instead:                                                                              *
+ *                                                                                                 *
+ *   :root {                                                                                       *
+ *     --font-sans: var(--my-next-font), system-ui, sans-serif;                                    *
+ *   }                                                                                             *
+ *                                                                                                 *
+ ***************************************************************************************************/
+
 @import url('https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,100..900;1,100..900&display=swap');
 @import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&display=swap');
 @import url('https://fonts.googleapis.com/css2?family=Playfair+Display:ital,wght@0,400..900;1,400..900&display=swap');
 
-/* Font Variables - Customize these to change fonts throughout your app */
 :root {
-  /* Base font definitions - these are the actual font stacks */
-  --font-inter: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-  --font-jetbrains-mono: 'JetBrains Mono', 'Fira Code', 'Consolas', 'Liberation Mono', 'Courier New', monospace;
-  --font-playfair-display: 'Playfair Display', 'Times New Roman', 'Times', 'Georgia', 'Cambria', serif;
-
-  /* Theme font family overrides - change these to customize fonts globally */
-  --font-sans: var(--font-inter); /* Override this for custom sans-serif */
-  --font-mono: var(--font-jetbrains-mono); /* Override this for custom monospace */
-  --font-serif: var(--font-playfair-display); /* Override this for custom serif */
-
-  /* Force proper font weight rendering */
-  font-synthesis: none; /* Prevent browser from synthesizing weights */
-}
-
-/* Radix Themes font weight enforcement */
-.radix-themes {
-  font-synthesis: none;
-  font-family: var(--default-font-family);
-}
-
-/* System font fallback for critical loading scenarios */
-@font-face {
-  font-family: 'System Fallback';
-  font-style: normal;
-  font-weight: 100 900;
-  font-display: block;
-  src: local('-apple-system'), local('BlinkMacSystemFont'), local('Segoe UI'), local('Roboto');
+  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI (Custom)', Roboto, 'Helvetica Neue', system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji';
+  --font-mono: 'JetBrains Mono', 'Menlo', 'Consolas (Custom)', 'Liberation Mono', monospace, 'Apple Color Emoji', 'Segoe UI Emoji';
+  --font-serif: 'Playfair Display', 'Times New Roman', 'Times', 'Georgia', 'Cambria', serif;
 }

package/src/styles/index.css

@@ -1,4 +1,3 @@
-@import './fonts.css';
 @import './tokens/index.css';
 @import './breakpoints.css';
 @import './scrollbar.css';

package/src/styles/tokens/base.css

@@ -4,6 +4,7 @@
 @import './radius.css';
 @import './shadow.css';
 @import './transition.css';
+@import './font-family.css';
 @import './typography.css';
 @import './blur.css';
 @import './opacity.css';

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);