diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69de29..7feb972 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# CONTRIBUTING.md + +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. + +## Table of Contents + +1. [Code of Conduct](#1-code-of-conduct) +2. [How Can I Contribute?](#2-how-can-i-contribute) + * [Reporting Bugs](#reporting-bugs) + * [Suggesting Enhancements](#suggesting-enhancements) + * [Your First Code Contribution](#your-first-code-contribution) + * [Pull Request Guidelines](#pull-request-guidelines) +3. [Development Setup](#3-development-setup) +4. [Testing](#4-testing) +5. [Coding Style](#5-coding-style) +6. [Commit Messages](#6-commit-messages) +7. [License](#7-license) + +## 1. Code of Conduct + +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]. + +## 2. How Can I Contribute? + +### Reporting Bugs + +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: + +* A clear and concise description of the bug. +* Steps to reproduce the behavior. +* Expected behavior. +* Actual behavior. +* Screenshots or video (if applicable). +* Your environment details (OS, browser, `@interactive-video-labs/react` version, React version). + +### Suggesting Enhancements + +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: + +* A clear and concise description of the proposed enhancement. +* Why this enhancement would be useful. +* Any potential use cases or examples. + +### Your First Code Contribution + +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). + +### Pull Request Guidelines + +1. **Fork the repository** and create your branch from `main`. +2. **Ensure your code adheres to the existing style** (see [Coding Style](#5-coding-style)). +3. **Add or update tests** for any new features or bug fixes. Ensure all tests pass. +4. **Update documentation** as necessary (e.g., `README.md`, `DEVELOPER.md`). +5. **Write clear and concise commit messages** (see [Commit Messages](#6-commit-messages)). +6. **Open a pull request** to the `main` branch. Provide a clear description of your changes and reference any related issues. + +## 3. Development Setup + +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. + +## 4. Testing + +All new features and bug fixes should be accompanied by appropriate tests. To run the test suite, use: + +```bash +pnpm test +``` + +Ensure all tests pass before submitting a pull request. + +## 5. Coding Style + +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`). + +## 6. Commit Messages + +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. + +Examples: + +* `feat: Add new video playback controls` +* `fix: Resolve issue with cue point triggering` +* `docs: Update README with new usage example` +* `chore: Update dependencies` + +## 7. License + +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. diff --git a/DEVELOPER.md b/DEVELOPER.md index e69de29..6de2134 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -0,0 +1,106 @@ +# DEVELOPER.md + +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. + +## Table of Contents + +1. [Getting Started](#getting-started) +2. [Project Structure](#project-structure) +3. [Available Scripts](#available-scripts) +4. [Testing](#testing) +5. [Building the Project](#building-the-project) +6. [Working with Examples](#working-with-examples) +7. [Contributing](#contributing) +8. [Troubleshooting](#troubleshooting) + +## 1. Getting Started + +To get started with development, follow these steps: + +1. **Clone the repository:** + ```bash + git clone https://github.com/interactive-video-labs/interactive-video-react-wrapper.git + cd interactive-video-react-wrapper + ``` + +2. **Install dependencies:** + This project uses `pnpm` as its package manager. If you don't have `pnpm` installed, you can install it via npm: + ```bash + npm install -g pnpm + ``` + Then, install the project dependencies: + ```bash + pnpm install + ``` + +## 2. Project Structure + +Here's an overview of the key directories and files in this project: + +* `src/`: Contains the main source code for the React wrapper (`index.tsx`). +* `test/`: Contains unit tests for the components (`InteractiveVideo.test.tsx`) and test setup (`setupTests.ts`). +* `examples/`: Contains a simple example React application demonstrating how to use the wrapper. + * `index.html`: The HTML entry point for the example. + * `index.tsx`: The React application code for the example. +* `dist/`: The output directory for the compiled library files. +* `tsup.config.ts`: Configuration for `tsup`, the bundler used to build the library. +* `vitest.config.ts`: Configuration for `Vitest`, the testing framework. +* `package.json`: Project metadata, dependencies, and scripts. + +## 3. Available Scripts + +This project includes several scripts defined in `package.json` to help with development: + +* `pnpm build`: Compiles the TypeScript source code into JavaScript for distribution (`dist` folder). +* `pnpm dev`: Starts `tsup` in watch mode, recompiling the library whenever source files change. +* `pnpm test`: Runs all unit tests using Vitest. +* `pnpm clean`: Removes the `dist` directory. +* `pnpm prepare`: Runs `pnpm build`. This script is typically run before publishing the package. +* `pnpm serve-examples`: Builds the example application and serves it using `http-server`. +* `pnpm build-examples`: Compiles the example application using `esbuild`. + +## 4. Testing + +Tests are written using `Vitest` and `React Testing Library`. You can run all tests with: + +```bash +pnpm test +``` + +When adding new features or fixing bugs, please ensure you add or update relevant tests to maintain code quality and prevent regressions. + +## 5. Building the Project + +The project is built using `tsup`. To compile the library for production, run: + +```bash +pnpm build +``` + +This will generate the compiled JavaScript files and TypeScript declaration files in the `dist` directory. + +## 6. Working with Examples + +The `examples/` directory contains a basic usage example. To run it: + +```bash +pnpm serve-examples +``` + +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. + +## 7. Contributing + +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: + +* Reporting bugs +* Suggesting enhancements +* Submitting pull requests +* Coding style and conventions + +## 8. Troubleshooting + +* **`pnpm` command not found**: Ensure `pnpm` is installed globally (`npm install -g pnpm`). +* **Build errors**: Check the output of `pnpm build` for specific error messages. Ensure all dependencies are installed (`pnpm install`). +* **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. +* **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). diff --git a/README.md b/README.md index a8a619b..39a43e3 100644 --- a/README.md +++ b/README.md @@ -17,4 +17,106 @@ Welcome to `@interactive-video-labs/react` — a lightweight React wrapper aroun 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. ---- \ No newline at end of file +--- + +## Introduction + +`@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. + +## Features + +* **Easy Integration**: Seamlessly embed interactive videos into your React components. +* **Cue Point Management**: Load and manage cue points for dynamic video interactions. +* **Analytics Events**: Receive detailed analytics events from the video player to track user engagement. +* **Localization**: Support for player localization through translations. +* **Direct Core API Access**: Provides a React-friendly interface while maintaining close alignment with the core IVLabsPlayer API. + +## Installation + +You can install the package using npm or pnpm: + +```bash +pnpm add @interactive-video-labs/react @interactive-video-labs/core react react-dom +# or +npm install @interactive-video-labs/react @interactive-video-labs/core react react-dom +``` + +## Usage + +To use the `InteractiveVideo` component, simply import it and pass the necessary props. The `videoUrl` prop is mandatory. + +```tsx +import React from 'react'; +import { InteractiveVideo } from '@interactive-video-labs/react'; + +const MyVideoPlayer = () => { + return ( +
+ { + console.log('Analytics Event:', event, payload); + // Handle analytics events, e.g., send to a tracking service + }} + cues={[ + { time: 10, id: 'intro-cue', type: 'pause' }, + { time: 25, id: 'question-cue', type: 'custom', data: { question: 'What is your favorite color?' } }, + ]} + translations={{ + en: { + play: 'Play Video', + pause: 'Pause Video', + }, + }} + /> +
+ ); +}; + +export default MyVideoPlayer; +``` + +## Props + +The `InteractiveVideo` component accepts the following props: + +* `videoUrl` (string, **required**): The URL of the video to be played. +* `onAnalyticsEvent` (function, optional): A callback function that is triggered when an analytics event occurs. It receives the `event` name and an optional `payload`. + * `event`: `PLAYER_LOADED`, `VIDEO_STARTED`, `VIDEO_PAUSED`, `VIDEO_ENDED`, `CUE_TRIGGERED`, `INTERACTION_COMPLETED`, `ERROR`. + * `payload`: An object containing event-specific data. +* `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. +* `translations` (Translations, optional): An object containing translations for player localization. This should conform to the `@interactive-video-labs/core` `Translations` interface. +* `...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. + +## Development + +To set up the development environment: + +1. Clone the repository. +2. Install dependencies: + ```bash + pnpm install + ``` +3. Build the project: + ```bash + pnpm build + ``` +4. Run tests: + ```bash + pnpm test + ``` +5. Run examples: + ```bash + pnpm serve-examples + ``` + +## Contributing + +We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for more details. + +## License + +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. diff --git a/tsup.config.ts b/tsup.config.ts index 5dcddfa..cabcfbd 100644 --- a/tsup.config.ts +++ b/tsup.config.ts @@ -1,23 +1,16 @@ import { defineConfig } from 'tsup'; import pkg from './package.json'; -export default defineConfig((options) => ({ -export default defineConfig((options) => ({ +export default defineConfig({ entry: ['src/index.tsx'], format: ['esm', 'cjs'], - outExtension: ext => ({ - esm: '.mjs', - cjs: '.cjs', - }), dts: true, - watch: options.watch, clean: true, -})); banner: { js: `/** * ${pkg.name} v${pkg.version} * Author: ${pkg.author} */ - `, + `, }, -})); \ No newline at end of file +}); \ No newline at end of file