shoelace/docs/_includes/component.njk

{% extends "default.njk" %}

{# Find the component based on the `tag` front matter #}
{% set component = getComponent('sl-' + page.fileSlug) %}

{% block content %}
  {# Determine the badge variant for code status #}
  {% if component.status == 'stable' %}
    {% set badgeVariant = 'primary' %}
  {% elseif component.status == 'experimental' %}
    {% set badgeVariant = 'warning' %}
  {% elseif component.status == 'planned' %}
    {% set badgeVariant = 'neutral' %}
  {% elseif component.status == 'deprecated' %}
    {% set badgeVariant = 'danger' %}
  {% else %}
    {% set badgeVariant = 'neutral' %}
  {% endif %}

  {# Determine the badge variant for pattern status #}
  {% if component.pattern.length %}
    {% if component.pattern == 'stable' %}
      {% set patternBadgeVariant = 'primary' %}
    {% elseif component.pattern == 'in review' %}
      {% set patternBadgeVariant = 'neutral' %}
    {% else %}
      {% set patternBadgeVariant = 'danger' %}
    {% endif %}
  {% else %}
    {% set patternBadgeVariant = 'danger' %}
  {% endif %}

  {# Determine the badge variant for figma status #}
  {% if component.figma.length %}
    {% if component.figma == 'ready' %}
      {% set figmaBadgeVariant = 'success' %}
    {% elseif component.figma == 'draft' %}
      {% set figmaBadgeVariant = 'warning' %}
    {% else %}
      {% set figmaBadgeVariant = 'danger' %}
    {% endif %}
  {% else %}
    {% set figmaBadgeVariant = 'danger' %}
  {% endif %}

  {# Header #}
  <header class="component-header">
    <div class="component-header__info">
      <sl-tag variant="neutral" size="small" pill>
        Since Shoelace {{component.since or '?' }}
      </sl-tag>
      <sl-tag size="small" variant="{{ badgeVariant }}" pill style="text-transform: capitalize" >
        Code {{ component.status }}
      </sl-tag>
      <sl-tag size="small" variant="{{ patternBadgeVariant }}" pill style="text-transform: capitalize" class="{% if component.pattern == 'hide' %}hidden{% endif %}" >
        Pattern {{ component.pattern or 'Tentative' }}
      </sl-tag>
      <sl-tag size="small" variant="{{ figmaBadgeVariant }}" pill style="text-transform: capitalize" class="{% if component.figma == 'hide' %}hidden{% endif %}" >
        Figma {{ component.figma or 'Needed' }}
      </sl-tag>
    </div>
    <h1>{{ component.name | classNameToComponentName }}</h1>

    <div class="component-header__tag">
      <code>{{ component.tagName }}</code>
    </div>
  </header>

  <p class="component-summary">
    {% if component.summary %}
      {{ component.summary | markdownInline | safe }}
    {% endif %}
  </p>

  {# Main Markdown Content #}
  {{ content | safe }}
  {# Guidelines #}
  {% if
  guidelines %}
    <h2>Usage</h2>
    <div id="guidelines-content">{{ guidelines | markdown | safe }}</div>
  {% endif %}
  {# Testing #}
  {% if
  testing %}
    <h2>Testing</h2>
    <div id="testing-content">{{ testing | markdown | safe }}</div>
  {% endif %}

  {# Importing #}
  {# <h2>Importing</h2>
  <p>
    If you're using the autoloader or the traditional loader, you can ignore this
    section. Otherwise, feel free to use any of the following snippets to
    <a href="/getting-started/installation#cherry-picking">cherry pick</a> this
    component.
  </p>

  <sl-tab-group>
    <sl-tab slot="nav" panel="script">Script</sl-tab>
    <sl-tab slot="nav" panel="import">Import</sl-tab>
    <sl-tab slot="nav" panel="bundler">Bundler</sl-tab>
    <sl-tab slot="nav" panel="react">React</sl-tab>

    <sl-tab-panel name="script">
      <p>
        To import this component from
        <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace"
          >the CDN</a
        >
        using a script tag:
      </p>
      <pre><code class="language-html">&lt;script type=&quot;module&quot; src=&quot;https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/{{ meta.cdndir }}/{{ component.path }}&quot;&gt;&lt;/script&gt;</code></pre>
    </sl-tab-panel>

    <sl-tab-panel name="import">
      <p>
        To import this component from
        <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace"
          >the CDN</a
        >
        using a JavaScript import:
      </p>
      <pre><code class="language-js">import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/{{ meta.cdndir }}/{{ component.path }}';</code></pre>
    </sl-tab-panel>

    <sl-tab-panel name="bundler">
      <p>
        To import this component using
        <a href="{{ rootUrl('/getting-started/installation#bundling') }}"
          >a bundler</a
        >:
      </p>
      <pre><code class="language-js">import '@shoelace-style/shoelace/{{ meta.npmdir }}/{{ component.path }}';</code></pre>
    </sl-tab-panel>

    <sl-tab-panel name="react">
      <p>
        To import this component as a
        <a href="/frameworks/react">React component</a>:
      </p>
      <pre><code class="language-js">import {{ component.name }} from '@shoelace-style/shoelace/{{ meta.npmdir }}/react/{{ component.tagNameWithoutPrefix }}';</code></pre>
    </sl-tab-panel>
  </sl-tab-group> #}

  {# Properties #}
  {% if component.properties.length %}
    <h2>Component Props</h2>
    {% if unusedProperties.length %}
      <div role="alert" class="callout callout--warning">
        <p>
          <strong>Note</strong>: The following appear as options in the Properties
          table but are currently not part of the Teamshares Design System. Please
          check with the design team before using these options:
        </p>
        {{ unusedProperties | markdown | safe }}
      </div>
    {% endif %}

    <table>
      <thead>
        <tr>
          <th class="table-name">Property</th>
          <th class="table-default">Default</th>
          <th class="table-description">Details</th>
        </tr>
      </thead>
      <tbody>
        {% for prop in component.properties %}
          <tr>
            <td class="table-name">
              <code class="nowrap prop">{{ prop.name }}</code>
              {% if prop.attribute | length > 0 %}
                {% if prop.reflects %}
                  <sl-tooltip content="Property reflects">
                    <sl-icon library="fa" label="yes" name="fas-star" style="color: var(--sl-color-teal-500);"></sl-icon>
                  </sl-tooltip>
                {% endif %}
                {% if prop.attribute != prop.name %}
                  <br/>
                  <sl-tooltip content="This attribute is different from its property">
                    <small>
                      <code class="nowrap">
                        {{ prop.attribute }}
                      </code>
                    </small>
                  </sl-tooltip>
                {% endif %}
              {% endif %}
            </td>
            <td class="table-default">
              {% if prop.default %}
                <code class="nowrap">{{ prop.default | markdownInline | safe }}</code>
              {% else %} &mdash; {% endif %}
            </td>
            <td class="table-description">
              <p>
                {% if prop.type.text %}
                  <code>{{ prop.type.text | trimPipes | markdownInline | safe }}</code>
                {% else %} &mdash; {% endif %}
              </p>
              <p>{{ prop.description | markdownInline | safe }}</p>
            </td>
          </tr>
        {% endfor %}
        <tr>
          <td class="table-name">
            <code class="prop">updateComplete</code>
          </td>
          <td></td>
          <td>
            A read-only promise that resolves when the component has <a href="/getting-started/usage?#component-rendering-and-updating">finished updating</a>.
          </td>
        </tr>
      </tbody>
    </table>

    <p>
      <em>Learn more about <a href="{{ rootUrl('/getting-started/usage#attributes-and-properties') }}" >attributes and properties</a >.</em>
    </p>
  {% endif %}

  {# Slots #}
  {% if component.slots.length %}
    <h2>Slots</h2>

    <table>
      <thead>
        <tr>
          <th class="table-name">Name</th>
          <th class="table-description">Details</th>
        </tr>
      </thead>
      <tbody>
        {% for slot in component.slots %}
          <tr>
            <td class="nowrap">
              {% if slot.name %}
                <code>{{ slot.name }}</code>
              {% else %} (default) {% endif %}
            </td>
            <td>{{ slot.description | markdownInline | safe }}</td>
          </tr>
        {% endfor %}
      </tbody>
    </table>

    <p>
      <em>Learn more about <a href="{{ rootUrl('/getting-started/usage#slots') }}">using slots</a>.</em>
    </p>
  {% endif %}

  {# Events #}
  {% if component.events.length %}
    <h2>Events</h2>

    <table>
      <thead>
        <tr>
          <th class="table-name" data-flavor="html">Name</th>
          <th class="table-name" data-flavor="slim">Name</th>
          <th class="table-name" data-flavor="simple-form">Name</th>
          <th class="table-name" data-flavor="react">React Event</th>
          <th class="table-description">Details</th>
        </tr>
      </thead>
      <tbody>
        {% for event in component.events %}
          <tr>
            <td data-flavor="html">
              <code class="nowrap">{{ event.name }}</code>
            </td>
            <td data-flavor="slim">
              <code class="nowrap">{{ event.name }}</code>
            </td>
            <td data-flavor="simple-form">
              <code class="nowrap">{{ event.name }}</code>
            </td>
            <td data-flavor="react">
              <code class="nowrap">{{ event.reactName }}</code>
            </td>
            <td>
              {% if event.type.text %}
                <p>
                  <code>{{ event.type.text | trimPipes }}</code>
                </p>
              {% endif %}
              <p>{{ event.description | markdownInline | safe }}</p>
            </td>
            <td></td>
          </tr>
        {% endfor %}
      </tbody>
    </table>

    <p>
      <em>Learn more about <a href="{{ rootUrl('/getting-started/usage#events') }}">events</a>.</em>
    </p>
  {% endif %}

  {# Methods #}
  {% if component.methods.length %}
    <h2>Methods</h2>

    <table>
      <thead>
        <tr>
          <th class="table-name">Name</th>
          <th class="table-description">Details</th>
        </tr>
      </thead>
      <tbody>
        {% for method in component.methods %}
          <tr>
            <td class="nowrap">
              <code>{{ method.name }}()</code>
            </td>
            <td>
              {% if method.parameters.length %}
                <p>
                  <code>
                    {% for param in method.parameters %}
                      {{ param.name }}: {{ param.type.text | trimPipes }}
                      {% if not loop.last %},{% endif %}
                    {% endfor %}
                  </code>
                </p>
              {% endif %}
              <p>{{ method.description | markdownInline | safe }}</p>
            </td>
          </tr>
        {% endfor %}
      </tbody>
    </table>

    <p>
      <em>Learn more about <a href="{{ rootUrl('/getting-started/usage#methods') }}">methods</a>.</em>
    </p>
  {% endif %}

  {# Custom Properties #}
  {% if component.cssProperties.length %}
    <h2>Custom Properties</h2>

    <table>
      <thead>
        <tr>
          <th class="table-name">Name</th>
          <th class="table-description">Details</th>
        </tr>
      </thead>
      <tbody>
        {% for cssProperty in component.cssProperties %}
          <tr>
            <td class="nowrap">
              <code>{{ cssProperty.name }}</code>
            </td>
            <td>
              {% if cssProperty.default.length %}
                <p>{{ cssProperty.default }}</p>
              {% endif %}
              <p>{{ cssProperty.description | markdownInline | safe }}</p>
            </td>
          </tr>
        {% endfor %}
      </tbody>
    </table>

    <p>
      <em>Learn more about <a href="{{ rootUrl('/getting-started/usage#custom-properties') }}">customizing CSS custom properties</a>.</em>
    </p>
  {% endif %}

  {# CSS Parts #}
  {% if component.cssParts.length %}
    <h2>CSS Parts</h2>

    <table>
      <thead>
        <tr>
          <th class="table-name">Name</th>
          <th class="table-description">Description</th>
        </tr>
      </thead>
      <tbody>
        {% for cssPart in component.cssParts %}
          <tr>
            <td class="nowrap">
              <code>{{ cssPart.name }}</code>
            </td>
            <td>{{ cssPart.description | markdownInline | safe }}</td>
          </tr>
        {% endfor %}
      </tbody>
    </table>

    <p>
      <em>Learn more about <a href="{{ rootUrl('/getting-started/customizing/#css-parts') }}">customizing CSS parts</a>.</em>
    </p>
  {% endif %}

  {# Animations #}
  {% if component.animations.length %}
    <h2>Animations</h2>

    <table>
      <thead>
        <tr>
          <th class="table-name">Name</th>
          <th class="table-description">Description</th>
        </tr>
      </thead>
      <tbody>
        {% for animation in component.animations %}
          <tr>
            <td class="nowrap">
              <code>{{ animation.name }}</code>
            </td>
            <td>{{ animation.description | markdownInline | safe }}</td>
          </tr>
        {% endfor %}
      </tbody>
    </table>

    <p>
      <em>Learn more about <a href="{{ rootUrl('/getting-started/customizing#animations') }}">customizing animations</a>.</em>
    </p>
  {% endif %}

  {# Dependencies #}
  {% if component.dependencies.length %}
    <h2>Dependencies</h2>

    <p>This component automatically imports the following dependencies.</p>

    <ul>
      {% for dependency in component.dependencies %}
        <li>
          <code>&lt;{{ dependency }}&gt;</code>
        </li>
      {% endfor %}
    </ul>
  {% endif %}
{% endblock %}