@djangocfg/widget-player
One media element that plays both audio and video, and the surfaces that borrow it: a footer dock, a route stage, and a transcript row.
Replaces @djangocfg/ui-tools' separate AudioPlayer and VideoPlayer. Two
independent players are two owners of "what is playing", and that race is
audible.
Install
pnpm add @djangocfg/widget-player @djangocfg/ui-core
Layers
Each is importable alone, so a host mounting a transcript row does not pull the dock.
| Subpath | What it is |
|---|---|
. | everything below |
./element | the ONE media element, and the failure translation |
./model | pure projection — what a surface renders. No React. |
./surfaces | PlayerDock (footer), PlayerStage (route), MediaButton (a row), TrackCover, PlayerInfo |
./domain | MediaTrack, MediaDetail, MediaFailure, machineTrack — the product language |
./i18n | 17 typed dictionaries; PlayerCopy is the schema of record |
The seam
This package does not import a store. State arrives as props, intents leave as callbacks — which is what lets every surface render in Storybook with no store and no transport.
import { PlayerDock, MediaButton, trackFromLink } from '@djangocfg/widget-player';
// A row in a transcript. Mounts nothing — for every kind, video included.
<MediaButton track={track} onPlay={play} />
// The footer dock HOLDS the element.
<PlayerDock track={track} playing={playing} onToggle={toggle} onOpenStage={open} />
Turning an address into a track needs two answers only a transport has — the playable kind and the URL that plays — so the caller supplies them:
const track = trackFromLink(hostId, path, {
kind: 'audio',
src: playableUrl,
poster: coverUrl, // optional; supplied, never derived
});
Copy
The package owns its copy, typed. usePlayerCopy() reads the active locale from
@djangocfg/i18n when a provider is mounted and falls back to English when one
is not — so a surface renders in a test without standing up a provider.
Verify
pnpm --filter @djangocfg/widget-player check-types test