@uibit/particles 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,17 @@
 # Particles
 
+[![NPM Version](https://img.shields.io/npm/v/@uibit/particles.svg?style=flat-square&color=black)](https://www.npmjs.com/package/@uibit/particles)
+
+
 [Interactive Demonstration](https://rawlings.github.io/uibit/components/particles)
 
+## Installation
+
+```bash
+npm install @uibit/particles
+```
+
+
 Particles provides an interactive canvas-based animation element. It renders dynamic background visuals across multiple presets—including floating nodes, snowfall, rainfall, matrix streams, vortexes, and connection grids—and supports interactive mouse proximity effects.
 
 ## Value Delivery

package/custom-elements.json

@@ -39,6 +39,14 @@
             "module": "./types"
           }
         },
+        {
+          "kind": "js",
+          "name": "ParticleMode",
+          "declaration": {
+            "name": "ParticleMode",
+            "module": "./types"
+          }
+        },
         {
           "kind": "js",
           "name": "EffectParticlesConfig",
@@ -55,7 +63,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "An interactive canvas effect element. Creates dynamic background visuals\nacross many modes: particles, abstract art, grids, flow fields, and more.",
+          "description": "An interactive canvas effect element. Creates dynamic background visuals",
           "name": "Particles",
           "cssProperties": [
             {
@@ -314,6 +322,211 @@
               "kind": "method",
               "name": "_updateAndDraw",
               "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "BCP 47 locale string for formatting and localization. Defaults to inherited document language.",
+              "attribute": "locale",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "resolvedLocale",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Resolves the active locale for formatting and localization.\nChecks the `locale` property first, then traverses up the DOM to find\nthe nearest ancestor with a `lang` attribute, and finally falls back\nto undefined (which defaults to browser locale).",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "_disposables",
+              "type": {
+                "text": "Set<() => void>"
+              },
+              "privacy": "private",
+              "default": "new Set()",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "createProperty",
+              "static": true,
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "PropertyKey"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "PropertyDeclaration"
+                  }
+                }
+              ],
+              "description": "Overrides createProperty to automatically map camelCase property names\nto kebab-case attribute names by default.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "finalizeStyles",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "Array<any>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "styles",
+                  "optional": true,
+                  "type": {
+                    "text": "CSSResultGroup"
+                  }
+                }
+              ],
+              "description": "Automatically prepends basic layout resets (border-box) to the\ncomponent's final styles.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "dispatchCustomEvent",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "detail",
+                  "optional": true,
+                  "type": {
+                    "text": "T"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "Omit<CustomEventInit<T>, 'detail'>"
+                  }
+                }
+              ],
+              "description": "Helper to dispatch a custom event with standard bubbles and composed options.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getCssPropertyValue",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "propertyName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Helper to retrieve a computed CSS custom property value from the element.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "registerDisposable",
+              "parameters": [
+                {
+                  "name": "cleanup",
+                  "type": {
+                    "text": "() => void"
+                  }
+                }
+              ],
+              "description": "Register a cleanup function to be executed when the element is disconnected from the DOM.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "listen",
+              "return": {
+                "type": {
+                  "text": "() => void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "EventTarget"
+                  }
+                },
+                {
+                  "name": "type",
+                  "type": {
+                    "text": "K"
+                  }
+                },
+                {
+                  "name": "listener",
+                  "type": {
+                    "text": "(this: EventTarget, ev: HTMLElementEventMap[K]) => any"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "boolean | AddEventListenerOptions"
+                  }
+                }
+              ],
+              "description": "Utility to add an event listener that is automatically cleaned up when the element is disconnected.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
             }
           ],
           "attributes": [
@@ -379,12 +592,32 @@
               "default": "100",
               "description": "Radius of the mouse hover interaction zone",
               "fieldName": "interactiveRadius"
+            },
+            {
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "BCP 47 locale string for formatting and localization. Defaults to inherited document language.",
+              "fieldName": "locale",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            }
+          ],
+          "cssStates": [
+            {
+              "name": "paused",
+              "description": "Active when particle animations are suspended."
             }
           ],
           "superclass": {
             "name": "UIBitElement",
             "package": "@uibit/core"
           },
