markawesome 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 561615ddddb39ccde6417037237c2bc490d2ded75aba4b36faf77e1db0eac1cc
-  data.tar.gz: 10ce10fcf7a740754303363579558de85881b4a9e101c73525c7d6ce3ca674e4
+  metadata.gz: afd9d40552aa4f47c46ce12a72e4340075e9049a0d374dabbd894d6b4e9c0771
+  data.tar.gz: bf63ff67375e59593d352c35b9e6852fd4f436a4005eba52bdf695b54d734f11
 SHA512:
-  metadata.gz: 48b713e5d9b0cd1f182ce321923d02c59c85132c42b75ef2f58088dc5ed433101dac9049ea76abd5858f8f03779c7f56a25a7e2a2e21d484839f19bd8fd038f1
-  data.tar.gz: 034dda0ddfc5ca7c24d0107e10632dae1312d122170f65608a3b0bc224b3fe34289b829d68c306da39af08b0e62f16e963d92ad9c92d125ca91bebac06e321e9
+  metadata.gz: eeb2dffdb406f0eeb414cedfe834a616540956dddf5854c972b9743088e62b9d92054a4a1db2be1dc68817b5b81bec1ef7f0b30a0055a5508c6641710b8dc5f1
+  data.tar.gz: c76afeb5d61c70cab00f10e8a3a0d9b2f825bf04b5c4e5f46915506092fb826c9f1e4cb49061da3c29437404c2c0d2188eaf38d634704a56f6398a3410438770

data/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.14.0] - 2026-06-24
+
+### Added
+
+- New `AccordionTransformer` producing Web Awesome `<wa-accordion>` / `<wa-accordion-item>` — a multi-section collapsible container for FAQs, docs sections, and "show more" content (the grouped, mutually-exclusive-capable sibling of `details`). The `/` delimiter is the container/item marker: container fence `//////` (6×), item fence `///` (3×) with an explicit `///` close, mirroring tabs (`++++++`/`+++`). An alternative `:::wa-accordion … :::` form is also accepted.
+  - **Container line** (bare tokens, order-independent, rightmost-wins): `appearance` (`outlined` default, `filled`, `filled-outlined`, `plain`), `mode` (`multiple`, `single`, `single-collapsible`), `icon-placement` (`start`, `end`), and a value-form `heading:N` → `heading-level="N"` where `N` is `1`–`6` or `none` (out-of-range values fall back to omitting the attribute). `appearance` is always emitted (defaulting to `outlined`); `mode`, `icon-placement`, and `heading-level` are emitted only when specified.
+  - **Item header** (`/// [expanded] [disabled] [icon:name] Label`): leading `expanded`/`disabled` flags become the matching boolean attributes; `icon:name` becomes a `<wa-icon slot="icon" name="…">` first child; the remaining text becomes the HTML-escaped `label`. Item bodies are full markdown and may contain other components.
+  - **Plain-markdown degradation** (`render_as_markdown`, used for `.md` endpoints / llms.txt): each item degrades to a `### Label` heading followed by its body, mirroring tabs.
+- `wa-accordion` is **experimental** in Web Awesome (added in 3.7), but `expanded`, `disabled`, and the `mode`/`appearance`/`icon-placement`/`heading-level` attributes are all declarative and static-site-safe — no JavaScript required. The interactive `expandAll()`/`collapseAll()` controls and rich/HTML `label` slot are out of scope for v1; item labels are plain text. The `--wa-accordion-divider-color` custom property removed in WA 3.9.0 is intentionally not exposed.
+
+## [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

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/plain_markdown_renderer.rb

@@ -24,8 +24,8 @@ module Markawesome
       # plugin during boot to override the default rendering for a single
       # component without forking the gem.
       #
