@taprootio/espalier 2.4.0 → 2.6.0

package/dist/footer/esp-footer-column.d.ts

@@ -0,0 +1,47 @@
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+/**
+ * A layout-only column for creator-controlled link-group stacking inside
+ * [`<esp-footer>`](/components/footer/).
+ *
+ * Use bare `esp-footer-link-group` children when groups should auto-flow
+ * independently through the footer grid. Wrap ordered groups in
+ * `esp-footer-column` when they must remain together as one grid item:
+ *
+ * ```html
+ * <esp-footer columns="3">
+ *   <esp-footer-column>
+ *     <esp-footer-link-group heading="Product">
+ *       <a href="/features">Features</a>
+ *       <a href="/pricing">Pricing</a>
+ *     </esp-footer-link-group>
+ *     <esp-footer-link-group heading="Company">
+ *       <a href="/about">About</a>
+ *       <a href="/careers">Careers</a>
+ *     </esp-footer-link-group>
+ *   </esp-footer-column>
+ * </esp-footer>
+ * ```
+ *
+ * The component adds no heading, landmark, or chrome. It preserves the
+ * slotted order of its child groups and uses `--esp-footer-row-gap`, defaulting
+ * to `var(--esp-size-big)`, for its vertical rhythm.
+ *
+ * @customElement esp-footer-column
+ * @slot - Ordered `esp-footer-link-group` children belonging to this column.
+ * @cssprop --esp-footer-row-gap - Vertical gap between footer grid rows and
+ * link groups stacked in `esp-footer-column`. Defaults to `var(--esp-size-big)`.
+ * @docPageTitle Footer Column
+ * @docUrl /components/footer/column
+ * @menuGroup Structure
+ * @menuLabel Footer Column
+ * @menuIcon columns
+ */
+export declare class EspalierFooterColumn extends EspalierElementBase {
+    protected render(): import("lit-html").TemplateResult<1>;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-footer-column": EspalierFooterColumn;
+    }
+}

package/dist/footer/esp-footer-column.js

@@ -0,0 +1,8 @@
+var m=function(r,o,t,l){var n=arguments.length,e=n<3?o:l===null?l=Object.getOwnPropertyDescriptor(o,t):l,s;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")e=Reflect.decorate(r,o,t,l);else for(var f=r.length-1;f>=0;f--)(s=r[f])&&(e=(n<3?s(e):n>3?s(o,t,e):s(o,t))||e);return n>3&&e&&Object.defineProperty(o,t,e),e};import{css as c,html as a}from"lit";import{customElement as u}from"lit/decorators.js";import{EspalierElementBase as p}from"../shared/esp-element-base.js";let i=class extends p{render(){return a`<slot></slot>`}};i.styles=[...p.styles,c`
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--esp-footer-row-gap, var(--esp-size-big));
+        min-inline-size: 0;
+      }
+    `],i=m([u("esp-footer-column")],i);export{i as EspalierFooterColumn};

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

@@ -1,5 +1,6 @@
 import { type PropertyValues } from "lit";
 import { EspalierElementBase } from "../shared/esp-element-base.js";
+import "./esp-footer-column.js";
 import "./esp-footer-link-group.js";
 export type FooterColumns = "auto" | "1" | "2" | "3" | "4" | "5" | "6";
 /**
@@ -8,16 +9,19 @@ export type FooterColumns = "auto" | "1" | "2" | "3" | "4" | "5" | "6";
  * Its background remains full-bleed while its content automatically aligns
  * to the surface of a containing [`<esp-page>`](/components/page/).
  *
- * Use [`<esp-footer-link-group>`](/components/footer/link-group/) children for
- * ordinary navigation columns. `columns` is a maximum: the grid always drops
- * columns when they no longer fit.
+ * Use bare [`<esp-footer-link-group>`](/components/footer/link-group/) children
+ * when navigation groups should auto-flow independently through the grid.
+ * `columns` is a maximum: the grid always drops columns when they no longer fit.
  *
  * ```html
  * <esp-footer
- *   brand-logo="/assets/favicon.svg"
+ *   light-brand-logo="/assets/logo-light.svg"
+ *   dark-brand-logo="/assets/logo-dark.svg"
  *   brand-text="Espalier"
  *   brand-href="/"
  *   brand-alt="Espalier logo"
