particle-network-bg 0.0.4 → 1.0.0

package/README.md

@@ -15,10 +15,10 @@ Run locally:
 
 ```bash
 # Vanilla
-cd lib/demo/vanilla && npm install && npm run dev
+cd demo/vanilla && npm install && npm run dev
 
 # React
-cd lib/demo/react && npm install && npm run dev
+cd demo/react && npm install && npm run dev
 ```
 
 ## Install
@@ -126,6 +126,126 @@ function App() {
 | `gradientOrbitRadius`    | number    | 0.3                      | **Radial:** Orbit radius for center movement (0–1)       |
 | `gradientDithering`      | boolean   | true                     | *(Deprecated)* No longer used with CSS gradients          |
 | `gradientSmoothStops`    | number    | 4                        | *(Deprecated)* No longer used with CSS gradients          |
+| `particleAssets`         | array     | —                        | Use icons/images as particles (see Asset Particles)       |
+| `assets`                 | object    | —                        | Map of asset keys to URLs or SVG strings (required with `particleAssets`) |
+| `assetColor`             | string    | —                        | Tint color for asset particles (hex). Omit to use original image colors |
+| `assetOpacity`           | number    | 1                        | Opacity for asset particles (0–1)                         |
+| `mouseAttractPercentage` | number    | —                        | % of particles that follow the mouse (0–100). Others repel |
+| `mouseAttractAssets`     | string[]  | —                        | Asset keys whose particles follow the mouse. Others repel  |
+| `minParticleDistance`    | number    | —                        | Min distance (px). Particles repel when closer              |
+| `minParticleForce`       | number    | 0.5                      | Strength of particle repulsion (0–2)                       |
+| `connectionRules`        | object    | —                        | Control which categories connect (see Connection Rules)     |
+| `liquidGlass`            | object    | —                        | Liquid glass styling (see Liquid Glass)                      |
+| `liquidGlassPercentage` | number    | —                        | % of particles that render as liquid glass (0–100)          |
+| `liquidGlassCount`       | number    | —                        | Exact count of liquid glass particles                       |
+| `particleTypes`          | array     | —                        | Mix circle, asset, liquidGlass (see Particle Types)          |
+
+## Liquid Glass
+
+3D fluid spheres with blur + contrast for a gooey liquid feel. Each particle is rendered as a 3D sphere with shading, highlights, and blur. Overlapping blobs merge visually via the contrast filter.
+
+```js
+new ParticleNetwork(canvas, {
+  liquidGlassPercentage: 40,
+  liquidGlass: {
+    blur: 12,                 // blur radius (px) for fluid gooey effect
+    contrast: 25,            // container contrast for gooey merge
+    color: "#88ccff",
+    opacity: 0.6,
+    reflectionStrength: 0.85,
+    highlightPosition: "top-left", // "top-left" | "top" | "top-right" | "center" | "bottom-right"
+    highlightColor: "#ffffff",
+    shadowStrength: 0.4,
+    secondaryReflection: 0.25,
+    secondaryHighlightPosition: "bottom-right",
+    minRadius: 20,            // min size for liquid glass particles (overrides root minRadius)
+    maxRadius: 40,            // max size for liquid glass particles (overrides root maxRadius)
+  },
+});
+```
+
+## Particle Types
+
+Use `particleTypes` to mix circle, asset, and liquid glass particles with full control:
+
+```js
+new ParticleNetwork(canvas, {
+  particleTypes: [
+    { type: "circle", percentage: 50 },
+    { type: "liquidGlass", percentage: 30 },
+    { type: "asset", asset: "star", count: 20, liquidGlass: true },
+  ],
+  assets: { star: "https://..." },
+  liquidGlass: { color: "#88ccff", blur: 12, contrast: 25, ... },
+});
+```
+
+- **`circle`**: Normal circles
+- **`liquidGlass`**: Liquid glass blobs (merge when close)
+- **`asset`**: Icons/images; use `liquidGlass: true` to combine with glass
+
+## Connection Rules
+
+Control which particle categories can connect to each other. Categories: `"default"` (normal circles) and asset keys (e.g. `"star"`, `"fa_solid_heart"`).
+
+```js
+new ParticleNetwork(canvas, {
+  particleAssets: [
+    { asset: "star", count: 20 },
+    { asset: "heart", count: 20 },
+  ],
+  assets: { star: "...", heart: "..." },
+  connectionRules: {
+    allow: [["default", "star"], ["star", "heart"]],  // only these pairs connect
+    deny: [["star", "heart"]],                         // or: all connect except these
+  },
+});
+```
+
+- **`allow`**: Only these category pairs connect. Omit or empty = all connect.
+- **`deny`**: These pairs never connect (applied after allow).
+
+## Asset Particles
+
+Use custom icons or images (SVG, PNG, etc.) as particles:
+
+```js
+new ParticleNetwork(canvas, {
+  particleCount: 100,
+  particleAssets: [
+    { asset: "star", count: 10 },           // exactly 10 particles with star icon
+    { asset: "heart", percentage: 30 },    // 30% of particles with heart icon
+  ],
+  assets: {
+    star: "https://example.com/star.svg",
+    heart: "<svg>...</svg>",  // inline SVG string also supported
+  },
+});
+```
+
+Each entry in `particleAssets` must specify exactly one of `count` (exact number) or `percentage` (0–100). Remaining particles render as default circles.
+
+## Mouse Attract
+
+Control which particles follow vs repel the mouse. Use one or both:
+
+```js
+new ParticleNetwork(canvas, {
+  mouseAttractPercentage: 30,           // 30% of particles follow the mouse
+  mouseAttractAssets: ["fa_solid_star"], // particles with this asset follow
+});
+```
+
+## Particle Repulsion
+
+Keep particles from overlapping. When two particles are closer than `minParticleDistance`, they repel each other:
+
+```js
+new ParticleNetwork(canvas, {
+  minParticleDistance: 20,
+  minParticleForce: 0.5,
+});
+```
 
 ## Gradient Examples
 
@@ -171,12 +291,140 @@ new ParticleNetwork(canvas, {
 });
 ```
 
+## Child Particles
+
+Attach real UI components (React nodes or DOM elements) as physics particles. Each child particle has an anchor point it springs back to, reacts to the mouse, and can optionally render as a liquid glass blob.
+
+### React
+
+Use `ChildParticle` or `GlassChildParticle` as children of `ParticleNetworkBg`:
+
+```jsx
+import { ParticleNetworkBg, ChildParticle, GlassChildParticle } from "particle-network-bg/react";
+
+function App() {
+  return (
+    <ParticleNetworkBg config={{ particleCount: 60 }} style={{ width: "100%", height: "100vh" }}>
+      {/* Normal circle particle with a React child */}
+      <ChildParticle id="card-1" x={300} y={200} radius={50}>
+        <div style={{ color: "#fff", fontSize: 12 }}>Hello</div>
+      </ChildParticle>
+
+      {/* Liquid glass blob particle */}
+      <GlassChildParticle id="clock" x={600} y={400} radius={60}>
+        <span>🕐</span>
+      </GlassChildParticle>
+
+      {/* Rectangular child particle */}
+      <ChildParticle id="widget" x={900} y={300} width={160} height={80} borderRadius={16}>
+        <div>Widget content</div>
+      </ChildParticle>
+    </ParticleNetworkBg>
+  );
+}
+```
+
+### `ChildParticle` / `GlassChildParticle` Props
+
+| Prop             | Type      | Default  | Description                                                   |
+| ---------------- | --------- | -------- | ------------------------------------------------------------- |
+| `id`             | string    | required | Unique identifier                                             |
+| `x`              | number    | required | Anchor X position (px)                                        |
+| `y`              | number    | required | Anchor Y position (px)                                        |
+| `radius`         | number    | required | Particle radius (px). Used for physics and as size            |
+| `width`          | number    | —        | Rectangular width (px). Set with `height` for rect shape      |
+| `height`         | number    | —        | Rectangular height (px)                                       |
+| `borderRadius`   | number    | —        | Border radius (px) for rectangular shapes. Default: fully round |
+| `overflow`       | string    | `"hidden"` | CSS overflow for the child content container                |
+| `anchorForce`    | number    | `0.05`   | Spring force pulling back to anchor (0–1). Lower = more floaty |
+| `mouseInfluence` | number    | `0.1`    | Mouse influence multiplier (0–1). 0 = ignores mouse           |
+| `children`       | ReactNode | —        | Content to render inside the particle                         |
+| `style`          | CSSProperties | —   | Style applied to the inner wrapper div                        |
+| `className`      | string    | —        | Class applied to the inner wrapper div                        |
+
+### Vanilla JS
+
+Use `addChildParticle` / `removeChildParticle` on the `ParticleNetwork` instance directly:
+
+```js
+const network = new ParticleNetwork(canvas, { particleCount: 60 });
+network.start();
+
+// Add a child particle
+network.addChildParticle({
+  id: "card-1",
+  x: 300,
+  y: 200,
+  radius: 50,
+  anchorForce: 0.05,
+  mouseInfluence: 0.1,
+  liquidGlass: false,
+});
+
+// Update its anchor (e.g. on scroll/resize)
+network.updateChildParticle("card-1", { x: 400, y: 250 });
+
+// Get current positions every frame via callback
+network.onChildUpdate = (positions) => {
+  const pos = positions.get("card-1");
+  // pos.x, pos.y, pos.radius, pos.currentRadius, pos.width, pos.height, pos.rotation
+  myDomEl.style.transform = `translate(${pos.x}px, ${pos.y}px)`;
+};
+
+// Remove
+network.removeChildParticle("card-1");
+```
+
+### Child Particle API
+
+| Method / Property                              | Description                                                          |
+| ---------------------------------------------- | -------------------------------------------------------------------- |
+| `addChildParticle(config)`                     | Register a child particle. Creates the particle with anchor physics. |
+| `removeChildParticle(id)`                      | Remove a child particle by ID.                                       |
+| `updateChildParticle(id, updates)`             | Update anchor position or any config property at runtime.            |
+| `getChildParticlePositions()`                  | Returns a `Map<string, ChildParticlePosition>` with current state.   |
+| `onChildUpdate`                                | Callback fired every frame: `(positions: Map<string, ChildParticlePosition>) => void` |
+| `getChildOverlayElement(id)`                   | Returns the DOM div overlay for a child particle (for manual use).   |
+
+### Types
+
+```ts
+import type { ChildParticleConfig, ChildParticlePosition } from "particle-network-bg";
+
+interface ChildParticleConfig {
+  id: string;
+  x: number;
+  y: number;
+  radius: number;
+  width?: number;
+  height?: number;
+  borderRadius?: number;
+  overflow?: string;
+  anchorForce?: number;
+  mouseInfluence?: number;
+  liquidGlass?: boolean;
+}
+
+interface ChildParticlePosition {
+  x: number;
+  y: number;
+  radius: number;
+  currentRadius: number;
+  width?: number;
+  height?: number;
+  rotation: number; // blob rotation in radians (liquid glass only, 0 for normal)
+}
+```
+
 ## API
 
 ### React (`particle-network-bg/react`)
 
-- `ParticleNetworkBg` – Wrapper component. Props: `config`, `style`, `className`
+- `ParticleNetworkBg` – Wrapper component. Props: `config`, `style`, `className`, `children` (for `ChildParticle` / `GlassChildParticle`)
 - `useParticleNetwork(config?)` – Hook that returns a canvas ref
+- `ChildParticle` – React child particle component (see [Child Particles](#child-particles))
+- `GlassChildParticle` – Liquid glass variant of `ChildParticle`
+- `ParticleNetworkContext` – React context exposing the `ParticleNetwork` instance; use `useContext(ParticleNetworkContext)` inside children of `ParticleNetworkBg` for direct instance access
 
 ### `ParticleNetwork` (vanilla)
 
@@ -193,6 +441,13 @@ import type {
   ParticleNetworkConfig,
   Particle,
   GradientType,
+  ConnectionRules,
+  LiquidGlassConfig,
+  LiquidGlassHighlightPosition,
+  ParticleTypeEntry,
+  ParticleAssetConfig,
+  ChildParticleConfig,
+  ChildParticlePosition,
 } from "particle-network-bg";
 ```