@taprootio/espalier 2.0.0

package/dist/empty-state/esp-empty-state.js

@@ -0,0 +1,99 @@
+var l=function(o,t,e,n){var a=arguments.length,i=a<3?t:n===null?n=Object.getOwnPropertyDescriptor(t,e):n,r;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(o,t,e,n);else for(var c=o.length-1;c>=0;c--)(r=o[c])&&(i=(a<3?r(i):a>3?r(t,e,i):r(t,e))||i);return a>3&&i&&Object.defineProperty(t,e,i),i};import{css as m,html as g,nothing as f}from"lit";import{customElement as y,property as h,state as u}from"lit/decorators.js";import{classMap as v}from"lit/directives/class-map.js";import{EspalierElementBase as p}from"../shared/esp-element-base.js";import{getIconHrefForHost as z}from"../shared/intent-values.js";import{syncNormalizedAttribute as S}from"../shared/attribute-helpers.js";import{SlottedIconController as b}from"../shared/slotted-icon-controller.js";import{renderSpriteIcon as E}from"../shared/svgs/render-sprite-icon.js";import{createRef as w,ref as d}from"lit/directives/ref.js";function x(o){return o==="large"?"large":"medium"}let s=class extends p{constructor(){super(...arguments),this.iconSlot=new b(this),this.actionSlot=w(),this.sizeBacker="medium",this.hasSlottedAction=!1,this.icon="",this.handleActionSlotChange=()=>{this.hasSlottedAction=(this.actionSlot.value?.assignedElements({flatten:!0}).length??0)>0}}get size(){return this.sizeBacker}set size(t){const e=this.sizeBacker;this.sizeBacker=x(t),this.requestUpdate("size",e),S(this,"size",this.sizeBacker)}render(){const t=z(this.icon,this),e=this.iconSlot.hasSlottedIcon(),n=e||t.length>0,a=this.hasSlottedAction||this.querySelector('[slot="action"]')!==null,i={"empty-state":!0,[`size-${this.size}`]:!0,"has-icon":n,"has-action":a};return g`
+      <section part="empty-state" class=${v(i)}>
+        <span part="icon" class="icon" aria-hidden="true">
+          <slot
+            name="icon"
+            ${d(this.iconSlot.slotRef)}
+            @slotchange=${this.iconSlot.handleSlotChange}
+          ></slot>
+          ${!e&&t?E(t):f}
+        </span>
+        <div part="heading" class="heading"><slot name="heading"></slot></div>
+        <div part="body" class="body"><slot></slot></div>
+        <div part="action" class="action">
+          <slot
+            name="action"
+            ${d(this.actionSlot)}
+            @slotchange=${this.handleActionSlotChange}
+          ></slot>
+        </div>
+      </section>
+    `}};s.styles=[...p.styles,m`
+      :host {
+        display: block;
+        color: var(--esp-color-text);
+        font-family: var(--esp-font-body);
+      }
+
+      .empty-state {
+        display: grid;
+        justify-items: center;
+        align-content: center;
+        text-align: center;
+        max-width: 56ch;
+        margin-inline: auto;
+        gap: var(--esp-size-tiny);
+      }
+
+      .size-medium {
+        padding: var(--esp-size-normal);
+      }
+
+      .size-large {
+        min-height: min(34rem, 60vh);
+        padding: var(--esp-size-large);
+        gap: var(--esp-size-small);
+      }
+
+      .icon {
+        display: none;
+        width: var(--esp-size-large);
+        height: var(--esp-size-large);
+        color: var(--esp-color-headings);
+      }
+
+      .has-icon .icon {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+      }
+
+      .generated-icon,
+      .icon ::slotted(svg) {
+        width: 100%;
+        height: 100%;
+      }
+
+      .size-large .icon {
+        width: var(--esp-size-huge);
+        height: var(--esp-size-huge);
+      }
+
+      .heading {
+        color: var(--esp-color-text);
+        font-family: var(--esp-font-headings);
+        font-size: var(--esp-type-medium);
+        font-weight: var(--esp-font-weight-headings);
+        line-height: 1.2;
+      }
+
+      .size-large .heading {
+        font-size: var(--esp-type-big);
+      }
+
+      .body {
+        color: var(--esp-color-headings);
+        font-size: var(--esp-size-font);
+        line-height: 1.5;
+      }
+
+      .action {
+        display: none;
+        justify-content: center;
+        margin-top: var(--esp-size-tiny);
+      }
+
+      .has-action .action {
+        display: flex;
+      }
+    `],l([u()],s.prototype,"hasSlottedAction",void 0),l([h({type:String})],s.prototype,"icon",void 0),l([h({type:String,reflect:!0})],s.prototype,"size",null),s=l([y("esp-empty-state")],s);export{s as EspalierEmptyState};

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

