@public-ui/components 1.1.15 → 1.1.16-rc.1

package/doc/link-group.md

@@ -0,0 +1,126 @@
+# LinkGroup
+
+Die **LinkGroup**-Komponente bildet einen umfassenden Container für eine listenartige, vertikale oder horizontale Darstellung von Links. Sie rendert eine auf Barrierefreiheit optimierte Liste von Links, die als Text, als Icon oder auch in Kombination ausgegeben werden kann. Möglich ist auch die Ausgabe von versteckten Links.
+
+## Konstruktion
+
+### Code
+
+```tsx
+<kol-link-group
+	_aria-label="Einfache LinkGroup"
+	_caption="Überschrift der LinkGroup"
+	_links="[{'_label':'Link 1','_href':'https://www.w3.org'},{'_label':'Link 2','_href':'https://www.w3.org'},{'_label':'Link 3','_href':'https://www.w3.org'}]"
+	_list-style-type="disc"
+	_orientation="'vertical"
+></kol-link-group>
+```
+
+### Beispiel
+
+<kol-link-group _aria-label="Einfache LinkGroup" _caption="Überschrift der LinkGroup" _links="[{'_label':'Link 1','_href':'https://www.w3.org'},{'_label':'Link 2','_href':'https://www.w3.org'},{'_label':'Link 3','_href':'https://www.w3.org'}]" _list-style-type="disc" _orientation="'vertical"></kol-link-group>
+
+## Verwendung
+
+### Links
+
+Die auszugebenden Links werden als JSON-Objekt an das Attribut `_links` übergeben.
+
+```tsx
+[
+	{ _label: 'Link 1', _href: 'https://www.w3.org' },
+	{ _label: 'Link 2', _href: 'https://www.w3.org' },
+	{ _label: 'Link 3', _href: 'https://www.w3.org' },
+];
+```
+
+Die Konstruktion der einzelnen **Links**, die innerhalb der JSON-Struktur über das Attribut **\_links** übergeben wird, ist im Abschnitt **Links** beschrieben.
+
+### Überschrift
+
+Die Überschrift der LinkGroup wird über das Attribut `_caption` übergeben.
+
+### Ausrichtung
+
+Über das Attribut `_orientation` kann die Ausrichtung der LinkGroup bestimmt werden. Standardwert ist `_orientation="vertical"`. Für eine horizontale Anzeige den Wert `horizontal` verwenden.
+
+### List-Style-Type
+
+Über das Attribut `_list-style-type` kann bestimmt werden, mit welchem Symbol die einzelnen Zeilen der Group dargestellt werden sollen. Es stehen vier Möglichkeiten zur Auswahl.
+
+- `disc`
+- `circle`
+- `square`
+- `none`
+
+<!--### Best practices-->
+
+### Anwendungsfälle
+
+#### LinkGroup innerhalb eines Fließtextes
+
+<p>
+  Lorem, ipsum dolor sit amet consectetur adipisicing elit. Ea optio deleniti fuga quos molestias, voluptate nobis
+  nemo, incidunt excepturi facilis, amet ducimus minus quae corporis eligendi cum distinctio. Fugit, repellendus.
+
+<kol-link-group _aria-label="LinkGroup innerhalb eines Fließtextes" _links="[{'_label':'Link 1'},{'_label':'Link 2'},{'_label':'Link 3'}]"></kol-link-group>
+
+Lorem, ipsum dolor sit amet consectetur adipisicing elit. Ea optio deleniti fuga quos molestias, voluptate nobis
+nemo, incidunt excepturi facilis, amet ducimus minus quae corporis eligendi cum distinctio. Fugit, repellendus.
+
+</p>
+
+## Barrierefreiheit
+
+### Tastatursteuerung
+
+| Taste   | Funktion                                    |
+| ------- | ------------------------------------------- |
+| `Tab`   | Fokussiert das erste Element der LinkGroup. |
+| `Enter` | Ruft den hinterlegten Link auf.             |
+
+<!--## Links und Referenzen
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property                  | Attribute          | Description                                                                                                                                                                                           | Type                                                                                                                                                                                                                  | Default      |
+| ------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `_ariaLabel` _(required)_ | `_aria-label`      | Gibt den Text an, der die Navigation von anderen Navigationen differenziert.                                                                                                                          | `string`                                                                                                                                                                                                              | `undefined`  |
+| `_heading`                | `_heading`         | Gibt die optionale Überschrift zur Link-Gruppe an.                                                                                                                                                    | `string \| undefined`                                                                                                                                                                                                 | `undefined`  |
+| `_level`                  | `_level`           | Gibt die geordnete Liste der Seitenhierarchie in Links an.                                                                                                                                            | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined`                                                                                                                                                                             | `undefined`  |
+| `_links` _(required)_     | `_links`           | Gibt die geordnete Liste der Seitenhierarchie in Links an.                                                                                                                                            | `NavLinkProps[] \| string`                                                                                                                                                                                            | `undefined`  |
+| `_listStyleType`          | `_list-style-type` | Gibt den List-Style-Typen für ungeordnete Listen aus. Wird bei horizontalen LinkGroups als Trenner verwendet                                                                                          | `"circle" \| "decimal" \| "decimal-leading-zero" \| "disc" \| "lower-alpha" \| "lower-greek" \| "lower-latin" \| "lower-roman" \| "none" \| "square" \| "upper-alpha" \| "upper-latin" \| "upper-roman" \| undefined` | `undefined`  |
+| `_ordered`                | `_ordered`         | <span class="text-red-500">**[DEPRECATED]**</span> Wird mittels der Property _list-style-type automatisch gesteuert. Gibt an, ob eine Ordered- oder eine Unordered-List verwendet werden soll.<br/><br/> | `boolean \| undefined`                                                                                                                                                                                                | `undefined`  |
+| `_orientation`            | `_orientation`     | Gibt die Ausrichtung der LinkList an.                                                                                                                                                                 | `"horizontal" \| "vertical" \| undefined`                                                                                                                                                                             | `'vertical'` |
+
+
+## Dependencies
+
+### Depends on
+
+- [kol-heading-wc](../heading)
+- [kol-link](../link)
+
+### Graph
+```mermaid
+graph TD;
+  kol-link-group --> kol-heading-wc
+  kol-link-group --> kol-link
+  kol-link --> kol-link-wc
+  kol-link-wc --> kol-span-wc
+  kol-link-wc --> kol-tooltip
+  kol-span-wc --> kol-icon
+  kol-tooltip --> kol-badge
+  kol-badge --> kol-span-wc
+  kol-badge --> kol-button-wc
+  kol-button-wc --> kol-span-wc
+  kol-button-wc --> kol-tooltip
+  style kol-link-group fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+

