{#
  @file Adding icons to our website, without loading an icon library.

  Available variables:
  - icon_name: The name of the icon svg file to load. (without the .svg extension)
  - icon_path: (optional) The path to the icon svg file. If not provided, it
    defaults to 'includes/icons' within the theme specified in the 'theme'
    variable.
    You can provide a full path starting with '@theme_name/' to load from
    another theme. For example: '@localgov_base/includes/icons'.
  - theme: (optional) The theme to load the icon from if 'icon_path' is not provided.
    Defaults to 'localgov_base'.
  - icon_classes: (optional) A string of additional classes to add to the icon
    wrapper element.
  - icon_wrapper_element: (optional) The HTML element to use to wrap the icon.
    Defaults to 'div'.
  - decoration: (optional) If set to 'true', the icon will have aria-hidden="true"
    added to the wrapper element. Defaults to 'true'. This is useful for decorative
    icons that do not add any meaning to the content.

  Examples of usage:

  Basic example usage, loading from LocalGov Base theme:
  {% include 'localgov_base:icon' with {
      icon_name: 'facebook',
    }
  %}

  Basic example, adding custom icon and span as element
  {% include 'localgov_base:icon' with {
    icon_name: 'twitter',
    icon_classes: 'lgd-icon--large',
    icon_wrapper_element: 'span',
  } %}

  Advanced example, loading from LocalGov Base theme:
  {% include 'localgov_base:icon' with {
    icon_name: 'whatsapp',
    icon_path: '@localgov_base/templates/includes/icons/font-awesome/brands',
    icon_classes: 'my-custom-icon-class',
    icon_wrapper_element: 'span',
  } %}


  Advanced example, loading from custom theme:
  {% include 'localgov_base:icon' with {
    icon_name: 'custom-icon',
    theme: '@my_custom_theme',
    icon_path: '@my_custom_theme/icons',
    icon_classes: 'my-custom-icon-class',
    icon_wrapper_element: 'span',
  } %}

  The only option above that is necessary is the 'icon_name' one. The others
  have sensible defaults. The 'theme' one is handy if you want to add custom
  icons to your own theme that will not be needed to share with LGD core.

  Icons default to a width of 1rem. To make them larger or smaller, just
  add the classes to the icon_classes variable. Note: this is a string, not
  an array. If you want to add more than one class, just include it in your
  string like so: icon_classes: 'class-1 class-2 class-3'.

  The widths we have available out of the box are:

    - lgd-icon--small
    - lgd-icon--smaller
    - lgd-icon--smallest
    - lgd-icon--large
    - lgd-icon--larger
    - lgd-icon--largest

  Each of these sizes corresponds to one of localgov_base's var(--spacing-*)
  sizes.
#}

{% set theme = theme|default('localgov_base') %}
{% set icon_wrapper_element = icon_wrapper_element|default('div') %}

{% set attributes = create_attribute()
  .setAttribute('aria-hidden', decoration|default('true'))
  .addClass('lgd-icon')
  .addClass(icon_classes)
%}

<{{ icon_wrapper_element }}{{ attributes }}>
  {%- set icon_path -%} {% if icon_path|first != '@' %}@{{ theme }}/{% endif %}{{ icon_path|default('includes/icons') }}/{{ icon_name }}.svg {%- endset -%} {% include icon_path %}
</{{ icon_wrapper_element }}>
