markawesome 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adad1d3e9850c4d1f82b4cbe73eb56ac9c82c413e66ea0adb1291794a3a9a25a
-  data.tar.gz: 07b7741a6e96f7031d38d1e10d6ca6a0314d5edd05341222f1f7d7964904d1c4
+  metadata.gz: c1a813451ca32ebe286489c510fd9ebc0f161877d6e20bdc50c390c8e54669c8
+  data.tar.gz: fe1f091910a15ebf1f825769266fdaa1ff776e1ceace7a041e0fe71370b42817
 SHA512:
-  metadata.gz: b4af697c90bf1d4a0d7d10de6fac07f784319b01d45b58fdcfb190475e97f4e5164b7b5fe7e7fd7475aece2651c78cd31181059cb7a8c1ec01ea33c05a154f11
-  data.tar.gz: ecca3f31fb0b27db1572cea1c82a2989434948699fe2125f8020f0cdd04e39f03a7d2426fbacfff8d65eba0252e6cdf0056a05d93ff7587ae85d39652e076553
+  metadata.gz: 1ddf1bc53111ca053bd5fe82040ee9387783dd95f0892658697a2f38f0b7a11ebd8fa1517df4e990fbda8aaa90f465f27bb1a6f46d673b8f6fc31a24acab5070
+  data.tar.gz: 83ac02b6ca5cb7744579661c068511c53666bf4ec8b550a6170050ab04f8911c053db46f1b87122b91aec2024b3a564f4e21d1a34e49189fdbb0e5152df99e49

data/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.5.0] - 2026-02-10
+
+### Added
+
+- **LayoutTransformer**: New `::::` (quadruple colon) syntax for wrapping content in Web Awesome CSS layout containers
+  - Supports 6 layout types: `grid`, `stack`, `cluster`, `split`, `flank`, `frame`
+  - Common attributes: `gap:SIZE`, `align:VALUE`, `justify:VALUE` for all layouts
+  - Grid-specific: `min:CSS_VALUE` for custom minimum column size (`--min-column-size`)
+  - Split-specific: `row` and `column` direction modifiers
+  - Flank-specific: `start`/`end` position modifiers, `size:CSS_VALUE`, `content:PCT`
+  - Frame-specific: `landscape`/`portrait`/`square` aspect ratios, `radius:SIZE`
+  - Dual syntax: both `::::grid` and `::::wa-grid` work identically
+  - CSS value sanitization for user-provided values (strips quotes, angle brackets, semicolons)
+  - Inner content is not markdown-converted, allowing component `:::` syntax to be processed by subsequent transformers
+  - Runs first in the pipeline so layout containers wrap around component output
+
+## [0.4.0] - 2026-02-09
+
+### Added
+
+- **IconSlotParser**: New reusable parser for `icon:name` and `icon:slot:name` syntax across components
+- **ButtonTransformer**: Icon support with `icon:name` (start slot) and `icon:end:name` for start/end icon slots
+- **CalloutTransformer**: Custom icon override with `icon:name` to replace default variant icons
+- **DetailsTransformer**: Custom expand/collapse icons with `icon:expand:name` and `icon:collapse:name`
+- **TagTransformer**: Inline content icons with `icon:name` for both block and inline tag syntax
+
+### Design
+
+- IconSlotParser composes with AttributeParser — strips icon tokens first, passes remaining params for attribute parsing
+- Supports slot name mapping (e.g. `expand` → `expand-icon`) for Web Awesome's HTML slot conventions
+- Rightmost-wins semantics consistent with AttributeParser
+- Content slot mode omits `slot=` attribute for inline icon usage (tags)
+
 ## [0.3.0] - 2026-02-08
 
 ### Added

