elixforms-web-pages/.agents/skills/create-new-page/SKILL.md

---
name: elixforms-create-new-page
description: >
  Guida step-by-step per creare una nuova pagina custom nel progetto elixForms.
  Copre la struttura dei file, la configurazione Vite per single-bundle,
  il setup TypeScript, l'importazione dei componenti common, e le convenzioni.
  Attiva questa skill quando devi creare una nuova pagina, duplicare una pagina esistente,
  o scaffoldare un nuovo micro-progetto nel monorepo.
---

# Creare una Nuova Pagina elixForms Custom

## Prerequisiti

- Node.js installato
- Dipendenze root installate: `cd react && npm install`

## Step 1: Scaffolding con Vite

```powershell
cd react
npm create vite@latest <nome-pagina> -- --template react
cd <nome-pagina>
npm install vite-plugin-css-injected-by-js
npm install -D sass-embedded
```

## Step 2: Configurare package.json

```json
{
  "name": "@elixforms/<nome-pagina>",
  "private": true,
  "version": "0.0.1",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "vite-plugin-css-injected-by-js": "^5.0.1"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^6.0.1",
    "sass-embedded": "^1.99.0",
    "vite": "^8.0.10"
  }
}
```

> **Nota**: React e ReactDOM NON vanno nel package.json della pagina.
> Sono nel `react/package.json` root e vengono risolti via hoisting di npm.

## Step 3: Configurare vite.config.js

```js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js';
import path from "path";

export default defineConfig({
  plugins: [
    react(),
    cssInjectedByJsPlugin()
  ],
  build: {
    outDir: 'dist',
    cssCodeSplit: false,
    rollupOptions: {
      input: 'src/main.jsx',          // o main.tsx se TypeScript
      output: {
        codeSplitting: false,
        manualChunks: undefined,
        entryFileNames: '<nome-pagina>.js',
        assetFileNames: '[name].[ext]'
      },
    },
    sourcemap: true,
  },
  resolve: {
    alias: {
      "@common": path.resolve(__dirname, "../common"),
    }
  },
  server: {
    fs: {
      allow: [".."]
    }
  }
})
```

## Step 4: Configurare tsconfig.json

```json
{
    "extends": "../tsconfig.base.json",
    "references": [
        { "path": "../common" }
    ],
    "compilerOptions": {
        "rootDir": "src",
        "outDir": "dist",
        "allowJs": true,
        "checkJs": true
    },
    "include": ["src/**/*"]
}
```

## Step 5: Creare il file di dichiarazioni globali

`src/global.d.ts`:
```typescript
declare module "*.css";
declare module "*.svg";
declare module "*.png";
```

## Step 6: Creare l'entry point

`src/main.jsx` (o `main.tsx`):
```jsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'

const rootElement = document.getElementById('root')
if (!rootElement) throw new Error('Root element not found')

createRoot(rootElement).render(
  <StrictMode>
    <App />
  </StrictMode>,
)
```

## Step 7: Creare il componente App

`src/App.jsx` (o `App.tsx`):
```jsx
import './App.css'
import * as ElixForms from '@common/src/ElixFormsComponent';

function App() {
  var myElixFormsReact = new ElixForms.ElixFormsReact({
    description: "Descrizione pagina",
    isDarkTheme: false,
    environmentMessage: "",
    hasTeamsContext: false,
    userDisplayName: "",
    customFormFieldsConfiguration: (formFieldFactory) => (
      <>
        {/* Aggiungi i tuoi campi qui usando formFieldFactory */}
      </>
    )
  });

  var elixFormsReactRender = myElixFormsReact.render();

  return <>
    <div className="container_12" id="pageBody">
      <div className="grid_12">
        <div id="userConsole" className="fe-behaviour">
          {/* Header, contenuto e footer della pagina */}
          <div className="grid_12 console_main">
            <div className="inside">
              <div className="mainview">
                <div className="container">
                  <h1>Titolo Pagina</h1>
                  {elixFormsReactRender}
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </>;
}

export default App
```

## Step 8: Configurare i CSS

`src/App.css` — Importa i CSS remoti del design system elixForms:
```css
@import url('https://console-unipr.elixforms.it/elixFormsCustom/css/elixForms.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/bootstrap_adaptation.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/console_user.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/designitalia_adaptation.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/fonts.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/style-bs.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/style.css');
/* ... altri CSS necessari */
```

## Step 9: Configurare VS Code (opzionale)

Aggiungere configurazione di launch e task in `.vscode/launch.json` e `.vscode/tasks.json` seguendo il pattern esistente per `scelta-carriera`.

## Step 10: Build e Deploy

```powershell
npm run build
```

Output in `dist/`:
- `<nome-pagina>.js` — Singolo bundle JS pronto per il deploy
- Eventuali asset (immagini) referenziati

## Checklist Nuova Pagina

- [ ] Cartella creata in `react/<nome-pagina>/`
- [ ] `package.json` con `"name": "@elixforms/<nome-pagina>"`
- [ ] `vite.config.js` con `entryFileNames: '<nome-pagina>.js'`
- [ ] `tsconfig.json` estende `../tsconfig.base.json`
- [ ] Alias `@common` configurato in vite.config.js
- [ ] CSS remoti importati in App.css
- [ ] Entry point `main.jsx` con mount su `#root`
- [ ] `global.d.ts` con dichiarazioni per moduli CSS/SVG/PNG
- [ ] `npm install` eseguito nella cartella della pagina
- [ ] `npm run dev` funziona senza errori
- [ ] `npm run build` produce singolo bundle in `dist/`