adding some documentation

index.html

@@ -155,6 +155,7 @@
             <div class="space-y-2">
               <h2 class="font-semibold lg:text-xl text-gray-400">More</h2>
               <div class="flex flex-col">
+                <a rel="noopener noreferrer" id="docs_bonus" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Bonus/Trivia</a>
                 <a rel="noopener noreferrer" id="docs_about" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">About Topos</a>
               </div>
             </div>

src/Documentation.ts

@@ -14,6 +14,7 @@ import { functions } from "./documentation/functions";
 import { ziffers } from "./documentation/ziffers";
 import { reference } from "./documentation/reference";
 import { synths } from "./documentation/synths";
+import { bonus } from "./documentation/bonus";
 
 export const key_shortcut = (shortcut: string): string => {
   return `<kbd class="lg:px-2 lg:py-1.5 px-1 py-1 lg:text-sm text-xs font-semibold text-gray-800 bg-gray-100 border border-gray-200 rounded-lg dark:bg-gray-600 dark:text-gray-100 dark:border-gray-500">${shortcut}</kbd>`;
@@ -64,6 +65,7 @@ export const documentation_factory = (application: Editor) => {
     functions: functions(application),
     reference: reference(),
     shortcuts: shortcuts(),
+    bonus: bonus(application),
     about: about(),
   };
 };

src/documentation/bonus.ts

@@ -0,0 +1,48 @@
+import { type Editor } from "../main";
+import { key_shortcut, makeExampleFactory } from "../Documentation";
+
+export const bonus = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+
+  return `
+# Bonus features
+
+Some features are not part of the core of Topos but are still very useful. They are not described in the main documentation but are still available in the API. These features are sometimes coming from personal experiments, from a thinking-out-loud process or from a sudden desire to hack things. This bonus set of functionalities is not guaranteed to be stable.
+
+## Hydra Visual Live Coding
+
+<div class="mx-12 bg-neutral-600 rounded-lg flex flex-col items-center justify-center">
+<warning>⚠️ This feature can generate flashing images that could trigger photosensitivity or epileptic seizures. ⚠️ </warning>
+</div>
+
+[Hydra](https://hydra.ojack.xyz/?sketch_id=mahalia_1) is a popular live-codable video synthesizer developed by [Olivia Jack](https://ojack.xyz/) and other contributors. It follows the metaphor of analog synthesizer patching to allow its user to create complex live visuals from a web browser window. Being very easy to use, extremely powerful and also very rewarding to use, Hydra has become a popular choice for adding visuals into a live code performance. Topos provides a simple way to integrate Hydra into a live coding session and to blend it with regular Topos code.
+
+${makeExample(
+  "Hydra integration",
+  `mod(4) :: app.hydra.osc(3, 0.5, 2).out()`,
+  true
+)}
+
+You may feel like it's doing nothing! Press ${key_shortcut(
+    "Ctrl+D"
+  )} to close the documentation. **Boom, all shiny!**
+
+Be careful not to call <ic>app.hydra</ic> too often as it can impact performances. You can use any rhythmical function like <ic>mod()</ic> function to limit the number of function calls. You can write any Topos code like <ic>[1,2,3].beat()</ic> to bring some life and movement in your Hydra sketches.
+
+Stopping **Hydra** is simple:
+
+${makeExample(
+  "Stopping Hydra",
+  `
+mod(4) :: stop_hydra()     // this one
+mod(4) :: app.hydra.hush() // or this one
+`,
+  true
+)}
+
+I won't teach you how to play with Hydra. You can find some great resources on the [Hydra website](https://hydra.ojack.xyz/):
+  - [Hydra interactive documentation](https://hydra.ojack.xyz/docs/)
+  - [List of Hydra Functions](https://hydra.ojack.xyz/api/)
+  - [Source code on GitHub](https://github.com/hydra-synth/hydra)
+`;
+};

src/documentation/samples.ts

@@ -1,4 +1,5 @@
 import { type Editor } from "../main";
