markawesome 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ff219b440ba6edf0b45bffa865e4ff4bf8516d5f3c214aa8bdff33c41133565
-  data.tar.gz: b22df3f6875fcae4e9a98f0b86e384c2841ad14942f85832f70c5521c6a4058e
+  metadata.gz: dde7893cda313985c975f86e5521db8a3f56268ebf8d0df5b304719e8db5b73b
+  data.tar.gz: 73e885ac60dfbe2b8734d44aa135fb345440c977390d8d3d7a22cc577328eadf
 SHA512:
-  metadata.gz: 84a1023e4464efd824f30f1612ede362a7469af9e47a3484b645dd921cad2c24aeda58f51ca4b00727ad5d327015e1cb68ed7892df00c97fdacee42ad3809c9a
-  data.tar.gz: 883d44d1df8777343f2ff998ef95f8a832a6333066eca8d9e782c6c9026884c1e56f9459ecbd40b30f1f6be716bf22773c225eb0384867b6ad8d2fe1bef5c8a4
+  metadata.gz: 1e4cab6567c4ef43c87472be12ec93d506fc7b4d47a9a7588aa4c99e28d58761e6705bbf56b0ed5efac032dff0960fa6af9d661042950aba516f76d8ee4881ac
+  data.tar.gz: 49df9a0d39e97272b3acd05b52980b86ace61eb00dd6be7e92d91dc90ec0c688b550e5b21e7999303c8f3dc6dd8188cac8d791c1fe5ad07baaac0ce10b23fd5c

data/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.13.0] - 2026-06-20
+
+### Added
+
+- The standalone `:::wa-icon` block now accepts `family` (`classic`, `sharp`, `duotone`, `sharp-duotone`, `brands`), `variant` (`thin`, `light`, `regular`, `solid`), and `animation` (`beat`, `fade`, `beat-fade`, `bounce`, `flip`, `shake`, `spin`, `spin-pulse`, `spin-reverse`) as bare enumerated tokens after the icon name (order-independent, rightmost-wins, unknown tokens dropped — same parsing as button `variant`/`size`). The block body becomes the icon's accessible `label` (stripped, whitespace-collapsed, HTML-escaped); an empty body emits no `label`, leaving the icon presentational per Web Awesome's default. Emit order is deterministic: `name family variant animation label`.
+- `CalloutTransformer` callouts can now override their icon's `family`/`variant`/`animation` using the same bare tokens on the callout line (e.g. `:::warning shake`). The historical `variant="solid"` default is preserved when no icon-variant token is given, so existing callouts render byte-identically. Works alongside the existing `icon:name` override.
+- New shared `Markawesome::IconAttributes` module — single source of truth for the `<wa-icon>` family/variant/animation vocabulary (verified against Web Awesome 3.x), consumed by both `IconTransformer` and `CalloutTransformer`.
+
+The inline `$$$name` form stays **name-only** (mid-prose, semantically decorative). Embedded `icon:slot:name` icons in button/tag/details are unchanged. Note: `family`/`variant` produce a *visible* weight/family change only with a Font Awesome Pro kit; the attributes are always emitted to the DOM regardless of kit tier (validated against the examples site's WA 3.8.0 kit, where `animation` and `label` are fully functional and the weight/family attributes reach the element without a visible glyph swap on the free tier).
+
+## [0.12.0] - 2026-06-19
+
+### Added
+
+- `ButtonTransformer` link-form buttons now accept `target` (`_blank`, `_self`, `_parent`, `_top`) and a boolean `download` flag. When `target="_blank"` is set, `rel="noopener noreferrer"` is emitted automatically to guard against reverse tabnabbing. These attributes are emitted **only** on link-form buttons (markup wrapping a markdown link, e.g. `%%%brand _blank\n[Text](url)\n%%%`); written on a regular (non-link) button they are parsed but dropped, consistent with the existing unrecognized-token behavior. They are also absent from the plain-markdown degradation path (`render_as_markdown`), since a plain `[text](url)` can't express them. A `download:filename` value form is a possible future enhancement.
+
 ## [0.11.0] - 2026-06-16
 
 Aligns generated markup with Web Awesome 3.8.0 (latest). See `ROADMAP.md` for the remaining enhancement backlog from the same audit.

data/lib/markawesome/icon_attributes.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Markawesome
+  # Shared <wa-icon> attribute vocabulary (family/variant/animation) and emission helper.
+  # Values verified against Web Awesome 3.x. Adding a value later is a one-line change.
+  module IconAttributes
+    SCHEMA = {
+      family: %w[classic sharp duotone sharp-duotone brands],
+      variant: %w[thin light regular solid],
+      animation: %w[beat fade beat-fade bounce flip shake spin spin-pulse spin-reverse]
+    }.freeze
+
+    # Returns ordered ['family="…"', 'variant="…"', 'animation="…"'] for present keys.
+    def self.pairs(attributes)
+      %i[family variant animation].filter_map do |key|
+        "#{key}=\"#{attributes[key]}\"" if attributes[key]
+      end
+    end
+  end
+end

data/lib/markawesome/transformers/button_transformer.rb

@@ -18,6 +18,11 @@ module Markawesome
   # - loading: loading (loading state)
   # - disabled: disabled (disabled state)
   #
+  # Link-form only (emitted only when content is a markdown link):
+  # - target: _blank, _self, _parent, _top (target="_blank" also emits
+  #   rel="noopener noreferrer" automatically)
+  # - download: download (bare download attribute)
+  #
   # Link buttons: %%%brand\n[Text](url)\n%%%
   # Regular buttons: %%%brand large pill\nText\n%%%
   class ButtonTransformer < BaseTransformer
@@ -29,7 +34,9 @@ module Markawesome
       pill: %w[pill],
       caret: %w[caret],
       loading: %w[loading],
-      disabled: %w[disabled]
+      disabled: %w[disabled],
+      target: %w[_blank _self _parent _top],
+      download: %w[download]
     }.freeze
 
     ICON_SLOTS = { default: 'start', slots: %w[start end] }.freeze
