@taprootio/espalier 2.0.0

package/dist/shared/events.d.ts

@@ -0,0 +1,361 @@
+/**
+ * @module events
+ *
+ * Central registry for every CustomEvent dispatched by Espalier
+ * components.  Provides:
+ *
+ * 1. **Event name constants** — `ESP_EVENTS` for stringly-typed safety.
+ * 2. **Detail types** — one interface per distinct payload shape.
+ * 3. **Per-component event maps** — typed maps for `addEventListener`.
+ * 4. **Re-exports** — types that already exist in component files,
+ *    gathered here for single-import convenience.
+ *
+ * ```ts
+ * import {
+ *   ESP_EVENTS,
+ *   type EspalierInputEventMap,
+ * } from "@taprootio/espalier";
+ *
+ * const input = document.querySelector("esp-input")!;
+ * input.addEventListener(ESP_EVENTS.VALUE_CHANGED, (e) => {
+ *   // e.detail is typed as `string`
+ * });
+ * ```
+ */
+export { type GridClickedEvent, type GridDataStateEventDetail, type GridItemsChangedEventDetail, type GridLoadErrorEventDetail, type GridLoadStartEventDetail, type GridLoadSuccessEventDetail, } from "../grid/esp-grid.js";
+export { type DestroyEspalierInfo } from "../info/esp-info.js";
+export { type ValidityChangedDetail, type ValidationError, VALIDITY_CHANGED_EVENT, } from "./validation.js";
+export { type ToastConfig } from "./toast-events.js";
+export { type PickerItem } from "../pickers/esp-picker-item.js";
+export { type EspalierUploadImage } from "../image-upload/image-helpers.js";
+export { type FontPickerValueChangedDetail, type GoogleFont, type WebSafeFont, } from "../font-picker/esp-font-picker.js";
+import type { EspalierDetails } from "../details/esp-details.js";
+import type { ValidityChangedDetail } from "./validation.js";
+import type { GridClickedEvent, GridItemsChangedEventDetail, GridLoadErrorEventDetail, GridLoadStartEventDetail, GridLoadSuccessEventDetail } from "../grid/esp-grid.js";
+import type { DestroyEspalierInfo } from "../info/esp-info.js";
+import type { PickerItem } from "../pickers/esp-picker-item.js";
+import type { EspalierUploadImage, UploadEventDetail } from "../image-upload/image-helpers.js";
+export type { UploadEventDetail } from "../image-upload/image-helpers.js";
+import type { FontPickerValueChangedDetail } from "../font-picker/esp-font-picker.js";
+/**
+ * Canonical event name strings for every CustomEvent in the library.
+ *
+ * Use these instead of raw strings to catch typos at compile time:
+ *
+ * ```ts
+ * el.addEventListener(ESP_EVENTS.VALUE_CHANGED, handler);
+ * ```
+ *
+ * @docUrl /api/esp-events
+ * @menuGroup Event Constants
+ * @menuLabel ESP_EVENTS
+ */
+export declare const ESP_EVENTS: {
+    readonly VALUE_CHANGED: "value-changed";
+    readonly VALIDITY_CHANGED: "validity-changed";
+    readonly CLICKED: "clicked";
+    readonly ESP_SUBMIT: "esp-submit";
+    readonly ESP_SUBMIT_RESPONSE: "esp-submit-response";
+    readonly ESP_SUBMIT_ERROR: "esp-submit-error";
+    readonly ESP_TAB_CHANGED: "esp-tab-changed";
+    readonly ESP_TAB_UPDATED: "esp-tab-updated";
+    readonly ESP_TOGGLE: "esp-toggle";
+    readonly ESP_ACCORDION_CHANGE: "esp-accordion-change";
+    readonly DRAWER_OPENED: "drawer-opened";
+    readonly DRAWER_CLOSED: "drawer-closed";
+    readonly POPOVER_OPENED: "popover-opened";
+    readonly POPOVER_CLOSED: "popover-closed";
+    readonly GRID_EVENT: "grid-event";
+    readonly GRID_LOAD_START: "esp-grid-load-start";
+    readonly GRID_LOAD_SUCCESS: "esp-grid-load-success";
+    readonly GRID_LOAD_ERROR: "esp-grid-load-error";
+    readonly GRID_ITEMS_CHANGED: "esp-grid-items-changed";
+    readonly DESTROY: "destroy";
+    readonly FILE_SELECTED: "file-selected";
+    readonly FILE_REMOVED: "file-removed";
+    readonly FILES_SELECTED: "files-selected";
+    readonly FILES_REJECTED: "files-rejected";
+    readonly UPLOAD_RETRY: "upload-retry";
+    readonly RETRY_UPLOAD: "retry-upload";
+    readonly IMAGES_REORDERED: "images-reordered";
+    readonly SEARCH_REQUESTED: "search-requested";
+    readonly RESULT_SELECTED: "result-selected";
+    readonly SEARCH_CLOSED: "search-closed";
+    readonly SELECTION_CHANGED: "selection-changed";
+    readonly CLOSE_MENU: "close-menu";
+    readonly REMOVE_IMAGE: "remove-image";
+};
+/**
+ * Detail for `value-changed` on toggle controls
+ * (`esp-checkbox`, `esp-switch`, `esp-radio-button`).
+ *
+ * @docUrl /api/toggle-value-changed-detail
+ * @menuGroup Event Details
+ * @menuLabel ToggleValueChangedDetail
+ */
+export interface ToggleValueChangedDetail {
+    /** The new checked state for the control. */
+    checked: boolean;
+    /** The associated control value submitted with the event. */
+    value: string;
+}
+/**
+ * Detail for `value-changed` on `esp-color-picker`.
+ *
+ * @docUrl /api/color-value-changed-detail
+ * @menuGroup Event Details
+ * @menuLabel ColorValueChangedDetail
+ */
+export interface ColorValueChangedDetail {
+    seedColor: string;
+    hue: number;
+    chroma: number;
+    lightness: number;
+}
+/**
+ * Detail for `esp-submit` on `esp-form`.
+ *
+ * @docUrl /api/esp-submit-detail
+ * @menuGroup Event Details
+ * @menuLabel EspSubmitDetail
+ */
+export interface EspSubmitDetail {
+    formData: FormData;
+    form: HTMLFormElement;
+}
+/**
+ * Detail for `esp-submit-response` on `esp-form`.
+ *
+ * @docUrl /api/esp-submit-response-detail
+ * @menuGroup Event Details
+ * @menuLabel EspSubmitResponseDetail
+ */
+export interface EspSubmitResponseDetail {
+    response: Response;
+    ok: boolean;
+}
+/**
+ * Detail for `esp-submit-error` on `esp-form`.
+ *
+ * @docUrl /api/esp-submit-error-detail
+ * @menuGroup Event Details
+ * @menuLabel EspSubmitErrorDetail
+ */
+export interface EspSubmitErrorDetail {
+    error: unknown;
+}
+/**
+ * Detail for `esp-tab-changed` on `esp-tab-group`.
+ *
+ * @docUrl /api/esp-tab-changed-detail
+ * @menuGroup Event Details
+ * @menuLabel EspTabChangedDetail
+ */
+export interface EspTabChangedDetail {
+    index: number;
+    label: string;
+}
+/**
+ * Detail for `esp-toggle` on `esp-details`.
+ *
+ * @docUrl /api/esp-toggle-detail
+ * @menuGroup Event Details
+ * @menuLabel EspToggleDetail
+ */
+export interface EspToggleDetail {
+    open: boolean;
+}
+/**
+ * Detail for `esp-accordion-change` on `esp-details-group`.
+ *
+ * @docUrl /api/esp-accordion-change-detail
+ * @menuGroup Event Details
+ * @menuLabel EspAccordionChangeDetail
+ */
+export interface EspAccordionChangeDetail {
+    openItem: EspalierDetails | null;
+}
+/** Events fired by `<esp-button>`. */
+export interface EspalierButtonEventMap {
+    [ESP_EVENTS.CLICKED]: CustomEvent<Record<string, never>>;
+}
+/** Events fired by `<esp-input>`. */
+export interface EspalierInputEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<string>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-textarea>`. */
+export interface EspalierTextareaEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<string>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-checkbox>`. */
+export interface EspalierCheckboxEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<ToggleValueChangedDetail>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-checkbox-group>`. */
+export interface EspalierCheckboxGroupEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<string[]>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-switch>`. */
+export interface EspalierSwitchEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<ToggleValueChangedDetail>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-radio-button>`. */
+export interface EspalierRadioButtonEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<ToggleValueChangedDetail>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-radio-button-group>`. */
+export interface EspalierRadioButtonGroupEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<string>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-pick-one>`. */
+export interface EspalierPickOneEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<PickerItem | undefined>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-pick-some>`. */
+export interface EspalierPickSomeEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<PickerItem[]>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-color-picker>`. */
+export interface EspalierColorPickerEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<ColorValueChangedDetail>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-font-picker>`. */
+export interface EspalierFontPickerEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<FontPickerValueChangedDetail>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-date-picker>`. */
+export interface EspalierDatePickerEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<string>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-form>`. */
+export interface EspalierFormEventMap {
+    [ESP_EVENTS.ESP_SUBMIT]: CustomEvent<EspSubmitDetail>;
+    [ESP_EVENTS.ESP_SUBMIT_RESPONSE]: CustomEvent<EspSubmitResponseDetail>;
+    [ESP_EVENTS.ESP_SUBMIT_ERROR]: CustomEvent<EspSubmitErrorDetail>;
+}
+/** Events fired by `<esp-tab-group>`. */
+export interface EspalierTabGroupEventMap {
+    [ESP_EVENTS.ESP_TAB_CHANGED]: CustomEvent<EspTabChangedDetail>;
+}
+/** Events fired by `<esp-details>`. */
+export interface EspalierDetailsEventMap {
+    [ESP_EVENTS.ESP_TOGGLE]: CustomEvent<EspToggleDetail>;
+}
+/** Events fired by `<esp-details-group>`. */
+export interface EspalierDetailsGroupEventMap {
+    [ESP_EVENTS.ESP_ACCORDION_CHANGE]: CustomEvent<EspAccordionChangeDetail>;
+}
+/** Events fired by `<esp-popover>`. */
+export interface EspalierPopoverEventMap {
+    [ESP_EVENTS.POPOVER_OPENED]: CustomEvent<void>;
+    [ESP_EVENTS.POPOVER_CLOSED]: CustomEvent<void>;
+}
+/** Events fired by `<esp-menu>`. */
+export interface EspalierMenuEventMap {
+    [ESP_EVENTS.DRAWER_OPENED]: CustomEvent<void>;
+    [ESP_EVENTS.DRAWER_CLOSED]: CustomEvent<void>;
+}
+/** Events fired by `<esp-header-button>`. */
+export interface EspalierHeaderButtonEventMap {
+    [ESP_EVENTS.CLICKED]: CustomEvent<Record<string, never>>;
+}
+/** Events fired by `<esp-grid>`. */
+export interface EspalierGridEventMap {
+    [ESP_EVENTS.GRID_EVENT]: CustomEvent<GridClickedEvent>;
+    [ESP_EVENTS.GRID_LOAD_START]: CustomEvent<GridLoadStartEventDetail>;
+    [ESP_EVENTS.GRID_LOAD_SUCCESS]: CustomEvent<GridLoadSuccessEventDetail>;
+    [ESP_EVENTS.GRID_LOAD_ERROR]: CustomEvent<GridLoadErrorEventDetail>;
+    [ESP_EVENTS.GRID_ITEMS_CHANGED]: CustomEvent<GridItemsChangedEventDetail>;
+}
+/** Events fired by `<esp-info>`. */
+export interface EspalierInfoEventMap {
+    [ESP_EVENTS.DESTROY]: CustomEvent<DestroyEspalierInfo>;
+}
+/**
+ * Detail for `images-reordered` on `esp-image-upload`.
+ *
+ * @docUrl /api/images-reordered-detail
+ * @menuGroup Event Details
+ * @menuLabel ImagesReorderedDetail
+ */
+export interface ImagesReorderedDetail {
+    images: EspalierUploadImage[];
+}
+/**
+ * Detail for `files-rejected` on `esp-image-upload`.
+ *
+ * Fired when some of the user's selected files are skipped. Route it to a
+ * toast or inline message if the component's built-in notice is not enough.
+ *
+ * @docUrl /api/files-rejected-detail
+ * @menuGroup Event Details
+ * @menuLabel FilesRejectedDetail
+ */
+export interface FilesRejectedDetail {
+    /** Files skipped because their type is not in `accept`. */
+    unsupported: File[];
+    /** Files skipped because they could not be read or decoded. */
+    unreadable: File[];
+}
+/** Events fired by `<esp-image-upload>`. */
+export interface EspalierImageUploadEventMap {
+    [ESP_EVENTS.FILE_SELECTED]: CustomEvent<UploadEventDetail>;
+    [ESP_EVENTS.FILE_REMOVED]: CustomEvent<EspalierUploadImage>;
+    [ESP_EVENTS.FILES_REJECTED]: CustomEvent<FilesRejectedDetail>;
+    [ESP_EVENTS.UPLOAD_RETRY]: CustomEvent<UploadEventDetail>;
+    [ESP_EVENTS.IMAGES_REORDERED]: CustomEvent<ImagesReorderedDetail>;
+}
+/** Events fired by `<esp-file-upload>`. */
+export interface EspalierFileUploadEventMap {
+    [ESP_EVENTS.FILES_SELECTED]: CustomEvent<FileList>;
+}
+/** Events fired by `<esp-burger>`. */
+export interface EspalierBurgerEventMap {
+    [ESP_EVENTS.DRAWER_OPENED]: CustomEvent<void>;
+    [ESP_EVENTS.DRAWER_CLOSED]: CustomEvent<void>;
+}
+/**
+ * Detail for `search-requested` on `esp-search`.
+ *
+ * @docUrl /api/search-requested-detail
+ * @menuGroup Event Details
+ * @menuLabel SearchRequestedDetail
+ */
+export interface SearchRequestedDetail {
+    /** The current query string. May be empty when the user clears the input. */
+    query: string;
+}
+/**
+ * Detail for `result-selected` on `esp-search`.
+ *
+ * @docUrl /api/result-selected-detail
+ * @menuGroup Event Details
+ * @menuLabel ResultSelectedDetail
+ */
+export interface ResultSelectedDetail {
+    /** The URL of the selected search result. */
+    url: string;
+}
+/** Events fired by `<esp-slider>`. */
+export interface EspalierSliderEventMap {
+    [ESP_EVENTS.VALUE_CHANGED]: CustomEvent<string>;
+    [ESP_EVENTS.VALIDITY_CHANGED]: CustomEvent<ValidityChangedDetail>;
+}
+/** Events fired by `<esp-search>`. */
+export interface EspalierSearchEventMap {
+    [ESP_EVENTS.SEARCH_REQUESTED]: CustomEvent<SearchRequestedDetail>;
+    [ESP_EVENTS.RESULT_SELECTED]: CustomEvent<ResultSelectedDetail>;
+    [ESP_EVENTS.SEARCH_CLOSED]: CustomEvent<Record<string, never>>;
+}

