Vite-Starter & React 1.2.0

Der Vite + statisches HTML-Starter im VelinStyle-Repo plus das offizielle Paket @velinstyle/react — ein Workflow für plain Sites und React-Apps. English: Vite starter & React

Reifegrad: In VelinStyle 1.2.0 als stable dokumentiert. Design Intelligence (plan / review / Agent-Meta) ist davon getrennt und dort, wo vermerkt, beta / foundation.

Wann sinnvoll

Statische Multi-Page-Vite-Sites über templates/vite-velinstyle oder React-Apps über @velinstyle/react.
CSS + WC-Verhalten in @birdapi/velinstyle halten; React nur für JSX-Ergonomie.

Wann nicht

Kein separates React-Redesign der Komponenten erwarten — Wrapper sind ein dünner Adapter über Custom Elements.
Keine nicht exportierten /dist/...-Pfade importieren; Package-Exports nutzen (/css, /bundle, .).

Vite-Starter-Template

Pfad: templates/vite-velinstyle. VelinStyle wird mit "velinstyle": "file:../.." gepinnt, damit Framework-Änderungen sofort sichtbar sind.

git clone https://github.com/SkyliteDesign/velinstyle
cd velinstyle/templates/vite-velinstyle
npm install
npm run dev

npm run build für ein Production-Bundle nutzen.

Multi-Page-HTML
Navigation
Theme-Toggle an VelinStyle-Tokens angebunden

Dieses Template als Referenz für Core-CSS, optionale Theme-Stylesheets und das Components-Bundle.

React-Integration

Paket: @velinstyle/react (packages/react). Das React-Paket ist ein dünner Wrapper um native Web Components — keine Re-Implementierung, keine doppelte Logik; typisierte Props und JSX-Ergonomie auf denselben Elementen wie in HTML.

Wrapper existieren für jedes kanonische velin-*-Element. Die Exportliste wird aus der Component Registry generiert; CI schlägt bei Drift fehl — ein neues Element kann nicht ohne Wrapper shippen. Deprecated *-wc-Aliase sind bewusst ausgenommen.

Lokal bauen (vom Repository-Root, nach git clone; Peer react):

npm run build:react

Verwendung — VelinStyle-CSS und Components-Bundle einmal importieren; Wrapper wie native Elemente nutzen. Props werden auf die Form gemappt, die das Custom Element erwartet; Handler und Refs hängen am DOM-Knoten.

import { useRef } from 'react';
import { VelinDialog, VelinThemeToggle } from '@velinstyle/react';
import '@birdapi/velinstyle/css';
import '@birdapi/velinstyle/bundle';

export function App() {
  const dialogRef = useRef(null);
  return (
    <>
      <VelinThemeToggle target="html" />
      <VelinDialog ref={dialogRef} />
      <button type="button" onClick={() => dialogRef.current?.confirm('Continue?', { title: 'Settings' })}>
        Open dialog
      </button>
    </>
  );
}

Runtime-Boot in React

Tree-Shaking bleibt möglich: bootFromDOM(document, { attributes: true }) einmal beim App-Start oder register([...]) für bekannte Tags. Die React-Wrapper setzen voraus, dass das Custom Element definiert ist (via Bundle-Import oder Runtime).

Prop-Mapping

React 18 macht aus unbekannten Props String-Attribute — open={false} würde open="false" rendern (für hasAttribute trotzdem truthy), Objekte würden stringifiziert. Die Wrapper leiten jedes Prop in die vom Custom Element erwartete Form:

Prop-Wert	Angewendet als
string, number	Attribut
boolean	Presence-Attribut (setzen oder entfernen)
object, array, function	Element-Property
`onVelin*` function	`addEventListener` für das passende Custom Event
`null` / `undefined`	weggelassen
`onClick` und andere React-Events	unverändert an React

Custom-Event-Namen folgen dem Prop-Namen: onVelinSearchSelect bindet velin-search-select.

<VelinSearch
  entries={entries}                    // element property, not stringified
  open={isOpen}                        // presence attribute
  onVelinSearchSelect={handleSelect}   // custom event listener
  onClick={handleClick}                // regular React handler
/>

Für eigene Custom Elements liefert createVelinComponent('my-widget') einen Wrapper mit demselben Verhalten.

React-Hinweise:

VelinStyle-CSS bleibt global (Stylesheet einmal beim App-Entry importieren).
Children werden ins Light DOM durchgereicht, wenn das Element Composition unterstützt (jeweils Komponentenseite prüfen).
<velin-dialog> ist vor allem imperativ (alert / confirm / prompt über Ref) — siehe Dialog.
Events erscheinen als CustomEvents am Element (z. B. velin-dialog-close); binden mit onVelinDialogClose oder per Ref.
TypeScript-Definitionen shippen mit dem Paket (dist/index.d.ts).

Siehe auch

Bestehendes Projekt — npm, CDN, Load Order
Web Components — Custom-Elements-Überblick
Dialog — Markup und Verhalten von <velin-dialog>
JavaScript-API — programmatische Helfer wo zutreffend