add support for multiple scoreboards (#2)

add support for multiple scoreboards

also improve the init() API to allow complete control over
info-message generation and ability to refresh/update custom scoreboard

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
   push:
     branches:
       - master
+      - main
 
 jobs:
   build:
@@ -13,7 +14,14 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: 16.x
-      - run: npm install
-      - run: npm run format:check
-      - run: npm test
+          node-version: 20.x
+      - run: npm install -g pnpm
+      - run: pnpm install
+      - run: pnpm check
+      - run: pnpm build
+      - run: |
+          cd example
+          pnpm install
+          pnpm link ..
+          pnpm check
+          pnpm build

.github/workflows/release.yml

@@ -14,11 +14,11 @@ jobs:
       - name: Setup node
         uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 20.x
 
+      - run: npm install -g pnpm
       - run: npm install
-      - run: npm run format:check
-      - run: npm test
+      - run: npm run check
       - run: npm run build
 
       - name: Release

.prettierignore

@@ -1,5 +1,2 @@
-dist/*js
-webxdc.js
-webxdc.d.ts
-pnpm-lock.yaml
-package-lock.json
+dist
+pnpm-lock.yaml

README.md

@@ -51,6 +51,4 @@ Include webxdc-scores lib (together with `webxdc.js`) in your `index.html`:
 
 Then you will have an scores API via `window.highscores` object, check `dist/webxdc-scores.d.ts` file for documentation of the available API.
 
-> **⚠️ NOTE:** If you pass the scoreboard parameter to `window.highscores.init()` you need to include `dist/webxdc-scores.css` in your `index.html`, edit it to adapt the scoreboard style to your app.
-
-For a full example check the `index.html` file included in this repository.
+For a full example check the `example/index.html` file included in this repository.

dist/webxdc-scores.d.ts

@@ -1,29 +1,43 @@
 //@ts-check
 
-type Player = {
-  /** the player's name */
+type Player<T> = {
+  /** The player's name */
   name: string;
-  /** the player's position in the scoreboard */
+  /** The player's position in the scoreboard */
   pos: string;
-  /** the player's high score */
-  score: number;
+  /** The player's high score */
+  score: T;
   /** true if this player is the current/self player, false otherwise. */
   current: boolean;
 };
 
-interface HighScores {
+type InitOptions<T> = {
+  /** Generator of new highscores messages.
+      If not provided, (name, score, board) => `${name} scored ${score}` is used
+  */
+  getAnnouncement?: (name: string, score: T, scoreboard?: string) => string;
+  /** A function that determines the order of the scores. It should return a number where:
+      - A negative value indicates that score1 < score2.
+      - A positive value indicates that score1 > score2.
+      - Zero indicates that score1 == score2.
+  */
+  compareScores?: (score1: T, score2: T, scoreboard?: string) => number;
+  /** callback that will be called when the high scores changed for a scoreboard */
+  onHighscoresChanged?: (scoreboard?: string) => void;
+};
+
+interface HighScores<T> {
   /**
-   * Initialize the scores API.
-   * @param appName the app's name that will be shown in info-messages.
-   * @param scoreboard the id of an HTML element where the scoreboard should be injected.
+   * Initialize the scores API. This MUST be called before start using the API.
    * @returns promise that resolves when the API is ready to be used.
    */
-  init(appName: string, scoreboard?: string): Promise<void>;
+  init(options?: InitOptions<T>): Promise<void>;
   /**
    * Use this method to get the high score of the current player.
+   * @param scoreboard if provided, get the score from this scoreboard. Otherwise the default scoreboard is used.
    * @returns the current player's high score.
    */
-  getScore(): number;
+  getScore(scoreboard?: string): T;
   /**
    * Use this method to set the high score of the current player.
    * The new score is ignored if it is not greater than the player's high score and
@@ -32,21 +46,29 @@ interface HighScores {
    * "PlayerName scored newScore in appName"
    * @param score the new high score.
    * @param force if the new score should override the old score even if it is smaller. False by default.
+   * @param scoreboard the scoreboard this score belongs to. Use it if your game can have more than one scoreboard.
    */
-  setScore(score: number, force?: boolean): void;
+  setScore(score: T, force?: boolean, scoreboard?: string): void;
   /**
-   * Use this method to get data for high score tables.
+   * Get the sorted list of high scores.
+   * @param scoreboard if provided, get scores from this scoreboard. Otherwise the default scoreboard is used.
    * @returns an array of Player objects.
    */
-  getHighScores(): Player[];
-  /** Returns the current player's own ID.
+  getHighScores(scoreboard?: string): Player<T>[];
+  /**
+   * Utility to generate a scoreboard in HTML. If you use this you need to include dist/webxdc-scores.css file or provide your own styling for the generated scoreboard.
+   * @param scoreboard if provided, this scoreboard is the one that will be rendered. Otherwise the default scoreboard is rendered.
+   * @returns a div HTMLElement with the scoreboard rows inside.
+   */
+  renderScoreboard(scoreboard?: string): HTMLElement;
+  /** The current player's own ID.
    */
   selfID: string;
 }
 
 declare global {
   interface Window {
-    highscores: HighScores;
+    highscores: HighScores<any>;
   }
 }