@taprootio/espalier 2.8.1 → 2.10.0

package/dist/header/esp-header.js

@@ -1,4 +1,4 @@
-var n=function(h,e,t,o){var s=arguments.length,i=s<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,t):o,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(h,e,t,o);else for(var d=h.length-1;d>=0;d--)(l=h[d])&&(i=(s<3?l(i):s>3?l(e,t,i):l(e,t))||i);return s>3&&i&&Object.defineProperty(e,t,i),i};import{css as C,html as x,nothing as D}from"lit";import{customElement as k,property as a,state as c}from"lit/decorators.js";import{classMap as A}from"lit/directives/class-map.js";import{styleMap as B}from"lit/directives/style-map.js";import"../burger/esp-burger.js";import{createRef as E,ref as L}from"lit/directives/ref.js";import{EspalierMenu as m}from"./esp-menu.js";import{renderConfiguredBrand as O,resolveConfiguredBrand as _}from"../shared/configured-brand.js";import{EspalierElementBase as T}from"../shared/esp-element-base.js";import{ESP_EVENTS as R}from"../shared/events.js";const z="(max-width: 36rem)";function u(h,e){const t=new Set(h);return{allowedValues:t,converter:{fromAttribute(s){return s??e},toAttribute(s){return t.has(s)?s:e}},defaultValue:e}}const H=["standard","centered-brand","extended","extended-centered","minimal"],V=["start","center","end"],U=["truncate","wrap","nowrap"],N=["auto","inline","drawer"],I=["hidden","visible"],g=u(H,"standard"),b=u(V,"start"),f=u(U,"truncate"),v=u(N,"auto"),w=u(I,"hidden");let r=class extends T{constructor(){super(...arguments),this.menuOpen=!1,this.menuTooLarge=!1,this.mobileMenu=!1,this.scrolled=!1,this.hiddenByScroll=!1,this.scrollProgress=0,this.showBurger=!1,this.layout=g.defaultValue,this.brandText="",this.brandLogo="",this.lightBrandLogo="",this.darkBrandLogo="",this.brandHref="",this.brandAlt="",this.brandColor="",this.lightBrandColor="",this.darkBrandColor="",this.brandAlign=b.defaultValue,this.brandWrap=f.defaultValue,this.menuDisplay=v.defaultValue,this.themeToggle=w.defaultValue,this.scrollBehavior="none",this.scrollThreshold=16,this.dockOffset=0,this.drawerTarget="",this.fullBleedContent=!1,this.menuContainer=E(),this.menuButton=E(),this.menu=void 0,this.externalDrawerTarget=null,this.lastScrollY=0,this.lastInlineMenuWidth=0,this.mobileMenuQuery=null,this.menuDrawerListenersAttached=!1,this.observingMenuContainer=!1,this.scrollListenersAttached=!1,this.scrollRafId=null,this.resizeObserver=new ResizeObserver(()=>this.syncMenuLayout()),this.menuChildObserver=null,this.updateScrollState=()=>{this.scrollRafId===null&&(this.scrollRafId=requestAnimationFrame(()=>{this.scrollRafId=null,this.runScrollStateUpdate()}))},this.handleMobileMenuQueryChange=e=>{this.mobileMenu=e.matches,this.syncMenuLayout(),this.syncExternalDrawerControl()},this.toggleTheme=()=>{const e=this.getThemeRoot();if(!e)return;e.scheme=e.scheme==="dark"?"light":"dark";const t=e.scheme==="dark"?"dark":"light";this.dispatchEvent(new CustomEvent(R.ESP_THEME_TOGGLE,{detail:{scheme:t},bubbles:!0,composed:!0}))},this.handleMenuToggleClicked=()=>{if(this.menuOpen){this.closeNav();return}this.openNav()},this.onMenuDrawerOpened=()=>{this.menuOpen=!0,document.body.classList.add("menu-open"),this.burger&&(this.burger.menuOpen=!0)},this.onMenuDrawerClosed=()=>{this.menuOpen=!1,document.body.classList.remove("menu-open"),this.burger&&(this.burger.menuOpen=!1)}}syncMenuLayout(){if(!this.menuContainer.value||!this.menu||!this.menu.getWidth)return;const e=this.menuContainer.value.clientWidth,t=this.menu.getWidth();t>0&&(this.lastInlineMenuWidth=t);const o=this.lastInlineMenuWidth||t,s=this.getExternalDrawerTarget(),i=this.menuDisplay!=="inline",l=this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal";this.menuTooLarge=i&&this.menuDisplay==="auto"&&o>e,this.menu.sliding=i&&!s&&this.hasDrawerableContent()&&(this.menuTooLarge||l||this.mobileMenu)}menuHasContent(){return!!(this.menu??this.querySelector(':scope > [slot="menu"]'))?.querySelector("esp-menu-item, esp-menu-group")}hasDrawerableContent(){return this.showBurger||!!this.getExternalDrawerTarget()||this.menuHasContent()}getExternalDrawerTarget(){if(!this.drawerTarget)return null;const e=document.getElementById(this.drawerTarget);return e===this.menu?null:e&&"openDrawer"in e&&typeof e.openDrawer=="function"&&"closeDrawer"in e&&typeof e.closeDrawer=="function"?e:null}getBurgerFocusTarget(){const t=this.shadowRoot?.querySelector("esp-header-button.menu-toggle")?.shadowRoot?.querySelector("button"),o=this.menuButton.value?.shadowRoot?.querySelector("button");return t??o??null}getScrollTokens(){const e=this.scrollBehavior.split(/\s+/).map(t=>t.trim().toLowerCase()).filter(Boolean);return new Set(e.filter(t=>t!=="none"))}getEffectiveScrollThreshold(){return Number.isFinite(this.scrollThreshold)?Math.max(0,this.scrollThreshold):0}clearScrollState(){this.scrolled=!1,this.hiddenByScroll=!1,this.scrollProgress=0}runScrollStateUpdate(){const e=this.getScrollTokens();if(!e.size){this.clearScrollState();return}const t=Math.max(0,window.scrollY||document.documentElement.scrollTop||0),o=this.getEffectiveScrollThreshold(),s=Number.isFinite(this.dockOffset)?Math.max(0,this.dockOffset):o,i=t>(e.has("dock")?s:o),l=t>this.lastScrollY,d=e.has("reveal")&&l&&t>o&&!this.menuOpen;if(this.scrolled=i,this.hiddenByScroll=d,e.has("progress")){const p=document.documentElement,y=Math.max(1,p.scrollHeight-window.innerHeight);this.scrollProgress=Math.min(1,t/y)}else this.scrollProgress=0;this.lastScrollY=t}cancelScrollUpdate(){this.scrollRafId!==null&&(cancelAnimationFrame(this.scrollRafId),this.scrollRafId=null)}syncScrollListeners(){const e=this.getScrollTokens().size>0;if(e&&!this.scrollListenersAttached?(window.addEventListener("scroll",this.updateScrollState,{passive:!0}),window.addEventListener("resize",this.updateScrollState,{passive:!0}),this.scrollListenersAttached=!0):!e&&this.scrollListenersAttached&&this.removeScrollListeners(),e){this.updateScrollState();return}this.cancelScrollUpdate(),this.clearScrollState()}removeScrollListeners(){this.scrollListenersAttached&&(window.removeEventListener("scroll",this.updateScrollState),window.removeEventListener("resize",this.updateScrollState),this.scrollListenersAttached=!1)}addMenuDrawerListeners(){!this.menu||this.menuDrawerListenersAttached||(this.menu.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.menu.addEventListener("drawer-closed",this.onMenuDrawerClosed),this.menuDrawerListenersAttached=!0)}removeMenuDrawerListeners(){!this.menu||!this.menuDrawerListenersAttached||(this.menu.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.menu.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.menuDrawerListenersAttached=!1)}observeMenuContainer(){!this.menuContainer.value||this.observingMenuContainer||(this.resizeObserver.observe(this.menuContainer.value),this.observingMenuContainer=!0)}disconnectResizeObserver(){this.observingMenuContainer&&(this.resizeObserver.disconnect(),this.observingMenuContainer=!1)}observeMenuChildren(){!this.menu||this.menuChildObserver||(this.menuChildObserver=new MutationObserver(()=>{this.syncMenuLayout(),this.requestUpdate()}),this.menuChildObserver.observe(this.menu,{childList:!0,subtree:!0}))}syncMobileMenuQuery(){if("matchMedia"in window){if(!this.mobileMenuQuery){this.mobileMenuQuery=window.matchMedia(z),this.mobileMenu=this.mobileMenuQuery.matches,this.mobileMenuQuery.addEventListener("change",this.handleMobileMenuQueryChange);return}this.mobileMenu=this.mobileMenuQuery.matches}}getThemeRoot(){return this.traverseToClosest("esp-root")}syncExternalDrawerTarget(){const e=this.getExternalDrawerTarget(),t=e===this.menu?null:e;t!==this.externalDrawerTarget&&(this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget instanceof m&&(this.externalDrawerTarget.hasExternalDrawerControl=!1),this.externalDrawerTarget=t,this.externalDrawerTarget?.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.addEventListener("drawer-closed",this.onMenuDrawerClosed)),this.syncExternalDrawerControl()}burgerVisibleForTarget(){if(this.menuDisplay==="inline")return!1;const e=this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal";return this.menuTooLarge||this.mobileMenu||e}syncExternalDrawerControl(){this.externalDrawerTarget instanceof m&&(this.externalDrawerTarget.hasExternalDrawerControl=this.burgerVisibleForTarget())}openNav(){const e=this.getBurgerFocusTarget(),t=this.getExternalDrawerTarget();if(this.burger&&(this.burger.menuOpen=!0),t){this.menuOpen=!0,t.openDrawer(e),document.body.classList.add("menu-open");return}if(this.menu){this.menu.sliding=!0,this.menuOpen=!0,this.menu.openDrawer(e),document.body.classList.add("menu-open");return}this.burger&&(this.burger.menuOpen=!1)}closeNav(){this.menuOpen=!1,this.burger&&(this.burger.menuOpen=!1);const e=this.getExternalDrawerTarget();if(e){e.closeDrawer(),document.body.classList.remove("menu-open");return}this.menu&&(this.menu.closeDrawer(),document.body.classList.remove("menu-open"))}get burger(){return this.menuButton.value??void 0}willUpdate(e){super.willUpdate(e),e.has("layout")&&!g.allowedValues.has(this.layout)&&(this.layout=g.defaultValue),e.has("brandAlign")&&!b.allowedValues.has(this.brandAlign)&&(this.brandAlign=b.defaultValue),e.has("brandWrap")&&!f.allowedValues.has(this.brandWrap)&&(this.brandWrap=f.defaultValue),e.has("menuDisplay")&&!v.allowedValues.has(this.menuDisplay)&&(this.menuDisplay=v.defaultValue),e.has("themeToggle")&&!w.allowedValues.has(this.themeToggle)&&(this.themeToggle=w.defaultValue)}firstUpdated(e){if(super.firstUpdated(e),!this.menuContainer.value)return;const s=(this.menuContainer.value.firstElementChild?.assignedElements()??[])[0];s instanceof m?(this.menu=s,this.addMenuDrawerListeners(),this.observeMenuChildren()):s&&console.warn("<esp-header>: the menu slot expects an <esp-menu> element, received",s),this.observeMenuContainer(),this.syncExternalDrawerTarget(),this.syncMobileMenuQuery(),this.syncScrollListeners(),this.syncMenuLayout()}updated(e){super.updated(e),(e.has("showBurger")||e.has("drawerTarget")||e.has("menuDisplay")||e.has("layout"))&&(this.syncExternalDrawerTarget(),this.syncMenuLayout()),(e.has("mobileMenu")||e.has("menuTooLarge"))&&this.syncExternalDrawerControl(),e.has("scrollBehavior")?this.syncScrollListeners():(e.has("scrollThreshold")||e.has("dockOffset"))&&this.updateScrollState()}connectedCallback(){super.connectedCallback(),this.syncScrollListeners(),this.syncMobileMenuQuery(),this.addMenuDrawerListeners(),this.syncExternalDrawerTarget(),this.observeMenuContainer(),this.observeMenuChildren()}disconnectedCallback(){this.removeMenuDrawerListeners(),this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget instanceof m&&(this.externalDrawerTarget.hasExternalDrawerControl=!1),this.externalDrawerTarget=null,this.mobileMenuQuery?.removeEventListener("change",this.handleMobileMenuQueryChange),this.mobileMenuQuery=null,this.removeScrollListeners(),this.cancelScrollUpdate(),this.disconnectResizeObserver(),this.menuChildObserver?.disconnect(),this.menuChildObserver=null,super.disconnectedCallback()}render(){const{menuOpen:e,menuTooLarge:t,mobileMenu:o}=this,s=this.menuDisplay!=="inline",i=s&&(this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal"),l=this.getScrollTokens(),d=l.has("progress"),p=_({scheme:this.scheme,brandLogo:this.brandLogo,brandColor:this.brandColor,lightBrandLogo:this.lightBrandLogo,darkBrandLogo:this.darkBrandLogo,lightBrandColor:this.lightBrandColor,darkBrandColor:this.darkBrandColor}),y={"--_esp-header-brand-color":p.brandColor||null,"--_esp-header-scroll-progress":String(this.scrollProgress)},M={"menu-open":e,"too-wide":s&&this.hasDrawerableContent()&&(t||o||i),[`layout-${this.layout}`]:!0,"is-scrolled":this.scrolled,"hide-on-scroll":this.hiddenByScroll,"scroll-compact":l.has("compact"),"scroll-elevate":l.has("elevate"),"scroll-transparent":l.has("transparent")||l.has("transparent-to-solid"),"scroll-collapse-topbar":l.has("collapse-topbar")},S=this.scheme==="dark"?"light":"dark";return x`
+var n=function(h,e,t,o){var s=arguments.length,i=s<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,t):o,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(h,e,t,o);else for(var d=h.length-1;d>=0;d--)(l=h[d])&&(i=(s<3?l(i):s>3?l(e,t,i):l(e,t))||i);return s>3&&i&&Object.defineProperty(e,t,i),i};import{css as S,html as x,nothing as D}from"lit";import{customElement as k,property as a,state as c}from"lit/decorators.js";import{classMap as A}from"lit/directives/class-map.js";import{styleMap as B}from"lit/directives/style-map.js";import"../burger/esp-burger.js";import{createRef as E,ref as L}from"lit/directives/ref.js";import{EspalierMenu as m}from"./esp-menu.js";import{renderConfiguredBrand as O,resolveConfiguredBrand as _}from"../shared/configured-brand.js";import{EspalierElementBase as T}from"../shared/esp-element-base.js";import{ESP_EVENTS as R}from"../shared/events.js";const z="(max-width: 36rem)";function u(h,e){const t=new Set(h);return{allowedValues:t,converter:{fromAttribute(s){return s??e},toAttribute(s){return t.has(s)?s:e}},defaultValue:e}}const H=["standard","centered-brand","extended","extended-centered","minimal"],V=["start","center","end"],U=["truncate","wrap","nowrap"],N=["auto","inline","drawer"],I=["hidden","visible"],g=u(H,"standard"),b=u(V,"start"),v=u(U,"truncate"),f=u(N,"auto"),w=u(I,"hidden");let r=class extends T{constructor(){super(...arguments),this.menuOpen=!1,this.menuTooLarge=!1,this.mobileMenu=!1,this.scrolled=!1,this.hiddenByScroll=!1,this.scrollProgress=0,this.showBurger=!1,this.layout=g.defaultValue,this.brandText="",this.brandLogo="",this.lightBrandLogo="",this.darkBrandLogo="",this.brandHref="",this.brandAlt="",this.brandColor="",this.lightBrandColor="",this.darkBrandColor="",this.brandAlign=b.defaultValue,this.brandWrap=v.defaultValue,this.menuDisplay=f.defaultValue,this.themeToggle=w.defaultValue,this.scrollBehavior="none",this.scrollThreshold=16,this.dockOffset=0,this.drawerTarget="",this.previewCollapseRequested=!1,this.fullBleedContent=!1,this.menuContainer=E(),this.menuButton=E(),this.menu=void 0,this.externalDrawerTarget=null,this.lastScrollY=0,this.lastInlineMenuWidth=0,this.mobileMenuQuery=null,this.menuDrawerListenersAttached=!1,this.observingMenuContainer=!1,this.scrollListenersAttached=!1,this.scrollRafId=null,this.resizeObserver=new ResizeObserver(()=>this.syncMenuLayout()),this.menuChildObserver=null,this.updateScrollState=()=>{this.scrollRafId===null&&(this.scrollRafId=requestAnimationFrame(()=>{this.scrollRafId=null,this.runScrollStateUpdate()}))},this.handleMobileMenuQueryChange=e=>{this.mobileMenu=e.matches,this.syncMenuLayout(),this.syncExternalDrawerControl()},this.toggleTheme=()=>{const e=this.getThemeRoot();if(!e)return;e.scheme=e.scheme==="dark"?"light":"dark";const t=e.scheme==="dark"?"dark":"light";this.dispatchEvent(new CustomEvent(R.ESP_THEME_TOGGLE,{detail:{scheme:t},bubbles:!0,composed:!0}))},this.handleMenuToggleClicked=()=>{if(this.menuOpen){this.closeNav();return}this.openNav()},this.onMenuDrawerOpened=()=>{this.menuOpen=!0,document.body.classList.add("menu-open"),this.burger&&(this.burger.menuOpen=!0)},this.onMenuDrawerClosed=()=>{this.menuOpen=!1,document.body.classList.remove("menu-open"),this.burger&&(this.burger.menuOpen=!1)}}syncMenuLayout(){if(!this.menuContainer.value||!this.menu||!this.menu.getWidth)return;const e=this.menuContainer.value.clientWidth,t=this.menu.getWidth();t>0&&(this.lastInlineMenuWidth=t);const o=this.lastInlineMenuWidth||t,s=this.getExternalDrawerTarget(),i=this.menuDisplay!=="inline",l=this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal"||this.previewCollapseRequested;this.menuTooLarge=i&&this.menuDisplay==="auto"&&o>e,this.menu.sliding=i&&!s&&this.hasDrawerableContent()&&(this.menuTooLarge||l||this.mobileMenu)}menuHasContent(){return!!(this.menu??this.querySelector(':scope > [slot="menu"]'))?.querySelector("esp-menu-item, esp-menu-group")}hasDrawerableContent(){return this.showBurger||!!this.getExternalDrawerTarget()||this.menuHasContent()}getExternalDrawerTarget(){if(!this.drawerTarget)return null;const e=document.getElementById(this.drawerTarget);return e===this.menu?null:e&&"openDrawer"in e&&typeof e.openDrawer=="function"&&"closeDrawer"in e&&typeof e.closeDrawer=="function"?e:null}getBurgerFocusTarget(){const t=this.shadowRoot?.querySelector("esp-header-button.menu-toggle")?.shadowRoot?.querySelector("button"),o=this.menuButton.value?.shadowRoot?.querySelector("button");return t??o??null}getScrollTokens(){const e=this.scrollBehavior.split(/\s+/).map(t=>t.trim().toLowerCase()).filter(Boolean);return new Set(e.filter(t=>t!=="none"))}getEffectiveScrollThreshold(){return Number.isFinite(this.scrollThreshold)?Math.max(0,this.scrollThreshold):0}clearScrollState(){this.scrolled=!1,this.hiddenByScroll=!1,this.scrollProgress=0}runScrollStateUpdate(){const e=this.getScrollTokens();if(!e.size){this.clearScrollState();return}const t=Math.max(0,window.scrollY||document.documentElement.scrollTop||0),o=this.getEffectiveScrollThreshold(),s=Number.isFinite(this.dockOffset)?Math.max(0,this.dockOffset):o,i=t>(e.has("dock")?s:o),l=t>this.lastScrollY,d=e.has("reveal")&&l&&t>o&&!this.menuOpen;if(this.scrolled=i,this.hiddenByScroll=d,e.has("progress")){const p=document.documentElement,y=Math.max(1,p.scrollHeight-window.innerHeight);this.scrollProgress=Math.min(1,t/y)}else this.scrollProgress=0;this.lastScrollY=t}cancelScrollUpdate(){this.scrollRafId!==null&&(cancelAnimationFrame(this.scrollRafId),this.scrollRafId=null)}syncScrollListeners(){const e=this.getScrollTokens().size>0;if(e&&!this.scrollListenersAttached?(window.addEventListener("scroll",this.updateScrollState,{passive:!0}),window.addEventListener("resize",this.updateScrollState,{passive:!0}),this.scrollListenersAttached=!0):!e&&this.scrollListenersAttached&&this.removeScrollListeners(),e){this.updateScrollState();return}this.cancelScrollUpdate(),this.clearScrollState()}removeScrollListeners(){this.scrollListenersAttached&&(window.removeEventListener("scroll",this.updateScrollState),window.removeEventListener("resize",this.updateScrollState),this.scrollListenersAttached=!1)}addMenuDrawerListeners(){!this.menu||this.menuDrawerListenersAttached||(this.menu.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.menu.addEventListener("drawer-closed",this.onMenuDrawerClosed),this.menuDrawerListenersAttached=!0)}removeMenuDrawerListeners(){!this.menu||!this.menuDrawerListenersAttached||(this.menu.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.menu.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.menuDrawerListenersAttached=!1)}observeMenuContainer(){!this.menuContainer.value||this.observingMenuContainer||(this.resizeObserver.observe(this.menuContainer.value),this.observingMenuContainer=!0)}disconnectResizeObserver(){this.observingMenuContainer&&(this.resizeObserver.disconnect(),this.observingMenuContainer=!1)}observeMenuChildren(){!this.menu||this.menuChildObserver||(this.menuChildObserver=new MutationObserver(()=>{this.syncMenuLayout(),this.requestUpdate()}),this.menuChildObserver.observe(this.menu,{childList:!0,subtree:!0}))}syncMobileMenuQuery(){if("matchMedia"in window){if(!this.mobileMenuQuery){this.mobileMenuQuery=window.matchMedia(z),this.mobileMenu=this.mobileMenuQuery.matches,this.mobileMenuQuery.addEventListener("change",this.handleMobileMenuQueryChange);return}this.mobileMenu=this.mobileMenuQuery.matches}}getThemeRoot(){return this.traverseToClosest("esp-root")}syncExternalDrawerTarget(){const e=this.getExternalDrawerTarget(),t=e===this.menu?null:e;t!==this.externalDrawerTarget&&(this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget instanceof m&&(this.externalDrawerTarget.hasExternalDrawerControl=!1),this.externalDrawerTarget=t,this.externalDrawerTarget?.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.addEventListener("drawer-closed",this.onMenuDrawerClosed)),this.syncExternalDrawerControl()}burgerVisibleForTarget(){if(this.menuDisplay==="inline")return!1;const e=this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal"||this.previewCollapseRequested;return this.menuTooLarge||this.mobileMenu||e}syncExternalDrawerControl(){this.externalDrawerTarget instanceof m&&(this.externalDrawerTarget.hasExternalDrawerControl=this.burgerVisibleForTarget())}openNav(){const e=this.getBurgerFocusTarget(),t=this.getExternalDrawerTarget();if(this.burger&&(this.burger.menuOpen=!0),t){this.menuOpen=!0,t.openDrawer(e),document.body.classList.add("menu-open");return}if(this.menu){this.menu.sliding=!0,this.menuOpen=!0,this.menu.openDrawer(e),document.body.classList.add("menu-open");return}this.burger&&(this.burger.menuOpen=!1)}closeNav(){this.menuOpen=!1,this.burger&&(this.burger.menuOpen=!1);const e=this.getExternalDrawerTarget();if(e){e.closeDrawer(),document.body.classList.remove("menu-open");return}this.menu&&(this.menu.closeDrawer(),document.body.classList.remove("menu-open"))}get burger(){return this.menuButton.value??void 0}willUpdate(e){super.willUpdate(e),e.has("layout")&&!g.allowedValues.has(this.layout)&&(this.layout=g.defaultValue),e.has("brandAlign")&&!b.allowedValues.has(this.brandAlign)&&(this.brandAlign=b.defaultValue),e.has("brandWrap")&&!v.allowedValues.has(this.brandWrap)&&(this.brandWrap=v.defaultValue),e.has("menuDisplay")&&!f.allowedValues.has(this.menuDisplay)&&(this.menuDisplay=f.defaultValue),e.has("themeToggle")&&!w.allowedValues.has(this.themeToggle)&&(this.themeToggle=w.defaultValue)}firstUpdated(e){if(super.firstUpdated(e),!this.menuContainer.value)return;const s=(this.menuContainer.value.firstElementChild?.assignedElements()??[])[0];s instanceof m?(this.menu=s,this.addMenuDrawerListeners(),this.observeMenuChildren()):s&&console.warn("<esp-header>: the menu slot expects an <esp-menu> element, received",s),this.observeMenuContainer(),this.syncExternalDrawerTarget(),this.syncMobileMenuQuery(),this.syncScrollListeners(),this.syncMenuLayout()}updated(e){super.updated(e),(e.has("showBurger")||e.has("drawerTarget")||e.has("menuDisplay")||e.has("layout")||e.has("previewCollapseRequested"))&&(this.syncExternalDrawerTarget(),this.syncMenuLayout()),(e.has("mobileMenu")||e.has("menuTooLarge"))&&this.syncExternalDrawerControl(),e.has("scrollBehavior")?this.syncScrollListeners():(e.has("scrollThreshold")||e.has("dockOffset"))&&this.updateScrollState()}connectedCallback(){super.connectedCallback(),this.syncScrollListeners(),this.syncMobileMenuQuery(),this.addMenuDrawerListeners(),this.syncExternalDrawerTarget(),this.observeMenuContainer(),this.observeMenuChildren()}disconnectedCallback(){this.removeMenuDrawerListeners(),this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget instanceof m&&(this.externalDrawerTarget.hasExternalDrawerControl=!1),this.externalDrawerTarget=null,this.mobileMenuQuery?.removeEventListener("change",this.handleMobileMenuQueryChange),this.mobileMenuQuery=null,this.removeScrollListeners(),this.cancelScrollUpdate(),this.disconnectResizeObserver(),this.menuChildObserver?.disconnect(),this.menuChildObserver=null,super.disconnectedCallback()}render(){const{menuOpen:e,menuTooLarge:t,mobileMenu:o}=this,s=this.menuDisplay!=="inline",i=s&&(this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal"||this.previewCollapseRequested),l=this.getScrollTokens(),d=l.has("progress"),p=_({scheme:this.scheme,brandLogo:this.brandLogo,brandColor:this.brandColor,lightBrandLogo:this.lightBrandLogo,darkBrandLogo:this.darkBrandLogo,lightBrandColor:this.lightBrandColor,darkBrandColor:this.darkBrandColor}),y={"--_esp-header-brand-color":p.brandColor||null,"--_esp-header-scroll-progress":String(this.scrollProgress)},M={"menu-open":e,"too-wide":s&&this.hasDrawerableContent()&&(t||o||i),[`layout-${this.layout}`]:!0,"is-scrolled":this.scrolled,"hide-on-scroll":this.hiddenByScroll,"scroll-compact":l.has("compact"),"scroll-elevate":l.has("elevate"),"scroll-transparent":l.has("transparent")||l.has("transparent-to-solid"),"scroll-collapse-topbar":l.has("collapse-topbar")},C=this.scheme==="dark"?"light":"dark";return x`
       <header class=${A(M)} style=${B(y)}>
         <section class="topbar">
           <slot name="topbar"></slot>
@@ -19,7 +19,7 @@ var n=function(h,e,t,o){var s=arguments.length,i=s<3?e:o===null?o=Object.getOwnP
           ${this.themeToggle==="visible"?x`<esp-header-button
                 class="theme-toggle"
                 icon=${this.scheme==="dark"?"sun":"moon"}
-                aria-label=${`Switch to ${S} mode`}
+                aria-label=${`Switch to ${C} mode`}
                 @clicked=${this.toggleTheme}
               ></esp-header-button>`:D}
           <esp-header-button
@@ -35,7 +35,7 @@ var n=function(h,e,t,o){var s=arguments.length,i=s<3?e:o===null?o=Object.getOwnP
         </section>
         ${d?x`<div class="scroll-progress" aria-hidden="true"></div>`:D}
       </header>
-    `}};r.styles=[...T.styles,C`
+    `}};r.styles=[...T.styles,S`
       :host {
         --_esp-header-current-height: var(--esp-header-height, calc(4.5 * var(--esp-size-small)));
 
@@ -429,4 +429,4 @@ var n=function(h,e,t,o){var s=arguments.length,i=s<3?e:o===null?o=Object.getOwnP
           transition: none;
         }
       }
-    `],n([c()],r.prototype,"menuOpen",void 0),n([c()],r.prototype,"menuTooLarge",void 0),n([c()],r.prototype,"mobileMenu",void 0),n([c()],r.prototype,"scrolled",void 0),n([c()],r.prototype,"hiddenByScroll",void 0),n([c()],r.prototype,"scrollProgress",void 0),n([a({attribute:"show-burger",type:Boolean})],r.prototype,"showBurger",void 0),n([a({converter:g.converter,reflect:!0})],r.prototype,"layout",void 0),n([a({attribute:"brand-text",type:String})],r.prototype,"brandText",void 0),n([a({attribute:"brand-logo",type:String})],r.prototype,"brandLogo",void 0),n([a({attribute:"light-brand-logo",type:String})],r.prototype,"lightBrandLogo",void 0),n([a({attribute:"dark-brand-logo",type:String})],r.prototype,"darkBrandLogo",void 0),n([a({attribute:"brand-href",type:String})],r.prototype,"brandHref",void 0),n([a({attribute:"brand-alt",type:String})],r.prototype,"brandAlt",void 0),n([a({attribute:"brand-color",type:String})],r.prototype,"brandColor",void 0),n([a({attribute:"light-brand-color",type:String})],r.prototype,"lightBrandColor",void 0),n([a({attribute:"dark-brand-color",type:String})],r.prototype,"darkBrandColor",void 0),n([a({attribute:"brand-align",converter:b.converter,reflect:!0})],r.prototype,"brandAlign",void 0),n([a({attribute:"brand-wrap",converter:f.converter,reflect:!0})],r.prototype,"brandWrap",void 0),n([a({attribute:"menu-display",converter:v.converter,reflect:!0})],r.prototype,"menuDisplay",void 0),n([a({attribute:"theme-toggle",converter:w.converter,reflect:!0})],r.prototype,"themeToggle",void 0),n([a({attribute:"scroll-behavior",type:String})],r.prototype,"scrollBehavior",void 0),n([a({attribute:"scroll-threshold",type:Number})],r.prototype,"scrollThreshold",void 0),n([a({attribute:"dock-offset",type:Number})],r.prototype,"dockOffset",void 0),n([a({attribute:"drawer-target",type:String})],r.prototype,"drawerTarget",void 0),n([a({attribute:"full-bleed-content",type:Boolean,reflect:!0})],r.prototype,"fullBleedContent",void 0),r=n([k("esp-header")],r);export{r as EspalierHeader};
+    `],n([c()],r.prototype,"menuOpen",void 0),n([c()],r.prototype,"menuTooLarge",void 0),n([c()],r.prototype,"mobileMenu",void 0),n([c()],r.prototype,"scrolled",void 0),n([c()],r.prototype,"hiddenByScroll",void 0),n([c()],r.prototype,"scrollProgress",void 0),n([a({attribute:"show-burger",type:Boolean})],r.prototype,"showBurger",void 0),n([a({converter:g.converter,reflect:!0})],r.prototype,"layout",void 0),n([a({attribute:"brand-text",type:String})],r.prototype,"brandText",void 0),n([a({attribute:"brand-logo",type:String})],r.prototype,"brandLogo",void 0),n([a({attribute:"light-brand-logo",type:String})],r.prototype,"lightBrandLogo",void 0),n([a({attribute:"dark-brand-logo",type:String})],r.prototype,"darkBrandLogo",void 0),n([a({attribute:"brand-href",type:String})],r.prototype,"brandHref",void 0),n([a({attribute:"brand-alt",type:String})],r.prototype,"brandAlt",void 0),n([a({attribute:"brand-color",type:String})],r.prototype,"brandColor",void 0),n([a({attribute:"light-brand-color",type:String})],r.prototype,"lightBrandColor",void 0),n([a({attribute:"dark-brand-color",type:String})],r.prototype,"darkBrandColor",void 0),n([a({attribute:"brand-align",converter:b.converter,reflect:!0})],r.prototype,"brandAlign",void 0),n([a({attribute:"brand-wrap",converter:v.converter,reflect:!0})],r.prototype,"brandWrap",void 0),n([a({attribute:"menu-display",converter:f.converter,reflect:!0})],r.prototype,"menuDisplay",void 0),n([a({attribute:"theme-toggle",converter:w.converter,reflect:!0})],r.prototype,"themeToggle",void 0),n([a({attribute:"scroll-behavior",type:String})],r.prototype,"scrollBehavior",void 0),n([a({attribute:"scroll-threshold",type:Number})],r.prototype,"scrollThreshold",void 0),n([a({attribute:"dock-offset",type:Number})],r.prototype,"dockOffset",void 0),n([a({attribute:"drawer-target",type:String})],r.prototype,"drawerTarget",void 0),n([a({attribute:!1})],r.prototype,"previewCollapseRequested",void 0),n([a({attribute:"full-bleed-content",type:Boolean,reflect:!0})],r.prototype,"fullBleedContent",void 0),r=n([k("esp-header")],r);export{r as EspalierHeader};

package/dist/help/esp-help-button.d.ts

@@ -0,0 +1,61 @@
+import { nothing, type PropertyValues } from "lit";
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+/**
+ * An icon-only trigger for URL-addressable help. Set `help-url` directly or
+ * place the button beneath an ancestor carrying `help-src`; `anchor` selects
+ * a stable heading id inside that document. The provider keeps the button's
+ * pressed state synchronized while its topic is showing.
+ *
+ * ```html
+ * <section help-src="/help/billing.html">
+ *   <h2>
+ *     Billing
+ *     <esp-help-button anchor="billing" label="Help for billing"></esp-help-button>
+ *   </h2>
+ * </section>
+ *
+ * <esp-help-button
+ *   help-url="/help/exporting.html#csv"
+ *   label="Help with CSV exports"
+ *   title="Export help">
+ * </esp-help-button>
+ * ```
+ *
+ * @docPageTitle Help Button
+ * @docUrl /components/help/button
+ * @menuGroup Interaction
+ * @menuLabel Help Button
+ * @menuIcon info
+ */
+export declare class EspalierHelpButton extends EspalierElementBase {
+    /**
+     * Per-trigger help document override. May include a topic fragment. When
+     * omitted, the nearest composed-tree ancestor's `help-src` is used.
+     */
+    helpUrl: string;
+    /** Stable heading id inside the resolved help document. */
+    anchor: string;
+    /** Accessible label for the icon-only button. */
+    label: string;
+    /** Optional flyout heading. Topic/document headings are used when omitted. */
+    helpTitle: string;
+    /**
+     * Element the contextual flyout should point at. Form items set this to
+     * their field control while the help button remains the focus-return target.
+     */
+    placementTarget: HTMLElement | undefined;
+    /** Whether this button's exact help topic is currently showing. */
+    active: boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Forward focus to the composed native control. */
+    focus(options?: FocusOptions): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): import("lit-html").TemplateResult<1> | typeof nothing;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-help-button": EspalierHelpButton;
+    }
+}

package/dist/help/esp-help-button.js

@@ -0,0 +1,49 @@
+var i=function(s,e,t,l){var a=arguments.length,o=a<3?e:l===null?l=Object.getOwnPropertyDescriptor(e,t):l,c;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(s,e,t,l);else for(var p=s.length-1;p>=0;p--)(c=s[p])&&(o=(a<3?c(o):a>3?c(e,t,o):c(e,t))||o);return a>3&&o&&Object.defineProperty(e,t,o),o};import{css as d,html as b,nothing as f}from"lit";import{customElement as g,property as n}from"lit/decorators.js";import{EspalierElementBase as u}from"../shared/esp-element-base.js";import{getEspBus as h}from"../shared/bus-events.js";import{requestHelp as m}from"../shared/help-events.js";import{getIconHrefForHost as v}from"../shared/intent-values.js";import{renderSpriteIcon as y}from"../shared/svgs/render-sprite-icon.js";import{resolveHelpTarget as T}from"./help-document.js";let r=class extends u{constructor(){super(...arguments),this.helpUrl="",this.anchor="",this.label="Help",this.helpTitle="",this.active=!1,this.boundHelpStateChanged=e=>{const t=this.resolvedTarget;this.active=!!(e.open&&t&&t.src===e.src&&(t.anchor??"")===(e.anchor??""))},this.handleActivation=()=>{if(this.active){const t=this.resolvedTarget;if(!t)return;h().publish("close-help",{src:t.src,...t.anchor?{anchor:t.anchor}:{}});return}const e=this.resolvedTarget;e&&m({src:e.src,...e.anchor?{anchor:e.anchor}:{},...this.helpTitle.trim()?{title:this.helpTitle.trim()}:{},...this.placementTarget?{placementTarget:this.placementTarget}:{},trigger:this})}}get resolvedTarget(){return T(this,{helpUrl:this.helpUrl,anchor:this.anchor})}connectedCallback(){super.connectedCallback(),h().subscribe("help-state-changed",this.boundHelpStateChanged)}disconnectedCallback(){h().unsubscribe("help-state-changed",this.boundHelpStateChanged),super.disconnectedCallback()}focus(e){this.shadowRoot?.querySelector("button")?.focus(e)}updated(e){super.updated(e),(e.has("helpUrl")||e.has("anchor"))&&(this.active=!1)}render(){if(!this.resolvedTarget)return f;const t=this.getAttribute("aria-label")?.trim()||this.label||"Help",l=v("info",this);return b`
+      <button
+        type="button"
+        aria-label=${t}
+        aria-pressed=${this.active?"true":"false"}
+        @click=${this.handleActivation}
+      >
+        ${y(l)}
+      </button>
+    `}};r.styles=[...u.styles,d`
+      :host {
+        display: inline-flex;
+        vertical-align: middle;
+      }
+
+      button {
+        appearance: none;
+        background: transparent;
+        border: 0;
+        border-radius: 0;
+        color: var(--esp-color-link);
+        cursor: pointer;
+        display: inline-grid;
+        font: inherit;
+        line-height: 1;
+        margin: 0;
+        padding: 0;
+        place-items: center;
+        transition:
+          background-color 0.15s ease,
+          color 0.15s ease;
+
+        .generated-icon {
+          block-size: 1em;
+          inline-size: 1em;
+        }
+
+        &:hover,
+        &[aria-pressed="true"] {
+          background: var(--esp-color-link-hover-bg);
+          color: var(--esp-color-link-hover);
+        }
+
+        &:focus-visible {
+          outline: 2px solid var(--esp-color-link);
+          outline-offset: 2px;
+        }
+      }
+    `],i([n({attribute:"help-url",type:String})],r.prototype,"helpUrl",void 0),i([n({type:String})],r.prototype,"anchor",void 0),i([n({type:String})],r.prototype,"label",void 0),i([n({attribute:"title",type:String})],r.prototype,"helpTitle",void 0),i([n({attribute:!1})],r.prototype,"placementTarget",void 0),i([n({type:Boolean,reflect:!0})],r.prototype,"active",void 0),r=i([g("esp-help-button")],r);export{r as EspalierHelpButton};

package/dist/help/esp-help-provider.d.ts

@@ -0,0 +1,40 @@
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+/**
+ * Headless provider for URL-addressable help documents. Place one provider
+ * inside the same `<esp-root>` as the page's shared `<esp-flyout>`. It
+ * services `requestHelp()` calls, fetches and normalizes the document, and
+ * swaps an internal help view into the generic flyout surface.
+ *
+ * Successful documents are cached by absolute source URL. A newer request
+ * aborts an older in-flight fetch, so help always reflects the most recent
+ * trigger. If no flyout services the provider's presentation request, the
+ * original URL opens in a new tab. Fetch failures stay in the flyout and
+ * offer an explicit "Open help document" action.
+ *
+ * ```html
+ * <esp-root>
+ *   <esp-help-provider></esp-help-provider>
+ *   <esp-page help-src="/help/account.html">
+ *     <esp-flyout slot="flyout"></esp-flyout>
+ *     <!-- page content -->
+ *   </esp-page>
+ * </esp-root>
+ * ```
+ *
+ * @docPageTitle Help Provider
+ * @docUrl /components/help/provider
+ * @menuGroup Feedback
+ * @menuLabel Help Provider
+ * @menuIcon info
+ */
+export declare class EspalierHelpProvider extends EspalierElementBase {
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected render(): symbol;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-help-provider": EspalierHelpProvider;
+    }
+}

package/dist/help/esp-help-provider.js

@@ -0,0 +1,5 @@
+var d=function(r,e,t,n){var o=arguments.length,s=o<3?e:n===null?n=Object.getOwnPropertyDescriptor(e,t):n,i;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(r,e,t,n);else for(var a=r.length-1;a>=0;a--)(i=r[a])&&(s=(o<3?i(s):o>3?i(e,t,s):i(e,t))||s);return o>3&&s&&Object.defineProperty(e,t,s),s};import{css as p,nothing as b}from"lit";import{customElement as f}from"lit/decorators.js";import{EspalierElementBase as v}from"../shared/esp-element-base.js";import{getEspBus as c}from"../shared/bus-events.js";import{publishFlyoutRequest as m}from"../shared/flyout-events.js";import{openHelpInNewTab as h}from"../shared/help-events.js";import{createHelpDocumentView as C,createHelpStatusView as u,normalizeHelpDocument as R}from"./help-document.js";let l=class extends v{constructor(){super(...arguments),this.cache=new Map,this.warnedMissingAnchors=new Set,this.activeRequest=null,this.activeController=null,this.activeContent=null,this.contentObserver=new MutationObserver(()=>{this.activeContent&&!this.activeContent.isConnected&&this.endActiveRequest()}),this.requestSequence=0,this.subscribed=!1,this.boundRequest=e=>{this.handleRequest(e)},this.boundCloseRequest=e=>{let t;try{t=new URL(e.src,document.baseURI).href}catch{return}if(!this.activeRequest||t!==this.activeRequest.src||(e.anchor??"")!==(this.activeRequest.anchor??""))return;const n=this.activeContent?.parentElement;n?.localName==="esp-flyout"&&n.close("programmatic")},this.boundFlyoutClosed=e=>{const t=e.target;!(t instanceof Element)||!this.activeContent||t.contains(this.activeContent)&&this.endActiveRequest()}}connectedCallback(){super.connectedCallback(),this.subscribed||(c().subscribe("request-help",this.boundRequest),c().subscribe("close-help",this.boundCloseRequest),this.subscribed=!0),document.addEventListener("flyout-closed",this.boundFlyoutClosed)}disconnectedCallback(){this.subscribed&&(c().unsubscribe("request-help",this.boundRequest),c().unsubscribe("close-help",this.boundCloseRequest),this.subscribed=!1),document.removeEventListener("flyout-closed",this.boundFlyoutClosed),this.endActiveRequest(),super.disconnectedCallback()}render(){return b}async handleRequest(e){const t=++this.requestSequence;this.activeController?.abort();const n=new AbortController;if(this.activeController=n,this.activeRequest=e,this.publishState(e,!0),this.showInFlyout(e,{heading:e.title??"Help",content:u({message:"Loading help\u2026"})})===0){this.endActiveRequest(),h(e);return}try{const s=this.cache.get(e.src)??await this.fetchDocument(e,n);if(t!==this.requestSequence||n.signal.aborted)return;if(!this.activeContent?.isConnected){this.endActiveRequest();return}this.cache.set(e.src,s);const i=C(s,e.anchor);this.warnForMissingAnchor(e,i.anchorFound),this.showInFlyout(e,{heading:e.title??i.topicTitle??s.title??"Help",content:i.element,fullHeight:i.fullDocument})}catch(s){if(t!==this.requestSequence||n.signal.aborted||w(s))return;if(!this.activeContent?.isConnected){this.endActiveRequest();return}this.showInFlyout(e,{heading:e.title??"Help unavailable",content:u({message:"Help could not be loaded.",actionLabel:"Open help document",onAction:()=>h(e)})})}finally{t===this.requestSequence&&(this.activeController=null)}}async fetchDocument(e,t){const n=await fetch(e.src,{signal:t.signal});if(!n.ok)throw new Error(`Help request failed with HTTP ${n.status}.`);return R(await n.text(),n.url||e.src)}showInFlyout(e,t){this.contentObserver.disconnect(),this.activeContent=t.content instanceof HTMLElement?t.content:null;const n=m({...t,anchor:e.placementTarget??e.trigger,returnFocusTo:e.trigger}),o=this.activeContent?.parentElement;return n&&o&&this.contentObserver.observe(o,{childList:!0}),n?1:0}publishState(e,t){c().publish("help-state-changed",{src:e.src,...e.anchor?{anchor:e.anchor}:{},open:t})}publishClosedState(){this.activeRequest&&(this.publishState(this.activeRequest,!1),this.activeRequest=null)}endActiveRequest(){(this.activeRequest||this.activeController)&&++this.requestSequence,this.activeController?.abort(),this.activeController=null,this.contentObserver.disconnect(),this.activeContent=null,this.publishClosedState()}warnForMissingAnchor(e,t){if(!e.anchor||t)return;const n=`${e.src}#${e.anchor}`;this.warnedMissingAnchors.has(n)||(this.warnedMissingAnchors.add(n),console.warn(`Help anchor "${e.anchor}" was not found in ${e.src}; showing the full document.`))}};l.styles=[p`
+      :host {
+        display: none;
+      }
+    `],l=d([f("esp-help-provider")],l);function w(r){return r instanceof DOMException&&r.name==="AbortError"}export{l as EspalierHelpProvider};

package/dist/help/help-document.js

@@ -0,0 +1,52 @@
+import"../button/esp-button.js";import{FLYOUT_FULL_HEIGHT_REQUEST_EVENT as w}from"../shared/flyout-events.js";import{decodeFragment as E}from"../shared/help-events.js";const v=new Set(["A","ABBR","B","BLOCKQUOTE","BR","CODE","DD","DEL","DETAILS","DL","DT","EM","FIGCAPTION","FIGURE","H1","H2","H3","H4","H5","H6","HR","I","IMG","KBD","LI","MARK","OL","P","PRE","Q","S","SAMP","SMALL","STRONG","SUB","SUMMARY","SUP","TABLE","TBODY","TD","TFOOT","TH","THEAD","TR","U","UL","VAR"]),N=new Set(["SCRIPT","STYLE","TEMPLATE","NOSCRIPT"]),y={A:["href"],DETAILS:["open"],IMG:["src","alt","width","height"],LI:["value"],OL:["start","reversed"],TD:["colspan","rowspan"],TH:["colspan","rowspan","scope"]},g=`
+  :host {
+    color: var(--esp-color-text);
+    display: block;
+    font-family: var(--esp-font-body);
+    font-size: var(--esp-size-font);
+    line-height: 1.5;
+  }
+
+  [part="content"] {
+    overflow-wrap: anywhere;
+  }
+
+  [part="content"] > :first-child {
+    margin-block-start: 0;
+  }
+
+  [part="content"] > :last-child {
+    margin-block-end: 0;
+  }
+
+  h1, h2, h3, h4, h5, h6 {
+    color: var(--esp-color-headings, var(--esp-color-text));
+    font-family: var(--esp-font-headings, var(--esp-font-body));
+    line-height: 1.2;
+  }
+
+  img {
+    block-size: auto;
+    max-inline-size: 100%;
+  }
+
+  pre {
+    max-inline-size: 100%;
+    overflow: auto;
+  }
+
+  table {
+    border-collapse: collapse;
+    inline-size: 100%;
+  }
+
+  th, td {
+    border: 1px solid var(--esp-color-border);
+    padding: var(--esp-size-tiny-to-small);
+    text-align: start;
+  }
+
+  [part="actions"] {
+    margin-block-start: var(--esp-size-padding);
+  }
+`;function P(e,t={}){const n=t.helpUrl?.trim()??"",o=n?"":H(e),r=n||o;if(!r)return null;let c;try{c=new URL(r,e.ownerDocument.baseURI)}catch{return null}const i=E(c.hash);c.hash="";const a=m(t.anchor,t.fallbackAnchor),s=n?m(i,a):m(a,i),u=new URL(c.href);return s&&(u.hash=s),{src:c.href,...s?{anchor:s}:{},href:u.href}}function k(e,t){const n=new URL(t,document.baseURI);n.hash="";const o=new DOMParser().parseFromString(e,"text/html"),r=o.querySelector("title")?.textContent?.trim()||void 0,c=document.createDocumentFragment();for(const i of[...o.body.childNodes])b(i,c,n.href);return{src:n.href,...r?{title:r}:{},body:c}}function D(e,t){const n=t?.trim()??"";if(!n)return{content:e.body.cloneNode(!0),anchorFound:!0,sectioned:!1};const o=T(e.body,n);if(!o)return{content:e.body.cloneNode(!0),anchorFound:!1,sectioned:!1};const r=A(o);if(!r||!o.parentNode)return{content:e.body.cloneNode(!0),anchorFound:!0,sectioned:!1};const c=document.createDocumentFragment();let i=o.nextSibling;for(;i;){if(i instanceof Element){const a=A(i);if(a&&a<=r)break}c.append(i.cloneNode(!0)),i=i.nextSibling}return{content:c,anchorFound:!0,sectioned:!0,heading:o.textContent?.trim()||void 0}}function B(e,t){const n=t?.trim()||void 0,o=D(e,n),r=document.createElement("section");r.dataset.espHelpDocument="";const c=r.attachShadow({mode:"open"}),i=document.createElement("style");i.textContent=g;const a=document.createElement("div");a.setAttribute("part","content");const s=document.createElement("div");s.setAttribute("part","actions");const u=d=>{a.replaceChildren(e.body.cloneNode(!0)),l?.setAttribute("disabled",""),l?.setAttribute("label","Full document"),r.dispatchEvent(new CustomEvent(w,{bubbles:!0,composed:!0})),d&&queueMicrotask(()=>S(a,d))};let l=null;return o.sectioned?(a.append(o.content),l=document.createElement("esp-button"),l.setAttribute("label","View full document"),l.setAttribute("collapsed",""),l.setAttribute("incognito",""),l.addEventListener("clicked",()=>u(n)),s.append(l)):a.append(o.content),a.addEventListener("click",d=>{const f=d.composedPath().find(L=>L instanceof HTMLAnchorElement)?.getAttribute("href")??"";if(!f)return;if(!f.startsWith("#")){d.preventDefault(),window.open(f,"_blank","noopener,noreferrer");return}d.preventDefault();const p=E(f);p&&(o.sectioned?u(p):S(a,p))}),c.append(i,a,s),{element:r,anchorFound:o.anchorFound,fullDocument:!o.sectioned,...o.heading?{topicTitle:o.heading}:{}}}function M(e){const t=document.createElement("section");t.dataset.espHelpStatus="";const n=t.attachShadow({mode:"open"}),o=document.createElement("style");o.textContent=g;const r=document.createElement("p");if(r.setAttribute("part","message"),r.textContent=e.message,n.append(o,r),e.actionLabel&&e.onAction){const c=document.createElement("div");c.setAttribute("part","actions");const i=document.createElement("esp-button");i.setAttribute("label",e.actionLabel),i.setAttribute("collapsed",""),i.addEventListener("clicked",e.onAction),c.append(i),n.append(c)}return t}function H(e){let t=e;const n=new Set;for(;t&&!n.has(t);){n.add(t);const o=t.getAttribute("help-src")?.trim()??"";if(o)return o;t=h(t)}return""}function h(e){if(e.assignedSlot)return e.assignedSlot;if(e.parentElement)return e.parentElement;const t=e.getRootNode();return t instanceof ShadowRoot?t.host:null}function m(...e){for(const t of e){const n=t?.trim()??"";if(n)return n}}function b(e,t,n){if(e.nodeType===Node.TEXT_NODE){t.appendChild(document.createTextNode(e.textContent??""));return}if(!(e instanceof Element)||N.has(e.tagName))return;if(!v.has(e.tagName)){for(const r of[...e.childNodes])b(r,t,n);return}const o=document.createElement(e.tagName.toLowerCase());R(e,o,n);for(const r of[...e.childNodes])b(r,o,n);t.appendChild(o)}function R(e,t,n){const o=e.getAttribute("id")?.trim();o&&t.setAttribute("id",o);for(const r of y[e.tagName]??[]){if(!e.hasAttribute(r))continue;const c=e.getAttribute(r)??"",i=r==="href"||r==="src"?C(c,n):c;i!==null&&t.setAttribute(r,i)}}function C(e,t){if(!e||e.startsWith("#"))return e;try{const n=new URL(e,t);return["http:","https:","mailto:","tel:"].includes(n.protocol)?n.href:null}catch{return null}}function T(e,t){return[...e.querySelectorAll("[id]")].find(n=>n.id===t)??null}function A(e){const t=/^H([1-6])$/u.exec(e.tagName);return t?Number(t[1]):null}function S(e,t){const n=T(e,t);if(!n)return;const o=x(n);if(!o)return;const r=n.getBoundingClientRect().top,c=o.getBoundingClientRect().top;o.scrollTop+=r-c}function x(e){for(let t=h(e);t;t=h(t)){if(!(t instanceof HTMLElement))continue;const n=getComputedStyle(t).overflowY;if(n==="auto"||n==="scroll")return t}return null}export{B as createHelpDocumentView,M as createHelpStatusView,k as normalizeHelpDocument,P as resolveHelpTarget,D as selectHelpContent};

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export * from "./color-picker/esp-color-picker.js";
 export * from "./flyout/esp-flyout.js";
 export * from "./form/esp-form.js";
 export * from "./form-item/esp-form-item.js";
+export * from "./help/esp-help-button.js";
+export * from "./help/esp-help-provider.js";
 export * from "./header/index.js";
 export * from "./page/esp-page.js";
 export * from "./popover/esp-popover.js";
@@ -62,7 +64,8 @@ export { FormFieldController, type FormFieldControllerOptions, } from "./shared/
 export { traverseToClosest } from "./shared/utilities.js";
 export { showToast, type ToastConfig } from "./shared/toast-events.js";
 export { showFlyout, closeFlyout, type FlyoutConfig, type FlyoutCloseReason, } from "./shared/flyout-events.js";
-export { getEspBus, type EspBusEventMap, type SchemeEvents, type ToastEvents, type FlyoutEvents, type PopoverEvents, type SizeEvents, type PageEventMap, type SeedColorRoot, } from "./shared/bus-events.js";
+export { requestHelp, type HelpRequest, type HelpState } from "./shared/help-events.js";
+export { getEspBus, type EspBusEventMap, type SchemeEvents, type ToastEvents, type FlyoutEvents, type HelpEvents, type PopoverEvents, type SizeEvents, type PageEventMap, type SeedColorRoot, } from "./shared/bus-events.js";
 export * from "./shared/events.js";
 export { getImageDetails, releasePreviewUrl, type EspalierUploadImage, type ImageDetailsOptions, type SelectedUploadImage, type ExistingUploadImage, type ExistingImage, type ResponsiveImageUrl, type UploadCallbacks, type UploadEventDetail, } from "./image-upload/image-helpers.js";
 export { calculatePhotoLayout, type LayoutImage, type PhotoRow, } from "./shared/justified-layout.js";

package/dist/index.js

@@ -1 +1 @@
-export*from"./box/esp-box.js";export*from"./action-menu/esp-action-menu.js";export*from"./action-menu/esp-action-menu-item.js";export*from"./avatar/esp-avatar.js";export*from"./avatar/esp-profile-chip.js";export*from"./badge/esp-badge.js";export*from"./checkbox/esp-checkbox.js";export*from"./checkbox/esp-checkbox-group.js";export*from"./data-cell/esp-data-cell.js";export*from"./radio-button/esp-radio-button.js";export*from"./radio-button/esp-radio-button-group.js";export*from"./repeater/esp-repeater.js";export*from"./breadcrumbs/esp-breadcrumbs.js";export*from"./button/esp-button.js";export*from"./button/esp-button-group.js";export*from"./color-picker/esp-color-picker.js";export*from"./flyout/esp-flyout.js";export*from"./form/esp-form.js";export*from"./form-item/esp-form-item.js";export*from"./header/index.js";export*from"./page/esp-page.js";export*from"./popover/esp-popover.js";export*from"./dialog/esp-dialog.js";export*from"./empty-state/esp-empty-state.js";export*from"./image-upload/esp-image-upload.js";export*from"./file-upload/esp-file-upload.js";export*from"./font-picker/esp-font-picker.js";export*from"./focus-picker/esp-focus-picker.js";export*from"./footer/index.js";export*from"./grid/esp-grid.js";export*from"./image/esp-image.js";export*from"./image/image-focus.js";export*from"./lightbox/esp-lightbox.js";export*from"./info/esp-info.js";export*from"./input/esp-input.js";export*from"./textarea/esp-textarea.js";export*from"./pickers/esp-pick-one.js";export*from"./pickers/esp-pick-some.js";export*from"./pickers/esp-picker-menu.js";export*from"./pickers/esp-picker-item.js";export*from"./root/esp-root.js";export*from"./menu/index.js";export*from"./burger/esp-burger.js";export*from"./date-picker/esp-date-picker.js";export*from"./details/esp-details.js";export*from"./details/esp-details-group.js";export*from"./tabs/esp-tab.js";export*from"./tabs/esp-tab-group.js";export*from"./slider/esp-slider.js";export*from"./switch/esp-switch.js";export*from"./toaster/esp-toaster.js";export*from"./tooltip/esp-tooltip.js";export*from"./progress/esp-progress.js";export*from"./search/esp-search.js";export*from"./status-indicator/esp-status-indicator.js";export*from"./tree/esp-tree.js";export*from"./tree/esp-tree-item.js";import{DEFAULT_ICON_SPRITE_URL as po,DEFAULT_ICON_VIEW_BOX as fo,INTENT_VARIANTS as xo,normalizeIntentVariant as ao,getIconHref as lo,getIconHrefForHost as so,getIconSpriteUrl as To}from"./shared/intent-values.js";import{EspalierElementBase as io}from"./shared/esp-element-base.js";import{VALIDITY_CHANGED_EVENT as Io}from"./shared/validation.js";import{FormFieldController as ho}from"./shared/form-field-controller.js";import{traverseToClosest as Fo}from"./shared/utilities.js";import{showToast as Ao}from"./shared/toast-events.js";import{showFlyout as No,closeFlyout as uo}from"./shared/flyout-events.js";import{getEspBus as Ho}from"./shared/bus-events.js";export*from"./shared/events.js";import{getImageDetails as yo,releasePreviewUrl as Co}from"./image-upload/image-helpers.js";import{calculatePhotoLayout as Vo}from"./shared/justified-layout.js";import{encodeTheme as Bo,parseTheme as Po,mergePartials as vo,layerThemes as wo,buildTaprootLightTheme as Go,buildTaprootDarkTheme as Oo,NESTED_THEME_KEYS as Ro}from"./shared/theme.js";import{WEIGHT_LABELS as zo,extractWeights as Yo,normalizeWeight as Ko,bestAvailableWeight as Mo,extractFamily as Xo,getFallbackFont as jo}from"./shared/font-helpers.js";import{getGoogleFonts as Jo}from"./font-picker/esp-font-picker.js";export{po as DEFAULT_ICON_SPRITE_URL,fo as DEFAULT_ICON_VIEW_BOX,io as EspalierElementBase,ho as FormFieldController,xo as INTENT_VARIANTS,Ro as NESTED_THEME_KEYS,Io as VALIDITY_CHANGED_EVENT,zo as WEIGHT_LABELS,Mo as bestAvailableWeight,Oo as buildTaprootDarkTheme,Go as buildTaprootLightTheme,Vo as calculatePhotoLayout,uo as closeFlyout,Bo as encodeTheme,Xo as extractFamily,Yo as extractWeights,Ho as getEspBus,jo as getFallbackFont,Jo as getGoogleFonts,lo as getIconHref,so as getIconHrefForHost,To as getIconSpriteUrl,yo as getImageDetails,wo as layerThemes,vo as mergePartials,ao as normalizeIntentVariant,Ko as normalizeWeight,Po as parseTheme,Co as releasePreviewUrl,No as showFlyout,Ao as showToast,Fo as traverseToClosest};
+export*from"./box/esp-box.js";export*from"./action-menu/esp-action-menu.js";export*from"./action-menu/esp-action-menu-item.js";export*from"./avatar/esp-avatar.js";export*from"./avatar/esp-profile-chip.js";export*from"./badge/esp-badge.js";export*from"./checkbox/esp-checkbox.js";export*from"./checkbox/esp-checkbox-group.js";export*from"./data-cell/esp-data-cell.js";export*from"./radio-button/esp-radio-button.js";export*from"./radio-button/esp-radio-button-group.js";export*from"./repeater/esp-repeater.js";export*from"./breadcrumbs/esp-breadcrumbs.js";export*from"./button/esp-button.js";export*from"./button/esp-button-group.js";export*from"./color-picker/esp-color-picker.js";export*from"./flyout/esp-flyout.js";export*from"./form/esp-form.js";export*from"./form-item/esp-form-item.js";export*from"./help/esp-help-button.js";export*from"./help/esp-help-provider.js";export*from"./header/index.js";export*from"./page/esp-page.js";export*from"./popover/esp-popover.js";export*from"./dialog/esp-dialog.js";export*from"./empty-state/esp-empty-state.js";export*from"./image-upload/esp-image-upload.js";export*from"./file-upload/esp-file-upload.js";export*from"./font-picker/esp-font-picker.js";export*from"./focus-picker/esp-focus-picker.js";export*from"./footer/index.js";export*from"./grid/esp-grid.js";export*from"./image/esp-image.js";export*from"./image/image-focus.js";export*from"./lightbox/esp-lightbox.js";export*from"./info/esp-info.js";export*from"./input/esp-input.js";export*from"./textarea/esp-textarea.js";export*from"./pickers/esp-pick-one.js";export*from"./pickers/esp-pick-some.js";export*from"./pickers/esp-picker-menu.js";export*from"./pickers/esp-picker-item.js";export*from"./root/esp-root.js";export*from"./menu/index.js";export*from"./burger/esp-burger.js";export*from"./date-picker/esp-date-picker.js";export*from"./details/esp-details.js";export*from"./details/esp-details-group.js";export*from"./tabs/esp-tab.js";export*from"./tabs/esp-tab-group.js";export*from"./slider/esp-slider.js";export*from"./switch/esp-switch.js";export*from"./toaster/esp-toaster.js";export*from"./tooltip/esp-tooltip.js";export*from"./progress/esp-progress.js";export*from"./search/esp-search.js";export*from"./status-indicator/esp-status-indicator.js";export*from"./tree/esp-tree.js";export*from"./tree/esp-tree-item.js";import{DEFAULT_ICON_SPRITE_URL as xo,DEFAULT_ICON_VIEW_BOX as ao,INTENT_VARIANTS as lo,normalizeIntentVariant as so,getIconHref as To,getIconHrefForHost as Eo,getIconSpriteUrl as io}from"./shared/intent-values.js";import{EspalierElementBase as Io}from"./shared/esp-element-base.js";import{VALIDITY_CHANGED_EVENT as ho}from"./shared/validation.js";import{FormFieldController as Fo}from"./shared/form-field-controller.js";import{traverseToClosest as uo}from"./shared/utilities.js";import{showToast as Lo}from"./shared/toast-events.js";import{showFlyout as Do,closeFlyout as Ho}from"./shared/flyout-events.js";import{requestHelp as bo}from"./shared/help-events.js";import{getEspBus as Co}from"./shared/bus-events.js";export*from"./shared/events.js";import{getImageDetails as Wo,releasePreviewUrl as Bo}from"./image-upload/image-helpers.js";import{calculatePhotoLayout as vo}from"./shared/justified-layout.js";import{encodeTheme as Go,parseTheme as Oo,mergePartials as Ro,layerThemes as ko,buildTaprootLightTheme as zo,buildTaprootDarkTheme as Yo,NESTED_THEME_KEYS as qo}from"./shared/theme.js";import{WEIGHT_LABELS as Mo,extractWeights as Xo,normalizeWeight as jo,bestAvailableWeight as Jo,extractFamily as Qo,getFallbackFont as Zo}from"./shared/font-helpers.js";import{getGoogleFonts as or}from"./font-picker/esp-font-picker.js";export{xo as DEFAULT_ICON_SPRITE_URL,ao as DEFAULT_ICON_VIEW_BOX,Io as EspalierElementBase,Fo as FormFieldController,lo as INTENT_VARIANTS,qo as NESTED_THEME_KEYS,ho as VALIDITY_CHANGED_EVENT,Mo as WEIGHT_LABELS,Jo as bestAvailableWeight,Yo as buildTaprootDarkTheme,zo as buildTaprootLightTheme,vo as calculatePhotoLayout,Ho as closeFlyout,Go as encodeTheme,Qo as extractFamily,Xo as extractWeights,Co as getEspBus,Zo as getFallbackFont,or as getGoogleFonts,To as getIconHref,Eo as getIconHrefForHost,io as getIconSpriteUrl,Wo as getImageDetails,ko as layerThemes,Ro as mergePartials,so as normalizeIntentVariant,jo as normalizeWeight,Oo as parseTheme,Bo as releasePreviewUrl,bo as requestHelp,Do as showFlyout,Lo as showToast,uo as traverseToClosest};

package/dist/menu/esp-menu.js

@@ -1,4 +1,4 @@
-var n=function(d,e,r,o){var t=arguments.length,i=t<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,r):o,s;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(d,e,r,o);else for(var h=d.length-1;h>=0;h--)(s=d[h])&&(i=(t<3?s(i):t>3?s(e,r,i):s(e,r))||i);return t>3&&i&&Object.defineProperty(e,r,i),i};import{css as x,html as w,nothing as f}from"lit";import{customElement as E,property as l,state as g}from"lit/decorators.js";import{classMap as m}from"lit/directives/class-map.js";import{unsafeHTML as v}from"lit/directives/unsafe-html.js";import{createRef as p,ref as c}from"lit/directives/ref.js";import{EspalierElementBase as b}from"../shared/esp-element-base.js";import{getEspBus as D}from"../shared/bus-events.js";import{normalizePath as S,pathStartsWithSegment as y,pathsMatch as T}from"../shared/path-matching.js";import{SwipeRevealController as A}from"./swipe-reveal-controller.js";import"./esp-menu-item.js";import"./esp-menu-group.js";import{EspalierMenuItem as C}from"./esp-menu-item.js";import{EspalierMenuGroup as u}from"./esp-menu-group.js";const O="(max-width: 50em)";let a=class extends b{constructor(){super(),this.itemsSlot=p(),this.railRef=p(),this.scrimRef=p(),this.drawerRef=p(),this.bus=D(),this.closeTransitionTimer=null,this.drawerGroupOpenOverrides=new Map,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.ariaLabel=null,this.autoExpand=!1,this.drawerOpen=!1,this.drawerTransitioning=!1,this.drawerTrigger=null,this.hasExternalDrawerControl=!1,this.getWidth=()=>{const e=this.railRef.value;return e?Math.max(e.scrollWidth,e.clientWidth):-1},this.onDrawerTransitionEnd=()=>{this.closeTransitionTimer&&(clearTimeout(this.closeTransitionTimer),this.closeTransitionTimer=null),this.drawerTransitioning=!1,this.drawerOpen||(this.hideDrawerPopover(),this.drawerGroupOpenOverrides.clear())},this.swipeController=new A(this,this.side),this.swipeController.enabled=!1}get sliding(){return this._sliding}set sliding(e){const r=this._sliding;this._sliding=e,this.syncSwipeEnabled(),this.propagateToItems(),this.requestUpdate("sliding",r)}get collapsed(){return this.drawerActive}set collapsed(e){e?this.mode="drawer":this.mode==="drawer"&&(this.mode="vertical")}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.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(O),this._mobileCollapsed=this.verticalDrawerQuery.matches,this.verticalDrawerQuery.addEventListener("change",this.onVerticalDrawerChange)),this.syncSwipeEnabled()}disconnectedCallback(){this.verticalDrawerQuery?.removeEventListener("change",this.onVerticalDrawerChange),this.verticalDrawerQuery=null,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()}updated(e){super.updated(e),(e.has("mode")||e.has("overflow")||e.has("side")||e.has("hasExternalDrawerControl"))&&(this.swipeController.direction=this.drawerSide,this.syncSwipeEnabled(),this.propagateToItems(),!this.drawerActive&&this.drawerOpen&&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)}toggleOpened(){this.toggleDrawer()}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 r of this.getAssignedChildren())r instanceof C?(r.mode=e,r.depth=0,r.touchDevice=this.swipeController.isTouch):r instanceof u&&(r.mode=e,r.depth=0,r.touchDevice=this.swipeController.isTouch)}handleSlotChange(){this.propagateToItems()}onSwipeRevealChanged(e){e!==this.drawerOpen&&(this.drawerOpen=e,e?(this.drawerGroupOpenOverrides.clear(),this.bus.publish("close-popovers",{}),this.updateComplete.then(()=>this.showDrawerPopover())):(this.drawerTransitioning=!0,this.updateComplete.then(()=>this.startCloseTransition()),requestAnimationFrame(()=>this.restoreDrawerTriggerFocus())),this.dispatchEvent(new CustomEvent(e?"drawer-opened":"drawer-closed",{bubbles:!0,composed:!0})))}showDrawerPopover(){const e=this.scrimRef.value,r=this.drawerRef.value;if(!(!e||!r)){this.swipeController.drawerElement=r;try{e.showPopover(),r.showPopover()}catch{}r.getBoundingClientRect(),requestAnimationFrame(()=>{this.drawerTransitioning=!0,this.requestUpdate()})}}startCloseTransition(){if(!this.drawerRef.value){this.hideDrawerPopover();return}this.closeTransitionTimer&&clearTimeout(this.closeTransitionTimer),this.closeTransitionTimer=setTimeout(()=>{this.closeTransitionTimer=null,!this.drawerOpen&&this.drawerTransitioning&&this.onDrawerTransitionEnd()},400)}hideDrawerPopover(){const e=this.scrimRef.value,r=this.drawerRef.value;this.swipeController.drawerElement=null,r&&(r.style.cssText="");try{r?.hidePopover()}catch{}try{e?.hidePopover()}catch{}}restoreDrawerTriggerFocus(){const e=this.drawerTrigger;this.drawerTrigger=null,e?.isConnected&&e.focus({preventScroll:!0})}getAutoExpandedGroups(e=!0){const r=new Set;let o=null;for(const i of this.querySelectorAll("esp-menu-item")){const s=i.url||i.getAttribute("url");if(s&&T(s)){o=i;break}}if(!o)for(const i of this.querySelectorAll("esp-menu-group")){const s=i.url||i.getAttribute("url");if(s&&T(s)){o=i;break}}if(!o&&e){for(const i of this.querySelectorAll("esp-menu-group"))i.parentElement===this&&r.add(i);return r}if(!o)return r;o instanceof u&&r.add(o);let t=o.parentElement;for(;t&&t!==this;)t instanceof u&&r.add(t),t=t.parentElement;return r}isHorizontalTopLevelGroup(e){return e.mode==="horizontal"&&e.depth===0}groupUrlPrefixMatches(e){return y(location.pathname,e.urlPrefix)}groupPathMatches(e){if(this.groupUrlPrefixMatches(e))return!0;const r=e.url||e.getAttribute("url");return r?y(location.pathname,S(r)):!1}expandToCurrentPage(){const e=this.getAutoExpandedGroups(),r=this.querySelectorAll("esp-menu-group");for(const o of r)o.open=e.has(o)&&!this.isHorizontalTopLevelGroup(o)}closeHorizontalTopLevelGroups(){for(const e of this.querySelectorAll("esp-menu-group"))this.isHorizontalTopLevelGroup(e)&&(e.open=!1)}getDrawerAutoExpandedGroups(){return this.getAutoExpandedGroups(!1)}collectDrawerNodes(e,r=this.getDrawerAutoExpandedGroups()){const o=[];for(const t of e)if(t instanceof C){const i=t.querySelector(":scope > svg, :scope > img");o.push({kind:"item",label:t.label,url:t.url,open:!1,icon:t.icon,iconHtml:i?.outerHTML||"",children:[],originalItem:t,originalGroup:null})}else if(t instanceof u){const i=t.querySelector(':scope > [slot="icon"]'),s=r.has(t)||this.groupPathMatches(t),h=this.drawerGroupOpenOverrides.get(t)??(t.open||s);o.push({kind:"group",label:t.label,url:t.url||"",open:h,icon:t.icon,iconHtml:i?.outerHTML||"",children:this.collectDrawerNodes(Array.from(t.children),r),originalItem:null,originalGroup:t})}return o}renderDrawerNode(e){return e.kind==="item"?w`<esp-menu-item
+var n=function(p,e,r,o){var t=arguments.length,i=t<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,r):o,s;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(p,e,r,o);else for(var h=p.length-1;h>=0;h--)(s=p[h])&&(i=(t<3?s(i):t>3?s(e,r,i):s(e,r))||i);return t>3&&i&&Object.defineProperty(e,r,i),i};import{css as x,html as w,nothing as f}from"lit";import{customElement as E,property as l,state as g}from"lit/decorators.js";import{classMap as m}from"lit/directives/class-map.js";import{unsafeHTML as v}from"lit/directives/unsafe-html.js";import{createRef as d,ref as c}from"lit/directives/ref.js";import{EspalierElementBase as b}from"../shared/esp-element-base.js";import{getEspBus as D}from"../shared/bus-events.js";import{normalizePath as S,pathStartsWithSegment as y,pathsMatch as C}from"../shared/path-matching.js";import{SwipeRevealController as A}from"./swipe-reveal-controller.js";import"./esp-menu-item.js";import"./esp-menu-group.js";import{EspalierMenuItem as T}from"./esp-menu-item.js";import{EspalierMenuGroup as u}from"./esp-menu-group.js";const O="(max-width: 50em)";let a=class extends b{constructor(){super(),this.itemsSlot=d(),this.railRef=d(),this.scrimRef=d(),this.drawerRef=d(),this.bus=D(),this.closeTransitionTimer=null,this.drawerGroupOpenOverrides=new Map,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.ariaLabel=null,this.autoExpand=!1,this.drawerOpen=!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.onDrawerTransitionEnd=()=>{this.closeTransitionTimer&&(clearTimeout(this.closeTransitionTimer),this.closeTransitionTimer=null),this.drawerTransitioning=!1,this.drawerOpen||(this.hideDrawerPopover(),this.drawerGroupOpenOverrides.clear())},this.swipeController=new A(this,this.side),this.swipeController.enabled=!1}get sliding(){return this._sliding}set sliding(e){const r=this._sliding;this._sliding=e,this.syncSwipeEnabled(),this.propagateToItems(),this.requestUpdate("sliding",r)}get collapsed(){return this.drawerActive}set collapsed(e){e?this.mode="drawer":this.mode==="drawer"&&(this.mode="vertical")}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(O),this._mobileCollapsed=this.verticalDrawerQuery.matches,this.verticalDrawerQuery.addEventListener("change",this.onVerticalDrawerChange)),this.syncSwipeEnabled()}disconnectedCallback(){this.verticalDrawerQuery?.removeEventListener("change",this.onVerticalDrawerChange),this.verticalDrawerQuery=null,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()}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)),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)}toggleOpened(){this.toggleDrawer()}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 r of this.getAssignedChildren())r instanceof T?(r.mode=e,r.depth=0,r.touchDevice=this.swipeController.isTouch):r instanceof u&&(r.mode=e,r.depth=0,r.touchDevice=this.swipeController.isTouch)}handleSlotChange(){this.propagateToItems()}onSwipeRevealChanged(e){e!==this.drawerOpen&&(this.drawerOpen=e,e?(this.drawerGroupOpenOverrides.clear(),this.bus.publish("close-popovers",{}),this.updateComplete.then(()=>this.showDrawerPopover())):(this.drawerTransitioning=!0,this.updateComplete.then(()=>this.startCloseTransition()),requestAnimationFrame(()=>this.restoreDrawerTriggerFocus())),this.dispatchEvent(new CustomEvent(e?"drawer-opened":"drawer-closed",{bubbles:!0,composed:!0})))}showDrawerPopover(){const e=this.scrimRef.value,r=this.drawerRef.value;if(!(!e||!r)){this.swipeController.drawerElement=r;try{e.showPopover(),r.showPopover()}catch{}r.getBoundingClientRect(),requestAnimationFrame(()=>{this.drawerTransitioning=!0,this.requestUpdate()})}}startCloseTransition(){if(!this.drawerRef.value){this.hideDrawerPopover();return}this.closeTransitionTimer&&clearTimeout(this.closeTransitionTimer),this.closeTransitionTimer=setTimeout(()=>{this.closeTransitionTimer=null,!this.drawerOpen&&this.drawerTransitioning&&this.onDrawerTransitionEnd()},400)}hideDrawerPopover(){const e=this.scrimRef.value,r=this.drawerRef.value;this.swipeController.drawerElement=null,r&&(r.style.cssText="");try{r?.hidePopover()}catch{}try{e?.hidePopover()}catch{}}restoreDrawerTriggerFocus(){const e=this.drawerTrigger;this.drawerTrigger=null,e?.isConnected&&e.focus({preventScroll:!0})}getAutoExpandedGroups(e=!0){const r=new Set;let o=null;for(const i of this.querySelectorAll("esp-menu-item")){const s=i.url||i.getAttribute("url");if(s&&C(s)){o=i;break}}if(!o)for(const i of this.querySelectorAll("esp-menu-group")){const s=i.url||i.getAttribute("url");if(s&&C(s)){o=i;break}}if(!o&&e){for(const i of this.querySelectorAll("esp-menu-group"))i.parentElement===this&&r.add(i);return r}if(!o)return r;o instanceof u&&r.add(o);let t=o.parentElement;for(;t&&t!==this;)t instanceof u&&r.add(t),t=t.parentElement;return r}isHorizontalTopLevelGroup(e){return e.mode==="horizontal"&&e.depth===0}groupUrlPrefixMatches(e){return y(location.pathname,e.urlPrefix)}groupPathMatches(e){if(this.groupUrlPrefixMatches(e))return!0;const r=e.url||e.getAttribute("url");return r?y(location.pathname,S(r)):!1}expandToCurrentPage(){const e=this.getAutoExpandedGroups(),r=this.querySelectorAll("esp-menu-group");for(const o of r)o.open=e.has(o)&&!this.isHorizontalTopLevelGroup(o)}closeHorizontalTopLevelGroups(){for(const e of this.querySelectorAll("esp-menu-group"))this.isHorizontalTopLevelGroup(e)&&(e.open=!1)}getDrawerAutoExpandedGroups(){return this.getAutoExpandedGroups(!1)}collectDrawerNodes(e,r=this.getDrawerAutoExpandedGroups()){const o=[];for(const t of e)if(t instanceof T){const i=t.querySelector(":scope > svg, :scope > img");o.push({kind:"item",label:t.label,url:t.url,open:!1,icon:t.icon,iconHtml:i?.outerHTML||"",children:[],originalItem:t,originalGroup:null})}else if(t instanceof u){const i=t.querySelector(':scope > [slot="icon"]'),s=r.has(t)||this.groupPathMatches(t),h=this.drawerGroupOpenOverrides.get(t)??(t.open||s);o.push({kind:"group",label:t.label,url:t.url||"",open:h,icon:t.icon,iconHtml:i?.outerHTML||"",children:this.collectDrawerNodes(Array.from(t.children),r),originalItem:null,originalGroup:t})}return o}renderDrawerNode(e){return e.kind==="item"?w`<esp-menu-item
         label=${e.label}
         .url=${e.url}
         .icon=${e.icon}
@@ -167,4 +167,4 @@ var n=function(d,e,r,o){var t=arguments.length,i=t<3?e:o===null?o=Object.getOwnP
           transition: none;
         }
       }