data/lib/markawesome/icon_slot_parser.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Markawesome
+  # Parses icon:... tokens from parameter strings for Web Awesome component icon slots
+  # Supports default slot mapping, explicit slot names, and slot name remapping
+  #
+  # Examples:
+  #   "icon:gear"           → default slot gets "gear"
+  #   "icon:end:arrow-right" → "end" slot gets "arrow-right"
+  #   "success icon:gear large" → icons: { 'start' => 'gear' }, remaining: "success large"
+  class IconSlotParser
+    # Parse icon tokens from a parameter string
+    # @param params_string [String] Space-separated parameter string potentially containing icon:... tokens
+    # @param slot_config [Hash] Configuration for icon slots
+    #   :default [String, nil] Default slot name for icon:name tokens (nil = no default)
+    #   :slots [Array<String>] Allowed slot names
+    #   :slot_map [Hash] Optional mapping from short slot names to HTML slot attributes
+    # @return [Hash] { icons: Hash, remaining: String }
+    def self.parse(params_string, slot_config)
+      return { icons: {}, remaining: '' } if params_string.nil? || params_string.strip.empty?
+
+      icons = {}
+      remaining_tokens = []
+      tokens = params_string.strip.split(/\s+/)
+
+      tokens.each do |token|
+        if token.start_with?('icon:')
+          parts = token.split(':', 3) # ["icon", slot_or_name, maybe_name]
+
+          if parts.length == 3
+            # Explicit slot: icon:slot:name
+            slot = parts[1]
+            name = parts[2]
+            icons[slot] = name if slot_config[:slots]&.include?(slot)
+          elsif parts.length == 2 && slot_config[:default]
+            # Default slot: icon:name
+            name = parts[1]
+            icons[slot_config[:default]] = name unless name.empty?
+          end
+        else
+          remaining_tokens << token
+        end
+      end
+
+      { icons: icons, remaining: remaining_tokens.join(' ') }
+    end
+
+    # Generate <wa-icon> HTML elements for parsed icons
+    # @param icons_hash [Hash] Slot name => icon name pairs
+    # @param slot_map [Hash, nil] Optional mapping from parsed slot names to HTML slot attributes
+    # @return [String] HTML string with <wa-icon> elements
+    def self.to_html(icons_hash, slot_map = nil)
+      icons_hash.map do |slot, name|
+        html_slot = slot_map ? (slot_map[slot] || slot) : slot
+        if html_slot == 'content'
+          "<wa-icon name=\"#{name}\"></wa-icon>"
+        else
+          "<wa-icon slot=\"#{html_slot}\" name=\"#{name}\"></wa-icon>"
+        end
+      end.join
+    end
+  end
+end

data/lib/markawesome/transformer.rb

@@ -7,6 +7,7 @@ module Markawesome
   # Main transformer that orchestrates all component transformers
   class Transformer
     def self.process(content, options = {})
+      content = LayoutTransformer.transform(content)
       content = BadgeTransformer.transform(content)
       content = ButtonTransformer.transform(content)
       content = CalloutTransformer.transform(content)

data/lib/markawesome/transformers/button_transformer.rb

@@ -2,6 +2,7 @@
 
 require_relative 'base_transformer'
 require_relative '../attribute_parser'
+require_relative '../icon_slot_parser'
 
 module Markawesome
   # Transforms button syntax into wa-button elements
@@ -31,6 +32,8 @@ module Markawesome
       disabled: %w[disabled]
     }.freeze
 
+    ICON_SLOTS = { default: 'start', slots: %w[start end] }.freeze
+
     def self.transform(content)
       # Define both regex patterns - capture all space-separated parameters
       primary_regex = /^%%%([^\n]*)\n(.*?)\n%%%/m
@@ -40,10 +43,11 @@ module Markawesome
       transform_proc = proc do |params_string, button_content|
         button_content = button_content.strip
 
-        # Parse attributes using AttributeParser
-        attributes = AttributeParser.parse(params_string, BUTTON_ATTRIBUTES)
+        # Parse icon tokens first, then pass remaining to AttributeParser
+        icon_result = IconSlotParser.parse(params_string, ICON_SLOTS)
+        attributes = AttributeParser.parse(icon_result[:remaining], BUTTON_ATTRIBUTES)
 
-        build_button_html(button_content, attributes)
+        build_button_html(button_content, attributes, icon_result[:icons])
       end
 
       # Apply both patterns
@@ -54,7 +58,7 @@ module Markawesome
     class << self
       private
 
-      def build_button_html(content, attributes)
+      def build_button_html(content, attributes, icons = {})
         # Build HTML attributes from parsed attributes
         html_attrs = []
 
@@ -67,6 +71,7 @@ module Markawesome
         html_attrs << 'disabled' if attributes[:disabled]
 
         attrs_string = html_attrs.empty? ? '' : " #{html_attrs.join(' ')}"
+        icon_html = IconSlotParser.to_html(icons)
 
         # Check if content contains a markdown link
         link_match = content.match(/^\[([^\]]+)\]\(([^)]+)\)$/)
