gradio-wordleboard 0.0.1
A custom Gradio component that renders and plays the Wordle word game
Requires Python: >=3.10
Keywords: game, gradio-custom-component, gradio-template-fallback, wordle


# WordleBoard

WordleBoard is a custom [Gradio](https://www.gradio.app/) component that delivers the familiar [Wordle](https://en.wikipedia.org/wiki/Wordle) gameplay directly inside a Gradio Blocks app. It handles the full game loop: rendering the grid, tracking guesses, evaluating feedback, and emitting actions back to the Python backend.

## Features

- Wordle-style grid rendered as a custom component
- Built-in Wordle rules for scoring guesses (`correct`, `present`, `absent`)
- Reset support and user feedback messaging
- Integrates with standard Gradio inputs (e.g. `Textbox`) for user guesses
- Compatible with Gradio’s custom component lifecycle (`postprocess`, examples)

## Backend Usage

```python
import gradio as gr
from gradio_wordleboard import WordleBoard

wordle_component = WordleBoard()
private_state = wordle_component.create_game_state()


def handle_guess(guess: str):
    global private_state
    private_state, public_state = wordle_component.apply_action({"action": "guess", "guess": guess}, private_state)
    return wordle_component.to_public_dict(public_state)


def handle_reset():
    global private_state
    private_state = wordle_component.create_game_state()
    return wordle_component.to_public_dict(wordle_component.public_from_private(private_state))


with gr.Blocks() as demo:
    board = WordleBoard(value=wordle_component.to_public_dict(wordle_component.public_from_private(private_state)))
    guess_box = gr.Textbox(label="Enter a guess", placeholder="Type a 5-letter word")
    submit_btn = gr.Button("Submit")
    reset_btn = gr.Button("Reset", variant="secondary")

    submit_btn.click(fn=handle_guess, inputs=guess_box, outputs=board, queue=False)
    reset_btn.click(fn=handle_reset, outputs=board, queue=False)
```

## Frontend

- `frontend/Index.svelte` renders the game board and status message.
- `frontend/Example.svelte` shows a compact preview for use in `gr.Examples`.

Refer to the official Gradio guides for additional background on custom component concepts and frontend development workflows: [Key Component Concepts](https://www.gradio.app/guides/key-component-concepts), [Frontend Guide](https://www.gradio.app/guides/frontend), and [FAQ](https://www.gradio.app/guides/frequently-asked-questions).


## Building and Publishing

- **Prep**: `cd /Users/ben/code/wordle_gradio/wordleboard && uv run npm install --prefix frontend` installs the Svelte deps the CLI expects (required once after scaffolding per the “create → dev → build → publish” flow in the custom-component guide [Gradio Docs](https://www.gradio.app/guides/custom-components-in-five-minutes)).
- **Hot-reload demo**: stay inside `wordleboard/` and run `uv run gradio component dev`. The CLI spins up the backend + Vite frontend; follow the “Frontend Server” URL printed to the console to play with your Wordle UI live ([Gradio Docs](https://www.gradio.app/guides/custom-components-in-five-minutes)).
- **Python demo app**: for a quick sanity check without the dev server, `uv run python demo/app.py` launches the packaged Blocks example using the component.
- **Build artifacts**: when you’re happy, still in `wordleboard/` run `uv run gradio component build`. This emits a wheel/tarball under `dist/` plus regenerated docs, matching the documented build phase before publishing ([Gradio Docs](https://www.gradio.app/guides/custom-components-in-five-minutes)).
- **Next steps**: After confirming the build, you can `uv run gradio component publish` to push to PyPI/Spaces, or install the wheel elsewhere to consume the component.