@kushagradhawan/kookie-ui 0.1.29 → 0.1.30

package/src/components/_internal/base-button.props.ts

@@ -5,26 +5,113 @@ import { radiusPropDef } from '../../props/radius.prop.js';
 
 import type { PropDef } from '../../props/prop-def.js';
 
+/**
+ * Available button sizes for responsive design
+ * Size 1: 24px - Compact for toolbars and dense interfaces
+ * Size 2: 32px - Standard for most interface contexts
+ * Size 3: 40px - Large for important actions and mobile touch targets
+ * Size 4: 48px - Extra large for hero sections and maximum impact
+ */
 const sizes = ['1', '2', '3', '4'] as const;
+
+/**
+ * Available button variants for different visual contexts
+ * - classic: Premium, sophisticated appearance
+ * - solid: Primary actions that should be noticed first
+ * - soft: Content-heavy interfaces, natural integration
+ * - surface: Elevated appearance with subtle depth
+ * - outline: Secondary actions that support primary actions
+ * - ghost: Utility functions that don't compete for attention
+ */
 const variants = ['classic', 'solid', 'soft', 'surface', 'outline', 'ghost'] as const;
+
+/**
+ * Available panel background options (deprecated)
+ * @deprecated Use `materials` instead
+ */
 const panelBackgrounds = ['solid', 'translucent'] as const;
 
+/**
+ * Available material options for visual rendering
+ * - solid: Opaque backgrounds and borders
+ * - translucent: Elevated effects with depth and visual separation
+ */
+const materials = ['solid', 'translucent'] as const;
+
+/**
+ * Base button prop definitions that define the component's API
+ * 
+ * These props are used by all button variants (Button, IconButton, etc.)
+ * to ensure consistent behavior and styling across the design system.
+ * 
+ * Key features:
+ * - Responsive sizing with mobile-first approach
+ * - Six visual variants for different interface contexts
+ * - Comprehensive color system with semantic meanings
+ * - Loading states with automatic accessibility
+ * - Material system for visual depth and elevation
+ * - Polymorphic rendering support via asChild
+ * 
+ * @example
+ * ```tsx
+ * // Basic button with default props
+ * <BaseButton>Click me</BaseButton>
+ * 
+ * // Button with custom size and variant
+ * <BaseButton size="3" variant="solid">Primary Action</BaseButton>
+ * 
+ * // Button with loading state
+ * <BaseButton loading>Processing...</BaseButton>
+ * 
+ * // Button with material and high contrast
+ * <BaseButton material="translucent" highContrast>Elevated Button</BaseButton>
+ * ```
+ */
 const baseButtonPropDefs = {
   ...asChildPropDef,
+  /**
+   * Button size for responsive design and interface density
+   * Supports responsive objects: { initial: '1', sm: '2', md: '3', lg: '4' }
+   */
   size: { type: 'enum', className: 'rt-r-size', values: sizes, default: '2', responsive: true },
+  /**
+   * Visual variant that determines the button's appearance and context
+   */
   variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'solid' },
   ...accentColorPropDef,
   ...highContrastPropDef,
   ...radiusPropDef,
+  /**
+   * Loading state that shows a spinner and disables interaction
+   * Automatically sets disabled=true and provides accessibility announcements
+   */
   loading: { type: 'boolean', className: 'rt-loading', default: false },
+  /**
+   * Full width mode that expands the button to fill its container
+   * Useful for mobile layouts and form submissions
+   */
   fullWidth: { type: 'boolean', className: 'rt-full-width', default: false },
+  /**
+   * Material type for visual rendering and depth effects
+   * Controls how the button renders its visual elements
+   */
+  material: { type: 'enum', values: materials, default: undefined },
+  /**
+   * Panel background type (deprecated)
+   * @deprecated Use `material` prop instead. This prop will be removed in a future version.
+   */
   panelBackground: { type: 'enum', values: panelBackgrounds, default: undefined },
