npm package: @suniltaneja/reading-time-widget
Description: An embeddable widget that calculates and displays reading time for any webpage
Latest version: 1.0.2

# Reading Time Widget

A lightweight, embeddable web component that calculates and displays reading time for any webpage content. Zero dependencies, fully isolated with Shadow DOM.

## Features

- **Zero dependencies** - Pure vanilla JavaScript
- **Shadow DOM isolation** - Styles won't conflict with your page
- **Smart content detection** - Automatically finds article content
- **Multiple themes** - Light and dark modes
- **Flexible positioning** - Inline, fixed, or floating/draggable
- **Mobile friendly** - Touch support and responsive design
- **Persistent state** - Remembers position and visibility

## Installation

### Via Script Tag

```html
<script src="https://unpkg.com/@suniltaneja/reading-time-widget/dist/reading-time-widget.min.js"></script>
```

### Via NPM

```bash
npm install @suniltaneja/reading-time-widget
```

```javascript
import '@suniltaneja/reading-time-widget';
```

## Usage

Add the widget anywhere in your HTML:

```html
<reading-time-widget></reading-time-widget>
```

That's it! The widget will automatically find your page content and display reading statistics.

## Configuration

Customize the widget using HTML attributes:

```html
<reading-time-widget
  theme="dark"
  wpm="200"
  position="floating"
  selector=".blog-post"
  closable="true">
</reading-time-widget>
```

### Attributes

| Attribute | Default | Description |
|-----------|---------|-------------|
| `selector` | `article, main, .content, .post, .entry-content, [role="main"], body` | CSS selector for content to analyze |
| `wpm` | `230` | Words per minute reading speed |
| `theme` | `light` | Color theme: `light` or `dark` |
| `position` | `inline` | Widget position: `inline`, `fixed-top`, `fixed-bottom`, or `floating` |
| `closable` | `false` (`true` for floating) | Show close button |

### Position Options

- **inline** - Embeds within page flow (default)
- **fixed-top** - Fixed header bar at top of viewport
- **fixed-bottom** - Fixed footer bar at bottom of viewport
- **floating** - Draggable widget, position saved to localStorage

## Examples

### Basic Usage

```html
<reading-time-widget></reading-time-widget>
```

### Dark Theme

```html
<reading-time-widget theme="dark"></reading-time-widget>
```

### Custom Reading Speed

```html
<reading-time-widget wpm="180"></reading-time-widget>
```

### Fixed Position

```html
<reading-time-widget position="fixed-top"></reading-time-widget>
```

### Floating Draggable Widget

```html
<reading-time-widget position="floating"></reading-time-widget>
```

### Target Specific Content

```html
<reading-time-widget selector="#my-article"></reading-time-widget>
```

### Combine Options

```html
<reading-time-widget
  theme="dark"
  wpm="200"
  position="fixed-bottom"
  selector="article">
</reading-time-widget>
```

## JavaScript API

```javascript
const widget = document.querySelector('reading-time-widget');

// Show/hide programmatically
widget.show();
widget.hide();

// Listen to events
widget.addEventListener('close', () => console.log('Widget closed'));
widget.addEventListener('open', () => console.log('Widget opened'));
```

## How It Works

1. **Content Detection** - Finds content using smart CSS selectors, prioritizing semantic elements like `<article>` and `<main>`
2. **Text Extraction** - Clones content and removes non-text elements (scripts, nav, ads, etc.)
3. **Calculation** - Counts words and calculates reading time based on WPM setting
4. **Display** - Shows time (e.g., "5 min read"), word count, and character count

## Browser Support

Works in all modern browsers that support Web Components:
- Chrome 54+
- Firefox 63+
- Safari 10.1+
- Edge 79+

## Development

### Prerequisites

- [Bun](https://bun.sh) runtime

### Setup

```bash
git clone https://github.com/yourusername/reading-time-widget.git
cd reading-time-widget
bun install
```

### Commands

```bash
# Start development server
bun run dev

# Build for production
bun run build

# Clean dist folder
bun run clean
```

## Release (Tag + Auto Publish)

This repo includes a GitHub Actions workflow that publishes the package to npm when you push a version tag that starts with `v` (for example: `v1.0.1`).

### Prerequisites

- Add a repository secret named `NPM_TOKEN` in GitHub:
  - GitHub: **Settings** -> **Secrets and variables** -> **Actions** -> **New repository secret**
  - npm: create an **Automation** access token with publish permissions for `@suniltaneja`

### Create a release tag

1. Update the version in `package.json` (example: `1.0.1`) and commit.
2. Create and push a git tag:

```bash
git tag v1.0.1
git push origin v1.0.1
```

Pushing the tag triggers the workflow in `.github/workflows/publish.yml`, which builds `dist/` and runs `npm publish --access public`.

### Output

The build generates three files in `dist/`:

- `reading-time-widget.min.js` - IIFE bundle for `<script>` tags
- `reading-time-widget.esm.js` - ES module for imports
- `reading-time-widget.d.ts` - TypeScript declarations

## License

MIT