@kushagradhawan/kookie-ui 0.1.29 → 0.1.30

package/src/components/button.css

@@ -1,7 +1,29 @@
+/**
+ * Button Component Styles
+ * 
+ * This file contains the core styling for the Button component, including
+ * size variants, icon handling, and responsive design patterns. The styles
+ * are built on top of the base button styles imported from _internal.
+ * 
+ * Key features:
+ * - Responsive sizing with mobile-first approach
+ * - Automatic icon sizing based on button size
+ * - Ghost variant with specialized padding
+ * - Consistent typography and spacing
+ */
+
 @import './_internal/base-button.css';
 
+/* 
+ * Button-specific styles that extend the base button
+ * These styles handle icon opacity and specialized behaviors
+ */
 .rt-Button {
   &:where(:not(.rt-variant-ghost)) {
+    /* 
+     * Reduce icon opacity slightly for better visual hierarchy
+     * This creates a subtle distinction between icons and text
+     */
     /* stylelint-disable-next-line selector-max-type */
     & :where(svg) {
       opacity: 0.9;
@@ -13,8 +35,18 @@
  *                                                                                                 *
  * SIZES                                                                                           *
  *                                                                                                 *
+ * Button sizes are designed for different interface densities and contexts:
+ * - 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
+ *                                                                                                 *
  ***************************************************************************************************/
 
+/* 
+ * Ghost variant has specialized padding that differs from other variants
+ * This creates a more subtle, text-like appearance
+ */
 .rt-Button {
   &:where(.rt-variant-ghost) {
     padding: var(--button-ghost-padding-y) var(--button-ghost-padding-x);
@@ -23,88 +55,132 @@
 
 @breakpoints {
   .rt-Button {
+    /* 
+     * Size 1: Compact (24px height)
+     * Designed for toolbars, dense interfaces, and space-constrained contexts
+     */
     &:where(.rt-r-size-1) {
       gap: var(--component-gap-1);
       font-size: var(--font-size-1);
       line-height: var(--line-height-1);
       letter-spacing: var(--letter-spacing-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);
       }
 
+      /* 
+       * Standard padding for non-ghost variants
+       * Provides adequate touch targets while maintaining compact appearance
+       */
       &:where(:not(.rt-variant-ghost)) {
         padding-left: var(--space-2);
         padding-right: var(--space-2);
       }
+      
+      /* 
+       * Ghost variant padding for size 1
+       * Reduced padding creates seamless text integration
+       */
       &:where(.rt-variant-ghost) {
         gap: var(--component-gap-ghost-1);
         --button-ghost-padding-x: var(--space-2);
         --button-ghost-padding-y: var(--space-1);
       }
     }
+    
+    /* 
+     * Size 2: Standard (32px height)
+     * Default size for most interface contexts and general use
+     */
     &:where(.rt-r-size-2) {
       gap: var(--component-gap-2);
       font-size: var(--font-size-2);
       line-height: var(--line-height-2);
       letter-spacing: var(--letter-spacing-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);
       }
 
+      /* Standard padding for non-ghost variants */
       &:where(:not(.rt-variant-ghost)) {
         padding-left: var(--space-3);
         padding-right: var(--space-3);
       }
+      
+      /* Ghost variant padding for size 2 */
       &:where(.rt-variant-ghost) {
         gap: var(--component-gap-ghost-2);
         --button-ghost-padding-x: var(--space-2);
         --button-ghost-padding-y: var(--space-1);
       }
     }
+    
+    /* 
+     * Size 3: Large (40px height)
+     * Recommended for important actions and mobile touch targets
+     */
     &:where(.rt-r-size-3) {
       gap: var(--component-gap-3);
       font-size: var(--font-size-3);
       line-height: var(--line-height-3);
       letter-spacing: var(--letter-spacing-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);
       }
 
+      /* Standard padding for non-ghost variants */
       &:where(:not(.rt-variant-ghost)) {
         padding-left: var(--space-4);
         padding-right: var(--space-4);
       }
+      
+      /* Ghost variant padding for size 3 */
       &:where(.rt-variant-ghost) {
         gap: var(--component-gap-ghost-3);
         --button-ghost-padding-x: var(--space-3);
         --button-ghost-padding-y: calc(var(--space-1) * 1.5);
       }
     }
+    
+    /* 
+     * Size 4: Extra Large (48px height)
+     * Designed for hero sections and maximum visual impact
+     */
     &:where(.rt-r-size-4) {
       gap: var(--component-gap-4);
       font-size: var(--font-size-4);
       line-height: var(--line-height-4);
       letter-spacing: var(--letter-spacing-4);
 
+      /* Icon sizing for size 4 */
       /* stylelint-disable-next-line selector-max-type */
       & :where(svg) {
         width: var(--content-icon-size-4);
         height: var(--content-icon-size-4);
       }
 
+      /* Standard padding for non-ghost variants */
       &:where(:not(.rt-variant-ghost)) {
         padding-left: var(--space-5);
         padding-right: var(--space-5);
       }
+      
+      /* Ghost variant padding for size 4 */
       &:where(.rt-variant-ghost) {
         gap: var(--component-gap-ghost-4);
         --button-ghost-padding-x: var(--space-4);
@@ -118,8 +194,20 @@
  *                                                                                                 *
  * VARIANTS                                                                                        *
  *                                                                                                 *
+ * Button variants provide different visual contexts and hierarchies:
+ * - 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
+ *                                                                                                 *
  ***************************************************************************************************/
 
+/* 
+ * Typography styling for all button variants
+ * Ensures consistent font weight across all button types
+ */
 .rt-Button {
   font-weight: var(--font-weight-medium);
 }

package/src/components/button.props.tsx

@@ -1 +1,18 @@
+/**
+ * Button prop definitions exported for external use
+ *
+ * This file re-exports the base button prop definitions to provide
+ * a clean API for the Button component. The base button props are
+ * defined in the _internal directory and used by all button variants
+ * to ensure consistency across the design system.
+ *
+ * @example
+ * ```tsx
+ * import { buttonPropDefs } from '@kushagradhawan/kookie-ui';
+ *
+ * // Access button prop definitions for type checking or validation
+ * type ButtonSize = typeof buttonPropDefs.size.values[number];
+ * type ButtonVariant = typeof buttonPropDefs.variant.values[number];
+ * ```
+ */
 export { baseButtonPropDefs as buttonPropDefs } from './_internal/base-button.props.js';

package/src/components/button.tsx

@@ -2,25 +2,127 @@ 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 ButtonElement = React.ElementRef<typeof BaseButton>;
 
-// Polymorphic Button props
-type ButtonOwnProps = Omit<BaseButtonProps, 'as'>;
+/**
+ * Tooltip configuration props that can be passed to Button
+ * These props are forwarded to the underlying Tooltip component
+ */
+interface ButtonTooltipProps {
+  /** 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 Button props excluding the 'as' prop for polymorphic behavior
+ * Combines BaseButton props with tooltip functionality
+ */
+type ButtonOwnProps = Omit<BaseButtonProps, 'as'> & ButtonTooltipProps;
+
+/**
+ * Polymorphic Button props that support rendering as different HTML elements
+ * @template C - The element type to render as (defaults to 'button')
+ */
 type ButtonProps<C extends React.ElementType = 'button'> = ButtonOwnProps & {
+  /** Element type to render as (e.g., 'a', 'span', etc.) */
   as?: C;
 } & Omit<React.ComponentPropsWithoutRef<C>, keyof ButtonOwnProps>;
 
+/**
+ * Button component type that supports polymorphic rendering
+ * @template C - The element type to render as
+ */
 type ButtonComponent = <C extends React.ElementType = 'button'>(
   props: ButtonProps<C> & { ref?: React.ForwardedRef<ButtonElement> },
 ) => React.ReactElement | null;
 
+/**
+ * Button component for triggering actions throughout your interface
+ *
+ * The Button component is the primary interactive element in the Kookie User Interface.
+ * It provides six visual variants, four sizes, comprehensive color options, and built-in
+ * tooltip support. The component automatically handles icon sizing, supports responsive
+ * layouts, and provides accessibility compliance out of the box.
+ *
+ * @example
+ * ```tsx
+ * // Basic button
+ * <Button>Click me</Button>
+ *
+ * // Button with variant and size
+ * <Button variant="solid" size="3">Primary Action</Button>
+ *
+ * // Button with tooltip
+ * <Button tooltip="Save your progress">Save</Button>
+ *
+ * // Polymorphic button as link
+ * <Button as="a" href="/dashboard">Go to Dashboard</Button>
+ * ```
+ */
 const Button = React.forwardRef(
-  ({ className, ...props }: ButtonProps, forwardedRef: React.ForwardedRef<ButtonElement>) => (
-    <BaseButton {...props} ref={forwardedRef} className={classNames('rt-Button', className)} />
-  ),
+  (
+    {
+      className,
+      tooltip,
+      tooltipSide = 'top',
+      tooltipAlign = 'center',
+      tooltipDelayDuration,
+      tooltipDisableHoverableContent,
+      ...props
+    }: ButtonProps,
+    forwardedRef: React.ForwardedRef<ButtonElement>,
+  ) => {
+    // Generate unique ID for tooltip accessibility
+    const tooltipId = React.useId();
+    const hasTooltip = Boolean(tooltip);
+
+    // Prepare accessibility props for tooltip integration
+    const tooltipAccessibilityProps = React.useMemo(
+      () => (hasTooltip ? { 'aria-describedby': tooltipId } : {}),
+      [hasTooltip, tooltipId],
+    );
+
+    // Create the base button element with tooltip accessibility props
+    const button = (
+      <BaseButton
+        {...props}
+        {...tooltipAccessibilityProps}
+        ref={forwardedRef}
+        className={classNames('rt-Button', className)}
+      />
+    );
+
+    // If no tooltip is provided, return the button as-is for better performance
+    if (!tooltip) {
+      return button;
+    }
+
+    // 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}
+        id={tooltipId}
+      >
+        {button}
+      </Tooltip>
+    );
+  },
 ) as ButtonComponent & { displayName?: string };
 
 Button.displayName = 'Button';

package/src/components/callout.css

@@ -7,9 +7,45 @@
   color: var(--accent-a11);
   transition: var(--transition-card);
 
+  /* Theme-level translucent override */
+  :where([data-panel-background='translucent'], [data-material='translucent']) & {
+    backdrop-filter: var(--backdrop-filter-components);
+    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+  }
+
+  /* Prevent backdrop-filter stacking with parents */
+  isolation: isolate;
+
+  /* Component-level overrides */
+  &:where([data-panel-background='solid'], [data-material='solid']) {
+    backdrop-filter: none;
+    --backdrop-filter-components: none;
+  }
+  
+  &:where([data-panel-background='translucent'], [data-material='translucent']) {
+    backdrop-filter: var(--backdrop-filter-components);
+    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+  }
+
   &:where(.rt-high-contrast) {
     color: var(--accent-12);
   }
+
+  /* Focus styles for accessibility */
+  &:where(:focus-visible) {
+    outline: 2px solid var(--accent-8);
+    outline-offset: 2px;
+  }
+
+  /* Reduced motion support */
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+
+  /* Forced colors support */
+  @media (forced-colors: active) {
+    border: 1px solid CanvasText;
+  }
 }
 
 .rt-CalloutIcon {
@@ -75,56 +111,56 @@
 /* soft */
 
 .rt-CalloutRoot:where(.rt-variant-soft) {
-  /* Base state: solid colors for solid panels */
-  background-color: var(--accent-3);
+  /* Base state: solid color for solid panels */
+  background-color: var(--accent-2);
+  color: var(--accent-a11);
 
   /* Theme-level translucent override */
-  :where([data-panel-background='translucent']) & {
-    background-color: var(--accent-a3);
-    backdrop-filter: var(--backdrop-filter-panel);
+  :where([data-panel-background='translucent'], [data-material='translucent']) & {
+    background-color: color-mix(in srgb, var(--accent-a2), var(--accent-2) 60%);
   }
 
   /* Component-level overrides (higher specificity) */
-  &:where([data-panel-background='solid']) {
-    background-color: var(--accent-3);
-    backdrop-filter: none;
-    --backdrop-filter-panel: none;
+  &:where([data-panel-background='solid'], [data-material='solid']) {
+    background-color: var(--accent-2);
+  }
+
+  &:where([data-panel-background='translucent'], [data-material='translucent']) {
+    background-color: color-mix(in srgb, var(--accent-a2), var(--accent-2) 60%);
   }
 
-  &:where([data-panel-background='translucent']) {
-    background-color: var(--accent-a3);
-    backdrop-filter: var(--backdrop-filter-panel);
-    --backdrop-filter-panel: blur(var(--backdrop-blur-panel));
+  &:where(.rt-high-contrast) {
+    color: var(--accent-12);
   }
 }
 
 /* surface */
 
 .rt-CalloutRoot:where(.rt-variant-surface) {
-  /* Base state: solid colors for solid panels */
+  /* Base state: solid accent for solid panels */
   background-color: var(--accent-2);
-  box-shadow: inset 0 0 0 var(--border-width-standard) var(--accent-6);
+  box-shadow: inset 0 0 0 1px var(--accent-6);
+  color: var(--accent-a11);
 
   /* Theme-level translucent override */
-  :where([data-panel-background='translucent']) & {
-    background-color: var(--accent-a2);
-    box-shadow: inset 0 0 0 var(--border-width-standard) var(--accent-a6);
-    backdrop-filter: var(--backdrop-filter-panel);
+  :where([data-panel-background='translucent'], [data-material='translucent']) & {
+    background-color: color-mix(in srgb, var(--accent-a2), var(--accent-2) 60%);
+    box-shadow: inset 0 0 0 1px var(--accent-a6);
   }
 
   /* Component-level overrides (higher specificity) */
-  &:where([data-panel-background='solid']) {
+  &:where([data-panel-background='solid'], [data-material='solid']) {
     background-color: var(--accent-2);
-    box-shadow: inset 0 0 0 var(--border-width-standard) var(--accent-6);
-    backdrop-filter: none;
-    --backdrop-filter-panel: none;
+    box-shadow: inset 0 0 0 1px var(--accent-6);
   }
 
-  &:where([data-panel-background='translucent']) {
-    background-color: var(--accent-a2);
-    box-shadow: inset 0 0 0 var(--border-width-standard) var(--accent-a6);
-    backdrop-filter: var(--backdrop-filter-panel);
-    --backdrop-filter-panel: blur(var(--backdrop-blur-panel));
+  &:where([data-panel-background='translucent'], [data-material='translucent']) {
+    background-color: color-mix(in srgb, var(--accent-a2), var(--accent-2) 60%);
+    box-shadow: inset 0 0 0 1px var(--accent-a6);
+  }
+
+  &:where(.rt-high-contrast) {
+    color: var(--accent-12);
   }
 }
 
@@ -132,19 +168,70 @@
 
 .rt-CalloutRoot:where(.rt-variant-outline) {
   /* Base state: solid colors for solid panels */
-  box-shadow: inset 0 0 0 var(--border-width-standard) var(--accent-7);
+  box-shadow: inset 0 0 0 1px var(--accent-6);
+  color: var(--accent-11);
 
   /* Theme-level translucent override */
-  :where([data-panel-background='translucent']) & {
-    box-shadow: inset 0 0 0 var(--border-width-standard) var(--accent-a7);
+  :where([data-panel-background='translucent'], [data-material='translucent']) & {
+    box-shadow: inset 0 0 0 1px var(--accent-a6);
+    color: var(--accent-a11);
   }
 
   /* Component-level overrides (higher specificity) */
-  &:where([data-panel-background='solid']) {
-    box-shadow: inset 0 0 0 var(--border-width-standard) var(--accent-7);
+  &:where([data-panel-background='solid'], [data-material='solid']) {
+    box-shadow: inset 0 0 0 1px var(--accent-6);
+    color: var(--accent-11);
   }
 
-  &:where([data-panel-background='translucent']) {
-    box-shadow: inset 0 0 0 var(--border-width-standard) var(--accent-a7);
+  &:where([data-panel-background='translucent'], [data-material='translucent']) {
+    box-shadow: inset 0 0 0 1px var(--accent-a6);
+    color: var(--accent-a11);
+  }
+
+  &:where(.rt-high-contrast) {
+    color: var(--accent-12);
   }
 }
+
+/* classic */
+
+.rt-CalloutRoot:where(.rt-variant-classic) {
+  /* Base state: solid surface for solid panels */
+  background-color: var(--color-surface-solid);
+  box-shadow: var(--shadow-2);
+  color: var(--accent-a11);
+  transition: var(--transition-text-field);
+
+  /* Theme-level translucent override */
+  :where([data-panel-background='translucent'], [data-material='translucent']) & {
+    background-color: var(--color-surface-translucent);
+  }
+
+  /* Component-level overrides (higher specificity) */
+  &:where([data-panel-background='solid'], [data-material='solid']) {
+    background-color: var(--color-surface-solid);
+  }
+
+  &:where([data-panel-background='translucent'], [data-material='translucent']) {
+    background-color: var(--color-surface-translucent);
+  }
+
+  &:where(.rt-high-contrast) {
+    color: var(--accent-12);
+    background-color: var(--color-surface-solid);
+
+    /* Theme-level translucent override for high contrast */
+    :where([data-panel-background='translucent'], [data-material='translucent']) & {
+      background-color: var(--color-surface-translucent);
+    }
+
+    /* Component-level overrides for high contrast */
+    &:where([data-panel-background='solid'], [data-material='solid']) {
+      background-color: var(--color-surface-solid);
+    }
+
+    &:where([data-panel-background='translucent'], [data-material='translucent']) {
+      background-color: var(--color-surface-translucent);
+    }
+  }
+}

package/src/components/callout.props.tsx

@@ -5,8 +5,9 @@ import { highContrastPropDef } from '../props/high-contrast.prop.js';
 import type { PropDef } from '../props/prop-def.js';
 
 const sizes = ['1', '2', '3'] as const;
-const variants = ['soft', 'surface', 'outline'] as const;
+const variants = ['soft', 'surface', 'outline', 'classic'] as const;
 const panelBackgrounds = ['solid', 'translucent'] as const;
+const materials = ['solid', 'translucent'] as const;
 
 const calloutRootPropDefs = {
   ...asChildPropDef,
@@ -14,10 +15,15 @@ const calloutRootPropDefs = {
   variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'soft' },
   ...accentColorPropDef,
   ...highContrastPropDef,
+  material: { type: 'enum', values: materials, default: undefined },
+  /**
+   * @deprecated Use `material` prop instead. This prop will be removed in a future version.
+   */
   panelBackground: { type: 'enum', values: panelBackgrounds, default: undefined },
 } satisfies {
   size: PropDef<(typeof sizes)[number]>;
   variant: PropDef<(typeof variants)[number]>;
+  material: PropDef<(typeof materials)[number] | undefined>;
   panelBackground: PropDef<(typeof panelBackgrounds)[number] | undefined>;
 };
 

package/src/components/callout.tsx

@@ -20,32 +20,55 @@ import type { GetPropDefTypes } from '../props/prop-def.js';
 
 type CalloutRootOwnProps = GetPropDefTypes<typeof calloutRootPropDefs>;
 
-type CalloutContextValue = { size?: CalloutRootOwnProps['size'] };
+type CalloutContextValue = {
+  size?: CalloutRootOwnProps['size'];
+  variant?: CalloutRootOwnProps['variant'];
+  color?: CalloutRootOwnProps['color'];
+};
 const CalloutContext = React.createContext<CalloutContextValue>({});
 
 type CalloutRootElement = React.ElementRef<'div'>;
 interface CalloutRootProps
   extends ComponentPropsWithout<'div', RemovedProps>,
     MarginProps,
-    CalloutRootOwnProps {}
+    CalloutRootOwnProps {
+  /** Controls the ARIA live region behavior for screen readers */
+  live?: 'off' | 'polite' | 'assertive';
+  /** Semantic role for the callout */
+  role?: 'alert' | 'status' | 'note';
+}
 const CalloutRoot = React.forwardRef<CalloutRootElement, CalloutRootProps>(
   (props, forwardedRef) => {
-    const { size = calloutRootPropDefs.size.default } = props;
-    const { asChild, children, className, color, panelBackground, ...rootProps } = extractProps(
-      props,
-      calloutRootPropDefs,
-      marginPropDefs,
-    );
+    const {
+      size = calloutRootPropDefs.size.default,
+      live = 'polite',
+      role = 'status',
+      variant,
+    } = props;
+    const { asChild, children, className, color, panelBackground, material, ...rootProps } =
+      extractProps(props, calloutRootPropDefs, marginPropDefs);
     const Comp = asChild ? Slot.Root : 'div';
+
+    // Determine appropriate ARIA attributes based on role and live
+    const ariaProps = {
+      role,
+      'aria-live': live,
+      'aria-atomic': true,
+    };
+
     return (
       <Comp
         data-accent-color={color}
         data-panel-background={panelBackground}
+        data-material={material}
         {...rootProps}
+        {...ariaProps}
         className={classNames('rt-CalloutRoot', className)}
         ref={forwardedRef}
       >
-        <CalloutContext.Provider value={React.useMemo(() => ({ size }), [size])}>
+        <CalloutContext.Provider
+          value={React.useMemo(() => ({ size, variant, color }), [size, variant, color])}
+        >
           {children}
         </CalloutContext.Provider>
       </Comp>