@webeach/gl-circular-progress 0.2.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2025 Ruslan Martynov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

package/README.md

@@ -0,0 +1,118 @@
+<div align="center">
+  <img alt="gl-circular-progress" src="./assets/logo.svg" height="96">
+  <br><br><br>
+  <p>
+    <a href="https://www.npmjs.com/package/@webeach/gl-circular-progress">
+       <img src="https://img.shields.io/npm/v/@webeach/gl-circular-progress.svg?color=646fe1&labelColor=9B7AEF" alt="npm package" />
+    </a>
+    <a href="https://github.com/webeach/gl-circular-progress/actions">
+      <img src="https://img.shields.io/github/actions/workflow/status/webeach/gl-circular-progress/ci.yml?color=646fe1&labelColor=9B7AEF" alt="build" />
+    </a>
+    <a href="https://www.npmjs.com/package/@webeach/gl-circular-progress">
+      <img src="https://img.shields.io/npm/dm/@webeach/gl-circular-progress.svg?color=646fe1&labelColor=9B7AEF" alt="npm downloads" />
+    </a>
+  </p>
+  <p><a href="./README.md">🇺🇸 English version</a> | <a href="./README.ru.md">🇷🇺 Русская версия</a></p>
+  <p>Beautiful WebGL circular progress bars library (Fire and Liquid effects).</p>
+  <br>
+  <p><a href="https://webeach.github.io/gl-circular-progress">👀 View Demo</a></p>
+</div>
+
+---
+
+## 💎 Features
+
+- **WebGL Rendering.** High performance and smooth shader animations.
+- **Stunning Effects.** Ready-to-use presets for `Fire` and `Liquid` simulation.
+- **Fully Customizable.** Configure colors, thickness, speed, intensity, and other parameters.
+- **Lightweight.** **Zero dependencies**, optimized code.
+- **TypeScript.** Full typing out of the box.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @webeach/gl-circular-progress
+```
+
+or
+
+```bash
+pnpm install @webeach/gl-circular-progress
+```
+
+or
+
+```bash
+yarn add @webeach/gl-circular-progress
+```
+
+---
+
+## 📥 Usage
+
+```ts
+import { CircularProgressFire } from '@webeach/gl-circular-progress';
+
+// Find canvas element
+const canvas = document.getElementById('my-canvas');
+
+// Initialize progress bar
+const instance = new CircularProgressFire(canvas, {
+  colors: [0xff5a00, 0xff9a00],
+  progress: 0.5, // Initial value
+  speed: 1.5,
+  thickness: 15,
+});
+
+// Don't forget to clean up when removing the component
+// instance.destroy();
+```
+
+---
+
+## 🛠 Classes and Documentation
+
+The library provides two main classes with different visual effects:
+
+### 🔥 [CircularProgressFire](./docs/en/CircularProgressFire.md)
+Circular progress with a dynamic fire effect. Supports configuration of fire intensity and color gradients.
+
+### 💧 [CircularProgressLiquid](./docs/en/CircularProgressLiquid.md)
+Circular progress with a fluid liquid and metaballs effect. Supports "volume" configuration for creating a 3D lens effect.
+
+---
+
+## 🧩 Dependencies
+
+The library has **Zero external dependencies** and is written in native WebGL.
+
+---
+
+## 🔖 Releasing
+
+Releases are automated with `semantic-release`.
+
+Before publishing a new version, make sure that:
+
+1. All changes are committed and pushed to `main`.
+2. Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+   - `feat: ...` — new features
+   - `fix: ...` — bug fixes
+   - `chore: ...`, `refactor: ...`, etc. — as needed
+3. The next version (`patch`, `minor`, `major`) is derived automatically from the commit types.
+
+---
+
+## 👤 Author
+
+Developed and maintained by [Ruslan Martynov](https://github.com/ruslan-mart).
+
+Have an idea or found a bug? Open an issue or send a pull request.
+
+---
+
+## 📄 License
+
+This package is distributed under the [MIT License](./LICENSE).

package/README.ru.md

@@ -0,0 +1,120 @@
+<div align="center">
+  <img alt="gl-circular-progress" src="./assets/logo.svg" height="96">
+  <br><br><br>
+  <p>
+    <a href="https://www.npmjs.com/package/@webeach/gl-circular-progress">
+       <img src="https://img.shields.io/npm/v/@webeach/gl-circular-progress.svg?color=646fe1&labelColor=9B7AEF" alt="npm package" />
+    </a>
+    <a href="https://github.com/webeach/gl-circular-progress/actions">
+      <img src="https://img.shields.io/github/actions/workflow/status/webeach/gl-circular-progress/ci.yml?color=646fe1&labelColor=9B7AEF" alt="build" />
+    </a>
+    <a href="https://www.npmjs.com/package/@webeach/gl-circular-progress">
+      <img src="https://img.shields.io/npm/dm/@webeach/gl-circular-progress.svg?color=646fe1&labelColor=9B7AEF" alt="npm downloads" />
+    </a>
+  </p>
+  <p><a href="./README.md">🇺🇸 English version</a> | <a href="./README.ru.md">🇷🇺 Русская версия</a></p>
+  <p>Библиотека красивых круговых прогресс-баров на WebGL (эффекты огня и жидкости).</p>
+  <br>
+  <p><a href="https://webeach.github.io/gl-circular-progress">👀 Смотреть Демо</a></p>
+</div>
+
+---
+
+## 💎 Особенности
+
+- **WebGL Рендеринг.** Высокая производительность и плавные анимации шейдеров.
+- **Эффектные стили.** Готовые пресеты для имитации огня (`Fire`) и жидкости (`Liquid`).
+- **Полная кастомизация.** Настройка цветов, толщины, скорости, интенсивности и других параметров.
+- **Легковесность.** Полное отсутствие зависимостей (Zero dependencies), оптимизированный код.
+- **TypeScript.** Полная типизация "из коробки".
+
+---
+
+## 📦 Установка
+
+```bash
+npm install @webeach/gl-circular-progress
+```
+
+или
+
+```bash
+pnpm install @webeach/gl-circular-progress
+```
+
+или
+
+```bash
+yarn add @webeach/gl-circular-progress
+```
+
+---
+
+## 📥 Использование
+
+```ts
+import { CircularProgressFire } from '@webeach/gl-circular-progress';
+
+// Находим canvas элемент
+const canvas = document.getElementById('my-canvas');
+
+// Инициализируем прогресс-бар
+const instance = new CircularProgressFire(canvas, {
+  colors: [0xff5a00, 0xff9a00],
+  progress: 0.5, // Начальное значение
+  speed: 1.5,
+  thickness: 15,
+});
+
+// Не забываем очищать при удалении компонента
+// instance.destroy();
+```
+
+---
+
+## 🛠 Классы и Документация
+
+Библиотека предоставляет два основных класса с различными визуальными эффектами:
+
+### 🔥 [CircularProgressFire](./docs/ru/CircularProgressFire.md)
+Круговой прогресс с динамичным эффектом пламени. Поддерживает настройку интенсивности огня и цветовых градиентов.
+
+### 💧 [CircularProgressLiquid](./docs/ru/CircularProgressLiquid.md)
+Круговой прогресс с эффектом текучей жидкости и метаболлов. Поддерживает настройку "объема" (volume) для создания 3D-эффекта линзы.
+
+---
+
+## 🧩 Зависимости
+
+Библиотека не имеет внешних зависимостей (**Zero dependencies**) и написана на нативном WebGL.
+
+---
+
+## 🔖 Выпуск новой версии
+
+Релизы обрабатываются автоматически с помощью `semantic-release`.
+
+Перед публикацией новой версии убедись, что:
+
+1. Все изменения закоммичены и запушены в ветку `main`.
+2. Сообщения коммитов соответствуют формату [Conventional Commits](https://www.conventionalcommits.org/ru/v1.0.0/):
+   - `feat: ...` — для новых фич
+   - `fix: ...` — для исправлений багов
+   - `chore: ...`, `refactor: ...` и другие типы — по необходимости
+3. Версионирование определяется автоматически на основе типа коммитов (`patch`, `minor`, `major`).
+
+---
+
+## 👨‍💻 Автор
+
+Разработка и поддержка: [Руслан Мартынов](https://github.com/ruslan-mart)
+
+Если у тебя есть предложения или найден баг, открывай issue или отправляй pull request.
+
+---
+
+## 📄 Лицензия
+
+Этот пакет распространяется под [лицензией MIT](./LICENSE).
+
+

package/docs/en/CircularProgressFire.md

@@ -0,0 +1,105 @@
+# CircularProgressFire
+
+## Description
+
+`CircularProgressFire` is a class for creating a circular progress bar with a **fire** effect using WebGL.
+It allows flexible customization of colors, speed, and intensity of the flame.
+
+The effect is rendered on the provided HTML `<canvas>` element.
+
+[👀 View Demo](https://webeach.github.io/gl-circular-progress/CircularProgressFire.html)
+
+---
+
+## Signature
+
+```ts
+new CircularProgressFire(container: HTMLCanvasElement, options: CircularProgressFireOptions)
+```
+
+- **Parameters**
+   - `container: HTMLCanvasElement` — the canvas element where the progress will be rendered.
+   - `options: CircularProgressFireOptions` — configuration object.
+
+---
+
+## Examples
+
+### Basic Usage
+
+```ts
+import { CircularProgressFire } from '@webeach/gl-circular-progress';
+
+const canvas = document.getElementById('canvas') as HTMLCanvasElement;
+
+const instance = new CircularProgressFire(canvas, {
+  colors: [0xff5a00, 0xff9a00, 0xffce00], // Fire colors
+  intensity: 1.0,
+  progress: 0.75, // Initial value
+  speed: 1.5,
+  thickness: 20,
+});
+```
+
+### Dynamic Updates
+
+All properties can be changed on the fly using the instance setters.
+
+```ts
+instance.colors = [0xff0000, 0x00ff00]; // Change gradient
+instance.intensity = 0.5; // Reduce fire intensity
+instance.speed = 2.0; // Speed up animation
+```
+
+---
+
+## API
+
+### Options (`CircularProgressFireOptions`)
+
+Configuration object passed to the constructor.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `colors`     | `number[]` | `[0x000000]` | **Required.** Array of HEX colors (e.g. `0xff5a00`). Used for the gradient. |
+| `intensity`  | `number`   | `1.0`        | Intensity of the fire effect. |
+| `progress`   | `number`   | `0`          | Initial progress value (0.0 to 1.0). |
+| `reversed`   | `boolean`  | `false`      | Fill direction. If `true`, progress fills counter-clockwise. |
+| `speed`      | `number`   | `1.0`        | Animation speed of the flame. |
+| `startAngle` | `number`   | `0`          | Starting angle of the progress in degrees. |
+| `thickness`  | `number`   | `10`         | Thickness of the progress ring in pixels. |
+
+### Instance Methods and Properties
+
+After creating an instance, the following methods and properties are available:
+
+#### `destroy(): void`
+
+Cleans up WebGL resources, removes event listeners (resize), and stops the animation. Must be called before removing the component.
+
+#### Properties
+
+The following properties can be read and written for dynamic updates:
+
+- `colors`: `number[]`
+- `intensity`: `number`
+- `progress`: `number`
+- `reversed`: `boolean`
+- `speed`: `number`
+- `startAngle`: `number`
+- `thickness`: `number`
+
+---
+
+## Typing
+
+```ts
+import type { CircularProgressFireOptions } from '@webeach/gl-circular-progress';
+```
+
+---
+
+## See Also
+
+- [CircularProgressLiquid](./CircularProgressLiquid.md) — liquid effect.
+

package/docs/en/CircularProgressLiquid.md

@@ -0,0 +1,106 @@
+# CircularProgressLiquid
+
+## Description
+
+`CircularProgressLiquid` is a class for creating a circular progress bar with a **liquid** (metaballs) effect using WebGL.
+It allows creating smooth animations with customizable volume distortion (lens effect).
+
+The effect is rendered on the provided HTML `<canvas>` element.
+
+[👀 View Demo](https://webeach.github.io/gl-circular-progress/CircularProgressLiquid.html)
+
+---
+
+## Signature
+
+```ts
+new CircularProgressLiquid(container: HTMLCanvasElement, options: CircularProgressLiquidOptions)
+```
+
+- **Parameters**
+   - `container: HTMLCanvasElement` — the canvas element where the progress will be rendered.
+   - `options: CircularProgressLiquidOptions` — configuration object.
+
+---
+
+## Examples
+
+### Basic Usage
+
+```ts
+import { CircularProgressLiquid } from '@webeach/gl-circular-progress/CircularProgressLiquid';
+
+const canvas = document.getElementById('canvas') as HTMLCanvasElement;
+
+const instance = new CircularProgressLiquid(canvas, {
+  colors: [0x00c6ff, 0x0072ff], // Liquid colors
+  progress: 0.6, // Initial value
+  speed: 0.5,
+  startAngle: -90, // Start from left
+  thickness: 30,
+  volume: 0.5, // Volume/Lens effect
+});
+```
+
+### Dynamic Updates
+
+All properties can be changed on the fly using the instance setters.
+
+```ts
+instance.speed = 1.2; // Speed up flow
+instance.volume = 0.8; // Increase lens effect
+instance.reversed = true; // Change direction
+```
+
+---
+
+## API
+
+### Options (`CircularProgressLiquidOptions`)
+
+Configuration object passed to the constructor.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `colors`     | `number[]` | `[0x000000]` | **Required.** Array of HEX colors. Used for the liquid gradient. |
+| `progress`   | `number`   | `0`          | Initial progress value (0.0 to 1.0). |
+| `reversed`   | `boolean`  | `false`      | Fill direction. If `true`, progress fills counter-clockwise. |
+| `speed`      | `number`   | `1.0`        | Animation speed of the liquid waves. |
+| `startAngle` | `number`   | `0`          | Starting angle of the progress in degrees. |
+| `thickness`  | `number`   | `10`         | Thickness of the progress ring in pixels. |
+| `volume`     | `number`   | `0`          | Volume effect (lens/3D). Value from `0.0` (flat) to `1.0` (strong effect). |
+
+### Instance Methods and Properties
+
+After creating an instance, the following methods and properties are available:
+
+#### `destroy(): void`
+
+Cleans up WebGL resources, removes event listeners, and stops the animation. Must be called before removing the component.
+
+#### Properties
+
+The following properties can be read and written for dynamic updates:
+
+- `colors`: `number[]`
+- `progress`: `number`
+- `reversed`: `boolean`
+- `speed`: `number`
+- `startAngle`: `number`
+- `thickness`: `number`
+- `volume`: `number`
+
+---
+
+## Typing
+
+```ts
+import type { CircularProgressLiquidOptions } from '@webeach/gl-circular-progress/CircularProgressLiquid';
+```
+
+---
+
+## See Also
+
+- [CircularProgressFire](./CircularProgressFire.md) — fire effect.
+

package/lib/cjs/classes/BaseCircularProgress/BaseCircularProgress.js

@@ -0,0 +1,151 @@
+'use strict';
+
+var constants = require('./constants.js');
+
+/**
+ * Abstract base class for circular progress indicators.
+ * Handles common state and lifecycle management.
+ */
+class BaseCircularProgress {
+    state;
+    canvas;
+    canvasHeight = 0;
+    canvasWidth = 0;
+    dpr = 1;
+    isDestroyed = false;
+    resizeObserver = null;
+    /**
+     * Creates an instance of BaseCircularProgress.
+     *
+     * @param canvas - The HTMLCanvasElement to render on.
+     * @param options - Configuration options.
+     */
+    constructor(canvas, options) {
+        this.canvas = canvas;
+        this.dpr = window.devicePixelRatio;
+        this.state = {
+            colors: [...options.colors],
+            progress: options.progress ?? 0,
+            reversed: options.reversed ?? constants.DEFAULT_REVERSED,
+            speed: options.speed ?? constants.DEFAULT_SPEED,
+            startAngle: options.startAngle ?? constants.DEFAULT_START_ANGLE,
+            thickness: options.thickness ?? constants.DEFAULT_THICKNESS,
+        };
+        this.handleResize = this.handleResize.bind(this);
+        this.resizeObserver = new ResizeObserver(this.handleResize);
+        this.resizeObserver.observe(this.canvas);
+        window.addEventListener('resize', this.handleResize);
+    }
+    /**
+     * Cleans up resources, event listeners, and stops animations.
+     * Must be called when the instance is no longer needed.
+     */
+    destroy() {
+        this.isDestroyed = true;
+        if (this.resizeObserver) {
+            this.resizeObserver.disconnect();
+            this.resizeObserver = null;
+        }
+        window.removeEventListener('resize', this.handleResize);
+    }
+    /**
+     * Gets the current colors array.
+     */
+    get colors() {
+        return [...this.state.colors];
+    }
+    /**
+     * Sets the colors array and updates rendering.
+     */
+    set colors(value) {
+        this.state.colors = [...value];
+        this.updateColors();
+    }
+    /**
+     * Gets the current progress value.
+     */
+    get progress() {
+        return this.state.progress;
+    }
+    /**
+     * Sets the progress value.
+     */
+    set progress(value) {
+        const clamped = Math.max(0, Math.min(1, value));
+        this.state.progress = clamped;
+        this.updateProgress(clamped);
+    }
+    /**
+     * Gets whether the progress fills in reverse direction.
+     */
+    get reversed() {
+        return this.state.reversed;
+    }
+    /**
+     * Sets the reverse direction flag and updates rendering.
+     */
+    set reversed(value) {
+        this.state.reversed = value;
+        this.updateReversed();
+    }
+    /**
+     * Gets the current animation speed.
+     */
+    get speed() {
+        return this.state.speed;
+    }
+    /**
+     * Sets the animation speed and updates rendering.
+     */
+    set speed(value) {
+        this.state.speed = value;
+        this.updateSpeed();
+    }
+    /**
+     * Gets the current start angle in degrees.
+     */
+    get startAngle() {
+        return this.state.startAngle;
+    }
+    /**
+     * Sets the start angle and updates rendering.
+     */
+    set startAngle(value) {
+        this.state.startAngle = value;
+        this.updateStartAngle();
+    }
+    /**
+     * Gets the current thickness in pixels.
+     */
+    get thickness() {
+        return this.state.thickness;
+    }
+    /**
+     * Sets the thickness and updates rendering.
+     */
+    set thickness(value) {
+        this.state.thickness = value;
+        this.updateThickness();
+    }
+    /**
+     * Handles canvas resize events from ResizeObserver.
+     * Updates canvas dimensions with devicePixelRatio and calls resize().
+     */
+    handleResize() {
+        const dpr = window.devicePixelRatio || 1;
+        const displayWidth = this.canvas.clientWidth;
+        const displayHeight = this.canvas.clientHeight;
+        this.canvasWidth = Math.floor(displayWidth * dpr);
+        this.canvasHeight = Math.floor(displayHeight * dpr);
+        this.dpr = dpr;
+        if (this.canvas.width !== this.canvasWidth ||
+            this.canvas.height !== this.canvasHeight) {
+            this.canvas.width = this.canvasWidth;
+            this.canvas.height = this.canvasHeight;
+        }
+        this.resize();
+    }
+}
+
+exports.BaseCircularProgress = BaseCircularProgress;
+//# sourceMappingURL=BaseCircularProgress.js.map

package/lib/cjs/classes/BaseCircularProgress/BaseCircularProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseCircularProgress.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/lib/cjs/classes/BaseCircularProgress/constants.js

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * Default colors (Black).
+ */
+/**
+ * Default reversed state (false).
+ */
+const DEFAULT_REVERSED = false;
+/**
+ * Default animation speed (1.0).
+ */
+const DEFAULT_SPEED = 1.0;
+/**
+ * Default start angle (0 degrees).
+ */
+const DEFAULT_START_ANGLE = 0;
+/**
+ * Default thickness (10px).
+ */
+const DEFAULT_THICKNESS = 10;
+
+exports.DEFAULT_REVERSED = DEFAULT_REVERSED;
+exports.DEFAULT_SPEED = DEFAULT_SPEED;
+exports.DEFAULT_START_ANGLE = DEFAULT_START_ANGLE;
+exports.DEFAULT_THICKNESS = DEFAULT_THICKNESS;
+//# sourceMappingURL=constants.js.map

package/lib/cjs/classes/BaseCircularProgress/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/lib/cjs/classes/BaseCircularProgress/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+var BaseCircularProgress = require('./BaseCircularProgress.js');
+
+
+
+exports.BaseCircularProgress = BaseCircularProgress.BaseCircularProgress;
+//# sourceMappingURL=index.js.map

package/lib/cjs/classes/BaseCircularProgress/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}