Merge pull request 'Add tags to reference' (#1645) from vvolhejn/strudel:radical-new-docs into main

Reviewed-on: https://codeberg.org/uzu/strudel/pulls/1645

jsdoc/jsdoc-synonyms.js

@@ -12,6 +12,13 @@ function defineTags(dictionary) {
       doclet.synonyms = doclet.synonyms_text.split(/[ ,]+/);
     },
   });
+
+  dictionary.defineTag('tags', {
+    mustHaveValue: true,
+    onTagged: function (doclet, tag) {
+      doclet.tags = tag.value.split(/[ ,]+/);
+    },
+  });
 }
 
 module.exports = { defineTags: defineTags };

packages/codemirror/codemirror.mjs

@@ -434,6 +434,7 @@ function s4() {
 /**
  * Overrides the css of highlighted events. Make sure to use single quotes!
  * @name markcss
+ * @tag visualization
  * @example
  * note("c a f e")
  * .markcss('text-decoration:underline')

packages/codemirror/slider.mjs

@@ -117,6 +117,7 @@ export const sliderPlugin = ViewPlugin.fromClass(
  * Displays a slider widget to allow the user manipulate a value
  *
  * @name slider
+ * @tags external_io, visualization
  * @param {number} value Initial value
  * @param {number} min Minimum value - optional, defaults to 0
  * @param {number} max Maximum value - optional, defaults to 1

packages/core/drawLine.mjs

@@ -15,6 +15,7 @@ import Fraction, { gcd } from './fraction.mjs';
  * - "-" hold previous value
  * - "." silence
  *
+ * @tags visualization
  * @param {Pattern} pattern the pattern to use
  * @param {number} chars max number of characters (approximately)
  * @returns string

packages/core/euclid.mjs

@@ -61,6 +61,7 @@ export const bjorklund = function (ons, steps) {
  *
  * @memberof Pattern
  * @name euclid
+ * @tags temporal
  * @param {number} pulses the number of onsets/beats
  * @param {number} steps the number of steps to fill
  * @returns Pattern
@@ -73,6 +74,7 @@ export const bjorklund = function (ons, steps) {
  * Like `euclid`, but has an additional parameter for 'rotating' the resulting sequence.
  * @memberof Pattern
  * @name euclidRot
+ * @tags temporal
  * @param {number} pulses the number of onsets/beats
  * @param {number} steps the number of steps to fill
  * @param {number} rotation offset in steps
@@ -156,6 +158,7 @@ export const { euclidrot, euclidRot } = register(['euclidrot', 'euclidRot'], fun
  * so there will be no gaps.
  * @name euclidLegato
  * @memberof Pattern
+ * @tags temporal
  * @param {number} pulses the number of onsets/beats
  * @param {number} steps the number of steps to fill
  * @param rotation offset in steps
@@ -187,6 +190,7 @@ export const euclidLegato = register(['euclidLegato'], function (pulses, steps,
  * the resulting sequence
  * @name euclidLegatoRot
  * @memberof Pattern
+ * @tags temporal
  * @param {number} pulses the number of onsets/beats
  * @param {number} steps the number of steps to fill
  * @param {number} rotation offset in steps
@@ -208,6 +212,7 @@ export const euclidLegatoRot = register(['euclidLegatoRot'], function (pulses, s
  * @name euclidish
  * @synonyms eish
  * @memberof Pattern
+ * @tags temporal
  * @param {number} pulses the number of onsets
  * @param {number} steps the number of steps to fill
  * @param {number} groove exists between the extremes of 0 (straight euclidian) and 1 (straight pulse)

packages/core/pick.mjs

@@ -28,6 +28,7 @@ const _pick = function (lookup, pat, modulo = true) {
 
 /** * Picks patterns (or plain values) either from a list (by index) or a lookup table (by name).
  * Similar to `inhabit`, but maintains the structure of the original patterns.
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -57,6 +58,7 @@ const __pick = register('pick', function (lookup, pat) {
  * it wraps around, rather than sticking at the maximum value.
  * For example, if you pick the fifth pattern of a list of three, you'll get the
  * second one.
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -67,6 +69,7 @@ export const pickmod = register('pickmod', function (lookup, pat) {
 });
 
 /** * pickF lets you use a pattern of numbers to pick which function to apply to another pattern.
+ * @tags combiners, functional
  * @param {Pattern} pat
  * @param {Pattern} lookup a pattern of indices
  * @param {function[]} funcs the array of functions from which to pull
@@ -83,6 +86,7 @@ export const pickF = register('pickF', function (lookup, funcs, pat) {
 
 /** * The same as `pickF`, but if you pick a number greater than the size of the functions list,
  * it wraps around, rather than sticking at the maximum value.
+ * @tags combiners
  * @param {Pattern} pat
  * @param {Pattern} lookup a pattern of indices
  * @param {function[]} funcs the array of functions from which to pull
@@ -93,6 +97,7 @@ export const pickmodF = register('pickmodF', function (lookup, funcs, pat) {
 });
 
 /** * Similar to `pick`, but it applies an outerJoin instead of an innerJoin.
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -103,6 +108,7 @@ export const pickOut = register('pickOut', function (lookup, pat) {
 
 /** * The same as `pickOut`, but if you pick a number greater than the size of the list,
  * it wraps around, rather than sticking at the maximum value.
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -112,6 +118,7 @@ export const pickmodOut = register('pickmodOut', function (lookup, pat) {
 });
 
 /** * Similar to `pick`, but the choosen pattern is restarted when its index is triggered.
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -122,6 +129,7 @@ export const pickRestart = register('pickRestart', function (lookup, pat) {
 
 /** * The same as `pickRestart`, but if you pick a number greater than the size of the list,
    * it wraps around, rather than sticking at the maximum value.
+   * @tags combiners
    * @param {Pattern} pat
    * @param {*} xs
    * @returns {Pattern}
@@ -138,6 +146,7 @@ export const pickmodRestart = register('pickmodRestart', function (lookup, pat)
 });
 
 /** * Similar to `pick`, but the choosen pattern is reset when its index is triggered.
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -148,6 +157,7 @@ export const pickReset = register('pickReset', function (lookup, pat) {
 
 /** * The same as `pickReset`, but if you pick a number greater than the size of the list,
  * it wraps around, rather than sticking at the maximum value.
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -159,6 +169,7 @@ export const pickmodReset = register('pickmodReset', function (lookup, pat) {
 /** Picks patterns (or plain values) either from a list (by index) or a lookup table (by name).
    * Similar to `pick`, but cycles are squeezed into the target ('inhabited') pattern.
    * @name inhabit
+   * @tags combiners
    * @synonyms pickSqueeze
    * @param {Pattern} pat
    * @param {*} xs
@@ -180,6 +191,7 @@ export const { inhabit, pickSqueeze } = register(['inhabit', 'pickSqueeze'], fun
  * second one.
  * @name inhabitmod
  * @synonyms pickmodSqueeze
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -192,6 +204,7 @@ export const { inhabitmod, pickmodSqueeze } = register(['inhabitmod', 'pickmodSq
 /**
  * Pick from the list of values (or patterns of values) via the index using the given
  * pattern of integers. The selected pattern will be compressed to fit the duration of the selecting event
+ * @tags combiners
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}

packages/core/repl.mjs

@@ -123,6 +123,7 @@ export function repl({
    * Changes the global tempo to the given cycles per minute
    *
    * @name setcpm
+   * @tags temporal
    * @alias setCpm
    * @param {number} cpm cycles per minute
    * @example
@@ -136,7 +137,9 @@ export function repl({
 
   // TODO - not documented as jsdoc examples as the test framework doesn't simulate enough context for `each` and `all`..
 
-  /** Applies a function to all the running patterns. Note that the patterns are groups together into a single `stack` before the function is applied. This is probably what you want, but see `each` for
+  let allTransforms = [];
+  /**
+   * Applies a function to all the running patterns. Note that the patterns are groups together into a single `stack` before the function is applied. This is probably what you want, but see `each` for
    * a version that applies the function to each pattern separately.
    * ```
    * $: sound("bd - cp sd")
@@ -148,18 +151,21 @@ export function repl({
    * $: sound("hh*8")
    * all(x => x.pianoroll())
    * ```
+   *
+   * @tags combiners
    */
-  let allTransforms = [];
   const all = function (transform) {
     allTransforms.push(transform);
     return silence;
   };
   /** Applies a function to each of the running patterns separately. This is intended for future use with upcoming 'stepwise' features. See `all` for a version that applies the function to all the patterns stacked together into a single pattern.
+   *
    * ```
    * $: sound("bd - cp sd")
    * $: sound("hh*8")
    * each(fast("<2 3>"))
    * ```
+   * @tags combiners
    */
   const each = function (transform) {
     eachTransform = transform;

packages/core/signal.mjs

@@ -24,6 +24,7 @@ export const signal = (func) => {
  *  A sawtooth signal between 0 and 1.
  *
  * @return {Pattern}
+ * @tags generators
  * @example
  * note("<c3 [eb3,g3] g2 [g3,bb3]>*8")
  * .clip(saw.slow(2))
@@ -38,6 +39,7 @@ export const saw = signal((t) => t % 1);
  *  A sawtooth signal between -1 and 1 (like `saw`, but bipolar).
  *
  * @return {Pattern}
+ * @tags generators
  */
 export const saw2 = saw.toBipolar();
 
@@ -45,6 +47,7 @@ export const saw2 = saw.toBipolar();
  *  A sawtooth signal between 1 and 0 (like `saw`, but flipped).
  *
  * @return {Pattern}
+ * @tags generators
  * @example
  * note("<c3 [eb3,g3] g2 [g3,bb3]>*8")
  * .clip(isaw.slow(2))
@@ -59,6 +62,7 @@ export const isaw = signal((t) => 1 - (t % 1));
  *  A sawtooth signal between 1 and -1 (like `saw2`, but flipped).
  *
  * @return {Pattern}
+ * @tags generators
  */
 export const isaw2 = isaw.toBipolar();
 
@@ -66,12 +70,14 @@ export const isaw2 = isaw.toBipolar();
  *  A sine signal between -1 and 1 (like `sine`, but bipolar).
  *
  * @return {Pattern}
+ * @tags generators
  */
 export const sine2 = signal((t) => Math.sin(Math.PI * 2 * t));
 
 /**
  *  A sine signal between 0 and 1.
  * @return {Pattern}
+ * @tags generators
  * @example
  * n(sine.segment(16).range(0,15))
  * .scale("C:minor")
@@ -83,6 +89,7 @@ export const sine = sine2.fromBipolar();
  *  A cosine signal between 0 and 1.
  *
  * @return {Pattern}
+ * @tags generators
  * @example
  * n(stack(sine,cosine).segment(16).range(0,15))
  * .scale("C:minor")
@@ -94,12 +101,14 @@ export const cosine = sine._early(Fraction(1).div(4));
  *  A cosine signal between -1 and 1 (like `cosine`, but bipolar).
  *
  * @return {Pattern}
+ * @tags generators
  */
 export const cosine2 = sine2._early(Fraction(1).div(4));
 
 /**
  *  A square signal between 0 and 1.
  * @return {Pattern}
+ * @tags generators
  * @example
  * n(square.segment(4).range(0,7)).scale("C:minor")
  *
@@ -110,6 +119,7 @@ export const square = signal((t) => Math.floor((t * 2) % 2));
  *  A square signal between -1 and 1 (like `square`, but bipolar).
  *
  * @return {Pattern}
+ * @tags generators
  */
 export const square2 = square.toBipolar();
 
@@ -117,6 +127,7 @@ export const square2 = square.toBipolar();
  *  A triangle signal between 0 and 1.
  *
  * @return {Pattern}
+ * @tags generators
  * @example
  * n(tri.segment(8).range(0,7)).scale("C:minor")
  *
@@ -127,6 +138,7 @@ export const tri = fastcat(saw, isaw);
  *  A triangle signal between -1 and 1 (like `tri`, but bipolar).
  *
  * @return {Pattern}
+ * @tags generators
  */
 export const tri2 = fastcat(saw2, isaw2);
 
@@ -134,6 +146,7 @@ export const tri2 = fastcat(saw2, isaw2);
  *  An inverted triangle signal between 1 and 0 (like `tri`, but flipped).
  *
  * @return {Pattern}
+ * @tags generators
  * @example
  * n(itri.segment(8).range(0,7)).scale("C:minor")
  *
@@ -144,6 +157,7 @@ export const itri = fastcat(isaw, saw);
  *  An inverted triangle signal between -1 and 1 (like `itri`, but bipolar).
  *
  * @return {Pattern}
+ * @tags generators
  */
 export const itri2 = fastcat(isaw2, saw2);
 
@@ -151,6 +165,7 @@ export const itri2 = fastcat(isaw2, saw2);
  *  A signal representing the cycle time.
  *
  * @return {Pattern}
+ * @tags generators
  */
 export const time = signal(id);
 
@@ -158,6 +173,7 @@ export const time = signal(id);
  *  The mouse's x position value ranges from 0 to 1.
  * @name mousex
  * @return {Pattern}
+ * @tags external_io
  * @example
  * n(mousex.segment(4).range(0,7)).scale("C:minor")
  *
@@ -167,6 +183,7 @@ export const time = signal(id);
  *  The mouse's y position value ranges from 0 to 1.
  * @name mousey
  * @return {Pattern}
+ * @tags external_io
  * @example
  * n(mousey.segment(4).range(0,7)).scale("C:minor")
  *
@@ -269,6 +286,7 @@ export const getRandsAtTime = (t, n = 1, seed = 0) => {
  * precise RNG, try `useRNG('precise')`.
  *
  * @name useRNG
+ * @tags generators, math
  * @param {string} mod - Mode. One of 'legacy', 'precise'
  * @example
  * useRNG('legacy')
@@ -280,6 +298,7 @@ export const useRNG = (mode = 'legacy') => (RNG_MODE = mode);
 
 /**
  * A discrete pattern of numbers from 0 to n-1
+ * @tags generators
  * @example
  * n(run(4)).scale("C4:pentatonic")
  * // n("0 1 2 3").scale("C4:pentatonic")
@@ -290,6 +309,7 @@ export const run = (n) => saw.range(0, n).round().segment(n);
  * Creates a binary pattern from a number.
  *
  * @name binary
+ * @tags generators
  * @param {number} n - input number to convert to binary
  * @example
  * "hh".s().struct(binary(5))
@@ -304,6 +324,7 @@ export const binary = (n) => {
  * Creates a binary pattern from a number, padded to n bits long.
  *
  * @name binaryN
+ * @tags generators
  * @param {number} n - input number to convert to binary
  * @param {number} nBits - pattern length, defaults to 16
  * @example
@@ -321,6 +342,7 @@ export const binaryN = (n, nBits = 16) => {
  * Creates a binary list pattern from a number.
  *
  * @name binaryL
+ * @tags generators
  * @param {number} n - input number to convert to binary
  * s("saw").seg(8)
  *   .partials(binaryL(irand(4096).add(1)))
@@ -334,6 +356,7 @@ export const binaryL = (n) => {
  * Creates a binary list pattern from a number, padded to n bits long.
  *
  * @name binaryNL
+ * @tags generators
  * @param {number} n - input number to convert to binary
  * @param {number} nBits - pattern length, defaults to 16
  */
@@ -353,6 +376,7 @@ export const binaryNL = (n, nBits = 16) => {
  * Creates a list of random numbers of the given length
  *
  * @name randL
+ * @tags generators
  * @param {number} n Number of random numbers to sample
  * @example
  * s("saw").seg(16).n(irand(12)).scale("F1:minor")
@@ -384,6 +408,7 @@ const _rearrangeWith = (ipat, n, pat) => {
  * Slices a pattern into the given number of parts, then plays those parts in random order.
  * Each part will be played exactly once per cycle.
  * @name shuffle
+ * @tags temporal
  * @example
  * note("c d e f").sound("piano").shuffle(4)
  * @example
@@ -397,6 +422,7 @@ export const shuffle = register('shuffle', (n, pat) => {
  * Slices a pattern into the given number of parts, then plays those parts at random. Similar to `shuffle`,
  * but parts might be played more than once, or not at all, per cycle.
  * @name scramble
+ * @tags temporal
  * @example
  * note("c d e f").sound("piano").scramble(4)
  * @example
@@ -409,6 +435,7 @@ export const scramble = register('scramble', (n, pat) => {
 /**
  * Modify a pattern by applying a function to the `randomSeed` control if present
  *
+ * @tags math
  * @param {Function} func Function from seed (or undefined) to seed (or undefined)
  * @param {Pattern} pat Pattern to update
  * @returns Pattern
@@ -428,6 +455,7 @@ export const withSeed = (func, pat) => {
  * that use randomness, like `shuffle` and `sometimes`.
  *
  * @name seed
+ * @tags math
  * @param {number} n A new seed. Can be any number.
  * @example
  * $: s("hh*4").degrade();
@@ -441,6 +469,7 @@ export const seed = register('seed', (n, pat) => {
  * A continuous pattern of random numbers, between 0 and 1.
  *
  * @name rand
+ * @tags generators
  * @example
  * // randomly change the cutoff
  * s("bd*4,hh*8").cutoff(rand.range(500,8000))
@@ -449,6 +478,7 @@ export const seed = register('seed', (n, pat) => {
 export const rand = signal((t, controls) => getRandsAtTime(t, 1, controls.randSeed));
 /**
  * A continuous pattern of random numbers, between -1 and 1
+ * @tags generators
  */
 export const rand2 = rand.toBipolar();
 
@@ -458,6 +488,7 @@ export const _brandBy = (p) => rand.fmap((x) => x < p);
  * A continuous pattern of 0 or 1 (binary random), with a probability for the value being 1
  *
  * @name brandBy
+ * @tags generators
  * @param {number} probability - a number between 0 and 1
  * @example
  * s("hh*10").pan(brandBy(0.2))
@@ -468,6 +499,7 @@ export const brandBy = (pPat) => reify(pPat).fmap(_brandBy).innerJoin();
  * A continuous pattern of 0 or 1 (binary random)
  *
  * @name brand
+ * @tags generators
  * @example
  * s("hh*10").pan(brand)
  */
@@ -479,6 +511,7 @@ export const _irand = (i) => rand.fmap((x) => Math.trunc(x * i));
  * A continuous pattern of random integers, between 0 and n-1.
  *
  * @name irand
+ * @tags generators
  * @param {number} n max value (exclusive)
  * @example
  * // randomly select scale notes from 0 - 7 (= C to C)
@@ -501,6 +534,7 @@ export const __chooseWith = (pat, xs) => {
 /**
  * Choose from the list of values (or patterns of values) using the given
  * pattern of numbers, which should be in the range of 0..1
+ * @tags temporal
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -514,6 +548,7 @@ export const chooseWith = (pat, xs) => {
 /**
  * As with {chooseWith}, but the structure comes from the chosen values, rather
  * than the pattern you're using to choose with.
+ * @tags temporal
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
@@ -524,6 +559,7 @@ export const chooseInWith = (pat, xs) => {
 
 /**
  * Chooses randomly from the given list of elements.
+ * @tags temporal
  * @param  {...any} xs values / patterns to choose from.
  * @returns {Pattern} - a continuous pattern.
  * @example
@@ -539,6 +575,7 @@ export const chooseOut = choose;
  * Chooses from the given list of values (or patterns of values), according
  * to the pattern that the method is called on. The pattern should be in
  * the range 0 .. 1.
+ * @tags temporal
  * @param  {...any} xs
  * @returns {Pattern}
  */
@@ -549,6 +586,7 @@ Pattern.prototype.choose = function (...xs) {
 /**
  * As with choose, but the pattern that this method is called on should be
  * in the range -1 .. 1
+ * @tags temporal
  * @param  {...any} xs
  * @returns {Pattern}
  */
@@ -558,6 +596,7 @@ Pattern.prototype.choose2 = function (...xs) {
 
 /**
  * Picks one of the elements at random each cycle.
+ * @tags temporal
  * @synonyms randcat
  * @returns {Pattern}
  * @example
@@ -600,6 +639,7 @@ const wchooseWith = (...args) => _wchooseWith(...args).outerJoin();
 
 /**
  * Chooses randomly from the given list of elements by giving a probability to each element
+ * @tags temporal
  * @param {...any} pairs arrays of value and weight
  * @returns {Pattern} - a continuous pattern.
  * @example
@@ -609,6 +649,7 @@ export const wchoose = (...pairs) => wchooseWith(rand, ...pairs);
 
 /**
  * Picks one of the elements at random each cycle by giving a probability to each element
+ * @tags temporal
  * @synonyms wrandcat
  * @returns {Pattern}
  * @example
@@ -652,6 +693,7 @@ function _berlin(t, seed = 0) {
 /**
  * Generates a continuous pattern of [perlin noise](https://en.wikipedia.org/wiki/Perlin_noise), in the range 0..1.
  *
+ * @tags generators
  * @name perlin
  * @example
  * // randomly change the cutoff
@@ -664,6 +706,7 @@ export const perlin = signal((t, controls) => _perlin(t, controls.randSeed));
  * Generates a continuous pattern of [berlin noise](conceived by Jame Coyne and Jade Rowland as a joke but turned out to be surprisingly cool and useful,
  * like perlin noise but with sawtooth waves), in the range 0..1.
  *
+ * @tags generators
  * @name berlin
  * @example
  * // ascending arpeggios
@@ -684,6 +727,7 @@ export const degradeByWith = register(
  * 0 = 0% chance of removal
  * 1 = 100% chance of removal
  *
+ * @tags temporal
  * @name degradeBy
  * @memberof Pattern
  * @param {number} amount - a number between 0 and 1
@@ -709,6 +753,7 @@ export const degradeBy = register(
  *
  * Randomly removes 50% of events from the pattern. Shorthand for `.degradeBy(0.5)`
  *
+ * @tags temporal
  * @name degrade
  * @memberof Pattern
  * @returns Pattern
@@ -725,6 +770,7 @@ export const degrade = register('degrade', (pat) => pat._degradeBy(0.5), true, t
  * 1 = 0% chance of removal
  * Events that would be removed by degradeBy are let through by undegradeBy and vice versa (see second example).
  *
+ * @tags temporal
  * @name undegradeBy
  * @memberof Pattern
  * @param {number} amount - a number between 0 and 1
@@ -753,6 +799,7 @@ export const undegradeBy = register(
  * Inverse of `degrade`: Randomly removes 50% of events from the pattern. Shorthand for `.undegradeBy(0.5)`
  * Events that would be removed by degrade are let through by undegrade and vice versa (see second example).
  *
+ * @tags temporal
  * @name undegrade
  * @memberof Pattern
  * @returns Pattern
@@ -771,6 +818,7 @@ export const undegrade = register('undegrade', (pat) => pat._undegradeBy(0.5), t
  * Randomly applies the given function by the given probability.
  * Similar to `someCyclesBy`
  *
+ * @tags temporal
  * @name sometimesBy
  * @memberof Pattern
  * @param {number | Pattern} probability - a number between 0 and 1
@@ -790,6 +838,7 @@ export const sometimesBy = register('sometimesBy', function (patx, func, pat) {
  *
  * Applies the given function with a 50% chance
  *
+ * @tags temporal
  * @name sometimes
  * @memberof Pattern
  * @param {function} function - the transformation to apply
@@ -811,6 +860,7 @@ export const sometimes = register('sometimes', function (func, pat) {
  * @param {number | Pattern} probability - a number between 0 and 1
  * @param {function} function - the transformation to apply
  * @returns Pattern
+ * @tags temporal
  * @example
  * s("bd,hh*8").someCyclesBy(.3, x=>x.speed("0.5"))
  */
@@ -833,6 +883,7 @@ export const someCyclesBy = register('someCyclesBy', function (patx, func, pat)
  * @name someCycles
  * @memberof Pattern
  * @returns Pattern
+ * @tags temporal
  * @example
  * s("bd,hh*8").someCycles(x=>x.speed("0.5"))
  */
@@ -847,6 +898,7 @@ export const someCycles = register('someCycles', function (func, pat) {
  * @name often
  * @memberof Pattern
  * @returns Pattern
+ * @tags temporal
  * @example
  * s("hh*8").often(x=>x.speed("0.5"))
  */
@@ -861,6 +913,7 @@ export const often = register('often', function (func, pat) {
  * @name rarely
  * @memberof Pattern
  * @returns Pattern
+ * @tags temporal
  * @example
  * s("hh*8").rarely(x=>x.speed("0.5"))
  */
@@ -872,6 +925,7 @@ export const rarely = register('rarely', function (func, pat) {
  *
  * Shorthand for `.sometimesBy(0.1, fn)`
  *
+ * @tags temporal
  * @name almostNever
  * @memberof Pattern
  * @returns Pattern
@@ -886,6 +940,7 @@ export const almostNever = register('almostNever', function (func, pat) {
  *
  * Shorthand for `.sometimesBy(0.9, fn)`
  *
+ * @tags temporal
  * @name almostAlways
  * @memberof Pattern
  * @returns Pattern
@@ -900,6 +955,7 @@ export const almostAlways = register('almostAlways', function (func, pat) {
  *
  * Shorthand for `.sometimesBy(0, fn)` (never calls fn)
  *
+ * @tags temporal
  * @name never
  * @memberof Pattern
  * @returns Pattern
@@ -914,6 +970,7 @@ export const never = register('never', function (_, pat) {
  *
  * Shorthand for `.sometimesBy(1, fn)` (always calls fn)
  *
+ * @tags temporal
  * @name always
  * @memberof Pattern
  * @returns Pattern
@@ -942,6 +999,7 @@ export function _keyDown(keyname) {
  * Do something on a keypress, or array of keypresses
  * [Key name reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)
  *
+ * @tags external_io
  * @name whenKey
  * @memberof Pattern
  * @returns Pattern
@@ -958,6 +1016,7 @@ export const whenKey = register('whenKey', function (input, func, pat) {
  * returns true when a key or array of keys is held
  * [Key name reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)
  *
+ * @tags external_io
  * @name keyDown
  * @memberof Pattern
  * @returns Pattern
@@ -975,6 +1034,8 @@ export const keyDown = register('keyDown', function (pat) {
  * event durations, from the pattern that it is combined with.
  * For example `cyclesPer.struct("1 1 [1 1] 1")` would give the same as `"0.25 0.25 [0.125 0.125] 0.25"`.
  * See also its reciprocal, `per`, also known as `perCycle`.
+ *
+ * @tags temporal
  * @example
  * // Shorter events are lower in pitch
  * sound("saw saw [saw saw] saw")
@@ -993,6 +1054,7 @@ export const cyclesPer = new Pattern(function (state) {
  * event durations, from the pattern that it is combined with.
  * For example `per.struct("1 1 [1 1] 1")` would give the same as `"4 4 [8 8] 4"`.
  * See also its reciprocal, `cyclesPer`.
+ * @tags temporal
  * @synonyms perCycle
  * @example
  * // Shorter events are more distorted
@@ -1010,6 +1072,7 @@ export const perCycle = per;
  * particular, where the event duration halves, the
  * returned value increases by one. `perx.struct("1 1 [1 [1 1]] 1")` would therefore be
  * the same as `"3 3 [4 [5 5]] 3"`.
+ * @tags temporal
  */
 export const perx = new Pattern(function (state) {
   const n = Fraction(1).div(state.span.duration);

packages/csound/index.mjs

@@ -135,6 +135,8 @@ export async function loadOrc(url) {
  *  p4 -- MIDI key number (as a real number, not an integer but in [0, 127].
  *  p5 -- MIDI velocity (as a real number, not an integer but in [0, 127].
  *  p6 -- Strudel controls, as a string.
+ *
+ * @tags external_io
  */
 export const csoundm = register('csoundm', (instrument, pat) => {
   let p1 = instrument;

packages/draw/pianoroll.mjs

@@ -42,6 +42,7 @@ const getValue = (e) => {
  *
  * @name pianoroll
  * @synonyms punchcard
+ * @tags visualization
  * @param {Object} options Object containing all the optional following parameters as key value pairs:
  * @param {integer} cycles number of cycles to be displayed at the same time - defaults to 4
  * @param {number} playhead location of the active notes on the time axis - 0 to 1, defaults to 0.5
@@ -299,6 +300,7 @@ Pattern.prototype.punchcard = function (options) {
  * Supports all the same options as pianoroll.
  *
  * @name wordfall
+ * @tags visualization
  */
 Pattern.prototype.wordfall = function (options) {
   return this.punchcard({ vertical: 1, labels: 1, stroke: 0, fillActive: 1, active: 'white', ...options });

packages/draw/pitchwheel.mjs

@@ -116,6 +116,7 @@ export function pitchwheel({
 /**
  * Renders a pitch circle to visualize frequencies within one octave
  * @name pitchwheel
+ * @tags visualization
  * @param {number} hapcircles
  * @param {number} circle
  * @param {number} edo

packages/draw/spiral.mjs

@@ -129,6 +129,7 @@ function drawSpiral(options) {
  * Displays a spiral visual.
  *
  * @name spiral
+ * @tags visualization
  * @param {Object} options Object containing all the optional following parameters as key value pairs:
  * @param {number} stretch controls the rotations per cycle ratio, where 1 = 1 cycle / 360 degrees
  * @param {number} size the diameter of the spiral

packages/midi/midi.mjs

@@ -138,6 +138,7 @@ function githubPath(base, subpath = '') {
 
 /**
  * configures the default midimap, which is used when no "midimap" port is set
+ * @tags external_io
  * @example
  * defaultmidimap({ lpf: 74 })
  * $: note("c a f e").midi();
@@ -151,6 +152,7 @@ let loadCache = {};
 
 /**
  * Adds midimaps to the registry. Inside each midimap, control names (e.g. lpf) are mapped to cc numbers.
+ * @tags external_io
  * @example
  * midimaps({ mymap: { lpf: 74 } })
  * $: note("c a f e")
@@ -305,6 +307,7 @@ function sendNote(note, velocity, duration, device, midichan, targetTime) {
 
 /**
  * MIDI output: Opens a MIDI output port.
+ * @tags external_io
  * @param {string | number} midiport MIDI device name or index defaulting to 0
  * @param {object} options Additional MIDI configuration options
  * @example
@@ -526,6 +529,7 @@ async function _initialize(input) {
  * The output is a function that accepts a midi cc value to query as well as (optionally) a midi channel
  *
  * @name midin
+ * @tags external_io
  * @param {string | number} input MIDI device name or index defaulting to 0
  * @returns {function(number, number=): Pattern} A function from (cc, channel?) to a pattern.
  *   When queried, the pattern will produces the most recently received midi value (normalized to 0 to 1)
@@ -573,6 +577,7 @@ export async function midin(input) {
  * note durations
  *
  * @name midikeys
+ * @tags external_io
  * @param {string | number} input MIDI device name or index defaulting to 0
  * @returns {function((number | Pattern)=): Pattern} A function that produces a pattern.
  *   When queried, the pattern will produces the most recently played midi notes and velocities,

packages/motion/motion.mjs

@@ -7,6 +7,7 @@ import { signal } from '../core/signal.mjs';
  * @name accelerationX
  * @return {Pattern}
  * @synonyms accX
+ * @tags external_io
  * @example
  * n(accelerationX.segment(4).range(0,7)).scale("C:minor")
  *
@@ -17,6 +18,7 @@ import { signal } from '../core/signal.mjs';
  * @name accelerationY
  * @return {Pattern}
  * @synonyms accY
+ * @tags external_io
  * @example
  * n(accelerationY.segment(4).range(0,7)).scale("C:minor")
  *
@@ -27,6 +29,7 @@ import { signal } from '../core/signal.mjs';
  * @name accelerationZ
  * @return {Pattern}
  * @synonyms accZ
+ * @tags external_io
  * @example
  * n(accelerationZ.segment(4).range(0,7)).scale("C:minor")
  *
@@ -37,6 +40,7 @@ import { signal } from '../core/signal.mjs';
  * @name gravityX
  * @return {Pattern}
  * @synonyms gravX
+ * @tags external_io
  * @example
  * n(gravityX.segment(4).range(0,7)).scale("C:minor")
  *
@@ -47,6 +51,7 @@ import { signal } from '../core/signal.mjs';
  * @name gravityY
  * @return {Pattern}
  * @synonyms gravY
+ * @tags external_io
  * @example
  * n(gravityY.segment(4).range(0,7)).scale("C:minor")
  *
@@ -57,6 +62,7 @@ import { signal } from '../core/signal.mjs';
  * @name gravityZ
  * @return {Pattern}
  * @synonyms gravZ
+ * @tags external_io
  * @example
  * n(gravityZ.segment(4).range(0,7)).scale("C:minor")
  *
@@ -67,6 +73,7 @@ import { signal } from '../core/signal.mjs';
  * @name rotationAlpha
  * @return {Pattern}
  * @synonyms rotA, rotZ, rotationZ
+ * @tags external_io
  * @example
  * n(rotationAlpha.segment(4).range(0,7)).scale("C:minor")
  *
@@ -77,6 +84,7 @@ import { signal } from '../core/signal.mjs';
  * @name rotationBeta
  * @return {Pattern}
  * @synonyms rotB, rotX, rotationX
+ * @tags external_io
  * @example
  * n(rotationBeta.segment(4).range(0,7)).scale("C:minor")
  *
@@ -87,6 +95,7 @@ import { signal } from '../core/signal.mjs';
  * @name rotationGamma
  * @return {Pattern}
  * @synonyms rotG, rotY, rotationY
+ * @tags external_io
  * @example
  * n(rotationGamma.segment(4).range(0,7)).scale("C:minor")
  *
@@ -97,6 +106,7 @@ import { signal } from '../core/signal.mjs';
  * @name orientationAlpha
  * @return {Pattern}
  * @synonyms oriA, oriZ, orientationZ
+ * @tags external_io
  * @example
  * n(orientationAlpha.segment(4).range(0,7)).scale("C:minor")
  *
@@ -107,6 +117,7 @@ import { signal } from '../core/signal.mjs';
  * @name orientationBeta
  * @return {Pattern}
  * @synonyms oriB, oriX, orientationX
+ * @tags external_io
  * @example
  * n(orientationBeta.segment(4).range(0,7)).scale("C:minor")
  *
@@ -117,6 +128,7 @@ import { signal } from '../core/signal.mjs';
  * @name orientationGamma
  * @return {Pattern}
  * @synonyms oriG, oriY, orientationY
+ * @tags external_io
  * @example
  * n(orientationGamma.segment(4).range(0,7)).scale("C:minor")
  *
@@ -127,6 +139,7 @@ import { signal } from '../core/signal.mjs';
  * @name absoluteOrientationAlpha
  * @return {Pattern}
  * @synonyms absOriA, absOriZ, absoluteOrientationZ
+ * @tags external_io
  * @example
  * n(absoluteOrientationAlpha.segment(4).range(0,7)).scale("C:minor")
  *
@@ -137,6 +150,7 @@ import { signal } from '../core/signal.mjs';
  * @name absoluteOrientationBeta
  * @return {Pattern}
  * @synonyms absOriB, absOriX, absoluteOrientationX
+ * @tags external_io
  * @example
  * n(absoluteOrientationBeta.segment(4).range(0,7)).scale("C:minor")
  *
@@ -147,6 +161,7 @@ import { signal } from '../core/signal.mjs';
  * @name absoluteOrientationGamma
  * @return {Pattern}
  * @synonyms absOriG, absOriY, absoluteOrientationY
+ * @tags external_io
  * @example
  * n(absoluteOrientationGamma.segment(4).range(0,7)).scale("C:minor")
  *

packages/osc/osc.mjs

@@ -79,6 +79,7 @@ export async function oscTrigger(hap, currentTime, cps = 1, targetTime) {
  * For more info, read [MIDI & OSC in the docs](https://strudel.cc/learn/input-output/)
  *
  * @name osc
+ * @tags external_io
  * @memberof Pattern
  * @returns Pattern
  */

packages/superdough/ola-processor.js

@@ -35,7 +35,9 @@ class OLAProcessor extends AudioWorkletProcessor {
   }
 
   /** Handles dynamic reallocation of input/output channels buffer
-     (channel numbers may lety during lifecycle) **/
+   * (channel numbers may vary during lifecycle)
+   * @tags internals
+   **/
   reallocateChannelsIfNeeded(inputs, outputs) {
     for (let i = 0; i < this.nbInputs; i++) {
       let nbChannels = inputs[i].length;
@@ -88,7 +90,10 @@ class OLAProcessor extends AudioWorkletProcessor {
     }
   }
 
-  /** Read next web audio block to input buffers **/
+  /**
+   * Read next web audio block to input buffers
+   * @tags internals
+   **/
   readInputs(inputs) {
     // when playback is paused, we may stop receiving new samples
     if (inputs[0].length && inputs[0][0].length == 0) {
@@ -108,7 +113,9 @@ class OLAProcessor extends AudioWorkletProcessor {
     }
   }
 
-  /** Write next web audio block from output buffers **/
+  /** Write next web audio block from output buffers
+   * @tags internals
+   **/
   writeOutputs(outputs) {
     for (let i = 0; i < this.nbInputs; i++) {
       for (let j = 0; j < this.inputBuffers[i].length; j++) {
@@ -118,7 +125,9 @@ class OLAProcessor extends AudioWorkletProcessor {
     }
   }
 
-  /** Shift left content of input buffers to receive new web audio block **/
+  /** Shift left content of input buffers to receive new web audio block
+   * @tags internals
+   **/
   shiftInputBuffers() {
     for (let i = 0; i < this.nbInputs; i++) {
       for (let j = 0; j < this.inputBuffers[i].length; j++) {
@@ -127,7 +136,9 @@ class OLAProcessor extends AudioWorkletProcessor {
     }
   }
 
-  /** Shift left content of output buffers to receive new web audio block **/
+  /** Shift left content of output buffers to receive new web audio block
+   * @tags internals
+   **/
   shiftOutputBuffers() {
     for (let i = 0; i < this.nbOutputs; i++) {
       for (let j = 0; j < this.outputBuffers[i].length; j++) {
@@ -137,7 +148,9 @@ class OLAProcessor extends AudioWorkletProcessor {
     }
   }
 
-  /** Copy contents of input buffers to buffer actually sent to process **/
+  /** Copy contents of input buffers to buffer actually sent to process
+   * @tags internals
+   **/
   prepareInputBuffersToSend() {
     for (let i = 0; i < this.nbInputs; i++) {
       for (let j = 0; j < this.inputBuffers[i].length; j++) {
@@ -146,7 +159,9 @@ class OLAProcessor extends AudioWorkletProcessor {
     }
   }
 
-  /** Add contents of output buffers just processed to output buffers **/
+  /** Add contents of output buffers just processed to output buffers
+   * @tags internals
+   **/
   handleOutputBuffersToRetrieve() {
     for (let i = 0; i < this.nbOutputs; i++) {
       for (let j = 0; j < this.outputBuffers[i].length; j++) {

packages/superdough/reverbGen.mjs

@@ -18,6 +18,7 @@ var reverbGen = {};
 
 /** Generates a reverb impulse response.
 
+ @tags internals
  @param {!Object} params TODO: Document the properties.
  @param {!function(!AudioBuffer)} callback Function to call when
   the impulse response has been generated. The impulse response
@@ -50,7 +51,7 @@ reverbGen.generateReverb = function (params, callback) {
 
 /** Creates a canvas element showing a graph of the given data.
 
-
+ @tags internals
  @param {!Float32Array} data An array of numbers, or a Float32Array.
  @param {number} width Width in pixels of the canvas.
  @param {number} height Height in pixels of the canvas.
@@ -81,7 +82,9 @@ reverbGen.generateGraph = function (data, width, height, min, max) {
  @param {number} lpFreqEnd
  @param {number} lpFreqEndAt
  @param {!function(!AudioBuffer)} callback May be called
-  immediately within the current execution context, or later.*/
+  immediately within the current execution context, or later.
+ @tags internals
+  */
 var applyGradualLowpass = function (input, lpFreqStart, lpFreqEnd, lpFreqEndAt, callback) {
   if (lpFreqStart == 0) {
     callback(input);

packages/superdough/sampler.mjs

@@ -235,6 +235,7 @@ export async function fetchSampleMap(url) {
 
 /**
  * Loads a collection of samples to use with `s`
+ * @tags samples
  * @example
  * samples('github:tidalcycles/dirt-samples');
  * s("[bd ~]*2, [~ hh]*2, ~ sd")

packages/superdough/superdough.mjs

@@ -40,6 +40,7 @@ export let maxPolyphony = DEFAULT_MAX_POLYPHONY;
  * start to die out in first-in-first-out order once the max polyphony has been hit
  *
  * @name setMaxPolyphony
+ * @tags fx, superdough
  * @param {number} Max polyphony. Defaults to 128
  * @example
  * setMaxPolyphony(4)
@@ -73,6 +74,7 @@ export function applyGainCurve(val) {
  * quadratic, exponential, etc. rather than linear
  *
  * @name setGainCurve
+ * @tags fx, superdough
  * @param {Function} function to apply to all gain values
  * @example
  * setGainCurve((x) => x * x) // quadratic gain
@@ -128,6 +130,8 @@ async function aliasBankPath(path) {
  * Optionally accepts a single argument string of a path to a JSON file containing bank aliases.
  * @param {string} bank - The bank to alias
  * @param {string} alias - The alias to use for the bank
+ *
+ * @tags samples
  */
 export async function aliasBank(...args) {
   switch (args.length) {
@@ -146,6 +150,7 @@ export async function aliasBank(...args) {
 
 /**
  * Register an alias for a sound.
+ * @tags samples
  * @param {string} original - The original sound name
  * @param {string} alias - The alias to use for the sound
  */

packages/superdough/util.mjs

@@ -110,7 +110,9 @@ export function getCommonSampleInfo(hapValue, bank) {
   return { transpose, url, index, midi, label };
 }
 
-/** Selects entries from `source` and renames them via `map` */
+/** Selects entries from `source` and renames them via `map`
+ * @tags internals
+ */
 export const pickAndRename = (source, map) => {
   return Object.fromEntries(Object.entries(map).map(([newKey, oldKey]) => [newKey, source[oldKey]]));
 };

packages/superdough/wavetable.mjs

@@ -186,6 +186,7 @@ export function registerWaveTable(key, tables, params) {
  * Loads a collection of wavetables to use with `s`
  *
  * @name tables
+ * @tags fx
  */
 export const tables = async (url, frameLen, json, options = {}) => {
   if (json !== undefined) return _processTables(json, url, frameLen);

packages/superdough/worklets.mjs

@@ -646,14 +646,18 @@ class PhaseVocoderProcessor extends OLAProcessor {
     this.timeCursor += this.hopSize;
   }
 
-  /** Apply Hann window in-place */
+  /** Apply Hann window in-place
+   * @tags internals
+   */
   applyHannWindow(input) {
     for (let i = 0; i < this.blockSize; i++) {
       input[i] *= this.hannWindow[i] * 1.62;
     }
   }
 
-  /** Compute squared magnitudes for peak finding **/
+  /** Compute squared magnitudes for peak finding
+   * @tags internals
+   **/
   computeMagnitudes() {
     let i = 0,
       j = 0;
@@ -667,7 +671,9 @@ class PhaseVocoderProcessor extends OLAProcessor {
     }
   }
 
-  /** Find peaks in spectrum magnitudes **/
+  /** Find peaks in spectrum magnitudes
+   * @tags internals
+   **/
   findPeaks() {
     this.nbPeaks = 0;
     let i = 2;
@@ -688,7 +694,9 @@ class PhaseVocoderProcessor extends OLAProcessor {
     }
   }
 
-  /** Shift peaks and regions of influence by pitchFactor into new specturm */
+  /** Shift peaks and regions of influence by pitchFactor into new specturm
+   * @tags internals
+   */
   shiftPeaks(pitchFactor) {
     // zero-fill new spectrum
     this.freqComplexBufferShifted.fill(0);
@@ -841,7 +849,9 @@ class PulseOscillatorProcessor extends AudioWorkletProcessor {
 
 registerProcessor('pulse-oscillator', PulseOscillatorProcessor);
 
-/**  BYTE BEATS */
+/**  BYTE BEATS
+ * @tags internals
+ */
 const chyx = {
   /*bit*/ bitC: function (x, y, z) {
     return x & y ? z : 0;

packages/supradough/dough.mjs

@@ -19,6 +19,7 @@ function applyGainCurve(val) {
  * @param {number} a - Signal A (can be a single value or an array value in buffer processing).
  * @param {number} b - Signal B (can be a single value or an array value in buffer processing).
  * @param {number} m - Crossfade parameter (0.0 = all A, 1.0 = all B, 0.5 = equal mix).
+ * @tags internals
  * @returns {number} Crossfaded output value.
  */
 function crossfade(a, b, m) {

packages/tonal/tonal.mjs

@@ -100,6 +100,7 @@ function scaleOffset(scale, offset, note) {
  * - 5P = perfect fifth
  * - 5d = diminished fifth
  *
+ * @tags music_theory
  * @param {string | number} amount Either number of semitones or interval string.
  * @returns Pattern
  * @memberof Pattern
@@ -154,6 +155,7 @@ export const { transpose, trans } = register(['transpose', 'trans'], function tr
  *
  * @memberof Pattern
  * @name scaleTranspose
+ * @tags music_theory
  * @param {offset} offset number of steps inside the scale
  * @returns Pattern
  * @synonyms scaleTrans, strans
@@ -244,6 +246,7 @@ function _getNearestScaleNote(scaleName, note, preferHigher = true) {
  * The root note defaults to octave 3, if no octave number is given.
  *
  * @name scale
+ * @tags music_theory
  * @param {string} scale Name of scale
  * @returns Pattern
  * @example

packages/tonal/voicings.mjs

@@ -90,6 +90,7 @@ export const setVoicingRange = (name, range) => addVoicings(name, voicingRegistr
  * Adds a new custom voicing dictionary.
  *
  * @name addVoicings
+ * @tags music_theory
  * @memberof Pattern
  * @param {string} name identifier for the voicing dictionary
  * @param {Object} dictionary maps chord symbol to possible voicings
@@ -133,6 +134,7 @@ const getVoicing = (chord, dictionaryName, lastVoicing) => {
  * Uses [chord-voicings package](https://github.com/felixroos/chord-voicings#chord-voicings).
  *
  * @name voicings
+ * @tags music_theory
  * @memberof Pattern
  * @param {string} dictionary which voicing dictionary to use.
  * @returns Pattern
@@ -157,6 +159,7 @@ export const voicings = register('voicings', function (dictionary, pat) {
  * Maps the chords of the incoming pattern to root notes in the given octave.
  *
  * @name rootNotes
+ * @tags music_theory
  * @memberof Pattern
  * @param {octave} octave octave to use
  * @returns Pattern
@@ -189,6 +192,7 @@ export const rootNotes = register('rootNotes', function (octave, pat) {
  * If you pass a pattern of strings to voicing, they will be interpreted as chords.
  *
  * @name voicing
+ * @tags music_theory
  * @returns Pattern
  * @example
  * n("0 1 2 3").chord("<C Am F G>").voicing()

packages/webaudio/scope.mjs

@@ -98,6 +98,7 @@ function clearScreen(smear = 0, smearRGB = `0,0,0`, ctx = getDrawContext()) {
 /**
  * Renders an oscilloscope for the frequency domain of the audio signal.
  * @name fscope
+ * @tags visualization
  * @param {string} color line color as hex or color name. defaults to white.
  * @param {number} scale scales the y-axis. Defaults to 0.25
  * @param {number} pos y-position relative to screen height. 0 = top, 1 = bottom of screen
@@ -122,6 +123,7 @@ Pattern.prototype.fscope = function (config = {}) {
  * Renders an oscilloscope for the time domain of the audio signal.
  * @name scope
  * @synonyms tscope
+ * @tags visualization
  * @param {object} config optional config with options:
  * @param {boolean} align if 1, the scope will be aligned to the first zero crossing. defaults to 1
  * @param {string} color line color as hex or color name. defaults to white.

packages/webaudio/spectrum.mjs

@@ -5,6 +5,7 @@ import { analysers, getAnalyzerData } from 'superdough';
 /**
  * Renders a spectrum analyzer for the incoming audio signal.
  * @name spectrum
+ * @tags visualization
  * @param {object} config optional config with options:
  * @param {integer} thickness line thickness in px (default 3)
  * @param {integer} speed scroll speed (default 1)

website/src/repl/components/panel/Reference.jsx

@@ -1,4 +1,4 @@
-import { memo, useMemo, useState } from 'react';
+import { memo, useEffect, useMemo, useState, Fragment } from 'react';
 
 import jsdocJson from '../../../../../doc.json';
 import { Textbox } from '../textbox/Textbox';
@@ -10,8 +10,16 @@ const availableFunctions = (() => {
   const functions = [];
   for (const doc of jsdocJson.docs) {
     if (!isValid(doc)) continue;
+    if (seen.has(doc.name)) continue;
+
+    // jsdoc also uses "tags" for when you use @something in the comments and it doesn't know what
+    // @something is. We only want data from comments like `@tags fx, superdough` here.
+    // If nothing is specified, we default to "untagged" for debugging
+    doc.tags = doc.tags?.filter((t) => t && typeof t === 'string') || ['untagged'];
     functions.push(doc);
+
     const synonyms = doc.synonyms || [];
+    seen.add(doc.name);
     for (const s of synonyms) {
       if (!s || seen.has(s)) continue;
       seen.add(s);
@@ -37,9 +45,25 @@ const getInnerText = (html) => {
 
 export const Reference = memo(function Reference() {
   const [search, setSearch] = useState('');
+  const [selectedTag, setSelectedTag] = useState(null);
+  const [selectedFunction, setSelectedFunction] = useState(null);
 
-  const visibleFunctions = useMemo(() => {
+  const toggleTag = (tag) => {
+    if (selectedTag === tag) {
+      setSelectedTag(null);
+    } else {
+      setSelectedTag(tag);
+    }
+  };
+
+  const searchVisibleFunctions = useMemo(() => {
     return availableFunctions.filter((entry) => {
+      if (selectedTag) {
+        if (!(entry.tags || ['untagged']).includes(selectedTag)) {
+          return false;
+        }
+      }
+
       if (!search) {
         return true;
       }
@@ -50,43 +74,128 @@ export const Reference = memo(function Reference() {
         (entry.synonyms?.some((s) => s.toLowerCase().includes(lowerCaseSearch)) ?? false)
       );
     });
-  }, [search]);
+  }, [search, selectedTag]);
+
+  const detailVisibleFunctions = useMemo(() => {
+    return searchVisibleFunctions.filter((x) => {
+      if (selectedTag === null) {
+        if (search) {
+          return true;
+        }
+        return x.name === selectedFunction;
+      } else {
+        return true;
+      }
+    });
+  }, [searchVisibleFunctions, selectedFunction, selectedTag]);
+
+  const tagCounts = {};
+  for (const doc of availableFunctions) {
+    (doc.tags || ['untagged']).forEach((t) => {
+      if (typeof t === 'string' && t) {
+        tagCounts[t] = (tagCounts[t] || 0) + 1;
+      }
+    });
+  }
+
+  const onSearchTagFilterClick = () => {
+    setSelectedTag(null);
+    setSelectedFunction(null);
+  };
+
+  useEffect(() => {
+    if (selectedFunction) {
+      const el = document.getElementById(`doc-${selectedFunction}`);
+      const container = document.getElementById('reference-container');
+      container.scrollTo(0, el.offsetTop);
+    }
+  }, [selectedFunction]);
 
   return (
     <div className="flex h-full w-full p-2 overflow-hidden">
-      <div className="h-full  flex flex-col gap-2 w-1/3 max-w-72 ">
+      <div className="h-full text-foreground flex flex-col gap-3 w-1/3 ">
         <div className="w-full flex">
-          <Textbox className="w-full" placeholder="Search" value={search} onChange={setSearch} />
+          <Textbox
+            className="w-full"
+            placeholder="Search"
+            value={search}
+            onChange={(e) => {
+              setSelectedFunction(null);
+              setSearch(e);
+            }}
+          />
         </div>
-        <div className="flex flex-col h-full overflow-y-auto  gap-1.5 bg-background bg-opacity-50  rounded-md">
+        {selectedTag && (
-          {visibleFunctions.map((entry, i) => (
+          <div className="w-72">
-            <a
+            <span
-              key={i}
+              className="text-foreground border-2 border-gray-500 px-1 py-0.5 my-2 rounded-md cursor-pointer font-sans"
-              className="cursor-pointer text-foreground flex-none hover:bg-lineHighlight overflow-x-hidden  px-1 text-ellipsis"
+              onClick={onSearchTagFilterClick}
-              onClick={() => {
-                const el = document.getElementById(`doc-${i}`);
-                const container = document.getElementById('reference-container');
-                container.scrollTo(0, el.offsetTop);
-              }}
             >
-              {entry.name} {/* <span className="text-gray-600">{entry.meta.filename}</span> */}
+              {selectedTag}
-            </a>
+            </span>
+          </div>
+        )}
+        <div className="flex flex-col h-full overflow-y-auto gap-1.5 bg-background bg-opacity-50 rounded-md">
+          {searchVisibleFunctions.map((entry, i) => (
+            <Fragment key={`entry-${entry.name}`}>
+              <a
+                className={
+                  'cursor-pointer flex-none hover:bg-lineHighlight overflow-x-hidden px-1 text-ellipsis ' +
+                  (entry.name === selectedFunction ? 'bg-lineHighlight font-bold' : '')
+                }
+                onClick={() => {
+                  if (entry.name === selectedFunction) {
+                    setSelectedFunction(null);
+                  } else {
+                    setSelectedFunction(entry.name);
+                  }
+                }}
+              >
+                {entry.name}
+              </a>{' '}
+            </Fragment>
           ))}
         </div>
       </div>
       <div
-        className="break-normal flex-grow flex-col overflow-y-auto overflow-x-hidden   px-2 flex relative"
+        className="break-normal flex-col overflow-y-auto overflow-x-hidden p-2 flex relative"
         id="reference-container"
       >
         <div className="prose dark:prose-invert min-w-full px-1 ">
           <h2>API Reference</h2>
-          <p>
+          <p className="font-sans text-md">
             This is the long list of functions you can use. Remember that you don't need to remember all of those and
             that you can already make music with a small set of functions!
           </p>
-          {visibleFunctions.map((entry, i) => (
+          <div>
-            <section key={i}>
+            {Object.entries(tagCounts)
-              <h3 id={`doc-${i}`}>{entry.name}</h3>
+              .sort(([a], [b]) => a.localeCompare(b))
+              .map(([t, count]) => (
+                <span key={t}>
+                  <a
+                    className={[
+                      'select-none text-white border-2 border-gray-500 px-1 py-0.5 my-2 cursor-pointer text-sm/8 rounded-md no-underline font-sans',
+                      `${selectedTag === t ? 'bg-gray-500 text-black' : ''}`,
+                    ].join(' ')}
+                    onClick={() => toggleTag(t)}
+                  >
+                    {t}&nbsp;({count})
+                  </a>{' '}
+                </span>
+              ))}
+          </div>
+          {detailVisibleFunctions.map((entry, i) => (
+            <section key={i} className="font-sans">
+              <div className="flex flex-row items-center mt-8 justify-between">
+                <h3 className="font-mono my-0" id={`doc-${entry.name}`}>
+                  {entry.name}
+                </h3>
+                {entry.tags && (
+                  <span className="ml-2 text-xs text-gray-400 border-2 border-gray-500 rounded-md px-1 py-0.5">
+                    {entry.tags.join(', ')}
+                  </span>
+                )}
+              </div>
               {!!entry.synonyms_text && (
                 <p>
                   Synonyms: <code>{entry.synonyms_text}</code>
@@ -107,7 +216,8 @@ export const Reference = memo(function Reference() {
                 </pre>
               ))}
             </section>
-          ))}
+          )) || <p className="font-sans">Searcb or select a tag to get started.</p>}
+          {detailVisibleFunctions.length > 0 && <div className="h-screen" />}
         </div>
       </div>
     </div>