astro-abcjs 1.0.0 → 2.0.0

package/README.md

@@ -1,11 +1,51 @@
+
 # astro-abcjs
 
 An abcjs component for Astro projects.
 
-## Credits & Inspiration
+## Usage
+
+### In .astro files
+
+Import the component and use it in your Astro page or component:
+
+```astro
+---
+import AbcjsPlayer from 'astro-abcjs/AbcjsPlayer.astro';
+---
+
+<AbcjsPlayer
+  notation={`X:1\nT:Scale\nM:4/4\nK:C\nC D E F | G A B c |`}
+  showControls={true}
+  responsive={true}
+  abcjsVersion="6.6.0"
+/>
+```
+
+### In MDX files
 
-This component was inspired by the article:
+First, make sure your project supports MDX and components in MDX.
+
+Import the component at the top of your MDX file:
+
+```mdx
+import AbcjsPlayer from 'astro-abcjs/AbcjsPlayer.astro';
+
+<AbcjsPlayer
+  notation={`X:1\nT:Scale\nM:4/4\nK:C\nC D E F | G A B c |`}
+  showControls={true}
+  responsive={true}
+  abcjsVersion="6.6.0"
+/>
+```
+
+#### Props
+
+- `notation` (string, required): The ABC notation string to render.
+- `showControls` (boolean, default: true): Show audio playback controls.
+- `responsive` (boolean, default: true): Make the notation responsive to container size.
+- `abcjsVersion` (string, optional, default: "6.6.0"): The abcjs version to load from CDN. Override to pin or upgrade/downgrade.
+
+## Credits & Inspiration
 
-**Building a Reusable Music Component in Astro using ABCjs**  
-by [Pavlin Gunov](https://www.pavlinbg.com/)  
-<https://www.pavlinbg.com/posts/building-a-reusable-music-component-in-astro-using-abcjs>
+This component was inspired by the article [Building a Reusable Music Component in Astro using ABCjs](https://www.pavlinbg.com/posts/building-a-reusable-music-component-in-astro-using-abcjs) by [Pavlin Gunov](https://www.pavlinbg.com/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-abcjs",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "An Astro component to embed abcjs in content",
   "keywords": [
     "astro",

package/src/components/AbcjsPlayer.astro

@@ -1,74 +1,101 @@
 ---
 // AbcjsPlayer.astro
 // Reusable Astro component for rendering ABCjs music notation and audio playback
+
 import "abcjs/abcjs-audio.css";
 
+// Use official abcjs types
+import type { AbcVisualParams } from "abcjs";
+
+// Props interface using official abcjs types
 interface Props {
   notation: string;
+  /**
+   * Options for abcjs.renderAbc (see AbcVisualParams in abcjs types)
+   * Note: Function callbacks (e.g., clickListener) are not supported as options
+   * are serialized to JSON for client-side use. For advanced interactivity, use
+   * custom events or request a callback/event API.
+   */
+  options?: AbcVisualParams;
+  /**
+   * Show audio playback controls (default: true)
+   */
   showControls?: boolean;
-  responsive?: boolean;
+  /**
+   * abcjs version to load from CDN (default: "6.6.0")
+   */
+  abcjsVersion?: string;
 }
 
-const { notation, showControls = true, responsive = true } = Astro.props;
+const {
+  notation,
+  options = {},
+  showControls = true,
+  abcjsVersion = "6.6.0",
+} = Astro.props;
 ---
 
 <div
   class="abcjs-container"
   data-notation={notation}
-  data-responsive={responsive}
+  data-options={JSON.stringify(options)}
 >
-  <div id="paper" class="abcjs-paper"></div>
-  {showControls && <div id="audio" class="abcjs-audio" />}
+  <div class="abcjs-paper"></div>
+  {showControls && <div class="abcjs-audio" />}
 </div>
 
-<script>
+<script define:vars={{ abcjsVersion, options }}>
   if (typeof window !== "undefined") {
-    import("abcjs").then((abcjs) => {
-      function initializeAbcjs() {
-        const containers = document.querySelectorAll(".abcjs-container");
-        containers.forEach((container) => {
-          if (container.dataset.abcjsInitialized === "true") return;
-          const notation = container.getAttribute("data-notation");
-          if (!notation) return;
-          const isResponsive =
-            container.getAttribute("data-responsive") === "true";
-          const paperDiv = container.querySelector("#paper");
-          const audioDiv = container.querySelector("#audio");
-          // Render music notation
-          const visualObj = abcjs.default.renderAbc(paperDiv, notation, {
-            responsive: isResponsive ? "resize" : undefined,
-            add_classes: true,
-            paddingleft: 0,
-            paddingright: 0,
-            paddingbottom: 10,
-            paddingtop: 10,
+    // Load abcjs browser build from CDN if not already loaded
+    if (!window.ABCJS) {
+      const script = document.createElement("script");
+      script.src = `https://cdn.jsdelivr.net/npm/abcjs@${abcjsVersion}/dist/abcjs-basic.js`;
+      script.onload = initializeAbcjs;
+      document.head.appendChild(script);
+    } else {
+      initializeAbcjs();
+    }
+
+    function initializeAbcjs() {
+      const abcjs = window.ABCJS;
+      if (!abcjs) return;
+      const containers = document.querySelectorAll(".abcjs-container");
+      containers.forEach((container) => {
+        if (container.dataset.abcjsInitialized === "true") return;
+        const notation = container.getAttribute("data-notation");
+        if (!notation) return;
+        const paperDiv = container.querySelector(".abcjs-paper");
+        const audioDiv = container.querySelector(".abcjs-audio");
+        // Render music notation using options prop (passed via define:vars)
+        // Render music notation using per-container options
+        const containerOptions = JSON.parse(
+          container.getAttribute("data-options") || "{}",
+        );
+        const visualObj = abcjs.renderAbc(paperDiv, notation, containerOptions);
+        // Audio playback controls
+        if (audioDiv && abcjs.synth) {
+          const synthControl = new abcjs.synth.SynthController();
+          synthControl.load(audioDiv, null, {
+            displayLoop: true,
+            displayRestart: true,
+            displayPlay: true,
+            displayProgress: true,
+            displayWarp: true,
           });
-          // Audio playback controls
-          if (audioDiv) {
-            const synthControl = new abcjs.default.synth.SynthController();
-            synthControl.load(audioDiv, null, {
-              displayLoop: true,
-              displayRestart: true,
-              displayPlay: true,
-              displayProgress: true,
-              displayWarp: true,
+          const createSynth = new abcjs.synth.CreateSynth();
+          createSynth
+            .init({ visualObj: visualObj[0] })
+            .then(() => {
+              synthControl.setTune(visualObj[0], false);
+            })
+            .catch((error) => {
+              console.warn("Audio synthesis initialization failed:", error);
             });
-            const createSynth = new abcjs.default.synth.CreateSynth();
-            createSynth
-              .init({ visualObj: visualObj[0] })
-              .then(() => {
-                synthControl.setTune(visualObj[0], false);
-              })
-              .catch((error) => {
-                console.warn("Audio synthesis initialization failed:", error);
-              });
-          }
-          container.dataset.abcjsInitialized = "true";
-        });
-      }
-      initializeAbcjs();
-      document.addEventListener("astro:page-load", initializeAbcjs);
-    });
+        }
+        container.dataset.abcjsInitialized = "true";
+      });
+    }
+    document.addEventListener("astro:page-load", initializeAbcjs);
   }
 </script>