Profile Bubbles Web Component

A React-based web component for displaying user profile bubbles, built with multiple bundling options.

Installation

pnpm install @percy.ai/profile-bubbles

Build Options

This package supports multiple build tools to handle different use cases:

1. Vite (Default)

pnpm run build

Generates:

• dist/umd/profile-bubbles.js - UMD build with external React dependencies (optimized with Vite)

2. Rollup (Alternative)

pnpm run build:rollup

Generates:

• dist/umd/profile-bubbles.js - UMD build with external React dependencies
• dist/umd/profile-bubbles.standalone.js - Self-contained build with React included
• dist/umd/profileBubbles.min.js - Minified UMD build

3. Webpack (Alternative)

pnpm run build:webpack

Generates builds in dist/webpack/ directory.

4. Build All

pnpm run build:all

Runs all build configurations.

Usage

Method 1: With External React Dependencies (Recommended)

Load React from CDN first, then the web component:

<!-- Load React dependencies -->
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- Load the web component -->
<script src="./dist/umd/profile-bubbles.js"></script>

<!-- Use the component -->
<profile-bubbles 
    users='[{"name":"John Doe","avatar":"https://via.placeholder.com/40"}]'
    background-color="#ffffff"
    text-color="#333333">
</profile-bubbles>

Method 2: Standalone Bundle (Rollup only)

Use the standalone bundle that includes React:

<script src="./dist/umd/profile-bubbles.standalone.js"></script>

<profile-bubbles 
    users='[{"name":"Jane Smith","avatar":"https://via.placeholder.com/40"}]'
    background-color="#f0f0f0">
</profile-bubbles>

Troubleshooting

Error: "Cannot read properties of undefined (reading 'createRoot')"

Problem: ReactDOM is not available when the web component tries to mount.

Solutions:

1. Load React before the component: Ensure React and ReactDOM are loaded before your web component script
2. Use standalone build: Use profile-bubbles.standalone.js which includes React (Rollup build only)
3. Check React version: Ensure you're using React 18+ which includes createRoot

<!-- Correct order -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="./dist/umd/profile-bubbles.js"></script>

Error: "Cannot read properties of undefined (reading 'jsx')"

Problem: JSX runtime is not properly mapped.

Solutions:

1. Updated builds include JSX runtime mapping - Both Vite and Rollup configs now properly map JSX runtime
2. Use React 18+ - Newer React versions have better JSX runtime support
3. Check browser console - Use the debug script in example.html to verify React availability

Error: "ReferenceError: React is not defined"

Problem: React global variable is not available.

Solutions:

1. Load React from CDN:

   <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>

2. Use standalone build that bundles React (Rollup only)
3. Check network tab to ensure React scripts load successfully

Component Props

| Prop | Type | Description | |------|------|-------------| | users | string (JSON) | Array of user objects with name and avatar | | background-color | string | Background color for the component | | text-color | string | Text color for user names | | endpoint-url | string | API endpoint URL | | to-agent-id | number | Target agent ID | | to-team-id | number | Target team ID | | agent-branded-page | boolean | Show agent branding | | show-checkbox | boolean | Display checkbox controls | | agent-name | string | Agent name to display | | brokerage-name | string | Brokerage name | | agent-type | string | Type of agent | | working-with-agent | string | Agent working status |

Development

# Install dependencies
pnpm install

# Build with tsup (creates dist/profile-bubbles.js)
pnpm run dev

# Build CSS
tailwindcss -i ./src/styles/global.css -o ./dist/styles.css

# Build UMD with Vite (default)
pnpm run build:vite

# Build UMD with Rollup (alternative)
pnpm run build:rollup

# Serve example locally
pnpm run serve:example
# Then visit http://localhost:8080/example.html

Debug Scripts

The example.html file includes debug scripts to check:

• React availability
• ReactDOM.createRoot availability
• Web component registration

Open browser console to see debug output when loading the example.

Build Architecture

1. tsup compiles TypeScript to JavaScript
2. tailwindcss processes CSS styles
3. Vite (default) or rollup/webpack (alternatives) bundle for UMD distribution
4. Multiple output formats provide flexibility for different deployment scenarios

Vite Benefits (Default):

• Faster build times
• Better tree-shaking
• Modern optimization features
• Cleaner output

Browser Support

• Modern browsers with Web Components support
• React 18+ (for createRoot API)
• ES2017+ JavaScript features