markawesome 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd9d40552aa4f47c46ce12a72e4340075e9049a0d374dabbd894d6b4e9c0771
-  data.tar.gz: bf63ff67375e59593d352c35b9e6852fd4f436a4005eba52bdf695b54d734f11
+  metadata.gz: eee224c1babae361baa15c8c0f0a65bebf839d9debc599bf8e4a43bb3752bdb4
+  data.tar.gz: 9d8d78ec8aaf682bf252c634a220fa7cb9283ec15dc70c280d69967ed9f2945b
 SHA512:
-  metadata.gz: eeb2dffdb406f0eeb414cedfe834a616540956dddf5854c972b9743088e62b9d92054a4a1db2be1dc68817b5b81bec1ef7f0b30a0055a5508c6641710b8dc5f1
-  data.tar.gz: c76afeb5d61c70cab00f10e8a3a0d9b2f825bf04b5c4e5f46915506092fb826c9f1e4cb49061da3c29437404c2c0d2188eaf38d634704a56f6398a3410438770
+  metadata.gz: edb36c15048371cf37c3d860d214faacc61158b9a497f09293ade0fb152b02bcb0c7a37ed1db0725939f1bea4d5159aad9bf3452456120ed5c5250c55dd61f4b
+  data.tar.gz: 112fbcbb947dc90348bc2c187b0ee3a8379fba4bff06e8da0ee3f8b550e9307933333795e245a524b41478b41fc75875f33a62f1b63263a13c5dabd16a37475f

