mirror of
https://github.com/elder-plinius/P4RS3LT0NGV3.git
synced 2026-07-25 05:20:49 +02:00
refactor: migrate to modular tool-based architecture
- Implement tool registry system with individual tool modules - Reorganize transformers into categorized source modules - Remove emojiLibrary.js, consolidate into EmojiUtils and emojiData - Fix mobile close button and tooltip functionality - Add build system for transforms and emoji data - Migrate from Python backend to pure JavaScript - Add comprehensive documentation and testing - Improve code organization and maintainability - Ignore generated files (transforms-bundle.js, emojiData.js)
This commit is contained in:
Dustin Farley
@@ -0,0 +1,80 @@
|
||||
# Tool System - Build-Time Template Injection
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Templates**: Separate `.html` files in `templates/` directory
|
||||
- **Build Process**: Injected into `index.html` at build time
|
||||
- **Result**: Single static HTML file (fast loading, no HTTP requests)
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
├── index.template.html # Base shell
|
||||
├── index.html # Generated (templates injected)
|
||||
├── templates/ # Edit HTML here
|
||||
│ ├── decoder.html
|
||||
│ ├── steganography.html
|
||||
│ └── ...
|
||||
├── js/tools/ # Tool classes (logic)
|
||||
│ ├── Tool.js # Base class
|
||||
│ └── *Tool.js # Auto-discovered
|
||||
└── build/
|
||||
└── inject-tool-templates.js
|
||||
```
|
||||
|
||||
## Creating a New Tool
|
||||
|
||||
### 1. Create Tool Class
|
||||
|
||||
`js/tools/MyTool.js`:
|
||||
```javascript
|
||||
class MyTool extends Tool {
|
||||
constructor() {
|
||||
super({
|
||||
id: 'mytool',
|
||||
name: 'My Tool',
|
||||
icon: 'fa-star',
|
||||
title: 'Description',
|
||||
order: 10
|
||||
});
|
||||
}
|
||||
|
||||
getVueData() {
|
||||
return { myInput: '', myOutput: '' };
|
||||
}
|
||||
|
||||
getVueMethods() {
|
||||
return {
|
||||
processInput() {
|
||||
this.myOutput = this.myInput.toUpperCase();
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Create Template
|
||||
|
||||
`templates/mytool.html`:
|
||||
```html
|
||||
<div v-if="activeTab === 'mytool'" class="tab-content">
|
||||
<div class="transform-layout">
|
||||
<textarea v-model="myInput" @input="processInput"></textarea>
|
||||
<div v-if="myOutput">{{ myOutput }}</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### 3. Build
|
||||
|
||||
```bash
|
||||
npm run build:tools # Auto-discovers and registers tool
|
||||
npm run build:templates # Injects template into index.html
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Development**: Edit templates in `templates/*.html`
|
||||
2. **Build**: `inject-tool-templates.js` reads templates and injects into `index.template.html`
|
||||
3. **Output**: Complete `index.html` with all templates embedded
|
||||
4. **Browser**: Vue compiles templates at page load (already in DOM)
|
||||
@@ -0,0 +1,181 @@
|
||||
# Tool Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The Tool system provides a way to organize features into modular, self-contained units. Each tool has:
|
||||
- Vue data properties
|
||||
- Vue methods
|
||||
- Tab button configuration
|
||||
- Tab content (template)
|
||||
|
||||
## Important Limitation: Vue Template Compilation
|
||||
|
||||
**Critical**: Tab content that uses Vue directives (`v-if`, `v-for`, `v-model`, `{{ }}`) **MUST** be defined in `index.html`, not in the Tool's `getTabContentHTML()` method.
|
||||
|
||||
### Why?
|
||||
|
||||
Vue's `v-html` directive (used for dynamic content insertion) has a fundamental limitation:
|
||||
- It inserts **raw HTML only**
|
||||
- It does **NOT** compile Vue templates
|
||||
- Vue directives and interpolations are treated as literal text
|
||||
|
||||
This is by design for security and performance reasons.
|
||||
|
||||
### What Works vs What Doesn't
|
||||
|
||||
✅ **Works in `getTabContentHTML()`:**
|
||||
```javascript
|
||||
getTabContentHTML() {
|
||||
return `
|
||||
<div class="static-content">
|
||||
<h1>Hello World</h1>
|
||||
<button onclick="doSomething()">Click</button>
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
❌ **Doesn't Work in `getTabContentHTML()`:**
|
||||
```javascript
|
||||
getTabContentHTML() {
|
||||
return `
|
||||
<div v-if="activeTab === 'mytool'">
|
||||
<input v-model="myData" />
|
||||
<p>{{ myData }}</p>
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
## Architecture Pattern
|
||||
|
||||
### For Simple Tools (Static HTML)
|
||||
|
||||
1. Define content in Tool's `getTabContentHTML()`
|
||||
2. Use plain HTML with inline event handlers
|
||||
3. No Vue directives needed
|
||||
|
||||
Example: A simple documentation viewer
|
||||
|
||||
### For Complex Tools (Vue Templates)
|
||||
|
||||
1. Define content in `index.html`
|
||||
2. Use full Vue template syntax
|
||||
3. Tool provides only data and methods
|
||||
4. `getTabContentHTML()` returns empty string
|
||||
|
||||
Example: Transform Tool, Decoder Tool, Emoji Tool
|
||||
|
||||
## Current Implementation
|
||||
|
||||
### Tools with Index.html Templates
|
||||
- ✅ Transform Tool - Complex category system
|
||||
- ✅ Decoder Tool - Dynamic alternatives list
|
||||
- ✅ Emoji Tool - Interactive emoji grid
|
||||
- ✅ Tokenade Tool - Complex nested options
|
||||
- ✅ Mutation Tool - Multiple fuzzing options
|
||||
- ✅ Tokenizer Tool - Dynamic token display
|
||||
|
||||
### Tools with Dynamic Content
|
||||
- ✅ Splitter Tool - Self-contained in SplitterTool.js
|
||||
|
||||
## Adding a New Tool
|
||||
|
||||
### Step 1: Create Tool Class
|
||||
|
||||
```javascript
|
||||
// js/tools/MyTool.js
|
||||
class MyTool extends Tool {
|
||||
constructor() {
|
||||
super({
|
||||
id: 'mytool',
|
||||
name: 'My Tool',
|
||||
icon: 'fa-star',
|
||||
title: 'My awesome tool',
|
||||
order: 10
|
||||
});
|
||||
}
|
||||
|
||||
getVueData() {
|
||||
return {
|
||||
myInput: '',
|
||||
myOutput: ''
|
||||
};
|
||||
}
|
||||
|
||||
getVueMethods() {
|
||||
return {
|
||||
processData: function() {
|
||||
this.myOutput = this.myInput.toUpperCase();
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
getTabContentHTML() {
|
||||
// If you need Vue directives, return empty and use index.html
|
||||
return '';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Add Content to index.html
|
||||
|
||||
```html
|
||||
<!-- My Tool Tab -->
|
||||
<div v-if="activeTab === 'mytool'" class="tab-content">
|
||||
<div class="transform-layout">
|
||||
<input v-model="myInput" placeholder="Enter text..." />
|
||||
<button @click="processData">Process</button>
|
||||
<div>{{ myOutput }}</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Step 3: Register Tool
|
||||
|
||||
```javascript
|
||||
// js/tools/index.js
|
||||
if (typeof MyTool !== 'undefined') {
|
||||
window.toolRegistry.register(new MyTool());
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Add Script Tag
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
<script src="js/tools/MyTool.js"></script>
|
||||
```
|
||||
|
||||
## Future Improvements
|
||||
|
||||
To enable fully dynamic tools with Vue templates, we would need to:
|
||||
|
||||
1. **Use Vue Components** - Convert each tool to a proper Vue component
|
||||
2. **Dynamic Component Loading** - Use `<component :is="currentTool">`
|
||||
3. **Component Registration** - Register components instead of raw HTML
|
||||
|
||||
This would require a significant refactor but would provide:
|
||||
- Fully modular tools
|
||||
- No index.html modifications for new tools
|
||||
- Better encapsulation
|
||||
- Proper Vue template compilation
|
||||
|
||||
## Summary
|
||||
|
||||
**Current Pattern:**
|
||||
- Tool provides: data, methods, lifecycle hooks
|
||||
- Index.html provides: template (for Vue directives)
|
||||
- Tool registry: merges data/methods, handles activation
|
||||
|
||||
**This works because:**
|
||||
- Vue compiles templates in index.html at app initialization
|
||||
- Data and methods are merged into the Vue instance
|
||||
- Templates can reference the merged data/methods
|
||||
|
||||
**Keep in mind:**
|
||||
- v-html is not a replacement for Vue components
|
||||
- Complex interactive UIs need proper Vue templates
|
||||
- Static content can be fully dynamic
|
||||
- The current hybrid approach is a practical compromise
|
||||
|
||||
@@ -0,0 +1,256 @@
|
||||
# UI Component Templates
|
||||
|
||||
This document outlines the standard reusable UI components available in the project. Use these to maintain consistency across the application.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Section Header with Description
|
||||
|
||||
Use when you need a section title with an icon and descriptive text.
|
||||
|
||||
**Responsive:** Stacks vertically on mobile (< 768px)
|
||||
|
||||
```html
|
||||
<div class="section-header-card">
|
||||
<div class="section-header-card-title">
|
||||
<i class="fas fa-book"></i>
|
||||
<h3>Gibberish Dictionary</h3>
|
||||
</div>
|
||||
<p class="section-header-card-description">
|
||||
Translate text into random gibberish and corresponding dictionary.
|
||||
</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Simple Title with Icon
|
||||
|
||||
Use for inline titles with optional subtitles.
|
||||
|
||||
**Responsive:** Wraps naturally
|
||||
|
||||
```html
|
||||
<div class="title-with-icon">
|
||||
<i class="fas fa-magic"></i>
|
||||
<h3>Universal Decoder</h3>
|
||||
<small>Prioritizing Base64</small>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Info Boxes
|
||||
|
||||
Use for tips, warnings, success messages, or disclaimers.
|
||||
|
||||
**Variants:** `.info-box-warning`, `.info-box-success`, `.info-box-danger`
|
||||
|
||||
```html
|
||||
<!-- Default (info) -->
|
||||
<div class="info-box">
|
||||
<i class="fas fa-info-circle"></i>
|
||||
<span>Copy this text and share it. The transformation can be reversed.</span>
|
||||
</div>
|
||||
|
||||
<!-- Warning -->
|
||||
<div class="info-box info-box-warning">
|
||||
<i class="fas fa-triangle-exclamation"></i>
|
||||
<span>DISCLAIMER: Use for testing only. Do not deploy to production.</span>
|
||||
</div>
|
||||
|
||||
<!-- Success -->
|
||||
<div class="info-box info-box-success">
|
||||
<i class="fas fa-check-circle"></i>
|
||||
<span>Settings applied successfully!</span>
|
||||
</div>
|
||||
|
||||
<!-- Danger -->
|
||||
<div class="info-box info-box-danger">
|
||||
<i class="fas fa-radiation"></i>
|
||||
<span>Danger zone: This will freeze your browser!</span>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🃏 Card Container
|
||||
|
||||
Use for grouped content sections.
|
||||
|
||||
**Responsive:** Full width, proper padding adjustments
|
||||
|
||||
```html
|
||||
<div class="card">
|
||||
<div class="card-header">
|
||||
<h4>Card Title</h4>
|
||||
<button class="btn btn-secondary">Action</button>
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<p>Your main content goes here...</p>
|
||||
</div>
|
||||
<div class="card-footer">
|
||||
<small>Optional footer information</small>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎛️ Button Groups
|
||||
|
||||
Use for multiple action buttons that should stay together.
|
||||
|
||||
**Responsive:** Stacks vertically on very small screens (< 400px)
|
||||
|
||||
```html
|
||||
<div class="button-group">
|
||||
<button class="btn btn-primary">
|
||||
<i class="fas fa-hammer"></i> Generate
|
||||
</button>
|
||||
<button class="btn">
|
||||
<i class="fas fa-copy"></i> Copy All
|
||||
</button>
|
||||
<button class="btn btn-secondary">
|
||||
<i class="fas fa-download"></i> Download
|
||||
</button>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔘 Button Variants
|
||||
|
||||
Standard button classes:
|
||||
|
||||
- `.btn` - Base button (default gray)
|
||||
- `.btn-primary` - Primary action (blue accent)
|
||||
- `.btn-secondary` - Secondary action (transparent with border)
|
||||
|
||||
```html
|
||||
<button class="btn">Default Button</button>
|
||||
<button class="btn btn-primary">Primary Action</button>
|
||||
<button class="btn btn-secondary">Cancel</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Form Inputs
|
||||
|
||||
All standard HTML inputs are automatically styled and fully responsive. No extra classes needed!
|
||||
|
||||
**Features:**
|
||||
- ✅ Responsive width (never overflows container)
|
||||
- ✅ Consistent styling across all inputs
|
||||
- ✅ Custom styled select dropdowns
|
||||
- ✅ Proper focus states
|
||||
- ✅ Text overflow handling (ellipsis)
|
||||
|
||||
```html
|
||||
<label>
|
||||
Input Label
|
||||
<input type="text" placeholder="Automatically styled!">
|
||||
<small>Optional helper text</small>
|
||||
</label>
|
||||
|
||||
<label>
|
||||
Select Dropdown (custom styled with arrow)
|
||||
<select>
|
||||
<option>Option 1</option>
|
||||
<option>Option 2 with longer text</option>
|
||||
</select>
|
||||
</label>
|
||||
|
||||
<label>
|
||||
Text Area
|
||||
<textarea placeholder="Also styled automatically!"></textarea>
|
||||
</label>
|
||||
|
||||
<label>
|
||||
Number Input
|
||||
<input type="number" min="0" max="100" value="50">
|
||||
</label>
|
||||
```
|
||||
|
||||
**Responsive Behavior:**
|
||||
- Desktop: Standard padding (8px 10px)
|
||||
- Mobile (< 400px): Reduced padding (6px 8px) and smaller font
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Grid Layouts
|
||||
|
||||
Use `.options-grid` for form layouts:
|
||||
|
||||
```html
|
||||
<div class="options-grid">
|
||||
<label>
|
||||
First Name
|
||||
<input type="text" placeholder="John">
|
||||
</label>
|
||||
<label>
|
||||
Last Name
|
||||
<input type="text" placeholder="Doe">
|
||||
</label>
|
||||
<label>
|
||||
Email
|
||||
<input type="email" placeholder="john@example.com">
|
||||
</label>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Responsive:** Automatically switches to single column on small screens
|
||||
|
||||
---
|
||||
|
||||
## ✨ Best Practices
|
||||
|
||||
1. **Always use these standard components** instead of creating custom styles
|
||||
2. **Only add overrides when absolutely necessary** - document why
|
||||
3. **Test responsiveness** at 400px, 768px, and 900px breakpoints
|
||||
4. **Use semantic HTML** - proper heading levels, labels, etc.
|
||||
5. **Include icons from Font Awesome** for visual consistency
|
||||
6. **Add ARIA labels** for accessibility when needed
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Anti-Patterns (Don't Do This)
|
||||
|
||||
❌ Creating inline styles
|
||||
❌ Duplicating component markup with slight variations
|
||||
❌ Adding `!important` to override standard styles
|
||||
❌ Using fixed widths that break responsiveness
|
||||
❌ Nesting cards more than 2 levels deep
|
||||
❌ Skipping semantic HTML elements
|
||||
|
||||
---
|
||||
|
||||
## 📐 Breakpoints
|
||||
|
||||
- **Mobile:** < 400px - Everything stacks, full width
|
||||
- **Tablet:** 400px - 768px - Moderate stacking
|
||||
- **Desktop:** > 768px - Full layout with sidebars
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Reference
|
||||
|
||||
| Component | Class | Responsive |
|
||||
|-----------|-------|------------|
|
||||
| Section Header | `.section-header-card` | Stacks < 768px |
|
||||
| Title + Icon | `.title-with-icon` | Wraps |
|
||||
| Info Box | `.info-box` | Full width |
|
||||
| Card | `.card` | Full width |
|
||||
| Button Group | `.button-group` | Stacks < 400px |
|
||||
| Options Grid | `.options-grid` | Single col < 400px |
|
||||
|
||||
---
|
||||
|
||||
## 📞 Need a New Component?
|
||||
|
||||
If you find yourself copying the same markup pattern 3+ times:
|
||||
1. Document the pattern
|
||||
2. Add it to `style.css` with clear comments
|
||||
3. Update this documentation
|
||||
4. Refactor existing code to use it
|
||||
|
||||
Reference in New Issue
Block a user