@womp/kookie-ui 0.3.22

package/src/helpers/input-attributes.ts

@@ -0,0 +1,82 @@
+// https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes
+
+type InputAttributes =
+  | 'accept'
+  | 'alt'
+  | 'autocapitalize'
+  | 'autocomplete'
+  | 'capture'
+  | 'checked'
+  | 'defaultChecked'
+  | 'defaultValue'
+  | 'disabled'
+  | 'form'
+  | 'formaction'
+  | 'formenctype'
+  | 'formmethod'
+  | 'formnovalidate'
+  | 'formtarget'
+  | 'height'
+  | 'list'
+  | 'max'
+  | 'maxlength'
+  | 'min'
+  | 'minlength'
+  | 'multiple'
+  | 'name'
+  | 'pattern'
+  | 'placeholder'
+  | 'popovertarget'
+  | 'popovertargetaction'
+  | 'readonly'
+  | 'required'
+  | 'size'
+  | 'src'
+  | 'step'
+  | 'type'
+  | 'value'
+  | 'width';
+
+// Includes all text-like inputs, e.g. text, email, password, number, date, etc.
+type InputTextualAttributes =
+  | 'autoCapitalize'
+  | 'autoComplete'
+  | 'defaultValue'
+  | 'disabled'
+  | 'form'
+  | 'list'
+  | 'maxLength'
+  | 'minLength'
+  | 'min'
+  | 'multiple'
+  | 'max'
+  | 'name'
+  | 'pattern'
+  | 'placeholder'
+  | 'readOnly'
+  | 'required'
+  | 'size'
+  | 'step'
+  | 'type'
+  | 'value';
+
+type InputRadioAttributes =
+  | 'checked'
+  | 'defaultChecked'
+  | 'defaultValue'
+  | 'disabled'
+  | 'form'
+  | 'name'
+  | 'required'
+  | 'value';
+
+type NotInputRadioAttributes = Exclude<InputAttributes, InputRadioAttributes>;
+type NotInputTextualAttributes = Exclude<InputAttributes, InputTextualAttributes>;
+
+export type {
+  InputAttributes,
+  InputRadioAttributes,
+  InputTextualAttributes,
+  NotInputRadioAttributes,
+  NotInputTextualAttributes,
+};

package/src/helpers/is-responsive-object.ts

