@taprootio/espalier 6.2.0 → 6.4.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

@@ -469,9 +469,25 @@
       "name": "--esp-dialog-bg-opacity",
       "description": "The opacity of the dialog overlay background."
     },
+    {
+      "name": "--esp-dialog-inset-block-end",
+      "description": "The bottom edge of the area the dialog covers, as a length from the viewport bottom. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-block-start",
+      "description": "The top edge of the area the dialog covers, as a length from the viewport top. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-inline-end",
+      "description": "The trailing edge (right in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-inline-start",
+      "description": "The leading edge (left in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`."
+    },
     {
       "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",

package/espalier.token-manifest.json

@@ -633,10 +633,34 @@
       "component": "esp-dialog",
       "description": "The opacity of the dialog overlay background."
     },
+    {
+      "name": "--esp-dialog-inset-block-end",
+      "category": "component",
+      "component": "esp-dialog",
+      "description": "The bottom edge of the area the dialog covers, as a length from the viewport bottom. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-block-start",
+      "category": "component",
+      "component": "esp-dialog",
+      "description": "The top edge of the area the dialog covers, as a length from the viewport top. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-inline-end",
+      "category": "component",
+      "component": "esp-dialog",
+      "description": "The trailing edge (right in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`."
+    },
+    {
+      "name": "--esp-dialog-inset-inline-start",
+      "category": "component",
+      "component": "esp-dialog",
+      "description": "The leading edge (left in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`."
+    },
     {
       "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",

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.2.0",
+  "version": "6.4.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",