react-media-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marek Miklaszewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# react-media-kit
+
+Headless, unstyled video and audio player primitives for React.
+
+`react-media-kit` gives you the behavior of a media player as a set of composable components.
+It renders no CSS and imposes no visual design, so your player looks exactly however you want!
+
+## Features
+
+- 🧱 **Compound components** - `Player`, `Video`, `Audio`, `Controls`, `Seekbar`,
+  `Volume`, `TimeDisplay`, `PlayButton`, `SkipButton`, `FullscreenButton`,
+  `PipButton`, `PlaybackRateButton`. Use only the parts you need.
+- 🎨 **Unstyled by default** - no shipped CSS, no default theme. Style
+  everything yourself with plain class names.
+- 🏷️ **Data-attribute state hooks** - playing, fullscreen, picture-in-picture,
+  and other states are exposed as `data-*` attributes, so state-driven styling
+  stays in CSS instead of JS.
+- ⌨️ **Keyboard shortcuts** built in (play/pause, mute, fullscreen, seeking).
+- 📦 **Small footprint** - Tree-shakeable, with no runtime dependencies beyond React.
+- ⚡ **Optimized for performance** - player state lives outside React in an
+  external store; components subscribe to only the slice of state they need.
+- 🔒 **Typed** - written in TypeScript.
+
+## Installation
+
+```sh
+npm install react-media-kit
+```
+
+```sh
+pnpm add react-media-kit
+```
+
+Requires React and React DOM `>=19`.
+
+## Usage
+
+```tsx
+import { Player, Video, Controls, Seekbar, PlayButton, TimeDisplay } from "react-media-kit";
+
+function App() {
+  return (
+    <Player.Root>
+      <Player.Container>
+        <Video.Root>
+          <Video.Player src="/my-video.mp4" />
+        </Video.Root>
+
+        <Controls.Root>
+          <Seekbar.Root>
+            <Seekbar.Track>
+              <Seekbar.Progress />
+              <Seekbar.Buffer />
+              <Seekbar.Thumb />
+            </Seekbar.Track>
+          </Seekbar.Root>
+
+          <PlayButton.Root>Play</PlayButton.Root>
+
+          <TimeDisplay.Root>
+            <TimeDisplay.Toggle>
+              <TimeDisplay.Timer />
+              <span>/</span>
+              <TimeDisplay.Duration />
+            </TimeDisplay.Toggle>
+          </TimeDisplay.Root>
+        </Controls.Root>
+      </Player.Container>
+    </Player.Root>
+  );
+}
+```
+
+All styling is up to you — target elements by class name or by the `data-*`
+state attributes they expose.
+
+### Adaptive streaming
+
+`react-media-kit` ships no streaming engine (HLS, DASH, ...) — it stays
+dependency-free. `Video.Player` and `Audio.Player` both accept a plain
+`ref`, which easily lets you hook in hls.js, dash.js, shaka-player, or
+whichever engine you need.
+
+## Core Concepts
+
+Each control is a **root + sub-parts**, in the spirit of BaseUI-style
+primitives:
+
+| Component            | Purpose                                     |
+| -------------------- | ------------------------------------------- |
+| `Player`             | Top-level provider; owns player state       |
+| `Video`              | The `<video>` element and its overlay       |
+| `Audio`              | The `<audio>` element                       |
+| `Controls`           | Wrapper for the control bar                 |
+| `Seekbar`            | Scrub/seek, with progress and buffer ranges |
+| `Volume`             | Mute toggle and volume slider               |
+| `TimeDisplay`        | Current time / duration                     |
+| `PlayButton`         | Play/pause toggle                           |
+| `SkipButton`         | Skip forward/back by an interval            |
+| `FullscreenButton`   | Toggle fullscreen                           |
+| `PipButton`          | Toggle picture-in-picture                   |
+| `PlaybackRateButton` | Set a specific playback rate                |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,275 @@
+import { ButtonHTMLAttributes, HTMLAttributes, MediaHTMLAttributes, MouseEventHandler, PointerEventHandler, ReactNode, Ref, TimeHTMLAttributes, VideoHTMLAttributes } from "react";
+//#region src/components/audio/player/AudioPlayer.d.ts
+interface AudioPlayerProps extends MediaHTMLAttributes<HTMLAudioElement> {
+  src?: string;
+  ref?: Ref<HTMLAudioElement>;
+}
+declare function AudioPlayer({ ref, ...props }: AudioPlayerProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports {
+  export { AudioPlayer as Player };
+}
+//#endregion
+//#region src/components/controls/root/ControlsRoot.d.ts
+interface ControlsRootProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function ControlsRoot(props: ControlsRootProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$1 {
+  export { ControlsRoot as Root };
+}
+//#endregion
+//#region src/types.d.ts
+type ButtonAttributes = ButtonHTMLAttributes<HTMLButtonElement>;
+type TimeDisplayAttributes = Omit<TimeHTMLAttributes<HTMLTimeElement>, "children" | "dateTime">;
+type OnErrorFunc = (playerError: PlayerError) => void;
+type PlayerError = MediaPlaybackError | GeneralError;
+interface MediaPlaybackError {
+  type: "media";
+  error: MediaError;
+}
+interface GeneralError {
+  type: "fullscreen" | "play" | "pip";
+  error: unknown;
+}
+//#endregion
+//#region src/components/fullscreenButton/root/FullscreenButtonRoot.d.ts
+interface FullscreenButtonRootProps extends ButtonAttributes {
+  ref?: Ref<HTMLButtonElement>;
+}
+declare function FullscreenButtonRoot({ onClick, ...props }: FullscreenButtonRootProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$2 {
+  export { FullscreenButtonRoot as Root };
+}
+//#endregion
+//#region src/components/pipButton/root/PipButtonRoot.d.ts
+interface PipButtonRootProps extends ButtonAttributes {
+  ref?: Ref<HTMLButtonElement>;
+}
+declare function PipButtonRoot({ onClick, ...props }: PipButtonRootProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$3 {
+  export { PipButtonRoot as Root };
+}
+//#endregion
+//#region src/components/playbackRateButton/root/PlaybackRateButtonRoot.d.ts
+interface PlaybackRateButtonRootProps extends ButtonAttributes {
+  playbackRate: number;
+  ref?: Ref<HTMLButtonElement>;
+}
+declare function PlaybackRateButtonRoot({ playbackRate, onClick, ...props }: PlaybackRateButtonRootProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$5 {
+  export { PlaybackRateButtonRoot as Root };
+}
+//#endregion
+//#region src/components/playButton/root/PlayButtonRoot.d.ts
+interface PlayButtonRootProps extends ButtonAttributes {
+  ref?: Ref<HTMLButtonElement>;
+}
+declare function PlayButtonRoot({ onClick, ...props }: PlayButtonRootProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$4 {
+  export { PlayButtonRoot as Root };
+}
+//#endregion
+//#region src/components/player/root/PlayerRoot.d.ts
+interface PlayerRootProps {
+  children: ReactNode;
+  lang?: string;
+  onError?: OnErrorFunc;
+}
+declare const PlayerRoot: ({ children, lang, onError }: PlayerRootProps) => import("react").JSX.Element;
+//#endregion
+//#region src/components/player/container/PlayerContainer.d.ts
+interface PlayerContainerProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function PlayerContainer({ onKeyDown, style, ref, ...props }: PlayerContainerProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$6 {
+  export { PlayerContainer as Container, PlayerRoot as Root };
+}
+//#endregion
+//#region src/components/seekbar/root/SeekbarRoot.d.ts
+interface SeekbarRootProps extends HTMLAttributes<HTMLDivElement> {
+  skipInterval?: number;
+  ref?: Ref<HTMLDivElement>;
+}
+declare function SeekbarRoot({ skipInterval, ref, onKeyDown, onPointerMove, onPointerDown, onLostPointerCapture, ...props }: SeekbarRootProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/seekbar/track/SeekbarTrack.d.ts
+interface SeekbarTrackProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function SeekbarTrack(props: SeekbarTrackProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/seekbar/progress/SeekbarProgress.d.ts
+interface SeekbarProgressProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function SeekbarProgress({ style, ...props }: SeekbarProgressProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/seekbar/buffer/SeekbarBuffer.d.ts
+interface SeekbarBufferProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function SeekbarBuffer({ style, ...props }: SeekbarBufferProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/seekbar/thumb/SeekbarThumb.d.ts
+interface SeekbarThumbProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function SeekbarThumb(props: SeekbarThumbProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$7 {
+  export { SeekbarBuffer as Buffer, SeekbarProgress as Progress, SeekbarRoot as Root, SeekbarThumb as Thumb, SeekbarTrack as Track };
+}
+//#endregion
+//#region src/components/skipButton/root/SkipButtonRoot.d.ts
+type SkipDirection = "back" | "forward";
+interface SkipButtonRootProps extends ButtonAttributes {
+  direction: SkipDirection;
+  skipInterval?: number;
+  ref?: Ref<HTMLButtonElement>;
+}
+declare function SkipButtonRoot({ direction, skipInterval, onClick, ...props }: SkipButtonRootProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$8 {
+  export { SkipButtonRoot as Root };
+}
+//#endregion
+//#region src/components/timeDisplay/root/TimeDisplayRoot.d.ts
+interface TimeDisplayRootProps extends HTMLAttributes<HTMLDivElement> {
+  initialMode?: "elapsed" | "remaining";
+  ref?: Ref<HTMLDivElement>;
+}
+declare function TimeDisplayRoot({ initialMode, ...props }: TimeDisplayRootProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/timeDisplay/toggle/TimeDisplayToggle.d.ts
+interface TimeDisplayToggleProps extends ButtonAttributes {
+  ref?: Ref<HTMLButtonElement>;
+}
+declare function TimeDisplayToggle({ onClick, ...props }: TimeDisplayToggleProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/timeDisplay/timer/TimeDisplayTimer.d.ts
+interface TimeDisplayTimerProps extends TimeDisplayAttributes {
+  ref?: Ref<HTMLTimeElement>;
+}
+declare function TimeDisplayTimer({ ref, ...props }: TimeDisplayTimerProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/timeDisplay/duration/TimeDisplayDuration.d.ts
+interface TimeDisplayDurationProps extends TimeDisplayAttributes {
+  ref?: Ref<HTMLTimeElement>;
+}
+declare function TimeDisplayDuration(props: TimeDisplayDurationProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$9 {
+  export { TimeDisplayDuration as Duration, TimeDisplayRoot as Root, TimeDisplayTimer as Timer, TimeDisplayToggle as Toggle };
+}
+//#endregion
+//#region src/components/video/root/VideoRoot.d.ts
+interface VideoRootProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function VideoRoot({ style, ...props }: VideoRootProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/video/overlay/useOverlayInteractivity.d.ts
+type OnDoubleClick = "fullscreen" | PointerEventHandler<HTMLButtonElement>;
+interface OverlayInteractivityOptions {
+  onPointerUp?: MouseEventHandler<HTMLButtonElement>;
+  onPointerDown?: MouseEventHandler<HTMLButtonElement>;
+  onDoubleClick?: OnDoubleClick;
+  onDoubleTouch?: OnDoubleClick;
+  doubleClickInterval?: number;
+}
+//#endregion
+//#region src/components/video/overlay/VideoOverlay.d.ts
+interface VideoOverlayRootProps extends Omit<ButtonAttributes, "onDoubleClick"> {
+  label: string;
+  onDoubleClick?: OverlayInteractivityOptions["onDoubleClick"];
+  onDoubleTouch?: OverlayInteractivityOptions["onDoubleTouch"];
+  doubleClickInterval?: number;
+  ref?: Ref<HTMLButtonElement>;
+}
+declare function VideoOverlayRoot({ style, label, onDoubleClick, onDoubleTouch, doubleClickInterval, onPointerDown, onPointerUp, onKeyDown, ...props }: VideoOverlayRootProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/video/player/VideoPlayer.d.ts
+interface VideoPlayerProps extends VideoHTMLAttributes<HTMLVideoElement> {
+  src?: string;
+  ref?: Ref<HTMLVideoElement>;
+}
+declare function VideoPlayer({ ref, ...props }: VideoPlayerProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$10 {
+  export { VideoOverlayRoot as Overlay, VideoPlayer as Player, VideoRoot as Root };
+}
+//#endregion
+//#region src/components/volume/slider/VolumeSlider.d.ts
+interface VolumeSliderRootProps extends HTMLAttributes<HTMLDivElement> {
+  volumeInterval?: number;
+  ref?: Ref<HTMLDivElement>;
+  computeAriaValueText?: ({ volume, isMuted }: {
+    volume: number;
+    isMuted: boolean;
+  }) => string;
+}
+declare function VolumeSlider({ volumeInterval, ref, onPointerDown, onPointerMove, onLostPointerCapture, onKeyDown, computeAriaValueText, ...props }: VolumeSliderRootProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/volume/mute/VolumeMute.d.ts
+interface VolumeMuteProps extends ButtonAttributes {
+  ref?: Ref<HTMLButtonElement>;
+}
+declare function VolumeMute({ onClick, ...props }: VolumeMuteProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/volume/track/VolumeTrack.d.ts
+interface VolumeTrackProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function VolumeTrack(props: VolumeTrackProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/volume/progress/VolumeProgress.d.ts
+interface VolumeProgressProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function VolumeProgress(props: VolumeProgressProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/volume/thumb/VolumeThumb.d.ts
+interface VolumeThumbProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<HTMLDivElement>;
+}
+declare function VolumeThumb(props: VolumeThumbProps): import("react").JSX.Element;
+declare namespace index_parts_d_exports$11 {
+  export { VolumeMute as Mute, VolumeProgress as Progress, VolumeSlider as Slider, VolumeThumb as Thumb, VolumeTrack as Track };
+}
+//#endregion
+//#region src/state/types.d.ts
+type Selector<T> = (state: PlayerState) => T;
+type LifeCycleState = "pending" | "loading" | "ready" | "error";
+interface PlayerState {
+  state: LifeCycleState;
+  isPlaying: boolean;
+  isMuted: boolean;
+  isFullscreen: boolean;
+  isPictureInPicture: boolean;
+  isBuffering: boolean;
+  durationInSec: number;
+  currentTimeInSec: number;
+  optimisticTimeInSec: number | null;
+  bufferedEndInSec: number | null;
+  volume: number;
+  playbackRate: number;
+}
+//#endregion
+//#region src/state/PlayerContext.d.ts
+declare function usePlayer<T>(selector: Selector<T>): T;
+declare function usePlayerControls(): {
+  play: () => Promise<void>;
+  pause: () => void | undefined;
+  toggle: () => void | Promise<void>;
+  seek: (time: number) => void;
+  skip: (delta: number) => void;
+  toggleFullscreen: () => Promise<void>;
+  togglePip: () => Promise<void>;
+  toggleMute: () => boolean | null;
+  mute: () => true | null;
+  unmute: () => false | null;
+  stepVolume: (delta: number) => void;
+  setVolume: (volume: number) => void;
+  stepPlaybackRate: (delta: number) => void;
+  setPlaybackRate: (rate: number) => void;
+};
+//#endregion
+export { index_parts_d_exports as Audio, index_parts_d_exports$1 as Controls, index_parts_d_exports$2 as FullscreenButton, type LifeCycleState, type OnErrorFunc, index_parts_d_exports$3 as PipButton, index_parts_d_exports$4 as PlayButton, index_parts_d_exports$5 as PlaybackRateButton, index_parts_d_exports$6 as Player, type PlayerError, type PlayerState, index_parts_d_exports$7 as Seekbar, type Selector, index_parts_d_exports$8 as SkipButton, index_parts_d_exports$9 as TimeDisplay, index_parts_d_exports$10 as Video, index_parts_d_exports$11 as Volume, usePlayer, usePlayerControls };
+//# sourceMappingURL=index.d.ts.map