-    `],n([l({type:String,reflect:!0})],a.prototype,"mode",void 0),n([l({type:String,reflect:!0})],a.prototype,"overflow",void 0),n([l({type:String,reflect:!0})],a.prototype,"side",void 0),n([l({attribute:"aria-label",type:String})],a.prototype,"ariaLabel",void 0),n([l({type:Boolean,attribute:"auto-expand"})],a.prototype,"autoExpand",void 0),n([l({type:Boolean})],a.prototype,"sliding",null),n([l({type:Boolean})],a.prototype,"collapsed",null),n([g()],a.prototype,"drawerOpen",void 0),n([g()],a.prototype,"drawerTransitioning",void 0),n([l({attribute:!1})],a.prototype,"hasExternalDrawerControl",void 0),a=n([E("esp-menu")],a);export{a as EspalierMenu};
+    `],n([l({type:String,reflect:!0})],a.prototype,"mode",void 0),n([l({type:String,reflect:!0})],a.prototype,"overflow",void 0),n([l({type:String,reflect:!0})],a.prototype,"side",void 0),n([l({attribute:"aria-label",type:String})],a.prototype,"ariaLabel",void 0),n([l({type:Boolean,attribute:"auto-expand"})],a.prototype,"autoExpand",void 0),n([l({type:Boolean})],a.prototype,"sliding",null),n([l({type:Boolean})],a.prototype,"collapsed",null),n([g()],a.prototype,"drawerOpen",void 0),n([g()],a.prototype,"drawerTransitioning",void 0),n([l({attribute:!1})],a.prototype,"hasExternalDrawerControl",void 0),n([l({attribute:!1})],a.prototype,"previewCollapseRequested",void 0),a=n([E("esp-menu")],a);export{a as EspalierMenu};

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

