@taprootio/espalier 2.0.0

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

@@ -0,0 +1,200 @@
+import { LitElement, type PropertyValues } from "lit";
+import { type SeedColorRoot } from "../shared/bus-events.js";
+import { type EspalierTheme } from "../shared/theme.js";
+export type GoogleFontLoadingPolicy = "auto" | "none";
+/**
+ * Root container for the Espalier design system.
+ *
+ * Provides the full design-token pipeline — colors, scales, and
+ * fonts — to every descendant component.  All tokens are
+ * JS-computed from a pair of Base64-encoded theme objects and
+ * emitted as CSS custom properties on the host element.
+ *
+ * ### Theme API
+ *
+ * Supply a `light-theme` and/or `dark-theme` attribute containing
+ * a **Base64-encoded JSON** partial theme.  Fields you omit fall
+ * back to built-in defaults.  Switch between them with `scheme`.
+ *
+ * ```html
+ * <esp-root
+ *   light-theme="eyJzZWVkQ29sb3IiOiJva2xjaCgwLjcgMC4yIDE1NSkifQ=="
+ *   scheme="light">
+ *   <esp-box>
+ *     <h2>Themed content</h2>
+ *   </esp-box>
+ * </esp-root>
+ * ```
+ *
+ * @customElement esp-root
+ * @slot - Place Espalier components and content here.
+ *
+ * @docPageTitle Root
+ * @docUrl /components/root
+ * @menuGroup Structure
+ * @menuOrder 1
+ * @menuLabel Root
+ * @menuIcon building
+ *
+ */
+export declare class EspalierRoot extends LitElement implements SeedColorRoot {
+    /** Unique ID for correlating bus events across multiple roots. */
+    correlationId: `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * Base64-encoded JSON partial theme for the **light** scheme.
+     *
+     * Only fields you wish to override need to be present — all
+     * others inherit from the built-in light defaults.
+     *
+     * ```html
+     * <esp-root
+     *   light-theme="eyJzZWVkQ29sb3IiOiJva2xjaCgwLjcgMC4xNSAyODUpIn0="
+     *   scheme="light">
+     *   <esp-box><h2>Purple light theme</h2></esp-box>
+     * </esp-root>
+     * ```
+     *
+     * @type {string}
+     */
+    lightThemeAttr: string;
+    /**
+     * Base64-encoded JSON partial theme for the **dark** scheme.
+     *
+     * ```html
+     * <esp-root
+     *   dark-theme="eyJzZWVkQ29sb3IiOiJva2xjaCgwLjcgMC4xNSAyODUpIn0="
+     *   scheme="dark">
+     *   <esp-box><h2>Purple dark theme</h2></esp-box>
+     * </esp-root>
+     * ```
+     *
+     * @type {string}
+     */
+    darkThemeAttr: string;
+    /**
+     * Root path for locally-cached font CSS files used by
+     * `<esp-font-picker>` to load font previews.
+     *
+     * The directory must contain the individual font CSS files
+     * generated by `npm run build-fonts`.  These files must be
+     * served at stable, predictable paths (no filename hashing)
+     * because the picker constructs URLs by font family name.
+     *
+     * @type {string}
+     */
+    fontCSSRoot: string;
+    /**
+     * Full URL to the `font-definitions.json` catalog used by
+     * `<esp-font-picker>`.
+     *
+     * When set, the picker fetches from this URL instead of
+     * `{fontCSSRoot}font-definitions.json`.  This allows the JSON
+     * to be served through a cache-busting asset pipeline while
+     * the individual font CSS files remain at stable paths.
+     *
+     * @type {string}
+     */
+    fontDefinitionsUrl: string;
+    /**
+     * Controls whether Espalier may inject runtime Google Fonts CDN
+     * stylesheet links for selected Google Fonts.
+     *
+     * `auto` preserves the default behavior: theme font families and
+     * selected Google font-picker values may load full fonts from
+     * `fonts.googleapis.com`.  `none` prevents those runtime Google
+     * Fonts links, leaving local preview CSS and web-safe font stacks
+     * available for locked-down, offline, or strict-CSP environments.
+     *
+     * @type {"auto" | "none"}
+     * @default "auto"
+     */
+    googleFontLoading: GoogleFontLoadingPolicy;
+    /**
+     * Full URL to the SVG sprite used by component-owned `icon`
+     * attributes.
+     *
+     * Components append the validated icon name as a fragment, so
+     * this should point to the sprite file itself, without `#icon`.
+     * Use this when your application serves the sprite from a
+     * subpath, CDN, or cache-busted asset pipeline. Set it to an
+     * empty string to disable generated sprite icon URLs for this root.
+     *
+     * ```html
+     * <esp-root icon-sprite-url="/dist/icons.abc123.svg">
+     *   <esp-button icon="save" label="Save"></esp-button>
+     * </esp-root>
+     * ```
+     *
+     * @type {string}
+     */
+    iconSpriteUrl: string;
+    /**
+     * Initial color scheme to apply when `scheme` is not set.
+     *
+     * Use `light` or `dark` for a fixed published-site default, or
+     * `system` to follow the visitor's `prefers-color-scheme` before
+     * they toggle the active `scheme`.
+     *
+     * @type {"light" | "dark" | "system"}
+     * @default "light"
+     */
+    defaultScheme: "light" | "dark" | "system";
+    /**
+     * The active color scheme.
+     *
+     * Light scheme
+     *
+     * ```html
+     * <esp-root scheme="light">
+     *   <esp-box>
+     *     <h2>Light Scheme</h2>
+     *     <esp-button label="I am light"></esp-button>
+     *   </esp-box>
+     * </esp-root>
+     * ```
+     *
+     * Dark scheme
+     *
+     * ```html
+     * <esp-root scheme="dark">
+     *   <esp-box>
+     *     <h2>Dark Scheme</h2>
+     *     <esp-button label="I am dark"></esp-button>
+     *   </esp-box>
+     * </esp-root>
+     * ```
+     *
+     * @type {"dark" | "light"}
+     * @default "light"
+     */
+    get scheme(): "dark" | "light" | "";
+    set scheme(val: "light" | "dark" | "");
+    /**
+     * The effective seed color from the active theme.
+     *
+     * Read-only — supply a theme attribute with a different
+     * `seedColor` value to change.
+     */
+    get seedColor(): string;
+    /** Returns the resolved theme for the active scheme. */
+    get activeTheme(): EspalierTheme;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(): void;
+    protected updated(changedProperties: PropertyValues): void;
+    disconnectedCallback(): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+    /**
+     * Light-DOM styles injected into `document.head` so that
+     * slotted content (headings, links, code blocks, lists, etc.)
+     * inherits the design-system tokens defined on `:host`.
+     * Selectors are scoped to `esp-root` descendants to avoid
+     * leaking into content outside the root.
+     */
+    static lightDomStyles: string;
+    static styles: import("lit").CSSResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-root": EspalierRoot;
+    }
+}

