PyReact

Framework UI Python declaratif base sur Tkinter, inspire de React.

PyReact apporte a Tkinter :

• des composants reutilisables
• un state local (useState / set_state)
• un rendu declaratif (VDOM + diff)
• un noyau reactif fine-grain (POC) avec state/computed/effect/memo/resource
• un systeme de styles/themes
• des hooks data pour consommer un backend
• des hooks avances (useMemo, useReducer, useForm)
• un routeur tiny officiel + un store tiny optionnel
• une observabilite runtime integree (instrumentation/profiling/warnings)
• un panel devtools timeline inline (DevtoolsTimelinePanel)

---

Sommaire

• Pourquoi PyReact
• Avant / Apres
• Installation
• Quick Start
• Architecture
• Composants
• Hooks
• Primitives signal-first (POC)
• Gap analysis vs React TS
• Styles et themes
• Backend et API
• Internals, animations et roadmap
• Documentation MkDocs
• Exemples disponibles
• Limitations

---

Pourquoi PyReact

Tkinter est solide, mais vite imperatif et verbeux pour des interfaces modernes.
PyReact conserve la simplicite de Tkinter tout en ajoutant une ergonomie type React.

---

Avant / Apres

Tkinter classique

import tkinter as tk

root = tk.Tk()
count = 0
label = tk.Label(root, text=f"Compteur: {count}")
label.pack()

def inc():
    global count
    count += 1
    label.config(text=f"Compteur: {count}")

tk.Button(root, text="+1", command=inc).pack()
root.mainloop()

PyReact

import tkinter as tk
from pyreact import Button, Frame, Text, h, render, useState

def Counter():
    count, set_count = useState(0)
    return Frame(children=[
        Text(value=f"Compteur: {count}"),
        Button(label="+1", on_click=lambda: set_count(count + 1)),
    ])

root = tk.Tk()
render(h(Counter), root)
root.mainloop()

---

Installation

# prerequis Tkinter si besoin
sudo apt install python3-tk

# depuis la racine du projet
pip install -e .

---

Quick Start

import tkinter as tk
from pyreact import Button, Frame, Text, h, render, useState

def App():
    n, set_n = useState(0)
    return Frame(style={"padding": 16}, children=[
        Text(value=f"Valeur: {n}", style={"font_weight": "bold"}),
        Button(label="+1", on_click=lambda: set_n(n + 1)),
        Button(label="Reset", on_click=lambda: set_n(0), pack={"pady": 6}),
    ])

root = tk.Tk()
root.geometry("320x180")
render(h(App), root)
root.mainloop()

---

Architecture

Le flux principal :

1. le composant retourne un VNode
2. le Renderer monte ou reconcilie
3. un changement de state planifie un re-render (batch after_idle)
4. seuls les changements utiles sont appliques sur les widgets Tkinter
5. le scheduler priorise les updates input avant les effets secondaires

---

Composants

Composants de base

• Button
• Text
• Input
• Frame

Layout et composition

• HStack, VStack, Spacer, Center, Container

Grille, flex et responsive

• Grid, GridItem, Flex
• responsive(), Show

Design system complet

Inclut aussi :

• typographie (Heading, Body, Caption, ...)
• surfaces (Card, Divider)
• controls (PrimaryButton, Switch, Checkbox, ...)
• feedback (Badge, Alert, ProgressBar, Spinner)
• navigation (NavBar, Sidebar, Tabs, Modal)

---

Hooks

• useState : etat local
• useEffect : effet apres rendu avec cleanup optionnel
• useRef : reference mutable persistante
• useMemo : memoisation basee sur dependances
• useReducer : state complexe via reducer
• useForm : gestion formulaire (values/errors/touched/submit)
• useWindowSize, useBreakpoint, useMediaQuery : hooks fenetre/responsive

---

Primitives signal-first (POC)

Le POC ajoute une API minimale orthogonale :

• state(initial) -> get()/set()/peek()
• computed(factory) -> derive paresseux avec dependances deterministes
• memo(factory) -> cache derive base sur le meme graphe reactif
• effect(callback) -> effet avec cleanup + dispose
• resource(loader, key=..., immediate=True) -> cache async + annulation
• useTransition() -> transitions non bloquantes
• create_router() / RouterView / useRouter -> navigation tiny
• createStore() / useStore -> store global minimal

Exemple:

from pyreact import computed, effect, state

count = state(0)
double = computed(lambda: count.get() * 2)
effect(lambda: print("count=", count.get()))

count.set(1)
print(double.get())  # 2

---

Gap analysis vs React TS

Ce qui est maintenant couvert de maniere solide :

• rendu declaratif + reconciliation keyed
• model composants classe/fonction + hooks coeur
• base design system UI (layout, nav, feedback, controls)
• data fetching backend (useFetch, useAPI)
• theming global et responsive hooks

Ce qui reste en dessous d'un framework React+TypeScript complet :

• pas de typage statique TypeScript-equivalent (annotations Python seulement)
• pas de routeur officiel integre
• accesibilite native limitee par Tkinter
• ecosysteme tests/devtools encore minimal
• POC signal-first encore experimental (API stabilisee mais outillage en progression)
• pas de runtime web SSR/CSR/hydratation (positionnement Tkinter-first)

Pour les details techniques et la priorisation, voir docs/gap-analysis-react-ts.md.

---

Styles et themes

PyReact mappe des styles CSS-like vers Tkinter :

• background -> bg
• color -> fg
• padding -> padx/pady
• font_size, font_weight -> font

Themes presets disponibles :

• light, dark, ocean, sunset, neon

---

Backend et API

PyReact fournit :

• APIClient (client HTTP)
• useFetch (hook fetch generique)
• useAPI (hook base sur APIClient)

Gestion incluse :

• loading
• error
• refetch (retry manuel)

Exemple backend local avec FastAPI :

pip install fastapi uvicorn
uvicorn examples.fastapi_server:app --reload
PYREACT_API=http://localhost:8000 python -m examples.api_demo

---

Internals, animations et roadmap

Module animations :

• interpolate_color
• ease_in_out, ease_out_cubic
• animate(widget, on_tick, ...)

Devtools DX MVP :

• DevtoolsTimelinePanel (inline) pour visualiser evenements runtime, couts et warnings.

---

Documentation MkDocs

La documentation complete est structuree dans docs/ et servie avec MkDocs Material.

pip install mkdocs mkdocs-material
mkdocs serve
mkdocs build

---

Limitations

Projet volontairement compact, donc certaines limites sont assumees :

• pas de useContext natif
• mapping style Tkinter partiel (ex: border_radius ignore)
• contraintes Tkinter sur pack/grid/place
• pas de SSR/hydratation web (scope Tkinter-first)

---

Licence

Projet open-source.