markawesome 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eee224c1babae361baa15c8c0f0a65bebf839d9debc599bf8e4a43bb3752bdb4
-  data.tar.gz: 9d8d78ec8aaf682bf252c634a220fa7cb9283ec15dc70c280d69967ed9f2945b
+  metadata.gz: b3ce7a2c074d2d33074977cfe3f20c474ba14908e4c07e283c8067e9adce65f4
+  data.tar.gz: 54c1bdd4ab2c53d11c14589757707b3325555afa5315142fa5341f6842d0b90a
 SHA512:
-  metadata.gz: edb36c15048371cf37c3d860d214faacc61158b9a497f09293ade0fb152b02bcb0c7a37ed1db0725939f1bea4d5159aad9bf3452456120ed5c5250c55dd61f4b
-  data.tar.gz: 112fbcbb947dc90348bc2c187b0ee3a8379fba4bff06e8da0ee3f8b550e9307933333795e245a524b41478b41fc75875f33a62f1b63263a13c5dabd16a37475f
+  metadata.gz: ae0b842c192958678ed64bca94c3f637d16c58c4c641c8cc02bc69234ca35e322fd4f677d424c959499c692a5b6f1c7acc477123ad86c3c4eb94a2c91c2ae654
+  data.tar.gz: d870d957d821ca0cd44c46a6afa7175d26436538ed3dae3ce2f7363afb8b1d20aa79a5195743fbfe7b47f5c7494402c89c32ce630acb6010d3f5fa91f1bb2b03

data/CHANGELOG.md

@@ -4,6 +4,57 @@ 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).
 
