Grundgesetz für Web Components

draft.txt

Grundgesetz für Web Components
------------------------------

§ 1 Web Components sind HTML-Elemente und müssen sich wie HTML-Elemente verhalten. Sie sind kein 1:1-Ersatz für andere Komponenten-Konzepte, sondern universelle, einfach zu benutzende Erweiterungen des HTML-Vokabulars. Ihre Attribute und APIs müssen so konzipiert sein, das sie HTML-Autoren nicht überraschen. Das stellt sicher, dass Web Components universelle Plugins sind, die in jedem Browser und Framework gut funktionieren. Insbesonders zu beachten ist:

  § 1.1 Web Components müssen einen nützlichen Use Case anbieten, der allein mit HTML-Mitteln umgesetzt werden kann. JavaScript-APIs können den Funktionionsumfang einer Web Component beliebig erweitern, dürfen aber nicht zur Pflicht werden (vgl. <video>). Das stellt sicher, dass jeder Mensch, der ein bisschen HTML kann, Web Components nutzen kann.

  § 1.2 Web Components müssen Fail-Safe sein. Sie dürfen keine JavaScript-Exceptions werfen sondern müssen wie native HTML-Elemente mit jeder Art von Input (oder der Abwesenheit von Input) zurechtkommen, und sei es, indem sie einfach nichts anzeigen (vgl. <video> ohne src-Attribut, <select> ohne <option>-Kinder).

  § 1.3 JavaScript-APIs von Web Components müssen, genau wie die APIs anderer HTML-Elemente imperativer Natur sein. Methoden, Getter, Setter und Events sind Observables, Hooks und anderen APIs, die nativen HTML-Elementen fremd sind, vorzuzuiehen. HTML-Attribute müssen in DOM-Properties gespiegelt werden. Dieser kleinste Gemeinsame Nenner ist für fortgeschrittene Programmierer leicht zu adaptieren und für JS-Einsteiger leicht zu verstehen.

  § 1.4 Web Components dürfen keine komplexen Micro-DSLs implementieren. JSON in Attribut-Werten oder aufwändig konfigurierte Kindelemente als Komponenten-Inputs sind verboten, denn so etwas gibt es in nativen HTML-Elementen auch nicht. JavaScript-APIs sind für komplexere Steuerungsaufgaben besser geeignet (vgl. API <video>).

§ 2 Web Components sind universelle Plugins und müssen ohne jedwede technische Voraussetzung (jenseits Browsersupport für relevante APIs) verwendbar sein. Web-Component-Packages müssen einen fertig kompiliertes, minifiziertes Drop-In-Build mit einkompilierten Dependencies anbieten wie auch ein mit Buildprozessen brauchbares ESM-Modul.

§ 3 Web Components sind leichtgewichtige Plugins. Sie dürfen keine JavaScript-Frameworks mit sich schleppen oder exessiv Dependencies nutzen. Sie können komplexe Buildprozesse nutzen und in originellen Sprachen geschrieben sein, dürfen aber ihren dadurch Nutzern keinerlei Arbeit oder Performance-Sorgen verursachen. Projekte werden protenziell viele verschiedenen Web Components nutzen, so dass jeder einzelne Baustein so leichtgewichtig sein muss, wie möglich.

§ 4 Web Components dürfen nicht für Zwecke eingesetzt werden, für die sie nicht geeignet sind. Für Projekte, die mit bestimmten Frameworks und Paradigmen arbeiten und die von der Universalität von Web Components nicht profitieren, sind Lösungen im Rahmen der genutzen Frameworks und Paradigmen einem Verbiegen der Regeln für Web Components vorzuziehen.

§ 5 Von der der obigen Regeln kann, wie bei jeder Programmier-Best-Practice aus trifitigen Gründen abgewichen werden. Die triftigen Gründe müssen dokumentiert und wortreich argumentiert sein.

Dateiendung sollte .md sein. Wir wollen doch nicht einen armen Text-Editor verwirren ;-)

Grundgesetz für Web Components

§ 1

Web Components sind HTML-Elemente und müssen sich wie HTML-Elemente verhalten. Sie sind kein 1:1-Ersatz für andere Komponenten-Konzepte, sondern universelle, einfach zu benutzende Erweiterungen des HTML-Vokabulars. Ihre Attribute und APIs müssen so konzipiert sein, das sie HTML-Autoren nicht überraschen. Das stellt sicher, dass Web Components universelle Plugins sind, die in jedem Browser und Framework gut funktionieren. Insbesonders zu beachten ist:

§ 1.1

Web Components müssen einen nützlichen Use Case anbieten, der allein mit HTML-Mitteln umgesetzt werden kann. JavaScript-APIs können den Funktionionsumfang einer Web Component beliebig erweitern, dürfen aber nicht zur Pflicht werden (vgl.

§ 1.2

Web Components müssen Fail-Safe sein. Sie dürfen keine JavaScript-Exceptions werfen sondern müssen wie native HTML-Elemente mit jeder Art von Input (oder der Abwesenheit von Input) zurechtkommen, und sei es, indem sie einfach nichts anzeigen (vgl. <video> ohne src-Attribut, <select> ohne <option>-Kinder).

§ 1.3

JavaScript-APIs von Web Components müssen, genau wie die APIs anderer HTML-Elemente imperativer Natur sein. Methoden, Getter, Setter und Events sind Observables, Hooks und anderen APIs, die nativen HTML-Elementen fremd sind, vorzuzuiehen. HTML-Attribute müssen in DOM-Properties gespiegelt werden. Dieser kleinste Gemeinsame Nenner ist für fortgeschrittene Programmierer leicht zu adaptieren und für JS-Einsteiger leicht zu verstehen.

§ 1.4

Web Components dürfen keine komplexen Micro-DSLs implementieren. JSON in Attribut-Werten oder aufwändig konfigurierte Kindelemente als Komponenten-Inputs sind verboten, denn so etwas gibt es in nativen HTML-Elementen auch nicht. JavaScript-APIs sind für komplexere Steuerungsaufgaben besser geeignet (vgl. API

§ 2

Web Components sind universelle Plugins und müssen ohne jedwede technische Voraussetzung (jenseits Browsersupport für relevante APIs) verwendbar sein. Web-Component-Packages müssen einen fertig kompiliertes, minifiziertes Drop-In-Build mit einkompilierten Dependencies anbieten wie auch ein mit Buildprozessen brauchbares ESM-Modul.

§ 3

Web Components sind leichtgewichtige Plugins. Sie dürfen keine JavaScript-Frameworks mit sich schleppen oder exessiv Dependencies nutzen. Sie können komplexe Buildprozesse nutzen und in originellen Sprachen geschrieben sein, dürfen aber ihren dadurch Nutzern keinerlei Arbeit oder Performance-Sorgen verursachen. Projekte werden protenziell viele verschiedenen Web Components nutzen, so dass jeder einzelne Baustein so leichtgewichtig sein muss, wie möglich.

§ 4

Web Components dürfen nicht für Zwecke eingesetzt werden, für die sie nicht geeignet sind. Für Projekte, die mit bestimmten Frameworks und Paradigmen arbeiten und die von der Universalität von Web Components nicht profitieren, sind Lösungen im Rahmen der genutzen Frameworks und Paradigmen einem Verbiegen der Regeln für Web Components vorzuziehen.

§ 5

Von der der obigen Regeln kann, wie bei jeder Programmier-Best-Practice aus trifitigen Gründen abgewichen werden. Die triftigen Gründe müssen dokumentiert und wortreich argumentiert sein.

source