package/doc/link.md

@@ -0,0 +1,166 @@
+# Link
+
+Die **Link**-Komponente rendert einen auf Barrierefreiheit optimierten Link, der als Text, als Icon oder auch in Kombination ausgegeben werden kann.
+Möglich ist auch die Ausgabe eines versteckten Links.
+
+Der Link wird standardmäßig in klassischer Form mit Unterstrich ausgegeben, der jedoch über ein Attribut auch ohne CSS entfernt werden kann. Weitere Informationen zu Custom Styles finden Sie weiter unten.
+
+Beachten Sie, dass die Komponente automatisch ein Padding links und rechts zum umgebenden Text erzeugt. Sie kann daher im Fließtext ohne
+Eingabe von Leerzeichen eingefügt werden. Zusätzliche Leerzeichen vergrößern den Abstand zum umgebenden Text.
+
+## Konstruktion
+
+### Code
+
+```tsx
+<kol-link _href="https://www.w3.org" _target="_self" _underline="false">
+	Hier steht ein Link
+</kol-link>
+```
+
+### Beispiel
+
+<p>
+   In diesem Absatz wird ein Link gesetzt, der keine weiteren Attribute enthält.
+  <kol-link _href="https://www.w3.org">Hier steht ein Link</kol-link> Er wird standardmäßig als <i>
+    <b>inline-Element</b>
+    </i> ausgegeben.
+</p>
+
+## Verwendung
+
+### Link innerhalb eines Fließtextes, mit unterschiedlichen **\_display**-Werten
+
+ <p>
+    In diesem Absatz wird ein Link gesetzt, der einmal als inline-block-Element ausgegeben wird.
+    <kol-link _display="inline-block">
+      Ich bin ein Link als <b>inline-block-Element</b>
+    </kol-link>, damit kann man mir per CSS-Styles eine Breite, eine Höhe und andere Eigenschaften zuweisen.
+    Danach folgt ein Link, der als block-Element ausgegeben wird.
+  <kol-link _display="block">
+      Ich bin ein Link als <b>block-Element</b>
+    </kol-link>,
+    daher gehe ich über die ganze Breite des Eltern-Elements erzeuge so einen Zeilenumbruch.
+</p>
+
+### Link innerhalb eines Fließtextes mit Icon und Text
+
+  <p>
+    <kol-link _icon="home">Ich bin ein Link mit Icon links</kol-link><br/>
+    <kol-link _icon="home" _icon-align="right">
+      Ich bin ein Link mit Icon rechts
+    </kol-link>
+    Lorem, ipsum dolor sit amet consectetur adipisicing elit. Ea optio deleniti fuga quos molestias, voluptate nobis
+    nemo, incidunt excepturi facilis, amet ducimus minus quae corporis eligendi cum distinctio. Fugit, repellendus.
+    <kol-link _icon="home">Ich bin ein Link mit Icon links</kol-link>. Lorem, ipsum dolor sit amet consectetur adipisicing
+    elit. Ea optio deleniti fuga quos molestias, voluptate nobis nemo, incidunt excepturi <kol-link
+      _icon="home"
+      _icon-align="right"
+    >
+      Ich bin ein Link mit Icon rechts
+    </kol-link>
+    facilis, amet ducimus minus quae corporis eligendi cum distinctio. Fugit, repellendus.
+
+  </p>
+
+### Link mit und ohne Unterstrich
+
+  <p>
+    <kol-link _icon="home">Ich bin ein Link in Standardausgabe mit Unterstrich</kol-link><br/>
+    <kol-link _icon="home" _underline="false">
+      Ich bin ein Link in Standardausgabe ohne Unterstrich
+    </kol-link>
+
+  </p>
+
+<!--### Best practices
+
+### Anwendungsfälle-->
+
+## Barrierefreiheit
+
+### Tastatursteuerung
+
+| Taste   | Funktion                        |
+| ------- | ------------------------------- |
+| `Tab`   | Fokussiert das Link-Element.    |
+| `Enter` | Ruft den hinterlegten Link auf. |
+
+<!--## Links und Referenzen
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property              | Attribute             | Description                                                                                                                                                                           | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Default                                        |
+| --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `_ariaControls`       | `_aria-controls`      | Gibt an, welche Elemente kontrolliert werden.  (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)                                             | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined`                                    |
+| `_ariaCurrent`        | `_aria-current`       | Gibt an, welchen aktuellen Auswahlstatus der Link hat. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)                                      | `"date" \| "location" \| "page" \| "step" \| "time" \| boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `undefined`                                    |
+| `_ariaExpanded`       | `_aria-expanded`      | Gibt an, ob durch den Link etwas aufgeklappt wurde. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded)                                        | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `undefined`                                    |
+| `_ariaLabel`          | `_aria-label`         | Gibt einen beschreibenden Text des Links an.  (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)                                                 | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `''`                                           |
+| `_ariaSelected`       | `_aria-selected`      | Gibt an, ob der Link gerade ausgewählt ist. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected)                                                | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `undefined`                                    |
+| `_disabled`           | `_disabled`           | Gibt an, ob der Link deaktiviert ist.                                                                                                                                                 | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                                        |
+| `_fill`               | `_fill`               | Gibt an, ob der Link die gesamte zur Verfügung stehende Breite ausfüllt.                                                                                                              | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                                        |
+| `_href`               | `_href`               | Gibt die Ziel-Url des Links an.                                                                                                                                                       | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `''`                                           |
+| `_icon`               | `_icon`               | Gibt den Class-Identifier eines Icons eine eingebunden Icofont an. (z.B. https://icofont.com/)                                                                                        | `string \| undefined \| { top: string \| KoliBriCustomIcon; right?: string \| KoliBriCustomIcon \| undefined; bottom?: string \| KoliBriCustomIcon \| undefined; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right: string \| KoliBriCustomIcon; bottom?: string \| KoliBriCustomIcon \| undefined; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right?: string \| KoliBriCustomIcon \| undefined; bottom: string \| KoliBriCustomIcon; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right?: string \| KoliBriCustomIcon \| undefined; bottom?: string \| KoliBriCustomIcon \| undefined; left: string \| KoliBriCustomIcon; }` | `undefined`                                    |
+| `_iconAlign`          | `_icon-align`         | <span class="text-red-500">**[DEPRECATED]**</span> Wird durch das neue flexibleren Icon-Typ abgedeckt.<br/><br/>Gibt an, ob das Icon entweder links oder rechts dargestellt werden soll. | `"left" \| "right" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `'left'`                                       |
+| `_iconOnly`           | `_icon-only`          | Gibt an, ob nur das Icon angezeigt wird.                                                                                                                                              | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                                        |
+| `_label` _(required)_ | `_label`              | Gibt den Label für die Beschriftung der Schaltfläche an.                                                                                                                              | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `undefined`                                    |
+| `_on`                 | --                    | <span style="color:red">**[DEPRECATED]**</span> Hierzu sollte statt Link- die ButtonLink-Komponente verwendet werden.<br/><br/>Gibt die EventCallback-Funktionen für den Link an.     | `undefined \| { onClick?: EventCallback<Event> \| undefined; }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `undefined`                                    |
+| `_part`               | `_part`               | Gibt den Identifier für den CSS-Part an, um das Icon von Außen ändern zu können. (https://meowni.ca/posts/part-theme-explainer/)                                                      | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined`                                    |
+| `_role`               | `_role`               | Gibt an, welche Role der Schalter hat.                                                                                                                                                | `"tab" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined`                                    |
+| `_selector`           | `_selector`           | Gibt die ID eines DOM-Elements, zu dem gesprungen werden soll, aus.                                                                                                                   | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined`                                    |
+| `_stealth`            | `_stealth`            | Gibt an, ob der Link nur beim Fokus sichtbar ist.                                                                                                                                     | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                                        |
+| `_tabIndex`           | `_tab-index`          | Gibt an, welchen Tab-Index der Button hat. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex)                                                             | `number \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined`                                    |
+| `_target`             | `_target`             | Definiert das Verhalten, bei dem der Link geöffnet werden soll.                                                                                                                       | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined`                                    |
+| `_targetDescription`  | `_target-description` | Gibt die Beschreibung an, wenn der Link in einem anderen Programm geöffnet wird.                                                                                                      | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `'Der Link wird in einem neuen Tab geöffnet.'` |
+| `_tooltipAlign`       | `_tooltip-align`      | Gibt an, ob der Tooltip entweder oben, rechts, unten oder links angezeigt werden soll.                                                                                                | `"bottom" \| "left" \| "right" \| "top" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `'right'`                                      |
+| `_underline`          | `_underline`          | Gibt an, ob die Links unterstrichen dargestellt werden.                                                                                                                               | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `true`                                         |
+| `_useCase`            | `_use-case`           | Gibt den Verwendungsfall des Links an.                                                                                                                                                | `"image" \| "nav" \| "text" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `'text'`                                       |
+
+
+## Shadow Parts
+
+| Part       | Description                               |
+| ---------- | ----------------------------------------- |
+| `"hidden"` | Ermöglicht das Ausblenden des Linktextes. |
+| `"link"`   | Ermöglicht das Stylen des Links.          |
+| `"span"`   | Ermöglicht das Stylen des Linktextes.     |
+
+
+## Dependencies
+
+### Used by
+
+ - [kol-breadcrumb](../breadcrumb)
+ - [kol-input-adapter-leanup](../input-adapter-leanup)
+ - [kol-link-group](../link-group)
+ - [kol-skip-nav](../skip-nav)
+
+### Depends on
+
+- kol-link-wc
+
+### Graph
+```mermaid
+graph TD;
+  kol-link --> kol-link-wc
+  kol-link-wc --> kol-span-wc
+  kol-link-wc --> kol-tooltip
+  kol-span-wc --> kol-icon
+  kol-tooltip --> kol-badge
+  kol-badge --> kol-span-wc
+  kol-badge --> kol-button-wc
+  kol-button-wc --> kol-span-wc
+  kol-button-wc --> kol-tooltip
+  kol-breadcrumb --> kol-link
+  kol-input-adapter-leanup --> kol-link
+  kol-link-group --> kol-link
+  kol-skip-nav --> kol-link
+  style kol-link fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+

package/doc/logo.md

@@ -0,0 +1,76 @@
+# Logo
+
+Mit Hilfe der **Logo**-Komponente können an beliebigen Positionen Logos ausgegeben werden. Die zur Verfügung stehenden Logos entstammen aus dem Umfeld
+der Bundesinstitutionen. Die **Logo**-Komponente rendert an beliebiger Position auf der Webseite ein Logo, das über ein Attribut definiert wird. Das Logo wird dabei aus einer
+Sammlung von SVG-Grafiken zusammengesetzt, die fertig konstruiert vorliegen. Die Ausgabe des Logos kann über das Attribut **style** definiert werden.
+
+## Konstruktion
+
+### Code
+
+```tsx
+<div>
+	<kol-logo _abbr="BReg"></kol-logo>
+</div>
+```
+
+### Beispiel
+
+<kol-logo _abbr="BReg"></kol-logo>
+
+## Verwendung
+
+Das Attribut `_abbr` wird für die Definition des gewünschten Logos verwendet. Es sind folgende Parameter möglich:
+
+**BReg** = **_Die Bundesregierung_**
+
+**BMF** = **_Bundesministerium der Finanzen_**
+
+**BMI** = **_Bundesministerium des Innern, für Bau und Heimat_**
+
+**AA** = **_Auswärtiges Amt_**
+
+**BMWi** = **_Bundesministerium für Wirtschaft und Energie_**
+
+**BMJV** = **_Bundesministerium der Justiz und für Verbraucherschutz_**
+
+**BMAS** = **_Bundesministerium für Arbeit und Soziales_**
+
+**BMVg** = **_Bundesministerium der Verteidigung_**
+
+**BMEL** = **_Bundesministerium für Ernährung und Landwirtschaft_**
+
+**BMFSFJ** = **_Bundesministerium für Familie, Senioren, Frauen und Jugend_**
+
+**BMG** = **_Bundesministerium für Gesundheit_**
+
+**BMVI** = **_Bundesministerium für Verkehr und digitale Infrastruktur_**
+
+**BMU** = **_Bundesministerium für Umwelt, Naturschutz und nukleare Sicherheit_**
+
+**BMBF** = **_Bundesministerium für Bildung und Forschung_**
+
+**BMZ** = **_Bundesministerium für wirtschaftliche Zusammenarbeit und Entwicklung_**
+
+<!--### Best practices
+
+### Anwendungsfälle-->
+
+## Barrierefreiheit
+
+<!--## Links und Referenzen
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property            | Attribute | Description                                                                                                                                                                     | Type                                                           | Default     |
+| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------- |
+| `_abbr`             | `_abbr`   | <span class="text-red-500">**[DEPRECATED]**</span> Verwende stattdessen das Property _org.<br/><br/>Gibt die Abkürzung eines Ministeriums, eines Amts oder einer Bundesanstalt an. | `Bundesamt \| Bundesanstalt \| Bundesministerium \| undefined` | `undefined` |
+| `_org` _(required)_ | `_org`    | Gibt die Abkürzung eines Ministeriums, eines Amts oder einer Bundesanstalt an.                                                                                                  | `Bundesamt \| Bundesanstalt \| Bundesministerium`              | `undefined` |
+
+
+----------------------------------------------
+
+

package/doc/modal.md

@@ -0,0 +1,124 @@
+# Modal
+
+Mit Hilfe der **Modal**-Komponente können zusätzliche Informationen oder auch Eingabeformulare in einem
+Dialogfenster angezeigt werden. Sie wird nach Klick auf einen Button aufgerufen und über ein eigenes
+Close-Icon wieder geschlossen. Die **Modal**-Komponente basiert auf der **Card**-Komponente und ist standardmäßig versteckt. Sie wird i.d.R.
+erst nach Klick auf einen Button oder sonstigem Trigger angezeigt. Dabei wird der Hintergrund des Fensters deaktiviert und allein der Inhalt
+des Modal-Fensters ist aktiv. Das **Modal**-Fenster wird über ein **Close-Icon** oben rechts im Kopfbereich wieder
+geschlossen.
+
+## Funktionsweise
+
+Das **Modal** realisiert die Basis für barrierefreie Overlays und ermöglicht es beliebige HTML-Inhalte anzuzeigen. Beispielsweise wäre eine Dialog-Komponente eine Komposition aus einer Card-Komponente die in einer **Modal**-Komponente eingefügt wird.
+
+Sobald ein **Modal** geöffnet wird, werden alle selektierbaren Elemente in der Webseite deaktiviert, außer die innerhalb des aktiven Modals.
+
+Werden mehrere **Modale** nach einander geöffnet, dann wird immer nur das letzte geöffnete angezeigt. Die **Modale** werden nach dem _Last In – First Out_ -Prinzip (LIFO) angezeigt, wobei die einzelnen **Modale** in beliebiger Reihenfolge wieder geschlossen werden können.
+
+## Konstruktion
+
+### Code
+
+> Um das Zusammenspiel von Komponenten (HTML) und Controller (TypeScript) gemeinsam darzustellen, wurden alle Code-Beispiele auf dieser Seite mit den Web Components im TSX geschrieben.
+
+```tsx
+<kol-modal
+  _activeElement={this.state.activeElement}
+  _aria-label="Beschreibung zur Modalbox"
+  _on={{
+    onClick: (event: Event) => {
+      this.setState({
+        activeElement: null // schließt das Modal
+      })
+    }
+  }}
+  _width="400px"
+>
+  <kol-card _heading="Vorgang löschen" _has-footer>
+    <p slot="content">Wollen Sie den Vorgang wirklich löschen?</p>
+    <div slot="footer">
+      <kol-button _label="Ok" _variant="primary"></kol-button>
+      <kol-button _label="Abbrechen"></kol-button>
+    </div>
+  </kol-card>
+</kol-modal>
+<kol-button
+  _on={{
+    onClick: (event: Event) => {
+      this.setState({
+        activeElement: event.target as HTMLElement // öffnen das Modal
+      })
+    }
+  }}
+  _label="Modal öffnen"
+></kol-button>
+```
+
+## Verwendung
+
+Über das Attribut `_width` geben Sie die gewünschte Breite der Modalbox an. Sie wird in der gewählten Größe immer mittig auf dem Bildschirm angezeigt.
+
+Da das Modal vom eigentlichen Modal entkoppelt ist, aber für eine teilweisen Sperrung der Inhalte sorgt. Muss es auch eine Möglichkeit bieten, das Schließen (Sperrung aufheben) aus dem Modal-Kontext zu ermöglichen. Das wird durch einen optionalen Schließen-Button rechts oben in der Ecke sichergestellt.
+
+<kol-alert _type="info">Standardmäßig wird die Modalbox mit einem **Close-Button** oben rechts gerendert. Diese Position ist aktuell fix und kann nicht geändert werden. Es ist aber möglich innerhalb der Modalbox einen eigenen Close-Button einzubauen und den Standardbutton auszublenden.</kol-alert>
+
+### Best practices
+
+- Verwenden Sie die Modalbox, um weiterführende Informationen zu einem Thema anzuzeigen.
+- Verwenden Sie die Modalbox, um umfangreiche Inhalte optisch kompakter zu gestalten.
+- Vermeiden Sie es, wichtige Informationen wie z.B. rechtliche Themen, auf die Nutzer:innen reagieren müssen, in Modalboxen zu platzieren.
+
+### Anwendungsfälle
+
+- Nutzen Sie die Modalbox, als Erklärungshilfe zu einzelnen Eingabefeldern in Formularen.
+- Nutzen Sie die Modalbox, um ergänzende Informationen erst nach Anforderung durch die Nutzer:innen anzuzeigen.
+- Nutzen Sie die Modalbox, um ein Feedback zu Speichervorgängen oder ähnliches anzuzeigen, z.B. **_Vielen Dank für Ihre Rückmeldung_** nach Absenden eines Formulars.
+
+## Barrierefreiheit
+
+> Die optische Standardausgabe der Komponente ist auf die Umsetzung der Barrierefreiheit hin optimiert. Wenn Sie eigene Custom Styles verwenden, kann das zu einer Einschränkung der Barrierefreiheit führen.
+
+Das **Modal** ist so realisiert, dass der Fokus darauf liegt, wenn es geöffnet wird. Elemente außerhalb des Modals sind dann nicht mehr fokussierbar.
+
+Wird das **Modal** geschlossen, liegt der Fokus wieder auf dem Element, welches ursprünglich das **Modal** geöffnet hatte.
+
+Bei der Realisierung dieser Funktionalität haben wir auf die Verwendung der CSS-Properties `user-select` und `pointer-events` verzichtet, um das Navigieren aus der Webseite in die Browser-Menü's weiterhin zu ermöglichen. Ebenfalls haben wir darauf verzichtet die _Event-Propagation_ zu manipulieren.
+
+Achten Sie für eine optimale Ausgabe der **Modal**-Komponente in Screenreadern darauf, das Attribut **`aria-label`** korrekt zu setzen.
+
+Beim Öffnen eines Modals, muss der Entwickler:in das aktive Element übergeben, zu dem nach dem Schließen des Modals automatisch der Fokus gesetzt werden soll.
+
+Des Weiteren gibt es immer nur maximal ein aktives Modal, welches alle selektierbaren Elemente deaktiviert außer die innerhalb des eigenen Modals. Hierbei ist zu beachten, dass KoliBri nur Elemente deaktiviert die sich im Browser-Seitenbereich befinden. Das Fokussieren den Browser-Menü's ist weiterhin möglich.
+
+Zusätzlich stellt die Komponente sicher, dass die Darstellung beliebiger Inhalte bei beliebiger Zoomstufe barrierefrei bleibt. Hierzu wird ein vertikaler Scroll-Balken bei bedarf verwendet.
+
+### Tastatursteuerung
+
+| Taste   | Funktion                                                                                                                                                                         |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tab`   | Fokussiert den Aufrufbutton des Modal. Bei geöffnetem Modal werden alle fokussierbaren Elemente der Reihenfolge nach angesprungen, insbesondere auch der Close-Button des Modal. |
+| `Enter` | Öffnet das Modal.                                                                                                                                                                |
+| `Leer`  | Öffnet das Modal.                                                                                                                                                                |
+
+## Links und Referenzen
+
+- https://www.w3.org/TR/wai-aria-practices/#dialog_modal
+- https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property                  | Attribute     | Description                                                                             | Type                                                            | Default     |
+| ------------------------- | ------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------- |
+| `_activeElement`          | --            | Gibt die Referenz auf das auslösende HTML-Element an, wodurch das Modal geöffnet wurde. | `HTMLElement \| null \| undefined`                              | `undefined` |
+| `_ariaLabel` _(required)_ | `_aria-label` | Gibt den Text an, der die Navigation von anderen Navigationen differenziert.            | `string`                                                        | `undefined` |
+| `_on`                     | --            | Gibt die EventCallback-Function für das Schließen des Modals an.                        | `undefined \| { onClose?: EventCallback<Event> \| undefined; }` | `undefined` |
+| `_show`                   | `_show`       | Gibt an, ob das Modal angezeigt wird.                                                   | `boolean \| undefined`                                          | `false`     |
+| `_width`                  | `_width`      | Gibt an, wie breit der Anzeigebereich sein soll (<= max-width: 100%).                   | `string \| undefined`                                           | `'100%'`    |
+
+
+----------------------------------------------
+
+