Repository files navigation

Design React Kit è un toolkit basato su Bootstrap Italia
per la creazione di applicazioni web sviluppate con React.

italia.github.io/design-react-kit

Read this in other languages:English 🇬🇧.

⚠️ Attenzione: questo kit è stato progettato per funzionare con la versione 2.x di Bootstrap Italia. Il kit per la versione 1.x di Bootstrap Italia è stato deprecato e si trova sul branch4.x.

Design React kit è un set di componenti React che implementaBootstrap Italia e gli stili presenti suDesign UI Kit.Per navigare la libreria e visualizzare i componenti, è stato utilizzatoStorybook.La versione pubblica dello Storybook è disponibilequi per l'ultima release stabile pubblicata.Per giocare con la libreria è disponibile ilPlayground React Kit.

• Indice
  • Come usare il kit
    • Aggiungere bootstrap-italia ed i font
    • Esempio
    • Caricamento Font
    • Peer dependencies
  • Come contribuire 💙
    • Con il codice
    • Impostare l'ambiente locale
  • Come creare nuovi componenti
    • Snapshot tests
  • Compilazione libreria
  • Link utili
  • Supporto browsers
  • TypeScript typings
  • Contributor della libreria

Per utilizzare Design React come dipendenza in un'app è possibile installarla danpm. Suggeriamo di usarecreate vite per creare una nuova webapp React, come segue:

yarn create vite nome-app --template reactcd nome-appyarn add design-react-kit --save

Maggiori informazioni per crere una nuova app con React:

• Documentazione ufficiale
• Vitejs

Ildesign-react-kit non include il CSS ed i file font, ed è quindi necessario installarli a parte:

yarn add bootstrap-italia typeface-lora typeface-roboto-mono typeface-titillium-web --save

A questo punto, è sufficiente importare esplicitamente nella app CSS e font se si è usatocreate vite all'interno del file./src/App.js:

importReactfrom'react';import'./App.css';import{Alert}from'design-react-kit';import'bootstrap-italia/dist/css/bootstrap-italia.min.css';import'typeface-titillium-web';import'typeface-roboto-mono';import'typeface-lora';functionApp(){return<Alert>This is an Alert</Alert>;}exportdefaultApp;

Puoi consultare questo template web con StackBlitz:Template web

Se si utilizzavite come bundler e si vuole personalizzare l'aspetto standard di Bootstrap Italia, è necessarioaggiungere un alias nel filevite.config.js:

import{defineConfig}from'vite';importreactfrom'@vitejs/plugin-react';exportdefaultdefineConfig({plugins:[react()],resolve:{alias:{"@splidejs/splide/src/css/core/index":"node_modules/@splidejs/splide/src/css/core/index.scss",}}});

Il tema Bootstrap Italia utilizza un set specifico di font typeface:titillium-web,roboto-mono elora. Il caricamento di questi font è lasciato al browser ma, volendo può essere controllato tramite l'apposito componenteFontLoader.È sufficiente dichiarare il componenteFontLoader in cima all'app react per permettere il caricamento.

In alternativa è necessario gestire il caricamento dei font manualmente mediante il pacchettowebfontloader:

constWebFont=require('webfontloader');WebFont.load({custom:{families:['Titillium Web:300,400,600,700:latin-ext','Lora:400,700:latin-ext','Roboto Mono:400,700:latin-ext']}});

La libreria non includereact ereact-dom, evitando clashing di versioni e aumento inutile delle dimensioni del bundle.Per questo motivo per lo sviluppo in locale sarà necessario installare manualmente le dipendenze.

Il comando da eseguire è

yarn install --peers

oppure in alternativa manualmente

yarn install react react-dom

👉🏻 È possibile contribuire alla libreria in vari modi:

• Con il proprio codice, prendendo in carico una issue tra quelle aperte e non già assegnate trale issue di React Kit (è sufficiente anche un commento sulla issue per notificare la volontà di presa in carico).
• Attraverso la segnalazione di bug o miglioramenti alrepository ufficiale di React Kit.
• Scrivendoci sulcanale dedicato di Slack.

Vorresti dare una mano su Design React Kit?Sei nel posto giusto!

Se non l'hai già fatto, inizia spendendo qualche minuto per approfondire la tua conoscenza sullelinee guida di design per i servizi web della PA,e fai riferimento alleindicazioni su come contribuire a Design React Kit.

I requisiti minimi del tuo ambiente locale devono essere:

• NodeJS (>= 18)
• Yarn

Clona il repository ed eseguiyarn per installare le dipendenze.Quindi esegui

yarn storybook:serve

per avviare il server di sviluppo.

Storybook sarà quindi disponibile all'indirizzohttp://localhost:9001/

Storybook è stato arricchito con alcuniaddons che lo rendono più parlante.

Questa sezione guiderà alla creazione di nuovi componenti nel repository.Tutti i componenti risiedono nella cartellasrc: ogni componente possiede una sua cartella con tutto ciò che è necessario per farlo funzionare.Le storieStorybook invece sono sottostories.I test unitari risiedono nella cartellatest.Il componenteButton ad esempio è presente sotto il percorsosrc/Button e la sua struttura è la seguente:

├── src│    └── Button│        └── Button.tsx├── stories│    ├── Components│    │   └── Button.stories.tsx│    └── Documentation│        └── Button.mdx└── test     └── Button.test.tsx

Alcune regole di base per strutturare i componenti:

• I file TSX file del componente utilizza la sintassi JSX.
• I file.stories.tsx dovrebbero contenere solo quanto relativo al componente stesso.
• I file.mdx dovrebbero contenere solo documentazione relativa al componente stesso
• I file.test.tsx dovrebbero contenere solo test relativi al componente stesso.

Una volta creato un nuovo componente, con la sua story, avviando Storybook sarà possibile controllare che tutto funzioni come dovrebbe.

Documentazione:

• Storybook
• MDX

Il sistema di testing prevede un controllo delle storie presenti, mediante una tecnica chiamata "snapshot" testing: il contenuto della storia Storybook verrà copiato in un file speciale e preservato per notificare eventuali cambiamenti in futuro. Questo fa si che l'aggiunta di nuove storie potrebbe risultare in un fallimento del task "test" in una PR.Qualora fosse stata aggiunta una nuova storia o modificata una già presente, sarà necessario aggiornare il file di snapshot come segue:

yarntest -u

A questo punto creare un nuovo commit ed aggiornare la PR con il file di snapshot aggiornato. Controllare che le modifiche apportate siano corrette prima di aggiornare la PR.

Per compilare la libreria e generare i file nella cartelladist, è sufficiente lanciare il comando dedicato:

yarn build

• Playground React Kit

Il kit segue le indicazioni riportate nelle Linee Guida di Design per i servizi web della Pubblica Amministrazione, sezione6.3.1.2.1. Supporto browser mediante l'utilizzo del pacchettobrowserslist-config-design-italia.

La libreria è stata portata a Typescript ed i tipi sono esportati con essa.

Un grazie speciale a chi ha reso possibile lo sviluppo di questa libreria!

Sabatino Galasso	Marco Liberati	Matteo Avesani	Federico Turbino

e al contributo diOpenCity Labs

Tutti i contributor (made withcontributors-img)