-      # @param component [Symbol] one of :callout, :badge, :button, :card,
-      #   :carousel, :comparison, :copy_button, :details, :dialog, :icon,
+      # @param component [Symbol] one of :accordion, :callout, :badge, :button,
+      #   :card, :carousel, :comparison, :copy_button, :details, :dialog, :icon,
       #   :image_dialog, :layout, :popover, :tabs, :tag.
       # @yield [content, options] Proc that receives the full source content
       #   and the renderer options; returns the content with that component
@@ -58,6 +58,7 @@ module Markawesome
       icon
       tag
       tabs
+      accordion
     ].freeze
 
     TRANSFORMER_MAP = {
@@ -75,7 +76,8 @@ module Markawesome
       dialog: DialogTransformer,
       icon: IconTransformer,
       tag: TagTransformer,
-      tabs: TabsTransformer
+      tabs: TabsTransformer,
+      accordion: AccordionTransformer
     }.freeze
 
     def self.process(content, options = {})

data/lib/markawesome/transformer.rb

@@ -32,6 +32,10 @@ module Markawesome
       content = TagTransformer.transform(content)
       content = TabsTransformer.transform(content)
 
+      # Accordion runs last so item bodies may contain other already-transformed
+      # components (same reason tabs runs near the end).
+      content = AccordionTransformer.transform(content)
+
       CodeBlockProtector.restore(content, tokens)
     end
   end

