refactor: Restructure data files into component-specific and common directories, add new UI components, and update project documentation.

2026-01-07 02:06:43 -05:00
parent 97d2b66f02
commit 5366865b4b
28 changed files with 1894 additions and 2051 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,152 @@
+# 🛠️ Contributing to OSSM Configurator
+
+Thank you for your interest in contributing to the OSSM Configurator! This document provides a detailed guide on how to add new components, mods, remotes, and hardware to the system.
+
+---
+
+## 🏗️ Data Architecture Overview
+
+The configurator's data is organized into several key directories within `website/src/data/`:
+
+-   `common/`: Shared data like `colors.json` and `hardware.json`.
+-   `components/`: Detailed definitions of physical parts (STLs, quantities, dependencies).
+-   `config/`: Wizard configuration, including `options.json` which defines the UI structure.
+
+---
+
+## ➕ Adding a New Component (Mod, Remote, or Part)
+
+Adding a component involves three main steps:
+1.  Defining the physical parts in `components/`.
+2.  Ensuring all required hardware exists in `common/hardware.json`.
+3.  Linking the component into the wizard UI via `config/options.json`.
+
+### Step 1: Define the Component
+Components are defined as JSON objects. A component can use one of two structures:
+
+#### A. Standard Component (e.g., `actuator.json`)
+Used for fixed assemblies where all selected parts are gathered into a single list.
+
+```json
+{
+  "my-new-mod": {
+    "category": "Mods",
+    "type": "mod",
+    "printedParts": [
+      {
+        "id": "mod-part-a",
+        "name": "Mod Part A",
+        "filamentEstimate": 45.2,
+        "timeEstimate": "1h30m",
+        "colour": "primary",
+        "required": true,
+        "url": "https://github.com/Owner/Repo/blob/main/part-a.stl?raw=true"
+      }
+    ],
+    "hardwareParts": [
+      {
+        "id": "hardware-fasteners-m3x8-shcs",
+        "required": true,
+        "quantity": 4,
+        "relatedParts": ["mod-part-a"]
+      }
+    ]
+  }
+}
+```
+
+#### B. System-based Component (e.g., `remote.json`, `hinges.json`)
+Used when a category has multiple distinct "systems" that a user chooses between.
+
+```json
+{
+  "remotes": {
+    "category": "Remote",
+    "systems": {
+      "my-custom-remote": {
+        "name": "Custom Remote v1",
+        "description": "A high-performance custom remote",
+        "image": "/images/options/custom-remote.png",
+        "bodyParts": [
+          {
+            "id": "remote-shell",
+            "name": "Remote Shell",
+            "url": "...",
+            "required": true
+          }
+        ],
+        "knobs": [
+          { "id": "knob-standard", "name": "Standard Knob", "url": "..." }
+        ],
+        "hardwareParts": [
+          { "id": "remote-hardware", "required": true }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Step 2: Register Hardware
+If your component requires hardware not already in the system, add it to `website/src/data/common/hardware.json`:
+
+```json
+"fasteners": {
+  "M3x12 SHCS": {
+    "id": "hardware-fasteners-m3x12-shcs",
+    "name": "M3x12 SHCS",
+    "price": 0.15
+  }
+}
+```
+
+### Step 3: Add to the Wizard (options.json)
+To make your part selectable, add its ID to the `sections` in `website/src/data/config/options.json`.
+
+```json
+"toyMounts": {
+  "sections": {
+    "myNewCategory": {
+      "title": "My New Category",
+      "componentIds": ["my-new-part-id"],
+      "isMultiSelect": true
+    }
+  }
+}
+```
+
+---
+
+## 📦 The Vendor System
+
+The configurator uses a script to "vendor" external files. This ensures that even if an upstream GitHub repo changes, our builds remain stable.
+
+After adding a new component with a `url` field:
+1.  Run the vendor script:
+    ```bash
+    python scripts/vendor_update.py
+    ```
+2.  The script will:
+    - Download the file to the `vendor/` directory.
+    - Calculate a checksum.
+    - Pin it to the current commit SHA.
+    - Update your component JSON with a `vendor` metadata block.
+
+---
+
+## 🖼️ Images & Assets
+
+-   **Component Images**: Place images in `website/public/images/options/`.
+-   **Naming**: Use the component `id` as the filename (e.g., `my-part-id.png`).
+-   **Specs**: Transparent PNGs are preferred for a premium "floating" look.
+
+---
+
+## ✅ Contribution Checklist
+
+1.  [ ] Component JSON added to `website/src/data/components/`.
+2.  [ ] Hardware added to `common/hardware.json` (if new).
+3.  [ ] ID added to `config/options.json`.
+4.  [ ] `python scripts/vendor_update.py` executed.
+5.  [ ] Verified that the part appears in the summary and correctly calculates hardware.
+6.  [ ] (Optional) High-quality image added to `/public/images/options/`.