markawesome 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd4d3d594adb8f57319bfbb9b353d9e1557cf9949417a4da62bd2e8e5f736ed3
-  data.tar.gz: e1018086c23e3c38f24312fb5a16c5194260083253e17100c7d591a9c93de25f
+  metadata.gz: aad59927898fc25ed0af9ae66614cf194c64e89ae06d9ac08dc1b82d810f9c07
+  data.tar.gz: 0e54e43e57692c1041fe898e972b703030e09dadb569f5c8cc57a9c385599e79
 SHA512:
-  metadata.gz: f3934636dd055cd7e418b276a1eae04f06f4c5a7527213ea6e59cdfd907cd8e9db0874a71790255891a559b907360889202205b36c15d6fa6b2a8c9454ab9c73
-  data.tar.gz: 83627f19b8439b91f2e2ac241cab1061546b2d50b267aa1096c2a3b96b4ee7b561d3bb53628cbeed2f285a07205331653fd1b6200d746cc0c2362bcfa7333bef
+  metadata.gz: ad7fccbc59895042fd63920d75dc6c4cd7505852226736af79dc9b5cf94feb2fca824e5973f68487d41494dd27d22193f2d35b84e3170222bd2e4dcae8fbdc6b
+  data.tar.gz: 47dab2727e5dc838ad25ead4a7f882e6ee8245e6e31ac8d5454654ec1b0d24f5b176747ba6d9673b043a2daf53f9e79c28ceff1e1dd90f298a1ea3b4467bd2fd

data/CHANGELOG.md

@@ -4,19 +4,42 @@ 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.7.0] - 2026-02-16
+## [0.9.0] - 2026-03-12
 
 ### Added
 
-- **IconTransformer: Size support** — Append a size token to control icon font-size via inline style. Primary syntax uses `:` separator (`$$$settings:lg`), alternative syntax uses space (`:::wa-icon settings lg`). Available sizes: `xs` (0.75em), `sm` (0.875em), `lg` (1.25em), `xl` (1.5em), `2x` (2em), `3x` (3em), `4x` (4em)
-- **IconTransformer: Custom SVG icons** — Use a file path starting with `/` or `./` to render `<wa-icon src="...">` instead of `<wa-icon name="...">`. Supports sizes too (`$$$/assets/icons/shoe.svg:2x`)
+- **PopoverTransformer**: Inline syntax `&&&trigger text >>> popover content&&&` for use within sentences
+  - Always renders as link-styled trigger (underlined text button)
+  - Supports all parameters: placement, `without-arrow`, `distance:N`
+  - Parameters placed before trigger text, separated by spaces
+  - Plain text content (HTML-escaped, no markdown processing)
+  - Multiple inline popovers supported on the same line
 
-## [0.6.0] - 2026-02-14
+## [0.8.0] - 2026-03-12
+
+### Added
+
+- **PopoverTransformer**: New `&&&` syntax for `wa-popover` floating content component
+  - Trigger text and popover content separated by `>>>` (same pattern as dialog/details)
+  - Placement options: `top` (default), `bottom`, `left`, `right`
+  - `without-arrow` flag to hide the popover arrow
+  - `distance:N` parameter for custom trigger-to-popover distance in pixels
+  - `link` flag to render trigger as a link-styled element instead of a button
+  - Unique anchor IDs generated via MD5 hash for trigger/popover pairing
+  - Alternative `:::wa-popover` syntax supported
+  - Markdown content support in popover body via Kramdown
+  - HTML escaping for trigger text (XSS prevention)
+
+## [0.7.0]
 
 ### Changed
 
 - **BREAKING: Card header syntax** — Card headers now use `**bold text**` instead of `# heading`. The first bold-only line inside a card block becomes the header slot. This avoids markdownlint warnings about multiple top-level headings (MD025) and incorrect heading levels (MD001), and better reflects that card titles are not semantic document headings.
 
+## [0.6.0] - 2026-02-14
+
+_(Version bump included LayoutTransformer and icon slot syntax — see 0.5.0 and 0.4.0 entries below.)_
+
 ## [0.5.0] - 2026-02-10
 
 ### Added

data/README.md

