@ngx-smz/core 21.1.16 → 21.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngx-smz/core",
-  "version": "21.1.16",
+  "version": "21.1.18",
   "peerDependencies": {
     "@angular/animations": ">=21.0.0",
     "@angular/common": ">=21.0.0",

package/resources/assets/scss/dialogs/smz-general-styles.scss

@@ -1,4 +1,4 @@
-@import "./responsive.scss";
+@use "./responsive" as *;
 
 .smz-dialog-minimized {
   z-index: -1 !important;

package/resources/assets/scss/fontawesome-free.scss

@@ -1,2 +1,2 @@
 /* FONTAWESOME FREE */
-@import "@fortawesome/fontawesome-free/css/all.min.css";
+@use "@fortawesome/fontawesome-free/css/all.min.css" as *;

package/resources/assets/scss/smz-dialogs.scss

@@ -1,5 +1,5 @@
-@import "./dialogs/smz-general-styles.scss";
+@use "./dialogs/smz-general-styles" as *;
 // @import "./dialogs/prime10.scss";
 // @import "./dialogs/theme10.scss";
-@import "./dialogs/dialog-ng19.scss";
-@import "./dialogs/menu-ng19.scss";
+@use "./dialogs/dialog-ng19" as *;
+@use "./dialogs/menu-ng19" as *;

package/resources/assets/scss/smz-dock.scss

@@ -1 +1 @@
-@import "./dock/dock.scss";
+@use "./dock/dock" as *;

package/resources/assets/scss/smz-forms.scss

@@ -1 +1 @@
-@import "./forms/forms.scss";
+@use "./forms/forms" as *;

package/resources/assets/scss/styles.scss

@@ -1,51 +1,50 @@
 /* EXTRAS */
-@import "./extras/extras.scss";
+@use "./extras/extras" as *;
 
 /* PRETTY JSON */
-@import "./extras/pretty-json.scss";
+@use "./extras/pretty-json" as *;
 
 /* SMZ-TABLES */
-@import "./smz-tables.scss";
+@use "./smz-tables" as *;
 
 /* SMZ-TREES */
-@import "./smz-trees.scss";
+@use "./smz-trees" as *;
 
 /* COLORS */
-@import "./extras/colors.scss";
+@use "./extras/colors" as *;
 
 /* DIVIDERS */
-@import "./extras/dividers.scss";
+@use "./extras/dividers" as *;
 
 /* PÁGINAS DE ERRO E NOTFOUND */
-@import "./pages/app-exceptions.scss";
+@use "./pages/app-exceptions" as *;
 
 /* DIALOGS */
-@import "./smz-dialogs.scss";
+@use "./smz-dialogs" as *;
 
 /* DOCKS */
-@import "./smz-dock.scss";
+@use "./smz-dock" as *;
 
 /* FORMS */
-@import "./smz-forms.scss";
+@use "./smz-forms" as *;
 
 /* DOCUMENTS */
-@import "./documents/documents.scss";
+@use "./documents/documents" as *;
 
 /* BROWSER STUFFS */
-@import "./extras/browser.scss";
+@use "./extras/browser" as *;
 
-@import "./smz-prime-fix";
+@use "./smz-prime-fix" as *;
 
 /* OVERLAY DO PRIME */
-@import "./overlay-panel/overlay-panel.scss";
+@use "./overlay-panel/overlay-panel" as *;
 
 /* FOI FEITO UM OVERRIDE DO PRIME GRID ORIGINAL PARA ADICIONAR !IMPORTANT */
-@import './prime-grid/grid';
+@use './prime-grid/grid' as *;
 
 /* PRIME ICONS */
-@import "primeicons/primeicons.css";
+@use "primeicons/primeicons.css" as *;
 
 /* ANIMATIONS */
 // @import "hover.css/css/hover-min.css";
-@import "animate.css/animate.min.css";
-
+@use "animate.css/animate.min.css" as *;

package/types/ngx-smz-core.d.ts

@@ -1337,6 +1337,8 @@ interface SmzForm<T> {
     context?: SmzFormContext<T>;
     isDebug?: boolean;
     formId?: string;
+    /** If set, root `<form>` of `smz-form-group` gets `data-testid` with this value. */
+    formTestId?: string;
     behaviors?: SmzFormsBehaviorsConfig;
     functions?: SmzFormsBehaviorsFunctions<T>;
     groups: SmzFormGroup[];
@@ -6615,7 +6617,8 @@ declare class SmzFormConditionalTooltipBuilder<TInput, TResponse> {
     private styleClass;
     private position;
     constructor(inputBuilder: TInput, inputRef: SmzFormsBaseControl, resolveMessage: (formValues: any) => string | null);
-    private initializeTooltip;
+    /** Reassigns the warning signal; `update()` is unsafe when the builder runs inside an Angular `computed` (NG0600). */
+    private applyWarningState;
     withStyleClass(styleClass: string): SmzFormConditionalTooltipBuilder<TInput, TResponse>;
     withPosition(position: 'top' | 'bottom' | 'left' | 'right'): SmzFormConditionalTooltipBuilder<TInput, TResponse>;
     get input(): TInput;
@@ -6907,10 +6910,11 @@ declare class SmzFormPasswordBuilder<TResponse> extends SmzFormInputBuilder<SmzF
     enableToggleMask(): SmzFormPasswordBuilder<TResponse>;
     setStrengthRegex(medium: string, strong: string): SmzFormPasswordBuilder<TResponse>;
 }
-declare class SmzFormInputValidatorBuilder<TInput, TResponse> {
+declare class SmzFormInputValidatorBuilder<TInput, TResponse> extends SmzBuilderUtilities<SmzFormInputValidatorBuilder<TInput, TResponse>> {
     inputRefBuilder: TInput;
     private inputRef;
     groupBuilderRef: SmzFormGroupBuilder<TResponse>;
+    protected that: this;
     constructor(inputRefBuilder: TInput, inputRef: SmzFormsBaseControl, groupBuilderRef: SmzFormGroupBuilder<TResponse>);
     required(): SmzFormInputValidatorBuilder<TInput, TResponse>;
     length(min: number, max: number): SmzFormInputValidatorBuilder<TInput, TResponse>;
@@ -7068,33 +7072,101 @@ declare class SmzFormUiDefinitionBuilder<TResponse> extends SmzBaseUiDefinitionB
     get form(): SmzFormBuilder<TResponse>;
 }
 
+/**
+ * Fluent builder for the entire form model ({@link SmzForm}).
+ *
+ * **Entry point:** start with `new SmzFormBuilder<T>()` (standalone) or obtain via
+ * {@link SmzDialogBuilder.form} when the form is hosted inside a dialog. Always add at least
+ * one {@link SmzFormBuilder.group} before defining controls, then call {@link SmzFormBuilder.build}
+ * to get immutable state for `smz-form-group` / form features.
+ */
 declare class SmzFormBuilder<TResponse> {
     dialogBuilderRef: SmzDialogBuilder<TResponse>;
     private defaultConfig;
     formState: SmzForm<TResponse>;
     createdByUiDefinitions: boolean;
+    /**
+     * @param dialogBuilderRef When non-null, this builder is owned by a dialog feature (see {@link SmzDialogBuilder.form}).
+     * @param state Optional existing {@link SmzForm} to mutate (e.g. UI definition hydration).
+     */
     constructor(dialogBuilderRef?: SmzDialogBuilder<TResponse>, state?: SmzForm<TResponse>);
+    /** Turns on form debug logging in the form group component. */
     debugMode(): SmzFormBuilder<TResponse>;
+    /**
+     * Sets {@link SmzForm.formTestId}: exposed on the root {@code <form>} as {@code data-testid}.
+     * Pass a blank string to clear a previously set id.
+     */
+    withFormTestId(testId: string): SmzFormBuilder<TResponse>;
+    /**
+     * Appends a new form group and returns a builder to add controls, layout, and validators.
+     * @param name Optional group title; when set, the group can show a heading.
+     * @param key Optional key used to identify the group in advanced scenarios (e.g. hide/show, reactions).
+     */
     group(name?: string, key?: string): SmzFormGroupBuilder<TResponse>;
+    /** If set, submitted data keeps nested object shape instead of flattening. */
     disableFlattenResponse(): SmzFormBuilder<TResponse>;
+    /**
+     * When true, per-control custom “on load” logic runs as the form is initialized
+     * (e.g. derived defaults).
+     */
     runCustomFunctionsOnLoad(): SmzFormBuilder<TResponse>;
+    /**
+     * Emits output events for all controls on first load, not only on user interaction
+     * (use when consumers need a full initial snapshot).
+     */
     emitAllOutputsOnLoad(): SmzFormBuilder<TResponse>;
+    /**
+     * Replaces the default “after change” behavior with a custom hook (advanced integration).
+     * Prefer control-level and group-level configuration when possible.
+     */
     setCustomBehavior(callback: (data: SmzFormsResponse<TResponse>, config: SmzForm<TResponse>, form: UntypedFormGroup, outputEvents: Record<string, unknown>) => void): SmzFormBuilder<TResponse>;
+    /**
+     * Sets the separator used in flattened response keys for nested data (e.g. `parent_child`).
+     * The dot (`.`) is not allowed because it is reserved for nested object paths.
+     */
     withNestedResponseKeySeparator(separator: string): SmzFormBuilder<TResponse>;
+    /**
+     * Sets default values on existing control definitions by `propertyName`.
+     * **Requires** at least one group with controls. Unlike {@link applyData}, values are
+     * applied directly as stored default values in the form model.
+     */
     applyValues(...values: {
         propertyName: string;
         value: unknown;
     }[]): SmzFormBuilder<TResponse>;
+    /**
+     * Merges a data object into existing controls (handles simple-entity values by id).
+     * **Requires** at least one group. Set `debug` to log merge steps in the console.
+     */
     applyData(data: Record<string, unknown>, debug?: boolean): SmzFormBuilder<TResponse>;
+    /** Debounce in ms for value emissions / validation feedback (form-level). */
     setDebounceTime(debouceTime: number): SmzFormBuilder<TResponse>;
+    /** Binds value updates to blur so emissions fire when leaving a field, not on every keystroke. */
     emitChangesOnFocusExit(): SmzFormBuilder<TResponse>;
+    /** When appropriate for the host, allows submitting the form on Enter. */
     enableSubmitOnEnter(): SmzFormBuilder<TResponse>;
+    /** Emits on every `change` event (as opposed to blur/submit). */
     emitChangesOnAllChanges(): SmzFormBuilder<TResponse>;
+    /** Skips the first emit pass after the form is built (avoids “dirty on load” in some UIs). */
     avoidEmitChangesOnLoad(): SmzFormBuilder<TResponse>;
+    /** When validation yields multiple issues, show all messages instead of only the first. */
     showMultipleErrorsMessages(): SmzFormBuilder<TResponse>;
+    /**
+     * Form-level custom validator: return `true` if the form is valid for your custom rules.
+     * Works alongside Angular validators on each control.
+     */
     setCustomValidator(callback: (data: SmzFormsResponse<TResponse>, formGroup: UntypedFormGroup) => boolean): SmzFormBuilder<TResponse>;
+    /** When this form was created from a dialog, returns the parent {@link SmzDialogBuilder}. */
     get dialog(): SmzDialogBuilder<TResponse>;
+    /**
+     * Finalizes the form model. Throws if any duplicate `propertyName` exists across groups.
+     * The returned state is what `smz-form-group` consumes as `[config]`.
+     */
     build(): SmzForm<TResponse>;
+    /**
+     * Switches to UI-definition–driven form construction (server or bundle definitions).
+     * Call once; further fluent API usage follows the UI definition builder.
+     */
     fromUiDefinition(entity: string): SmzFormUiDefinitionBuilder<TResponse>;
 }
 
@@ -7226,11 +7298,17 @@ declare class SmzDialogOverlayPanelBuilder<TResponse> extends SmzBuilderUtilitie
     get dialog(): SmzDialogBuilder<TResponse>;
 }
 
+/**
+ * Fluent builder for a modal (or inline) dialog: title, feature stack (form, table, custom component, …),
+ * and button/callback configuration. Chains to {@link SmzFormBuilder} for form content via
+ * {@link SmzDialogBuilder.form} — that is the recommended entry to compose form UIs that open in dialogs.
+ */
 declare class SmzDialogBuilder<TResponse> extends SmzBuilderUtilities<SmzDialogBuilder<TResponse>> {
     protected that: this;
     private defaultConfig;
     dialogState: SmzDialog<TResponse>;
     createdByUiDefinitions: boolean;
+    /** Shown in the dialog header. Pass `null` to clear the title. */
     setTitle(title?: string | null): SmzDialogBuilder<TResponse>;
     useAdvancedResponse(): SmzDialogBuilder<TResponse>;
     closeOnEscape(): SmzDialogBuilder<TResponse>;
@@ -7256,8 +7334,21 @@ declare class SmzDialogBuilder<TResponse> extends SmzBuilderUtilities<SmzDialogB
     setPreset(preset: SmzPresetTypes): SmzDialogBuilder<TResponse>;
     useAsOverlayPanel(elementId: string, guideState: SmzUiGuidesState): SmzDialogOverlayPanelBuilder<TResponse>;
     buttons(): SmzDialogButtonsBuilder<TResponse>;
+    /**
+     * Start dialog construction from a server-side UI definition. Mutually exclusive with manual
+     * `form()` / `component()` / … chains until the definition layer finishes hydrating state.
+     */
     fromUiDefinition(entityName: string): SmzDialogUiDefinitionBuilder<TResponse>;
+    /**
+     * Appends a **form** feature and returns {@link SmzFormBuilder} to define groups/controls in the
+     * usual way. **Primary entry** for “dialog + form” product flows. Pass a prebuilt {@link SmzForm} to
+     * edit existing state, or omit/`null` to start an empty form model owned by the returned builder.
+     */
     form(form?: SmzForm<TResponse>): SmzFormBuilder<TResponse>;
+    /**
+     * Like {@link form} but returns {@link SmzDialogFormBuilder} to set layout on the form feature
+     * container before calling {@link SmzDialogFormBuilder.form} for the {@link SmzFormBuilder} chain.
+     */
     formFeature(): SmzDialogFormBuilder<TResponse>;
     component(component: ComponentDataBase | any): SmzDialogComponentBuilder<TResponse>;
     message(message: string | string[]): SmzDialogBuilder<TResponse>;