Een component maken in die-core

Component aanmaken met het create-component script

Om een nieuwe component aan te maken, gebruik je het volgende commando in de terminal:

npx nx run tools:create-component --name=<comp-name>

Vervang <comp-name> door de naam van je component in kebab-case (woorden gescheiden door koppeltekens). Het dcr- prefix wordt automatisch toegevoegd als je dat weglaat.

Bijvoorbeeld:

npx nx run tools:create-component --name=status-badge

of

npx nx run tools:create-component --name=dcr-status-badge

Wat doet het script?

Het create-component script automatiseert verschillende stappen:

1. Maakt een componentmap in libs/dcr-components/src/lib/<comp-name>
2. Maakt een docs-map voor Storybook documentatie
3. Genereert alle benodigde bestanden met een standaard startstructuur
4. Voegt de component toe aan de main export file
5. Werkt package.json aan met de nieuwe export entries

Gegenereerde bestandsstructuur

Na het uitvoeren van het commando wordt de volgende bestandsstructuur aangemaakt:

libs/dcr-components/src/lib/status-badge/
├── dcr-status-badge.ts               # Hoofdcomponentbestand
├── dcr-status-badge.interface.ts     # TypeScript interface definitie
├── dcr-status-badge.styles.scss      # SCSS stijlen voor de component
├── dcr-status-badge.styles.ts        # Gegenereerd CSS-in-JS bestand (niet direct bewerken)
├── index.ts                          # Export barrel bestand
└── docs/
    └── dcr-status-badge.stories.ts   # Storybook documentatie

Bestanden en hun doel

dcr-status-badge.ts

Dit is het hoofdbestand van de component waar je de LitElement-logica implementeert. Het bevat:

• De component class met decorator
• Shadow DOM configuratie
• Render methode
• Eventuele properties en methods

dcr-status-badge.styles.scss

Dit bestand bevat de component-specifieke SCSS stijlen. Zoals besproken in de [styling richtlijnen]((/handboek/developers/component-maken/basisprincipes/styling), gebruik je hier semantische classnamen en CDS design tokens:

@use '@diekeure/cds-tokens' as cds;

:host {
  display: block;
}

.badge {
  /* Component-specifieke styling met semantische classnamen */
}

dcr-status-badge.interface.ts

Dit bestand definieert de publieke API van je component als TypeScript interface. Voeg hier properties en methodes toe die beschikbaar moeten zijn voor gebruikers van je component.

docs/dcr-status-badge.stories.ts

Dit bestand bevat de Storybook configuratie voor je component, waarmee je verschillende varianten en states kunt documenteren en testen.

Volgende stappen na het aanmaken

Na het aanmaken van de component:

1. Implementeer de componentlogica in het .ts bestand
2. Voeg styling toe in het .scss bestand volgens de semantische naamgevingsrichtlijnen
3. Definieer de publieke API in het interface bestand
4. Creëer Storybook documentatie in het stories bestand
5. Voer tests uit om de werking te valideren

Tips voor het implementeren van je component

• Volg de styling richtlijnen voor componenten voor een consistente aanpak
• Gebruik CDS design tokens voor kleuren, typografie en andere visuele eigenschappen
• Zorg voor semantische classnamen die het doel van elementen beschrijven
• Documenteer je component goed met JSDoc commentaar en Storybook voorbeelden
• Test verschillende gebruiksscenario's van je component

Voorbeeld: dcr-status-badge component

Een minimaal voorbeeld van een geïmplementeerde component:

// dcr-status-badge.ts (voorbeeld implementatie)
import { LitElement, html } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { Interface } from './../_shared/decorators.js';
import styles from './dcr-status-badge.styles.js';

@Interface()
@customElement('dcr-status-badge')
export class DcrStatusBadge extends LitElement {
  static override styles = styles;

  @property({ type: String })
  status = '';

  @property({ type: String })
  variant = 'default';

  override render() {
    return html`
      <div class="badge ${this.variant}">
        <slot name="icon"></slot>
        <span class="text">${this.status}</span>
      </div>
    `;
  }
}

Door dit geautomatiseerde proces te gebruiken, kun je snel en consistent nieuwe componenten toevoegen aan de die-core bibliotheek zonder handmatig alle benodigde bestanden en configuraties te hoeven maken.