@@ -23,50 +23,12 @@ Used as the transformation engine for the [jekyll-webawesome](https://github.com
 | **Copy Button** | `<<<` | `:::wa-copy-button` | `<wa-copy-button value="content">content</wa-copy-button>` |
 | **Details** | `^^^appearance? icon-placement?` | `:::wa-details appearance? icon-placement?` | `<wa-details>content</wa-details>` |
 | **Dialog** | `???params?` | `:::wa-dialog params?` | `<wa-dialog>` with trigger button and content |
-| **Icon** | `$$$icon-name` or `$$$icon-name:size` | `:::wa-icon icon-name [size]` | `<wa-icon name="icon-name"></wa-icon>` |
+| **Icon** | `$$$icon-name` | `:::wa-icon icon-name` | `<wa-icon name="icon-name"></wa-icon>` |
 | **Image Dialog** | `![alt](url)` | — | Wraps images in clickable `<wa-dialog>` overlays |
+| **Popover** | `&&&params?` or inline `&&&trigger >>> content&&&` | `:::wa-popover params?` | `<wa-popover>` with trigger button and content |
 | **Tab Group** | `++++++` | `:::wa-tabs` | `<wa-tab-group><wa-tab>content</wa-tab></wa-tab-group>` |
 | **Tag** | `@@@brand` | `:::wa-tag brand` | `<wa-tag variant="brand">content</wa-tag>` |
 
-## Icon
-
-### Named icons
-
-Use a Web Awesome icon name:
-
-```markdown
-Click $$$settings to configure.
-A large $$$home:lg icon.
-```
-
-### Custom SVG icons
-
-Point to a local SVG file by starting the path with `/` or `./`:
-
-```markdown
-$$$/assets/icons/shoe.svg
-$$$/assets/icons/shoe.svg:2x
-$$$./icons/logo.svg:xl
-```
-
-This outputs `<wa-icon src="/assets/icons/shoe.svg"></wa-icon>` instead of using the `name` attribute.
-
-### Sizes
-
-Append a size token after `:` (primary syntax) or as a space-separated parameter (alternative syntax):
-
-| Token | CSS `font-size` |
-|-------|----------------|
-| `xs`  | 0.75em         |
-| `sm`  | 0.875em        |
-| `lg`  | 1.25em         |
-| `xl`  | 1.5em          |
-| `2x`  | 2em            |
-| `3x`  | 3em            |
-| `4x`  | 4em            |
-
-Without a size token, the icon inherits the surrounding font size.
-
 ## Layout Utilities
 
 Layout utilities use `::::` (quadruple colon) syntax to wrap content in CSS layout containers. Inner content is not markdown-converted, so component `:::` syntax inside layouts works normally.

data/lib/markawesome/transformer.rb

@@ -24,6 +24,7 @@ module Markawesome
       end
 
       content = DialogTransformer.transform(content)
+      content = PopoverTransformer.transform(content)
       content = IconTransformer.transform(content)
       content = TagTransformer.transform(content)
       TabsTransformer.transform(content)

data/lib/markawesome/transformers/icon_transformer.rb

@@ -4,46 +4,30 @@ require_relative 'base_transformer'
 
 module Markawesome
   # Transforms icon syntax into wa-icon elements
-  # Primary syntax: $$$icon-name or $$$icon-name:size
-  # Custom SVG syntax: $$$/path/to/icon.svg or $$$/path/to/icon.svg:size
-  # Alternative syntax: :::wa-icon icon-name [size] or :::wa-icon /path/to/icon.svg [size]
+  # Primary syntax: $$$icon-name
+  # Alternative syntax: :::wa-icon icon-name
   #
   # Examples:
   # $$$settings -> <wa-icon name="settings"></wa-icon>
-  # $$$settings:lg -> <wa-icon name="settings" style="font-size: 1.25em;"></wa-icon>
-  # $$$/assets/icons/shoe.svg -> <wa-icon src="/assets/icons/shoe.svg"></wa-icon>
-  # $$$/assets/icons/shoe.svg:2x -> <wa-icon src="/assets/icons/shoe.svg" style="font-size: 2em;"></wa-icon>
-  #
-  # Available sizes: xs (0.75em), sm (0.875em), lg (1.25em), xl (1.5em), 2x (2em), 3x (3em), 4x (4em)
+  # $$$home -> <wa-icon name="home"></wa-icon>
+  # $$$user-circle -> <wa-icon name="user-circle"></wa-icon>
   class IconTransformer < BaseTransformer
-    SIZES = {
-      'xs' => '0.75em',
-      'sm' => '0.875em',
-      'lg' => '1.25em',
-      'xl' => '1.5em',
-      '2x' => '2em',
-      '3x' => '3em',
-      '4x' => '4em'
-    }.freeze
-
     def self.transform(content)
       # Protect code blocks first
       protected_content, code_blocks = protect_code_blocks(content)
 
       # Apply primary syntax transformation
-      # Supports named icons ($$$settings:lg) and custom SVG paths ($$$/path/to/icon.svg:2x)
-      result = protected_content.gsub(%r{\$\$\$(\.?/[a-zA-Z0-9\-_./]+|[a-zA-Z0-9\-_]+)(?::([a-zA-Z0-9]+))?(?![a-zA-Z0-9\-_]|\s+name\b)}) do
-        icon_ref = ::Regexp.last_match(1)
-        size = ::Regexp.last_match(2)
-        build_icon_html(icon_ref, size)
+      # Only block patterns that look like incomplete icon names:
+      # $$$icon name (where 'icon name' could be intended as one identifier)
+      result = protected_content.gsub(/\$\$\$([a-zA-Z0-9\-_]+)(?![a-zA-Z0-9\-_]|\s+name\b)/) do
+        icon_name = ::Regexp.last_match(1)
+        build_icon_html(icon_name)
       end
 
       # Apply alternative syntax transformation
-      # Supports named icons and custom SVG paths with optional size
-      result = result.gsub(%r{:::wa-icon\s+(\.?/[a-zA-Z0-9\-_./]+|[a-zA-Z0-9\-_]+)(?:\s+([a-zA-Z0-9]+))?\s*\n:::}m) do
-        icon_ref = ::Regexp.last_match(1)
-        size = ::Regexp.last_match(2)
-        build_icon_html(icon_ref, size)
+      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)
       end
 
       # Restore code blocks
