npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@pagopa/interop-fe-commons

v1.4.8

Published

![CI](https://github.com/pagopa/interop-fe-commons/actions/workflows/ci.yml/badge.svg) ![NPM](https://img.shields.io/npm/v/@pagopa/interop-fe-commons)

Downloads

335

Readme

CI NPM

PDND Interoperabilità: commons

Raccolta di componenti e funzionalità utilizzati da progetti PDND Interoperabilità.

Installazione

npm install @pagopa/interop-fe-commons

⚠️ Accertarsi di avere installato tutte le peerDependencies richieste.

npm install @pagopa/mui-italia @mui/material @mui/lab @mui/icons-material @emotion/react @emotion/styled date-fns @mui/x-date-pickers react-router-dom

Filtri

I filtri vengono gestiti attraverso un hook, useFilters, e un componente Filters.

useFilters mantiene lo stato dei filtri in sync con i parametri url. Ritorna l'oggetto contenente i dati da passare alla query e ciò che serve al componente Filters per renderizzare i campi, i filtri attivi e gestire le interazioni con l'utente.

L'hook accetta un array di oggetti che descrivono i filtri disponibili. Ogni oggetto deve essere costituito dai seguenti campi obbligatori:

  • label: Etichetta del filtro
  • name: Nome del filtro, usato internamente per identificare il filtro e per costruire i parametri url.
  • type: Tipo del filto. Può essere
    • freetext
    • numeric
    • autocomplete-multiple
    • autocomplete-single
    • datepicker

I filtri di tipo autocomplete-multiple e autocomplete-single, oltre ai campi obbligatori, accettano anche i seguenti campi:

  • options: Richiesto. Deve contenere un array di oggetti con i seguenti campi:
    • value: valore dell'opzione
    • label: etichetta dell'opzione
  • onTextInputChange: opzionale. Callback che viene chiamata quando l'utente modifica il testo inserito nel campo di testo. Può essere usata per aggiornare l'array di opzioni passato al filtro.

I filtri di tipo numeric, oltre ai campi obbligatori, accettano opzionalmente, i seguenti campi:

  • min: valore minimo accettato
  • max: valore massimo accettato

Esempio di utilizzo:

import React from "react";
import { useFilters, Filters } from "@pagopa/interop-fe-commons";

const FiltersExample: React.FC = () => {
  const { filtersParams, ...handlers } = useFilters<EServiceListQueryFilters>([
    { name: "q", type: "freetext", label: "Find by name" },
    {
      name: "version",
      type: "numeric",
      label: "Find by version number",
      min: 10,
      max: 20,
    },
    {
      name: "consumerId",
      type: "autocomplete-multiple",
      label: "Find by consumer",
      options: [
        { value: "option-1", label: "PagoPA S.p.A." },
        { value: "option-2", label: "Agenzia delle Entrate" },
      ],
      onTextInputChange: (value) => console.log(value),
    },
    {
      name: "state",
      type: "autocomplete-single",
      label: "Find by State",
      options: [
        { value: "option-1", label: "PagoPA S.p.A." },
        { value: "option-2", label: "Agenzia delle Entrate" },
      ],
      onTextInputChange: (value) => console.log(value),
    },
    {
      name: "createdAt",
      type: "datepicker",
      label: "Find by creation date",
    },
  ]);
  
  return <Filters {...handlers} />
}

Paginazione

La paginazione viene gestita attraverso un hook, usePagination, e un componente Pagination.

usePagination è un hook che mantiene lo stato della paginazione in sync con i parametri url. Accetta in input un oggetto con una proprietà limit che indica il numero di elementi desiderati per pagina e ritorna un oggetto contente:

  • paginationParams: oggetto contenente i parametri da passare alla query.
  • paginatinoProps: le props da passare al componente Pagination.
  • getTotalPageCount: funzione che prende in input il numero totale di elementi e ritorna il numero totale di pagine.

Il componente Pagination è di default allineato a destra e non viene renderizzato se il numero di pagine è inferiore a 2. Esso accetta tutte le props di un componente Stack di MUI nel caso si voglia personalizzare il layout.

Esempio di utilizzo:

import React from "react";
import { usePagination, Pagination } from "@pagopa/interop-fe-commons";
import { useQuery } from '@tanstack/react-query'

const PaginationExample: React.FC = () => {
  const { 
    paginationParams, 
    paginationProps, 
    getTotalPageCount 
  } = usePagination({ limit: 10 });

  const { data } = useQuery(
    ["Records", paginationParams], 
    /* ... */
  ) 
  const totalPages = getTotalPageCount(data.totalCount);

  return (
    <Pagination 
      totalPages={totalPages} 
      {...paginationProps} 
    />
  );
}

Componenti

Table e TableRow

Table accetta come props:

  • headLabels: array di stringhe che vanno a comporre l'intestazione della tabella. Il numero di elementi sarà uguale al numero di colonne.
  • isEmpty: booleano opzionale che indica se la tabella è vuota. Se è true, viene renderizzato una alert di MUI con messaggio di avviso.
  • noDataLabel: stringa opzionale che indica il messaggio da mostrare nel renderizzato nel caso isEmpty sia true. Di default è 'La ricerca corrente non ha prodotto risultati' che viene tradotto in base alla lingua impostata (italiano o inglese).

TableRow, vanno inserite come children del componente Table. Accetta come props:

  • cellData: array di stringhe o elementi JSX che vanno a comporre una riga della tabella. Attenzione: nel caso di elementi JSX, è necessario passare un key univoco per ogni elemento.
  • children: opzionale, se viene passato, viene renderizzato come ultima colonna della tabella, allineata a destra. Può essere usato per renderizzare un azione (es. un bottone) per ogni riga.

Esempio di utilizzo:

import React from "react";
import { Table, TableRow } from "@pagopa/interop-fe-commons";
import { Button, Chip } from "@mui/material";

const tableData = [
  { name: "e-service 1", state: "ACTIVE" },
  { name: "e-service 2", state: "SUSPENDED" },
  { name: "e-service 3", state: "ARCHIVED" },
];

export const TableExample: React.FC = () => {
  const headLabels = ["Nome", "Stato", ""];
  const isEmpty = tableData.length === 0;

  return (
    <Table isEmpty={isEmpty} headLabels={headLabels}>
      {tableData.map((data) => (
        <TableRow
          key={data.name}
          cellData={[data.name, <Chip key={data.name} label={data.state} />]}
        >
          <Button size="small" variant="outlined">
            Ispeziona
          </Button>
        </TableRow>
      ))}
    </Table>
  );
};

InformationContainer

Componente che viene generalmente utilizzato per mostrare un informazione costituita da una label ed un contenuto. Accetta come props:

  • label: stringa che indica il titolo da mostrare.
  • labelDescription: stringa opzionale che indica una descrizione del titolo.
  • content: stringa o elemento JSX che indica il contenuto da mostrare.
  • copyToClipboard: opzionale, prende un oggetto con le props del componente CopyToClipboard di @pagopa/mui-italia che vengono passate al componente stesso. Se non viene passato, il componente non viene renderizzato.

Esempio di utilizzo:

import React from "react";
import { InformationContainer } from "@pagopa/interop-fe-commons";

const InformationContainerExample: React.FC = () => {
  return (
    <InformationContainer
      label="E-Service"
      labelDescription="This is the e-service name"
      content="Service"
    />
  )
}

CodeBlock

Accetta come props:

  • code: stringa che indica il codice da mostrare. Se viene passato un oggetto, viene serializzato tramite JSON.stringify.
  • hideCopyButton: booleano opzionale che indica se il bottone per copiare il codice deve essere nascosto. Di default viene mostrato.

Spinner

Accetta come props:

  • label: opzionale, stringa che indica il testo da mostrare vicino lo spinner.
  • direction: opzionale, stringa che indica la direzione dello spinner in base al testo. Accetta:
    • row
    • column (default)
    • row-reverse
    • column-reverse
  • sx: opzionale, oggetto che indica le props sx di MUI da passare allo spinner.

Hooks

useAutocompleteTextInput

Hook che gestisce il caso in cui ci sia bisogno di effettuare query per filtrare le opzioni di un Autocomplete di MUI.

Per il filtraggio dinamico delle opzioni utilizziamo la seguente logica:

  • se il valore del campo di testo contiene meno di 3 caratteri, dal backend ci tornano tutte le opzioni (max 50) ed il filtraggio delle opzioni avviene client-side (svolto in automatico dall'Autocomplete di MUI).
  • se il valore del campo di testo contiene almeno 3 caratteri, il filtraggio delle opzioni avviene tramite query al backend.

L'hook si comporta analogamente a useState di React, l'unica differenza è la funzione di setState che implementa il comportamento descritto sopra, applicando un debounce di 300ms al cambio di stato.

Esempio di utilizzo:

import React from "react";
import { useAutocompleteTextInput } from "@pagopa/interop-fe-commons";
import { Autocomplete } from "@mui/material";
import { useQuery } from "@tanstack/react-query";

const AutocompleteExample: React.FC = () => {
  const [optionsSearchQuery, setInputTextValue] = useAutocompleteTextInput();

  const { data: options } = useQuery(
    ["Options", { q: optionsSearchQuery }],
    /* ... */
  )

  return (
    <Autocomplete
      value={value}
      options={options}
      onInputChange={setInputTextValue}
      {/** ... */}
    />
  );
};