+          "summary": "A lightweight canvas-based interactive particle background effect.\nacross many modes: particles, abstract art, grids, flow fields, and more.",
           "tagName": "uibit-particles",
           "customElement": true
         }
@@ -442,6 +675,250 @@
       "path": "src/types.ts",
       "declarations": [],
       "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "../../platform/core/src/element.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A foundational base class for all UIBit web components.\nProvides custom event helpers, default kebab-case attribute mapping,\nautomatic cleanup/disposable tracking, and auto-injected reset styles.",
+          "name": "UIBitElement",
+          "members": [
+            {
+              "kind": "field",
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "BCP 47 locale string for formatting and localization. Defaults to inherited document language.",
+              "attribute": "locale"
+            },
+            {
+              "kind": "field",
+              "name": "resolvedLocale",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Resolves the active locale for formatting and localization.\nChecks the `locale` property first, then traverses up the DOM to find\nthe nearest ancestor with a `lang` attribute, and finally falls back\nto undefined (which defaults to browser locale).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "_disposables",
+              "type": {
+                "text": "Set<() => void>"
+              },
+              "privacy": "private",
+              "default": "new Set()"
+            },
+            {
+              "kind": "method",
+              "name": "createProperty",
+              "static": true,
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "PropertyKey"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "PropertyDeclaration"
+                  }
+                }
+              ],
+              "description": "Overrides createProperty to automatically map camelCase property names\nto kebab-case attribute names by default."
+            },
+            {
+              "kind": "method",
+              "name": "finalizeStyles",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "Array<any>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "styles",
+                  "optional": true,
+                  "type": {
+                    "text": "CSSResultGroup"
+                  }
+                }
+              ],
+              "description": "Automatically prepends basic layout resets (border-box) to the\ncomponent's final styles."
+            },
+            {
+              "kind": "method",
+              "name": "dispatchCustomEvent",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "detail",
+                  "optional": true,
+                  "type": {
+                    "text": "T"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "Omit<CustomEventInit<T>, 'detail'>"
+                  }
+                }
+              ],
+              "description": "Helper to dispatch a custom event with standard bubbles and composed options."
+            },
+            {
+              "kind": "method",
+              "name": "getCssPropertyValue",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "propertyName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Helper to retrieve a computed CSS custom property value from the element."
+            },
+            {
+              "kind": "method",
+              "name": "registerDisposable",
+              "parameters": [
+                {
+                  "name": "cleanup",
+                  "type": {
+                    "text": "() => void"
+                  }
+                }
+              ],
+              "description": "Register a cleanup function to be executed when the element is disconnected from the DOM."
+            },
+            {
+              "kind": "method",
+              "name": "listen",
+              "return": {
+                "type": {
+                  "text": "() => void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "EventTarget"
+                  }
+                },
+                {
+                  "name": "type",
+                  "type": {
+                    "text": "K"
+                  }
+                },
+                {
+                  "name": "listener",
+                  "type": {
+                    "text": "(this: EventTarget, ev: HTMLElementEventMap[K]) => any"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "boolean | AddEventListenerOptions"
+                  }
+                }
+              ],
+              "description": "Utility to add an event listener that is automatically cleaned up when the element is disconnected."
+            },
+            {
+              "kind": "method",
+              "name": "listen",
+              "return": {
+                "type": {
+                  "text": "() => void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "EventTarget"
+                  }
+                },
+                {
+                  "name": "type",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "listener",
+                  "type": {
+                    "text": "EventListenerOrEventListenerObject"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "boolean | AddEventListenerOptions"
+                  }
+                }
+              ]
+            }
+          ],
+          "attributes": [
+            {
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "BCP 47 locale string for formatting and localization. Defaults to inherited document language.",
+              "fieldName": "locale"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UIBitElement",
+          "declaration": {
+            "name": "UIBitElement",
+            "module": "../../platform/core/src/element.ts"
+          }
+        }
+      ]
     }
   ]
 }

