first commit

docs/ui/react/react-audio/src/components/basic-player/basic-player.md

@@ -0,0 +1,77 @@
+# `<BasicPlayer>`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`<BasicPlayer>` is the minimal media-player surface for an
+`AudioPlayerPlugin`. It is implemented as a thin composition over
+`<AudioPlayer>` with the loop toggle and playback-rate input disabled,
+leaving only the essential controls: play / pause / stop / seek /
+volume. Use this when you want a clean, distraction-free player and
+don't need the advanced playback adjustments the full player exposes.
+
+Because it is a strict composition, every behavioural guarantee of
+`<AudioPlayer>` — cancel-on-unmount, error surfacing, state polling —
+applies here unchanged.
+
+## Features
+
+- Forwards every relevant prop to `<AudioPlayer>`.
+- Hides the loop toggle and playback rate input.
+- Adds the `.rax-basic-player` class (or merges it with the supplied
+  `className`) so theming targets are stable across the two surfaces.
+
+## Usage: Basic Example
+
+```tsx
+import { AudioPlayerPlugin } from "@suaveplan/audio-fx-plugin-audio-player";
+import { AudioProvider, BasicPlayer } from "@suaveplan/react-audio";
+
+const plugin = new AudioPlayerPlugin({});
+
+export function Card() {
+    return (
+        <AudioProvider>
+            <BasicPlayer plugin={plugin} src="https://cdn/short.wav" />
+        </AudioProvider>
+    );
+}
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { AudioPlayerPlugin } from "@suaveplan/audio-fx-plugin-audio-player";
+import { AudioProvider, BasicPlayer } from "@suaveplan/react-audio";
+
+const plugin = new AudioPlayerPlugin({});
+
+export function MutedCard() {
+    return (
+        <AudioProvider>
+            <BasicPlayer plugin={plugin} className="muted-row" />
+        </AudioProvider>
+    );
+}
+```
+
+## API Reference
+
+| Prop        | Type                       | Default | Notes                                       |
+| ----------- | -------------------------- | ------- | ------------------------------------------- |
+| `plugin`    | `AudioPlayerPlugin`        | —       | Required.                                   |
+| `src`       | `string \| undef`          | —       | Auto-load this URL on mount.                |
+| `className` | `string \| undef`          | —       | Forwarded; merged with `rax-basic-player`.  |
+
+## Implementation Notes
+
+The `showLoop` / `showPlaybackRate` props on the underlying
+`<AudioPlayer>` are fixed at `false`, which makes the BasicPlayer's
+prop signature smaller than the full player's. There is no separate
+state, no separate effect — every behavioural guarantee of the full
+player applies. Pass-through is deliberately verbose (one prop at a
+time) so future additions to `<AudioPlayer>` do not silently widen
+`<BasicPlayer>`'s surface; new props must be added explicitly.