@@ -105,7 +112,9 @@ module Markawesome
           # Fix whitespace issues like in badges
           button_html = button_html.gsub(%r{(</\w+>)\s+}, '\1&nbsp;')
 
-          "<wa-button#{attrs_string} href=\"#{link_url}\">#{icon_html}#{button_html}</wa-button>"
+          link_attrs_string = link_pass_through_attrs(attributes)
+
+          "<wa-button#{attrs_string} href=\"#{link_url}\"#{link_attrs_string}>#{icon_html}#{button_html}</wa-button>"
         else
           # It's a regular button
           button_html = markdown_to_html(content).strip
@@ -117,6 +126,17 @@ module Markawesome
           "<wa-button#{attrs_string}>#{icon_html}#{button_html}</wa-button>"
         end
       end
+
+      # Plain anchor pass-throughs, meaningful only on link-form buttons.
+      # Auto-emit rel="noopener noreferrer" with target="_blank" to guard
+      # against reverse tabnabbing.
+      def link_pass_through_attrs(attributes)
+        link_attrs = []
+        link_attrs << "target=\"#{attributes[:target]}\"" if attributes[:target]
+        link_attrs << 'rel="noopener noreferrer"' if attributes[:target] == '_blank'
+        link_attrs << 'download' if attributes[:download]
+        link_attrs.empty? ? '' : " #{link_attrs.join(' ')}"
+      end
     end
   end
 end

data/lib/markawesome/transformers/callout_transformer.rb

@@ -3,6 +3,7 @@
 require_relative 'base_transformer'
 require_relative '../attribute_parser'
 require_relative '../icon_slot_parser'
+require_relative '../icon_attributes'
 
 module Markawesome
   # Transforms callout syntax into wa-callout elements
@@ -28,20 +29,20 @@ module Markawesome
       transform_proc = proc do |variant, extra_params, inner_content|
         actual_variant = VARIANT_ALIASES.fetch(variant, variant)
 
-        # Parse icon tokens first, then pass remaining to AttributeParser
+        # Parse icon tokens first, then pass remaining to AttributeParser.
+        # CALLOUT_ATTRIBUTES and IconAttributes::SCHEMA namespaces are disjoint, so the
+        # same remaining-token string can be parsed against both independently.
         icon_result = IconSlotParser.parse(extra_params, ICON_SLOTS)
         extra_attrs = AttributeParser.parse(icon_result[:remaining], CALLOUT_ATTRIBUTES)
+        icon_attrs  = AttributeParser.parse(icon_result[:remaining], IconAttributes::SCHEMA)
+        icon_attrs[:variant] ||= 'solid' # preserve historical default
 
         attr_parts = ["variant=\"#{actual_variant}\""]
         attr_parts << "appearance=\"#{extra_attrs[:appearance]}\"" if extra_attrs[:appearance]
         attr_parts << "size=\"#{extra_attrs[:size]}\"" if extra_attrs[:size]
 
-        # Use custom icon if provided, otherwise use default variant icon
-        icon_html = if icon_result[:icons]['icon']
-                      "<wa-icon slot=\"icon\" name=\"#{icon_result[:icons]['icon']}\" variant=\"solid\"></wa-icon>"
-                    else
-                      icon_for(actual_variant)
-                    end
+        icon_name = icon_result[:icons]['icon'] || icon_name_for(actual_variant)
+        icon_html = callout_icon_html(icon_name, icon_attrs)
         html_content = "#{icon_html}#{markdown_to_html(inner_content)}"
 
         "<wa-callout #{attr_parts.join(' ')}>#{html_content}</wa-callout>"
@@ -79,11 +80,16 @@ module Markawesome
     class << self
       private
 
-      def icon_for(variant)
+      def icon_name_for(variant)
         config = Markawesome.configuration
         icons = config&.callout_icons || default_icons
-        icon_name = icons[variant.to_sym]
-        "<wa-icon slot=\"icon\" name=\"#{icon_name}\" variant=\"solid\"></wa-icon>"
+        icons[variant.to_sym]
+      end
+
+      def callout_icon_html(name, attributes)
+        parts = ['slot="icon"', "name=\"#{name}\""]
+        parts.concat(IconAttributes.pairs(attributes))
+        "<wa-icon #{parts.join(' ')}></wa-icon>"
       end
 
       def default_icons