package/dist/frameworks/angular/index.ts

@@ -2,69 +2,91 @@ import { Component, ChangeDetectionStrategy, ElementRef, input, effect, booleanA
 import '@uibit/particles';
 import type { Particles as HTMLElementClass } from '@uibit/particles';
 import type { Particle, ParticleHoverEffect, ParticleMode } from '@uibit/particles';
-
 @Component({
-  selector: 'uibit-particles',
-  template: '<ng-content></ng-content>',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  standalone: true
+    selector: 'uibit-particles',
+    template: '<ng-content></ng-content>',
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    standalone: true
 })
 export class NgxParticles {
-  constructor(private el: ElementRef<HTMLElementClass>) {
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement.count = this.count();
-      }
+    constructor(private el: ElementRef<HTMLElementClass>){
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement.count = this.count();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement.speed = this.speed();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement.mode = this.mode();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement.connect = this.connect();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement.connectDistance = this.connectDistance();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement.hoverEffect = this.hoverEffect();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement.interactiveRadius = this.interactiveRadius();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement._resize = this._resize();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement._loop = this._loop();
+            }
+        });
+        effect(()=>{
+            if (this.el.nativeElement) {
+                this.el.nativeElement.locale = this.locale();
+            }
+        });
+    }
+    readonly count = input<number, any>(50, {
+        transform: numberAttribute
     });
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement.speed = this.speed();
-      }
+    readonly speed = input<number, any>(1, {
+        transform: numberAttribute
     });
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement.mode = this.mode();
-      }
+    readonly mode = input<ParticleMode>('float');
+    readonly connect = input<boolean, any>(false, {
+        transform: booleanAttribute
     });
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement.connect = this.connect();
-      }
+    readonly connectDistance = input<number, any>(100, {
+        transform: numberAttribute
     });
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement.connectDistance = this.connectDistance();
-      }
+    readonly hoverEffect = input<ParticleHoverEffect>('repel');
+    readonly interactiveRadius = input<number, any>(100, {
+        transform: numberAttribute
     });
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement.hoverEffect = this.hoverEffect();
-      }
-    });
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement.interactiveRadius = this.interactiveRadius();
-      }
-    });
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement._resize = this._resize();
-      }
-    });
-    effect(() => {
-      if (this.el.nativeElement) {
-        this.el.nativeElement._loop = this._loop();
-      }
-    });
-  }
-
-  readonly count = input<number, any>(50, { transform: numberAttribute });
-  readonly speed = input<number, any>(1, { transform: numberAttribute });
-  readonly mode = input<ParticleMode, any>('float');
-  readonly connect = input<boolean, any>(false, { transform: booleanAttribute });
-  readonly connectDistance = input<number, any>(100, { transform: numberAttribute });
-  readonly hoverEffect = input<ParticleHoverEffect, any>('repel');
-  readonly interactiveRadius = input<number, any>(100, { transform: numberAttribute });
-  readonly _resize = input<any, any>(new ResizeController(this, { callback: (entry) => { const { width, height } = entry.contentRect; this._resizeCanvas(width, height); } }));
-  readonly _loop = input<any, any>(new LoopController(this, { autoStart: false, callback: () => this._updateAndDraw() }));
+    readonly _resize = input<any>(new ResizeController(this, {
+        callback: (entry)=>{
+            const { width, height } = entry.contentRect;
+            this._resizeCanvas(width, height);
+        }
+    }));
+    readonly _loop = input<any>(new LoopController(this, {
+        autoStart: false,
+        callback: ()=>this._updateAndDraw()
+    }));
+    readonly locale = input<string>('');
 }