# Pollcatch

A collection of lightweight, customizable feedback Web Components built with Lit and TypeScript.

## Features

- Modular design with specialized components for different feedback types
- Lightweight and focused components that can be used individually or combined
- Supports multiple feedback types:
  - Star ratings
  - Reactions (emoji-based feedback, including thumbs up/down)
  - NPS (Net Promoter Score)
  - Poll questions
  - Text feedback
- Consistent API across all components
- Styling via CSS custom properties
- Accessible and responsive design

## Installation

```bash
pnpm install pollcatch
```

## Basic Usage

```html
<!-- Load from CDN -->
<script type="module" src="https://cdn.jsdelivr.net/npm/pollcatch@latest"></script>

<!-- Or import directly in your JavaScript module -->
<script type="module">
  import 'pollcatch';
</script>

<!-- Use the unified wrapper component (recommended) -->
<poll-catch type="stars" label="Rate our service" max="5"></poll-catch>
<poll-catch type="nps" label="How likely are you to recommend us?"></poll-catch>
<poll-catch type="poll" label="Favorite color?" options='["Red", "Blue", "Green"]'></poll-catch>
<poll-catch type="text" label="Feedback" placeholder="Tell us what you think..."></poll-catch>
<poll-catch type="reaction" label="How was your experience?" options='["👍", "👎"]'></poll-catch>

<!-- Or use the components individually -->
<pc-stars max-stars="5" label="How would you rate our service?"></pc-stars>
<pc-reaction options="👍,👎" label="Was this helpful?"></pc-reaction>
<pc-reaction icon="like" label="Like this article?"></pc-reaction>
```

## Available Components

### Stars Component (`<pc-stars>`)

A flexible star rating component with a sophisticated two-mode experience for collecting and displaying user feedback.

#### Basic Usage

```html
<pc-stars name="satisfaction" label="How satisfied are you?" show-stats></pc-stars>
<pc-stars name="service" label="Service quality" show-stats="always"show-chart></pc-stars>
<pc-stars name="detailed" label="Detailed rating (1-10)" num-stars="10" show-stats></pc-stars>
<pc-stars name="quick" label="Quick feedback"></pc-stars>
```

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `name` | `string` | Required | Unique identifier for the rating |
| `label` | `string` | `''` | Label text displayed above the stars |
| `num-stars` | `number` | `5` | Number of stars to display (1-10) |
| `show-stats` | `boolean` | `false` | Show stats text below stars |
| `show-chart` | `boolean` | `false` | Enable chart toggle button |
| `readonly` | `boolean` | `false` | Hide add/edit controls |
| `primary-color` | `string` | `''` | Custom primary color |
| `accent-color` | `string` | `''` | Custom star color |

### Reaction Component (`<pc-reaction>`)

An emoji-based reaction component for emotional feedback. Can be used for thumbs up/down, emoji reactions, custom feedback options, and also supports custom reaction icons.

```html
<pc-reaction label="Was this helpful?" options="👍,👎" </pc-reaction>
<pc-reaction label="React to this article" options="👍,❤️,😂,😮,😢,😡" compact multiple show-stats></pc-reaction>
```

**Custom Reaction Icons:**
You can define custom icons using the `<pc-reaction-icon>` element as children of `<pc-reaction>`. This allows you to use SVGs or custom images as reaction options.

```html
<pc-reaction label="How do you feel?"
  <pc-reaction-icon name="like" icon="👍" tooltip="Like"></pc-reaction-icon>
  <pc-reaction-icon name="love" icon="❤️" tooltip="Love"></pc-reaction-icon>
  <pc-reaction-icon name="star" icon="star-outline.svg" tooltip="Star"></pc-reaction-icon>
  <pc-reaction-icon name="custom" icon="/images/custom-icon.png" tooltip="Custom"></pc-reaction-icon>
</pc-reaction>
```

### NPS Component (`<pc-nps>`)

A Net Promoter Score component for collecting loyalty metrics.

```html
<pc-nps label="How likely are you to recommend us?"></pc-nps>
```

### Poll Component (`<pc-poll>`)

A component for single-choice poll questions.

```html
<pc-poll label="Would you use this feature again?" options='["Yes", "No", "Maybe"]' selected="Yes"></pc-poll>
```

### Text Component (`<pc-text>`)

A component for collecting free-form text feedback.

```html
<pc-text label="Additional comments" placeholder="Your thoughts?" maxlength="200"></pc-text>
```

## Common Attributes

All components inherit from the base widget and share these common attributes:

- `label`: The question or prompt text
- `label-position`: Position of the label (top, left, right, bottom)
- `label-align`: Alignment of the label
- `readonly`: Whether the field is readonly
- `tags`: Custom tags for analytics or data categorization
- `widget-type`: Type identifier for the widget (automatically set)
- `name`: Identifier for the component
- `project`: Project identifier for the component (optional, for registered users)

## Events

All components emit a `change` event when their value changes:

```javascript
document.querySelector('pc-stars').addEventListener('change', (e) => {
  console.log('New rating:', e.detail.value);
});
```

The event detail contains:

- `projectId`: The project identifier
- `widgetType`: The type of the widget
- `widgetName`: The name of the widget
- `sessionId`: The session identifier
- `timestamp`: The timestamp of the event
- `url`: The URL of the page
- `numericValue`: The numeric value of the widget
- `textValues`: The text values of the widget
- `tags`: Any custom tags assigned to the widget

## Customization

### CSS Custom Properties

You can customize the appearance using the following CSS variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `--pc-primary-color` | `#2196f3` | Primary accent color for components |
| `--pc-text-color` | `#333333` | Main text color |
| `--pc-mute-color` | `#cccccc` | Muted/disabled color |
| `--pc-accent-color` | `#f2b200` | Accent color for stars, icons, etc. |
| `--pc-accent-hover-color` | `#ffc61a` | Hover state for accent elements |
| `--pc-icon-size` | `clamp(1.1em, calc(1em + 0.4vw), 1.6em)` | Icon size |
| `--pc-control-spacing` | `clamp(0.4em, 0.6em, 0.8em)` | Spacing between controls |
| `--pc-button-radius` | `var(--pc-border-radius-md)` | Border radius for buttons |
| `--pc-border-radius-sm` | `2px` | Small border radius |
| `--pc-border-radius-md` | `4px` | Medium border radius |
| `--pc-border-radius-lg` | `8px` | Large border radius |
| `--pc-loading-width` | `clamp(1.4em, 1.8em, 2.2em)` | Width of loading indicator |
| `--pc-loading-height` | `clamp(0.6em, 0.7em, 0.8em)` | Height of loading indicator |
| `--pc-chart-max-width` | `clamp(200px, 100%, 300px)` | Max width for charts |
| `--pc-chart-min-width` | `clamp(150px, 12px, 200px)` | Min width for charts |
| `--pc-bar-height` | `clamp(0.5em, 0.6em, 0.8em)` | Height of bar charts |
| `--pc-font-size-small` | `clamp(0.6em, 0.7em, 0.8em)` | Small font size |
| `--pc-font-size-medium` | `clamp(0.8em, 0.9em, 1em)` | Medium font size |

These variables can be overridden globally or per-component to customize the look and feel of Pollcatch widgets.

### Custom CSS via Attribute

You can also use the `css` attribute on any Pollcatch component to inject custom CSS for internal elements. This allows for advanced customization beyond the available CSS variables.

**Example:**
```html
<pc-stars
  label="Custom Stars"
  css=".stars-section { background: #f9f9f9; } .pc-label { color: #e91e63; }"
></pc-stars>
```

## Accessibility

All components are designed with accessibility in mind:
- Proper ARIA attributes
- Keyboard navigation
- Screen reader announcements
- Sufficient color contrast

## Browser Support

Pollcatch components work in all modern browsers that support Web Components:
- Chrome
- Firefox
- Safari
- Edge

## Project Attribute

Registered users can organize their widgets and polls under a unique project by using the `project` attribute. Each project can contain one or more widgets, allowing for better data security, integrity, and access to advanced features.

**Benefits of using a project:**
- Enhanced data security and integrity
- Project-level reporting and analytics
- Webhook integrations for real-time notifications
- Website/domain whitelisting for data access control
- Longer data retention and advanced management options

**Example:**
```html
<pc-stars name="customer-satisfaction" label="How satisfied are you?" project="my-website-project"></pc-stars>
<pc-poll name="feature-vote" label="Vote for a feature" project="my-website-project"></pc-poll>
```

To use these features, register and create a project in your Pollcatch dashboard, then assign the `project` attribute to your widgets.

## How to Set the Project Attribute

There are several ways to specify the `project` for your widgets. Choose the approach that best fits your integration:

### 1. Set on Each Widget (Tag Level)
Assign the `project` attribute directly to each widget tag. This is the most explicit and flexible method.

```html
<pc-stars name="customer-satisfaction" label="How satisfied are you?" project="my-website-project"></pc-stars>
<pc-poll name="feature-vote" label="Vote for a feature" project="my-website-project"></pc-poll>
```

### 2. Set as a Global Variable
If all widgets on the page share the same project, you can set a global variable before loading the Pollcatch script:

```html
<script>
  window.pcProject = 'my-website-project';
</script>
<script type="module" src="https://cdn.jsdelivr.net/npm/pollcatch@latest"></script>
```

### 3. Set via Script Tag Attribute
Alternatively, add a `pc-project` attribute to the script tag that loads Pollcatch. All widgets on the page will use this project key by default:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/pollcatch@latest" pc-project="my-website-project"></script>
```

> **Note:** The order of precedence is: tag-level `project` attribute > global variable > script tag attribute. If a widget has its own `project` attribute, it will override the global or script tag setting.