data/lib/markawesome/transformers/accordion_transformer.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative 'base_transformer'
+require_relative '../attribute_parser'
+require_relative '../icon_slot_parser'
+
+module Markawesome
+  # Transforms accordion syntax into wa-accordion / wa-accordion-item elements
+  # Primary syntax:
+  #   //////appearance? mode? icon-placement? heading:N?
+  #   /// [expanded] [disabled] [icon:name] Label text
+  #   item body markdown
+  #   ///
+  #   //////
+  # Alternative syntax: :::wa-accordion ...same items... :::
+  #
+  # Container attributes (bare, order-independent, rightmost-wins):
+  #   - appearance: outlined (default), filled, filled-outlined, plain
+  #   - mode: multiple (default), single, single-collapsible
+  #   - icon-placement: start, end (default emitted only when given)
+  #   - heading:N -> heading-level="N" where N is 1-6 or "none"
+  # Item tokens (leading flags, then the rest of the line is the label):
+  #   - expanded -> expanded; disabled -> disabled
+  #   - icon:name -> <wa-icon slot="icon" name="name"></wa-icon> as first child
+  #
+  # wa-accordion is experimental in Web Awesome (added 3.7). expanded/disabled
+  # and the mode/appearance/icon-placement attributes are all static-safe.
+  class AccordionTransformer < BaseTransformer
+    CONTAINER_ATTRIBUTES = {
+      appearance: %w[outlined filled filled-outlined plain],
+      mode: %w[multiple single single-collapsible],
+      icon_placement: %w[start end]
+    }.freeze
+
+    ICON_SLOTS = {
+      default: 'icon',
+      slots: %w[icon],
+      slot_map: { 'icon' => 'icon' }
+    }.freeze
+
+    ITEM_FLAGS = %w[expanded disabled].freeze
+
+    PRIMARY_REGEX = %r{^/{6}([^\n]*)\n((?:/{3} [^\n]+\n.*?\n/{3}\n?)+)/{6}}m
+    ALTERNATIVE_REGEX = %r{^:::wa-accordion\s*([^\n]*)\n((?:/{3} [^\n]+\n.*?\n/{3}\n?)+):::}m
+    ITEM_REGEX = %r{^/{3} ([^\n]+)\n(.*?)\n/{3}}m
+
+    def self.transform(content)
+      transform_proc = proc do |params_string, items_block, _third|
+        attributes = AttributeParser.parse(params_string.to_s.strip, CONTAINER_ATTRIBUTES)
+        heading_level = extract_heading_level(params_string)
+
+        attr_parts = ["appearance=\"#{normalize_appearance(attributes[:appearance])}\""]
+        attr_parts << "mode=\"#{attributes[:mode]}\"" if attributes[:mode]
+        attr_parts << "icon-placement=\"#{attributes[:icon_placement]}\"" if attributes[:icon_placement]
+        attr_parts << "heading-level=\"#{heading_level}\"" if heading_level
+
+        "<wa-accordion #{attr_parts.join(' ')}>#{build_items(items_block)}</wa-accordion>"
+      end
+
+      patterns = dual_syntax_patterns(PRIMARY_REGEX, ALTERNATIVE_REGEX, transform_proc)
+      apply_multiple_patterns(content, patterns)
+    end
+
+    def self.render_as_markdown(content, _options = {})
+      transform_proc = proc do |_params_string, items_block, _third|
+        items_block.scan(ITEM_REGEX).map do |header, body|
+          _flags, label = parse_item_flags_and_label(IconSlotParser.parse(header, ICON_SLOTS)[:remaining])
+          "### #{label}\n\n#{body.strip}"
+        end.join("\n\n")
+      end
+
+      patterns = dual_syntax_patterns(PRIMARY_REGEX, ALTERNATIVE_REGEX, transform_proc)
+      apply_multiple_patterns(content, patterns)
+    end
+
+    class << self
+      private
+
+      def build_items(items_block)
+        items_block.scan(ITEM_REGEX).map do |header, body|
+          icon_result = IconSlotParser.parse(header, ICON_SLOTS)
+          flags, label = parse_item_flags_and_label(icon_result[:remaining])
+
+          item_attrs = ["label=\"#{escape_html(label)}\""]
+          item_attrs << 'expanded' if flags.include?('expanded')
+          item_attrs << 'disabled' if flags.include?('disabled')
+
+          icon_html = IconSlotParser.to_html(icon_result[:icons], ICON_SLOTS[:slot_map])
+          body_html = markdown_to_html(body.strip)
+
+          "<wa-accordion-item #{item_attrs.join(' ')}>#{icon_html}#{body_html}</wa-accordion-item>"
+        end.join
+      end
+
+      # Consume leading expanded/disabled tokens; the remainder is the label.
+      def parse_item_flags_and_label(remaining)
+        tokens = remaining.to_s.strip.split(/\s+/)
+        flags = []
+        flags << tokens.shift while tokens.any? && ITEM_FLAGS.include?(tokens.first)
+        [flags, tokens.join(' ')]
+      end
+
+      def extract_heading_level(params_string)
+        return nil if params_string.nil? || params_string.strip.empty?
+
+        token = params_string.strip.split(/\s+/).find { |t| t.start_with?('heading:') }
+        return nil unless token
+
+        value = token.sub(/^heading:/, '')
+        return value if value == 'none' || value.match?(/\A[1-6]\z/)
+
+        nil
+      end
+
+      def normalize_appearance(appearance_param)
+        case appearance_param
+        when 'filled'
+          'filled'
+        when 'filled-outlined'
+          'filled-outlined'
+        when 'plain'
+          'plain'
+        else
+          'outlined'
+        end
+      end
+
+      def escape_html(text)
+        text.to_s
+            .gsub('&', '&amp;')
+            .gsub('<', '&lt;')
+            .gsub('>', '&gt;')
+            .gsub('"', '&quot;')
+            .gsub("'", '&#39;')
+      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/transformers.rb

@@ -4,6 +4,7 @@
 # This file makes it easy to require all transformers at once
 
 require_relative 'transformers/base_transformer'
+require_relative 'transformers/accordion_transformer'
 require_relative 'transformers/badge_transformer'
 require_relative 'transformers/button_transformer'
 require_relative 'transformers/callout_transformer'

data/lib/markawesome/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markawesome
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Janne Waren
@@ -79,10 +79,12 @@ 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
 - lib/markawesome/transformers.rb
+- lib/markawesome/transformers/accordion_transformer.rb
 - lib/markawesome/transformers/badge_transformer.rb
 - lib/markawesome/transformers/base_transformer.rb
 - lib/markawesome/transformers/button_transformer.rb