docs: Add coloring guide (#120)

Author: Danielku15

.github/workflows/build-pr.yml

@@ -13,6 +13,7 @@ jobs:
         node-version: lts/*
     - run: npm install
     - run: npm install @coderline/alphatab@alpha
+    - run: npm run generate-alphatabdoc
     - run: npm run build
     - run: cp web.config ./build
     - uses: actions/upload-artifact@v4

.github/workflows/deploy-develop.yml

@@ -19,6 +19,7 @@ jobs:
         node-version: lts/*
     - run: npm install
     - run: npm install @coderline/alphatab@alpha
+    - run: npm run generate-alphatabdoc
     - run: npm run build
     - run: cp web.config ./build
     - name: Package Zip

.github/workflows/deploy-main.yml

@@ -19,6 +19,7 @@ jobs:
         node-version: lts/*
     - run: npm install
     - run: npm install @coderline/alphatab@latest
+    - run: npm run generate-alphatabdoc
     - run: npm run build
     - run: cp web.config ./build
     - name: Package Zip

.gitignore

@@ -18,3 +18,5 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+src/alphatabdoc/

docs/guides/breaking-changes-095-096.mdx

@@ -1,5 +1,6 @@
 ---
 title: Breaking changes on settings between 0.9.5 and 0.9.6 
+order: 100
 ---
 
 import { CodeBadge } from '@site/src/components/CodeBadge';

docs/guides/breaking-changes-097-098.mdx

@@ -1,5 +1,6 @@
 ---
 title: Breaking changes on settings between 0.9.7 and 0.9.8 
+order: 101
 ---
 
 import { CodeBadge } from '@site/src/components/CodeBadge';

docs/guides/coloring.mdx

@@ -0,0 +1,103 @@
+---
+title: Coloring Music Sheet
+since: 1.5.0
+---
+
+# Coloring Music Sheet
+
+import { SinceBadge } from '@site/src/components/SinceBadge';
+
+<SinceBadge since="1.5.0" />
+
+
+import * as alphaTab from '@coderline/alphatab';
+import { getDescriptionText } from '@site/src/alphatabdoc';
+
+export function EnumMemberList({ doc }) {
+    return (
+        <>
+            <code>{doc.name}</code>
+            <ul>
+                {doc.members.map(n => (<li key={n.name}><code>{n.name}</code> - {getDescriptionText(n.tsdoc)}</li>))}
+            </ul>
+        </>
+    )
+}
+
+alphaTab supports individual styling of music notation elements via a special `style` container which is available on
+most levels of the [Data Model](../reference/score.mdx). This means you can customize the colors of individual notes being rendered 
+base on custom logic. 
+
+The best place to apply custom coloring is the [`api.scoreLoaded`](../reference/api/scoreloaded.mdx) event which is triggered whenever
+a new score is detected. But you can modify the styles later at any time by accessing the [`score`](../reference/api/score.mdx) and then 
+initiating a re-render via [`render`](../reference/api/render.mdx). 
+
+:::important
+alphaTab does not detect dynamically any changes made to the data model. Rendering happens in a background worker, and calling `render` will ensure
+all updated information is passed to this renderer and the display is updated. Calling `render` will initiate a full re-layout and drawing of 
+the music sheet to apply any style changes accordingly, hence it is a quite performance intense operation. 
+:::
+
+The example codes in this Guide are in JavaScript but can be adapted to the other platforms accordingly.
+
+## Quick Start
+
+This code example here should give you a good first idea how you apply custom colors to elements. Depending on the elements you want to color,
+you have to traverse the tree of elements. Then on the `style` container you can fill the colors with the particular elements
+
+import { ColoringExample } from '@site/src/components/ColoringExample';
+
+<ColoringExample />
+
+## Styleable elements
+
+alphaTab tries to give fine grained access to coloring music notation elements. Only when it comes to individual effects and annotations things get more coarse. 
+
+### Score level
+
+On Score level initialize the `score.style = new alphaTab.model.ScoreStyle()` and then select the element to color via `alphaTab.model.ScoreSubElement`.
+
+import scoreSubElementDoc from '@site/src/alphatabdoc/model/ScoreSubElement';
+
+<EnumMemberList doc={scoreSubElementDoc} />
+
+### Track level
+
+On Track level initialize the `track.style = new alphaTab.model.TrackStyle()` and then select the element to color via `alphaTab.model.TrackSubElement`.
+
+import trackSubElementDoc from '@site/src/alphatabdoc/model/TrackSubElement';
+
+<EnumMemberList doc={trackSubElementDoc} />
+
+### Bar level
+
+On Bar level initialize the `bar.style = new alphaTab.model.BarStyle()` and then select the element to color via `alphaTab.model.BarSubElement`.
+
+import barSubElementDoc from '@site/src/alphatabdoc/model/BarSubElement';
+
+<EnumMemberList doc={barSubElementDoc} />
+
+
+### Voice level
+
+On Bar level initialize the `voice.style = new alphaTab.model.VoiceStyle()` and then select the element to color via `alphaTab.model.VoiceSubElement`.
+
+import voiceSubElementDoc from '@site/src/alphatabdoc/model/VoiceSubElement';
+
+<EnumMemberList doc={voiceSubElementDoc} />
+
+### Beat level
+
+On Beat level initialize the `beat.style = new alphaTab.model.BeatStyle()` and then select the element to color via `alphaTab.model.BeatSubElement`.
+
+import beatSubElementDoc from '@site/src/alphatabdoc/model/BeatSubElement';
+
+<EnumMemberList doc={beatSubElementDoc} />
+
+### Note level
+
+On Note level initialize the `note.style = new alphaTab.model.NoteStyle()` and then select the element to color via `alphaTab.model.NoteSubElement`.
+
+import noteSubElementDoc from '@site/src/alphatabdoc/model/NoteSubElement';
+
+<EnumMemberList doc={noteSubElementDoc} />

docs/reference/api/enumerateoutputdevices.mdx

@@ -13,6 +13,7 @@ import { SinceBadge } from '@site/src/components/SinceBadge';
 <SinceBadge since="1.5.0" />
 
 import { TypeTable, TypeRow } from '@site/src/components/TypeTable';
+import {ParameterTable, ParameterRow} from '@site/src/components/ParameterTable';
 
 ## Description
 Loads and lists the available output devices which can be used by the player. Will request permissions if needed.

docs/reference/api/setoutputdevice.mdx

@@ -13,6 +13,7 @@ import { SinceBadge } from '@site/src/components/SinceBadge';
 <SinceBadge since="1.5.0" />
 
 import { TypeTable, TypeRow } from '@site/src/components/TypeTable';
+import {ParameterTable, ParameterRow} from '@site/src/components/ParameterTable';
 
 ## Description
 Changes the output device which should be used for playing the audio (player must be enabled).

docusaurus.config.ts

@@ -32,7 +32,7 @@ function getSortValue(
   prop: string,
   docs: Map<string, SidebarItemsGeneratorDoc>,
   item: NormalizedSidebarItem
-): string | number {
+): string | number | undefined {
   if (prop in item) {
     return item[prop];
   }
@@ -76,8 +76,8 @@ function getSortValue(
     }
   }
 
-  console.warn(`Could not get sort prop '${prop}' on sidebar item`, item);
-  return "";
+  // console.warn(`Could not get sort prop '${prop}' on sidebar item`, item);
+  return undefined;
 }
 
 const config: Config = {
@@ -115,8 +115,12 @@ const config: Config = {
             const sidebarItems = await defaultSidebarItemsGenerator(args);
 
             if (Array.isArray(args.item.customProps?.["sort"])) {
-              const ascending = args.item.customProps?.["sort"][1] !== "desc";
-              const prop = args.item.customProps?.["sort"][0];
+              let props = args.item.customProps?.["sort"] as
+                | [string, string]
+                | [string, string][];
+              if (!Array.isArray(props[0])) {
+                props = [props as [string, string]];
+              }
 
               const docsLookup = new Map<string, SidebarItemsGeneratorDoc>(
                 args.docs.map((d) => [d.id, d])
@@ -125,27 +129,45 @@ const config: Config = {
               // Reverse items in categories
 
               sidebarItems.sort((a, b) => {
-                let av = getSortValue(prop, docsLookup, a);
-                let bv = getSortValue(prop, docsLookup, b);
+                for (const prop of props) {
+                  const ascending = prop[1] !== "desc";
 
-                if (typeof av !== typeof bv) {
-                  av = String(av);
-                  bv = String(bv);
-                }
+                  let av = getSortValue(prop[0], docsLookup, a);
+                  let bv = getSortValue(prop[0], docsLookup, b);
 
-                if (typeof av === "string") {
-                  if (ascending) {
-                    return av.localeCompare(bv as string);
-                  } else {
-                    return (bv as string).localeCompare(av);
+                  if (typeof av !== typeof bv) {
+                    av = av === undefined ? av : String(av);
+                    bv = bv === undefined ? bv : String(bv);
                   }
-                } else {
-                  if (ascending) {
-                    return av - (bv as number);
+
+                  var result = 0;
+
+                  if (av === undefined && bv === undefined) {
+                    // continue
+                  } else if (av === undefined) {
+                    return -1;
+                  } else if (bv === undefined) {
+                    return 1;
+                  } else if (typeof av === "string") {
+                    if (ascending) {
+                      result = av.localeCompare(bv as string);
+                    } else {
+                      result = (bv as string).localeCompare(av);
+                    }
                   } else {
-                    return (bv as number) - av;
+                    if (ascending) {
+                      result = av - (bv as number);
+                    } else {
+                      result = (bv as number) - av;
+                    }
+                  }
+
+                  if (result !== 0) {
+                    return result;
                   }
                 }
+
+                return 0;
               });
             }
 
@@ -319,16 +341,14 @@ const config: Config = {
         const sassLoader = sassRule!.use[sassLoaderIndex] as RuleSetRule;
         sassLoader.options = {
           ...((sassLoader.options as object | undefined) ?? {}),
-          sourceMap: true // force sourcemaps
+          sourceMap: true, // force sourcemaps
         };
 
-
         // insert resolve-url-loader before SASS loader to fix relative URLs
         sassRule!.use.splice(sassLoaderIndex, 0, {
           loader: "resolve-url-loader",
         });
 
-        
         return {
           plugins: [
             // Copy the Font and SoundFont Files to the output