Skip to content

FILE-GUIDE.md

Latest commit

 

History

History
234 lines (182 loc) · 6.89 KB

FILE-GUIDE.md

File metadata and controls

234 lines (182 loc) · 6.89 KB

📦 FLOATING ORB COMPONENT - FILE GUIDE

🤔 WHICH FILES DO I NEED?

This can be confusing! Here's the complete breakdown:

📁 THE 3 CORE FILES (Required)

1. floating-orb.js (Web Component - Core Engine)

What it is: The actual 3D orb component (JavaScript/Three.js) When to use: ALWAYS - this is the engine that makes everything work Works with:

  • ✅ Vanilla HTML
  • ✅ React
  • ✅ Vue
  • ✅ Any framework

Size: ~13 KB Dependencies: Three.js (peer dependency)

// This file contains the actual Web Component class
class FloatingOrb extends HTMLElement {
  // All the Three.js 3D magic happens here
}
customElements.define('floating-orb', FloatingOrb);

2. FloatingOrb.jsx (React Wrapper - OPTIONAL)

What it is: Makes the web component easy to use in React When to use: ONLY if you're using React Depends on: floating-orb.js

Size: ~4 KB Dependencies: React, PropTypes

// This wraps the web component for React
import FloatingOrb from './FloatingOrb';

function App() {
  return <FloatingOrb color="#fafafa" size={300} />;
}

3. demo.html or *.html (Demos - OPTIONAL)

What it is: Working examples showing how to use the component When to use: For testing or learning Types:

  • floating-orb-standalone.html - Single orb demo
  • demo-floating-orb.html - Multiple orbs demo
  • floating_orb_perfect_chrome.html - Chrome material demo

🎯 WHICH FILES FOR WHICH USE CASE?

Use Case 1: Vanilla JavaScript / HTML

Your Project/
├── index.html           ← Your page
└── floating-orb.js      ← Include this

In your HTML:

<script type="module" src="floating-orb.js"></script>
<floating-orb color="#fafafa" size="500"></floating-orb>

Files needed: 1 file (floating-orb.js)

Use Case 2: React Project

Your Project/
├── src/
│   ├── App.jsx          ← Your React app
│   ├── FloatingOrb.jsx  ← React wrapper
│   └── floating-orb.js  ← Core component
└── package.json

In your React app:

import FloatingOrb from './FloatingOrb';

function App() {
  return <FloatingOrb color="#fafafa" size={500} />;
}

Files needed: 2 files (floating-orb.js + FloatingOrb.jsx)

Use Case 3: Testing / Demos

Your Project/
├── floating-orb-standalone.html  ← Just open this in browser!

Files needed: 1 file (standalone HTML has everything built-in)

🏗️ HOW THE FILES WORK TOGETHER

┌─────────────────────────────────────────────────┐
│           YOUR PROJECT                          │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────────┐                              │
│  │  React App   │  (If using React)            │
│  │  (App.jsx)   │                              │
│  └──────┬───────┘                              │
│         │ uses                                  │
│         ↓                                       │
│  ┌──────────────────┐                          │
│  │ FloatingOrb.jsx  │  (React wrapper)         │
│  │ (Optional)       │                          │
│  └──────┬───────────┘                          │
│         │ imports                               │
│         ↓                                       │
│  ┌──────────────────┐                          │
│  │ floating-orb.js  │  ← CORE ENGINE           │
│  │ (Required)       │     (Three.js magic)     │
│  └──────┬───────────┘                          │
│         │ uses                                  │
│         ↓                                       │
│  ┌──────────────────┐                          │
│  │   Three.js       │  (3D library)            │
│  │   (from npm)     │                          │
│  └──────────────────┘                          │
│                                                 │
└─────────────────────────────────────────────────┘

🎨 FILE TYPE GUIDE

JSX Files (.jsx)

  • Format: React JavaScript
  • Used in: React projects
  • Can run alone? ❌ NO - needs React build system
  • Example: FloatingOrb.jsx

JS Files (.js)

  • Format: ES6 Modules
  • Used in: Vanilla JS, React, Vue, etc.
  • Can run alone? ✅ YES (in modern browsers)
  • Example: floating-orb.js

HTML Files (.html)

  • Format: Complete web pages
  • Used in: Testing, demos, standalone
  • Can run alone? ✅ YES (just double-click!)
  • Example: floating-orb-standalone.html

📦 FOR SELLING ($29.99 PACKAGE)

Include ALL these files:

floating-orb-component/
├── src/
│   ├── floating-orb.js           ← Core (13 KB)
│   └── FloatingOrb.jsx            ← React wrapper (4 KB)
├── examples/
│   ├── vanilla-demo.html          ← HTML demo
│   ├── react-demo.jsx             ← React demo
│   └── floating-orb-standalone.html ← Quick test
├── docs/
│   ├── README.md                  ← Installation guide
│   ├── API.md                     ← API reference
│   └── FILE-GUIDE.md              ← This file!
├── package.json                   ← npm config
└── LICENSE                        ← MIT License

Customers get:

  • ✅ Core component (works everywhere)
  • ✅ React wrapper (optional)
  • ✅ 3 working demos
  • ✅ Complete documentation
  • ✅ npm-ready package

❓ QUICK ANSWERS

Q: Do I need both .js and .jsx? A: Only if using React. Vanilla JS just needs .js

Q: Can I use .html files in production? A: No - they're for demos. Use .js or .jsx files

Q: Which file has the 3D code? A: floating-orb.js - all the Three.js magic is here

Q: Do I need to install Three.js? A: Yes - it's a peer dependency. Run: npm install three

Q: What's the difference between demos? A: Different lighting/materials. All use the same core engine

✅ SIMPLEST SETUP

For HTML:

<script type="module" src="floating-orb.js"></script>
<floating-orb></floating-orb>

For React:

import FloatingOrb from './FloatingOrb';
<FloatingOrb />

That's it! 🎉