elixforms-web-pages/react/AGENTS.md

Agente React — Regole e Convenzioni

Questo file definisce le istruzioni specifiche, le regole e le convenzioni per lo sviluppo e la manutenzione delle pagine custom e dei componenti scritti in React e TypeScript nel monorepo react/.

Gestione ID dei Form Element

Gli ID dei campi del form (es. nel Dropdown, Checkbox, TextField) creati tramite i metodi create... in ElixFormsComponentAbstract.tsx non devono mai essere cambiati o manipolati (ad es. aggiungendo suffissi come _dropdown), in quanto la piattaforma elixForms si basa sul loro nome ed ID esatto. In caso di conflitti di ID (ad esempio con input hidden), applicare il suffisso _hidden all'input hidden e mantenere l'ID originale senza suffissi sull'elemento principale visibile.

Convenzioni di Codice e Framework

1. Libreria Common (react/common/):

   • Scritta in TypeScript (.tsx o .ts).
   • Usa React Class Components (non hooks/functional components) ereditando da React.Component.
   • Lo stato è gestito in modo immutabile tramite this.setState.
   • I checkbox mantengono uno stato locale tramite un Map<string, number[]> interno.

2. Pagine Custom (react/<nome-pagina>/):

   • Possono essere in .jsx o .tsx (TypeScript con checkJs: true).
   • Usano Functional Components ed eventualmente Hooks se necessario.
   • Istanziano la pagina tramite la classe: new ElixForms.ElixFormsReact(props).render().

3. Import di Tipi:

   • Avendo verbatimModuleSyntax: true abilitato in TypeScript, è obbligatorio usare import type per i tipi (es. import type { JSX } from 'react';).

Configurazione di Build e Sviluppo

• Ogni pagina è un'applicazione Vite autonoma configurata in vite.config.js.
• La build deve produrre un singolo bundle JS autolimitato (codeSplitting: false, manualChunks: undefined).
• I CSS locali e SCSS moduli devono essere iniettati nel bundle finale tramite il plugin vite-plugin-css-injected-by-js.
• I CSS globali del design system di UniPR non vanno inclusi nella build ma caricati a runtime via @import url(...) in App.css.

Skill React Correlate

Fai riferimento alle seguenti skill per maggiori dettagli operativi:

• elixforms-common-library: Documentazione componenti e factory.
• elixforms-create-new-page: Scaffolding di una nuova pagina React.
• elixforms-typescript-conventions: Linee guida di tipizzazione.
• elixforms-vite-build-config: Bundling e build singola.
• elixforms-dev-workflow: Comandi dev, build e debug in VS Code.