@womp/kookie-ui 0.3.22

package/src/components/theme.props.tsx

@@ -0,0 +1,96 @@
+import { asChildPropDef } from '../props/as-child.prop.js';
+import { accentColors, grayColors } from '../props/color.prop.js';
+import { radii } from '../props/radius.prop.js';
+
+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 fontFamilies = ['sans', 'mono', 'serif'] as const;
+
+const themePropDefs = {
+  ...asChildPropDef,
+  /**
+   * Whether to apply background color to the Theme element.
+   *
+   * Defaults to true for the root Theme and for Theme elements that
+   * have an explicit light or dark appearance prop.
+   */
+  hasBackground: { type: 'boolean', default: true },
+  /**
+   * Sets the color scheme of the theme, typcially referred to as light and dark mode.
+   *
+   * @link
+   * https://www.radix-ui.com/themes/docs/theme/dark-mode
+   */
+  appearance: { type: 'enum', values: appearances, default: 'inherit' },
+  /**
+   * Selects one of the accent color options to use in the Theme.
+   *
+   * @link
+   * https://www.radix-ui.com/themes/docs/theme/color
+   */
+  accentColor: { type: 'enum', values: accentColors, default: 'blue' },
+  /**
+   * Selects one of the gray color options to use in the Theme.
+   *
+   * @link
+   * https://www.radix-ui.com/themes/docs/theme/color
+   */
+  grayColor: { type: 'enum', values: grayColors, default: 'slate' },
+  /**
+   * Controls whether to use a solid or translucent background color on panelled
+   * elements such as Card or Table is solid or translucent.
+   *
+   * @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.
+   *
+   * @link
+   * https://www.radix-ui.com/themes/docs/theme/visual-style
+   */
+  radius: { type: 'enum', values: radii, default: 'medium' },
+  /**
+   * Sets a scaling multiplier for values like spacing, font sizes, line heights, etc. are scaled.
+   *
+   * @link
+   * https://www.radix-ui.com/themes/docs/theme/layout
+   */
+  scaling: { type: 'enum', values: scalings, default: '100%' },
+  /**
+   * Sets the font family for the theme.
+   *
+   * @default 'sans'
+   */
+  fontFamily: { type: 'enum', values: fontFamilies, default: 'sans' },
+} satisfies {
+  hasBackground: PropDef<boolean>;
+  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]>;
+  fontFamily: PropDef<(typeof fontFamilies)[number]>;
+};
+
+type ThemeOwnProps = GetPropDefTypes<typeof themePropDefs & typeof asChildPropDef>;
+
+export { themePropDefs };
+export type { ThemeOwnProps };

package/src/components/theme.tsx