package/dist/root/esp-root.js

@@ -0,0 +1,128 @@
+var h=function(m,e,t,o){var n=arguments.length,s=n<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,t):o,r;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(m,e,t,o);else for(var a=m.length-1;a>=0;a--)(r=m[a])&&(s=(n<3?r(s):n>3?r(e,t,s):r(e,t))||s);return n>3&&s&&Object.defineProperty(e,t,s),s},c;import{css as k,html as b,LitElement as T}from"lit";import{customElement as w,property as l}from"lit/decorators.js";import{getEspBus as p}from"../shared/bus-events.js";import{DEFAULT_LIGHT_THEME as f,DEFAULT_DARK_THEME as g,parseTheme as y,mergeTheme as v}from"../shared/theme.js";import{computeThemeProperties as E}from"./helpers/compute-theme-properties.js";let i=c=class extends T{constructor(){super(...arguments),this.schemeBacker="",this.schemeExplicitlySet=!1,this.resolvingDefaultScheme=!1,this.systemSchemeQuery=null,this.lastSeedColor="",this.resolvedLightTheme={...f},this.resolvedDarkTheme={...g},this.correlationId=globalThis.crypto?.randomUUID?.()??Math.random().toString(36),this.lightThemeAttr="",this.darkThemeAttr="",this.fontCSSRoot="/css/fonts/",this.fontDefinitionsUrl="",this.googleFontLoading="auto",this.iconSpriteUrl="/assets/icons.svg",this.defaultScheme="light",this.resizeObserver=new ResizeObserver(()=>{p().publish("window-resized",{emWidth:window.innerWidth/parseFloat(getComputedStyle(document.documentElement).fontSize),emHeight:window.innerHeight/parseFloat(getComputedStyle(document.documentElement).fontSize),pxWidth:window.innerWidth,pxHeight:window.innerHeight})}),this.handleSystemSchemeChange=e=>{this.schemeExplicitlySet||this.defaultScheme!=="system"||(this.resolvingDefaultScheme=!0,this.scheme=e.matches?"dark":"light",this.resolvingDefaultScheme=!1)}}get scheme(){return this.schemeBacker}set scheme(e){const t=e==="dark"?"dark":e==="light"?"light":"",o=this.schemeBacker;this.resolvingDefaultScheme||(this.schemeExplicitlySet=t.length>0),t!==o&&(this.schemeBacker=t,this.requestUpdate("scheme",o),t&&p().publish("scheme-changed",{scheme:t,correlationId:this.correlationId}))}get seedColor(){return this.activeTheme.seedColor}static extractFamily(e){if(!e)return"";const t=e.match(/^"([^"]+)"|^'([^']+)'/);return t&&(t[1]||t[2])||""}injectGoogleFontLink(e,t,o){const n="data-esp-font",s=`${this.correlationId}-${e}`,r=document.head.querySelector(`link[${n}="${s}"]`);if(this.googleFontLoading==="none"){r?.remove();return}if(r&&t&&r.dataset.espFamily===t&&r.dataset.espWeight===(o??"")||(r?.remove(),!t))return;const a=encodeURIComponent(t),u=o==="bold"?"700":o==="normal"?"400":o,S=u&&u!=="400"?`:wght@${u}`:"",d=document.createElement("link");d.rel="stylesheet",d.href=`https://fonts.googleapis.com/css2?family=${a}${S}&display=swap`,d.setAttribute(n,s),d.dataset.espFamily=t,d.dataset.espWeight=o??"",document.head.appendChild(d)}syncGoogleFontLinks(){this.googleFontLoading==="none"&&this.removeRuntimeGoogleFontLinks();const e=this.activeTheme;this.injectGoogleFontLink("body",c.extractFamily(e.fontBody),e.fontWeightBody),this.injectGoogleFontLink("headings",c.extractFamily(e.fontHeadings),e.fontWeightHeadings),this.injectGoogleFontLink("brand",c.extractFamily(e.fontBrand),e.fontWeightBrand),this.injectGoogleFontLink("monospace",c.extractFamily(e.fontMonospace),e.fontWeightMonospace)}removeRuntimeGoogleFontLinks(){for(const e of document.head.querySelectorAll(`link[data-esp-font^="${this.correlationId}-"]`))e.remove();for(const e of document.head.querySelectorAll(`link[data-esp-font-picker-root="${CSS.escape(this.correlationId)}"]`))e.remove()}get activeTheme(){return this.scheme==="dark"?this.resolvedDarkTheme:this.resolvedLightTheme}resolveThemes(){const e=this.lightThemeAttr?y(this.lightThemeAttr):null;this.resolvedLightTheme=e?v(f,e):{...f};const t=this.darkThemeAttr?y(this.darkThemeAttr):null;this.resolvedDarkTheme=t?v(g,t):{...g}}willUpdate(e){const t=["lightThemeAttr","darkThemeAttr"];(!this.lastSeedColor||t.some(r=>e.has(r)))&&(this.resolveThemes(),p().publish("theme-changed",{correlationId:this.correlationId}));const n=E(this.activeTheme,this.scheme==="dark"?"dark":"light");for(const[r,a]of Object.entries(n))this.style.setProperty(r,a);const s=this.activeTheme.seedColor;this.lastSeedColor&&this.lastSeedColor!==s&&p().publish("seed-color-changed",{seedColor:s,correlationId:this.correlationId}),this.lastSeedColor=s,e.has("iconSpriteUrl")&&p().publish("icon-sprite-url-changed",{iconSpriteUrl:this.iconSpriteUrl,correlationId:this.correlationId}),this.syncGoogleFontLinks()}firstUpdated(){document.addEventListener("click",t=>{const o=t.composedPath().filter(n=>n instanceof HTMLElement&&n.tagName==="ESP-POPOVER");p().publish("close-popovers",{source:t.target??void 0,skipPopovers:o})}),this.resizeObserver.observe(this);const e=this.activeTheme.stylesheets;if(e.length)for(const t of e){const o=document.createElement("link");o.rel="stylesheet",o.href=t,document.head.appendChild(o)}if(!document.getElementById("esp-root-base-styles")){const t=document.createElement("style");t.id="esp-root-base-styles",t.textContent=c.lightDomStyles,document.head.appendChild(t)}this.applyDefaultScheme()}updated(e){(e.has("defaultScheme")||e.has("scheme"))&&!this.schemeExplicitlySet&&this.applyDefaultScheme()}disconnectedCallback(){this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null,this.resizeObserver.disconnect(),super.disconnectedCallback()}applyDefaultScheme(){this.schemeExplicitlySet||(this.resolvingDefaultScheme=!0,this.scheme=this.resolveDefaultScheme(),this.resolvingDefaultScheme=!1,this.syncSystemSchemeListener())}resolveDefaultScheme(){return this.defaultScheme==="dark"||this.defaultScheme==="system"&&window.matchMedia?.("(prefers-color-scheme: dark)").matches?"dark":"light"}syncSystemSchemeListener(){if(this.defaultScheme!=="system"||!window.matchMedia){this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null;return}this.systemSchemeQuery||(this.systemSchemeQuery=window.matchMedia("(prefers-color-scheme: dark)"),this.systemSchemeQuery.addEventListener("change",this.handleSystemSchemeChange))}render(){return b`<slot></slot>`}};i.lightDomStyles=`
+    
+    esp-root {
+      font-family: var(--esp-font-body);
+      font-weight: var(--esp-font-weight-body);
+      line-height: 1.5;
+      font-size: var(--esp-type-normal);
+      color: var(--esp-color-text);
+    }
+
+    
+    esp-root ul[role="list"],
+    esp-root ol[role="list"] {
+      list-style: none;
+    }
+
+    esp-root ul li::marker,
+    esp-root ol li::marker {
+      font-weight: bold;
+    }
+
+    
+    esp-root input,
+    esp-root select,
+    esp-root button {
+      font-family: var(--esp-font-body);
+    }
+
+    
+    esp-root a:not([class]) {
+      text-decoration-skip-ink: auto;
+      font-weight: bold;
+      color: var(--esp-color-link);
+    }
+
+    esp-root a {
+      text-decoration: underline;
+      text-decoration-skip-ink: auto;
+      color: var(--esp-color-link);
+    }
+
+    esp-root a:hover {
+      background-color: var(--esp-color-link-hover-bg);
+      color: var(--esp-color-link-hover);
+      text-decoration: none;
+    }
+
+    
+    esp-root input,
+    esp-root button,
+    esp-root textarea,
+    esp-root select,
+    esp-root p,
+    esp-root ul,
+    esp-root li {
+      font-family: var(--esp-font-body);
+      color: var(--esp-color-text);
+      font-size: inherit;
+    }
+
+    esp-root textarea:not([rows]) {
+      min-height: 10em;
+    }
+
+    
+    esp-root h1,
+    esp-root h2,
+    esp-root h3,
+    esp-root h4,
+    esp-root h5 {
+      font-family: var(--esp-font-headings);
+      font-weight: var(--esp-font-weight-headings);
+      color: var(--esp-color-headings);
+      margin: var(--esp-size-small-to-normal) 0 var(--esp-size-tiny-to-small);
+    }
+
+    esp-root h5 { font-size: var(--esp-type-small); line-height: 1.4; }
+    esp-root h4 { font-size: var(--esp-type-medium); line-height: 1.3; }
+    esp-root h3 { font-size: var(--esp-type-big); line-height: 1.2; }
+    esp-root h2 { font-size: var(--esp-type-large); line-height: 1.15; }
+    esp-root h1 { font-size: var(--esp-type-huge); line-height: 1.1; }
+
+    
+    esp-root pre,
+    esp-root code {
+      font-family: var(--esp-font-monospace);
+      font-weight: var(--esp-font-weight-monospace);
+    }
+
+    esp-root code {
+      font-size: var(--esp-type-small);
+      background: var(--esp-color-layer-1);
+      border-radius: var(--esp-size-border-radius);
+      padding: 0 0.35em;
+      display: inline-block;
+      border: 1px dotted var(--esp-color-border);
+    }
+
+    esp-root pre {
+      background-color: var(--esp-color-layer-1);
+      border-radius: var(--esp-size-border-radius);
+      border: 1px dotted var(--esp-color-border);
+    }
+
+    esp-root pre > code {
+      font-size: var(--esp-type-tiny);
+      display: block;
+      background: none;
+      border: none;
+      hyphens: none;
+      tab-size: 2;
+      white-space: pre;
+      padding: var(--esp-size-padding);
+      overflow: auto;
+      line-height: 1.8;
+    }
+
+    
+    esp-root img,
+    esp-root picture {
+      max-width: 100%;
+      display: block;
+    }
+  `,i.styles=k`
+    :host {
+      display: block;
+    }
+  `,h([l({attribute:!1})],i.prototype,"correlationId",void 0),h([l({attribute:"light-theme"})],i.prototype,"lightThemeAttr",void 0),h([l({attribute:"dark-theme"})],i.prototype,"darkThemeAttr",void 0),h([l({attribute:"font-css-root",type:String})],i.prototype,"fontCSSRoot",void 0),h([l({attribute:"font-definitions-url",type:String})],i.prototype,"fontDefinitionsUrl",void 0),h([l({attribute:"google-font-loading",type:String})],i.prototype,"googleFontLoading",void 0),h([l({attribute:"icon-sprite-url",type:String})],i.prototype,"iconSpriteUrl",void 0),h([l({attribute:"default-scheme",type:String,reflect:!0})],i.prototype,"defaultScheme",void 0),h([l({attribute:"scheme",type:String,reflect:!0})],i.prototype,"scheme",null),i=c=h([w("esp-root")],i);export{i as EspalierRoot};

package/dist/root/helpers/compute-theme-properties.js

@@ -0,0 +1 @@
+import{parseOklch as y,serializeOklch as p,gamutMapToSRGB as S,deriveSemantic as v,deriveSemanticWithContrast as B}from"../../shared/color-engine.js";import{generateScaleProperties as x}from"../../shared/scale-engine.js";import{SEMANTIC_COLOR_NAMES as l,LIGHTNESS_KEYS as C,semanticToCSS as b}from"../../shared/theme.js";import{lightnessKeyToCSS as I}from"./lightness-key-to-css.js";import{computeVariants as O}from"./compute-variants.js";function M(o){return{rootFontSize:o.rootFontSize,typeRatio:o.typeRatio,spaceRatio:o.spaceRatio,borderRadius:o.borderRadius,viewportMin:o.viewportMin,viewportMax:o.viewportMax}}function W(o,k){const d=y(o.seedColor);if(!d)return{};const n={};n["--esp-scheme"]=k,n["--esp-seed-color"]=o.seedColor;const c=O(d,o);for(const[a,t]of Object.entries(c))n[`--esp-color-${a}`]=p(S(t));for(const a of C)n[I(a)]=`${Math.round(o.lightness[a]*100)}%`;const u={text:{bg:"background",targetLc:75},dangerText:{bg:"background",targetLc:75},headings:{bg:"background",targetLc:60},headingsHover:{bg:"background",targetLc:60},link:{bg:"background",targetLc:75},linkHover:{bg:"background",targetLc:75},actionText:{bg:"actionBackground",targetLc:75},inputCaret:{bg:"layer2",targetLc:60},inputSelection:{bg:"inputSelectionBg",targetLc:60}},s={};for(const a of l){if(u[a])continue;const t=o.semanticMappings[a],i=o.chroma[a],r=c[t.source],e=o.lightness[t.lightness],g=v(r,e,i.min,i.max);s[a]=g,n[b(a)]=p(g)}for(const a of l){const t=u[a];if(!t)continue;const i=o.semanticMappings[a],r=o.chroma[a],e=c[i.source],g=o.lightness[i.lightness],m=s[t.bg],f=B(e,g,r.min,r.max,m,t.targetLc);s[a]=f,n[b(a)]=p(f)}return Object.assign(n,x(M(o))),o.fontBody&&(n["--esp-font-body"]=o.fontBody),o.fontHeadings&&(n["--esp-font-headings"]=o.fontHeadings),o.fontBrand&&(n["--esp-font-brand"]=o.fontBrand),o.fontMonospace&&(n["--esp-font-monospace"]=o.fontMonospace),n["--esp-font-weight-body"]=o.fontWeightBody,n["--esp-font-weight-headings"]=o.fontWeightHeadings,n["--esp-font-weight-brand"]=o.fontWeightBrand,n["--esp-font-weight-monospace"]=o.fontWeightMonospace,o.pageBackgroundImage&&(n["--esp-page-background-image"]=o.pageBackgroundImage),o.pageBackgroundImageOpacity!==void 0&&(n["--esp-page-background-image-opacity"]=o.pageBackgroundImageOpacity.toString()),o.boxBackgroundImage&&(n["--esp-box-background-image"]=o.boxBackgroundImage),o.boxBackgroundImageOpacity!==void 0&&(n["--esp-box-background-image-opacity"]=o.boxBackgroundImageOpacity.toString()),o.vellumOpacity!==void 0&&(n["--esp-vellum-opacity"]=o.vellumOpacity.toString()),o.vellumBackgroundImage&&(n["--esp-vellum-background-image"]=o.vellumBackgroundImage),o.vellumBackgroundImageOpacity!==void 0&&(n["--esp-vellum-background-image-opacity"]=o.vellumBackgroundImageOpacity.toString()),n}export{W as computeThemeProperties};

package/dist/root/helpers/compute-variants.js

@@ -0,0 +1 @@
+import{rotateHue as l}from"../../shared/color-engine.js";const h=.6,p=.85;function s(t,i){const{angles:c,semanticHues:n,variantChroma:o}=i,a=m=>o[m]??t.c,r=Math.min(p,Math.max(h,t.l));return{primary:t,"analogous-left":{l:t.l,c:a("analogous-left"),h:l(t.h,-c.analogous)},"analogous-right":{l:t.l,c:a("analogous-right"),h:l(t.h,c.analogous)},complementary:{l:t.l,c:a("complementary"),h:l(t.h,c.complementary)},"split-complementary-left":{l:t.l,c:a("split-complementary-left"),h:l(t.h,c.complementary-c.splitComplementary)},"split-complementary-right":{l:t.l,c:a("split-complementary-right"),h:l(t.h,c.complementary+c.splitComplementary)},"triadic-left":{l:t.l,c:a("triadic-left"),h:l(t.h,c.triadic)},"triadic-right":{l:t.l,c:a("triadic-right"),h:l(t.h,-c.triadic)},danger:{l:r,c:a("danger"),h:l(n.danger,0)},success:{l:r,c:a("success"),h:l(n.success,0)},warning:{l:r,c:a("warning"),h:l(n.warning,0)}}}export{s as computeVariants};

package/dist/root/helpers/lightness-key-to-css.js

@@ -0,0 +1 @@
+function r(e){return`--esp-l-${e.replace(/([A-Z])/g,"-$1").replace(/(\d)/g,"-$1").toLowerCase()}`}export{r as lightnessKeyToCSS};

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

@@ -0,0 +1,90 @@
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+/**
+ * A search result item provided by the consumer via `setResults()`.
+ * The `excerpt` field may contain HTML with `<mark>` highlights.
+ */
+export interface SearchResult {
+    /** URL to navigate to when this result is selected. */
+    url: string;
+    /** Page title. */
+    title: string;
+    /** Excerpt with `<mark>` highlights (HTML string). */
+    excerpt: string;
+}
+/**
+ * Modal search overlay with a Cmd+K / Ctrl+K interaction pattern.
+ *
+ * `<esp-search>` is a pure UI shell with no search-engine dependency.
+ * Consumers wire it to any search backend (Pagefind, MiniSearch, API,
+ * etc.) by listening for `search-requested` events and calling
+ * `setResults()` with the matches.
+ *
+ * @fires search-requested — The user changed the query input. Fires on
+ *   every keystroke (not debounced) so consumers can track the latest
+ *   query and discard stale async results. Consumers that need debouncing
+ *   should apply it themselves (e.g. Pagefind's `debouncedSearch()`).
+ *   `detail: { query: string }`
+ * @fires result-selected — The user chose a result.
+ *   `detail: { url: string }`
+ * @fires search-closed — The overlay was closed (Escape, backdrop click,
+ *   or result selection). Consumers should use this to cancel in-flight
+ *   searches or discard pending results.
+ *   `detail: {}`
+ *
+ * @cssprop --esp-search-max-width - Maximum width of the search
+ *   panel. Defaults to `40rem`.
+ * @cssprop --esp-search-max-height - Maximum height of the results
+ *   list. Defaults to `60vh`.
+ * @cssprop --esp-search-backdrop - Backdrop color behind the panel.
+ *   Defaults to `oklch(0.15 0 0 / 0.6)`.
+ * @cssprop --esp-search-panel-background - Background color of the search panel.
+ *   Defaults to `var(--esp-color-layer-1)`.
+ * @cssprop --esp-search-panel-shadow - Box shadow of the search panel.
+ * @cssprop --esp-search-border-color - Divider and loading-track color used
+ *   by the search panel. Defaults to `var(--esp-color-border)`.
+ * @cssprop --esp-search-text-color - Main text color used by the search UI.
+ *   Defaults to `var(--esp-color-text)`.
+ * @cssprop --esp-search-muted-color - Muted text color for placeholders,
+ *   excerpts, and empty states.
+ * @cssprop --esp-search-title-color - Title color for result rows.
+ *   Defaults to `var(--esp-color-headings)`.
+ * @cssprop --esp-search-active-background - Background color of the active
+ *   result row. Defaults to `var(--esp-color-layer-2)`.
+ * @cssprop --esp-search-highlight-background - Background color applied to
+ *   `<mark>` highlights inside excerpts.
+ * @cssprop --esp-search-loading-indicator-color - Accent color of the loading
+ *   spinner. Defaults to `var(--esp-color-primary)`.
+ * @cssprop --esp-search-loading-indicator-track-color - Track color of the
+ *   loading spinner. Defaults to `var(--esp-search-border-color)`.
+ *
+ * @docUrl /components/search
+ * @docPageTitle Search
+ * @menuLabel Search
+ * @menuGroup Interaction
+ * @menuOrder 5
+ * @docSections examples,properties,events,cssprops
+ *
+ * @example Basic search (consumer wiring not shown)
+ * ```html
+ * <esp-search placeholder="Search docs..."></esp-search>
+ * ```
+ */
+export declare class EspalierSearch extends EspalierElementBase {
+    /** Placeholder text for the search input. */
+    placeholder: string;
+    /** Open the search overlay and focus the input. */
+    show(): void;
+    /** Close the search overlay and restore focus. */
+    hide(): void;
+    /** Update the displayed search results. */
+    setResults(results: SearchResult[]): void;
+    /** Show or hide the loading indicator. */
+    setLoading(loading: boolean): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-search": EspalierSearch;
+    }
+}

package/dist/search/esp-search.js

@@ -0,0 +1,210 @@
+var o=function(a,e,t,c){var h=arguments.length,r=h<3?e:c===null?c=Object.getOwnPropertyDescriptor(e,t):c,p;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(a,e,t,c);else for(var d=a.length-1;d>=0;d--)(p=a[d])&&(r=(h<3?p(r):h>3?p(e,t,r):p(e,t))||r);return h>3&&r&&Object.defineProperty(e,t,r),r};import{css as y,html as l,nothing as i}from"lit";import{customElement as k,property as w,state as n}from"lit/decorators.js";import{classMap as f}from"lit/directives/class-map.js";import{createRef as u,ref as v}from"lit/directives/ref.js";import{unsafeHTML as E}from"lit/directives/unsafe-html.js";import{EspalierElementBase as b}from"../shared/esp-element-base.js";import{OverlayController as I}from"../shared/overlay-controller.js";import{ESP_EVENTS as m}from"../shared/events.js";import{srOnly as $}from"../shared/style-fragments.js";const g="%%ESP_MARK_OPEN%%",x="%%ESP_MARK_CLOSE%%";function R(a){return a.replace(/<mark>/gi,g).replace(/<\/mark>/gi,x).replace(/<[^>]*>/g,"").replaceAll(g,"<mark>").replaceAll(x,"</mark>")}let s=class extends b{constructor(){super(...arguments),this.placeholder="Search\u2026",this.isOpen=!1,this.results=[],this.loading=!1,this.query="",this.activeIndex=-1,this.vellumRef=u(),this.inputRef=u(),this.resultsRef=u(),this.idPrefix=`esp-search-${this.correlationId}`,this._overlay=new I({host:this,getFocusTrapContainer:()=>this.vellumRef.value??null,getFocusFallback:()=>this.inputRef.value??null})}show(){this.isOpen||(this.isOpen=!0,this._overlay.open(),this.updateComplete.then(()=>{this.inputRef.value?.focus()}))}hide(){this.isOpen&&(this.isOpen=!1,this.query="",this.results=[],this.activeIndex=-1,this.loading=!1,this._overlay.close(),this.dispatchEvent(new CustomEvent(m.SEARCH_CLOSED,{detail:{},bubbles:!0,composed:!0})))}setResults(e){this.results=e,this.activeIndex=e.length>0?0:-1}setLoading(e){this.loading=e}handleInput(e){const t=e.target.value;this.query=t,this.activeIndex=-1,this.dispatchEvent(new CustomEvent(m.SEARCH_REQUESTED,{detail:{query:t},bubbles:!0,composed:!0})),t.trim()||(this.results=[])}selectResult(e){this.dispatchEvent(new CustomEvent(m.RESULT_SELECTED,{detail:{url:e.url},bubbles:!0,composed:!0})),this.hide()}handleKeyDown(e){if(this.isOpen)switch(e.key){case"Escape":e.preventDefault(),this.hide();break;case"ArrowDown":e.preventDefault(),this.results.length>0&&(this.activeIndex=Math.min(this.activeIndex+1,this.results.length-1),this.scrollActiveIntoView());break;case"ArrowUp":e.preventDefault(),this.results.length>0&&(this.activeIndex=Math.max(this.activeIndex-1,0),this.scrollActiveIntoView());break;case"Enter":e.preventDefault(),this.activeIndex>=0&&this.activeIndex<this.results.length&&this.selectResult(this.results[this.activeIndex]);break;case"Tab":this._overlay.trapFocus(e);break}}handleBackdropClick(e){e.target===this.vellumRef.value&&this.hide()}scrollActiveIntoView(){this.updateComplete.then(()=>{const e=this.resultsRef.value?.querySelectorAll(".result");e&&this.activeIndex>=0&&e[this.activeIndex]&&e[this.activeIndex].scrollIntoView({block:"nearest"})})}get hasListbox(){return this.results.length>0}get listboxId(){return`${this.idPrefix}-listbox`}optionId(e){return`${this.idPrefix}-option-${e}`}render(){return l`
+      <div
+        ${v(this.vellumRef)}
+        class=${f({vellum:!0,"is-open":this.isOpen})}
+        role=${this.isOpen?"dialog":i}
+        aria-modal=${this.isOpen?"true":i}
+        aria-label="Search"
+        tabindex="-1"
+        @keydown=${this.handleKeyDown}
+        @click=${this.handleBackdropClick}
+      >
+        <div class="panel">
+          <div class="input-row">
+            <svg class="search-icon" viewBox="0 0 24 24" aria-hidden="true">
+              <circle cx="10" cy="10" r="7" />
+              <path d="M21 21l-6-6" />
+            </svg>
+            <input
+              ${v(this.inputRef)}
+              type="search"
+              class="search-input"
+              .value=${this.query}
+              placeholder=${this.placeholder}
+              autocomplete="off"
+              aria-label="Search"
+              role="combobox"
+              aria-expanded=${this.hasListbox}
+              aria-controls=${this.hasListbox?this.listboxId:i}
+              aria-activedescendant=${this.activeIndex>=0&&this.hasListbox?this.optionId(this.activeIndex):i}
+              @input=${this.handleInput}
+            />
+            <span class="loading-status sr-only" role="status" aria-live="polite">
+              ${this.loading?"Loading results\u2026":i}
+            </span>
+            ${this.loading?l`<span class="loading-indicator" aria-hidden="true"></span>`:i}
+          </div>
+          ${this.renderResults()}
+        </div>
+      </div>
+    `}renderResults(){return this.query.trim()?this.results.length===0&&!this.loading?l`<div class="empty" role="status">No results found.</div>`:this.results.length===0?i:l`
+      <ul ${v(this.resultsRef)} class="results" role="listbox" id=${this.listboxId}>
+        ${this.results.map((e,t)=>l`
+            <li
+              id=${this.optionId(t)}
+              class=${f({result:!0,active:t===this.activeIndex})}
+              role="option"
+              aria-selected=${t===this.activeIndex}
+              @click=${()=>this.selectResult(e)}
+              @mouseenter=${()=>{this.activeIndex=t}}
+            >
+              <span class="result-title">${e.title}</span>
+              <span class="result-excerpt">${E(R(e.excerpt))}</span>
+            </li>
+          `)}
+      </ul>
+    `:i}};s.styles=[...b.styles,$,y`
+      :host {
+        display: block;
+      }
+
+      .vellum {
+        display: flex;
+        align-items: flex-start;
+        justify-content: center;
+        padding-top: 10vh;
+        visibility: hidden;
+        position: fixed;
+        z-index: 10000;
+        inset: 0;
+        outline: none;
+
+        &::before {
+          content: "";
+          position: fixed;
+          inset: 0;
+          background: var(--esp-search-backdrop, oklch(0.15 0 0 / 0.6));
+          z-index: 1;
+        }
+
+        &.is-open {
+          visibility: visible;
+        }
+      }
+
+      .panel {
+        position: relative;
+        z-index: 2;
+        width: 100%;
+        max-width: var(--esp-search-max-width, 40rem);
+        background: var(--esp-search-panel-background, var(--esp-color-layer-1));
+        border-radius: var(--esp-size-border-radius, 0.5rem);
+        box-shadow: var(
+          --esp-search-panel-shadow,
+          0 1rem 3rem oklch(from var(--esp-color-shadow) l c h / 0.3)
+        );
+        overflow: hidden;
+        margin: 0 var(--esp-size-small);
+      }
+
+      .input-row {
+        display: flex;
+        align-items: center;
+        gap: var(--esp-size-tiny);
+        padding: var(--esp-size-small) var(--esp-size-normal);
+        border-bottom: 1px solid var(--esp-search-border-color, var(--esp-color-border));
+      }
+
+      .search-icon {
+        width: 1.25em;
+        height: 1.25em;
+        flex-shrink: 0;
+        fill: none;
+        stroke: currentColor;
+        stroke-width: 2;
+        stroke-linecap: round;
+        stroke-linejoin: round;
+        opacity: 0.5;
+      }
+
+      .search-input {
+        flex: 1;
+        border: none;
+        outline: none;
+        background: transparent;
+        font: inherit;
+        font-size: var(--esp-type-medium, 1.125rem);
+        color: var(--esp-search-text-color, var(--esp-color-text));
+        padding: 0;
+
+        &::placeholder {
+          color: var(--esp-search-muted-color, oklch(from var(--esp-color-text) l c h / 0.7));
+        }
+      }
+
+      
+      .search-input::-webkit-search-cancel-button {
+        display: none;
+      }
+
+      .loading-indicator {
+        width: 1.25em;
+        height: 1.25em;
+        flex-shrink: 0;
+        border: 2px solid
+          var(
+            --esp-search-loading-indicator-track-color,
+            var(--esp-search-border-color, var(--esp-color-border))
+          );
+        border-top-color: var(--esp-search-loading-indicator-color, var(--esp-color-primary));
+        border-radius: 50%;
+        animation: spin 0.6s linear infinite;
+      }
+
+      @keyframes spin {
+        to {
+          transform: rotate(360deg);
+        }
+      }
+
+      .results {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        max-height: var(--esp-search-max-height, 60vh);
+        overflow-y: auto;
+      }
+
+      .result {
+        padding: var(--esp-size-tiny) var(--esp-size-normal);
+        cursor: pointer;
+        border-bottom: 1px solid var(--esp-search-border-color, var(--esp-color-border));
+
+        &:last-child {
+          border-bottom: none;
+        }
+
+        &.active {
+          background: var(--esp-search-active-background, var(--esp-color-layer-2));
+        }
+      }
+
+      .result-title {
+        display: block;
+        font-weight: 600;
+        font-family: var(--esp-font-headings, inherit);
+        color: var(--esp-search-title-color, var(--esp-color-headings));
+      }
+
+      .result-excerpt {
+        display: block;
+        font-size: 0.875em;
+        color: var(--esp-search-muted-color, oklch(from var(--esp-color-text) l c h / 0.7));
+        margin-top: 0.125em;
+        line-height: 1.4;
+
+        & mark {
+          background: var(--esp-search-highlight-background, var(--esp-color-link-hover-bg));
+          color: inherit;
+          padding: 0 0.1em;
+          border-radius: 0.15em;
+        }
+      }
+
+      .empty {
+        padding: var(--esp-size-normal);
+        text-align: center;
+        color: var(--esp-search-muted-color, oklch(from var(--esp-color-text) l c h / 0.7));
+        font-style: italic;
+      }
+    `],o([w({type:String})],s.prototype,"placeholder",void 0),o([n()],s.prototype,"isOpen",void 0),o([n()],s.prototype,"results",void 0),o([n()],s.prototype,"loading",void 0),o([n()],s.prototype,"query",void 0),o([n()],s.prototype,"activeIndex",void 0),s=o([k("esp-search")],s);export{s as EspalierSearch};

package/dist/shared/attribute-helpers.js

@@ -0,0 +1 @@
+function u(t,i,n){const r=t.getAttribute(i);r!==null&&r!==n&&t.setAttribute(i,n)}export{u as syncNormalizedAttribute};