@fuentis/phoenix-ui 0.0.9-alpha.550 → 0.0.9-alpha.552

package/index.d.ts

@@ -1240,65 +1240,137 @@ interface MetaFormV2Config {
 
 type AccordionValue = string | number | string[] | number[] | null | undefined;
 declare class MetaFormV2Component implements OnChanges, OnDestroy {
+    /** Form instance created/owned by the parent (dialog/page) */
     form: FormGroup;
+    /**
+     * V2 metadata/config:
+     * - controls (grouped or flat)
+     * - initialValues
+     * - submitValidators (run on submit only)
+     * - setupDependencies (optional runtime bindings)
+     */
     config: MetaFormV2Config;
-    /** Page-level readOnly (parent toggles) */
+    /**
+     * Page-level readOnly state controlled by parent.
+     * Used both for rendering and for "enter edit mode" behavior.
+     */
     readOnly: boolean;
-    /** Optional layout props */
+    /** Optional layout customization for inner content wrapper */
     contentStyle: Record<string, any> | null;
+    /** Optional class name(s) applied to inner content wrapper */
     contentClass: string | null;
+    /** Builds/ensures controls exist (ensures validators & default values are wired) */
     private fb;
+    /** Registers and executes submit-only validators (async validation on submit) */
     private submitValidator;
+    /** Used for validator localization (lang-dependent validators / messages) */
     private translate;
+    /**
+     * A lightweight signature of the current metadata structure.
+     * Used to detect when the form schema changes (and avoid unnecessary resets).
+     */
     private lastSignature;
+    /**
+     * Cleanup function returned by setupDependencies (if any).
+     * Called only when metadata structure changes or on destroy.
+     */
     private depCleanup?;
-    /** PrimeNG accordion active value(s) */
+    /**
+     * PrimeNG Accordion "value" for opened panels.
+     * For multiple panels, PrimeNG expects an array of ids.
+     */
     expandedGroupIds: string[];
     ngOnChanges(changes: SimpleChanges): void;
+    /**
+     * PrimeNG Accordion emits value as:
+     * - single id (string/number)
+     * - array of ids
+     * We normalize everything into string[] for stable internal state.
+     */
     onAccordionValueChange(v: AccordionValue): void;
+    /** Normalizes Accordion value into a stable string[] representation */
     private normalizeAccordionValue;
+    /** True when metadata contains at least one control definition */
     get hasControls(): boolean;
+    /**
+     * Heuristic: grouped config has "ctrl" on first element.
+     * (Keeps template simple and avoids extra schema fields.)
+     */
     get isGrouped(): boolean;
+    /** Returns grouped schema structure (accordion groups) */
     get groupedControls(): any[];
+    /** Returns flat schema structure (grid mode) */
     get flatControls(): any[];
+    /** TrackBy for group rendering */
     groupTrack(g: any, idx: number): any;
-    /** PrimeNG panel value must match accordion value type */
+    /**
+     * PrimeNG accordion panel `value` must match accordion `value` type.
+     * We always convert group id to string for consistent behavior.
+     */
     panelValue(g: any): string;
     /**
-     * Mark & validate ONLY controls that already have a meaningful value.
-     * This prevents "required" errors from showing immediately on CREATE dialogs.
+     * Marks & validates ONLY controls that already have meaningful values.
+     * This is used when switching from readOnly -> edit mode to avoid:
+     * - triggering "required" errors for empty fields
+     * - expanding groups based on empty mandatory fields on CREATE dialogs
      */
     private touchAndValidateOnlyFilledControls;
     /**
-     * What counts as a "meaningful value"?
+     * Defines what counts as a "meaningful" value:
      * - non-empty strings
      * - numbers / booleans
      * - non-empty arrays
-     * - objects with at least one key (or common "selected item" shapes)
+     * - objects with common identifiers (key/uuid/id) or any own keys
      */
     private hasMeaningfulValue;
     /**
-     * Visible invalid = invalid AND (touched OR dirty).
-     * This aligns with the goal: don't expand groups due to empty required fields on create.
+     * "Visible invalid" means:
+     * - invalid
+     * - AND user has interacted with it (touched or dirty)
+     * This matches typical UI behavior: show errors only after interaction.
      */
     private isVisibleInvalid;
+    /**
+     * Checks if a group contains at least one visible invalid control.
+     * Used to auto-expand groups when entering edit mode.
+     */
     private groupHasVisibleInvalid;
-    /** Expand invalid groups but KEEP already opened ones */
+    /**
+     * Expands all groups that contain visible invalid controls,
+     * while preserving any groups already expanded by the user.
+     */
     private expandVisibleInvalidGroupsUnion;
+    /** Cleanup dependency subscriptions when component is destroyed */
     ngOnDestroy(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<MetaFormV2Component, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<MetaFormV2Component, "phoenix-meta-form-v2", never, { "form": { "alias": "form"; "required": true; }; "config": { "alias": "config"; "required": true; }; "readOnly": { "alias": "readOnly"; "required": false; }; "contentStyle": { "alias": "contentStyle"; "required": false; }; "contentClass": { "alias": "contentClass"; "required": false; }; }, {}, never, never, true, never>;
 }
 
 declare class MetaFormFieldV2Component {
+    /** Metadata definition of the field (type, key, options, styles, flags, etc.) */
     field: MetaFieldConfig;
+    /** Parent FormGroup that contains the FormControl for this field */
     form: FormGroup;
-    /** External "page read-only" state; when true, we render read-only fields (like V1). */
+    /**
+     * Page-level read-only flag.
+     * When true, the component renders ReadOnlyInputV2Component instead of editable controls.
+     */
     readOnly: boolean;
+    /**
+     * Global disable flag (e.g. parent dialog toggles entire form disabled).
+     * This is merged with field-level disable configuration.
+     */
     disableForm: boolean;
+    /** Used to manually trigger change detection for OnPush strategy */
     private cdr;
+    /** Used to automatically unsubscribe from value/status streams on destroy */
     private dr;
+    /** Translation service for validation and display labels */
     private translate;
+    /**
+     * Exposed enum-like mapping of MetaFieldType for template usage.
+     * Keeps templates readable and avoids magic strings.
+     */
     readonly MetaFieldType: Readonly<{
         TEXT: "TEXT";
         NUMBER: "NUMBER";
@@ -1324,22 +1396,56 @@ declare class MetaFormFieldV2Component {
         LINKS_DATA: "LINKS_DATA";
         SLOT: "SLOT";
     }>;
+    /** Control key resolved from MetaFieldConfig */
     get key(): string;
+    /** Field type resolved from MetaFieldConfig */
     get type(): MetaFieldType;
+    /** Column width class for grid layout (falls back to default if not provided) */
     get colClass(): string;
     ngOnInit(): void;
+    /** Human-friendly label defined in metadata (already localized key) */
     userFriendlyMessage(): string | null;
+    /** Optional placeholder i18n key defined in metadata */
     placeholderKey(): string | null;
+    /**
+     * Resolves final read-only state for this field:
+     * - page-level readOnly OR field-level readOnly
+     */
     isReadOnly(): boolean;
+    /**
+     * Resolves final disabled state for this field:
+     * - page-level disable OR field-level disable
+     */
     isDisabled(): boolean;
+    /** Shortcut to underlying FormControl */
     ctrl(): _angular_forms.AbstractControl<any, any, any> | null;
-    /** Used by read-only renderer. Keep it simple, same as V1 behavior. */
+    /**
+     * Minimal value formatter for legacy read-only rendering.
+     * Kept intentionally simple to match V1 behavior.
+     */
     displayValue(): any;
+    /**
+     * Determines whether validation error should be displayed.
+     * Errors are shown only after user interaction (touched or dirty).
+     */
     showError(): boolean;
-    /** mapira error key (sync + submit-only async) */
+    /**
+     * Maps control error object to a normalized error key.
+     * Supports:
+     * - Angular built-in validators
+     * - Phoenix custom validators
+     * - Submit-only async validators
+     */
     errorKey(): string | null;
-    /** minimal: posle prevežeš na i18n ključeve */
+    /**
+     * Resolves translated error message based on errorKey().
+     * This is the single place responsible for validation message UX.
+     */
     errorText(): string;
+    /**
+     * Lightweight text formatter for simple read-only display use cases.
+     * This is used mainly for inline displays and summary UIs.
+     */
     valueText(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<MetaFormFieldV2Component, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<MetaFormFieldV2Component, "phoenix-meta-form-field-v2", never, { "field": { "alias": "field"; "required": true; }; "form": { "alias": "form"; "required": true; }; "readOnly": { "alias": "readOnly"; "required": false; }; "disableForm": { "alias": "disableForm"; "required": false; }; }, {}, never, never, true, never>;
@@ -1361,13 +1467,61 @@ type MetaAsyncExecutor = (url: string, body?: any) => Observable<any>;
 declare const META_FORM_ASYNC_EXECUTOR: InjectionToken<MetaAsyncExecutor>;
 
 declare class MetaSubmitValidatorService {
+    /**
+     * Optional async executor abstraction used to perform server-side validation
+     * (e.g. uniqueness checks).
+     *
+     * If not provided, submit-only validators will be skipped gracefully.
+     */
     private executor?;
+    /** Used to automatically clean up subscriptions when the service is destroyed */
     private dr;
-    constructor(executor?: MetaAsyncExecutor | undefined);
+    constructor(
+    /**
+     * Optional async executor abstraction used to perform server-side validation
+     * (e.g. uniqueness checks).
+     *
+     * If not provided, submit-only validators will be skipped gracefully.
+     */
+    executor?: MetaAsyncExecutor | undefined);
+    /**
+     * Registers submit-only validators on the given form.
+     *
+     * - Attaches validator metadata to the form instance (via Symbols)
+     * - Cleans up any previous subscriptions
+     * - Subscribes to valueChanges in order to auto-clear submit-only errors
+     *   when the user modifies the field after a failed submit
+     */
     register(form: FormGroup, validators: MetaSubmitValidatorConfig[] | null | undefined): void;
+    /**
+     * Executes submit-only validators.
+     *
+     * Flow:
+     * 1) Mark all controls as touched/dirty so sync validation messages become visible
+     * 2) If form is sync-invalid, skip async validation
+     * 3) Clear previous submit-only errors
+     * 4) Execute async validators sequentially
+     * 5) Apply mapped errors back to controls
+     *
+     * Returns:
+     * - true  → form is valid (sync + submit-only async)
+     * - false → at least one submit-only validator failed
+     */
     run(form: FormGroup): Promise<boolean>;
+    /**
+     * Removes a specific submit-only error from the control without
+     * touching other validation errors.
+     */
     private removeError;
+    /**
+     * Clears submit-only errors for all controls involved in submit validators.
+     * This does NOT trigger updateValueAndValidity to avoid unnecessary re-validation.
+     */
     private clearSubmitErrors;
+    /**
+     * Marks all form controls as touched and dirty.
+     * This is used on submit to make validation errors visible to the user.
+     */
     private markAllTouchedOnSubmit;
     static ɵfac: i0.ɵɵFactoryDeclaration<MetaSubmitValidatorService, [{ optional: true; }]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<MetaSubmitValidatorService>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuentis/phoenix-ui",
-  "version": "0.0.9-alpha.550",
+  "version": "0.0.9-alpha.552",
   "description": "Phoenix UI Angular component library",
   "license": "MIT",
   "peerDependencies": {