react-modern-audio-player 2.0.0 → 2.2.0

package/README.md

@@ -1,7 +1,7 @@
 <!-- markdownlint-disable MD033 MD041 MD028 -->
 
 <p align="center">
-<img width="20%" src="https://user-images.githubusercontent.com/70849655/180391190-2b268d23-c9f3-4e95-9fce-090897842c04.png" alt="rm-audio-player" />
+<img width="12%" src="https://raw.githubusercontent.com/slash9494/react-modern-audio-player/main/package/assets/icon.png" alt="rm-audio-player" />
 <h1 align="center">React Modern Audio Player</h1>
 </p>
 
@@ -15,31 +15,58 @@
   <a href="https://www.npmjs.com/package/react-modern-audio-player">
     <img src="https://img.shields.io/npm/dt/react-modern-audio-player" alt="Download">
   </a>
-  <a href="https://bundlephobia.com/package/react-modern-audio-player@0.0.3">
+  <a href="https://bundlephobia.com/package/react-modern-audio-player">
     <img src="https://img.shields.io/bundlephobia/minzip/react-modern-audio-player" alt="BundleSize">
   </a>
+  <a href="https://github.com/slash9494/react-modern-audio-player/actions/workflows/integration.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/slash9494/react-modern-audio-player/integration.yml?branch=main&label=CI" alt="CI">
+  </a>
+  <img src="https://img.shields.io/badge/TypeScript-first-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
 </p>
 
+## Highlights
+
+- **Waveform** progress bar powered by `wavesurfer.js`
+- **Playlist** with drag-and-drop reorder, repeat, shuffle
+- **Fully customizable** — swap any sub-component, CSS variable theming, light & dark themes
+- **Compound slots** — `AudioPlayer.Volume`, `AudioPlayer.Progress`, `AudioPlayer.PlayList`, etc. for partial customization without losing the preset
+- **Multi-instance playlist** — render multiple players on the same page with isolated playlist drawers and fully independent audio state
+- **Accessible** — WAI-ARIA patterns, full keyboard navigation, axe-tested
+- **TypeScript-first** — typed props and hooks (`useAudioPlayer`, sub-hooks)
+- **SSR-friendly** — works with Next.js App Router / Server Components
+
 ## DEMO
 
-<https://codesandbox.io/s/basic-91y82y?file=/src/App.tsx>
+<https://codesandbox.io/p/sandbox/basic-nfrpfq>
 
 # **Flexible and Customizable UI**
 
-## This can offer waveform by `wavesurfer.js`
+## Waveform progress with `wavesurfer.js`
+
+<img width="100%" src="https://raw.githubusercontent.com/slash9494/react-modern-audio-player/main/package/assets/screenshots/waveform-light.png" alt="Waveform view" />
+
+## Customizable layout and placement — with light & dark themes
 
-<img width="100%" src="https://user-images.githubusercontent.com/70849655/180435472-f043dbb4-54df-43e0-bc5c-67492510e817.png" alt="">
+### Full View
 
-## This can offer various UI and you can also customize each component position
+<p align="center">
+  <img width="49%" src="https://raw.githubusercontent.com/slash9494/react-modern-audio-player/main/package/assets/screenshots/full-view-light.png" alt="Full view — light" />
+  <img width="49%" src="https://raw.githubusercontent.com/slash9494/react-modern-audio-player/main/package/assets/screenshots/full-view-dark.png" alt="Full view — dark" />
+</p>
 
-> Full View
-> <img width="100%" src="https://user-images.githubusercontent.com/70849655/180435489-263fae23-f066-4a37-a524-58918eb40b0c.png" alt="">
+### Position Change
 
-> Position Change
-> <img width="110%" src="https://user-images.githubusercontent.com/70849655/180435493-2c2e08c5-b67b-4ab7-aded-5a0403d42050.png" alt="">
+<p align="center">
+  <img width="49%" src="https://raw.githubusercontent.com/slash9494/react-modern-audio-player/main/package/assets/screenshots/position-change-light.png" alt="Position change — light" />
+  <img width="49%" src="https://raw.githubusercontent.com/slash9494/react-modern-audio-player/main/package/assets/screenshots/position-change-dark.png" alt="Position change — dark" />
+</p>
 
