Merge pull request #17 from riyaddecoder/feat/doc-update-add-ref

feat: doc updated, added ref

Author: riyaddecoder

documentation/docs/.vitepress/components/AudioPlayerRefExample.vue

@@ -0,0 +1,43 @@
+<template>
+  <div ref="el" />
+</template>
+
+<script setup>
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ref, onMounted, defineProps } from 'vue';
+import AudioPlayerWithRef from './AudioPlayerWithRef.jsx';
+
+const props = defineProps({
+  src: {
+    type: String,
+    required: true
+  }
+});
+
+const el = ref();
+
+onMounted(() => {
+  const root = createRoot(el.value);
+  root.render(createElement(AudioPlayerWithRef, { ...props }));
+});
+</script>
+<style>
+.audio-example-with-ref button {
+  padding: 1px 10px;
+  background: white;
+  color: black;
+  border-radius: 5px;
+  margin-right: 3px;
+  margin-top: 5px;
+  box-shadow: 1px 1px 8px 3px #ececec;
+}
+
+.dark .audio-example-with-ref button {
+  box-shadow: none;
+}
+
+.audio-example-with-ref button:hover {
+  background: #ddd;
+}
+</style>

documentation/docs/.vitepress/components/AudioPlayerWithRef.jsx

@@ -0,0 +1,32 @@
+import React, { useRef } from 'react';
+import { AudioPlayer } from 'react-audio-play';
+
+export default function AudioPlayerWithRef(props) {
+  const playerRef = useRef(null);
+
+  const handlePlay = () => {
+    playerRef.current?.play();
+  };
+
+  const handlePause = () => {
+    playerRef.current?.pause();
+  };
+
+  const handleStop = () => {
+    playerRef.current?.stop();
+  };
+
+  const handleFocus = () => {
+    playerRef.current?.focus();
+  };
+
+  return (
+    <div className='audio-example-with-ref'>
+      <AudioPlayer ref={playerRef} src={props.src} />
+      <button onClick={handlePlay}>Play</button>
+      <button onClick={handlePause}>Pause</button>
+      <button onClick={handleStop}>Stop</button>
+      <button onClick={handleFocus}>Focus</button>
+    </div>
+  );
+}

documentation/docs/examples.md

@@ -81,7 +81,51 @@ Preview
 
 <small>Music Source: <a :href="music.getCurrentMusic().sourceLink" target="_blank">{{music.getCurrentMusic().title}}</a></small>
 
-## Example 4: Darkmode using basic style props
+## Example 4: Usage with ref (available from v1.0.4)
+
+```tsx
+import { useRef } from 'react';
+import { AudioPlayer, AudioPlayerRef } from 'react-audio-play';
+
+function App() {
+  const playerRef = useRef<AudioPlayerRef>(null);
+
+  const handlePlay = () => {
+    playerRef.current?.play();
+  };
+
+  const handlePause = () => {
+    playerRef.current?.pause();
+  };
+
+  const handleStop = () => {
+    playerRef.current?.stop();
+  };
+
+  const handleFocus = () => {
+    playerRef.current?.focus();
+  };
+
+  return (
+    <div>
+      <AudioPlayer ref={playerRef} src="path/to/audio.mp3" autoPlay />
+      <button onClick={handlePlay}>Play</button>
+      <button onClick={handlePause}>Pause</button>
+      <button onClick={handleStop}>Stop</button>
+      <button onClick={handleFocus}>Focus</button>
+    </div>
+  );
+}
+
+```
+
+Preview
+
+<AudioPlayerRefExample :src="music.nextMusic().url"/>
+
+<small>Music Source: <a :href="music.getCurrentMusic().sourceLink" target="_blank">{{music.getCurrentMusic().title}}</a></small>
+
+## Example 5: Darkmode using basic style props
 
 ```js
 import { AudioPlayer } from "react-audio-play";
@@ -104,7 +148,7 @@ Preview
 
 <small>Music Source: <a :href="music.getCurrentMusic().sourceLink" target="_blank">{{music.getCurrentMusic().title}}</a></small>
 
-## Example 5: Using Style Object
+## Example 6: Using Style Object
 
 ```js
 import { AudioPlayer } from "react-audio-play";
@@ -127,7 +171,7 @@ Preview
 
 <small>Music Source: <a :href="music.getCurrentMusic().sourceLink" target="_blank">{{music.getCurrentMusic().title}}</a></small>
 
-## Example 6: Using Custom CSS
+## Example 7: Using Custom CSS
 
 ::: code-group
 
@@ -183,7 +227,7 @@ Preview
 
 <small>Music Source: <a :href="music.getCurrentMusic().sourceLink" target="_blank">{{music.getCurrentMusic().title}}</a></small>
 
-## Example 7: More Playing With CSS
+## Example 8: More Playing With CSS
 
 ::: code-group
 
@@ -255,6 +299,7 @@ Preview
 <script setup>
 import { Music } from './.vitepress/lib/Music.ts';
 import AudioPlayerWrapper from './.vitepress/components/AudioPlayerWrapper.vue'; 
+import AudioPlayerRefExample from './.vitepress/components/AudioPlayerRefExample.vue'; 
 
 const music = new Music();
 </script>

documentation/docs/index.md

@@ -52,6 +52,20 @@ The **AudioPlayer** component accepts the following props:
 | `width`         | string, optional     | The width of the audio player. For example, `"100%"`, `"300px"`, etc.                          |
 | `style`         | object, optional     | An object containing additional inline styles for the component.                               |
 
+
+## Advanced Usage
+
+Starting with version `v1.0.4`, you can access certain actions of the `AudioPlayer` component programmatically using a `ref` with the following interface:
+
+- `play`: Function to start audio playback.
+- `pause`: Function to pause audio playback.
+- `stop`: Function to stop the audio playback.
+- `focus`: Function to focus on the audio player component.
+
+::: info  
+[Example Here](/examples.html#example-4-usage-with-ref-available-from-v1-0-4)
+:::
+
 ## Keyboard Shortcuts
 
 Below are the keyboard shortcuts available when the audio player is focused. They can be turned off by setting the `hasKeyBindings` prop to `false`.