npm package: @madajoe6969/microfeedback-react
Description: React widget component for MicroFeedback with unified styling
Author: MicroFeedback
Latest version: 1.0.0

# MicroFeedback React Widget

A fully customizable React feedback widget component with unified styling, responsive design, and interactive features.

## Features

### ✅ Task 5.1: React Component with Styled-Components
- **MicroFeedbackWidget**: Main React component using styled-components
- **UnifiedStyleRenderer Integration**: Consistent styling across all widget implementations
- **TypeScript Definitions**: Complete type safety for all style-related props and interfaces
- **Theme Provider**: Centralized theme management with styled-components integration

### ✅ Task 5.2: React-Specific Style Handling
- **Theme Provider Integration**: `MicroFeedbackThemeProvider` for consistent styling
- **Prop-Based Style Overrides**: Easy customization through component props
- **Advanced Style Configuration**: Enhanced hooks for loading and caching style configurations
- **Style Override System**: `WithStyleOverrides` component for dynamic style modifications

### ✅ Task 5.3: Responsive and Interactive Features
- **Responsive Behavior**: Automatic adaptation to mobile, tablet, and desktop viewports
- **Interactive States**: Hover, focus, and press states matching dashboard preview
- **Memory Management**: Proper cleanup and resource management
- **Accessibility**: Full WCAG 2.1 AA compliance with focus-visible support
- **Performance Optimization**: Debounced updates and efficient re-rendering

## Installation

```bash
bun add @my-better-t-app/embed-react
```

## Basic Usage

```tsx
import { MicroFeedbackWidget } from '@my-better-t-app/embed-react';

function App() {
  return (
    <MicroFeedbackWidget
      widgetId="your-widget-id"
      apiKey="your-api-key"
      onSubmit={(feedback) => console.log('Feedback:', feedback)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
```

## Advanced Usage with Style Overrides

```tsx
import { MicroFeedbackWidget } from '@my-better-t-app/embed-react';

function CustomizedWidget() {
  return (
    <MicroFeedbackWidget
      widgetId="your-widget-id"
      apiKey="your-api-key"
      // Style overrides
      primaryColor="#6366f1"
      backgroundColor="#ffffff"
      textColor="#1f2937"
      borderRadius="12px"
      fontFamily="Inter, sans-serif"
      // Custom CSS
      customCSS={`
        .mf-container {
          box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
        }
      `}
      // Event handlers
      onSubmit={async (feedback) => {
        await submitToAPI(feedback);
      }}
      onError={(error) => {
        console.error('Widget error:', error);
      }}
      onOpen={() => console.log('Widget opened')}
      onClose={() => console.log('Widget closed')}
    />
  );
}
```

## Theme Provider Usage

```tsx
import { 
  MicroFeedbackThemeProvider, 
  MicroFeedbackWidget 
} from '@my-better-t-app/embed-react';

function ThemedApp() {
  const [styleConfig, setStyleConfig] = useState(defaultConfig);

  return (
    <MicroFeedbackThemeProvider 
      config={styleConfig}
      onConfigUpdate={setStyleConfig}
    >
      <MicroFeedbackWidget
        widgetId="your-widget-id"
        apiKey="your-api-key"
      />
    </MicroFeedbackThemeProvider>
  );
}
```

## Responsive Hooks

```tsx
import { useResponsive, useReducedMotion } from '@my-better-t-app/embed-react';

function ResponsiveComponent() {
  const { currentBreakpoint, isMobile, isTablet, isDesktop } = useResponsive();
  const reducedMotion = useReducedMotion();

  return (
    <div>
      <p>Current breakpoint: {currentBreakpoint}</p>
      <p>Reduced motion: {reducedMotion ? 'Yes' : 'No'}</p>
    </div>
  );
}
```

## Interactive State Management

```tsx
import { useInteractiveStates, useFocusVisible } from '@my-better-t-app/embed-react';

function InteractiveButton() {
  const interactive = useInteractiveStates({
    onHover: (isHovered) => console.log('Hovered:', isHovered),
    onFocus: (isFocused) => console.log('Focused:', isFocused),
  });
  
  const focusVisible = useFocusVisible();

  return (
    <button
      {...interactive.handlers}
      {...focusVisible.focusVisibleProps}
      style={{
        opacity: interactive.isHovered ? 0.8 : 1,
        outline: focusVisible.isFocusVisible ? '2px solid blue' : 'none',
      }}
    >
      Interactive Button
    </button>
  );
}
```

## Performance Monitoring

```tsx
import { usePerformanceMonitor } from '@my-better-t-app/embed-react';

function MonitoredComponent() {
  const { startTiming, getMetrics } = usePerformanceMonitor('MyComponent');

  const handleExpensiveOperation = () => {
    const endTiming = startTiming('expensive-operation');
    
    // Perform expensive operation
    doExpensiveWork();
    
    endTiming();
  };

  return (
    <div>
      <button onClick={handleExpensiveOperation}>
        Expensive Operation
      </button>
      <pre>{JSON.stringify(getMetrics(), null, 2)}</pre>
    </div>
  );
}
```

## API Reference

### Components
- `MicroFeedbackWidget` - Main widget component
- `MicroFeedbackThemeProvider` - Theme provider for style management
- `WithStyleOverrides` - HOC for style overrides
- `ResponsiveExample` - Example component demonstrating features

### Hooks
- `useStyleConfig` - Load and manage widget style configuration
- `useAdvancedStyleConfig` - Advanced style configuration with caching and polling
- `useWidgetState` - Manage widget state (open/closed, feedback, etc.)
- `useResponsive` - Responsive breakpoint detection
- `useReducedMotion` - Detect user's motion preferences
- `useInteractiveStates` - Manage hover, focus, and press states
- `useFocusVisible` - Keyboard navigation focus detection
- `useCleanupManager` - Automatic resource cleanup
- `usePerformanceMonitor` - Performance monitoring and metrics

### Utilities
- `createStyleOverridesFromProps` - Convert props to style overrides
- `debounce` - Debounce function calls
- `throttle` - Throttle function calls
- `PerformanceMonitor` - Performance monitoring class
- `StyleResourceManager` - Style resource cleanup

## Requirements Fulfilled

This implementation fulfills all requirements from the widget style sync rebuild specification:

- **Requirement 3.1**: React component accepts style configuration and renders with UnifiedStyleRenderer
- **Requirement 3.2**: Styled-components integration with theme from style renderer
- **Requirement 3.3**: TypeScript definitions for all style-related props and interfaces
- **Requirement 3.4**: Theme provider integration for consistent styling
- **Requirement 3.5**: Prop-based style overrides while maintaining base configuration
- **Requirement 8.3**: Responsive behavior using styled-components media queries
- **Requirement 8.4**: Hover, focus, and disabled states matching dashboard preview
- **Requirement 9.3**: Proper cleanup and memory management for style resources

## Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## License

MIT