@@ -0,0 +1,57 @@
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+import "../button/esp-button.js";
+/**
+ * Used to upload files.
+ *
+ * ```html
+ * <esp-file-upload choose-text="Upload Document"></esp-file-upload>
+ * <script>
+ *   const theFileUpload = findByTagName("esp-file-upload")[0];
+ *   theFileUpload.addEventListener("files-selected", () => {
+ *     showToast({
+ *       message: `You selected a file!`,
+ *       icon: "info-i",
+ *       duration: 2,
+ *       onClosed: () => {
+ *         theFileUpload.finishedProcessingFiles();
+ *       },
+ *     });
+ *   });
+ * </script>
+ * ```
+ *
+ * @docPageTitle File Upload
+ * @docUrl /components/file-upload
+ * @menuGroup Form Controls
+ * @menuLabel File Upload
+ * @menuIcon upload
+ * @customElement esp-file-upload
+ */
+export declare class EspalierFileUpload extends EspalierElementBase {
+    /**
+     * The accepted file types. For example, to allow JPEG, PNG, and WebP images:
+     *
+     * `image/jpeg, image/png, image/webp`
+     */
+    accept: string;
+    /**
+     * The text to display on the button.
+     */
+    chooseText: string;
+    /**
+     * Allow multiple files to be selected.
+     */
+    multiple: boolean;
+    /**
+     * The `files-selected` event sets the file upload to a processing state.
+     * Call this method when you have finished processing the selected files
+     * to reset the file upload.
+     */
+    finishedProcessingFiles(): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-file-upload": EspalierFileUpload;
+    }
+}

package/dist/file-upload/esp-file-upload.js