package/dist/shared/events.js

@@ -0,0 +1 @@
+import{VALIDITY_CHANGED_EVENT as r}from"./validation.js";const e={VALUE_CHANGED:"value-changed",VALIDITY_CHANGED:"validity-changed",CLICKED:"clicked",ESP_SUBMIT:"esp-submit",ESP_SUBMIT_RESPONSE:"esp-submit-response",ESP_SUBMIT_ERROR:"esp-submit-error",ESP_TAB_CHANGED:"esp-tab-changed",ESP_TAB_UPDATED:"esp-tab-updated",ESP_TOGGLE:"esp-toggle",ESP_ACCORDION_CHANGE:"esp-accordion-change",DRAWER_OPENED:"drawer-opened",DRAWER_CLOSED:"drawer-closed",POPOVER_OPENED:"popover-opened",POPOVER_CLOSED:"popover-closed",GRID_EVENT:"grid-event",GRID_LOAD_START:"esp-grid-load-start",GRID_LOAD_SUCCESS:"esp-grid-load-success",GRID_LOAD_ERROR:"esp-grid-load-error",GRID_ITEMS_CHANGED:"esp-grid-items-changed",DESTROY:"destroy",FILE_SELECTED:"file-selected",FILE_REMOVED:"file-removed",FILES_SELECTED:"files-selected",FILES_REJECTED:"files-rejected",UPLOAD_RETRY:"upload-retry",RETRY_UPLOAD:"retry-upload",IMAGES_REORDERED:"images-reordered",SEARCH_REQUESTED:"search-requested",RESULT_SELECTED:"result-selected",SEARCH_CLOSED:"search-closed",SELECTION_CHANGED:"selection-changed",CLOSE_MENU:"close-menu",REMOVE_IMAGE:"remove-image"};export{e as ESP_EVENTS,r as VALIDITY_CHANGED_EVENT};