+## [Unreleased]
+
+## [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
+
+- New `VideoTransformer` producing Web Awesome's two media components — `<wa-video>` (a single embedded video with custom controls) and `<wa-video-playlist>` (a playlist wrapping multiple `<wa-video>` children). Both are Web Awesome **Pro** (experimental); the markup emitted is declarative and static-site-safe.
+  - **Single video** (primary): a `;;;<tokens>` fence, body, closing `;;;`. **Playlist** (primary): a `;;;;;;<tokens>` container wrapping bare `;;;` items (mirroring the carousel `~~~`/`~~~~~~` structure — the bare `;;;` item open keeps the closing `;;;;;;` from being mis-read as an item). Block alternatives: `:::wa-video <tokens>` and `:::wa-video-playlist <tokens>`. Runs in the pipeline immediately after `ComparisonTransformer`.
+  - **Body**: the first markdown link `[text](url)` supplies `title`/`src`; the first markdown image `![alt](url)` supplies `poster` (a negative lookbehind keeps the image's `[…]()` from being taken as the link). A block with no link (no `src`) is left untransformed.
+  - **Tokens**: `controls:none|standard|full` and `preload:auto|metadata|none` (enum-validated `key:value`; invalid values dropped) plus the boolean flags `autoplay`, `autoplay-muted`, `autoplay-on-visible`, `loop`, `muted` (whole-token matched, so `autoplay-muted` never triggers `autoplay`). The playlist's `controls` preset is forwarded to the container only — children omit it. Deterministic emission order: `src`, `poster`, `title`, `controls`, `preload`, then `autoplay`, `autoplay-muted`, `autoplay-on-visible`, `loop`, `muted`; `src`/`poster`/`title` are HTML-escaped.
+  - **Plain-markdown degradation** (`render_as_markdown`, used for `.md` endpoints / llms.txt): a single video degrades to `[title](src)`; a playlist degrades to a bulleted list of `- [title](src)`.
+  - Captions (`<track>`) and multi-format `<source>` children are documented v1 follow-ups — a single `src` attribute suffices today.
+- New `DateTransformer` producing Web Awesome's two declarative timestamp components — `<wa-format-date>` (an absolute, locale-formatted date such as "June 26, 2026") and `<wa-relative-time>` ("3 days ago", optionally live-ticking). The date value is baked into the markup at build time; both components are pure declarative wrappers over the browser's `Intl.DateTimeFormat` / `Intl.RelativeTimeFormat`, with no data fetching — ideal for blog post dates, changelog stamps, and "last updated".
+  - **Inline syntax** (primary): `[[[ <date> <tokens> ]]]` — triple square brackets, single-line, transformed before Kramdown (runs right after `TooltipTransformer`). `[[[` collides with no other delimiter and survives Kramdown + Jekyll/Liquid.
+  - **Block alternative**: `:::wa-format-date <date> <tokens>` / `:::wa-relative-time <date> <tokens>` with an empty body closed by `:::`. The selector name chooses the mode directly.
+  - **Mode**: absolute (`<wa-format-date>`) is the default; a bare `relative` token in the inline form switches to `<wa-relative-time>`.
+  - **Date token**: the token matching ISO 8601 `YYYY-MM-DD` (optionally `THH:MM[:SS][.s][Z|±HH:MM]`) is passed verbatim (escaped) into `date="…"`. If omitted, `date` is dropped and the component shows the viewer's **current** time (runtime-now). Datetimes use the `T` separator (a space would break tokenization).
+  - **format-date formatting**: `style:short|medium|long|full` and `time:short|medium|long|full` presets expand to Web Awesome's granular attributes, with granular overrides (`weekday`, `era`, `year`, `month`, `day`, `hour`, `minute`, `second`, `hour-format`, `time-zone-name`, `time-zone`, `lang`/`locale` → `lang`) winning per key (rightmost-wins). Enum values are validated; invalid values and unknown tokens are silently dropped. A bare date with no style/time/granular field defaults to `style:long`. Deterministic emission order: `date weekday era year month day hour minute second time-zone-name time-zone hour-format lang`.
+  - **relative-time formatting**: `format` (`long|short|narrow`, default `long` omitted), `numeric` (`auto|always`, default `auto` omitted), `sync` (boolean live-update flag), and `lang`/`locale` → `lang`. Date/style tokens are ignored in relative mode. Deterministic emission order: `date format numeric sync lang`.
+  - **Plain-markdown degradation** (`render_as_markdown`, used for `.md` endpoints / llms.txt): each timestamp degrades to its raw date string (empty for a runtime-now timestamp), since plain text has no locale formatting.
+- **Static-site caveat**: like `<wa-icon>`, both timestamp components render generated text into shadow DOM with no light-DOM fallback — with Web Awesome's JS disabled they show nothing. This matches our existing generated-content model (documented alongside the `<wa-tag with-remove>` caveat); no fallback text is emitted.
+- `PopoverTransformer` and `TooltipTransformer` now accept **all twelve** Web Awesome placements — the four primary (`top`, `bottom`, `left`, `right`) plus the eight aligned variants (`top-start`, `top-end`, `right-start`, `right-end`, `bottom-start`, `bottom-end`, `left-start`, `left-end`) — matching `<wa-popover>`/`<wa-tooltip>`'s full `placement` surface. `AttributeParser` matches whole tokens, so `bottom-start` resolves without colliding with `bottom`.
+- `PopoverTransformer` and `TooltipTransformer` gain a `skidding:N` token, mirroring `distance:N`. It emits `<wa-popover>`/`<wa-tooltip>`'s `skidding` attribute — the offset **along** the target (whereas `distance` is the offset **away** from it). Negative values are allowed (`skidding:-4`). Emission order is deterministic: `placement`, `without-arrow`, `distance`, `skidding` (popover) and `placement`, `distance`, `skidding` (tooltip).
+- `TabsTransformer` supports a per-tab `disabled` flag as a **leading token** on the `+++ ` item header (e.g. `+++ disabled Coming soon`), mirroring the accordion item flags. It emits `<wa-tab disabled>` (the tab renders but cannot be selected) and strips the flag from the label; a non-leading occurrence of the word is left untouched. The `render_as_markdown` degradation strips the flag too (`### Coming soon`). Non-disabled tabs are byte-identical to before.
+
 ## [0.16.0] - 2026-06-25
 
 ### 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.
@@ -46,12 +47,14 @@ module Markawesome
       layout
       popover
       tooltip
+      date
       badge
       button
       callout
       card
       carousel
       comparison
+      video
       copy_button
       details
       image_dialog
@@ -60,18 +63,22 @@ module Markawesome
       tag
       tabs
       accordion
+      tree
+      random_content
     ].freeze
 
     TRANSFORMER_MAP = {
       layout: LayoutTransformer,
       popover: PopoverTransformer,
       tooltip: TooltipTransformer,
+      date: DateTransformer,
       badge: BadgeTransformer,
       button: ButtonTransformer,
       callout: CalloutTransformer,
       card: CardTransformer,
       carousel: CarouselTransformer,
       comparison: ComparisonTransformer,
+      video: VideoTransformer,
       copy_button: CopyButtonTransformer,
       details: DetailsTransformer,
       image_dialog: ImageDialogTransformer,
@@ -79,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

@@ -13,12 +13,14 @@ module Markawesome
       content = LayoutTransformer.transform(content)
       content = PopoverTransformer.transform(content)
       content = TooltipTransformer.transform(content)
+      content = DateTransformer.transform(content)
       content = BadgeTransformer.transform(content)
       content = ButtonTransformer.transform(content)
       content = CalloutTransformer.transform(content)
       content = CardTransformer.transform(content)
       content = CarouselTransformer.transform(content)
       content = ComparisonTransformer.transform(content)
+      content = VideoTransformer.transform(content)
       content = CopyButtonTransformer.transform(content)
       content = DetailsTransformer.transform(content)
 
@@ -37,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/date_transformer.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative 'base_transformer'
+
+module Markawesome
+  # Transforms declarative timestamp syntax into Web Awesome's two timestamp
+  # components:
+  #   <wa-format-date>   — an absolute, locale-formatted date ("June 26, 2026")
+  #   <wa-relative-time> — a relative phrase ("3 days ago"), optionally ticking
+  #
+  # These are pure declarative wrappers over the browser's Intl.DateTimeFormat /
+  # Intl.RelativeTimeFormat: the date value is baked into the markup at build
+  # time, with no data fetching. Great for blog dates, changelog stamps, and
+  # "last updated".
+  #
+  # Inline (primary):    [[[ <date> <tokens> ]]]
+  # Block (alternative): :::wa-format-date <date> <tokens>  /  :::wa-relative-time …
+  #                      followed by a closing ::: (empty body)
+  #
+  # Mode: absolute (<wa-format-date>) is the default; a bare `relative` token in
+  # the inline form switches to <wa-relative-time>. The block selector name
+  # chooses the mode directly.
+  #
+  # Static-site caveat: both components render generated text into shadow DOM
+  # with no light-DOM fallback — with Web Awesome's JS disabled they show
+  # nothing. This is identical to <wa-icon> and the other generated-content
+  # components we already emit, so it is consistent with our model.
+  class DateTransformer < BaseTransformer
+    # Inline: content excludes `]`, non-greedy, multiple-per-line, single-line.
+    INLINE_REGEX = /\[\[\[[ \t]*([^\]\r\n]+?)[ \t]*\]\]\]/
+    # Block: selector name picks the mode; an empty body, closed by `:::`.
+    ALTERNATIVE_REGEX = /^:::wa-(format-date|relative-time)[ \t]*([^\n]*)\n:::$/
+
+    # A token is the date when it is an ISO 8601 date or datetime (datetimes use
+    # the `T` separator — a space would break whitespace tokenization).
+    DATE_TOKEN_REGEX =
+      /\A\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?\z/
+
+    # style:/time: presets expand to Web Awesome's granular date/time attributes.
+    STYLE_PRESETS = {
+      'short' => { 'month' => 'numeric', 'day' => 'numeric', 'year' => '2-digit' },
+      'medium' => { 'month' => 'short', 'day' => 'numeric', 'year' => 'numeric' },
+      'long' => { 'month' => 'long', 'day' => 'numeric', 'year' => 'numeric' },
+      'full' => { 'weekday' => 'long', 'month' => 'long', 'day' => 'numeric', 'year' => 'numeric' }
+    }.freeze
+
+    TIME_PRESETS = {
+      'short' => { 'hour' => 'numeric', 'minute' => 'numeric' },
+      'medium' => { 'hour' => 'numeric', 'minute' => 'numeric', 'second' => 'numeric' },
+      'long' => { 'hour' => 'numeric', 'minute' => 'numeric', 'second' => 'numeric', 'time-zone-name' => 'short' },
+      'full' => { 'hour' => 'numeric', 'minute' => 'numeric', 'second' => 'numeric', 'time-zone-name' => 'long' }
+    }.freeze
+
+    # Granular key:value tokens that pass through to the same-named WA attribute,
+    # validated against an allowed enum (invalid values dropped).
+    GRANULAR_ENUMS = {
+      'weekday' => %w[narrow short long],
+      'era' => %w[narrow short long],
+      'year' => %w[numeric 2-digit],
+      'month' => %w[numeric 2-digit narrow short long],
+      'day' => %w[numeric 2-digit],
+      'hour' => %w[numeric 2-digit],
+      'minute' => %w[numeric 2-digit],
+      'second' => %w[numeric 2-digit],
+      'hour-format' => %w[auto 12 24],
+      'time-zone-name' => %w[short long]
+    }.freeze
+
+    # Granular keys that count as an explicit date/time field — their presence
+    # (or a style:/time: preset) suppresses the style:long default.
+    CONTENT_FIELDS = %w[weekday era year month day hour minute second time-zone-name].freeze
+
+    # Deterministic emission order (required for byte-for-byte parity).
+    FORMAT_DATE_ORDER = %w[date weekday era year month day hour minute second
+                           time-zone-name time-zone hour-format lang].freeze
+
+    RELATIVE_FORMATS = %w[long short narrow].freeze
+    RELATIVE_NUMERICS = %w[auto always].freeze
+
+    def self.transform(content)
+      patterns = [
+        { regex: INLINE_REGEX, block: proc { |_m, md| render_tokens(md[1], nil) } },
+        { regex: ALTERNATIVE_REGEX,
+          block: proc { |_m, md| render_tokens(md[2], md[1] == 'relative-time' ? :relative : :absolute) } }
+      ]
+      apply_multiple_patterns(content, patterns)
+    end
+
+    # Plain-markdown degradation: there is no locale formatting in plain text,
+    # so each timestamp degrades to its raw date string (empty when omitted).
+    def self.render_as_markdown(content, _options = {})
+      patterns = [
+        { regex: INLINE_REGEX, block: proc { |_m, md| extract_date(md[1]) } },
+        { regex: ALTERNATIVE_REGEX, block: proc { |_m, md| extract_date(md[2]) } }
+      ]
+      apply_multiple_patterns(content, patterns)
+    end
+
+    class << self
+      private
+
+      def render_tokens(token_string, mode_override)
+        tokens = token_string.to_s.strip.split(/\s+/)
+        date, tokens = split_date(tokens)
+        mode = mode_override || (tokens.include?('relative') ? :relative : :absolute)
+
+        mode == :relative ? build_relative_time(date, tokens) : build_format_date(date, tokens)
+      end
+
+      # Pull the first date/datetime token out, leaving the option tokens.
+      def split_date(tokens)
+        index = tokens.index { |token| token.match?(DATE_TOKEN_REGEX) }
+        return [nil, tokens] unless index
+
+        [tokens[index], tokens[0...index] + tokens[(index + 1)..]]
+      end
+
+      def extract_date(token_string)
+        tokens = token_string.to_s.strip.split(/\s+/)
+        tokens.find { |token| token.match?(DATE_TOKEN_REGEX) }.to_s
+      end
+
+      def build_format_date(date, tokens)
+        attrs = {}
+        apply_presets(tokens, attrs)
+        apply_granular(tokens, attrs)
+        # A bare date (no style/time/granular field) defaults to style:long.
+        attrs.merge!(STYLE_PRESETS['long']) if (attrs.keys & CONTENT_FIELDS).empty?
+        attrs['date'] = date if date
+
+        parts = FORMAT_DATE_ORDER.filter_map do |key|
+          "#{key}=\"#{escape_html(attrs[key])}\"" if attrs.key?(key)
+        end
+        build_element('wa-format-date', parts)
+      end
+
+      # Apply the rightmost valid style: and time: presets.
+      def apply_presets(tokens, attrs)
+        style = nil
+        time = nil
+        tokens.each do |token|
+          if (m = token.match(/\Astyle:(.+)\z/)) && STYLE_PRESETS.key?(m[1])
+            style = m[1]
+          elsif (m = token.match(/\Atime:(.+)\z/)) && TIME_PRESETS.key?(m[1])
+            time = m[1]
+          end
+        end
+        attrs.merge!(STYLE_PRESETS[style]) if style
+        attrs.merge!(TIME_PRESETS[time]) if time
+      end
+
+      # Apply granular enum keys (override presets) and free-string modifiers
+      # (time-zone, lang/locale). Later tokens win.
+      def apply_granular(tokens, attrs)
+        tokens.each do |token|
+          next unless (m = token.match(/\A([a-z-]+):(.+)\z/))
+
+          key = m[1]
+          value = m[2]
+          if GRANULAR_ENUMS[key]&.include?(value)
+            attrs[key] = value
+          elsif key == 'time-zone'
+            attrs['time-zone'] = value
+          elsif %w[lang locale].include?(key)
+            attrs['lang'] = value
+          end
+        end
+      end
+
+      def build_relative_time(date, tokens)
+        opts = parse_relative_options(tokens)
+        parts = []
+        parts << "date=\"#{escape_html(date)}\"" if date
+        parts << "format=\"#{opts[:format]}\"" if opts[:format] && opts[:format] != 'long'
+        parts << "numeric=\"#{opts[:numeric]}\"" if opts[:numeric] && opts[:numeric] != 'auto'
+        parts << 'sync' if opts[:sync]
+        parts << "lang=\"#{escape_html(opts[:lang])}\"" if opts[:lang]
+        build_element('wa-relative-time', parts)
+      end
+
+      def parse_relative_options(tokens)
+        opts = { format: nil, numeric: nil, sync: false, lang: nil }
+        tokens.each do |token|
+          if token == 'sync'
+            opts[:sync] = true
+          elsif (m = token.match(/\Aformat:(.+)\z/)) && RELATIVE_FORMATS.include?(m[1])
+            opts[:format] = m[1]
+          elsif (m = token.match(/\Anumeric:(.+)\z/)) && RELATIVE_NUMERICS.include?(m[1])
+            opts[:numeric] = m[1]
+          elsif (m = token.match(/\A(?:lang|locale):(.+)\z/))
+            opts[:lang] = m[1]
+          end
+        end
+        opts
+      end
+
+      def build_element(tag, parts)
+        return "<#{tag}></#{tag}>" if parts.empty?
+
+        "<#{tag} #{parts.join(' ')}></#{tag}>"
+      end
+
+      def escape_html(text)
+        text.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+            .gsub('"', '&quot;').gsub("'", '&#39;')
+      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/popover_transformer.rb