@@ -0,0 +1,19 @@
+import type { Responsive, Breakpoint } from '../props/prop-def.js';
+
+// Use a Set for O(1) lookup instead of array.includes() which is O(n)
+const breakpointSet = new Set<string>(['initial', 'xs', 'sm', 'md', 'lg', 'xl']);
+
+export function isResponsiveObject<Value extends string>(
+  obj: Responsive<Value | Omit<string, Value>> | undefined
+): obj is Record<Breakpoint, string> {
+  if (typeof obj !== 'object' || obj === null) {
+    return false;
+  }
+  // Use for...in to avoid Object.keys() array allocation
+  for (const key in obj) {
+    if (breakpointSet.has(key)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/helpers/map-prop-values.ts

@@ -0,0 +1,40 @@
+import type { baseButtonPropDefs } from '../components/_internal/base-button.props.js';
+import type { calloutRootPropDefs } from '../components/callout.props.js';
+import type { spinnerPropDefs } from '../components/spinner.props.js';
+import type { textPropDefs } from '../components/text.props.js';
+import type { Responsive } from '../props/prop-def.js';
+
+function mapResponsiveProp<Input extends string, Output>(
+  propValue: Responsive<Input> | undefined,
+  mapValue: (value: Input) => Output
+): Responsive<Output> | undefined {
+  if (propValue === undefined) return undefined;
+  if (typeof propValue === 'string') {
+    return mapValue(propValue);
+  }
+  return Object.fromEntries(
+    Object.entries(propValue).map(([key, value]) => [key, mapValue(value)])
+  );
+}
+
+function mapCalloutSizeToTextSize(
+  size: (typeof calloutRootPropDefs.size.values)[number]
+): (typeof textPropDefs.size.values)[number] {
+  return size === '3' ? '3' : size === '1' ? '1' : '2';
+}
+
+function mapButtonSizeToSpinnerSize(
+  size: (typeof baseButtonPropDefs.size.values)[number]
+): (typeof spinnerPropDefs.size.values)[number] {
+  switch (size) {
+    case '1':
+      return '1';
+    case '2':
+    case '3':
+      return '2';
+    case '4':
+      return '3';
+  }
+}
+
+export { mapResponsiveProp, mapCalloutSizeToTextSize, mapButtonSizeToSpinnerSize };

package/src/helpers/merge-styles.ts

@@ -0,0 +1,22 @@
+type InlineStyle =
+  | React.CSSProperties
+  | Record<string, string | number | null | undefined>
+  | undefined;
+
+// Merges CSS styles like `classNames` merges CSS classes
+// Optimized to avoid object spread in loop - uses Object.assign for in-place mutation
+export function mergeStyles(...styles: Array<InlineStyle>): InlineStyle {
+  let result: Record<string, string | number | null | undefined> | undefined;
+
+  for (const style of styles) {
+    if (style) {
+      if (result === undefined) {
+        // First non-empty style - create result object
+        result = {};
+      }
+      Object.assign(result, style);
+    }
+  }
+
+  return result;
+}

package/src/helpers/normalize-to-px.ts

@@ -0,0 +1,42 @@
+/**
+ * Normalize CSS length values to pixels.
+ * Supports: px, rem, %, and bare numbers.
+ *
+ * @param value - The value to normalize (number, string, or undefined)
+ * @param orientation - 'horizontal' for width-based % or 'vertical' for height-based %
+ * @returns The value in pixels, or undefined if invalid
+ */
+export function normalizeToPx(
+  value: number | string | undefined,
+  orientation: 'horizontal' | 'vertical' = 'horizontal',
+): number | undefined {
+  if (value == null) return undefined;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+
+  const str = String(value).trim();
+  if (!str) return undefined;
+
+  // px: direct parse
+  if (str.endsWith('px')) return Number.parseFloat(str);
+
+  // rem: multiply by root font size
+  if (str.endsWith('rem')) {
+    const rem = Number.parseFloat(getComputedStyle(document.documentElement).fontSize || '16') || 16;
+    return Number.parseFloat(str) * rem;
+  }
+
+  // %: calculate based on viewport dimension
+  if (str.endsWith('%')) {
+    const pct = Number.parseFloat(str);
+    const base =
+      orientation === 'horizontal'
+        ? document.documentElement.clientWidth || window.innerWidth || 0
+        : document.documentElement.clientHeight || window.innerHeight || 0;
+    return (pct / 100) * base;
+  }
+
+  // Bare number-like string
+  const n = Number.parseFloat(str);
+  return Number.isFinite(n) ? n : undefined;
+}
+

package/src/helpers/require-react-element.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+
+/** A function that throws an error when a value isn't a valid React Element, otherwise returns the value */
+export const requireReactElement = <T extends React.ReactNode>(children: T): T => {
+  const isReactElement = React.isValidElement(children);
+
+  if (!isReactElement) {
+    throw Error(
+      `Expected a single React Element child, but got: ${React.Children.toArray(children)
+        .map((child) =>
+          typeof child === 'object' && 'type' in child && typeof child.type === 'string'
+            ? child.type
+            : typeof child
+        )
+        .join(', ')}`
+    );
+  }
+
+  return children;
+};

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useLiveAnnouncer } from './use-live-announcer.js';
+export { useBodyPointerEventsCleanup } from './use-body-pointer-events-cleanup.js';
+export { useTooltipWrapper } from './use-tooltip-wrapper.js';
+export { useToggleState } from './use-toggle-state.js';

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

@@ -0,0 +1,112 @@
+import * as React from 'react';
+
+let cleanupInstalled = false;
+
+/**
+ * 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.
+ */
+export function useBodyPointerEventsCleanup() {
+  React.useEffect(() => {
+    if (typeof document === 'undefined') return;
+    if (cleanupInstalled) return;
+
+    cleanupInstalled = true;
+
+    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 = '';
+
+        // 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
+        setTimeout(forceCleanup, 100);
+      }
+    };
+
+    // Force cleanup on ESC key
+    const onEscapeKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setTimeout(forceCleanup, 200);
+      }
+    };
+
+    // Safe cleanup on other interactions
+    const onInteraction = () => {
+      setTimeout(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(() => {
+      setTimeout(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
+    setTimeout(safeCleanup, 100);
+
+    // Cleanup function (keep listeners for app lifetime)
+    return () => {
+      clearInterval(intervalId);
+    };
+  }, []);
+}

package/src/hooks/use-breakpoint.ts

@@ -0,0 +1,63 @@
+'use client';
+
+import * as React from 'react';
+import { _BREAKPOINTS, type Breakpoint } from '../components/shell.types.js';
+
+/**
+ * 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.
+ */
+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);
+          }
+        }
+      });
+    };
+  }, []);
+
+  return { breakpoint: currentBp, ready };
+}