@@ -0,0 +1,305 @@
+'use client';
+
+import * as React from 'react';
+import classNames from 'classnames';
+import { Direction, Slot, Tooltip as TooltipPrimitive } from 'radix-ui';
+
+import { getMatchingGrayColor } from '../helpers/get-matching-gray-color.js';
+import { themePropDefs } from './theme.props.js';
+
+import type { ThemeOwnProps } from './theme.props.js';
+import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
+
+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];
+type ThemeFontFamily = (typeof themePropDefs.fontFamily.values)[number];
+
+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;
+  onFontFamilyChange: (fontFamily: ThemeFontFamily) => void;
+}
+
+interface ThemeContextValue extends ThemeChangeHandlers {
+  appearance: ThemeAppearance;
+  accentColor: ThemeAccentColor;
+  grayColor: ThemeGrayColor;
+  resolvedGrayColor: ThemeGrayColor;
+  material: ThemeMaterial;
+  panelBackground: ThemePanelBackground;
+  radius: ThemeRadius;
+  scaling: ThemeScaling;
+  fontFamily: ThemeFontFamily;
+}
+// Default theme values used when components render outside a Theme provider
+const defaultThemeContext: ThemeContextValue = {
+  appearance: themePropDefs.appearance.default,
+  accentColor: themePropDefs.accentColor.default,
+  grayColor: themePropDefs.grayColor.default,
+  resolvedGrayColor: themePropDefs.grayColor.default,
+  material: themePropDefs.material.default,
+  panelBackground: themePropDefs.panelBackground.default,
+  radius: themePropDefs.radius.default,
+  scaling: themePropDefs.scaling.default,
+  fontFamily: themePropDefs.fontFamily.default,
+  onAppearanceChange: noop,
+  onAccentColorChange: noop,
+  onGrayColorChange: noop,
+  onMaterialChange: noop,
+  onPanelBackgroundChange: noop,
+  onRadiusChange: noop,
+  onScalingChange: noop,
+  onFontFamilyChange: noop,
+};
+
+const ThemeContext = React.createContext<ThemeContextValue | undefined>(undefined);
+
+function useThemeContext() {
+  const context = React.useContext(ThemeContext);
+  // Return default context if used outside Theme provider (e.g., during SSR)
+  return context ?? defaultThemeContext;
+}
+
+interface ThemeProps extends ThemeImplPublicProps {}
+const Theme = React.forwardRef<ThemeImplElement, ThemeProps>((props, forwardedRef) => {
+  const context = React.useContext(ThemeContext);
+  const isRoot = context === undefined;
+  if (isRoot) {
+    return (
+      <TooltipPrimitive.Provider delayDuration={200}>
+        <Direction.Provider dir="ltr">
+          <ThemeRoot {...props} ref={forwardedRef} />
+        </Direction.Provider>
+      </TooltipPrimitive.Provider>
+    );
+  }
+  return <ThemeImpl {...props} ref={forwardedRef} />;
+});
+Theme.displayName = 'Theme';
+
+const ThemeRoot = React.forwardRef<ThemeImplElement, ThemeImplPublicProps>(
+  (props, forwardedRef) => {
+    const {
+      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,
+      fontFamily: fontFamilyProp = themePropDefs.fontFamily.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]);
+
+    const [accentColor, setAccentColor] = React.useState(accentColorProp);
+    React.useEffect(() => setAccentColor(accentColorProp), [accentColorProp]);
+
+    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(material), [material]);
+
+    const [radius, setRadius] = React.useState(radiusProp);
+    React.useEffect(() => setRadius(radiusProp), [radiusProp]);
+
+    const [scaling, setScaling] = React.useState(scalingProp);
+    React.useEffect(() => setScaling(scalingProp), [scalingProp]);
+
+    const [fontFamily, setFontFamily] = React.useState(fontFamilyProp);
+    React.useEffect(() => setFontFamily(fontFamilyProp), [fontFamilyProp]);
+
+    return (
+      <ThemeImpl
+        {...rootProps}
+        ref={forwardedRef}
+        isRoot
+        hasBackground={hasBackground}
+        //
+        appearance={appearance}
+        accentColor={accentColor}
+        grayColor={grayColor}
+        material={material}
+        panelBackground={panelBackground}
+        radius={radius}
+        scaling={scaling}
+        fontFamily={fontFamily}
+        //
+        onAppearanceChange={setAppearance}
+        onAccentColorChange={setAccentColor}
+        onGrayColorChange={setGrayColor}
+        onMaterialChange={setMaterial}
+        onPanelBackgroundChange={setPanelBackground}
+        onRadiusChange={setRadius}
+        onScalingChange={setScaling}
+        onFontFamilyChange={setFontFamily}
+      />
+    );
+  },
+);
+ThemeRoot.displayName = 'ThemeRoot';
+
+type ThemeImplElement = React.ElementRef<'div'>;
+interface ThemeImplProps extends ThemeImplPublicProps, ThemeImplPrivateProps {}
+interface ThemeImplPublicProps
+  extends ComponentPropsWithout<'div', RemovedProps | 'dir'>,
+    ThemeOwnProps {}
+interface ThemeImplPrivateProps extends Partial<ThemeChangeHandlers> {
+  isRoot?: boolean;
+}
+function getClientOS(): 'windows' | 'macos' | 'linux' | undefined {
+  if (typeof navigator === 'undefined') return undefined;
+  const ua = navigator.userAgent;
+  if (ua.includes('Win')) return 'windows';
+  if (ua.includes('Mac')) return 'macos';
+  if (ua.includes('Linux')) return 'linux';
+  return undefined;
+}
+
+const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, forwardedRef) => {
+  const context = React.useContext(ThemeContext);
+  const {
+    asChild,
+    isRoot,
+    hasBackground: hasBackgroundProp,
+    //
+    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,
+    radius = props.radius ?? context?.radius ?? themePropDefs.radius.default,
+    scaling = props.scaling ?? context?.scaling ?? themePropDefs.scaling.default,
+    fontFamily = props.fontFamily ?? context?.fontFamily ?? themePropDefs.fontFamily.default,
+    //
+    onAppearanceChange = noop,
+    onAccentColorChange = noop,
+    onGrayColorChange = noop,
+    onMaterialChange = noop,
+    onPanelBackgroundChange = noop,
+    onRadiusChange = noop,
+    onScalingChange = noop,
+    onFontFamilyChange = noop,
+    //
+    ...themeProps
+  } = props;
+  const Comp = asChild ? Slot.Root : 'div';
+  const resolvedGrayColor = grayColor === 'auto' ? getMatchingGrayColor(accentColor) : grayColor;
+  const isExplicitAppearance = props.appearance === 'light' || props.appearance === 'dark';
+  const hasBackground =
+    hasBackgroundProp === undefined ? isRoot || isExplicitAppearance : hasBackgroundProp;
+
+  const [clientOS, setClientOS] = React.useState<ReturnType<typeof getClientOS>>(undefined);
+  React.useEffect(() => {
+    if (isRoot) setClientOS(getClientOS());
+  }, [isRoot]);
+
+  return (
+    <ThemeContext.Provider
+      value={React.useMemo(
+        () => ({
+          appearance,
+          accentColor,
+          grayColor,
+          resolvedGrayColor,
+          material,
+          panelBackground,
+          radius,
+          scaling,
+          fontFamily,
+          //
+          onAppearanceChange,
+          onAccentColorChange,
+          onGrayColorChange,
+          onMaterialChange,
+          onPanelBackgroundChange,
+          onRadiusChange,
+          onScalingChange,
+          onFontFamilyChange,
+        }),
+        [
+          appearance,
+          accentColor,
+          grayColor,
+          resolvedGrayColor,
+          material,
+          panelBackground,
+          radius,
+          scaling,
+          fontFamily,
+          //
+          onAppearanceChange,
+          onAccentColorChange,
+          onGrayColorChange,
+          onMaterialChange,
+          onPanelBackgroundChange,
+          onRadiusChange,
+          onScalingChange,
+          onFontFamilyChange,
+        ],
+      )}
+    >
+      <Comp
+        data-is-root-theme={isRoot ? 'true' : 'false'}
+        data-accent-color={accentColor}
+        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}
+        data-font-family={fontFamily}
+        data-os={isRoot ? clientOS : undefined}
+        ref={forwardedRef}
+        {...themeProps}
+        className={classNames(
+          'radix-themes',
+          {
+            light: appearance === 'light',
+            dark: appearance === 'dark',
+          },
+          themeProps.className,
+        )}
+      />
+    </ThemeContext.Provider>
+  );
+});
+ThemeImpl.displayName = 'ThemeImpl';
+
+export { Theme, ThemeContext, useThemeContext };
+export type { ThemeProps, ThemeContextValue };

