hr-design-system-handlebars 1.11.11 → 1.12.0

package/src/stories/views/components/button/button.hbs

@@ -1,30 +1,15 @@
-<button 
-    {{~#if _aria}} aria-label="{{_aria}}"{{/if}} 
-    {{~#if _isButton}} type="button"{{else}} type="submit"{{/if~}} 
+<button
+    {{#if _id}} id="{{_id}}"{{/if}} 
+    class="ds-button {{> components/button/utilities/button_base_classes}} {{> components/button/utilities/button_variation_classes _variant=_variant _onBackground=_onBackground _disableButtonPress=_disableButtonPress}} {{> components/button/utilities/button_dimension_classes _size=_size}}{{#if _css}} {{_css}}{{/if}} {{#> css}}{{/css}}{{#if _openModal}} js-modalButton{{/if}}"
+    {{#if _openModal}} aria-haspopup="true"{{/if}}
+    {{~#if _ariaLabel}} aria-label="{{_ariaLabel}}"{{/if}}
+    type="{{defaultIfEmpty _type "submit"}}"
     {{~#if _name}} name="{{_name}}"{{/if}} 
-    {{~#if _title}} title="{{_title}}"{{/if}} 
-    class="{{_addClass}}{{#if _addClass2}} {{_addClass2}}{{/if}}{{#if _buttonColor}} {{_buttonColor}}{{/if}}{{#if _buttonSpace}} {{> components/button/button_round_classes _teaserSize=_teaserSize _teaserType=_teaserType _isMobile1to1=_isMobile1to1}}{{/if}}{{#if _webview}} -webview{{/if}}"
+    {{~#if _title}} title="{{_title}}"{{/if}}
     {{~#if _value}} value="{{_value}}"{{/if}} 
     {{~#if _alpineClick}} @click="{{_alpineClick}}"{{/if}} 
     {{~#if _x-show}} x-show="{{_x-show}}"{{/if}} 
     {{~#if _noFocus}} tabindex="-1"{{/if}}
->
-    {{~#if _showIcon~}}
-        {{> components/base/image/icon
-                _icon=_icon
-                _iconmap=_iconmap
-                _addClass=_addIconClass
-                _webview=_webview
-                _ariaHidden=false
-                _iconTitle=false
-                _iconDesc=false
-                _iconText=false
-                _overlayIcon=false
-        }}
-    {{/if~}}
-    {{~#if _label~}}
-        <span {{#if _srOnly}}class="sr-only"{{/if}}>
-            {{~_label~}}
-        </span>
-    {{/if~}}
+    {{#> html_properties}}{{/html_properties}}>
+    {{> @partial-block }}
 </button>

package/src/stories/views/components/button/button.mdx

@@ -0,0 +1,186 @@
+import { ArgsTable, Meta, Story, Canvas } from '@storybook/blocks'
+import * as ButtonStories from './button.stories'
+
+<Meta of={ButtonStories} />
+
+# Button
+
+-   [Übersicht](#übersicht)
+-   [Eigenschaften](#eigenschaften)
+-   [Varianten](#varianten)
+-   [Verwendung](#verwendung)
+
+## Übersicht
+
+Buttons erlauben es eine Aktion oder ein Ereignis mit einem Klick auszulösen. Sie werden z.B. in der Navigation einer Tab-Box verwendet, um zwischen
+den unterschiedlichen Tabs umzuschalten oder werden genutzt, um ein ein Modal zu öffnen.
+Soll die Schaltfläche optisch wie ein Button aussehen, bei einem Klick aber eine neue Seite öffnen, darf nicht die Button-Komponente genutzt werden.
+Für diesen Anwendungsfall gibt es mit dem Button-Link eine eigene Komponente. Sie erzeugt technisch ein HTML Link Element,
+das optisch genauso wie ein Button aussieht. Beispiele hierfür sind die Schaltfläche am unteren Rand einer Tab-Box, die es
+ermöglicht auf eine Seite mit weiteren Inhalten zu kommen, die Schaltfläche innerhalb eines Cluster-Teasers, die auf eine Seite mit weiteren Beiträgen verlinkt
+oder die Schaltfläche innerhalb eines Poster-Teasers, die auf den konkreten Inhalt verlinkt.
+
+Die Button-Komponente als solches ist sehr einfach gehalten. Sie stellt nur ein Grundgerüst (ein gestyltes HTML-Button Element) zur Verfügung.
+Alle Inhalte des Buttons, wie das [Label](?path=/docs/komponenten-buttons-komponenten-label--label) oder ein mögliches
+[Icon](?path=/docs/komponenten-buttons-komponenten-icon--icon), können flexibel durch Subkomponenten hinzugefügt werden.
+
+<Canvas>
+    <Story of={ButtonStories.Spielplatz} />
+</Canvas>
+
+## Eigenschaften
+
+<ArgsTable story="Spielplatz" />
+
+## Varianten
+
+Auf einer Inhaltsseite kann mehr als ein Button platziert werden. Um wichtige von weniger wichtigen Aktionen
+unterscheidbar zu machen, sind unterschiedliche optische Varianten und Größen von Buttons zu verwenden.
+
+### Größen
+
+<Canvas>
+    <Story of={ButtonStories.ButtonLg} />
+    <Story of={ButtonStories.ButtonMd} />
+    <Story of={ButtonStories.ButtonSm} />
+</Canvas>
+
+### Button-Arten
+
+<Canvas>
+    <Story of={ButtonStories.ButtonPrimary} />
+    <Story of={ButtonStories.ButtonSecondary} />
+    <Story of={ButtonStories.ButtonTertiary} />
+</Canvas>
+
+### Button mit Icon <a id="button-icon" />
+
+<Canvas>
+    <Story of={ButtonStories.ButtonIconRechts} />
+    <Story of={ButtonStories.ButtonIconLinks} />
+</Canvas>
+
+## Verwendung
+
+Ein Button wird mit der Handlebar Komponente `button` eingebunden. Wie einleitend schon beschrieben, stellt diese
+Komponente lediglich das Grundgerüst eines Buttons dar. Die Beschriftung und/oder ein Icon müssen mit Subkomponenten hinzugefügt
+werden.
+
+<div class="bg-blue-200 !mt-4 p-4">
+  <h4 class="!text-stone-950 font-bold">Hinweis</h4>
+
+  <p>
+    Sowohl die Button-Komponente als auch die Subkomponenten Button-Label und Button-Icon sind
+    standardmäßig bereits gestyled. Das setzen von zusätzlichen Style Klassen über den Parameter{' '}
+    <pre class="inline">\_css</pre> ist zwar bei jeder Komponente möglich, sollte aber nur dann
+    gemacht werden, wenn es gar nicht anders geht.
+  </p>
+</div>
+
+### Button mit Text
+
+Ein Button der Ausprägung `primary` mit Beschriftung wird, wie in folgendem Codebeispiel gezeigt, gebaut.
+
+<Canvas>
+    <Story of={ButtonStories.ButtonPrimary} />
+</Canvas>
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Primary"}}
+{{/components/button/button}}
+```
+
+### Button mit Text und Icon
+
+Ein Button der Ausprägung `primary` mit einem Label und einem rechts daneben stehenden Icon wird, wie
+in folgendem Codebeispiel gezeigt, gebaut.
+
+<Canvas>
+    <Story of={ButtonStories.ButtonIconRechts} />
+</Canvas>
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Icon rechts"}}
+    {{> components/button/components/button_icon _icon="arrow-right" _iconmap="icons"}}
+{{/components/button/button}}
+```
+
+Soll das Icon links vom Label stehen, muss der Aufruf der Subkomponenten einfach vertauscht werden.
+
+<Canvas>
+    <Story of={ButtonStories.ButtonIconLinks} />{' '}
+</Canvas>
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_icon _icon="arrow-left" _iconmap="icons"}}
+    {{> components/button/components/button_label _label="Icon links"}}
+{{/components/button/button}}
+```
+
+Der passende Abstand zwischen Icon und Label wird automatisch per CSS gesetzt.
+
+### Button auf farbigem Hintergund
+
+Soll ein Button auf einem farbigen Hintergrund (bietet sich vor allem bei dunklen Hintergründen an) genutzt werden, kann durch setzen des Parameters
+`_onBackground` eine auf dunkle Hintergründe abgestimmte kontrastreichere optische Variante der Button aktiviert werden.
+
+<Canvas>
+    <Story of={ButtonStories.ButtonPrimaryAufFarbigemHintergrund} />
+    <Story of={ButtonStories.ButtonSecondaryAufFarbigemHintergrund} />
+    <Story of={ButtonStories.ButtonTertiaryAufFarbigemHintergrund} />
+</Canvas>
+
+```handlebars
+{{#> components/button/link_button _size="lg" _onBackground=true}}
+    {{> components/button/components/button_label _label="Primary"}}
+{{/components/button/link_button}}
+```
+
+### Besonderheiten
+
+Die Button-Komponente kann mit [Inline-Partials](?path=/docs/grundlegendes-konventionen-und-datenstrukturen--docs#namen-übergebener-komponenten-parameter-in-partial-blocks-und-inline-partials)
+um zusätzliche HTML-Properties oder in Style-Komponenten ausgelagerte CSS-Klassen erweitert werden.
+
+#### Setzen zusätzlicher HTML Attribute
+
+In manchen Fällen reichen die standardmäßig von der Button-Komponente gesetzten HTML-Attribute nicht aus. Sollen weitere
+Attribute gesetzt werden (z.B. zum Setzen von alpine.js Direktiven), muss dies wie in folgendem Beispiel gezeigt umgesetzt werden.
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Button"}}
+{{/components/button/button}}
+{{#*inline "html_properties"}}
+    x-ref="button"
+    x-on:click="toggle()"
+    :aria-expanded="open"
+    :aria-controls="$id('dropdown-button')"
+    :class="open ? 'drop-shadow' : ''"
+    data-hr-click-tracking='{"settings": [{"type": "uxAction", "clickLabel": "podcastAbonnieren:ButtonClick"}]}'
+{{/inline}}
+```
+
+Dem hier gerenderten HTML-Button werden mit Hilfe des Inline-Partials `html_properties` die Attribute `x-ref`, `x-on`, `:aria-expanded`, `:aria-controls`, `:class`
+sowie `data-hr-click-tracking` hinzugefügt.
+
+#### Setzen von in Subkomponenten ausgelagerte CSS Klassen
+
+Müssen CSS Klassen abhängig von bestimmten Eigenschaften (z.B. Teaser-Größe, Teaser-Art, etc.) gesetzt werden, hat sich mit der Zeit
+als Best-Practice eine Auslagerung der ganzen Logik in Subkomponenten herausgestellt. Um den Inhalt dieser Subkomponenten einer
+anderen Komponente dynamisch zu übergeben, können die bislang genutzten Standard Handlebar Properties (im Kontext der Button Komponente
+`_css`) nicht genutzt werden. Einer solchen Property können ausschließlich Strings übergeben werden. Stattdessen werden auch hierfür
+Inline-Partials eingesetzt.
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Button"}}
+{{/components/button/button}}
+{{#*inline "css"}}
+    {{> components/button/utilities/button_on_image_classes _teaserSize=_teaserSize _teaserType=_teaserType _isMobile1to1=_isMobile1to1}}
+{{/inline}}
+```
+
+Über das Inline-Partial `css` können auf diese Weise theoretisch beliebig viele in Subkomponenten ausgelagerte CSS Klassen übergeben werden.