@@ -11,12 +11,15 @@ module Markawesome
   # Inline syntax: &&&params? trigger text >>> popover content&&&
   #
   # Params: space-separated tokens (order doesn't matter)
-  # Placement: top (default), bottom, left, right
+  # Placement: top (default), bottom, left, right, plus the eight aligned
+  #   variants (top-start, top-end, right-start, …) — the full wa-popover surface
   # Flags: without-arrow
-  # Distance: distance:N (e.g., distance:10)
+  # Distance: distance:N (e.g., distance:10) — offset away from the target
+  # Skidding: skidding:N (e.g., skidding:12, skidding:-4) — offset along the target
   class PopoverTransformer < BaseTransformer
     POPOVER_ATTRIBUTES = {
-      placement: %w[top bottom left right],
+      placement: %w[top top-start top-end right right-start right-end
+                    bottom bottom-start bottom-end left left-start left-end],
       without_arrow: %w[without-arrow],
       trigger_style: %w[link]
     }.freeze
@@ -42,13 +45,13 @@ module Markawesome
           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)
+          placement, without_arrow, distance, _link_style, skidding = parse_parameters(params_string)
 
           popover_id = generate_popover_id(trigger_text, popover_content, seen_ids)
 
           build_inline_popover_html(popover_id, trigger_text, popover_content,
                                     { placement: placement, without_arrow: without_arrow,
-                                      distance: distance })
+                                      distance: distance, skidding: skidding })
         end
       }
 
