docs: enhance component documentation with examples for avatars, buttons, cards, and offcanvas

docs/content/ui/components/avatars.md

@@ -4,6 +4,9 @@ summary: Avatars help customize various elements of a user interface and make th
 description: Personalize UI with user avatars.
 ---
 
+{% capture html %}{% include "ui/avatar.html" %}{% endcapture %}
+{% include "docs/component.html" html=html width-start=40 height=40 icon-size=24 icon-x=8 icon-y=8 border=0 %}
+
 ## Default markup
 
 Use the `avatar` class to add an avatar to your interface design for greater customization.

docs/content/ui/components/buttons.md

@@ -5,6 +5,9 @@ bootstrapLink: components/buttons/
 description: Customizable buttons for user actions.
 ---
 
+{% capture html %}{% include "ui/button.html" text="Button" icon="user-circle" %}{% endcapture %}
+{% include "docs/component.html" html=html padding-right=16 padding-left=12 gap=8 gap-start=32 height-start=40 icon-size=20 icon-x=12 icon-y=9 %}
+
 ## Button tag
 
 As one of the most common elements of UI design, buttons have a very important function of engaging users within your website or app and guiding them in their actions. Use the `.btn` classes with the `<button>` element and add additional styling that will make your buttons serve their purpose and draw users' attention.

docs/content/ui/components/cards.md

@@ -5,6 +5,9 @@ bootstrapLink: components/card/
 description: Organize content with flexible cards.
 ---
 
+{% capture html %}{% include "cards/card.html" %}{% endcapture %}
+{% include "docs/component.html" html=html padding-left=20 padding-right=20 padding-top=16 padding-bottom=16 max-width=300 %}
+
 ## Default card
 
 Use the `.card` and `.card-body` classes to create a card and use it as the basis for a more advanced card design. A card is a perfect way to organize content and make it look neat and tidy.

docs/content/ui/components/offcanvas.md

@@ -9,6 +9,11 @@ Offcanvas is a sidebar component that can be toggled via JavaScript to appear fr
 To create an offcanvas, add the `.offcanvas` class to a container element. You can also add the `.offcanvas-start`, `.offcanvas-end`, `.offcanvas-top`, or `.offcanvas-bottom` class to specify the position of the offcanvas. The `.show` class is used to display the offcanvas.
 
 {% capture html -%}
+<button class="btn" data-bs-toggle="offcanvas" href="#offcanvas" role="button" aria-controls="offcanvas">
+  Toggle offcanvas
+</button>
+{%- endcapture %}
+{% capture html-teleport -%}
 <div
   class="offcanvas offcanvas-start"
   tabindex="-1"
@@ -22,13 +27,18 @@ To create an offcanvas, add the `.offcanvas` class to a container element. You c
   </div>
 </div>
 {%- endcapture %}
-{% include "docs/example.html" html=html raw %}
+{% include "docs/example.html" html=html html-teleport=html-teleport centered %}
 
 ## Cookies banner
 
 The offcanvas component is used to display a cookies banner. It is a great way to inform users about the use of cookies on your website and to get their consent.
 
 {% capture html -%}
+<button class="btn" data-bs-toggle="offcanvas" href="#offcanvasBottom" role="button" aria-controls="offcanvas">
+  🍪 Show cookie banner
+</button>
+{%- endcapture %}
+{% capture html-teleport -%}
 <div
   class="offcanvas offcanvas-bottom h-auto"
   tabindex="-1"
@@ -60,7 +70,7 @@ The offcanvas component is used to display a cookies banner. It is a great way t
   </div>
 </div>
 {%- endcapture %}
