@taprootio/espalier 2.0.0

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

@@ -0,0 +1,173 @@
+import { type PropertyValues } from "lit";
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+import "./esp-image-option.js";
+/**
+ * A responsive image with a native `<picture>`.
+ *
+ * `esp-image` accepts two authoring shapes:
+ *
+ * 1. **Project a light-DOM `<picture>`** — the recommended form for published /
+ *    server-rendered markup. Provide a real `<picture>` (or a bare `<img>`) as
+ *    a child and `esp-image` projects it through a `<slot>`, adding only the
+ *    layout box, border, and lightbox wiring. Because the image lives in the
+ *    served HTML it is discoverable by the preload scanner and visible to
+ *    crawlers, and it is fetched exactly once (the component renders no
+ *    competing internal image).
+ * 2. **Declare [esp-image-option](/components/image/image-option) children** —
+ *    the editor / fallback form. `esp-image` builds a shadow `<picture>` and
+ *    `srcset` from them. Useful for editor previews before a native `<picture>`
+ *    has been generated.
+ *
+ * Source precedence, most specific first: `local-image` → a slotted
+ * `<picture>` / `<img>` → `esp-image-option` children. In every mode the host
+ * reserves the layout box up front via `aspect-ratio` (from `original-width` /
+ * `original-height`), so there is no layout shift while the image loads.
+ *
+ * @slot - A light-DOM `<picture>` or `<img>` to project, or
+ * [esp-image-option](/components/image/image-option) children describing each
+ * available size. When projecting, `alt` lives on your `<img>`; the component's
+ * `caption` still drives the [esp-lightbox](/components/lightbox) drawer (the
+ * two may differ).
+ *
+ * ```html
+ * <!-- Projected native <picture> — published markup, crawlable + preloadable -->
+ * <esp-image original-width="1200" original-height="800" caption="A scenic mountain lake">
+ *   <picture>
+ *     <source
+ *       srcset="https://picsum.photos/600/400 400w, https://picsum.photos/900/600 800w, https://picsum.photos/1200/800 1200w"
+ *       sizes="100vw"
+ *     />
+ *     <img src="https://picsum.photos/1200/800" alt="A scenic mountain lake" />
+ *   </picture>
+ * </esp-image>
+ * ```
+ *
+ * ```html
+ * <!-- esp-image-option children — editor / fallback form -->
+ * <esp-image
+ *   original-width="1200"
+ *   original-height="800"
+ *   low-res="https://picsum.photos/300/200"
+ *   caption="A scenic mountain lake"
+ *   sizes="100vw"
+ * >
+ *   <esp-image-option width="400" url="https://picsum.photos/600/400"></esp-image-option>
+ *   <esp-image-option width="800" url="https://picsum.photos/900/600"></esp-image-option>
+ *   <esp-image-option width="1200" url="https://picsum.photos/1200/800"></esp-image-option>
+ * </esp-image>
+ * ```
+ *
+ * The component picks the responsive variant for its **own rendered box**: after
+ * it upgrades it measures its width (via a `ResizeObserver`) and sets `sizes` to
+ * that, so a small card or gallery column does not over-fetch — no hand-authored
+ * `sizes` required. The `sizes` attribute is only a fallback: it covers the brief
+ * window before the first measurement and the server-rendered *initial* fetch
+ * (the browser's preload scanner runs before the component upgrades). Set it to
+ * the layout's server-side estimate when that initial fetch matters:
+ *
+ * ```html
+ * <esp-image
+ *   original-width="1200"
+ *   original-height="800"
+ *   low-res="https://picsum.photos/300/200"
+ *   sizes="(max-width: 600px) 100vw, 320px"
+ *   style="max-width: 320px;"
+ * >
+ *   <esp-image-option width="320" url="https://picsum.photos/640/427"></esp-image-option>
+ *   <esp-image-option width="640" url="https://picsum.photos/960/640"></esp-image-option>
+ * </esp-image>
+ * ```
+ *
+ * @cssprop --esp-image-border - Set the border property of the image.
+ *
+ * ```html
+ * <style>
+ * esp-image.with-custom-border {
+ *   --esp-image-border: 5px dashed orange;
+ * }
+ * </style>
+ * <esp-image class="with-custom-border" original-width="1200" original-height="800" low-res="https://picsum.photos/300/200" sizes="100vw">
+ *   <esp-image-option width="400" url="https://picsum.photos/600/400"></esp-image-option>
+ *   <esp-image-option width="900" url="https://picsum.photos/900/600"></esp-image-option>
+ *   <esp-image-option width="1200" url="https://picsum.photos/1200/800"></esp-image-option>
+ * </esp-image>
+ * ```
+ *
+ * @docPageTitle Image
+ * @docUrl /components/image
+ * @menuGroup Media
+ * @menuLabel Image
+ * @menuIcon photo
+ */
+export declare class EspalierImage extends EspalierElementBase {
+    /**
+     * The original height of the image; used to calculate the orientation of
+     * the image and set the element aspect ratio.
+     * @type {number}
+     */
+    originalHeight: number;
+    /**
+     * The original width of the image; used to calculate the orientation of
+     * the image and set the element aspect ratio.
+     * @type {number}
+     */
+    originalWidth: number;
+    /**
+     * The fallback image URL. Used as the `<img src>` — the variant the browser
+     * loads when it cannot evaluate the responsive `srcset` (very old browsers),
+     * and the SEO/no-JS source. Named `low-res` because a small, fast-loading
+     * variant is the sensible default to point it at.
+     * @type {string}
+     */
+    imageUrl: string;
+    /**
+     * A local image URL (e.g. a `blob:` URL) that takes priority over responsive
+     * selection. When set, a plain `<img>` with no responsive sources is rendered
+     * so the local preview always wins. Used during upload to show the user's
+     * local file immediately while CDN variants are generated in the background.
+     * @type {string}
+     */
+    localImage: string;
+    /**
+     * A caption for the image. Drives the visible caption in the
+     * [esp-lightbox](/components/lightbox) drawer in every mode. In the
+     * fallback / `local-image` paths it is also applied as the internal
+     * `<img alt>`; when projecting a light-DOM `<picture>` / `<img>`, put `alt` on
+     * your own `<img>` (it may legitimately differ from the drawer caption).
+     * @type {string}
+     */
+    caption: string;
+    /**
+     * Fallback `sizes` hint used only until the element measures its own rendered
+     * width (and for the server-rendered *initial* fetch, which the browser
+     * performs before this component upgrades). Once measured, the element
+     * advertises its actual box width instead — in both the built-from-options
+     * and projection paths — so the browser picks the smallest variant that
+     * covers the box (× DPR), in any layout, with no hand-authored `sizes`. Set
+     * this when you need a specific server-side hint (e.g. the generator's
+     * per-layout value); otherwise leave it and the component sizes itself.
+     * @type {string}
+     */
+    sizes: string;
+    /**
+     * The native `loading` strategy for the **internally rendered** `<img>` (the
+     * fallback and `local-image` paths). Use `lazy` to defer offscreen gallery
+     * images until they approach the viewport. Defaults to `eager`. Has no effect
+     * in projection mode, where the projected `<img>` carries its own `loading`,
+     * `decoding`, and `fetchpriority` directly.
+     * @type {"eager" | "lazy"}
+     */
+    loading: "eager" | "lazy";
+    get isPortrait(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changedProperties: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-image": EspalierImage;
+    }
+}

