npm package: @pamfilico/issuebeam-material
Description: Material UI components for IssueBeam feedback widget integration
Author: pamfilico
Latest version: 0.1.5

# @pamfilico/issuebeam-material

Material UI components for integrating the IssueBeam feedback widget into React applications.

## Installation

```bash
npm install @pamfilico/issuebeam-material
# or
yarn add @pamfilico/issuebeam-material
# or
pnpm add @pamfilico/issuebeam-material
```

### Peer Dependencies

This package requires the following peer dependencies:

- React (16.8.0 or higher)
- Material UI v5 or v6
- @emotion/react
- @emotion/styled

## Usage

### Basic Usage

```tsx
import { FeedbackButton } from '@pamfilico/issuebeam-material';

function App() {
  return (
    <div>
      <h1>My Application</h1>
      <FeedbackButton appId="YOUR_APP_ID" />
    </div>
  );
}
```

### Custom Position and Styling

```tsx
import { FeedbackButton } from '@pamfilico/issuebeam-material';

function App() {
  return (
    <FeedbackButton 
      appId="YOUR_APP_ID"
      position="bottom-left"
      primaryColor="#4CAF50"
      userEmail="user@example.com"
      apiUrl="https://api.yourdomain.com"
    />
  );
}
```

### Embedded in Container (Parent Positioning)

Perfect for integrating the feedback button into navigation bars or specific UI areas:

```tsx
import { useRef } from 'react';
import { FeedbackButton } from '@pamfilico/issuebeam-material';
import { Box, BottomNavigation, BottomNavigationAction } from '@mui/material';
import { Home, Settings, Person } from '@mui/icons-material';

function NavigationWithFeedback() {
  const feedbackContainerRef = useRef<HTMLDivElement>(null);
  
  return (
    <Box sx={{ position: 'fixed', bottom: 0, left: 0, right: 0 }}>
      <Box sx={{ display: 'flex', alignItems: 'center' }}>
        <BottomNavigation sx={{ flex: 1 }}>
          <BottomNavigationAction label="Home" icon={<Home />} />
          <BottomNavigationAction label="Settings" icon={<Settings />} />
          <BottomNavigationAction label="Profile" icon={<Person />} />
        </BottomNavigation>
        
        {/* Feedback button container */}
        <Box
          ref={feedbackContainerRef}
          id="feedback-nav-container"
          sx={{
            position: "relative",
            width: 80,
            height: 56,
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            borderLeft: '1px solid',
            borderColor: 'divider',
          }}
        >
          <FeedbackButton
            appId="YOUR_APP_ID"
            position="parent"
            containerRef={feedbackContainerRef}
            primaryColor="#667eea"
          />
        </Box>
      </Box>
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `appId` | `string` | **Required** | Your IssueBeam application ID |
| `position` | `string` | `"bottom-right"` | Button position: `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`, `"left-middle"`, `"right-middle"`, `"parent"` |
| `primaryColor` | `string` | `"#667eea"` | Primary color for the feedback button |
| `apiUrl` | `string` | `"https://api.issuebeam.com"` | API endpoint URL |
| `userEmail` | `string` | `""` | User's email for identification |
| `domain` | `string` | Current hostname | Domain name for tracking |
| `containerRef` | `React.RefObject<HTMLElement>` | `undefined` | Reference to container element (required for `position="parent"`) |
| `demoMode` | `boolean` | `false` | Enable demo mode (prevents API calls) |
| `scriptSrc` | `string` | `"https://issuebeam.com/js/feedback.js"` | URL to the feedback widget script |

## Position Options

### Fixed Positions
- **`bottom-right`**: Default position, fixed at bottom-right corner
- **`bottom-left`**: Fixed at bottom-left corner
- **`top-right`**: Fixed at top-right corner
- **`top-left`**: Fixed at top-left corner
- **`left-middle`**: Fixed at left side, vertically centered
- **`right-middle`**: Fixed at right side, vertically centered

### Parent Position
- **`parent`**: Renders inside a container element. Requires `containerRef` prop.

## TypeScript Support

This package includes TypeScript definitions. The main types are:

```typescript
interface FeedbackButtonProps {
  appId: string;
  userEmail?: string;
  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left" | "left-middle" | "right-middle" | "parent";
  apiUrl?: string;
  primaryColor?: string;
  domain?: string;
  containerRef?: React.RefObject<HTMLElement>;
  demoMode?: boolean;
  scriptSrc?: string;
}
```

## Material UI Integration

This component is designed to work seamlessly with Material UI applications. It:
- Follows Material Design principles
- Works with Material UI themes
- Can be embedded in Material UI components
- Supports all Material UI breakpoints

## Demo Mode

Enable demo mode for testing without making actual API calls:

```tsx
<FeedbackButton
  appId="demo-app"
  demoMode={true}
/>
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

## License

MIT

## Links

- [IssueBeam Documentation](https://docs.issuebeam.com)
- [GitHub Repository](https://github.com/pamfilico/issuebeam)
- [NPM Package](https://www.npmjs.com/package/@pamfilico/issuebeam-material)
- [Issue Tracker](https://github.com/pamfilico/issuebeam/issues)