pollcatch

# 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  <script type="module" src="https://cdn.jsdelivr.net/npm/pollcatch@latest"></script>  <script type="module"> import 'pollcatch'; </script>  <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>  <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.