open-likes/README.md

Open source web component for reactions with Supabase backend

# Open Likes

> A modern web component for content reactions. Perfect for blogs, articles, and any content that deserves some love! 💖

[![npm version](https://img.shields.io/npm/v/open-likes.svg)](https://www.npmjs.com/package/open-likes)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/open-likes)](https://bundlephobia.com/package/open-likes)
[![License](https://img.shields.io/npm/l/open-likes.svg)](LICENSE)

## ✨ Features

- 🎯 **Zero dependencies** - Self-contained web component
- 🎨 **Highly customizable** - Icons, colors, positioning, and behavior
- ⚡ **Lightweight** - Only 8.4kB gzipped
- 📱 **Mobile-first** - Works perfectly on touch devices
- 🔥 **Multitap support** - Applause with debounced submissions
- 💾 **Smart persistence** - Prevents duplicate reactions in single-tap mode
- 🎭 **Beautiful animations** - Particle effects and smooth transitions
- 🗄️ **Supabase ready** - Easy backend integration
- 🧪 **Well tested** - 97+ unit tests with 100% core coverage

## 🚀 Quick Start

### CDN (Recommended)

```html
<script>
  // Configure your Supabase connection
  window.OPEN_LIKES_SUPABASE_URL = 'https://your-project.supabase.co';
  window.OPEN_LIKES_SUPABASE_ANON_KEY = 'your-anon-key';
</script>

<script
  type="module"
  src="https://unpkg.com/open-likes@1.0.0/dist/open-likes.js"
></script>

<open-likes id="my-article"></open-likes>
```

## 📖 Usage

### Basic Usage

```html
<!-- Simple heart button -->
<open-likes id="article-1"></open-likes>

<!-- Custom icon and color -->
<open-likes id="article-2" icon="star" color="#ffd93d"></open-likes>

<!-- Single-tap mode with custom positioning -->
<open-likes
  id="article-3"
  icon="thumbs"
  counter="top"
  multitap="false"
></open-likes>
```

### Configuration

Set up your Supabase connection:

```javascript
window.OPEN_LIKES_SUPABASE_URL = 'https://your-project.supabase.co';
window.OPEN_LIKES_SUPABASE_ANON_KEY = 'your-anon-key';

// Optional: Set defaults for all components
window.OPEN_LIKES_DEFAULTS = {
  icon: 'heart',
  color: '#ff6b6b',
  counter: 'right',
  multitap: true,
};
```

### Attributes

| Attribute  | Type                                               | Default                | Description                       |
| ---------- | -------------------------------------------------- | ---------------------- | --------------------------------- |
| `id`       | `string`                                           | `window.location.href` | Unique identifier for the content |
| `icon`     | `heart` \| `thumbs` \| `star`                      | `heart`                | Icon style                        |
| `color`    | `string`                                           | `currentColor`         | Color theme                       |
| `counter`  | `left` \| `right` \| `top` \| `bottom` \| `hidden` | `right`                | Counter position                  |
| `multitap` | `boolean`                                          | `true`                 | Enable multiple reactions         |

## 🎨 Customization Examples

### Icons and Colors

```html
<!-- Different icons -->
<open-likes icon="heart" color="#e91e63"></open-likes>
<open-likes icon="thumbs" color="#2196f3"></open-likes>
<open-likes icon="star" color="#ff9800"></open-likes>
```

### Counter Positions

```html
<!-- Counter positioning -->
<open-likes counter="top"></open-likes>
<open-likes counter="left"></open-likes>
<open-likes counter="bottom"></open-likes>
<open-likes counter="hidden"></open-likes>
```

## 🗄️ Backend Setup (Supabase)

Supabase is recommended for most scenarios because their free tier is quite generous and includes standard PostgreSQL syntax. This means your database schema and queries can be easily moved to another PostgreSQL service or even completely replaced with a different backend implementation if needed.

> **Quick Setup**: All SQL files are included in this repository under `/sql/` directory. Run them in order: `01-create-table.sql`, `02-security-policies.sql`, `03-functions.sql`.

### 1. Create Database Table

```sql
-- Create the likes table
CREATE TABLE likes (
  id TEXT PRIMARY KEY,
  likes INTEGER NOT NULL DEFAULT 0,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Security: Block direct table access
ALTER TABLE likes ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Block all direct access" ON likes FOR ALL USING (false);
```

### 2. Create API Functions

```sql
-- Function to get likes count
CREATE OR REPLACE FUNCTION get_likes(content_id TEXT)
RETURNS INTEGER
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  like_count INTEGER;
BEGIN
  SELECT likes INTO like_count FROM likes WHERE id = content_id;
  RETURN COALESCE(like_count, 0);
END;
$$;

-- Function to increment likes
CREATE OR REPLACE FUNCTION increment_likes(content_id TEXT, increment_by INTEGER DEFAULT 1)
RETURNS INTEGER
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  final_count INTEGER;
BEGIN
  -- Limit increment to prevent abuse
  increment_by := LEAST(increment_by, 100);

  INSERT INTO likes (id, likes)
  VALUES (content_id, increment_by)
  ON CONFLICT (id)
  DO UPDATE SET
    likes = likes.likes + increment_by,
    updated_at = NOW()
  RETURNING likes INTO final_count;

  RETURN final_count;
END;
$$;
```

### 3. Configure Permissions

In your Supabase dashboard, ensure anonymous users can execute these functions but cannot access the table directly.

## 🎭 Advanced Features

### Multitap Behavior

```html
<!-- Medium-style applause: users can tap multiple times -->
<open-likes multitap="true"></open-likes>
```

- **Debounced submissions**: Collects taps for 300ms before sending to server
- **Optimistic updates**: UI responds immediately
- **Server reconciliation**: Updates display with authoritative count after 3 seconds
- **Visual feedback**: Particle animations and persistent filled state

### Single-tap Mode

```html
<!-- Traditional like button: one reaction per user -->
<open-likes multitap="false"></open-likes>
```

- **localStorage persistence**: Remembers user reactions
- **Duplicate prevention**: Blocks multiple reactions per content ID
- **Visual state**: Icon stays filled after interaction

### Particle Animations

Every tap triggers a beautiful burst of particles that emanate from the icon center, providing satisfying visual feedback.

## 🧪 Development

### Local Development

```bash
git clone https://codeberg.org/asci/open-likes
cd open-likes
bun install
bun run dev
```

### Testing

```bash
# Unit tests
bun run test

# Integration tests
bun run test:integration

# Build for production
bun run build
```

### Project Structure

```
src/
├── component.ts     # Main web component
├── state.ts        # Business logic & state management
├── renderer.ts     # DOM rendering & UI updates
├── animation.ts    # Particle effects & animations
├── api.ts          # Supabase API client
├── storage.ts      # localStorage wrapper
├── utils.ts        # Utility functions
├── types.ts        # TypeScript interfaces
├── styles.ts       # CSS styles (inlined)
└── icons.ts        # SVG icons (inlined)
```

## 🤝 Contributing

We love contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch: `git checkout -b amazing-feature`
3. Make your changes and add tests
4. Run tests: `bun run test`
5. Submit a pull request

## 📄 License

MIT © [Artem R](https://codeberg.org/asci)

## 🙏 Acknowledgments

- Built with modern web standards
- Powered by [Supabase](https://supabase.com)

---

**Made with ❤️ for the web community**

\_Have a question or need help? [Open an issue](https://codeberg.org/asci/open-likes/issues)