docs: SSR storybook guide + minimal NextJS App Router example (#462)

* docs: added SSR integration guide for Next.js, SvelteKit and other SSR frameworks

Documents the two levels reachable today: avoiding server-side crashes
(deferred import of elements.js) and HTML-first + hydration (static
slotted markup emitted server-side). Real SSR with Declarative Shadow
DOM via @lit-labs/ssr is explicitly out of scope pending kit fixes.
Adds cross-links from the React/Svelte/Vue/Angular framework pages and
from the technical documentation, plus a warning about the Turbopack
CSS parse error caused by an upstream bootstrap-italia bug.

Refs #360

* feat(examples): added Next.js example app with SSR-safe kit integration

Minimal Next.js 16 (App Router, static export) app demonstrating the
patterns from the Framework/SSR Storybook page: elements.js import
deferred to useEffect with static slotted markup (HTML-first), and
next/dynamic with ssr:false for client-only components. Wired into the
examples preview pipeline. Uses --webpack because Turbopack rejects a
malformed CSS custom property in styles.css inherited from an upstream
bootstrap-italia bug (var(-bsi-spacing-inset-m), missing dash).

Refs #360

* docs: storybook docs and nextjs app minimal example

Author: deodorhunter

.changeset/ssr-docs-issue-360.md

@@ -0,0 +1,5 @@
+---
+'@italia/dev-kit-italia': minor
+---
+
+Added SSR documentation and a Next.js example app: how to avoid crashes and reach HTML-first hydration in Next.js, SvelteKit and other SSR frameworks (#360)

examples/README.md

@@ -13,6 +13,20 @@ npm run dev
 
 Una volta avviato il server di sviluppo, l'applicazione sarà accessibile all'indirizzo [http://localhost:5173](http://localhost:5173).
 
+## Next.js
+
+Questa applicazione è generata con [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app) (App Router) e usa l'esportazione statica di Next.js (`output: 'export'`). Per avviare l'applicazione di esempio:
+
+```bash
+cd next-app
+npm install
+npm run dev
+```
+
+Una volta avviato il server di sviluppo, l'applicazione sarà accessibile all'indirizzo [http://localhost:3000/next-app](http://localhost:3000/next-app).
+
+Questo esempio mostra come integrare i web component del kit in un contesto con rendering lato server senza causare crash in fase di build/prerendering, secondo i pattern documentati nella pagina Storybook "Framework/SSR".
+
 ## Angular
 
 Questa applicazione è generata e gestita con [Angular CLI](https://angular.io/cli).

examples/next-app/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/next-app/.npmrc

@@ -0,0 +1 @@
+legacy-peer-deps=true

examples/next-app/.nvmrc

@@ -0,0 +1 @@
+24

examples/next-app/README.md

@@ -0,0 +1,19 @@
+# Esempio di integrazione: Next.js (App Router)
+
+Applicazione Next.js 16 minimale che integra i web component di `@italia/dev-kit-italia` in un contesto con rendering lato server, senza causare crash in fase di build/prerendering. Replica i pattern documentati nella pagina Storybook "Framework/SSR":
+
+- `components/KitDemo.js` — import di `elements.js` differito in `useEffect`, con markup e contenuto slottato statici nel JSX così che il server li emetta comunque (HTML-first);
+- `components/ClientOnlyDemo.js` + `components/NoSsrKit.js` — esclusione completa dal render server tramite `next/dynamic` con `ssr: false`, per componenti privi di markup utile lato server.
+
+## Avvio
+
+```bash
+npm install
+npm run dev
+```
+
+L'applicazione sarà accessibile all'indirizzo [http://localhost:3000/next-app](http://localhost:3000/next-app) (il `basePath` è configurato per il deploy statico sotto `/next-app/`).
+
+## Nota su Turbopack
+
+Gli script `dev` e `build` usano `--webpack` anziché Turbopack (default in Next.js 16): il file `styles.css` del kit contiene attualmente una regola CSS malformata ereditata da `bootstrap-italia` (`var(-bsi-spacing-inset-m)`, manca un trattino) che il parser CSS di Turbopack rifiuta con un errore bloccante, mentre webpack la tollera. Il flag potrà essere rimosso quando il bug sarà corretto a monte.

examples/next-app/app/favicon.ico

@@ -0,0 +1,9 @@
+body {
+  min-height: 100vh;
+}
+
+main {
+  max-width: 60rem;
+  margin: 0 auto;
+  padding: 2rem 1rem;
+}

examples/next-app/app/globals.css

@@ -0,0 +1,25 @@
+import '@italia/dev-kit-italia/fonts.css';
+import '@italia/dev-kit-italia/styles.css';
+import './globals.css';
+
+import Header from '../components/Header';
+import Footer from '../components/Footer';
+import KitElementsLoader from '../components/KitElementsLoader';
+
+export const metadata = {
+  title: 'Dev Kit Italia + Next.js',
+  description: 'Esempio di integrazione SSR-safe di @italia/dev-kit-italia con Next.js App Router.',
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="it">
+      <body>
+        <KitElementsLoader />
+        <Header />
+        {children}
+        <Footer />
+      </body>
+    </html>
+  );
+}

examples/next-app/app/layout.js

@@ -0,0 +1,27 @@
+import KitDemo from '../components/KitDemo';
+import ClientOnlyDemo from '../components/ClientOnlyDemo';
+
+export default function Home() {
+  return (
+    <main className="container my-4">
+      <it-callout variant="primary">
+        <it-icon slot="icon" name="it-info-circle" aria-hidden="true"></it-icon>
+        <span slot="title">Solo integrazione SSR</span>
+        <p>
+          Questo esempio Next.js mostra soltanto l&rsquo;integrazione lato server (SSR) del Dev Kit Italia. Per esempi
+          completi dei componenti in React, consulta l&rsquo;app di esempio React.
+        </p>
+      </it-callout>
+
+      <h1>Dev Kit Italia + Next.js</h1>
+      <p>
+        Questo esempio integra i web component di <code>@italia/dev-kit-italia</code> in una app Next.js (App Router)
+        senza causare crash durante il rendering lato server, secondo i pattern descritti nella pagina Storybook
+        &ldquo;Framework/SSR&rdquo;.
+      </p>
+
+      <KitDemo />
+      <ClientOnlyDemo />
+    </main>
+  );
+}