@@ -57,7 +60,7 @@ module Markawesome
         trigger_text = trigger_text.strip
         popover_content = popover_content.strip
 
-        placement, without_arrow, distance, link_style = parse_parameters(params_string)
+        placement, without_arrow, distance, link_style, skidding = parse_parameters(params_string)
 
         popover_id = generate_popover_id(trigger_text, popover_content, seen_ids)
 
@@ -65,7 +68,7 @@ module Markawesome
 
         build_popover_html(popover_id, trigger_text, content_html,
                            { placement: placement, without_arrow: without_arrow,
-                             distance: distance, link_style: link_style })
+                             distance: distance, link_style: link_style, skidding: skidding })
       end
 
       # Inline patterns first to avoid conflicts with block patterns
@@ -106,19 +109,21 @@ module Markawesome
       private
 
       def parse_parameters(params_string)
-        return ['top', false, nil, false] if params_string.nil? || params_string.strip.empty?
+        return ['top', false, nil, false, nil] 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
+        # Look for distance:N and skidding:N parameters (skidding may be negative)
         tokens = params_string.strip.split(/\s+/)
         distance_token = tokens.find { |token| token.match?(/^distance:\d+$/) }
         distance = distance_token&.sub('distance:', '')
+        skidding_token = tokens.find { |token| token.match?(/^skidding:-?\d+$/) }
+        skidding = skidding_token&.sub('skidding:', '')
 