+import { makeExampleFactory } from "../Documentation";
 
 export const samples_to_markdown = (application: Editor) => {
   let samples = application.api._all_samples();
@@ -42,19 +43,35 @@ export const injectAvailableSamples = (application: Editor): string => {
 };
 
 export const samples = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
   return `
 # Audio Samples
 	
-Audio samples are dynamically loaded from the web. By default, Topos is providing some samples coming from the classic [Dirt-Samples](https://github.com/tidalcycles/Dirt-Samples) but also from the [Topos-Samples](https://github.com/Bubobubobubobubo/Topos-Samples) repository. You can contribute to the latter if you want to share your samples with the community! For each sample folder, we are indicating how many of them are available in parentheses.
-
-The samples starting with <ic>ST</ic> are coming from [this wonderful collection](https://archive.org/details/AmigaSoundtrackerSamplePacksst-xx) of Ultimate Tracker Amiga audio samples released by Karsten Obarski. They are very high-pitched as was usual in the tracker era. Pitch them down using <ic>.speed(0.5)</ic>.
+Audio samples are dynamically loaded from the web. By default, Topos is providing some samples coming from the classic [Dirt-Samples](https://github.com/tidalcycles/Dirt-Samples) but also from the [Topos-Samples](https://github.com/Bubobubobubobubo/Topos-Samples) repository. You can contribute to the latter if you want to share your samples with the community! For each sample folder, we are indicating how many of them are available in parentheses. The samples starting with <ic>ST</ic> are coming from [a wonderful collection](https://archive.org/details/AmigaSoundtrackerSamplePacksst-xx) of Ultimate Tracker Amiga audio samples released by Karsten Obarski. They are very high-pitched as was usual in the tracker era. Pitch them down using <ic>.speed(0.5)</ic>.
 
 ## Available audio samples
-
 	
 <b class="flex lg:pl-6 lg:pr-6 text-bold mb-8">Samples can take a few seconds to load. Please wait if you are not hearing anything. Lower your volume, take it slow. Some sounds might be harsh.</b>
-<div class="lg:pl-6 lg:pr-6 inline-block w-fit flex flex-row flex-wrap gap-x-2 gap-y-2">
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
 ${injectAvailableSamples(application)}
 </div>
+
+# Loading your own samples
+
+Topos is exposing the <ic>samples</ic> function that you can use to load your own set of samples. Samples are loaded on-the-fly from the web. Topos is a web application living in the browser. It is running in a sandboxed environment. Thus, it cannot have access to the files stored on your local system. Loading samples requires building a _map_ of the audio files, where a name is associated to a specific file:
+
+${makeExample(
+  "This is how Topos is loading its own samples",
+  `
+// Visit the concerned repos and search for 'strudel.json'
+samples("github:tidalcycles/Dirt-Samples/master");
+samples("github:Bubobubobubobubo/Dough-Samples/main");
+samples("github:Bubobubobubobubo/Dough-Amiga/main");
+`,
+  true
+)}
+
+To learn more about the audio sample loading mechanism, please refer to [this page](https://strudel.tidalcycles.org/learn/samples) written by Felix Roos who has implemented the sample loading mechanism. The API is absolutely identic in Topos!
+
 `;
 };

src/main.ts

@@ -37,6 +37,8 @@ const classMap = {
   ul: "text-underline pl-6",
   li: "list-disc lg:text-2xl text-base text-white lg:mx-4 mx-2 my-4 my-2 leading-normal",
   p: "lg:text-2xl text-base text-white lg:mx-6 mx-2 my-4 leading-normal",
+  warning:
+    "animate-pulse lg:text-2xl font-bold text-rose-600 lg:mx-6 mx-2 my-4 leading-normal",
   a: "lg:text-2xl text-base text-orange-300",
   code: "lg:my-4 sm:my-1 text-base lg:text-xl block whitespace-pre overflow-x-hidden",
   icode:
@@ -621,6 +623,7 @@ export class Editor {
       // "reference",
       "shortcuts",
       "about",
+      "bonus",
     ].forEach((e) => {
       let name = `docs_` + e;
       document.getElementById(name)!.addEventListener("click", async () => {