@taprootio/espalier 6.2.0 → 6.4.0

package/dist/menu/esp-menu.js

@@ -1,4 +1,4 @@
-var l=function(g,e,t,i){var r=arguments.length,s=r<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,n;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(g,e,t,i);else for(var o=g.length-1;o>=0;o--)(n=g[o])&&(s=(r<3?n(s):r>3?n(e,t,s):n(e,t))||s);return r>3&&s&&Object.defineProperty(e,t,s),s},y;import{css as N,html as f,nothing as w}from"lit";import{customElement as M,property as c,state as F}from"lit/decorators.js";import{classMap as x}from"lit/directives/class-map.js";import{unsafeHTML as z}from"lit/directives/unsafe-html.js";import{createRef as p,ref as u}from"lit/directives/ref.js";import{styleMap as k}from"lit/directives/style-map.js";import{EspalierElementBase as P}from"../shared/esp-element-base.js";import{ESP_EVENTS as S}from"../shared/events.js";import{getEspBus as I}from"../shared/bus-events.js";import{normalizePath as $,pathStartsWithSegment as R,pathsMatch as O}from"../shared/path-matching.js";import{renderConfiguredBrand as L}from"../shared/configured-brand.js";import{FOCUSABLE_SELECTOR as A,OverlayController as T}from"../shared/overlay-controller.js";import{SwipeRevealController as _}from"./swipe-reveal-controller.js";import"./esp-menu-item.js";import"./esp-menu-group.js";import"../burger/esp-burger.js";import{EspalierMenuItem as E}from"./esp-menu-item.js";import{EspalierMenuGroup as v}from"./esp-menu-group.js";import{COMPACT_VIEWPORT_MEDIA_QUERY as G}from"../shared/responsive.js";import{RafThrottle as H}from"../shared/raf-throttle.js";import{viewportSize as q}from"../shared/viewport.js";import{solveDrawerNestedFit as B}from"./drawer-nested-fit.js";const K=new Set(["panel","full-screen"]),U=new Set(["fade","slide-down","slide-up","slide-left","slide-right"]);let a=y=class extends P{ownsDrawerLock(){return this.isFullScreenDrawer}fullScreenInertAnchor(){return y.inertAnchorFor(this)}static inertAnchorFor(e){let t=e,i=e;for(;;){const r=i.parentElement;if(r){if(r.localName==="esp-page"||r.localName==="esp-root")return i;r===document.body&&(t=i),i=r;continue}const s=i.getRootNode();if(s instanceof ShadowRoot&&s.host instanceof HTMLElement){i=s.host;continue}return t}}constructor(){super(),this.itemsSlot=p(),this.railRef=p(),this.scrimRef=p(),this.drawerRef=p(),this.bus=I(),this.closeTransitionTimer=null,this.drawerGroupOpenOverrides=new Map,this.overlay=new T({host:this,getFocusTrapContainer:()=>this.drawerRef.value??null,getFocusScope:()=>this.fullScreenFocusScope(),getInertAnchor:()=>this.fullScreenInertAnchor(),promote:!1,scrollLock:{preserveScrollPosition:!0}}),this.fullScreenSession=!1,this.openedFullScreen=!1,this.drawerKeydownAttached=!1,this.nestedFitProbe=p(),this.nestedFitCapProbe=p(),this.nestedFitFloorProbe=p(),this.nestedFitPadProbe=p(),this.nestedFitTextProbe=p(),this.nestedFit=null,this.nestedFitMeasured=!1,this.nestedFitIdleHandle=null,this.nestedFitFallback=null,this.nestedFitResize=new H(()=>this.measureNestedFit()),this.nestedFitObserver=null,this.onNestedFitResize=()=>{this.drawerPresentation==="full-screen"&&this.nestedFitResize.schedule()},this.onNestedFitFontsLoaded=()=>this.scheduleNestedFit(!0),this.onOverlayOpened=e=>{if(e===this.overlay||!this.drawerOpen)return;const t=this.drawerTrigger;this.drawerTrigger=null,t&&e.redirectFocusRestore(t),this.swipeController.closeForHandoff(),this.onDrawerTransitionEnd()},this._sliding=!1,this._mobileCollapsed=!1,this.verticalDrawerQuery=null,this.onVerticalDrawerChange=e=>this.setMobileCollapsed(e.matches),this.mode="horizontal",this.overflow="auto",this.side="left",this.drawerPresentation="panel",this.fullScreenTransition="fade",this.drawerBrand=null,this.liftedCloseControl=null,this.ariaLabel=null,this.autoExpand=!1,this.drawerOpen=!1,this.drawerShown=!1,this.drawerTransitioning=!1,this.drawerTrigger=null,this.hasExternalDrawerControl=!1,this.previewCollapseRequested=!1,this.getWidth=()=>{const e=this.railRef.value;return e?Math.max(e.scrollWidth,e.clientWidth):-1},this.onDrawerKeydown=e=>{!this.drawerOpen||!this.openedFullScreen||e.key==="Tab"&&this.overlay.trapFocus(e)},this.onDrawerTransitionEnd=e=>{e&&e.target!==this.drawerRef.value||(this.closeTransitionTimer&&(clearTimeout(this.closeTransitionTimer),this.closeTransitionTimer=null),this.drawerTransitioning=!1,this.drawerOpen||(this.hideDrawerPopover(),this.drawerGroupOpenOverrides.clear()))},this.handleDrawerCloseClick=()=>{this.closeDrawer()},this.swipeController=new _(this,this.side),this.swipeController.enabled=!1}get isFullScreenDrawer(){return K.has(this.drawerPresentation)?this.drawerPresentation==="full-screen":!1}get resolvedFullScreenTransition(){return U.has(this.fullScreenTransition)?this.fullScreenTransition:"fade"}get sliding(){return this._sliding}set sliding(e){const t=this._sliding;this._sliding=e,this.syncSwipeEnabled(),this.propagateToItems(),this.requestUpdate("sliding",t)}get drawerSide(){return this.overflow==="right-drawer"?"right":this.overflow==="left-drawer"?"left":this.side}get drawerActive(){return this.mode==="drawer"||this._sliding||this.overflow==="left-drawer"||this.overflow==="right-drawer"||this.mode==="vertical"&&(this._mobileCollapsed||this.previewCollapseRequested)&&this.hasExternalDrawerControl}get railMode(){return this.mode==="horizontal"?"horizontal":"vertical"}connectedCallback(){super.connectedCallback(),this.getAttribute("slot")==="right"&&(this.side="right"),!this.verticalDrawerQuery&&typeof window<"u"&&"matchMedia"in window&&(this.verticalDrawerQuery=window.matchMedia(G),this._mobileCollapsed=this.verticalDrawerQuery.matches,this.verticalDrawerQuery.addEventListener("change",this.onVerticalDrawerChange)),this.syncSwipeEnabled(),T.addOpenListener(this.onOverlayOpened),window.addEventListener("resize",this.onNestedFitResize),typeof document<"u"&&document.fonts&&(document.fonts.addEventListener("loadingdone",this.onNestedFitFontsLoaded),document.fonts.ready.then(()=>{this.isConnected&&this.scheduleNestedFit(!0)})),!this.nestedFitObserver&&typeof MutationObserver<"u"&&(this.nestedFitObserver=new MutationObserver(()=>this.scheduleNestedFit(!0)),this.nestedFitObserver.observe(this,{subtree:!0,childList:!0,attributes:!0,attributeFilter:["label"]}))}disconnectedCallback(){T.removeOpenListener(this.onOverlayOpened),window.removeEventListener("resize",this.onNestedFitResize),document.fonts?.removeEventListener("loadingdone",this.onNestedFitFontsLoaded),this.nestedFitObserver?.disconnect(),this.nestedFitObserver=null,this.nestedFitResize.cancel(),this.cancelNestedFitIdle(),this.nestedFitMeasured=!1,this.verticalDrawerQuery?.removeEventListener("change",this.onVerticalDrawerChange),this.verticalDrawerQuery=null,this.detachDrawerKeydown(),this.fullScreenSession=!1,super.disconnectedCallback()}setMobileCollapsed(e){e!==this._mobileCollapsed&&(this._mobileCollapsed=e,this.mode==="vertical"&&this.applyMobileCollapse())}applyMobileCollapse(){this.swipeController.direction=this.drawerSide,this.syncSwipeEnabled(),this.propagateToItems(),this.requestUpdate(),!this.drawerActive&&this.drawerOpen&&this.swipeController.close(!0)}firstUpdated(e){super.firstUpdated(e),this.propagateToItems(),this.scheduleNestedFit()}updated(e){super.updated(e),(e.has("mode")||e.has("overflow")||e.has("side")||e.has("hasExternalDrawerControl")||e.has("previewCollapseRequested"))&&(this.swipeController.direction=this.drawerSide,this.syncSwipeEnabled(),this.propagateToItems(),!this.drawerActive&&this.drawerOpen&&this.swipeController.close(!0)),e.has("drawerPresentation")&&(this.nestedFitMeasured=!1,this.scheduleNestedFit()),this.drawerOpen&&this.openedFullScreen!==this.isFullScreenDrawer&&this.swipeController.close(!0),this.autoExpand&&(e.has("autoExpand")||e.has("mode")&&this.mode!=="horizontal")?this.expandToCurrentPage():this.mode==="horizontal"&&e.has("mode")&&this.closeHorizontalTopLevelGroups()}openDrawer(e){this.drawerActive&&(e?this.drawerTrigger=e:this.drawerOpen||(this.drawerTrigger=null),this.swipeController.open())}closeDrawer(){this.swipeController.close(!0)}toggleDrawer(e){this.drawerOpen?this.closeDrawer():this.openDrawer(e)}get isDrawerOpen(){return this.drawerOpen}syncSwipeEnabled(){this.swipeController.direction=this.drawerSide,this.swipeController.enabled=this.drawerActive}getAssignedChildren(){return this.itemsSlot.value?.assignedElements()??[]}propagateToItems(){const e=this.railMode;for(const t of this.getAssignedChildren())t instanceof E?(t.mode=e,t.depth=0,t.touchDevice=this.swipeController.isTouch):t instanceof v&&(t.mode=e,t.depth=0,t.touchDevice=this.swipeController.isTouch)}handleSlotChange(){this.propagateToItems(),this.scheduleNestedFit(!0)}scheduleNestedFit(e=!1){if(this.drawerPresentation!=="full-screen"){this.cancelNestedFitIdle(),this.nestedFit!==null&&(this.nestedFit=null);return}if(e&&(this.nestedFitMeasured=!1),e&&this.drawerShown){this.cancelNestedFitIdle(),this.nestedFitResize.schedule();return}if(this.nestedFitIdleHandle!==null||this.nestedFitFallback!==null)return;const t=()=>{this.nestedFitIdleHandle=null,this.nestedFitFallback=null,this.isConnected&&this.measureNestedFit()};typeof requestIdleCallback=="function"?this.nestedFitIdleHandle=requestIdleCallback(t,{timeout:2e3}):this.nestedFitFallback={stage:"frame",handle:requestAnimationFrame(()=>{this.nestedFitFallback={stage:"timeout",handle:window.setTimeout(t,0)}})}}cancelNestedFitIdle(){this.nestedFitIdleHandle!==null&&(cancelIdleCallback(this.nestedFitIdleHandle),this.nestedFitIdleHandle=null),this.nestedFitFallback!==null&&(this.nestedFitFallback.stage==="frame"?cancelAnimationFrame(this.nestedFitFallback.handle):window.clearTimeout(this.nestedFitFallback.handle),this.nestedFitFallback=null)}ensureNestedFitMeasured(){this.nestedFitMeasured||(this.cancelNestedFitIdle(),this.measureNestedFit())}collectNestedLabels(){const e=[];let t=!1;const i=(r,s)=>{for(const n of r){const o=s>0;n instanceof E?o&&e.push(n.label):n instanceof v&&(o&&(e.push(n.label),n.url&&(t=!0)),i(Array.from(n.children),s+1))}};return i(this.getAssignedChildren(),0),{labels:e,linkedGroup:t}}readNestedFitMetrics(e){const t=this.nestedFitCapProbe.value,i=this.nestedFitFloorProbe.value,r=this.nestedFitPadProbe.value,s=this.nestedFitTextProbe.value;if(!t||!i||!r||!s)return null;const n=parseFloat(getComputedStyle(t).fontSize),o=parseFloat(getComputedStyle(i).fontSize),d=getComputedStyle(r),h=parseFloat(d.paddingInlineStart),b=parseFloat(d.paddingInlineEnd);if(![n,o,h,b].every(m=>Number.isFinite(m)))return null;s.replaceChildren(...e.map(m=>{const D=document.createElement("span");return D.textContent=m,D}));const C=Array.from(s.children,m=>m.getBoundingClientRect().width);return s.replaceChildren(),{capPx:n,floorPx:o,paddingPx:h,smallPx:b,widths:C}}measureNestedFit(){if(!this.isConnected||this.drawerPresentation!=="full-screen")return;const{labels:e,linkedGroup:t}=this.collectNestedLabels();if(this.nestedFitMeasured=!0,e.length===0){this.nestedFit!==null&&(this.nestedFit=null);return}const i=this.readNestedFitMetrics(e);if(!i)return;const r=this.drawerRef.value,s=r&&this.drawerShown?r.getBoundingClientRect().width:0,n=s>0?s:q().width,o=t?2*(2*i.smallPx+4.5):0,d=n-2*i.paddingPx-o,h=B({capPx:i.capPx,floorPx:i.floorPx,availablePx:d,widestAtCapPx:Math.max(0,...i.widths)});this.nestedFit&&this.nestedFit.fontSizePx===h.fontSizePx&&this.nestedFit.wrap===h.wrap||(this.nestedFit=h)}onSwipeRevealChanged(e){e!==this.drawerOpen&&(this.drawerOpen=e,e?(this.openedFullScreen=this.isFullScreenDrawer,this.openedFullScreen&&this.ensureNestedFitMeasured(),this.drawerGroupOpenOverrides.clear(),this.bus.publish("close-popovers",{}),this.updateComplete.then(()=>this.showDrawerPopover())):(this.detachDrawerKeydown(),this.fullScreenSession&&(this.fullScreenSession=!1,this.overlay.close()),this.drawerShown=!1,this.drawerTransitioning=!0,this.updateComplete.then(()=>this.startCloseTransition()),requestAnimationFrame(()=>this.restoreDrawerTriggerFocus())),this.dispatchEvent(new CustomEvent(e?S.MENU_DRAWER_OPENED:S.MENU_DRAWER_CLOSED,{bubbles:!0,composed:!0})))}showDrawerPopover(){const e=this.scrimRef.value,t=this.drawerRef.value;if(!(!e||!t||!this.isConnected)){this.swipeController.drawerElement=t;try{this.openedFullScreen||e.showPopover(),t.showPopover()}catch{}this.dispatchEvent(new CustomEvent(S.MENU_DRAWER_PRESENTED,{bubbles:!0,composed:!0})),t.getBoundingClientRect(),requestAnimationFrame(()=>{!this.drawerOpen||!this.isConnected||(this.drawerTransitioning=!0,this.drawerShown=!0,this.openedFullScreen&&(this.fullScreenSession=!0,this.overlay.open(),this.attachDrawerKeydown(),this.updateComplete.then(()=>{this.drawerOpen&&this.overlay.moveFocusInto()})))})}}attachDrawerKeydown(){this.drawerKeydownAttached||(document.addEventListener("keydown",this.onDrawerKeydown),this.drawerKeydownAttached=!0)}detachDrawerKeydown(){this.drawerKeydownAttached&&(document.removeEventListener("keydown",this.onDrawerKeydown),this.drawerKeydownAttached=!1)}fullScreenFocusScope(){const e=this.drawerRef.value;if(!e)return[];const t=n=>n instanceof HTMLElement&&n.getClientRects().length>0,i=[],r=n=>{if(n.matches(A)&&t(n)&&i.push(n),n.shadowRoot)for(const o of n.shadowRoot.querySelectorAll(A))t(o)&&i.push(o)};for(const n of e.querySelectorAll("*"))if(r(n),n instanceof HTMLSlotElement)for(const o of n.assignedElements({flatten:!0})){r(o);for(const d of o.querySelectorAll("*"))r(d)}const s=this.liftedCloseControl;if(s?.isConnected){const n=s.shadowRoot?.querySelector("button")??s;t(n)&&i.push(n)}return i}static drawerTransitionMs(e){const t=getComputedStyle(e),i=o=>o.split(",").map(d=>d.trim()).filter(Boolean).map(d=>{const h=Number.parseFloat(d);return Number.isFinite(h)?d.endsWith("ms")?h:h*1e3:0}),r=i(t.transitionDuration),s=i(t.transitionDelay);let n=0;return r.forEach((o,d)=>{n=Math.max(n,o+(s[d%Math.max(s.length,1)]??0))}),n}startCloseTransition(){const e=this.drawerRef.value;if(!e){this.hideDrawerPopover();return}this.closeTransitionTimer&&clearTimeout(this.closeTransitionTimer);const t=y.drawerTransitionMs(e);if(t===0){this.onDrawerTransitionEnd();return}this.closeTransitionTimer=setTimeout(()=>{this.closeTransitionTimer=null,!this.drawerOpen&&this.drawerTransitioning&&this.onDrawerTransitionEnd()},t+50)}hideDrawerPopover(){const e=this.scrimRef.value,t=this.drawerRef.value;this.swipeController.drawerElement=null,t&&(t.style.cssText="");try{t?.hidePopover()}catch{}try{e?.hidePopover()}catch{}}restoreDrawerTriggerFocus(){const e=this.drawerTrigger;this.drawerTrigger=null,e?.isConnected&&e.focus({preventScroll:!0})}getAutoExpandedGroups(e=!0){const t=new Set;let i=null;for(const s of this.querySelectorAll("esp-menu-item")){const n=s.url||s.getAttribute("url");if(n&&O(n)){i=s;break}}if(!i)for(const s of this.querySelectorAll("esp-menu-group")){const n=s.url||s.getAttribute("url");if(n&&O(n)){i=s;break}}if(!i&&e){for(const s of this.querySelectorAll("esp-menu-group"))s.parentElement===this&&t.add(s);return t}if(!i)return t;i instanceof v&&t.add(i);let r=i.parentElement;for(;r&&r!==this;)r instanceof v&&t.add(r),r=r.parentElement;return t}isHorizontalTopLevelGroup(e){return e.mode==="horizontal"&&e.depth===0}groupUrlPrefixMatches(e){return R(location.pathname,e.urlPrefix)}groupPathMatches(e){if(this.groupUrlPrefixMatches(e))return!0;const t=e.url||e.getAttribute("url");return t?R(location.pathname,$(t)):!1}expandToCurrentPage(){const e=this.getAutoExpandedGroups(),t=this.querySelectorAll("esp-menu-group");for(const i of t)i.open=e.has(i)&&!this.isHorizontalTopLevelGroup(i)}closeHorizontalTopLevelGroups(){for(const e of this.querySelectorAll("esp-menu-group"))this.isHorizontalTopLevelGroup(e)&&(e.open=!1)}getDrawerAutoExpandedGroups(){return this.getAutoExpandedGroups(!1)}collectDrawerNodes(e,t=this.getDrawerAutoExpandedGroups()){const i=[];for(const r of e)if(r instanceof E){const s=r.querySelector(":scope > svg, :scope > img");i.push({kind:"item",label:r.label,url:r.url,open:!1,icon:r.icon,iconHtml:s?.outerHTML||"",children:[],originalItem:r,originalGroup:null})}else if(r instanceof v){const s=r.querySelector(':scope > [slot="icon"]'),n=t.has(r)||this.groupPathMatches(r),o=this.drawerGroupOpenOverrides.get(r)??(r.open||n);i.push({kind:"group",label:r.label,url:r.url||"",open:o,icon:r.icon,iconHtml:s?.outerHTML||"",children:this.collectDrawerNodes(Array.from(r.children),t),originalItem:null,originalGroup:r})}return i}renderDrawerNode(e){return e.kind==="item"?f`<esp-menu-item
+var l=function(g,e,t,i){var r=arguments.length,s=r<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,n;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(g,e,t,i);else for(var o=g.length-1;o>=0;o--)(n=g[o])&&(s=(r<3?n(s):r>3?n(e,t,s):n(e,t))||s);return r>3&&s&&Object.defineProperty(e,t,s),s},y;import{css as N,html as f,nothing as w}from"lit";import{customElement as M,property as c,state as F}from"lit/decorators.js";import{classMap as x}from"lit/directives/class-map.js";import{unsafeHTML as z}from"lit/directives/unsafe-html.js";import{createRef as p,ref as u}from"lit/directives/ref.js";import{styleMap as k}from"lit/directives/style-map.js";import{EspalierElementBase as P}from"../shared/esp-element-base.js";import{ESP_EVENTS as S}from"../shared/events.js";import{getEspBus as I}from"../shared/bus-events.js";import{normalizePath as $,pathStartsWithSegment as R,pathsMatch as O}from"../shared/path-matching.js";import{renderConfiguredBrand as _}from"../shared/configured-brand.js";import{FOCUSABLE_SELECTOR as A,OverlayController as T}from"../shared/overlay-controller.js";import{SwipeRevealController as L}from"./swipe-reveal-controller.js";import"./esp-menu-item.js";import"./esp-menu-group.js";import"../burger/esp-burger.js";import{EspalierMenuItem as E}from"./esp-menu-item.js";import{EspalierMenuGroup as v}from"./esp-menu-group.js";import{COMPACT_VIEWPORT_MEDIA_QUERY as G}from"../shared/responsive.js";import{RafThrottle as H}from"../shared/raf-throttle.js";import{viewportSize as q}from"../shared/viewport.js";import{solveDrawerNestedFit as B}from"./drawer-nested-fit.js";const K=new Set(["panel","full-screen"]),U=new Set(["fade","slide-down","slide-up","slide-left","slide-right"]);let a=y=class extends P{ownsDrawerLock(){return this.isFullScreenDrawer}fullScreenInertAnchor(){return y.inertAnchorFor(this)}static inertAnchorFor(e){let t=e,i=e;for(;;){const r=i.parentElement;if(r){if(r.localName==="esp-page"||r.localName==="esp-root")return i;r===document.body&&(t=i),i=r;continue}const s=i.getRootNode();if(s instanceof ShadowRoot&&s.host instanceof HTMLElement){i=s.host;continue}return t}}constructor(){super(),this.itemsSlot=p(),this.railRef=p(),this.scrimRef=p(),this.drawerRef=p(),this.bus=I(),this.closeTransitionTimer=null,this.drawerGroupOpenOverrides=new Map,this.overlay=new T({host:this,getFocusTrapContainer:()=>this.drawerRef.value??null,getFocusScope:()=>this.fullScreenFocusScope(),getInertAnchor:()=>this.fullScreenInertAnchor(),promote:!1,scrollLock:{preserveScrollPosition:!0}}),this.fullScreenSession=!1,this.openedFullScreen=!1,this.drawerKeydownAttached=!1,this.nestedFitProbe=p(),this.nestedFitCapProbe=p(),this.nestedFitFloorProbe=p(),this.nestedFitPadProbe=p(),this.nestedFitTextProbe=p(),this.nestedFit=null,this.nestedFitMeasured=!1,this.nestedFitIdleHandle=null,this.nestedFitFallback=null,this.nestedFitResize=new H(()=>this.measureNestedFit()),this.nestedFitObserver=null,this.onNestedFitResize=()=>{this.drawerPresentation==="full-screen"&&this.nestedFitResize.schedule()},this.onNestedFitFontsLoaded=()=>this.scheduleNestedFit(!0),this.onOverlayOpened=e=>{if(e===this.overlay||!this.drawerOpen)return;const t=this.drawerTrigger;this.drawerTrigger=null,t&&e.redirectFocusRestore(t),this.swipeController.closeForHandoff(),this.onDrawerTransitionEnd()},this._sliding=!1,this._mobileCollapsed=!1,this.verticalDrawerQuery=null,this.onVerticalDrawerChange=e=>this.setMobileCollapsed(e.matches),this.mode="horizontal",this.overflow="auto",this.side="left",this.drawerPresentation="panel",this.fullScreenTransition="fade",this.drawerBrand=null,this.liftedCloseControl=null,this.ariaLabel=null,this.autoExpand=!1,this.drawerOpen=!1,this.drawerShown=!1,this.drawerTransitioning=!1,this.drawerTrigger=null,this.hasExternalDrawerControl=!1,this.previewCollapseRequested=!1,this.getWidth=()=>{const e=this.railRef.value;return e?Math.max(e.scrollWidth,e.clientWidth):-1},this.onDrawerKeydown=e=>{!this.drawerOpen||!this.openedFullScreen||e.key==="Tab"&&this.overlay.trapFocus(e)},this.onDrawerTransitionEnd=e=>{e&&e.target!==this.drawerRef.value||(this.closeTransitionTimer&&(clearTimeout(this.closeTransitionTimer),this.closeTransitionTimer=null),this.drawerTransitioning=!1,this.drawerOpen||(this.hideDrawerPopover(),this.drawerGroupOpenOverrides.clear()))},this.handleDrawerCloseClick=()=>{this.closeDrawer()},this.swipeController=new L(this,this.side),this.swipeController.enabled=!1}get isFullScreenDrawer(){return K.has(this.drawerPresentation)?this.drawerPresentation==="full-screen":!1}get resolvedFullScreenTransition(){return U.has(this.fullScreenTransition)?this.fullScreenTransition:"fade"}get sliding(){return this._sliding}set sliding(e){const t=this._sliding;this._sliding=e,this.syncSwipeEnabled(),this.propagateToItems(),this.requestUpdate("sliding",t)}get drawerSide(){return this.overflow==="right-drawer"?"right":this.overflow==="left-drawer"?"left":this.side}get drawerActive(){return this.mode==="drawer"||this._sliding||this.overflow==="left-drawer"||this.overflow==="right-drawer"||this.mode==="vertical"&&(this._mobileCollapsed||this.previewCollapseRequested)&&this.hasExternalDrawerControl}get railMode(){return this.mode==="horizontal"?"horizontal":"vertical"}connectedCallback(){super.connectedCallback(),this.getAttribute("slot")==="right"&&(this.side="right"),!this.verticalDrawerQuery&&typeof window<"u"&&"matchMedia"in window&&(this.verticalDrawerQuery=window.matchMedia(G),this._mobileCollapsed=this.verticalDrawerQuery.matches,this.verticalDrawerQuery.addEventListener("change",this.onVerticalDrawerChange)),this.syncSwipeEnabled(),T.addOpenListener(this.onOverlayOpened),window.addEventListener("resize",this.onNestedFitResize),typeof document<"u"&&document.fonts&&(document.fonts.addEventListener("loadingdone",this.onNestedFitFontsLoaded),document.fonts.ready.then(()=>{this.isConnected&&this.scheduleNestedFit(!0)})),!this.nestedFitObserver&&typeof MutationObserver<"u"&&(this.nestedFitObserver=new MutationObserver(()=>this.scheduleNestedFit(!0)),this.nestedFitObserver.observe(this,{subtree:!0,childList:!0,attributes:!0,attributeFilter:["label"]}))}disconnectedCallback(){T.removeOpenListener(this.onOverlayOpened),window.removeEventListener("resize",this.onNestedFitResize),document.fonts?.removeEventListener("loadingdone",this.onNestedFitFontsLoaded),this.nestedFitObserver?.disconnect(),this.nestedFitObserver=null,this.nestedFitResize.cancel(),this.cancelNestedFitIdle(),this.nestedFitMeasured=!1,this.verticalDrawerQuery?.removeEventListener("change",this.onVerticalDrawerChange),this.verticalDrawerQuery=null,this.detachDrawerKeydown(),this.fullScreenSession=!1,super.disconnectedCallback()}setMobileCollapsed(e){e!==this._mobileCollapsed&&(this._mobileCollapsed=e,this.mode==="vertical"&&this.applyMobileCollapse())}applyMobileCollapse(){this.swipeController.direction=this.drawerSide,this.syncSwipeEnabled(),this.propagateToItems(),this.requestUpdate(),!this.drawerActive&&this.drawerOpen&&this.swipeController.close(!0)}firstUpdated(e){super.firstUpdated(e),this.propagateToItems(),this.scheduleNestedFit()}updated(e){super.updated(e),(e.has("mode")||e.has("overflow")||e.has("side")||e.has("hasExternalDrawerControl")||e.has("previewCollapseRequested"))&&(this.swipeController.direction=this.drawerSide,this.syncSwipeEnabled(),this.propagateToItems(),!this.drawerActive&&this.drawerOpen&&this.swipeController.close(!0)),e.has("drawerPresentation")&&(this.nestedFitMeasured=!1,this.scheduleNestedFit()),this.drawerOpen&&this.openedFullScreen!==this.isFullScreenDrawer&&this.swipeController.close(!0),this.autoExpand&&(e.has("autoExpand")||e.has("mode")&&this.mode!=="horizontal")?this.expandToCurrentPage():this.mode==="horizontal"&&e.has("mode")&&this.closeHorizontalTopLevelGroups()}openDrawer(e){this.drawerActive&&(e?this.drawerTrigger=e:this.drawerOpen||(this.drawerTrigger=null),this.swipeController.open())}closeDrawer(){this.swipeController.close(!0)}toggleDrawer(e){this.drawerOpen?this.closeDrawer():this.openDrawer(e)}get isDrawerOpen(){return this.drawerOpen}syncSwipeEnabled(){this.swipeController.direction=this.drawerSide,this.swipeController.enabled=this.drawerActive}getAssignedChildren(){return this.itemsSlot.value?.assignedElements()??[]}propagateToItems(){const e=this.railMode;for(const t of this.getAssignedChildren())t instanceof E?(t.mode=e,t.depth=0,t.touchDevice=this.swipeController.isTouch):t instanceof v&&(t.mode=e,t.depth=0,t.touchDevice=this.swipeController.isTouch)}handleSlotChange(){this.propagateToItems(),this.scheduleNestedFit(!0)}scheduleNestedFit(e=!1){if(this.drawerPresentation!=="full-screen"){this.cancelNestedFitIdle(),this.nestedFit!==null&&(this.nestedFit=null);return}if(e&&(this.nestedFitMeasured=!1),e&&this.drawerShown){this.cancelNestedFitIdle(),this.nestedFitResize.schedule();return}if(this.nestedFitIdleHandle!==null||this.nestedFitFallback!==null)return;const t=()=>{this.nestedFitIdleHandle=null,this.nestedFitFallback=null,this.isConnected&&this.measureNestedFit()};typeof requestIdleCallback=="function"?this.nestedFitIdleHandle=requestIdleCallback(t,{timeout:2e3}):this.nestedFitFallback={stage:"frame",handle:requestAnimationFrame(()=>{this.nestedFitFallback={stage:"timeout",handle:window.setTimeout(t,0)}})}}cancelNestedFitIdle(){this.nestedFitIdleHandle!==null&&(cancelIdleCallback(this.nestedFitIdleHandle),this.nestedFitIdleHandle=null),this.nestedFitFallback!==null&&(this.nestedFitFallback.stage==="frame"?cancelAnimationFrame(this.nestedFitFallback.handle):window.clearTimeout(this.nestedFitFallback.handle),this.nestedFitFallback=null)}ensureNestedFitMeasured(){this.nestedFitMeasured||(this.cancelNestedFitIdle(),this.measureNestedFit())}collectNestedLabels(){const e=[];let t=!1;const i=(r,s)=>{for(const n of r){const o=s>0;n instanceof E?o&&e.push(n.label):n instanceof v&&(o&&(e.push(n.label),n.url&&(t=!0)),i(Array.from(n.children),s+1))}};return i(this.getAssignedChildren(),0),{labels:e,linkedGroup:t}}readNestedFitMetrics(e){const t=this.nestedFitCapProbe.value,i=this.nestedFitFloorProbe.value,r=this.nestedFitPadProbe.value,s=this.nestedFitTextProbe.value;if(!t||!i||!r||!s)return null;const n=parseFloat(getComputedStyle(t).fontSize),o=parseFloat(getComputedStyle(i).fontSize),d=getComputedStyle(r),h=parseFloat(d.paddingInlineStart),b=parseFloat(d.paddingInlineEnd);if(![n,o,h,b].every(m=>Number.isFinite(m)))return null;s.replaceChildren(...e.map(m=>{const D=document.createElement("span");return D.textContent=m,D}));const C=Array.from(s.children,m=>m.getBoundingClientRect().width);return s.replaceChildren(),{capPx:n,floorPx:o,paddingPx:h,smallPx:b,widths:C}}measureNestedFit(){if(!this.isConnected||this.drawerPresentation!=="full-screen")return;const{labels:e,linkedGroup:t}=this.collectNestedLabels();if(this.nestedFitMeasured=!0,e.length===0){this.nestedFit!==null&&(this.nestedFit=null);return}const i=this.readNestedFitMetrics(e);if(!i)return;const r=this.drawerRef.value,s=r&&this.drawerShown?r.getBoundingClientRect().width:0,n=s>0?s:q().width,o=t?2*(2*i.smallPx+4.5):0,d=n-2*i.paddingPx-o,h=B({capPx:i.capPx,floorPx:i.floorPx,availablePx:d,widestAtCapPx:Math.max(0,...i.widths)});this.nestedFit&&this.nestedFit.fontSizePx===h.fontSizePx&&this.nestedFit.wrap===h.wrap||(this.nestedFit=h)}onSwipeRevealChanged(e){e!==this.drawerOpen&&(this.drawerOpen=e,e?(this.openedFullScreen=this.isFullScreenDrawer,this.openedFullScreen&&this.ensureNestedFitMeasured(),this.drawerGroupOpenOverrides.clear(),this.bus.publish("close-popovers",{}),this.updateComplete.then(()=>this.showDrawerPopover())):(this.detachDrawerKeydown(),this.fullScreenSession&&(this.fullScreenSession=!1,this.overlay.close()),this.drawerShown=!1,this.drawerTransitioning=!0,this.updateComplete.then(()=>this.startCloseTransition()),requestAnimationFrame(()=>this.restoreDrawerTriggerFocus())),this.dispatchEvent(new CustomEvent(e?S.MENU_DRAWER_OPENED:S.MENU_DRAWER_CLOSED,{bubbles:!0,composed:!0})))}showDrawerPopover(){const e=this.scrimRef.value,t=this.drawerRef.value;if(!(!e||!t||!this.isConnected)){this.swipeController.drawerElement=t;try{this.openedFullScreen||e.showPopover(),t.showPopover()}catch{}this.dispatchEvent(new CustomEvent(S.MENU_DRAWER_PRESENTED,{bubbles:!0,composed:!0})),t.getBoundingClientRect(),requestAnimationFrame(()=>{!this.drawerOpen||!this.isConnected||(this.drawerTransitioning=!0,this.drawerShown=!0,this.openedFullScreen&&(this.fullScreenSession=!0,this.overlay.open(),this.attachDrawerKeydown(),this.updateComplete.then(()=>{this.drawerOpen&&this.overlay.moveFocusInto()})))})}}attachDrawerKeydown(){this.drawerKeydownAttached||(document.addEventListener("keydown",this.onDrawerKeydown),this.drawerKeydownAttached=!0)}detachDrawerKeydown(){this.drawerKeydownAttached&&(document.removeEventListener("keydown",this.onDrawerKeydown),this.drawerKeydownAttached=!1)}fullScreenFocusScope(){const e=this.drawerRef.value;if(!e)return[];const t=n=>n instanceof HTMLElement&&n.getClientRects().length>0,i=[],r=n=>{if(n.matches(A)&&t(n)&&i.push(n),n.shadowRoot)for(const o of n.shadowRoot.querySelectorAll(A))t(o)&&i.push(o)};for(const n of e.querySelectorAll("*"))if(r(n),n instanceof HTMLSlotElement)for(const o of n.assignedElements({flatten:!0})){r(o);for(const d of o.querySelectorAll("*"))r(d)}const s=this.liftedCloseControl;if(s?.isConnected){const n=s.shadowRoot?.querySelector("button")??s;t(n)&&i.push(n)}return i}static drawerTransitionMs(e){const t=getComputedStyle(e),i=o=>o.split(",").map(d=>d.trim()).filter(Boolean).map(d=>{const h=Number.parseFloat(d);return Number.isFinite(h)?d.endsWith("ms")?h:h*1e3:0}),r=i(t.transitionDuration),s=i(t.transitionDelay);let n=0;return r.forEach((o,d)=>{n=Math.max(n,o+(s[d%Math.max(s.length,1)]??0))}),n}startCloseTransition(){const e=this.drawerRef.value;if(!e){this.hideDrawerPopover();return}this.closeTransitionTimer&&clearTimeout(this.closeTransitionTimer);const t=y.drawerTransitionMs(e);if(t===0){this.onDrawerTransitionEnd();return}this.closeTransitionTimer=setTimeout(()=>{this.closeTransitionTimer=null,!this.drawerOpen&&this.drawerTransitioning&&this.onDrawerTransitionEnd()},t+50)}hideDrawerPopover(){const e=this.scrimRef.value,t=this.drawerRef.value;this.swipeController.drawerElement=null,t&&(t.style.cssText="");try{t?.hidePopover()}catch{}try{e?.hidePopover()}catch{}}restoreDrawerTriggerFocus(){const e=this.drawerTrigger;this.drawerTrigger=null,e?.isConnected&&e.focus({preventScroll:!0})}getAutoExpandedGroups(e=!0){const t=new Set;let i=null;for(const s of this.querySelectorAll("esp-menu-item")){const n=s.url||s.getAttribute("url");if(n&&O(n)){i=s;break}}if(!i)for(const s of this.querySelectorAll("esp-menu-group")){const n=s.url||s.getAttribute("url");if(n&&O(n)){i=s;break}}if(!i&&e){for(const s of this.querySelectorAll("esp-menu-group"))s.parentElement===this&&t.add(s);return t}if(!i)return t;i instanceof v&&t.add(i);let r=i.parentElement;for(;r&&r!==this;)r instanceof v&&t.add(r),r=r.parentElement;return t}isHorizontalTopLevelGroup(e){return e.mode==="horizontal"&&e.depth===0}groupUrlPrefixMatches(e){return R(location.pathname,e.urlPrefix)}groupPathMatches(e){if(this.groupUrlPrefixMatches(e))return!0;const t=e.url||e.getAttribute("url");return t?R(location.pathname,$(t)):!1}expandToCurrentPage(){const e=this.getAutoExpandedGroups(),t=this.querySelectorAll("esp-menu-group");for(const i of t)i.open=e.has(i)&&!this.isHorizontalTopLevelGroup(i)}closeHorizontalTopLevelGroups(){for(const e of this.querySelectorAll("esp-menu-group"))this.isHorizontalTopLevelGroup(e)&&(e.open=!1)}getDrawerAutoExpandedGroups(){return this.getAutoExpandedGroups(!1)}collectDrawerNodes(e,t=this.getDrawerAutoExpandedGroups()){const i=[];for(const r of e)if(r instanceof E){const s=r.querySelector(":scope > svg, :scope > img");i.push({kind:"item",label:r.label,url:r.url,open:!1,icon:r.icon,iconHtml:s?.outerHTML||"",children:[],originalItem:r,originalGroup:null})}else if(r instanceof v){const s=r.querySelector(':scope > [slot="icon"]'),n=t.has(r)||this.groupPathMatches(r),o=this.drawerGroupOpenOverrides.get(r)??(r.open||n);i.push({kind:"group",label:r.label,url:r.url||"",open:o,icon:r.icon,iconHtml:s?.outerHTML||"",children:this.collectDrawerNodes(Array.from(r.children),t),originalItem:null,originalGroup:r})}return i}renderDrawerNode(e){return e.kind==="item"?f`<esp-menu-item
         label=${e.label}
         .url=${e.url}
         .icon=${e.icon}
@@ -19,7 +19,7 @@ var l=function(g,e,t,i){var r=arguments.length,s=r<3?e:i===null?i=Object.getOwnP
     </esp-menu-group>`}handleDrawerItemClick(e){e.dispatchEvent(new CustomEvent(S.CLICKED,{detail:{},bubbles:!0,composed:!0})),this.swipeController.close(!0)}render(){const e=this.drawerOpen||this.drawerTransitioning,t=this.drawerActive,i={rail:!0,horizontal:this.railMode==="horizontal",vertical:this.railMode==="vertical",wrap:this.overflow==="wrap",scroll:this.overflow==="scroll","drawer-forced":this.drawerActive},r=e?this.openedFullScreen:this.isFullScreenDrawer,s={drawer:!0,"drawer-left":this.drawerSide==="left","drawer-right":this.drawerSide==="right","full-screen":r,[`transition-${this.resolvedFullScreenTransition}`]:r,transitioning:this.drawerTransitioning,open:this.drawerShown,"nested-wrap":r&&this.nestedFit?.wrap===!0},n={"--_esp-menu-drawer-nested-font-size":r&&this.nestedFit?`${this.nestedFit.fontSizePx}px`:null},o=e?this.collectDrawerNodes(this.getAssignedChildren()):[],d=this.ariaLabel??"Navigation",h={"--_esp-menu-drawer-brand-color":this.drawerBrand?.brandColor||null},b=r&&e?f`<div class="drawer-chrome">
             <div class="drawer-brand" style=${k(h)}>
               <slot name="drawer-brand"
-                >${this.drawerBrand?L(this.drawerBrand):w}</slot
+                >${this.drawerBrand?_(this.drawerBrand):w}</slot
               >
             </div>
             ${this.liftedCloseControl?w:f`
@@ -99,6 +99,7 @@ var l=function(g,e,t,i){var r=arguments.length,s=r<3?e:i===null?i=Object.getOwnP
       }
 
       .rail.vertical {
+        --_esp-surface-layer: 1;
         position: relative;
         display: flex;
         flex-direction: column;
@@ -112,6 +113,7 @@ var l=function(g,e,t,i){var r=arguments.length,s=r<3?e:i===null?i=Object.getOwnP
 
       .scrim,
       .drawer {
+        --_esp-surface-layer: 1;
         margin: 0;
         padding: 0;
         border: none;

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

@@ -23,7 +23,7 @@ export interface PageWorkspaceResizeDetail {
     flyoutWidth: number;
 }
 /**
- * Used to lay out standard page structure.
+ * Arranges a page's header, navigation, main content, and footer.
  *
  * @slot header - Global navigation content (typically an `esp-header`).
  *

package/dist/page/esp-page.styles.js

@@ -1,5 +1,6 @@
 import{css as a,unsafeCSS as e}from"lit";import{EspalierElementBase as i}from"../shared/esp-element-base.js";import{COMPACT_VIEWPORT_MEDIA_QUERY as t}from"../shared/responsive.js";const n=[...i.styles,a`
     :host {
+      --_esp-surface-layer: initial;
       --_esp-page-resolved-max-width: var(--esp-page-main-max-width, 1536px);
       --_esp-page-main-min-width: var(--esp-page-main-min-width, 30rem);
       --_esp-page-preview-resolved-min-width: var(--esp-page-preview-min-width, 22.5rem);

package/dist/pickers/esp-pick-one.d.ts

@@ -4,8 +4,7 @@ import "./esp-picker-menu.js";
 import { type PickerItem } from "./esp-picker-item.js";
 import { EspalierPickerBase } from "./esp-picker-base.js";
 /**
- * Component for selecting a single option from a list of
- * options. For selecting multiple options, see
+ * Selects one option from a list. For selecting multiple options, see
  * [esp-pick-some](/components/pickers/pick-some/).
  *
  * ```html

package/dist/pickers/esp-pick-some.d.ts

@@ -4,7 +4,7 @@ import "./esp-picker-menu.js";
 import { type PickerItem } from "./esp-picker-item.js";
 import { EspalierPickerBase } from "./esp-picker-base.js";
 /**
- * Component for selecting multiple options from a list of options.
+ * Selects multiple options from a list.
  *
  * ```html
  * <esp-box>

package/dist/pickers/esp-picker-item.js

@@ -1,7 +1,7 @@
-var c=function(e,t,r,n){var i=arguments.length,o=i<3?t:n===null?n=Object.getOwnPropertyDescriptor(t,r):n,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(e,t,r,n);else for(var h=e.length-1;h>=0;h--)(l=e[h])&&(o=(i<3?l(o):i>3?l(t,r,o):l(t,r))||o);return i>3&&o&&Object.defineProperty(t,r,o),o};import{LitElement as g,nothing as u,css as v,html as a}from"lit";import{customElement as m,property as p}from"lit/decorators.js";import{ref as f}from"lit/directives/ref.js";import{getIconHrefForHost as y}from"../shared/intent-values.js";import{SlottedIconController as x}from"../shared/slotted-icon-controller.js";import{renderSpriteIcon as b}from"../shared/svgs/render-sprite-icon.js";import{DocumentSpriteController as k}from"../shared/document-sprite.js";const S=["text","icon","styles"],d=new WeakMap;function P(e,t){d.set(e,t)}function E(e){return{text:e.text||e.getAttribute("text")||e.textContent?.trim()||"",icon:e.icon||e.getAttribute("icon")||"",styles:e.styles}}function H(e,t){return e.text===t.text&&(e.icon??"")===(t.icon??"")&&e.styles===t.styles}function j(e){return e.value||e.getAttribute("value")||""}let s=class extends g{constructor(){super(),this.internals=this.attachInternals(),this.iconSlot=new x(this),this.text="",this.icon="",this.value="",this.selected=!1,new k(this,{reactToSpriteChanges:!0}),this.internals.role="option"}connectedCallback(){super.connectedCallback(),this.hasAttribute("role")||this.setAttribute("role","option")}updated(t){super.updated(t),S.some(r=>t.has(r))&&d.get(this)?.pickerItemChanged(this),t.has("selected")&&(this.internals.ariaSelected=String(this.selected),this.setAttribute("aria-selected",String(this.selected)))}renderHighlightedText(){const t=this.highlightRanges;if(!t||t.length===0)return this.text;const r=[...t].sort((o,l)=>o[0]-l[0]),n=[];let i=0;for(const[o,l]of r)o>i&&n.push(a`${this.text.slice(i,o)}`),n.push(a`<mark>${this.text.slice(o,l)}</mark>`),i=l;return i<this.text.length&&n.push(a`${this.text.slice(i)}`),n}render(){const t=y(this.icon,this),r=this.iconSlot.hasSlottedIcon(":scope > *");return a`<div>
+var c=function(e,t,o,n){var s=arguments.length,r=s<3?t:n===null?n=Object.getOwnPropertyDescriptor(t,o):n,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(e,t,o,n);else for(var h=e.length-1;h>=0;h--)(l=e[h])&&(r=(s<3?l(r):s>3?l(t,o,r):l(t,o))||r);return s>3&&r&&Object.defineProperty(t,o,r),r};import{LitElement as u,nothing as g,css as f,html as a}from"lit";import{customElement as v,property as p}from"lit/decorators.js";import{ref as m}from"lit/directives/ref.js";import{getIconHrefForHost as y}from"../shared/intent-values.js";import{SlottedIconController as x}from"../shared/slotted-icon-controller.js";import{renderSpriteIcon as b}from"../shared/svgs/render-sprite-icon.js";import{DocumentSpriteController as k}from"../shared/document-sprite.js";const S=["text","icon","styles"],d=new WeakMap;function z(e,t){d.set(e,t)}function P(e){return{text:e.text||e.getAttribute("text")||e.textContent?.trim()||"",icon:e.icon||e.getAttribute("icon")||"",styles:e.styles}}function E(e,t){return e.text===t.text&&(e.icon??"")===(t.icon??"")&&e.styles===t.styles}function H(e){return e.value||e.getAttribute("value")||""}let i=class extends u{constructor(){super(),this.internals=this.attachInternals(),this.iconSlot=new x(this),this.text="",this.icon="",this.value="",this.selected=!1,new k(this,{reactToSpriteChanges:!0}),this.internals.role="option"}connectedCallback(){super.connectedCallback(),this.hasAttribute("role")||this.setAttribute("role","option")}updated(t){super.updated(t),S.some(o=>t.has(o))&&d.get(this)?.pickerItemChanged(this),t.has("selected")&&(this.internals.ariaSelected=String(this.selected),this.setAttribute("aria-selected",String(this.selected)))}renderHighlightedText(){const t=this.highlightRanges;if(!t||t.length===0)return this.text;const o=[...t].sort((r,l)=>r[0]-l[0]),n=[];let s=0;for(const[r,l]of o)r>s&&n.push(a`${this.text.slice(s,r)}`),n.push(a`<mark>${this.text.slice(r,l)}</mark>`),s=l;return s<this.text.length&&n.push(a`${this.text.slice(s)}`),n}render(){const t=y(this.icon,this),o=this.iconSlot.hasSlottedIcon(":scope > *");return a`<div>
       <span class="icon">
-        <slot ${f(this.iconSlot.slotRef)} @slotchange=${this.iconSlot.handleSlotChange}></slot>
-        ${!r&&t?b(t):u}
+        <slot ${m(this.iconSlot.slotRef)} @slotchange=${this.iconSlot.handleSlotChange}></slot>
+        ${!o&&t?b(t):g}
       </span>
       <span class="text">${this.renderHighlightedText()}</span>
       ${this.selected?a`<svg
@@ -19,13 +19,15 @@ var c=function(e,t,r,n){var i=arguments.length,o=i<3?t:n===null?n=Object.getOwnP
             />
             <path d="M9 12l2 2l4 -4" />
           </svg>`:a``}
-    </div>`}};s.styles=v`
+    </div>`}};i.styles=f`
     :host(:hover),
     :host(.highlighted) {
       div {
+        --_esp-surface-layer: 3;
         background-color: var(--esp-color-picker-bg-hover, var(--esp-color-layer-3));
 
         > span.icon {
+          --_esp-surface-layer: 4;
           background-color: var(--esp-color-picker-bg-alt-hover, var(--esp-color-layer-4));
         }
       }
@@ -43,11 +45,13 @@ var c=function(e,t,r,n){var i=arguments.length,o=i<3?t:n===null?n=Object.getOwnP
     }
 
     div {
+      --_esp-surface-layer: 2;
       display: grid;
       grid-template-columns: min-content auto min-content;
       background-color: var(--esp-color-picker-bg, var(--esp-color-layer-2));
 
       .icon {
+        --_esp-surface-layer: 3;
         display: grid;
         grid-template-columns: min-content;
         background-color: var(--esp-color-picker-bg-alt, var(--esp-color-layer-3));
@@ -77,4 +81,4 @@ var c=function(e,t,r,n){var i=arguments.length,o=i<3?t:n===null?n=Object.getOwnP
         margin: var(--esp-size-tiny);
       }
     }
-  `,c([p({type:Object})],s.prototype,"styles",void 0),c([p({type:String})],s.prototype,"text",void 0),c([p({type:String})],s.prototype,"icon",void 0),c([p({type:String})],s.prototype,"value",void 0),c([p({type:Boolean})],s.prototype,"selected",void 0),c([p({attribute:"highlight-ranges",type:Array})],s.prototype,"highlightRanges",void 0),s=c([m("esp-picker-item")],s);export{s as EspalierPickerItem,P as adoptPickerItem,E as pickerItemDisplay,j as pickerItemValue,H as samePickerItemDisplay};
+  `,c([p({type:Object})],i.prototype,"styles",void 0),c([p({type:String})],i.prototype,"text",void 0),c([p({type:String})],i.prototype,"icon",void 0),c([p({type:String})],i.prototype,"value",void 0),c([p({type:Boolean})],i.prototype,"selected",void 0),c([p({attribute:"highlight-ranges",type:Array})],i.prototype,"highlightRanges",void 0),i=c([v("esp-picker-item")],i);export{i as EspalierPickerItem,z as adoptPickerItem,P as pickerItemDisplay,H as pickerItemValue,E as samePickerItemDisplay};

package/dist/pickers/esp-picker-menu.js

@@ -55,6 +55,7 @@ var u=function(a,e,t,r){var s=arguments.length,i=s<3?e:r===null?r=Object.getOwnP
     }
 
     .status-message {
+      --_esp-surface-layer: 2;
       display: grid;
       place-content: center;
       min-height: 3em;
@@ -76,6 +77,7 @@ var u=function(a,e,t,r){var s=arguments.length,i=s<3?e:r===null?r=Object.getOwnP
       }
 
       :host([data-fullscreen]) .menu-content {
+        --_esp-surface-layer: 2;
         grid-row: 2;
         box-sizing: border-box;
         min-height: 0;

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

@@ -1,9 +1,7 @@
 import { LitElement, type PropertyValues } from "lit";
 /**
- * Display a contextual UI overlay that appears when a
- * user interacts with an element, providing a temporary space
- * for additional information, options, or actions without blocking
- * the underlying content. Uses the native Popover API to render
+ * Shows contextual information, options, or actions while the underlying
+ * page remains interactive. Uses the native Popover API to render
  * in the browser's top layer, escaping all ancestor `overflow`
  * and `z-index` contexts.
  *

package/dist/repeater/esp-repeater.js

@@ -73,6 +73,7 @@ var n=function(f,e,t,s){var r=arguments.length,o=r<3?e:s===null?s=Object.getOwnP
 
       .state-panel,
       .status-footer {
+        --_esp-surface-layer: 2;
         display: grid;
         gap: var(--esp-size-tiny);
         padding: var(--esp-repeater-padding, var(--esp-size-small));

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

@@ -8,10 +8,10 @@ export type { SchemeEvents } from "../shared/bus-events.js";
 /**
  * Root container for the Espalier design system.
  *
- * Provides the full design-token pipeline — colors, scales, and
- * fonts — to every descendant component.  All tokens are
- * JS-computed from a pair of Base64-encoded theme objects and
- * emitted as CSS custom properties on the host element.
+ * Supplies descendant components with color, size, and font tokens.
+ * Configure light and dark themes through JavaScript properties or
+ * Base64-encoded attributes. The root emits CSS custom properties
+ * for the active theme.
  *
  * ### Theme API
  *

package/dist/root/esp-root.js

@@ -1,4 +1,6 @@
-var r=function(c,e,t,s){var h=arguments.length,i=h<3?e:s===null?s=Object.getOwnPropertyDescriptor(e,t):s,m;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(c,e,t,s);else for(var l=c.length-1;l>=0;l--)(m=c[l])&&(i=(h<3?m(i):h>3?m(e,t,i):m(e,t))||i);return h>3&&i&&Object.defineProperty(e,t,i),i},a;import{css as b,html as w,LitElement as E}from"lit";import{customElement as C,property as n,state as R}from"lit/decorators.js";import{getEspBus as d}from"../shared/bus-events.js";import{subscribeToRootEvent as x}from"../shared/root-event-subscription.js";import{DEFAULT_LIGHT_THEME as f,DEFAULT_DARK_THEME as g,encodeTheme as y,parseTheme as u,mergeTheme as v}from"../shared/theme.js";import{extractFamily as p,isLocalFontFamily as L,removeRuntimeGoogleFontLinks as S,syncRuntimeGoogleFontLink as D}from"../shared/font-helpers.js";import{computeThemeProperties as A}from"./helpers/compute-theme-properties.js";import{registerImageTexture as F,registeredImageTextures as I}from"../shared/image-texture-registry.js";import{registerImageTexture as Q,registeredImageTextures as $,BUILT_IN_IMAGE_TEXTURES as N}from"../shared/image-texture-registry.js";const T=1e3;let o=a=class extends E{constructor(){super(...arguments),this.schemeBacker="",this.schemeExplicitlySet=!1,this.resolvingDefaultScheme=!1,this.themeEventsReady=!1,this.systemSchemeQuery=null,this.lastSeedColor="",this.resolvedLightTheme={...f},this.resolvedDarkTheme={...g},this.appliedThemeProperties=new Set,this.documentClickRegistrationActive=!1,this.correlationId=globalThis.crypto?.randomUUID?.()??Math.random().toString(36),this.lightThemeAttr="",this.darkThemeAttr="",this.fontCSSRoot="/css/fonts/",this.fontDefinitionsUrl="",this.googleFontLoading="auto",this.iconSpriteUrl="/assets/icons.svg",this.themePending=!1,this.themeReadyState=!1,this.themeSettleWaiters=[],this.warnedThemeSettleTimeout=!1,this.defaultScheme="light",this.resizeObserver=new ResizeObserver(()=>{d().publish("window-resized",{emWidth:window.innerWidth/parseFloat(getComputedStyle(document.documentElement).fontSize),emHeight:window.innerHeight/parseFloat(getComputedStyle(document.documentElement).fontSize),pxWidth:window.innerWidth,pxHeight:window.innerHeight})}),this.handleSystemSchemeChange=e=>{this.schemeExplicitlySet||this.defaultScheme!=="system"||(this.resolvingDefaultScheme=!0,this.scheme=e.matches?"dark":"light",this.resolvingDefaultScheme=!1)}}static registerTexture(e,t){F(e,t)}static registeredTextures(){return I()}subscribeScoped(e,t){return x(this,e,t)}get lightTheme(){return this.lightThemeAttr?u(this.lightThemeAttr):null}set lightTheme(e){this.lightThemeAttr=e?y(e):""}get darkTheme(){return this.darkThemeAttr?u(this.darkThemeAttr):null}set darkTheme(e){this.darkThemeAttr=e?y(e):""}get themeSettled(){return this.themeReadyState}whenThemeSettled(){return this.themeReadyState?Promise.resolve():new Promise(e=>{this.themeSettleWaiters.push(e)})}get hasAuthorTheme(){return!!(this.scheme==="dark"?this.darkThemeAttr:this.lightThemeAttr)}settleTheme(){if(this.themeSettleTimer!==void 0&&(clearTimeout(this.themeSettleTimer),this.themeSettleTimer=void 0),this.themeReadyState)return;this.themeReadyState=!0;const e=this.themeSettleWaiters;this.themeSettleWaiters=[];for(const t of e)t()}get scheme(){return this.schemeBacker}set scheme(e){const t=e==="dark"?"dark":e==="light"?"light":"",s=this.schemeBacker,h=this.schemeExplicitlySet;this.resolvingDefaultScheme||(this.schemeExplicitlySet=t.length>0);const i=t||this.resolveDefaultScheme();h!==this.schemeExplicitlySet&&this.isConnected&&this.syncSystemSchemeListener(),i!==s&&(this.schemeBacker=i,this.requestUpdate("scheme",s),this.themeEventsReady&&d().publish("scheme-changed",{scheme:i,correlationId:this.correlationId}))}get seedColor(){return this.activeTheme.seedColor}injectGoogleFontLink(e,t,s){const h=`${this.correlationId}-${e}`,i=L(t)?"":t;D({owner:`root:${h}`,family:i,weight:s,enabled:this.googleFontLoading!=="none"})}syncGoogleFontLinks(){this.googleFontLoading==="none"&&this.removeRuntimeGoogleFontLinks();const e=this.activeTheme;this.injectGoogleFontLink("body",p(e.fontBody),e.fontWeightBody),this.injectGoogleFontLink("headings",p(e.fontHeadings),e.fontWeightHeadings),this.injectGoogleFontLink("brand",p(e.fontBrand),e.fontWeightBrand),this.injectGoogleFontLink("menu",p(e.fontMenu),e.fontWeightMenu),this.injectGoogleFontLink("monospace",p(e.fontMonospace),e.fontWeightMonospace)}removeRuntimeGoogleFontLinks(){S(`root:${this.correlationId}-`),S(`picker:${this.correlationId}:`)}get activeTheme(){return this.scheme==="dark"?this.resolvedDarkTheme:this.resolvedLightTheme}resolveThemes(){const e=this.lightThemeAttr?u(this.lightThemeAttr):null;this.resolvedLightTheme=e?v(f,e):{...f};const t=this.darkThemeAttr?u(this.darkThemeAttr):null;this.resolvedDarkTheme=t?v(g,t):{...g}}connectedCallback(){super.connectedCallback(),this.registerDocumentClickBridge(),this.resizeObserver.observe(this),this.hasUpdated&&(this.applyDefaultScheme(),this.syncGoogleFontLinks(),this.hasAuthorTheme||this.startThemeSettleTimer())}willUpdate(e){const t=["lightThemeAttr","darkThemeAttr"];(!this.lastSeedColor||t.some(l=>e.has(l)))&&(this.resolveThemes(),this.themeEventsReady&&d().publish("theme-changed",{correlationId:this.correlationId})),this.hasAuthorTheme&&this.settleTheme();const h=A(this.activeTheme,this.scheme==="dark"?"dark":"light"),i=new Set(Object.keys(h));for(const l of this.appliedThemeProperties)i.has(l)||this.style.removeProperty(l);for(const[l,k]of Object.entries(h))this.style.setProperty(l,k);this.appliedThemeProperties=i;const m=this.activeTheme.seedColor;this.themeEventsReady&&this.lastSeedColor&&this.lastSeedColor!==m&&d().publish("seed-color-changed",{seedColor:m,correlationId:this.correlationId}),this.lastSeedColor=m,this.themeEventsReady&&e.has("iconSpriteUrl")&&d().publish("icon-sprite-url-changed",{iconSpriteUrl:this.iconSpriteUrl,correlationId:this.correlationId}),this.syncGoogleFontLinks()}firstUpdated(){const e=this.activeTheme.stylesheets;if(e.length)for(const t of e){const s=document.createElement("link");s.rel="stylesheet",s.href=t,document.head.appendChild(s)}if(!document.getElementById("esp-root-base-styles")){const t=document.createElement("style");t.id="esp-root-base-styles",t.textContent=a.lightDomStyles,document.head.appendChild(t)}this.applyDefaultScheme(),this.lastSeedColor=this.activeTheme.seedColor,this.themeEventsReady=!0,this.startThemeSettleTimer()}startThemeSettleTimer(){if(this.themeReadyState||this.themeSettleTimer!==void 0)return;this.themeSettleDeadline??=performance.now()+T;const e=Math.max(0,this.themeSettleDeadline-performance.now());if(e===0){this.closeThemeWindow();return}this.themeSettleTimer=setTimeout(()=>this.closeThemeWindow(),e)}closeThemeWindow(){this.themeSettleTimer=void 0,this.themePending&&!this.warnedThemeSettleTimeout&&(this.warnedThemeSettleTimeout=!0,console.warn(`Espalier root: theme-pending was declared but no ${this.scheme} theme arrived within ${T}ms, so the default palette is rendering. Assign ${this.scheme==="dark"?"darkTheme":"lightTheme"} (or remove theme-pending).`)),this.settleTheme()}updated(e){this.toggleAttribute("data-theme-ready",this.themeReadyState),(e.has("defaultScheme")||e.has("scheme"))&&!this.schemeExplicitlySet&&this.applyDefaultScheme()}disconnectedCallback(){this.themeSettleTimer!==void 0&&(clearTimeout(this.themeSettleTimer),this.themeSettleTimer=void 0),this.unregisterDocumentClickBridge(),this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null,this.resizeObserver.disconnect(),this.removeRuntimeGoogleFontLinks(),super.disconnectedCallback()}registerDocumentClickBridge(){this.documentClickRegistrationActive||(this.documentClickRegistrationActive=!0,a.connectedRootCount+=1,a.connectedRootCount===1&&document.addEventListener("click",a.handleDocumentClick))}unregisterDocumentClickBridge(){this.documentClickRegistrationActive&&(this.documentClickRegistrationActive=!1,a.connectedRootCount=Math.max(0,a.connectedRootCount-1),a.connectedRootCount===0&&document.removeEventListener("click",a.handleDocumentClick))}applyDefaultScheme(){this.schemeExplicitlySet||(this.resolvingDefaultScheme=!0,this.scheme=this.resolveDefaultScheme(),this.resolvingDefaultScheme=!1,this.syncSystemSchemeListener())}resolveDefaultScheme(){return this.defaultScheme==="dark"||this.defaultScheme==="system"&&window.matchMedia?.("(prefers-color-scheme: dark)").matches?"dark":"light"}syncSystemSchemeListener(){if(this.schemeExplicitlySet||this.defaultScheme!=="system"||!window.matchMedia){this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null;return}this.systemSchemeQuery||(this.systemSchemeQuery=window.matchMedia("(prefers-color-scheme: dark)"),this.systemSchemeQuery.addEventListener("change",this.handleSystemSchemeChange))}render(){return w`<slot></slot>`}};o.connectedRootCount=0,o.handleDocumentClick=c=>{const e=c.composedPath().filter(t=>t instanceof HTMLElement&&t.tagName==="ESP-POPOVER");d().publish("close-popovers",{source:c.target??void 0,skipPopovers:e})},o.lightDomStyles=`
+var r=function(c,e,t,s){var h=arguments.length,i=h<3?e:s===null?s=Object.getOwnPropertyDescriptor(e,t):s,m;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(c,e,t,s);else for(var l=c.length-1;l>=0;l--)(m=c[l])&&(i=(h<3?m(i):h>3?m(e,t,i):m(e,t))||i);return h>3&&i&&Object.defineProperty(e,t,i),i},a;import{surfaceLayerAttributes as b}from"../shared/surface-layer.js";import{css as w,html as E,LitElement as C}from"lit";import{customElement as R,property as n,state as x}from"lit/decorators.js";import{getEspBus as d}from"../shared/bus-events.js";import{subscribeToRootEvent as L}from"../shared/root-event-subscription.js";import{DEFAULT_LIGHT_THEME as f,DEFAULT_DARK_THEME as g,encodeTheme as y,parseTheme as u,mergeTheme as v}from"../shared/theme.js";import{extractFamily as p,isLocalFontFamily as A,removeRuntimeGoogleFontLinks as S,syncRuntimeGoogleFontLink as D}from"../shared/font-helpers.js";import{computeThemeProperties as F}from"./helpers/compute-theme-properties.js";import{registerImageTexture as I,registeredImageTextures as z}from"../shared/image-texture-registry.js";import{registerImageTexture as N,registeredImageTextures as V,BUILT_IN_IMAGE_TEXTURES as q}from"../shared/image-texture-registry.js";const T=1e3;let o=a=class extends C{constructor(){super(...arguments),this.schemeBacker="",this.schemeExplicitlySet=!1,this.resolvingDefaultScheme=!1,this.themeEventsReady=!1,this.systemSchemeQuery=null,this.lastSeedColor="",this.resolvedLightTheme={...f},this.resolvedDarkTheme={...g},this.appliedThemeProperties=new Set,this.documentClickRegistrationActive=!1,this.correlationId=globalThis.crypto?.randomUUID?.()??Math.random().toString(36),this.lightThemeAttr="",this.darkThemeAttr="",this.fontCSSRoot="/css/fonts/",this.fontDefinitionsUrl="",this.googleFontLoading="auto",this.iconSpriteUrl="/assets/icons.svg",this.themePending=!1,this.themeReadyState=!1,this.themeSettleWaiters=[],this.warnedThemeSettleTimeout=!1,this.defaultScheme="light",this.resizeObserver=new ResizeObserver(()=>{d().publish("window-resized",{emWidth:window.innerWidth/parseFloat(getComputedStyle(document.documentElement).fontSize),emHeight:window.innerHeight/parseFloat(getComputedStyle(document.documentElement).fontSize),pxWidth:window.innerWidth,pxHeight:window.innerHeight})}),this.handleSystemSchemeChange=e=>{this.schemeExplicitlySet||this.defaultScheme!=="system"||(this.resolvingDefaultScheme=!0,this.scheme=e.matches?"dark":"light",this.resolvingDefaultScheme=!1)}}static registerTexture(e,t){I(e,t)}static registeredTextures(){return z()}subscribeScoped(e,t){return L(this,e,t)}get lightTheme(){return this.lightThemeAttr?u(this.lightThemeAttr):null}set lightTheme(e){this.lightThemeAttr=e?y(e):""}get darkTheme(){return this.darkThemeAttr?u(this.darkThemeAttr):null}set darkTheme(e){this.darkThemeAttr=e?y(e):""}get themeSettled(){return this.themeReadyState}whenThemeSettled(){return this.themeReadyState?Promise.resolve():new Promise(e=>{this.themeSettleWaiters.push(e)})}get hasAuthorTheme(){return!!(this.scheme==="dark"?this.darkThemeAttr:this.lightThemeAttr)}settleTheme(){if(this.themeSettleTimer!==void 0&&(clearTimeout(this.themeSettleTimer),this.themeSettleTimer=void 0),this.themeReadyState)return;this.themeReadyState=!0;const e=this.themeSettleWaiters;this.themeSettleWaiters=[];for(const t of e)t()}get scheme(){return this.schemeBacker}set scheme(e){const t=e==="dark"?"dark":e==="light"?"light":"",s=this.schemeBacker,h=this.schemeExplicitlySet;this.resolvingDefaultScheme||(this.schemeExplicitlySet=t.length>0);const i=t||this.resolveDefaultScheme();h!==this.schemeExplicitlySet&&this.isConnected&&this.syncSystemSchemeListener(),i!==s&&(this.schemeBacker=i,this.requestUpdate("scheme",s),this.themeEventsReady&&d().publish("scheme-changed",{scheme:i,correlationId:this.correlationId}))}get seedColor(){return this.activeTheme.seedColor}injectGoogleFontLink(e,t,s){const h=`${this.correlationId}-${e}`,i=A(t)?"":t;D({owner:`root:${h}`,family:i,weight:s,enabled:this.googleFontLoading!=="none"})}syncGoogleFontLinks(){this.googleFontLoading==="none"&&this.removeRuntimeGoogleFontLinks();const e=this.activeTheme;this.injectGoogleFontLink("body",p(e.fontBody),e.fontWeightBody),this.injectGoogleFontLink("headings",p(e.fontHeadings),e.fontWeightHeadings),this.injectGoogleFontLink("brand",p(e.fontBrand),e.fontWeightBrand),this.injectGoogleFontLink("menu",p(e.fontMenu),e.fontWeightMenu),this.injectGoogleFontLink("monospace",p(e.fontMonospace),e.fontWeightMonospace)}removeRuntimeGoogleFontLinks(){S(`root:${this.correlationId}-`),S(`picker:${this.correlationId}:`)}get activeTheme(){return this.scheme==="dark"?this.resolvedDarkTheme:this.resolvedLightTheme}resolveThemes(){const e=this.lightThemeAttr?u(this.lightThemeAttr):null;this.resolvedLightTheme=e?v(f,e):{...f};const t=this.darkThemeAttr?u(this.darkThemeAttr):null;this.resolvedDarkTheme=t?v(g,t):{...g}}connectedCallback(){super.connectedCallback(),this.registerDocumentClickBridge(),this.resizeObserver.observe(this),this.hasUpdated&&(this.applyDefaultScheme(),this.syncGoogleFontLinks(),this.hasAuthorTheme||this.startThemeSettleTimer())}willUpdate(e){const t=["lightThemeAttr","darkThemeAttr"];(!this.lastSeedColor||t.some(l=>e.has(l)))&&(this.resolveThemes(),this.themeEventsReady&&d().publish("theme-changed",{correlationId:this.correlationId})),this.hasAuthorTheme&&this.settleTheme();const h=F(this.activeTheme,this.scheme==="dark"?"dark":"light"),i=new Set(Object.keys(h));for(const l of this.appliedThemeProperties)i.has(l)||this.style.removeProperty(l);for(const[l,k]of Object.entries(h))this.style.setProperty(l,k);this.appliedThemeProperties=i;const m=this.activeTheme.seedColor;this.themeEventsReady&&this.lastSeedColor&&this.lastSeedColor!==m&&d().publish("seed-color-changed",{seedColor:m,correlationId:this.correlationId}),this.lastSeedColor=m,this.themeEventsReady&&e.has("iconSpriteUrl")&&d().publish("icon-sprite-url-changed",{iconSpriteUrl:this.iconSpriteUrl,correlationId:this.correlationId}),this.syncGoogleFontLinks()}firstUpdated(){const e=this.activeTheme.stylesheets;if(e.length)for(const t of e){const s=document.createElement("link");s.rel="stylesheet",s.href=t,document.head.appendChild(s)}if(!document.getElementById("esp-root-base-styles")){const t=document.createElement("style");t.id="esp-root-base-styles",t.textContent=a.lightDomStyles,document.head.appendChild(t)}this.applyDefaultScheme(),this.lastSeedColor=this.activeTheme.seedColor,this.themeEventsReady=!0,this.startThemeSettleTimer()}startThemeSettleTimer(){if(this.themeReadyState||this.themeSettleTimer!==void 0)return;this.themeSettleDeadline??=performance.now()+T;const e=Math.max(0,this.themeSettleDeadline-performance.now());if(e===0){this.closeThemeWindow();return}this.themeSettleTimer=setTimeout(()=>this.closeThemeWindow(),e)}closeThemeWindow(){this.themeSettleTimer=void 0,this.themePending&&!this.warnedThemeSettleTimeout&&(this.warnedThemeSettleTimeout=!0,console.warn(`Espalier root: theme-pending was declared but no ${this.scheme} theme arrived within ${T}ms, so the default palette is rendering. Assign ${this.scheme==="dark"?"darkTheme":"lightTheme"} (or remove theme-pending).`)),this.settleTheme()}updated(e){this.toggleAttribute("data-theme-ready",this.themeReadyState),(e.has("defaultScheme")||e.has("scheme"))&&!this.schemeExplicitlySet&&this.applyDefaultScheme()}disconnectedCallback(){this.themeSettleTimer!==void 0&&(clearTimeout(this.themeSettleTimer),this.themeSettleTimer=void 0),this.unregisterDocumentClickBridge(),this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null,this.resizeObserver.disconnect(),this.removeRuntimeGoogleFontLinks(),super.disconnectedCallback()}registerDocumentClickBridge(){this.documentClickRegistrationActive||(this.documentClickRegistrationActive=!0,a.connectedRootCount+=1,a.connectedRootCount===1&&document.addEventListener("click",a.handleDocumentClick))}unregisterDocumentClickBridge(){this.documentClickRegistrationActive&&(this.documentClickRegistrationActive=!1,a.connectedRootCount=Math.max(0,a.connectedRootCount-1),a.connectedRootCount===0&&document.removeEventListener("click",a.handleDocumentClick))}applyDefaultScheme(){this.schemeExplicitlySet||(this.resolvingDefaultScheme=!0,this.scheme=this.resolveDefaultScheme(),this.resolvingDefaultScheme=!1,this.syncSystemSchemeListener())}resolveDefaultScheme(){return this.defaultScheme==="dark"||this.defaultScheme==="system"&&window.matchMedia?.("(prefers-color-scheme: dark)").matches?"dark":"light"}syncSystemSchemeListener(){if(this.schemeExplicitlySet||this.defaultScheme!=="system"||!window.matchMedia){this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null;return}this.systemSchemeQuery||(this.systemSchemeQuery=window.matchMedia("(prefers-color-scheme: dark)"),this.systemSchemeQuery.addEventListener("change",this.handleSystemSchemeChange))}render(){return E`<slot></slot>`}};o.connectedRootCount=0,o.handleDocumentClick=c=>{const e=c.composedPath().filter(t=>t instanceof HTMLElement&&t.tagName==="ESP-POPOVER");d().publish("close-popovers",{source:c.target??void 0,skipPopovers:e})},o.lightDomStyles=`
+    ${b("esp-root [surface-layer]").cssText}
+
     
     esp-root {
       font-family: var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif));
@@ -127,7 +129,7 @@ var r=function(c,e,t,s){var h=arguments.length,i=h<3?e:s===null?s=Object.getOwnP
       max-width: 100%;
       display: block;
     }
-  `,o.styles=b`
+  `,o.styles=w`
     :host {
       display: block;
     }
@@ -136,4 +138,4 @@ var r=function(c,e,t,s){var h=arguments.length,i=h<3?e:s===null?s=Object.getOwnP
     :host([theme-pending]:not([data-theme-ready])) {
       visibility: hidden;
     }
-  `,r([n({attribute:!1})],o.prototype,"correlationId",void 0),r([n({attribute:"light-theme"})],o.prototype,"lightThemeAttr",void 0),r([n({attribute:"dark-theme"})],o.prototype,"darkThemeAttr",void 0),r([n({attribute:!1})],o.prototype,"lightTheme",null),r([n({attribute:!1})],o.prototype,"darkTheme",null),r([n({attribute:"font-css-root",type:String})],o.prototype,"fontCSSRoot",void 0),r([n({attribute:"font-definitions-url",type:String})],o.prototype,"fontDefinitionsUrl",void 0),r([n({attribute:"google-font-loading",type:String})],o.prototype,"googleFontLoading",void 0),r([n({attribute:"icon-sprite-url",type:String})],o.prototype,"iconSpriteUrl",void 0),r([n({attribute:"theme-pending",reflect:!0,type:Boolean})],o.prototype,"themePending",void 0),r([R()],o.prototype,"themeReadyState",void 0),r([n({attribute:"default-scheme",type:String,reflect:!0})],o.prototype,"defaultScheme",void 0),r([n({attribute:"scheme",type:String,reflect:!0})],o.prototype,"scheme",null),o=a=r([C("esp-root")],o);export{N as BUILT_IN_IMAGE_TEXTURES,o as EspalierRoot,Q as registerImageTexture,$ as registeredImageTextures};
+  `,r([n({attribute:!1})],o.prototype,"correlationId",void 0),r([n({attribute:"light-theme"})],o.prototype,"lightThemeAttr",void 0),r([n({attribute:"dark-theme"})],o.prototype,"darkThemeAttr",void 0),r([n({attribute:!1})],o.prototype,"lightTheme",null),r([n({attribute:!1})],o.prototype,"darkTheme",null),r([n({attribute:"font-css-root",type:String})],o.prototype,"fontCSSRoot",void 0),r([n({attribute:"font-definitions-url",type:String})],o.prototype,"fontDefinitionsUrl",void 0),r([n({attribute:"google-font-loading",type:String})],o.prototype,"googleFontLoading",void 0),r([n({attribute:"icon-sprite-url",type:String})],o.prototype,"iconSpriteUrl",void 0),r([n({attribute:"theme-pending",reflect:!0,type:Boolean})],o.prototype,"themePending",void 0),r([x()],o.prototype,"themeReadyState",void 0),r([n({attribute:"default-scheme",type:String,reflect:!0})],o.prototype,"defaultScheme",void 0),r([n({attribute:"scheme",type:String,reflect:!0})],o.prototype,"scheme",null),o=a=r([R("esp-root")],o);export{q as BUILT_IN_IMAGE_TEXTURES,o as EspalierRoot,N as registerImageTexture,V as registeredImageTextures};

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

@@ -5,8 +5,7 @@ declare const ROW_JUSTIFIES: readonly ["start", "center", "end", "between"];
 export type EspalierJustify = (typeof ROW_JUSTIFIES)[number];
 export { ROW_JUSTIFIES };
 /**
- * A horizontal flow: children sit in a wrapping row with a themed gap —
- * "row, wrap, gap Y" without writing flexbox (ADR-010's micro half).
+ * Arranges children in a wrapping row with a themed gap.
  *
  * ```html
  * <esp-row gap="small" justify="between">

package/dist/search/esp-search.js

@@ -83,6 +83,7 @@ var o=function(a,e,t,c){var h=arguments.length,r=h<3?e:c===null?c=Object.getOwnP
       }
 
       .panel {
+        --_esp-surface-layer: 1;
         position: relative;
         z-index: 2;
         width: 100%;
@@ -175,6 +176,7 @@ var o=function(a,e,t,c){var h=arguments.length,r=h<3?e:c===null?c=Object.getOwnP
         }
 
         &.active {
+          --_esp-surface-layer: 2;
           background: var(--esp-search-active-background, var(--esp-color-layer-2));
         }
       }

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

@@ -6,7 +6,7 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  * `esp-section` paints the local `--esp-color-background` edge to edge
  * and centers its content in a capped well. It carries no card identity:
  * no raised surface, no border radius, no shadow. Give it a `context`
- * (see the theming guide, `/guides/color/theming` on the docs site) and
+ * (see [theme overview](/espalier-guides/#foundations)) and
  * the band renders the zone's complete token table with nothing to
  * neutralize:
  *

package/dist/section/esp-section.js

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

package/dist/shared/configured-brand.d.ts

@@ -26,49 +26,23 @@ export interface ResolvedConfiguredBrand {
  */
 export declare function resolveConfiguredBrand({ scheme, brandLogo, brandColor, lightBrandLogo, darkBrandLogo, lightBrandColor, darkBrandColor, }: ConfiguredBrandConfiguration): ResolvedConfiguredBrand;
 /**
- * The ratio a configured-brand logo's box is reserved at before its bytes
- * arrive, shared by both consumers so they cannot drift apart.
+ * Reserve a logo's width while its image is loading or has failed.
  *
- * Both hosts give the logo a definite block size and leave the inline size to
- * the image, so until the image resolves there is no natural ratio to derive it
- * from: a pending request lays the element out at zero inline size and a failed
- * one at the width of its alt text. Either way the brand region resizes for a
- * reason that has nothing to do with the logo — on first paint, and again on
- * every scheme swap that fails, because both schemes exchange `src` at runtime.
+ * The header and footer give logos a fixed block size, so an image without
+ * intrinsic dimensions would otherwise have zero width or use its alt text's
+ * width. `aspect-ratio: auto <ratio>` uses this fallback only until a natural
+ * ratio is available, keeping loaded logos unchanged.
  *
- * Each host spends it as the fallback of its own
- * `--esp-{header,footer}-brand-logo-aspect-ratio`, in an
- * `aspect-ratio: auto <ratio>` declaration. `auto` is what makes this one
- * declaration the whole fix: it keeps a replaced element's *natural* ratio
- * authoritative whenever it has one, so a logo that loads is laid out exactly
- * as it is today — including a very wide one, where the inline cap clamps the
- * used width without feeding back into the definite block size. The ratio
- * governs only the states with nothing to measure.
- *
- * `3 / 1` because the existing caps already imply a wordmark of about that
- * shape: the footer's `3rem` block size against a `12rem` inline cap clamps at
- * 4:1, and the header's `0.72 x --esp-header-height` against the same cap
- * clamps near 3.7:1. A 3:1 reservation is therefore never born clamped, so the
- * reserved box is always the full ratio box.
+ * The 3:1 fallback fits below both hosts' existing inline caps, so the initial
+ * reservation is not clipped.
  */
 export declare const CONFIGURED_BRAND_LOGO_ASPECT_RATIO: import("lit").CSSResult;
 /**
- * Keep a failed logo's alt text from deciding how wide the logo's box is.
- *
- * The `alt` text is not suppressed — it still names the image for assistive
- * technology and still renders as the visible fallback. But a failed image is
- * no longer replaced content, so it takes an automatic minimum size from its
- * own text, and a minimum wider than the reserved box wins: measured in real
- * Chrome, a one-word alt of 37 characters pushed the header's logo back out to
- * its inline cap and swallowed the reservation whole. Allowing a break anywhere
- * makes that minimum one character wide, so the reserved ratio decides the box
- * and the alt text wraps inside it.
+ * Allow failed-image alt text to wrap within the reserved logo width.
  *
- * The footer already had this by inheritance — it sets `overflow-wrap` on
- * `.configured-brand`, where the header sets it only on `.brand-text` — so this
- * makes the two consumers agree rather than changing the footer. It has no
- * effect at all on an image that loads, because replaced content has no text to
- * break.
+ * A failed image can take its automatic minimum width from its alt text.
+ * Breaking long words prevents that minimum from overriding the reserved box.
+ * The text remains visible and accessible. Loaded images are unaffected.
  */
 export declare const configuredBrandLogoGeometry: import("lit").CSSResult;
 /**

package/dist/shared/esp-element-base.d.ts

@@ -8,7 +8,10 @@ import { type EspalierIntentVariant } from "./intent-values.js";
  * pickers, date pickers, buttons, and similar controls exposes the
  * following shared styling hooks:
  *
- * @cssprop --esp-field-background - Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.
+ * A field fills one layer above the surface it sits on.
+ *
+ * @attr {"1"|"2"|"3"|"4"} surface-layer - Declares the painted surface depth. Fields use the next local layer, capped at layer 4.
+ * @cssprop --esp-field-background - 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.
  * @cssprop --esp-field-border-color - Border color of the shared field shell. Defaults to `var(--esp-color-border)`.
  * @cssprop --esp-field-border-width - Border width of the shared field shell. Defaults to `1px`.
  * @cssprop --esp-field-text-color - Text color used inside the shared field shell. Defaults to `var(--esp-color-text)`.