@@ -83,7 +88,7 @@ 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}\">#{button_html}</wa-button>"
+          "<wa-button#{attrs_string} href=\"#{link_url}\">#{icon_html}#{button_html}</wa-button>"
         else
           # It's a regular button
           button_html = markdown_to_html(content).strip
@@ -92,7 +97,7 @@ module Markawesome
           # Fix whitespace issues like in badges
           button_html = button_html.gsub(%r{(</\w+>)\s+}, '\1&nbsp;')
 
-          "<wa-button#{attrs_string}>#{button_html}</wa-button>"
+          "<wa-button#{attrs_string}>#{icon_html}#{button_html}</wa-button>"
         end
       end
     end

data/lib/markawesome/transformers/callout_transformer.rb

@@ -2,6 +2,7 @@
 
 require_relative 'base_transformer'
 require_relative '../attribute_parser'
+require_relative '../icon_slot_parser'
 
 module Markawesome
   # Transforms callout syntax into wa-callout elements
@@ -17,6 +18,7 @@ module Markawesome
       appearance: %w[accent filled outlined plain filled-outlined]
     }.freeze
     VARIANT_ALIASES = { 'info' => 'brand' }.freeze
+    ICON_SLOTS = { default: 'icon', slots: %w[icon] }.freeze
 
     def self.transform(content)
       variant_pattern = VARIANTS.join('|')
@@ -25,13 +27,21 @@ module Markawesome
 
       transform_proc = proc do |variant, extra_params, inner_content|
         actual_variant = VARIANT_ALIASES.fetch(variant, variant)
-        extra_attrs = AttributeParser.parse(extra_params, CALLOUT_ATTRIBUTES)
+
+        # Parse icon tokens first, then pass remaining to AttributeParser
+        icon_result = IconSlotParser.parse(extra_params, ICON_SLOTS)
+        extra_attrs = AttributeParser.parse(icon_result[:remaining], CALLOUT_ATTRIBUTES)
 
         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]
 
-        icon_html = icon_for(actual_variant)
+        # 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
         html_content = "#{icon_html}#{markdown_to_html(inner_content)}"
 
         "<wa-callout #{attr_parts.join(' ')}>#{html_content}</wa-callout>"

data/lib/markawesome/transformers/details_transformer.rb

@@ -2,6 +2,7 @@
 
 require_relative 'base_transformer'
 require_relative '../attribute_parser'
+require_relative '../icon_slot_parser'
 
 module Markawesome
   # Transforms summary/details syntax into wa-details elements
@@ -19,6 +20,12 @@ module Markawesome
       open: %w[open]
     }.freeze
 
+    ICON_SLOTS = {
+      default: nil,
+      slots: %w[expand collapse],
+      slot_map: { 'expand' => 'expand-icon', 'collapse' => 'collapse-icon' }
+    }.freeze
+
     def self.transform(content)
       # Define both regex patterns - capture parameter string
       primary_regex = /^\^\^\^?(.*?)\n(.*?)\n^>>>\n(.*?)\n^\^\^\^?/m
@@ -29,11 +36,12 @@ module Markawesome
         summary_content = summary_content.strip
         details_content = details_content.strip
 
-        # Parse parameters using AttributeParser
-        attributes = AttributeParser.parse(params_string, COMPONENT_ATTRIBUTES)
+        # Parse icon tokens first, then pass remaining to AttributeParser and name extraction
+        icon_result = IconSlotParser.parse(params_string, ICON_SLOTS)
+        attributes = AttributeParser.parse(icon_result[:remaining], COMPONENT_ATTRIBUTES)
 
         # Extract name parameter (format: name:value) - special handling
-        name_value = extract_name_value(params_string)
+        name_value = extract_name_value(icon_result[:remaining])
 
         appearance_class = normalize_appearance(attributes[:appearance])
         icon_placement = attributes[:icon_placement] || 'end'
@@ -46,9 +54,11 @@ module Markawesome
         attr_parts << 'open' if attributes[:open]
         attr_parts << "name='#{name_value}'" if name_value
 
+        icon_html = IconSlotParser.to_html(icon_result[:icons], ICON_SLOTS[:slot_map])
+
         "<wa-details #{attr_parts.join(' ')}>" \
           "<span slot='summary'>#{summary_html}</span>" \
-          "#{details_html}</wa-details>"
+          "#{icon_html}#{details_html}</wa-details>"
       end
 
       # Apply both patterns