package/src/components/toggle-button.tsx

@@ -0,0 +1,100 @@
+import * as React from 'react';
+import { Toggle } from 'radix-ui';
+import { Button } from './button.js';
+import { useToggleState } from '../hooks/use-toggle-state.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, children, ...buttonProps }, forwardedRef) => {
+  /**
+   * 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]);
+
+  // Use shared toggle state hook for accessibility announcements and warnings
+  const { handlePressedChange } = useToggleState({
+    pressed,
+    onPressedChange,
+    getAccessibleName,
+    componentName: 'ToggleButton',
+  });
+
+  // Render the toggle button using Radix UI's Toggle primitive
+  // This provides proper ARIA attributes and keyboard navigation
+  return (
+    <Toggle.Root pressed={pressed} onPressedChange={handlePressedChange} defaultPressed={defaultPressed} asChild>
+      <Button {...buttonProps} ref={forwardedRef}>
+        {children}
+      </Button>
+    </Toggle.Root>
+  );
+});
+ToggleButton.displayName = 'ToggleButton';
+
+export { ToggleButton };
+export type { ToggleButtonProps };

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

@@ -0,0 +1,167 @@
+import * as React from 'react';
+import { Toggle } from 'radix-ui';
+import { IconButton } from './icon-button.js';
+import { BaseButton } from './_internal/base-button.js';
+import { useToggleState } from '../hooks/use-toggle-state.js';
+import type { IconButtonProps } from './icon-button.js';
+
+type ToggleIconButtonElement = React.ElementRef<typeof BaseButton>;
+
+/**
+ * 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)
+ * 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 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 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) => {
+  // Extract specific props for stable dependency array
+  const { 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, children } = iconButtonProps;
+
+  // Cache the label lookup from aria-labelledby to avoid repeated DOM queries
+  const cachedLabelRef = React.useRef<string | null>(null);
+
+  // Clear cached label when ariaLabelledBy changes
+  React.useEffect(() => {
+    cachedLabelRef.current = null;
+  }, [ariaLabelledBy]);
+
+  /**
+   * 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(() => {
+    // First priority: direct aria-label
+    if (ariaLabel) return ariaLabel;
+
+    // Second priority: referenced label element (cached)
+    if (ariaLabelledBy) {
+      if (cachedLabelRef.current === null) {
+        const labelElement = document.getElementById(ariaLabelledBy);
+        cachedLabelRef.current = labelElement?.textContent || 'Toggle icon button';
+      }
+      return cachedLabelRef.current;
+    }
+
+    // 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';
+  }, [ariaLabel, ariaLabelledBy, children]);
+
+  // Use shared toggle state hook for accessibility announcements and warnings
+  const { handlePressedChange } = useToggleState({
+    pressed,
+    onPressedChange,
+    getAccessibleName,
+    componentName: 'ToggleIconButton',
+  });
+
+  // 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={handlePressedChange} defaultPressed={defaultPressed} asChild>
+      <IconButton {...iconButtonProps} ref={forwardedRef} />
+    </Toggle.Root>
+  );
+});
+ToggleIconButton.displayName = 'ToggleIconButton';
+
+export { ToggleIconButton };
+export type { ToggleIconButtonPropsWithAccessibility as ToggleIconButtonProps };