-        [placement, without_arrow, distance, link_style]
+        [placement, without_arrow, distance, link_style, skidding]
       end
 
       def generate_popover_id(trigger_text, content, seen_ids)
@@ -156,42 +161,36 @@ module Markawesome
 
       def popover_param?(token)
         POPOVER_ATTRIBUTES.any? { |_attr, values| values.include?(token) } ||
-          token.match?(/^distance:\d+$/)
+          token.match?(/^distance:\d+$/) ||
+          token.match?(/^skidding:-?\d+$/)
+      end
+
+      # Build the <wa-popover> attribute list. Emission order is fixed:
+      # for, placement, without-arrow, distance, skidding.
+      def popover_attributes(popover_id, options)
+        attrs = ["for='#{popover_id}'", "placement='#{options[:placement]}'"]
+        attrs << 'without-arrow' if options[:without_arrow]
+        attrs << "distance='#{options[:distance]}'" if options[:distance]
+        attrs << "skidding='#{options[:skidding]}'" if options[:skidding]
+        attrs
       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)
-        content_escaped = content_escaped.gsub('\n', '<br>')
-
-        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]
+        content_escaped = escape_html(content_text).gsub('\n', '<br>')
 
+        attrs = popover_attributes(popover_id, options)
         trigger = build_trigger(popover_id, trigger_content, true)
 
-        "#{trigger}<wa-popover #{popover_attrs.join(' ')}>#{content_escaped}</wa-popover>"
+        "#{trigger}<wa-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]
-
+        attrs = popover_attributes(popover_id, options)
         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")
