v10/packages/html/html-icons/README.md

@vjs-10/html-icons

Web Component icon elements for Video.js

Status: Early Development

⚠️ PROTOTYPE - SUBJECT TO CHANGE

This package is in early prototype phase. Expect significant changes including:

• Package restructuring and naming
• Breaking API changes
• Major architectural updates
• Incomplete or experimental features

Not recommended for production use.

Overview

@vjs-10/html-icons provides Web Component implementations of Video.js icons. These are DOM-ready icon elements that can be used directly in HTML or with any framework that supports custom elements.

Key Features

• Web Components - Custom element icon implementations
• Framework Agnostic - Works with vanilla JS, React, Vue, Angular, etc.
• Accessible - Built-in ARIA attributes and semantic markup
• Customizable - Style with CSS custom properties
• Lightweight - Minimal runtime overhead

Installation

npm install @vjs-10/html-icons

Quick Start

Import and Use

import '@vjs-10/html-icons';

// Or import specific icons
import '@vjs-10/html-icons/play';
import '@vjs-10/html-icons/pause';

In HTML

<!-- After importing, use custom elements -->
<vjs-icon-play></vjs-icon-play>
<vjs-icon-pause></vjs-icon-pause>
<vjs-icon-volume-high></vjs-icon-volume-high>
<vjs-icon-volume-low></vjs-icon-volume-low>
<vjs-icon-volume-off></vjs-icon-volume-off>
<vjs-icon-fullscreen-enter></vjs-icon-fullscreen-enter>
<vjs-icon-fullscreen-exit></vjs-icon-fullscreen-exit>

With JavaScript

import { PauseIcon, PlayIcon, VolumeHighIcon } from '@vjs-10/html-icons';

// Create icon element
const playIcon = new PlayIcon();
document.body.appendChild(playIcon);

// Or use createElement
const pauseIcon = document.createElement('vjs-icon-pause');
document.body.appendChild(pauseIcon);

Styling

CSS Custom Properties

vjs-icon-play {
  /* Size */
  --icon-size: 24px;

  /* Color */
  --icon-color: #fff;

  /* Opacity */
  --icon-opacity: 1;

  /* Additional styles */
  width: var(--icon-size);
  height: var(--icon-size);
  color: var(--icon-color);
}

Standard CSS

vjs-icon-play {
  width: 32px;
  height: 32px;
  color: blue;
  cursor: pointer;
  transition: color 0.2s;
}

vjs-icon-play:hover {
  color: lightblue;
}

Available Icons

Playback Controls

• <vjs-icon-play> - Play button
• <vjs-icon-pause> - Pause button
• <vjs-icon-spinner> - Loading spinner

Volume Controls

• <vjs-icon-volume-high> - High volume
• <vjs-icon-volume-low> - Low volume
• <vjs-icon-volume-off> - Muted

Screen Controls

• <vjs-icon-fullscreen-enter> - Enter fullscreen
• <vjs-icon-fullscreen-exit> - Exit fullscreen
• <vjs-icon-fullscreen-enter-alt> - Alternative fullscreen enter
• <vjs-icon-fullscreen-exit-alt> - Alternative fullscreen exit

Usage Examples

Button with Icon

<button class="play-button">
  <vjs-icon-play></vjs-icon-play>
  <span>Play Video</span>
</button>

<style>
  .play-button {
    display: flex;
    align-items: center;
    gap: 8px;
  }

  vjs-icon-play {
    width: 20px;
    height: 20px;
  }
</style>

Toggle Icon State

import { PauseIcon, PlayIcon } from '@vjs-10/html-icons';

const button = document.querySelector('.play-pause-button');
let isPlaying = false;

button.addEventListener('click', () => {
  isPlaying = !isPlaying;

  // Replace icon
  const oldIcon = button.querySelector('vjs-icon-play, vjs-icon-pause');
  const newIcon = isPlaying
    ? new PauseIcon()
    : new PlayIcon();

  oldIcon?.replaceWith(newIcon);
});

With Framework (React Example)

// React automatically supports Web Components
function PlayButton() {
  return (
    <button>
      <vjs-icon-play></vjs-icon-play>
      Play
    </button>
  );
}

Dynamic Icon Selection

const iconMap = {
  play: 'vjs-icon-play',
  pause: 'vjs-icon-pause',
  'volume-high': 'vjs-icon-volume-high',
  'volume-off': 'vjs-icon-volume-off',
};

function createIcon(name: keyof typeof iconMap) {
  return document.createElement(iconMap[name]);
}

const playIcon = createIcon('play');
const volumeIcon = createIcon('volume-high');

Accessibility

All icon components include:

• ARIA labels - Screen reader friendly descriptions
• Role attributes - Semantic roles for assistive tech
• Focusable - Keyboard navigation support

<!-- Automatically includes accessibility attributes -->
<vjs-icon-play role="img" aria-label="Play"> </vjs-icon-play>

Architecture

@vjs-10/icons (SVG source)
    ↓
@vjs-10/html-icons (Web Components)
    ↓
@vjs-10/html (Complete player UI)

This package:

• Transforms SVG sources into Web Components
• Registers custom elements in the browser
• Provides a DOM-native icon system

API Reference

Icon Element Interface

interface IconElement extends HTMLElement {
  // Standard HTML element properties
  className: string;
  style: CSSStyleDeclaration;

  // Custom properties
  size?: number;
  color?: string;
}

Methods

// All standard HTMLElement methods available
icon.setAttribute('aria-label', 'Custom label');
icon.classList.add('custom-class');
icon.style.width = '32px';

Package Dependencies

• Dependencies: @vjs-10/icons (SVG source assets)
• Used by: @vjs-10/html (HTML player UI)

Development

# Build the package
pnpm build

# Watch mode for development
pnpm dev

# Run tests
pnpm test

# Clean build artifacts
pnpm clean

Browser Support

Web Components require:

• Chrome 54+
• Firefox 63+
• Safari 10.1+
• Edge 79+

For older browsers, use a Web Components polyfill.

Related Packages

• @vjs-10/icons - Source SVG assets
• @vjs-10/react-icons - React icon components
• @vjs-10/html - Complete HTML player

License

Apache-2.0