+ *   light-brand-color="oklch(0.35 0.12 216)"
+ *   dark-brand-color="oklch(0.9 0.08 216)"
  *   columns="3">
  *   <esp-footer-link-group heading="Explore">
  *     <a href="/components">Components</a>
@@ -32,6 +36,33 @@ export type FooterColumns = "auto" | "1" | "2" | "3" | "4" | "5" | "6";
  * </esp-footer>
  * ```
  *
+ * For creator-controlled columns, wrap each ordered stack of groups in
+ * [`<esp-footer-column>`](/components/footer/column/). Each wrapper is one grid
+ * item at wide sizes; below the footer's compact container breakpoint, the
+ * columns become full-width rows in their slotted order. `columns` remains the
+ * maximum number of grid items per row:
+ *
+ * ```html
+ * <esp-footer columns="3">
+ *   <esp-footer-column>
+ *     <esp-footer-link-group heading="Product">
+ *       <a href="/features">Features</a>
+ *       <a href="/pricing">Pricing</a>
+ *     </esp-footer-link-group>
+ *     <esp-footer-link-group heading="Company">
+ *       <a href="/about">About</a>
+ *       <a href="/careers">Careers</a>
+ *     </esp-footer-link-group>
+ *   </esp-footer-column>
+ *   <esp-footer-column>
+ *     <esp-footer-link-group heading="Resources">
+ *       <a href="/docs">Documentation</a>
+ *       <a href="/support">Support</a>
+ *     </esp-footer-link-group>
+ *   </esp-footer-column>
+ * </esp-footer>
+ * ```
+ *
  * A slotted brand replaces configured branding, while the media slot accepts
  * a responsive `picture`, native image, or `esp-image`. Media spans the
  * surface-aligned content well; use the decorative background layer for
@@ -109,7 +140,8 @@ export type FooterColumns = "auto" | "1" | "2" | "3" | "4" | "5" | "6";
  * preferably responsive `<picture>` markup or an `esp-image` with appropriate
  * alternative text.
  * @slot brand - Custom brand identity. Overrides configured brand properties.
- * @slot - `esp-footer-link-group` navigation columns.
+ * @slot - Bare `esp-footer-link-group` children for automatic flow, or
+ * `esp-footer-column` children for creator-controlled group stacks.
  * @slot aside - Supporting content such as a newsletter, call to action,
  * contact details, social links, or locale controls.
  * @slot bottom - Copyright, legal/utility links, attribution, accessibility
@@ -134,7 +166,8 @@ export type FooterColumns = "auto" | "1" | "2" | "3" | "4" | "5" | "6";
  * @cssprop --esp-footer-padding-inline - Content inline padding. Defaults to `var(--esp-size-padding-page)`.
  * @cssprop --esp-footer-section-gap - Gap between media, primary, and bottom regions. Defaults to `var(--esp-size-big)`.
  * @cssprop --esp-footer-column-gap - Gap between link-group columns and major primary regions. Defaults to `var(--esp-size-padding-page)`.
- * @cssprop --esp-footer-row-gap - Compact-layout row gap. Defaults to `var(--esp-size-big)`.
+ * @cssprop --esp-footer-row-gap - Vertical gap between footer grid rows and
+ * link groups stacked in `esp-footer-column`. Defaults to `var(--esp-size-big)`.
  * @cssprop --esp-footer-link-group-min-width - Intrinsic minimum link-group column width. Defaults to `10rem`.
  * @cssprop --esp-footer-link-group-gap - Space between a link-group heading and its links. Defaults to `var(--esp-size-small)`.
  * @cssprop --esp-footer-brand-logo-size - Configured logo block size. Defaults to `3rem`.
@@ -158,10 +191,38 @@ export declare class EspalierFooter extends EspalierElementBase {
     brandText: string;
     /** Configured brand logo URL used when the `brand` slot is empty. */
     brandLogo: string;
+    /**
+     * Configured brand logo URL used in light scheme. A non-empty value
+     * overrides `brand-logo`; an empty value falls back to it.
+     */
+    lightBrandLogo: string;
+    /**
+     * Configured brand logo URL used in dark scheme. A non-empty value
+     * overrides `brand-logo`; an empty value falls back to it.
+     */
+    darkBrandLogo: string;
     /** Optional configured-brand link target. */
     brandHref: string;
     /** Accessible text for a configured logo. */
     brandAlt: string;
+    /**
+     * Optional configured brand color. Scheme-specific colors override it;
+     * when all configured colors are empty, `--esp-footer-heading-color`
+     * remains the fallback.
+     */
+    brandColor: string;
+    /**
+     * Configured brand color used in light scheme. A non-empty value
+     * overrides `brand-color`; an empty value falls back to it and then
+     * `--esp-footer-heading-color`.
+     */
+    lightBrandColor: string;
+    /**
+     * Configured brand color used in dark scheme. A non-empty value
+     * overrides `brand-color`; an empty value falls back to it and then
+     * `--esp-footer-heading-color`.
+     */
+    darkBrandColor: string;
     /**
      * Maximum number of link-group columns. Numeric values cap the wide layout;
      * the intrinsic grid still renders fewer columns when space is limited.

package/dist/footer/esp-footer.js

@@ -1,16 +1,20 @@
-var i=function(s,e,r,a){var o=arguments.length,n=o<3?e:a===null?a=Object.getOwnPropertyDescriptor(e,r):a,d;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")n=Reflect.decorate(s,e,r,a);else for(var l=s.length-1;l>=0;l--)(d=s[l])&&(n=(o<3?d(n):o>3?d(e,r,n):d(e,r))||n);return o>3&&n&&Object.defineProperty(e,r,n),n};import{css as b,html as f,nothing as v}from"lit";import{customElement as y,property as p,state as x}from"lit/decorators.js";import{classMap as _}from"lit/directives/class-map.js";import{renderConfiguredBrand as z}from"../shared/configured-brand.js";import{EspalierElementBase as g}from"../shared/esp-element-base.js";import{slotHasContent as c}from"../shared/slot-content.js";import"./esp-footer-link-group.js";const m=new Set(["auto","1","2","3","4","5","6"]),u={media:!1,brand:!1,groups:!1,aside:!1,bottom:!1},k={fromAttribute(s){return s&&m.has(s)?s:"auto"},toAttribute(s){return m.has(s)?s:"auto"}};let t=class extends g{constructor(){super(...arguments),this.slotContent={...u},this.brandText="",this.brandLogo="",this.brandHref="",this.brandAlt="",this.columns="auto",this.fullBleedContent=!1,this.landmarkLabel="",this.handleSlotChange=e=>{if(!(e.target instanceof HTMLSlotElement))return;const r=this.slotRegion(e.target);if(!r)return;const a=c(e.target);this.slotContent[r]!==a&&(this.slotContent={...this.slotContent,[r]:a})}}willUpdate(e){super.willUpdate(e),e.has("columns")&&!m.has(this.columns)&&(this.columns="auto")}slotRegion(e){return e.name?["media","brand","aside","bottom"].includes(e.name)?e.name:null:"groups"}firstUpdated(e){super.firstUpdated(e);const r={...u};for(const a of this.shadowRoot?.querySelectorAll("slot")??[]){const o=this.slotRegion(a);o&&(r[o]=c(a))}Object.entries(r).some(([a,o])=>this.slotContent[a]!==o)&&(this.slotContent=r)}render(){const{media:e,brand:r,groups:a,aside:o,bottom:n}=this.slotContent,d=r||!!(this.brandLogo||this.brandText),l=d||a||o,h={primary:!0,"has-brand":d,"has-groups":a,"has-aside":o};return f`
-      <footer part="footer" aria-label=${this.landmarkLabel||v}>
+var t=function(i,o,e,a){var s=arguments.length,d=s<3?o:a===null?a=Object.getOwnPropertyDescriptor(o,e):a,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")d=Reflect.decorate(i,o,e,a);else for(var p=i.length-1;p>=0;p--)(l=i[p])&&(d=(s<3?l(d):s>3?l(o,e,d):l(o,e))||d);return s>3&&d&&Object.defineProperty(o,e,d),d};import{css as f,html as v,nothing as y}from"lit";import{customElement as x,property as n,state as C}from"lit/decorators.js";import{classMap as k}from"lit/directives/class-map.js";import{styleMap as _}from"lit/directives/style-map.js";import{renderConfiguredBrand as z,resolveConfiguredBrand as B}from"../shared/configured-brand.js";import{EspalierElementBase as g}from"../shared/esp-element-base.js";import{slotHasContent as c}from"../shared/slot-content.js";import"./esp-footer-column.js";import"./esp-footer-link-group.js";const m=new Set(["auto","1","2","3","4","5","6"]),h={media:!1,brand:!1,groups:!1,aside:!1,bottom:!1},S={fromAttribute(i){return i&&m.has(i)?i:"auto"},toAttribute(i){return m.has(i)?i:"auto"}};let r=class extends g{constructor(){super(...arguments),this.slotContent={...h},this.brandText="",this.brandLogo="",this.lightBrandLogo="",this.darkBrandLogo="",this.brandHref="",this.brandAlt="",this.brandColor="",this.lightBrandColor="",this.darkBrandColor="",this.columns="auto",this.fullBleedContent=!1,this.landmarkLabel="",this.handleSlotChange=o=>{if(!(o.target instanceof HTMLSlotElement))return;const e=this.slotRegion(o.target);if(!e)return;const a=c(o.target);this.slotContent[e]!==a&&(this.slotContent={...this.slotContent,[e]:a})}}willUpdate(o){super.willUpdate(o),o.has("columns")&&!m.has(this.columns)&&(this.columns="auto")}slotRegion(o){return o.name?["media","brand","aside","bottom"].includes(o.name)?o.name:null:"groups"}firstUpdated(o){super.firstUpdated(o);const e={...h};for(const a of this.shadowRoot?.querySelectorAll("slot")??[]){const s=this.slotRegion(a);s&&(e[s]=c(a))}Object.entries(e).some(([a,s])=>this.slotContent[a]!==s)&&(this.slotContent=e)}render(){const{media:o,brand:e,groups:a,aside:s,bottom:d}=this.slotContent,l=B({scheme:this.scheme,brandLogo:this.brandLogo,brandColor:this.brandColor,lightBrandLogo:this.lightBrandLogo,darkBrandLogo:this.darkBrandLogo,lightBrandColor:this.lightBrandColor,darkBrandColor:this.darkBrandColor}),p=e||!!(l.brandLogo||this.brandText),u=p||a||s,b={primary:!0,"has-brand":p,"has-groups":a,"has-aside":s};return v`
+      <footer
+        part="footer"
+        aria-label=${this.landmarkLabel||y}
+        style=${_({"--_esp-footer-brand-color":l.brandColor||null})}
+      >
         <div part="background" class="background" aria-hidden="true"></div>
         <div part="content" class="content-frame">
           <div class="content">
-            <div part="media" class="media" ?hidden=${!e}>
+            <div part="media" class="media" ?hidden=${!o}>
               <slot name="media" @slotchange=${this.handleSlotChange}></slot>
             </div>
 
-            <div part="primary" class=${_(h)} ?hidden=${!l}>
-              <div part="brand" class="brand" ?hidden=${!d}>
+            <div part="primary" class=${k(b)} ?hidden=${!u}>
+              <div part="brand" class="brand" ?hidden=${!p}>
                 <slot name="brand" @slotchange=${this.handleSlotChange}
-                  >${z({brandLogo:this.brandLogo,brandText:this.brandText,brandHref:this.brandHref,brandAlt:this.brandAlt})}</slot
+                  >${z({brandLogo:l.brandLogo,brandText:this.brandText,brandHref:this.brandHref,brandAlt:this.brandAlt})}</slot
                 >
               </div>
 
@@ -18,18 +22,18 @@ var i=function(s,e,r,a){var o=arguments.length,n=o<3?e:a===null?a=Object.getOwnP
                 <slot @slotchange=${this.handleSlotChange}></slot>
               </div>
 
-              <div part="aside" class="aside" ?hidden=${!o}>
+              <div part="aside" class="aside" ?hidden=${!s}>
                 <slot name="aside" @slotchange=${this.handleSlotChange}></slot>
               </div>
             </div>
 
-            <div part="bottom" class="bottom" ?hidden=${!n}>
+            <div part="bottom" class="bottom" ?hidden=${!d}>
               <slot name="bottom" @slotchange=${this.handleSlotChange}></slot>
             </div>
           </div>
         </div>
       </footer>
-    `}};t.styles=[...g.styles,b`
+    `}};r.styles=[...g.styles,f`
       :host {
         display: block;
         min-inline-size: 0;
@@ -216,7 +220,10 @@ var i=function(s,e,r,a){var o=arguments.length,n=o<3?e:a===null?a=Object.getOwnP
         align-items: center;
         gap: var(--esp-size-small);
         max-inline-size: 100%;
-        color: var(--esp-footer-heading-color, var(--esp-color-headings));
+        color: var(
+          --_esp-footer-brand-color,
+          var(--esp-footer-heading-color, var(--esp-color-headings))
+        );
         font-family: var(--esp-font-brand, var(--esp-font-headings));
         font-size: var(--esp-type-medium);
         font-weight: var(--esp-font-weight-brand, var(--esp-font-weight-headings));
@@ -250,6 +257,10 @@ var i=function(s,e,r,a){var o=arguments.length,n=o<3?e:a===null?a=Object.getOwnP
       }
 
       @container esp-footer (max-width: 48rem) {
+        .groups ::slotted(esp-footer-column) {
+          grid-column: 1 / -1;
+        }
+
         .primary,
         .primary.has-brand.has-groups:not(.has-aside),
         .primary.has-groups.has-aside:not(.has-brand),
@@ -297,4 +308,4 @@ var i=function(s,e,r,a){var o=arguments.length,n=o<3?e:a===null?a=Object.getOwnP
           grid-template-areas: "aside";
         }
       }
-    `],i([x()],t.prototype,"slotContent",void 0),i([p({attribute:"brand-text",type:String})],t.prototype,"brandText",void 0),i([p({attribute:"brand-logo",type:String})],t.prototype,"brandLogo",void 0),i([p({attribute:"brand-href",type:String})],t.prototype,"brandHref",void 0),i([p({attribute:"brand-alt",type:String})],t.prototype,"brandAlt",void 0),i([p({converter:k,reflect:!0})],t.prototype,"columns",void 0),i([p({attribute:"full-bleed-content",type:Boolean,reflect:!0})],t.prototype,"fullBleedContent",void 0),i([p({attribute:"landmark-label",type:String})],t.prototype,"landmarkLabel",void 0),t=i([y("esp-footer")],t);export{t as EspalierFooter};
+    `],t([C()],r.prototype,"slotContent",void 0),t([n({attribute:"brand-text",type:String})],r.prototype,"brandText",void 0),t([n({attribute:"brand-logo",type:String})],r.prototype,"brandLogo",void 0),t([n({attribute:"light-brand-logo",type:String})],r.prototype,"lightBrandLogo",void 0),t([n({attribute:"dark-brand-logo",type:String})],r.prototype,"darkBrandLogo",void 0),t([n({attribute:"brand-href",type:String})],r.prototype,"brandHref",void 0),t([n({attribute:"brand-alt",type:String})],r.prototype,"brandAlt",void 0),t([n({attribute:"brand-color",type:String})],r.prototype,"brandColor",void 0),t([n({attribute:"light-brand-color",type:String})],r.prototype,"lightBrandColor",void 0),t([n({attribute:"dark-brand-color",type:String})],r.prototype,"darkBrandColor",void 0),t([n({converter:S,reflect:!0})],r.prototype,"columns",void 0),t([n({attribute:"full-bleed-content",type:Boolean,reflect:!0})],r.prototype,"fullBleedContent",void 0),t([n({attribute:"landmark-label",type:String})],r.prototype,"landmarkLabel",void 0),r=t([x("esp-footer")],r);export{r as EspalierFooter};

package/dist/footer/index.d.ts

@@ -1,2 +1,3 @@
+export * from "./esp-footer-column.js";
 export * from "./esp-footer-link-group.js";
 export * from "./esp-footer.js";

package/dist/footer/index.js

@@ -1 +1 @@
-export*from"./esp-footer-link-group.js";export*from"./esp-footer.js";
+export*from"./esp-footer-column.js";export*from"./esp-footer-link-group.js";export*from"./esp-footer.js";

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

@@ -2,11 +2,19 @@ import { type PropertyValues } from "lit";
 import "../burger/esp-burger.js";
 import { type EspalierBurger } from "../burger/esp-burger.js";
 import { EspalierElementBase } from "../shared/esp-element-base.js";
-type HeaderLayout = "standard" | "centered-brand" | "extended" | "extended-centered" | "minimal";
-type HeaderBrandAlign = "start" | "center" | "end";
-type HeaderBrandWrap = "truncate" | "wrap" | "nowrap";
-type HeaderMenuDisplay = "auto" | "inline" | "drawer";
-type HeaderThemeToggle = "hidden" | "visible";
+declare const HEADER_LAYOUT_VALUES: readonly ["standard", "centered-brand", "extended", "extended-centered", "minimal"];
+declare const HEADER_BRAND_ALIGN_VALUES: readonly ["start", "center", "end"];
+declare const HEADER_BRAND_WRAP_VALUES: readonly ["truncate", "wrap", "nowrap"];
+declare const HEADER_MENU_DISPLAY_VALUES: readonly ["auto", "inline", "drawer"];
+declare const HEADER_THEME_TOGGLE_VALUES: readonly ["hidden", "visible"];
+export type HeaderLayout = (typeof HEADER_LAYOUT_VALUES)[number];
+export type HeaderBrandAlign = (typeof HEADER_BRAND_ALIGN_VALUES)[number];
+export type HeaderBrandWrap = (typeof HEADER_BRAND_WRAP_VALUES)[number];
+export type HeaderMenuDisplay = (typeof HEADER_MENU_DISPLAY_VALUES)[number];
+export type HeaderThemeToggle = (typeof HEADER_THEME_TOGGLE_VALUES)[number];
+export interface EspThemeToggleEventDetail {
+    scheme: "light" | "dark";
+}
 /**
  * Used to build the top navigation for a site. An empty header
  * displays a bar. It has three slots for populating header content:
@@ -104,10 +112,13 @@ type HeaderThemeToggle = "hidden" | "visible";
  *   <esp-header
  *     slot="header"
  *     layout="centered-brand"
- *     brand-logo="/assets/favicon.svg"
+ *     light-brand-logo="/assets/logo-light.svg"
+ *     dark-brand-logo="/assets/logo-dark.svg"
  *     brand-text="Espalier"
  *     brand-href="/"
  *     brand-alt="Espalier logo"
+ *     light-brand-color="oklch(0.35 0.12 216)"
+ *     dark-brand-color="oklch(0.9 0.08 216)"
  *     brand-align="center"
  *     menu-display="auto"
  *     theme-toggle="visible"
@@ -137,6 +148,19 @@ type HeaderThemeToggle = "hidden" | "visible";
  * </esp-header>
  * ```
  *
+ * The built-in theme toggle emits `esp-theme-toggle` only for a visitor
+ * activation, so a host can persist explicit choices without treating
+ * automatic scheme resolution as intent:
+ *
+ * ```js
+ * const root = document.querySelector("esp-root");
+ * root.addEventListener("esp-theme-toggle", (event) => {
+ *   localStorage.setItem("scheme", event.detail.scheme);
+ * });
+ * ```
+ *
+ * @event {CustomEvent<EspThemeToggleEventDetail>} esp-theme-toggle - Fired after the built-in theme toggle changes the nearest `esp-root`. Bubbles and crosses the shadow boundary.
+ *
  * @cssprop --esp-header-background - The background color of the header bar. Defaults to `var(--esp-color-layer-2)`.
  * @cssprop --esp-header-border-width - The border width of the header. Defaults to `0 0 1px 0`.
  * @cssprop --esp-header-border - The border style of the header. Defaults to `solid var(--esp-color-border)`.
@@ -240,6 +264,8 @@ export declare class EspalierHeader extends EspalierElementBase {
      *   picker.addEventListener("value-changed", applyLayout);
      * </script>
      * ```
+     *
+     * @default "standard"
      */
     layout: HeaderLayout;
     /**
@@ -250,6 +276,16 @@ export declare class EspalierHeader extends EspalierElementBase {
      * Configured brand logo URL used when the `brand` slot is empty.
      */
     brandLogo: string;
+    /**
+     * Configured brand logo URL used in light scheme. A non-empty value
+     * overrides `brand-logo`; an empty value falls back to it.
+     */
+    lightBrandLogo: string;
+    /**
+     * Configured brand logo URL used in dark scheme. A non-empty value
+     * overrides `brand-logo`; an empty value falls back to it.
+     */
+    darkBrandLogo: string;
     /**
      * Optional brand link used by configured logo/text branding.
      */
@@ -265,24 +301,40 @@ export declare class EspalierHeader extends EspalierElementBase {
      * header override.
      */
     brandColor: string;
+    /**
+     * Configured brand color used in light scheme. A non-empty value
+     * overrides `brand-color`; an empty value falls back to it and then
+     * `--esp-header-brand-color`.
+     */
+    lightBrandColor: string;
+    /**
+     * Configured brand color used in dark scheme. A non-empty value
+     * overrides `brand-color`; an empty value falls back to it and then
+     * `--esp-header-brand-color`.
+     */
+    darkBrandColor: string;
     /**
      * Horizontal placement of the brand content inside its grid area.
+     * @default "start"
      */
     brandAlign: HeaderBrandAlign;
     /**
      * Long-brand behavior for configured brand text.
+     * @default "truncate"
      */
     brandWrap: HeaderBrandWrap;
     /**
      * Navigation display intent. `auto` tries inline navigation before
      * using a drawer, `drawer` always uses the burger/drawer pattern,
      * and `inline` leaves overflow handling to the slotted menu.
+     * @default "auto"
      */
     menuDisplay: HeaderMenuDisplay;
     /**
      * Whether the header renders its built-in light/dark toggle.
      * Consumers can still provide their own control in the `buttons`
      * slot when this is `hidden`.
+     * @default "hidden"
      */
     themeToggle: HeaderThemeToggle;
     /**
@@ -323,6 +375,7 @@ export declare class EspalierHeader extends EspalierElementBase {
      * (e.g. when a drawer is closed via swipe).
      */
     get burger(): EspalierBurger | undefined;
+    protected willUpdate(changedProperties: PropertyValues): void;
     protected firstUpdated(props: PropertyValues): void;
     protected updated(changedProperties: PropertyValues): void;
     connectedCallback(): void;

package/dist/header/esp-header.js

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

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

@@ -1,7 +1,8 @@
 import { LitElement, type PropertyValues } from "lit";
-import { type SeedColorRoot } from "../shared/bus-events.js";
+import { type SchemeEvents, type SeedColorRoot } from "../shared/bus-events.js";
 import { type EspalierTheme } from "../shared/theme.js";
 export type GoogleFontLoadingPolicy = "auto" | "none";
+export type { SchemeEvents } from "../shared/bus-events.js";
 /**
  * Root container for the Espalier design system.
  *
@@ -26,6 +27,31 @@ export type GoogleFontLoadingPolicy = "auto" | "none";
  * </esp-root>
  * ```
  *
+ * ### Nested theme previews and scoped events
+ *
+ * A nested root creates a scoped theme for its descendants. It does not create
+ * a separate event bus: every root publishes theme changes through the same
+ * Espalier singleton. Subscribe through the root whose changes you own so a
+ * nested preview cannot be mistaken for an application-level theme change.
+ *
+ * ```ts
+ * const applicationRoot = document.querySelector<EspalierRoot>("#application-theme")!;
+ *
+ * const unsubscribe = applicationRoot.subscribeScoped("scheme-changed", ({ scheme }) => {
+ *   localStorage.setItem("scheme", scheme);
+ * });
+ *
+ * // Initial state is read directly; scoped events report later changes only.
+ * renderScheme(applicationRoot.scheme);
+ *
+ * // Call when the owning integration is disposed.
+ * unsubscribe();
+ * ```
+ *
+ * This contract covers `scheme-changed`, `seed-color-changed`,
+ * `theme-changed`, and `icon-sprite-url-changed`. Components derived from
+ * `EspalierElementBase` use the same closest-root filter internally.
+ *
  * @customElement esp-root
  * @slot - Place Espalier components and content here.
  *
@@ -40,6 +66,17 @@ export type GoogleFontLoadingPolicy = "auto" | "none";
 export declare class EspalierRoot extends LitElement implements SeedColorRoot {
     /** Unique ID for correlating bus events across multiple roots. */
     correlationId: `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * Subscribe to a theme event published by this root only.
+     *
+     * All roots share Espalier's global bus. This method filters foreign and
+     * nested-root payloads by `correlationId` and returns a cleanup function.
+     * It reports changes after mount; read initial state from this root.
+     *
+     * @param event Root-scoped theme event to observe.
+     * @param handler Callback invoked with that event's typed payload.
+     */
+    subscribeScoped<K extends keyof SchemeEvents>(event: K, handler: (payload: SchemeEvents[K]) => void): () => void;
     /**
      * Base64-encoded JSON partial theme for the **light** scheme.
      *
@@ -178,6 +215,7 @@ export declare class EspalierRoot extends LitElement implements SeedColorRoot {
     get seedColor(): string;
     /** Returns the resolved theme for the active scheme. */
     get activeTheme(): EspalierTheme;
+    connectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(): void;
     protected updated(changedProperties: PropertyValues): void;