@@ -32,8 +32,29 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * </esp-page>
  * ```
  *
+ * A persistent preview uses spare trailing canvas first. Set a main-well
+ * floor to let it reclaim surface width, and opt into collapsing a directly
+ * paired header/sidebar navigation to its accessible burger/drawer mode:
+ *
+ * ```html
+ * <esp-page
+ *   preview-open
+ *   preview-collapse-sidebar
+ *   style="--esp-page-preview-width: 20rem; --esp-page-preview-min-main-width: 900px;"
+ * >
+ *   <esp-header slot="header" drawer-target="site-nav"></esp-header>
+ *   <esp-menu id="site-nav" slot="sidebar" mode="vertical"></esp-menu>
+ *   <article>Primary content</article>
+ *   <aside slot="preview">Preview content</aside>
+ * </esp-page>
+ * ```
+ *
  * @slot sidebar - Contextual navigation placed in the left aside.
  * @slot right - Content to place in the right aside.
+ * @slot preview - Persistent preview content that uses spare right canvas
+ * width first, then optionally reclaims navigation and main-well width down
+ * to `--esp-page-preview-min-main-width`. Unlike flyout content, preview
+ * content is never replaced by the flyout request bus.
  * @slot flyout - A transient `esp-flyout` panel that lives on the
  * canvas, outside the content surface. Closed it costs no width; open
  * it claims the right canvas gutter first — the surface keeps its
@@ -143,6 +164,12 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * for content that floats directly on the page with no frame.
  * @cssprop --esp-page-flyout-width - The width of the open flyout
  * track (and of the `esp-flyout` overlay drawer). Defaults to `20rem`.
+ * @cssprop --esp-page-preview-width - Width of the persistent preview
+ * panel. Defaults to `20rem`.
+ * @cssprop --esp-page-preview-min-main-width - Optional minimum width of
+ * the main content well while preview is reclaiming canvas/surface space.
+ * Unset by default, so preview uses spare canvas only. Set a length such
+ * as `900px` to opt into reclaim behavior.
  * @cssprop --esp-page-fixed-header-offset - Offset reserved for fixed
  * headers. Defaults to `var(--esp-header-height)`.
  * @cssprop --esp-page-sticky-header-top - Top inset for sticky headers.
@@ -152,6 +179,8 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  *
  * @csspart canvas - The two canvas gutter regions flanking the surface.
  * @csspart surface - The surface backdrop carrying the edge shadow/border.
+ * @csspart preview - The persistent preview complementary landmark.
+ * @csspart preview-content - The sticky wrapper around preview content.
  *
  * ```html
  * <style>