data/lib/markawesome/transformers/icon_transformer.rb

@@ -1,17 +1,25 @@
 # frozen_string_literal: true
 
 require_relative 'base_transformer'
+require_relative '../attribute_parser'
+require_relative '../icon_attributes'
 
 module Markawesome
   # Transforms icon syntax into wa-icon elements
-  # Primary syntax: $$$icon-name
-  # Alternative syntax: :::wa-icon icon-name
+  # Primary syntax: $$$icon-name (name only, decorative)
+  # Alternative syntax: :::wa-icon icon-name [family] [variant] [animation]\n[label]\n:::
   #
   # Examples:
   # $$$settings -> <wa-icon name="settings"></wa-icon>
   # $$$home -> <wa-icon name="home"></wa-icon>
   # $$$user-circle -> <wa-icon name="user-circle"></wa-icon>
+  # :::wa-icon star spin\n::: -> <wa-icon name="star" animation="spin"></wa-icon>
+  # :::wa-icon heart solid\nFavorite\n::: ->
+  #   <wa-icon name="heart" variant="solid" label="Favorite"></wa-icon>
   class IconTransformer < BaseTransformer
+    # First-line params + optional multi-line body. The closer is anchored to a line
+    # start; the opener is intentionally not anchored so it still matches mid-prose.
+    ALTERNATIVE_REGEX = /:::wa-icon[ \t]+([^\n]*?)[ \t]*\n(.*?)^:::/m
     def self.transform(content)
       # Protect code blocks first
       protected_content, code_blocks = protect_code_blocks(content)
@@ -25,9 +33,16 @@ module Markawesome
       end
 
       # Apply alternative syntax transformation
-      result = result.gsub(/:::wa-icon\s+([a-zA-Z0-9\-_]+)\s*\n:::/m) do
-        icon_name = ::Regexp.last_match(1)
-        build_icon_html(icon_name)
+      result = result.gsub(ALTERNATIVE_REGEX) do
+        first_line = ::Regexp.last_match(1)
+        raw_body   = ::Regexp.last_match(2)
+
+        tokens     = first_line.strip.split(/\s+/)
+        icon_name  = tokens.shift # first token is always the name
+        attributes = AttributeParser.parse(tokens.join(' '), IconAttributes::SCHEMA)
+        label      = normalize_label(raw_body)
+
+        build_icon_html(icon_name, attributes, label)
       end
 
       # Restore code blocks
@@ -39,7 +54,12 @@ module Markawesome
 
       # Drop primary-syntax icons entirely.
       result = protected_content.gsub(/\$\$\$([a-zA-Z0-9\-_]+)(?![a-zA-Z0-9\-_]|\s+name\b)/, '')
-      result = result.gsub(/:::wa-icon\s+([a-zA-Z0-9\-_]+)\s*\n:::/m, '')
+
+      # A labeled block degrades to its label text (collapsed, not HTML-escaped — it
+      # re-enters a markdown stream); an unlabeled block degrades to ''.
+      result = result.gsub(ALTERNATIVE_REGEX) do
+        ::Regexp.last_match(2).to_s.strip.gsub(/\s+/, ' ')
+      end
 
       restore_code_blocks(result, code_blocks)
     end
@@ -47,12 +67,24 @@ module Markawesome
     class << self
       private
 
-      def build_icon_html(icon_name)
-        # Clean and validate icon name
-        clean_name = icon_name.strip
+      def build_icon_html(icon_name, attributes = {}, label = nil)
+        parts = ["name=\"#{icon_name.strip}\""]
+        parts.concat(IconAttributes.pairs(attributes))
+        parts << "label=\"#{label}\"" if label && !label.empty?
+        "<wa-icon #{parts.join(' ')}></wa-icon>"
+      end
+
+      # Label is an attribute VALUE, not markup: strip, collapse whitespace, HTML-escape.
+      # Deliberately NOT run through markdown_to_html (unlike button/callout bodies).
+      def normalize_label(raw_body)
+        text = raw_body.to_s.strip.gsub(/\s+/, ' ')
+        text.empty? ? nil : escape_html(text)
+      end
 
-        # Return the wa-icon element
-        "<wa-icon name=\"#{clean_name}\"></wa-icon>"
+      # Same escape set as Dialog/Popover transformers.
+      def escape_html(text)
+        text.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+            .gsub('"', '&quot;').gsub("'", '&#39;')
       end
 
       def protect_code_blocks(content)

data/lib/markawesome/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markawesome
-  VERSION = '0.11.0'
+  VERSION = '0.13.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markawesome
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Janne Waren
@@ -79,6 +79,7 @@ files:
 - lib/markawesome.rb
 - lib/markawesome/attribute_parser.rb
 - lib/markawesome/code_block_protector.rb
+- lib/markawesome/icon_attributes.rb
 - lib/markawesome/icon_slot_parser.rb
 - lib/markawesome/plain_markdown_renderer.rb
 - lib/markawesome/transformer.rb