commons-shared-web-ui 0.0.58 → 0.0.60

package/index.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { OnChanges, EventEmitter, SimpleChanges, ChangeDetectorRef, OnInit, OnDestroy, ElementRef, QueryList, PipeTransform, AfterViewInit, NgZone } from '@angular/core';
+import { OnChanges, EventEmitter, SimpleChanges, ChangeDetectorRef, OnInit, AfterViewInit, OnDestroy, ElementRef, QueryList, PipeTransform, NgZone } from '@angular/core';
 import * as i2 from '@angular/material/snack-bar';
 import { MatSnackBar, MatSnackBarRef } from '@angular/material/snack-bar';
 import * as i2$1 from '@angular/common';
@@ -258,6 +258,14 @@ interface FieldConfig {
     subType?: string;
     visible?: boolean;
     visibilityExpression?: string;
+    /**
+     * A boolean expression string (same syntax as visibilityExpression) evaluated
+     * at runtime to dynamically toggle the `required` validator on this control.
+     * When omitted, the static `required` boolean governs validation as before —
+     * fully backwards-compatible.
+     * Example: "[12,15].indexOf(Number(sessionTypeId)) !== -1"
+     */
+    requiredExpression?: string;
     isEnabled?: boolean;
     required?: boolean;
     disabled?: boolean;
@@ -1387,10 +1395,11 @@ interface TimePickerConfig {
     disabledColor?: string;
 }
 
-declare class FormFieldComponent implements OnInit, OnDestroy {
+declare class FormFieldComponent implements OnInit, AfterViewInit, OnDestroy {
     private fb;
     private expressionService;
     private http;
+    private hostRef;
     config: FieldConfig;
     controller: SmartFormController;
     /**
@@ -1446,6 +1455,7 @@ declare class FormFieldComponent implements OnInit, OnDestroy {
     mediaDeviceInput: ElementRef<HTMLInputElement>;
     /** Host div for the library picker — always in DOM, moved to body to escape parent transforms */
     libraryModalRef: ElementRef<HTMLDivElement>;
+    private portalElement;
     showMediaMenu: boolean;
     showYoutubeInput: boolean;
     youtubeUrlInput: string;
@@ -1525,7 +1535,9 @@ declare class FormFieldComponent implements OnInit, OnDestroy {
      * Priority: sectionConfig.name > field.name > camelCase(label) > '__group__'
      */
     get groupKey(): string;
-    constructor(fb: FormBuilder, expressionService: ExpressionService, http: HttpClient);
+    constructor(fb: FormBuilder, expressionService: ExpressionService, http: HttpClient, hostRef: ElementRef<HTMLElement>);
+    /** Portal root, resolved from this component's own node rather than the global document. */
+    private get portalRoot();
     ngOnInit(): void;
     get addMultiLabel(): string;
     /** Getter for Select placeholder label */
@@ -1588,6 +1600,25 @@ declare class FormFieldComponent implements OnInit, OnDestroy {
      */
     setupMatchValidation(): void;
     setupVisibility(): void;
+    /**
+     * When config.requiredExpression is set, dynamically re-evaluates the required
+     * validator whenever any referenced variable changes in the controller.
+     * Fully backwards-compatible: fields without requiredExpression are unaffected.
+     */
+    setupRequiredExpression(): void;
+    /**
+     * Returns all validators from getValidators() except Validators.required.
+     * Used by setupRequiredExpression() to rebuild the validator list without
+     * duplicating the required validator.
+     */
+    private getValidatorsWithoutRequired;
+    /**
+     * trackBy function for field *ngFor loops in ROW containers.
+     * Keying by field name (or type as fallback for unnamed containers) prevents
+     * Angular from destroying and recreating FormFieldComponent instances on re-render,
+     * preserving localOptionList cache and avoiding duplicate API calls.
+     */
+    trackByFieldName(_: number, field: FieldConfig): string;
     setupMinDateField(): void;
     /**
      * Wires up a dynamic minimum for a TIME field from a sibling TIME field
@@ -1684,7 +1715,7 @@ declare class FormFieldComponent implements OnInit, OnDestroy {
     /** Execute client-side or server-side dropdown search. */
     private executeDropdownSearch;
     /** Resets the dropdown search text and filtered list. */
-    resetDropdownSearch(): void;
+    resetDropdownSearch(forceLoad?: boolean, bypassCache?: boolean): void;
     /** Merges option(s) from selectedOptionsData into the local dropdown options list */
     mergeSelectedOptionsIntoList(): void;
     /**
@@ -2034,6 +2065,14 @@ declare class FormSectionComponent implements OnInit, OnDestroy {
     get flatFormGroup(): FormGroup;
     /** Flatten a field tree to get all leaf fields (for ROW children etc.) */
     getFlatFields(fields: FieldConfig[]): FieldConfig[];
+    /**
+     * trackBy function for field *ngFor loops.
+     * Keying by field name (or type as fallback for unnamed containers) prevents
+     * Angular from destroying and recreating FormFieldComponent instances when the
+     * parent re-renders — preserving localOptionList cache and avoiding duplicate
+     * API calls.
+     */
+    trackByFieldName(_: number, field: FieldConfig): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<FormSectionComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<FormSectionComponent, "lib-form-section", never, { "config": { "alias": "config"; "required": false; }; "controller": { "alias": "controller"; "required": false; }; "formGroup": { "alias": "formGroup"; "required": false; }; }, {}, never, never, false, never>;
 }
@@ -3391,7 +3430,39 @@ interface TableFilter {
     handling?: 'standard' | 'nested_string';
     nestedStringConfig?: NestedStringConfig;
 }
-interface TableActionItem {
+/**
+ * A single condition evaluated against a row to decide action visibility.
+ *
+ * `field` is a path into the row (supports nesting + array index, e.g.
+ * 'status.code', 'subStatus.code', 'name[0].text'). When the resolved value is
+ * an object (e.g. `{ code, name, value }`), it is normalized to its `code`
+ * (then `name`, then `value`) so the SAME rule works whether the API returns
+ * `status: { code: 'ACTIVE' }` or `status: 'ACTIVE'`.
+ *
+ * String comparisons are case-insensitive.
+ */
+interface VisibilityRule {
+    /** Path into the row, e.g. 'status.code' or just 'status'. */
+    field: string;
+    /** Comparison operator. Default: 'eq'. */
+    operator?: 'eq' | 'neq' | 'in' | 'nin' | 'truthy' | 'falsy';
+    /** Comparison value for 'eq' / 'neq'. */
+    value?: any;
+    /** Comparison list for 'in' / 'nin'. */
+    values?: any[];
+}
+/**
+ * Row-aware visibility config shared by actions and action items.
+ * - `visibleWhen`: ALL rules must pass (AND) for the action to show.
+ * - `hiddenWhen`: if ANY rule passes (OR), the action is hidden.
+ * `hiddenWhen` takes precedence over `visibleWhen`. Either may be a single
+ * rule or an array of rules.
+ */
+interface ActionVisibility {
+    visibleWhen?: VisibilityRule | VisibilityRule[];
+    hiddenWhen?: VisibilityRule | VisibilityRule[];
+}
+interface TableActionItem extends ActionVisibility {
     label: string;
     type: 'api' | 'callback' | 'route' | 'delete';
     icon?: string;
@@ -3413,7 +3484,7 @@ interface TableActionItem {
         cancelLabel?: string;
     };
 }
-interface TableAction {
+interface TableAction extends ActionVisibility {
     label: string;
     type: 'api' | 'callback' | 'route' | 'edit' | 'dropdown';
     icon?: string;
@@ -4637,10 +4708,30 @@ declare class SmartTableComponent implements OnInit, OnChanges, AfterViewInit, O
     private calculateStickyPositions;
     private toTitleCase;
     get columnCount(): number;
-    /** Filters out actions/action-items explicitly disabled via `isEnabled: false`. */
+    /**
+     * Filters out actions/action-items that are either explicitly disabled via
+     * `isEnabled: false` or hidden for the given row by their `visibleWhen` /
+     * `hiddenWhen` rules. Pass `row` to enable the row-aware rule evaluation;
+     * omit it (e.g. for header/colspan calculations) to evaluate `isEnabled` only.
+     */
     getVisibleActions<T extends {
         isEnabled?: boolean;
-    }>(actions?: T[] | null): T[];
+    } & ActionVisibility>(actions?: T[] | null, row?: any): T[];
+    /**
+     * Evaluates an action's `visibleWhen` / `hiddenWhen` rules against a row.
+     * `hiddenWhen` wins over `visibleWhen`. With no row or no rules, returns true.
+     */
+    private isActionVisibleForRow;
+    /** Evaluates a single visibility rule against a row. */
+    private evaluateRule;
+    /**
+     * Normalizes a value for comparison. Objects shaped like `{ code, name, value }`
+     * collapse to their `code` (then `name`, then `value`) so a rule targeting
+     * `status` works whether the API returns an object or a plain string.
+     */
+    private normalizeRuleValue;
+    /** Case-insensitive comparison for strings; strict-ish equality otherwise. */
+    private ruleValuesEqual;
     get showPagination(): boolean;
     private applyPaginationDefaults;
     onColumnClick(row: any, col: TableColumn): void;
@@ -4928,4 +5019,4 @@ declare class SnackbarModule {
 }
 
 export { AlertComponent, AlertModule, ButtonComponent, ButtonDropdownComponent, ButtonDropdownModule, ButtonModule, CheckboxComponent, ClickOutsideDirective, ConfigColumnNodeComponent, ConfigFieldNodeComponent, ConfigSchemaTreeService, ConfigSectionNodeComponent, ConfigurableFormComponent, configurableForm_examples_d as ConfigurableFormExamples, ConfigurableFormModule, ConfirmationModalComponent, ConfirmationModalModule, DEFAULT_ITEMS_PER_PAGE, DEFAULT_PAGE_SIZE_OPTIONS, DEFAULT_SIDE_NAV_TOOLTIP_POSITION, DatepickerComponent, DropdownComponent, ExpressionService, FieldConfigurationService, FieldConfiguratorComponent, FieldSelectionComponent, FilterComponent, FilterModule, FilterSidebarComponent, FilterSidebarModule, FilterTableSelectorComponent, FilterTableSelectorModule, FormBuilderModule, FormComponentsModule, FormFieldConfigurationComponent, FormFieldConfigurationModule, InputComponent, MaterialModule, NAV_ORIENTATION_DEFAULT, NAV_VARIANT_DEFAULT, NavComponent, NavModule, PAGINATION_THEME_DARK, PAGINATION_THEME_DEFAULT, PaginationComponent, PaginationModule, RadioComponent, SearchComponent, SharedUiModule, SideNavComponent, SideNavModule, SmartFormComponent, SmartFormController, smartForm_examples_d as SmartFormExamples, SmartFormModule, SmartTableComponent, SmartTableModule, SnackbarComponent, SnackbarModule, SnackbarService, StringUtils, SummaryCardComponent, SummaryCardModule, TableColumnConfigurationComponent, TableColumnConfigurationModule, TableColumnConfigurationService, TimePickerComponent, TimePickerModule, TimeWheelPanelComponent, ToggleComponent, ValidationUtils, appendBaseUrlRecursively, clearLocalStorage, clearSessionStorage, getLocalStorageItem, getSessionStorageItem, removeLocalStorageItem, removeSessionStorageItem, setLocalStorageItem, setSessionStorageItem, translateConfig };
-export type { AlertLabels, AlertVariant, AttachmentConfig, ButtonLabels, ButtonVariant, CheckboxConfig, CheckboxLabels, CheckboxOption, ConfigColumnNode, ConfigFieldNode, ConfigSectionNode, ConfirmationModalConfig, DateConfig, DatePickerConfig, DatepickerLabels, DropdownAction, DropdownConfig, DropdownLabels, DropdownOption, EmailConfig, FieldConfig, FieldEventPayload, FieldType, FilterChangeEvent, FilterConfig, FilterItem, FilterItemType, FilterOutput, FilterPanelConfig, FilterParamMap, FilterSearchConfig, FilterSidebarChangeEvent, FilterSidebarConfig, FilterSidebarOutput, FilterTableConfig, FilterTableSelectorConfig, FormConfig, FormField, FormOption, FormSchema, FormSection, GeneratedConfig, HierarchyCfg, IconInput, InputConfig, InputLabels, InputType, JsonFieldConfig, JsonFormConfig, KeyType, LengthConstraint, LocationConfig, NavItem, NavStyleConfig, NestedStringConfig, NumberConfig, OptionConfig, OptionDTO, OptionItem, PaginationConfig, PaginationLabels, PhoneConfig, QueryParamsConfig, RadioConfig, RadioLabels, RadioOption, RangeConfig, RatingConfig, SearchConfig, SearchLabels, SectionConfig, SelectionConfig, SideNavItem, SideNavSection, SideNavStyleConfig, SnackbarConfig, SnackbarVariant, StepperConfig, SubmitConfig, SuffixActionIcon, SummaryCardConfig, SummaryCardLabels, SummaryCardMeta, TableAction, TableActionItem, TableColumn, TableColumnSubField, TableConfig, TableDataChangeEvent, TableFilter, TableFilterChangeEvent, TableFilterColumn, TableFilterConfig, TableFilterItem, TableFilterLabels, TableFilterOutput, TableLabels, TableOption, TableRowSaveEvent, TableTheme, TextConfig, TimeMode, TimePickerConfig, TimePickerLabels, TimePickerVariant, ToggleConfig, ToggleLabels, UIConfig, UISubType, UIType, UploadedFile, ValidationResult, ValidationRules };
+export type { ActionVisibility, AlertLabels, AlertVariant, AttachmentConfig, ButtonLabels, ButtonVariant, CheckboxConfig, CheckboxLabels, CheckboxOption, ConfigColumnNode, ConfigFieldNode, ConfigSectionNode, ConfirmationModalConfig, DateConfig, DatePickerConfig, DatepickerLabels, DropdownAction, DropdownConfig, DropdownLabels, DropdownOption, EmailConfig, FieldConfig, FieldEventPayload, FieldType, FilterChangeEvent, FilterConfig, FilterItem, FilterItemType, FilterOutput, FilterPanelConfig, FilterParamMap, FilterSearchConfig, FilterSidebarChangeEvent, FilterSidebarConfig, FilterSidebarOutput, FilterTableConfig, FilterTableSelectorConfig, FormConfig, FormField, FormOption, FormSchema, FormSection, GeneratedConfig, HierarchyCfg, IconInput, InputConfig, InputLabels, InputType, JsonFieldConfig, JsonFormConfig, KeyType, LengthConstraint, LocationConfig, NavItem, NavStyleConfig, NestedStringConfig, NumberConfig, OptionConfig, OptionDTO, OptionItem, PaginationConfig, PaginationLabels, PhoneConfig, QueryParamsConfig, RadioConfig, RadioLabels, RadioOption, RangeConfig, RatingConfig, SearchConfig, SearchLabels, SectionConfig, SelectionConfig, SideNavItem, SideNavSection, SideNavStyleConfig, SnackbarConfig, SnackbarVariant, StepperConfig, SubmitConfig, SuffixActionIcon, SummaryCardConfig, SummaryCardLabels, SummaryCardMeta, TableAction, TableActionItem, TableColumn, TableColumnSubField, TableConfig, TableDataChangeEvent, TableFilter, TableFilterChangeEvent, TableFilterColumn, TableFilterConfig, TableFilterItem, TableFilterLabels, TableFilterOutput, TableLabels, TableOption, TableRowSaveEvent, TableTheme, TextConfig, TimeMode, TimePickerConfig, TimePickerLabels, TimePickerVariant, ToggleConfig, ToggleLabels, UIConfig, UISubType, UIType, UploadedFile, ValidationResult, ValidationRules, VisibilityRule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commons-shared-web-ui",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "peerDependencies": {
     "@angular/animations": "20.3.15",
     "@angular/cdk": "20.2.14",