@womp/kookie-ui 0.23.0 → 0.25.0

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

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

@@ -1,142 +1,141 @@
 import * as React from 'react';
 
-let cleanupInstalled = false;
+// How many overlays currently use the hook. The listeners are shared: the first mount installs
+// them and the last unmount removes them, so closing one overlay never strips the fallback from
+// another that is still mounted.
+let mountCount = 0;
+let teardown: (() => void) | null = null;
+
+const devLog = (message: string) => {
+  if (process.env.NODE_ENV !== 'production') {
+    console.log(message);
+  }
+};
+
+function install(): () => void {
+  // Deferred cleanups are tracked so teardown 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 isStuck = () => document.body.style.pointerEvents === 'none';
+
+  const hasOpenModal = (): boolean => {
+    // Open dialogs and alert dialogs
+    const hasDialogs = Boolean(
+      document.querySelector('[role="dialog"][aria-modal="true"], [role="alertdialog"][aria-modal="true"]'),
+    );
+
+    // Any Radix overlay that is still mounted. Only overlays count: an open Accordion or
+    // Collapsible also carries data-state="open" and must not keep a stuck page blocked.
+    const hasRadixOverlays = Boolean(
+      document.querySelector(
+        '[data-radix-popper-content-wrapper], [role="dialog"][data-state="open"], [role="alertdialog"][data-state="open"]',
+      ),
+    );
+
+    return hasDialogs || hasRadixOverlays;
+  };
+
+  // Only clears pointer-events when no modal is open. Scroll-lock attributes belong to
+  // react-remove-scroll and are never touched here.
+  const safeCleanup = () => {
+    if (isStuck() && !hasOpenModal()) {
+      devLog('[KookieUI] Cleaning stuck pointer-events: none from body');
+      document.body.style.pointerEvents = '';
+    }
+  };
+
+  // Every trigger queues a check only while the body is actually blocked.
+  const scheduleCleanup = (delay: number) => {
+    if (isStuck()) defer(safeCleanup, delay);
+  };
+
+  const onDocumentClick = (event: Event) => {
+    const target = event.target as Element;
+    if (target && !target.closest('[role="dialog"], [role="alertdialog"], [data-radix-popper-content-wrapper]')) {
+      scheduleCleanup(100);
+    }
+  };
+
+  const onEscapeKey = (event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      scheduleCleanup(200);
+    }
+  };
+
+  const onInteraction = () => {
+    scheduleCleanup(50);
+  };
+
+  document.addEventListener('click', onDocumentClick, true);
+  document.addEventListener('keydown', onEscapeKey, true);
+  document.addEventListener('pointerup', onInteraction, true);
+  document.addEventListener('transitionend', onInteraction, true);
+  document.addEventListener('animationend', onInteraction, true);
+
+  // Portals mount and unmount as direct children of body, and the stuck value lives in body's
+  // style, so body's own children and style are all that need watching.
+  const observer = new MutationObserver(() => {
+    scheduleCleanup(0);
+  });
+  observer.observe(document.body, { childList: true, attributes: true, attributeFilter: ['style'] });
+
+  // Fallback periodic cleanup
+  const intervalId = setInterval(safeCleanup, 1000);
+
+  // Initial cleanup
+  scheduleCleanup(100);
+
+  // 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.
+  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);
+  };
+}
 
 /**
  * Hook to cleanup stuck pointer-events: none on document.body
  *
  * This addresses an issue where react-remove-scroll (used by Radix UI Dialog)
  * sometimes fails to restore body pointer-events after dialog closes,
- * leaving the page unclickable.
+ * leaving the page unclickable. It never clears the value while a modal is open.
  */
 export function useBodyPointerEventsCleanup() {
   React.useEffect(() => {
     if (typeof document === 'undefined') return;
-    if (cleanupInstalled) return;
-
-    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(
-        document.querySelector(
-          '[role="dialog"][aria-modal="true"], [role="alertdialog"][aria-modal="true"]',
-        ),
-      );
-
-      // Also check for any Radix overlays that are still mounted
-      const hasRadixOverlays = Boolean(
-        document.querySelector('[data-radix-popper-content-wrapper], [data-state="open"]'),
-      );
 
-      return hasDialogs || hasRadixOverlays;
-    };
-
-    const forceCleanup = () => {
-      // Aggressive cleanup - remove pointer-events regardless
-      if (document.body.style.pointerEvents === 'none') {
-        console.log('[KookieUI] Force cleaning stuck pointer-events: none from body');
-        document.body.style.pointerEvents = '';
+    mountCount += 1;
+    if (mountCount === 1) {
+      teardown = install();
+    }
 
-        // Also remove any scroll-lock related attributes
-        document.body.removeAttribute('data-scroll-locked');
-        document.body.removeAttribute('data-remove-scroll');
-
-        // Remove any classes that might be causing issues
-        document.body.classList.remove('ReactModal__Body--open');
-      }
-    };
-
-    const safeCleanup = () => {
-      if (document.body.style.pointerEvents === 'none' && !hasOpenModal()) {
-        console.log('[KookieUI] Safe cleaning stuck pointer-events: none from body');
-        document.body.style.pointerEvents = '';
-      }
-    };
-
-    // Force cleanup on any click outside modal content
-    const onDocumentClick = (event: Event) => {
-      const target = event.target as Element;
-      if (
-        target &&
-        !target.closest(
-          '[role="dialog"], [role="alertdialog"], [data-radix-popper-content-wrapper]',
-        )
-      ) {
-        // Clicked outside any modal - force cleanup after a short delay
-        defer(forceCleanup, 100);
-      }
-    };
-
-    // Force cleanup on ESC key
-    const onEscapeKey = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        defer(forceCleanup, 200);
-      }
-    };
-
-    // Safe cleanup on other interactions
-    const onInteraction = () => {
-      defer(safeCleanup, 50);
-    };
-
-    // Install global listeners
-    document.addEventListener('click', onDocumentClick, true);
-    document.addEventListener('keydown', onEscapeKey, true);
-    document.addEventListener('pointerup', onInteraction, true);
-    document.addEventListener('transitionend', onInteraction, true);
-    document.addEventListener('animationend', onInteraction, true);
-
-    // Watch for DOM changes that might indicate overlay removal
-    const observer = new MutationObserver(() => {
-      defer(safeCleanup, 0);
-    });
-    observer.observe(document.body, { childList: true, subtree: true, attributes: true });
-
-    // Fallback periodic cleanup
-    const intervalId = setInterval(() => {
-      if (document.body.style.pointerEvents === 'none' && !hasOpenModal()) {
-        console.log('[KookieUI] Periodic cleanup of stuck pointer-events');
-        document.body.style.pointerEvents = '';
-      }
-    }, 1000);
-
-    // Initial cleanup
-    defer(safeCleanup, 100);
-
-    // 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;
+      mountCount -= 1;
+      if (mountCount === 0) {
+        teardown?.();
+        teardown = null;
+      }
     };
   }, []);
 }

