@taprootio/espalier 4.16.0 → 4.17.0

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

@@ -4,6 +4,7 @@ import { type FocusPoint } from "./image-focus.js";
 import "./esp-image-option.js";
 export type ImageScrim = "auto" | "none" | "flat" | "top" | "bottom" | "left" | "right" | "radial";
 export type ImageScrimStrength = "soft" | "medium" | "strong";
+export type ImageScrimEdge = "none" | "flush";
 export type ImageTexture = "none" | "dots" | "halftone" | "paper" | "grain" | "grunge" | "scanlines" | "duotone";
 export type ImageTextureScale = "fine" | "medium" | "coarse";
 export type ImageBannerScheme = "auto" | "light" | "dark";
@@ -116,6 +117,66 @@ export declare function parseImageRatio(value: string): string | null;
  * </esp-image>
  * ```
  *
+ * ### Meeting an adjoining band
+ *
+ * A directional scrim is capped by `scrim-strength`, so even `strong` leaves
+ * roughly a quarter of the photograph showing at the very edge it is anchored
+ * to. `scrim-edge="flush"` paints that edge at full alpha and relaxes to the
+ * ordinary strength over `--esp-image-scrim-edge-depth` (12% of the gradient
+ * axis by default), so a banner dissolves into a section band directly beneath
+ * it with no seam. Above that band the scrim is unchanged — `flush` is an edge
+ * treatment, not a heavier veil over the subject.
+ *
+ * The join is exact because both sides paint the same token: when
+ * `banner-scheme` resolves to the page scheme the scrim ink *is*
+ * `--esp-color-background`, which is what [esp-section](/components/section)
+ * paints its band with. Put the banner in a section with no padding, directly
+ * above a section in the same context:
+ *
+ * ```html
+ * <esp-section style="--esp-section-max-width: none; --esp-section-padding-inline: 0; --esp-section-padding-block: 0;">
+ *   <esp-image banner ratio="3/1" scrim="bottom" scrim-strength="strong" scrim-edge="flush" focus="0.65 0.4">
+ *     <img src="/assets/focus-picker-unsplash.jpg" alt="A woman standing in a sunlit field with her back to the camera" />
+ *     <h2 slot="overlay">Grow somewhere wonderful</h2>
+ *   </esp-image>
+ * </esp-section>
+ * <esp-section>
+ *   <p>The banner's bottom edge and this band are the same color, so the photograph fades into the page rather than stopping at a line.</p>
+ * </esp-section>
+ * ```
+ *
+ * `flush` is inert unless the *resolved* scrim is directional — an `auto`
+ * scrim that resolves to `top` or `bottom` picks it up, while `none`, `flat`,
+ * and `radial` ignore it, having no anchored edge for it to close.
+ *
+ * It is its own attribute rather than a fourth `scrim-strength` because the two
+ * are independent: `scrim-strength` is how much veil sits over the subject,
+ * `scrim-edge` is whether the anchored edge completes. A light veil with a
+ * closed edge is exactly the composition this exists for, and a strength step
+ * could not express it.
+ *
+ * A seamless tile can bleed across the join too — any `background-image` value,
+ * a tile the application serves, a data URI, or a gradient. Hand the edge the
+ * same background the adjoining section paints and it tiles up over the
+ * photograph, fading out over the same band:
+ *
+ * ```html
+ * <esp-image
+ *   banner
+ *   ratio="3/1"
+ *   scrim="bottom"
+ *   scrim-edge="flush"
+ *   style="--esp-image-scrim-edge-image: repeating-linear-gradient(45deg, oklch(0.55 0.08 255 / 0.18) 0 6px, transparent 6px 18px); --esp-image-scrim-edge-size: 18px 18px; --esp-image-scrim-edge-depth: 22%;"
+ * >
+ *   <img src="/assets/focus-picker-unsplash.jpg" alt="A woman standing in a sunlit field with her back to the camera" />
+ * </esp-image>
+ * ```
+ *
+ * The component anchors its own side of the tile to the scrim's edge, so the
+ * banner's last tile row ends exactly at the join. Continuity into the section
+ * below is the consumer's half of the contract: the same `background-size`,
+ * and a `top`-anchored `background-position` on the adjoining band.
+ *
  * Every procedural preset supports `fine`, `medium`, and `coarse` scales.
  *
  * ### Dots
@@ -232,8 +293,11 @@ export declare function parseImageRatio(value: string): string | null;
  * @cssprop --esp-image-border-radius - Corner radius; defaults to `var(--esp-size-border-radius)` or zero in banner mode.
  * @cssprop --esp-image-object-position - Final object-position override.
  * @cssprop --esp-image-compact-width - Component-width threshold; defaults to `40rem`.
- * @cssprop --esp-image-scrim-color - Scrim ink; defaults to the theme background when the banner polarity matches the scheme, else a polarity-pinned derivation.
+ * @cssprop --esp-image-scrim-color - Scrim ink; defaults to the theme background when the banner polarity matches the scheme, else a polarity-pinned derivation. A `scrim-edge="flush"` join is seamless only while the ink is the adjoining band's own color, so an explicit cross-scheme `banner-scheme` (or an override to any other color) makes the edge a deliberate color break rather than a dissolve.
  * @cssprop --esp-image-scrim-opacity - Scrim-strength opacity override.
+ * @cssprop --esp-image-scrim-edge-depth - How far a `scrim-edge="flush"` edge takes to relax from full alpha to the ordinary scrim strength, along the gradient axis; defaults to `12%`.
+ * @cssprop --esp-image-scrim-edge-image - Background image painted over the flush edge and faded out with it — the adjoining band's seamless tile; defaults to `none`. Inert unless `scrim-edge="flush"` resolves onto a directional scrim.
+ * @cssprop --esp-image-scrim-edge-size - Background size for `--esp-image-scrim-edge-image`; defaults to `auto`. Match the adjoining band's own `background-size` for a continuous tile.
  * @cssprop --esp-image-texture-color - Procedural texture ink; defaults to a theme-derived color following `banner-scheme`.
  * @cssprop --esp-image-texture-opacity - Procedural texture opacity override.
  * @cssprop --esp-image-texture-scale - CSS-gradient texture pitch override.
@@ -309,6 +373,14 @@ export declare class EspalierImage extends EspalierElementBase {
     scrim: ImageScrim;
     /** Preset opacity for the scrim. */
     scrimStrength: ImageScrimStrength;
+    /**
+     * Edge treatment for a directional scrim. `flush` paints the scrim ink at
+     * full alpha along the edge the scrim is anchored to, relaxing to the
+     * ordinary strength over `--esp-image-scrim-edge-depth`, so a banner can
+     * dissolve into a section band it adjoins. Inert unless the resolved scrim
+     * is `top`, `bottom`, `left`, or `right`.
+     */
+    scrimEdge: ImageScrimEdge;
     /**
      * Optional texture: a built-in procedural preset, or the name of a
      * texture registered with `registerImageTexture`. Unknown names render

package/dist/image/esp-image.js

@@ -1,11 +1,11 @@
-var n=function(d,e,t,r){var i=arguments.length,s=i<3?e:r===null?r=Object.getOwnPropertyDescriptor(e,t):r,o;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(d,e,t,r);else for(var l=d.length-1;l>=0;l--)(o=d[l])&&(s=(i<3?o(s):i>3?o(e,t,s):o(e,t))||s);return i>3&&s&&Object.defineProperty(e,t,s),s},p;import{css as I,html as m,nothing as C}from"lit";import{customElement as $,property as c,state as g}from"lit/decorators.js";import{EspalierElementBase as v}from"../shared/esp-element-base.js";import{slotHasContent as y}from"../shared/slot-content.js";import{renderVisualOverlay as T,visualOverlayStyles as A}from"../shared/visual-overlay.js";import{focusConverter as N,normalizeFocus as R}from"./image-focus.js";import{ensureImageTextureFilters as W,imageTextureFilterId as E}from"./image-texture-filters.js";import{getImageTexture as b,isBuiltInImageTexture as x,subscribeToImageTextureRegistry as M}from"../shared/image-texture-registry.js";import{validImageDimensions as _}from"./image-dimensions.js";import"./esp-image-option.js";const k=new Set(["auto","none","flat","top","bottom","left","right","radial"]),S=new Set(["soft","medium","strong"]),w=new Set(["fine","medium","coarse"]),j=new Set(["auto","light","dark"]),O=new Set(["bottom-start","bottom","bottom-end","center","top-start","top","top-end"]);function h(d,e){return{fromAttribute(t){return t&&d.has(t)?t:e},toAttribute(t){return d.has(t)?t:e}}}function z(d){const e=d.trim();if(!e)return null;const t=e.split("/").map(i=>i.trim());if(t.length>2||t.some(i=>i.length===0))return null;const r=t.map(Number);return r.some(i=>!Number.isFinite(i)||i<=0)?null:r.length===1?String(r[0]):`${r[0]} / ${r[1]}`}let a=p=class extends v{constructor(){super(...arguments),this.originalHeight=0,this.originalWidth=0,this.imageUrl="",this.localImage="",this.caption="",this.sizes="100vw",this.loading="eager",this.deferOffscreen=!1,this.banner=!1,this.bannerScheme="auto",this.scrim="auto",this.scrimStrength="medium",this.texture="none",this.textureScale="medium",this.contentPosition="bottom-start",this.focusPoint={x:.5,y:.5},this.ratio="",this.compactRatio="",this.renderedWidth=0,this.measuredWidth=0,this.compact=!1,this.overlayHasContent=!1,this.resizeObserver=null,this.offscreenObserver=null,this.offscreenAdmitted=!1,this.deferredProjectedImage=null,this.unsubscribeTextures=null,this.handleSlotChange=e=>{if(e.target instanceof HTMLSlotElement){if(e.target.name==="overlay"){const t=y(e.target);t!==this.overlayHasContent&&(this.overlayHasContent=t);return}this.requestUpdate()}}}get isPortrait(){const e=_(this.originalWidth,this.originalHeight);return e!==null&&e.height>e.width}findProjected(){for(const e of this.children)if(e.tagName==="PICTURE"||e.tagName==="IMG")return e;return null}findProjectedImage(e=this.findProjected()){return e?e.tagName==="IMG"?e:e.querySelector("img"):null}requiresOffscreenDeferral(e=this.findProjectedImage()){return this.deferOffscreen&&e?.getAttribute("loading")?.toLowerCase()==="lazy"}shouldDeferProjectedSizes(){return this.requiresOffscreenDeferral()&&!this.offscreenAdmitted}applyMeasuredWidth(){this.measuredWidth>0&&this.measuredWidth!==this.renderedWidth&&(this.renderedWidth=this.measuredWidth)}syncOffscreenDeferral(){const e=this.findProjectedImage();if(e!==this.deferredProjectedImage&&(this.offscreenAdmitted=!1,this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.deferredProjectedImage=e),!this.requiresOffscreenDeferral(e)){this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.offscreenAdmitted=!1,this.deferredProjectedImage=null,this.applyMeasuredWidth();return}if(!this.offscreenAdmitted){if(typeof IntersectionObserver>"u"){this.offscreenAdmitted=!0,this.applyMeasuredWidth();return}if(!this.offscreenObserver){const t=e,r=new IntersectionObserver(i=>{if(this.offscreenObserver===r){if(this.findProjectedImage()!==t){this.syncOffscreenDeferral();return}i.some(s=>s.isIntersecting)&&(this.offscreenAdmitted=!0,this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.applyMeasuredWidth(),this.requestUpdate())}},{rootMargin:"200px"});this.offscreenObserver=r}this.offscreenObserver.observe(this)}}connectedCallback(){super.connectedCallback(),p.ensureProjectionStyles(this.getRootNode()),this.unsubscribeTextures??=M(()=>this.requestUpdate()),this.resizeObserver??=new ResizeObserver(e=>{const t=e[0]?.contentBoxSize?.[0],r=Math.round(t?t.inlineSize:e[0]?.contentRect.width??0);r<=0||(this.measuredWidth=r,this.syncOffscreenDeferral(),this.applyMeasuredWidth())}),this.resizeObserver.observe(this),this.syncOffscreenDeferral()}disconnectedCallback(){super.disconnectedCallback(),this.unsubscribeTextures?.(),this.unsubscribeTextures=null,this.resizeObserver?.disconnect(),this.resizeObserver=null,this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.offscreenAdmitted=!1,this.deferredProjectedImage=null}effectiveSizes(){return this.renderedWidth>0?`${this.renderedWidth}px`:this.sizes}buildSources(){const e=new Map;for(const t of this.querySelectorAll("esp-image-option")){const r=t.getAttribute("url"),i=Number(t.getAttribute("width"));if(!r||!Number.isFinite(i)||i<=0)continue;const s=t.getAttribute("type")??"",o=e.get(s)??[];o.push({url:r,width:i}),e.set(s,o)}return Array.from(e,([t,r])=>({type:t,srcset:r.sort((i,s)=>i.width-s.width).map(i=>`${i.url} ${i.width}w`).join(", ")})).filter(t=>t.srcset.length>0)}resolvedBannerScheme(){return this.bannerScheme!=="auto"?this.bannerScheme:this.scheme==="dark"?"dark":"light"}resolvedTexture(){return x(this.texture)?this.texture:b(this.texture)?this.texture:"none"}resolvedScrim(){return this.scrim!=="auto"?this.scrim:this.overlayHasContent?this.contentPosition.startsWith("top")?"top":this.contentPosition.startsWith("bottom")?"bottom":"radial":"none"}resolvedAspectRatio(){const e=_(this.originalWidth,this.originalHeight);if(!this.banner)return e?`${e.width} / ${e.height}`:null;const t=z(this.ratio);return(this.compact?z(this.compactRatio):null)??t??(e?`${e.width} / ${e.height}`:null)}normalizeEnums(e){e.has("scrim")&&!k.has(this.scrim)&&(this.scrim="auto"),e.has("bannerScheme")&&!j.has(this.bannerScheme)&&(this.bannerScheme="auto"),e.has("scrimStrength")&&!S.has(this.scrimStrength)&&(this.scrimStrength="medium"),e.has("textureScale")&&!w.has(this.textureScale)&&(this.textureScale="medium"),e.has("contentPosition")&&!O.has(this.contentPosition)&&(this.contentPosition="bottom-start")}willUpdate(e){super.willUpdate(e),this.normalizeEnums(e);const t=R(this.focusPoint),r=Number((t.x*100).toFixed(4)),i=Number((t.y*100).toFixed(4));this.style.setProperty("--_esp-image-object-position",`${r}% ${i}%`);const s=this.resolvedAspectRatio();s?this.style.setProperty("--_esp-image-aspect-ratio",s):this.style.removeProperty("--_esp-image-aspect-ratio");const o=this.resolvedTexture();if(["paper","grain","grunge"].includes(o)){const u=o==="grunge"&&this.resolvedBannerScheme()==="light"?"grunge-light":o;this.style.setProperty("--_esp-image-texture-filter",`url(#${E(u,this.textureScale)})`)}else this.style.removeProperty("--_esp-image-texture-filter");const l=x(o)?void 0:b(o),P=[["--_esp-image-registered-image",l?.image],["--_esp-image-registered-size",l?.size],["--_esp-image-registered-repeat",l?.repeat],["--_esp-image-registered-position",l?.position],["--_esp-image-registered-opacity",l?.opacity?.toString()],["--_esp-image-registered-blend-mode",l?.blendMode]];for(const[u,f]of P)f===void 0?this.style.removeProperty(u):this.style.setProperty(u,f)}firstUpdated(e){super.firstUpdated(e);const t=this.shadowRoot?.querySelector('slot[name="overlay"]');t&&(this.overlayHasContent=y(t))}updated(e){if(super.updated(e),this.syncOffscreenDeferral(),["paper","grain","grunge"].includes(this.resolvedTexture())&&this.renderRoot&&W(this.renderRoot),this.renderedWidth>0){const o=this.shadowRoot?.querySelector(".compact-sentinel")?.getBoundingClientRect().width??0,l=o>0&&this.renderedWidth<o;l!==this.compact&&(this.compact=l)}if(this.renderedWidth<=0||this.shouldDeferProjectedSizes())return;const t=this.findProjected();if(!t)return;const r=this.effectiveSizes();if(t.tagName==="PICTURE")for(const s of t.querySelectorAll("source"))s.setAttribute("sizes",r);const i=this.findProjectedImage(t);i?.hasAttribute("srcset")&&i.setAttribute("sizes",r)}renderMedia(){if(this.localImage)return m`<img
+var n=function(d,e,t,r){var i=arguments.length,s=i<3?e:r===null?r=Object.getOwnPropertyDescriptor(e,t):r,o;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(d,e,t,r);else for(var l=d.length-1;l>=0;l--)(o=d[l])&&(s=(i<3?o(s):i>3?o(e,t,s):o(e,t))||s);return i>3&&s&&Object.defineProperty(e,t,s),s},p;import{css as T,html as h,nothing as C}from"lit";import{customElement as $,property as c,state as u}from"lit/decorators.js";import{EspalierElementBase as v}from"../shared/esp-element-base.js";import{slotHasContent as y}from"../shared/slot-content.js";import{renderVisualOverlay as E,visualOverlayStyles as A}from"../shared/visual-overlay.js";import{focusConverter as N,normalizeFocus as R}from"./image-focus.js";import{ensureImageTextureFilters as W,imageTextureFilterId as M}from"./image-texture-filters.js";import{getImageTexture as b,isBuiltInImageTexture as x,subscribeToImageTextureRegistry as D}from"../shared/image-texture-registry.js";import{validImageDimensions as _}from"./image-dimensions.js";import"./esp-image-option.js";const k=new Set(["auto","none","flat","top","bottom","left","right","radial"]),w=new Set(["soft","medium","strong"]),S=new Set(["none","flush"]),z=new Set(["fine","medium","coarse"]),j=new Set(["auto","light","dark"]),O=new Set(["bottom-start","bottom","bottom-end","center","top-start","top","top-end"]);function m(d,e){return{fromAttribute(t){return t&&d.has(t)?t:e},toAttribute(t){return d.has(t)?t:e}}}function I(d){const e=d.trim();if(!e)return null;const t=e.split("/").map(i=>i.trim());if(t.length>2||t.some(i=>i.length===0))return null;const r=t.map(Number);return r.some(i=>!Number.isFinite(i)||i<=0)?null:r.length===1?String(r[0]):`${r[0]} / ${r[1]}`}let a=p=class extends v{constructor(){super(...arguments),this.originalHeight=0,this.originalWidth=0,this.imageUrl="",this.localImage="",this.caption="",this.sizes="100vw",this.loading="eager",this.deferOffscreen=!1,this.banner=!1,this.bannerScheme="auto",this.scrim="auto",this.scrimStrength="medium",this.scrimEdge="none",this.texture="none",this.textureScale="medium",this.contentPosition="bottom-start",this.focusPoint={x:.5,y:.5},this.ratio="",this.compactRatio="",this.renderedWidth=0,this.measuredWidth=0,this.compact=!1,this.overlayHasContent=!1,this.resizeObserver=null,this.offscreenObserver=null,this.offscreenAdmitted=!1,this.deferredProjectedImage=null,this.unsubscribeTextures=null,this.handleSlotChange=e=>{if(e.target instanceof HTMLSlotElement){if(e.target.name==="overlay"){const t=y(e.target);t!==this.overlayHasContent&&(this.overlayHasContent=t);return}this.requestUpdate()}}}get isPortrait(){const e=_(this.originalWidth,this.originalHeight);return e!==null&&e.height>e.width}findProjected(){for(const e of this.children)if(e.tagName==="PICTURE"||e.tagName==="IMG")return e;return null}findProjectedImage(e=this.findProjected()){return e?e.tagName==="IMG"?e:e.querySelector("img"):null}requiresOffscreenDeferral(e=this.findProjectedImage()){return this.deferOffscreen&&e?.getAttribute("loading")?.toLowerCase()==="lazy"}shouldDeferProjectedSizes(){return this.requiresOffscreenDeferral()&&!this.offscreenAdmitted}applyMeasuredWidth(){this.measuredWidth>0&&this.measuredWidth!==this.renderedWidth&&(this.renderedWidth=this.measuredWidth)}syncOffscreenDeferral(){const e=this.findProjectedImage();if(e!==this.deferredProjectedImage&&(this.offscreenAdmitted=!1,this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.deferredProjectedImage=e),!this.requiresOffscreenDeferral(e)){this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.offscreenAdmitted=!1,this.deferredProjectedImage=null,this.applyMeasuredWidth();return}if(!this.offscreenAdmitted){if(typeof IntersectionObserver>"u"){this.offscreenAdmitted=!0,this.applyMeasuredWidth();return}if(!this.offscreenObserver){const t=e,r=new IntersectionObserver(i=>{if(this.offscreenObserver===r){if(this.findProjectedImage()!==t){this.syncOffscreenDeferral();return}i.some(s=>s.isIntersecting)&&(this.offscreenAdmitted=!0,this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.applyMeasuredWidth(),this.requestUpdate())}},{rootMargin:"200px"});this.offscreenObserver=r}this.offscreenObserver.observe(this)}}connectedCallback(){super.connectedCallback(),p.ensureProjectionStyles(this.getRootNode()),this.unsubscribeTextures??=D(()=>this.requestUpdate()),this.resizeObserver??=new ResizeObserver(e=>{const t=e[0]?.contentBoxSize?.[0],r=Math.round(t?t.inlineSize:e[0]?.contentRect.width??0);r<=0||(this.measuredWidth=r,this.syncOffscreenDeferral(),this.applyMeasuredWidth())}),this.resizeObserver.observe(this),this.syncOffscreenDeferral()}disconnectedCallback(){super.disconnectedCallback(),this.unsubscribeTextures?.(),this.unsubscribeTextures=null,this.resizeObserver?.disconnect(),this.resizeObserver=null,this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.offscreenAdmitted=!1,this.deferredProjectedImage=null}effectiveSizes(){return this.renderedWidth>0?`${this.renderedWidth}px`:this.sizes}buildSources(){const e=new Map;for(const t of this.querySelectorAll("esp-image-option")){const r=t.getAttribute("url"),i=Number(t.getAttribute("width"));if(!r||!Number.isFinite(i)||i<=0)continue;const s=t.getAttribute("type")??"",o=e.get(s)??[];o.push({url:r,width:i}),e.set(s,o)}return Array.from(e,([t,r])=>({type:t,srcset:r.sort((i,s)=>i.width-s.width).map(i=>`${i.url} ${i.width}w`).join(", ")})).filter(t=>t.srcset.length>0)}resolvedBannerScheme(){return this.bannerScheme!=="auto"?this.bannerScheme:this.scheme==="dark"?"dark":"light"}resolvedTexture(){return x(this.texture)?this.texture:b(this.texture)?this.texture:"none"}resolvedScrim(){return this.scrim!=="auto"?this.scrim:this.overlayHasContent?this.contentPosition.startsWith("top")?"top":this.contentPosition.startsWith("bottom")?"bottom":"radial":"none"}resolvedAspectRatio(){const e=_(this.originalWidth,this.originalHeight);if(!this.banner)return e?`${e.width} / ${e.height}`:null;const t=I(this.ratio);return(this.compact?I(this.compactRatio):null)??t??(e?`${e.width} / ${e.height}`:null)}normalizeEnums(e){e.has("scrim")&&!k.has(this.scrim)&&(this.scrim="auto"),e.has("bannerScheme")&&!j.has(this.bannerScheme)&&(this.bannerScheme="auto"),e.has("scrimStrength")&&!w.has(this.scrimStrength)&&(this.scrimStrength="medium"),e.has("scrimEdge")&&!S.has(this.scrimEdge)&&(this.scrimEdge="none"),e.has("textureScale")&&!z.has(this.textureScale)&&(this.textureScale="medium"),e.has("contentPosition")&&!O.has(this.contentPosition)&&(this.contentPosition="bottom-start")}willUpdate(e){super.willUpdate(e),this.normalizeEnums(e);const t=R(this.focusPoint),r=Number((t.x*100).toFixed(4)),i=Number((t.y*100).toFixed(4));this.style.setProperty("--_esp-image-object-position",`${r}% ${i}%`);const s=this.resolvedAspectRatio();s?this.style.setProperty("--_esp-image-aspect-ratio",s):this.style.removeProperty("--_esp-image-aspect-ratio");const o=this.resolvedTexture();if(["paper","grain","grunge"].includes(o)){const g=o==="grunge"&&this.resolvedBannerScheme()==="light"?"grunge-light":o;this.style.setProperty("--_esp-image-texture-filter",`url(#${M(g,this.textureScale)})`)}else this.style.removeProperty("--_esp-image-texture-filter");const l=x(o)?void 0:b(o),P=[["--_esp-image-registered-image",l?.image],["--_esp-image-registered-size",l?.size],["--_esp-image-registered-repeat",l?.repeat],["--_esp-image-registered-position",l?.position],["--_esp-image-registered-opacity",l?.opacity?.toString()],["--_esp-image-registered-blend-mode",l?.blendMode]];for(const[g,f]of P)f===void 0?this.style.removeProperty(g):this.style.setProperty(g,f)}firstUpdated(e){super.firstUpdated(e);const t=this.shadowRoot?.querySelector('slot[name="overlay"]');t&&(this.overlayHasContent=y(t))}updated(e){if(super.updated(e),this.syncOffscreenDeferral(),["paper","grain","grunge"].includes(this.resolvedTexture())&&this.renderRoot&&W(this.renderRoot),this.renderedWidth>0){const o=this.shadowRoot?.querySelector(".compact-sentinel")?.getBoundingClientRect().width??0,l=o>0&&this.renderedWidth<o;l!==this.compact&&(this.compact=l)}if(this.renderedWidth<=0||this.shouldDeferProjectedSizes())return;const t=this.findProjected();if(!t)return;const r=this.effectiveSizes();if(t.tagName==="PICTURE")for(const s of t.querySelectorAll("source"))s.setAttribute("sizes",r);const i=this.findProjectedImage(t);i?.hasAttribute("srcset")&&i.setAttribute("sizes",r)}renderMedia(){if(this.localImage)return h`<img
         src=${this.localImage}
         alt=${this.caption}
         decoding="async"
         loading=${this.loading}
-      />`;const e=m`<slot @slotchange=${this.handleSlotChange}></slot>`;if(this.findProjected())return e;const t=this.buildSources();return m`
+      />`;const e=h`<slot @slotchange=${this.handleSlotChange}></slot>`;if(this.findProjected())return e;const t=this.buildSources();return h`
       <picture>
-        ${t.map(r=>m`
+        ${t.map(r=>h`
             <source
               srcset=${r.srcset}
               sizes=${this.effectiveSizes()}
@@ -15,19 +15,20 @@ var n=function(d,e,t,r){var i=arguments.length,s=i<3?e:r===null?r=Object.getOwnP
         <img src=${this.imageUrl} alt=${this.caption} decoding="async" loading=${this.loading} />
       </picture>
       ${e}
-    `}render(){return m`
+    `}render(){return h`
       <div
         part="frame"
         class="frame"
         data-banner-scheme=${this.resolvedBannerScheme()}
         data-scrim=${this.resolvedScrim()}
         data-scrim-strength=${this.scrimStrength}
+        data-scrim-edge=${this.scrimEdge}
         data-texture=${this.resolvedTexture()}
         data-texture-scale=${this.textureScale}
         data-content-position=${this.contentPosition}
       >
         <div part="image" class="image">${this.renderMedia()}</div>
-        ${T({className:"banner-layers",imagePart:"texture",scrimPart:"scrim",texturePart:"texture"})}
+        ${E({className:"banner-layers",imagePart:"texture",scrimPart:"scrim",texturePart:"texture"})}
         <div part="overlay" class="overlay" ?hidden=${!this.banner||!this.overlayHasContent}>
           <slot name="overlay" @slotchange=${this.handleSlotChange}></slot>
         </div>
@@ -49,7 +50,7 @@ var n=function(d,e,t,r){var i=arguments.length,s=i<3?e:r===null?r=Object.getOwnP
       object-fit: var(--_esp-image-object-fit, cover);
       object-position: var(--esp-image-object-position, var(--_esp-image-object-position, center));
     }
-  `,a.styles=[...v.styles,I`
+  `,a.styles=[...v.styles,T`
       :host {
         display: block;
         aspect-ratio: var(--_esp-image-aspect-ratio, auto);
@@ -224,6 +225,71 @@ var n=function(d,e,t,r){var i=arguments.length,s=i<3?e:r===null?r=Object.getOwnP
       }
 
       
+      :host([banner]) .banner-layers::after {
+        content: var(--_esp-image-scrim-edge-content, none);
+        position: absolute;
+        inset: 0;
+        pointer-events: none;
+        background-color: var(--_esp-image-scrim-edge-color, transparent);
+        background-image: var(--_esp-image-scrim-edge-image, none);
+        background-position: var(--_esp-image-scrim-edge-position, 0 0);
+        background-repeat: repeat;
+        background-size: var(--_esp-image-scrim-edge-size, auto);
+        mask-image: var(--_esp-image-scrim-edge-mask, none);
+        mask-mode: alpha;
+      }
+
+      
+      .frame[data-scrim-edge="flush"][data-scrim="top"] {
+        --_esp-image-scrim-edge-content: "";
+        --_esp-image-scrim-edge-color: var(--_esp-image-scrim-resolved);
+        --_esp-image-scrim-edge-image: var(--esp-image-scrim-edge-image, none);
+        --_esp-image-scrim-edge-size: var(--esp-image-scrim-edge-size, auto);
+        --_esp-image-scrim-edge-position: left top;
+        --_esp-image-scrim-edge-mask: linear-gradient(
+          to bottom,
+          black 0%,
+          transparent var(--esp-image-scrim-edge-depth, 12%)
+        );
+      }
+      .frame[data-scrim-edge="flush"][data-scrim="bottom"] {
+        --_esp-image-scrim-edge-content: "";
+        --_esp-image-scrim-edge-color: var(--_esp-image-scrim-resolved);
+        --_esp-image-scrim-edge-image: var(--esp-image-scrim-edge-image, none);
+        --_esp-image-scrim-edge-size: var(--esp-image-scrim-edge-size, auto);
+        --_esp-image-scrim-edge-position: left bottom;
+        --_esp-image-scrim-edge-mask: linear-gradient(
+          to top,
+          black 0%,
+          transparent var(--esp-image-scrim-edge-depth, 12%)
+        );
+      }
+      .frame[data-scrim-edge="flush"][data-scrim="left"] {
+        --_esp-image-scrim-edge-content: "";
+        --_esp-image-scrim-edge-color: var(--_esp-image-scrim-resolved);
+        --_esp-image-scrim-edge-image: var(--esp-image-scrim-edge-image, none);
+        --_esp-image-scrim-edge-size: var(--esp-image-scrim-edge-size, auto);
+        --_esp-image-scrim-edge-position: left top;
+        --_esp-image-scrim-edge-mask: linear-gradient(
+          to right,
+          black 0%,
+          transparent var(--esp-image-scrim-edge-depth, 12%)
+        );
+      }
+      .frame[data-scrim-edge="flush"][data-scrim="right"] {
+        --_esp-image-scrim-edge-content: "";
+        --_esp-image-scrim-edge-color: var(--_esp-image-scrim-resolved);
+        --_esp-image-scrim-edge-image: var(--esp-image-scrim-edge-image, none);
+        --_esp-image-scrim-edge-size: var(--esp-image-scrim-edge-size, auto);
+        --_esp-image-scrim-edge-position: right top;
+        --_esp-image-scrim-edge-mask: linear-gradient(
+          to left,
+          black 0%,
+          transparent var(--esp-image-scrim-edge-depth, 12%)
+        );
+      }
+
+      
       .frame[data-banner-scheme="dark"] {
         --_esp-image-scrim-ink: oklch(from var(--esp-color-background, oklch(0.98 0 0)) 0.13 c h);
         --_esp-image-texture-ink: oklch(from var(--esp-color-background, oklch(0.98 0 0)) 0.12 c h);
@@ -439,4 +505,4 @@ var n=function(d,e,t,r){var i=arguments.length,s=i<3?e:r===null?r=Object.getOwnP
           transition: none !important;
         }
       }
-    `,A],n([c({attribute:"original-height",type:Number})],a.prototype,"originalHeight",void 0),n([c({attribute:"original-width",type:Number})],a.prototype,"originalWidth",void 0),n([c({attribute:"low-res",type:String})],a.prototype,"imageUrl",void 0),n([c({attribute:"local-image",type:String})],a.prototype,"localImage",void 0),n([c({type:String})],a.prototype,"caption",void 0),n([c({attribute:"sizes",type:String})],a.prototype,"sizes",void 0),n([c({attribute:"loading",type:String})],a.prototype,"loading",void 0),n([c({attribute:"defer-offscreen",type:Boolean})],a.prototype,"deferOffscreen",void 0),n([c({type:Boolean,reflect:!0})],a.prototype,"banner",void 0),n([c({attribute:"banner-scheme",converter:h(j,"auto"),reflect:!0})],a.prototype,"bannerScheme",void 0),n([c({converter:h(k,"auto"),reflect:!0})],a.prototype,"scrim",void 0),n([c({attribute:"scrim-strength",converter:h(S,"medium"),reflect:!0})],a.prototype,"scrimStrength",void 0),n([c({type:String,reflect:!0})],a.prototype,"texture",void 0),n([c({attribute:"texture-scale",converter:h(w,"medium"),reflect:!0})],a.prototype,"textureScale",void 0),n([c({attribute:"content-position",converter:h(O,"bottom-start"),reflect:!0})],a.prototype,"contentPosition",void 0),n([c({attribute:"focus",converter:N,reflect:!0})],a.prototype,"focusPoint",void 0),n([c({type:String})],a.prototype,"ratio",void 0),n([c({attribute:"compact-ratio",type:String})],a.prototype,"compactRatio",void 0),n([g()],a.prototype,"renderedWidth",void 0),n([g()],a.prototype,"compact",void 0),n([g()],a.prototype,"overlayHasContent",void 0),a=p=n([$("esp-image")],a);export{a as EspalierImage,z as parseImageRatio};
+    `,A],n([c({attribute:"original-height",type:Number})],a.prototype,"originalHeight",void 0),n([c({attribute:"original-width",type:Number})],a.prototype,"originalWidth",void 0),n([c({attribute:"low-res",type:String})],a.prototype,"imageUrl",void 0),n([c({attribute:"local-image",type:String})],a.prototype,"localImage",void 0),n([c({type:String})],a.prototype,"caption",void 0),n([c({attribute:"sizes",type:String})],a.prototype,"sizes",void 0),n([c({attribute:"loading",type:String})],a.prototype,"loading",void 0),n([c({attribute:"defer-offscreen",type:Boolean})],a.prototype,"deferOffscreen",void 0),n([c({type:Boolean,reflect:!0})],a.prototype,"banner",void 0),n([c({attribute:"banner-scheme",converter:m(j,"auto"),reflect:!0})],a.prototype,"bannerScheme",void 0),n([c({converter:m(k,"auto"),reflect:!0})],a.prototype,"scrim",void 0),n([c({attribute:"scrim-strength",converter:m(w,"medium"),reflect:!0})],a.prototype,"scrimStrength",void 0),n([c({attribute:"scrim-edge",converter:m(S,"none"),reflect:!0})],a.prototype,"scrimEdge",void 0),n([c({type:String,reflect:!0})],a.prototype,"texture",void 0),n([c({attribute:"texture-scale",converter:m(z,"medium"),reflect:!0})],a.prototype,"textureScale",void 0),n([c({attribute:"content-position",converter:m(O,"bottom-start"),reflect:!0})],a.prototype,"contentPosition",void 0),n([c({attribute:"focus",converter:N,reflect:!0})],a.prototype,"focusPoint",void 0),n([c({type:String})],a.prototype,"ratio",void 0),n([c({attribute:"compact-ratio",type:String})],a.prototype,"compactRatio",void 0),n([u()],a.prototype,"renderedWidth",void 0),n([u()],a.prototype,"compact",void 0),n([u()],a.prototype,"overlayHasContent",void 0),a=p=n([$("esp-image")],a);export{a as EspalierImage,I as parseImageRatio};

package/dist/lightbox/esp-lightbox.js

@@ -73,6 +73,7 @@ var d=function(c,e,t,i){var s=arguments.length,r=s<3?e:i===null?i=Object.getOwnP
         aria-modal="true"
         aria-label="Image lightbox"
         tabindex="-1"
+        data-no-swipe
         @keydown=${this._handleKeyDown}
         @click=${this._handleLightboxClick}
         @touchstart=${this._handleTouchStart}

package/espalier.css-data.json

@@ -1043,7 +1043,19 @@
     },
     {
       "name": "--esp-image-scrim-color",
-      "description": "Scrim ink; defaults to the theme background when the banner polarity matches the scheme, else a polarity-pinned derivation."
+      "description": "Scrim ink; defaults to the theme background when the banner polarity matches the scheme, else a polarity-pinned derivation. A `scrim-edge=\"flush\"` join is seamless only while the ink is the adjoining band's own color, so an explicit cross-scheme `banner-scheme` (or an override to any other color) makes the edge a deliberate color break rather than a dissolve."
+    },
+    {
+      "name": "--esp-image-scrim-edge-depth",
+      "description": "How far a `scrim-edge=\"flush\"` edge takes to relax from full alpha to the ordinary scrim strength, along the gradient axis; defaults to `12%`."
+    },
+    {
+      "name": "--esp-image-scrim-edge-image",
+      "description": "Background image painted over the flush edge and faded out with it — the adjoining band's seamless tile; defaults to `none`. Inert unless `scrim-edge=\"flush\"` resolves onto a directional scrim."
+    },
+    {
+      "name": "--esp-image-scrim-edge-size",
+      "description": "Background size for `--esp-image-scrim-edge-image`; defaults to `auto`. Match the adjoining band's own `background-size` for a continuous tile."
     },
     {
       "name": "--esp-image-scrim-opacity",

package/espalier.token-manifest.json

@@ -1480,7 +1480,25 @@
       "name": "--esp-image-scrim-color",
       "category": "component",
       "component": "esp-image",
-      "description": "Scrim ink; defaults to the theme background when the banner polarity matches the scheme, else a polarity-pinned derivation."
+      "description": "Scrim ink; defaults to the theme background when the banner polarity matches the scheme, else a polarity-pinned derivation. A `scrim-edge=\"flush\"` join is seamless only while the ink is the adjoining band's own color, so an explicit cross-scheme `banner-scheme` (or an override to any other color) makes the edge a deliberate color break rather than a dissolve."
+    },
+    {
+      "name": "--esp-image-scrim-edge-depth",
+      "category": "component",
+      "component": "esp-image",
+      "description": "How far a `scrim-edge=\"flush\"` edge takes to relax from full alpha to the ordinary scrim strength, along the gradient axis; defaults to `12%`."
+    },
+    {
+      "name": "--esp-image-scrim-edge-image",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Background image painted over the flush edge and faded out with it — the adjoining band's seamless tile; defaults to `none`. Inert unless `scrim-edge=\"flush\"` resolves onto a directional scrim."
+    },
+    {
+      "name": "--esp-image-scrim-edge-size",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Background size for `--esp-image-scrim-edge-image`; defaults to `auto`. Match the adjoining band's own `background-size` for a continuous tile."
     },
     {
       "name": "--esp-image-scrim-opacity",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "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",