npm package: @jfcmontmorency/maze-widget
Description: Canvas maze widget (ES module)
Author: JF Cartier
Latest version: 1.0.3

# @jfcmontmorency/maze-widget

A lightweight, customizable maze generator with HTML5 Canvas rendering. Create beautiful, interactive mazes with configurable options and ES module support.

[![npm version](https://badge.fury.io/js/@jfcmontmorency%2Fmaze-widget.svg)](https://www.npmjs.com/package/@jfcmontmorency/maze-widget)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Customizable**: Configure colors, dimensions, entry/exit points
- **Deterministic**: Use seeds for reproducible maze generation
- **Responsive**: Automatically adapts to container size
- **Lightweight**: Zero dependencies, pure JavaScript
- **ES Modules**: Modern JavaScript module support
- **TypeScript Ready**: Works seamlessly with TypeScript projects

## Installation

```bash
npm install @jfcmontmorency/maze-widget
```

## Quick Start

### Basic Usage

```javascript
import { createMazeWidget } from '@jfcmontmorency/maze-widget';

// Create a simple maze
const maze = createMazeWidget('#maze-container');
```

### HTML Structure

```html
<div id="maze-container" style="width: 400px; height: 400px;"></div>
```

## API Reference

### `createMazeWidget(mount, options)`

Creates a new maze widget instance.

#### Parameters

- **`mount`** `{HTMLElement|string}` - Container element or CSS selector
- **`options`** `{Object}` - Configuration options (optional)

#### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `cols` | `number` | `5` | Number of columns in the maze |
| `rows` | `number` | `5` | Number of rows in the maze |
| `wallColor` | `string` | `"#ffffff"` | Color of the maze walls |
| `bgColor` | `string` | `"#000000"` | Background color |
| `lineWidthRatio` | `number` | `0.25` | Wall thickness as ratio of cell size |
| `seed` | `number` | `983811` | Random seed for consistent maze generation |
| `entry` | `Object` | `{x: 0, y: 0, side: "top"}` | Entry point configuration |
| `exit` | `Object` | `{x: null, y: null, side: "bottom"}` | Exit point configuration |
| `squareBy` | `string` | `"width"` | How to calculate dimensions (`"width"` or `"min"`) |
| `padding` | `number` | `0` | Internal padding in pixels |

#### Returns

An API object with the following methods:

- **`regenerate()`** - Generate a new maze with current options
- **`redraw()`** - Redraw the current maze
- **`setOptions(options)`** - Update options and redraw
- **`destroy()`** - Clean up and remove the widget
- **`getState()`** - Get current state (options, grid, canvas, mount)

## Examples

### Custom Styling

```javascript
const maze = createMazeWidget('#container', {
  cols: 15,
  rows: 15,
  wallColor: '#ff6b6b',
  bgColor: '#4ecdc4',
  lineWidthRatio: 0.3,
  padding: 10
});
```

### Using Seeds for Reproducible Mazes

```javascript
// Generate the same maze every time
const maze = createMazeWidget('#container', {
  cols: 10,
  rows: 10,
  seed: 12345
});

// Generate a random maze
const randomMaze = createMazeWidget('#container', {
  seed: Math.floor(Math.random() * 1000000)
});
```

### Dynamic Options

```javascript
const maze = createMazeWidget('#container');

// Change maze size
maze.setOptions({ cols: 20, rows: 15 });

// Change colors
maze.setOptions({ 
  wallColor: '#2c3e50', 
  bgColor: '#ecf0f1' 
});

// Generate new maze with same settings
maze.regenerate();
```

### Custom Entry and Exit Points

```javascript
const maze = createMazeWidget('#container', {
  cols: 12,
  rows: 8,
  entry: { x: 0, y: 0, side: 'left' },
  exit: { x: 11, y: 7, side: 'right' }
});
```

### Responsive Design

```javascript
// The maze automatically adapts to container size
const maze = createMazeWidget('#responsive-container', {
  cols: 15,
  rows: 15,
  squareBy: 'min' // Use minimum of width/height for square cells
});

// Listen for container size changes
window.addEventListener('resize', () => {
  maze.redraw();
});
```

## Advanced Usage

### Getting Maze State

```javascript
const maze = createMazeWidget('#container');
const state = maze.getState();

console.log(state.options);  // Current configuration
console.log(state.grid);     // Maze grid data
console.log(state.canvas);   // Canvas element
console.log(state.mount);    // Mount element
```

### Cleanup

```javascript
const maze = createMazeWidget('#container');

// Clean up when no longer needed
maze.destroy();
```

## Browser Support

- Chrome/Edge 88+
- Firefox 78+
- Safari 14+

Requires ES2020 support and Canvas API.

## TypeScript

While this package is written in JavaScript, it works seamlessly with TypeScript projects:

```typescript
import { createMazeWidget } from '@jfcmontmorency/maze-widget';

interface MazeOptions {
  cols?: number;
  rows?: number;
  wallColor?: string;
  bgColor?: string;
  // ... other options
}

const options: MazeOptions = {
  cols: 10,
  rows: 10,
  wallColor: '#333'
};

const maze = createMazeWidget('#container', options);
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT © [JF Cartier](https://github.com/jfcmontmorency)

## Repository

[https://github.com/jfcmontmorency/maze-widget](https://github.com/jfcmontmorency/maze-widget)