-> Particular View
-> <br/> > <img width="50%" margin='10px' src="https://user-images.githubusercontent.com/70849655/180435497-0f839cd1-e1fd-400f-a013-82ba441ca79b.png" alt=""> > <img width="20%" margin='10px' src="https://user-images.githubusercontent.com/70849655/180435479-4f056620-f850-4d21-ab23-24efc4300d68.png" alt=""> > <br/> > <img width="20%" margin='10px' src="https://user-images.githubusercontent.com/70849655/180435484-3331b7cb-1555-4ffb-a36c-a5343f72c8c3.png" alt=""> > <img width="50%" margin='10px' src="https://user-images.githubusercontent.com/70849655/180435486-2402ba80-7121-410c-9a06-9a737be72ec2.png" alt="">
+### Particular View
+
+<p align="center" style="display:flex; gap: 10%;">
+  <img width="39%" src="https://raw.githubusercontent.com/slash9494/react-modern-audio-player/main/package/assets/screenshots/particular-view-dark.png" alt="Particular view — compact compound" />
+  <img width="10%" height="50%" src="https://raw.githubusercontent.com/slash9494/react-modern-audio-player/main/package/assets/screenshots/particular-view-play-only-dark.png" alt="Particular view — play button only" />
+</p>
 
 # **Installation**
 
