Ayo b535b23fcc chore: restructure to cozy-games monorepo

2026-07-03 15:51:02 +02:00

8.7 KiB

Raw Blame History

Leaderboard configuration reference

Complete reference for configuring @cozy-games/leaderboard. There are two ways to use it — a JS API and a web component — and they share the same option set. The element simply forwards options to the service under the hood.

Options at a glance
JS API — LeaderBoardService
Web component — <cozy-leaderboard>
Adapters (backend config)
Localization (i18n)
Score entry shape
Where config is read / precedence

Options at a glance

option	type	default	purpose
`adapter`	object	— (required)	storage backend — a `FirebaseAdapter`, `SupabaseAdapter`, or your own
`scoreOrder`	`'asc'` \| `'desc'`	`'asc'`	`asc` = lower is better (time); `desc` = higher is better (points)
`formatScore`	`(value) => string`	`String(value)`	how a score is displayed
`qualifies`	`(entry) => boolean`	server `passingStatus` vs `entry.status`	whether a submitted entry is ranked
`labels`	object	`{today,week,month,all}` English	tab labels, keyed by `today`/`week`/`month`/`all`
`tooltips`	object	`Last 24 hours` / `Last 7 days` / `Last 30 days` / `All time`	tab hover text, keyed by `today`/`week`/`month`/`all`
`emptyMessages`	`string[]`	built-in pool	messages for an empty window (one picked at random)
`loadingText`	string	`Loading…`	shown while a window loads
`errorText`	string	`Leaderboard unavailable right now.`	shown when a window fails to load
`anonymousName`	string	`Anonymous`	fallback display name for entries without one

Every user-facing string (labels, emptyMessages, loadingText, errorText, anonymousName) is an option — see Localization.

JS API — `LeaderBoardService`

import { LeaderBoardService } from '@cozy-games/leaderboard/leader-board.js'
import { FirebaseAdapter } from '@cozy-games/leaderboard/adapters/firebase.js'

const service = new LeaderBoardService({
  adapter: new FirebaseAdapter({ firebaseConfig, namespace: 'mw' }),
  scoreOrder: 'asc',
  formatScore: ms => prettyTime(ms)
})

Methods

render(category, title, duration?) → Promise<HTMLElement> Builds the board (duration tabs + list) for category with heading title. duration is one of today (default) · week · month · all. When omitted on a re-render, the last-selected tab is kept. Append the returned element to the page.

Windows are rolling and strictly nested: today = last 24h, week = last 7 days, month = last 30 days, all = everything — each shows the top scores whose time_stamp falls in the window. Each tab's hover text (tooltips) spells this out.
submit(entry) → Promise Records a finished game (archives it; ranks it if it qualifies). See Score entry shape.

Web component — `<cozy-leaderboard>`

Configure the backend once in JS, then compose the UI in HTML.

<script type="module">
  import { configureLeaderboard } from '@cozy-games/leaderboard/leaderboard-element.js'
  import { FirebaseAdapter } from '@cozy-games/leaderboard/adapters/firebase.js'

  configureLeaderboard({
    adapter: new FirebaseAdapter({ firebaseConfig, namespace: 'mw' }),
    scoreOrder: 'asc',
    format: 'time'
  })
</script>

<cozy-leaderboard category="beginner" title="Best Times" format="time"></cozy-leaderboard>

`configureLeaderboard(options)`

Sets shared defaults for every <cozy-leaderboard> on the page. Accepts all the options above, plus format (a preset shorthand for formatScore — see below). Call it once at startup. Calling it again re-renders mounted elements.

Attributes

attribute	values	purpose
`category`	string	which board to show (e.g. a difficulty/level id)
`title`	string	heading text above the tabs
`duration`	`today` \| `week` \| `month` \| `all`	initial tab (default `today`)
`score-order`	`asc` \| `desc`	overrides the shared `scoreOrder`
`format`	`time` \| `number` \| `plain`	score display preset (below)