@@ -0,0 +1,15 @@
+var s=function(o,e,l,p){var r=arguments.length,t=r<3?e:p===null?p=Object.getOwnPropertyDescriptor(e,l):p,u;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")t=Reflect.decorate(o,e,l,p);else for(var n=o.length-1;n>=0;n--)(u=o[n])&&(t=(r<3?u(t):r>3?u(e,l,t):u(e,l))||t);return r>3&&t&&Object.defineProperty(e,l,t),t};import{customElement as c,property as a,state as h}from"lit/decorators.js";import{EspalierElementBase as f}from"../shared/esp-element-base.js";import{html as d}from"lit-html";import"../button/esp-button.js";import{uploadSVG as m}from"../shared/svgs/upload.js";import{createRef as v,ref as b}from"lit/directives/ref.js";let i=class extends f{constructor(){super(...arguments),this.uploadInput=v(),this.processingFiles=!1,this.accept="*",this.chooseText="Choose File",this.multiple=!1,this.filesSelected=async e=>{this.uploadInput.value&&(this.processingFiles=!0,this.dispatchEvent(new CustomEvent("files-selected",{detail:e,bubbles:!0,composed:!0})))}}finishedProcessingFiles(){this.processingFiles=!1,this.uploadInput.value&&(this.uploadInput.value.value="")}render(){return d`<esp-button
+        .label="${this.chooseText}"
+        .loading=${this.processingFiles}
+        @click=${()=>{this.uploadInput.value?.click()}}
+      >
+        ${m}
+      </esp-button>
+      <input
+        ${b(this.uploadInput)}
+        type="file"
+        ?multiple=${this.multiple}
+        .accept=${this.accept}
+        hidden
+        @change=${()=>{!this.uploadInput.value||!this.uploadInput.value.files||this.filesSelected(this.uploadInput.value.files)}}
+      />`}};s([h()],i.prototype,"processingFiles",void 0),s([a({attribute:"accept",type:String})],i.prototype,"accept",void 0),s([a({attribute:"choose-text",type:String})],i.prototype,"chooseText",void 0),s([a({attribute:"multiple",type:Boolean})],i.prototype,"multiple",void 0),i=s([c("esp-file-upload")],i);export{i as EspalierFileUpload};

package/dist/font-picker/esp-font-picker.d.ts

@@ -0,0 +1,153 @@
+import "../pickers/esp-pick-one.js";
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+import { type EspalierFormField } from "../form-item/esp-form-item.js";
+import { type PropertyValues } from "lit";
+export type GoogleFont = {
+    family: string;
+    variants: string[];
+    subsets: string[];
+    version: string;
+    lastModified: string;
+    files?: Record<string, string>;
+    category: FontCategory;
+    kind: string;
+};
+export type FontCategory = "serif" | "sans-serif" | "display" | "handwriting" | "monospace" | "not-display";
+export type FontSource = "google" | "web-safe";
+export type WebSafeFont = {
+    family: string;
+    stack: string;
+    category: Extract<FontCategory, "serif" | "sans-serif" | "monospace">;
+    kind: "web-safe";
+};
+export type FontPickerFont = GoogleFont | WebSafeFont;
+export type FontPickerValueChangedDetail = FontPickerFont | undefined;
+export declare const WEB_SAFE_FONTS: Array<WebSafeFont>;
+/**
+ * Load the font catalog from the build-generated `font-definitions.json`
+ * file served alongside the font CSS files.  The JSON is fetched from
+ * `{fontCSSRoot}font-definitions.json` where `fontCSSRoot` comes from
+ * the nearest `<esp-root>` element's `font-css-root` attribute.
+ *
+ * Results are cached at the module level so only one fetch occurs per page.
+ */
+export declare const getGoogleFonts: () => Promise<Array<GoogleFont>>;
+/**
+ * Build the CSS `font-family` value used by picker items.
+ * Consumers should reference this when setting `styles.fontFamily`
+ * on picker items to match the preview `@font-face` name.
+ */
+export declare const previewFontFamily: (family: string) => string;
+/**
+ * Font picker component backed by the Google Fonts catalog by default.
+ *
+ * The font catalog is loaded at runtime from a build-generated
+ * `font-definitions.json` file served alongside the individual font CSS
+ * files.  Run `npm run build-fonts` to generate both assets.
+ *
+ * Set `font-source="web-safe"` for email editors or other places where
+ * the picker should offer only CSS font stacks that do not need font
+ * downloads.
+ *
+ * **Required setup:**
+ * 1. Serve the `css/fonts/` directory under a public path.
+ * 2. Point `<esp-root font-css-root="/your/path/">` at that path.
+ *
+ * ```html
+ * <esp-root font-css-root="/css/fonts/">
+ *   <esp-form-item label="Pick a font">
+ *     <esp-font-picker></esp-font-picker>
+ *   </esp-form-item>
+ * </esp-root>
+ * ```
+ *
+ * ```html
+ * <esp-form-item label="Email font">
+ *   <esp-font-picker font-source="web-safe"></esp-font-picker>
+ * </esp-form-item>
+ * ```
+ *
+ * @event {CustomEvent<FontPickerValueChangedDetail>} value-changed - Fired
+ * when the user selects a font
+ *
+ * @customElement esp-font-picker
+ * @docPageTitle Font Picker
+ * @docUrl /components/font-picker
+ * @menuGroup Form Controls
+ * @menuLabel Font Picker
+ * @menuIcon typography
+ */
+export declare class EspalierFontPicker extends EspalierElementBase implements EspalierFormField {
+    /**
+     * Category of fonts to display in the picker.
+     *
+     * If not set, all font categories are displayed.
+     *
+     * ```html
+     * <esp-box>
+     *   <h2>Monospace Fonts</h2>
+     *   <esp-form-item label="Pick a font">
+     *     <esp-font-picker category="monospace"></esp-font-picker>
+     *   </esp-form-item>
+     * </esp-box>
+     * ```
+     */
+    category: FontCategory | null;
+    /**
+     * Source of fonts to display. `google` preserves the default Google
+     * Fonts catalog behavior. `web-safe` shows email-safe/system CSS
+     * font stacks and does not load Google font assets.
+     *
+     * ```html
+     * <esp-box>
+     *   <h2>Email-safe fonts</h2>
+     *   <esp-form-item label="Pick a font stack">
+     *     <esp-font-picker font-source="web-safe"></esp-font-picker>
+     *   </esp-form-item>
+     * </esp-box>
+     * ```
+     */
+    fontSource: FontSource;
+    /**
+     * The selected font family or CSS font stack.
+     *
+     * In the default Google Fonts mode this is the font family name, such
+     * as `"Aclonica"`. In `font-source="web-safe"` mode this is the full CSS
+     * font stack, such as `"Arial, Helvetica, sans-serif"`, so pre-selection
+     * via the `value` attribute must use the stack value.
+     *
+     * ```html
+     * <esp-box>
+     *   <h2>Have Aclonica pre-selected</h2>
+     *   <esp-form-item label="Pick a font">
+     *     <esp-font-picker value="Aclonica"></esp-font-picker>
+     *   </esp-form-item>
+     * </esp-box>
+     * ```
+     */
+    value: string;
+    /**
+     * The placeholder text for the picker input.
+     *
+     * @type {string}
+     */
+    placeholder: string;
+    /**
+     * Focus the picker input.
+     */
+    focus(): void;
+    protected getUpdateComplete(): Promise<boolean>;
+    protected firstUpdated(_changedProperties: PropertyValues): void;
+    protected updated(changedProperties: PropertyValues): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+}
+/**
+ * Reset the module-level font cache.  Exposed for test cleanup so each
+ * test starts with a fresh slate.
+ */
+export declare const resetFontCache: () => void;
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-font-picker": EspalierFontPicker;
+    }
+}

package/dist/font-picker/esp-font-picker.js

@@ -0,0 +1,9 @@
+var u=function(t,e,o,n){var a=arguments.length,s=a<3?e:n===null?n=Object.getOwnPropertyDescriptor(e,o):n,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(t,e,o,n);else for(var c=t.length-1;c>=0;c--)(l=t[c])&&(s=(a<3?l(s):a>3?l(e,o,s):l(e,o))||s);return a>3&&s&&Object.defineProperty(e,o,s),s};import"../pickers/esp-pick-one.js";import{customElement as I,property as p,state as G}from"lit/decorators.js";import{EspalierElementBase as A}from"../shared/esp-element-base.js";import{html as N}from"lit";const F=[{family:"Arial / Helvetica",stack:"Arial, Helvetica, sans-serif",category:"sans-serif",kind:"web-safe"},{family:"Georgia / Times New Roman",stack:'Georgia, "Times New Roman", Times, serif',category:"serif",kind:"web-safe"},{family:"Verdana / Geneva",stack:"Verdana, Geneva, sans-serif",category:"sans-serif",kind:"web-safe"},{family:"Tahoma / Geneva",stack:"Tahoma, Geneva, sans-serif",category:"sans-serif",kind:"web-safe"},{family:"Trebuchet MS",stack:'"Trebuchet MS", Arial, sans-serif',category:"sans-serif",kind:"web-safe"},{family:"Courier New",stack:'"Courier New", Courier, monospace',category:"monospace",kind:"web-safe"},{family:"System Sans",stack:'-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',category:"sans-serif",kind:"web-safe"},{family:"System Serif",stack:'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',category:"serif",kind:"web-safe"},{family:"System Monospace",stack:'ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", "Courier New", monospace',category:"monospace",kind:"web-safe"}];let f,m=!1;const U=async()=>{if(f)return f;if(m){for(;!f;)await new Promise(n=>setTimeout(n,100));return f}m=!0;const t=document.getElementsByTagName("esp-root")[0];if(!t)throw new Error("<esp-font-picker> requires an <esp-root> ancestor. Wrap your application in <esp-root> to use the font picker.");const e=t.fontDefinitionsUrl||`${t.fontCSSRoot}font-definitions.json`,o=await fetch(e);if(!o.ok)throw m=!1,new Error(`Failed to load font definitions from ${e} (${o.status}). Run 'npm run build-fonts' to generate the font catalog.`);return f=await o.json(),f},k="esp-preview-",V=t=>`${k}${t}`,d=new Map,g=async t=>{if(d.has(t))return!0;try{const e=document.getElementsByTagName("esp-root")[0];if(!e)return!1;const o=t.replaceAll(" ","-"),n=await fetch(`${e.fontCSSRoot}${o}.css`);if(!n.ok)return!1;let a=await n.text();a=a.replace(/font-family:\s*'([^']+)'/g,(l,c)=>`font-family: '${k}${c}'`);const s=document.createElement("style");return s.textContent=a,s.dataset.font=t,document.head.appendChild(s),d.set(t,s),!0}catch(e){return console.warn(`Failed to load CSS for font ${t}:`,e),!1}},v=t=>{const e=d.get(t);e&&(e.remove(),d.delete(t))},S="data-esp-font-picker",b="data-esp-font-picker-root",C=t=>t.closest("esp-root"),E=t=>C(t)?.correlationId??"",R=(t,e)=>`link[${S}="${CSS.escape(t)}"][${b}="${CSS.escape(e)}"]`,w=(t,e)=>{if(!e)return;const o=C(t),n=o?.correlationId??"";if(o?.googleFontLoading==="none"){h(t,e);return}if(document.head.querySelector(R(e,n)))return;const a=encodeURIComponent(e),s=document.createElement("link");s.rel="stylesheet",s.href=`https://fonts.googleapis.com/css2?family=${a}&display=swap`,s.setAttribute(S,e),s.setAttribute(b,n),document.head.appendChild(s)},h=(t,e)=>{if(!e)return;const o=E(t);if(Array.from(document.getElementsByTagName("esp-font-picker")).some(s=>E(s)===o&&s.fontSource==="google"&&s.value===e))return;document.head.querySelector(R(e,o))?.remove()},_=t=>t.kind!=="web-safe",y=t=>_(t)?t.family:t.stack,x=t=>_(t)?`${V(t.family)}, "${t.family}"`:t.stack,T=(t,e)=>t.filter(o=>{switch(e){case"not-display":return o.category!=="display";default:return o.category===e}});let r=class extends A{constructor(){super(...arguments),this.loadedFonts=new Set,this._rangeGeneration=0,this._initGeneration=0,this._fontsReady=Promise.resolve(),this.fonts=[],this.category=null,this.fontSource="google",this.value="",this.placeholder="Choose a font...",this.handleItemsInViewEvent=e=>{e.stopPropagation(),this.handleItemsInView(e.detail)}}focus(){this.shadowRoot?.querySelector("esp-pick-one")?.focus()}async getUpdateComplete(){const e=await super.getUpdateComplete();return await this._fontsReady,e}firstUpdated(e){super.firstUpdated(e),this._fontsReady=this.initFonts()}updated(e){super.updated(e);const o=e.has("fontSource")&&e.get("fontSource")!==void 0,n=e.has("category")&&e.get("category")!==void 0;if(o||n){if(e.get("fontSource")==="google"&&this.fontSource==="web-safe"){const a=this.value;for(const s of this.loadedFonts)v(s);this.loadedFonts.clear(),this.value="",a&&h(this,a)}this._fontsReady=this.initFonts()}if(e.has("value")&&this.value&&this.fontSource==="google"){const a=e.get("value");a!==this.value&&this.ensureFontLoaded(this.value,a)}}async ensureFontLoaded(e,o){await g(e)&&this.loadedFonts.add(e),this.value===e&&(w(this,e),o&&o!==e&&h(this,o))}async initFonts(){const e=++this._initGeneration;if(this.fontSource==="web-safe"){this.fonts=this.category?T(F,this.category):F;return}const o=await U();if(!(e!==this._initGeneration||this.fontSource!=="google")&&(this.fonts=this.category?T(o,this.category):o,this.value&&this.fonts.some(n=>y(n)===this.value))){const n=this.value;if(await g(n)){if(e!==this._initGeneration||this.fontSource!=="google"||this.value!==n){v(n);return}this.loadedFonts.add(n)}if(e!==this._initGeneration||this.fontSource!=="google"||this.value!==n)return;w(this,n)}}async handleItemsInView(e){if(this.fontSource==="web-safe")return;const o=++this._rangeGeneration,n=3,a=e.items??[],s=new Set,l=Math.max(0,e.first),c=Math.min(e.last+n,a.length);for(let i=l;i<c;i++)s.add(a[i].value);for(const i of s)this.loadedFonts.has(i)||await g(i)&&this.loadedFonts.add(i);if(o!==this._rangeGeneration)return;const $=new Set(Array.from(document.getElementsByTagName("esp-font-picker")).map(i=>i.value).filter(Boolean));for(const i of this.loadedFonts)$.has(i)||s.has(i)||(this.loadedFonts.delete(i),v(i))}render(){return N`<esp-pick-one
+      typeahead
+      .pickerItems=${this.fonts.map(e=>({text:e.family,value:y(e),selected:this.value===y(e),styles:{fontFamily:x(e)}}))}
+      .value=${this.value}
+      .placeholder=${this.placeholder}
+      @range-changed=${this.handleItemsInViewEvent}
+      @value-changed=${async e=>{e.stopPropagation();const o=this.value;if(!e.detail){this.value="",o&&h(this,o),this.dispatchEvent(new CustomEvent("value-changed",{detail:void 0,bubbles:!0,composed:!0}));return}const n=this.fonts.find(a=>y(a)===e.detail.value);this.value=e.detail.value,this.fontSource==="google"&&(await g(this.value)&&this.loadedFonts.add(this.value),w(this,this.value),o&&o!==this.value&&h(this,o)),this.dispatchEvent(new CustomEvent("value-changed",{detail:n,bubbles:!0,composed:!0}))}}
+    >
+    </esp-pick-one>`}};u([G()],r.prototype,"fonts",void 0),u([p({attribute:"category",type:String})],r.prototype,"category",void 0),u([p({attribute:"font-source",type:String})],r.prototype,"fontSource",void 0),u([p({type:String})],r.prototype,"value",void 0),u([p({type:String})],r.prototype,"placeholder",void 0),r=u([I("esp-font-picker")],r);const q=()=>{f=void 0,m=!1;for(const t of document.head.querySelectorAll("style[data-font]"))t.remove();d.clear();for(const t of document.head.querySelectorAll(`link[${S}]`))t.remove()};export{r as EspalierFontPicker,F as WEB_SAFE_FONTS,U as getGoogleFonts,V as previewFontFamily,q as resetFontCache};

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

@@ -0,0 +1,284 @@
+import { LitElement } from "lit";
+/**
+ * A form wrapper that renders a native `<form>` element in
+ * the light DOM. All form-associated custom elements placed
+ * inside participate natively in form submission, validation,
+ * and reset.
+ *
+ * `esp-form` has no visual presentation of its own — all
+ * styling, labels, and layout should be handled independently
+ * (e.g. via [esp-form-item](/components/form-item), `esp-box`,
+ * or plain CSS).
+ *
+ * ### Standard submission
+ *
+ * ```html
+ * <esp-form action="/api/save" method="post" label="Contact form">
+ *   <esp-form-item label="Name">
+ *     <esp-input name="name" required></esp-input>
+ *   </esp-form-item>
+ *   <esp-button button-type="submit" label="Send"></esp-button>
+ * </esp-form>
+ * ```
+ *
+ * ### Fetch submission
+ *
+ * ```html
+ * <esp-form action="/api/save" use-fetch use-json label="Settings">
+ *   <esp-form-item label="Email">
+ *     <esp-input name="email" input-type="email" required></esp-input>
+ *   </esp-form-item>
+ *   <esp-button button-type="submit" label="Save"></esp-button>
+ * </esp-form>
+ * ```
+ *
+ * ### Dialog integration
+ *
+ * When `method="dialog"`, submitting the form dispatches a
+ * `closeDialog` event that `esp-dialog` listens for, closing
+ * the dialog without a network request.
+ *
+ * ### Multi-field form with validation
+ *
+ * Required fields are validated on submit. The first invalid
+ * field is scrolled into view and focused. Errors clear as
+ * the user corrects each field. Use the `required-message`
+ * attribute on any form control to customize the error text.
+ *
+ * ```html
+ * <style>
+ * esp-form.signup-demo { display: grid; gap: var(--esp-size-small); }
+ * esp-form.signup-demo .actions { display: flex; gap: var(--esp-size-small); }
+ * </style>
+ * <esp-form class="signup-demo" use-fetch use-json action="/api/signup" label="Sign up">
+ *   <esp-form-item label="Full name">
+ *     <esp-input name="fullName" required required-message="We need your full name."></esp-input>
+ *   </esp-form-item>
+ *   <esp-form-item label="Email address">
+ *     <esp-input name="email" input-type="email" required></esp-input>
+ *   </esp-form-item>
+ *   <esp-form-item label="Password">
+ *     <esp-input name="password" input-type="password" required required-message="You must enter a password to continue!"></esp-input>
+ *   </esp-form-item>
+ *   <esp-form-item label="Favorite color">
+ *     <esp-pick-one name="color" required placeholder="Pick one..." required-message="Please choose your favorite color.">
+ *       <esp-picker-item text="Red" value="red"></esp-picker-item>
+ *       <esp-picker-item text="Green" value="green"></esp-picker-item>
+ *       <esp-picker-item text="Blue" value="blue"></esp-picker-item>
+ *     </esp-pick-one>
+ *   </esp-form-item>
+ *   <esp-form-item label="I agree to the terms">
+ *     <esp-checkbox name="terms" value="agreed" required required-message="You must accept the terms to continue.">
+ *       Yes, I accept
+ *     </esp-checkbox>
+ *   </esp-form-item>
+ *   <div class="actions">
+ *     <esp-button button-type="submit" label="Sign Up"></esp-button>
+ *     <esp-button button-type="reset" label="Reset" variant="danger"></esp-button>
+ *   </div>
+ * </esp-form>
+ * ```
+ *
+ * ### Skipping validation
+ *
+ * Add `formnovalidate` to a submit button to bypass constraint
+ * validation. This is useful for "Save Draft" buttons that
+ * should persist incomplete data.
+ *
+ * ```html
+ * <style>
+ * esp-form.draft-demo { display: grid; gap: var(--esp-size-small); }
+ * esp-form.draft-demo .actions { display: flex; gap: var(--esp-size-small); }
+ * </style>
+ * <esp-form class="draft-demo" use-fetch use-json action="/api/drafts" label="Article editor">
+ *   <esp-form-item label="Title">
+ *     <esp-input name="title" required></esp-input>
+ *   </esp-form-item>
+ *   <esp-form-item label="Category">
+ *     <esp-pick-one name="category" required placeholder="Select...">
+ *       <esp-picker-item text="Technology" value="tech"></esp-picker-item>
+ *       <esp-picker-item text="Design" value="design"></esp-picker-item>
+ *       <esp-picker-item text="Business" value="biz"></esp-picker-item>
+ *     </esp-pick-one>
+ *   </esp-form-item>
+ *   <div class="actions">
+ *     <esp-button button-type="submit" label="Publish"></esp-button>
+ *     <esp-button button-type="submit" formnovalidate label="Save Draft" variant="split-complementary-left"></esp-button>
+ *   </div>
+ * </esp-form>
+ * ```
+ *
+ * ### Handling the response
+ *
+ * Listen for `esp-submit-response` and `esp-submit-error` to
+ * react to the server's reply when using fetch submission.
+ *
+ * ```html
+ * <style>
+ * esp-form.response-demo { display: grid; gap: var(--esp-size-small); }
+ * </style>
+ * <esp-form class="response-demo" use-fetch use-json action="/api/feedback" label="Feedback">
+ *   <esp-form-item label="Your feedback">
+ *     <esp-input name="message" required></esp-input>
+ *   </esp-form-item>
+ *   <esp-button button-type="submit" label="Send Feedback"></esp-button>
+ *   <esp-info id="response-msg" icon="info-i" style="display:none">
+ *     <span id="response-text"></span>
+ *   </esp-info>
+ * </esp-form>
+ * <script>
+ *   const form = findByTagName("esp-form")[0];
+ *   const msg = findById("response-msg");
+ *   const text = findById("response-text");
+ *   form.addEventListener("esp-submit-response", (ev) => {
+ *     msg.style.display = "";
+ *     msg.setAttribute("variant", ev.detail.ok ? "success" : "warning");
+ *     text.textContent = ev.detail.ok
+ *       ? "Submitted successfully!"
+ *       : "Server returned an error.";
+ *   });
+ *   form.addEventListener("esp-submit-error", () => {
+ *     msg.style.display = "";
+ *     msg.setAttribute("variant", "danger");
+ *     text.textContent = "Network error — please try again.";
+ *   });
+ * </script>
+ * ```
+ *
+ * ### Form with diverse input types
+ *
+ * Combines email, telephone, number, and date inputs with
+ * validation and custom messages.
+ *
+ * ```html
+ * <style>
+ * esp-form.diverse-demo { display: grid; gap: var(--esp-size-small); }
+ * esp-form.diverse-demo .actions { display: flex; gap: var(--esp-size-small); }
+ * </style>
+ * <esp-form class="diverse-demo" use-fetch use-json action="/api/contact" label="Contact info">
+ *   <esp-form-item label="Email">
+ *     <esp-input name="email" input-type="email" required></esp-input>
+ *   </esp-form-item>
+ *   <esp-form-item label="Phone">
+ *     <esp-input name="phone" input-type="tel"
+ *       tel-localities="US CA GB" required>
+ *     </esp-input>
+ *   </esp-form-item>
+ *   <esp-form-item label="Age">
+ *     <esp-input name="age" input-type="number"
+ *       min="0" max="150" required>
+ *     </esp-input>
+ *   </esp-form-item>
+ *   <esp-form-item label="Date of birth">
+ *     <esp-input name="dob" input-type="date" required></esp-input>
+ *   </esp-form-item>
+ *   <esp-form-item label="Comments">
+ *     <esp-textarea name="comments" rows="3"
+ *       placeholder="Any additional comments...">
+ *     </esp-textarea>
+ *   </esp-form-item>
+ *   <div class="actions">
+ *     <esp-button button-type="submit" label="Submit"></esp-button>
+ *     <esp-button button-type="reset" label="Reset" variant="danger"></esp-button>
+ *   </div>
+ * </esp-form>
+ * ```
+ *
+ * @customElement esp-form
+ *
+ * @event {CustomEvent<{ formData: FormData; form: HTMLFormElement }>} esp-submit - Fired when `use-fetch` is true and the form passes validation. Cancelable; calling `preventDefault()` aborts the fetch.
+ * @event {CustomEvent<{ response: Response; ok: boolean }>} esp-submit-response - Fired after a successful `fetch` submission.
+ * @event {CustomEvent<{ error: unknown }>} esp-submit-error - Fired when a `fetch` submission fails.
+ * @event {CustomEvent} closeDialog - Fired when `method="dialog"` is used and the form requests its containing `<esp-dialog>` to close. The event detail is an empty object.
+ *
+ * @docPageTitle Form
+ * @docUrl /components/form
+ * @menuGroup Form Controls
+ * @menuLabel Form
+ * @menuIcon forms
+ */
+export declare class EspalierForm extends LitElement {
+    constructor();
+    /** Render into the host element itself (no shadow root). */
+    protected createRenderRoot(): this;
+    /**
+     * The URL that processes the form submission. When `use-fetch`
+     * is true this is the URL `fetch()` sends the request to.
+     *
+     * @type {string}
+     */
+    action: string;
+    /**
+     * The HTTP method for submission. Standard values are `get`,
+     * `post`, and `dialog`. When set to `dialog`, submitting the
+     * form closes the nearest `esp-dialog` ancestor without making
+     * a network request.
+     *
+     * @type {string}
+     */
+    method: string;
+    /**
+     * When true, constraint validation is skipped during
+     * submission.
+     *
+     * @type {boolean}
+     */
+    novalidate: boolean;
+    /**
+     * When true, the form uses `fetch()` instead of native
+     * browser navigation for submission. An `esp-submit` event
+     * is fired with the `FormData` in the detail, allowing
+     * consumers to cancel or modify the request.
+     *
+     * @type {boolean}
+     */
+    useFetch: boolean;
+    /**
+     * When `use-fetch` is true and this is also true, the request
+     * body is serialized as JSON instead of `FormData`.
+     *
+     * @type {boolean}
+     */
+    useJson: boolean;
+    /**
+     * The encoding type for form submission. Maps to the native
+     * `enctype` attribute on the inner `<form>`.
+     *
+     * @type {string}
+     */
+    enctype: string;
+    /**
+     * An accessible label applied as `aria-label` on the inner
+     * `<form>` element so the form is discoverable as an ARIA
+     * `form` landmark by screen readers.
+     *
+     * @type {string}
+     */
+    label: string;
+    connectedCallback(): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+    protected firstUpdated(): void;
+    protected updated(): void;
+    /**
+     * Run constraint validation on all controls without showing
+     * any UI feedback.
+     */
+    checkValidity(): boolean;
+    /**
+     * Run constraint validation, display error messages via each
+     * control's `esp-form-item`, and scroll the first invalid
+     * item into view.
+     *
+     * @returns `true` when every control is valid, `false` otherwise.
+     */
+    reportValidity(): boolean;
+    /** Programmatically reset the form and all its controls. */
+    reset(): void;
+    /** Programmatically trigger form submission (with validation). */
+    submit(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-form": EspalierForm;
+    }
+}

package/dist/form/esp-form.js

@@ -0,0 +1 @@
+var l=function(f,t,e,i){var n=arguments.length,s=n<3?t:i===null?i=Object.getOwnPropertyDescriptor(t,e):i,o;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")s=Reflect.decorate(f,t,e,i);else for(var r=f.length-1;r>=0;r--)(o=f[r])&&(s=(n<3?o(s):n>3?o(t,e,s):o(t,e))||s);return n>3&&s&&Object.defineProperty(t,e,s),s};import{LitElement as d,html as m}from"lit";import{customElement as b,property as h}from"lit/decorators.js";let a=class extends d{constructor(){super(),this._formReady=!1,this.action="",this.method="post",this.novalidate=!1,this.useFetch=!1,this.useJson=!1,this.enctype="application/x-www-form-urlencoded",this.label="",this._form=document.createElement("form"),this._form.noValidate=!0,this._form.addEventListener("submit",t=>this.handleSubmit(t)),this._form.addEventListener("keydown",t=>this.handleKeyDown(t))}createRenderRoot(){return this}connectedCallback(){if(!this._formReady){for(this._formReady=!0;this.firstChild;)this._form.appendChild(this.firstChild);this.appendChild(this._form)}super.connectedCallback()}render(){return this.syncFormAttributes(),m``}syncFormAttributes(){const t=this._form;this.action?t.action=this.action:t.removeAttribute("action"),t.method=this.method,t.enctype=this.enctype,this.label?t.setAttribute("aria-label",this.label):t.removeAttribute("aria-label")}firstUpdated(){this._form.parentElement||this.appendChild(this._form)}updated(){this._form.parentElement||this.appendChild(this._form)}checkValidity(){return this._form.checkValidity()}reportValidity(){const t=this._form,e=Array.from(t.querySelectorAll("esp-form-item"));let i=null,n=null;for(const o of e){const r=o.querySelector("[name], esp-input, esp-textarea, esp-pick-one, esp-pick-some, esp-checkbox, esp-checkbox-group, esp-radio-button-group, esp-date-picker, esp-color-picker");r&&("validate"in r&&typeof r.validate=="function"&&r.validate(),"checkValidity"in r&&typeof r.checkValidity=="function"&&!r.checkValidity()&&(i||(i=r,n=o)))}for(const o of Array.from(t.elements))"validate"in o&&typeof o.validate=="function"&&o.validate(),!i&&"checkValidity"in o&&typeof o.checkValidity=="function"&&!o.checkValidity()&&(i=o);return i?((n??i).scrollIntoView({behavior:"smooth",block:"center"}),typeof i.focus=="function"&&i.focus(),!1):!0}reset(){this._form.reset()}submit(){this._form.requestSubmit()}handleSubmit(t){if(this.method==="dialog"){t.preventDefault(),this.dispatchEvent(new CustomEvent("closeDialog",{detail:{},bubbles:!0,composed:!0}));return}let e=this.novalidate;const i=t.submitter;if(i&&(i.formNoValidate&&(e=!0),i.closest?.("esp-button")?.hasAttribute("formnovalidate")&&(e=!0)),!e&&!this.reportValidity()){t.preventDefault();return}if(this.useFetch){t.preventDefault(),this.submitViaFetch(this._form);return}}handleKeyDown(t){if(t.key!=="Enter")return;let e=t.target;for(;e&&e!==this._form;){if(e.hasAttribute("submit-on-enter")){t.preventDefault(),this._form.requestSubmit();return}e=e.parentElement}}async submitViaFetch(t){const e=new FormData(t),i=new CustomEvent("esp-submit",{detail:{formData:e,form:t},bubbles:!0,cancelable:!0});if(!this.dispatchEvent(i))return;const n=this.action||window.location.href,s=(this.method||"POST").toUpperCase();let o;const r={};if(s!=="GET")if(this.useJson){const c={};e.forEach((p,u)=>{c[u]=p}),o=JSON.stringify(c),r["Content-Type"]="application/json"}else o=e;try{const c=await fetch(n,{method:s,body:o,headers:r});this.dispatchEvent(new CustomEvent("esp-submit-response",{detail:{response:c,ok:c.ok},bubbles:!0}))}catch(c){this.dispatchEvent(new CustomEvent("esp-submit-error",{detail:{error:c},bubbles:!0}))}}};l([h({type:String})],a.prototype,"action",void 0),l([h({type:String})],a.prototype,"method",void 0),l([h({type:Boolean})],a.prototype,"novalidate",void 0),l([h({attribute:"use-fetch",type:Boolean})],a.prototype,"useFetch",void 0),l([h({attribute:"use-json",type:Boolean})],a.prototype,"useJson",void 0),l([h({type:String})],a.prototype,"enctype",void 0),l([h({type:String})],a.prototype,"label",void 0),a=l([b("esp-form")],a);export{a as EspalierForm};