@taprootio/espalier 2.0.1 → 2.1.0

package/custom-elements.json

@@ -17753,7 +17753,7 @@
                 "text": "GridRow[]"
               },
               "privacy": "public",
-              "description": "If using a `data-url`, the items retrieved are available\nin the items property. An items array can be assigned\ninstead of using a `data-url`.",
+              "description": "If using a `data-url`, the items retrieved are available\nin the items property. An items array can be assigned\ninstead of using a `data-url`.\n\nAssigning a new items array preserves the grid's current\nintrinsic state: an active search term is re-applied to the\nnew items, the active sort column re-sorts them, and the\ncurrent page is kept when it still exists (clamping to the\nnearest valid page otherwise). Infinite grids delegate search\nand sort to the server through `fetchPage` instead.",
               "attribute": "items"
             },
             {
@@ -18229,6 +18229,25 @@
               "name": "handleSearch",
               "privacy": "private"
             },
+            {
+              "kind": "method",
+              "name": "applySearchTerm",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "GridRow[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "items",
+                  "type": {
+                    "text": "GridRow[]"
+                  }
+                }
+              ],
+              "description": "Filters `items` by the current intrinsic search term, matching\nagainst `searchFields` when configured (all fields otherwise).\nReturns the input array untouched when no search term is active."
+            },
             {
               "kind": "method",
               "name": "loadDataUrl",
@@ -18888,7 +18907,7 @@
               "type": {
                 "text": "GridRow[]"
               },
-              "description": "If using a `data-url`, the items retrieved are available\nin the items property. An items array can be assigned\ninstead of using a `data-url`.",
+              "description": "If using a `data-url`, the items retrieved are available\nin the items property. An items array can be assigned\ninstead of using a `data-url`.\n\nAssigning a new items array preserves the grid's current\nintrinsic state: an active search term is re-applied to the\nnew items, the active sort column re-sorts them, and the\ncurrent page is kept when it still exists (clamping to the\nnearest valid page otherwise). Infinite grids delegate search\nand sort to the server through `fetchPage` instead.",
               "fieldName": "items"
             },
             {
@@ -19222,6 +19241,14 @@
               "description": "The z-index of the header host. Defaults to `20`.",
               "name": "--esp-header-z-index"
             },
+            {
+              "description": "Surface-alignment contract set by `esp-page`: the maximum width the bar content is constrained to (the bar background stays full-bleed). Defaults to `100%` (no constraint). `esp-page` sets this to its resolved content cap.",
+              "name": "--esp-header-content-max-width"
+            },
+            {
+              "description": "Surface-alignment contract set by `esp-page`: the fraction of the leftover width placed before the content, aligning it (`0` = start, `0.5` = center, `1` = end). Defaults to `0`.",
+              "name": "--esp-header-content-lead"
+            },
             {
               "description": "The height of compact scroll-reactive headers. Defaults to `max(44px, calc(3.5 * var(--esp-size-small)))`.",
               "name": "--esp-header-compact-height"
@@ -19638,6 +19665,18 @@
               "description": "Optional ID of an external drawer-capable menu controlled by the\nheader burger. When set, burger open/close events call\n`openDrawer()` / `closeDrawer()` on that element instead of the\nmenu slotted into the header.",
               "attribute": "drawer-target"
             },
+            {
+              "kind": "field",
+              "name": "fullBleedContent",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Opt out of surface alignment. When an `esp-header` is slotted into an\n`esp-page`, it constrains its bar content to the page's content\nsurface by default (the bar background stays full-bleed). Set this to\nlet the content span the full width instead, as it did before the\npage grew alignment modes. Standalone headers (outside `esp-page`) are\nalready full-bleed and unaffected.",
+              "attribute": "full-bleed-content",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "menuContainer",
@@ -20555,6 +20594,15 @@
               "description": "Optional ID of an external drawer-capable menu controlled by the\nheader burger. When set, burger open/close events call\n`openDrawer()` / `closeDrawer()` on that element instead of the\nmenu slotted into the header.",
               "fieldName": "drawerTarget"
             },
