Developer Guide

Architektur

Das CP-Registry-System besteht aus vier Teilen:

Tech Stack

CLI im Detail

Das CLI nutzt @clack/prompts für ein interaktives Interface. Alle Befehle funktionieren auch non-interaktiv mit Flags.

Installation

cd cp-registry
pnpm install            # Projekt-Dependencies

# CLI global installieren (empfohlen)
./cli/setup.sh

# Prüfen
cp-components --help

Deinstallation

# CLI global entfernen
./cli/setup.sh uninstall

Update

# Nach git pull: CLI neu bauen und re-linken
./cli/setup.sh update

# Status prüfen
./cli/setup.sh status

Ohne globale Installation

Falls du die CLI nicht global installieren willst, kannst du sie direkt aus dem Repository ausführen:

# Über npm-Script
npm run cli -- add accordion button

# Oder direkt
node cli/dist/index.js --help

init

Ohne Flags startet ein interaktiver Wizard: Projektname, Sitepackage, Components und Skills per Multi-Select.

# Interaktiv (empfohlen)
cp-components init

# Non-interaktiv
cp-components init --name "mein-projekt" --sitepackage "mein_sitepackage"

add

Ohne Argumente: interaktiver Multi-Select mit Beschreibungen. Mit Argumenten: direktes Installieren.

# Interaktiv (zeigt alle verfügbaren Components)
cp-components add

# Direkt
cp-components add accordion button card hero navigation

# Dry Run (nur Vorschau)
cp-components add accordion --dry-run

new

Scaffoldet eine neue Component mit Boilerplate (Astro-Datei, Manifest, Showcase-Seite).

cp-components new Timeline -c content
cp-components new SearchBar -c ui --with-script

diff, sync & remove

# Unterschiede anzeigen
cp-components diff accordion

# Alle unmodifizierten updaten
cp-components sync
cp-components sync --force   # Auch modifizierte

# Component entfernen
cp-components remove accordion
cp-components remove accordion -f   # Dependency-Warnungen ignorieren

skills

Installiert Claude Code Skills und Agents in das Zielprojekt.

# Interaktiv (Multi-Select)
cp-components skills

# Alle installieren
cp-components skills all

# Nur universelle (funktionieren in jedem Projekt)
cp-components skills --universal

# Bestimmte nach Name
cp-components skills pr review-pr a11y-auditor

# Nur auflisten
cp-components skills --list

validate

Prüft alle Component-Manifeste auf Konsistenz (Pflichtfelder, Datei-Existenz, Naming).

cp-components validate

Component Manifest

Jedes Component hat ein JSON-Manifest unter registry/components/. Komplexe Components werden in mehrere Dateien aufgeteilt:

{
  "name": "DatePicker",
  "category": "form",
  "description": "Datumswahl mit Kalender-Popover und Tastatursteuerung.",
  "files": [
    "src/components/DatePicker/DatePicker.astro",
    "src/components/DatePicker/datepicker.css",
    "src/components/DatePicker/datepicker.ts"
  ],
  "dependencies": {
    "components": [],       // Andere Components die mitinstalliert werden
    "npm": [],              // npm-Pakete die gebraucht werden (z.B. "swiper")
    "modules": ["a11y/utils"]  // Shared Modules (optional)
  },
  "requiredTokens": [       // Design-Tokens die vorhanden sein müssen
    "--color-brand-primary",
    "--color-brand-border",
    "--color-brand-surface",
    "--color-brand-foreground"
  ],
  "types": [],               // TypeScript-Typdefinitionen
  "globalsImports": []       // CSS-Imports für globals.css (optional)
}

Neues Component erstellen

// In der .astro-Datei:
---
import './datepicker.css';   // CSS im Frontmatter importieren
---
<div>...</div>
<script>import './datepicker.ts';</script>  // TS per Script-Tag

TYPO3-Integration

# TypoScript
page.includeCSS {
  main = EXT:mein_sitepackage/Resources/Public/Css/style.css
}

# TypoScript - pro Component
page.includeJSFooter {
  accordion = EXT:mein_sitepackage/Resources/Public/JavaScript/accordion.js
  accordion.defer = 1

  navigation = EXT:mein_sitepackage/Resources/Public/JavaScript/navigation.js
  navigation.defer = 1

  gallery = EXT:mein_sitepackage/Resources/Public/JavaScript/gallery.js
  gallery.defer = 1
}

# TypoScript - globales Bundle
page.includeJSFooter {
  main = EXT:mein_sitepackage/Resources/Public/JavaScript/main.js
  main.defer = 1
}

Testing

# Tests ausführen
pnpm test

# Watch-Modus
pnpm test:watch

import { describe, it, expect } from 'vitest';
import { uid, ensureId, getFocusable } from '../src/components/a11y/utils';

describe('uid', () => {
  it('generiert einzigartige IDs', () => {
    const id1 = uid('test');
    const id2 = uid('test');
    expect(id1).not.toBe(id2);
  });
});

describe('getFocusable', () => {
  it('findet alle interaktiven Elemente', () => {
    const div = document.createElement('div');
    div.innerHTML = '<button>OK</button><input /><span>Text</span>';
    document.body.appendChild(div);
    expect(getFocusable(div)).toHaveLength(2);
  });
});

Claude Code Integration

Das Registry bringt eigene Skills (Slash-Commands) und Agents für Claude Code mit — plus globale Harnesses, generelle Disziplin-Skills und Subagents.

Vollständige Dev-Doku aller Skills und Agents: → /docs/claude-code

Schnelle Installation der universellen Skills in ein eigenes Projekt: cp-components skills --universal