> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Helper di Storybook.

> Presenta anteprime dei componenti e cataloghi di varianti con twenty-ui/testing.

## Panoramica

`twenty-ui/testing` espone decoratori Storybook, helper di layout dell'anteprima e override delle media query. Configura gli stili e un [ThemeProvider](https://docs.twenty.com/it/ui/theming.md) nell'anteprima di Storybook prima di eseguire il rendering dei componenti con tema.

## Ruoli delle story

Inizia ogni guida dei componenti con una story `Display` che mostri un esempio rappresentativo e utilizzabile. Falla seguire da codice di utilizzo che riproduca l'anteprima usando importazioni pubbliche. I componenti composti mostrano insieme le loro parti. I provider e gli helper di accessibilità mostrano il loro effetto nel contesto.

Aggiungi un `Catalog` quando un confronto con etichette aiuta i lettori a scegliere tra opzioni visive. Raggruppa separatamente varianti, dimensioni, colori e stati; usa una matrice solo quando è utile confrontare insieme due dimensioni. Un componente semplice può usare un esempio alternativo. Le finestre di dialogo, i menu e altri componenti interattivi di solito necessitano di esempi mirati per ogni workflow.

Mantieni una copertura completa degli screenshot in story `VisualRegression` separate, inclusi temi scuri e matrici di varianti. Contrassegna tali story con `!autodocs` e tienile fuori dalle guide dei componenti.

Dai alle altre story il nome di ciò che mostrano, ad esempio `Controlled`, `WithValidation` o `MultipleSelection`. Mantieni i controlli di interazione in story separate con funzioni `play`. La visualizzazione e le altre anteprime della documentazione rimangono utilizzabili dal lettore senza azioni automatizzate.

## ComponentDecorator

`ComponentDecorator` racchiude una storia in `ComponentStorybookLayout`. Imposta `parameters.container.width` e `parameters.container.height` in pixel. Legge inoltre gli argomenti `inverted` e `accent` della storia per scegliere uno sfondo facoltativo.

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { ComponentDecorator } from 'twenty-ui/testing';

const meta = {
  component: Button,
  decorators: [ComponentDecorator],
  parameters: { container: { width: 240, height: 100 } },
};

export default meta;

export const Display = { args: { children: 'Save changes' } };
```

## Catalogo raggruppato

`GroupedCatalog` fornisce ai cataloghi curati un layout condiviso per intestazioni, righe a capo e spaziatura. Ogni gruppo ha un `label` e un array `examples`. Ogni esempio necessita di un `label` univoco all'interno del proprio gruppo; può contenere qualsiasi altro dato utilizzato da `renderExample`.

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';
import { GroupedCatalog } from 'twenty-ui/testing';

const groups = [
  {
    label: 'Variants',
    examples: [
      { label: 'Solid', variant: 'solid' as const },
      { label: 'Outline', variant: 'outline' as const },
    ],
  },
];

export const ButtonCatalog = () => (
  <GroupedCatalog
    groups={groups}
    renderExample={({ label, variant }) => (
      <>
        <Text>{label}</Text>
        <Button variant={variant}>Save changes</Button>
      </>
    )}
  />
);
```

**groups** `\{ label: string; examples: CatalogExample[]; \}[]` *required*

Labeled groups of examples. Each example has a unique label within its group and can include additional data for the renderer.

**renderExample** `(example: CatalogExample) =\> ReactNode` *required*

Renders one example, including its visible label or accessible name. The layout supplies the surrounding cell and spacing.

## CatalogDecorator

`CatalogDecorator` esegue il rendering di combinazioni di fino a quattro dimensioni da `parameters.catalog.dimensions`. Ogni dimensione ha un `name`, `values`, un mapper `props(value)` e un formattatore facoltativo `labels(value)`. Il mapper restituisce le props per quella cella. `parameters.catalog.options.elementContainer` accetta `width`, `style` e `className`.

```tsx theme={null}
import { Button, type ButtonVariant } from 'twenty-ui/primitives/input';
import { CatalogDecorator } from 'twenty-ui/testing';

const meta = { component: Button };
export default meta;

export const VisualRegression = {
  tags: ['!autodocs'],
  args: { children: 'Save changes' },
  decorators: [CatalogDecorator],
  parameters: {
    catalog: {
      dimensions: [
        {
          name: 'variant',
          values: ['outline', 'solid', 'ghost'],
          props: (variant: ButtonVariant) => ({ variant }),
        },
      ],
    },
  },
};
```

## ComponentStorybookLayout

Usa il layout direttamente quando componi un'anteprima al di fuori di un decorator. Accetta un elemento figlio.

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { ComponentStorybookLayout } from 'twenty-ui/testing';

export const ButtonPreview = () => (
  <ComponentStorybookLayout width={240} height={100}>
    <Button>Save changes</Button>
  </ComponentStorybookLayout>
);
```

**backgroundColor** `string`

Background color override.

**children** `Element` *required*

The component preview element.

**height** `number`

Container height in pixels. Defaults to fit-content.

**width** `number`

Container width in pixels. When omitted, the container has a 300px minimum width.

## Override delle media query

Usa `overrideMediaQueryMatches` nel `beforeEach` di una story per forzare i risultati degli hook responsive. Restituisci la relativa funzione di pulizia per ripristinare `window.matchMedia` dopo la story:

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { overrideMediaQueryMatches } from 'twenty-ui/testing';
import { MOBILE_MEDIA_QUERY, useIsMobile } from 'twenty-ui/utilities';

const ResponsiveAction = () => {
  const isMobile = useIsMobile();

  return <Button fullWidth={isMobile}>Save changes</Button>;
};

const meta = { component: ResponsiveAction };
export default meta;

export const Mobile = {
  beforeEach: () => overrideMediaQueryMatches({ [MOBILE_MEDIA_QUERY]: true }),
};
```

Le query omesse dall'override mantengono il loro comportamento nativo. Esegui l'override di `TOUCH_DEVICE_MEDIA_QUERY` separatamente quando un esempio dipende dall'input touch. Questi override controllano i risultati di `matchMedia`; usa una viewport Storybook per modificare le media query CSS e la larghezza dell'anteprima.

## Anteprime della documentazione

Le storie incorporate nella documentazione devono essere solo di presentazione e non avere una funzione `play`. Mantieni i test di interazione in storie separate. Condividi `args`, `render`, `decorators` e `parameters` espliciti quando necessario, anziché espandere una storia di interazione in un'anteprima. Il controllo degli elementi incorporati nella documentazione rifiuta le storie contrassegnate con il tag `play-fn` di Storybook, incluse le funzioni play ereditate.

Il primo incorporamento di ogni guida dei componenti deve fare riferimento a una story esportata come `Display`. Assegna a ogni incorporamento un titolo descrittivo per il relativo iframe e un'altezza sufficiente per mostrare l'esempio. L'anteprima condivisa fornisce schede chiare e scure e un link a Storybook, dove i lettori possono usare i controlli per esplorare le props.

Esegui `npx nx check:ui-stories twenty-docs` per controllare la visualizzazione richiesta, i titoli delle anteprime, i riferimenti e le regole di presentazione. Esegui `npx nx check:ui twenty-docs` per convalidare i riferimenti API generati e verificare i tipi degli esempi copiabili.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.