@taprootio/espalier 6.1.0 → 6.3.0

package/dist/shared/esp-element-base.js

@@ -1,19 +1,8 @@
-var c=function(f,e,t,r){var o=arguments.length,s=o<3?e:r===null?r=Object.getOwnPropertyDescriptor(e,t):r,a;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(f,e,t,r);else for(var i=f.length-1;i>=0;i--)(a=f[i])&&(s=(o<3?a(s):o>3?a(e,t,s):a(e,t))||s);return o>3&&s&&Object.defineProperty(e,t,s),s};import{css as R,LitElement as C}from"lit";import{property as d,state as S}from"lit/decorators.js";import{subscribeToRootEvent as p}from"./root-event-subscription.js";import{traverseToClosest as g}from"./utilities.js";import{parseCssColor as w,serializeOklch as P,gamutMapToSRGB as x}from"./color-engine.js";import{computeVariants as v}from"../root/helpers/compute-variants.js";import{computeSemanticProperties as m}from"../root/helpers/compute-semantic-properties.js";import{DocumentSpriteController as E}from"./document-sprite.js";import{dataCompanionProperties as V}from"../root/helpers/data-companion-properties.js";import{dataSeriesProperties as U}from"../root/helpers/compute-theme-properties.js";import{lightnessRampProperties as I}from"../root/helpers/lightness-ramp-properties.js";import{ELEVATION_PROPERTIES as O,TYPE_ROLE_COLOR_PROPERTIES as A}from"./scale-engine.js";import{resolveContextTheme as y,resolveDataColorSource as _,semanticToCSS as D}from"./theme.js";import{alignAttributeTextInheritance as z,focusRing as N}from"./style-fragments.js";import{syncNormalizedAttribute as F}from"./attribute-helpers.js";import{INTENT_VARIANTS as k,normalizeIntentVariant as j}from"./intent-values.js";import{ESP_EVENTS as B}from"./events.js";class n extends C{get seedColor(){return this.seedColorBacker}set seedColor(e){this.seedColorBacker=e}focusResolvedElementAfterUpdate(e,t){const r=()=>{const o=e();return o?(o.focus(t),!0):!1};r()||this.updateComplete.then(()=>{r()})}focusShadowElementAfterUpdate(e,t){this.focusResolvedElementAfterUpdate(()=>this.shadowRoot?.querySelector(e),t)}emitValueChanged(e){this.dispatchEvent(new CustomEvent(B.VALUE_CHANGED,{detail:e,bubbles:!0,composed:!0}))}get intent(){return this.intentBacker}set intent(e){const t=typeof e=="string"?e.trim():"";t!==""&&!k.includes(t)&&!this.warnedUnknownIntents.has(t)&&(this.warnedUnknownIntents.add(t),console.warn(`Espalier intent: "${t}" is not an intent; expected one of ${k.join(", ")}. Treating it as "neutral".`));const r=this.intentBacker,o=j(e);F(this,"intent",o),o!==r&&(this.intentBacker=o,this.requestUpdate("intent",r),this.applyTokensWhenRootReady())}get context(){return this.contextBacker}set context(e){const t=e??"";t!==this.contextBacker&&(this.contextBacker=t,this.applyTokensWhenRootReady(),this.refreshDescendantIntentDerivations())}refreshDescendantIntentDerivations(){const e=new Set,t=o=>{for(const s of Array.from(o.children))r(s)},r=o=>{if(!e.has(o)){if(e.add(o),o instanceof n&&o.applyTokensWhenRootReady(),o.shadowRoot&&t(o.shadowRoot),o instanceof HTMLSlotElement)for(const s of o.assignedElements({flatten:!0}))r(s);t(o)}};t(this),this.shadowRoot&&t(this.shadowRoot)}static flattenedParent(e){return e instanceof Element&&e.assignedSlot?e.assignedSlot:e instanceof ShadowRoot?e.host:e.parentNode}resolveAncestorZoneTheme(e){let t=n.flattenedParent(this);for(;t;){if(t instanceof Element&&t.localName==="esp-root")return null;if(t instanceof n){const r=t.contextBacker.trim();if(r){const o=this.resolveNamedContextTheme(e,r);if(o)return o}}t=n.flattenedParent(t)}return null}connectedCallback(){super.connectedCallback();const e=this.syncRootFromDom(!1);e&&this.subscribeToRootEvents(e)}disconnectedCallback(){super.disconnectedCallback(),this.unsubscribeFromRootEvents(),this.clearScopedTokens(),this.espRoot=null}firstUpdated(e){this.syncRootFromDom(!0),this.applyTokensWhenRootReady()}syncRootFromDom(e){const t=g(this,"esp-root");if(!t){if(this.espRoot&&this.clearScopedTokens(),this.unsubscribeFromRootEvents(),this.espRoot=null,!e)return null;throw new Error("No esp-root ancestor found. Espalier components must be placed inside an <esp-root> element.")}const r=t!==this.espRoot,s=t.scheme==="dark"?"dark":"light",a=this.scheme!==s,i=this.seedColor!==t.seedColor;return this.espRoot=t,r&&this.isConnected&&this.subscribeToRootEvents(t),(r||a||i)&&(this.scheme=s,this.seedColor=t.seedColor,this.applyTokensWhenRootReady()),r&&this.requestUpdate(),t}applyTokensWhenRootReady(){const e=this.espRoot;if(e&&(!e.hasUpdated||e.isUpdatePending)){this.applyTokensAfterInitialRootUpdate(e);return}this.applyScopedColorTokens()}applyTokensAfterInitialRootUpdate(e){if(this.pendingInitialThemeRoot===e)return;this.pendingInitialThemeRoot=e;const t=e.updateComplete;if(!t){this.pendingInitialThemeRoot=null,this.applyScopedColorTokens();return}t.then(()=>{this.pendingInitialThemeRoot===e&&(this.pendingInitialThemeRoot=null),!(!this.isConnected||this.espRoot!==e)&&(this.scheme=e.scheme==="dark"?"dark":"light",this.seedColor=e.seedColor,this.applyScopedColorTokens())})}subscribeToRootEvents(e){this.rootEventSubscriptionsActive&&this.subscribedRoot===e||(this.unsubscribeFromRootEvents(),this.subscribedRoot=e,this.rootEventUnsubscribers=[p(e,"seed-color-changed",this.handleSeedColorChanged),p(e,"scheme-changed",this.handleSchemeChanged),p(e,"theme-changed",this.handleThemeChanged),p(e,"icon-sprite-url-changed",this.handleIconSpriteUrlChanged)],this.rootEventSubscriptionsActive=!0)}unsubscribeFromRootEvents(){if(this.rootEventSubscriptionsActive){for(const e of this.rootEventUnsubscribers)e();this.rootEventUnsubscribers=[],this.subscribedRoot=null,this.rootEventSubscriptionsActive=!1}}constructor(){super(),this.seedColorBacker="oklch(0.7 0.125 216)",this.espRoot=null,this.contextBacker="",this.scopedTokenOriginalValues=new Map,this.warnedUnknownContexts=new Set,this.pendingInitialThemeRoot=null,this.rootEventSubscriptionsActive=!1,this.subscribedRoot=null,this.rootEventUnsubscribers=[],this.intentBacker="neutral",this.intentEmitsTokens=!0,this.warnedUnknownIntents=new Set,this.correlationId=globalThis.crypto?.randomUUID?.()??Math.random().toString(36),this.scheme="light",this.handleSeedColorChanged=e=>{this.syncRootFromDom(!1)&&(this.seedColor=e.seedColor,this.applyScopedColorTokens())},this.handleSchemeChanged=e=>{!this.syncRootFromDom(!1)||this.scheme===e.scheme||(this.scheme=e.scheme,this.applyScopedColorTokens())},this.handleThemeChanged=()=>{this.syncRootFromDom(!1)&&this.applyScopedColorTokens()},this.handleIconSpriteUrlChanged=()=>{this.syncRootFromDom(!1)&&this.requestUpdate()},new E(this,{reactToSpriteChanges:!1})}traverseToClosest(e){return g(this,e)}applyScopedColorTokens(){if(!this.espRoot)return;const e=this.intentEmitsTokens?n.intentColorSources[this.intentBacker]:"";if(!e&&!this.context.trim()){this.clearScopedTokens();return}const t=this.espRoot.activeTheme;if(!t){this.clearScopedTokens();return}const r=this.resolveContextTheme(t),o=r.theme,s=w(o.seedColor);if(!s)return;const a=v(s,o),i={};if(r.applied&&(Object.assign(i,m(o,a)),Object.assign(i,I(o)),Object.assign(i,O),Object.assign(i,A),Object.assign(i,V(i,U(o,s,l=>(typeof l=="string"?_(l,o.anchors):null)??o.seedColor)))),e){let l=o;r.applied||(l=this.resolveAncestorZoneTheme(t)??o);const b=l===o?a:v(s,l),T=m(l,b,{effectiveSource:(u,h)=>n.semanticActionTokens.has(u)?e:h});i["--esp-color-primary"]=P(x(b[e]));for(const u of n.semanticActionTokens){const h=D(u);i[h]=T[h]}}this.applyScopedTokenProperties(i)}resolveContextTheme(e){const t=this.context.trim();if(!t)return{applied:!1,theme:e};const r=this.resolveNamedContextTheme(e,t);return r?{applied:!0,theme:r}:(this.warnUnknownContextWhenSettled(t),{applied:!1,theme:e})}warnUnknownContextWhenSettled(e){if(this.warnedUnknownContexts.has(e))return;const t=this.espRoot;if(t&&!t.themeSettled){t.whenThemeSettled().then(()=>{if(!this.isConnected||this.espRoot!==t||this.context.trim()!==e)return;const r=t.activeTheme;r&&y(r,e)||this.warnUnknownContextWhenSettled(e)});return}this.warnedUnknownContexts.add(e),console.warn(`Espalier context: "${e}" is not defined by the active theme; inheriting root tokens.`)}resolveNamedContextTheme(e,t){return y(e,t)}applyScopedTokenProperties(e){for(const t of this.scopedTokenOriginalValues.keys())t in e||this.restoreScopedTokenProperty(t);for(const[t,r]of Object.entries(e))this.setScopedTokenProperty(t,r)}setScopedTokenProperty(e,t){const r=this.scopedTokenOriginalValues.get(e);if(r){const o=this.style.getPropertyValue(e),s=this.style.getPropertyPriority(e);(o!==r.generatedValue||s!==r.generatedPriority)&&(r.originalValue=o.length?o:null,r.originalPriority=s),r.generatedValue=t,r.generatedPriority=""}else{const o=this.style.getPropertyValue(e);this.scopedTokenOriginalValues.set(e,{generatedPriority:"",generatedValue:t,originalPriority:this.style.getPropertyPriority(e),originalValue:o.length?o:null})}this.style.setProperty(e,t)}restoreScopedTokenProperty(e){const t=this.scopedTokenOriginalValues.get(e);if(!t)return;const r=this.style.getPropertyValue(e),o=this.style.getPropertyPriority(e);(r!==t.generatedValue||o!==t.generatedPriority)&&(t.originalValue=r.length?r:null,t.originalPriority=o),t.originalValue===null?this.style.removeProperty(e):this.style.setProperty(e,t.originalValue,t.originalPriority),this.scopedTokenOriginalValues.delete(e)}clearScopedTokens(){for(const e of[...this.scopedTokenOriginalValues.keys()])this.restoreScopedTokenProperty(e)}}n.intentColorSources={danger:"danger",info:"info",neutral:"",success:"success",warning:"warning"},n.semanticActionTokens=new Set(["actionBackground","actionText"]),n.styles=[N(".esp-field:focus-within","--esp-field-focus-shadow"),z,R`
+var c=function(f,e,t,r){var o=arguments.length,s=o<3?e:r===null?r=Object.getOwnPropertyDescriptor(e,t):r,a;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(f,e,t,r);else for(var i=f.length-1;i>=0;i--)(a=f[i])&&(s=(o<3?a(s):o>3?a(e,t,s):a(e,t))||s);return o>3&&s&&Object.defineProperty(e,t,s),s};import{css as C,LitElement as S}from"lit";import{property as h,state as w}from"lit/decorators.js";import{subscribeToRootEvent as p}from"./root-event-subscription.js";import{traverseToClosest as b}from"./utilities.js";import{parseCssColor as P,serializeOklch as x,gamutMapToSRGB as E}from"./color-engine.js";import{computeVariants as m}from"../root/helpers/compute-variants.js";import{computeSemanticProperties as v}from"../root/helpers/compute-semantic-properties.js";import{DocumentSpriteController as V}from"./document-sprite.js";import{dataCompanionProperties as U}from"../root/helpers/data-companion-properties.js";import{dataSeriesProperties as _}from"../root/helpers/compute-theme-properties.js";import{lightnessRampProperties as I}from"../root/helpers/lightness-ramp-properties.js";import{ELEVATION_PROPERTIES as A,TYPE_ROLE_COLOR_PROPERTIES as O}from"./scale-engine.js";import{resolveContextTheme as y,resolveDataColorSource as D,semanticToCSS as z}from"./theme.js";import{alignAttributeTextInheritance as N,focusRing as F}from"./style-fragments.js";import{syncNormalizedAttribute as j}from"./attribute-helpers.js";import{INTENT_VARIANTS as k,normalizeIntentVariant as B}from"./intent-values.js";import{ESP_EVENTS as W}from"./events.js";import{surfaceLayerAttributes as R,surfaceLayerColor as L}from"./surface-layer.js";class n extends S{get seedColor(){return this.seedColorBacker}set seedColor(e){this.seedColorBacker=e}focusResolvedElementAfterUpdate(e,t){const r=()=>{const o=e();return o?(o.focus(t),!0):!1};r()||this.updateComplete.then(()=>{r()})}focusShadowElementAfterUpdate(e,t){this.focusResolvedElementAfterUpdate(()=>this.shadowRoot?.querySelector(e),t)}emitValueChanged(e){this.dispatchEvent(new CustomEvent(W.VALUE_CHANGED,{detail:e,bubbles:!0,composed:!0}))}get intent(){return this.intentBacker}set intent(e){const t=typeof e=="string"?e.trim():"";t!==""&&!k.includes(t)&&!this.warnedUnknownIntents.has(t)&&(this.warnedUnknownIntents.add(t),console.warn(`Espalier intent: "${t}" is not an intent; expected one of ${k.join(", ")}. Treating it as "neutral".`));const r=this.intentBacker,o=B(e);j(this,"intent",o),o!==r&&(this.intentBacker=o,this.requestUpdate("intent",r),this.applyTokensWhenRootReady())}get context(){return this.contextBacker}set context(e){const t=e??"";t!==this.contextBacker&&(this.contextBacker=t,this.applyTokensWhenRootReady(),this.refreshDescendantIntentDerivations())}refreshDescendantIntentDerivations(){const e=new Set,t=o=>{for(const s of Array.from(o.children))r(s)},r=o=>{if(!e.has(o)){if(e.add(o),o instanceof n&&o.applyTokensWhenRootReady(),o.shadowRoot&&t(o.shadowRoot),o instanceof HTMLSlotElement)for(const s of o.assignedElements({flatten:!0}))r(s);t(o)}};t(this),this.shadowRoot&&t(this.shadowRoot)}static flattenedParent(e){return e instanceof Element&&e.assignedSlot?e.assignedSlot:e instanceof ShadowRoot?e.host:e.parentNode}resolveAncestorZoneTheme(e){let t=n.flattenedParent(this);for(;t;){if(t instanceof Element&&t.localName==="esp-root")return null;if(t instanceof n){const r=t.contextBacker.trim();if(r){const o=this.resolveNamedContextTheme(e,r);if(o)return o}}t=n.flattenedParent(t)}return null}connectedCallback(){super.connectedCallback();const e=this.syncRootFromDom(!1);e&&this.subscribeToRootEvents(e)}disconnectedCallback(){super.disconnectedCallback(),this.unsubscribeFromRootEvents(),this.clearScopedTokens(),this.espRoot=null}firstUpdated(e){this.syncRootFromDom(!0),this.applyTokensWhenRootReady()}syncRootFromDom(e){const t=b(this,"esp-root");if(!t){if(this.espRoot&&this.clearScopedTokens(),this.unsubscribeFromRootEvents(),this.espRoot=null,!e)return null;throw new Error("No esp-root ancestor found. Espalier components must be placed inside an <esp-root> element.")}const r=t!==this.espRoot,s=t.scheme==="dark"?"dark":"light",a=this.scheme!==s,i=this.seedColor!==t.seedColor;return this.espRoot=t,r&&this.isConnected&&this.subscribeToRootEvents(t),(r||a||i)&&(this.scheme=s,this.seedColor=t.seedColor,this.applyTokensWhenRootReady()),r&&this.requestUpdate(),t}applyTokensWhenRootReady(){const e=this.espRoot;if(e&&(!e.hasUpdated||e.isUpdatePending)){this.applyTokensAfterInitialRootUpdate(e);return}this.applyScopedColorTokens()}applyTokensAfterInitialRootUpdate(e){if(this.pendingInitialThemeRoot===e)return;this.pendingInitialThemeRoot=e;const t=e.updateComplete;if(!t){this.pendingInitialThemeRoot=null,this.applyScopedColorTokens();return}t.then(()=>{this.pendingInitialThemeRoot===e&&(this.pendingInitialThemeRoot=null),!(!this.isConnected||this.espRoot!==e)&&(this.scheme=e.scheme==="dark"?"dark":"light",this.seedColor=e.seedColor,this.applyScopedColorTokens())})}subscribeToRootEvents(e){this.rootEventSubscriptionsActive&&this.subscribedRoot===e||(this.unsubscribeFromRootEvents(),this.subscribedRoot=e,this.rootEventUnsubscribers=[p(e,"seed-color-changed",this.handleSeedColorChanged),p(e,"scheme-changed",this.handleSchemeChanged),p(e,"theme-changed",this.handleThemeChanged),p(e,"icon-sprite-url-changed",this.handleIconSpriteUrlChanged)],this.rootEventSubscriptionsActive=!0)}unsubscribeFromRootEvents(){if(this.rootEventSubscriptionsActive){for(const e of this.rootEventUnsubscribers)e();this.rootEventUnsubscribers=[],this.subscribedRoot=null,this.rootEventSubscriptionsActive=!1}}constructor(){super(),this.seedColorBacker="oklch(0.7 0.125 216)",this.espRoot=null,this.contextBacker="",this.scopedTokenOriginalValues=new Map,this.warnedUnknownContexts=new Set,this.pendingInitialThemeRoot=null,this.rootEventSubscriptionsActive=!1,this.subscribedRoot=null,this.rootEventUnsubscribers=[],this.intentBacker="neutral",this.intentEmitsTokens=!0,this.warnedUnknownIntents=new Set,this.correlationId=globalThis.crypto?.randomUUID?.()??Math.random().toString(36),this.scheme="light",this.handleSeedColorChanged=e=>{this.syncRootFromDom(!1)&&(this.seedColor=e.seedColor,this.applyScopedColorTokens())},this.handleSchemeChanged=e=>{!this.syncRootFromDom(!1)||this.scheme===e.scheme||(this.scheme=e.scheme,this.applyScopedColorTokens())},this.handleThemeChanged=()=>{this.syncRootFromDom(!1)&&this.applyScopedColorTokens()},this.handleIconSpriteUrlChanged=()=>{this.syncRootFromDom(!1)&&this.requestUpdate()},new V(this,{reactToSpriteChanges:!1})}traverseToClosest(e){return b(this,e)}applyScopedColorTokens(){if(!this.espRoot)return;const e=this.intentEmitsTokens?n.intentColorSources[this.intentBacker]:"";if(!e&&!this.context.trim()){this.clearScopedTokens();return}const t=this.espRoot.activeTheme;if(!t){this.clearScopedTokens();return}const r=this.resolveContextTheme(t),o=r.theme,s=P(o.seedColor);if(!s)return;const a=m(s,o),i={};if(r.applied&&(Object.assign(i,v(o,a)),Object.assign(i,I(o)),Object.assign(i,A),Object.assign(i,O),Object.assign(i,U(i,_(o,s,l=>(typeof l=="string"?D(l,o.anchors):null)??o.seedColor)))),e){let l=o;r.applied||(l=this.resolveAncestorZoneTheme(t)??o);const g=l===o?a:m(s,l),T=v(l,g,{effectiveSource:(u,d)=>n.semanticActionTokens.has(u)?e:d});i["--esp-color-primary"]=x(E(g[e]));for(const u of n.semanticActionTokens){const d=z(u);i[d]=T[d]}}this.applyScopedTokenProperties(i)}resolveContextTheme(e){const t=this.context.trim();if(!t)return{applied:!1,theme:e};const r=this.resolveNamedContextTheme(e,t);return r?{applied:!0,theme:r}:(this.warnUnknownContextWhenSettled(t),{applied:!1,theme:e})}warnUnknownContextWhenSettled(e){if(this.warnedUnknownContexts.has(e))return;const t=this.espRoot;if(t&&!t.themeSettled){t.whenThemeSettled().then(()=>{if(!this.isConnected||this.espRoot!==t||this.context.trim()!==e)return;const r=t.activeTheme;r&&y(r,e)||this.warnUnknownContextWhenSettled(e)});return}this.warnedUnknownContexts.add(e),console.warn(`Espalier context: "${e}" is not defined by the active theme; inheriting root tokens.`)}resolveNamedContextTheme(e,t){return y(e,t)}applyScopedTokenProperties(e){for(const t of this.scopedTokenOriginalValues.keys())t in e||this.restoreScopedTokenProperty(t);for(const[t,r]of Object.entries(e))this.setScopedTokenProperty(t,r)}setScopedTokenProperty(e,t){const r=this.scopedTokenOriginalValues.get(e);if(r){const o=this.style.getPropertyValue(e),s=this.style.getPropertyPriority(e);(o!==r.generatedValue||s!==r.generatedPriority)&&(r.originalValue=o.length?o:null,r.originalPriority=s),r.generatedValue=t,r.generatedPriority=""}else{const o=this.style.getPropertyValue(e);this.scopedTokenOriginalValues.set(e,{generatedPriority:"",generatedValue:t,originalPriority:this.style.getPropertyPriority(e),originalValue:o.length?o:null})}this.style.setProperty(e,t)}restoreScopedTokenProperty(e){const t=this.scopedTokenOriginalValues.get(e);if(!t)return;const r=this.style.getPropertyValue(e),o=this.style.getPropertyPriority(e);(r!==t.generatedValue||o!==t.generatedPriority)&&(t.originalValue=r.length?r:null,t.originalPriority=o),t.originalValue===null?this.style.removeProperty(e):this.style.setProperty(e,t.originalValue,t.originalPriority),this.scopedTokenOriginalValues.delete(e)}clearScopedTokens(){for(const e of[...this.scopedTokenOriginalValues.keys()])this.restoreScopedTokenProperty(e)}}n.intentColorSources={danger:"danger",info:"info",neutral:"",success:"success",warning:"warning"},n.semanticActionTokens=new Set(["actionBackground","actionText"]),n.styles=[R(":host"),R("[surface-layer]"),F(".esp-field:focus-within","--esp-field-focus-shadow"),N,C`
       :host {
         
         --_esp-font-body-fallback: system-ui, sans-serif;
         --_esp-font-monospace-fallback: monospace;
-
-        
-        --_esp-field-resolved-hover-bg: var(
-          --esp-field-hover-bg,
-          oklch(from var(--esp-field-background, var(--esp-color-layer-2)) calc(l * 0.88) c h)
-        );
-        --_esp-field-resolved-focus-bg: var(
-          --esp-field-focus-bg,
-          oklch(from var(--esp-field-background, var(--esp-color-layer-2)) calc(l * 0.82) c h)
-        );
-
         display: block;
 
         * {
@@ -21,21 +10,6 @@ var c=function(f,e,t,r){var o=arguments.length,s=o<3?e:r===null?r=Object.getOwnP
         }
       }
 
-      :host([scheme="light"]) {
-        --_esp-field-resolved-hover-bg: var(
-          --esp-field-hover-bg,
-          oklch(
-            from var(--esp-field-background, var(--esp-color-layer-2)) calc(l + (1 - l) * 0.5) c h
-          )
-        );
-        --_esp-field-resolved-focus-bg: var(
-          --esp-field-focus-bg,
-          oklch(
-            from var(--esp-field-background, var(--esp-color-layer-2)) calc(l + (1 - l) * 0.75) c h
-          )
-        );
-      }
-
       ::placeholder {
         color: var(--esp-color-headings);
       }
@@ -68,13 +42,25 @@ var c=function(f,e,t,r){var o=arguments.length,s=o<3?e:r===null?r=Object.getOwnP
       }
 
       .esp-field {
+        --_esp-field-resolved-background: var(--esp-field-background, ${L(2)});
+
+        
+        --_esp-field-resolved-hover-bg: var(
+          --esp-field-hover-bg,
+          oklch(from var(--_esp-field-resolved-background) calc(l * 0.88) c h)
+        );
+        --_esp-field-resolved-focus-bg: var(
+          --esp-field-focus-bg,
+          oklch(from var(--_esp-field-resolved-background) calc(l * 0.82) c h)
+        );
+
         font-family: var(
           --_esp-font-body-effective,
           var(--esp-font-body, var(--_esp-font-body-fallback))
         );
         font-size: var(--esp-size-font);
         font-weight: var(--esp-font-weight-body);
-        background-color: var(--esp-field-background, var(--esp-color-layer-2));
+        background-color: var(--_esp-field-resolved-background);
         border-radius: var(--esp-size-border-radius);
         border: var(--esp-field-border-width, 1px) solid
           var(--esp-field-border-color, var(--esp-color-border));
@@ -125,6 +111,17 @@ var c=function(f,e,t,r){var o=arguments.length,s=o<3?e:r===null?r=Object.getOwnP
         }
       }
 
+      :host([scheme="light"]) .esp-field {
+        --_esp-field-resolved-hover-bg: var(
+          --esp-field-hover-bg,
+          oklch(from var(--_esp-field-resolved-background) calc(l + (1 - l) * 0.5) c h)
+        );
+        --_esp-field-resolved-focus-bg: var(
+          --esp-field-focus-bg,
+          oklch(from var(--_esp-field-resolved-background) calc(l + (1 - l) * 0.75) c h)
+        );
+      }
+
       .esp-field:has(button:disabled),
       .esp-field:has(a:disabled),
       .esp-field:has(input:disabled),
@@ -136,6 +133,6 @@ var c=function(f,e,t,r){var o=arguments.length,s=o<3?e:r===null?r=Object.getOwnP
       .esp-field:has(a:disabled):hover,
       .esp-field:has(input:disabled):hover,
       .esp-field:has(textarea:disabled):hover {
-        background-color: var(--esp-field-background, var(--esp-color-layer-2));
+        background-color: var(--_esp-field-resolved-background);
       }
-    `],c([S()],n.prototype,"seedColor",null),c([d({attribute:!1})],n.prototype,"correlationId",void 0),c([d({type:String,reflect:!0})],n.prototype,"scheme",void 0),c([d({type:String,attribute:"intent",reflect:!0,useDefault:!0})],n.prototype,"intent",null),c([d({type:String,attribute:"context",reflect:!0})],n.prototype,"context",null);export{n as EspalierElementBase};
+    `],c([w()],n.prototype,"seedColor",null),c([h({attribute:!1})],n.prototype,"correlationId",void 0),c([h({type:String,reflect:!0})],n.prototype,"scheme",void 0),c([h({type:String,attribute:"intent",reflect:!0,useDefault:!0})],n.prototype,"intent",null),c([h({type:String,attribute:"context",reflect:!0})],n.prototype,"context",null);export{n as EspalierElementBase};

package/dist/shared/justified-layout.d.ts

@@ -67,25 +67,13 @@ export declare function normalizeAlbumMaxRowHeightVh(value: unknown): number;
  */
 export declare function normalizeMaxImagesPerRow(value: unknown, fallback?: number, maximum?: number): number;
 /**
- * Compute justified album rows with explicit cell widths.
+ * Compute justified album rows and the geometry a renderer needs for cropping.
  *
- * Algorithm:
- * 1. Add images to a row one at a time, scaled to the target row height.
- * 2. When the combined width overflows the container, the row breaks either
- *    before or after the overflowing image — whichever leaves the row height
- *    closer to the target. Keeping the image shrinks the row slightly below
- *    target; pushing it to the next row stretches the row above target.
- * 3. Scale the finished row so it fills the container width exactly.
+ * Completed rows fill the available width. A row capped by `maxRowHeight` keeps
+ * relative cell widths, allowing `object-fit: cover` to crop its images. A final
+ * row below a finite `maxImagesPerRow` remains partial and preserves proportions;
+ * its height is capped by the preceding rows or target height and `maxRowHeight`.
  *
- * Completed rows always span the available width. When their justified height exceeds
- * `maxRowHeight`, their cells retain their relative widths while expanding to
- * the row width at the ceiling; a renderer can use `object-fit: cover` to crop
- * the resulting cells. A final row below a finite `maxImagesPerRow` instead
- * remains partial and preserves its image proportions. Its height is capped by
- * the tallest preceding row (or the target height when it is the only row) and
- * by `maxRowHeight`.
- *
- * With an omitted or invalid `maxImagesPerRow`, rows are unlimited in length
- * and every row is completed.
+ * An omitted or invalid `maxImagesPerRow` means unlimited, completed rows.
  */
 export declare function calculateAlbumLayout<T extends LayoutImage>(images: T[], options: AlbumLayoutOptions): AlbumLayoutRow<T>[];

package/dist/shared/surface-layer.d.ts

@@ -0,0 +1,12 @@
+import { type CSSResult } from "lit";
+export type SurfaceLayer = 1 | 2 | 3 | 4;
+/**
+ * Support `surface-layer="1|2|3|4"` on consumer surfaces in a shadow root.
+ * Include `surfaceLayerAttributes(":host")` for the consumer component's host,
+ * or `surfaceLayerAttributes("[surface-layer]")` for elements inside its shadow
+ * tree. Espalier installs these rules for its own hosts and root light DOM.
+ * The attribute declares depth; consumer components still paint their surface.
+ * A component that always paints a known layer can pass that depth as its
+ * default, so callers do not need to declare it on each instance.
+ */
+export declare function surfaceLayerAttributes(selector: string, defaultLayer?: SurfaceLayer): CSSResult;

package/dist/shared/surface-layer.js

@@ -0,0 +1,10 @@
+import{css as t,unsafeCSS as a}from"lit";function l(r,o){return a((o===void 0?"":`${r} { --_esp-surface-layer: ${o}; }
+`)+[1,2,3,4].map(e=>`${r===":host"?`:host([surface-layer="${e}"])`:`${r}[surface-layer="${e}"]`} { --_esp-surface-layer: ${e}; }`).join(`
+`))}function $(r,o=r){const e=["","var(--esp-color-layer-1)","var(--esp-color-layer-2)","var(--esp-color-layer-3)","var(--esp-color-layer-4)"],c=s=>s===o?e[s]:`${e[s].slice(0,-1)}, ${e[o]})`;let n=c(r);for(let s=r+1;s<=4;s++){const u=s-r;n=`color-mix(in oklch, ${n}, ${c(s)} calc(clamp(0, var(--_esp-surface-layer, 1) - ${u}, 1) * 100%))`}return a(n)}function f(r,o=":host"){return t`
+    ${a(o)} {
+      --_esp-surface-layer: ${r};
+      --_esp-surface-background: ${$(1,r)};
+    }
+    ${o===":host"?t``:a([1,2,3,4].map(e=>`:host([surface-layer="${e}"]) ${o} { --_esp-surface-layer: ${e}; }`).join(`
+`))}
+  `}export{f as paintedSurface,l as surfaceLayerAttributes,$ as surfaceLayerColor};

package/dist/shared/theme.d.ts

@@ -254,19 +254,11 @@ export type PartialThemeContexts = Record<string, ThemeContext | undefined>;
 /** Ordered role names, for validation and iteration. */
 export declare const ROLE_NAMES: readonly RoleName[];
 /**
- * Which semantic tokens each role slot paints, and at which ramp stop.
+ * Map role slots to semantic tokens and ramp stops.
  *
- * This is the compilation table: it turns five designer-facing roles
- * into the twenty-three engine-room tokens. `dangerText` is absent by
- * design — the status family is reserved and keeps its own source.
- *
- * The `accent` role has no body-text slot on purpose. "Rose is
- * decorative only" is a structural guarantee here, not a comment: text
- * that must come from the accent family comes through `accent.text`,
- * the deepened variant a designer picked for legibility. `accent.hover`
- * lets a hover change *family*, not just lightness — "plum link, rose
- * hover" is an ordinary brand rule (ESP0172); absent, `linkHover` keeps
- * following `accent.text` exactly as before.
+ * `dangerText` stays outside the roles layer because status meanings are reserved.
+ * Accent body copy must use the legible `accent.text` slot. `accent.hover` can
+ * select a different family; without it, hovered links follow `accent.text`.
  */
 export declare const ROLE_TOKEN_PLAN: Readonly<Record<RoleName, Readonly<Record<string, ReadonlyArray<[SemanticColorName, LightnessKey]>>>>>;
 /**
@@ -323,13 +315,10 @@ interface CompileRoleOptions {
     actionSurfacePole?: (source: MappingSource, lightness: number) => "dark" | "light";
 }
 /**
- * Compile roles into semantic mappings.
+ * Compile declared roles into semantic mappings.
  *
- * Only the tokens a declared role owns are emitted, so a theme that
- * declares no roles compiles to nothing and every existing theme keeps
- * its exact output. Token-level `semanticMappings` layer over the
- * result — the engine room stays available for the cases roles do not
- * reach.
+ * A theme with no roles produces no role overrides. Token-level
+ * `semanticMappings` take precedence over the compiled result.
  */
 export declare function compileRoles(roles: ThemeRoles, lightness: LightnessMap, baseMappings: SemanticMappings, options?: CompileRoleOptions): Partial<SemanticMappings>;
 /**

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

@@ -2,10 +2,8 @@ import { type PropertyValues } from "lit";
 import { EspalierElementBase } from "../shared/esp-element-base.js";
 import { type EspalierFormField } from "../form-item/esp-form-item.js";
 /**
- * A range slider for selecting numeric values. Built entirely from
- * custom elements with ARIA `role="slider"` — no native
- * `<input type="range">` — for consistent cross-browser styling and
- * intentional touch interaction.
+ * A numeric range slider with ARIA `role="slider"`, keyboard support,
+ * and separate touch and pointer behavior.
  *
  * On touch devices, only dragging the thumb changes the value.
  * Tapping the track is ignored so the user can scroll the page

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

@@ -7,8 +7,7 @@ declare const STACK_ALIGNS: readonly ["start", "center", "end", "stretch"];
 export type EspalierAlign = (typeof STACK_ALIGNS)[number];
 export { STACK_GAPS, STACK_ALIGNS };
 /**
- * A vertical flow: children stack in a column with a themed gap —
- * "column, gap X" without writing flexbox (ADR-010's micro half).
+ * Stacks children vertically with a themed gap.
  *
  * ```html
  * <esp-stack gap="medium">

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

@@ -1,10 +1,8 @@
 import { EspalierElementBase } from "../shared/esp-element-base.js";
 import { type EspalierFormField } from "../form-item/esp-form-item.js";
 /**
- * A toggle switch for boolean on/off values. Uses a CSS-only
- * track-and-thumb design with a smooth sliding transition.
- * Functionally equivalent to a checkbox but visually communicates
- * an immediate state change rather than a deferred selection.
+ * An on/off switch for settings that take effect immediately. Use a
+ * checkbox when the choice should be applied with a later form submission.
  *
  * ```html
  * <esp-box>

package/dist/tabs/esp-tab-group.d.ts

@@ -6,6 +6,9 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  * generated automatically from each child's `label` attribute.
  * Only one tab panel is visible at a time.
  *
+ * A field fills one layer above the surface it sits on.
+ * Use `surface-layer="1|2|3|4"` to select the default painted layer.
+ *
  * ```html
  * <esp-tab-group>
  *   <esp-tab label="Overview">

package/dist/tabs/esp-tab-group.js

@@ -1,4 +1,4 @@
-var d=function(l,t,a,e){var s=arguments.length,r=s<3?t:e===null?e=Object.getOwnPropertyDescriptor(t,a):e,o;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(l,t,a,e);else for(var n=l.length-1;n>=0;n--)(o=l[n])&&(r=(s<3?o(r):s>3?o(t,a,r):o(t,a))||r);return s>3&&r&&Object.defineProperty(t,a,r),r};import{css as u,html as c,nothing as v}from"lit";import{customElement as f,property as g,state as m}from"lit/decorators.js";import{createRef as y,ref as w}from"lit/directives/ref.js";import{EspalierElementBase as b}from"../shared/esp-element-base.js";import{ESP_EVENTS as x}from"../shared/events.js";import{EspalierTab as p}from"./esp-tab.js";import{disabledControl as T}from"../shared/style-fragments.js";let i=class extends b{constructor(){super(...arguments),this.panelsSlot=y(),this.disabled=!1,this.tabData=[]}getTabs(){const t=this.panelsSlot.value?Array.from(this.panelsSlot.value.assignedElements()).filter(a=>a instanceof p):[];return t.length>0?t:Array.from(this.children).filter(a=>a instanceof p)}syncTabData(){const t=this.getTabs();if(t.length===0){this.tabData=[];return}const a=t.find(e=>e.active&&!e.disabled);if(a)for(const e of t)e!==a&&(e.active=!1);else{const e=t.find(s=>!s.disabled);e?e.active=!0:t[0].active=!0}this.tabData=t.map((e,s)=>{const r=`esp-tab-btn-${this.correlationId}-${s}`,o=`esp-tab-panel-${this.correlationId}-${s}`;return e.panelId=o,e.ariaLabelledBy=r,{label:e.label,active:e.active,disabled:this.disabled||e.disabled,buttonId:r,panelId:o}})}activateTab(t){const a=this.getTabs(),e=a[t];if(!(!e||e.disabled||this.disabled)){for(const s of a)s.active=s===e;this.syncTabData(),this.dispatchEvent(new CustomEvent(x.TAB_GROUP_CHANGED,{detail:{index:t,label:e.label},bubbles:!0,composed:!0}))}}handleTabClick(t){this.activateTab(t),this.updateComplete.then(()=>{this.shadowRoot?.getElementById(this.tabData[t]?.buttonId)?.focus()})}handleKeyDown(t){if(!["ArrowLeft","ArrowRight","Home","End"].includes(t.key))return;t.preventDefault();const e=this.tabData.map((n,h)=>({td:n,i:h})).filter(({td:n})=>!n.disabled).map(({i:n})=>n);if(e.length===0)return;const s=this.tabData.findIndex(n=>n.active),r=e.indexOf(s);let o;switch(t.key){case"ArrowRight":r===-1?o=e[0]:o=e[(r+1)%e.length];break;case"ArrowLeft":r===-1?o=e[e.length-1]:o=e[(r-1+e.length)%e.length];break;case"Home":o=e[0];break;case"End":o=e[e.length-1];break;default:return}this.activateTab(o),this.updateComplete.then(()=>{this.shadowRoot?.getElementById(this.tabData[o]?.buttonId)?.focus()})}handleChildUpdated(){this.syncTabData()}handleSlotChange(){this.syncTabData()}connectedCallback(){super.connectedCallback(),this.syncTabData()}willUpdate(t){super.willUpdate(t),t.has("disabled")&&this.syncTabData()}render(){return c`
+var d=function(l,t,a,e){var s=arguments.length,r=s<3?t:e===null?e=Object.getOwnPropertyDescriptor(t,a):e,o;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(l,t,a,e);else for(var n=l.length-1;n>=0;n--)(o=l[n])&&(r=(s<3?o(r):s>3?o(t,a,r):o(t,a))||r);return s>3&&r&&Object.defineProperty(t,a,r),r};import{paintedSurface as u}from"../shared/surface-layer.js";import{css as v,html as c,nothing as f}from"lit";import{customElement as g,property as m,state as y}from"lit/decorators.js";import{createRef as w,ref as x}from"lit/directives/ref.js";import{EspalierElementBase as b}from"../shared/esp-element-base.js";import{ESP_EVENTS as T}from"../shared/events.js";import{EspalierTab as p}from"./esp-tab.js";import{disabledControl as k}from"../shared/style-fragments.js";let i=class extends b{constructor(){super(...arguments),this.panelsSlot=w(),this.disabled=!1,this.tabData=[]}getTabs(){const t=this.panelsSlot.value?Array.from(this.panelsSlot.value.assignedElements()).filter(a=>a instanceof p):[];return t.length>0?t:Array.from(this.children).filter(a=>a instanceof p)}syncTabData(){const t=this.getTabs();if(t.length===0){this.tabData=[];return}const a=t.find(e=>e.active&&!e.disabled);if(a)for(const e of t)e!==a&&(e.active=!1);else{const e=t.find(s=>!s.disabled);e?e.active=!0:t[0].active=!0}this.tabData=t.map((e,s)=>{const r=`esp-tab-btn-${this.correlationId}-${s}`,o=`esp-tab-panel-${this.correlationId}-${s}`;return e.panelId=o,e.ariaLabelledBy=r,{label:e.label,active:e.active,disabled:this.disabled||e.disabled,buttonId:r,panelId:o}})}activateTab(t){const a=this.getTabs(),e=a[t];if(!(!e||e.disabled||this.disabled)){for(const s of a)s.active=s===e;this.syncTabData(),this.dispatchEvent(new CustomEvent(T.TAB_GROUP_CHANGED,{detail:{index:t,label:e.label},bubbles:!0,composed:!0}))}}handleTabClick(t){this.activateTab(t),this.updateComplete.then(()=>{this.shadowRoot?.getElementById(this.tabData[t]?.buttonId)?.focus()})}handleKeyDown(t){if(!["ArrowLeft","ArrowRight","Home","End"].includes(t.key))return;t.preventDefault();const e=this.tabData.map((n,h)=>({td:n,i:h})).filter(({td:n})=>!n.disabled).map(({i:n})=>n);if(e.length===0)return;const s=this.tabData.findIndex(n=>n.active),r=e.indexOf(s);let o;switch(t.key){case"ArrowRight":r===-1?o=e[0]:o=e[(r+1)%e.length];break;case"ArrowLeft":r===-1?o=e[e.length-1]:o=e[(r-1+e.length)%e.length];break;case"Home":o=e[0];break;case"End":o=e[e.length-1];break;default:return}this.activateTab(o),this.updateComplete.then(()=>{this.shadowRoot?.getElementById(this.tabData[o]?.buttonId)?.focus()})}handleChildUpdated(){this.syncTabData()}handleSlotChange(){this.syncTabData()}connectedCallback(){super.connectedCallback(),this.syncTabData()}willUpdate(t){super.willUpdate(t),t.has("disabled")&&this.syncTabData()}render(){return c`
       <div class="tab-container">
         <div class="tab-list" role="tablist" part="tab-list" @keydown=${this.handleKeyDown}>
           ${this.tabData.map((t,a)=>c`
@@ -9,7 +9,7 @@ var d=function(l,t,a,e){var s=arguments.length,r=s<3?t:e===null?e=Object.getOwnP
                 part="tab-button"
                 aria-selected=${t.active?"true":"false"}
                 aria-controls=${t.panelId}
-                aria-disabled=${t.disabled?"true":v}
+                aria-disabled=${t.disabled?"true":f}
                 tabindex=${t.active?"0":"-1"}
                 ?disabled=${t.disabled}
                 @click=${()=>this.handleTabClick(a)}
@@ -20,13 +20,13 @@ var d=function(l,t,a,e){var s=arguments.length,r=s<3?t:e===null?e=Object.getOwnP
         </div>
         <div class="panels" part="panels">
           <slot
-            ${w(this.panelsSlot)}
+            ${x(this.panelsSlot)}
             @slotchange=${this.handleSlotChange}
             @esp-internal-tab-updated=${this.handleChildUpdated}
           ></slot>
         </div>
       </div>
-    `}};i.styles=[...b.styles,T(".tab-button[disabled]"),u`
+    `}};i.styles=[...b.styles,u(1),k(".tab-button[disabled]"),v`
       :host {
         display: block;
         --_esp-tab-resolved-button-hover: var(
@@ -45,7 +45,7 @@ var d=function(l,t,a,e){var s=arguments.length,r=s<3?t:e===null?e=Object.getOwnP
       .tab-container {
         
         --_esp-tab-inner-radius: max(0px, calc(var(--esp-size-border-radius) - 1px));
-        background-color: var(--esp-tab-color-background, var(--esp-color-layer-1));
+        background-color: var(--esp-tab-color-background, var(--_esp-surface-background));
         border-radius: var(--esp-size-border-radius);
         box-shadow: 1px 1px 4px var(--esp-color-shadow);
         border: 1px solid var(--esp-tab-color-border, var(--esp-color-border));
@@ -56,7 +56,7 @@ var d=function(l,t,a,e){var s=arguments.length,r=s<3?t:e===null?e=Object.getOwnP
       .tab-list {
         display: flex;
         overflow-x: auto;
-        background-color: var(--esp-tab-color-strip-background, var(--esp-color-layer-1));
+        background-color: var(--esp-tab-color-strip-background, var(--_esp-surface-background));
         border-bottom: 1px solid var(--esp-tab-color-border, var(--esp-color-border));
         border-start-start-radius: var(--_esp-tab-inner-radius);
         border-start-end-radius: var(--_esp-tab-inner-radius);
@@ -119,4 +119,4 @@ var d=function(l,t,a,e){var s=arguments.length,r=s<3?t:e===null?e=Object.getOwnP
       .panels {
         
       }
-    `],d([g({type:Boolean,reflect:!0})],i.prototype,"disabled",void 0),d([m()],i.prototype,"tabData",void 0),i=d([f("esp-tab-group")],i);export{i as EspalierTabGroup};
+    `],d([m({type:Boolean,reflect:!0})],i.prototype,"disabled",void 0),d([y()],i.prototype,"tabData",void 0),i=d([g("esp-tab-group")],i);export{i as EspalierTabGroup};

package/dist/tooltip/esp-tooltip.js

@@ -44,6 +44,7 @@ var o=function(a,e,t,n){var p=arguments.length,r=p<3?e:n===null?n=Object.getOwnP
       }
 
       .tooltip-content {
+        --_esp-surface-layer: 1;
         
         white-space: normal;
         overflow-wrap: anywhere;

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

@@ -127,11 +127,6 @@ export declare function buildWebTreePath({ parentPath, segment, rootPath, }: Esp
  * For static declarative node definitions, see
  * [`<esp-tree-item>`](/components/tree/item/).
  *
- * The name is apt: an espalier is a tree trained flat against a frame,
- * so the visual language — branches trained to vertical guide wires,
- * grafting a new shoot onto an existing limb — is the component's own
- * metaphor.
- *
  * ## Data-driven first, composition-capable
  *
  * Bind a hierarchy to the `nodes` property for the primary, data-driven

package/dist/tree/esp-tree.js

@@ -311,6 +311,7 @@ var d=function(c,e,t,i){var s=arguments.length,o=s<3?e:i===null?i=Object.getOwnP
       }
 
       .row {
+        --_esp-surface-layer: 1;
         background-color: var(--esp-tree-row-bg, var(--esp-color-layer-1));
         border: 1px solid var(--esp-tree-row-border-color, var(--esp-color-border));
         border-radius: var(--esp-size-border-radius);
@@ -334,6 +335,7 @@ var d=function(c,e,t,i){var s=arguments.length,o=s<3?e:i===null?i=Object.getOwnP
       }
 
       .row:hover {
+        --_esp-surface-layer: 2;
         background-color: var(--esp-tree-hover-bg, var(--esp-color-layer-2));
         border-color: oklch(
           from var(--esp-tree-row-border-color, var(--esp-color-border)) calc(l * 1.1) c h
@@ -341,6 +343,7 @@ var d=function(c,e,t,i){var s=arguments.length,o=s<3?e:i===null?i=Object.getOwnP
       }
 
       .row.selected {
+        --_esp-surface-layer: 3;
         border-color: var(--esp-color-primary);
         background-color: var(--esp-tree-selected-bg, var(--esp-color-layer-3));
       }

package/espalier.css-data.json

@@ -471,7 +471,7 @@
     },
     {
       "name": "--esp-field-background",
-      "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`."
+      "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins."
     },
     {
       "name": "--esp-field-border-color",
@@ -989,6 +989,14 @@
       "name": "--esp-header-z-index",
       "description": "The z-index of the header host. Defaults to `20`."
     },
+    {
+      "name": "--esp-image-banner-block-size",
+      "description": "A soft height target for a banner: it replaces the ratio as the banner height (viewport-fill banners), and copy that would not fit grows the banner past it. In the compact band it sizes only the image box. Unlike `block-size`, it never clips copy. Defaults to none."
+    },
+    {
+      "name": "--esp-image-banner-max-block-size",
+      "description": "A soft height cap for a banner: the ratio-sized height is the smaller of the ratio height and this length, and copy that would not fit (spacing included) grows the banner past it. In the compact band it caps only the image box. Unlike `max-block-size`, it never clips copy. Defaults to none."
+    },
     {
       "name": "--esp-image-border",
       "description": "Border; defaults to `2px solid var(--esp-color-border)` or none in banner mode."

package/espalier.token-manifest.json

@@ -636,7 +636,7 @@
     {
       "name": "--esp-field-background",
       "category": "shared-hook",
-      "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`."
+      "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins."
     },
     {
       "name": "--esp-field-border-color",
@@ -1398,6 +1398,18 @@
       "component": "esp-header",
       "description": "The z-index of the header host. Defaults to `20`."
     },
+    {
+      "name": "--esp-image-banner-block-size",
+      "category": "component",
+      "component": "esp-image",
+      "description": "A soft height target for a banner: it replaces the ratio as the banner height (viewport-fill banners), and copy that would not fit grows the banner past it. In the compact band it sizes only the image box. Unlike `block-size`, it never clips copy. Defaults to none."
+    },
+    {
+      "name": "--esp-image-banner-max-block-size",
+      "category": "component",
+      "component": "esp-image",
+      "description": "A soft height cap for a banner: the ratio-sized height is the smaller of the ratio height and this length, and copy that would not fit (spacing included) grows the banner past it. In the compact band it caps only the image box. Unlike `max-block-size`, it never clips copy. Defaults to none."
+    },
     {
       "name": "--esp-image-border",
       "category": "component",

package/licenses/README.md

@@ -1,36 +1,39 @@
-# Espalier Commercial Licensing Drafts
+# Licensing and commercial documents
 
-These files are draft business/legal documents for attorney review. They are
-intended to support a proprietary public package containing compiled and
-obfuscated Espalier artifacts, without publishing source code.
+The [binary license](ESPALIER_PROPRIETARY_BINARY_LICENSE.md) governs the public
+compiled package. Its approved text is recorded in
+[LICENSE_APPROVAL.json](LICENSE_APPROVAL.json); the publish gate verifies that
+the shipped text matches that approval.
 
-They are not legal advice and should not be used with customers or partners
-until reviewed and adapted by qualified IP and technology-transactions counsel.
+The order form, term sheets, and escrow addendum are commercial templates for
+attorney review. Have counsel review and adapt them before customer or partner
+use. Notices and provenance records document the assets distributed with
+Espalier.
 
 ## Documents
 
-- `ESPALIER_PROPRIETARY_BINARY_LICENSE.md` - default license for the public
+- [ESPALIER_PROPRIETARY_BINARY_LICENSE.md](ESPALIER_PROPRIETARY_BINARY_LICENSE.md) - default license for the public
   compiled package and for paid production use by direct enterprise customers.
-- `ESPALIER_ENTERPRISE_ORDER_FORM_TEMPLATE.md` - short commercial order form to
+- [ESPALIER_ENTERPRISE_ORDER_FORM_TEMPLATE.md](ESPALIER_ENTERPRISE_ORDER_FORM_TEMPLATE.md) - short commercial order form to
   pair with the binary license for direct customers.
-- `ESPALIER_STRATEGIC_PARTNER_LICENSE_TERM_SHEET.md` - draft terms for a
+- [ESPALIER_STRATEGIC_PARTNER_LICENSE_TERM_SHEET.md](ESPALIER_STRATEGIC_PARTNER_LICENSE_TERM_SHEET.md) - draft terms for a
   strategic enterprise reseller/OEM/private-label deal with a $3M+ annual
   minimum guarantee.
-- `ESPALIER_SOURCE_ESCROW_ADDENDUM.md` - source escrow terms for enterprise
+- [ESPALIER_SOURCE_ESCROW_ADDENDUM.md](ESPALIER_SOURCE_ESCROW_ADDENDUM.md) - source escrow terms for enterprise
   reassurance without giving source away in the ordinary case.
-- `ESPALIER_SOURCE_SNAPSHOT_PURCHASE_TERM_SHEET.md` - draft terms for a
+- [ESPALIER_SOURCE_SNAPSHOT_PURCHASE_TERM_SHEET.md](ESPALIER_SOURCE_SNAPSHOT_PURCHASE_TERM_SHEET.md) - draft terms for a
   $20M+ one-time source snapshot transaction while preserving Taproot's
   continuing ownership and future development rights unless counsel negotiates
   a broader sale.
-- `ESPALIER_DEAL_READINESS_CHECKLIST.md` - practical readiness checklist for
+- [ESPALIER_DEAL_READINESS_CHECKLIST.md](ESPALIER_DEAL_READINESS_CHECKLIST.md) - practical readiness checklist for
   lawyer review, diligence, packaging, and outreach.
-- `THIRD_PARTY_NOTICES.md` - third-party open-source notices for materials
+- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) - third-party open-source notices for materials
   copied into Espalier distribution artifacts, including Lit Virtualizer,
   Tabler Icons, and the self-hosted documentation shell fonts.
-- `asset-provenance.json` and `ASSET_PROVENANCE.md` - machine-readable and
+- [asset-provenance.json](asset-provenance.json) and [ASSET_PROVENANCE.md](ASSET_PROVENANCE.md) - machine-readable and
   human-readable provenance records for generated fonts, icons, vendored
   runtime source, textures, demo datasets, and docs assets.
-- `open-source-audit/` - preserved dependency/license audit material for
+- [open-source-audit/](open-source-audit/) - preserved dependency/license audit material for
   open-source diligence, SBOM planning, and third-party notice review.
 
 ## Commercial Position

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "6.1.0",
+  "version": "6.3.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",
@@ -373,6 +373,10 @@
     "./textures/espalier-paper.png": "./css/textures/espalier-paper.png",
     "./textures/espalier-grain.png": "./css/textures/espalier-grain.png",
     "./textures/espalier-grunge.png": "./css/textures/espalier-grunge.png",
+    "./shared/surface-layer": {
+      "types": "./dist/shared/surface-layer.d.ts",
+      "import": "./dist/shared/surface-layer.js"
+    },
     "./custom-elements.json": "./custom-elements.json",
     "./espalier.css-data.json": "./espalier.css-data.json",
     "./css/esp-reset.css": "./css/esp-reset.css",