react-modern-audio-player 2.1.0 → 2.2.0

package/README.md

@@ -15,11 +15,11 @@
   <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@2.0.0">
+  <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://github.com/slash9494/react-modern-audio-player/actions/workflows/integration.yml/badge.svg?branch=main" alt="CI">
+    <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>
@@ -29,6 +29,8 @@
 - **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
@@ -154,8 +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
@@ -238,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
@@ -379,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
@@ -590,6 +602,116 @@ 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.
@@ -608,6 +730,19 @@ All controls are reachable via `Tab` and respond to standard keyboard activation
 
 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