@kushagradhawan/kookie-ui 0.1.29 → 0.1.30

package/src/components/text-field.tsx

@@ -40,47 +40,98 @@ interface TextFieldRootProps extends TextFieldInputProps, MarginProps, TextField
 const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>(
   (props, forwardedRef) => {
     const inputRef = React.useRef<HTMLInputElement>(null);
-    const { children, className, color, radius, panelBackground, style, ...inputProps } =
+    const { children, className, color, radius, panelBackground, material, style, ...inputProps } =
       extractProps(props, textFieldRootPropDefs, marginPropDefs);
+    const effectiveMaterial = material || panelBackground;
+
+    // Generate unique IDs for accessibility
+    const errorId = React.useId();
+
+    // Determine invalid state
+    const isInvalid = inputProps.error || inputProps.isInvalid;
+
+    const { 'aria-describedby': ariaDescribedby, 'aria-labelledby': ariaLabelledby } = inputProps;
+    
+    // Build aria-describedby string
+    const describedBy = React.useMemo(() => {
+      const parts = [];
+      if (inputProps.errorMessage) parts.push(errorId);
+      if (ariaDescribedby) parts.push(ariaDescribedby);
+      return parts.length > 0 ? parts.join(' ') : undefined;
+    }, [inputProps.errorMessage, ariaDescribedby, errorId]);
+
+    // Build aria attributes
+    const ariaProps = React.useMemo(
+      () => ({
+        'aria-invalid': isInvalid,
+        'aria-describedby': describedBy,
+        'aria-labelledby': ariaLabelledby,
+      }),
+      [isInvalid, describedBy, ariaLabelledby],
+    );
+
+    // Filter out our custom props to avoid DOM warnings
+    const {
+      error,
+      errorMessage,
+      isInvalid: _isInvalid,
+      required,
+      'aria-describedby': _ariaDescribedby,
+      'aria-labelledby': _ariaLabelledby,
+      ...nativeInputProps
+    } = inputProps;
+
+    // Memoized pointer event handler
+    const handlePointerDown = React.useCallback((event: React.PointerEvent) => {
+      const target = event.target as HTMLElement;
+      if (target.closest('input, button, a')) return;
+
+      const input = inputRef.current;
+      if (!input) return;
+
+      // Same selector as in the CSS to find the right slot
+      const isRightSlot = target.closest(`
+        .rt-TextFieldSlot[data-side='right'],
+        .rt-TextFieldSlot:not([data-side='right']) ~ .rt-TextFieldSlot:not([data-side='left'])
+      `);
+
+      const cursorPosition = isRightSlot ? input.value.length : 0;
+
+      requestAnimationFrame(() => {
+        // Only some input types support this, browsers will throw an error if not supported
+        // See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange#:~:text=Note%20that%20according,not%20support%20selection%22.
+        try {
+          input.setSelectionRange(cursorPosition, cursorPosition);
+        } catch {}
+        input.focus();
+      });
+    }, []);
+
     return (
       <div
         data-accent-color={color}
         data-radius={radius}
-        data-panel-background={panelBackground}
+        data-panel-background={effectiveMaterial}
+        data-material={effectiveMaterial}
         style={style}
-        className={classNames('rt-TextFieldRoot', className)}
-        onPointerDown={(event) => {
-          const target = event.target as HTMLElement;
-          if (target.closest('input, button, a')) return;
-
-          const input = inputRef.current;
-          if (!input) return;
-
-          // Same selector as in the CSS to find the right slot
-          const isRightSlot = target.closest(`
-            .rt-TextFieldSlot[data-side='right'],
-            .rt-TextFieldSlot:not([data-side='right']) ~ .rt-TextFieldSlot:not([data-side='left'])
-          `);
-
-          const cursorPosition = isRightSlot ? input.value.length : 0;
-
-          requestAnimationFrame(() => {
-            // Only some input types support this, browsers will throw an error if not supported
-            // See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange#:~:text=Note%20that%20according,not%20support%20selection%22.
-            try {
-              input.setSelectionRange(cursorPosition, cursorPosition);
-            } catch {}
-            input.focus();
-          });
-        }}
+        className={classNames('rt-TextFieldRoot', className, {
+          'rt-error': isInvalid,
+        })}
+        onPointerDown={handlePointerDown}
       >
         <input
           spellCheck="false"
-          {...inputProps}
+          {...nativeInputProps}
+          {...ariaProps}
           ref={composeRefs(inputRef, forwardedRef)}
           className="rt-reset rt-TextFieldInput"
         />
         {children}
+        {inputProps.errorMessage && (
+          <div id={errorId} className="rt-TextFieldErrorMessage" role="alert" aria-live="polite">
+            {inputProps.errorMessage}
+          </div>
+        )}
       </div>
     );
   },

package/src/components/theme.props.tsx

@@ -6,6 +6,7 @@ import type { GetPropDefTypes, PropDef } from '../props/prop-def.js';
 
 const appearances = ['inherit', 'light', 'dark'] as const;
 const panelBackgrounds = ['solid', 'translucent'] as const;
+const materials = ['solid', 'translucent'] as const;
 const scalings = ['90%', '95%', '100%', '105%', '110%'] as const;
 
 const themePropDefs = {
@@ -45,6 +46,16 @@ const themePropDefs = {
    * @link
    * https://www.radix-ui.com/themes/docs/theme/visual-style
    */
+  material: { type: 'enum', values: materials, default: 'translucent' },
+  /**
+   * Controls whether to use a solid or translucent background color on panelled
+   * elements such as Card or Table is solid or translucent.
+   *
+   * @deprecated Use `material` prop instead. This prop will be removed in a future version.
+   *
+   * @link
+   * https://www.radix-ui.com/themes/docs/theme/visual-style
+   */
   panelBackground: { type: 'enum', values: panelBackgrounds, default: 'translucent' },
   /**
    * Sets the default radius of the components.
@@ -65,6 +76,7 @@ const themePropDefs = {
   appearance: PropDef<(typeof appearances)[number]>;
   accentColor: PropDef<(typeof accentColors)[number]>;
   grayColor: PropDef<(typeof grayColors)[number]>;
+  material: PropDef<(typeof materials)[number]>;
   panelBackground: PropDef<(typeof panelBackgrounds)[number]>;
   radius: PropDef<(typeof radii)[number]>;
   scaling: PropDef<(typeof scalings)[number]>;

package/src/components/theme.tsx

@@ -15,6 +15,7 @@ const noop = () => {};
 type ThemeAppearance = (typeof themePropDefs.appearance.values)[number];
 type ThemeAccentColor = (typeof themePropDefs.accentColor.values)[number];
 type ThemeGrayColor = (typeof themePropDefs.grayColor.values)[number];
+type ThemeMaterial = (typeof themePropDefs.material.values)[number];
 type ThemePanelBackground = (typeof themePropDefs.panelBackground.values)[number];
 type ThemeRadius = (typeof themePropDefs.radius.values)[number];
 type ThemeScaling = (typeof themePropDefs.scaling.values)[number];
@@ -23,6 +24,7 @@ interface ThemeChangeHandlers {
   onAppearanceChange: (appearance: ThemeAppearance) => void;
   onAccentColorChange: (accentColor: ThemeAccentColor) => void;
   onGrayColorChange: (grayColor: ThemeGrayColor) => void;
+  onMaterialChange: (material: ThemeMaterial) => void;
   onPanelBackgroundChange: (panelBackground: ThemePanelBackground) => void;
   onRadiusChange: (radius: ThemeRadius) => void;
   onScalingChange: (scaling: ThemeScaling) => void;
@@ -33,6 +35,7 @@ interface ThemeContextValue extends ThemeChangeHandlers {
   accentColor: ThemeAccentColor;
   grayColor: ThemeGrayColor;
   resolvedGrayColor: ThemeGrayColor;
+  material: ThemeMaterial;
   panelBackground: ThemePanelBackground;
   radius: ThemeRadius;
   scaling: ThemeScaling;
@@ -70,12 +73,23 @@ const ThemeRoot = React.forwardRef<ThemeImplElement, ThemeImplPublicProps>(
       appearance: appearanceProp = themePropDefs.appearance.default,
       accentColor: accentColorProp = themePropDefs.accentColor.default,
       grayColor: grayColorProp = themePropDefs.grayColor.default,
+      material: materialProp = themePropDefs.material.default,
       panelBackground: panelBackgroundProp = themePropDefs.panelBackground.default,
       radius: radiusProp = themePropDefs.radius.default,
       scaling: scalingProp = themePropDefs.scaling.default,
       hasBackground = themePropDefs.hasBackground.default,
       ...rootProps
     } = props;
+
+    // Show deprecation warning for panelBackground when used
+    React.useEffect(() => {
+      if (props.panelBackground !== undefined) {
+        console.warn(
+          'Warning: The `panelBackground` prop is deprecated and will be removed in a future version. Use `material` prop instead.',
+        );
+      }
+    }, [props.panelBackground]);
+
     const [appearance, setAppearance] = React.useState(appearanceProp);
     React.useEffect(() => setAppearance(appearanceProp), [appearanceProp]);
 
@@ -85,8 +99,15 @@ const ThemeRoot = React.forwardRef<ThemeImplElement, ThemeImplPublicProps>(
     const [grayColor, setGrayColor] = React.useState(grayColorProp);
     React.useEffect(() => setGrayColor(grayColorProp), [grayColorProp]);
 
+    // Material takes precedence over panelBackground
+    const effectiveMaterial =
+      materialProp !== themePropDefs.material.default ? materialProp : panelBackgroundProp;
+    const [material, setMaterial] = React.useState(effectiveMaterial);
+    React.useEffect(() => setMaterial(effectiveMaterial), [effectiveMaterial]);
+
+    // Keep panelBackground in sync with material for backward compatibility
     const [panelBackground, setPanelBackground] = React.useState(panelBackgroundProp);
-    React.useEffect(() => setPanelBackground(panelBackgroundProp), [panelBackgroundProp]);
+    React.useEffect(() => setPanelBackground(material), [material]);
 
     const [radius, setRadius] = React.useState(radiusProp);
     React.useEffect(() => setRadius(radiusProp), [radiusProp]);
@@ -104,6 +125,7 @@ const ThemeRoot = React.forwardRef<ThemeImplElement, ThemeImplPublicProps>(
         appearance={appearance}
         accentColor={accentColor}
         grayColor={grayColor}
+        material={material}
         panelBackground={panelBackground}
         radius={radius}
         scaling={scaling}
@@ -111,6 +133,7 @@ const ThemeRoot = React.forwardRef<ThemeImplElement, ThemeImplPublicProps>(
         onAppearanceChange={setAppearance}
         onAccentColorChange={setAccentColor}
         onGrayColorChange={setGrayColor}
+        onMaterialChange={setMaterial}
         onPanelBackgroundChange={setPanelBackground}
         onRadiusChange={setRadius}
         onScalingChange={setScaling}
@@ -138,6 +161,7 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
     appearance = props.appearance ?? context?.appearance ?? themePropDefs.appearance.default,
     accentColor = props.accentColor ?? context?.accentColor ?? themePropDefs.accentColor.default,
     grayColor = props.grayColor ?? context?.resolvedGrayColor ?? themePropDefs.grayColor.default,
+    material = props.material ?? context?.material ?? themePropDefs.material.default,
     panelBackground = props.panelBackground ??
       context?.panelBackground ??
       themePropDefs.panelBackground.default,
@@ -147,6 +171,7 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
     onAppearanceChange = noop,
     onAccentColorChange = noop,
     onGrayColorChange = noop,
+    onMaterialChange = noop,
     onPanelBackgroundChange = noop,
     onRadiusChange = noop,
     onScalingChange = noop,
@@ -166,6 +191,7 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
           accentColor,
           grayColor,
           resolvedGrayColor,
+          material,
           panelBackground,
           radius,
           scaling,
@@ -173,6 +199,7 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
           onAppearanceChange,
           onAccentColorChange,
           onGrayColorChange,
+          onMaterialChange,
           onPanelBackgroundChange,
           onRadiusChange,
           onScalingChange,
@@ -182,6 +209,7 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
           accentColor,
           grayColor,
           resolvedGrayColor,
+          material,
           panelBackground,
           radius,
           scaling,
@@ -189,6 +217,7 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
           onAppearanceChange,
           onAccentColorChange,
           onGrayColorChange,
+          onMaterialChange,
           onPanelBackgroundChange,
           onRadiusChange,
           onScalingChange,
@@ -201,6 +230,7 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
         data-gray-color={resolvedGrayColor}
         // for nested `Theme` background
         data-has-background={hasBackground ? 'true' : 'false'}
+        data-material={material}
         data-panel-background={panelBackground}
         data-radius={radius}
         data-scaling={scaling}

package/src/components/toggle-button.tsx

@@ -1,25 +1,124 @@
 import * as React from 'react';
 import { Toggle } from 'radix-ui';
 import { Button } from './button.js';
+import { useLiveAnnouncer } from '../hooks/use-live-announcer.js';
 
+/**
+ * ToggleButton props that extend Button with toggle-specific functionality
+ *
+ * The ToggleButton component provides a button that can be pressed/unpressed
+ * with proper accessibility announcements and state management.
+ */
 interface ToggleButtonProps extends React.ComponentPropsWithoutRef<typeof Button> {
+  /** Controlled pressed state */
   pressed?: boolean;
+  /** Callback when pressed state changes */
   onPressedChange?: (pressed: boolean) => void;
+  /** Default pressed state for uncontrolled usage */
   defaultPressed?: boolean;
 }
 
 type ToggleButtonElement = React.ElementRef<typeof Button>;
 
+/**
+ * ToggleButton component for buttons that can be pressed/unpressed
+ *
+ * The ToggleButton component extends Button with toggle functionality using
+ * Radix UI's Toggle primitive. It provides proper accessibility announcements,
+ * controlled/uncontrolled state management, and seamless integration with
+ * the existing Button component.
+ *
+ * Key features:
+ * - Controlled and uncontrolled state management
+ * - Live accessibility announcements for screen readers
+ * - Automatic state validation and warnings
+ * - Seamless integration with Button props and styling
+ * - Proper ARIA attributes for toggle functionality
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled toggle button
+ * <ToggleButton defaultPressed={false}>
+ *   Toggle Me
+ * </ToggleButton>
+ *
+ * // Controlled toggle button
+ * const [pressed, setPressed] = React.useState(false);
+ * <ToggleButton
+ *   pressed={pressed}
+ *   onPressedChange={setPressed}
+ * >
+ *   {pressed ? 'On' : 'Off'}
+ * </ToggleButton>
+ *
+ * // Toggle button with all Button props
+ * <ToggleButton
+ *   variant="solid"
+ *   size="3"
+ *   color="blue"
+ *   pressed={isActive}
+ *   onPressedChange={setIsActive}
+ * >
+ *   {isActive ? 'Active' : 'Inactive'}
+ * </ToggleButton>
+ * ```
+ */
 const ToggleButton = React.forwardRef<ToggleButtonElement, ToggleButtonProps>(
-  ({ pressed, onPressedChange, defaultPressed, ...buttonProps }, forwardedRef) => {
+  ({ pressed, onPressedChange, defaultPressed, children, ...buttonProps }, forwardedRef) => {
+    // Get the live announcer for accessibility announcements
+    const announce = useLiveAnnouncer();
+
+    /**
+     * Extract accessible name from button content for announcements
+     * This ensures screen readers announce meaningful state changes
+     */
+    const getAccessibleName = React.useCallback(() => {
+      if (typeof children === 'string') return children;
+      if (React.isValidElement(children) && typeof (children.props as any)?.children === 'string') {
+        return (children.props as any).children;
+      }
+      return 'Toggle button';
+    }, [children]);
+
+    /**
+     * Memoized handler for state changes with accessibility announcements
+     * This ensures screen readers announce the new state immediately
+     */
+    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
+    // This helps developers avoid common state management mistakes
+    React.useEffect(() => {
+      if (process.env.NODE_ENV === 'development' && pressed !== undefined && onPressedChange === undefined) {
+        console.warn(
+          'ToggleButton: 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]);
+
+    // Render the toggle button using Radix UI's Toggle primitive
+    // This provides proper ARIA attributes and keyboard navigation
     return (
       <Toggle.Root
         pressed={pressed}
-        onPressedChange={onPressedChange}
+        onPressedChange={handlePressedChange}
         defaultPressed={defaultPressed}
         asChild
       >
-        <Button {...buttonProps} ref={forwardedRef} />
+        <Button {...buttonProps} ref={forwardedRef}>
+          {children}
+        </Button>
       </Toggle.Root>
     );
   },

package/src/components/toggle-icon-button.tsx

@@ -2,37 +2,180 @@ import * as React from 'react';
 import { Toggle } from 'radix-ui';
 import { IconButton } from './icon-button.js';
 import { BaseButton } from './_internal/base-button.js';
-import type { BaseButtonProps } from './_internal/base-button.js';
+import { useLiveAnnouncer } from '../hooks/use-live-announcer.js';
+import type { IconButtonProps } from './icon-button.js';
 
 type ToggleIconButtonElement = React.ElementRef<typeof BaseButton>;
 
-// Extract toggle-specific props from Radix Toggle
+/**
+ * Extract toggle-specific props from Radix Toggle
+ * These props control the toggle state and behavior
+ */
 type ToggleProps = React.ComponentPropsWithoutRef<typeof Toggle.Root>;
 
-// Required accessibility props for icon buttons (same as IconButton)
+/**
+ * Required accessibility props for icon buttons (same as IconButton)
+ * Icon buttons must have an accessible name to meet WCAG guidelines
+ *
+ * Three ways to provide accessibility:
+ * 1. aria-label: Direct descriptive text
+ * 2. aria-labelledby: Reference to a label element
+ * 3. children: Visible text content (fallback)
+ */
 type AccessibilityProps =
   | { 'aria-label': string; 'aria-labelledby'?: never }
   | { 'aria-label'?: never; 'aria-labelledby': string }
   | { 'aria-label'?: never; 'aria-labelledby'?: never; children: React.ReactNode };
 
-// Combine BaseButton props with Toggle-specific props and accessibility requirements
-interface ToggleIconButtonProps extends Omit<BaseButtonProps, 'as'> {
+/**
+ * Combine IconButton props with Toggle-specific props
+ * Includes tooltip props from IconButton for comprehensive functionality
+ */
+interface ToggleIconButtonProps extends Omit<IconButtonProps, 'as'> {
+  /** Controlled pressed state */
   pressed?: ToggleProps['pressed'];
+  /** Callback when pressed state changes */
   onPressedChange?: ToggleProps['onPressedChange'];
+  /** Default pressed state for uncontrolled usage */
   defaultPressed?: ToggleProps['defaultPressed'];
 }
 
-// Intersection with accessibility props
+/**
+ * Intersection with accessibility props to ensure compliance
+ * This type ensures all ToggleIconButton instances have proper accessibility
+ */
 type ToggleIconButtonPropsWithAccessibility = ToggleIconButtonProps & AccessibilityProps;
 
+/**
+ * ToggleIconButton component for icon buttons that can be pressed/unpressed
+ *
+ * The ToggleIconButton component extends IconButton with toggle functionality
+ * using Radix UI's Toggle primitive. It provides proper accessibility announcements,
+ * controlled/uncontrolled state management, and seamless integration with
+ * the existing IconButton component.
+ *
+ * Key features:
+ * - Controlled and uncontrolled state management
+ * - Live accessibility announcements for screen readers
+ * - Enforced accessibility requirements (aria-label, aria-labelledby, or children)
+ * - Automatic state validation and warnings
+ * - Seamless integration with IconButton props and styling
+ * - Proper ARIA attributes for toggle functionality
+ * - Built-in tooltip support from IconButton
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled toggle icon button
+ * <ToggleIconButton defaultPressed={false} aria-label="Toggle notifications">
+ *   <Bell />
+ * </ToggleIconButton>
+ *
+ * // Controlled toggle icon button
+ * const [pressed, setPressed] = React.useState(false);
+ * <ToggleIconButton
+ *   pressed={pressed}
+ *   onPressedChange={setPressed}
+ *   aria-label="Toggle notifications"
+ * >
+ *   <Bell />
+ * </ToggleIconButton>
+ *
+ * // Toggle icon button with tooltip
+ * <ToggleIconButton
+ *   variant="solid"
+ *   size="3"
+ *   color="blue"
+ *   pressed={isActive}
+ *   onPressedChange={setIsActive}
+ *   aria-label="Toggle feature"
+ *   tooltip="Toggle this feature on/off"
+ * >
+ *   <Star />
+ * </ToggleIconButton>
+ *
+ * // Toggle icon button with aria-labelledby
+ * <ToggleIconButton
+ *   aria-labelledby="notifications-label"
+ *   pressed={notificationsEnabled}
+ *   onPressedChange={setNotificationsEnabled}
+ * >
+ *   <Bell />
+ * </ToggleIconButton>
+ * <span id="notifications-label">Toggle notifications</span>
+ * ```
+ */
 const ToggleIconButton = React.forwardRef<
   ToggleIconButtonElement,
   ToggleIconButtonPropsWithAccessibility
 >(({ pressed, onPressedChange, defaultPressed, ...iconButtonProps }, forwardedRef) => {
+  // Get the live announcer for accessibility announcements
+  const announce = useLiveAnnouncer();
+
+  /**
+   * Extract accessible name from various sources for announcements
+   * This ensures screen readers announce meaningful state changes
+   * Priority: aria-label > aria-labelledby > children > fallback
+   */
+  const getAccessibleName = React.useCallback(() => {
+    const {
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      children,
+    } = iconButtonProps;
+
+    // First priority: direct aria-label
+    if (ariaLabel) return ariaLabel;
+
+    // Second priority: referenced label element
+    if (ariaLabelledBy) {
+      const labelElement = document.getElementById(ariaLabelledBy);
+      return labelElement?.textContent || 'Toggle icon button';
+    }
+
+    // Third priority: visible text children
+    if (typeof children === 'string') return children;
+    if (React.isValidElement(children) && typeof (children.props as any)?.children === 'string') {
+      return (children.props as any).children;
+    }
+
+    // Fallback for edge cases
+    return 'Toggle icon button';
+  }, [iconButtonProps]);
+
+  /**
+   * Memoized handler for state changes with accessibility announcements
+   * This ensures screen readers announce the new state immediately
+   */
+  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
+  // This helps developers avoid common state management mistakes
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'development' && pressed !== undefined && onPressedChange === undefined) {
+      console.warn(
+        'ToggleIconButton: 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]);
+
+  // Render the toggle icon button using Radix UI's Toggle primitive
+  // This provides proper ARIA attributes and keyboard navigation
+  // The IconButton component handles accessibility validation internally
   return (
     <Toggle.Root
       pressed={pressed}
-      onPressedChange={onPressedChange}
+      onPressedChange={handlePressedChange}
       defaultPressed={defaultPressed}
       asChild
     >

package/src/components/tooltip.css

@@ -2,12 +2,12 @@
   box-sizing: border-box;
   padding: var(--space-1) var(--space-2);
   background-color: var(--gray-12);
-  border-radius: var(--radius-2);
+  border-radius: var(--radius-1);
 
   transform-origin: var(--radix-tooltip-content-transform-origin);
 
-  animation-duration: 140ms;
-  animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
+  animation-duration: var(--duration-2);
+  animation-timing-function: var(--ease-3);
 
   @media (prefers-reduced-motion: no-preference) {
     &:where([data-state='delayed-open']) {

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useLiveAnnouncer } from './use-live-announcer.js'; 

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

@@ -0,0 +1,52 @@
+import * as React from 'react';
+
+/**
+ * Hook for making live announcements to screen readers
+ * Creates a hidden aria-live region for announcing dynamic content changes
+ */
+export function useLiveAnnouncer() {
+
+  // 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);
+    }
+
+    return () => {
+      // Clean up on unmount if no other components are using it
+      if (liveRegion && !liveRegion.hasChildNodes()) {
+        liveRegion.remove();
+      }
+    };
+  }, []);
+
+  const announce = React.useCallback((message: string) => {
+    const liveRegion = document.getElementById('rt-live-announcer');
+    if (liveRegion) {
+      // Clear previous announcements
+      liveRegion.textContent = '';
+      
+      // Add new announcement with a small delay to ensure it's announced
+      setTimeout(() => {
+        liveRegion.textContent = message;
+      }, 100);
+    }
+  }, []);
+
+  return announce;
+} 

package/src/index.ts

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