@siliconst/metaui 1.4.51 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/plugins/controls/ObjectPlugin.ts

@@ -1,111 +1,75 @@
-/**
- * @file ObjectPlugin.ts
- * @description Renders a button that opens a dialog to edit a nested object structure.
- */
-
-import { BasePlugin } from "./BasePlugin";
-import { IPluginValidationResult } from "../../interfaces/IPlugin";
-import { ISchema, IPropertyMetadata } from "../../interfaces/ISchema";
-import Control from "sap/ui/core/Control";
-import Event from "sap/ui/base/Event";
-import Button from "sap/m/Button";
-import JSONModel from "sap/ui/model/json/JSONModel";
-import { SCHEMA_TYPE, UI5_EVENT } from "../../constants/MetaUIConstants";
-
-export class ObjectPlugin extends BasePlugin {
-    /**
-     * Renders a `sap.m.Button` to open a nested Object form dialog.
-     * 
-     * @param field The specific JSON schema properties for this field.
-     * @param bindingPath The JSON path bound to this control.
-     * @param modelName The UI5 JSONModel name.
-     * @param engineScopeId The deterministic scope ID.
-     * @param onChange The callback fired on value change.
-     * @returns {Control} The configured Button control.
-     */
-    public render(field: IPropertyMetadata,  bindingPath: string,  modelName: string = "meta", engineScopeId?: string, onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void): Control {
-        this.onChange = onChange;
-        this.metadata = field;
-        const propKey = bindingPath.startsWith("/") ? bindingPath.substring(1) : bindingPath;
-        
-        const subSchema: ISchema = {
-            type: SCHEMA_TYPE.OBJECT,
-            title: field.ui?.label || propKey,
-            properties: field.properties || {}
-        };
-        
-        if (field.uiLayout) {
-            subSchema.uiLayout = field.uiLayout;
-        }
-
-        this.control = new Button({
-            id: this.generateStableId(engineScopeId, bindingPath),
-            text: !this.isEditable ? "View Details" : "Edit Details",
-            icon: !this.isEditable ? "sap-icon://display" : "sap-icon://form",
-            press: (oEvent: Event) => {
-                const btn = oEvent.getSource() as Button;
-                const parentModel = btn.getModel(modelName) as JSONModel;
-                if (!parentModel) return;
-                
-                const bindingContext = btn.getBindingContext(modelName);
-                let updatePath = bindingPath;
-                if (bindingContext && !bindingPath.startsWith("/")) {
-                    const ctxPath = bindingContext.getPath();
-                    updatePath = ctxPath.endsWith("/") ? ctxPath + bindingPath : (ctxPath === "/" ? "/" + bindingPath : ctxPath + "/" + bindingPath);
-                }
-                
-                // Deep clone to prevent live-mutations on the parent model before 'Submit' is clicked
-                const nestedData = JSON.parse(JSON.stringify(parentModel.getProperty(updatePath) || {}));
-
-                sap.ui.require(["nz/co/siliconst/ui5/metaui/controls/DynamicHost"], (DynamicHostClass: typeof import("../../controls/DynamicHost").default) => {
-                    const host = new DynamicHostClass({
-                        schemaDefinition: subSchema,
-                        data: nestedData,
-                        editable: this.isEditable,
-                        layoutBudget: this.metadata?.ui?.layoutBudget || 0
-                    } as object);
-
-                    if (!!this.isEditable) {
-                        host.attachEvent(UI5_EVENT.SUBMIT, (e: Event) => {
-                            const payload = e.getParameter("payload");
-                            parentModel.setProperty(updatePath, payload);
-                            
-                            // CRITICAL: Notify the parent Engine that this field mutated
-                            // so it can trigger LiveUpdate syncs and validate!
-                            if (this.onChange) {
-                                this.onChange(true, propKey);
-                            }
-                        });
-                    }
-
-                    const buttonText = field.ui?.dialogButtonText || (!this.isEditable ? "Close" : "OK");
-                    host.openInDialog(`Nested Details: ${field.ui?.label || propKey}`, buttonText);
-                });
-            }
-        });
-
-        return this.control as Control;
-    }
-
-    /**
-     * Validates the object plugin (always true as validation is deferred to the dialog host).
-     * @returns {IPluginValidationResult} The validation result.
-     */
-    public validate(): IPluginValidationResult {
-        return { isValid: true };
-    }
-
-    /**
-     * Read-only component for the engine, returns null.
-     */
-    protected getValue(): null {
-        return null;
-    }
-
-    /**
-     * Read-only component, no dynamic state handling needed for the button itself.
-     */
-    protected applyState(): void {
-        // No dynamic state handling needed for the button
-    }
-}
+/**
+ * @file ObjectPlugin.ts
+ * @description Renders a button that launches a modal DynamicHost dialog for nested object editing,
+ * and validates nested object payloads headlessly via PayloadValidator.
+ */
+
+import { INestedDialogDescriptor, NestedDialogPlugin } from "./NestedDialogPlugin";
+import { IPropertyMetadata, ISchema } from "../../interfaces/ISchema";
+import { isRecord } from "../../utils/TypeGuards";
+import { I18n, MetaUITextKey, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering nested object triggers (`sap.m.Button`) inside forms or table cells,
+ * opening a modal `DynamicHost` dialog when pressed.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class ObjectPlugin extends NestedDialogPlugin {
+    protected readonly defaultErrorTooltipKey: MetaUITextKey = TEXT_KEY.nestedObjectInvalid;
+    protected readonly emptyFallbackValue: unknown = null;
+
+    /**
+     * Resolves the default button label for nested objects.
+     *
+     * @param metadata The property metadata.
+     * @returns {string} The button label stem.
+     */
+    protected getDefaultLabel(metadata: IPropertyMetadata): string {
+        return metadata.ui?.label || I18n.getText(TEXT_KEY.nestedObjectLabel);
+    }
+
+    /**
+     * Resolves the edit/display icon for the nested object trigger button.
+     *
+     * @param canEdit True if editable.
+     * @returns {string} The SAP icon URI.
+     */
+    protected getButtonIcon(canEdit: boolean): string {
+        return canEdit ? "sap-icon://edit" : "sap-icon://display";
+    }
+
+    /**
+     * Coerces the current raw model value to a record object.
+     *
+     * @param rawCurrent The raw model value.
+     * @returns {Record<string, unknown>} The record payload.
+     */
+    protected override coerceCurrentData(rawCurrent: unknown): unknown {
+        return isRecord(rawCurrent) ? rawCurrent : {};
+    }
+
+    /**
+     * Builds the modal sub-schema descriptor for the nested object.
+     *
+     * @param metadata The nested object's property metadata.
+     * @returns {INestedDialogDescriptor} The modal dialog descriptor.
+     */
+    protected buildDialogDescriptor(metadata: IPropertyMetadata): INestedDialogDescriptor {
+        const title = metadata.ui?.label || I18n.getText(TEXT_KEY.nestedObjectTitle);
+        const subSchema: ISchema = {
+            title,
+            type: "object",
+            properties: metadata.properties || {},
+            additionalProperties: metadata.additionalProperties,
+            uiLayout: metadata.uiLayout,
+            readOnly: metadata.readOnly,
+            minProperties: metadata.minProperties,
+            maxProperties: metadata.maxProperties,
+            required: Array.isArray(metadata.required) ? metadata.required : undefined,
+            ui: this.buildSubSchemaUi(metadata)
+        };
+        return { title, subSchema, isArrayRoot: false };
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/controls/OptionListPlugin.ts

@@ -0,0 +1,149 @@
+/**
+ * @file OptionListPlugin.ts
+ * @description Shared abstract base class for the plugins that render a list of selectable options
+ * (`sap.m.Select`, `sap.m.ComboBox`, `sap.m.MultiComboBox`), consolidating `valueHelp` resolution,
+ * display-mode key-to-text mapping, and item-list synchronisation.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IPropertyMetadata, IValueHelpOption } from "../../interfaces/ISchema";
+import Item from "sap/ui/core/Item";
+import Control from "sap/ui/core/Control";
+
+/**
+ * A single resolved `{ key, text }` option, already stringified for the UI5 `Item` aggregation.
+ */
+export interface IOptionItem {
+    key: string;
+    text: string;
+}
+
+/**
+ * The structural contract shared by every UI5 control that owns an `items` aggregation of
+ * `sap.ui.core.Item` — `sap.m.Select`, `sap.m.ComboBox`, and `sap.m.MultiComboBox`.
+ */
+export interface IOptionListControl extends Control {
+    getItems(): Item[];
+    destroyItems(): unknown;
+    addItem(item: Item): unknown;
+}
+
+/**
+ * Shared abstract base class for `DropdownPlugin`, `MultiSelectPlugin`, and any other plugin that
+ * populates a UI5 option list. Owns the three pieces every such plugin otherwise reimplements:
+ * the `ui.valueHelp` → `valueHelp` resolution order, the display-mode mapping from stored key to
+ * option text, and the "replace the items only when they actually differ" synchronisation that
+ * keeps the user's selection alive across a metadata update.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export abstract class OptionListPlugin extends BasePlugin {
+    /**
+     * Resolves the configured option list, preferring `ui.valueHelp` over the schema-level `valueHelp`.
+     *
+     * @param metadata The property metadata.
+     * @returns {IValueHelpOption[] | undefined} The configured options, or `undefined` when none are declared.
+     */
+    protected resolveValueHelpList(metadata: IPropertyMetadata): IValueHelpOption[] | undefined {
+        if (Array.isArray(metadata.ui?.valueHelp)) {
+            return metadata.ui.valueHelp;
+        }
+        return Array.isArray(metadata.valueHelp) ? metadata.valueHelp : undefined;
+    }
+
+    /**
+     * Builds the desired `{ key, text }` option list from the configured `valueHelp`, falling back to
+     * the supplied enum list. A `valueHelp` list always wins, even when it is empty.
+     *
+     * @param metadata The property metadata.
+     * @param enumList The schema enum to use when no `valueHelp` is configured.
+     * @returns {IOptionItem[]} The stringified options to put into the control's `items` aggregation.
+     */
+    protected buildOptionItems(metadata: IPropertyMetadata, enumList?: unknown[]): IOptionItem[] {
+        const vhList = this.resolveValueHelpList(metadata);
+        const desiredItems: IOptionItem[] = [];
+        if (vhList) {
+            for (const opt of vhList) {
+                desiredItems.push({ key: String(opt.key), text: String(opt.text) });
+            }
+            return desiredItems;
+        }
+        if (Array.isArray(enumList)) {
+            for (const val of enumList) {
+                desiredItems.push({ key: String(val), text: String(val) });
+            }
+        }
+        return desiredItems;
+    }
+
+    /**
+     * Creates the display-mode `sap.m.Text` for a single-valued option list, mapping the stored key
+     * through the configured `valueHelp` so the user reads the option text rather than the raw key.
+     * Falls back to the plain bound value when no options are configured.
+     *
+     * @param engineScopeId Deterministic scope ID prefix.
+     * @param bindingPath Property binding path.
+     * @param modelName The UI5 JSONModel alias.
+     * @param metadata The property metadata.
+     * @returns {Control} The configured `sap.m.Text` control.
+     */
+    protected createOptionDisplayText(
+        engineScopeId: string | undefined,
+        bindingPath: string,
+        modelName: string,
+        metadata: IPropertyMetadata
+    ): Control {
+        const vhList = this.resolveValueHelpList(metadata);
+        if (!vhList || vhList.length === 0) {
+            return this.createDisplayText(engineScopeId, bindingPath);
+        }
+        const displayBinding = this.generateBindingInfo(bindingPath, modelName, undefined, {
+            formatter: (val: unknown) => {
+                if (val === undefined || val === null) {
+                    return "";
+                }
+                const matched = vhList.find((opt) => String(opt.key) === String(val));
+                return matched ? String(matched.text) : String(val);
+            }
+        });
+        return this.createDisplayText(engineScopeId, bindingPath, displayBinding);
+    }
+
+    /**
+     * Replaces the control's `items` aggregation with `desiredItems`, but only when the two actually
+     * differ. Rebuilding an identical list would destroy and recreate every `Item`, which drops the
+     * user's open selection, so the equality check is load-bearing rather than an optimisation.
+     * The current selection is read before the swap and written back afterwards.
+     *
+     * @param target The option list control to synchronise.
+     * @param desiredItems The option list the metadata now implies.
+     * @param readSelection Reads the currently selected keys from the control.
+     * @param writeSelection Restores the selected keys onto the rebuilt control.
+     */
+    protected syncOptionItems(
+        target: IOptionListControl,
+        desiredItems: IOptionItem[],
+        readSelection: () => string[],
+        writeSelection: (keys: string[]) => void
+    ): void {
+        const existingItems = typeof target.getItems === "function" ? target.getItems() : [];
+        if (
+            existingItems.length === desiredItems.length &&
+            existingItems.every(
+                (item, idx) => item.getKey() === desiredItems[idx].key && item.getText() === desiredItems[idx].text
+            )
+        ) {
+            return;
+        }
+
+        const previousKeys = readSelection();
+        target.destroyItems();
+        for (const opt of desiredItems) {
+            target.addItem(new Item({ key: opt.key, text: opt.text }));
+        }
+        if (previousKeys.length > 0) {
+            writeSelection(previousKeys);
+        }
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/controls/PasswordPlugin.ts

@@ -1,49 +1,71 @@
-import { BasePlugin } from "./BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Input from "sap/m/Input";
-import Control from "sap/ui/core/Control";
-import TextControl from "sap/m/Text";
-
-export class PasswordPlugin extends BasePlugin {
-    public render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName: string = "meta", engineScopeId?: string, onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void): Control {
-        this.onChange = onChange;
-        this.metadata = fieldMetadata;
-        this.fieldKey = bindingPath.replace("/", "");
-        
-        if (!this.isEditable) {
-            // Password in read-only should be masked natively
-            this.control = new TextControl({
-                id: this.generateStableId(engineScopeId, bindingPath),
-                text: "********" 
-            });
-            this.applyCommonDirectives(this.control, fieldMetadata, modelName);
-            return this.control as Control;
-        }
-
-        this.control = new Input({
-            id: this.generateStableId(engineScopeId, bindingPath),
-            value: this.generateBindingInfo(bindingPath, modelName),
-            type: "Password",
-            maxLength: fieldMetadata.maxLength || 0,
-            required: !!fieldMetadata.required,
-            change: (oEvent: sap.ui.base.Event) => {
-                const result = this.validate();
-                if (this.onChange) this.onChange(result.isValid, this.fieldKey, result.errorMessage);
-            }
-        });
-
-        this.applyCommonDirectives(this.control, fieldMetadata, modelName);
-        return this.control as Control;
-    }
-
-    protected getValue(): unknown {
-        return this.control && this.control.getMetadata().getName() === "sap.m.Input" ? (this.control as Input).getProperty('value') : null;
-    }
-
-    protected applyState(): void {
-        if (!this.control || !this.metadata || this.control.getMetadata().getName() !== "sap.m.Input") return;
-        const input = this.control as Input;
-        input.setEditable(!this.metadata.ui?.readOnly);
-        input.setRequired(!!this.metadata.required);
-    }
-}
+/**
+ * @file PasswordPlugin.ts
+ * @description Renders a password-masked sap.m.Input control.
+ */
+
+import { TextLikeInputPlugin } from "./TextLikeInputPlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Input from "sap/m/Input";
+import Control from "sap/ui/core/Control";
+import Event from "sap/ui/base/Event";
+import { InputType } from "sap/m/library";
+import { PropertyBindingInfo } from "sap/ui/base/ManagedObject";
+import { I18n, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Handles rendering logic for Password strings (`ui.widget = "password"` or `format = "password"`).
+ * Masks characters in both edit mode (`InputType.Password`) and display mode (`********`).
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class PasswordPlugin extends TextLikeInputPlugin {
+    /**
+     * Renders a masked `********` display text control when the host is in display mode.
+     *
+     * @param _metadata The property metadata.
+     * @param bindingPath The JSON path bound to this control.
+     * @param modelName The UI5 JSONModel name.
+     * @param engineScopeId The deterministic scope ID.
+     * @returns {Control} The masked Text control.
+     */
+    protected override renderDisplayControl(
+        _metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string,
+        engineScopeId?: string
+    ): Control {
+        const maskedBinding = this.generateBindingInfo(bindingPath, modelName, undefined, {
+            formatter: (val: unknown) => (val ? "********" : "")
+        }) as PropertyBindingInfo;
+        return this.createDisplayText(engineScopeId, bindingPath, maskedBinding);
+    }
+
+    /**
+     * Constructs the editable `sap.m.Input` control with `type: InputType.Password`.
+     *
+     * @param metadata The specific JSON schema properties for this field.
+     * @param bindingPath The JSON path bound to this control.
+     * @param modelName The UI5 JSONModel name.
+     * @param engineScopeId The deterministic scope ID.
+     * @returns {Control} The configured password Input control.
+     */
+    protected createEditableControl(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string,
+        engineScopeId?: string
+    ): Control {
+        return new Input({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            type: InputType.Password,
+            value: this.generateBindingInfo(bindingPath, modelName) as unknown as string,
+            placeholder: metadata.ui?.placeholder || I18n.getText(TEXT_KEY.passwordPlaceholder),
+            maxLength: metadata.maxLength || 0,
+            required: this.isRequired(),
+            change: (oEvent: Event) => {
+                this.notifyChange((oEvent.getSource() as Control).getId());
+            }
+        });
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/controls/PickerPlugin.ts

@@ -0,0 +1,158 @@
+/**
+ * @file PickerPlugin.ts
+ * @description Shared abstract base class for UI5 DatePicker, TimePicker, and DateTimePicker control plugins.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import DatePicker, { $DatePickerSettings } from "sap/m/DatePicker";
+import TimePicker, { $TimePickerSettings } from "sap/m/TimePicker";
+import DateTimePicker, { $DateTimePickerSettings } from "sap/m/DateTimePicker";
+import Control from "sap/ui/core/Control";
+import Event from "sap/ui/base/Event";
+import { PropertyBindingInfo } from "sap/ui/base/ManagedObject";
+import { I18n, MetaUITextKey } from "../../utils/I18n";
+
+/**
+ * Union of SAPUI5 date/time picker control instances.
+ */
+export type PickerControlInstance = (DatePicker | TimePicker | DateTimePicker) & {
+    isValidValue?(): boolean;
+};
+
+/**
+ * Shared constructor settings accepted by all three picker controls.
+ */
+export type PickerSettings = $DatePickerSettings & $TimePickerSettings & $DateTimePickerSettings;
+
+/**
+ * Static configuration descriptor for a concrete `PickerPlugin` subclass.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export interface IPickerPluginConfig {
+    ControlClass: new (mSettings?: PickerSettings) => PickerControlInstance;
+    bindingType: string;
+    sourcePattern: string;
+    displayFormat?: string;
+    /** Bundle key of the sentence shown when the control cannot parse what the user typed. */
+    parseErrorMessageKey: MetaUITextKey;
+}
+
+/**
+ * Shared abstract base class for `DatePlugin`, `TimePlugin`, and `DateTimePlugin`.
+ * Consolidates binding generation, display-mode rendering, `change` event parse validation,
+ * `getParseError`, `getValue`, and `applyState`.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export abstract class PickerPlugin extends BasePlugin {
+    protected abstract readonly pickerConfig: IPickerPluginConfig;
+
+    /**
+     * Renders the configured UI5 picker control in edit mode or a formatted `sap.m.Text` in display mode.
+     *
+     * @param fieldMetadata The specific JSON schema properties for this field.
+     * @param bindingPath The JSON path bound to this control.
+     * @param modelName The UI5 JSONModel name.
+     * @param engineScopeId The deterministic scope ID.
+     * @param onChange The callback fired on value change.
+     * @returns {Control} The configured picker or display text control.
+     */
+    public render(
+        fieldMetadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string = "meta",
+        engineScopeId?: string,
+        onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void
+    ): Control {
+        this.initialize(fieldMetadata, bindingPath, modelName, onChange);
+
+        const cfg = this.pickerConfig;
+        const pickerBinding = this.generateBindingInfo(bindingPath, modelName, cfg.bindingType, {
+            formatOptions: {
+                source: { pattern: cfg.sourcePattern },
+                pattern: cfg.sourcePattern
+            }
+        }) as PropertyBindingInfo;
+
+        if (!this.isEditable) {
+            return this.createDisplayText(engineScopeId, bindingPath, pickerBinding);
+        }
+
+        const PickerCtor = cfg.ControlClass;
+        this.control = new PickerCtor({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            value: pickerBinding as unknown as string,
+            ...(cfg.displayFormat ? { displayFormat: cfg.displayFormat } : {}),
+            ...(fieldMetadata.ui?.placeholder ? { placeholder: fieldMetadata.ui.placeholder } : {}),
+            editable: this.isControlEditable(),
+            required: this.isRequired(),
+            change: (oEvent: Event) => {
+                const src = oEvent.getSource() as PickerControlInstance;
+                const params = oEvent.getParameters() as { valid?: boolean };
+                const cleanPath = this.resolveAbsolutePath(src).replace(/^\//, "") || this.fieldKey || "";
+                if (params.valid === false) {
+                    this.invalidParsePaths.set(cleanPath, I18n.getText(cfg.parseErrorMessageKey));
+                    src.data("metauiParseInvalid", true);
+                } else {
+                    this.invalidParsePaths.delete(cleanPath);
+                    src.data("metauiParseInvalid", null);
+                }
+                this.notifyChange(src.getId());
+            }
+        });
+
+        this.applyCommonDirectives(this.control, fieldMetadata, modelName);
+        return this.control;
+    }
+
+    /**
+     * Checks whether the picker currently holds an unparseable value via `isValidValue()`.
+     *
+     * @param sourceControl Optional runtime source control (e.g., cloned table cell).
+     * @returns {string | undefined} The parse error message if invalid, otherwise `undefined`.
+     */
+    protected override getParseError(sourceControl?: Control): string | undefined {
+        const target = (sourceControl ?? this.control) as PickerControlInstance | undefined;
+        if (this.isEditable && target && typeof target.isValidValue === "function" && !target.isValidValue()) {
+            return I18n.getText(this.pickerConfig.parseErrorMessageKey);
+        }
+        return undefined;
+    }
+
+    /**
+     * Retrieves the current string value from the picker control.
+     *
+     * @param sourceControl Optional runtime source control (e.g., cloned table cell).
+     * @returns {unknown} The picker value.
+     */
+    protected getValue(sourceControl?: Control): unknown {
+        if (!this.isEditable) {
+            return this.getModelValue(sourceControl) ?? null;
+        }
+        const target = (sourceControl ?? this.control) as PickerControlInstance | undefined;
+        if (!target) {
+            return null;
+        }
+        const val = target.getProperty("value");
+        if (!val && !target.getDomRef()) {
+            return this.getModelValue(target) ?? null;
+        }
+        return val;
+    }
+
+    /**
+     * Applies dynamic `readOnly`, `required`, and `placeholder` state updates to the picker control.
+     */
+    protected applyState(): void {
+        if (this.control && this.metadata && this.isEditable) {
+            const picker = this.control as PickerControlInstance;
+            picker.setEditable(this.isControlEditable());
+            picker.setRequired(this.isRequired());
+            picker.setPlaceholder(this.metadata.ui?.placeholder || "");
+        }
+    }
+}