@richpods/coloeus

Embeddable Vue 3 poll components for the Coloeus poll service.

Installation

npm install @richpods/coloeus

Quick Start

import { createApp } from 'vue'
import { configureColoeus, ColoeusPolls } from '@richpods/coloeus'
import '@richpods/coloeus/style.css'

// Configure the API endpoint
configureColoeus({
  apiUrl: 'https://your-api.example.com'
})

const app = createApp(App)
app.component('ColoeusPolls', ColoeusPolls)
app.mount('#app')

Configuration

Before using any components, configure the library with your API endpoint:

import { configureColoeus } from '@richpods/coloeus'

configureColoeus({
  apiUrl: 'https://your-api.example.com',
  // Optional: provide auth token for admin operations
  getAuthToken: async () => {
    return await yourAuthService.getToken()
  }
})

Config Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiUrl | string | Yes | Base URL of your Coloeus API | | getAuthToken | () => Promise<string \| null> | No | Async function returning a JWT for authenticated requests |

Components

ColoeusPolls

Displays a poll and allows users to vote.

<template>
  <ColoeusPolls
    id="your-poll-id"
    @voted="handleVoted"
    @error="handleError"
  />
</template>

<script setup>
import { ColoeusPolls } from '@richpods/coloeus'

function handleVoted(pollId, optionIndices) {
  console.log(`Voted on poll ${pollId}:`, optionIndices)
}

function handleError(error) {
  console.error('Vote error:', error)
}
</script>

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | id | string | Yes | The poll ID to display |

Events

| Event | Payload | Description | |-------|---------|-------------| | voted | (pollId: string, optionIndices: number[]) | Emitted after a successful vote | | error | (error: string) | Emitted when an error occurs |

ColoeusEditor

Create or edit polls. Requires authentication via getAuthToken.

<template>
  <ColoeusEditor
    :id="pollId"
    @saved="handleSaved"
    @cancel="handleCancel"
    @error="handleError"
  />
</template>

<script setup>
import { ColoeusEditor } from '@richpods/coloeus'

const pollId = undefined // omit for create mode, provide ID for edit mode

function handleSaved(poll) {
  console.log('Poll saved:', poll)
}

function handleCancel() {
  console.log('Edit cancelled')
}

function handleError(error) {
  console.error('Save error:', error)
}
</script>

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | id | string | No | Poll ID to edit. Omit to create a new poll |

Events

| Event | Payload | Description | |-------|---------|-------------| | saved | (poll: AdminPoll) | Emitted after successful save | | cancel | none | Emitted when cancel is clicked | | error | (error: string) | Emitted when an error occurs |

Composables

For advanced use cases, you can use the composables directly:

import { usePoll, useVote } from '@richpods/coloeus'

// Fetch and manage poll state
const { poll, loading, error, totalVotes, isActive } = usePoll('poll-id')

// Manage voting state
const { selectedOptions, submitVote, alreadyVoted } = useVote('poll-id')

Types

TypeScript types are included:

import type {
  PublicPoll,
  PollOption,
  VoteResponse,
  CreatePollInput,
  UpdatePollInput,
  AdminPoll,
  ColoeusConfig
} from '@richpods/coloeus'

Styling

Import the default styles:

import '@richpods/coloeus/style.css'

All components use BEM-style class names prefixed with coloeus- for easy customization:

• .coloeus-poll - Poll container
• .coloeus-poll__title - Poll title
• .coloeus-poll__options - Options list
• .coloeus-poll__option - Individual option
• .coloeus-poll__vote-btn - Vote button
• .coloeus-editor - Editor container
• .coloeus-editor__field - Form field
• .coloeus-editor__input - Input element

License

Blue Oak Model License 1.0.0