package/src/hooks/use-live-announcer.ts

@@ -0,0 +1,79 @@
+import * as React from 'react';
+
+/**
+ * Reference counter to track how many components are using the live region.
+ * Only remove the live region when no components are using it.
+ */
+let liveRegionRefCount = 0;
+
+/**
+ * Hook for making live announcements to screen readers
+ * Creates a hidden aria-live region for announcing dynamic content changes
+ */
+export function useLiveAnnouncer() {
+  // Track the timeout so we can clean it up on unmount
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  // Create aria-live region if it doesn't exist
+  React.useEffect(() => {
+    let liveRegion = document.getElementById('rt-live-announcer');
+
+    if (!liveRegion) {
+      liveRegion = document.createElement('div');
+      liveRegion.id = 'rt-live-announcer';
+      liveRegion.setAttribute('aria-live', 'polite');
+      liveRegion.setAttribute('aria-atomic', 'true');
+      liveRegion.style.cssText = `
+        position: absolute;
+        left: -10000px;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+      `;
+      document.body.appendChild(liveRegion);
+    }
+
+    // Increment ref count when component mounts
+    liveRegionRefCount++;
+
+    return () => {
+      // Decrement ref count when component unmounts
+      liveRegionRefCount--;
+
+      // Clean up timeout on unmount
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+
+      // Only remove the live region if no components are using it
+      if (liveRegionRefCount === 0) {
+        const region = document.getElementById('rt-live-announcer');
+        if (region) {
+          region.remove();
+        }
+      }
+    };
+  }, []);
+
+  const announce = React.useCallback((message: string) => {
+    const liveRegion = document.getElementById('rt-live-announcer');
+    if (liveRegion) {
+      // Clear any pending timeout
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+
+      // Clear previous announcements
+      liveRegion.textContent = '';
+
+      // Add new announcement with a small delay to ensure it's announced
+      timeoutRef.current = setTimeout(() => {
+        liveRegion.textContent = message;
+      }, 100);
+    }
+  }, []);
+
+  return announce;
+}

package/src/hooks/use-toggle-state.ts

@@ -0,0 +1,72 @@
+import * as React from 'react';
+import { useLiveAnnouncer } from './use-live-announcer.js';
+
+/**
+ * Options for the useToggleState hook
+ */
+interface UseToggleStateOptions {
+  /** Controlled pressed state */
+  pressed?: boolean;
+  /** Callback when pressed state changes */
+  onPressedChange?: (pressed: boolean) => void;
+  /** Function to get the accessible name for announcements */
+  getAccessibleName: () => string;
+  /** Component name for warning messages */
+  componentName: string;
+}
+
+/**
+ * Hook for shared toggle button state management.
+ * Provides accessibility announcements and controlled/uncontrolled warnings.
+ *
+ * @param options - Configuration options for the toggle state
+ * @returns Object containing the handlePressedChange callback
+ *
+ * @example
+ * ```tsx
+ * const getAccessibleName = React.useCallback(() => 'Toggle button', []);
+ *
+ * const { handlePressedChange } = useToggleState({
+ *   pressed,
+ *   onPressedChange,
+ *   getAccessibleName,
+ *   componentName: 'ToggleButton',
+ * });
+ * ```
+ */
+export function useToggleState({ pressed, onPressedChange, getAccessibleName, componentName }: UseToggleStateOptions) {
+  const announce = useLiveAnnouncer();
+
+  // Track if we've already warned about controlled without handler
+  const warnedRef = React.useRef(false);
+
+  /**
+   * Memoized handler for state changes with accessibility announcements.
+   * Announces the new state immediately for screen readers.
+   */
+  const handlePressedChange = React.useCallback(
+    (newPressed: boolean) => {
+      const accessibleName = getAccessibleName();
+      // Announce the state change for screen readers
+      announce(`${accessibleName} ${newPressed ? 'pressed' : 'unpressed'}`);
+      // Call the user's change handler
+      onPressedChange?.(newPressed);
+    },
+    [announce, onPressedChange, getAccessibleName],
+  );
+
+  // Development-only warning for controlled/uncontrolled pattern
+  // Only warns once to avoid console spam
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'development' && pressed !== undefined && onPressedChange === undefined && !warnedRef.current) {
+      warnedRef.current = true;
+      console.warn(
+        `${componentName}: You provided a \`pressed\` prop without an \`onPressedChange\` handler. ` +
+          'This will result in a read-only toggle button. If you want the button to be interactive, ' +
+          'you should provide an `onPressedChange` handler.',
+      );
+    }
+  }, [pressed, onPressedChange, componentName]);
+
+  return { handlePressedChange };
+}