package/dist/shared/font-helpers.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @module font-helpers
+ *
+ * Pure utility functions for working with Google Font metadata.
+ *
+ * These helpers extract, normalize, and compare font weights, parse
+ * CSS `font-family` strings, and map Google Font categories to
+ * generic CSS fallbacks.  They are consumed by both the UX client
+ * (site-settings, profile-editor) and the server-side renderer.
+ *
+ * None of these functions touch the DOM or network — they operate
+ * entirely on data.
+ */
+import type { GoogleFont } from "../font-picker/esp-font-picker.js";
+/**
+ * Human-readable labels for the nine standard CSS `font-weight`
+ * values (100–900).
+ *
+ * Useful for building weight-picker UIs where the numeric value
+ * alone isn't descriptive enough.
+ */
+export declare const WEIGHT_LABELS: Readonly<Record<string, string>>;
+/**
+ * Extract available non-italic weights from a {@link GoogleFont},
+ * sorted numerically.
+ *
+ * Google Fonts encodes weights as variant strings: `"regular"` maps
+ * to `"400"`, italic variants (e.g. `"300italic"`) are excluded,
+ * and every other variant string is its numeric weight.
+ *
+ * @param font A Google Font entry, or `null`.
+ * @returns Sorted weight strings.  Defaults to `["400"]` when the
+ *   font is `null` or has no non-italic variants.
+ */
+export declare function extractWeights(font: GoogleFont | null): string[];
+/**
+ * Normalize a CSS `font-weight` keyword to its numeric equivalent.
+ *
+ * - `"bold"` → `"700"`
+ * - `"normal"` → `"400"`
+ * - Falsy / `undefined` → `defaultWeight`
+ * - Everything else passes through unchanged.
+ *
+ * @param weight The weight to normalize.
+ * @param defaultWeight Fallback when `weight` is falsy.
+ */
+export declare function normalizeWeight(weight: string | undefined, defaultWeight: string): string;
+/**
+ * Find the closest available weight to a desired one.
+ *
+ * If the desired weight appears in `available`, it is returned
+ * directly.  Otherwise the weight with the smallest absolute
+ * numeric distance is returned.  If `available` is empty, returns
+ * `"400"` as a safe default.
+ *
+ * @param desired The target weight (numeric string).
+ * @param available Sorted weight strings from {@link extractWeights}.
+ *   Typically non-empty — {@link extractWeights} always returns at
+ *   least `["400"]`.
+ * @returns The best matching weight from `available`, or `"400"`
+ *   if `available` is empty.
+ */
+export declare function bestAvailableWeight(desired: string, available: string[]): string;
+/**
+ * Extract the first family name from a CSS `font-family` string,
+ * stripping both single and double quotes and whitespace.
+ *
+ * @example
+ * ```ts
+ * extractFamily('"Noto Sans", sans-serif'); // "Noto Sans"
+ * extractFamily("'Roboto', sans-serif");    // "Roboto"
+ * extractFamily("monospace");               // "monospace"
+ * ```
+ */
+export declare function extractFamily(cssFamily: string): string;
+/**
+ * Return the generic CSS fallback for a Google Font category.
+ *
+ * - `"serif"` → `"serif"`
+ * - `"monospace"` → `"monospace"`
+ * - `"handwriting"` → `"cursive"`
+ * - Everything else (including `"sans-serif"`, `"display"`) →
+ *   `"sans-serif"`
+ */
+export declare function getFallbackFont(category: string): string;