+  /**
+   * Flush mode that removes visual padding for seamless text integration
+   * Only effective with ghost variant
+   */
   flush: { type: 'boolean', default: false },
 } satisfies {
   size: PropDef<(typeof sizes)[number]>;
   variant: PropDef<(typeof variants)[number]>;
   loading: PropDef<boolean>;
   fullWidth: PropDef<boolean>;
+  material: PropDef<(typeof materials)[number] | undefined>;
   panelBackground: PropDef<(typeof panelBackgrounds)[number] | undefined>;
   flush: PropDef<boolean>;
 };

package/src/components/_internal/base-button.tsx

@@ -17,17 +17,54 @@ import type { GetPropDefTypes } from '../../props/prop-def.js';
 type BaseButtonElement = React.ElementRef<'button'>;
 type BaseButtonOwnProps = GetPropDefTypes<typeof baseButtonPropDefs>;
 
-// Polymorphic types using the proper ComponentPropsWithout pattern
+/**
+ * Polymorphic BaseButton props that support rendering as different HTML elements
+ * Uses the proper ComponentPropsWithout pattern for type safety
+ * @template C - The element type to render as (defaults to 'button')
+ */
 type PolymorphicBaseButtonProps<C extends React.ElementType = 'button'> = {
+  /** Element type to render as (e.g., 'a', 'span', etc.) */
   as?: C;
 } & BaseButtonOwnProps &
   MarginProps &
   ComponentPropsWithout<C, RemovedProps | keyof BaseButtonOwnProps | keyof MarginProps | 'as'>;
 
+/**
+ * BaseButton props interface that combines all available props
+ */
 interface BaseButtonProps extends PolymorphicBaseButtonProps {}
 