package/dist/image/esp-image.js

@@ -0,0 +1,51 @@
+var a=function(h,e,t,i){var o=arguments.length,r=o<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,n;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(h,e,t,i);else for(var d=h.length-1;d>=0;d--)(n=h[d])&&(r=(o<3?n(r):o>3?n(e,t,r):n(e,t))||r);return o>3&&r&&Object.defineProperty(e,t,r),r},c;import{css as u,html as p,nothing as m}from"lit";import{customElement as b,property as l,state as f}from"lit/decorators.js";import{EspalierElementBase as g}from"../shared/esp-element-base.js";import"./esp-image-option.js";let s=c=class extends g{constructor(){super(...arguments),this.originalHeight=0,this.originalWidth=0,this.imageUrl="",this.localImage="",this.caption="",this.sizes="100vw",this.loading="eager",this.renderedWidth=0,this.resizeObserver=null,this.handleSlotChange=()=>{this.requestUpdate()}}get isPortrait(){return this.originalHeight>this.originalWidth}findProjected(){for(const e of this.children)if(e.tagName==="PICTURE"||e.tagName==="IMG")return e;return null}connectedCallback(){super.connectedCallback(),c.ensureProjectionStyles(this.getRootNode()),this.resizeObserver??=new ResizeObserver(e=>{const t=e[0]?.contentBoxSize?.[0],i=Math.round(t?t.inlineSize:e[0]?.contentRect.width??0);i>0&&i!==this.renderedWidth&&(this.renderedWidth=i)}),this.resizeObserver.observe(this)}disconnectedCallback(){super.disconnectedCallback(),this.resizeObserver?.disconnect(),this.resizeObserver=null}effectiveSizes(){return this.renderedWidth>0?`${this.renderedWidth}px`:this.sizes}buildSources(){const e=Array.from(this.querySelectorAll("esp-image-option")),t=new Map;for(const i of e){const o=i.getAttribute("url"),r=Number(i.getAttribute("width"));if(!o||!Number.isFinite(r)||r<=0)continue;const n=i.getAttribute("type")??"",d=t.get(n)??[];d.push({url:o,width:r}),t.set(n,d)}return Array.from(t,([i,o])=>({type:i,srcset:o.sort((r,n)=>r.width-n.width).map(r=>`${r.url} ${r.width}w`).join(", ")})).filter(i=>i.srcset.length>0)}willUpdate(e){super.willUpdate(e),(!this.hasUpdated||e.has("originalWidth")||e.has("originalHeight"))&&(this.originalWidth>0&&this.originalHeight>0?this.style.setProperty("--_esp-image-aspect-ratio",`${this.originalWidth} / ${this.originalHeight}`):this.style.removeProperty("--_esp-image-aspect-ratio"))}updated(e){if(super.updated(e),this.renderedWidth<=0)return;const t=this.findProjected();if(!t)return;const i=this.effectiveSizes();if(t.tagName==="PICTURE")for(const r of t.querySelectorAll("source"))r.setAttribute("sizes",i);const o=t.tagName==="IMG"?t:t.querySelector("img");o?.hasAttribute("srcset")&&o.setAttribute("sizes",i)}render(){if(this.localImage)return p`<img
+        src=${this.localImage}
+        alt=${this.caption}
+        decoding="async"
+        loading=${this.loading}
+      />`;const e=p`<slot @slotchange=${this.handleSlotChange}></slot>`;if(this.findProjected())return e;const t=this.buildSources();return p`<picture>
+        ${t.map(i=>p`<source
+              srcset=${i.srcset}
+              sizes=${this.effectiveSizes()}
+              type=${i.type||m}
+            />`)}
+        <img src=${this.imageUrl} alt=${this.caption} decoding="async" loading=${this.loading} />
+      </picture>
+      ${e}`}static ensureProjectionStyles(e){const t=e instanceof ShadowRoot?e:document.head;if(c.styledRoots.has(t))return;c.styledRoots.add(t);const i=document.createElement("style");i.textContent=c.projectionStyles,t.appendChild(i)}};s.projectionStyles=`
+    esp-image > picture,
+    esp-image > img {
+      display: block;
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+    }
+    esp-image > picture > img {
+      display: block;
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+    }
+  `,s.styledRoots=new WeakSet,s.styles=[...g.styles,u`
+      :host {
+        display: block;
+        aspect-ratio: var(--_esp-image-aspect-ratio, auto);
+        border: var(--esp-image-border, 2px solid var(--esp-color-border));
+        box-sizing: border-box;
+        border-radius: var(--esp-size-border-radius);
+        overflow: hidden;
+        position: relative;
+      }
+
+      picture {
+        display: block;
+        height: 100%;
+        width: 100%;
+      }
+
+      img {
+        display: block;
+        height: 100%;
+        width: 100%;
+        object-fit: cover;
+      }
+    `],a([l({attribute:"original-height",type:Number})],s.prototype,"originalHeight",void 0),a([l({attribute:"original-width",type:Number})],s.prototype,"originalWidth",void 0),a([l({attribute:"low-res",type:String})],s.prototype,"imageUrl",void 0),a([l({attribute:"local-image",type:String})],s.prototype,"localImage",void 0),a([l({type:String})],s.prototype,"caption",void 0),a([l({attribute:"sizes",type:String})],s.prototype,"sizes",void 0),a([l({attribute:"loading",type:String})],s.prototype,"loading",void 0),a([f()],s.prototype,"renderedWidth",void 0),s=c=a([b("esp-image")],s);export{s as EspalierImage};

