@taprootio/espalier 2.0.0

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

@@ -0,0 +1,434 @@
+import { type PropertyValues } from "lit";
+import { type EspalierFormField } from "../form-item/esp-form-item.js";
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+/**
+ * Wraps a standard HTML input field,
+ * providing value binding, input validation, and programmatic
+ * focus for Espalier forms and UIs. It supports several input
+ * types, and has an `icon` attribute plus a slotted icon escape
+ * hatch.
+ *
+ * ```html
+ * <esp-box>
+ *   <h2>esp-input example</h2>
+ *   <p>Hello from the input!</p>
+ *   <esp-input
+ *     value="Hello from the input!"
+ *     icon="user-circle"
+ *     icon-label="Open user details">
+ *   </esp-input>
+ * </esp-box>
+ * <script>
+ *   const theInput = findByTagName("esp-input")[0];
+ *   const theP = findByTagName("p")[0];
+ *   theInput.addEventListener("value-changed", (ev) => {
+ *     theP.innerText = ev.detail.length ? ev.detail : "The input is empty...";
+ *   });
+ * </script>
+ * ```
+ *
+ * Input can have [color variants](/guides/colors/variants). Here are some examples:
+ *
+ * ```html
+ * <esp-input variant="split-complementary-left"></esp-input>
+ * <esp-input variant="analogous-left"></esp-input>
+ * ```
+ *
+ * ### Email validation
+ *
+ * Set `input-type="email"` to get built-in email validation. You
+ * can customize the error message with `validation-message`:
+ *
+ * ```html
+ * <esp-box>
+ *   <esp-form-item label="Email address">
+ *     <esp-input name="email" input-type="email" required
+ *       validation-message="Please enter a valid work email.">
+ *     </esp-input>
+ *   </esp-form-item>
+ * </esp-box>
+ * ```
+ *
+ * ### Number input with min/max
+ *
+ * ```html
+ * <esp-box>
+ *   <esp-form-item label="Quantity (1-100)">
+ *     <esp-input name="qty" input-type="number"
+ *       min="1" max="100" step="1" required>
+ *     </esp-input>
+ *   </esp-form-item>
+ * </esp-box>
+ * ```
+ *
+ * ### Telephone with locale-aware formatting
+ *
+ * The `tel` type uses phone localities to parse and format phone
+ * numbers on blur. The value is submitted as E.164 (e.g.
+ * `"+15551234567"`). Use `tel-localities` to specify which regions
+ * are accepted (space-separated region codes); when omitted, a
+ * sensible default set of 10 common regions is used.
+ *
+ * ```html
+ * <esp-box>
+ *   <esp-form-item label="Phone number">
+ *     <esp-input name="phone" input-type="tel"
+ *       tel-localities="US CA GB">
+ *     </esp-input>
+ *   </esp-form-item>
+ * </esp-box>
+ * ```
+ *
+ * ### Date input with locale-aware mask
+ *
+ * The `date` type displays a placeholder based on the user's
+ * locale (e.g. "MM/DD/YYYY"). The user types freely and the
+ * input parses the date on blur, submitting the value as
+ * ISO 8601 (`2025-01-15`).
+ *
+ * ```html
+ * <esp-box>
+ *   <esp-form-item label="Start date">
+ *     <esp-input name="startDate" input-type="date" required>
+ *     </esp-input>
+ *   </esp-form-item>
+ * </esp-box>
+ * ```
+ *
+ * @customElement esp-input
+ * @event {CustomEvent<string>} value-changed - Emitted when the input value changes.
+ * @event {CustomEvent} icon-clicked - Emitted when the icon action button is clicked.
+ *
+ * ```html
+ * <esp-box>
+ *   <esp-form-item label="Clickable icon">
+ *     <esp-input
+ *       value="Click the icon"
+ *       icon="circle-x"
+ *       icon-label="Clear value">
+ *     </esp-input>
+ *   </esp-form-item>
+ *   <p>Icon has not been clicked.</p>
+ * </esp-box>
+ * <script>
+ *   const theInput = findByTagName("esp-input")[0];
+ *   const theP = findByTagName("p")[0];
+ *   theInput.addEventListener("icon-clicked", () => {
+ *     theP.innerText = "Icon clicked!";
+ *   });
+ * </script>
+ * ```
+ *
+ * ```html
+ * <esp-box>
+ *   <p>Hello from the input!</p>
+ *   <esp-input value="Hello from the input!"></esp-input>
+ * </esp-box>
+ * <script>
+ *   const theInput = findByTagName("esp-input")[0];
+ *   const theP = findByTagName("p")[0];
+ *   theInput.addEventListener("value-changed", (ev) => {
+ *     theP.innerText = ev.detail.length ? ev.detail : "The input is empty...";
+ *   });
+ * </script>
+ * ```
+ *
+ * @slot - Optional custom SVG icon. Slotted icons override the
+ * generated SVG from the `icon` attribute.
+ *
+ * ```html
+ * <esp-input icon="user-circle" icon-label="Open user details"></esp-input>
+ * ```
+ *
+ * ```html
+ * <esp-input
+ *   name="affiliateLink"
+ *   value="https://example.com/?ref=taproot"
+ *   readonly
+ *   icon="external-link"
+ *   icon-label="Open affiliate link">
+ * </esp-input>
+ * ```
+ *
+ * @docPageTitle Input
+ * @docUrl /components/input
+ * @menuGroup Form Controls
+ * @menuLabel Input
+ * @menuIcon forms
+ *
+ * @implements {EspalierFormField}
+ */
+export declare class EspalierInput extends EspalierElementBase implements EspalierFormField {
+    static formAssociated: boolean;
+    /**
+     * A string value used for the id of the input field.
+     *
+     * ```html
+     * <esp-input field-name="username"></esp-input>
+     * ```
+     *
+     * @type {string}
+     */
+    fieldName: string;
+    /**
+     * Optional icon name from the configured Espalier SVG sprite.
+     * Slotted content remains supported and overrides this value.
+     *
+     * @type {string}
+     */
+    icon: string;
+    /**
+     * Accessible label for the icon action button. Consumers should
+     * provide a meaningful label whenever `icon` or a slotted icon
+     * represents an action. The trimmed value is applied as both
+     * `aria-label` and `title`; if omitted, the button falls back to
+     * a label derived from `icon`, then to a generic action label.
+     *
+     * ```html
+     * <esp-input icon="external-link" icon-label="Open affiliate link"></esp-input>
+     * ```
+     *
+     * @type {string}
+     */
+    iconLabel: string;
+    /**
+     * Specifies the type of input, such as text, email, password, etc.
+     * The `date` type provides a locale-aware placeholder mask —
+     * the user types a date freely, and the value is parsed and
+     * submitted as ISO 8601 on blur. The `tel` type provides
+     * phone locality matching — the user types digits and
+     * separators, and the value is parsed and submitted as E.164
+     * on blur.
+     *
+     * ```html
+     * <esp-input input-type="email"></esp-input>
+     * ```
+     *
+     * @type {"text" | "email" | "password" | "search" | "tel" | "url" | "number" | "date"}
+     */
+    inputType: "text" | "email" | "password" | "search" | "tel" | "url" | "number" | "date";
+    /**
+     * Placeholder text shown when no value is set. For `date`
+     * and `tel` inputs, an explicitly provided placeholder
+     * overrides the locale-derived placeholder. Set
+     * `placeholder=""` to suppress the derived placeholder.
+     *
+     * ```html
+     * <esp-input placeholder="Enter a value"></esp-input>
+     * ```
+     *
+     * @type {string | undefined}
+     */
+    placeholder: string | undefined;
+    /**
+     * A boolean value. When true, values the user enters are
+     * forced to lowercase.
+     *
+     * ```html
+     * <esp-input force-lowercase></esp-input>
+     * ```
+     *
+     * @type {boolean}
+     */
+    forceLowercase: boolean;
+    /**
+     * The value of the input. For `input-type="date"`, this is
+     * an ISO 8601 date string (e.g. `"2025-06-15"`). For
+     * `input-type="tel"`, this is an E.164 phone number
+     * (e.g. `"+15551234567"`).
+     *
+     * ```html
+     * <esp-input value="Hello World"></esp-input>
+     * ```
+     *
+     * @type {string}
+     */
+    value: string;
+    /**
+     * The name used when the input participates in a `<form>`.
+     *
+     * ```html
+     * <form>
+     *   <esp-input name="username" value="Jane Doe"></esp-input>
+     * </form>
+     * ```
+     *
+     * @type {string}
+     */
+    name: string;
+    /**
+     * When true, the field must have a value before the form can be
+     * submitted.
+     *
+     * ```html
+     * <esp-input required></esp-input>
+     * ```
+     *
+     * @type {boolean}
+     */
+    required: boolean;
+    /**
+     * A custom message to display when the field is required but empty.
+     * Defaults to `"Please fill out this field."` when not set.
+     *
+     * ```html
+     * <esp-input required required-message="You must enter your password to continue!"></esp-input>
+     * ```
+     *
+     * @type {string}
+     */
+    requiredMessage: string;
+    /**
+     * A custom message to display when the value doesn't match
+     * the expected type or pattern. The default depends on the
+     * input type (e.g. "Please enter a valid email address."
+     * for `input-type="email"`).
+     *
+     * ```html
+     * <esp-input input-type="email"
+     *   validation-message="This doesn't look like a valid email.">
+     * </esp-input>
+     * ```
+     *
+     * @type {string}
+     */
+    validationMessage: string;
+    /**
+     * When true, the input is disabled and cannot be interacted with.
+     *
+     * ```html
+     * <esp-input disabled></esp-input>
+     * ```
+     *
+     * @type {boolean}
+     */
+    disabled: boolean;
+    /**
+     * When true, the input value is submitted with forms but cannot
+     * be edited by the user. The icon action remains enabled unless
+     * `disabled` is also set.
+     *
+     * ```html
+     * <esp-input readonly value="Copy-only value"></esp-input>
+     * ```
+     *
+     * @type {boolean}
+     */
+    readonly: boolean;
+    /**
+     * A regular expression the value must match. Only applies to
+     * text-like types (text, email, url, tel, password, search).
+     *
+     * ```html
+     * <esp-input pattern="[A-Za-z]{3}" validation-message="Enter exactly 3 letters."></esp-input>
+     * ```
+     *
+     * @type {string | undefined}
+     */
+    pattern: string | undefined;
+    /**
+     * Minimum number of characters. Only applies to text-like types.
+     *
+     * @type {number | undefined}
+     */
+    minlength: number | undefined;
+    /**
+     * Maximum number of characters. Only applies to text-like types.
+     *
+     * @type {number | undefined}
+     */
+    maxlength: number | undefined;
+    /**
+     * Minimum value. For `input-type="number"` this is passed to
+     * the native input. For `input-type="date"` it is an ISO 8601
+     * date used for custom range validation.
+     *
+     * ```html
+     * <esp-input input-type="number" min="0"></esp-input>
+     * <esp-input input-type="date" min="2025-01-01"></esp-input>
+     * ```
+     *
+     * @type {string | undefined}
+     */
+    min: string | undefined;
+    /**
+     * Maximum value. For `input-type="number"` this is passed to
+     * the native input. For `input-type="date"` it is an ISO 8601
+     * date used for custom range validation.
+     *
+     * ```html
+     * <esp-input input-type="number" max="100"></esp-input>
+     * <esp-input input-type="date" max="2030-12-31"></esp-input>
+     * ```
+     *
+     * @type {string | undefined}
+     */
+    max: string | undefined;
+    /**
+     * Step value for `input-type="number"`.
+     *
+     * @type {number | undefined}
+     */
+    step: number | undefined;
+    /**
+     * Hint the browser about which virtual keyboard to show.
+     * When not set, a sensible default is chosen based on
+     * `input-type` (e.g. `"email"` for email, `"numeric"` for
+     * number and date).
+     *
+     * @type {string | undefined}
+     */
+    inputmode: string | undefined;
+    /**
+     * Space-separated list of region codes that defines which
+     * phone localities are accepted for `input-type="tel"`. The
+     * first locality whose format matches wins. When omitted,
+     * defaults to a set of 10 common regions.
+     *
+     * ```html
+     * <esp-input input-type="tel" tel-localities="US CA GB"></esp-input>
+     * ```
+     *
+     * @type {string | undefined}
+     */
+    telLocalities: string | undefined;
+    /**
+     * Focus the input element.
+     *
+     * ```html
+     * <div class="input-with-button">
+     *   <esp-input value="Click to focus -->"></esp-input>
+     *   <esp-button label="Focus" icon="arrow-big-left"></esp-button>
+     * </div>
+     * <script>
+     *   const theInput = findByTagName("esp-input")[0];
+     *   const theButton = findByTagName("esp-button")[0];
+     *   theButton.addEventListener("clicked", () => {
+     *     theInput.focus();
+     *   });
+     * </script>
+     * ```
+     *
+     */
+    focus(options?: FocusOptions): void;
+    /** Re-run constraint validation and dispatch `validity-changed`. */
+    validate(): void;
+    /** Check whether the current state is valid (delegates to ElementInternals). */
+    checkValidity(): boolean;
+    /** Called by the browser when the owning `<form>` is reset. */
+    formResetCallback(): void;
+    /** Called by the browser to restore form state (bfcache, etc.). */
+    formStateRestoreCallback(state: string): void;
+    /** Called by the browser when a parent `<fieldset>` is enabled or disabled. */
+    formDisabledCallback(isDisabled: boolean): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changedProperties: PropertyValues): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-input": EspalierInput;
+    }
+}