-{% include "docs/example.html" html=html raw %}
+{% include "docs/example.html" html=html html-teleport=html-teleport centered %}
 
 <script>
 document.addEventListener('DOMContentLoaded', function() {

preview/pages/el-test.html

@@ -0,0 +1,50 @@
+---
+layout: default
+title: El Test
+permalink: /el-test.html
+page-header: El Test
+---
+
+<div class="card">
+   <div class="card-body">
+      <div class="space-y">
+         {% capture html %}{% include "ui/button.html" text="Button" %}{% endcapture %}
+         {% include "docs/component.html" html=html padding=16 height-start=40 margin-bottom=16 %}
+
+         {% capture html %}{% include "ui/button.html" text="Button" icon="user-circle" %}{% endcapture %}
+         {% include "docs/component.html" html=html padding-right=16 padding-left=12 gap=8 gap-start=32 height-start=40 margin-left=16 margin-right=16 icon-size=20 icon-x=12 icon-y=9 %}
+
+         {% capture html %}{% include "ui/button.html" text="Button" icon-end="user-circle" %}{% endcapture %}
+         {% include "docs/component.html" html=html padding-right=12 padding-left=16 gap=8 gap-end=32 height=40 icon-size=20 icon-end-x=12 icon-y=9 %}
+
+         {% capture html %}{% include "ui/avatar.html" %}{% endcapture %}
+         {% include "docs/component.html" html=html height=40  width=40 %}
+
+         {% capture html %}{% include "ui/avatar.html" %}{% endcapture %}
+         {% include "docs/component.html" html=html height-start=40 width=40 width-start %}
+
+         {% capture html %}<input type="text" class="form-control" placeholder="Input placeholder">{% endcapture %}
+         {% include "docs/component.html" html=html height=40 padding-top=8 padding-bottom=8 padding-left=16 padding-right=16 %}
+
+         {% capture html %}<textarea class="form-control" rows="3" placeholder="Textarea placeholder"></textarea>{% endcapture %}
+         {% include "docs/component.html" html=html padding=12 height=80 %}
+
+         {% capture html %}{% include "ui/form/input-icon.html" icon="search" placeholder="Search…" %}{% endcapture %}
+         {% include "docs/component.html" html=html padding-right=8 padding-left=16 height=40 %}
+
+         {% capture html %}{% include "ui/progress.html" value=50 %}{% endcapture %}
+         {% include "docs/component.html" html=html height=8 max-width=300 %}
+
+         {% capture html %}{% include "ui/alert.html" type="success" title="Success alert" class="m-0" %}{% endcapture %}
+         {% include "docs/component.html" html=html padding=16 max-width=400 %}
+
+         {% capture html %}{% include "ui/badge.html" text="Badge" color="blue" %}{% endcapture %}
+         {% include "docs/component.html" html=html padding=8 height=24 %}
+
+         {% capture html %}<div class="card"><div class="card-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</div></div>{% endcapture %}
+         {% include "docs/component.html" html=html padding=20 max-width=400 %}
+
+
+      </div>
+   </div>
+</div>

shared/includes/docs/component.html

@@ -0,0 +1,143 @@
+{% removeemptylines %}
+{% assign border = include.border | default: 1 %}
+{% assign height = include.height | default: include.height-start | default: false %}
+{% assign width = include.width | default: include.width-start | default: false %}
+
+{% assign icon-size = include.icon-size | default: false %}
+{% assign icon-x = include.icon-x | default: 0 %}
+{% assign icon-y = include.icon-y | default: 0 %}
+
+{% assign padding-left = include.padding-left | default: include.padding | default: false %}
+{% assign padding-right = include.padding-right | default: include.padding | default: false %}
+{% assign padding-top = include.padding-top | default: false %}
+{% assign padding-bottom = include.padding-bottom | default: false %}
+
+{% assign gap = include.gap | default: false %}
+{% assign gap-start = include.gap-start | default: false %}
+{% assign gap-end = include.gap-end | default: false %}
+
+{% assign size-color = 'var(--tblr-blue)' %}
+{% assign margin-color = 'var(--tblr-purple)' %}
+{% assign padding-color = 'var(--tblr-pink)' %}
+{% assign icon-color = 'var(--tblr-green)' %}
+
+<div
+   class="border fs-base lh-base rounded px-4 py-8 my-5 d-flex justify-content-center align-items-center bg-surface-secondary{% if include.class %} {{ include.class }}{% endif %}">
+   <div style="display: flex; flex-direction: column;">
+      <div style="display: flex; flex-direction: row; max-width: 100%; pointer-events: none;">
+         {% if include.margin-left %}
+         <div style="position: relative; width: {{ include.margin-left }}px;">
+            <div style="position: absolute; color: {{ margin-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; width: 100%; left: 0; right: 0; top: calc(100% + 0.5rem); border-top: 1px solid {{ margin-color }}; border-color: {{ margin-color }}; padding-top: 0.25rem;">
+               {{ include.margin-left }}px
+               <div style="position: absolute; border: 0 solid {{ margin-color }}; left: 0; right: 0; top: -3px; height: 5px; border-left-width: 1px; border-right-width: 1px; border-color: {{ margin-color }};"></div>
+            </div>
+            <div style="background: {{ margin-color }}; position: relative; height: 100%; opacity: .1;"></div>
+         </div>
+         {% endif %}
+         {% # element %}
+         <div style="position: relative; display: inline-flex; max-width: 100%;">
+            <div style="display: block; position: relative;{% if include.max-width %} width: {{ include.max-width }}px; max-width: 100%;{% endif %}">
+               {{ include.html }}
+            </div>
+            {% if icon-size %}
+            <div style="position: absolute; background: {{ icon-color }}; opacity: .1; top: {{ icon-y | plus: border }}px; width: {{ icon-size }}px; height: {{ icon-size }}px; {% if include.icon-end-x %}right: {{ include.icon-end-x | plus: border }}px; {% else %}left: {{ icon-x | plus: border }}px; {% endif %}"></div>
+            <div
+               style="position: absolute; top: {{ icon-y | plus: border }}px; width: {{ icon-size }}px; height: {{ icon-size }}px; border: 1px solid {{ icon-color }};{% if include.icon-end-x %}right: {{ include.icon-end-x | plus: border }}px; {% else %}left: {{ icon-x | plus: border }}px; {% endif %}">
+               <div
+                  style="position: absolute; top: 100%; left: 50%; height: {% if include.margin-left or include.margin-right %}40px{% else %}20px{% endif %}; border-left: 1px solid {{ icon-color }};">
+                  <div style="position: absolute; top: 100%; left: 0; transform: translateX(-50%); text-align: center; font-size: 11px; line-height: 1; pointer-events: none; color: {{ icon-color }}; padding-top: .25rem;">
+                     {{ icon-size }}&times;{{ icon-size }}px
+                  </div>
+               </div>
+            </div>
+            {% endif %}
+            {% if height or height-start %}
+            {% # height of element %}
+            <div style="position: absolute; color: {{ size-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; height: 100%; top: 0; bottom: 0; {% if include.height-start %}right: calc(100% + {{ include.margin-left | default: 0 }}px + .5rem); padding-right: .25rem; border-right: 1px solid {{ size-color }}; {% else %}left: calc(100% + {{ include.margin-left | default: 0 }}px + .5rem); padding-left: .25rem; border-left: 1px solid ; {% endif %}">
+               {{ height }}px
+               <div style="position: absolute; border: 0 solid {{ size-color }}; top: 0; bottom: 0; width: 5px; border-top-width: 1px; border-bottom-width: 1px;{% if include.height-start %} right: -3px;{% else %} left: -3px;{% endif %}"></div>
+            </div>
+            {% endif %}
+            {% if width %}
+            {% # width of element %}
+            <div
+               style="position: absolute; color: {{ size-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; left: 0; right: 0; {% if include.width-start %}bottom: calc(100% + .5rem); padding-bottom: .25rem; border-bottom: 1px solid {{ size-color }}; {% else %}top: calc(100% + .5rem); padding-top: .25rem; border-top: 1px solid; {% endif %}">
+               {{ width }}px
+               <div style="position: absolute; border: 0 solid {{ size-color }}; left: 0; right: 0; height: 5px; border-left-width: 1px; border-right-width: 1px;{% if include.width-start %} bottom: -3px;{% else %} top: -3px;{% endif %}"></div>
+            </div>
+            {% endif %}
+            {% if padding-left %}
+            <div style="position: absolute; color: {{ padding-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; left: {{ border }}px; bottom: calc(100% + 0.5rem); border-bottom: 1px solid {{ padding-color }}; padding-bottom: 0.25rem; width: {{ padding-left }}px;">
+               {{ padding-left }}px
+               <div style="position: absolute; border: 0 solid {{ padding-color }}; left: 0; right: 0; bottom: -3px; height: 5px; border-left-width: 1px; border-right-width: 1px; border-color: {{ padding-color }};"></div>
+            </div>
+            <div style="background: {{ padding-color }}; opacity: .1; position: absolute; top: {{ border }}px; bottom: {{ border }}px; left: {{ border }}px; width: {{ padding-left }}px;"></div>
+            {% endif %}
+            {% if padding-right %}
+            <div style="position: absolute; color: {{ padding-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; left: auto; right: {{ border }}px; bottom: calc(100% + 0.5rem); border-bottom: 1px solid {{ padding-color }}; padding-bottom: 0.25rem; width: {{ padding-right }}px;">
+               {{ padding-right }}px
+               <div style="position: absolute; border: 0 solid {{ padding-color }}; left: 0; right: 0; bottom: -3px; height: 5px; border-left-width: 1px; border-right-width: 1px; border-color: {{ padding-color }};"></div>
+            </div>
+            <div style="background: {{ padding-color }}; opacity: .1; position: absolute; top: {{ border }}px; bottom: {{ border }}px; left: auto; right: {{ border }}px; width: {{ padding-right }}px;"></div>
+            {% endif %}
+            {% if padding-top %}
+            <div
+               style="position: absolute; color: {{ padding-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; top: {{ border }}px; right: calc(100% + 0.5rem); border-right: 1px solid {{ padding-color }}; padding-right: 0.25rem; height: {{ padding-top }}px;">
+               {{ padding-top }}px
+               <div
+                  style="position: absolute; border: 0 solid {{ padding-color }}; top: 0; bottom: 0; right: -3px; width: 5px; border-top-width: 1px; border-bottom-width: 1px; border-color: {{ padding-color }};">
+               </div>
+            </div>
+            <div
+               style="background: {{ padding-color }}; opacity: .1; position: absolute; left: {{ border | plus: padding-left }}px; right: {{ border | plus: padding-right }}px; top: {{ border }}px; height: {{ padding-top }}px;">
+            </div>
+            {% endif %}
+            {% if padding-bottom %}
+            <div
+               style="position: absolute; color: {{ padding-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; bottom: {{ border }}px; right: calc(100% + 0.5rem); border-right: 1px solid {{ padding-color }}; padding-right: 0.25rem; height: {{ padding-bottom }}px;">
+               {{ padding-bottom }}px
+               <div
+                  style="position: absolute; border: 0 solid {{ padding-color }}; top: 0; bottom: 0; right: -3px; width: 5px; border-top-width: 1px; border-bottom-width: 1px; border-color: {{ padding-color }};">
+               </div>
+            </div>
+            <div
+               style="background: {{ padding-color }}; opacity: .1; position: absolute; left: {{ border | plus: padding-left }}px; right: {{ border | plus: padding-right }}px; bottom: {{ border }}px; height: {{ padding-bottom }}px;">
+            </div>
+            {% endif %}
+            {% if gap and gap-start %}
+            <div style="position: absolute; color: {{ padding-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; left: {{ gap-start | plus: border }}px; bottom: calc(100% + 0.5rem); border-bottom: 1px solid {{ padding-color }}; padding-bottom: 0.25rem; width: {{ gap }}px;">
+               {{ gap }}px
+               <div style="position: absolute; border: 0 solid {{ padding-color }}; left: 0; right: 0; bottom: -3px; height: 5px; border-left-width: 1px; border-right-width: 1px; border-color: {{ padding-color }};"></div>
+            </div>
+            <div style="background: {{ padding-color }}; opacity: .1; position: absolute; top: {{ border }}px; bottom: {{ border }}px; left: {{ gap-start | plus: border  }}px; width: {{ gap }}px;"></div>
+            {% endif %}
+            {% if gap and gap-end %}
+            <div style="position: absolute; color: {{ padding-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; right: {{ gap-end }}px; left: auto; bottom: calc(100% + 0.5rem); border-bottom: 1px solid {{ padding-color }}; padding-bottom: 0.25rem; width: {{ gap }}px;">
+               {{ gap }}px
+               <div style="position: absolute; border: 0 solid {{ padding-color }}; left: 0; right: 0; bottom: -3px; height: 5px; border-left-width: 1px; border-right-width: 1px; border-color: {{ padding-color }};"></div>
+            </div>
+            <div style="background: {{ padding-color }}; opacity: .1; position: absolute; top: {{ border }}px; bottom: {{ border }}px; right: {{ gap-end }}px; left: auto; width: {{ gap }}px;"></div>
+            {% endif %}
+         </div>
+         {% if include.margin-right %}
+         <div style="position: relative; width: {{ include.margin-right }}px;">
+            <div style="position: absolute; color: {{ margin-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; width: 100%; left: 0; right: 0; top: calc(100% + 0.5rem); border-top: 1px solid {{ margin-color }}; border-color: {{ margin-color }}; padding-top: 0.25rem;">
+               {{ include.margin-right }}px
+               <div style="position: absolute; border: 0 solid {{ margin-color }}; left: 0; right: 0; top: -3px; height: 5px; border-left-width: 1px; border-right-width: 1px; border-color: {{ margin-color }};"></div>
+            </div>
+            <div style="background: {{ margin-color }}; position: relative; height: 100%; opacity: .1;"></div>
+         </div>
+         {% endif %}
+      </div>
+      {% if include.margin-bottom %}
+      <div style="position: relative; width: 100%; height: {{ include.margin-bottom }}px;">
+         <div style="position: absolute; color: {{ margin-color }}; display: flex; align-items: center; justify-content: center; font-size: 11px; line-height: 1; pointer-events: none; height: 100%; top: 0; bottom: 0; left: calc(100% + 0.5rem); border-left: 1px solid {{ margin-color }}; border-color: {{ margin-color }}; padding-left: 0.25rem;">
+            {{ include.margin-bottom }}px
+            <div style="position: absolute; border: 0 solid {{ margin-color }}; top: 0; bottom: 0; left: -3px; width: 5px; border-top-width: 1px; border-bottom-width: 1px; border-color: {{ margin-color }};"></div>
+         </div>
+         <div style="background: {{ margin-color }}; position: relative; height: 100%; opacity: .1;"></div>
+      </div>
+      {% endif %}
+   </div>
+</div>
+{% endremoveemptylines %}

shared/includes/docs/example.html

@@ -1,11 +1,17 @@
 <!--EXAMPLE-->
 <div
-	class="example fs-base border rounded my-5{% unless include.raw %} d-flex flex-wrap justify-content-center{% endunless %} overflow-{{ include.overflow | default: 'auto' }} position-relative {% if include.bg %}bg-{{ include.bg }}{% endif %}{% if include.class %} {{ include.class }}{% endif %}"{% if include.height %} style="height: {{ include.height }}"{% endif %}{% unless include.bg %} style="background: url('data:image/svg+xml;utf8,<svg xmlns=\'http://www.w3.org/2000/svg\' width=\'20\' height=\'20\' viewBox=\'0 0 20 20\'><rect fill=\'rgba(0, 0, 0, .01)\' x=\'0\' y=\'0\' width=\'10\' height=\'10\' /><rect fill=\'rgba(0, 0, 0, .01)\' x=\'10\' y=\'10\' width=\'10\' height=\'10\' /></svg>')"{% endunless %}}>
+	class="example fs-base lh-base border rounded my-5{% unless include.raw %} d-flex flex-wrap justify-content-center{% endunless %} overflow-{{ include.overflow | default: 'auto' }} position-relative {% if include.bg %}bg-{{ include.bg }}{% endif %}{% if include.class %} {{ include.class }}{% endif %}"{% if include.height %} style="height: {{ include.height }}"{% endif %}{% unless include.bg %} style="background: url('data:image/svg+xml;utf8,<svg xmlns=\'http://www.w3.org/2000/svg\' width=\'20\' height=\'20\' viewBox=\'0 0 20 20\'><rect fill=\'rgba(0, 0, 0, .01)\' x=\'0\' y=\'0\' width=\'10\' height=\'10\' /><rect fill=\'rgba(0, 0, 0, .01)\' x=\'10\' y=\'10\' width=\'10\' height=\'10\' /></svg>')"{% endunless %}}>
 	{%- unless include.raw -%}<div class="p-6 w-full{% if include.column %} d-flex gap-3 flex-column{% elsif include.centered %} d-flex flex-fill flex-wrap gap-2 justify-content-center{% if include.vertical %} align-items-center flex-column{% else %} justify-content-center{% endif %}{% endif %}" {% if include.column %}style="max-width: 25rem;"{% endif %}>{%- endunless -%}
 		{{ include.html | remove-href }}
 	{%- unless include.raw -%}</div>{%- endunless -%}
 </div>
 
+{% if include.html-teleport %}
+<div class="example-teleport">
+	{{ include.html-teleport | remove-href }}
+</div>
+{% endif %}
+
 {% unless include.hide-code %}
 <div class="position-relative">
 <a class="btn btn-icon btn-dark position-absolute m-2 top-0 end-0 z-3" data-clipboard-text="{{ include.html | escape_attribute }}">
@@ -15,6 +21,9 @@
 
 ```html
 {{ include.html }}
+{% if include.html-teleport %}
+{{ include.html-teleport }}
+{% endif %}
 ```
 
 </div>

shared/includes/ui/avatar.html

@@ -33,6 +33,6 @@
 {% elsif include.icon %}
 {% include "ui/icon.html" icon=include.icon class="avatar-icon" %}
 {% else %}
-{% include "ui/icon.html" icon="user" class="avatar-icon" %}
+{% include "ui/icon.html" icon="user-circle" class="avatar-icon" %}
 {% endif %}
 </{{ el }}>