@@ -205,6 +234,7 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
 export declare class EspalierPage extends EspalierElementBase {
     constructor();
     connectedCallback(): void;
+    disconnectedCallback(): void;
     /**
      * The layout mode of the page.
      *
@@ -265,6 +295,35 @@ export declare class EspalierPage extends EspalierElementBase {
      * Prefer `header-position="fixed"` for new code.
      */
     fixedMenus: boolean;
+    /**
+     * Whether the persistent preview is logically open. The page may keep the
+     * preview hidden while space is unavailable; `preview-visible` reflects its
+     * actual presentation and the preview restores automatically when room returns.
+     */
+    previewOpen: boolean;
+    /** Accessible name for the preview's complementary landmark. */
+    previewLabel: string;
+    /**
+     * Allow a directly slotted, safely linked vertical menu/header pair to
+     * collapse to its burger/drawer presentation when preview needs more room.
+     */
+    previewCollapseSidebar: boolean;
+    /**
+     * Whether preview content is currently rendered. Managed by the page's
+     * space negotiation; consumers should treat this reflected property as read-only.
+     */
+    previewVisible: boolean;
+    /**
+     * Whether preview is currently reserving width and allowing the main well
+     * to shrink toward `--esp-page-preview-min-main-width`. Managed by the page.
+     */
+    previewReclaiming: boolean;
+    /** Request the persistent preview without moving focus. */
+    showPreview(): void;
+    /** Close the persistent preview without moving focus. */
+    closePreview(): void;
+    /** Toggle the persistent preview without moving focus. */
+    togglePreview(): void;
     /**
      * Inject an element into a div with the highest z-index so dialogs are
      * rendered on top of everything else.