Migrating To Espalier 4
Espalier 4 removes expired compatibility APIs and gives every public bubbling
DOM event one deterministic esp- name. It does not dual-dispatch legacy event
names. Update listeners and imports in the same consumer change that upgrades
the package.
Event listener migration
Shared cross-control protocols use shared names. Component-owned events use
esp-<component>-<action>.
| Espalier 3 | Espalier 4 |
|---|---|
value-changed |
esp-value-changed |
validity-changed |
esp-validity-changed |
clicked |
esp-clicked |
opened / closed on esp-burger |
esp-burger-opened / esp-burger-closed |
select on esp-action-menu |
esp-action-menu-select |
esp-toggle |
esp-details-toggle |
esp-accordion-change |
esp-details-group-change |
files-selected on esp-file-upload |
esp-file-upload-files-selected |
flyout-opened / flyout-closed / flyout-state-changed |
esp-flyout-opened / esp-flyout-closed / esp-flyout-state-changed |
focus-changed |
esp-focus-picker-changed |
closeDialog |
esp-form-dialog-close-requested |
esp-submit / esp-submit-response / esp-submit-error |
esp-form-submit / esp-form-submit-response / esp-form-submit-error |
grid-event |
esp-grid-event |
esp-theme-toggle |
esp-header-theme-toggle |
file-selected / file-removed / files-rejected on esp-image-upload |
esp-image-upload-file-selected / esp-image-upload-file-removed / esp-image-upload-files-rejected |
upload-retry / images-reordered on esp-image-upload |
esp-image-upload-retry / esp-image-upload-images-reordered |
destroy on esp-info |
esp-info-destroy |
icon-clicked |
esp-input-icon-clicked |
esp-group-toggle |
esp-menu-group-toggle |
drawer-opened / drawer-closed on esp-menu |
esp-menu-drawer-opened / esp-menu-drawer-closed |
selection-changed on esp-picker-menu |
esp-picker-menu-selection-changed |
close-menu on esp-picker-menu |
esp-picker-menu-close-requested |
range-changed on esp-picker-menu |
esp-picker-menu-range-changed |
popover-opened / popover-closed |
esp-popover-opened / esp-popover-closed |
search-requested / result-selected / search-closed |
esp-search-requested / esp-search-result-selected / esp-search-closed |
esp-tab-changed |
esp-tab-group-changed |
The existing esp-dialog-*, esp-grid-load-*,
esp-grid-items-changed, esp-lightbox-changed,
esp-page-workspace-resize, and esp-tree-* families are unchanged.
The grid's authoring attribute also remains grid-event; only the event emitted
by the grid changes to esp-grid-event.
Search listener code, Lit @event-name bindings, test fixtures, automation
drivers, and synthetic CustomEvent dispatches together:
rg -n 'value-changed|validity-changed|clicked|closeDialog|esp-submit|grid-event' src __tests__
Prefer the exhaustive ESP_EVENTS registry in TypeScript dispatch/listener
code:
import { ESP_EVENTS } from "@taprootio/espalier";
control.addEventListener(ESP_EVENTS.VALUE_CHANGED, (event) => {
console.log(event.detail);
});
ESP_EVENTS key changes
The registry uses component-qualified keys where the old keys were ambiguous.
| Espalier 3 key | Espalier 4 key |
|---|---|
ESP_SUBMIT |
FORM_SUBMIT |
ESP_SUBMIT_RESPONSE |
FORM_SUBMIT_RESPONSE |
ESP_SUBMIT_ERROR |
FORM_SUBMIT_ERROR |
ESP_TAB_CHANGED |
TAB_GROUP_CHANGED |
ESP_TOGGLE |
DETAILS_TOGGLE |
ESP_ACCORDION_CHANGE |
DETAILS_GROUP_CHANGE |
DRAWER_OPENED / DRAWER_CLOSED |
MENU_DRAWER_OPENED / MENU_DRAWER_CLOSED |
ESP_THEME_TOGGLE |
HEADER_THEME_TOGGLE |
ESP_PAGE_WORKSPACE_RESIZE |
PAGE_WORKSPACE_RESIZE |
DESTROY |
INFO_DESTROY |
FILES_SELECTED |
FILE_UPLOAD_FILES_SELECTED |
FILE_SELECTED / FILE_REMOVED |
IMAGE_UPLOAD_FILE_SELECTED / IMAGE_UPLOAD_FILE_REMOVED |
FILES_REJECTED / UPLOAD_RETRY / IMAGES_REORDERED |
IMAGE_UPLOAD_FILES_REJECTED / IMAGE_UPLOAD_RETRY / IMAGE_UPLOAD_IMAGES_REORDERED |
RESULT_SELECTED |
SEARCH_RESULT_SELECTED |
SELECTION_CHANGED / CLOSE_MENU |
PICKER_MENU_SELECTION_CHANGED / PICKER_MENU_CLOSE_REQUESTED |
The internal ESP_TAB_UPDATED, RETRY_UPLOAD, and REMOVE_IMAGE keys are
removed without replacements. Internal child/parent coordination events are no
longer part of ESP_EVENTS or the Custom Elements Manifest.
Removed exports
| Removed export | Replacement |
|---|---|
getIconHref |
getIconHrefForHost(icon, host) |
RepeaterFetchParams |
CursorPageRequest |
RepeaterFetchResult |
CursorPageResult<T> |
scrollElementIntoView |
element.scrollIntoView(options) |
isFixedInShadowDom |
No library replacement; keep layout decisions in the owning application/component |
isFixedOrAncestorFixed |
No library replacement; keep layout decisions in the owning application/component |
These aliases are deleted from runtime modules and declarations. There are no deprecated forwarding exports in Espalier 4.
Subclassing and forms
The supported third-party extension surface is deliberately small:
EspalierElementBaseFormFieldControllerandFormFieldControllerOptions- validation types and documented intent/icon helpers, including
getIconHrefForHost
Form-associated components continue to compose FormFieldController; there is
no additional form base class or mixin. Each component keeps its own validation
surface. In particular, esp-slider remains always-valid and does not gain
required or requiredMessage.
Styling fragments and implementation helpers such as intentSurfaceTokens,
renderSpriteIcon, SlottedIconController, srOnly, disabledControl,
focusRing, and syncNormalizedAttribute remain internal and are not package
exports.