@@ -83,7 +110,13 @@ This library includes the `'use client'` directive and can be imported directly
 import AudioPlayer from "react-modern-audio-player";
 
 const playList = [
-  { name: "track", writer: "artist", img: "cover.jpg", src: "audio.mp3", id: 1 },
+  {
+    name: "track",
+    writer: "artist",
+    img: "cover.jpg",
+    src: "audio.mp3",
+    id: 1,
+  },
 ];
 
 export default function Page() {
@@ -123,7 +156,9 @@ export default function PlayerPage() {
 | **Props**            | [PlayList](#playlist) · [InitialStates](#initialstates) · [ActiveUI](#activeui) · [Placement](#placement) · [RootContainerProps](#rootcontainerprops) |
 | **Override & Style** | [CustomIcons](#customicons) · [CoverImgsCss](#coverimgscss) · [Theme mode](#theme-mode-dark-mode) · [ID & Classnames](#id--classnames)                |
 | **Player Hook API**  | [useAudioPlayer](#useaudioplayer) · [AudioPlayerControls](#audioplayercontrols) · [Sub-Hooks](#sub-hooks)                                             |
-| **Custom Component** | [Custom Component](#custom-component)                                                                                                                 |
+| **Custom Component** | [Custom Component](#custom-component) · [Compound Slots](#compound-slots)                                                                             |
+| **Accessibility**    | [Keyboard support](#keyboard-support)                                                                                                                 |
+| **Gotchas**          | [Gotchas](#gotchas)                                                                                                                                   |
 | **Example**          | [Example](#example)                                                                                                                                   |
 
 # Props
@@ -173,6 +208,26 @@ type AudioData = {
 };
 ```
 
+### Empty playlist handling
+
+Passing `playList={[]}` renders the player in an empty state without crashing. This is useful while waiting for asynchronous track data:
+
+```tsx
+function App() {
+  const [tracks, setTracks] = useState<PlayList>([]);
+
+  useEffect(() => {
+    fetchTracks().then(setTracks);
+  }, []);
+
+  // Safe — the player mounts with no audio source and activates once tracks arrive.
+  return <AudioPlayer playList={tracks} />;
+}
+```
+
+- When the playlist becomes empty after updates, playback stops and all time state resets.
+- When `audioInitialState.curPlayId` doesn't match any track in the current list, the player falls back to `playList[0]` automatically.
+
 ## InitialStates
 
 ```tsx
@@ -186,9 +241,12 @@ type InitialStates = Omit<
   currentTime?: number;
   duration?: number;
   curPlayId: number;
+  playListExpanded?: boolean;
 };
 ```
 
+> `playListExpanded: true` opens the playlist drawer on mount. Consistent with the other fields on `audioInitialState`, this is read once at mount and is not tracked in reducer state.
+
 ## ActiveUI
 
 ```tsx
@@ -327,6 +385,12 @@ const defaultInterfacePlacement = {
 
 - rm-audio-player
 
+> **Multi-instance note**: when multiple `<AudioPlayer>` instances share a
+> page the root `id` is duplicated across them. Playlist and audio state are
+> still isolated per instance (each player has its own React provider tree
+> and its own `<audio>` DOM node). If you need per-instance selectors, target
+> via the class names below rather than the id.
+
 ### root ClassName
 
 - rmap-player-provider
@@ -389,8 +453,7 @@ function PlayerControls() {
       <button onClick={() => setVolume(0.5)}>Volume 50%</button>
       <button onClick={() => setTrack(1)}>Track 2</button>
       <p>
-        {currentTrack?.name} — {currentTime.toFixed(0)}s / {duration.toFixed(0)}
-        s
+        {currentTrack?.name} — {currentTime.toFixed(0)}s / {duration.toFixed(0)}s
       </p>
     </div>
   );
@@ -451,17 +514,21 @@ function PlayButton() {
 // Only re-renders on time updates
 function TimeDisplay() {
   const { currentTime, duration } = useAudioPlayerTime();
-  return <span>{currentTime.toFixed(0)}s / {duration.toFixed(0)}s</span>;
+  return (
+    <span>
+      {currentTime.toFixed(0)}s / {duration.toFixed(0)}s
+    </span>
+  );
 }
 ```
 
-| Hook                       | Returns                                                                         |
-| -------------------------- | ------------------------------------------------------------------------------- |
-| `useAudioPlayerPlayback`   | `{ isPlaying, repeatType, play, pause, togglePlay }`                            |
-| `useAudioPlayerTrack`      | `{ currentPlayId, currentIndex, playList, currentTrack, setTrack, next, prev }` |
-| `useAudioPlayerVolume`     | `{ volume, muted, setVolume, toggleMute }`                                      |
-| `useAudioPlayerTime`       | `{ currentTime, duration, seek }`                                               |
-| `useAudioPlayerElement`    | `{ audioEl, waveformInst }` (advanced)                                          |
+| Hook                     | Returns                                                                         |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `useAudioPlayerPlayback` | `{ isPlaying, repeatType, play, pause, togglePlay }`                            |
+| `useAudioPlayerTrack`    | `{ currentPlayId, currentIndex, playList, currentTrack, setTrack, next, prev }` |
+| `useAudioPlayerVolume`   | `{ volume, muted, setVolume, toggleMute }`                                      |
+| `useAudioPlayerTime`     | `{ currentTime, duration, seek }`                                               |
+| `useAudioPlayerElement`  | `{ audioEl, waveformInst }` (advanced)                                          |
 
 # Context Hooks
 
@@ -535,6 +602,147 @@ const CustomComponent = () => {
 </AudioPlayer>;
 ```
 
+# Compound Slots
+
+`AudioPlayer` exposes its built-in controls as static members so you can re-place or augment individual pieces without rebuilding the whole layout.
+
+| Member | Renders |
+| --- | --- |
+| `AudioPlayer.Progress` | progress bar / waveform |
+| `AudioPlayer.Volume` | volume trigger + slider |
+| `AudioPlayer.PlayList` | sortable playlist drawer (accepts `initialExpanded?`) |
+| `AudioPlayer.PlayListEmpty` | fallback rendered inside the playlist drawer when `playList` is empty |
+| [`AudioPlayer.PlayButton`](#audioplayerplaybutton-and-activeuiprevnnext) | Play + Prev + Next group (Prev/Next visibility follows `activeUI.prevNnext`) |
+| `AudioPlayer.RepeatButton` | repeat-type button |
+| `AudioPlayer.Artwork` | track artwork |
+| `AudioPlayer.TrackInfo` | track title / writer |
+| `AudioPlayer.TrackTime` | current + duration time |
+| `AudioPlayer.CustomComponent` | user-defined slot |
+
+Each slot accepts the full `GridItemLayoutProps` set — `gridArea?`, `visible?`, `width?`, `padding?`, `justifySelf?`, `UNSAFE_className?` — plus its own domain props. `AudioPlayer.TrackTime` is the exception: it only exposes `visible?` because the slot maps to two grid areas internally.
+
+Native HTML attributes (`className`, `style`, `onClick`, `data-*`, etc.) are **not** forwarded by compound slots. Compose the underlying primitives (`PlayBtn`, `PrevBtn`, `NextBtn`, etc., still exported) when full DOM control is needed; headless support with native attribute pass-through is planned for v3.
+
+## Mental model — `activeUI` vs compound children
+
+- **`activeUI`** governs the **preset** (default layout) — which built-in controls are shown.
+- **Compound children** are **explicit placements** that always render (`visible` defaults to `true`).
+
+The two layers are orthogonal. Compound children render **additively** alongside the preset. To truly replace a preset control, disable it in `activeUI` and render the compound counterpart:
+
+```tsx
+// Remove the default volume, re-place it with a custom gridArea
+<AudioPlayer
+  playList={playList}
+  activeUI={{ all: true, volume: false }}
+>
+  <AudioPlayer.Volume gridArea="1 / 5 / 1 / 6" />
+</AudioPlayer>
+```
+
+In development, a `console.warn` is emitted when a compound slot is rendered while its preset counterpart is still active, so silent duplication is easy to catch.
+
+## `AudioPlayer.PlayButton` and `activeUI.prevNnext`
+
+`AudioPlayer.PlayButton` is a single slot that renders the **Play + Prev + Next** group as one unit. There is no separate `AudioPlayer.PrevButton` / `AudioPlayer.NextButton` compound slot — Prev / Next are part of the `PlayButton` compound, and there are two ways to render them.
+
+### Method 1 — `AudioPlayer.PlayButton` compound (group)
+
+Place the whole group at a custom grid area; Prev / Next visibility inside the group follows `activeUI.prevNnext` (which defaults to `activeUI.all`):
+
+```tsx
+// Re-place the full Play + Prev + Next group at a custom area
+<AudioPlayer
+  playList={playList}
+  activeUI={{ all: true, playButton: false }} // hide the preset transport
+>
+  <AudioPlayer.PlayButton gridArea="row1-3" />
+</AudioPlayer>
+
+// Same compound, but render Play only — Prev / Next hidden by activeUI.prevNnext
+<AudioPlayer
+  playList={playList}
+  activeUI={{ all: true, playButton: false, prevNnext: false }}
+>
+  <AudioPlayer.PlayButton gridArea="row1-3" />
+</AudioPlayer>
+```
+
+### Method 2 — primitives via `AudioPlayer.CustomComponent`
+
+When you need finer control — placing Prev / Play / Next in different grid cells, applying custom wrappers, or attaching native HTML attributes — drop down to the `PlayBtn`, `PrevBtn`, and `NextBtn` primitives (still exported) and render them inside `AudioPlayer.CustomComponent`:
+
+```tsx
+import AudioPlayer, {
+  PrevBtn,
+  PlayBtn,
+  NextBtn,
+} from "react-modern-audio-player";
+
+<AudioPlayer
+  playList={playList}
+  activeUI={{ all: true, playButton: false }} // hide the preset transport
+  placement={{
+    interface: { customComponentsArea: { "custom-transport": "row1-3" } },
+  }}
+>
+  <AudioPlayer.CustomComponent id="custom-transport">
+    <div className="my-transport">
+      <PrevBtn isVisible />
+      <PlayBtn />
+      <NextBtn isVisible />
+    </div>
+  </AudioPlayer.CustomComponent>
+</AudioPlayer>;
+```
+
+`PrevBtn` / `NextBtn` accept an `isVisible` boolean for symmetry with the compound group's visibility logic; pass `false` to omit them. Use Method 2 when Method 1's group placement and `activeUI.prevNnext` toggle aren't enough.
+
+## Custom empty-playlist UI
+
+Pass children to `AudioPlayer.PlayListEmpty` to render a custom node inside the playlist drawer when `playList` is empty. Omit the slot to keep the default (drawer content renders nothing).
+
+```tsx
+<AudioPlayer playList={[]}>
+  <AudioPlayer.PlayListEmpty>
+    <div className="my-empty">Playlist is empty</div>
+  </AudioPlayer.PlayListEmpty>
+</AudioPlayer>
+```
+
+`PlayListEmpty` is a marker slot; its children are consumed by the drawer via context and the component itself does not render in-place.
+
+# **Accessibility**
+
+The player follows WAI-ARIA patterns and is fully navigable by keyboard and screen readers.
+
+## Keyboard support
+
+All controls are reachable via `Tab` and respond to standard keyboard activation. The playlist uses the WAI-ARIA "Listbox with Rearrangeable Options" pattern:
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move focus between player controls |
+| `Space` / `Enter` | Activate the focused button (play/pause, prev/next, repeat, mute, playlist) |
+| `ArrowUp` / `ArrowDown` | Move focus between playlist items |
+| `Alt+ArrowUp` / `Alt+ArrowDown` | Reorder the focused playlist item |
+| `Enter` / `Space` on a playlist item | Select and play that track |
+
+Drag-and-drop reordering is preserved as an alternative — keyboard and mouse both call the same `onReorder` handler.
+
+# **Gotchas**
+
+Common integration mistakes to avoid:
+
+- **Don't toggle the theme via `rootContainerProps.style.colorScheme`.** The native CSS `color-scheme` property does not switch the player's theme. Use the top-level [`colorScheme`](#theme-mode-dark-mode) prop, which drives the `[data-theme]` attribute and re-initializes the waveform colors.
+- **Set the `InterfacePlacement` generic when placing `customComponentsArea` beyond row 9.** TypeScript rejects values past the default range, so use `InterfacePlacement<N>` where `N` is `(max row length + 1)` — e.g. `InterfacePlacement<11>` for `"row1-10"` (see [Custom Component](#custom-component)).
+- **`AudioPlayer.CustomComponent` accepts a single React element child.** It uses `React.cloneElement` internally, so passing multiple children or a primitive (string, number) will throw.
+- **Volume is `0..1`, not `0..100`.** `setVolume` clamps out-of-range values, so `setVolume(50)` silently becomes `setVolume(1)`.
+- **Compound slots don't forward native HTML attributes.** `<AudioPlayer.Volume className="...">` is rejected by TypeScript — only `GridItemLayoutProps` (layout) pass through. Compose the underlying primitives (`PlayBtn`, `PrevBtn`, `NextBtn`, etc., still exported) when you need `className`, `style`, `onClick`, or `data-*`. Full headless support is planned for v3.
+- **`id: 0` is a valid track id.** The reducer uses nullish checks, so tracks with `id: 0` are handled correctly — don't filter them out of `playList` on the assumption that zero is falsy.
+- **Don't import the CSS manually.** Styles are auto-injected via `sideEffects: ["*.css"]`; `import "react-modern-audio-player/dist/index.css"` will 404 or double-load.
+- **Multiple mounted `<AudioPlayer>` instances don't share React state, but they do share the user's speakers.** Each instance has its own provider and its own `<audio>` element, so the state is isolated — but if two instances both play, the user hears both tracks simultaneously. Coordinate playback yourself (e.g. pause the others when one `play()` fires).
+
 # **Example**
 
 ```tsx