# Track Exporter — 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-export-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

- `setTrack(track, options)`: Render an independently selectable track from supplied track data
- `trackId`: Read numeric track ID
- `checked`: Get or set checkbox selection
- `setDisabled(boolean)`: Disable all controls

## Events and callbacks

- `selectionchange`: Composed and bubbling CustomEvent when checked changes

## Example

```javascript
import './components/track-row.js';
const row = document.createElement('stem-export-track');
row.setTrack({id:1,name:'Vocals',color:'#e89249'}, {action:'Select',detail:'ALAC · 48 kHz'});
row.addEventListener('selectionchange', () => console.log(row.trackId,row.checked));
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.
