@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 | | lang | string | No | Language code (e.g. "de", "de-AT"). Falls back to English if no match is found | | l10n | Partial<ColoeusLocale> | No | Custom string overrides, merged on top of the resolved language |

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 | | lang | string | No | Language code (e.g. "de", "de-AT"). Falls back to English if no match is found | | l10n | Partial<ColoeusLocale> | No | Custom string overrides, merged on top of the resolved language |

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')

Localization

Built-in locales: English (default) and German. Use the lang prop to select a language:

<ColoeusPolls id="abc" lang="de" />
<ColoeusEditor lang="de-AT" />

Regional codes like "de-AT" resolve to the base language "de" if no exact match exists. Unknown codes fall back to English.

Override individual strings with the l10n prop — omitted keys fall back to the resolved language:

<ColoeusPolls id="abc" lang="de" :l10n="{ pollVote: 'Jetzt abstimmen' }" />

Registering custom locales

import { registerLocale } from '@richpods/coloeus'
import type { ColoeusLocale } from '@richpods/coloeus'

const FR_LOCALE: ColoeusLocale = { /* all keys required */ }
registerLocale('fr', FR_LOCALE)

After registration, lang="fr" (or lang="fr-CA") will resolve to it.

Types

TypeScript types are included:

import type {
  PublicPoll,
  PollOption,
  VoteResponse,
  CreatePollInput,
  UpdatePollInput,
  AdminPoll,
  ColoeusConfig,
  ColoeusLocale
} 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