data/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.16.0] - 2026-06-25
+
+### Added
+
+- `CopyButtonTransformer` now accepts a `tooltip:full|copy|none` token controlling Web Awesome's `<wa-copy-button>` **`tooltip`** attribute (added in WA 3.6) — the *mode* of the built-in hover affordance, distinct from the existing `tooltip-placement`:
+  - **`full`** (WA default) — the tooltip shows on hover **and** focus, and is reused to display the brief copy-success/error feedback. Emitting `tooltip="full"` is explicit-but-redundant.
+  - **`copy`** — the tooltip stays **silent on hover/focus** and appears **only briefly to confirm a successful or failed copy** (feedback-only, no hover hint).
+  - **`none`** — no tooltip in any state.
+- The token is a `key:value` form (like `distance:N`, `icon:name`), order-independent with the other copy-button tokens. The capture is **enum-anchored** (`full|copy|none`), so invalid values such as `tooltip:bogus` simply don't match and are dropped, falling back to WA's default — consistent with the "unknown tokens dropped" convention. Emit order stays deterministic: `tooltip` follows `tooltip-placement`.
+- The plain-markdown degradation path (`render_as_markdown`) is unaffected — the wrapper and all params are discarded, leaving only the copied content.
+
+## [0.15.0] - 2026-06-24
+
+### Added
+
+- New `TooltipTransformer` producing Web Awesome `<wa-tooltip>` — inline contextual help on hover/focus for glossary terms and inline definitions. Declarative, zero-JS, and static-site-safe: the tooltip is attached to a focusable anchor `<span>` via an auto-generated `for`/`id` pair, so authors write only the trigger term and the tip text.
+  - **Inline syntax** (primary): `(((anchor term >>> tip text)))`. The `(((` delimiter is unused by any other transformer, is not Markdown- or Liquid-special, and never appears in normal prose; the `>>>` separator matches the popover/dialog/details convention (anchor first, tip after `>>>`).
+  - **Block alternative**: `:::wa-tooltip placement? distance:N?` / anchor / `>>>` / tip / `:::`, for consistency with every other component's `:::wa-*` form.
+  - **Attributes** (order-independent leading tokens): `placement` (`top` default, `bottom`, `left`, `right`) and `distance:N`. Mirrors `PopoverTransformer`'s surface minus `link`/`without-arrow` (WA `<wa-tooltip>` has no `without-arrow` boolean — arrow size is CSS-only).
+  - **Tip content** is plain text (HTML-escaped), with literal `\n` rendered as `<br>` — the same surface as the popover's *inline* form. Tooltips hold brief text, so there is no Markdown body.
+  - **Emitted markup**: a focusable `<span id="tooltip-…" tabindex="0" class="ma-tooltip-anchor" style="text-decoration: underline dotted; cursor: help;">` anchor followed by `<wa-tooltip for="tooltip-…" placement="…" [distance="…"]>`. The anchor is focusable so keyboard/AT users get the tip (tooltips fire on focus too); `ma-tooltip-anchor` is a styling hook (mirrors popover's `ma-popover-trigger`).
+  - **IDs** are auto-wired via `tooltip-<first 8 of MD5(anchor+tip)>`, with `-2`/`-3` dedup suffixes for repeated identical tooltips — the same scheme as `PopoverTransformer`. Runs immediately after `PopoverTransformer` (early, after `LayoutTransformer`) so inline tooltips inside cards/callouts/details are transformed before Kramdown escapes `(((`/`>>>`.
+  - **Plain-markdown degradation** (`render_as_markdown`, used for `.md` endpoints / llms.txt): both forms degrade to `**anchor** (tip)`, mirroring the popover inline degradation.
+- Aligned placements (`top-start`, …), `show-delay`/`hide-delay`, and a rich-content block form are explicit future follow-ups, not part of v1.
+
 ## [0.14.0] - 2026-06-24
 
 ### Added

data/README.md

@@ -20,7 +20,7 @@ Used as the transformation engine for the [jekyll-webawesome](https://github.com
 | **Card** | `===` | `:::wa-card` | `<wa-card>content</wa-card>` |
 | **Carousel** | `~~~~~~` | `:::wa-carousel` | `<wa-carousel>` with carousel items |
 | **Comparison** | `\|\|\|` or `\|\|\|25` | `:::wa-comparison` or `:::wa-comparison 25` | `<wa-comparison>` with before/after slots |
-| **Copy Button** | `<<<` | `:::wa-copy-button` | `<wa-copy-button value="content">content</wa-copy-button>` |
+| **Copy Button** | `<<<placement? tooltip:full\|copy\|none?` | `:::wa-copy-button placement? tooltip:full\|copy\|none?` | `<wa-copy-button value="content" tooltip-placement="top" tooltip="copy"></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` | `:::wa-icon icon-name` | `<wa-icon name="icon-name"></wa-icon>` |

data/lib/markawesome/plain_markdown_renderer.rb

@@ -26,7 +26,7 @@ module Markawesome
       #
       # @param component [Symbol] one of :accordion, :callout, :badge, :button,
       #   :card, :carousel, :comparison, :copy_button, :details, :dialog, :icon,
-      #   :image_dialog, :layout, :popover, :tabs, :tag.
+      #   :image_dialog, :layout, :popover, :tabs, :tag, :tooltip.
       # @yield [content, options] Proc that receives the full source content
       #   and the renderer options; returns the content with that component
       #   syntax replaced.
@@ -45,6 +45,7 @@ module Markawesome
     PIPELINE = %i[
       layout
       popover
+      tooltip
       badge
       button
       callout
@@ -64,6 +65,7 @@ module Markawesome
     TRANSFORMER_MAP = {
       layout: LayoutTransformer,
       popover: PopoverTransformer,
+      tooltip: TooltipTransformer,
       badge: BadgeTransformer,
       button: ButtonTransformer,
       callout: CalloutTransformer,

data/lib/markawesome/transformer.rb

@@ -12,6 +12,7 @@ module Markawesome
 
       content = LayoutTransformer.transform(content)
       content = PopoverTransformer.transform(content)
+      content = TooltipTransformer.transform(content)
       content = BadgeTransformer.transform(content)
       content = ButtonTransformer.transform(content)
       content = CalloutTransformer.transform(content)

data/lib/markawesome/transformers/copy_button_transformer.rb

@@ -10,6 +10,7 @@ module Markawesome
   #
   # Params: space-separated tokens, any order (rightmost-wins for conflicts)
   # Placement: top, right, bottom, left
+  # Tooltip mode: tooltip:full|copy|none (when the built-in tooltip appears)
   # Duration: numeric value (feedback-duration in milliseconds)
   # Flags: disabled
   # Labels: copy-label="text", success-label="text", error-label="text"
@@ -37,6 +38,8 @@ module Markawesome
       disabled: %w[disabled]
     }.freeze
 
+    TOOLTIP_MODES = %w[full copy none].freeze
+
     def self.transform(content)
       # Define both regex patterns - capture params as a single string
       primary_regex = /^<<<(.*?)\n(.*?)\n<<</m
@@ -58,6 +61,10 @@ module Markawesome
         # Extract numeric feedback-duration
         attributes[:feedback_duration] = ::Regexp.last_match(1) if params_string =~ /\b(\d+)\b/
 
+        # Extract tooltip mode (enum-anchored: invalid values simply don't match and are dropped)
+        tooltip_mode_regex = /\btooltip:(#{TOOLTIP_MODES.join('|')})\b/
+        attributes[:tooltip] = ::Regexp.last_match(1) if params_string =~ tooltip_mode_regex
+
         build_copy_button_html(copy_content, attributes)
       end
 
@@ -98,6 +105,9 @@ module Markawesome
         # Add tooltip placement
         attr_parts << "tooltip-placement=\"#{attributes[:placement]}\"" if attributes[:placement]
 
+        # Add tooltip mode
+        attr_parts << "tooltip=\"#{attributes[:tooltip]}\"" if attributes[:tooltip]
+
         # Add custom labels
         attr_parts << "copy-label=\"#{attributes[:copy_label]}\"" if attributes[:copy_label]
         attr_parts << "success-label=\"#{attributes[:success_label]}\"" if attributes[:success_label]

data/lib/markawesome/transformers/tooltip_transformer.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'base_transformer'
+require_relative '../attribute_parser'
+
+module Markawesome
+  # Transforms tooltip syntax into wa-tooltip elements attached to a focusable
+  # anchor span via an auto-generated for/id pair. Declarative, zero-JS, and
+  # static-site-safe — great for glossary terms and inline definitions.
+  #
+  # Inline syntax (primary): (((anchor term >>> tip text)))
+  # Alternative block syntax: :::wa-tooltip params\nanchor\n>>>\ntip\n:::
+  #
+  # Params: space-separated tokens (order doesn't matter)
+  # Placement: top (default), bottom, left, right
+  # Distance: distance:N (e.g., distance:10)
+  #
+  # Tip content is plain text (HTML-escaped), with literal `\n` rendered as
+  # <br> — the same surface as the popover's inline form. Tooltips hold brief
+  # text, so there is no markdown body.
+  class TooltipTransformer < BaseTransformer
+    TOOLTIP_ATTRIBUTES = {
+      placement: %w[top bottom left right]
+    }.freeze
+
+    # Inline regex (single-line, no newlines allowed): capture 1 = params+anchor,
+    # capture 2 = tip text.
+    INLINE_REGEX = /\(\(\([ \t]*([^\r\n]*?)[ \t]*>>>[ \t]*([^\r\n]+?)[ \t]*\)\)\)/
+    # Block alternative regex (multiline): capture 1 = params, 2 = anchor, 3 = tip.
+    ALTERNATIVE_REGEX = /^:::wa-tooltip([^\n]*)$\n(.*?)\n^>>>$\n(.*?)\n^:::$/m
+
+    def self.transform(content)
+      # Tracks ID base usage within this transform call so repeated tooltips
+      # (same anchor + tip) get disambiguated suffixes instead of colliding on
+      # the page.
+      seen_ids = Hash.new(0)
+
+      inline_transform = {
+        regex: INLINE_REGEX,
+        block: proc do |_match, matchdata|
+          combined = matchdata[1]
+          tip_text = matchdata[2].strip
+
+          params_string, anchor_text = parse_inline_anchor_and_params(combined)
+          placement, distance = parse_parameters(params_string)
+
+          tooltip_id = generate_tooltip_id(anchor_text, tip_text, seen_ids)
+
+          build_tooltip_html(tooltip_id, anchor_text, tip_text,
+                             { placement: placement, distance: distance })
+        end
+      }
+
+      alternative_transform = {
+        regex: ALTERNATIVE_REGEX,
+        block: proc do |_match, matchdata|
+          params_string = matchdata[1]
+          anchor_text = matchdata[2].strip
+          tip_text = matchdata[3].strip
+
+          placement, distance = parse_parameters(params_string)
+
+          tooltip_id = generate_tooltip_id(anchor_text, tip_text, seen_ids)
+
+          build_tooltip_html(tooltip_id, anchor_text, tip_text,
+                             { placement: placement, distance: distance })
+        end
+      }
+
+      # Inline pattern first to avoid conflicts with the block pattern.
+      apply_multiple_patterns(content, [inline_transform, alternative_transform])
+    end
+
+    def self.render_as_markdown(content, _options = {})
+      inline_transform = {
+        regex: INLINE_REGEX,
+        block: proc do |_match, matchdata|
+          combined = matchdata[1]
+          tip_text = matchdata[2].strip
+          _params, anchor_text = parse_inline_anchor_and_params(combined)
+          "**#{anchor_text}** (#{tip_text})"
+        end
+      }
+
+      alternative_transform = {
+        regex: ALTERNATIVE_REGEX,
+        block: proc do |_match, matchdata|
+          anchor_text = matchdata[2].strip
+          tip_text = matchdata[3].strip
+          "**#{anchor_text}** (#{tip_text})"
+        end
+      }
+
+      apply_multiple_patterns(content, [inline_transform, alternative_transform])
+    end
+
+    class << self
+      private
+
+      def parse_parameters(params_string)
+        return ['top', nil] if params_string.nil? || params_string.strip.empty?
+
+        attributes = AttributeParser.parse(params_string, TOOLTIP_ATTRIBUTES)
+        placement = attributes[:placement] || 'top'
+
+        # Look for distance:N parameter (rightmost-wins)
+        tokens = params_string.strip.split(/\s+/)
+        distance_token = tokens.reverse.find { |token| token.match?(/^distance:\d+$/) }
+        distance = distance_token&.sub('distance:', '')
+
+        [placement, distance]
+      end
+
+      def generate_tooltip_id(anchor_text, tip_text, seen_ids)
+        hash_input = "#{anchor_text}#{tip_text}"
+        hash = Digest::MD5.hexdigest(hash_input)
+        base = "tooltip-#{hash[0..7]}"
+        occurrence = seen_ids[base] += 1
+        occurrence == 1 ? base : "#{base}-#{occurrence}"
+      end
+
+      def parse_inline_anchor_and_params(combined_string)
+        tokens = combined_string.strip.split(/\s+/)
+        param_tokens = []
+        anchor_tokens = []
+        found_anchor = false
+
+        tokens.each do |token|
+          if !found_anchor && tooltip_param?(token)
+            param_tokens << token
+          else
+            found_anchor = true
+            anchor_tokens << token
+          end
+        end
+
+        anchor_text = anchor_tokens.join(' ')
+
+        # If no anchor text remains, treat entire string as the anchor (no params)
+        if anchor_text.empty?
+          ['', combined_string.strip]
+        else
+          [param_tokens.join(' '), anchor_text]
+        end
+      end
+
+      def tooltip_param?(token)
+        TOOLTIP_ATTRIBUTES.any? { |_attr, values| values.include?(token) } ||
+          token.match?(/^distance:\d+$/)
+      end
+
+      def build_tooltip_html(tooltip_id, anchor_text, tip_text, options)
+        anchor_content = escape_html(anchor_text)
+        tip_escaped = escape_html(tip_text).gsub('\n', '<br>')
+
+        tooltip_attrs = ["for=\"#{tooltip_id}\""]
+        tooltip_attrs << "placement=\"#{options[:placement]}\""
+        tooltip_attrs << "distance=\"#{options[:distance]}\"" if options[:distance]
+
+        anchor = build_anchor(tooltip_id, anchor_content)
+
+        "#{anchor}<wa-tooltip #{tooltip_attrs.join(' ')}>#{tip_escaped}</wa-tooltip>"
+      end
+
+      # Focusable span so keyboard/AT users get the tip (tooltips fire on focus
+      # too). The dotted underline + help cursor mirror the link-style popover
+      # trigger; the ma-tooltip-anchor class is a styling hook for consumers.
+      def build_anchor(tooltip_id, anchor_content)
+        style = 'text-decoration: underline dotted; cursor: help;'
+        "<span id=\"#{tooltip_id}\" tabindex=\"0\" class=\"ma-tooltip-anchor\" " \
+          "style=\"#{style}\">#{anchor_content}</span>"
+      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

@@ -20,3 +20,4 @@ require_relative 'transformers/layout_transformer'
 require_relative 'transformers/popover_transformer'
 require_relative 'transformers/tabs_transformer'
 require_relative 'transformers/tag_transformer'
+require_relative 'transformers/tooltip_transformer'

data/lib/markawesome/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markawesome
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Janne Waren
@@ -101,6 +101,7 @@ files:
 - lib/markawesome/transformers/popover_transformer.rb
 - lib/markawesome/transformers/tabs_transformer.rb
 - lib/markawesome/transformers/tag_transformer.rb
+- lib/markawesome/transformers/tooltip_transformer.rb
 - lib/markawesome/version.rb
 - markawesome.gemspec
 homepage: https://github.com/jannewaren/markawesome