+            {
+              "name": "full-bleed-content",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt out of surface alignment. When an `esp-header` is slotted into an\n`esp-page`, it constrains its bar content to the page's content\nsurface by default (the bar background stays full-bleed). Set this to\nlet the content span the full width instead, as it did before the\npage grew alignment modes. Standalone headers (outside `esp-page`) are\nalready full-bleed and unaffected.",
+              "fieldName": "fullBleedContent"
+            },
             {
               "name": "scheme",
               "type": {
@@ -30496,11 +30544,11 @@
           "name": "EspalierPage",
           "cssProperties": [
             {
-              "description": "The background color of the page. Defaults to `var(--esp-color-background)`.",
+              "description": "The background color of the page. Fills both the surface and the canvas gutters; the canvas tokens paint over it in the gutters only. Defaults to `var(--esp-color-background)`.",
               "name": "--esp-page-background"
             },
             {
-              "description": "The maximum width of the main content well. Set automatically by the `kind` attribute: `1536px` (wide), `768px` (narrow), or `none` (full).",
+              "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-max-width"
             },
             {
@@ -30511,6 +30559,26 @@
               "description": "The opacity of the background image layer. Defaults to `1`.",
               "name": "--esp-page-background-image-opacity"
             },
+            {
+              "description": "The background color of the canvas gutters (the outer regions revealed when the viewport exceeds the cap). Defaults to `transparent`, so gutters match the page until styled and narrow viewports are unaffected.",
+              "name": "--esp-page-canvas-background"
+            },
+            {
+              "description": "A background image for the canvas gutters, mirroring the page background-image knob. Defaults to `none`.",
+              "name": "--esp-page-canvas-background-image"
+            },
+            {
+              "description": "The opacity of the canvas gutter image layer. Defaults to `1`.",
+              "name": "--esp-page-canvas-background-image-opacity"
+            },
+            {
+              "description": "The box shadow drawn on the left and right edges of the content surface. On by default; casts into the gutters and is clipped away when the surface fills the viewport, so it only shows above the cap. Set to `none` to remove it.",
+              "name": "--esp-page-surface-shadow"
+            },
+            {
+              "description": "An optional border on the inline edges of the surface, for themes preferring a hairline over a shadow. Defaults to `none` (e.g. `1px solid var(--esp-color-border)`).",
+              "name": "--esp-page-surface-border"
+            },
             {
               "description": "Offset reserved for fixed headers. Defaults to `var(--esp-header-height)`.",
               "name": "--esp-page-fixed-header-offset"
@@ -30520,7 +30588,7 @@
               "name": "--esp-page-sticky-header-top"
             },
             {
-              "description": "Z-index for fixed/sticky header regions. Defaults to `20`. ```html <style> esp-page.with-background { --esp-page-background-image: url(/assets/espalier-paper-texture.png); --esp-page-background-image-opacity: .5; } </style> <esp-page class=\"docs with-background\"> <div slot=\"header\" style=\"background-color: red;\">header</div> <div slot=\"sidebar\" style=\"background-color: green;\">sidebar</div> <div slot=\"right\" style=\"background-color: purple;\">right</div> <div slot=\"footer\" style=\"background-color: blue;\">footer</div> <div style=\"overflow: hidden;\"> <h2>With background image</h2> </div> </esp-page> ```",
+              "description": "Z-index for fixed/sticky header regions. Defaults to `20`.",
               "name": "--esp-page-header-z-index"
             },
             {
@@ -30584,6 +30652,14 @@
             {
               "description": "The page wrapper. It defaults to a grid with a height of 100vh. For the demo page, the height is set to 400px by styling the CSS part: ```html <style> esp-page.docs { &::part(wrapper) { min-height: 400px; height: 400px; } > div { height: 100%; color: yellow; padding: var(--esp-size-padding); } } .demo-wrapper { border: 2px solid var(--esp-color-border); } </style> <esp-page class=\"docs\"> <div slot=\"header\" style=\"background-color: red;\">header</div> <div slot=\"sidebar\" style=\"background-color: green;\">sidebar</div> <div slot=\"right\" style=\"background-color: purple;\">right</div> <div slot=\"footer\" style=\"background-color: blue;\">footer</div> <div style=\"background-color: black; overflow: hidden;\"> content </div> </esp-page> ```",
               "name": "wrapper"
+            },
+            {
+              "description": "The two canvas gutter regions flanking the surface.",
+              "name": "canvas"
+            },
+            {
+              "description": "The surface backdrop carrying the edge shadow/border. ```html <style> esp-page.with-background { --esp-page-background-image: url(/assets/espalier-paper-texture.png); --esp-page-background-image-opacity: .5; } </style> <esp-page class=\"docs with-background\"> <div slot=\"header\" style=\"background-color: red;\">header</div> <div slot=\"sidebar\" style=\"background-color: green;\">sidebar</div> <div slot=\"right\" style=\"background-color: purple;\">right</div> <div slot=\"footer\" style=\"background-color: blue;\">footer</div> <div style=\"overflow: hidden;\"> <h2>With background image</h2> </div> </esp-page> ``` Use `align` to place the surface within the page once it hits its cap, and the canvas tokens to style the gutters. A low `--esp-page-max-width` is set here only so the gutters are visible inside the narrow demo frame; the surface edge shadow is on by default. ```html <style> esp-page.align-demo { --esp-page-max-width: 520px; --esp-page-canvas-background: var(--esp-color-layer-1); } </style> <esp-page class=\"docs align-demo\" align=\"center\"> <div slot=\"header\" style=\"background-color: red;\">header</div> <div slot=\"sidebar\" style=\"background-color: green;\">sidebar</div> <div slot=\"right\" style=\"background-color: purple;\">right</div> <div slot=\"footer\" style=\"background-color: blue;\">footer</div> <div style=\"background-color: black; overflow: hidden;\"> content </div> </esp-page> ```",
+              "name": "surface"
             }
           ],
           "slots": [
@@ -30626,6 +30702,30 @@
               "attribute": "kind",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "align",
+              "type": {
+                "text": "\"start\" | \"center\" | \"end\""
+              },
+              "privacy": "public",
+              "default": "\"start\"",
+              "description": "Horizontal alignment of the content **surface** (left aside + main\nwell + right aside) within the page once the viewport is wider than\nthe content cap. The surplus width becomes styleable **canvas**\ngutters on the outer edges, weighted by this attribute.\n\n- `start` (default) — the surface hugs the leading edge; all spare\n  width collects in the trailing gutter. This reproduces today's\n  layout.\n- `center` — spare width is split evenly into both gutters, centering\n  the surface.\n- `end` — the surface hugs the trailing edge; spare width collects in\n  the leading gutter.\n\nHas no effect when `kind=\"full\"` (no cap means no gutters) or on\nviewports narrower than the cap (the surface already fills the width).",
+              "attribute": "align",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "contained",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "When set, the header and footer sit **on** the content surface —\nthe same width as the left aside + main well + right aside — instead\nof spanning the full viewport. Combined with a styled canvas this\nframes the whole page as one contained band floating on the canvas,\nwith a single continuous surface edge shadow running from the header\nthrough the content to the footer.\n\nBelow the cap there are no gutters, so a contained page renders\nidentically to the default full-bleed chrome. Designed for\n`header-position=\"normal\"` or `\"sticky\"`; a fixed header cannot be\nbanded to the surface.",
+              "attribute": "contained",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "headerPosition",
@@ -31134,6 +31234,24 @@
               "description": "The layout mode of the page.\n\n- `wide` (default) — constrains the main content well to 1536px.\n  Optimized for high-density dashboards and complex data grids.\n- `narrow` — constrains the main content well to 768px and applies\n  a `max-inline-size: 66ch` reading measure. Optimized for\n  long-form reading content.\n- `full` — no max-width constraint; the content well spans the\n  full available space. Optimized for immersive canvases like\n  maps or design tools.",
               "fieldName": "kind"
             },
+            {
+              "name": "align",
+              "type": {
+                "text": "\"start\" | \"center\" | \"end\""
+              },
+              "default": "\"start\"",
+              "description": "Horizontal alignment of the content **surface** (left aside + main\nwell + right aside) within the page once the viewport is wider than\nthe content cap. The surplus width becomes styleable **canvas**\ngutters on the outer edges, weighted by this attribute.\n\n- `start` (default) — the surface hugs the leading edge; all spare\n  width collects in the trailing gutter. This reproduces today's\n  layout.\n- `center` — spare width is split evenly into both gutters, centering\n  the surface.\n- `end` — the surface hugs the trailing edge; spare width collects in\n  the leading gutter.\n\nHas no effect when `kind=\"full\"` (no cap means no gutters) or on\nviewports narrower than the cap (the surface already fills the width).",
+              "fieldName": "align"
+            },
+            {
+              "name": "contained",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When set, the header and footer sit **on** the content surface —\nthe same width as the left aside + main well + right aside — instead\nof spanning the full viewport. Combined with a styled canvas this\nframes the whole page as one contained band floating on the canvas,\nwith a single continuous surface edge shadow running from the header\nthrough the content to the footer.\n\nBelow the cap there are no gutters, so a contained page renders\nidentically to the default full-bleed chrome. Designed for\n`header-position=\"normal\"` or `\"sticky\"`; a fixed header cannot be\nbanded to the surface.",
+              "fieldName": "contained"
+            },
             {
               "name": "header-position",
               "type": {

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

@@ -394,6 +394,13 @@ export declare class EspalierGrid extends EspalierElementBase {
      * If using a `data-url`, the items retrieved are available
      * in the items property. An items array can be assigned
      * instead of using a `data-url`.
+     *
+     * Assigning a new items array preserves the grid's current
+     * intrinsic state: an active search term is re-applied to the
+     * new items, the active sort column re-sorts them, and the
+     * current page is kept when it still exists (clamping to the
+     * nearest valid page otherwise). Infinite grids delegate search
+     * and sort to the server through `fetchPage` instead.
      */
     get items(): GridRow[];
     set items(newItems: GridRow[]);

package/dist/grid/esp-grid.js

@@ -1,4 +1,4 @@
-var h=function(I,e,t,i){var s=arguments.length,o=s<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,r;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(I,e,t,i);else for(var n=I.length-1;n>=0;n--)(r=I[n])&&(o=(s<3?r(o):s>3?r(e,t,o):r(e,t))||o);return s>3&&o&&Object.defineProperty(e,t,o),o};import{css as E,html as c}from"lit";import{customElement as A,property as m,state as u}from"lit/decorators.js";import"../input/esp-input.js";import"../button/esp-button.js";import{EspalierElementBase as S}from"../shared/esp-element-base.js";import{ref as y,createRef as w}from"lit/directives/ref.js";import"./esp-grid-column.js";import{classMap as x}from"lit/directives/class-map.js";import{styleMap as P}from"lit/directives/style-map.js";import{leftArrow as N}from"../shared/svgs/left-arrow.js";import{rightArrow as T}from"../shared/svgs/right-arrow.js";import{filter as G}from"../shared/svgs/filter.js";import"../shared/virtualizer/lit-virtualizer.js";const L="esp-grid-load-start",M="esp-grid-load-success",z="esp-grid-load-error",j="esp-grid-items-changed";let d=class extends S{constructor(){super(...arguments),this.columnDefinitionsSlot=w(),this.headerButtonsSlot=w(),this.filteredItems=[],this.sortColumn=void 0,this.itemsBacker=[],this.virtualizerRef=w(),this.gridHeaderRowRef=w(),this.infiniteContainerRef=w(),this.pageLoadVersion=0,this.nextCursor=null,this.searchTerm="",this.allowNext=!1,this.allowPrevious=!1,this.columnDefinitions=new Array,this.displayedItems=[],this.pageNumber=1,this.footerMessage="",this.allLoadedItems=[],this.hasMoreData=!1,this.isLoadingFirstPage=!1,this.isLoadingPage=!1,this.effectiveGridHeight="",this.pendingHeightRetry=!1,this.wheelHandlerAttached=!1,this.dataField="",this.dataUrl="",this.pageSize=10,this.gridHeight="60vh",this.searchFields=[],this.fetchPageBacker=null,this.isAdjustingHeight=!1,this.heightRetryObserver=null,this.pinnedOffsets=new Map,this.handleGridClick=e=>{const t=e.target,i=t.hasAttribute("grid-event")?t:t.closest("[grid-event]");if(!i)return;const s=i.closest("tr")??i.closest(".grid-row"),o=Number(s?.dataset.rowIndex),r=this.isInfiniteMode?this.allLoadedItems:this.displayedItems,n=Number.isInteger(o)&&o>=0?r[o]:void 0;this.dispatchEvent(new CustomEvent("grid-event",{detail:{grid:this,target:i,event:i.getAttribute("grid-event")??"",data:n??{}},bubbles:!1,composed:!0})),e.stopPropagation()},this.syncHeaderScroll=()=>{const e=this.virtualizerRef.value,t=this.gridHeaderRowRef.value;e&&t&&(t.scrollLeft=e.scrollLeft)},this.handleVirtualizerWheel=e=>{const t=this.infiniteContainerRef.value;if(!t)return;const i=t.getBoundingClientRect(),s=window.innerHeight,o=i.top>=0&&i.bottom<=s,r=i.top<=0&&i.bottom>=s;!o&&!r&&(e.preventDefault(),window.scrollBy(0,e.deltaY))},this.handleSearch=e=>{const t=e.detail.toLowerCase();if(this.isInfiniteMode)this.searchDebounceTimer&&clearTimeout(this.searchDebounceTimer),this.searchDebounceTimer=setTimeout(async()=>{this.searchTerm=t,await this.resetAndReload().catch(()=>{})},300);else{this.searchTerm=t;const i=this.items.filter(s=>{let o;return this.searchFields.length>0?o=this.searchFields.map(r=>s[r]):o=Object.values(s),o.some(r=>String(r).toLowerCase().includes(t))});this.filteredItems=i,this.setPage(1),this.dispatchItemsChanged()}}}get items(){return this.itemsBacker}set items(e){this.applyPagedItems(e)}applyPagedItems(e,t={}){const i=t.emitItemsChanged??!0,s=t.pageNumber??this.pageNumber??1;this.itemsBacker=e,this.filteredItems=this.itemsBacker,this.sortColumn?this.sort({emitItemsChanged:!1,pageNumber:s}):this.setPage(s),i&&this.dispatchItemsChanged()}get fetchPage(){return this.fetchPageBacker}set fetchPage(e){this.fetchPageBacker=e,e&&this.hasUpdated&&this.loadPage(null).then(async()=>{await this.updateComplete,this.measurePinnedOffsets()}).catch(()=>{})}get isInfiniteMode(){return this.fetchPage!==null}get currentDataStateItems(){return this.isInfiniteMode?this.allLoadedItems:this.filteredItems}getCurrentSortField(){return this.sortColumn?this.sortColumn.sortField.length>0?this.sortColumn.sortField:this.sortColumn.fieldName:""}createDataStateDetail(e={}){const t=[...this.currentDataStateItems],i=e.cursor??null,s=e.isFirstPage??(this.isInfiniteMode?i===null:this.pageNumber<=1);return{items:t,itemCount:t.length,isFirstPage:s,cursor:i,nextCursor:this.nextCursor,hasRows:t.length>0,isEmpty:t.length===0,search:this.searchTerm,sortField:this.getCurrentSortField(),sortOrder:this.sortColumn?.sortOrder??""}}dispatchGridDataEvent(e,t){this.dispatchEvent(new CustomEvent(e,{detail:t,bubbles:!0,composed:!0}))}dispatchItemsChanged(e={}){this.dispatchGridDataEvent(j,this.createDataStateDetail(e))}setPage(e){const t=Math.ceil(this.filteredItems.length/this.pageSize);e>t&&(e=t),this.pageNumber=e;const i=(this.pageNumber-1)*this.pageSize;switch(this.displayedItems=this.filteredItems.slice(i,i+this.pageSize),this.allowPrevious=this.pageNumber>1,this.allowNext=t>this.pageNumber,t){case 0:this.footerMessage="No matching items";break;case 1:this.footerMessage=this.filteredItems.length<this.items.length?"Showing all filtered items":"Showing all items";break;default:this.footerMessage=`Showing page ${this.pageNumber} of ${t} pages`}}async loadPage(e){const t=this.fetchPage;if(!t||e!==null&&this.isLoadingPage)return;const i=++this.pageLoadVersion,s=e===null;let o=!1;this.isLoadingPage=!0,this.isLoadingFirstPage=s,s&&(this.nextCursor=null,this.hasMoreData=!1);const r={cursor:e,limit:this.pageSize,search:this.searchTerm,sortField:this.getCurrentSortField(),sortOrder:this.sortColumn?.sortOrder??""};this.dispatchGridDataEvent(L,this.createDataStateDetail({cursor:e,isFirstPage:s}));try{const n=await t(r);if(i!==this.pageLoadVersion)return;e===null?this.allLoadedItems=[...n.items]:this.allLoadedItems=[...this.allLoadedItems,...n.items],this.nextCursor=n.nextCursor,this.hasMoreData=n.nextCursor!==null,o=!0,this.dispatchGridDataEvent(M,this.createDataStateDetail({cursor:e,isFirstPage:s})),this.dispatchItemsChanged({cursor:e,isFirstPage:s})}catch(n){throw i===this.pageLoadVersion&&this.dispatchGridDataEvent(z,{...this.createDataStateDetail({cursor:e,isFirstPage:s}),error:n}),n}finally{if(i===this.pageLoadVersion){if(this.isLoadingPage=!1,this.isLoadingFirstPage=!1,s&&o){const n=this.virtualizerRef.value;if(n&&n.scrollTop>0)try{n.scrollTo({top:0})}catch{n.scrollTop=0}}await this.adjustInfiniteHeight()}}}async resetAndReload(){await this.loadPage(null)}onRangeChanged(e){this.isLoadingFirstPage||e.last>=this.allLoadedItems.length-5&&this.hasMoreData&&!this.isLoadingPage&&this.loadPage(this.nextCursor).catch(()=>{})}async adjustInfiniteHeight(){if(!this.isAdjustingHeight){this.isAdjustingHeight=!0;try{const e=this.virtualizerRef.value;e&&(e.style.minHeight=""),this.effectiveGridHeight=this.gridHeight,await this.updateComplete;const t=this.infiniteContainerRef.value,i=this.virtualizerRef.value;if(!t||this.hasMoreData)return;const o=this.gridHeaderRowRef.value?.offsetHeight??0;if(!i){const p=t.querySelector(".no-results");let f=0;p?f=o+p.offsetHeight:t.querySelectorAll(":scope > *").forEach(R=>f+=R.offsetHeight),f<t.offsetHeight&&(this.effectiveGridHeight=`${f}px`);return}const r=i.querySelectorAll(".grid-row");let n=0,a=!1;if(r.forEach(p=>{const f=p.offsetHeight;f===0&&(a=!0),n+=f}),r.length===0||a||n===0){this.pendingHeightRetry||(this.pendingHeightRetry=!0,this.observeForHeightRetry(i));return}const l=i.querySelectorAll(".grid-row :defined"),g=[];l.forEach(p=>{"updateComplete"in p&&g.push(p.updateComplete)}),g.length>0&&(await Promise.all(g),n=0,r.forEach(p=>{n+=p.offsetHeight}));const v=n+o,b=t.offsetHeight;v<b&&r.length>=this.allLoadedItems.length&&(i.style.minHeight=`${n}px`,this.effectiveGridHeight=`${v}px`),!this.hasMoreData&&!this.pendingHeightRetry&&(this.pendingHeightRetry=!0,setTimeout(()=>{this.pendingHeightRetry=!1;const p=this.infiniteContainerRef.value,f=this.virtualizerRef.value;if(!p||!f||this.hasMoreData)return;const O=this.gridHeaderRowRef.value?.offsetHeight??0,k=f.querySelectorAll(".grid-row");let C=0,D=!1;if(k.forEach(F=>{const H=F.offsetHeight;H===0&&(D=!0),C+=H}),k.length===0||D||C===0)return;const $=C+O;$<p.offsetHeight&&k.length>=this.allLoadedItems.length&&(f.style.minHeight=`${C}px`,this.effectiveGridHeight=`${$}px`)},100))}finally{this.isAdjustingHeight=!1}}}observeForHeightRetry(e){this.heightRetryObserver?.disconnect(),this.heightRetryObserver=new IntersectionObserver(t=>{if(!t.some(r=>r.isIntersecting))return;this.heightRetryObserver?.disconnect(),this.heightRetryObserver=null;let s=0;const o=()=>{this.pendingHeightRetry=!1,this.adjustInfiniteHeight(),this.pendingHeightRetry&&++s<5&&setTimeout(o,100)};requestAnimationFrame(()=>setTimeout(o,50))},{threshold:0}),this.heightRetryObserver.observe(e)}async sortOn(e){this.sortColumn===e?this.sortColumn.sortOrder=this.sortColumn.sortOrder=="asc"?"desc":"asc":(this.sortColumn=e,this.sortColumn.sortOrder="asc"),this.isInfiniteMode?await this.resetAndReload():this.sort()}sort(e={}){if(!this.sortColumn)return;const t=this.getCurrentSortField(),i=this.sortColumn.sortOrder==="asc"?1:-1,s=this.sortColumn.sortType,o=this.filteredItems.map((r,n)=>{const a=r[t]??"",l=s==="number"?Number(a):a.toString().toLowerCase();return{item:r,index:n,sortValue:l}});o.sort((r,n)=>r.sortValue<n.sortValue?-1*i:r.sortValue>n.sortValue?1*i:r.index-n.index),this.filteredItems=o.map(({item:r})=>r),this.setPage(e.pageNumber??1),(e.emitItemsChanged??!0)&&this.dispatchItemsChanged()}delete(e){if(this.isInfiniteMode){const t=this.allLoadedItems.filter(i=>!e(i));if(t.length===this.allLoadedItems.length)return;this.allLoadedItems=t,this.dispatchItemsChanged(),this.adjustInfiniteHeight()}else{const t=this.items.filter(i=>!e(i));if(t.length===this.items.length)return;this.items=t}}addOrReplace(e,t){if(this.isInfiniteMode){const i=this.allLoadedItems.findIndex(e);if(i>=0){const s=[...this.allLoadedItems];s[i]={...s[i],...t},this.allLoadedItems=s}else this.allLoadedItems=[...this.allLoadedItems,t];this.dispatchItemsChanged(),this.adjustInfiniteHeight()}else this.items.find(e)?this.items=this.items.map(s=>e(s)?{...s,...t}:s):this.items=[...this.items,t]}addInOrder(e,t,i){if(this.isInfiniteMode){const a=this.allLoadedItems.findIndex(e),l=[...this.allLoadedItems];if(a>=0)return l[a]={...l[a],...t},this.allLoadedItems=l,this.dispatchItemsChanged(),a;let g=0,v=l.length;for(;g<v;){const b=g+v>>>1;i(l[b],t)<0?g=b+1:v=b}return l.splice(g,0,t),this.allLoadedItems=l,this.dispatchItemsChanged(),this.adjustInfiniteHeight(),g}const s=this.items.findIndex(e),o=[...this.items];if(s>=0)return o[s]={...o[s],...t},this.items=o,s;let r=0,n=o.length;for(;r<n;){const a=r+n>>>1;i(o[a],t)<0?r=a+1:n=a}return o.splice(r,0,t),this.items=o,r}async scrollToIndex(e,t="center"){if(this.isInfiniteMode){await this.updateComplete;const i=this.virtualizerRef.value;if(!i)return;await i.updateComplete,await new Promise(s=>requestAnimationFrame(s)),await i.layoutComplete,i.scrollToIndex(e,t)}else{const i=Math.floor(e/this.pageSize)+1;this.setPage(i)}}clear(){if(this.isInfiniteMode){if(this.allLoadedItems.length===0&&this.nextCursor===null&&!this.hasMoreData)return;this.allLoadedItems=[],this.nextCursor=null,this.hasMoreData=!1,this.dispatchItemsChanged(),this.adjustInfiniteHeight()}else{if(this.items.length===0)return;this.items=[]}}async reload(){this.isInfiniteMode&&await this.resetAndReload()}computePinnedStyles(){return this.pinnedOffsets}measurePinnedOffsets(){this.pinnedOffsets=new Map,this.isInfiniteMode?this.computePinnedOffsetsFromWidths():this.measurePinnedOffsetsFromCells(),this.requestUpdate()}computePinnedOffsetsFromWidths(){const e=this.columnDefinitions.filter(r=>r.pin==="left"),t=this.columnDefinitions.filter(r=>r.pin==="right"),i=[];for(let r=0;r<e.length;r++){const n=e[r],a=i.length===0?"0px":`calc(${i.join(" + ")})`;this.pinnedOffsets.set(n,{position:"sticky",left:a,zIndex:`${e.length-r+1}`}),i.push(n.width||"0px")}const s=[],o=[...t].reverse();for(let r=0;r<o.length;r++){const n=o[r],a=s.length===0?"0px":`calc(${s.join(" + ")})`;this.pinnedOffsets.set(n,{position:"sticky",right:a,zIndex:`${o.length-r+1}`}),s.push(n.width||"0px")}}measurePinnedOffsetsFromCells(){const e=this.shadowRoot?.querySelectorAll("thead th");if(!e)return;const t=this.columnDefinitions.filter(a=>a.pin==="left"),i=this.columnDefinitions.filter(a=>a.pin==="right"),s=new Map;this.columnDefinitions.forEach((a,l)=>{e[l]&&s.set(a,e[l])});let o=0;for(let a=0;a<t.length;a++){const l=t[a];this.pinnedOffsets.set(l,{position:"sticky",left:`${o}px`,zIndex:`${t.length-a+1}`});const g=s.get(l);g&&(o+=g.offsetWidth)}let r=0;const n=[...i].reverse();for(let a=0;a<n.length;a++){const l=n[a];this.pinnedOffsets.set(l,{position:"sticky",right:`${r}px`,zIndex:`${n.length-a+1}`});const g=s.get(l);g&&(r+=g.offsetWidth)}}computeGridTemplateColumns(){return this.columnDefinitions.map(e=>e.width?e.grow?`minmax(${e.width}, 1fr)`:e.width:e.grow?"minmax(0, 1fr)":"auto").join(" ")}get hasGrowableColumns(){return this.columnDefinitions.some(e=>e.grow)}computePinnedColumnFlags(){const e=new Map,t=this.columnDefinitions.filter(r=>r.pin==="left"),i=this.columnDefinitions.filter(r=>r.pin==="right"),s=t[t.length-1],o=i[0];return this.columnDefinitions.forEach((r,n)=>{e.set(r,{beforePinnedRight:this.columnDefinitions[n+1]?.pin==="right",firstPinnedRight:o===r,lastPinnedLeft:s===r})}),e}renderCell(e,t){if(!e.fieldName)return c`<span></span>`;const i=e.textAlign??"left";return c`<span style="text-align: ${i};"> ${t[e.fieldName]} </span>`}attachWheelHandler(){const e=this.virtualizerRef.value;e&&!this.wheelHandlerAttached?(e.addEventListener("wheel",this.handleVirtualizerWheel,{passive:!1}),this.wheelHandlerAttached=!0):!e&&this.wheelHandlerAttached&&(this.wheelHandlerAttached=!1)}async firstUpdated(e){super.firstUpdated(e),this.headerButtonsSlot.value.assignedElements().length===0&&this.headerButtonsSlot.value.remove();for(const i of this.columnDefinitionsSlot.value.assignedElements())i.localName==="esp-grid-column"&&this.columnDefinitions.push(i);const t=this.columnDefinitions.find(i=>i.sortOrder!=="");t&&(this.sortColumn=t),this.isInfiniteMode?await this.loadPage(null).catch(()=>{}):this.dataUrl.length&&await this.loadDataUrl().catch(()=>{}),await this.updateComplete,this.measurePinnedOffsets()}updated(e){super.updated(e),this.isInfiniteMode&&this.attachWheelHandler()}async loadDataUrl(){this.dispatchGridDataEvent(L,this.createDataStateDetail({cursor:null,isFirstPage:!0}));try{const t=await fetch(this.dataUrl).then(i=>i.json());this.applyPagedItems(this.dataField?t[this.dataField]:t,{emitItemsChanged:!1}),this.dispatchGridDataEvent(M,this.createDataStateDetail({cursor:null,isFirstPage:!0})),this.dispatchItemsChanged({cursor:null,isFirstPage:!0})}catch(t){throw this.dispatchGridDataEvent(z,{...this.createDataStateDetail({cursor:null,isFirstPage:!0}),error:t}),t}}disconnectedCallback(){super.disconnectedCallback();const e=this.virtualizerRef.value;e&&e.removeEventListener("wheel",this.handleVirtualizerWheel),this.wheelHandlerAttached=!1,this.heightRetryObserver?.disconnect(),this.heightRetryObserver=null}renderSortIcons(){return c`
+var h=function(I,e,t,i){var s=arguments.length,o=s<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,r;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(I,e,t,i);else for(var n=I.length-1;n>=0;n--)(r=I[n])&&(o=(s<3?r(o):s>3?r(e,t,o):r(e,t))||o);return s>3&&o&&Object.defineProperty(e,t,o),o};import{css as E,html as c}from"lit";import{customElement as A,property as m,state as u}from"lit/decorators.js";import"../input/esp-input.js";import"../button/esp-button.js";import{EspalierElementBase as S}from"../shared/esp-element-base.js";import{ref as y,createRef as w}from"lit/directives/ref.js";import"./esp-grid-column.js";import{classMap as x}from"lit/directives/class-map.js";import{styleMap as P}from"lit/directives/style-map.js";import{leftArrow as T}from"../shared/svgs/left-arrow.js";import{rightArrow as G}from"../shared/svgs/right-arrow.js";import{filter as N}from"../shared/svgs/filter.js";import"../shared/virtualizer/lit-virtualizer.js";const L="esp-grid-load-start",M="esp-grid-load-success",z="esp-grid-load-error",j="esp-grid-items-changed";let d=class extends S{constructor(){super(...arguments),this.columnDefinitionsSlot=w(),this.headerButtonsSlot=w(),this.filteredItems=[],this.sortColumn=void 0,this.itemsBacker=[],this.virtualizerRef=w(),this.gridHeaderRowRef=w(),this.infiniteContainerRef=w(),this.pageLoadVersion=0,this.nextCursor=null,this.searchTerm="",this.allowNext=!1,this.allowPrevious=!1,this.columnDefinitions=new Array,this.displayedItems=[],this.pageNumber=1,this.footerMessage="",this.allLoadedItems=[],this.hasMoreData=!1,this.isLoadingFirstPage=!1,this.isLoadingPage=!1,this.effectiveGridHeight="",this.pendingHeightRetry=!1,this.wheelHandlerAttached=!1,this.dataField="",this.dataUrl="",this.pageSize=10,this.gridHeight="60vh",this.searchFields=[],this.fetchPageBacker=null,this.isAdjustingHeight=!1,this.heightRetryObserver=null,this.pinnedOffsets=new Map,this.handleGridClick=e=>{const t=e.target,i=t.hasAttribute("grid-event")?t:t.closest("[grid-event]");if(!i)return;const s=i.closest("tr")??i.closest(".grid-row"),o=Number(s?.dataset.rowIndex),r=this.isInfiniteMode?this.allLoadedItems:this.displayedItems,n=Number.isInteger(o)&&o>=0?r[o]:void 0;this.dispatchEvent(new CustomEvent("grid-event",{detail:{grid:this,target:i,event:i.getAttribute("grid-event")??"",data:n??{}},bubbles:!1,composed:!0})),e.stopPropagation()},this.syncHeaderScroll=()=>{const e=this.virtualizerRef.value,t=this.gridHeaderRowRef.value;e&&t&&(t.scrollLeft=e.scrollLeft)},this.handleVirtualizerWheel=e=>{const t=this.infiniteContainerRef.value;if(!t)return;const i=t.getBoundingClientRect(),s=window.innerHeight,o=i.top>=0&&i.bottom<=s,r=i.top<=0&&i.bottom>=s;!o&&!r&&(e.preventDefault(),window.scrollBy(0,e.deltaY))},this.handleSearch=e=>{const t=e.detail.toLowerCase();this.isInfiniteMode?(this.searchDebounceTimer&&clearTimeout(this.searchDebounceTimer),this.searchDebounceTimer=setTimeout(async()=>{this.searchTerm=t,await this.resetAndReload().catch(()=>{})},300)):(this.searchTerm=t,this.filteredItems=this.applySearchTerm(this.items),this.sortColumn?this.sort({emitItemsChanged:!1,pageNumber:1}):this.setPage(1),this.dispatchItemsChanged())}}get items(){return this.itemsBacker}set items(e){this.applyPagedItems(e)}applyPagedItems(e,t={}){const i=t.emitItemsChanged??!0,s=t.pageNumber??this.pageNumber??1;this.itemsBacker=e,this.filteredItems=this.applySearchTerm(this.itemsBacker),this.sortColumn?this.sort({emitItemsChanged:!1,pageNumber:s}):this.setPage(s),i&&this.dispatchItemsChanged()}get fetchPage(){return this.fetchPageBacker}set fetchPage(e){this.fetchPageBacker=e,e&&this.hasUpdated&&this.loadPage(null).then(async()=>{await this.updateComplete,this.measurePinnedOffsets()}).catch(()=>{})}get isInfiniteMode(){return this.fetchPage!==null}get currentDataStateItems(){return this.isInfiniteMode?this.allLoadedItems:this.filteredItems}getCurrentSortField(){return this.sortColumn?this.sortColumn.sortField.length>0?this.sortColumn.sortField:this.sortColumn.fieldName:""}createDataStateDetail(e={}){const t=[...this.currentDataStateItems],i=e.cursor??null,s=e.isFirstPage??(this.isInfiniteMode?i===null:this.pageNumber<=1);return{items:t,itemCount:t.length,isFirstPage:s,cursor:i,nextCursor:this.nextCursor,hasRows:t.length>0,isEmpty:t.length===0,search:this.searchTerm,sortField:this.getCurrentSortField(),sortOrder:this.sortColumn?.sortOrder??""}}dispatchGridDataEvent(e,t){this.dispatchEvent(new CustomEvent(e,{detail:t,bubbles:!0,composed:!0}))}dispatchItemsChanged(e={}){this.dispatchGridDataEvent(j,this.createDataStateDetail(e))}setPage(e){const t=Math.ceil(this.filteredItems.length/this.pageSize);e>t&&(e=t),e<1&&(e=1),this.pageNumber=e;const i=(this.pageNumber-1)*this.pageSize;switch(this.displayedItems=this.filteredItems.slice(i,i+this.pageSize),this.allowPrevious=this.pageNumber>1,this.allowNext=t>this.pageNumber,t){case 0:this.footerMessage="No matching items";break;case 1:this.footerMessage=this.filteredItems.length<this.items.length?"Showing all filtered items":"Showing all items";break;default:this.footerMessage=`Showing page ${this.pageNumber} of ${t} pages`}}async loadPage(e){const t=this.fetchPage;if(!t||e!==null&&this.isLoadingPage)return;const i=++this.pageLoadVersion,s=e===null;let o=!1;this.isLoadingPage=!0,this.isLoadingFirstPage=s,s&&(this.nextCursor=null,this.hasMoreData=!1);const r={cursor:e,limit:this.pageSize,search:this.searchTerm,sortField:this.getCurrentSortField(),sortOrder:this.sortColumn?.sortOrder??""};this.dispatchGridDataEvent(L,this.createDataStateDetail({cursor:e,isFirstPage:s}));try{const n=await t(r);if(i!==this.pageLoadVersion)return;e===null?this.allLoadedItems=[...n.items]:this.allLoadedItems=[...this.allLoadedItems,...n.items],this.nextCursor=n.nextCursor,this.hasMoreData=n.nextCursor!==null,o=!0,this.dispatchGridDataEvent(M,this.createDataStateDetail({cursor:e,isFirstPage:s})),this.dispatchItemsChanged({cursor:e,isFirstPage:s})}catch(n){throw i===this.pageLoadVersion&&this.dispatchGridDataEvent(z,{...this.createDataStateDetail({cursor:e,isFirstPage:s}),error:n}),n}finally{if(i===this.pageLoadVersion){if(this.isLoadingPage=!1,this.isLoadingFirstPage=!1,s&&o){const n=this.virtualizerRef.value;if(n&&n.scrollTop>0)try{n.scrollTo({top:0})}catch{n.scrollTop=0}}await this.adjustInfiniteHeight()}}}async resetAndReload(){await this.loadPage(null)}onRangeChanged(e){this.isLoadingFirstPage||e.last>=this.allLoadedItems.length-5&&this.hasMoreData&&!this.isLoadingPage&&this.loadPage(this.nextCursor).catch(()=>{})}async adjustInfiniteHeight(){if(!this.isAdjustingHeight){this.isAdjustingHeight=!0;try{const e=this.virtualizerRef.value;e&&(e.style.minHeight=""),this.effectiveGridHeight=this.gridHeight,await this.updateComplete;const t=this.infiniteContainerRef.value,i=this.virtualizerRef.value;if(!t||this.hasMoreData)return;const o=this.gridHeaderRowRef.value?.offsetHeight??0;if(!i){const p=t.querySelector(".no-results");let f=0;p?f=o+p.offsetHeight:t.querySelectorAll(":scope > *").forEach(R=>f+=R.offsetHeight),f<t.offsetHeight&&(this.effectiveGridHeight=`${f}px`);return}const r=i.querySelectorAll(".grid-row");let n=0,a=!1;if(r.forEach(p=>{const f=p.offsetHeight;f===0&&(a=!0),n+=f}),r.length===0||a||n===0){this.pendingHeightRetry||(this.pendingHeightRetry=!0,this.observeForHeightRetry(i));return}const l=i.querySelectorAll(".grid-row :defined"),g=[];l.forEach(p=>{"updateComplete"in p&&g.push(p.updateComplete)}),g.length>0&&(await Promise.all(g),n=0,r.forEach(p=>{n+=p.offsetHeight}));const v=n+o,b=t.offsetHeight;v<b&&r.length>=this.allLoadedItems.length&&(i.style.minHeight=`${n}px`,this.effectiveGridHeight=`${v}px`),!this.hasMoreData&&!this.pendingHeightRetry&&(this.pendingHeightRetry=!0,setTimeout(()=>{this.pendingHeightRetry=!1;const p=this.infiniteContainerRef.value,f=this.virtualizerRef.value;if(!p||!f||this.hasMoreData)return;const O=this.gridHeaderRowRef.value?.offsetHeight??0,k=f.querySelectorAll(".grid-row");let C=0,D=!1;if(k.forEach(F=>{const H=F.offsetHeight;H===0&&(D=!0),C+=H}),k.length===0||D||C===0)return;const $=C+O;$<p.offsetHeight&&k.length>=this.allLoadedItems.length&&(f.style.minHeight=`${C}px`,this.effectiveGridHeight=`${$}px`)},100))}finally{this.isAdjustingHeight=!1}}}observeForHeightRetry(e){this.heightRetryObserver?.disconnect(),this.heightRetryObserver=new IntersectionObserver(t=>{if(!t.some(r=>r.isIntersecting))return;this.heightRetryObserver?.disconnect(),this.heightRetryObserver=null;let s=0;const o=()=>{this.pendingHeightRetry=!1,this.adjustInfiniteHeight(),this.pendingHeightRetry&&++s<5&&setTimeout(o,100)};requestAnimationFrame(()=>setTimeout(o,50))},{threshold:0}),this.heightRetryObserver.observe(e)}async sortOn(e){this.sortColumn===e?this.sortColumn.sortOrder=this.sortColumn.sortOrder=="asc"?"desc":"asc":(this.sortColumn=e,this.sortColumn.sortOrder="asc"),this.isInfiniteMode?await this.resetAndReload():this.sort()}sort(e={}){if(!this.sortColumn)return;const t=this.getCurrentSortField(),i=this.sortColumn.sortOrder==="asc"?1:-1,s=this.sortColumn.sortType,o=this.filteredItems.map((r,n)=>{const a=r[t]??"",l=s==="number"?Number(a):a.toString().toLowerCase();return{item:r,index:n,sortValue:l}});o.sort((r,n)=>r.sortValue<n.sortValue?-1*i:r.sortValue>n.sortValue?1*i:r.index-n.index),this.filteredItems=o.map(({item:r})=>r),this.setPage(e.pageNumber??1),(e.emitItemsChanged??!0)&&this.dispatchItemsChanged()}delete(e){if(this.isInfiniteMode){const t=this.allLoadedItems.filter(i=>!e(i));if(t.length===this.allLoadedItems.length)return;this.allLoadedItems=t,this.dispatchItemsChanged(),this.adjustInfiniteHeight()}else{const t=this.items.filter(i=>!e(i));if(t.length===this.items.length)return;this.items=t}}addOrReplace(e,t){if(this.isInfiniteMode){const i=this.allLoadedItems.findIndex(e);if(i>=0){const s=[...this.allLoadedItems];s[i]={...s[i],...t},this.allLoadedItems=s}else this.allLoadedItems=[...this.allLoadedItems,t];this.dispatchItemsChanged(),this.adjustInfiniteHeight()}else this.items.find(e)?this.items=this.items.map(s=>e(s)?{...s,...t}:s):this.items=[...this.items,t]}addInOrder(e,t,i){if(this.isInfiniteMode){const a=this.allLoadedItems.findIndex(e),l=[...this.allLoadedItems];if(a>=0)return l[a]={...l[a],...t},this.allLoadedItems=l,this.dispatchItemsChanged(),a;let g=0,v=l.length;for(;g<v;){const b=g+v>>>1;i(l[b],t)<0?g=b+1:v=b}return l.splice(g,0,t),this.allLoadedItems=l,this.dispatchItemsChanged(),this.adjustInfiniteHeight(),g}const s=this.items.findIndex(e),o=[...this.items];if(s>=0)return o[s]={...o[s],...t},this.items=o,s;let r=0,n=o.length;for(;r<n;){const a=r+n>>>1;i(o[a],t)<0?r=a+1:n=a}return o.splice(r,0,t),this.items=o,r}async scrollToIndex(e,t="center"){if(this.isInfiniteMode){await this.updateComplete;const i=this.virtualizerRef.value;if(!i)return;await i.updateComplete,await new Promise(s=>requestAnimationFrame(s)),await i.layoutComplete,i.scrollToIndex(e,t)}else{const i=Math.floor(e/this.pageSize)+1;this.setPage(i)}}clear(){if(this.isInfiniteMode){if(this.allLoadedItems.length===0&&this.nextCursor===null&&!this.hasMoreData)return;this.allLoadedItems=[],this.nextCursor=null,this.hasMoreData=!1,this.dispatchItemsChanged(),this.adjustInfiniteHeight()}else{if(this.items.length===0)return;this.items=[]}}async reload(){this.isInfiniteMode&&await this.resetAndReload()}computePinnedStyles(){return this.pinnedOffsets}measurePinnedOffsets(){this.pinnedOffsets=new Map,this.isInfiniteMode?this.computePinnedOffsetsFromWidths():this.measurePinnedOffsetsFromCells(),this.requestUpdate()}computePinnedOffsetsFromWidths(){const e=this.columnDefinitions.filter(r=>r.pin==="left"),t=this.columnDefinitions.filter(r=>r.pin==="right"),i=[];for(let r=0;r<e.length;r++){const n=e[r],a=i.length===0?"0px":`calc(${i.join(" + ")})`;this.pinnedOffsets.set(n,{position:"sticky",left:a,zIndex:`${e.length-r+1}`}),i.push(n.width||"0px")}const s=[],o=[...t].reverse();for(let r=0;r<o.length;r++){const n=o[r],a=s.length===0?"0px":`calc(${s.join(" + ")})`;this.pinnedOffsets.set(n,{position:"sticky",right:a,zIndex:`${o.length-r+1}`}),s.push(n.width||"0px")}}measurePinnedOffsetsFromCells(){const e=this.shadowRoot?.querySelectorAll("thead th");if(!e)return;const t=this.columnDefinitions.filter(a=>a.pin==="left"),i=this.columnDefinitions.filter(a=>a.pin==="right"),s=new Map;this.columnDefinitions.forEach((a,l)=>{e[l]&&s.set(a,e[l])});let o=0;for(let a=0;a<t.length;a++){const l=t[a];this.pinnedOffsets.set(l,{position:"sticky",left:`${o}px`,zIndex:`${t.length-a+1}`});const g=s.get(l);g&&(o+=g.offsetWidth)}let r=0;const n=[...i].reverse();for(let a=0;a<n.length;a++){const l=n[a];this.pinnedOffsets.set(l,{position:"sticky",right:`${r}px`,zIndex:`${n.length-a+1}`});const g=s.get(l);g&&(r+=g.offsetWidth)}}computeGridTemplateColumns(){return this.columnDefinitions.map(e=>e.width?e.grow?`minmax(${e.width}, 1fr)`:e.width:e.grow?"minmax(0, 1fr)":"auto").join(" ")}get hasGrowableColumns(){return this.columnDefinitions.some(e=>e.grow)}computePinnedColumnFlags(){const e=new Map,t=this.columnDefinitions.filter(r=>r.pin==="left"),i=this.columnDefinitions.filter(r=>r.pin==="right"),s=t[t.length-1],o=i[0];return this.columnDefinitions.forEach((r,n)=>{e.set(r,{beforePinnedRight:this.columnDefinitions[n+1]?.pin==="right",firstPinnedRight:o===r,lastPinnedLeft:s===r})}),e}renderCell(e,t){if(!e.fieldName)return c`<span></span>`;const i=e.textAlign??"left";return c`<span style="text-align: ${i};"> ${t[e.fieldName]} </span>`}attachWheelHandler(){const e=this.virtualizerRef.value;e&&!this.wheelHandlerAttached?(e.addEventListener("wheel",this.handleVirtualizerWheel,{passive:!1}),this.wheelHandlerAttached=!0):!e&&this.wheelHandlerAttached&&(this.wheelHandlerAttached=!1)}applySearchTerm(e){return this.searchTerm.length===0?e:e.filter(t=>{let i;return this.searchFields.length>0?i=this.searchFields.map(s=>t[s]):i=Object.values(t),i.some(s=>String(s).toLowerCase().includes(this.searchTerm))})}async firstUpdated(e){super.firstUpdated(e),this.headerButtonsSlot.value.assignedElements().length===0&&this.headerButtonsSlot.value.remove();for(const i of this.columnDefinitionsSlot.value.assignedElements())i.localName==="esp-grid-column"&&this.columnDefinitions.push(i);const t=this.columnDefinitions.find(i=>i.sortOrder!=="");t&&(this.sortColumn=t),this.isInfiniteMode?await this.loadPage(null).catch(()=>{}):this.dataUrl.length&&await this.loadDataUrl().catch(()=>{}),await this.updateComplete,this.measurePinnedOffsets()}updated(e){super.updated(e),this.isInfiniteMode&&this.attachWheelHandler()}async loadDataUrl(){this.dispatchGridDataEvent(L,this.createDataStateDetail({cursor:null,isFirstPage:!0}));try{const t=await fetch(this.dataUrl).then(i=>i.json());this.applyPagedItems(this.dataField?t[this.dataField]:t,{emitItemsChanged:!1}),this.dispatchGridDataEvent(M,this.createDataStateDetail({cursor:null,isFirstPage:!0})),this.dispatchItemsChanged({cursor:null,isFirstPage:!0})}catch(t){throw this.dispatchGridDataEvent(z,{...this.createDataStateDetail({cursor:null,isFirstPage:!0}),error:t}),t}}disconnectedCallback(){super.disconnectedCallback();const e=this.virtualizerRef.value;e&&e.removeEventListener("wheel",this.handleVirtualizerWheel),this.wheelHandlerAttached=!1,this.heightRetryObserver?.disconnect(),this.heightRetryObserver=null}renderSortIcons(){return c`
       <svg
         xmlns="http://www.w3.org/2000/svg"
         viewBox="0 0 24 24"
@@ -37,7 +37,7 @@ var h=function(I,e,t,i){var s=arguments.length,o=s<3?e:i===null?i=Object.getOwnP
       <slot ${y(this.columnDefinitionsSlot)}></slot>
 
       <div class="header-controls">
-        <esp-input fieldName="filter" @value-changed=${this.handleSearch}> ${G} </esp-input>
+        <esp-input fieldName="filter" @value-changed=${this.handleSearch}> ${N} </esp-input>
         <slot name="header-buttons" ${y(this.headerButtonsSlot)}></slot>
       </div>
 
@@ -79,7 +79,7 @@ var h=function(I,e,t,i){var s=arguments.length,o=s<3?e:i===null?i=Object.getOwnP
           .disabled=${!this.allowPrevious}
           @clicked=${i=>{this.setPage(this.pageNumber-1),i.stopPropagation()}}
         >
-          ${N}
+          ${T}
         </esp-button>
         <h4>${this.footerMessage}</h4>
         <esp-button
@@ -87,7 +87,7 @@ var h=function(I,e,t,i){var s=arguments.length,o=s<3?e:i===null?i=Object.getOwnP
           .disabled=${!this.allowNext}
           @clicked=${i=>{this.setPage(this.pageNumber+1),i.stopPropagation()}}
         >
-          ${T}
+          ${G}
         </esp-button>
       </div>
     `}renderInfiniteMode(e,t){const i=this.computeGridTemplateColumns(),s=this.hasGrowableColumns?"":"width: max-content; min-width: 100%;",o=(r,n)=>this.renderVirtualRow(r,n,e,t,i);return c`

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

@@ -144,6 +144,8 @@ type HeaderThemeToggle = "hidden" | "visible";
  * @cssprop --esp-header-height - The height of the header bar. Defaults to `calc(4.5 * var(--esp-size-small))`.
  * @cssprop --esp-header-color - The text/icon color inherited by header controls. Defaults to `var(--esp-color-text)`.
  * @cssprop --esp-header-z-index - The z-index of the header host. Defaults to `20`.
+ * @cssprop --esp-header-content-max-width - Surface-alignment contract set by `esp-page`: the maximum width the bar content is constrained to (the bar background stays full-bleed). Defaults to `100%` (no constraint). `esp-page` sets this to its resolved content cap.
+ * @cssprop --esp-header-content-lead - Surface-alignment contract set by `esp-page`: the fraction of the leftover width placed before the content, aligning it (`0` = start, `0.5` = center, `1` = end). Defaults to `0`.
  * @cssprop --esp-header-compact-height - The height of compact scroll-reactive headers. Defaults to `max(44px, calc(3.5 * var(--esp-size-small)))`.
  * @cssprop --esp-header-extended-menu-height - The second-row menu height for extended layouts. Defaults to `calc(3.5 * var(--esp-size-small))`.
  * @cssprop --esp-header-extended-menu-border - The border between the primary row and second-row menu in extended layouts. Defaults to `1px solid var(--esp-color-border)`.
@@ -306,6 +308,15 @@ export declare class EspalierHeader extends EspalierElementBase {
      * menu slotted into the header.
      */
     drawerTarget: string;
+    /**
+     * Opt out of surface alignment. When an `esp-header` is slotted into an
+     * `esp-page`, it constrains its bar content to the page's content
+     * surface by default (the bar background stays full-bleed). Set this to
+     * let the content span the full width instead, as it did before the
+     * page grew alignment modes. Standalone headers (outside `esp-page`) are
+     * already full-bleed and unaffected.
+     */
+    fullBleedContent: boolean;
     /**
      * The burger element inside the header. External code can use
      * this to programmatically reset the burger's visual state

package/dist/header/esp-header.js

@@ -1,7 +1,7 @@
-var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,t):o,i;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")a=Reflect.decorate(p,e,t,o);else for(var h=p.length-1;h>=0;h--)(i=p[h])&&(a=(s<3?i(a):s>3?i(e,t,a):i(e,t))||a);return s>3&&a&&Object.defineProperty(e,t,a),a};import{css as y,html as d,nothing as c}from"lit";import{customElement as x,property as l,state as u}from"lit/decorators.js";import{classMap as M}from"lit/directives/class-map.js";import{styleMap as S}from"lit/directives/style-map.js";import"../burger/esp-burger.js";import{createRef as b,ref as v}from"lit/directives/ref.js";import{EspalierMenu as T}from"./esp-menu.js";import{EspalierElementBase as f}from"../shared/esp-element-base.js";const D="(max-width: 36rem)";let r=class extends f{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="standard",this.brandText="",this.brandLogo="",this.brandHref="",this.brandAlt="",this.brandColor="",this.brandAlign="start",this.brandWrap="truncate",this.menuDisplay="auto",this.themeToggle="hidden",this.scrollBehavior="none",this.scrollThreshold=16,this.dockOffset=0,this.drawerTarget="",this.menuContainer=b(),this.menuButton=b(),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.updateScrollState=()=>{this.scrollRafId===null&&(this.scrollRafId=requestAnimationFrame(()=>{this.scrollRafId=null,this.runScrollStateUpdate()}))},this.handleMobileMenuQueryChange=e=>{this.mobileMenu=e.matches,this.syncMenuLayout()},this.toggleTheme=()=>{const e=this.getThemeRoot();e&&(e.scheme=e.scheme==="dark"?"light":"dark")},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(),a=this.menuDisplay!=="inline",i=this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal";this.menuTooLarge=a&&this.menuDisplay==="auto"&&o>e,this.menu.sliding=a&&!s&&(this.menuTooLarge||i||this.mobileMenu)}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,a=t>(e.has("dock")?s:o),i=t>this.lastScrollY,h=e.has("reveal")&&i&&t>o&&!this.menuOpen;if(this.scrolled=a,this.hiddenByScroll=h,e.has("progress")){const m=document.documentElement,g=Math.max(1,m.scrollHeight-window.innerHeight);this.scrollProgress=Math.min(1,t/g)}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)}syncMobileMenuQuery(){if("matchMedia"in window){if(!this.mobileMenuQuery){this.mobileMenuQuery=window.matchMedia(D),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=t,this.externalDrawerTarget?.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.addEventListener("drawer-closed",this.onMenuDrawerClosed))}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}firstUpdated(e){if(super.firstUpdated(e),!this.menuContainer.value)return;const s=(this.menuContainer.value.firstElementChild?.assignedElements()??[])[0];s instanceof T?(this.menu=s,this.addMenuDrawerListeners()):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("scrollBehavior")?this.syncScrollListeners():(e.has("scrollThreshold")||e.has("dockOffset"))&&this.updateScrollState()}connectedCallback(){super.connectedCallback(),this.syncScrollListeners(),this.syncMobileMenuQuery(),this.addMenuDrawerListeners(),this.syncExternalDrawerTarget(),this.observeMenuContainer()}disconnectedCallback(){this.removeMenuDrawerListeners(),this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget=null,this.mobileMenuQuery?.removeEventListener("change",this.handleMobileMenuQueryChange),this.mobileMenuQuery=null,this.removeScrollListeners(),this.cancelScrollUpdate(),this.disconnectResizeObserver(),super.disconnectedCallback()}renderConfiguredBrand(){if(!this.brandLogo&&!this.brandText)return c;const e=this.brandAlt||(this.brandText?"":"Site logo"),t=d`
+var n=function(p,e,t,a){var s=arguments.length,i=s<3?e:a===null?a=Object.getOwnPropertyDescriptor(e,t):a,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(p,e,t,a);else for(var h=p.length-1;h>=0;h--)(l=p[h])&&(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 y,html as d,nothing as c}from"lit";import{customElement as x,property as o,state as u}from"lit/decorators.js";import{classMap as M}from"lit/directives/class-map.js";import{styleMap as S}from"lit/directives/style-map.js";import"../burger/esp-burger.js";import{createRef as b,ref as f}from"lit/directives/ref.js";import{EspalierMenu as T}from"./esp-menu.js";import{EspalierElementBase as v}from"../shared/esp-element-base.js";const D="(max-width: 36rem)";let r=class extends v{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="standard",this.brandText="",this.brandLogo="",this.brandHref="",this.brandAlt="",this.brandColor="",this.brandAlign="start",this.brandWrap="truncate",this.menuDisplay="auto",this.themeToggle="hidden",this.scrollBehavior="none",this.scrollThreshold=16,this.dockOffset=0,this.drawerTarget="",this.fullBleedContent=!1,this.menuContainer=b(),this.menuButton=b(),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.updateScrollState=()=>{this.scrollRafId===null&&(this.scrollRafId=requestAnimationFrame(()=>{this.scrollRafId=null,this.runScrollStateUpdate()}))},this.handleMobileMenuQueryChange=e=>{this.mobileMenu=e.matches,this.syncMenuLayout()},this.toggleTheme=()=>{const e=this.getThemeRoot();e&&(e.scheme=e.scheme==="dark"?"light":"dark")},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 a=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"&&a>e,this.menu.sliding=i&&!s&&(this.menuTooLarge||l||this.mobileMenu)}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"),a=this.menuButton.value?.shadowRoot?.querySelector("button");return t??a??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),a=this.getEffectiveScrollThreshold(),s=Number.isFinite(this.dockOffset)?Math.max(0,this.dockOffset):a,i=t>(e.has("dock")?s:a),l=t>this.lastScrollY,h=e.has("reveal")&&l&&t>a&&!this.menuOpen;if(this.scrolled=i,this.hiddenByScroll=h,e.has("progress")){const m=document.documentElement,g=Math.max(1,m.scrollHeight-window.innerHeight);this.scrollProgress=Math.min(1,t/g)}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)}syncMobileMenuQuery(){if("matchMedia"in window){if(!this.mobileMenuQuery){this.mobileMenuQuery=window.matchMedia(D),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=t,this.externalDrawerTarget?.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.addEventListener("drawer-closed",this.onMenuDrawerClosed))}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}firstUpdated(e){if(super.firstUpdated(e),!this.menuContainer.value)return;const s=(this.menuContainer.value.firstElementChild?.assignedElements()??[])[0];s instanceof T?(this.menu=s,this.addMenuDrawerListeners()):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("scrollBehavior")?this.syncScrollListeners():(e.has("scrollThreshold")||e.has("dockOffset"))&&this.updateScrollState()}connectedCallback(){super.connectedCallback(),this.syncScrollListeners(),this.syncMobileMenuQuery(),this.addMenuDrawerListeners(),this.syncExternalDrawerTarget(),this.observeMenuContainer()}disconnectedCallback(){this.removeMenuDrawerListeners(),this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget=null,this.mobileMenuQuery?.removeEventListener("change",this.handleMobileMenuQueryChange),this.mobileMenuQuery=null,this.removeScrollListeners(),this.cancelScrollUpdate(),this.disconnectResizeObserver(),super.disconnectedCallback()}renderConfiguredBrand(){if(!this.brandLogo&&!this.brandText)return c;const e=this.brandAlt||(this.brandText?"":"Site logo"),t=d`
       ${this.brandLogo?d`<img class="brand-logo" src=${this.brandLogo} alt=${e} />`:c}
       ${this.brandText?d`<span class="brand-text">${this.brandText}</span>`:c}
-    `;return this.brandHref?d`<a class="configured-brand" href=${this.brandHref}>${t}</a>`:d`<span class="configured-brand">${t}</span>`}render(){const{menuOpen:e,menuTooLarge:t,mobileMenu:o}=this,s=this.menuDisplay!=="inline",a=s&&(this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal"),i=this.getScrollTokens(),h=i.has("progress"),m={"--_esp-header-brand-color":this.brandColor||null,"--_esp-header-scroll-progress":String(this.scrollProgress)},g={"menu-open":e,"too-wide":s&&(t||o||a),[`layout-${this.layout}`]:!0,"is-scrolled":this.scrolled,"hide-on-scroll":this.hiddenByScroll,"scroll-compact":i.has("compact"),"scroll-elevate":i.has("elevate"),"scroll-transparent":i.has("transparent")||i.has("transparent-to-solid"),"scroll-collapse-topbar":i.has("collapse-topbar")},w=this.scheme==="dark"?"light":"dark";return d`
+    `;return this.brandHref?d`<a class="configured-brand" href=${this.brandHref}>${t}</a>`:d`<span class="configured-brand">${t}</span>`}render(){const{menuOpen:e,menuTooLarge:t,mobileMenu:a}=this,s=this.menuDisplay!=="inline",i=s&&(this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal"),l=this.getScrollTokens(),h=l.has("progress"),m={"--_esp-header-brand-color":this.brandColor||null,"--_esp-header-scroll-progress":String(this.scrollProgress)},g={"menu-open":e,"too-wide":s&&(t||a||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")},w=this.scheme==="dark"?"light":"dark";return d`
       <header class=${M(g)} style=${S(m)}>
         <section class="topbar">
           <slot name="topbar"></slot>
@@ -11,7 +11,7 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
           <slot name="brand">${this.renderConfiguredBrand()}</slot>
         </section>
 
-        <section ${v(this.menuContainer)} class="menu-container">
+        <section ${f(this.menuContainer)} class="menu-container">
           <slot name="menu"></slot>
         </section>
 
@@ -31,12 +31,12 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
             aria-expanded=${e?"true":"false"}
             @clicked=${this.handleMenuToggleClicked}
           >
-            <esp-burger ${v(this.menuButton)} presentation-only></esp-burger>
+            <esp-burger ${f(this.menuButton)} presentation-only></esp-burger>
           </esp-header-button>
         </section>
         ${h?d`<div class="scroll-progress" aria-hidden="true"></div>`:c}
       </header>
-    `}};r.styles=[...f.styles,y`
+    `}};r.styles=[...v.styles,y`
       :host {
         --_esp-header-current-height: var(--esp-header-height, calc(4.5 * var(--esp-size-small)));
 
@@ -51,6 +51,14 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
           var(--esp-header-brand-color, var(--esp-color-headings))
         );
 
+        
+        --_esp-header-content-surplus: max(
+          0px,
+          calc(100% - var(--esp-header-content-max-width, 100%))
+        );
+        padding-inline: calc(var(--_esp-header-content-surplus) * var(--esp-header-content-lead, 0))
+          calc(var(--_esp-header-content-surplus) * (1 - var(--esp-header-content-lead, 0)));
+
         display: grid;
         grid-template-columns: minmax(0, max-content) minmax(0, 1fr) max-content;
         grid-template-rows: min-content var(--_esp-header-current-height);
@@ -349,6 +357,11 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
         }
       }
 
+      
+      :host([full-bleed-content]) header {
+        padding-inline: 0;
+      }
+
       :host([brand-align="center"]) header section.brand {
         justify-content: center;
         text-align: center;
@@ -418,4 +431,4 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
           transition: none;
         }
       }
-    `],n([u()],r.prototype,"menuOpen",void 0),n([u()],r.prototype,"menuTooLarge",void 0),n([u()],r.prototype,"mobileMenu",void 0),n([u()],r.prototype,"scrolled",void 0),n([u()],r.prototype,"hiddenByScroll",void 0),n([u()],r.prototype,"scrollProgress",void 0),n([l({attribute:"show-burger",type:Boolean})],r.prototype,"showBurger",void 0),n([l({type:String,reflect:!0})],r.prototype,"layout",void 0),n([l({attribute:"brand-text",type:String})],r.prototype,"brandText",void 0),n([l({attribute:"brand-logo",type:String})],r.prototype,"brandLogo",void 0),n([l({attribute:"brand-href",type:String})],r.prototype,"brandHref",void 0),n([l({attribute:"brand-alt",type:String})],r.prototype,"brandAlt",void 0),n([l({attribute:"brand-color",type:String})],r.prototype,"brandColor",void 0),n([l({attribute:"brand-align",type:String,reflect:!0})],r.prototype,"brandAlign",void 0),n([l({attribute:"brand-wrap",type:String,reflect:!0})],r.prototype,"brandWrap",void 0),n([l({attribute:"menu-display",type:String,reflect:!0})],r.prototype,"menuDisplay",void 0),n([l({attribute:"theme-toggle",type:String,reflect:!0})],r.prototype,"themeToggle",void 0),n([l({attribute:"scroll-behavior",type:String})],r.prototype,"scrollBehavior",void 0),n([l({attribute:"scroll-threshold",type:Number})],r.prototype,"scrollThreshold",void 0),n([l({attribute:"dock-offset",type:Number})],r.prototype,"dockOffset",void 0),n([l({attribute:"drawer-target",type:String})],r.prototype,"drawerTarget",void 0),r=n([x("esp-header")],r);export{r as EspalierHeader};
+    `],n([u()],r.prototype,"menuOpen",void 0),n([u()],r.prototype,"menuTooLarge",void 0),n([u()],r.prototype,"mobileMenu",void 0),n([u()],r.prototype,"scrolled",void 0),n([u()],r.prototype,"hiddenByScroll",void 0),n([u()],r.prototype,"scrollProgress",void 0),n([o({attribute:"show-burger",type:Boolean})],r.prototype,"showBurger",void 0),n([o({type:String,reflect:!0})],r.prototype,"layout",void 0),n([o({attribute:"brand-text",type:String})],r.prototype,"brandText",void 0),n([o({attribute:"brand-logo",type:String})],r.prototype,"brandLogo",void 0),n([o({attribute:"brand-href",type:String})],r.prototype,"brandHref",void 0),n([o({attribute:"brand-alt",type:String})],r.prototype,"brandAlt",void 0),n([o({attribute:"brand-color",type:String})],r.prototype,"brandColor",void 0),n([o({attribute:"brand-align",type:String,reflect:!0})],r.prototype,"brandAlign",void 0),n([o({attribute:"brand-wrap",type:String,reflect:!0})],r.prototype,"brandWrap",void 0),n([o({attribute:"menu-display",type:String,reflect:!0})],r.prototype,"menuDisplay",void 0),n([o({attribute:"theme-toggle",type:String,reflect:!0})],r.prototype,"themeToggle",void 0),n([o({attribute:"scroll-behavior",type:String})],r.prototype,"scrollBehavior",void 0),n([o({attribute:"scroll-threshold",type:Number})],r.prototype,"scrollThreshold",void 0),n([o({attribute:"dock-offset",type:Number})],r.prototype,"dockOffset",void 0),n([o({attribute:"drawer-target",type:String})],r.prototype,"drawerTarget",void 0),n([o({attribute:"full-bleed-content",type:Boolean,reflect:!0})],r.prototype,"fullBleedContent",void 0),r=n([x("esp-header")],r);export{r as EspalierHeader};

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

@@ -96,15 +96,33 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * </esp-page>
  * ```
  *
- * @cssprop --esp-page-background - The background color of the page.
- * Defaults to `var(--esp-color-background)`.
+ * @cssprop --esp-page-background - The background color of the page. Fills
+ * both the surface and the canvas gutters; the canvas tokens paint over it
+ * in the gutters only. Defaults to `var(--esp-color-background)`.
  * @cssprop --esp-page-max-width - The maximum width of the main content
  * well. Set automatically by the `kind` attribute: `1536px` (wide),
- * `768px` (narrow), or `none` (full).
+ * `768px` (narrow), or `none` (full). This cap now sizes the main grid
+ * track; surplus width beyond it becomes the canvas gutters.
  * @cssprop --esp-page-background-image - The background image to
  * display behind page content. Defaults to `none`.
  * @cssprop --esp-page-background-image-opacity - The opacity of the
  * background image layer. Defaults to `1`.
+ * @cssprop --esp-page-canvas-background - The background color of the
+ * canvas gutters (the outer regions revealed when the viewport exceeds
+ * the cap). Defaults to `transparent`, so gutters match the page until
+ * styled and narrow viewports are unaffected.
+ * @cssprop --esp-page-canvas-background-image - A background image for the
+ * canvas gutters, mirroring the page background-image knob. Defaults to
+ * `none`.
+ * @cssprop --esp-page-canvas-background-image-opacity - The opacity of the
+ * canvas gutter image layer. Defaults to `1`.
+ * @cssprop --esp-page-surface-shadow - The box shadow drawn on the left
+ * and right edges of the content surface. On by default; casts into the
+ * gutters and is clipped away when the surface fills the viewport, so it
+ * only shows above the cap. Set to `none` to remove it.
+ * @cssprop --esp-page-surface-border - An optional border on the inline
+ * edges of the surface, for themes preferring a hairline over a shadow.
+ * Defaults to `none` (e.g. `1px solid var(--esp-color-border)`).
  * @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.
@@ -112,6 +130,9 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * @cssprop --esp-page-header-z-index - Z-index for fixed/sticky header
  * regions. Defaults to `20`.
  *
+ * @csspart canvas - The two canvas gutter regions flanking the surface.
+ * @csspart surface - The surface backdrop carrying the edge shadow/border.
+ *
  * ```html
  * <style>
  * esp-page.with-background {
@@ -130,6 +151,29 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * </esp-page>
  * ```
  *
+ * Use `align` to place the surface within the page once it hits its cap,
+ * and the canvas tokens to style the gutters. A low `--esp-page-max-width`
+ * is set here only so the gutters are visible inside the narrow demo
+ * frame; the surface edge shadow is on by default.
+ *
+ * ```html
+ * <style>
+ * esp-page.align-demo {
+ *   --esp-page-max-width: 520px;
+ *   --esp-page-canvas-background: var(--esp-color-layer-1);
+ * }
+ * </style>
+ * <esp-page class="docs align-demo" align="center">
+ *   <div slot="header" style="background-color: red;">header</div>
+ *   <div slot="sidebar" style="background-color: green;">sidebar</div>
+ *   <div slot="right" style="background-color: purple;">right</div>
+ *   <div slot="footer" style="background-color: blue;">footer</div>
+ *   <div style="background-color: black; overflow: hidden;">
+ *     content
+ *   </div>
+ * </esp-page>
+ * ```
+ *
  * @docPageTitle Page
  * @docUrl /components/page
  * @menuGroup Structure
@@ -153,6 +197,38 @@ export declare class EspalierPage extends EspalierElementBase {
      *   maps or design tools.
      */
     kind: "wide" | "narrow" | "full";
+    /**
+     * Horizontal alignment of the content **surface** (left aside + main
+     * well + right aside) within the page once the viewport is wider than
+     * the content cap. The surplus width becomes styleable **canvas**
+     * gutters on the outer edges, weighted by this attribute.
+     *
+     * - `start` (default) — the surface hugs the leading edge; all spare
+     *   width collects in the trailing gutter. This reproduces today's
+     *   layout.
+     * - `center` — spare width is split evenly into both gutters, centering
+     *   the surface.
+     * - `end` — the surface hugs the trailing edge; spare width collects in
+     *   the leading gutter.
+     *
+     * Has no effect when `kind="full"` (no cap means no gutters) or on
+     * viewports narrower than the cap (the surface already fills the width).
+     */
+    align: "start" | "center" | "end";
+    /**
+     * When set, the header and footer sit **on** the content surface —
+     * the same width as the left aside + main well + right aside — instead
+     * of spanning the full viewport. Combined with a styled canvas this
+     * frames the whole page as one contained band floating on the canvas,
+     * with a single continuous surface edge shadow running from the header
+     * through the content to the footer.
+     *
+     * Below the cap there are no gutters, so a contained page renders
+     * identically to the default full-bleed chrome. Designed for
+     * `header-position="normal"` or `"sticky"`; a fixed header cannot be
+     * banded to the surface.
+     */
+    contained: boolean;
     /**
      * Header positioning behavior for the `header` slot.
      *

package/dist/page/esp-page.js

@@ -1,5 +1,8 @@
-var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,i):o,p;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")t=Reflect.decorate(s,e,i,o);else for(var d=s.length-1;d>=0;d--)(p=s[d])&&(t=(r<3?p(t):r>3?p(e,i,t):p(e,i))||t);return r>3&&t&&Object.defineProperty(e,i,t),t};import{css as c,html as f}from"lit";import{customElement as m,property as l}from"lit/decorators.js";import{classMap as u}from"lit/directives/class-map.js";import{createRef as v,ref as x}from"lit/directives/ref.js";import{EspalierElementBase as g}from"../shared/esp-element-base.js";import{BiDirectionalStickyController as h}from"./bi-directional-sticky-controller.js";import{getEspBus as y}from"../shared/bus-events.js";import"../toaster/esp-toaster.js";let a=class extends g{constructor(){super(),this.dialogZone=v(),this.kind="wide",this.headerPosition="normal",this.fixedMenus=!1,new h(this,".esp-page-left > .sticky-wrapper"),new h(this,".esp-page-right > .sticky-wrapper")}AddDialog(e){this.dialogZone.value?.appendChild(e)}updated(e){super.updated(e),(e.has("fixedMenus")||e.has("headerPosition"))&&y().publish("fixed-menus-changed",{fixed:this.fixedMenus||this.headerPosition==="fixed"})}render(){const e=this.fixedMenus||this.headerPosition==="fixed",i=!e&&this.headerPosition==="sticky";return f`
-      <div part="wrapper" class="esp-page ${u({"fixed-menus":e,"fixed-header":e,"sticky-header":i})}">
+var o=function(n,e,s,r){var d=arguments.length,a=d<3?e:r===null?r=Object.getOwnPropertyDescriptor(e,s):r,p;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")a=Reflect.decorate(n,e,s,r);else for(var l=n.length-1;l>=0;l--)(p=n[l])&&(a=(d<3?p(a):d>3?p(e,s,a):p(e,s))||a);return d>3&&a&&Object.defineProperty(e,s,a),a};import{css as g,html as f}from"lit";import{customElement as u,property as i}from"lit/decorators.js";import{classMap as m}from"lit/directives/class-map.js";import{createRef as v,ref as w}from"lit/directives/ref.js";import{EspalierElementBase as h}from"../shared/esp-element-base.js";import{BiDirectionalStickyController as c}from"./bi-directional-sticky-controller.js";import{getEspBus as b}from"../shared/bus-events.js";import"../toaster/esp-toaster.js";let t=class extends h{constructor(){super(),this.dialogZone=v(),this.kind="wide",this.align="start",this.contained=!1,this.headerPosition="normal",this.fixedMenus=!1,new c(this,".esp-page-left > .sticky-wrapper"),new c(this,".esp-page-right > .sticky-wrapper")}AddDialog(e){this.dialogZone.value?.appendChild(e)}updated(e){super.updated(e),(e.has("fixedMenus")||e.has("headerPosition"))&&b().publish("fixed-menus-changed",{fixed:this.fixedMenus||this.headerPosition==="fixed"})}render(){const e=this.fixedMenus||this.headerPosition==="fixed",s=!e&&this.headerPosition==="sticky";return f`
+      <div part="wrapper" class="esp-page ${m({"fixed-menus":e,"fixed-header":e,"sticky-header":s})}">
+        <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>
         </div>
@@ -19,12 +22,17 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
         <footer>
           <slot name="footer"></slot>
         </footer>
-        <div id="dialog-drop-zone" ${x(this.dialogZone)}></div>
+        <div id="dialog-drop-zone" ${w(this.dialogZone)}></div>
         <esp-toaster></esp-toaster>
       </div>
-    `}};a.styles=[...g.styles,c`
+    `}};t.styles=[...h.styles,g`
       :host {
         --_esp-page-resolved-max-width: var(--esp-page-max-width, 1536px);
+        
+        --_esp-page-main-track: minmax(0, var(--_esp-page-resolved-max-width));
+        
+        --_esp-page-gutter-left: 0;
+        --_esp-page-gutter-right: 1fr;
         --_esp-page-fixed-header-offset: var(
           --esp-page-fixed-header-offset,
           var(--esp-header-height, calc(4.5 * var(--esp-size-small)))
@@ -37,8 +45,53 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
         --_esp-page-resolved-max-width: var(--esp-page-max-width, 768px);
       }
 
+      :host([align="center"]) {
+        --_esp-page-gutter-left: 1fr;
+        --_esp-page-gutter-right: 1fr;
+      }
+
+      :host([align="end"]) {
+        --_esp-page-gutter-left: 1fr;
+        --_esp-page-gutter-right: 0;
+      }
+
+      
       :host([kind="full"]) {
         --_esp-page-resolved-max-width: var(--esp-page-max-width, none);
+        --_esp-page-main-track: 1fr;
+        --_esp-page-gutter-left: 0;
+        --_esp-page-gutter-right: 0;
+      }
+
+      
+      slot[name="header"]::slotted(esp-header) {
+        --esp-header-content-max-width: var(--_esp-page-resolved-max-width);
+        --esp-header-content-lead: 0;
+      }
+
+      :host([align="center"]) slot[name="header"]::slotted(esp-header) {
+        --esp-header-content-lead: 0.5;
+      }
+
+      :host([align="end"]) slot[name="header"]::slotted(esp-header) {
+        --esp-header-content-lead: 1;
+      }
+
+      
+      :host([kind="full"]) slot[name="header"]::slotted(esp-header) {
+        --esp-header-content-max-width: 100%;
+      }
+
+      
+      :host([contained]) .esp-page > div.esp-page-top,
+      :host([contained]) .esp-page > footer {
+        grid-column: surface;
+      }
+
+      
+      :host([contained]) slot[name="header"]::slotted(esp-header) {
+        --esp-header-content-max-width: 100%;
+        --esp-header-shadow: none;
       }
 
       :host([kind="narrow"]) .esp-page > div.esp-page-main {
@@ -57,10 +110,12 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
         min-height: 100vh;
         display: grid;
         grid-template-columns:
-          [full-start left-start] min-content
-          [left-end main-start] 1fr
+          [full-start canvas-left-start] var(--_esp-page-gutter-left)
+          [canvas-left-end surface-start left-start] min-content
+          [left-end main-start] var(--_esp-page-main-track)
           [main-end right-start] min-content
-          [right-end full-end];
+          [right-end surface-end canvas-right-start] var(--_esp-page-gutter-right)
+          [canvas-right-end full-end];
         grid-template-rows:
           [top-start] min-content
           [top-end content-start] 1fr
@@ -113,7 +168,7 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
           grid-row: content;
           position: relative;
           overflow: hidden;
-          max-width: var(--_esp-page-resolved-max-width);
+          
           contain: inline-size;
         }
 
@@ -122,6 +177,48 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
         }
 
         
+        > .esp-page-canvas {
+          
+          grid-row: top-start / footer-end;
+          z-index: 1;
+          position: relative;
+          pointer-events: none;
+          background-color: var(--esp-page-canvas-background, transparent);
+
+          
+          &::before {
+            content: "";
+            position: absolute;
+            inset: 0;
+            background-image: var(--esp-page-canvas-background-image, none);
+            opacity: var(--esp-page-canvas-background-image-opacity, 1);
+          }
+        }
+
+        > .esp-page-canvas--left {
+          grid-column: canvas-left;
+        }
+
+        > .esp-page-canvas--right {
+          grid-column: canvas-right;
+        }
+
+        
+        > .esp-page-surface {
+          grid-column: surface;
+          
+          grid-row: top-start / footer-end;
+          z-index: 2;
+          pointer-events: none;
+          box-shadow: var(
+            --esp-page-surface-shadow,
+            -0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow),
+            0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow)
+          );
+          border-inline: var(--esp-page-surface-border, none);
+        }
+
+        
         .sticky-wrapper {
           will-change: top;
           display: block;
@@ -166,7 +263,9 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
 
           > div.esp-page-main,
           > aside.esp-page-left,
-          > aside.esp-page-right {
+          > aside.esp-page-right,
+          > .esp-page-surface,
+          > .esp-page-canvas {
             margin-top: var(--_esp-page-fixed-header-offset);
           }
         }
@@ -194,4 +293,4 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
       .esp-page:has(esp-dialog[is-open="true"]) {
         overflow: hidden;
       }
-    `],n([l({reflect:!0})],a.prototype,"kind",void 0),n([l({attribute:"header-position",reflect:!0})],a.prototype,"headerPosition",void 0),n([l({attribute:"fixed-menus",type:Boolean,reflect:!0})],a.prototype,"fixedMenus",void 0),a=n([m("esp-page")],a);export{a as EspalierPage};
+    `],o([i({reflect:!0})],t.prototype,"kind",void 0),o([i({reflect:!0})],t.prototype,"align",void 0),o([i({type:Boolean,reflect:!0})],t.prototype,"contained",void 0),o([i({attribute:"header-position",reflect:!0})],t.prototype,"headerPosition",void 0),o([i({attribute:"fixed-menus",type:Boolean,reflect:!0})],t.prototype,"fixedMenus",void 0),t=o([u("esp-page")],t);export{t as EspalierPage};

package/espalier.token-manifest.json

@@ -842,6 +842,18 @@
       "component": "esp-header",
       "description": "The height of compact scroll-reactive headers. Defaults to `max(44px, calc(3.5 * var(--esp-size-small)))`."
     },
+    {
+      "name": "--esp-header-content-lead",
+      "category": "component",
+      "component": "esp-header",
+      "description": "Surface-alignment contract set by `esp-page`: the fraction of the leftover width placed before the content, aligning it (`0` = start, `0.5` = center, `1` = end). Defaults to `0`."
+    },
+    {
+      "name": "--esp-header-content-max-width",
+      "category": "component",
+      "component": "esp-header",
+      "description": "Surface-alignment contract set by `esp-page`: the maximum width the bar content is constrained to (the bar background stays full-bleed). Defaults to `100%` (no constraint). `esp-page` sets this to its resolved content cap."
+    },
     {
       "name": "--esp-header-extended-menu-border",
       "category": "component",
@@ -1219,7 +1231,7 @@
       "name": "--esp-page-background",
       "category": "component",
       "component": "esp-page",
-      "description": "The background color of the page. Defaults to `var(--esp-color-background)`."
+      "description": "The background color of the page. Fills both the surface and the canvas gutters; the canvas tokens paint over it in the gutters only. Defaults to `var(--esp-color-background)`."
     },
     {
       "name": "--esp-page-background-image",
@@ -1231,6 +1243,24 @@
       "category": "root-theme",
       "description": "The opacity of the background image layer. Defaults to `1`."
     },
+    {
+      "name": "--esp-page-canvas-background",
+      "category": "component",
+      "component": "esp-page",
+      "description": "The background color of the canvas gutters (the outer regions revealed when the viewport exceeds the cap). Defaults to `transparent`, so gutters match the page until styled and narrow viewports are unaffected."
+    },
+    {
+      "name": "--esp-page-canvas-background-image",
+      "category": "component",
+      "component": "esp-page",
+      "description": "A background image for the canvas gutters, mirroring the page background-image knob. Defaults to `none`."
+    },
+    {
+      "name": "--esp-page-canvas-background-image-opacity",
+      "category": "component",
+      "component": "esp-page",
+      "description": "The opacity of the canvas gutter image layer. Defaults to `1`."
+    },
     {
       "name": "--esp-page-fixed-header-offset",
       "category": "component",
@@ -1247,7 +1277,7 @@
       "name": "--esp-page-max-width",
       "category": "component",
       "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)."
+      "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-sticky-header-top",
@@ -1255,6 +1285,18 @@
       "component": "esp-page",
       "description": "Top inset for sticky headers. Defaults to `0`."
     },
+    {
+      "name": "--esp-page-surface-border",
+      "category": "component",
+      "component": "esp-page",
+      "description": "An optional border on the inline edges of the surface, for themes preferring a hairline over a shadow. Defaults to `none` (e.g. `1px solid var(--esp-color-border)`)."
+    },
+    {
+      "name": "--esp-page-surface-shadow",
+      "category": "component",
+      "component": "esp-page",
+      "description": "The box shadow drawn on the left and right edges of the content surface. On by default; casts into the gutters and is clipped away when the surface fills the viewport, so it only shows above the cap. Set to `none` to remove it."
+    },
     {
       "name": "--esp-progress-border-color",
       "category": "component",

package/licenses/ASSET_PROVENANCE.md

@@ -14,6 +14,8 @@ removing, or replacing non-code assets.
 | `dist/shared/virtualizer/**` | Vendored Lit Virtualizer runtime source compiled into Espalier's package. | `licenses/THIRD_PARTY_NOTICES.md` |
 | Brand favicons/logos | Taproot-owned Espalier brand assets. | None |
 | Demo textures | Taproot-owned generated PNG textures created for this repository. | None |
+| `assets/canvas-bg.jpg` | Docs-only light canvas texture — Envato Elements item "Seamless Pattern Design With Colorful Flowers" by yusufdemirci; certificate `licenses/license_certificate_A2BVZ6Y9DN.pdf`; attribution not required; kept out of the published `@taprootio/espalier` package. | None |
+| `assets/canvas-bg-dark.jpg` | Docs-only dark canvas texture — Envato Elements item "Nocturnal Garden Pattern" by Webvilla; certificate `licenses/license_certificate_HF5ZVPRNC2.pdf`; attribution not required; kept out of the published package. | None |
 | Demo JSON data | Taproot-authored fictitious samples or standards-derived factual color data. | None |
 
 ## Texture Replacement

package/licenses/asset-provenance.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "updatedAt": "2026-06-30",
+  "updatedAt": "2026-07-11",
   "entries": [
     {
       "id": "google-font-preview-assets",
@@ -211,6 +211,44 @@
       "noticeRequirement": "none",
       "noticePaths": [],
       "reviewStatus": "documented"
+    },
+    {
+      "id": "envato-canvas-background-texture",
+      "paths": [
+        "assets/canvas-bg.jpg"
+      ],
+      "assetType": "decorative floral background texture (JPEG, 400x400 seamless tile)",
+      "classification": "third-party licensed",
+      "owner": "Envato Elements author \"yusufdemirci\" retains ownership; licensed to Jereme Evans / Taproot under an Envato Elements subscription",
+      "source": "Envato Elements item \"Seamless Pattern Design With Colorful Flowers\" (item id ab0dc3dd-7d36-44be-9898-d148173189da, https://app.envato.com/item/ab0dc3dd-7d36-44be-9898-d148173189da), downloaded 2026-07-11 under an active subscription. License certificate A2BVZ6Y9DN on file at licenses/license_certificate_A2BVZ6Y9DN.pdf.",
+      "license": "Envato Elements subscription license (certificate A2BVZ6Y9DN): broad commercial use permitted and attribution is not required for this use. The author retains ownership; the item (or any product using it) may not be trademarked or claimed as Taproot-owned, and it must not be redistributed so that others can extract it. Valid only while the Envato subscription remains active.",
+      "transformations": [
+        "None; used as-is as a repeating docs-site canvas gutter background at 50% image-layer opacity"
+      ],
+      "packageInclusion": "not included in npm package",
+      "docsInclusion": "docs-site only — referenced as --esp-page-canvas-background-image in css/docs.css (which the public @taprootio/espalier package excludes) and served from the Eleventy /assets passthrough",
+      "noticeRequirement": "none",
+      "noticePaths": [],
+      "reviewStatus": "documented"
+    },
+    {
+      "id": "envato-canvas-background-texture-dark",
+      "paths": [
+        "assets/canvas-bg-dark.jpg"
+      ],
+      "assetType": "decorative dark botanical background texture (JPEG, 500x500 seamless tile)",
+      "classification": "third-party licensed",
+      "owner": "Envato Elements author \"Webvilla\" retains ownership; licensed to Jereme Evans / Taproot under an Envato Elements subscription",
+      "source": "Envato Elements item \"Nocturnal Garden Pattern\" (item id df520f04-5dfb-41c3-aa87-2ce3c03c8c34, https://app.envato.com/item/df520f04-5dfb-41c3-aa87-2ce3c03c8c34), downloaded 2026-07-11 under an active subscription as the dark-mode counterpart to canvas-bg.jpg. License certificate HF5ZVPRNC2 on file at licenses/license_certificate_HF5ZVPRNC2.pdf.",
+      "license": "Envato Elements subscription license (certificate HF5ZVPRNC2), same terms as canvas-bg.jpg: broad commercial use permitted and attribution not required; author retains ownership, no trademark/ownership claims, no redistribution for extraction, valid only while the subscription is active.",
+      "transformations": [
+        "None; used as-is as a repeating docs-site dark-mode canvas gutter background at 50% image-layer opacity"
+      ],
+      "packageInclusion": "not included in npm package",
+      "docsInclusion": "docs-site only — referenced as --esp-page-canvas-background-image under esp-root[scheme=\"dark\"] in css/docs.css (excluded from the public @taprootio/espalier package) and served from the Eleventy /assets passthrough",
+      "noticeRequirement": "none",
+      "noticePaths": [],
+      "reviewStatus": "documented"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Espalier — a themeable, accessible, framework-agnostic, enterprise-grade design system built on web standards and love.",
   "customElements": "custom-elements.json",
   "type": "module",