@acorex/platform 20.8.9 → 20.8.11

package/{layout/builder/index.d.ts → types/acorex-platform-layout-builder.d.ts}

@@ -3,12 +3,13 @@ import { OnInit, EventEmitter } from '@angular/core';
 import * as i1 from '@angular/common';
 import { AXFormComponent } from '@acorex/components/form';
 import { AXValidationSummary } from '@acorex/core/validation';
-import { AXPWidgetNode, AXPWidgetRenderMode, AXPWidgetCoreContextChangeEvent, AXPWidgetContainerComponent, AXPWidgetCoreElementAction } from '@acorex/platform/layout/widget-core';
+import { AXPWidgetNode, AXPWidgetRenderMode, AXPWidgetContainerComponent, AXPWidgetCoreElementAction } from '@acorex/platform/layout/widget-core';
 import { AXDataSource } from '@acorex/cdk/common';
 import { AXPopupSizeType } from '@acorex/components/popup';
 import { AXStepWizardLook } from '@acorex/components/step-wizard';
-import { AXPGridLayoutOptions, AXPExpression, AXPValidationRules, AXPOptionsData, AXPActionMenuItem } from '@acorex/platform/core';
+import { AXPMetaData, AXPGridLayoutOptions, AXPActionMenuItem, AXPMultiLanguageString, AXPExpression, AXPValidationRules, AXPOptionsData, AXPContextChangeEvent, AXPExecuteCommandResult } from '@acorex/platform/core';
 import { AXBasePageComponent } from '@acorex/components/page';
+import { AXPCommand } from '@acorex/platform/runtime';
 
 /**
  * Extended widget node properties (excluding type, path, name, options, children)
@@ -29,9 +30,9 @@ type AXPDynamicFormMode = 'view' | 'edit';
 type AXPDynamicFormDirection = 'vertical' | 'horizontal' | 'grid';
 interface AXPDynamicFormFieldDefinition {
     path: string;
-    title?: string;
+    title?: AXPMultiLanguageString;
     badge?: string;
-    description?: string;
+    description?: AXPMultiLanguageString;
     widget: AXPWidgetNode;
     /**
      * Optional per-field rendering mode. Takes precedence over section and form modes.
@@ -41,8 +42,8 @@ interface AXPDynamicFormFieldDefinition {
 }
 interface AXPDynamicFormGroupDefinition {
     name: string;
-    title?: string;
-    description?: string;
+    title?: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
     parameters: AXPDynamicFormFieldDefinition[];
     /**
      * Optional per-section rendering mode. Takes precedence over form mode and is overridden by field mode.
@@ -64,7 +65,7 @@ interface AXPDialogRef {
     /**
      * Manually close the dialog (optional - dialog closes automatically after user interaction)
      */
-    close(): void;
+    close(result?: any): void;
     /**
      * Get the form data from the dialog
      */