package/dist/shared/font-helpers.js

@@ -0,0 +1 @@
+const u={100:"100 Thin",200:"200 Extra Light",300:"300 Light",400:"400 Regular",500:"500 Medium",600:"600 Semi Bold",700:"700 Bold",800:"800 Extra Bold",900:"900 Black"};function c(t){if(!t)return["400"];const r=new Set;for(const e of t.variants)e.includes("italic")||r.add(e==="regular"?"400":e);const n=[...r].sort((e,o)=>Number(e)-Number(o));return n.length>0?n:["400"]}function a(t,r){return t?t==="bold"?"700":t==="normal"?"400":t:r}function f(t,r){if(r.length===0)return"400";if(r.includes(t))return t;const n=Number(t);let e=r[0],o=Math.abs(Number(e)-n);for(const i of r){const s=Math.abs(Number(i)-n);s<o&&(e=i,o=s)}return e}function l(t){return t.split(",")[0].replace(/["']/g,"").trim()}function m(t){switch(t){case"serif":return"serif";case"monospace":return"monospace";case"handwriting":return"cursive";default:return"sans-serif"}}export{u as WEIGHT_LABELS,f as bestAvailableWeight,l as extractFamily,c as extractWeights,m as getFallbackFont,a as normalizeWeight};

package/dist/shared/form-field-controller.d.ts

@@ -0,0 +1,120 @@
+import type { ReactiveController, ReactiveControllerHost } from "lit";
+/**
+ * Configuration for `FormFieldController`.
+ *
+ * Every form-associated custom element creates its own
+ * `ElementInternals` instance (via `this.attachInternals()`) and
+ * passes it here together with a small set of callbacks that
+ * describe the host's value and validation semantics.
+ */
+export interface FormFieldControllerOptions {
+    /** The host element that owns this controller. */
+    host: ReactiveControllerHost & HTMLElement;
+    /** The ElementInternals instance created on the host. */
+    internals: ElementInternals;
+    /**
+     * Return the current form value for submission.
+     * Return `null` when the control has no value (omitted from FormData).
+     */
+    getFormValue: () => string | FormData | null;
+    /**
+     * Return a validity error, or `null` when the control is valid.
+     * The controller translates this into `internals.setValidity()`.
+     */
+    getValidity: () => {
+        flags: ValidityStateFlags;
+        message: string;
+    } | null;
+    /**
+     * Return the element to use as the validation anchor for
+     * browser-native tooltip positioning. Defaults to the host.
+     */
+    getValidationAnchor?: () => HTMLElement;
+    /** Called when the owning `<form>` is reset. */
+    onReset?: () => void;
+    /** Called when the browser restores form state (bfcache, etc.). */
+    onRestore?: (state: string) => void;
+    /** Called when the browser fires `formDisabledCallback`. */
+    onDisabled?: (isDisabled: boolean) => void;
+}
+/**
+ * A Lit reactive controller that centralises `ElementInternals`
+ * form-value syncing, constraint validation, and event dispatch
+ * for form-associated custom elements.
+ *
+ * ### Usage
+ *
+ * ```ts
+ * class MyInput extends LitElement {
+ *   static formAssociated = true;
+ *   private internals = this.attachInternals();
+ *
+ *   private formCtrl = new FormFieldController({
+ *     host: this,
+ *     internals: this.internals,
+ *     getFormValue: () => this.value || null,
+ *     getValidity: () =>
+ *       this.required && !this.value
+ *         ? { flags: { valueMissing: true }, message: "Please fill out this field." }
+ *         : null,
+ *   });
+ * }
+ * ```
+ */
+export declare class FormFieldController implements ReactiveController {
+    constructor(opts: FormFieldControllerOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    hostUpdated(): void;
+    /**
+     * Push the current value into `ElementInternals` for form
+     * participation, then run constraint validation and dispatch
+     * a `validity-changed` event.
+     *
+     * Call this whenever the host's value changes.
+     */
+    syncValue(): void;
+    /**
+     * Push the current value into `ElementInternals` and update
+     * validity **without** dispatching any events. Use this when
+     * the form value must stay in sync but no UI feedback should
+     * be shown (e.g. while the user is still typing and no error
+     * is currently displayed).
+     */
+    syncValueSilently(): void;
+    /**
+     * Run constraint validation against the host's current state
+     * and dispatch a `validity-changed` event.
+     */
+    validate(): void;
+    /**
+     * Check whether the host's current state is valid.
+     * Delegates to `ElementInternals.checkValidity()`.
+     *
+     * Some browsers don't auto-expose `checkValidity()` on the
+     * host element itself, so form controls should expose a public
+     * method that delegates here.
+     */
+    checkValidity(): boolean;
+    /**
+     * Delegate for the host's `formResetCallback()`.
+     * Calls the `onReset` hook, silently re-syncs the form value
+     * and validity, then dispatches `validity-changed` with
+     * `valid: true` so that `esp-form-item` clears any displayed
+     * errors. The internals are updated to reflect the real
+     * (possibly invalid) state, but the event always reports
+     * valid so the UI returns to its pristine appearance.
+     */
+    handleFormReset(): void;
+    /**
+     * Delegate for the host's `formStateRestoreCallback()`.
+     * Calls the `onRestore` hook, then re-syncs value and validation.
+     */
+    handleFormStateRestore(state: string): void;
+    /**
+     * Delegate for the host's `formDisabledCallback()`.
+     * Calls the `onDisabled` hook so the host can update its
+     * disabled property to match the `<fieldset>` state.
+     */
+    handleFormDisabled(isDisabled: boolean): void;
+}

package/dist/shared/form-field-controller.js

@@ -0,0 +1 @@
+import{VALIDITY_CHANGED_EVENT as i}from"./validation.js";class a{constructor(t){this._initialSyncDone=!1,this.opts=t,t.host.addController(this)}hostConnected(){this._initialSyncDone=!1}hostDisconnected(){}hostUpdated(){this._initialSyncDone||(this._initialSyncDone=!0,this.syncValidity())}syncValue(){const t=this.opts.getFormValue();this.opts.internals.setFormValue(t),this.validate()}syncValueSilently(){const t=this.opts.getFormValue();this.opts.internals.setFormValue(t),this.syncValidity()}validate(){this.syncValidity();const t={valid:this.opts.internals.validity.valid,message:this.opts.internals.validationMessage};this.opts.host.dispatchEvent(new CustomEvent(i,{detail:t,bubbles:!0,composed:!0}))}checkValidity(){return this.syncValidity(),this.opts.internals.checkValidity()}syncValidity(){const t=this.opts.getValidity();if(t){const s=this.opts.getValidationAnchor?.();s&&s!==this.opts.host?this.opts.internals.setValidity(t.flags,t.message,s):this.opts.internals.setValidity(t.flags,t.message)}else this.opts.internals.setValidity({})}handleFormReset(){this.opts.onReset?.();const t=this.opts.getFormValue();this.opts.internals.setFormValue(t),this.syncValidity();const s={valid:!0,message:""};this.opts.host.dispatchEvent(new CustomEvent(i,{detail:s,bubbles:!0,composed:!0}))}handleFormStateRestore(t){this.opts.onRestore?.(t),this.syncValue()}handleFormDisabled(t){this.opts.onDisabled?.(t)}}export{a as FormFieldController};

package/dist/shared/intent-values.d.ts

@@ -0,0 +1,15 @@
+export type EspalierIntentVariant = "neutral" | "success" | "warning" | "danger" | "info";
+export declare const DEFAULT_ICON_SPRITE_URL = "/assets/icons.svg";
+export declare const DEFAULT_ICON_VIEW_BOX = "0 0 24 24";
+export declare const INTENT_VARIANTS: readonly EspalierIntentVariant[];
+export declare function normalizeIntentVariant(value: string | null | undefined): EspalierIntentVariant;
+export declare function getIconHref(icon: string | null | undefined, host?: Element | null | undefined): string;
+export declare const getIconHrefForHost: typeof getIconHref;
+export declare function getIconSpriteUrl(host: Element | null | undefined): string;
+/**
+ * Reset the per-process record of which invalid icon names have
+ * already produced a `console.warn`. Tests should call this in a
+ * `beforeEach` (or equivalent) so assertions on warning counts are
+ * not order-dependent across the worker's module-cached state.
+ */
+export declare function resetWarnedInvalidIconNames(): void;

package/dist/shared/intent-values.js

@@ -0,0 +1 @@
+import{traverseToClosest as a}from"./utilities.js";const i="/assets/icons.svg",p="0 0 24 24",c=/^[A-Za-z0-9][A-Za-z0-9_-]*$/u,l=100,r=new Set,o=[],u=["neutral","success","warning","danger","info"];function N(n){return u.includes(n)?n:"neutral"}function I(n,t=null){const e=n?.trim()??"";if(!c.test(e))return e.length>0&&m(e)&&console.warn(`Invalid Espalier icon name "${e}". Icon names must start with a letter or number and may only contain letters, numbers, dashes, and underscores.`),"";const s=d(t);return s?`${s}#${e}`:""}const _=I;function d(n){const t=n?a(n,"esp-root"):null;return(t?(t.iconSpriteUrl??"").trim():i).split("#")[0]?.trim()||""}function m(n){if(r.has(n))return!1;if(r.add(n),o.push(n),o.length>l){const t=o.shift();t&&r.delete(t)}return!0}function g(){r.clear(),o.length=0}export{i as DEFAULT_ICON_SPRITE_URL,p as DEFAULT_ICON_VIEW_BOX,u as INTENT_VARIANTS,I as getIconHref,_ as getIconHrefForHost,d as getIconSpriteUrl,N as normalizeIntentVariant,g as resetWarnedInvalidIconNames};

package/dist/shared/justified-layout.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Justified photo layout — the algorithm popularized by Google Photos.
+ *
+ * Groups images into rows and scales each row to exactly fill the container
+ * width while preserving aspect ratios and keeping row heights as close to
+ * the target as possible. Pure and framework-free so the same layout can be
+ * shared between `<esp-image-upload>` previews and consumer-rendered
+ * galleries.
+ */
+/** Minimal shape required to lay out an item: its intrinsic dimensions. */
+export interface LayoutImage {
+    width: number;
+    height: number;
+}
+/** A single laid-out row: the items it contains and the row height in px. */
+export interface PhotoRow<T extends LayoutImage = LayoutImage> {
+    images: T[];
+    height: number;
+}
+/**
+ * Compute justified layout rows for a list of images.
+ *
+ * Algorithm:
+ * 1. Add images to a row one at a time, scaled to the target row height
+ * 2. When the combined width overflows the container, the row breaks either
+ *    before or after the overflowing image — whichever leaves the row height
+ *    closer to the target. Keeping the image shrinks the row slightly below
+ *    target; pushing it to the next row stretches the row above target.
+ * 3. Scale the finished row so it fills the container width exactly.
+ *
+ * Every row — including the last — is scaled to fill `containerWidth`
+ * exactly, except rows clamped by `maxRowHeight`: those keep their aspect
+ * ratios at the clamped height and no longer span the full width. Items are
+ * returned by reference in their original order.
+ *
+ * @param images Items with intrinsic `width`/`height` (extra fields preserved)
+ * @param containerWidth Available width in px that each row must fill
+ * @param targetRowHeight Preferred row height in px before scaling
+ * @param gap Horizontal gap in px between images within a row
+ * @param maxRowHeight Ceiling for row heights — keeps a stretched final row
+ * (or a single image) from ballooning past e.g. half the viewport height
+ */
+export declare function calculatePhotoLayout<T extends LayoutImage>(images: T[], containerWidth: number, targetRowHeight?: number, gap?: number, maxRowHeight?: number): PhotoRow<T>[];

package/dist/shared/justified-layout.js

@@ -0,0 +1 @@
+function T(o,u,h=220,l=8,w=Number.POSITIVE_INFINITY){if(o.length===0)return[];const i=t=>t.reduce((e,s)=>e+s.width/s.height,0),c=t=>{const e=(t.length-1)*l;return(u-e)/i(t)},d=t=>t>h?t/h:h/t,p=[];let n=[];const r=(t,e)=>{p.push({images:[...t],height:Math.min(e,w)})};for(let t=0;t<o.length;t++){n.push(o[t]);const s=i(n)*h+(n.length-1)*l>u,a=t===o.length-1;if(s&&n.length>1){const f=c(n),I=c(n.slice(0,-1));d(f)<=d(I)?r(n,f):(n.pop(),t--,r(n,I)),n=[]}else a&&(r(n,c(n)),n=[])}return p}export{T as calculatePhotoLayout};

package/dist/shared/overlay-controller.js

@@ -0,0 +1 @@
+const l=['a[href]:not([disabled]):not([tabindex="-1"])','button:not([disabled]):not([tabindex="-1"])','input:not([disabled]):not([tabindex="-1"])','select:not([disabled]):not([tabindex="-1"])','textarea:not([disabled]):not([tabindex="-1"])','[tabindex]:not([tabindex="-1"]):not([disabled])'].join(", "),a="[autofocus]:not([disabled])";class o{static lock(){o._count===0&&(o._savedOverflow=document.body.style.overflow,document.body.style.overflow="hidden"),o._count++}static unlock(){o._count<=0||(o._count--,o._count===0&&(document.body.style.overflow=o._savedOverflow??"",o._savedOverflow=null))}static _reset(){o._count=0,o._savedOverflow=null}}o._count=0,o._savedOverflow=null;function f(){o._reset()}class r{static lock(t){const e=r._counts.get(t);return e!==void 0?(r._counts.set(t,e+1),!0):t.inert?!1:(r._counts.set(t,1),t.inert=!0,!0)}static unlock(t){const e=r._counts.get(t)??0;if(e<=0)return;const s=e-1;s===0?(t.inert=!1,r._counts.delete(t)):r._counts.set(t,s)}static _reset(){r._counts.clear()}}r._counts=new Map;function d(){r._reset()}class _{get isPromoting(){return this._promoting}constructor(t){this._isOpen=!1,this._previouslyFocused=null,this._inertElements=[],this._promoted=!1,this._dropZone=null,this._promoting=!1,this._host=t.host,this._opts=t,t.host.addController(this)}get isOpen(){return this._isOpen}open(){this._isOpen||(this._previouslyFocused=document.activeElement??null,this._isOpen=!0,o.lock(),this._promoteToDropZone(),this._setInert(!0))}close(){this._isOpen&&(this._isOpen=!1,o.unlock(),this._setInert(!1),this._previouslyFocused?.focus(),this._previouslyFocused=null)}trapFocus(t){const e=this.getFocusableElements();if(e.length===0)return;const s=e[0],n=e[e.length-1],i=this._getDeepActiveElement();t.shiftKey?(i===s||this._isOrContains(s,i))&&(t.preventDefault(),n.focus()):(i===n||this._isOrContains(n,i))&&(t.preventDefault(),s.focus())}moveFocusInto(){const t=this._getAutofocusElement();if(t&&(t.focus(),this._autofocusLanded(t)))return;const e=this.getFocusableElements();if(e.length>0){e[0].focus();return}const s=this._opts.getFocusFallback?.();if(s){s.focus();return}this._opts.getFocusTrapContainer()?.focus()}_getAutofocusElement(){return this._getMatchingElements(a)[0]??null}getFocusableElements(){return this._getMatchingElements(l)}_getMatchingElements(t){const e=this._opts.getFocusTrapContainer();if(!e)return[];const s=[];for(const n of Array.from(e.querySelectorAll("*")))if(n instanceof HTMLElement){if(n.matches(t)&&s.push(n),n.shadowRoot){const i=n.shadowRoot.querySelectorAll(t);s.push(...Array.from(i))}if(n instanceof HTMLSlotElement)for(const i of n.assignedElements({flatten:!0})){if(!(i instanceof HTMLElement))continue;i.matches(t)&&s.push(i);const u=i.querySelectorAll(t);if(s.push(...Array.from(u)),i.shadowRoot){const c=i.shadowRoot.querySelectorAll(t);s.push(...Array.from(c))}}}for(const n of Array.from(this._host.children)){if(!(n instanceof HTMLElement))continue;n.matches(t)&&(s.includes(n)||s.push(n));const i=n.querySelectorAll(t);for(const u of Array.from(i))s.includes(u)||s.push(u);if(n.shadowRoot){const u=n.shadowRoot.querySelectorAll(t);for(const c of Array.from(u))s.includes(c)||s.push(c)}}return s}hostConnected(){}hostDisconnected(){this._promoting||this._isOpen&&(this._setInert(!1),o.unlock(),this._isOpen=!1)}_setInert(t){if(t){this._inertElements=[];const e=this._resolveInertAnchor(),s=e.parentElement??document.body;for(const n of s.children)n instanceof HTMLElement&&n!==e&&r.lock(n)&&this._inertElements.push(n)}else{for(const e of this._inertElements)r.unlock(e);this._inertElements=[]}}_resolveInertAnchor(){if(this._dropZone)return this._dropZone;let t=this._host;for(;!t.parentElement;){const e=t.getRootNode();if(e instanceof ShadowRoot&&e.host instanceof HTMLElement)t=e.host;else break}return t}_getDeepActiveElement(){let t=document.activeElement;for(;t?.shadowRoot?.activeElement;)t=t.shadowRoot.activeElement;return t}_isOrContains(t,e){return e?t===e?!0:t.contains(e):!1}_autofocusLanded(t){const e=this._getActiveElementChain(),s=e[0];return e.some(n=>this._isOrContains(t,n)?!0:n!==s&&n instanceof HTMLElement&&this._isOrContains(n,t))}_getActiveElementChain(){const t=[];let e=document.activeElement;for(;e;){t.push(e);const s=e.shadowRoot?.activeElement??null;if(!s||s===e)break;e=s}return t}_promoteToDropZone(){if(this._promoted&&this._dropZone){this._promoting=!0;try{this._dropZone.appendChild(this._host)}finally{this._promoting=!1}return}const t=this._host,e=t.closest("esp-page");if(e){if(customElements.get("esp-page")){this._tryPromote(e);return}customElements.whenDefined("esp-page").then(()=>{if(!this._isOpen||!t.isConnected)return;const s=t.closest("esp-page");this._tryPromote(s)&&(this._setInert(!1),this._setInert(!0))})}}_tryPromote(t){if(!t||this._promoted)return!1;const e=t.AddDialog;if(typeof e=="function"){this._promoting=!0;try{e.call(t,this._host)}finally{this._promoting=!1}return this._promoted=!0,this._dropZone=this._host.parentElement,!0}return!1}}export{l as FOCUSABLE_SELECTOR,_ as OverlayController,d as _resetInertLock,f as _resetScrollLock};

package/dist/shared/path-matching.js

@@ -0,0 +1 @@
+function r(t){return t.replace(/\/$/,"")||"/"}function o(t,n=location.pathname){return r(t)===r(n)}function i(t,n){if(!n)return!1;const e=r(t),a=r(n);return e===a||e.startsWith(`${a}/`)}export{r as normalizePath,i as pathStartsWithSegment,o as pathsMatch};