@kushagradhawan/kookie-ui 0.1.29 → 0.1.30

package/src/components/dropdown-menu.tsx

@@ -52,11 +52,34 @@ interface DropdownMenuContentProps
 const DropdownMenuContent = React.forwardRef<DropdownMenuContentElement, DropdownMenuContentProps>(
   (props, forwardedRef) => {
     const themeContext = useThemeContext();
+
+    // 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]);
+
+    // Material takes precedence over panelBackground
+    const effectiveMaterial =
+      props.material ?? props.panelBackground ?? themeContext.panelBackground;
+
+    // Memoize theme context values to prevent unnecessary re-renders
+    const memoizedThemeContext = React.useMemo(
+      () => ({
+        material: effectiveMaterial,
+        accentColor: themeContext.accentColor,
+      }),
+      [effectiveMaterial, themeContext.accentColor],
+    );
+
     const {
       size = dropdownMenuContentPropDefs.size.default,
       variant = dropdownMenuContentPropDefs.variant.default,
       highContrast = dropdownMenuContentPropDefs.highContrast.default,
-      panelBackground = props.panelBackground ?? themeContext.panelBackground,
+      material = memoizedThemeContext.material,
     } = props;
     const {
       className,
@@ -64,16 +87,23 @@ const DropdownMenuContent = React.forwardRef<DropdownMenuContentElement, Dropdow
       color,
       container,
       forceMount,
-      panelBackground: _,
+      material: _,
+      panelBackground: __,
       ...contentProps
     } = extractProps(props, dropdownMenuContentPropDefs);
-    const resolvedColor = color || themeContext.accentColor;
+
+    // Memoize color resolution to prevent unnecessary re-renders
+    const resolvedColor = React.useMemo(
+      () => color || memoizedThemeContext.accentColor,
+      [color, memoizedThemeContext.accentColor],
+    );
     return (
       <DropdownMenuPrimitive.Portal container={container} forceMount={forceMount}>
         <Theme asChild>
           <DropdownMenuPrimitive.Content
             data-accent-color={resolvedColor}
-            data-panel-background={panelBackground}
+            data-material={material}
+            data-panel-background={material}
             align="start"
             sideOffset={4}
             collisionPadding={10}
@@ -91,8 +121,8 @@ const DropdownMenuContent = React.forwardRef<DropdownMenuContentElement, Dropdow
               <div className={classNames('rt-BaseMenuViewport', 'rt-DropdownMenuViewport')}>
                 <DropdownMenuContentContext.Provider
                   value={React.useMemo(
-                    () => ({ size, variant, color: resolvedColor, highContrast, panelBackground }),
-                    [size, variant, resolvedColor, highContrast, panelBackground],
+                    () => ({ size, variant, color: resolvedColor, highContrast, material }),
+                    [size, variant, resolvedColor, highContrast, material],
                   )}
                 >
                   {children}
@@ -307,25 +337,31 @@ DropdownMenuSubTrigger.displayName = 'DropdownMenu.SubTrigger';
 
 type DropdownMenuSubContentElement = React.ElementRef<typeof DropdownMenuPrimitive.SubContent>;
 interface DropdownMenuSubContentProps
-  extends ComponentPropsWithout<typeof DropdownMenuPrimitive.SubContent, RemovedProps> {
+  extends ComponentPropsWithout<typeof DropdownMenuPrimitive.SubContent, RemovedProps>,
+    DropdownMenuContentContextValue {
   container?: React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Portal>['container'];
 }
 const DropdownMenuSubContent = React.forwardRef<
   DropdownMenuSubContentElement,
   DropdownMenuSubContentProps
 >((props, forwardedRef) => {
-  const { size, variant, color, highContrast, panelBackground } = React.useContext(
-    DropdownMenuContentContext,
+  // Memoize context consumption to prevent unnecessary re-renders
+  const contextValue = React.useContext(DropdownMenuContentContext);
+  const { size, variant, color, highContrast, material } = React.useMemo(
+    () => contextValue,
+    [contextValue],
   );
+
   const {
     className,
     children,
     container,
     forceMount,
-    panelBackground: _,
+    material: _,
+    panelBackground: __,
     ...subContentProps
   } = extractProps(
-    { size, variant, color, highContrast, panelBackground, ...props },
+    { size, variant, color, highContrast, material, ...props },
     dropdownMenuContentPropDefs,
   );
   return (
@@ -333,7 +369,8 @@ const DropdownMenuSubContent = React.forwardRef<
       <Theme asChild>
         <DropdownMenuPrimitive.SubContent
           data-accent-color={color}
-          data-panel-background={panelBackground}
+          data-material={material}
+          data-panel-background={material}
           alignOffset={-Number(size) * 4}
           // Side offset accounts for the outer solid box-shadow
           sideOffset={1}

package/src/components/icon-button.css

@@ -1,11 +1,35 @@
+/**
+ * IconButton Component Styles
+ * 
+ * This file contains the core styling for the IconButton component, which
+ * extends the base button with specialized behavior for icon-only interactions.
+ * Icon buttons maintain square aspect ratios and provide consistent icon sizing
+ * across all variants and sizes.
+ * 
+ * Key features:
+ * - Square aspect ratios for consistent visual alignment
+ * - Automatic icon sizing based on button size
+ * - Specialized flush behavior for ghost variants
+ * - Responsive design with mobile-first approach
+ * - Seamless text integration with negative margins
+ */
+
 @import './_internal/base-button.css';
 
 /***************************************************************************************************
  *                                                                                                 *
  * SIZES                                                                                           *
  *                                                                                                 *
+ * Icon button sizes maintain square aspect ratios for consistent visual alignment.
+ * Each size corresponds to the same dimensions as regular buttons but ensures
+ * perfect squares for optimal icon display and touch targets.
+ *                                                                                                 *
  ***************************************************************************************************/
 
+/* 
+ * Base icon button styling that ensures square aspect ratios
+ * Uses the same height as base buttons but sets width to match
+ */
 .rt-IconButton {
   height: var(--base-button-height);
   width: var(--base-button-height);
@@ -13,28 +37,54 @@
 
 @breakpoints {
   .rt-IconButton {
+    /* 
+     * Size 1: Compact (24px x 24px)
+     * Designed for toolbars and dense interfaces
+     */
     &:where(.rt-r-size-1) {
+      /* 
+       * Icon sizing for size 1
+       * Icons are automatically sized to match the button's scale
+       */
       /* stylelint-disable-next-line selector-max-type */
       & :where(svg) {
         width: var(--content-icon-size-1);
         height: var(--content-icon-size-1);
       }
     }
+    
+    /* 
+     * Size 2: Standard (32px x 32px)
+     * Default size for most interface contexts
+     */
     &:where(.rt-r-size-2) {
+      /* Icon sizing for size 2 */
       /* stylelint-disable-next-line selector-max-type */
       & :where(svg) {
         width: var(--content-icon-size-2);
         height: var(--content-icon-size-2);
       }
     }
+    
+    /* 
+     * Size 3: Large (40px x 40px)
+     * Recommended for important actions and mobile touch targets
+     */
     &:where(.rt-r-size-3) {
+      /* Icon sizing for size 3 */
       /* stylelint-disable-next-line selector-max-type */
       & :where(svg) {
         width: var(--content-icon-size-3);
         height: var(--content-icon-size-3);
       }
     }
+    
+    /* 
+     * Size 4: Extra Large (48px x 48px)
+     * Designed for hero sections and maximum visual impact
+     */
     &:where(.rt-r-size-4) {
+      /* Icon sizing for size 4 */
       /* stylelint-disable-next-line selector-max-type */
       & :where(svg) {
         width: var(--content-icon-size-4);
@@ -43,27 +93,42 @@
     }
   }
 
+  /* 
+   * Specialized flush behavior for ghost variant icon buttons
+   * This creates seamless text integration by using negative margins
+   * to compensate for the button's padding
+   */
   .rt-IconButton:where(.rt-variant-ghost) {
     &:where([data-flush='true']) {
-      /* We reset the defined margin variables to avoid inheriting them from a higher component */
-      /* If a margin IS defined on the component itself, the utility class will win and reset it */
+      /* 
+       * Reset defined margin variables to avoid inheriting from higher components
+       * If a margin IS defined on the component itself, the utility class will win and reset it
+       */
       --margin-top: 0px;
       --margin-right: 0px;
       --margin-bottom: 0px;
       --margin-left: 0px;
 
-      /* Define the overrides to incorporate the negative margins using ghost padding */
+      /* 
+       * Define overrides to incorporate negative margins using ghost padding
+       * This creates the seamless integration effect by pulling the button
+       * closer to surrounding text
+       */
       --margin-top-override: calc(var(--margin-top) - var(--icon-button-ghost-padding));
       --margin-right-override: calc(var(--margin-right) - var(--icon-button-ghost-padding));
       --margin-bottom-override: calc(var(--margin-bottom) - var(--icon-button-ghost-padding));
       --margin-left-override: calc(var(--margin-left) - var(--icon-button-ghost-padding));
 
+      /* Apply the calculated negative margins */
       margin-top: var(--margin-top-override);
       margin-right: var(--margin-right-override);
       margin-bottom: var(--margin-bottom-override);
       margin-left: var(--margin-left-override);
 
-      /* Reset the overrides on direct children */
+      /* 
+       * Reset the overrides on direct children
+       * This prevents the negative margins from affecting child elements
+       */
       :where(&) > * {
         --margin-top-override: initial;
         --margin-right-override: initial;
@@ -72,6 +137,10 @@
       }
     }
 
+    /* 
+     * Ghost padding values for different sizes
+     * These determine the amount of negative margin applied in flush mode
+     */
     &:where(.rt-r-size-1) {
       --icon-button-ghost-padding: var(--space-1);
     }

package/src/components/icon-button.tsx

@@ -2,55 +2,161 @@ import * as React from 'react';
 import classNames from 'classnames';
 
 import { BaseButton } from './_internal/base-button.js';
+import { Tooltip } from './tooltip.js';
 import type { BaseButtonProps } from './_internal/base-button.js';
 
 type IconButtonElement = React.ElementRef<typeof BaseButton>;
 
-// Required accessibility props for icon buttons
+/**
+ * Required accessibility props for icon buttons
+ * 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 };
 
-// Polymorphic IconButton props with required accessibility
-type IconButtonOwnProps = Omit<BaseButtonProps, 'as'> & AccessibilityProps;
+/**
+ * Tooltip configuration props that can be passed to IconButton
+ * These props are forwarded to the underlying Tooltip component
+ */
+interface IconButtonTooltipProps {
+  /** Content to display in the tooltip on hover/focus */
+  tooltip?: React.ReactNode;
+  /** Side of the button where the tooltip should appear */
+  tooltipSide?: 'top' | 'right' | 'bottom' | 'left';
+  /** Alignment of the tooltip relative to the button */
+  tooltipAlign?: 'start' | 'center' | 'end';
+  /** Delay before showing the tooltip (in milliseconds) */
+  tooltipDelayDuration?: number;
+  /** Whether to disable hoverable content behavior */
+  tooltipDisableHoverableContent?: boolean;
+}
 
+/**
+ * Core IconButton props excluding the 'as' prop for polymorphic behavior
+ * Combines BaseButton props with accessibility requirements and tooltip functionality
+ */
+type IconButtonOwnProps = Omit<BaseButtonProps, 'as'> & AccessibilityProps & IconButtonTooltipProps;
+
+/**
+ * Polymorphic IconButton props that support rendering as different HTML elements
+ * @template C - The element type to render as (defaults to 'button')
+ */
 type IconButtonProps<C extends React.ElementType = 'button'> = IconButtonOwnProps & {
+  /** Element type to render as (e.g., 'a', 'span', etc.) */
   as?: C;
 } & Omit<React.ComponentPropsWithoutRef<C>, keyof IconButtonOwnProps>;
 
+/**
+ * IconButton component type that supports polymorphic rendering
+ * @template C - The element type to render as
+ */
 type IconButtonComponent = <C extends React.ElementType = 'button'>(
   props: IconButtonProps<C> & { ref?: React.ForwardedRef<IconButtonElement> },
 ) => React.ReactElement | null;
 
+/**
+ * IconButton component for compact, accessible icon-only interactions
+ *
+ * The IconButton component extends Button with specialized behavior for visual symbols.
+ * It enforces accessibility requirements, provides automatic square sizing, and includes
+ * built-in tooltip integration. Icon buttons are essential for space-efficient interfaces
+ * while maintaining accessibility compliance.
+ *
+ * Key features:
+ * - Enforced accessibility requirements (aria-label, aria-labelledby, or children)
+ * - Automatic square aspect ratios for consistent visual alignment
+ * - Built-in tooltip support for context and guidance
+ * - Same variant and size system as Button for consistency
+ * - Runtime validation for accessibility compliance
+ *
+ * @example
+ * ```tsx
+ * // Basic icon button with aria-label
+ * <IconButton aria-label="Settings">
+ *   <Settings />
+ * </IconButton>
+ *
+ * // Icon button with tooltip
+ * <IconButton aria-label="Save" tooltip="Save your progress">
+ *   <Save />
+ * </IconButton>
+ *
+ * // Icon button with aria-labelledby
+ * <IconButton aria-labelledby="settings-label">
+ *   <Settings />
+ * </IconButton>
+ * <span id="settings-label">Open settings panel</span>
+ *
+ * // Icon button with visible text (fallback)
+ * <IconButton>
+ *   <Settings />
+ *   Settings
+ * </IconButton>
+ * ```
+ */
 const IconButton = React.forwardRef(
   (
-    { className, ...props }: IconButtonProps,
+    {
+      className,
+      tooltip,
+      tooltipSide = 'top',
+      tooltipAlign = 'center',
+      tooltipDelayDuration,
+      tooltipDisableHoverableContent,
+      ...props
+    }: IconButtonProps,
     forwardedRef: React.ForwardedRef<IconButtonElement>,
   ) => {
-    // Warn in development if no accessibility attributes are provided
-    if (process.env.NODE_ENV === 'development') {
-      const hasAriaLabel = 'aria-label' in props && props['aria-label'];
-      const hasAriaLabelledBy = 'aria-labelledby' in props && props['aria-labelledby'];
-      const hasChildren = 'children' in props && props.children;
-
-      if (!hasAriaLabel && !hasAriaLabelledBy && !hasChildren) {
-        console.warn(
-          'IconButton: Icon buttons must have an accessible name. Please provide either:' +
-            '\n- aria-label prop with descriptive text' +
-            '\n- aria-labelledby prop referencing a label element' +
-            '\n- or visible text children',
-        );
-      }
+    // Runtime accessibility validation to ensure WCAG compliance
+    // This helps catch accessibility issues during development
+    const hasAriaLabel = 'aria-label' in props && props['aria-label'];
+    const hasAriaLabelledBy = 'aria-labelledby' in props && props['aria-labelledby'];
+    const hasChildren = 'children' in props && props.children;
+
+    // Throw descriptive error if no accessible name is provided
+    if (!hasAriaLabel && !hasAriaLabelledBy && !hasChildren) {
+      throw new Error(
+        'IconButton: Icon buttons must have an accessible name. Please provide either:' +
+          '\n- aria-label prop with descriptive text' +
+          '\n- aria-labelledby prop referencing a label element' +
+          '\n- or visible text children',
+      );
     }
 
-    return (
+    // Create the base icon button element with accessibility props
+    const iconButton = (
       <BaseButton
         {...props}
         ref={forwardedRef}
         className={classNames('rt-IconButton', className)}
       />
     );
+
+    // If no tooltip is provided, return the icon button as-is for better performance
+    if (!tooltip) {
+      return iconButton;
+    }
+
+    // Wrap with Tooltip when tooltip content is provided
+    // This creates a compound component that handles both button and tooltip functionality
+    return (
+      <Tooltip
+        content={tooltip}
+        side={tooltipSide}
+        align={tooltipAlign}
+        delayDuration={tooltipDelayDuration}
+        disableHoverableContent={tooltipDisableHoverableContent}
+      >
+        {iconButton}
+      </Tooltip>
+    );
   },
 ) as IconButtonComponent & { displayName?: string };