# Creator — 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-wav-input-track>`
- `<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

- `setStem(stem,index,options)`: Renders WAV info, name/color editors, track metadata and remove button
- `setDisabled(boolean)`: Disable native form controls
- `controls`: NodeList of inputs/buttons inside Shadow DOM

## Events and callbacks

- `onUpdate()`: Host callback after editing name, color, artwork or metadata
- `onRemove()`: Host callback requesting removal; host owns array

## Example

```javascript
import './components/track-row.js';
const row = document.createElement('stem-wav-input-track');
const stem = {file:{name:'Vocals.wav'},name:'Vocals',color:'#e89249',metadata:{}};
row.setStem(stem,0,{format:info => '48 kHz / Stereo',onUpdate:()=>console.log(stem),onRemove:()=>console.log('remove')});
document.body.append(row);
```

## 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.

**Cross-app integration:** the shared `<stem-app-panel>` definition is guarded so multiple reference mini-app modules can be imported into one host without duplicate registration errors.