Attributes are reactive: change category/title at runtime and the board re-renders, keeping the selected duration tab.

`format` presets

`format`	result
`time`	milliseconds → `mm:ss.t` (e.g. `01:34.6`)
`number` / `plain` / unset	`String(value)`

For anything else, set a formatScore function (via configureLeaderboard or the per-element property).

Override properties & method

Set these JS properties on an element to override the shared config for that one element (useful for multi-board or multi-backend pages):

adapter, formatScore, qualifies, labels, emptyMessages, loadingText, errorText, anonymousName.

const el = document.querySelector('cozy-leaderboard')
el.emptyMessages = ['¡Sé el primero!']
el.formatScore = pts => `${pts} pts`

submit(entry) — submit a finished game through this element's service:

el.submit({ name: 'Ayo', playerId: 'abc', score: 4200, category: 'beginner', time_stamp: new Date(), status: 'win' })

Adapters (backend config)

`FirebaseAdapter`

import { FirebaseAdapter } from '@cozy-games/leaderboard/adapters/firebase.js'
new FirebaseAdapter({ firebaseConfig, namespace: 'mw', emulator })

option	type	default	purpose
`firebaseConfig`	object	—	Firebase web config (public; access governed by rules)
`namespace`	string	`lb`	collection prefix → `{ns}-scores`, `{ns}-all`, `{ns}-config`
`emulator`	`{ host?, port? }`	—	point at a local Firestore emulator (dev only); host `127.0.0.1`, port `8080`

Needs the firebase peer dependency. Rolling-window and all-time queries use Firestore's automatic single-field indexes — no composite indexes to deploy.

`SupabaseAdapter`

import { createClient } from '@supabase/supabase-js'
import { SupabaseAdapter } from '@cozy-games/leaderboard/adapters/supabase.js'
new SupabaseAdapter({ client: createClient(url, anonKey), namespace: 'mw' })

option	type	default	purpose
`client`	supabase-js client	—	you construct it (package takes no supabase dep)
`namespace`	string	`lb`	table prefix → `{ns}_scores`, `{ns}_archive`, `{ns}_config`

See the README for the SQL schema.

Localization (i18n)

This package ships English defaults only — localization is your app's job. Pass translated copy for every user-facing string:

configureLeaderboard({
  adapter,
  labels: { today: 'Hoy', week: 'Semana', month: 'Mes', all: 'Histórico' },
  emptyMessages: [
    '¡Sé el primero en el marcador!',
    'Aún no hay puntajes. ¡Reclama la cima!'
  ],
  loadingText: 'Cargando…',
  errorText: 'Marcador no disponible ahora.',
  anonymousName: 'Anónimo'
})

The same keys work when constructing LeaderBoardService directly. To switch languages at runtime, call configureLeaderboard() again with the new strings (mounted elements re-render).

Score entry shape

The object passed to submit(entry):

{
  name,        // string — display name (falls back to `anonymousName`)
  playerId,    // string — opaque id (e.g. a browser fingerprint)
  score,       // number — the ranked value (minesweeper: finish time in ms)
  category,    // string — which board (minesweeper: level id)
  time_stamp,  // Date — when the game finished (used to compute day/week/month)
  status,      // string, optional — read by the default `qualifies`
  meta         // object, optional — extra fields to store (e.g. { isMobile })
}

The package computes the day/week/month bucket keys from time_stamp (UTC) before storing — you don't set those.

Where config is read / precedence

JS API: options are read when you construct LeaderBoardService.
Web component: the element builds its service on first render (on connect), reading — in order — its own attribute/property, then the shared configureLeaderboard() value, then the package default:
```
per-element attribute/property  >  configureLeaderboard(...)  >  built-in default
```
The service is cached per element, so set overrides before the element connects (or set the property and clear the element's _svc to force a rebuild). score-order and format are read from attributes; the function/ array/string overrides are read from properties.

8.7 KiB Raw Blame History