+        [trigger, "<wa-popover #{attrs.join(' ')}>", content_html, '</wa-popover>'].join("\n")
       end
 
       def build_trigger(popover_id, trigger_content, link_style)

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

@@ -12,6 +12,8 @@ module Markawesome
   #   - activation: auto (default), manual
   #   - active: panel name to show initially (e.g., "general", "tab-2")
   #   - no-scroll-controls: disables scroll arrows
+  # Per-tab flag (leading token on the `+++ ` item header, mirroring accordion):
+  #   - disabled: this tab renders but cannot be selected (e.g., "+++ disabled Coming soon")
   class TabsTransformer < BaseTransformer
     COMPONENT_ATTRIBUTES = {
       placement: %w[top bottom start end],
@@ -66,7 +68,8 @@ module Markawesome
       transform_proc = proc do |_params_string, tabs_block, _third|
         tab_contents = tabs_block.scan(/^\+\+\+ ([^\n]+)\n(.*?)\n\+\+\+/m)
         tab_contents.map do |title, panel_content|
-          "### #{title.strip}\n\n#{panel_content.strip}"
+          label, = parse_tab_header(title)
+          "### #{label}\n\n#{panel_content.strip}"
         end.join("\n\n")
       end
 
@@ -85,7 +88,11 @@ module Markawesome
 
         tab_contents.each_with_index do |(title, panel_content), index|
           tab_id = "tab-#{index + 1}"
-          tabs << "<wa-tab panel=\"#{tab_id}\">#{title.strip}</wa-tab>"
+          label, disabled = parse_tab_header(title)
+
+          tab_attrs = ["panel=\"#{tab_id}\""]
+          tab_attrs << 'disabled' if disabled
+          tabs << "<wa-tab #{tab_attrs.join(' ')}>#{label}</wa-tab>"
 
           panel_html = markdown_to_html(panel_content.strip)
           tab_panels << "<wa-tab-panel name=\"#{tab_id}\">#{panel_html}</wa-tab-panel>"
@@ -93,6 +100,17 @@ module Markawesome
 
         [tabs, tab_panels]
       end
+
+      # Parse a tab item header. A leading `disabled` token (case-sensitive,
+      # exactly `disabled` or `disabled `-prefixed) flags the tab as disabled and
+      # is stripped from the label; otherwise the label is the stripped title,
+      # unchanged. Mirrors accordion's leading item flags.
+      def parse_tab_header(title)
+        stripped = title.to_s.strip
+        return [stripped, false] unless stripped == 'disabled' || stripped.start_with?('disabled ')
+
+        [stripped.sub(/\Adisabled\s*/, ''), true]
+      end
     end
   end
 end

data/lib/markawesome/transformers/tooltip_transformer.rb

@@ -13,15 +13,18 @@ module Markawesome
   # 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)
+  # Placement: top (default), bottom, left, right, plus the eight aligned
+  #   variants (top-start, top-end, right-start, …) — the full wa-tooltip surface
+  # Distance: distance:N (e.g., distance:10) — offset away from the target
+  # Skidding: skidding:N (e.g., skidding:12, skidding:-4) — offset along the target
   #
   # 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]
+      placement: %w[top top-start top-end right right-start right-end
+                    bottom bottom-start bottom-end left left-start left-end]
     }.freeze
 
     # Inline regex (single-line, no newlines allowed): capture 1 = params+anchor,
@@ -43,12 +46,12 @@ module Markawesome
           tip_text = matchdata[2].strip
 
           params_string, anchor_text = parse_inline_anchor_and_params(combined)
-          placement, distance = parse_parameters(params_string)
+          placement, distance, skidding = 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 })
+                             { placement: placement, distance: distance, skidding: skidding })
         end
       }
 
@@ -59,12 +62,12 @@ module Markawesome
           anchor_text = matchdata[2].strip
           tip_text = matchdata[3].strip
 
-          placement, distance = parse_parameters(params_string)
+          placement, distance, skidding = 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 })
+                             { placement: placement, distance: distance, skidding: skidding })
         end
       }
 
@@ -99,17 +102,19 @@ module Markawesome
       private
 
       def parse_parameters(params_string)
-        return ['top', nil] if params_string.nil? || params_string.strip.empty?
+        return ['top', nil, 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)
+        # Look for distance:N / skidding:N parameters (rightmost-wins; skidding may be negative)
         tokens = params_string.strip.split(/\s+/)
         distance_token = tokens.reverse.find { |token| token.match?(/^distance:\d+$/) }
         distance = distance_token&.sub('distance:', '')
+        skidding_token = tokens.reverse.find { |token| token.match?(/^skidding:-?\d+$/) }
+        skidding = skidding_token&.sub('skidding:', '')
 
