string-tune-3d 0.0.6 → 0.0.7

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "string-tune-3d",
-  "version": "0.0.6",
-  "description": "StringTune-3D is a powerful 3D graphics adapter library that provides a unified interface for working with different 3D engines like Three.js. Part of the StringTune ecosystem, it enables seamless integration and synchronization of 3D objects, scenes, cameras, and lights across various rendering engines.",
+  "version": "0.0.7",
+  "description": "CSS-driven 3D graphics library that lets you control Three.js objects through CSS custom properties.",
   "keywords": [
     "3d",
     "threejs",
     "three",
+    "css",
+    "css-custom-properties",
+    "css-first",
+    "dom-sync",
+    "web-components",
     "stringtune",
     "typescript",
     "3d-graphics",

package/readme.md

@@ -1,170 +1,254 @@
-# StringTune-3D
+<p align="center">
+  <img src="/assets/logo.png" alt="StringTune-3D Logo" width="120" />
+</p>
+<h1 align="center">StringTune-3D</h1>
+<p align="center">
+  <strong>CSS-driven 3D graphics for the web</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/string-tune-3d"><img src="https://img.shields.io/npm/v/string-tune-3d?color=blue&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/penev-palemiya/StringTune-3D/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License" /></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0-blue?logo=typescript&logoColor=white" alt="TypeScript" /></a>
+  <a href="https://threejs.org/"><img src="https://img.shields.io/badge/Three.js-r160+-black?logo=three.js" alt="Three.js" /></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="https://penev.tech/string-tune-3d/overview">Documentation</a> •
+  <a href="#examples">Examples</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/hero.gif" alt="StringTune-3D Demo" width="600" />
+</p>
 
 ## Overview
 
-**StringTune-3D** is a powerful 3D graphics module for the StringTune ecosystem. It provides seamless integration of 3D objects with HTML elements using a simple attribute-based approach. StringTune-3D works exclusively within the StringTune framework and enables automatic synchronization between DOM elements and 3D objects rendered via Three.js.
+**StringTune-3D** is a 3D graphics module for the [StringTune](https://github.com/fiddle-digital/string-tune) ecosystem that lets you control 3D objects through **CSS custom properties**. No imperative Three.js code — just HTML attributes and CSS.
 
-> **Important**: StringTune-3D is a module for StringTune and requires the base `@fiddle-digital/string-tune` package to function.
-
-### Key Features
+```html
+<div
+  string="3d"
+  string-3d="sphere"
+  style="
+    width: 150px;
+    height: 150px;
+    --material-color: #667eea;
+    --rotate-y: 45;
+    --material-metalness: 0.8;
+  "
+></div>
+```
 
-- **Attribute-Based 3D**: Add 3D objects to your HTML using simple `string-3d` attributes
-- **Engine Abstraction**: Currently supports Three.js with more engines planned
-- **Automatic Synchronization**: 3D objects automatically follow DOM element positions and transformations
-- **Type-Safe**: Built with TypeScript for excellent developer experience
-- **Modular Architecture**: Lightweight addition to your StringTune setup
-- **Performance-Oriented**: Optimized for smooth 3D rendering
+> **Note**: StringTune-3D requires the base `@fiddle-digital/string-tune` package.
 
-### Supported 3D Engines
+---
 
-- **Three.js** - Full support via ThreeJSProvider
+## Features
 
-## Installation
+| Feature           | Description                                                          |
+| ----------------- | -------------------------------------------------------------------- |
+| 🎨 **CSS-First**  | Control transforms, materials, and effects via CSS custom properties |
+| 🔄 **Auto-Sync**  | 3D objects automatically follow DOM element position and size        |
+| 📦 **Primitives** | Box, sphere, plane, cylinder + GLTF/GLB model loading                |
+| 💡 **Lighting**   | Ambient, directional, point, spot, and hemisphere lights             |
+| ✨ **Filters**    | Blur, bloom, pixel effects through `--filter` property               |
+| 🎭 **Materials**  | Basic, standard PBR, and custom shader materials                     |
+| 🔤 **3D Text**    | Extruded text geometry with bevel support                            |
+| 🌟 **Particles**  | Emitter and instanced particle systems                               |
 
-First, install the base StringTune library:
+---
 
-```bash
-npm install @fiddle-digital/string-tune
-```
-
-Then install StringTune-3D:
+## Installation
 
 ```bash
-npm install string-tune-3d
+# Install dependencies
+npm install @fiddle-digital/string-tune string-tune-3d three
 ```
 
-For Three.js support, also install Three.js:
-
-```bash
-npm install three
-```
+---
 
 ## Quick Start
 
-### 1. Import Dependencies
+### 1. Setup
 
 ```typescript
 import { StringTune } from "@fiddle-digital/string-tune";
 import { String3D, ThreeJSProvider } from "string-tune-3d";
 import * as THREE from "three";
-import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
-```
 
-### 2. Initialize StringTune with 3D Support
+// Configure Three.js provider
+String3D.setProvider(new ThreeJSProvider(THREE));
 
-```typescript
-// Set the 3D provider (Three.js + model loaders)
-String3D.setProvider(
-  new ThreeJSProvider(THREE, {
-    gltf: GLTFLoader,
-  })
-);
-
-// Get StringTune instance and register the 3D module
+// Initialize StringTune with 3D module
 const stringTune = StringTune.getInstance();
-stringTune.use(String3D, { modelLoaderType: "gltf" });
-
-// Start StringTune
-stringTune.start(60); // 60 FPS
+stringTune.use(String3D);
+stringTune.start(60);
 ```
 
-### 3. Add 3D Objects in HTML
+### 2. Add 3D Objects
 
 ```html
-<!-- 3D Box -->
+<!-- Lighting -->
 <div
-  class="shape"
   string="3d"
-  string-3d="box"
-  string-3d-material="standard[#667eea]"
-  string-3d-opacity="0.5"
->
-  BOX
-</div>
-
-<!-- Ambient Light -->
+  string-3d="ambientLight"
+  style="--light-intensity: 0.5"
+></div>
 <div
   string="3d"
-  string-3d="ambientLight"
-  string-3d-color="#ffffff"
-  string-3d-intensity="0.5"
+  string-3d="directionalLight"
+  style="--light-intensity: 1"
 ></div>
 
-<!-- Directional Light -->
+<!-- 3D Box -->
 <div
   string="3d"
-  string-3d="directionalLight"
-  string-3d-color="#ffffff"
-  string-3d-intensity="1"
+  string-3d="box"
+  style="
+    width: 150px;
+    height: 150px;
+    --material-type: standard;
+    --material-color: #667eea;
+    --material-metalness: 0.5;
+    --rotate-y: 20;
+  "
 ></div>
 ```
 
-### 4. Basic Styling
+### 3. Animate with CSS
 
 ```css
-.shape {
-  width: 200px;
-  height: 200px;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 700;
-  transition: --rotate-x 0.3s, --rotate-y 0.3s;
+.my-3d-object {
+  --rotate-y: 0;
+  transition: --rotate-y 0.4s ease;
 }
 
-.shape:hover {
-  --rotate-x: 45;
-  --rotate-y: 45;
+.my-3d-object:hover {
+  --rotate-y: 180;
 }
 ```
 
-## Available Attributes
+---
+
+## Examples
+
+### Metallic Sphere
+
+```html
+<div
+  string="3d"
+  string-3d="sphere"
+  style="
+    --material-type: standard;
+    --material-color: #c0c0c0;
+    --material-metalness: 1;
+    --material-roughness: 0.1;
+  "
+></div>
+```
+
+### Glowing Object with Bloom
 
-### Core Attributes
+```html
+<div
+  string="3d"
+  string-3d="box"
+  style="
+    --material-emissive: #ff0066;
+    --filter: bloom(0.6, 0.3);
+  "
+></div>
+```
 
-- `string="3d"` - Enables 3D for the element
-- `string-3d="<type>"` - Type of 3D object: `box`, `sphere`, `plane`, `ambientLight`, `directionalLight`, etc.
-- `string-3d="model"` - Loads a model (e.g. glTF)
+### Load 3D Model
 
-### Material & Appearance
+```html
+<div
+  string="3d"
+  string-3d="model"
+  string-3d-model="/models/robot.glb"
+  string-3d-model-fit="contain"
+  style="width: 300px; height: 300px;"
+></div>
+```
+
+---
+
+## CSS Properties
+
+| Property                   | Description                    |
+| -------------------------- | ------------------------------ |
+| `--translate-x/y/z`        | Position offset                |
+| `--rotate-x/y/z`           | Rotation in degrees            |
+| `--scale`, `--scale-x/y/z` | Scale multipliers              |
+| `--opacity`                | Transparency (0-1)             |
+| `--material-type`          | `basic`, `standard`, or custom |
+| `--material-color`         | Surface color                  |
+| `--material-metalness`     | Metallic look (0-1)            |
+| `--material-roughness`     | Surface roughness (0-1)        |
+| `--filter`                 | Post-processing effects        |
+
+📖 **[Full CSS Reference →](https://penev.tech/string-tune-3d/reference/css-properties)**
 
-- `string-3d-material="<type>[<color>]"` - Material type: `basic`, `standard`
-- `string-3d-color="<color>"` - Object or light color
-- `string-3d-opacity="<number>"` - Opacity (0-1)
-- `string-3d-metalness="<number>"` - Metalness (standard only)
-- `string-3d-roughness="<number>"` - Roughness (standard only)
+---
 
-### Lighting
+## Documentation
 
-- `string-3d-intensity="<number>"` - Light intensity
+| Guide                                                                          | Description                 |
+| ------------------------------------------------------------------------------ | --------------------------- |
+| [Installation](https://penev.tech/string-tune-3d/getting-started/installation) | Setup and dependencies      |
+| [Quick Start](https://penev.tech/string-tune-3d/getting-started/quick-start)   | First 3D scene              |
+| [Core Concepts](https://penev.tech/string-tune-3d/getting-started/concepts)    | Architecture overview       |
+| [CSS Properties](https://penev.tech/string-tune-3d/reference/css-properties)   | Complete property reference |
+| [3D Objects](https://penev.tech/string-tune-3d/reference/3d-objects)           | Available object types      |
+| [Materials](https://penev.tech/string-tune-3d/reference/materials)             | Material & texture system   |
+| [Lighting](https://penev.tech/string-tune-3d/reference/lighting)               | Light types & shadows       |
+| [Filters](https://penev.tech/string-tune-3d/reference/filters)                 | Post-processing effects     |
+| [Performance](https://penev.tech/string-tune-3d/advanced/performance)          | Optimization tips           |
 
-### Models
+---
 
-- `string-3d-model="<url>"` - Path to model (e.g. `.gltf`, `.glb`)
-- `string-3d-model-loader="<type>"` - Loader override per element (e.g. `gltf`)
-- `string-3d-model-scale="<number>"` - Uniform scale (default `1`)
-- `string-3d-model-center="true|false"` - Center model at origin (default `false`)
-- `string-3d-model-fit="contain|cover"` - Fit model into element bounds (default `contain`)
-- `string-3d-model-texture-base="<url>"` - Base path for model texture URLs
-- `string-3d-model-textures='{"old.png":"/new.png"}'` - Remap model texture URLs
-  > Note: Model materials are only overridden when you specify material or map attributes.
+## Browser Support
 
-### Textures & Maps
+| Browser | Version |
+| ------- | ------- |
+| Chrome  | 56+     |
+| Firefox | 51+     |
+| Safari  | 11+     |
+| Edge    | 79+     |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+```bash
+# Clone and install
+git clone https://github.com/penev-palemiya/StringTune-3D.git
+cd string-tune-3d
+npm install
+
+# Build
+npm run build
+```
 
-- `string-3d-map="<url>"` - Base color map
-- `string-3d-normalMap="<url>"` - Normal map
-- `string-3d-roughnessMap="<url>"` - Roughness map
-- `string-3d-metalnessMap="<url>"` - Metalness map
-- `string-3d-aoMap="<url>"` - Ambient occlusion map
-- `string-3d-texture-flipY="true|false"` - Flip Y for all maps (default `true`)
-- `string-3d-colorSpace="srgb|linear"` - Color space for base color map
+---
 
 ## License
 
 MIT © [penev.tech](https://penev.tech)
 
-## Links
+---
 
-- [GitHub Repository](https://github.com/penev-palemiya/StringTune-3D)
-- [Issues](https://github.com/penev-palemiya/StringTune-3D/issues)
-- [StringTune Main Library](https://www.npmjs.com/package/@fiddle-digital/string-tune)
+<p align="center">
+  <a href="https://github.com/fiddle-digital/string-tune">StringTune</a> •
+  <a href="https://penev.tech/string-tune-3d/overview">Documentation</a> •
+  <a href="https://github.com/penev-palemiya/StringTune-3D/issues">Report Bug</a>
+</p>