Design conventions

Project scope

Fast.Element.Plus is the open-source SDK for Fast business components. Team efficiency and consistent interaction take priority, including intentional changes to Element Plus defaults, events, and workflows.

Native capabilities

Wrappers forward Element Plus props, events, slots, and expose where appropriate, but are not transparent proxies. Fast additions, overrides, and unsupported features follow these docs and public TypeScript types.

Every Element Plus minor upgrade, such as 2.14.x to 2.15.x or later, requires reviewing props, emits, slots, expose, defaults, and internal styles. See the compatibility checklist.

Asynchronous business flows

FaDialog and FaDrawer open/close events indicate completion of Fast business hooks:

• open fires after afterOpen completes.
• close fires after closeFunction or beforeClose completes.
• Components remain loading while waiting to prevent repeated actions.

This intentionally differs from the DOM timing of same-named native Element Plus lifecycle events.

Selector models and events

FaSelect, FaSelectPage, FaSelectV2, FaTreeSelect, and FaInputDialogPage separate model updates from business-data events:

• update:modelValue is the sole selected-value update channel and preserves native value types; clearing multiple selection still produces an array.
• FaSelect, FaSelectPage, FaSelectV2, and FaTreeSelect retain change(data, value): an option object for single selection, option objects for multiple selection, and null on clear. It does not update the model again.
• Other events such as clear, remove-tag, and check preserve Element Plus arguments.
• v-model:label is derived from current values and options; applications may instead handle labels through update:modelValue.
• FaTreeSelect node-click only means a node was clicked. Determine final selection through update:modelValue, change, or check.
• FaInputDialogPage change(data, value) returns confirmed rows and values. selectionRow expose tracks selected rows and clears with the selection.

Programmatic selection through expose updates the model without synthesizing native user-change events.

FaTree emits change(data, node, instance, event) only when the current value changes; node-click always represents a click.

Upload models and callbacks

• FaUpload, FaUploadImage, and FaUploadImages emit uploaded URL models only through update:modelValue.
• onChange(uploadFile, uploadFiles) remains an Element Plus file-state callback, without URL strings or arrays mixed in.
• Clearing multiple files emits []; clearing a single file emits null.
• update:fileList writes only when the list changes, without duplicate assignment during removal callbacks.

Styles and themes

• Colors, borders, backgrounds, and text prefer --el-* variables, following application theme changes.
• Component-specific variables such as --fa-dialog-and --fa-table- remain only where they express component semantics.
• Shared SCSS breakpoints cover phone, tablet, and desktop layouts.
• Existing public variables such as --width remain supported.

Public API

Props, Emits, Slots, Expose, instances, and helper types are public APIs. The current release does not promise stable compatibility; breaking changes must update types, examples, API documentation, and Changelog together.