@konfetti-js/web-components 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrea Bettich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @konfetti-js/web-components
+
+Custom elements for [konfetti.js](https://andreabettich.github.io/konfetti.js/), usable in any framework or plain HTML. Installs `@konfetti-js/core` for you and is safe to import during server rendering.
+
+```bash
+npm install @konfetti-js/web-components
+```
+
+```html
+<script type="module">
+  import { defineAllElements } from '@konfetti-js/web-components';
+  defineAllElements();
+</script>
+
+<!-- Fires from itself when clicked -->
+<konfetti-trigger preset="fireworks">
+  <button>Click me!</button>
+</konfetti-trigger>
+
+<!-- Fire from your own code -->
+<konfetti-burst id="burst" preset="cannon" particle-count="150"></konfetti-burst>
+<script>
+  document.getElementById('burst').fire();
+</script>
+```
+
+Attributes use kebab-case option names (`particle-count`, `start-velocity`, `origin-x`, `z-index`, comma-separated `colors`). `trigger` changes the event for `<konfetti-trigger>`, and both elements dispatch `konfetti-fired`. See the [full documentation](https://github.com/andreabettich/konfetti.js#readme).
+
+MIT licensed.

package/dist/index.cjs

@@ -0,0 +1,168 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  KonfettiElement: () => KonfettiElement,
+  KonfettiTriggerElement: () => KonfettiTriggerElement,
+  defineAllElements: () => defineAllElements,
+  defineKonfettiElement: () => defineKonfettiElement,
+  defineKonfettiTriggerElement: () => defineKonfettiTriggerElement
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/KonfettiElement.ts
+var import_core2 = require("@konfetti-js/core");
+
+// src/attributes.ts
+var import_core = require("@konfetti-js/core");
+var BaseElement = typeof HTMLElement === "undefined" ? class {
+} : HTMLElement;
+var NUMBER_ATTRIBUTES = {
+  "particle-count": "particleCount",
+  angle: "angle",
+  spread: "spread",
+  "start-velocity": "startVelocity",
+  decay: "decay",
+  gravity: "gravity",
+  drift: "drift",
+  ticks: "ticks",
+  scalar: "scalar",
+  "z-index": "zIndex"
+};
+function readNumber(el, name) {
+  const raw = el.getAttribute(name);
+  if (raw === null || raw.trim() === "") return void 0;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : void 0;
+}
+function readList(el, name) {
+  const raw = el.getAttribute(name);
+  if (!raw) return void 0;
+  const items = raw.split(",").map((item) => item.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+function readOptions(el) {
+  const options = {};
+  for (const [attribute, option] of Object.entries(NUMBER_ATTRIBUTES)) {
+    const value = readNumber(el, attribute);
+    if (value !== void 0) options[option] = value;
+  }
+  const origin = {};
+  const originX = readNumber(el, "origin-x");
+  const originY = readNumber(el, "origin-y");
+  if (originX !== void 0) origin.x = originX;
+  if (originY !== void 0) origin.y = originY;
+  if (Object.keys(origin).length > 0) options.origin = origin;
+  const colors = readList(el, "colors");
+  if (colors) options.colors = colors;
+  const shapes = readList(el, "shapes");
+  if (shapes) options.shapes = shapes;
+  return options;
+}
+function readPreset(el) {
+  const preset = el.getAttribute("preset");
+  return (0, import_core.isPresetName)(preset) ? preset : void 0;
+}
+
+// src/KonfettiElement.ts
+var KonfettiElement = class extends BaseElement {
+  /** Fire konfetti with the element's attributes, optionally overridden */
+  fire(overrides) {
+    const options = { ...readOptions(this) };
+    for (const [key, value] of Object.entries(overrides ?? {})) {
+      if (value !== void 0) options[key] = value;
+    }
+    const preset = readPreset(this);
+    if (preset) {
+      (0, import_core2.firePreset)(preset, options);
+    } else {
+      (0, import_core2.fire)(options);
+    }
+    this.dispatchEvent(new CustomEvent("konfetti-fired", { detail: options }));
+  }
+  /** Clear all konfetti */
+  reset() {
+    (0, import_core2.reset)();
+  }
+};
+function defineKonfettiElement(tagName = "konfetti-burst") {
+  if (typeof customElements === "undefined") return;
+  if (!customElements.get(tagName)) {
+    customElements.define(tagName, KonfettiElement);
+  }
+}
+
+// src/KonfettiTriggerElement.ts
+var import_core3 = require("@konfetti-js/core");
+var KonfettiTriggerElement = class extends BaseElement {
+  constructor() {
+    super(...arguments);
+    /** The event the listener is currently attached to, if any */
+    this.boundTrigger = null;
+    this.handleTrigger = () => {
+      const options = readOptions(this);
+      (0, import_core3.fireFromElement)(this, { ...options, preset: readPreset(this) });
+      this.dispatchEvent(new CustomEvent("konfetti-fired", { detail: options }));
+    };
+  }
+  connectedCallback() {
+    this.bind();
+  }
+  disconnectedCallback() {
+    this.unbind();
+  }
+  attributeChangedCallback() {
+    if (this.isConnected) this.bind();
+  }
+  bind() {
+    const trigger = this.getAttribute("trigger") || "click";
+    if (trigger === this.boundTrigger) return;
+    this.unbind();
+    this.addEventListener(trigger, this.handleTrigger);
+    this.boundTrigger = trigger;
+  }
+  unbind() {
+    if (this.boundTrigger === null) return;
+    this.removeEventListener(this.boundTrigger, this.handleTrigger);
+    this.boundTrigger = null;
+  }
+};
+KonfettiTriggerElement.observedAttributes = ["trigger"];
+function defineKonfettiTriggerElement(tagName = "konfetti-trigger") {
+  if (typeof customElements === "undefined") return;
+  if (!customElements.get(tagName)) {
+    customElements.define(tagName, KonfettiTriggerElement);
+  }
+}
+
+// src/define.ts
+function defineAllElements() {
+  defineKonfettiElement();
+  defineKonfettiTriggerElement();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KonfettiElement,
+  KonfettiTriggerElement,
+  defineAllElements,
+  defineKonfettiElement,
+  defineKonfettiTriggerElement
+});

package/dist/index.d.cts

@@ -0,0 +1,95 @@
+import { KonfettiOptions } from '@konfetti-js/core';
+
+/**
+ * Register all konfetti custom elements
+ *
+ * @example
+ * ```html
+ * <script type="module">
+ *   import { defineAllElements } from '@konfetti-js/web-components';
+ *   defineAllElements();
+ * </script>
+ *
+ * <konfetti-trigger preset="fireworks">
+ *   <button>Click me!</button>
+ * </konfetti-trigger>
+ * ```
+ */
+declare function defineAllElements(): void;
+
+/**
+ * Base class that does not touch HTMLElement on the server, so importing this
+ * package during server rendering does not throw
+ */
+declare const BaseElement: typeof HTMLElement;
+
+/**
+ * Custom element for firing konfetti from your own code
+ *
+ * @example
+ * ```html
+ * <!-- Register the element -->
+ * <script type="module">
+ *   import { defineKonfettiElement } from '@konfetti-js/web-components';
+ *   defineKonfettiElement();
+ * </script>
+ *
+ * <!-- Use it -->
+ * <konfetti-burst
+ *   particle-count="100"
+ *   spread="70"
+ *   preset="fireworks"
+ * ></konfetti-burst>
+ *
+ * <!-- Trigger via JavaScript -->
+ * <script>
+ *   document.querySelector('konfetti-burst').fire();
+ * </script>
+ * ```
+ */
+declare class KonfettiElement extends BaseElement {
+    /** Fire konfetti with the element's attributes, optionally overridden */
+    fire(overrides?: KonfettiOptions): void;
+    /** Clear all konfetti */
+    reset(): void;
+}
+/** Register the konfetti-burst custom element */
+declare function defineKonfettiElement(tagName?: string): void;
+
+/**
+ * Custom element that fires konfetti from itself on click (or the `trigger` event)
+ *
+ * @example
+ * ```html
+ * <!-- Register the element -->
+ * <script type="module">
+ *   import { defineKonfettiTriggerElement } from '@konfetti-js/web-components';
+ *   defineKonfettiTriggerElement();
+ * </script>
+ *
+ * <!-- Use it -->
+ * <konfetti-trigger particle-count="100" spread="70">
+ *   <button>Click me!</button>
+ * </konfetti-trigger>
+ *
+ * <!-- With preset -->
+ * <konfetti-trigger preset="fireworks">
+ *   <button>Fireworks!</button>
+ * </konfetti-trigger>
+ * ```
+ */
+declare class KonfettiTriggerElement extends BaseElement {
+    static observedAttributes: string[];
+    /** The event the listener is currently attached to, if any */
+    private boundTrigger;
+    private readonly handleTrigger;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private bind;
+    private unbind;
+}
+/** Register the konfetti-trigger custom element */
+declare function defineKonfettiTriggerElement(tagName?: string): void;
+
+export { KonfettiElement, KonfettiTriggerElement, defineAllElements, defineKonfettiElement, defineKonfettiTriggerElement };

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import { KonfettiOptions } from '@konfetti-js/core';
+
+/**
+ * Register all konfetti custom elements
+ *
+ * @example
+ * ```html
+ * <script type="module">
+ *   import { defineAllElements } from '@konfetti-js/web-components';
+ *   defineAllElements();
+ * </script>
+ *
+ * <konfetti-trigger preset="fireworks">
+ *   <button>Click me!</button>
+ * </konfetti-trigger>
+ * ```
+ */
+declare function defineAllElements(): void;
+
+/**
+ * Base class that does not touch HTMLElement on the server, so importing this
+ * package during server rendering does not throw
+ */
+declare const BaseElement: typeof HTMLElement;
+
+/**
+ * Custom element for firing konfetti from your own code
+ *
+ * @example
+ * ```html
+ * <!-- Register the element -->
+ * <script type="module">
+ *   import { defineKonfettiElement } from '@konfetti-js/web-components';
+ *   defineKonfettiElement();
+ * </script>
+ *
+ * <!-- Use it -->
+ * <konfetti-burst
+ *   particle-count="100"
+ *   spread="70"
+ *   preset="fireworks"
+ * ></konfetti-burst>
+ *
+ * <!-- Trigger via JavaScript -->
+ * <script>
+ *   document.querySelector('konfetti-burst').fire();
+ * </script>
+ * ```
+ */
+declare class KonfettiElement extends BaseElement {
+    /** Fire konfetti with the element's attributes, optionally overridden */
+    fire(overrides?: KonfettiOptions): void;
+    /** Clear all konfetti */
+    reset(): void;
+}
+/** Register the konfetti-burst custom element */
+declare function defineKonfettiElement(tagName?: string): void;
+
+/**
+ * Custom element that fires konfetti from itself on click (or the `trigger` event)
+ *
+ * @example
+ * ```html
+ * <!-- Register the element -->
+ * <script type="module">
+ *   import { defineKonfettiTriggerElement } from '@konfetti-js/web-components';
+ *   defineKonfettiTriggerElement();
+ * </script>
+ *
+ * <!-- Use it -->
+ * <konfetti-trigger particle-count="100" spread="70">
+ *   <button>Click me!</button>
+ * </konfetti-trigger>
+ *
+ * <!-- With preset -->
+ * <konfetti-trigger preset="fireworks">
+ *   <button>Fireworks!</button>
+ * </konfetti-trigger>
+ * ```
+ */
+declare class KonfettiTriggerElement extends BaseElement {
+    static observedAttributes: string[];
+    /** The event the listener is currently attached to, if any */
+    private boundTrigger;
+    private readonly handleTrigger;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private bind;
+    private unbind;
+}
+/** Register the konfetti-trigger custom element */
+declare function defineKonfettiTriggerElement(tagName?: string): void;
+
+export { KonfettiElement, KonfettiTriggerElement, defineAllElements, defineKonfettiElement, defineKonfettiTriggerElement };

package/dist/index.js

@@ -0,0 +1,137 @@
+// src/KonfettiElement.ts
+import { fire, firePreset, reset } from "@konfetti-js/core";
+
+// src/attributes.ts
+import { isPresetName } from "@konfetti-js/core";
+var BaseElement = typeof HTMLElement === "undefined" ? class {
+} : HTMLElement;
+var NUMBER_ATTRIBUTES = {
+  "particle-count": "particleCount",
+  angle: "angle",
+  spread: "spread",
+  "start-velocity": "startVelocity",
+  decay: "decay",
+  gravity: "gravity",
+  drift: "drift",
+  ticks: "ticks",
+  scalar: "scalar",
+  "z-index": "zIndex"
+};
+function readNumber(el, name) {
+  const raw = el.getAttribute(name);
+  if (raw === null || raw.trim() === "") return void 0;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : void 0;
+}
+function readList(el, name) {
+  const raw = el.getAttribute(name);
+  if (!raw) return void 0;
+  const items = raw.split(",").map((item) => item.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+function readOptions(el) {
+  const options = {};
+  for (const [attribute, option] of Object.entries(NUMBER_ATTRIBUTES)) {
+    const value = readNumber(el, attribute);
+    if (value !== void 0) options[option] = value;
+  }
+  const origin = {};
+  const originX = readNumber(el, "origin-x");
+  const originY = readNumber(el, "origin-y");
+  if (originX !== void 0) origin.x = originX;
+  if (originY !== void 0) origin.y = originY;
+  if (Object.keys(origin).length > 0) options.origin = origin;
+  const colors = readList(el, "colors");
+  if (colors) options.colors = colors;
+  const shapes = readList(el, "shapes");
+  if (shapes) options.shapes = shapes;
+  return options;
+}
+function readPreset(el) {
+  const preset = el.getAttribute("preset");
+  return isPresetName(preset) ? preset : void 0;
+}
+
+// src/KonfettiElement.ts
+var KonfettiElement = class extends BaseElement {
+  /** Fire konfetti with the element's attributes, optionally overridden */
+  fire(overrides) {
+    const options = { ...readOptions(this) };
+    for (const [key, value] of Object.entries(overrides ?? {})) {
+      if (value !== void 0) options[key] = value;
+    }
+    const preset = readPreset(this);
+    if (preset) {
+      firePreset(preset, options);
+    } else {
+      fire(options);
+    }
+    this.dispatchEvent(new CustomEvent("konfetti-fired", { detail: options }));
+  }
+  /** Clear all konfetti */
+  reset() {
+    reset();
+  }
+};
+function defineKonfettiElement(tagName = "konfetti-burst") {
+  if (typeof customElements === "undefined") return;
+  if (!customElements.get(tagName)) {
+    customElements.define(tagName, KonfettiElement);
+  }
+}
+
+// src/KonfettiTriggerElement.ts
+import { fireFromElement } from "@konfetti-js/core";
+var KonfettiTriggerElement = class extends BaseElement {
+  constructor() {
+    super(...arguments);
+    /** The event the listener is currently attached to, if any */
+    this.boundTrigger = null;
+    this.handleTrigger = () => {
+      const options = readOptions(this);
+      fireFromElement(this, { ...options, preset: readPreset(this) });
+      this.dispatchEvent(new CustomEvent("konfetti-fired", { detail: options }));
+    };
+  }
+  connectedCallback() {
+    this.bind();
+  }
+  disconnectedCallback() {
+    this.unbind();
+  }
+  attributeChangedCallback() {
+    if (this.isConnected) this.bind();
+  }
+  bind() {
+    const trigger = this.getAttribute("trigger") || "click";
+    if (trigger === this.boundTrigger) return;
+    this.unbind();
+    this.addEventListener(trigger, this.handleTrigger);
+    this.boundTrigger = trigger;
+  }
+  unbind() {
+    if (this.boundTrigger === null) return;
+    this.removeEventListener(this.boundTrigger, this.handleTrigger);
+    this.boundTrigger = null;
+  }
+};
+KonfettiTriggerElement.observedAttributes = ["trigger"];
+function defineKonfettiTriggerElement(tagName = "konfetti-trigger") {
+  if (typeof customElements === "undefined") return;
+  if (!customElements.get(tagName)) {
+    customElements.define(tagName, KonfettiTriggerElement);
+  }
+}
+
+// src/define.ts
+function defineAllElements() {
+  defineKonfettiElement();
+  defineKonfettiTriggerElement();
+}
+export {
+  KonfettiElement,
+  KonfettiTriggerElement,
+  defineAllElements,
+  defineKonfettiElement,
+  defineKonfettiTriggerElement
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@konfetti-js/web-components",
+  "version": "0.3.0",
+  "description": "Web Components wrapper for konfetti.js",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "konfetti",
+    "confetti",
+    "web-components",
+    "custom-elements",
+    "animation"
+  ],
+  "author": "Andrea Bettich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andreabettich/konfetti.js.git",
+    "directory": "packages/web-components"
+  },
+  "homepage": "https://andreabettich.github.io/konfetti.js/",
+  "bugs": {
+    "url": "https://github.com/andreabettich/konfetti.js/issues"
+  },
+  "dependencies": {
+    "@konfetti-js/core": "^0.3.0"
+  },
+  "devDependencies": {
+    "jsdom": "^30.1.2",
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint src",
+    "check": "biome check src --write"
+  }
+}