package/dist/image-upload/esp-image-preview.js

@@ -0,0 +1,172 @@
+var i=function(l,e,t,s){var a=arguments.length,r=a<3?e:s===null?s=Object.getOwnPropertyDescriptor(e,t):s,p;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(l,e,t,s);else for(var d=l.length-1;d>=0;d--)(p=l[d])&&(r=(a<3?p(r):a>3?p(e,t,r):p(e,t))||r);return a>3&&r&&Object.defineProperty(e,t,r),r};import{css as g,html as c,nothing as v}from"lit";import{customElement as b,property as n}from"lit/decorators.js";import{classMap as m}from"lit/directives/class-map.js";import{createRef as f,ref as w}from"lit/directives/ref.js";import"../button/esp-button.js";import"../progress/esp-progress.js";import{EspalierElementBase as h}from"../shared/esp-element-base.js";import{ESP_EVENTS as u}from"../shared/events.js";let o=class extends h{constructor(){super(...arguments),this.image=f(),this.url="",this.alt="",this.failed=!1}render(){const e=this.progress!==void 0,t=this.failed&&!e,s=e?this.alt?`Cancel upload and remove ${this.alt}`:"Cancel upload and remove image":this.alt?`Remove ${this.alt}`:"Remove image";return c`<div>
+      <img ${w(this.image)} src=${this.url} alt=${this.alt} draggable="false" decoding="async" />
+      <button
+        type="button"
+        aria-label=${s}
+        class=${m({uploading:e})}
+        @click=${()=>{this.dispatchEvent(new CustomEvent(u.REMOVE_IMAGE,{detail:this,bubbles:!0,composed:!0}))}}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+          <path d="M18 6l-12 12" />
+          <path d="M6 6l12 12" />
+        </svg>
+      </button>
+      ${e?c`
+            <div class="upload-overlay">
+              <esp-progress
+                mode="circle"
+                size="small"
+                show-value
+                .value=${this.progress}
+                label="Upload progress"
+              ></esp-progress>
+            </div>
+          `:v}
+      ${t?c`
+            <div class="upload-overlay failed">
+              <svg
+                class="alert-icon"
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+                <path d="M12 9v4" />
+                <path
+                  d="M10.363 3.591l-8.106 13.534a1.914 1.914 0 0 0 1.636 2.871h16.214a1.914 1.914 0 0 0 1.636 -2.87l-8.106 -13.536a1.914 1.914 0 0 0 -3.274 0z"
+                />
+                <path d="M12 16h.01" />
+              </svg>
+              <span class="error-label">Upload failed</span>
+              <esp-button
+                class="retry-btn"
+                collapsed
+                label="Retry upload"
+                @clicked=${a=>{a.stopPropagation(),this.dispatchEvent(new CustomEvent(u.RETRY_UPLOAD,{detail:this,bubbles:!0,composed:!0}))}}
+              >
+                Retry
+              </esp-button>
+            </div>
+          `:v}
+    </div>`}};o.styles=[...h.styles,g`
+      :host {
+        display: block;
+        box-sizing: border-box;
+        position: relative;
+      }
+
+      div {
+        border-radius: var(--esp-size-border-radius);
+        border: 2px solid var(--esp-image-preview-border-color, var(--esp-color-border));
+        
+        box-sizing: border-box;
+        overflow: hidden;
+        height: 100%;
+
+        img {
+          width: 100%;
+          height: 100%;
+          object-fit: cover;
+          display: block;
+        }
+
+        button:not(.retry-btn) {
+          visibility: hidden;
+          display: grid;
+          place-content: center;
+          cursor: pointer;
+          background: oklch(from var(--esp-color-danger) var(--esp-l-raised-3) c h);
+          border: 2px solid oklch(from var(--esp-color-danger) var(--esp-l-border) c h);
+          color: var(--esp-image-preview-remove-color, var(--esp-color-danger-text));
+          padding: var(--esp-size-tiny);
+          border-radius: var(--esp-size-medium);
+          position: absolute;
+          top: var(--esp-size-padding);
+          right: var(--esp-size-padding);
+          box-shadow: 1px 1px 2px var(--esp-color-shadow);
+          transition: background 0.5s ease;
+          z-index: 2;
+
+          &:hover {
+            background: oklch(from var(--esp-color-danger) calc(var(--esp-l-raised-3) * 0.88) c h);
+            border-color: oklch(from var(--esp-color-danger) var(--esp-l-ink) c h);
+          }
+
+          &:active {
+            box-shadow: 0px 0px 0px oklch(from var(--esp-color-danger) var(--esp-l-shadow) c h);
+            border-color: oklch(from var(--esp-color-danger) var(--esp-l-shadow) c h);
+          }
+
+          svg {
+            height: var(--esp-size-medium);
+          }
+
+          
+          &.uploading {
+            visibility: visible;
+          }
+        }
+
+        &:hover,
+        &:focus-within {
+          button:not(.retry-btn) {
+            visibility: visible;
+          }
+        }
+      }
+
+      .upload-overlay {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+        background: oklch(from var(--esp-color-shadow) l c h / 0.6);
+        border-radius: var(--esp-size-border-radius);
+        z-index: 1;
+
+        esp-progress {
+          --esp-progress-text-color: var(
+            --esp-image-preview-overlay-text,
+            var(--esp-color-layer-1)
+          );
+        }
+
+        &.failed {
+          background: oklch(from var(--esp-color-danger) l c h / 0.75);
+          grid-template-rows: auto auto auto;
+          align-content: center;
+          gap: var(--esp-size-tiny);
+          color: var(--esp-image-preview-overlay-text, var(--esp-color-layer-1));
+        }
+      }
+
+      .alert-icon {
+        width: calc(2 * var(--esp-size-medium));
+        height: calc(2 * var(--esp-size-medium));
+        stroke: var(--esp-image-preview-overlay-text, var(--esp-color-layer-1));
+      }
+
+      .error-label {
+        font-size: var(--esp-type-small);
+        font-weight: 600;
+      }
+
+      .retry-btn {
+        --esp-color-action-background: transparent;
+        --esp-color-action-text: var(--esp-image-preview-overlay-text, var(--esp-color-layer-1));
+        --esp-color-border: var(--esp-image-preview-overlay-text, var(--esp-color-layer-1));
+      }
+    `],i([n()],o.prototype,"url",void 0),i([n()],o.prototype,"alt",void 0),i([n({type:Number})],o.prototype,"progress",void 0),i([n({type:Boolean})],o.prototype,"failed",void 0),o=i([b("esp-image-preview")],o);export{o as EspalierImagePreview};

