npm package: @harryjwang/simplewordcloud
Description: A simple word cloud generator supporting English and Chinese text
Author: Harry Wang
Latest version: 1.1.0

# SimpleWordCloud

A simple and lightweight word cloud generator for English and Chinese text, built with TypeScript.

## Features

- Supports both English and Chinese text
- Customizable appearance (colors, fonts, sizes, etc.)
- Works in both Node.js and browser environments
- Built with TypeScript for type safety
- Uses simple tokenization algorithms for both English and Chinese text
- Generates SVG-based word clouds using d3-cloud

## Published Package

This package is published on npm as [@harryjwang/simplewordcloud](https://www.npmjs.com/package/@harryjwang/simplewordcloud).

## Installation

```bash
# Using npm
npm install @harryjwang/simplewordcloud

# Using pnpm (recommended)
pnpm add @harryjwang/simplewordcloud

# Using yarn
yarn add @harryjwang/simplewordcloud
```

## Usage

### React

The package includes a React component that can be easily integrated into your React applications.

```tsx
import React from 'react';
import { WordCloud } from '@harryjwang/simplewordcloud/react';

const MyComponent = () => {
  const text = 'This is a sample text for word cloud generation...';
  
  return (
    <WordCloud 
      text={text}
      language="english"
      width={800}
      height={600}
      maxWords={100}
      fontFamily="Arial, sans-serif"
      rotationAngles={[0, 0, 90]}
      rotationProbability={0.2}
    />
  );
};

export default MyComponent;
```

#### Props

The `WordCloud` component accepts the following props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `text` | string | (required) | The text to generate the word cloud from |
| `language` | 'english' \| 'chinese' | 'english' | The language of the text |
| `width` | number | 800 | The width of the word cloud in pixels |
| `height` | number | 600 | The height of the word cloud in pixels |
| `maxWords` | number | 100 | The maximum number of words to include in the word cloud |
| `fontFamily` | string | 'Arial, sans-serif' | The font family to use for the words |
| `rotationAngles` | number[] | [0, 0, 90] | The possible rotation angles for the words |
| `rotationProbability` | number | 0.2 | The probability of a word being rotated |

### Node.js

```typescript
import { NodeSVGGenerator } from '@harryjwang/simplewordcloud';

// Generate a word cloud from English text
const englishText = 'This is a sample English text for word cloud generation...';
const svgString = NodeSVGGenerator.generateSVG(englishText, 'english', 800, 600, 100);

// Generate a word cloud from Chinese text
const chineseText = '这是一个用于生成词云的中文示例文本...';
const svgString2 = NodeSVGGenerator.generateSVG(chineseText, 'chinese', 800, 600, 100);

// Save the SVG to a file
const fs = require('fs');
fs.writeFileSync('wordcloud.svg', svgString);
```

### Browser

```html
<!-- Include the SimpleWordCloud library -->
<!-- Option 1: From node_modules -->
<script src="node_modules/@harryjwang/simplewordcloud/dist/browser/simplewordcloud.min.js"></script>

<!-- Option 2: From CDN (recommended for production) -->
<script src="https://cdn.jsdelivr.net/npm/@harryjwang/simplewordcloud/dist/browser/simplewordcloud.min.js"></script>

<div id="wordcloud-container"></div>

<script>
  // Generate a word cloud
  const text = 'This is a sample text for word cloud generation...';
  const container = document.getElementById('wordcloud-container');
  
  // Generate the word cloud with custom options
  SimpleWordCloud.generateWordCloud(text, 'english', container, {
    width: 800,
    height: 600,
    maxWords: 100,
    fontFamily: 'Arial, sans-serif',
    minFontSize: 10,
    maxFontSize: 60
  });
</script>
```

## API

### `NodeSVGGenerator`

A utility class for generating word clouds in Node.js environments.

#### Methods

- `generateSVG(text: string, language: Language, width?: number, height?: number, maxWords?: number): string` - Generate a word cloud as an SVG string

### `WordCloud`

The main class for generating word clouds in browser environments.

#### Constructor

```typescript
new WordCloud(options?: WordCloudOptions)
```

#### Methods

- `generate(text: string, language: Language): SVGElement | string` - Generate a word cloud as an SVG element (browser) or string (Node.js)
- `generateSVG(text: string, language: Language): string` - Generate a word cloud as an SVG string

### `WordCloudOptions`

Options for customizing the word cloud appearance.

```typescript
interface WordCloudOptions {
  width?: number;            // Width of the word cloud (default: 800)
  height?: number;           // Height of the word cloud (default: 600)
  fontFamily?: string;       // Font family (default: 'Arial, sans-serif')
  maxWords?: number;         // Maximum number of words (default: 100)
  colors?: string[];         // Color scheme (default: d3.schemeCategory10)
  padding?: number;          // Padding between words (default: 5)
  minFontSize?: number;      // Minimum font size (default: 10)
  maxFontSize?: number;      // Maximum font size (default: 60)
  rotationAngles?: number[]; // Rotation angles in degrees (default: [0, 90])
  rotationProbability?: number; // Probability of rotation (default: 0.3)
}
```

### `Language`

Supported languages for tokenization.

```typescript
type Language = 'english' | 'chinese';
```

## Demo

The package includes two demos:

1. **Standard Demo**: A simple HTML/JavaScript demo that shows how to use the library in a browser environment.
2. **React Demo**: A React-based demo that demonstrates how to use the React component.

### Running the Demos

To run the demos locally:

1. Clone this repository
2. Install dependencies: `pnpm install`
3. Build the package: `pnpm run build:all`
4. Start the demo server: `pnpm run start:demo`
5. Open `http://localhost:3000/` in your browser

The server will automatically redirect you to the React demo. You can also access the demos directly:

- Standard Demo: `http://localhost:3000/demo/index.html`
- React Demo: `http://localhost:3000/react`

### React Demo Features

- Input text area for entering custom text
- Language selection (English or Chinese)
- Sample texts for both languages
- Generate button to create/update the word cloud
- Customizable word cloud appearance

Alternatively, you can run the Node.js test script:

```bash
node test/node-test.js
```

This will generate two SVG files in the test directory: `english-wordcloud.svg` and `chinese-wordcloud.svg`.

### Sample Word Clouds

Here are examples of the word clouds generated by the package:

#### English Word Cloud

![English Word Cloud](https://github.com/user-attachments/assets/f0be12eb-8632-4e28-9b7e-ad7736b2530c)

#### Chinese Word Cloud

![Chinese Word Cloud](https://github.com/user-attachments/assets/bceb1f07-3340-4f2a-ad9a-a2a9f042f731)

The test script uses d3-cloud with node-canvas to generate word clouds that look identical to those produced in the browser.

## Browser Compatibility

The package is designed to work in modern browsers. The browser version uses a simplified tokenization approach to avoid dependencies on Node.js-specific modules.

## Development

### Building

```bash
# Build the Node.js version
pnpm run build

# Build the browser version
pnpm run build:browser

# Build the React version
pnpm run build:react

# Build the React demo
pnpm run build:demo

# Build all versions (Node.js, browser, and React)
pnpm run build:all
```

### Testing

The package includes a test script that demonstrates how to use the library in a Node.js environment. The test script uses `d3-cloud` with `node-canvas` to generate word clouds that look identical to those produced in the browser.

```bash
# Install the canvas dependency for testing
pnpm add canvas --save-dev

# Run the test script
node test/node-test.js
```

The test script will generate two SVG files in the test directory: one for English text and one for Chinese text.

## License

MIT