-        [placement, distance]
+        [placement, distance, skidding]
       end
 
       def generate_tooltip_id(anchor_text, tip_text, seen_ids)
@@ -147,7 +152,8 @@ module Markawesome
 
       def tooltip_param?(token)
         TOOLTIP_ATTRIBUTES.any? { |_attr, values| values.include?(token) } ||
-          token.match?(/^distance:\d+$/)
+          token.match?(/^distance:\d+$/) ||
+          token.match?(/^skidding:-?\d+$/)
       end
 
       def build_tooltip_html(tooltip_id, anchor_text, tip_text, options)
@@ -157,6 +163,7 @@ module Markawesome
         tooltip_attrs = ["for=\"#{tooltip_id}\""]
         tooltip_attrs << "placement=\"#{options[:placement]}\""
         tooltip_attrs << "distance=\"#{options[:distance]}\"" if options[:distance]
+        tooltip_attrs << "skidding=\"#{options[:skidding]}\"" if options[:skidding]
 
         anchor = build_anchor(tooltip_id, anchor_content)
 

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative 'base_transformer'
+require_relative '../attribute_parser'
+
+module Markawesome
+  # Transforms video syntax into Web Awesome's two media components:
+  #   <wa-video>          — a single embedded video with custom controls
+  #   <wa-video-playlist> — a playlist wrapping multiple <wa-video> children
+  #
+  # Single video
+  #   Primary:     ;;;tokens\n[Title](src)\n![Poster](poster)\n;;;
+  #   Alternative: :::wa-video tokens\n…\n:::
+  #
+  # Playlist (a ;;;;;; container wrapping bare ;;; items, mirroring carousel)
+  #   Primary:     ;;;;;;tokens\n;;;\n[Title](src)\n;;;\n…\n;;;;;;
+  #   Alternative: :::wa-video-playlist tokens\n;;;\n…\n;;;\n:::
+  #
+  # Body: the first markdown link `[text](url)` supplies `title`/`src`; the first
+  # markdown image `![alt](url)` supplies `poster`. A block with no link (no
+  # `src`) is left untransformed.
+  #
+  # Tokens: `controls:none|standard|full` and `preload:auto|metadata|none`
+  # (enum-validated, invalid values dropped) plus the boolean flags
+  # `autoplay`, `autoplay-muted`, `autoplay-on-visible`, `loop`, `muted`.
+  # Playlist children omit `controls` (the container forwards it to each child).
+  class VideoTransformer < BaseTransformer
+    # Boolean flags, matched as whole tokens so `autoplay-muted` never triggers
+    # `autoplay`. Parsed via AttributeParser (rightmost-wins, order-independent).
+    VIDEO_FLAGS = {
+      autoplay: %w[autoplay],
+      'autoplay-muted': %w[autoplay-muted],
+      'autoplay-on-visible': %w[autoplay-on-visible],
+      loop: %w[loop],
+      muted: %w[muted]
+    }.freeze
+
+    # Deterministic emission order for the boolean flags.
+    FLAG_ORDER = %w[autoplay autoplay-muted autoplay-on-visible loop muted].freeze
+
+    CONTROLS_VALUES = %w[none standard full].freeze
+    PRELOAD_VALUES = %w[auto metadata none].freeze
+
+    # Playlist consumes its inner ;;; items first; the bare `;;;\n` item open
+    # (no params) is load-bearing — it stops the closing `;;;;;;` from being
+    # mis-read as another item (mirrors carousel's `~~~`/`~~~~~~` trick).
+    PLAYLIST_PRIMARY = /^;{6}([^\n]*)\n((?:;;;\n(?:.*?\n)?;;;\n?)+);{6}/m
+    PLAYLIST_ALT = /^:::wa-video-playlist\s*([^\n]*)\n(.*?)\n:::/m
+    # `(?!;)` keeps the single open from matching a leftover `;;;;;;` fence.
+    SINGLE_PRIMARY = /^;;;(?!;)([^\n]*)\n(.*?)\n^;;;$/m
+    SINGLE_ALT = /^:::wa-video\s*([^\n]*)\n(.*?)\n:::/m
+    ITEM_REGEX = /;;;\n(.*?);;;(?:\n|$)/m
+
+    # First markdown link that is not the `![…]()` of an image (negative
+    # lookbehind on `!`) → title + src.
+    LINK_REGEX = /(?<!!)\[([^\]]+)\]\(([^)]+)\)/
+    # First markdown image → poster.
+    IMAGE_REGEX = /!\[([^\]]*)\]\(([^)]+)\)/
+
+    def self.transform(content)
+      patterns = [
+        { regex: PLAYLIST_PRIMARY, block: proc { |_m, md| build_playlist(md[1], md[2]) } },
+        { regex: PLAYLIST_ALT, block: proc { |_m, md| build_playlist(md[1], md[2]) } },
+        { regex: SINGLE_PRIMARY, block: proc { |m, md| build_single(md[1], md[2]) || m } },
+        { regex: SINGLE_ALT, block: proc { |m, md| build_single(md[1], md[2]) || m } }
+      ]
+      apply_multiple_patterns(content, patterns)
+    end
+
+    def self.render_as_markdown(content, _options = {})
+      patterns = [
+        { regex: PLAYLIST_PRIMARY, block: proc { |_m, md| render_playlist_markdown(md[2]) } },
+        { regex: PLAYLIST_ALT, block: proc { |_m, md| render_playlist_markdown(md[2]) } },
+        { regex: SINGLE_PRIMARY, block: proc { |m, md| render_single_markdown(md[2]) || m } },
+        { regex: SINGLE_ALT, block: proc { |m, md| render_single_markdown(md[2]) || m } }
+      ]
+      apply_multiple_patterns(content, patterns)
+    end
+
+    class << self
+      private
+
+      def build_single(params, body)
+        build_video(params, body, suppress_controls: false)
+      end
+
+      def build_playlist(params, body)
+        controls = parse_tokens(params)[:controls]
+        controls_attr = controls ? " controls=\"#{controls}\"" : ''
+        children = extract_items(body).filter_map do |item_body|
+          build_video('', item_body, suppress_controls: true)
+        end
+        "<wa-video-playlist#{controls_attr}>#{children.join}</wa-video-playlist>"
+      end
+
+      # Returns the <wa-video> HTML, or nil when the body has no link (no `src`),
+      # signalling the caller to leave the block untransformed.
+      def build_video(params, body, suppress_controls:)
+        tokens = parse_tokens(params)
+        title, src, poster = extract_link_and_image(body)
+        return nil unless src
+
+        parts = ["src=\"#{escape_html(src)}\""]
+        parts << "poster=\"#{escape_html(poster)}\"" if poster
+        parts << "title=\"#{escape_html(title)}\"" if title && !title.empty?
+        parts << "controls=\"#{tokens[:controls]}\"" if tokens[:controls] && !suppress_controls
+        parts << "preload=\"#{tokens[:preload]}\"" if tokens[:preload]
+        FLAG_ORDER.each { |flag| parts << flag if tokens[:flags].include?(flag) }
+
+        "<wa-video #{parts.join(' ')}></wa-video>"
+      end
+
+      def parse_tokens(params)
+        result = { controls: nil, preload: nil, flags: [] }
+        params.to_s.strip.split(/\s+/).each do |token|
+          if (m = token.match(/\Acontrols:(.+)\z/)) && CONTROLS_VALUES.include?(m[1])
+            result[:controls] = m[1]
+          elsif (m = token.match(/\Apreload:(.+)\z/)) && PRELOAD_VALUES.include?(m[1])
+            result[:preload] = m[1]
+          end
+        end
+        result[:flags] = AttributeParser.parse(params, VIDEO_FLAGS).keys.map(&:to_s)
+        result
+      end
+
+      def extract_items(body)
+        body.scan(ITEM_REGEX).map { |match| match[0] }
+      end
+
+      def extract_link_and_image(body)
+        link = body.match(LINK_REGEX)
+        image = body.match(IMAGE_REGEX)
+        [link && link[1], link && link[2], image && image[2]]
+      end
+
+      def render_single_markdown(body)
+        title, src, = extract_link_and_image(body)
+        return nil unless src
+
+        "[#{title.to_s.empty? ? src : title}](#{src})"
+      end
+
+      def render_playlist_markdown(body)
+        extract_items(body).filter_map do |item_body|
+          title, src, = extract_link_and_image(item_body)
+          next unless src
+
+          "- [#{title.to_s.empty? ? src : title}](#{src})"
+        end.join("\n")
+      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

@@ -12,12 +12,16 @@ require_relative 'transformers/card_transformer'
 require_relative 'transformers/carousel_transformer'
 require_relative 'transformers/comparison_transformer'
 require_relative 'transformers/copy_button_transformer'
+require_relative 'transformers/date_transformer'
 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/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.16.0'
+  VERSION = '0.18.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markawesome
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Janne Waren
@@ -93,15 +93,19 @@ files:
 - lib/markawesome/transformers/carousel_transformer.rb
 - lib/markawesome/transformers/comparison_transformer.rb
 - lib/markawesome/transformers/copy_button_transformer.rb
+- lib/markawesome/transformers/date_transformer.rb
 - lib/markawesome/transformers/details_transformer.rb
 - 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/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
 homepage: https://github.com/jannewaren/markawesome