@taprootio/espalier 4.19.0 → 4.20.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 4.20.0
+
+Sections and pages stop failing accessibility audits they should pass: section decoration becomes an explicit opt-in, and page asides become landmarks only when they have content, each with its own name.
+
+- **Fixed: every `esp-section` caused a false color-contrast failure in axe-core and Lighthouse.** Each section painted a full-bleed decoration plane in its heading color and hid it with a fully transparent mask. Neither auditor models `mask-image`, so both measured every line of section text against that invisible plane: body text in a light section against the heading color, and text in a `context="inverted"` section, including text inside a child component's shadow root, against the zone's near-white heading color instead of its dark canvas. The pages looked correct and failed anyway. An undecorated section now renders no decorative layer at all, so audits measure its text against the band behind it. Nothing changes visually.
+- **New: the `decoration` attribute on `esp-section` (reflected boolean property `decoration`).** It turns on the decorative mask plane. **The `--esp-section-decoration-image`, `-color`, `-position`, `-size` and `-opacity` hooks now take effect only on a section that carries it**, so a section that sets the image hook without the attribute paints no decoration. Add `decoration` wherever you set the image: `<esp-section decoration style="--esp-section-decoration-image: url(...)">`. This is a minor release rather than a major one on purpose: every site that uses the hook is owner-managed and picks up the attribute when it moves to this version. With the attribute, a decorated section looks exactly as it did before. The contract is to set it together with an image, never on its own: a `decoration` section whose image is absent or `none` still paints nothing you can see, but auditors read its tint as the background again. Auditors treat a decorated section as though the tint covered it edge to edge, so text that passes an audit also reads where it crosses the mark. Keep `--esp-section-decoration-opacity` low (for example `0.09`): at its default of `1`, auditors measure the section's text against the solid tint.
+- The other users of the shared overlay layers, `esp-footer` and `esp-image`, are unaffected. Neither paints a layer that only a transparent mask hides: the footer's overlay paints its real background color, and image textures are visible gradients, masked only (and partially) for halftone.
+- **Fixed: every `esp-page` exposed two empty, unnamed complementary landmarks, failing axe-core's `landmark-unique` audit.** The page always rendered its left and right asides, whether or not anything was slotted into `sidebar` or `right`, and gave neither a name. Screen reader users met two indistinguishable, empty regions on every page, and Lighthouse flagged them. An aside whose slot is empty is now not a landmark at all (`role="none"`). It keeps its element and grid track and still collapses to zero width, so layout is unchanged. The aside becomes a landmark again as soon as content is slotted, and drops the role again when the content is removed.
+- **New: `sidebar-label` and `right-label` on `esp-page` (reflected string properties `sidebarLabel` and `rightLabel`).** They name the left and right asides' complementary landmarks while the aside has content, the same way `preview-label` names the preview. The defaults are `Sidebar` and `Related`. If you rename one, keep the two different so the landmarks stay distinguishable.
+
 # 4.19.0
 
 Filled action labels meet their contrast target, and the theme fit report says when a brand colour did not survive the compile.