initial

docs/RETOOL_USAGE.md

@@ -0,0 +1,162 @@
+# How to Use ARC Renderer in Retool
+
+## Setup Instructions
+
+### Step 1: Add the JavaScript Code
+
+1. In Retool, create a new **JavaScript Query** (or Code Block)
+2. Copy the entire contents of `arcRender.js`
+3. Paste it into the JavaScript Query
+4. Name it something like `arcRenderFunctions`
+
+### Step 2: Create HTML Component for Main Puzzle Display
+
+1. Add an **HTML Component** to your Retool app
+2. In the HTML content field, use the following:
+
+```javascript
+{{ renderArcPuzzle(query1.data) }}
+```
+
+Replace `query1.data` with your actual data source (could be from an API query, transformer, etc.)
+
+### Step 3: Create HTML Component for Test Output (Optional)
+
+1. Add another **HTML Component** for the test output answer
+2. Use:
+
+```javascript
+{{ renderTestOutput(query1.data.test[0].output) }}
+```
+
+3. You can control visibility with a Toggle component or Button
+
+## Usage Examples
+
+### Example 1: Basic Usage with API Query
+
+```javascript
+// In your HTML component:
+{{ renderArcPuzzle(arcPuzzleQuery.data) }}
+```
+
+### Example 2: With JSON Transformer
+
+If your data needs transformation:
+```javascript
+// In a Transformer:
+return {
+  train: transformedTrainData,
+  test: transformedTestData
+};
+
+// In HTML component:
+{{ renderArcPuzzle(transformer1.value) }}
+```
+
+### Example 3: Toggle Test Output
+
+**Setup:**
+1. Add a Toggle component (name it `showTestOutput`)
+2. Add an HTML component with conditional rendering:
+
+```javascript
+{{ showTestOutput.value ? renderTestOutput(arcPuzzleQuery.data.test[0].output) : '' }}
+```
+
+### Example 4: With Local JSON Data
+
+```javascript
+// In a JavaScript Query, define your data:
+const puzzleData = {
+  "train": [
+    {
+      "input": [[0, 1, 2], [3, 4, 5]],
+      "output": [[1, 2, 3], [4, 5, 6]]
+    }
+  ],
+  "test": [
+    {
+      "input": [[0, 0, 0], [1, 1, 1]],
+      "output": [[2, 2, 2], [3, 3, 3]]
+    }
+  ]
+};
+
+return puzzleData;
+
+// In HTML component:
+{{ renderArcPuzzle(jsQuery1.data) }}
+```
+
+## Data Structure Requirements
+
+Your JSON data must follow this structure:
+
+```json
+{
+  "train": [
+    {
+      "input": [[0, 1, 2], [3, 4, 5], [6, 7, 8]],
+      "output": [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
+    }
+  ],
+  "test": [
+    {
+      "input": [[0, 1], [2, 3]],
+      "output": [[1, 2], [3, 4]]
+    }
+  ]
+}
+```
+
+- `train`: Array of training examples
+- `test`: Array of test examples
+- Each example has `input` and `output` as 2D arrays
+- Values are integers 0-9 representing colors
+
+## Troubleshooting
+
+### "Invalid JSON data" Error
+- Check that your data source is properly formatted
+- Verify the JSON structure matches the required format
+- Try parsing manually: `JSON.parse(yourDataSource)`
+
+### Grids Not Displaying
+- Ensure the HTML component has sufficient height/width
+- Check browser console for JavaScript errors
+- Verify data is being passed correctly with `{{ query1.data }}`
+
+### Colors Look Wrong
+- Verify your grid values are 0-9
+- Check the color mapping in the code matches ARC standard
+
+## Customization
+
+To modify styling, edit these values in `arcRender.js`:
+
+- **Cell size**: Change `cellSize = 20` (line 27)
+- **Grid border**: Change `border: 2px solid #000000` (line 38)
+- **Cell borders**: Change `border: 1px solid #DDDDDD` (line 48)
+- **Spacing**: Modify the spacing divs (lines 77, 91)
+- **Colors**: Edit the `ARC_COLORS` object (lines 8-19)
+
+## Functions Available
+
+### `renderArcPuzzle(jsonData)`
+- **Purpose**: Renders complete puzzle with training pairs and test input
+- **Input**: ARC puzzle JSON object or string
+- **Output**: HTML string
+- **Displays**: All training INPUT-OUTPUT pairs + Test INPUT only
+
+### `renderTestOutput(testOutputGrid)`
+- **Purpose**: Renders only the test output grid (the answer)
+- **Input**: 2D array representing test output
+- **Output**: HTML string
+- **Use case**: For showing/hiding the puzzle answer
+
+## Performance Notes
+
+- Fixed 20px cells work well for grids up to ~30×30
+- Larger grids may require scrolling in the HTML component
+- Consider adding overflow:auto to the HTML component for large puzzles