# 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