@@ -53,20 +37,12 @@ module Markawesome
     class << self
       private
 
-      def build_icon_html(icon_ref, size = nil)
-        clean_ref = icon_ref.strip
-
-        # Paths (starting with / or ./) use src attribute, otherwise use name
-        attr = if clean_ref.include?('/')
-                 "src=\"#{clean_ref}\""
-               else
-                 "name=\"#{clean_ref}\""
-               end
-
-        # Build style attribute for size
-        style = SIZES[size] ? " style=\"font-size: #{SIZES[size]};\"" : ''
+      def build_icon_html(icon_name)
+        # Clean and validate icon name
+        clean_name = icon_name.strip
 
-        "<wa-icon #{attr}#{style}></wa-icon>"
+        # Return the wa-icon element
+        "<wa-icon name=\"#{clean_name}\"></wa-icon>"
       end
 
       def protect_code_blocks(content)

data/lib/markawesome/transformers/popover_transformer.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'base_transformer'
+require_relative '../attribute_parser'
+
+module Markawesome
+  # Transforms popover syntax into wa-popover elements with trigger buttons
+  # Primary syntax: &&&params\ntrigger text\n>>>\ncontent\n&&&
+  # Alternative syntax: :::wa-popover params\ntrigger text\n>>>\ncontent\n:::
+  # Inline syntax: &&&params? trigger text >>> popover content&&&
+  #
+  # Params: space-separated tokens (order doesn't matter)
+  # Placement: top (default), bottom, left, right
+  # Flags: without-arrow
+  # Distance: distance:N (e.g., distance:10)
+  class PopoverTransformer < BaseTransformer
+    POPOVER_ATTRIBUTES = {
+      placement: %w[top bottom left right],
+      without_arrow: %w[without-arrow],
+      trigger_style: %w[link]
+    }.freeze
+
+    def self.transform(content)
+      # Inline regex (single-line, no newlines allowed)
+      inline_regex = /&&&[ \t]*([^\r\n]*?)[ \t]*>>>[ \t]*([^\r\n]+?)[ \t]*&&&/
+
+      # Block regexes (multiline)
+      primary_regex = /^&&&([^\n]*)$\n(.*?)\n^>>>$\n(.*?)\n^&&&$/m
+      alternative_regex = /^:::wa-popover([^\n]*)$\n(.*?)\n^>>>$\n(.*?)\n^:::$/m
+
+      # Inline transformation (always link style, plain text content)
+      inline_transform = {
+        regex: inline_regex,
+        block: proc do |_match, matchdata|
+          combined = matchdata[1]
+          popover_content = matchdata[2].strip
+
+          params_string, trigger_text = parse_inline_trigger_and_params(combined)
+          placement, without_arrow, distance, _link_style = parse_parameters(params_string)
+
+          popover_id = generate_popover_id(trigger_text, popover_content)
+
+          build_inline_popover_html(popover_id, trigger_text, popover_content,
+                                    { placement: placement, without_arrow: without_arrow,
+                                      distance: distance })
+        end
+      }
+
+      # Block transformation (existing)
+      transform_proc = proc do |params_string, trigger_text, popover_content|
+        trigger_text = trigger_text.strip
+        popover_content = popover_content.strip
+
+        placement, without_arrow, distance, link_style = parse_parameters(params_string)
+
+        popover_id = generate_popover_id(trigger_text, popover_content)
+
+        content_html = markdown_to_html(popover_content)
+
+        build_popover_html(popover_id, trigger_text, content_html,
+                           { placement: placement, without_arrow: without_arrow,
+                             distance: distance, link_style: link_style })
+      end
+
+      # Inline patterns first to avoid conflicts with block patterns
+      patterns = [
+        inline_transform,
+        *dual_syntax_patterns(primary_regex, alternative_regex, transform_proc)
+      ]
+      apply_multiple_patterns(content, patterns)
+    end
+
+    class << self
+      private
+
+      def parse_parameters(params_string)
+        return ['top', false, nil, false] if params_string.nil? || params_string.strip.empty?
+
+        attributes = AttributeParser.parse(params_string, POPOVER_ATTRIBUTES)
+        placement = attributes[:placement] || 'top'
+        without_arrow = attributes[:without_arrow] == 'without-arrow'
+        link_style = attributes[:trigger_style] == 'link'
+
+        # Look for distance:N parameter
+        tokens = params_string.strip.split(/\s+/)
+        distance_token = tokens.find { |token| token.match?(/^distance:\d+$/) }
+        distance = distance_token&.sub('distance:', '')
+
+        [placement, without_arrow, distance, link_style]
+      end
+
+      def generate_popover_id(trigger_text, content)
+        hash_input = "#{trigger_text}#{content}"
+        hash = Digest::MD5.hexdigest(hash_input)
+        "popover-#{hash[0..7]}"
+      end
+
+      def parse_inline_trigger_and_params(combined_string)
+        tokens = combined_string.strip.split(/\s+/)
+        param_tokens = []
+        trigger_tokens = []
+        found_content = false
+
+        tokens.each do |token|
+          if !found_content && popover_param?(token)
+            param_tokens << token
+          else
+            found_content = true
+            trigger_tokens << token
+          end
+        end
+
+        trigger_text = trigger_tokens.join(' ')
+
+        # If no trigger text remains, treat entire string as trigger (no params)
+        if trigger_text.empty?
+          ['', combined_string.strip]
+        else
+          [param_tokens.join(' '), trigger_text]
+        end
+      end
+
+      def popover_param?(token)
+        POPOVER_ATTRIBUTES.any? { |_attr, values| values.include?(token) } ||
+          token.match?(/^distance:\d+$/)
+      end
+
+      def build_inline_popover_html(popover_id, trigger_text, content_text, options)
+        trigger_content = escape_html(trigger_text)
+        content_escaped = escape_html(content_text)
+
+        popover_attrs = ["for='#{popover_id}'"]
+        popover_attrs << "placement='#{options[:placement]}'"
+        popover_attrs << 'without-arrow' if options[:without_arrow]
+        popover_attrs << "distance='#{options[:distance]}'" if options[:distance]
+
+        trigger = build_trigger(popover_id, trigger_content, true)
+
+        "#{trigger}<wa-popover #{popover_attrs.join(' ')}>#{content_escaped}</wa-popover>"
+      end
+
+      def build_popover_html(popover_id, trigger_text, content_html, options)
+        # Escape trigger text for security
+        trigger_content = escape_html(trigger_text)
+
+        # Build popover attributes
+        popover_attrs = ["for='#{popover_id}'"]
+        popover_attrs << "placement='#{options[:placement]}'"
+        popover_attrs << 'without-arrow' if options[:without_arrow]
+        popover_attrs << "distance='#{options[:distance]}'" if options[:distance]
+
+        trigger = build_trigger(popover_id, trigger_content, options[:link_style])
+
+        html = []
+        html << trigger
+        html << "<wa-popover #{popover_attrs.join(' ')}>"
+        html << content_html
+        html << '</wa-popover>'
+        html.join("\n")
+      end
+
+      def build_trigger(popover_id, trigger_content, link_style)
+        if link_style
+          link_style_attr = 'background: none; border: none; padding: 0; ' \
+                            'color: inherit; text-decoration: underline; ' \
+                            'cursor: pointer; font: inherit;'
+          "<button id='#{popover_id}' style='#{link_style_attr}'>#{trigger_content}</button>"
+        else
+          "<wa-button id='#{popover_id}' variant='text'>#{trigger_content}</wa-button>"
+        end
+      end
+
+      def escape_html(text)
+        text.gsub('&', '&amp;')
+            .gsub('<', '&lt;')
+            .gsub('>', '&gt;')
+            .gsub('"', '&quot;')
+            .gsub("'", '&#39;')
+      end
+    end
+  end
+end

data/lib/markawesome/transformers.rb

@@ -16,5 +16,6 @@ require_relative 'transformers/dialog_transformer'
 require_relative 'transformers/icon_transformer'
 require_relative 'transformers/image_dialog_transformer'
 require_relative 'transformers/layout_transformer'
+require_relative 'transformers/popover_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.7.0'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markawesome
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Janne Waren
@@ -108,6 +108,7 @@ files:
 - lib/markawesome/transformers/icon_transformer.rb
 - lib/markawesome/transformers/image_dialog_transformer.rb
 - lib/markawesome/transformers/layout_transformer.rb
+- lib/markawesome/transformers/popover_transformer.rb
 - lib/markawesome/transformers/tabs_transformer.rb
 - lib/markawesome/transformers/tag_transformer.rb
 - lib/markawesome/version.rb