package/src/hooks/use-scroll-edges.ts

@@ -1,8 +1,10 @@
 import * as React from 'react';
 
 /**
- * Publishes how much content is hidden past each block edge of a scroller, as
- * `--scroll-overflow-start` and `--scroll-overflow-end` (px) on the element.
+ * Publishes how much content is hidden past each edge of a scroller, as
+ * `--scroll-overflow-start` and `--scroll-overflow-end` (block axis) and
+ * `--scroll-overflow-x-start` and `--scroll-overflow-x-end` (inline axis, from
+ * the inline start, so right-to-left reads the same) in px on the element.
  * The scroll fade reads them, so an edge fades only while content is hidden
  * there, and the fade ramps in over the first pixels of scrolling.
  *
@@ -21,6 +23,11 @@ export function useScrollEdges<T extends HTMLElement>(enabled: boolean) {
       const end = Math.max(0, element.scrollHeight - element.clientHeight - element.scrollTop);
       element.style.setProperty('--scroll-overflow-start', `${start}px`);
       element.style.setProperty('--scroll-overflow-end', `${end}px`);
+      // scrollLeft runs negative in right-to-left, so its size is the distance from the inline start.
+      const xStart = Math.abs(element.scrollLeft);
+      const xEnd = Math.max(0, element.scrollWidth - element.clientWidth - xStart);
+      element.style.setProperty('--scroll-overflow-x-start', `${xStart}px`);
+      element.style.setProperty('--scroll-overflow-x-end', `${xEnd}px`);
     };
     const schedule = () => {
       if (!frame) frame = requestAnimationFrame(write);
@@ -39,6 +46,8 @@ export function useScrollEdges<T extends HTMLElement>(enabled: boolean) {
       mutations?.disconnect();
       element.style.removeProperty('--scroll-overflow-start');
       element.style.removeProperty('--scroll-overflow-end');
+      element.style.removeProperty('--scroll-overflow-x-start');
+      element.style.removeProperty('--scroll-overflow-x-end');
     };
   }, [enabled, element]);
 

package/src/props/gap.props.ts

@@ -23,7 +23,7 @@ const gapPropDefs = {
     responsive: true,
   },
   /**
-   * Sets the CSS **row-gap** property.
+   * Sets the CSS **column-gap** property.
    * Supports space scale values, CSS strings, and responsive objects.
    *
    * @example
@@ -32,7 +32,7 @@ const gapPropDefs = {
    * gapX={{ sm: '2', lg: '3em' }}
    *
    * @link
-   * https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap
+   * https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap
    */
   gapX: {
     type: 'enum | string',
@@ -42,7 +42,7 @@ const gapPropDefs = {
     responsive: true,
   },
   /**
-   * Sets the CSS **column-gap** property.
+   * Sets the CSS **row-gap** property.
    * Supports space scale values, CSS strings, and responsive objects.
    *
    * @example
@@ -51,7 +51,7 @@ const gapPropDefs = {
    * gapY={{ sm: '2', lg: '3em' }}
    *
    * @link
-   * https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap
+   * https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap
    */
   gapY: {
     type: 'enum | string',

package/src/styles/utilities/margin.css

@@ -401,8 +401,8 @@
 }
 @media (--sm) {
   .sm\:kui-r-mx {
-    --margin-left: var(--ml-md);
-    --margin-right: var(--mr-md);
+    --margin-left: var(--ml-sm);
+    --margin-right: var(--mr-sm);
   }
 }
 @media (--md) {

package/src/styles/utilities/text-align.css

@@ -10,4 +10,12 @@
   .kui-r-ta-right {
     text-align: right;
   }
+
+  .kui-r-ta-start {
+    text-align: start;
+  }
+
+  .kui-r-ta-end {
+    text-align: end;
+  }
 }

package/src/styles/utilities/truncate.css

@@ -3,3 +3,13 @@
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+
+/* An inline box can't clip its text, so an inline element that truncates becomes an inline block
+   no wider than its container. `bottom` keeps it on the line, because a clipped inline block puts
+   its baseline at its bottom edge. Inside a flex or grid layout the element is a block anyway. */
+/* stylelint-disable-next-line selector-max-type */
+.kui-truncate:where(span, code, a, label) {
+  display: inline-block;
+  max-width: 100%;
+  vertical-align: bottom;
+}