package/src/hooks/use-tooltip-wrapper.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+
+/**
+ * Hook for managing tooltip accessibility props and conditional rendering.
+ * Encapsulates tooltip ID generation and aria-describedby binding.
+ *
+ * @param tooltip - The tooltip content (if any)
+ * @returns Object containing tooltipId, hasTooltip flag, and accessibility props
+ *
+ * @example
+ * ```tsx
+ * const { tooltipId, hasTooltip, accessibilityProps } = useTooltipWrapper(tooltip);
+ *
+ * const button = <button {...accessibilityProps}>Click me</button>;
+ *
+ * if (!hasTooltip) return button;
+ *
+ * return <Tooltip id={tooltipId} content={tooltip}>{button}</Tooltip>;
+ * ```
+ */
+export function useTooltipWrapper(tooltip: React.ReactNode) {
+  const tooltipId = React.useId();
+  const hasTooltip = Boolean(tooltip);
+
+  const accessibilityProps = React.useMemo(() => (hasTooltip ? { 'aria-describedby': tooltipId } : {}), [hasTooltip, tooltipId]);
+
+  return { tooltipId, hasTooltip, accessibilityProps };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './components/index.js';
+export * from './hooks/index.js';

package/src/props/as-child.prop.ts

@@ -0,0 +1,15 @@
+import type { PropDef } from './prop-def.js';
+
+const asChildPropDef = {
+  /**
+   * Composes the component into its immediate child instead of rendering its own HTML element.
+   * You’ll have to provide a single React Element child.
+   */
+  asChild: {
+    type: 'boolean',
+  },
+} satisfies {
+  asChild: PropDef<boolean>;
+};
+
+export { asChildPropDef };

package/src/props/color.prop.ts

@@ -0,0 +1,36 @@
+import type { PropDef } from './prop-def.js';
+
+// prettier-ignore
+const accentColors = ['gray', 'gold', 'bronze', 'brown', 'yellow', 'amber', 'orange', 'tomato', 'red', 'ruby', 'crimson', 'pink', 'plum', 'purple', 'violet', 'iris', 'indigo', 'blue', 'cyan', 'teal', 'jade', 'green', 'grass', 'lime', 'mint', 'sky'] as const;
+
+const grayColors = ['auto', 'gray', 'mauve', 'slate', 'sage', 'olive', 'sand'] as const;
+
+const colorPropDef = {
+  color: {
+    type: 'enum',
+    values: accentColors,
+    default: undefined as (typeof accentColors)[number] | undefined,
+  },
+} satisfies {
+  color: PropDef<(typeof accentColors)[number]>;
+};
+
+// 1. When used on components that compose Text, sets the color of the text to the current accent.
+// 2. Defines accent color for descendant text components with `highContrast={true}`.
+const accentColorPropDef = {
+  color: {
+    type: 'enum',
+    values: accentColors,
+    default: '' as (typeof accentColors)[number],
+  },
+} satisfies {
+  color: PropDef<(typeof accentColors)[number]>;
+};
+
+export {
+  accentColorPropDef,
+  colorPropDef,
+  //
+  accentColors,
+  grayColors,
+};

package/src/props/font-family.prop.ts

@@ -0,0 +1,15 @@
+import type { PropDef } from './prop-def.js';
+
+const fontFamilies = ['sans', 'mono', 'serif'] as const;
+
+const fontFamilyPropDef = {
+  font: {
+    type: 'enum',
+    className: 'rt-r-ff',
+    values: fontFamilies,
+  },
+} satisfies {
+  font: PropDef<(typeof fontFamilies)[number]>;
+};
+
+export { fontFamilyPropDef };