@@ -77,6 +78,17 @@ interface AXPDialogRef {
      * Set the loading state of the dialog
      */
     setLoading(loading: boolean): void;
+    /**
+     * Deep-merge partial values into the dialog layout context (e.g. after create returns an id).
+     */
+    patchContext?(partial: Record<string, unknown>): void;
+    /**
+     * Invoke a registered widget's public `api()` method (e.g. step-wizard `next`).
+     */
+    invokeWidget?(widgetName: string, method: string, options?: {
+        setLoading?: (loading: boolean) => void;
+        close?: (result?: any) => void;
+    }): Promise<void>;
 }
 interface LayoutWidgetOptions {
     name?: string;
@@ -87,7 +99,7 @@ interface ValueWidgetOptions extends LayoutWidgetOptions {
     validations?: AXPValidationRules;
 }
 interface TextBoxOptions extends ValueWidgetOptions {
-    placeholder?: string;
+    placeholder?: AXPMultiLanguageString;
     maxLength?: number;
     minLength?: number;
     prefix?: string;
@@ -98,14 +110,14 @@ interface NumberBoxOptions extends ValueWidgetOptions {
     min?: number;
     max?: number;
     step?: number;
-    placeholder?: string;
+    placeholder?: AXPMultiLanguageString;
     format?: string;
 }
 interface SelectBoxOptions extends ValueWidgetOptions {
     dataSource: any[] | (() => any[]) | (() => Promise<any[]>) | AXDataSource<any>;
     valueField?: string;
     textField?: string;
-    placeholder?: string;
+    placeholder?: AXPMultiLanguageString;
     multiple?: boolean;
     searchable?: boolean;
     clearButton?: boolean;
@@ -116,7 +128,7 @@ interface DateTimeBoxOptions extends ValueWidgetOptions {
     format?: string;
     min?: Date | string;
     max?: Date | string;
-    placeholder?: string;
+    placeholder?: AXPMultiLanguageString;
     clearButton?: boolean;
 }
 interface ToggleSwitchOptions extends ValueWidgetOptions {
@@ -128,7 +140,7 @@ interface LargeTextBoxOptions extends ValueWidgetOptions {
     rows?: number;
     maxLength?: number;
     minLength?: number;
-    placeholder?: string;
+    placeholder?: AXPMultiLanguageString;
     resizable?: boolean;
 }
 interface ColorBoxOptions extends ValueWidgetOptions {
@@ -227,12 +239,18 @@ interface AXPFieldsetContainerOptions extends LayoutWidgetOptions {
     isOpen?: boolean;
     look?: 'fieldset' | 'card' | 'group' | 'container';
     disabled?: boolean;
+    showTitle?: boolean;
     showHeader?: boolean;
     cols?: number;
 }
+/** How optional `hint` text is rendered in `form-field` layout widgets. */
+type AXPFormFieldHintDisplayMode = 'icon' | 'note';
 interface AXPFormFieldOptions extends LayoutWidgetOptions {
     label?: string;
     showLabel?: boolean;
+    /** Translated/helper copy; pairing with {@link hintDisplayMode}. */
+    hint?: AXPMultiLanguageString;
+    hintDisplayMode?: AXPFormFieldHintDisplayMode;
 }
 interface AXPDialogContainerOptions extends LayoutWidgetOptions {
     title?: string;
@@ -240,14 +258,35 @@ interface AXPDialogContainerOptions extends LayoutWidgetOptions {
     size?: AXPopupSizeType;
     closeButton?: boolean;
     context?: any;
+    metadata?: AXPMetaData;
+    /**
+     * When set, invoked on footer action with {@link AXPDialogRef}.
+     * Set via {@link IDialogBuilder.onAction}.
+     */
+    onAction?: (dialogRef: AXPDialogRef) => unknown | Promise<unknown>;
+}
+/**
+ * Popup payload for `AXPDialogRendererComponent` (`data.config`) and the `layout-builder.dialog.config` hook.
+ */
+interface AXPLayoutBuilderDialogConfig {
+    title: string;
+    context: Record<string, unknown>;
+    definition: AXPWidgetNode;
+    metadata?: AXPMetaData;
+    actions: NonNullable<DialogBuilderState['actions']>;
+    onAction?: (dialogRef: AXPDialogRef) => unknown | Promise<unknown>;
 }
 interface RichTextOptions extends ValueWidgetOptions {
-    placeholder?: string;
+    placeholder?: AXPMultiLanguageString;
     toolbar?: string[];
     readonly?: boolean;
+    /** Max height (px) for scrollable full preview when `showFullContent` is true. */
+    height?: number;
+    /** When true, view mode renders full HTML in a scrollable area instead of a truncated snippet. */
+    showFullContent?: boolean;
 }
 interface PasswordBoxOptions extends ValueWidgetOptions {
-    placeholder?: string;
+    placeholder?: AXPMultiLanguageString;
     revealToggle?: boolean;
     maxLength?: number;
 }
@@ -269,7 +308,7 @@ interface SelectionListOptions extends ValueWidgetOptions {
     textField?: string;
     multiple?: boolean;
     searchable?: boolean;
-    placeholder?: string;
+    placeholder?: AXPMultiLanguageString;
 }
 interface AXPListWidgetColumn {
     name: string;
@@ -408,7 +447,9 @@ type DialogBuilderState = AXPWidgetNode & {
 interface IActionBuilder {
     cancel(text?: string): IActionBuilder;
     submit(text?: string): IActionBuilder;
-    custom(action: AXPActionMenuItem): IActionBuilder;
+    custom(action: AXPActionMenuItem & {
+        position?: 'prefix' | 'suffix';
+    }): IActionBuilder;
 }
 interface ILayoutBuilder {
     grid(delegate: (container: IGridContainerBuilder) => void): ILayoutBuilder;
@@ -508,6 +549,8 @@ interface IGridContainerBuilder extends IBaseContainerBuilder<IGridContainerBuil
     setBackgroundColor(color: string): IGridContainerBuilder;
     setPadding(padding: string): IGridContainerBuilder;
     setMargin(margin: string): IGridContainerBuilder;
+    /** Add a grid-item-layout child with optional placement; delegate builds the fieldset content. */
+    item(layoutOptions: Partial<AXPGridLayoutOptions> | null | undefined, delegate: (container: IFieldsetContainerBuilder) => void): IGridContainerBuilder;
 }
 interface IPanelContainerBuilder extends IBaseContainerBuilder<IPanelContainerBuilder>, ILayoutContainerBuilder<IPanelContainerBuilder>, IChildContainerBuilder<IPanelContainerBuilder>, IWidgetContainerBuilder<IPanelContainerBuilder> {
     setOptions(options: AXPPanelContainerOptions): IPanelContainerBuilder;
@@ -659,6 +702,11 @@ declare class AXPLayoutRendererComponent implements OnInit {
      */
     mode: _angular_core.InputSignal<AXPDynamicFormMode>;
     protected widgetTree: _angular_core.WritableSignal<AXPWidgetNode | null>;
+    /**
+     * Prefer explicit {@link AXPWidgetNode.mode} on the root node (e.g. dialog flex `mode('view')`)
+     * so nested widgets resolve view vs edit correctly; fall back to the layout `mode` input.
+     */
+    protected effectiveRenderMode: _angular_core.Signal<"view" | "edit" | "column" | "designer" | "print" | "filter">;
     /**
      * Convert layout data to widget tree when inputs change
      */
@@ -685,7 +733,7 @@ declare class AXPLayoutRendererComponent implements OnInit {
     /**
      * Handle context change events from widget container (optimized with RxJS)
      */
-    protected handleContextChanged(event: AXPWidgetCoreContextChangeEvent): void;
+    protected handleContextChanged(event: AXPContextChangeEvent): void;
     /**
      * Get the form component instance
      */
@@ -740,8 +788,40 @@ declare class LayoutBuilderModule {
     static ɵinj: _angular_core.ɵɵInjectorDeclaration<LayoutBuilderModule>;
 }
 
+/**
+ * Runs after dialog options and context are prepared and **before** footer customization and popup open.
+ * Listeners may mutate {@link AXPLayoutBuilderDialogBeforeOpenPayload.context} by reference.
+ */
+declare const AXP_LAYOUT_BUILDER_DIALOG_BEFORE_OPEN_HOOK_KEY = "layout-builder.dialog.before-open";
+interface AXPLayoutBuilderDialogBeforeOpenPayload {
+    context: Record<string, unknown>;
+    dialogOptions: AXPDialogContainerOptions;
+}
+/**
+ * Runs after builder-defined footer actions exist and **before** the dialog opens.
+ * Listeners receive the live `actions.footer.prefix` / `suffix` arrays (same references as the dialog)
+ * so they may push, splice, filter, or replace items. They may also mutate {@link AXPLayoutBuilderDialogFooterPayload.context} by reference.
+ */
+declare const AXP_LAYOUT_BUILDER_DIALOG_CONFIG_HOOK_KEY = "layout-builder.dialog.config";
+/**
+ * Runs whenever the dialog layout builder context changes (debounced upstream), **after** the popup is visible.
+ * Use for side effects that depend on live context (for example values updated by widgets after render).
+ * Payload mirrors `AXPDialogRendererComponent` semantics: {@link AXPLayoutBuilderDialogContextChangedPayload.getContext},
+ * {@link AXPLayoutBuilderDialogContextChangedPayload.patchContext}, and optional loading state.
+ */
+declare const AXP_LAYOUT_BUILDER_DIALOG_CONTEXT_CHANGED_HOOK_KEY = "layout-builder.dialog.context-changed";
+interface AXPLayoutBuilderDialogContextChangedPayload {
+    /** Stable id for this dialog instance; lets listeners correlate repeated emissions or async follow-up work. */
+    sessionKey: string;
+    getContext: () => Record<string, unknown>;
+    metadata: Record<string, unknown> | undefined;
+    patchContext: (partial: Record<string, unknown>) => void;
+    setLoading: (loading: boolean) => void;
+}
+
 declare class AXPLayoutBuilderService {
     private popupService;
+    private readonly hookService;
     /**
      * Create a new layout builder
      */
@@ -816,23 +896,7 @@ declare class AXPLayoutConversionService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<AXPLayoutConversionService>;
 }
 
-interface DialogRendererConfig {
-    title: string;
-    message?: string;
-    context: any;
-    definition: AXPWidgetNode;
-    actions?: {
-        footer?: {
-            prefix?: any[];
-            suffix?: any[];
-        };
-    };
-    /**
-     * When present, handler is called on action click with AXPDialogRef.
-     * Throw = stay open for retry. Return = close and resolve show() with return value.
-     */
-    onAction?: (dialogRef: AXPDialogRef) => any | Promise<any>;
-}
+type DialogRendererConfig = AXPLayoutBuilderDialogConfig;
 interface DialogRendererResult {
     context: any;
     action?: string;
@@ -843,35 +907,93 @@ declare class AXPDialogRendererComponent extends AXBasePageComponent implements
     result: EventEmitter<DialogRendererResult>;
     private widgetCoreService;
     private expressionEvaluator;
+    private readonly commandService;
+    private readonly hookService;
     private dialogResult?;
     context: _angular_core.WritableSignal<any>;
-    callBack: (dialogRef: AXPDialogRef) => void;
+    callBack: (result: unknown) => void;
     data: any;
     private isDialogLoading;
     footerPrefix: _angular_core.WritableSignal<AXPWidgetCoreElementAction[]>;
     footerSuffix: _angular_core.WritableSignal<AXPWidgetCoreElementAction[]>;
+    /**
+     * Correlate layout context snapshots for distributed hooks (`layout-builder.dialog.context-changed`).
+     */
+    private readonly contextChangedHooksSessionKey;
     ngOnInit(): void;
     private layoutRenderer;
     private debounceTimer?;
     handleContextChanged(event: any): void;
     handleContextInitiated(event: any): void;
+    private invokeLayoutContextChangedHooks;
     footerPrefixActions(): AXPWidgetCoreElementAction[];
     footerSuffixActions(): AXPWidgetCoreElementAction[];
     isFormLoading(): boolean;
     isSubmitting(): boolean;
     executeAction(action: AXPWidgetCoreElementAction): Promise<void>;
+    /** Whether the layout form should be validated before running this footer command. */
+    private shouldValidateBeforeAction;
+    /** True when a footer handler or command result asks to leave the dialog open (`keepDialogOpen` on the result or `result.data`). */
+    private shouldKeepDialogOpenAfterCommandResult;
+    private createDialogRef;
+    private closeWithOptionalSkipValidate;
+    /** Resolves footer/widget action command to a string (e.g. `cancel`, `submit`, `widget:...`). */
+    private resolveActionCommandName;
     private parseWidgetCommand;
-    private executeWidgetApi;
+    private invokeWidget;
     close(result?: DialogRendererResult): Promise<void>;
     private aggregateAndEvaluateActions;
     private collectWidgetActions;
     private collectDialogActionsFromConfig;
     private evaluatePredicates;
     private evalBool;
+    /** Resolves footer action title when it contains {{ ... }} (e.g. wizard labels from dialog context). */
+    private evalActionTitle;
     private resolveApi;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AXPDialogRendererComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<AXPDialogRendererComponent, "axp-dialog-renderer", never, {}, { "result": "result"; }, never, never, true, never>;
 }
 
-export { AXPDialogRendererComponent, AXPLayoutBuilderService, AXPLayoutConversionService, AXPLayoutRendererComponent, LayoutBuilderModule };
-export type { AXPDialogContainerOptions, AXPDialogRef, AXPDynamicFormDefinition, AXPDynamicFormDirection, AXPDynamicFormFieldDefinition, AXPDynamicFormGroupDefinition, AXPDynamicFormLook, AXPDynamicFormMode, AXPFieldsetContainerOptions, AXPFlexContainerOptions, AXPFormFieldOptions, AXPGridContainerOptions, AXPListWidgetColumn, AXPListWidgetOptions, AXPListWidgetRowCommand, AXPPageContainerOptions, AXPPanelContainerOptions, AXPStepDefinition, AXPStepWizardContainerOptions, AXPStepWizardDefinition, AXPStepWizardGuardPayload, AXPStepWizardStatus, AXPTabsetContainerOptions, AXPWidgetConfiguration, AXPWidgetNodeExtendedProperties, AXPWizardActionDefinition, AXPWizardActions, ColorBoxOptions, DateTimeBoxOptions, DialogBuilderState, DialogRendererConfig, DialogRendererResult, FormFieldBuilderState, IActionBuilder, IBaseContainerBuilder, IChildContainerBuilder, IDialogBuilder, IFieldsetContainerBuilder, IFlexContainerBuilder, IFormFieldBuilder, IGridContainerBuilder, ILayoutBuilder, ILayoutContainerBuilder, IListWidgetBuilder, IPageContainerBuilder, IPanelContainerBuilder, IStepBuilder, IStepWizardBuilder, ITabsetContainerBuilder, IWidgetBuilder, IWidgetContainerBuilder, InheritanceContext, InheritedProperties, LargeTextBoxOptions, LayoutBuilderState, LayoutWidgetOptions, LookupBoxOptions, NumberBoxOptions, PasswordBoxOptions, RichTextOptions, SelectBoxOptions, SelectionListOptions, TextBoxOptions, ToggleSwitchOptions, ValueWidgetOptions, WidgetBuilderState };
+/** Registration key for {@link AXPPreviewWidgetFieldCommand}; lives alone so `LayoutBuilderModule` can reference it without static-importing the command implementation. */
+declare const AXP_PREVIEW_WIDGET_FIELD_COMMAND_KEY = "Widget:Preview";
+
+/** See `AXP_PREVIEW_WIDGET_FIELD_COMMAND_KEY` in `preview-widget-field.command.key.ts`. */
+interface AXPPreviewWidgetFieldCommandInput {
+    /** Widget node to render (same shape as `widget-field-configurator` model). */
+    widget?: AXPWidgetNode;
+    /**
+     * Alternate property name for the widget node (matches metadata definition `interface` field).
+     */
+    interface?: AXPWidgetNode | string;
+    fieldName?: string;
+    fieldTitle?: AXPMultiLanguageString;
+    name?: string;
+    title?: AXPMultiLanguageString;
+}
+type AXPPreviewWidgetFieldInvocation = AXPPreviewWidgetFieldCommandInput & {
+    __context__?: {
+        data?: Record<string, unknown>;
+        options?: Record<string, unknown>;
+    };
+};
+/**
+ * Opens a dialog that previews a widget configuration (same behavior as the preview button on
+ * `axp-widget-field-configurator`). Invoked from that component and from entity list actions.
+ */
+declare class AXPPreviewWidgetFieldCommand implements AXPCommand<AXPPreviewWidgetFieldCommandInput, void> {
+    private readonly formBuilderService;
+    private readonly widgetRegistry;
+    private readonly translationService;
+    private readonly crudService;
+    execute(input: AXPPreviewWidgetFieldInvocation): Promise<AXPExecuteCommandResult<void>>;
+    private mergeInvocation;
+    private normalizeWidget;
+    private resolveFieldTitleLabel;
+    private isCancelDialogOutcome;
+    private resolveWidgetDisplayTitle;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AXPPreviewWidgetFieldCommand, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<AXPPreviewWidgetFieldCommand>;
+}
+
+export { AXPDialogRendererComponent, AXPLayoutBuilderService, AXPLayoutConversionService, AXPLayoutRendererComponent, AXPPreviewWidgetFieldCommand, AXP_LAYOUT_BUILDER_DIALOG_BEFORE_OPEN_HOOK_KEY, AXP_LAYOUT_BUILDER_DIALOG_CONFIG_HOOK_KEY, AXP_LAYOUT_BUILDER_DIALOG_CONTEXT_CHANGED_HOOK_KEY, AXP_PREVIEW_WIDGET_FIELD_COMMAND_KEY, LayoutBuilderModule };
+export type { AXPDialogContainerOptions, AXPDialogRef, AXPDynamicFormDefinition, AXPDynamicFormDirection, AXPDynamicFormFieldDefinition, AXPDynamicFormGroupDefinition, AXPDynamicFormLook, AXPDynamicFormMode, AXPFieldsetContainerOptions, AXPFlexContainerOptions, AXPFormFieldHintDisplayMode, AXPFormFieldOptions, AXPGridContainerOptions, AXPLayoutBuilderDialogBeforeOpenPayload, AXPLayoutBuilderDialogConfig, AXPLayoutBuilderDialogContextChangedPayload, AXPListWidgetColumn, AXPListWidgetOptions, AXPListWidgetRowCommand, AXPPageContainerOptions, AXPPanelContainerOptions, AXPPreviewWidgetFieldCommandInput, AXPStepDefinition, AXPStepWizardContainerOptions, AXPStepWizardDefinition, AXPStepWizardGuardPayload, AXPStepWizardStatus, AXPTabsetContainerOptions, AXPWidgetConfiguration, AXPWidgetNodeExtendedProperties, AXPWizardActionDefinition, AXPWizardActions, ColorBoxOptions, DateTimeBoxOptions, DialogBuilderState, DialogRendererConfig, DialogRendererResult, FormFieldBuilderState, IActionBuilder, IBaseContainerBuilder, IChildContainerBuilder, IDialogBuilder, IFieldsetContainerBuilder, IFlexContainerBuilder, IFormFieldBuilder, IGridContainerBuilder, ILayoutBuilder, ILayoutContainerBuilder, IListWidgetBuilder, IPageContainerBuilder, IPanelContainerBuilder, IStepBuilder, IStepWizardBuilder, ITabsetContainerBuilder, IWidgetBuilder, IWidgetContainerBuilder, InheritanceContext, InheritedProperties, LargeTextBoxOptions, LayoutBuilderState, LayoutWidgetOptions, LookupBoxOptions, NumberBoxOptions, PasswordBoxOptions, RichTextOptions, SelectBoxOptions, SelectionListOptions, TextBoxOptions, ToggleSwitchOptions, ValueWidgetOptions, WidgetBuilderState };