Skip to content

Commit 2904f53

Browse files
taj54taj54
authored
Merge pull request #7 from taj54/main
docs: Update README.md with detailed project information
2 parents 6860d20 + f101302 commit 2904f53

File tree

4 files changed

+300
-11
lines changed

4 files changed

+300
-11
lines changed

‎CONTRIBUTING.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# CONTRIBUTING.md
2+
3+
We welcome contributions to the `@interactive-video-labs/react` project! By contributing, you help us improve and expand the capabilities of this React wrapper for interactive video experiences. Please take a moment to review this document to understand how to contribute effectively.
4+
5+
## Table of Contents
6+
7+
1. [Code of Conduct](#1-code-of-conduct)
8+
2. [How Can I Contribute?](#2-how-can-i-contribute)
9+
* [Reporting Bugs](#reporting-bugs)
10+
* [Suggesting Enhancements](#suggesting-enhancements)
11+
* [Your First Code Contribution](#your-first-code-contribution)
12+
* [Pull Request Guidelines](#pull-request-guidelines)
13+
3. [Development Setup](#3-development-setup)
14+
4. [Testing](#4-testing)
15+
5. [Coding Style](#5-coding-style)
16+
6. [Commit Messages](#6-commit-messages)
17+
7. [License](#7-license)
18+
19+
## 1. Code of Conduct
20+
21+
This project adheres to the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [your contact email or issue tracker].
22+
23+
## 2. How Can I Contribute?
24+
25+
### Reporting Bugs
26+
27+
If you find a bug, please open an issue on our [GitHub Issues](https://github.com/interactive-video-labs/interactive-video-react-wrapper/issues) page. When reporting a bug, please include:
28+
29+
* A clear and concise description of the bug.
30+
* Steps to reproduce the behavior.
31+
* Expected behavior.
32+
* Actual behavior.
33+
* Screenshots or video (if applicable).
34+
* Your environment details (OS, browser, `@interactive-video-labs/react` version, React version).
35+
36+
### Suggesting Enhancements
37+
38+
We love new ideas! If you have a suggestion for an enhancement or a new feature, please open an issue on our [GitHub Issues](https://github.com/interactive-video-labs/interactive-video-react-wrapper/issues) page. Please include:
39+
40+
* A clear and concise description of the proposed enhancement.
41+
* Why this enhancement would be useful.
42+
* Any potential use cases or examples.
43+
44+
### Your First Code Contribution
45+
46+
If you're looking to make your first code contribution, look for issues labeled `good first issue` on our [issue tracker](https://github.com/interactive-video-labs/interactive-video-react-wrapper/issues).
47+
48+
### Pull Request Guidelines
49+
50+
1. **Fork the repository** and create your branch from `main`.
51+
2. **Ensure your code adheres to the existing style** (see [Coding Style](#5-coding-style)).
52+
3. **Add or update tests** for any new features or bug fixes. Ensure all tests pass.
53+
4. **Update documentation** as necessary (e.g., `README.md`, `DEVELOPER.md`).
54+
5. **Write clear and concise commit messages** (see [Commit Messages](#6-commit-messages)).
55+
6. **Open a pull request** to the `main` branch. Provide a clear description of your changes and reference any related issues.
56+
57+
## 3. Development Setup
58+
59+
For detailed instructions on setting up your development environment, installing dependencies, and running the project locally, please refer to the [DEVELOPER.md](DEVELOPER.md) file.
60+
61+
## 4. Testing
62+
63+
All new features and bug fixes should be accompanied by appropriate tests. To run the test suite, use:
64+
65+
```bash
66+
pnpm test
67+
```
68+
69+
Ensure all tests pass before submitting a pull request.
70+
71+
## 5. Coding Style
72+
73+
We use ESLint and Prettier to maintain a consistent coding style. Please ensure your code is formatted correctly before submitting a pull request. You can typically run linting and formatting checks via your IDE or by running project-specific scripts (if available, check `package.json`).
74+
75+
## 6. Commit Messages
76+
77+
We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for our commit messages. This helps with automated changelog generation and understanding the history of changes.
78+
79+
Examples:
80+
81+
* `feat: Add new video playback controls`
82+
* `fix: Resolve issue with cue point triggering`
83+
* `docs: Update README with new usage example`
84+
* `chore: Update dependencies`
85+
86+
## 7. License
87+
88+
By contributing to `@interactive-video-labs/react`, you agree that your contributions will be licensed under its MIT License. See the [LICENSE](LICENSE) file for details.

‎DEVELOPER.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# DEVELOPER.md
2+
3+
This document provides a guide for developers who want to contribute to or work with the `@interactive-video-labs/react` project. It covers setting up the development environment, understanding the project structure, running tests, building the project, and working with examples.
4+
5+
## Table of Contents
6+
7+
1. [Getting Started](#getting-started)
8+
2. [Project Structure](#project-structure)
9+
3. [Available Scripts](#available-scripts)
10+
4. [Testing](#testing)
11+
5. [Building the Project](#building-the-project)
12+
6. [Working with Examples](#working-with-examples)
13+
7. [Contributing](#contributing)
14+
8. [Troubleshooting](#troubleshooting)
15+
16+
## 1. Getting Started
17+
18+
To get started with development, follow these steps:
19+
20+
1. **Clone the repository:**
21+
```bash
22+
git clone https://github.com/interactive-video-labs/interactive-video-react-wrapper.git
23+
cd interactive-video-react-wrapper
24+
```
25+
26+
2. **Install dependencies:**
27+
This project uses `pnpm` as its package manager. If you don't have `pnpm` installed, you can install it via npm:
28+
```bash
29+
npm install -g pnpm
30+
```
31+
Then, install the project dependencies:
32+
```bash
33+
pnpm install
34+
```
35+
36+
## 2. Project Structure
37+
38+
Here's an overview of the key directories and files in this project:
39+
40+
* `src/`: Contains the main source code for the React wrapper (`index.tsx`).
41+
* `test/`: Contains unit tests for the components (`InteractiveVideo.test.tsx`) and test setup (`setupTests.ts`).
42+
* `examples/`: Contains a simple example React application demonstrating how to use the wrapper.
43+
* `index.html`: The HTML entry point for the example.
44+
* `index.tsx`: The React application code for the example.
45+
* `dist/`: The output directory for the compiled library files.
46+
* `tsup.config.ts`: Configuration for `tsup`, the bundler used to build the library.
47+
* `vitest.config.ts`: Configuration for `Vitest`, the testing framework.
48+
* `package.json`: Project metadata, dependencies, and scripts.
49+
50+
## 3. Available Scripts
51+
52+
This project includes several scripts defined in `package.json` to help with development:
53+
54+
* `pnpm build`: Compiles the TypeScript source code into JavaScript for distribution (`dist` folder).
55+
* `pnpm dev`: Starts `tsup` in watch mode, recompiling the library whenever source files change.
56+
* `pnpm test`: Runs all unit tests using Vitest.
57+
* `pnpm clean`: Removes the `dist` directory.
58+
* `pnpm prepare`: Runs `pnpm build`. This script is typically run before publishing the package.
59+
* `pnpm serve-examples`: Builds the example application and serves it using `http-server`.
60+
* `pnpm build-examples`: Compiles the example application using `esbuild`.
61+
62+
## 4. Testing
63+
64+
Tests are written using `Vitest` and `React Testing Library`. You can run all tests with:
65+
66+
```bash
67+
pnpm test
68+
```
69+
70+
When adding new features or fixing bugs, please ensure you add or update relevant tests to maintain code quality and prevent regressions.
71+
72+
## 5. Building the Project
73+
74+
The project is built using `tsup`. To compile the library for production, run:
75+
76+
```bash
77+
pnpm build
78+
```
79+
80+
This will generate the compiled JavaScript files and TypeScript declaration files in the `dist` directory.
81+
82+
## 6. Working with Examples
83+
84+
The `examples/` directory contains a basic usage example. To run it:
85+
86+
```bash
87+
pnpm serve-examples
88+
```
89+
90+
This will build the example and start a local web server, usually accessible at `http://localhost:8080` (or another port if 8080 is in use). You can modify the `examples/index.tsx` file to test your changes in a live environment.
91+
92+
## 7. Contributing
93+
94+
We welcome contributions to this project! Please refer to our [CONTRIBUTING.md](CONTRIBUTING.md) file for detailed guidelines on how to contribute, including information on:
95+
96+
* Reporting bugs
97+
* Suggesting enhancements
98+
* Submitting pull requests
99+
* Coding style and conventions
100+
101+
## 8. Troubleshooting
102+
103+
* **`pnpm` command not found**: Ensure `pnpm` is installed globally (`npm install -g pnpm`).
104+
* **Build errors**: Check the output of `pnpm build` for specific error messages. Ensure all dependencies are installed (`pnpm install`).
105+
* **Test failures**: Review the test output for details on failing tests. You can often debug tests by adding `console.log` statements or using your IDE's debugger.
106+
* **Example server not starting**: Check if port 8080 (or the default `http-server` port) is already in use. You might need to stop other processes using that port or configure `http-server` to use a different port (though this is not directly supported by the `serve-examples` script).

‎README.md‎

Lines changed: 103 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,106 @@ Welcome to `@interactive-video-labs/react` — a lightweight React wrapper aroun
1717

1818
This wrapper makes it easy to embed interactive video players in React apps using familiar props and event handlers, while keeping close to the core API.
1919

20-
---
20+
---
21+
22+
## Introduction
23+
24+
`@interactive-video-labs/react` is a thin React component that provides a convenient way to integrate interactive video experiences into your React applications. It leverages the powerful `@interactive-video-labs/core` engine, allowing you to easily manage video playback, cue points, and analytics within a familiar React paradigm.
25+
26+
## Features
27+
28+
* **Easy Integration**: Seamlessly embed interactive videos into your React components.
29+
* **Cue Point Management**: Load and manage cue points for dynamic video interactions.
30+
* **Analytics Events**: Receive detailed analytics events from the video player to track user engagement.
31+
* **Localization**: Support for player localization through translations.
32+
* **Direct Core API Access**: Provides a React-friendly interface while maintaining close alignment with the core IVLabsPlayer API.
33+
34+
## Installation
35+
36+
You can install the package using npm or pnpm:
37+
38+
```bash
39+
pnpm add @interactive-video-labs/react @interactive-video-labs/core react react-dom
40+
# or
41+
npm install @interactive-video-labs/react @interactive-video-labs/core react react-dom
42+
```
43+
44+
## Usage
45+
46+
To use the `InteractiveVideo` component, simply import it and pass the necessary props. The `videoUrl` prop is mandatory.
47+
48+
```tsx
49+
import React from 'react';
50+
import { InteractiveVideo } from '@interactive-video-labs/react';
51+
52+
const MyVideoPlayer = () => {
53+
return (
54+
<div style={{ width: '100%', maxWidth: '800px', margin: '0 auto' }}>
55+
<InteractiveVideo
56+
videoUrl="https://interactive-video-labs.github.io/interactive-video-demos/videos/big_buck_bunny.mp4"
57+
autoplay={true}
58+
loop={false}
59+
controls={true}
60+
onAnalyticsEvent={(event, payload) => {
61+
console.log('Analytics Event:', event, payload);
62+
// Handle analytics events, e.g., send to a tracking service
63+
}}
64+
cues={[
65+
{ time: 10, id: 'intro-cue', type: 'pause' },
66+
{ time: 25, id: 'question-cue', type: 'custom', data: { question: 'What is your favorite color?' } },
67+
]}
68+
translations={{
69+
en: {
70+
play: 'Play Video',
71+
pause: 'Pause Video',
72+
},
73+
}}
74+
/>
75+
</div>
76+
);
77+
};
78+
79+
export default MyVideoPlayer;
80+
```
81+
82+
## Props
83+
84+
The `InteractiveVideo` component accepts the following props:
85+
86+
* `videoUrl` (string, **required**): The URL of the video to be played.
87+
* `onAnalyticsEvent` (function, optional): A callback function that is triggered when an analytics event occurs. It receives the `event` name and an optional `payload`.
88+
* `event`: `PLAYER_LOADED`, `VIDEO_STARTED`, `VIDEO_PAUSED`, `VIDEO_ENDED`, `CUE_TRIGGERED`, `INTERACTION_COMPLETED`, `ERROR`.
89+
* `payload`: An object containing event-specific data.
90+
* `cues` (CuePoint[], optional): An array of cue points to load into the player. Each `CuePoint` object should conform to the `@interactive-video-labs/core` `CuePoint` interface.
91+
* `translations` (Translations, optional): An object containing translations for player localization. This should conform to the `@interactive-video-labs/core` `Translations` interface.
92+
* `...restOptions` (PlayerConfig, optional): Any other valid `PlayerConfig` options from `@interactive-video-labs/core` (excluding `videoUrl`, `cues`, and `translations`). This allows for direct pass-through of core player configurations like `autoplay`, `loop`, `controls`, `locale`, etc.
93+
94+
## Development
95+
96+
To set up the development environment:
97+
98+
1. Clone the repository.
99+
2. Install dependencies:
100+
```bash
101+
pnpm install
102+
```
103+
3. Build the project:
104+
```bash
105+
pnpm build
106+
```
107+
4. Run tests:
108+
```bash
109+
pnpm test
110+
```
111+
5. Run examples:
112+
```bash
113+
pnpm serve-examples
114+
```
115+
116+
## Contributing
117+
118+
We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
119+
120+
## License
121+
122+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

‎tsup.config.ts‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,16 @@
11
import { defineConfig } from 'tsup';
22
import pkg from './package.json';
33

4-
export default defineConfig((options) => ({
5-
export default defineConfig((options) => ({
4+
export default defineConfig({
65
entry: ['src/index.tsx'],
76
format: ['esm', 'cjs'],
8-
outExtension: ext => ({
9-
esm: '.mjs',
10-
cjs: '.cjs',
11-
}),
127
dts: true,
13-
watch: options.watch,
148
clean: true,
15-
}));
169
banner: {
1710
js: `/**
1811
* ${pkg.name} v${pkg.version}
1912
* Author: ${pkg.author}
2013
*/
21-
`,
14+
`,
2215
},
23-
}));
16+
});

0 commit comments

Comments
 (0)