markawesome 0.17.0 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8753b6516f4a04d147b50bd980b9dd2040dc2cba63a87746121b4e25bb8529e
-  data.tar.gz: 606d078978520bf6f53c96d4d91f2f1bb66cbdbc85e1d4236d2d3ca18f222c35
+  metadata.gz: 6c2c5ebb3f9f231f78078d8ff504c309a0a20a2b786835db6763b79ec02c2ecb
+  data.tar.gz: c2828be808439565b2ff460feaf052ed97640fd9605a973897656d86b71160e6
 SHA512:
-  metadata.gz: a647d34d02688da9ce8b7a5511f8544123c4943c9f108f66598a9da8246bf6c7130d2138cde68392efc8b7603be42679e88843414847759c69d48d1cfc8297ca
-  data.tar.gz: fc0f43062d5ca3a7a2a12d80c8a77cbfc33a856270b1d02dbb5d9203200c591b6b74e768ea3ccc8c48b1aadb607bf9228dd5602acd0bcc81dbc8f8d865a920da
+  metadata.gz: 43d62e1980cd64700193e51dfef75007b4a64382ee70b4623283e24d29bd9dc6b0043834411bad243131abf57328587008704c858da90a4dc2d33a3410db9faf
+  data.tar.gz: 2668f52f02046b64911bbc7cb979fb4d9cd6c061eb811f3f06a7f21d0a46eb859adf300d836c30b1e544f2b03fabc39617a384c83c12ae70f1159db7b1424c02

data/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
 