+/**
+ * BaseButton component that provides the core button functionality
+ *
+ * This is the foundational button component that handles all the complex logic
+ * including loading states, accessibility, performance optimizations, and
+ * polymorphic rendering. It's used by Button, IconButton, and other button
+ * variants to ensure consistent behavior across the design system.
+ *
+ * Key features:
+ * - Loading state with spinner and accessibility announcements
+ * - Performance optimizations for backdrop-filter effects
+ * - Comprehensive accessibility support
+ * - Polymorphic rendering support
+ * - Material/panel background handling
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <BaseButton>Click me</BaseButton>
+ *
+ * // With loading state
+ * <BaseButton loading>Processing...</BaseButton>
+ *
+ * // Polymorphic rendering
+ * <BaseButton as="a" href="/link">Link Button</BaseButton>
+ * ```
+ */
 const BaseButton = React.forwardRef<BaseButtonElement, BaseButtonProps>((props, forwardedRef) => {
   const { size = baseButtonPropDefs.size.default } = props;
+
+  // Extract button-specific props from the combined props object
   const {
     className,
     children,
@@ -35,16 +72,72 @@ const BaseButton = React.forwardRef<BaseButtonElement, BaseButtonProps>((props,
     as,
     color,
     radius,
+    material,
     panelBackground,
     flush,
-    disabled = props.loading,
+    disabled = props.loading, // Loading state automatically disables the button
     ...baseButtonProps
   } = extractProps(props, baseButtonPropDefs, marginPropDefs);
 
-  // asChild takes precedence over as prop
+  // Show deprecation warning for panelBackground when used
+  // This helps developers migrate to the new material prop
+  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 for backward compatibility
+  const effectiveMaterial = material ?? panelBackground;
+
+  // Will-change cleanup for backdrop-filter performance optimization
+  // This prevents layout thrashing when using translucent materials
+  const buttonRef = React.useRef<HTMLElement>(null);
+
+  React.useEffect(() => {
+    const button = buttonRef.current;
+    if (!button) return;
+
+    const hasTranslucentMaterial = effectiveMaterial === 'translucent';
+
+    if (hasTranslucentMaterial) {
+      // Add will-change when material is translucent to optimize rendering
+      button.style.setProperty('will-change', 'backdrop-filter');
+
+      // Clean up will-change after transition completes to prevent memory leaks
+      const cleanup = () => {
+        const transitionDuration =
+          getComputedStyle(button).getPropertyValue('--duration-2') || '75ms';
+        const duration = parseInt(transitionDuration) || 75;
+
+        setTimeout(() => {
+          if (button && effectiveMaterial !== 'translucent') {
+            button.style.setProperty('will-change', 'auto');
+          }
+        }, duration);
+      };
+
+      // Listen for material changes to clean up will-change property
+      const observer = new MutationObserver(cleanup);
+      observer.observe(button, { attributes: true, attributeFilter: ['data-material'] });
+
+      return () => {
+        observer.disconnect();
+        button.style.setProperty('will-change', 'auto');
+      };
+    } else {
+      // Remove will-change when material is not translucent
+      button.style.setProperty('will-change', 'auto');
+    }
+  }, [effectiveMaterial]);
+
+  // asChild takes precedence over as prop for Radix Slot integration
   const Comp = asChild ? Slot.Root : as || 'button';
 
   // Only pass disabled for elements that support it
+  // This prevents invalid HTML attributes on unsupported elements
   const shouldPassDisabled =
     asChild || !as || ['button', 'input', 'textarea', 'select'].includes(as);
 
@@ -52,14 +145,28 @@ const BaseButton = React.forwardRef<BaseButtonElement, BaseButtonProps>((props,
   const loadingId = React.useId();
   const describedById = props.loading ? `${loadingId}-loading` : undefined;
 
+  // Extract button text for accessibility announcements
+  const buttonText = React.useMemo(() => {
+    if (typeof children === 'string') return children;
+    if (React.isValidElement(children) && typeof (children.props as any)?.children === 'string') {
+      return (children.props as any).children;
+    }
+    return 'button';
+  }, [children]);
+
   // Enhanced accessibility props for loading state
-  const accessibilityProps = props.loading
-    ? {
+  // These ensure screen readers announce the loading state properly
+  const accessibilityProps = React.useMemo(() => {
+    if (props.loading) {
+      return {
         'aria-busy': true,
         'aria-disabled': true,
         'aria-describedby': describedById,
-      }
-    : {};
+        'aria-label': `${buttonText} (loading)`,
+      };
+    }
+    return {};
+  }, [props.loading, describedById, buttonText]);
 
   return (
     <Comp
@@ -67,11 +174,20 @@ const BaseButton = React.forwardRef<BaseButtonElement, BaseButtonProps>((props,
       data-disabled={disabled || undefined}
       data-accent-color={color}
       data-radius={radius}
-      data-panel-background={panelBackground}
+      data-material={effectiveMaterial}
+      data-panel-background={effectiveMaterial}
       data-flush={flush ? 'true' : undefined}
       {...baseButtonProps}
       {...accessibilityProps}
-      ref={forwardedRef}
+      ref={(node) => {
+        // Handle both forwarded ref and internal ref for performance optimization
+        if (typeof forwardedRef === 'function') {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+        buttonRef.current = node;
+      }}
       className={classNames('rt-reset', 'rt-BaseButton', className)}
       {...(shouldPassDisabled && { disabled })}
     >
@@ -90,10 +206,11 @@ const BaseButton = React.forwardRef<BaseButtonElement, BaseButtonProps>((props,
 
           {/* Enhanced accessibility for loading state */}
           <VisuallyHidden>
-            <span id={describedById}>Loading, please wait...</span>
+            <span id={describedById}>{buttonText} is loading, please wait...</span>
             {children}
           </VisuallyHidden>
 
+          {/* Centered spinner overlay during loading state */}
           <Flex asChild align="center" justify="center" position="absolute" inset="0">
             <span>
               <Spinner