package/dist/image-upload/esp-image-upload.d.ts

@@ -0,0 +1,178 @@
+import { type EspalierUploadImage, type ExistingImage } from "./image-helpers.js";
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+/**
+ * Used to upload images.
+ *
+ * ```html
+ * <esp-image-upload></esp-image-upload>
+ * ```
+ *
+ * **Uploading new images**
+ *
+ * The `file-selected` event detail provides the `image`
+ * reference (the actual object in `uploadedImages`) plus
+ * `onProgress`, `onComplete`, and `onFailed` callbacks
+ * bound to it, and a `signal` that aborts if the user removes
+ * the image while it is still uploading. The same shape is
+ * used for `upload-retry`.
+ *
+ * ```html
+ * <script>
+ *   // Stubs — replace with your real upload/delete logic.
+ *   function uploadToServer(file, opts) {
+ *     let pct = 0;
+ *     const id = setInterval(() => {
+ *       pct = Math.min(pct + 20, 100);
+ *       if (opts.onProgress) opts.onProgress(pct);
+ *       if (pct >= 100) { clearInterval(id); }
+ *     }, 200);
+ *     return new Promise((r) => setTimeout(() => r("id-" + file.name), 1200));
+ *   }
+ *   function deleteFromServer(id) { console.log("delete", id); }
+ *
+ *   const uploader = findByTagName("esp-image-upload")[0];
+ *   uploader.addEventListener("file-selected", (e) => {
+ *     const { image, signal, onProgress, onComplete, onFailed } = e.detail;
+ *     // Pass `signal` to fetch/XHR so removing the image cancels the upload.
+ *     uploadToServer(image.file, {
+ *       signal,
+ *       onProgress: (pct) => onProgress(pct),
+ *     }).then((id) => onComplete(id))
+ *       .catch(() => onFailed());
+ *   });
+ *   uploader.addEventListener("upload-retry", (e) => {
+ *     const { image, signal, onProgress, onComplete } = e.detail;
+ *     uploadToServer(image.file, {
+ *       signal,
+ *       onProgress: (pct) => onProgress(pct),
+ *     }).then((id) => onComplete(id));
+ *   });
+ *   uploader.addEventListener("file-removed", (e) => {
+ *     deleteFromServer(e.detail.uploadedId);
+ *   });
+ * </script>
+ * <esp-image-upload></esp-image-upload>
+ * ```
+ *
+ * **Simulated upload progress demo**
+ *
+ * Select images to see simulated progress. The second file
+ * will fail — click Retry to re-upload it.
+ *
+ * ```html
+ * <script>
+ *   const uploader = findByTagName("esp-image-upload")[0];
+ *   let fileIndex = 0;
+ *
+ *   function simulateUpload(detail, shouldFail) {
+ *     let progress = 0;
+ *     const interval = setInterval(() => {
+ *       progress += Math.floor(Math.random() * 11) + 5;
+ *       if (shouldFail && progress >= 45) {
+ *         clearInterval(interval);
+ *         detail.onFailed();
+ *         return;
+ *       }
+ *       if (progress >= 100) {
+ *         clearInterval(interval);
+ *         detail.onProgress(100);
+ *         setTimeout(() => detail.onComplete("id-" + detail.image.file.name), 500);
+ *         return;
+ *       }
+ *       detail.onProgress(progress);
+ *     }, 300 + Math.random() * 300);
+ *   }
+ *
+ *   uploader.addEventListener("file-selected", (e) => {
+ *     const idx = fileIndex++;
+ *     simulateUpload(e.detail, idx === 1);
+ *   });
+ *
+ *   uploader.addEventListener("upload-retry", (e) => {
+ *     simulateUpload(e.detail, false);
+ *   });
+ * </script>
+ * <esp-image-upload></esp-image-upload>
+ * ```
+ *
+ * **Editing with existing images**
+ *
+ * Pre-populate with server images via `setExistingImages`.
+ * Existing images never show upload overlays.
+ *
+ * ```html
+ * <script>
+ *   const uploader = findByTagName("esp-image-upload")[0];
+ *   uploader.setExistingImages([
+ *     { url: "https://picsum.photos/id/29/1200/800", width: 1200, height: 800, uploadedId: "img-1" },
+ *     { url: "https://picsum.photos/id/15/900/1200", width: 900,  height: 1200, uploadedId: "img-2" },
+ *   ]);
+ *   uploader.addEventListener("file-removed", (e) => {
+ *     if (e.detail.source === "existing") {
+ *       console.log("Mark for deletion:", e.detail.uploadedId);
+ *     }
+ *   });
+ * </script>
+ * <esp-image-upload></esp-image-upload>
+ * ```
+ *
+ * @event {CustomEvent<EspalierUploadImage>} file-removed - Fired when
+ * an image has been removed by the user. Narrow on `detail.source` to
+ * distinguish newly selected images from pre-existing server images.
+ * If the image's upload was still in flight, its `signal` aborts.
+ *
+ * @event {CustomEvent<UploadEventDetail>} file-selected - Fired when
+ * an image has been selected by the user. `detail.image` is the actual
+ * object stored in `uploadedImages`; `detail.onProgress`, `detail.onComplete`,
+ * and `detail.onFailed` are callbacks bound to that image. `detail.signal`
+ * aborts if the image is removed mid-upload — pass it to fetch/XHR.
+ *
+ * @event {CustomEvent<UploadEventDetail>} upload-retry - Fired when
+ * the user clicks Retry on a failed upload. `detail.image` is the same
+ * object reference; fresh callbacks and a fresh `signal` are provided.
+ * The component automatically resets the image to indeterminate progress.
+ *
+ * @event {CustomEvent<ImagesReorderedDetail>} images-reordered - Fired
+ * after the user drags an image to a new position. `detail.images` is the
+ * reordered array (same references, new order).
+ *
+ * @event {CustomEvent<FilesRejectedDetail>} files-rejected - Fired when
+ * selected files are skipped, either because their type is not accepted
+ * (`detail.unsupported`) or because they could not be read or decoded
+ * (`detail.unreadable`). The component also shows a transient inline notice.
+ *
+ * @cssprop --esp-image-upload-preview-background - The background color of the image preview area.
+ * @docPageTitle Image Upload
+ * @docUrl /components/image-upload
+ * @menuGroup Form Controls
+ * @menuLabel Image Upload
+ * @menuIcon photo-up
+ */
+export declare class EspalierImageUpload extends EspalierElementBase {
+    uploadedImages: Array<EspalierUploadImage>;
+    /**
+     * Comma-separated list of accepted file types, in the same format as the
+     * native input `accept` attribute: MIME types (`image/png`), MIME
+     * wildcards (`image/*`), or extensions (`.png`). Files outside this list
+     * are skipped and reported via the `files-rejected` event.
+     */
+    accept: string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Populate the component with images that already exist on the server.
+     * Each entry must provide a display URL, dimensions for layout, and
+     * an `uploadedId` that identifies the server-side image.
+     *
+     * Entries with missing `url`/`uploadedId` or non-finite/non-positive
+     * dimensions are silently filtered out.
+     */
+    setExistingImages: (images: ExistingImage[]) => void;
+    protected render(): import("lit-html").TemplateResult<1>;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-image-upload": EspalierImageUpload;
+    }
+}