@taprootio/espalier 4.19.0 → 4.20.1

package/dist/section/esp-section.d.ts

@@ -33,11 +33,13 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  *
  * A section may also tint one raster alpha mask behind its content.
  * The component owns clipping, no-repeat mask behavior, stacking, and
- * interaction isolation; consumers supply only the image, semantic tint,
- * position, size, and opacity:
+ * interaction isolation; consumers opt in with the `decoration`
+ * attribute and supply only the image, semantic tint, position, size, and
+ * opacity:
  *
  * ```html
  * <esp-section
+ *   decoration
  *   style="
  *     --esp-section-decoration-image: url('/assets/brand-mark.png');
  *     --esp-section-decoration-position: calc(100% + 2rem) -2rem;
@@ -49,6 +51,15 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  * </esp-section>
  * ```
  *
+ * Without `decoration` the section renders no decorative layer at all, and
+ * the `--esp-section-decoration-*` hooks have no effect. The attribute is
+ * what keeps an undecorated band free of painted planes: accessibility
+ * auditors such as axe-core and Lighthouse do not model `mask-image`, so a
+ * tinted plane hidden only by a mask is read as the background behind every
+ * word in the section. Set it together with the image, never on its own. A
+ * decorated band is audited as though the tint covered it everywhere, so
+ * text that passes an audit also reads where it crosses the mark.
+ *
  * CSS image values are trusted stylesheet input. Products that accept image
  * references from documents or users must enforce their own asset ownership
  * and URL policy before mapping a value to this hook.
@@ -61,7 +72,7 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  * @cssprop --esp-section-max-width - The content well's cap. Defaults to `var(--esp-page-well-max-width, 72rem)`; `none` lets content span the band.
  * @cssprop --esp-section-padding-block - Vertical rhythm above and below the well. Defaults to `var(--esp-size-section)`.
  * @cssprop --esp-section-padding-inline - Horizontal breathing room inside the band at narrow viewports. Defaults to `var(--esp-size-medium)`.
- * @cssprop --esp-section-decoration-image - Raster alpha mask painted behind the well. Defaults to `none`.
+ * @cssprop --esp-section-decoration-image - Raster alpha mask painted behind the well when `decoration` is set. Defaults to `none`.
  * @cssprop --esp-section-decoration-color - Semantic tint applied through the mask. Defaults to the local `--esp-color-headings`.
  * @cssprop --esp-section-decoration-position - Mask position, including responsive or bleeding values. Defaults to `center`.
  * @cssprop --esp-section-decoration-size - Mask size. Defaults to `contain`.
@@ -72,6 +83,15 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  * @menuIcon layout
  */
 export declare class EspalierSection extends EspalierElementBase {
+    /**
+     * Whether the section paints its decorative mask plane. Set it whenever
+     * `--esp-section-decoration-image` names an image; without it the
+     * section renders no decorative layer and the decoration hooks are
+     * inert.
+     *
+     * @type {boolean}
+     */
+    decoration: boolean;
     protected render(): import("lit-html").TemplateResult<1>;
     static styles: import("lit").CSSResult[];
 }

package/dist/section/esp-section.js

@@ -1,11 +1,11 @@
-var c=function(i,o,t,n){var a=arguments.length,e=a<3?o:n===null?n=Object.getOwnPropertyDescriptor(o,t):n,s;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")e=Reflect.decorate(i,o,t,n);else for(var l=i.length-1;l>=0;l--)(s=i[l])&&(e=(a<3?s(e):a>3?s(o,t,e):s(o,t))||e);return a>3&&e&&Object.defineProperty(o,t,e),e};import{css as d,html as v}from"lit";import{customElement as m}from"lit/decorators.js";import{EspalierElementBase as p}from"../shared/esp-element-base.js";import{renderVisualOverlay as u,visualOverlayStyles as y}from"../shared/visual-overlay.js";let r=class extends p{render(){return v`
+var p=function(r,t,o,n){var s=arguments.length,e=s<3?t:n===null?n=Object.getOwnPropertyDescriptor(t,o):n,a;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")e=Reflect.decorate(r,t,o,n);else for(var l=r.length-1;l>=0;l--)(a=r[l])&&(e=(s<3?a(e):s>3?a(t,o,e):a(t,o))||e);return s>3&&e&&Object.defineProperty(t,o,e),e};import{css as d,html as v,nothing as m}from"lit";import{customElement as u,property as h}from"lit/decorators.js";import{EspalierElementBase as c}from"../shared/esp-element-base.js";import{renderVisualOverlay as y,visualOverlayStyles as f}from"../shared/visual-overlay.js";let i=class extends c{constructor(){super(...arguments),this.decoration=!1}render(){return v`
       <div class="esp-section" part="section">
-        ${u({className:"decoration"})}
+        ${this.decoration?y({className:"decoration"}):m}
         <div class="esp-section-well" part="well">
           <slot></slot>
         </div>
       </div>
-    `}};r.styles=[...p.styles,d`
+    `}};i.styles=[...c.styles,d`
       :host {
         display: block;
       }
@@ -40,4 +40,4 @@ var c=function(i,o,t,n){var a=arguments.length,e=a<3?o:n===null?n=Object.getOwnP
         position: relative;
         z-index: 1;
       }
-    `,y],r=c([m("esp-section")],r);export{r as EspalierSection};
+    `,f],p([h({type:Boolean,reflect:!0})],i.prototype,"decoration",void 0),i=p([u("esp-section")],i);export{i as EspalierSection};

package/espalier.css-data.json

@@ -1635,7 +1635,7 @@
     },
     {
       "name": "--esp-section-decoration-image",
-      "description": "Raster alpha mask painted behind the well. Defaults to `none`."
+      "description": "Raster alpha mask painted behind the well when `decoration` is set. Defaults to `none`."
     },
     {
       "name": "--esp-section-decoration-opacity",

package/espalier.token-manifest.json

@@ -2352,7 +2352,7 @@
       "name": "--esp-section-decoration-image",
       "category": "component",
       "component": "esp-section",
-      "description": "Raster alpha mask painted behind the well. Defaults to `none`."
+      "description": "Raster alpha mask painted behind the well when `decoration` is set. Defaults to `none`."
     },
     {
       "name": "--esp-section-decoration-opacity",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "4.19.0",
+  "version": "4.20.1",
   "packageManager": "bun@1.3.12",
   "description": "Espalier — a themeable, accessible, framework-agnostic, enterprise-grade design system built on web standards and love.",
   "customElements": "custom-elements.json",