data/lib/markawesome/transformers/layout_transformer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'base_transformer'
+
+module Markawesome
+  # Transforms layout syntax into CSS layout utility containers
+  # Primary syntax: ::::type params?\ncontent\n::::
+  # Alternative syntax: ::::wa-type params?\ncontent\n::::
+  # Supported types: grid, stack, cluster, split, flank, frame
+  #
+  # Common attributes (all layouts):
+  #   gap:SIZE - wa-gap-{SIZE} class (0, 3xs, 2xs, xs, s, m, l, xl, 2xl, 3xl)
+  #   align:VALUE - wa-align-items-{VALUE} class (start, end, center, stretch, baseline)
+  #   justify:VALUE - wa-justify-content-{VALUE} class (start, end, center, space-between, space-around, space-evenly)
+  #
+  # Grid-specific: min:CSS_VALUE - sets --min-column-size style
+  # Split-specific: row, column modifiers
+  # Flank-specific: start, end modifiers; size:CSS_VALUE, content:PCT
+  # Frame-specific: landscape, portrait, square modifiers; radius:SIZE
+  class LayoutTransformer < BaseTransformer
+    VALID_GAPS = %w[0 3xs 2xs xs s m l xl 2xl 3xl].freeze
+    VALID_ALIGNS = %w[start end center stretch baseline].freeze
+    VALID_JUSTIFIES = %w[start end center space-between space-around space-evenly].freeze
+    VALID_RADII = %w[s m l pill circle square].freeze
+
+    KEYWORD_MODIFIERS = {
+      split: %w[row column],
+      flank: %w[start end],
+      frame: %w[landscape portrait square]
+    }.freeze
+
+    COMMON_KEY_CLASS_MAP = {
+      'gap' => ->(v) { "wa-gap-#{v}" if VALID_GAPS.include?(v) },
+      'align' => ->(v) { "wa-align-items-#{v}" if VALID_ALIGNS.include?(v) },
+      'justify' => ->(v) { "wa-justify-content-#{v}" if VALID_JUSTIFIES.include?(v) }
+    }.freeze
+
+    def self.transform(content)
+      primary_regex = /^::::(grid|stack|cluster|split|flank|frame)[ \t]*([^\n]*)\n(.*?)\n::::/m
+      alternative_regex = /^::::wa-(grid|stack|cluster|split|flank|frame)[ \t]*([^\n]*)\n(.*?)\n::::/m
+
+      transform_proc = proc do |type, params_string, inner_content|
+        classes, styles = build_attributes(type, params_string)
+        build_html(classes, styles, inner_content)
+      end
+
+      patterns = dual_syntax_patterns(primary_regex, alternative_regex, transform_proc)
+      apply_multiple_patterns(content, patterns)
+    end
+
+    class << self
+      private
+
+      def build_attributes(type, params_string)
+        classes = ["wa-#{type}"]
+        styles = []
+
+        return [classes, styles] if params_string.nil? || params_string.strip.empty?
+
+        tokens = params_string.strip.split(/\s+/)
+
+        tokens.each do |token|
+          process_token(type, token, classes, styles)
+        end
+
+        [classes, styles]
+      end
+
+      def process_token(type, token, classes, styles)
+        if token.include?(':')
+          process_key_value(type, token, classes, styles)
+        else
+          process_keyword(type, token, classes)
+        end
+      end
+
+      def process_key_value(type, token, classes, styles)
+        key, value = token.split(':', 2)
+        return if value.nil? || value.empty?
+
+        if COMMON_KEY_CLASS_MAP.key?(key)
+          css_class = COMMON_KEY_CLASS_MAP[key].call(value)
+          classes << css_class if css_class
+        else
+          process_type_specific_key_value(type, key, value, classes, styles)
+        end
+      end
+
+      def process_type_specific_key_value(type, key, value, classes, styles)
+        case key
+        when 'min'
+          styles << "--min-column-size: #{sanitize_css(value)}" if type == 'grid'
+        when 'size'
+          styles << "--flank-size: #{sanitize_css(value)}" if type == 'flank'
+        when 'content'
+          styles << "--content-percentage: #{sanitize_css(value)}" if type == 'flank'
+        when 'radius'
+          classes << "wa-border-radius-#{value}" if type == 'frame' && VALID_RADII.include?(value)
+        end
+      end
+
+      def process_keyword(type, token, classes)
+        modifiers = KEYWORD_MODIFIERS[type.to_sym]
+        return unless modifiers&.include?(token)
+
+        classes[0] = "wa-#{type}:#{token}"
+      end
+
+      def sanitize_css(value)
+        value.gsub(/["'<>;]/, '')
+      end
+
+      def build_html(classes, styles, inner_content)
+        attr_parts = ["class=\"#{classes.join(' ')}\""]
+        attr_parts << "style=\"#{styles.join('; ')}\"" unless styles.empty?
+
+        "<div #{attr_parts.join(' ')}>\n#{inner_content}\n</div>"
+      end
+    end
+  end
+end

data/lib/markawesome/transformers/tag_transformer.rb

@@ -2,6 +2,7 @@
 
 require_relative 'base_transformer'
 require_relative '../attribute_parser'
+require_relative '../icon_slot_parser'
 
 module Markawesome
   # Transforms tag syntax into wa-tag elements
@@ -25,6 +26,8 @@ module Markawesome
       'with-remove': %w[with-remove]
     }.freeze
 
+    ICON_SLOTS = { default: 'content', slots: %w[content] }.freeze
+
     def self.transform(content)
       # Define regex patterns
       # Block syntax (multiline with newlines) - supports both LF and CRLF
@@ -51,10 +54,14 @@ module Markawesome
         params_tokens = []
         content_tokens = []
 
-        # Separate attribute tokens from content tokens
+        # Separate attribute and icon tokens from content tokens
         tokens.each do |token|
           matched = COMPONENT_ATTRIBUTES.any? { |_attr, values| values.include?(token) }
-          matched ? params_tokens << token : content_tokens << token
+          if matched || token.start_with?('icon:')
+            params_tokens << token
+          else
+            content_tokens << token
+          end
         end
 
         # Build params and content strings
@@ -81,8 +88,9 @@ module Markawesome
       private
 
       def build_tag_html(content, params)
-        # Parse attributes using AttributeParser
-        attributes = AttributeParser.parse(params, COMPONENT_ATTRIBUTES)
+        # Parse icon tokens first, then pass remaining to AttributeParser
+        icon_result = IconSlotParser.parse(params, ICON_SLOTS)
+        attributes = AttributeParser.parse(icon_result[:remaining], COMPONENT_ATTRIBUTES)
 
         # Build HTML attributes
         html_attrs = []
@@ -93,13 +101,14 @@ module Markawesome
         html_attrs << 'with-remove' if attributes[:'with-remove']
 
         attrs_string = html_attrs.empty? ? '' : " #{html_attrs.join(' ')}"
+        icon_html = IconSlotParser.to_html(icon_result[:icons])
 
         tag_html = markdown_to_html(content).strip
 
         # Remove paragraph tags if the content is just text
         tag_html = tag_html.gsub(%r{^<p>(.*)</p>$}m, '\1')
 
-        "<wa-tag#{attrs_string}>#{tag_html}</wa-tag>"
+        "<wa-tag#{attrs_string}>#{icon_html}#{tag_html}</wa-tag>"
       end
     end
   end

data/lib/markawesome/transformers.rb

@@ -15,5 +15,6 @@ require_relative 'transformers/details_transformer'
 require_relative 'transformers/dialog_transformer'
 require_relative 'transformers/icon_transformer'
 require_relative 'transformers/image_dialog_transformer'
+require_relative 'transformers/layout_transformer'
 require_relative 'transformers/tabs_transformer'
 require_relative 'transformers/tag_transformer'

data/lib/markawesome/version.rb

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

data/lib/markawesome.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'markawesome/version'
+require_relative 'markawesome/icon_slot_parser'
 require_relative 'markawesome/transformer'
 
 # Main module for Markawesome - framework-agnostic Markdown to Web Awesome component transformer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markawesome
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Janne Waren
@@ -92,6 +92,7 @@ files:
 - README.md
 - lib/markawesome.rb
 - lib/markawesome/attribute_parser.rb
+- lib/markawesome/icon_slot_parser.rb
 - lib/markawesome/transformer.rb
 - lib/markawesome/transformers.rb
 - lib/markawesome/transformers/badge_transformer.rb
@@ -106,6 +107,7 @@ files:
 - lib/markawesome/transformers/dialog_transformer.rb
 - lib/markawesome/transformers/icon_transformer.rb
 - lib/markawesome/transformers/image_dialog_transformer.rb
+- lib/markawesome/transformers/layout_transformer.rb
 - lib/markawesome/transformers/tabs_transformer.rb
 - lib/markawesome/transformers/tag_transformer.rb
 - lib/markawesome/version.rb