package/dist/input/esp-input.js

@@ -0,0 +1,91 @@
+var r=function(p,e,t,i){var a=arguments.length,l=a<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,o;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")l=Reflect.decorate(p,e,t,i);else for(var u=p.length-1;u>=0;u--)(o=p[u])&&(l=(a<3?o(l):a>3?o(e,t,l):o(e,t))||l);return a>3&&l&&Object.defineProperty(e,t,l),l};import{css as _,html as c,nothing as b}from"lit";import{customElement as T,property as n,state as y}from"lit/decorators.js";import{ifDefined as h}from"lit/directives/if-defined.js";import{createRef as D,ref as f}from"lit/directives/ref.js";import{EspalierElementBase as g}from"../shared/esp-element-base.js";import{FormFieldController as x}from"../shared/form-field-controller.js";import{getIconHrefForHost as v}from"../shared/intent-values.js";import{SlottedIconController as M}from"../shared/slotted-icon-controller.js";import{renderSpriteIcon as I}from"../shared/svgs/render-sprite-icon.js";import{detectDatePattern as P,parseDateInput as C,formatDateForLocale as d}from"./date-locale.js";import{getPhoneLocalities as S,parsePhoneInput as $,formatPhoneForLocale as L}from"./tel-locale.js";let s=class extends g{constructor(){super(...arguments),this.internals=this.attachInternals(),this.theInput=D(),this.iconSlot=new M(this),this.formCtrl=new x({host:this,internals:this.internals,getFormValue:()=>this.value||null,getValidity:()=>this._getValidity(),getValidationAnchor:()=>this.theInput.value??this,onReset:()=>{this.value="",this._dateDisplayText="",this._dateManaged=!1,this._telDisplayText="",this._telManaged=!1,this._hasVisibleError=!1},onRestore:e=>{this.value=e,this.inputType==="date"&&e&&this._restoreDateDisplay(e),this.inputType==="tel"&&e&&this._restoreTelDisplay(e)},onDisabled:e=>{this.disabled=e}}),this._hasVisibleError=!1,this._datePattern=null,this._dateDisplayText="",this._dateManaged=!1,this._phoneLocalitiesCache=null,this._telDisplayText="",this._telManaged=!1,this.fieldName="",this.icon="",this.iconLabel="",this.inputType="text",this.forceLowercase=!1,this.value="",this.name="",this.required=!1,this.requiredMessage="",this.validationMessage="",this.disabled=!1,this.readonly=!1,this._trackVisibleError=e=>{const t=e.detail;this._hasVisibleError=!t.valid}}_getDatePattern(){return this._datePattern||(this._datePattern=P()),this._datePattern}_getPhoneLocalities(){if(!this._phoneLocalitiesCache){const e=this.telLocalities?this.telLocalities.trim().split(/\s+/):void 0;this._phoneLocalitiesCache=S(e)}return this._phoneLocalitiesCache}get _nativeInputType(){return this.inputType==="date"?"text":this.inputType}get _effectiveInputmode(){if(this.inputmode)return this.inputmode;switch(this.inputType){case"email":return"email";case"url":return"url";case"tel":return"tel";case"number":return"decimal";case"date":return"numeric";default:return}}get _displayValue(){return this.inputType==="date"?this._dateDisplayText:this.inputType==="tel"?this._telDisplayText:this.value}get _effectivePlaceholder(){if(this.placeholder!==void 0)return this.placeholder;if(this.inputType==="date")return this._getDatePattern().placeholder;if(this.inputType==="tel"){const e=this._getPhoneLocalities();return e.length>0?e[0].placeholder:void 0}}handleInput(e){const t=e.target;if(this.readonly){t.value=this._displayValue;return}let i=t.value;if(this.inputType==="date"){const a=i.replace(/[^\d/\-.\s]/g,"");if(a!==i){const l=i.length-a.length,o=Math.max(0,(t.selectionStart??a.length)-l);t.value=a,t.setSelectionRange(o,o),i=a}this._dateDisplayText=i,this._dateManaged=!0,i||(this.value="",this._syncInput());return}if(this.inputType==="tel"){const a=i.replace(/[^\d+\-.()\s]/g,"");if(a!==i){const l=i.length-a.length,o=Math.max(0,(t.selectionStart??a.length)-l);t.value=a,t.setSelectionRange(o,o),i=a}this._telDisplayText=i,this._telManaged=!0,i||(this.value="",this._syncInput());return}this.forceLowercase&&(i=i.toLowerCase()),this.value=t.value=i,this._syncInput()}_syncInput(){this._hasVisibleError?this.formCtrl.syncValue():this.formCtrl.syncValueSilently(),this.emitValueChanged(this.value)}_handleBlur(){this.inputType==="date"&&this._finalizeDateValue(),this.inputType==="tel"&&this._finalizeTelValue(),this.formCtrl.syncValue()}_finalizeDateValue(){const e=this._dateDisplayText;if(!e.trim()){this.value="",this._dateDisplayText="",this._dateManaged=!1,this.emitValueChanged(this.value);return}const t=this._getDatePattern(),i=C(e,t);i?(this._dateDisplayText=d(i,t),this.value=i.toString()):this.value=e,this._dateManaged=!0,this.requestUpdate(),this.emitValueChanged(this.value)}_finalizeTelValue(){const e=this._telDisplayText;if(!e.trim()){this.value="",this._telDisplayText="",this._telManaged=!1,this.emitValueChanged(this.value);return}const t=this._getPhoneLocalities(),i=$(e,t);i?(this._telDisplayText=i.displayText,this.value=i.e164):this.value=e,this._telManaged=!0,this.requestUpdate(),this.emitValueChanged(this.value)}_getValidity(){if(this.inputType==="date")return this._getDateValidity();if(this.inputType==="tel")return this._getTelValidity();const e=this.theInput.value;if(e&&!e.validity.valid){const t=e.validity,i={valueMissing:t.valueMissing,typeMismatch:t.typeMismatch,patternMismatch:t.patternMismatch,tooLong:t.tooLong,tooShort:t.tooShort,rangeUnderflow:t.rangeUnderflow,rangeOverflow:t.rangeOverflow,stepMismatch:t.stepMismatch,badInput:t.badInput};return{flags:i,message:this._getFriendlyMessage(i)}}return this.required&&!this.value?{flags:{valueMissing:!0},message:this.requiredMessage||"Please fill out this field."}:null}_getFriendlyMessage(e){if(e.valueMissing)return this.requiredMessage||"Please fill out this field.";if(e.typeMismatch){if(this.validationMessage)return this.validationMessage;switch(this.inputType){case"email":return"Please enter a valid email address.";case"url":return"Please enter a valid URL.";case"number":return"Please enter a valid number.";case"tel":return"Please enter a valid phone number.";default:return"Please enter a valid value."}}return e.patternMismatch?this.validationMessage||"Please match the requested format.":e.tooShort?`Must be at least ${this.minlength} characters.`:e.tooLong?`Must be no more than ${this.maxlength} characters.`:e.rangeUnderflow?`Value must be ${this.min} or greater.`:e.rangeOverflow?`Value must be ${this.max} or less.`:(e.stepMismatch||e.badInput,"Please enter a valid value.")}_getDateValidity(){if(this.required&&!this.value)return{flags:{valueMissing:!0},message:this.requiredMessage||"Please fill out this field."};if(!this.value)return null;let e;try{e=Temporal.PlainDate.from(this.value)}catch{return{flags:{typeMismatch:!0},message:this.validationMessage||"Please enter a valid date."}}if(this.min)try{const t=Temporal.PlainDate.from(this.min);if(Temporal.PlainDate.compare(e,t)<0){const i=this._getDatePattern(),a=d(t,i);return{flags:{rangeUnderflow:!0},message:`Date must be ${a} or later.`}}}catch{}if(this.max)try{const t=Temporal.PlainDate.from(this.max);if(Temporal.PlainDate.compare(e,t)>0){const i=this._getDatePattern(),a=d(t,i);return{flags:{rangeOverflow:!0},message:`Date must be ${a} or earlier.`}}}catch{}return null}_getTelValidity(){return this.required&&!this.value?{flags:{valueMissing:!0},message:this.requiredMessage||"Please fill out this field."}:this.value?/^\+\d+$/.test(this.value)?null:{flags:{typeMismatch:!0},message:this.validationMessage||"Please enter a valid phone number."}:null}focus(e){this.focusResolvedElementAfterUpdate(()=>this.theInput.value,e)}validate(){this.formCtrl.validate()}checkValidity(){return this.formCtrl.checkValidity()}formResetCallback(){this.formCtrl.handleFormReset()}formStateRestoreCallback(e){this.formCtrl.handleFormStateRestore(e)}formDisabledCallback(e){this.formCtrl.handleFormDisabled(e)}connectedCallback(){super.connectedCallback(),this.addEventListener("validity-changed",this._trackVisibleError),this.inputType==="date"&&this.value&&this._restoreDateDisplay(this.value),this.inputType==="tel"&&this.value&&this._restoreTelDisplay(this.value)}disconnectedCallback(){super.disconnectedCallback(),this.removeEventListener("validity-changed",this._trackVisibleError)}updated(e){super.updated(e),e.has("value")&&this.inputType==="date"&&!this._dateManaged&&this._restoreDateDisplay(this.value),e.has("value")&&this.inputType==="tel"&&!this._telManaged&&this._restoreTelDisplay(this.value),e.has("telLocalities")&&(this._phoneLocalitiesCache=null),this._dateManaged=!1,this._telManaged=!1}_restoreDateDisplay(e){if(!e){this._dateDisplayText="";return}try{const t=Temporal.PlainDate.from(e),i=this._getDatePattern();this._dateDisplayText=d(t,i)}catch{this._dateDisplayText=e}}_restoreTelDisplay(e){if(!e){this._telDisplayText="";return}const t=this._getPhoneLocalities();this._telDisplayText=L(e,t)}_handleIconClick(){this.disabled||!(this.hasIconSlotContent||v(this.icon,this).length>0)||this.dispatchEvent(new CustomEvent("icon-clicked",{bubbles:!0,composed:!0}))}get hasIconSlotContent(){return this.iconSlot.hasSlottedIcon(":scope > :not([slot]), :scope > [slot='']")}_getIconButtonLabel(){const e=this.iconLabel.trim();if(e)return e;const t=this.icon.trim();return t?`${this._humanizeIconName(t)} action`:"Input icon action"}_humanizeIconName(e){const t=e.replace(/[-_]+/gu," ").trim();return t?t.charAt(0).toUpperCase()+t.slice(1):"Icon"}render(){const e=this.inputType==="date",t=this.inputType==="number",i=this.inputType==="tel",a=e||t||i,l=v(this.icon,this),o=this.hasIconSlotContent,u=o||l.length>0,m=this._getIconButtonLabel();return c`
+      <div class="esp-field">
+        <input
+          id=${this.fieldName}
+          ${f(this.theInput)}
+          .value=${this._displayValue}
+          @input=${this.handleInput}
+          @blur=${this._handleBlur}
+          type=${this._nativeInputType}
+          placeholder=${h(this._effectivePlaceholder)}
+          inputmode=${h(this._effectiveInputmode)}
+          pattern=${h(a?void 0:this.pattern)}
+          minlength=${h(a?void 0:this.minlength)}
+          maxlength=${h(a?void 0:this.maxlength)}
+          min=${h(e||i?void 0:this.min)}
+          max=${h(e||i?void 0:this.max)}
+          step=${h(e||i?void 0:this.step)}
+          ?required=${this.required}
+          ?disabled=${this.disabled}
+          ?readonly=${this.readonly}
+        />
+        ${u?c`
+              <button
+                class="icon-action"
+                type="button"
+                aria-label=${m}
+                title=${m}
+                ?disabled=${this.disabled}
+                @click=${this._handleIconClick}
+              >
+                <slot
+                  ${f(this.iconSlot.slotRef)}
+                  @slotchange=${this.iconSlot.handleSlotChange}
+                ></slot>
+                ${!o&&l?I(l):b}
+              </button>
+            `:c`
+              <span class="icon-slot-probe" hidden>
+                <slot
+                  ${f(this.iconSlot.slotRef)}
+                  @slotchange=${this.iconSlot.handleSlotChange}
+                ></slot>
+              </span>
+            `}
+      </div>
+    `}};s.formAssociated=!0,s.styles=[...g.styles,_`
+      .esp-field {
+        margin: 1px;
+        display: grid;
+        grid-template-columns: auto min-content;
+
+        &:focus-within {
+          border-width: 2px;
+          margin: 0;
+        }
+
+        > input {
+          grid-column: 1;
+        }
+
+        > .icon-action {
+          appearance: none;
+          cursor: pointer;
+          grid-column: 2;
+          display: grid;
+          place-content: center;
+          line-height: 1;
+          padding: 0;
+          width: auto;
+
+          &:focus-visible {
+            border-radius: max(0px, calc(var(--esp-size-border-radius) - 0.1rem));
+            box-shadow:
+              inset 0 0 0 2px var(--esp-field-focus-shadow, var(--esp-color-shadow)),
+              0 0 3px var(--esp-field-focus-shadow, var(--esp-color-shadow));
+          }
+
+          &:disabled {
+            cursor: not-allowed;
+          }
+
+          .generated-icon,
+          ::slotted(svg),
+          > svg {
+            height: calc(1.2 * var(--esp-size-font));
+            width: calc(1.2 * var(--esp-size-font));
+            margin: 0 var(--esp-size-tiny);
+          }
+        }
+      }
+    `],r([y()],s.prototype,"_dateDisplayText",void 0),r([y()],s.prototype,"_telDisplayText",void 0),r([n({attribute:"field-name",type:String})],s.prototype,"fieldName",void 0),r([n({type:String})],s.prototype,"icon",void 0),r([n({attribute:"icon-label",type:String})],s.prototype,"iconLabel",void 0),r([n({attribute:"input-type",type:String})],s.prototype,"inputType",void 0),r([n({type:String})],s.prototype,"placeholder",void 0),r([n({attribute:"force-lowercase",type:Boolean})],s.prototype,"forceLowercase",void 0),r([n({type:String})],s.prototype,"value",void 0),r([n({type:String,reflect:!0})],s.prototype,"name",void 0),r([n({type:Boolean,reflect:!0})],s.prototype,"required",void 0),r([n({attribute:"required-message"})],s.prototype,"requiredMessage",void 0),r([n({attribute:"validation-message"})],s.prototype,"validationMessage",void 0),r([n({type:Boolean,reflect:!0})],s.prototype,"disabled",void 0),r([n({type:Boolean,reflect:!0})],s.prototype,"readonly",void 0),r([n({type:String})],s.prototype,"pattern",void 0),r([n({type:Number})],s.prototype,"minlength",void 0),r([n({type:Number})],s.prototype,"maxlength",void 0),r([n({type:String})],s.prototype,"min",void 0),r([n({type:String})],s.prototype,"max",void 0),r([n({type:Number})],s.prototype,"step",void 0),r([n({type:String})],s.prototype,"inputmode",void 0),r([n({attribute:"tel-localities",type:String})],s.prototype,"telLocalities",void 0),s=r([T("esp-input")],s);export{s as EspalierInput};

package/dist/input/tel-locale.js

@@ -0,0 +1 @@
+const c=new Map([["US",{region:"US",callingCode:"1",nationalDigitCounts:[10],placeholder:"(555) 123-4567",formatNational:i=>`(${i.slice(0,3)}) ${i.slice(3,6)}-${i.slice(6,10)}`}],["CA",{region:"CA",callingCode:"1",nationalDigitCounts:[10],placeholder:"(555) 123-4567",formatNational:i=>`(${i.slice(0,3)}) ${i.slice(3,6)}-${i.slice(6,10)}`}],["GB",{region:"GB",callingCode:"44",nationalDigitCounts:[10,11],placeholder:"07911 123456",formatNational:i=>i.length===11?`${i.slice(0,5)} ${i.slice(5)}`:`${i.slice(0,5)} ${i.slice(5)}`}],["AU",{region:"AU",callingCode:"61",nationalDigitCounts:[9],placeholder:"0412 345 678",formatNational:i=>`${i.slice(0,4)} ${i.slice(4,7)} ${i.slice(7)}`}],["DE",{region:"DE",callingCode:"49",nationalDigitCounts:[10,11],placeholder:"0170 1234567",formatNational:i=>`${i.slice(0,4)} ${i.slice(4)}`}],["FR",{region:"FR",callingCode:"33",nationalDigitCounts:[9],placeholder:"06 12 34 56 78",formatNational:i=>`${i.slice(0,2)} ${i.slice(2,4)} ${i.slice(4,6)} ${i.slice(6,8)} ${i.slice(8)}`}],["IN",{region:"IN",callingCode:"91",nationalDigitCounts:[10],placeholder:"98765 43210",formatNational:i=>`${i.slice(0,5)} ${i.slice(5)}`}],["JP",{region:"JP",callingCode:"81",nationalDigitCounts:[10,11],placeholder:"090-1234-5678",formatNational:i=>i.length===11?`${i.slice(0,3)}-${i.slice(3,7)}-${i.slice(7)}`:`${i.slice(0,3)}-${i.slice(3,6)}-${i.slice(6)}`}],["BR",{region:"BR",callingCode:"55",nationalDigitCounts:[10,11],placeholder:"(11) 91234-5678",formatNational:i=>i.length===11?`(${i.slice(0,2)}) ${i.slice(2,7)}-${i.slice(7)}`:`(${i.slice(0,2)}) ${i.slice(2,6)}-${i.slice(6)}`}],["MX",{region:"MX",callingCode:"52",nationalDigitCounts:[10],placeholder:"55 1234 5678",formatNational:i=>`${i.slice(0,2)} ${i.slice(2,6)} ${i.slice(6)}`}]]),s=["US","CA","GB","AU","DE","FR","IN","JP","BR","MX"];function r(i){const t=i??s,o=[];for(const l of t){const n=l.toUpperCase(),e=c.get(n);e&&o.push(e)}return o}function g(i,t){if(!i.trim()||t.length===0)return null;const o=i.trimStart().startsWith("+"),l=i.replace(/\D/g,"");if(!l)return null;if(o){for(const n of t)if(l.startsWith(n.callingCode)){const e=l.slice(n.callingCode.length);if(n.nationalDigitCounts.includes(e.length))return a(n,e)}}for(const n of t)if(l.startsWith(n.callingCode)){const e=l.slice(n.callingCode.length);if(n.nationalDigitCounts.includes(e.length))return a(n,e)}for(const n of t)if(n.nationalDigitCounts.includes(l.length))return a(n,l);return null}function a(i,t){const o=`+${i.callingCode}${t}`,l=`+${i.callingCode} ${i.formatNational(t)}`;return{locality:i,e164:o,displayText:l}}function $(i,t){if(!i||!i.startsWith("+"))return i;const o=i.slice(1);for(const l of t)if(o.startsWith(l.callingCode)){const n=o.slice(l.callingCode.length);if(l.nationalDigitCounts.includes(n.length))return`+${l.callingCode} ${l.formatNational(n)}`}return i}export{s as DEFAULT_TEL_REGIONS,$ as formatPhoneForLocale,r as getPhoneLocalities,g as parsePhoneInput};

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

@@ -0,0 +1,81 @@
+import { LitElement, nothing, type PropertyValues } from "lit";
+import "../image/esp-image.js";
+import "../image/esp-image-option.js";
+import "../button/esp-button.js";
+/**
+ * A full-screen lightbox for viewing high-res versions of
+ * [esp-image](/components/image) elements. Point the `for` attribute
+ * at a CSS selector for the container that holds the images. Clicking
+ * any image in that container opens the lightbox at that image.
+ *
+ * On mobile, swipe left or right to navigate. The gallery wraps
+ * around — swiping past the last image goes back to the first.
+ *
+ * A subtle caret at the bottom of the screen reveals a drawer
+ * overlay containing the image caption and a `comments` slot.
+ *
+ * ```html
+ * <div class="gallery">
+ *   <esp-image caption="A mountain lake" original-width="1200" original-height="800" low-res="https://picsum.photos/id/29/300/200">
+ *     <esp-image-option width="400" url="https://picsum.photos/id/29/600/400"></esp-image-option>
+ *     <esp-image-option width="800" url="https://picsum.photos/id/29/900/600"></esp-image-option>
+ *     <esp-image-option width="1024" url="https://picsum.photos/id/29/1200/800"></esp-image-option>
+ *   </esp-image>
+ *   <esp-image caption="A forest path" original-width="1200" original-height="800" low-res="https://picsum.photos/id/15/300/200">
+ *     <esp-image-option width="400" url="https://picsum.photos/id/15/600/400"></esp-image-option>
+ *     <esp-image-option width="800" url="https://picsum.photos/id/15/900/600"></esp-image-option>
+ *     <esp-image-option width="1024" url="https://picsum.photos/id/15/1200/800"></esp-image-option>
+ *   </esp-image>
+ *   <esp-image caption="Ocean waves" original-width="1200" original-height="800" low-res="https://picsum.photos/id/65/300/200">
+ *     <esp-image-option width="400" url="https://picsum.photos/id/65/600/400"></esp-image-option>
+ *     <esp-image-option width="800" url="https://picsum.photos/id/65/900/600"></esp-image-option>
+ *     <esp-image-option width="1024" url="https://picsum.photos/id/65/1200/800"></esp-image-option>
+ *   </esp-image>
+ * </div>
+ * <esp-lightbox for=".gallery"></esp-lightbox>
+ * ```
+ *
+ * @event {CustomEvent<{ index: number }>} esp-lightbox-changed -
+ * Fired when the displayed image changes — on open, navigation
+ * (prev/next buttons, keyboard arrows, swipe, dot click).
+ * The `index` in the detail is the zero-based position of the
+ * now-visible image in the source container.
+ *
+ * @slot comments - A slot for comments UX, rendered inside a collapsible drawer.
+ * @cssprop --esp-lightbox-bg - The background color of the lightbox overlay (falls through to --esp-vellum-background, then --esp-color-layer-3).
+ * @cssprop --esp-lightbox-bg-opacity - The opacity of the overlay background (falls through to --esp-vellum-opacity, default: 0.85).
+ * @cssprop --esp-vellum-background-image - Optional repeating background image for the overlay (default: none).
+ * @cssprop --esp-vellum-background-image-opacity - Opacity of the background image layer (default: 0.3).
+ * @docPageTitle Lightbox
+ * @docUrl /components/lightbox
+ * @menuGroup Media
+ * @menuLabel Lightbox
+ * @menuIcon photo
+ */
+export declare class EspalierLightbox extends LitElement {
+    /**
+     * A CSS selector for the container element that holds the
+     * `esp-image` elements to include in the lightbox.
+     * @type {string}
+     */
+    for: string;
+    /**
+     * The number of comments to display in the comment bar.
+     * @type {number}
+     */
+    commentCount: number;
+    /** Open the lightbox at the given image index. */
+    open(index: number): void;
+    /** Close the lightbox. */
+    close(): void;
+    connectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
+    disconnectedCallback(): void;
+    protected render(): import("lit-html").TemplateResult<1> | typeof nothing;
+    static styles: import("lit").CSSResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-lightbox": EspalierLightbox;
+    }
+}