# Simple Player — Web Components API

This document is the source-reference companion to [`components.html`](./components.html). The live page imports the actual production components and has editable demonstrations. No `.stem` file or audio engine is needed to browse examples.

## Components

- `<stem-mixer-channel>`
- `<stem-app-panel>`

The host application owns file I/O, codec, playback, state persistence, and other operations unless explicitly noted. Components are native Custom Elements. CSS in component Shadow DOM resolves relative to the module file. The app owns any callback-supplied state.

Primary component source: [`components/track-row.js`](./components/track-row.js).

`<stem-app-panel>` is also reusable. It uses **Light DOM**, not Shadow DOM, so host styles and ordinary HTML labels work normally. It exposes `show()` and `hide()` and sets `role="region"` by default.

## Public methods and properties

- `setTrack(track, pref, options)`: Renders a channel with gain, mute, solo, and optional metadata inputs
- `refresh(mode)`: Updates gain/mute/solo presentation using the existing pref object
- `setDisabled(boolean)`: Enable or disable its controls
- `controls`: NodeList of controls inside Shadow DOM

## Events and callbacks

- `Callbacks: onGain/onMute/onSolo`: Functions provided in setTrack options; no custom event
- `onEdit(field,value)`: Editor only: invoked on metadata edits

## Example

```javascript
import './components/track-row.js';
const channel = document.createElement('stem-mixer-channel');
const pref = {gainDb:0,mute:false,solo:false};
channel.setTrack({id:1,name:'Vocals',color:'#e89249'}, pref, {
  mode:'stems',
  onGain:db => {pref.gainDb=db; channel.refresh('stems')},
  onMute:() => {pref.mute=!pref.mute; channel.refresh('stems')},
  onSolo:() => {pref.solo=!pref.solo; channel.refresh('stems')}
});
document.body.append(channel);
```

## Testing and limitations

- Catalog data and artworks are synthetic demonstration content; they are not loaded from audio files.
- Changing a property in the catalog reconfigures or remounts the real component so modes can be inspected.
- The catalog's events log is not a replacement for host-state management.
- For production integration, always copy the **entire relevant mini-app folder** with its sibling suite dependencies rather than a partial HTML patch.

## Multi-app host warning

Both the Simple Player and Editor ship a legacy `<stem-mixer-channel>` tag for compatibility with their existing apps. When you import both into a single Custom Elements registry, use the namespaced `<stem-simple-mixer-channel>` alias for this mini-app. Its class and UI behavior are the same as the legacy element. Shared `<stem-app-panel>` registration is guarded and can safely be imported from more than one mini-app.
