@taprootio/espalier 2.8.1 → 2.10.0

package/dist/page/esp-page.js

@@ -1,14 +1,14 @@
-var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnPropertyDescriptor(e,a):s,t;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(h,e,a,s);else for(var n=h.length-1;n>=0;n--)(t=h[n])&&(o=(d<3?t(o):d>3?t(e,a,o):t(e,a))||o);return d>3&&o&&Object.defineProperty(e,a,o),o};import{css as m,html as v,nothing as y}from"lit";import{customElement as w,property as l,state as b}from"lit/decorators.js";import{classMap as k}from"lit/directives/class-map.js";import{createRef as p,ref as c}from"lit/directives/ref.js";import{EspalierElementBase as g}from"../shared/esp-element-base.js";import{BiDirectionalStickyController as u}from"./bi-directional-sticky-controller.js";import{getEspBus as x}from"../shared/bus-events.js";import"../toaster/esp-toaster.js";const f='esp-footer, footer, [role~="contentinfo"]';let r=class extends g{constructor(){super(),this.dialogZone=p(),this.flyoutSlot=p(),this.footerSlot=p(),this.footerWrapperIsLandmark=!0,this.kind="wide",this.align="start",this.contained=!1,this.headerPosition="normal",this.fixedMenus=!1,new u(this,".esp-page-left > .sticky-wrapper"),new u(this,".esp-page-right > .sticky-wrapper"),new u(this,".esp-page-flyout > .sticky-wrapper"),this.addEventListener("flyout-state-changed",e=>this.syncFlyoutState(e))}connectedCallback(){const e=Array.from(this.children).filter(a=>a.getAttribute("slot")==="footer");this.footerWrapperIsLandmark=!e.some(a=>this.footerElementProvidesLandmark(a)),super.connectedCallback()}syncFlyoutState(e){if(e&&e.target?.closest?.("esp-page")!==this)return;const a=t=>{const n=t.mode;return(typeof n=="string"?n:t.getAttribute("mode"))==="overlay"},s=t=>{const n=t.open;return typeof n=="boolean"?n:t.hasAttribute("open")},d=t=>t.anchor!=null,o=(this.flyoutSlot.value?.assignedElements()??[]).filter(t=>t.tagName==="ESP-FLYOUT");this.toggleAttribute("flyout-open",o.some(t=>s(t)&&!a(t))),this.toggleAttribute("flyout-overlay-open",o.some(t=>s(t)&&a(t))),this.toggleAttribute("flyout-anchored",o.some(t=>s(t)&&d(t)))}footerElementProvidesLandmark(e){return e.matches(f)||e.querySelector(f)!==null}syncFooterLandmark(){const a=(this.footerSlot.value?.assignedElements({flatten:!0})??[]).some(s=>this.footerElementProvidesLandmark(s));this.footerWrapperIsLandmark=!a}AddDialog(e){this.dialogZone.value?.appendChild(e)}firstUpdated(e){super.firstUpdated(e),this.syncFlyoutState()}updated(e){super.updated(e),(e.has("fixedMenus")||e.has("headerPosition"))&&x().publish("fixed-menus-changed",{fixed:this.fixedMenus||this.headerPosition==="fixed"})}render(){const e=this.fixedMenus||this.headerPosition==="fixed",a=!e&&this.headerPosition==="sticky";return v`
-      <div part="wrapper" class="esp-page ${k({"fixed-menus":e,"fixed-header":e,"sticky-header":a})}">
+var p=function(u,t,e,a){var r=arguments.length,s=r<3?t:a===null?a=Object.getOwnPropertyDescriptor(t,e):a,i;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(u,t,e,a);else for(var o=u.length-1;o>=0;o--)(i=u[o])&&(s=(r<3?i(s):r>3?i(t,e,s):i(t,e))||s);return r>3&&s&&Object.defineProperty(t,e,s),s};import{css as k,html as x,nothing as S}from"lit";import{customElement as P,property as l,state as C}from"lit/decorators.js";import{classMap as z}from"lit/directives/class-map.js";import{createRef as d,ref as h}from"lit/directives/ref.js";import{EspalierElementBase as f}from"../shared/esp-element-base.js";import{BiDirectionalStickyController as g}from"./bi-directional-sticky-controller.js";import{getEspBus as R}from"../shared/bus-events.js";import"../toaster/esp-toaster.js";const w='esp-footer, footer, [role~="contentinfo"]',_="(max-width: 50em)",c=1;let n=class extends f{constructor(){super(),this.dialogZone=d(),this.flyoutSlot=d(),this.footerSlot=d(),this.previewSlot=d(),this.previewSpace=d(),this.previewWidthProbe=d(),this.previewMainMinProbe=d(),this.previewObservedWidths=new WeakMap,this.previewSyncRaf=null,this.previewSyncGeneration=0,this.previewSyncTask=Promise.resolve(),this.previewHeader=null,this.previewMenu=null,this.previewCollapsedSidebarWidth=0,this.footerWrapperIsLandmark=!0,this.schedulePreviewLayout=()=>{if(!this.isConnected||!this.hasUpdated)return;this.previewSyncGeneration+=1;const t=this.previewSyncGeneration;this.previewSyncRaf!==null&&cancelAnimationFrame(this.previewSyncRaf),this.previewSyncRaf=requestAnimationFrame(()=>{this.previewSyncRaf=null,this.previewSyncTask=this.previewSyncTask.then(()=>this.syncPreviewLayout(t)).catch(()=>{})})},this.onPreviewMediaChange=()=>this.schedulePreviewLayout(),this.onPreviewResize=t=>{t.some(a=>{const r=a.contentRect.width,s=this.previewObservedWidths.get(a.target);return this.previewObservedWidths.set(a.target,r),s===void 0||Math.abs(s-r)>.25})&&this.schedulePreviewLayout()},this.kind="wide",this.align="start",this.contained=!1,this.headerPosition="normal",this.fixedMenus=!1,this.previewOpen=!1,this.previewLabel="Preview",this.previewCollapseSidebar=!1,this.previewVisible=!1,this.previewReclaiming=!1,new g(this,".esp-page-left > .sticky-wrapper"),new g(this,".esp-page-right > .sticky-wrapper"),new g(this,".esp-page-flyout > .sticky-wrapper"),new g(this,".esp-page-preview > .sticky-wrapper"),this.addEventListener("flyout-state-changed",t=>this.syncFlyoutState(t))}connectedCallback(){const t=Array.from(this.children).filter(e=>e.getAttribute("slot")==="footer");this.footerWrapperIsLandmark=!t.some(e=>this.footerElementProvidesLandmark(e)),super.connectedCallback(),this.hasUpdated&&queueMicrotask(()=>this.setupPreviewLayoutObserver())}disconnectedCallback(){this.previewResizeObserver?.disconnect(),this.previewResizeObserver=void 0,this.previewMediaQuery?.removeEventListener("change",this.onPreviewMediaChange),this.previewMediaQuery=void 0,this.previewSyncRaf!==null&&(cancelAnimationFrame(this.previewSyncRaf),this.previewSyncRaf=null),this.previewSyncGeneration+=1,this.toggleAttribute("data-preview-measuring",!1),this.setPreviewLayoutState(!1,!1),this.setPreviewNavigationCollapse(!1),super.disconnectedCallback()}syncFlyoutState(t){if(t&&t.target?.closest?.("esp-page")!==this)return;const e=i=>{const o=i.mode;return(typeof o=="string"?o:i.getAttribute("mode"))==="overlay"},a=i=>{const o=i.open;return typeof o=="boolean"?o:i.hasAttribute("open")},r=i=>i.anchor!=null,s=(this.flyoutSlot.value?.assignedElements()??[]).filter(i=>i.tagName==="ESP-FLYOUT");this.toggleAttribute("flyout-open",s.some(i=>a(i)&&!e(i))),this.toggleAttribute("flyout-overlay-open",s.some(i=>a(i)&&e(i))),this.toggleAttribute("flyout-anchored",s.some(i=>a(i)&&r(i))),this.schedulePreviewLayout()}previewHasContent(){const t=this.previewSlot.value?.assignedNodes({flatten:!0});return t?t.some(e=>e.nodeType===Node.ELEMENT_NODE||(e.textContent?.trim().length??0)>0):Array.from(this.childNodes).some(e=>e instanceof Element&&e.getAttribute("slot")==="preview"&&!e.hasAttribute("hidden"))}getPreviewNavigationPair(){if(!this.previewCollapseSidebar)return null;const t=Array.from(this.children),e=t.find(i=>i.slot==="header"&&i.tagName==="ESP-HEADER"),a=t.find(i=>i.slot==="sidebar"&&i.tagName==="ESP-MENU");if(!e||!a||!a.id)return null;const r=typeof e.drawerTarget=="string"?e.drawerTarget:e.getAttribute("drawer-target")??"",s=typeof a.mode=="string"?a.mode:a.getAttribute("mode");return r!==a.id||s!=="vertical"||!("previewCollapseRequested"in e)||!("previewCollapseRequested"in a)?null:{header:e,menu:a}}async setPreviewNavigationCollapse(t){const e=t?this.getPreviewNavigationPair():null,a=e!==null&&this.previewHeader===e.header&&this.previewMenu===e.menu,r=this.previewHeader&&this.previewHeader!==e?.header?this.previewHeader:null,s=this.previewMenu&&this.previewMenu!==e?.menu?this.previewMenu:null;if(r&&(r.previewCollapseRequested=!1),s&&(s.previewCollapseRequested=!1),this.previewHeader=e?.header??null,this.previewMenu=e?.menu??null,this.toggleAttribute("data-preview-navigation-collapsed",!1),await r?.updateComplete,await s?.updateComplete,!e)return this.previewCollapsedSidebarWidth=0,!1;const i=a?this.previewCollapsedSidebarWidth:this.shadowRoot?.querySelector(".esp-page-left")?.getBoundingClientRect().width??0;return e.header.previewCollapseRequested=!0,e.menu.previewCollapseRequested=!0,await e.header.updateComplete,await e.menu.updateComplete,e.menu.hasExternalDrawerControl===!0?(this.previewCollapsedSidebarWidth=i,this.toggleAttribute("data-preview-navigation-collapsed",!0),!0):(e.header.previewCollapseRequested=!1,e.menu.previewCollapseRequested=!1,await e.header.updateComplete,await e.menu.updateComplete,this.previewHeader=null,this.previewMenu=null,this.previewCollapsedSidebarWidth=0,!1)}previewTokenIsConfigured(){return getComputedStyle(this).getPropertyValue("--esp-page-preview-min-main-width").trim().length>0}setPreviewLayoutState(t,e){this.previewVisible=t,this.previewReclaiming=t&&e}previewFitsWithinPage(t,e){const a=this.shadowRoot?.querySelector(".esp-page-main"),r=this.shadowRoot?.querySelector(".esp-page-preview");if(!a||!r)return!1;const s=this.getBoundingClientRect(),i=a.getBoundingClientRect(),o=r.getBoundingClientRect();return i.width+c>=t&&o.width+c>=e&&o.left+c>=s.left&&o.right<=s.right+c}async syncPreviewLayout(t){if(t!==this.previewSyncGeneration||!this.isConnected)return;let e=!1;this.toggleAttribute("data-preview-measuring",!0);try{const a=this.previewOpen&&this.previewHasContent(),r=this.previewMediaQuery?.matches??!1,s=this.hasAttribute("flyout-overlay-open"),i=this.hasAttribute("data-preview-navigation-collapsed")?this.previewCollapsedSidebarWidth:0;if(this.setPreviewLayoutState(!1,!1),this.toggleAttribute("data-preview-navigation-collapsed",!1),await this.updateComplete,t!==this.previewSyncGeneration||!a||r||s)return;const o=this.previewWidthProbe.value?.getBoundingClientRect().width??0,m=this.previewSpace.value?.getBoundingClientRect().width??0,y=Math.max(0,m-i);if(o<=0)return;if(y+c>=o){this.setPreviewLayoutState(!0,!1);return}if(!this.previewTokenIsConfigured())return;const v=this.previewMainMinProbe.value?.getBoundingClientRect().width??0;if(v<=0||(e=await this.setPreviewNavigationCollapse(this.previewCollapseSidebar),t!==this.previewSyncGeneration)||(this.setPreviewLayoutState(!0,!0),await new Promise(b=>requestAnimationFrame(()=>b())),t!==this.previewSyncGeneration))return;this.previewFitsWithinPage(v,o)||(this.setPreviewLayoutState(!1,!1),e=!1)}finally{t===this.previewSyncGeneration&&!e&&await this.setPreviewNavigationCollapse(!1),t===this.previewSyncGeneration&&this.toggleAttribute("data-preview-measuring",!1)}}setupPreviewLayoutObserver(){this.isConnected&&(!this.previewMediaQuery&&typeof window.matchMedia=="function"&&(this.previewMediaQuery=window.matchMedia(_),this.previewMediaQuery.addEventListener("change",this.onPreviewMediaChange)),!this.previewResizeObserver&&typeof ResizeObserver<"u"&&(this.previewResizeObserver=new ResizeObserver(this.onPreviewResize),this.previewResizeObserver.observe(this),this.previewWidthProbe.value&&this.previewResizeObserver.observe(this.previewWidthProbe.value),this.previewMainMinProbe.value&&this.previewResizeObserver.observe(this.previewMainMinProbe.value)),this.schedulePreviewLayout())}footerElementProvidesLandmark(t){return t.matches(w)||t.querySelector(w)!==null}syncFooterLandmark(){const e=(this.footerSlot.value?.assignedElements({flatten:!0})??[]).some(a=>this.footerElementProvidesLandmark(a));this.footerWrapperIsLandmark=!e}showPreview(){this.previewOpen=!0}closePreview(){this.previewOpen=!1}togglePreview(){this.previewOpen=!this.previewOpen}AddDialog(t){this.dialogZone.value?.appendChild(t)}firstUpdated(t){super.firstUpdated(t),this.syncFlyoutState(),this.setupPreviewLayoutObserver()}updated(t){super.updated(t),(t.has("fixedMenus")||t.has("headerPosition"))&&R().publish("fixed-menus-changed",{fixed:this.fixedMenus||this.headerPosition==="fixed"}),(t.has("previewOpen")||t.has("previewCollapseSidebar"))&&this.schedulePreviewLayout()}render(){const t=this.fixedMenus||this.headerPosition==="fixed",e=!t&&this.headerPosition==="sticky";return x`
+      <div part="wrapper" class="esp-page ${z({"fixed-menus":t,"fixed-header":t,"sticky-header":e})}">
         <div part="canvas" class="esp-page-canvas esp-page-canvas--left" aria-hidden="true"></div>
         <div part="canvas" class="esp-page-canvas esp-page-canvas--right" aria-hidden="true"></div>
         <div part="surface" class="esp-page-surface" aria-hidden="true"></div>
         <div class="esp-page-top">
-          <slot name="header"></slot>
+          <slot name="header" @slotchange=${this.schedulePreviewLayout}></slot>
         </div>
         <aside class="esp-page-left">
           <div class="sticky-wrapper">
-            <slot name="sidebar"></slot>
+            <slot name="sidebar" @slotchange=${this.schedulePreviewLayout}></slot>
           </div>
         </aside>
         <div class="esp-page-main">
@@ -23,18 +23,39 @@ var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnP
           <div class="sticky-wrapper">
             <slot
               name="flyout"
-              ${c(this.flyoutSlot)}
+              ${h(this.flyoutSlot)}
               @slotchange=${()=>this.syncFlyoutState()}
             ></slot>
           </div>
         </div>
-        <div class="esp-page-footer" role=${this.footerWrapperIsLandmark?"contentinfo":y}>
-          <slot name="footer" ${c(this.footerSlot)} @slotchange=${this.syncFooterLandmark}></slot>
+        <div
+          class="esp-page-preview-width-probe"
+          aria-hidden="true"
+          ${h(this.previewWidthProbe)}
+        ></div>
+        <div
+          class="esp-page-preview-main-min-probe"
+          aria-hidden="true"
+          ${h(this.previewMainMinProbe)}
+        ></div>
+        <div class="esp-page-preview-space" ${h(this.previewSpace)}>
+          <aside part="preview" class="esp-page-preview" aria-label=${this.previewLabel}>
+            <div part="preview-content" class="sticky-wrapper">
+              <slot
+                name="preview"
+                ${h(this.previewSlot)}
+                @slotchange=${this.schedulePreviewLayout}
+              ></slot>
+            </div>
+          </aside>
         </div>
-        <div id="dialog-drop-zone" ${c(this.dialogZone)}></div>
+        <div class="esp-page-footer" role=${this.footerWrapperIsLandmark?"contentinfo":S}>
+          <slot name="footer" ${h(this.footerSlot)} @slotchange=${this.syncFooterLandmark}></slot>
+        </div>
+        <div id="dialog-drop-zone" ${h(this.dialogZone)}></div>
         <esp-toaster></esp-toaster>
       </div>
-    `}};r.styles=[...g.styles,m`
+    `}};n.styles=[...f.styles,k`
       :host {
         --_esp-page-resolved-max-width: var(--esp-page-max-width, 1536px);
         
@@ -45,6 +66,8 @@ var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnP
         
         --_esp-page-flyout-min: 0px;
         
+        --_esp-page-preview-min: 0px;
+        
         --_esp-page-surface-edge-shadow: 0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow);
         
         --_esp-page-surface-shadow: var(
@@ -88,11 +111,31 @@ var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnP
         --_esp-page-flyout-min: var(--esp-page-flyout-width, 20rem);
       }
 
+      :host([preview-reclaiming]) {
+        --_esp-page-preview-min: var(--esp-page-preview-width, 20rem);
+        --_esp-page-main-track: minmax(
+          var(--esp-page-preview-min-main-width, 0px),
+          var(--_esp-page-resolved-max-width)
+        );
+      }
+
+      :host([kind="full"][preview-reclaiming]) {
+        --_esp-page-main-track: minmax(var(--esp-page-preview-min-main-width, 0px), 1fr);
+      }
+
       
       @media (max-width: 50em) {
         :host([flyout-open]) {
           --_esp-page-flyout-min: 0px;
         }
+
+        :host([preview-reclaiming]) {
+          --_esp-page-preview-min: 0px;
+        }
+
+        .esp-page > .esp-page-preview-space {
+          display: none;
+        }
       }
 
       
@@ -175,6 +218,20 @@ var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnP
         position: absolute;
       }
 
+      :host([preview-visible]) .esp-page > div.esp-page-preview-space > .esp-page-preview {
+        display: block;
+      }
+
+      
+      :host([data-preview-navigation-collapsed]) .esp-page > aside.esp-page-left {
+        inline-size: 0;
+        min-inline-size: 0;
+      }
+
+      :host([data-preview-measuring]) .esp-page {
+        transition: none;
+      }
+
       .esp-page {
         
         min-height: 100vh;
@@ -186,7 +243,7 @@ var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnP
           [left-end main-start] var(--_esp-page-main-track)
           [main-end right-start] min-content
           [right-end surface-end canvas-right-start flyout-start] minmax(
-            var(--_esp-page-flyout-min),
+            calc(var(--_esp-page-flyout-min) + var(--_esp-page-preview-min)),
             var(--_esp-page-gutter-right)
           )
           [flyout-end canvas-right-end full-end];
@@ -272,6 +329,41 @@ var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnP
         }
 
         
+        > div.esp-page-preview-space {
+          grid-column: flyout;
+          grid-row: content;
+          z-index: 4;
+          position: relative;
+          min-inline-size: 0;
+          margin-inline-start: var(--_esp-page-flyout-min);
+
+          > .esp-page-preview {
+            display: none;
+            inline-size: var(--esp-page-preview-width, 20rem);
+            max-inline-size: 100%;
+            position: relative;
+          }
+        }
+
+        
+        > .esp-page-preview-width-probe,
+        > .esp-page-preview-main-min-probe {
+          position: absolute;
+          block-size: 0;
+          visibility: hidden;
+          pointer-events: none;
+          contain: strict;
+        }
+
+        > .esp-page-preview-width-probe {
+          inline-size: var(--esp-page-preview-width, 20rem);
+        }
+
+        > .esp-page-preview-main-min-probe {
+          inline-size: var(--esp-page-preview-min-main-width, 0px);
+        }
+
+        
         > .esp-page-canvas {
           
           grid-row: top-start / footer-end;
@@ -359,6 +451,7 @@ var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnP
           > aside.esp-page-left,
           > aside.esp-page-right,
           > div.esp-page-flyout,
+          > div.esp-page-preview-space,
           > .esp-page-surface,
           > .esp-page-canvas {
             margin-top: var(--_esp-page-fixed-header-offset);
@@ -394,4 +487,4 @@ var i=function(h,e,a,s){var d=arguments.length,o=d<3?e:s===null?s=Object.getOwnP
           transition: none;
         }
       }
-    `],i([b()],r.prototype,"footerWrapperIsLandmark",void 0),i([l({reflect:!0})],r.prototype,"kind",void 0),i([l({reflect:!0})],r.prototype,"align",void 0),i([l({type:Boolean,reflect:!0})],r.prototype,"contained",void 0),i([l({attribute:"header-position",reflect:!0})],r.prototype,"headerPosition",void 0),i([l({attribute:"fixed-menus",type:Boolean,reflect:!0})],r.prototype,"fixedMenus",void 0),r=i([w("esp-page")],r);export{r as EspalierPage};
+    `],p([C()],n.prototype,"footerWrapperIsLandmark",void 0),p([l({reflect:!0})],n.prototype,"kind",void 0),p([l({reflect:!0})],n.prototype,"align",void 0),p([l({type:Boolean,reflect:!0})],n.prototype,"contained",void 0),p([l({attribute:"header-position",reflect:!0})],n.prototype,"headerPosition",void 0),p([l({attribute:"fixed-menus",type:Boolean,reflect:!0})],n.prototype,"fixedMenus",void 0),p([l({attribute:"preview-open",type:Boolean,reflect:!0})],n.prototype,"previewOpen",void 0),p([l({attribute:"preview-label",type:String,reflect:!0})],n.prototype,"previewLabel",void 0),p([l({attribute:"preview-collapse-sidebar",type:Boolean,reflect:!0})],n.prototype,"previewCollapseSidebar",void 0),p([l({attribute:"preview-visible",type:Boolean,reflect:!0})],n.prototype,"previewVisible",void 0),p([l({attribute:"preview-reclaiming",type:Boolean,reflect:!0})],n.prototype,"previewReclaiming",void 0),n=p([P("esp-page")],n);export{n as EspalierPage};

package/dist/shared/bus-events.d.ts

@@ -29,6 +29,7 @@
 import { EspBus } from "./esp-bus.js";
 import type { ToastConfig } from "./toast-events.js";
 import type { FlyoutConfig } from "./flyout-events.js";
+import type { HelpRequest, HelpState } from "./help-events.js";
 /**
  * Contract for elements that provide a seed color to their subtree.
  * Implemented by `EspalierRoot` (the global provider) and
@@ -115,6 +116,24 @@ export interface FlyoutEvents {
     "show-flyout": FlyoutConfig;
     "close-flyout": Record<string, never>;
 }
+/**
+ * URL help-system coordination events.
+ *
+ * `request-help` is published by {@link requestHelp} and serviced by a
+ * connected `<esp-help-provider>`. `close-help` asks that provider to close
+ * only the flyout presenting the matching topic. The provider publishes
+ * `help-state-changed` whenever a topic opens, swaps, or closes so all
+ * matching trigger affordances can synchronize `aria-pressed`.
+ *
+ * @docUrl /api/help-events
+ * @menuGroup Bus Events
+ * @menuLabel HelpEvents
+ */
+export interface HelpEvents {
+    "request-help": HelpRequest;
+    "close-help": Pick<HelpRequest, "src" | "anchor">;
+    "help-state-changed": HelpState;
+}
 /**
  * Cross-popover coordination events.
  *
@@ -181,7 +200,7 @@ export interface PageEventMap {
  * @menuGroup Bus Events
  * @menuLabel EspBusEventMap
  */
-export type EspBusEventMap = SchemeEvents & ToastEvents & FlyoutEvents & PopoverEvents & SizeEvents & PageEventMap;
+export type EspBusEventMap = SchemeEvents & ToastEvents & FlyoutEvents & HelpEvents & PopoverEvents & SizeEvents & PageEventMap;
 /**
  * Typed accessor for the singleton bus.
  *

package/dist/shared/esp-bus.d.ts

@@ -2,5 +2,5 @@ export declare class EspBus<TEventMap extends Record<string, any>> {
     static getInstance<TBus extends Record<string, any>>(): EspBus<TBus>;
     subscribe<K extends keyof TEventMap>(event: K, callback: (payload: TEventMap[K]) => void): void;
     unsubscribe<K extends keyof TEventMap>(event: K, callback: (payload: TEventMap[K]) => void): void;
-    publish<K extends keyof TEventMap>(event: K, payload: TEventMap[K]): void;
+    publish<K extends keyof TEventMap>(event: K, payload: TEventMap[K]): number;
 }

package/dist/shared/esp-bus.js

@@ -1 +1 @@
-class i{constructor(){this.subscribers={}}static getInstance(){return i.instanceBacker||(i.instanceBacker=new i),i.instanceBacker}subscribe(s,r){this.subscribers[s]||(this.subscribers[s]=[]),this.subscribers[s].push(r)}unsubscribe(s,r){this.subscribers[s]&&(this.subscribers[s]=this.subscribers[s].filter(b=>b!==r))}publish(s,r){this.subscribers[s]&&this.subscribers[s].forEach(b=>b(r))}}export{i as EspBus};
+class i{constructor(){this.subscribers={}}static getInstance(){return i.instanceBacker||(i.instanceBacker=new i),i.instanceBacker}subscribe(s,r){this.subscribers[s]||(this.subscribers[s]=[]),this.subscribers[s].push(r)}unsubscribe(s,r){this.subscribers[s]&&(this.subscribers[s]=this.subscribers[s].filter(c=>c!==r))}publish(s,r){const c=this.subscribers[s]??[],b=c.length;return c.forEach(t=>t(r)),b}}export{i as EspBus};

package/dist/shared/events.d.ts

@@ -27,6 +27,7 @@ export { type DestroyEspalierInfo } from "../info/esp-info.js";
 export { type ValidityChangedDetail, type ValidationError, VALIDITY_CHANGED_EVENT, } from "./validation.js";
 export { type ToastConfig } from "./toast-events.js";
 export { type FlyoutConfig, type FlyoutCloseReason } from "./flyout-events.js";
+export { type HelpRequest, type HelpState } from "./help-events.js";
 export { type PickerItem } from "../pickers/esp-picker-item.js";
 export { type EspalierUploadImage } from "../image-upload/image-helpers.js";
 export { type FontPickerValueChangedDetail, type GoogleFont, type WebSafeFont, } from "../font-picker/esp-font-picker.js";

package/dist/shared/flyout-events.d.ts

@@ -37,14 +37,21 @@ export type FlyoutConfig = {
      * has (e.g. declaratively slotted markup).
      */
     content?: string | Node | undefined;
+    /**
+     * Fill the visible block-size in gutter and docked modes instead of
+     * sizing the panel to its content. The content region scrolls
+     * independently. Overlay drawers already fill the viewport.
+     */
+    fullHeight?: boolean | undefined;
     /**
      * Triggering element whose block-start edge the in-grid flyout
      * should align with. The flyout stays in the page's normal scroll
      * flow, shifting upward only while needed to fit the visible
      * scrollport. Content taller than that scrollport scrolls inside the
      * panel. Overlay drawers ignore this geometry and remain
-     * viewport-fixed. When omitted, the flyout starts at the top of the
-     * page's content row.
+     * viewport-fixed. Its outermost containing `esp-page` also supplies
+     * the default flyout scope. When omitted, the flyout starts at the
+     * top of the page's content row.
      */
     anchor?: HTMLElement | undefined;
     /**
@@ -66,9 +73,13 @@ export type FlyoutConfig = {
  * showFlyout({ heading: "Details", content: detailsFragment });
  * ```
  *
- * If no `<esp-flyout>` is connected, the event goes unserviced —
- * callers that need a fallback (e.g. opening a URL in a new tab)
- * should check for a connected flyout themselves.
+ * Anchored requests target the outermost containing `esp-page` by
+ * default; a nested flyout with `scope="nearest"` explicitly overrides
+ * that routing. The nearest-scope flyout must be a light-DOM descendant
+ * of the page whose requests it owns. If no eligible `<esp-flyout>` is
+ * connected, the event goes unserviced — callers that need a fallback
+ * (e.g. opening a URL in a new tab) should check for a connected flyout
+ * themselves.
  *
  * @param config - Flyout configuration.
  * @docUrl /api/show-flyout

package/dist/shared/flyout-events.js

@@ -1 +1 @@
-import{getEspBus as o}from"./bus-events.js";function l(t={}){o().publish("show-flyout",t)}function s(){o().publish("close-flyout",{})}export{s as closeFlyout,l as showFlyout};
+import{getEspBus as o}from"./bus-events.js";const u=new WeakSet,r="flyout-full-height-requested";function n(t={}){s(t)}function s(t={}){const e={...t};return o().publish("show-flyout",e),u.has(e)}function c(t){u.add(t)}function i(){o().publish("close-flyout",{})}export{r as FLYOUT_FULL_HEIGHT_REQUEST_EVENT,i as closeFlyout,c as markFlyoutRequestServiced,s as publishFlyoutRequest,n as showFlyout};

package/dist/shared/help-events.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A request for one topic in a URL-addressable help document.
+ *
+ * @docUrl /api/help-request
+ * @menuGroup Configuration
+ * @menuLabel HelpRequest
+ */
+export type HelpRequest = {
+    /** Absolute document URL without a fragment. */
+    src: string;
+    /** Stable heading id to show first. */
+    anchor?: string | undefined;
+    /** Explicit flyout title. */
+    title?: string | undefined;
+    /** Element whose bounds the contextual flyout should align with. */
+    placementTarget?: HTMLElement | undefined;
+    /** Originating control used for focus restoration. */
+    trigger?: HTMLElement | undefined;
+};
+/**
+ * Current help-topic state published by `esp-help-provider`.
+ *
+ * @docUrl /api/help-state
+ * @menuGroup Event Details
+ * @menuLabel HelpState
+ */
+export type HelpState = {
+    src: string;
+    anchor?: string | undefined;
+    open: boolean;
+};
+/**
+ * Request help through the shared provider. Relative `src` values are
+ * resolved against the current document; a fragment becomes `anchor`
+ * unless the explicit property wins. When no provider is connected,
+ * the resolved topic opens in a new tab.
+ *
+ * ```ts
+ * import { requestHelp } from "@taprootio/espalier";
+ *
+ * requestHelp({
+ *   src: "/help/account.html",
+ *   anchor: "display-name",
+ *   title: "Account help",
+ *   placementTarget: document.querySelector<HTMLElement>("#display-name") ?? undefined,
+ *   trigger: document.querySelector("#account-help") ?? undefined,
+ * });
+ * ```
+ *
+ * @param config - Help document, topic, title, and optional placement/focus targets.
+ * @docUrl /api/request-help
+ * @menuGroup Functions
+ * @menuLabel requestHelp
+ */
+export declare function requestHelp(config: HelpRequest): void;

package/dist/shared/help-events.js

@@ -0,0 +1 @@
+import{getEspBus as c}from"./bus-events.js";function i(e){const r=u(e);c().publish("request-help",r)===0&&s(r)}function s(e){const r=a(e);window.open(r.href,"_blank","noopener,noreferrer")}function u(e){const r=new URL(e.src,document.baseURI),t=l(r.hash);r.hash="";const n=e.anchor?.trim()||t,o=e.title?.trim()||void 0;return{src:r.href,...n?{anchor:n}:{},...o?{title:o}:{},...e.placementTarget?{placementTarget:e.placementTarget}:{},...e.trigger?{trigger:e.trigger}:{}}}function a(e){const r=new URL(e.src,document.baseURI);return e.anchor&&(r.hash=e.anchor),r}function l(e){const r=e.replace(/^#/,"").trim();if(r)try{return decodeURIComponent(r)}catch{return r}}export{l as decodeFragment,s as openHelpInNewTab,i as requestHelp};

package/espalier.token-manifest.json

@@ -1639,6 +1639,18 @@
       "component": "esp-page",
       "description": "The maximum width of the main content well. Set automatically by the `kind` attribute: `1536px` (wide), `768px` (narrow), or `none` (full). This cap now sizes the main grid track; surplus width beyond it becomes the canvas gutters."
     },
+    {
+      "name": "--esp-page-preview-min-main-width",
+      "category": "component",
+      "component": "esp-page",
+      "description": "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."
+    },
+    {
+      "name": "--esp-page-preview-width",
+      "category": "component",
+      "component": "esp-page",
+      "description": "Width of the persistent preview panel. Defaults to `20rem`."
+    },
     {
       "name": "--esp-page-sticky-header-top",
       "category": "component",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "packageManager": "bun@1.3.12",
   "description": "Espalier — a themeable, accessible, framework-agnostic, enterprise-grade design system built on web standards and love.",
   "customElements": "custom-elements.json",
@@ -130,6 +130,14 @@
       "types": "./dist/header/index.d.ts",
       "import": "./dist/header/index.js"
     },
+    "./help/button": {
+      "types": "./dist/help/esp-help-button.d.ts",
+      "import": "./dist/help/esp-help-button.js"
+    },
+    "./help/provider": {
+      "types": "./dist/help/esp-help-provider.d.ts",
+      "import": "./dist/help/esp-help-provider.js"
+    },
     "./image": {
       "types": "./dist/image/esp-image.d.ts",
       "import": "./dist/image/esp-image.js"