Appearance
Additional data команд
Параметры команды действия («какое значение выставить», «какое состояние включить») — additional data. Декларации schema-first: тип объекта объявляет в model/schema.ts рядом со схемой настроек события, команды, zod-схемы values каждой команды и UI-мету полей; редактор и контроллер-синхронизация читают эти декларации, а не хардкодят команды.
Декларации типа
ts
/** UI-мета поля команды: чем рендерить, какие опции и границы. */
export interface IReactionFieldMeta {
/** виджет редактора (dropdown/number/time/interval/виджеты таймеров) */
widget: AdditionalDataType;
/** локализованный заголовок поля */
label: string;
/** опции dropdown: Map/Record значение→лейбл (источник для UI и протокола контроллера) */
options?: Map<string | number, string> | Record<string, string>;
/**
* источник опций dropdown — данные цели, а не статичная карта:
* "targetStates" = состояния mode-объекта (settings.States, id→имя).
* Взаимоисключающе с options; resolveFieldProps адаптера читает
* дескриптор при построении полей.
*/
optionsSource?: "targetStates";
/**
* граница может зависеть от настроек цели (например, Max ≥ Min из настроек);
* any здесь присущ: мета живёт в общем интерфейсе, а поля настроек у каждого типа свои
*/
min?: number | ((targetSettings: any) => number);
max?: number | ((targetSettings: any) => number);
/** максимум знаков после запятой для number-виджета */
maxFractionDigits?: number;
class?: string;
/** конфигурация виджета-объекта таймера (props поля целиком) */
timerSetup?: TTimerSetupConfig;
}
/** Мета полей команды: ключи обязаны совпадать с ключами схемы values. */
export type TReactionFieldMetas<TSchema extends z.ZodTypeAny> = Record<
keyof z.infer<TSchema>,
IReactionFieldMeta
>;
/**
* Как тип объекта описывает параметры своих команд для редактора логики.
* Живёт в model/schema.ts типа (рядом с zod-схемой настроек) и отдаётся
* редактору через IObjectReactable.actionDeclarations.
*/
export interface IActionDeclarations<TActions extends string = string> {
/** Zod-схема значений каждой команды: по ней значения из БД проверяются
* при загрузке. Команды описываются через satisfies Record<ActionTypeX, ...> —
* пропущенная команда не скомпилируется. */
valuesSchemas: Partial<Record<TActions, z.ZodTypeAny>>;
/** Как рендерить каждое поле команды: виджет, лейбл, опции, границы. */
fieldMeta: Partial<Record<TActions, Record<string, IReactionFieldMeta>>>;
/** Начальные значения команды. Фабрика, а не объект: дефолты зависят
* от настроек целевого объекта. */
defaults: Partial<Record<TActions, (targetSettings: any) => object>>;
/** CSS-класс контейнера полей команды в редакторе. */
containerClass?: string;
}Дефолты — фабрики от настроек цели: например, CMD_CHANGE_VALUE у mode-object берёт состояние с индексом settings.Value цели, а не константу.
Адаптерный конвейер
Между декларациями и редактором стоит адаптер. Цель действия разрешается в два вида: editorObject (что показывать — для групп делегированный вид члена) и semanticObject (чей семантикой живут значения).
ts
/**
* Разрешённая цель действия: одна запись БД, два вида.
* Для групп — editorObject несёт делегированные перечисления первого члена
* (редактор показывает команды члена), а semanticObject — реальный объект,
* чьи настройки/семантика используются в рантайме.
*/
export type ResolvedActionTargetObject = {
/** объект для UI schema/additionalData list; для групп — делегированный вид */
editorObject: ReactableTargetObject | TDelegatedGroupView;
/** реальный target object для runtime semantics */
semanticObject: ReactableTargetObject;
};ts
/**
* Адаптер связи экшена: перевод между тремя видами значений — editor-state
* (что видит редактор), storedDB (actionData.values в БД) и runtime payload
* (объект на контроллер). Generic-фабрика строит его из деклараций типа;
* специализированные — для доменных кейсов.
*/
export interface ActionLinkAdapter extends ILinkAdapter<
ActionAdditionalDataEditorState,
Record<string, unknown>,
Record<string, string | number> | undefined
> {
/** экшеновое расширение: пересчёт проекций при смене полей команды */
createEditorState(
storedDB?: Record<string, unknown>,
options?: { changedFieldIds?: string[] },
): ActionAdditionalDataEditorState;
}Адаптер additional data команды. Запись в actionDataAdapters цели — знак междоменной связи: фабрика строит поля из чужих данных (состояния/поля цели, записи реестров). Нет записи — связи нет: базовый движок строит поля из собственных деклараций типа (fieldMeta/defaults).
Схема поля и projection
Адаптер строит из деклараций поля — схемы редактора (не stored data). Вычисляемые части поля (значение, опции, границы) описываются projection-ом; словарь проекций — доменно-нейтральный, вынесен на отдельную страницу, его же используют драйвер-линки.
ts
/**
* Schema одного поля нового additional-data editor-а.
*
* Важно: это не stored data. Schema живет в adapter layer и описывает,
* как из `actionData.values` собрать editor-state, какие projections применить,
* и какой widget показать.
*/
export type ActionFieldDefinition = {
/** id поля в editor-state; для полей без ключа (виджеты-объекты таймеров) — синтетический `__field_N` */
id: string;
valueType: ActionFieldValueType;
widget: ActionFieldWidget;
label: string;
/** начальное значение, когда в actionData.values поля ещё нет */
defaultValue: unknown;
/** конфигурация виджета: опции dropdown, границы number или конфигурация виджета таймера */
props?: TAdditionalFieldData;
class?: string;
persistence: FieldPersistence;
/**
* Projection описывает не только значение поля, но и editor metadata.
*
* `value` - вычисляет само значение поля.
* Например, PID/SHIM CMD_CHANGE_FIELD подставляет value из выбранного target setting.
*
* `options` - вычисляет список вариантов для dropdown.
* Например, ModeObject CMD_CHANGE_VALUE строит options из target.settings.States.
*
* `constraints` - вычисляет ограничения ввода: min/max/step и похожие props.
* Например, numeric action field может брать min/max из scale settings target object.
*
* Эти части разделены, потому что могут зависеть от разных источников
* и пересчитываться по разным правилам.
*/
projection?: {
value?: ActionFieldProjection;
options?: ActionFieldProjection;
constraints?: ActionFieldProjection;
};
};ts
/** Вычисление значения проекции: объект-владелец + values полей редактора. */
export type TProjectionResolver<TSource> = (
source: TSource,
values: Record<string, unknown>,
) => unknown;
/**
* Поле может не хранить значение, а вычислять его у владельца: так работают
* опции дропдауна состояний, предзаполнение «изменить на» или адрес в запросе
* на контроллер. FieldProjection — правило этого вычисления. TSource — тип
* объекта-владельца; его привязывает потребитель правила (логика экшенов
* передаёт объект-цель команды).
*/
export type FieldProjection<TSource> = {
/**
* Вычисление: получает объект-владельца (TSource) и текущие значения полей
* редактора; где внутри владельца искать и в каком виде отдать — дело самой
* функции.
*/
resolver: TProjectionResolver<TSource>;
/**
* При инициализации значение читается один раз и дальше само не меняется.
* Если оно должно обновляться и после — перечисляем поля команды, при смене
* которых перечитывать. Смены остальных полей пересчёт не запускают:
* в частности, ввод руками в само проекционное поле не затирается.
*
* @example
* Команда «изменение поля» PID: [Параметр ▾] [Значение]. Правило «Значения»:
* { resolver: parameterValue, dependsOn: ["field"] }, где parameterValue
* читает у цели settings[выбранный параметр]. Открыли команду — подставилось
* текущее значение выбранного параметра. Переключили «Параметр» —
* подставилось значение нового. Вписали число руками — живёт, ничем
* не затирается.
*/
dependsOn?: string[];
};Три вида значений
Editor-values — что видит и правит редактор (по одному значению на поле, включая virtual). Stored — actionData.values в БД. Runtime — плоский объект ActionCmdData, уходящий на контроллер (toRuntimePayload адаптера). Перевод editor → stored:
Editor-values → stored values (actionData.values): literal-поля пишутся по своему valueKey, reference — stable id, virtual — не пишутся вовсе. Команда с root-полем (виджет-таймер) — исключение: stored values становятся самим объектом виджета, без обёртки в ключ поля.
Специализированные адаптеры
Generic-конвейер покрывает декларативные команды; когда runtime-формат или семантика значений расходится с editor-values, команда получает специализированный адаптер. Существующие:
- change-field —
CMD_CHANGE_FIELDу PID и SHIM: value-projection из настроек цели; - start-dim —
CMD_START_DIM: числовоеValueна контроллер без AddData-массива; - change-value —
CMD_CHANGE_VALUE: ссылочная модель состояний.