commons-shared-web-ui 0.0.78 → 0.0.80

package/index.d.ts

@@ -3770,6 +3770,70 @@ interface TableColumnSubField {
         defaultValue?: any;
     };
 }
+/**
+ * Resolves raw codes returned by the row API into human-readable labels by
+ * calling a secondary "lookup" API (roles, MDM master data, statuses, ...).
+ *
+ * Works for BOTH shapes of row value:
+ *  - a single code      -> `gender: "GENDER.FEMALE"`           => "Female"
+ *  - an array of codes  -> `roleCodes: ["role.a", "role.b"]`   => "Role A, Role B"
+ * An object value (e.g. `{ code: 'X' }`) is normalized to its `code`/`value`/`id`
+ * before matching, so the same config works regardless of the API shape.
+ *
+ * The lookup API is called ONCE per distinct endpoint (not per row, not per cell)
+ * and the resulting code -> label map is cached for the life of the component.
+ * Columns pointing at the same endpoint share the same cache entry.
+ *
+ * Any HTTP verb is supported (`apiMethod`), with free-form `queryParams`,
+ * `apiPayload` and `headers` — this is not limited to plain GET endpoints.
+ */
+interface ColumnLookupConfig {
+    /**
+     * Name of a shared lookup declared in `TableConfig.lookups`. Any property set
+     * here overrides the shared definition, so `{ "ref": "roles" }` alone is enough
+     * to reuse one lookup across several columns.
+     */
+    ref?: string;
+    /** Lookup endpoint. Supports a `{codes}` / `{value}` placeholder (see `paramName`). */
+    apiUrl?: string;
+    /** HTTP verb. Default: 'GET'. */
+    apiMethod?: 'GET' | 'POST' | 'PUT' | 'PATCH';
+    /** Static request body for non-GET verbs. Merged with `paramName` in targeted mode. */
+    apiPayload?: any;
+    /** Static query params, e.g. `{ classCode: 'CLASS.GENDER', size: 200 }`. Array values are repeated. */
+    queryParams?: {
+        [key: string]: any;
+    };
+    /** Extra headers, merged on top of the table's auth header. */
+    headers?: {
+        [key: string]: string;
+    };
+    /** Path to the array inside the response. Omit (or '') when the response IS the array. e.g. 'elements'. */
+    dataPath?: string;
+    /** Path inside each lookup item holding the code matched against the row value. Default: 'code'. */
+    valueKey?: string;
+    /** Path inside each lookup item holding the label. Supports array indexes, e.g. 'name[0].text'. Default: 'name'. */
+    labelKey?: string;
+    /**
+     * TARGETED MODE. When set, the full list is NOT downloaded: only the distinct
+     * codes present on the current page are requested, under this key.
+     * GET -> query param (`?codes=A,B`); non-GET -> body key (`{ "codes": ["A","B"] }`).
+     * Leave unset to fetch the whole list once and resolve everything client-side.
+     */
+    paramName?: string;
+    /** How multiple codes are sent in targeted mode. Default: 'csv' for GET, 'array' otherwise. */
+    paramFormat?: 'csv' | 'repeat' | 'array';
+    /** Separator used when codes are joined into a CSV param / the `{codes}` placeholder. Default: ','. */
+    paramSeparator?: string;
+    /** Joins the labels when the row value is an array. Default: ', '. */
+    separator?: string;
+    /** Match codes case-insensitively. Default: true. */
+    caseInsensitive?: boolean;
+    /** What to show for a code with no match: 'code' shows the raw code (default), 'empty' drops it. */
+    fallback?: 'code' | 'empty';
+    /** Explicit cache bucket. Defaults to `ref`, else derived from method + url + params + payload. */
+    cacheKey?: string;
+}
 interface TableColumn {
     key: string;
     label: string;
@@ -3791,6 +3855,11 @@ interface TableColumn {
     clickAction?: 'route' | 'callback';
     clickRoute?: string;
     subFields?: TableColumnSubField[];
+    /**
+     * Resolves the code(s) held in this column into display labels via a secondary API.
+     * Handles both a single code and an array of codes. See {@link ColumnLookupConfig}.
+     */
+    lookupConfig?: ColumnLookupConfig;
     editConfig?: {
         disabled?: boolean;
         defaultValue?: any;
@@ -3934,6 +4003,13 @@ interface TableConfig {
     filterData?: {
         [key: string]: any[];
     };
+    /**
+     * Reusable lookup definitions, referenced from a column via
+     * `lookupConfig: { "ref": "<key>" }`. Columns may override any property inline.
+     */
+    lookups?: {
+        [key: string]: ColumnLookupConfig;
+    };
     pagination?: PaginationConfig;
     actions?: TableAction[];
     topBarButtons?: TableAction[];
@@ -5073,6 +5149,12 @@ declare class SmartTableComponent implements OnInit, OnChanges, AfterViewInit, O
     deleteModalOpen: boolean;
     deleteModalConfig: any;
     private pendingDeleteAction;
+    /** code -> label maps for column lookups, bucketed by lookup cache key. */
+    private lookupMaps;
+    /** Guards against firing the same lookup request twice. */
+    private lookupInFlight;
+    /** Full-list lookups already attempted — stops an empty/failed list refetching on every page. */
+    private lookupLoaded;
     searchSubject: Subject<string>;
     stickyHeaders: QueryList<ElementRef>;
     private resizeObserver;
@@ -5130,6 +5212,40 @@ declare class SmartTableComponent implements OnInit, OnChanges, AfterViewInit, O
     getAscOpacity(key: string): number;
     getDescOpacity(key: string): number;
     private replaceParams;
+    /**
+     * Merges a column's inline lookup config with the shared definition it
+     * references (`TableConfig.lookups`). Inline properties win.
+     */
+    private getLookupConfig;
+    /** Bucket the resolved code -> label map lives in. Identical endpoints share one. */
+    private getLookupCacheKey;
+    /**
+     * Fires the lookup request for every column that declares one.
+     * - Full-list mode (no `paramName`): one request per endpoint, ever.
+     * - Targeted mode (`paramName` set): requests only the codes on the current
+     *   page that are not cached yet, so it re-runs as the user pages/searches.
+     */
+    private loadColumnLookups;
+    /** Distinct, non-empty codes held by `col` across the rows currently loaded. */
+    private collectColumnCodes;
+    /** Substitutes the `{codes}` / `{value}` placeholder in a url or param value. */
+    private applyLookupPlaceholders;
+    /**
+     * Issues the lookup request with any verb, then folds the response into the
+     * code -> label map. `codes` is null in full-list mode.
+     */
+    private fetchLookup;
+    /** A label must be printable — objects/arrays degrade to the raw code. */
+    private coerceLookupLabel;
+    /** Map key for a code, honouring `caseInsensitive` (default true). */
+    private normalizeLookupKey;
+    /**
+     * Turns the raw cell value into its label(s). Accepts a single code, an array
+     * of codes, or objects wrapping a code. Unresolved codes are shown as-is
+     * (`fallback: 'code'`, the default) or dropped (`fallback: 'empty'`).
+     * Returns null when nothing is left, so the caller applies `emptyValue`.
+     */
+    private resolveLookupLabel;
     private loadFilterOptions;
     private getValueByPath;
     private calculateStickyPositions;
@@ -5413,6 +5529,14 @@ interface HierarchyCfg {
     colSpan: number;
     payloadPrefix: string;
     dependencyParam: string;
+    /**
+     * Per-classCode overrides, keyed by the template's classCode (e.g. "GREF.REGION_DISTRICT").
+     * Recognized keys: name, label, placeholder, payloadField, colSpan, required, errorMessage,
+     * noDependency, hidden (skip this node but keep walking its children), disabled (render the
+     * generated field as disabled — e.g. to lock a level to a known value), and leaf (stop
+     * descending past this classCode, so deeper template levels — e.g. Ward below District —
+     * are never generated for this consumer).
+     */
     nodes: Record<string, any>;
     branchSubType: string;
     showLoader: boolean;
@@ -5477,4 +5601,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 { ActionVisibility, AlertLabels, AlertVariant, AttachmentConfig, ButtonLabels, ButtonVariant, CheckboxConfig, CheckboxLabels, CheckboxOption, ConfigColumnNode, ConfigFieldNode, ConfigSectionNode, ConfirmationModalConfig, DateConfig, DatePickerConfig, DatepickerLabels, DropdownAction, DropdownConfig, DropdownLabels, DropdownOption, EmailConfig, FieldColSpanPayload, FieldConfig, FieldEventPayload, FieldReorderPayload, 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 };
+export type { ActionVisibility, AlertLabels, AlertVariant, AttachmentConfig, ButtonLabels, ButtonVariant, CheckboxConfig, CheckboxLabels, CheckboxOption, ColumnLookupConfig, ConfigColumnNode, ConfigFieldNode, ConfigSectionNode, ConfirmationModalConfig, DateConfig, DatePickerConfig, DatepickerLabels, DropdownAction, DropdownConfig, DropdownLabels, DropdownOption, EmailConfig, FieldColSpanPayload, FieldConfig, FieldEventPayload, FieldReorderPayload, 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.78",
+  "version": "0.0.80",
   "peerDependencies": {
     "@angular/animations": "20.3.15",
     "@angular/cdk": "20.2.14",