+## [0.18.1] - 2026-07-04
+
+### Fixed
+
+- **Horizontal cards no longer overflow with multi-block bodies.** A `===horizontal` card whose body has more than one block (e.g. a `#` heading plus a paragraph) now wraps the body in a single `<div>`, so Web Awesome's `:host([orientation='horizontal']) .body slot::slotted(*) { height: 100% }` rule — which it applies to **every** direct body child — targets the one wrapper instead of each block. Previously each block was stretched to the full card height and the extra ones spilled out below the card. Vertical cards are unchanged (no wrapper is emitted). Parity locked by the new `card-horizontal-body-wrap` case in `markawesome-js`'s `test/parity-corpus.test.ts`.
+
+## [0.18.0] - 2026-07-04
+
+### Added
+
+- **`<wa-icon>` Web Awesome 3.10.0 attribute sync** — widens the shared icon vocabulary in `Markawesome::IconAttributes::SCHEMA` (used by both `$$$name` / `:::wa-icon …` **and**, transparently, callout icon overrides via `IconAttributes.pairs`, so the whole surface inherits it for free). Adds a **new `canvas` attribute** (`fixed`/`auto`/`square`/`roomy`; emitted only when specified — `fixed` is WA's default), a **new `semibold` variant** (alongside `thin light regular solid`), **nine new animations** (`flip-360`, `spin-snap`, `spin-snap-4`, `spin-snap-8`, `buzz`, `float`, `jello`, `swing`, `wag`), and a **full sync of the current WA family vocabulary** (`mosaic`, `pixel`, `vellum`, `slab-duo`, `slab-press-duo`, `chisel`, `etch`, `graphite`, `jelly`, `jelly-duo`, `jelly-fill`, `notdog`, `notdog-duo`, `slab`, `slab-press`, `thumbprint`, `utility`, `utility-duo`, `utility-fill`, `whiteboard` — family values are pure passthrough; whether one renders depends on the site's Font Awesome kit tier). The schema is a hard allowlist (`AttributeParser` silently drops unlisted tokens), so these values were previously unusable. **Deterministic emission order** is `family variant animation canvas` (`canvas` appended last) for byte-for-byte parity with `markawesome-js`. `auto-width` is unaffected — the engine never emitted it, and `canvas="auto"` is WA's supported replacement.
+- New `RandomContentTransformer` producing Web Awesome's experimental `<wa-random-content>` — a container that shows one or more of its direct element children at random (optionally rotating them) and hides the rest, all in Web Awesome's own runtime. It gives an otherwise static site a "little bit dynamic" rotating tips / testimonials / featured-content block with **zero authored JavaScript**.
+  - **Primary syntax**: a `......` (6 dots) open fence carrying the params, options separated by a `>>>` line, closed by `......`. **Block alternative**: `:::wa-random-content <params>` … `>>>` … `:::`. The character space is nearly exhausted, so both glyphs are reused: `......` (six dots never occur in prose) and the **shared** `>>>` separator already used inside details/dialog/popover/tooltip.
+  - **Gated sigils**: `>>>` and `......` only act *inside* a `......`/`:::wa-random-content` block — a stray `>>>` or `...` in ordinary prose is inert. A line of exactly `>>>` or `......` inside an option is therefore a separator/close-fence; options cannot contain those literal lines (a hard constraint, like carousel's `~~~`).
+  - **Each option is wrapped in a single `<div>`** so Web Awesome sees exactly one selectable element child per option (a multi-paragraph option becomes one `<div>` with several `<p>` — precisely why the wrapper exists). Empty options are dropped (an empty rotating option would show nothing).
+  - **Params** (order-independent, on the opening fence line): `mode` (`unique` WA default / `random` / `sequence`, as a bare enum or `mode:VALUE`), `animation` (`none`/`fade`/`fade-up`/`fade-down`/`fade-left`/`fade-right`, bare or `animation:VALUE`), `autoplay` (bare boolean), `items` (a bare integer or `items:N`), and `autoplay-interval:N`. Bare enums/booleans are parsed by `AttributeParser`; `mode:`/`animation:` colon forms are enum-validated; unknown/invalid tokens are silently ignored. **Deterministic emission order** (for byte-parity with `markawesome-js`): `mode`, `items`, `animation`, `autoplay`, `autoplay-interval`. `mode`/`animation` are omitted when unspecified (WA supplies its own defaults).
+  - **Runs last in the pipeline** (after `TreeTransformer`): its options routinely wrap already-transformed components (callouts/badges/cards), and dialog/details/popover/tooltip must consume their own `>>>` upstream before our `^>>>$` split runs. Consequence: a `......` block is the outermost container and cannot be nested inside another container body (the same constraint `TreeTransformer` documents).
+  - **Plain-markdown degradation** (`render_as_markdown`, used for `.md` endpoints / llms.txt): the block degrades to its option bodies joined by blank lines, with the fences, params, and `>>>` separators dropped.
+- New `TreeTransformer` producing Web Awesome's `<wa-tree>` / `<wa-tree-item>` from a **nested Markdown bullet list** — the first transformer that maps indentation (rather than flat item fences) onto a component. Ideal for file/directory layouts, taxonomies, and nested navigation.
+  - **Static-only scope**: Web Awesome's tree is fundamentally a *selection* control, and selection is interactive (needs JS). We deliberately emit a **display/navigation-only** tree — visual hierarchy via nesting, initial expand state, and leading folder/file icons, all declarative and static-safe. `selection`, `lazy`, `selected`, and selection events are skipped entirely.
+  - **Primary syntax**: a single `||||||` (6 pipes) open fence wrapping a normal nested Markdown list, closed by `||||||` (modeled on `LayoutTransformer`'s single-fence shape, not accordion's container+item fences). `|` is unused by any other transformer, and the transform runs before Markdown so there is no table collision. **Block alternative**: `:::wa-tree … :::`.
+  - **Fence token**: `open` (alias `expanded`) marks every branch node `expanded`. **Web Awesome runtime caveat** (verified against the WA 3.9.0 kit): `<wa-tree-item>` only honors a static `expanded` on items that are *visible at load*, so in practice `open` expands the **top-level** branches and deeper branches stay collapsed until their parent is opened (WA strips `expanded` from nested items at init). The attribute is still emitted on every branch on purpose — it's harmless (WA ignores the nested ones), records authorial intent, and is forward-compatible if WA ever honors nested initial-expand.
+  - **Per-node leading tokens** on each list item (stripped from the label, like the accordion item flags): `expanded` (force one branch open — subject to the same top-level-only WA caveat above) and `icon:name` (a leading content `<wa-icon name="name">` with no `slot`, e.g. `icon:folder`). The remaining text is the label.
+  - **Indentation parser**: list lines (`-`/`*`/`+`) are kept and their leading-whitespace width measured (a tab counts as four columns); nesting is built by comparing actual indent values, so 2-space and 4-space lists both work as long as children are strictly more indented than parents. Blank and non-list lines are skipped.
+  - **Labels are plain text** (HTML-escaped), so colon-bearing labels like `cbc:ID` and `<`/`>` are safe. `expanded` is emitted only on nodes that **have children** AND (the fence is `open` OR the node carries its own `expanded` flag); leaves never get `expanded`. Runs last in the pipeline (after accordion).
+  - **Plain-markdown degradation** (`render_as_markdown`, used for `.md` endpoints / llms.txt): the tree degrades to a clean nested bullet list (2-space indent per depth, tokens and fence stripped).
+  - Inline markdown / links in labels are a documented v1 follow-up; nesting a tree inside a markdown-converted body (accordion item, card) is not supported in v1 — the same pipeline constraint other components already have. Deep expand-on-load (beyond the top level) needs Web Awesome's interactive JS, so it is out of scope for the static surface.
+
+### Documentation
+
+- Documented the `<wa-tag with-remove>` static-site caveat in the README: the attribute renders a remove (×) button, but Web Awesome only *fires* a `wa-remove` event and does not remove the tag itself, so on a page with no authored JavaScript the button is inert. We **keep** the attribute (the emitted markup is valid Web Awesome) and document the one-line listener needed to make it functional, rather than dropping it from the static-safe surface. This also makes the existing 0.17.0 reference to "the `<wa-tag with-remove>` caveat" accurate.
+
 ## [0.17.0] - 2026-06-26
 
 ### Added

data/README.md

@@ -29,6 +29,13 @@ Used as the transformation engine for the [jekyll-webawesome](https://github.com
 | **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>` |
 
+> **Note on `<wa-tag>` `with-remove`:** the `with-remove` attribute renders a
+> remove (×) button, but Web Awesome only *fires* a `wa-remove` event — it does
+> not remove the tag for you. On a page with no JavaScript beyond the Web Awesome
+> library, the button is inert. To make it functional, add your own `wa-remove`
+> listener (e.g. a single global handler that removes `event.target`). The markup
+> we emit is valid either way.
+
 ## 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/icon_attributes.rb

@@ -1,18 +1,28 @@
 # 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.
+  # Shared <wa-icon> attribute vocabulary (family/variant/animation/canvas) and emission helper.
+  # Values verified against Web Awesome 3.10.0. 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]
+      family: %w[
+        classic sharp duotone sharp-duotone brands
+        mosaic pixel vellum slab-duo slab-press-duo chisel etch graphite
+        jelly jelly-duo jelly-fill notdog notdog-duo slab slab-press
+        thumbprint utility utility-duo utility-fill whiteboard
+      ],
+      variant: %w[thin light regular solid semibold],
+      animation: %w[
+        beat fade beat-fade bounce flip shake spin spin-pulse spin-reverse
+        flip-360 spin-snap spin-snap-4 spin-snap-8 buzz float jello swing wag
+      ],
+      canvas: %w[fixed auto square roomy]
     }.freeze
 
-    # Returns ordered ['family="…"', 'variant="…"', 'animation="…"'] for present keys.
+    # Returns ordered ['family="…"', 'variant="…"', 'animation="…"', 'canvas="…"'] for present
+    # keys. Emission order is fixed (canvas last) for byte-for-byte parity with markawesome-js.
     def self.pairs(attributes)
-      %i[family variant animation].filter_map do |key|
+      %i[family variant animation canvas].filter_map do |key|
         "#{key}=\"#{attributes[key]}\"" if attributes[key]
       end
     end

data/lib/markawesome/plain_markdown_renderer.rb

@@ -26,7 +26,8 @@ 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, :tooltip.
+      #   :image_dialog, :layout, :popover, :random_content, :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.
@@ -62,6 +63,8 @@ module Markawesome
       tag
       tabs
       accordion
+      tree
+      random_content
     ].freeze
 
     TRANSFORMER_MAP = {
@@ -83,7 +86,9 @@ module Markawesome
       icon: IconTransformer,
       tag: TagTransformer,
       tabs: TabsTransformer,
-      accordion: AccordionTransformer
+      accordion: AccordionTransformer,
+      tree: TreeTransformer,
+      random_content: RandomContentTransformer
     }.freeze
 
     def self.process(content, options = {})

data/lib/markawesome/transformer.rb

@@ -39,6 +39,17 @@ module Markawesome
       # components (same reason tabs runs near the end).
       content = AccordionTransformer.transform(content)
 
+      # Tree runs after accordion; its body is a plain nested list (never a
+      # markdown-converted body), so ordering relative to accordion is moot.
+      content = TreeTransformer.transform(content)
+
+      # Random-content runs LAST: its options routinely wrap already-transformed
+      # components (callouts/badges/cards), and dialog/details/popover/tooltip
+      # must consume their own `>>>` upstream before our `^>>>$` item split
+      # runs. Consequence: a `......` block is the outermost container and cannot
+      # be nested inside another container body (same constraint Tree documents).
+      content = RandomContentTransformer.transform(content)
+
       CodeBlockProtector.restore(content, tokens)
     end
   end

data/lib/markawesome/transformers/card_transformer.rb

@@ -138,8 +138,7 @@ module Markawesome
 
         # Main content
         if parts[:content] && !parts[:content].empty?
-          content_html = markdown_to_html(parts[:content])
-          html_parts << content_html
+          html_parts << body_content_html(parts[:content], orientation)
         end
 
         # Footer slot
@@ -149,6 +148,17 @@ module Markawesome
 
         "<wa-card#{attr_string}>#{html_parts.join}</wa-card>"
       end
+
+      # Horizontal cards wrap the body in a single <div> so Web Awesome's
+      # `:host([orientation='horizontal']) .body slot::slotted(*) { height: 100% }`
+      # rule — which it applies to EVERY direct body child — targets one wrapper
+      # instead of each block. Without the wrapper a multi-block body (e.g. a
+      # heading plus a paragraph) has each child stretched to the full card
+      # height, so the extra ones overflow below it.
+      def body_content_html(content, orientation)
+        content_html = markdown_to_html(content)
+        orientation == 'horizontal' ? "<div>#{content_html}</div>" : content_html
+      end
     end
   end
 end

data/lib/markawesome/transformers/icon_transformer.rb

@@ -7,13 +7,14 @@ require_relative '../icon_attributes'
 module Markawesome
   # Transforms icon syntax into wa-icon elements
   # Primary syntax: $$$icon-name (name only, decorative)
-  # Alternative syntax: :::wa-icon icon-name [family] [variant] [animation]\n[label]\n:::
+  # Alternative syntax: :::wa-icon icon-name [family] [variant] [animation] [canvas]\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 star roomy\n::: -> <wa-icon name="star" canvas="roomy"></wa-icon>
   # :::wa-icon heart solid\nFavorite\n::: ->
   #   <wa-icon name="heart" variant="solid" label="Favorite"></wa-icon>
   class IconTransformer < BaseTransformer

data/lib/markawesome/transformers/random_content_transformer.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative 'base_transformer'
+require_relative '../attribute_parser'
+
+module Markawesome
+  # Transforms random-content syntax into Web Awesome's experimental
+  # <wa-random-content> element, which shows one or more of its direct element
+  # children at random (optionally rotating them) and hides the rest — all in
+  # WA's own runtime, so the author writes zero JavaScript. Ideal for a "little
+  # bit dynamic" rotating tips / testimonials / featured-content block on an
+  # otherwise static site.
+  #
+  # Primary syntax:
+  #   ......mode:random items:2 animation:fade
+  #   First option
+  #   >>>
+  #   Second option
+  #   ......
+  # Alternative syntax:
+  #   :::wa-random-content <params>
+  #   First option
+  #   >>>
+  #   Second option
+  #   :::
+  #
+  # Each option (split on a `>>>` line) has its rendered Markdown wrapped in a
+  # single <div> so WA sees exactly one selectable element child per option.
+  #
+  # Params (order-independent, on the opening fence line):
+  #   - mode:      unique (WA default) | random | sequence — bare enum or mode:VALUE
+  #   - animation: none | fade | fade-up | fade-down | fade-left | fade-right —
+  #                bare enum or animation:VALUE
+  #   - autoplay:  bare boolean flag
+  #   - items:     a bare integer or items:N (how many children to show)
+  #   - autoplay-interval:N (ms between rotations)
+  # Unknown/invalid tokens are silently ignored. Deterministic emission order:
+  # mode, items, animation, autoplay, autoplay-interval.
+  #
+  # The `>>>` separator is the SHARED glyph already used inside
+  # details/dialog/popover/tooltip; it only acts as an item separator *inside* a
+  # `......`/`:::wa-random-content` block. A line of exactly `>>>` or `......`
+  # inside an option is therefore a separator/close-fence — options cannot
+  # contain those literal lines (a hard constraint, like carousel's `~~~`).
+  class RandomContentTransformer < BaseTransformer
+    COMPONENT_ATTRIBUTES = {
+      mode: %w[unique random sequence],
+      animation: %w[none fade fade-up fade-down fade-left fade-right],
+      autoplay: %w[autoplay]
+    }.freeze
+
+    # Dots MUST be escaped. The body is unstructured `(.*?)` under /m, so the
+    # closing anchor makes an unclosed fence not match and lets multiple blocks
+    # match left-to-right. Deliberately NO `\s*` after the alt fence (unlike
+    # carousel): with an unstructured body a greedy `\s*` would swallow the
+    # first newline and capture the first option line as params. `([^\n]*)`
+    # only — a leading space on the alt form is stripped by the parser.
+    PRIMARY_REGEX = /^\.{6}([^\n]*)\n(.*?)\n\.{6}/m
+    ALTERNATIVE_REGEX = /^:::wa-random-content([^\n]*)\n(.*?)\n:::/m
+    ITEM_SEPARATOR = /^>>>$/
+
+    def self.transform(content)
+      transform_proc = proc do |params, items_block|
+        build_html(extract_items(items_block), parse_params(params))
+      end
+
+      patterns = dual_syntax_patterns(PRIMARY_REGEX, ALTERNATIVE_REGEX, transform_proc)
+      apply_multiple_patterns(content, patterns)
+    end
+
+    # Degrade to the option bodies joined by blank lines (fences, params, and
+    # `>>>` separators dropped), used for `.md` endpoints / llms.txt.
+    def self.render_as_markdown(content, _options = {})
+      transform_proc = proc do |_params, items_block|
+        extract_items(items_block).reject(&:empty?).join("\n\n")
+      end
+
+      patterns = dual_syntax_patterns(PRIMARY_REGEX, ALTERNATIVE_REGEX, transform_proc)
+      apply_multiple_patterns(content, patterns)
+    end
+
+    class << self
+      private
+
+      def extract_items(items_block)
+        items_block.split(ITEM_SEPARATOR).map(&:strip)
+      end
+
+      def parse_params(params)
+        return {} if params.nil? || params.strip.empty?
+
+        result = {}
+
+        # Bare enum/boolean tokens via AttributeParser (rightmost-wins).
+        attributes = AttributeParser.parse(params, COMPONENT_ATTRIBUTES)
+        result['mode'] = attributes[:mode] if attributes[:mode]
+        result['animation'] = attributes[:animation] if attributes[:animation]
+        result['autoplay'] = true if attributes[:autoplay]
+
+        # Manual pass for key:value and bare-integer tokens.
+        params.strip.split(/\s+/).each { |token| merge_manual_token(result, token) }
+
+        result
+      end
+
+      # Fold a single space-separated token into the parsed attribute hash:
+      # `mode:`/`animation:` (enum-validated), `items:` / bare integer, and
+      # `autoplay-interval:`. Anything else is ignored.
+      def merge_manual_token(result, token)
+        if token.include?(':')
+          key, value = token.split(':', 2)
+          case key
+          when 'mode'
+            result['mode'] = value if COMPONENT_ATTRIBUTES[:mode].include?(value)
+          when 'animation'
+            result['animation'] = value if COMPONENT_ATTRIBUTES[:animation].include?(value)
+          when 'items'
+            result['items'] = value
+          when 'autoplay-interval'
+            result['autoplay-interval'] = value
+          end
+        elsif token.match?(/^\d+$/)
+          result['items'] = token
+        end
+      end
+
+      def build_html(items, params)
+        attr_string = build_attributes(params)
+
+        # Empty options are dropped — an empty rotating option would show
+        # nothing. Keep Kramdown's trailing "\n" inside each <div> (no strip).
+        divs = items.reject(&:empty?).map { |item| "<div>#{markdown_to_html(item)}</div>" }.join
+
+        "<wa-random-content#{attr_string}>#{divs}</wa-random-content>"
+      end
+
+      # Fixed emission order for byte-parity: mode, items, animation, autoplay,
+      # autoplay-interval.
+      def build_attributes(params)
+        attrs = []
+        attrs << "mode=\"#{params['mode']}\"" if params['mode']
+        attrs << "items=\"#{params['items']}\"" if params['items']
+        attrs << "animation=\"#{params['animation']}\"" if params['animation']
+        attrs << 'autoplay' if params['autoplay']
+        attrs << "autoplay-interval=\"#{params['autoplay-interval']}\"" if params['autoplay-interval']
+
+        attrs.empty? ? '' : " #{attrs.join(' ')}"
+      end
+    end
+  end
+end

data/lib/markawesome/transformers/tree_transformer.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative 'base_transformer'
+require_relative '../icon_slot_parser'
+
+module Markawesome
+  # Transforms tree syntax into wa-tree / wa-tree-item elements from a nested
+  # Markdown bullet list.
+  # Primary syntax:
+  #   ||||||open?
+  #   - icon:folder? expanded? Label
+  #     - child label
+  #   ||||||
+  # Alternative syntax: :::wa-tree open? ...same list... :::
+  #
+  # Web Awesome's tree is fundamentally a *selection* control, which is
+  # interactive (needs JS). On a static site we deliberately emit a
+  # display/navigation-only tree: visual hierarchy via nesting, initial expand
+  # state, and leading folder/file icons — all declarative and static-safe. We
+  # skip selection, lazy, selected, and selection events entirely.
+  #
+  # Fence token:
+  #   - open (alias expanded) -> mark every branch (node with children) expanded
+  # Per-node leading tokens (stripped from the label):
+  #   - expanded -> force this one branch open
+  #   - icon:name -> leading content <wa-icon name="name"> on the item
+  # The remaining text is the (plain-text, HTML-escaped) label.
+  #
+  # expanded is emitted only on nodes that HAVE children AND (fence open OR the
+  # node's own expanded flag); leaves never get expanded.
+  #
+  # WA runtime caveat (verified against the WA 3.9.0 kit): <wa-tree-item> only
+  # honors a static `expanded` on items that are VISIBLE at load, so in practice
+  # `open` expands the TOP-LEVEL branches and deeper branches stay collapsed
+  # until their parent is opened (WA strips `expanded` from nested items at
+  # init). We still emit `expanded` on every branch on purpose: it's harmless
+  # (WA ignores the nested ones), records authorial intent, and is
+  # forward-compatible if WA ever honors nested initial-expand.
+  class TreeTransformer < BaseTransformer
+    # Content slot: emits <wa-icon name="..."> with no slot attribute.
+    ICON_SLOTS = {
+      default: 'content',
+      slots: %w[content],
+      slot_map: { 'content' => 'content' }
+    }.freeze
+
+    ITEM_FLAGS = %w[expanded].freeze
+    FENCE_TOKENS = %w[open expanded].freeze
+    TAB_WIDTH = 4
+
+    PRIMARY_REGEX = /^\|{6}[ \t]*([^\n]*)\n(.*?)\n\|{6}/m
+    ALTERNATIVE_REGEX = /^:::wa-tree[ \t]*([^\n]*)\n(.*?)\n:::/m
+    LIST_LINE_REGEX = /^(\s*)[-*+]\s+(.*)$/
+
+    def self.transform(content)
+      transform_proc = proc do |params_string, body, _third|
+        fence_open = fence_open?(params_string)
+        nodes = parse_lines(body)
+        "<wa-tree>#{build_items(nodes, fence_open)}</wa-tree>"
+      end
+
+      patterns = dual_syntax_patterns(PRIMARY_REGEX, ALTERNATIVE_REGEX, transform_proc)
+      apply_multiple_patterns(content, patterns)
+    end
+
+    # Degrade to a clean nested Markdown list (2-space indent per depth, tokens
+    # stripped, fence removed).
+    def self.render_as_markdown(content, _options = {})
+      transform_proc = proc do |_params_string, body, _third|
+        nodes = parse_lines(body)
+        render_list(nodes, -1, { pos: 0 }, 0)
+      end
+
+      patterns = dual_syntax_patterns(PRIMARY_REGEX, ALTERNATIVE_REGEX, transform_proc)
+      apply_multiple_patterns(content, patterns)
+    end
+
+    class << self
+      private
+
+      def fence_open?(params_string)
+        params_string.to_s.strip.split(/\s+/).any? { |t| FENCE_TOKENS.include?(t) }
+      end
+
+      # Keep only list lines; record each line's indent width and its raw text
+      # (everything after the bullet). Blank/non-list lines are skipped.
+      def parse_lines(body)
+        nodes = []
+        body.to_s.each_line do |line|
+          match = LIST_LINE_REGEX.match(line.chomp)
+          next unless match
+
+          nodes << { indent: indent_width(match[1]), raw: match[2] }
+        end
+        nodes
+      end
+
+      def indent_width(whitespace)
+        whitespace.to_s.chars.sum { |char| char == "\t" ? TAB_WIDTH : 1 }
+      end
+
+      def build_items(nodes, fence_open)
+        helper(nodes, -1, { pos: 0 }, fence_open)
+      end
+
+      # Pointer + recursion comparing actual indent values (width-agnostic, no
+      # fixed step assumed): children are strictly more indented than the parent.
+      def helper(nodes, parent_indent, state, fence_open)
+        out = +''
+        while state[:pos] < nodes.length && nodes[state[:pos]][:indent] > parent_indent
+          node = nodes[state[:pos]]
+          current = node[:indent]
+          state[:pos] += 1
+          children_html = helper(nodes, current, state, fence_open)
+          out << emit_item(node, children_html, fence_open)
+        end
+        out
+      end
+
+      def emit_item(node, children_html, fence_open)
+        icon_result = IconSlotParser.parse(node[:raw], ICON_SLOTS)
+        flags, label = parse_item_flags_and_label(icon_result[:remaining])
+        has_children = !children_html.empty?
+        expanded = has_children && (fence_open || flags.include?('expanded'))
+
+        attrs = expanded ? ' expanded' : ''
+        icon_html = IconSlotParser.to_html(icon_result[:icons], ICON_SLOTS[:slot_map])
+        "<wa-tree-item#{attrs}>#{icon_html}#{escape_html(label)}#{children_html}</wa-tree-item>"
+      end
+
+      def render_list(nodes, parent_indent, state, depth)
+        lines = []
+        while state[:pos] < nodes.length && nodes[state[:pos]][:indent] > parent_indent
+          node = nodes[state[:pos]]
+          current = node[:indent]
+          state[:pos] += 1
+          _flags, label = parse_item_flags_and_label(IconSlotParser.parse(node[:raw], ICON_SLOTS)[:remaining])
+          lines << "#{'  ' * depth}- #{label}"
+          child = render_list(nodes, current, state, depth + 1)
+          lines << child unless child.empty?
+        end
+        lines.join("\n")
+      end
+
+      # Consume leading expanded 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 escape_html(text)
+        text.to_s
+            .gsub('&', '&amp;')
+            .gsub('<', '&lt;')
+            .gsub('>', '&gt;')
+            .gsub('"', '&quot;')
+            .gsub("'", '&#39;')
+      end
+    end
+  end
+end

data/lib/markawesome/transformers.rb

@@ -19,7 +19,9 @@ require_relative 'transformers/icon_transformer'
 require_relative 'transformers/image_dialog_transformer'
 require_relative 'transformers/layout_transformer'
 require_relative 'transformers/popover_transformer'
+require_relative 'transformers/random_content_transformer'
 require_relative 'transformers/tabs_transformer'
 require_relative 'transformers/tag_transformer'
 require_relative 'transformers/tooltip_transformer'
+require_relative 'transformers/tree_transformer'
 require_relative 'transformers/video_transformer'

data/lib/markawesome/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markawesome
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.1
 platform: ruby
 authors:
 - Janne Waren
@@ -100,9 +100,11 @@ files:
 - lib/markawesome/transformers/image_dialog_transformer.rb
 - lib/markawesome/transformers/layout_transformer.rb
 - lib/markawesome/transformers/popover_transformer.rb
+- lib/markawesome/transformers/random_content_transformer.rb
 - lib/markawesome/transformers/tabs_transformer.rb
 - lib/markawesome/transformers/tag_transformer.rb
 - lib/markawesome/transformers/tooltip_transformer.rb
+- lib/markawesome/transformers/tree_transformer.rb
 - lib/markawesome/transformers/video_transformer.rb
 - lib/markawesome/version.rb
 - markawesome.gemspec