@dynatrace/strato-components 3.2.1 → 3.3.1

package/filters/filter-field/suggestions/SuggestionDetails.d.ts

@@ -12,6 +12,6 @@ export type FilterFieldSuggestionDetailsProps = WithChildren & StylingProps & Da
  * @public
  */
 export declare const SuggestionDetails: {
-    (props: FilterFieldSuggestionDetailsProps): import("react/jsx-runtime.js").JSX.Element;
+    (props: FilterFieldSuggestionDetailsProps): import("react/jsx-runtime").JSX.Element;
     displayValue: string;
 };

package/filters/filter-field/suggestions/SuggestionDetails.sty.js

@@ -23,5 +23,5 @@ __export(SuggestionDetails_css_exports, {
 });
 module.exports = __toCommonJS(SuggestionDetails_css_exports);
 var import_SuggestionDetails_css_ts_vanilla = require("./SuggestionDetails.css");
-var suggestionDetails = "_tn2lgm0-3-2-1";
-var suggestionDetailsText = "_tn2lgm1-3-2-1";
+var suggestionDetails = "_tn2lgm0-3-3-1";
+var suggestionDetailsText = "_tn2lgm1-3-3-1";

package/filters/filter-field/suggestions/SuggestionGroup.css

@@ -1,4 +1,4 @@
-._1smjoa12-3-2-1:not(:first-child) > ._5cheea1-3-2-1::before {
+._1smjoa12-3-3-1:not(:first-child) > ._5cheea1-3-3-1::before {
   content: "";
   position: relative;
   display: block;
@@ -6,17 +6,17 @@
   padding-top: var(--dt-spacings-size-8, 8px);
   border-bottom: var(--dt-borders-width-default, 1px) var(--dt-borders-style-default, solid) var(--dt-colors-border-neutral-default, #dadbe4);
 }
-._5cheea2-3-2-1 {
+._5cheea2-3-3-1 {
   position: relative;
   margin: 0;
   padding: 0;
   list-style-type: none;
   height: fit-content;
 }
-._5cheea2-3-2-1:not(:first-child)::before,
-    ._5cheea0-3-2-1:not(:first-child) ._5cheea2-3-2-1::before,
-    ._ssu5rt2-3-2-1:not(._5cheea0-3-2-1) ._1smjoa12-3-2-1:has(._5cheea2-3-2-1):not(:first-child) ._5cheea2-3-2-1::before,
-    ._ssu5rt2-3-2-1:not(._5cheea0-3-2-1) ._1smjoa12-3-2-1:has(._5cheea2-3-2-1):has(+ ._1smjoa12-3-2-1 > :not(._5cheea2-3-2-1)) ._5cheea2-3-2-1::after
+._5cheea2-3-3-1:not(:first-child)::before,
+    ._5cheea0-3-3-1:not(:first-child) ._5cheea2-3-3-1::before,
+    ._ssu5rt2-3-3-1:not(._5cheea0-3-3-1) ._1smjoa12-3-3-1:has(._5cheea2-3-3-1):not(:first-child) ._5cheea2-3-3-1::before,
+    ._ssu5rt2-3-3-1:not(._5cheea0-3-3-1) ._1smjoa12-3-3-1:has(._5cheea2-3-3-1):has(+ ._1smjoa12-3-3-1 > :not(._5cheea2-3-3-1)) ._5cheea2-3-3-1::after
    {
   content: "";
   position: relative;

package/filters/filter-field/suggestions/SuggestionGroup.d.ts

@@ -3,6 +3,6 @@ import type { FilterFieldSuggestionGroupProps } from './SuggestionGroup.types.js
  * @public
  */
 export declare const SuggestionGroup: {
-    (props: FilterFieldSuggestionGroupProps): import("react/jsx-runtime.js").JSX.Element;
+    (props: FilterFieldSuggestionGroupProps): import("react/jsx-runtime").JSX.Element;
     displayValue: string;
 };

package/filters/filter-field/suggestions/SuggestionGroup.sty.js

@@ -26,6 +26,6 @@ module.exports = __toCommonJS(SuggestionGroup_css_exports);
 var import_SuggestionsOverlay_css_ts_vanilla = require("./SuggestionsOverlay.css");
 var import_Suggestion_css_ts_vanilla = require("./Suggestion.css");
 var import_SuggestionGroup_css_ts_vanilla = require("./SuggestionGroup.css");
-var builtInSuggestionsContainer = "_5cheea0-3-2-1";
-var groupHeaderSeparator = "_5cheea1-3-2-1";
-var suggestionGroup = "_5cheea2-3-2-1";
+var builtInSuggestionsContainer = "_5cheea0-3-3-1";
+var groupHeaderSeparator = "_5cheea1-3-3-1";
+var suggestionGroup = "_5cheea2-3-3-1";

package/filters/filter-field/suggestions/SuggestionGroup.types.d.ts

@@ -8,7 +8,7 @@ import type { StylingProps } from '../../../core/types/styling-props.js';
  * FilterFieldSuggestionGroup properties
  * @public
  */
-export type FilterFieldSuggestionGroup = DOMProps & {
+export type FilterFieldSuggestionGroup = DOMProps & AriaLabelingProps & {
     /**
      * Label rendered for the suggestion group.
      * If a `FilterField.SuggestionGroupLabel` is present, it will override the label prop.
@@ -26,4 +26,4 @@ export type FilterFieldSuggestionGroup = DOMProps & {
  * Accepted properties for FilterField suggestion group.
  * @public
  */
-export type FilterFieldSuggestionGroupProps = PropsWithChildren<FilterFieldSuggestionGroup & AriaLabelingProps & StylingProps & DataTestId>;
+export type FilterFieldSuggestionGroupProps = PropsWithChildren<FilterFieldSuggestionGroup & StylingProps & DataTestId>;

package/filters/filter-field/suggestions/SuggestionGroupLabel.css

@@ -1,4 +1,4 @@
-._1mfalko0-3-2-1 {
+._1mfalko0-3-3-1 {
   padding: var(--dt-spacings-size-12, 12px);
   padding-bottom: var(--dt-spacings-size-4, 4px);
   color: var(--dt-colors-text-neutral-subdued, #595a7d);

package/filters/filter-field/suggestions/SuggestionGroupLabel.d.ts

@@ -11,6 +11,6 @@ export type FilterFieldSuggestionGroupLabelProps = WithChildren & DOMProps & Sty
  * @public
  */
 export declare const SuggestionGroupLabel: {
-    (props: FilterFieldSuggestionGroupLabelProps): import("react/jsx-runtime.js").JSX.Element;
+    (props: FilterFieldSuggestionGroupLabelProps): import("react/jsx-runtime").JSX.Element;
     displayValue: string;
 };

package/filters/filter-field/suggestions/SuggestionGroupLabel.sty.js

@@ -22,4 +22,4 @@ __export(SuggestionGroupLabel_css_exports, {
 });
 module.exports = __toCommonJS(SuggestionGroupLabel_css_exports);
 var import_SuggestionGroupLabel_css_ts_vanilla = require("./SuggestionGroupLabel.css");
-var suggestionGroupLabel = "_1mfalko0-3-2-1";
+var suggestionGroupLabel = "_1mfalko0-3-3-1";

package/filters/filter-field/suggestions/SuggestionPin.d.ts

@@ -18,4 +18,4 @@ export declare function SuggestionPin(props: Readonly<{
     disabled?: boolean;
     'aria-disabled'?: boolean;
     showError?: boolean;
-}>): import("react/jsx-runtime.js").JSX.Element | null;
+}>): import("react/jsx-runtime").JSX.Element | null;

package/filters/filter-field/suggestions/SuggestionTips.css

@@ -1,22 +1,22 @@
-._1dx7u80-3-2-1 {
-  --_1igzksy0-3-2-1: var(--dt-borders-radius-surface-subdued, 9px);
+._1dx7u80-3-3-1 {
+  --_1igzksy0-3-3-1: var(--dt-borders-radius-surface-subdued, 9px);
 }
-._1dx7u81-3-2-1 {
+._1dx7u81-3-3-1 {
   color: var(--dt-colors-text-neutral-subdued, #595a7d);
   flex: 1;
 }
-._1dx7u82-3-2-1 {
+._1dx7u82-3-3-1 {
   width: 100%;
   overflow: hidden;
   transform-origin: center;
 }
-._1dx7u84-3-2-1 {
+._1dx7u84-3-3-1 {
   overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
 }
-@container _ssu5rt0-3-2-1 (max-width: 289px) {
-  ._1dx7u83-3-2-1 {
+@container _ssu5rt0-3-3-1 (max-width: 289px) {
+  ._1dx7u83-3-3-1 {
     flex-direction: column;
     width: 100%;
   }

package/filters/filter-field/suggestions/SuggestionTips.d.ts

@@ -1,4 +1,4 @@
 /**
  * @public
  */
-export declare const SuggestionTips: () => import("react/jsx-runtime.js").JSX.Element;
+export declare const SuggestionTips: () => import("react/jsx-runtime").JSX.Element;

package/filters/filter-field/suggestions/SuggestionTips.js

@@ -132,6 +132,7 @@ const SuggestionTips = () => {
                   (0, import_textStyle_css.textStyle)({ textStyle: "small" }),
                   styles.docsLink
                 ),
+                "data-dt-name": "FilterSyntax",
                 children: intl.formatMessage(import_messages.filterFieldMessages.docsLink)
               }
             )

package/filters/filter-field/suggestions/SuggestionTips.sty.js

@@ -27,8 +27,8 @@ __export(SuggestionTips_css_exports, {
 module.exports = __toCommonJS(SuggestionTips_css_exports);
 var import_SuggestionsOverlay_css_ts_vanilla = require("./SuggestionsOverlay.css");
 var import_SuggestionTips_css_ts_vanilla = require("./SuggestionTips.css");
-var docsLink = "_1dx7u84-3-2-1";
-var suggestionTips = "_1dx7u80-3-2-1";
-var suggestionTipsContent = "_1dx7u83-3-2-1";
-var suggestionTipsWrapper = "_1dx7u82-3-2-1";
-var suggstionTipsEllipsis = "_1dx7u81-3-2-1";
+var docsLink = "_1dx7u84-3-3-1";
+var suggestionTips = "_1dx7u80-3-3-1";
+var suggestionTipsContent = "_1dx7u83-3-3-1";
+var suggestionTipsWrapper = "_1dx7u82-3-3-1";
+var suggstionTipsEllipsis = "_1dx7u81-3-3-1";

package/filters/filter-field/suggestions/Suggestions.d.ts

@@ -14,6 +14,6 @@ export type FilterFieldSuggestionsProps = WithChildren & StylingProps & DataTest
  * @public
  */
 export declare const Suggestions: {
-    (props: FilterFieldSuggestionsProps): import("react/jsx-runtime.js").JSX.Element;
+    (props: FilterFieldSuggestionsProps): import("react/jsx-runtime").JSX.Element;
     displayValue: string;
 };

package/filters/filter-field/suggestions/Suggestions.js

@@ -60,6 +60,9 @@ var import_Surface = require("../../../layouts/surface/Surface.js");
 var import_CSSHighlight = require("../components/CSSHighlight.js");
 var import_useFilterFieldContext = require("../hooks/useFilterFieldContext.js");
 var import_flatten_suggestions = require("../utils/suggestions-utils/flatten-suggestions.js");
+function toGroupLabelId(groupId) {
+  return `group-label-${groupId.replace(/\s+/g, "-")}`;
+}
 function renderFlattenedSuggestionItem(flatItem, trailing) {
   switch (flatItem.kind) {
     case "group-header": {
@@ -84,7 +87,7 @@ function renderFlattenedSuggestionItem(flatItem, trailing) {
       };
     }
     case "suggestion": {
-      const ariaDescribedBy = flatItem.groupId ? `group-label-${flatItem.groupId}` : void 0;
+      const ariaDescribedBy = flatItem.groupId ? toGroupLabelId(flatItem.groupId) : void 0;
       return {
         child: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
           import_Suggestion.Suggestion,
@@ -98,12 +101,14 @@ function renderFlattenedSuggestionItem(flatItem, trailing) {
       };
     }
     case "react-node": {
-      const ariaDescribedBy = flatItem.groupId ? `group-label-${flatItem.groupId}` : void 0;
+      const groupLabelId = flatItem.groupId ? toGroupLabelId(flatItem.groupId) : void 0;
       let child = flatItem.node;
       let key = "";
-      if ((0, import_react.isValidElement)(flatItem.node) && ariaDescribedBy) {
+      if ((0, import_react.isValidElement)(flatItem.node) && groupLabelId) {
+        const existing = flatItem.node.props["aria-describedby"] ?? "";
+        const merged = existing ? `${existing} ${groupLabelId}` : groupLabelId;
         child = (0, import_react.cloneElement)(flatItem.node, {
-          "aria-describedby": ariaDescribedBy
+          "aria-describedby": merged
         });
         key = `react-node-${flatItem.node.key}`;
       }
@@ -321,7 +326,7 @@ const Suggestions = (props) => {
       "data-testid": dataTestId,
       children: [
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_AriaLiveInfo.AriaLiveInfo, { flattenedSuggestionItems }),
-        groupMetadata.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_VisuallyHidden.VisuallyHidden, { children: groupMetadata.map(({ groupId, label }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { id: `group-label-${groupId}`, children: label }, groupId)) }),
+        groupMetadata.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_VisuallyHidden.VisuallyHidden, { children: groupMetadata.map(({ groupId, label }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { id: toGroupLabelId(groupId), children: label }, groupId)) }),
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
           "div",
           {

package/filters/filter-field/suggestions/SuggestionsOverlay.css

@@ -1,23 +1,23 @@
-._ssu5rt1-3-2-1 {
+._ssu5rt1-3-3-1 {
   display: flex;
   flex-direction: column;
   gap: var(--dt-spacings-size-4, 4px);
   container-type: inline-size;
-  container-name: _ssu5rt0-3-2-1;
+  container-name: _ssu5rt0-3-3-1;
   transform-origin: top;
 }
-._ssu5rt2-3-2-1 {
+._ssu5rt2-3-3-1 {
   box-sizing: border-box;
   padding: 0;
 }
-._ssu5rt2-3-2-1._ssu5rt2-3-2-1 {
-  --_1igzksy0-3-2-1: var(--dt-borders-radius-surface-subdued, 9px);
+._ssu5rt2-3-3-1._ssu5rt2-3-3-1 {
+  --_1igzksy0-3-3-1: var(--dt-borders-radius-surface-subdued, 9px);
 }
-._ssu5rt3-3-2-1 {
+._ssu5rt3-3-3-1 {
   overflow: hidden;
   height: 100%;
 }
-._ssu5rt4-3-2-1 {
+._ssu5rt4-3-3-1 {
   padding: var(--dt-spacings-size-4, 4px);
   height: 100%;
   max-height: 101vh;

package/filters/filter-field/suggestions/SuggestionsOverlay.sty.js

@@ -26,8 +26,8 @@ __export(SuggestionsOverlay_css_exports, {
 });
 module.exports = __toCommonJS(SuggestionsOverlay_css_exports);
 var import_SuggestionsOverlay_css_ts_vanilla = require("./SuggestionsOverlay.css");
-var suggestionsOverlay = "_ssu5rt2-3-2-1";
-var suggestionsOverlayWrapper = "_ssu5rt1-3-2-1";
-var suggestionsOverlayWrapperContainer = "_ssu5rt0-3-2-1";
-var suggestionsScrollContainer = "_ssu5rt4-3-2-1";
-var suggestionsScrollContainerWrapper = "_ssu5rt3-3-2-1";
+var suggestionsOverlay = "_ssu5rt2-3-3-1";
+var suggestionsOverlayWrapper = "_ssu5rt1-3-3-1";
+var suggestionsOverlayWrapperContainer = "_ssu5rt0-3-3-1";
+var suggestionsScrollContainer = "_ssu5rt4-3-3-1";
+var suggestionsScrollContainerWrapper = "_ssu5rt3-3-3-1";

package/filters/filter-field/suggestions/suggestions-extension.d.ts

@@ -1,13 +1,14 @@
 import type { EditorState, Extension } from '@codemirror/state';
 import type { OverlayTriggerState } from '../../../overlays/hooks/useOverlay.js';
-import type { FallbackKeys, FilterFieldProps, FilterStatementKeysMap } from '../FilterField.types.js';
+import type { FilterFieldProps } from '../FilterField.types.js';
 import type { FilterFieldSuggestion } from './Suggestion.types.js';
 import type { useCachedTreeConversion } from '../hooks/useCachedTreeConversion.js';
 import type { NumberFormatParser } from '../parser/getNumberParser.js';
 import type { FilterFieldGroupedSuggestions, FilterFieldSuggestionsCallback } from '../types/suggestions.js';
 import type { FilterFieldNode, FilterFieldStatementNode, FilterFieldValueNode } from '../types/tree-nodes.js';
-import type { FilterFieldCustomTypes, FilterFieldValidatorMap } from '../types/validation.js';
+import type { FilterFieldCustomTypes } from '../types/validation.js';
 import { type FilterFieldSuggestionRecentPinnedSuggestion } from '../utils/suggestions-utils/recent-and-pinned-suggestions.js';
+import type { InternalValidatorMap } from '../utils/validation-utils/normalize-validator-map.js';
 /** @internal */
 export type FilterFieldSuggestionsContext = {
     token: FilterFieldValueNode;
@@ -28,7 +29,7 @@ export type InternalFilterFieldSuggestionsCallback = (args: {
 type SuggestionsExtensionProps = {
     overlayState: OverlayTriggerState;
     numberParser: NumberFormatParser;
-    validatorMap?: FilterFieldValidatorMap;
+    internalValidatorMap?: InternalValidatorMap;
     /**
      * Internal callback that is triggered whenever suggestions may need to be updated.
      * Used to update flags to determine which suggestions to show in the suggestions
@@ -41,14 +42,12 @@ type SuggestionsExtensionProps = {
     getSyntaxTree: ReturnType<typeof useCachedTreeConversion>['getSyntaxTree'];
     /** Config to enable new nodes being returned in the FilterFieldTree */
     parserConfig?: FilterFieldProps['parserConfig'];
-    fallbackKeys?: FallbackKeys;
-    filterStatementKeysMap?: FilterStatementKeysMap;
     customTypes?: FilterFieldCustomTypes;
 };
 /**
  * @internal
  */
-export declare const suggestionsExtension: ({ overlayState, numberParser, validatorMap, fallbackKeys, filterStatementKeysMap, onSuggest, _onSuggest, getSyntaxTree, customTypes, parserConfig, }: SuggestionsExtensionProps) => Extension;
+export declare const suggestionsExtension: ({ overlayState, numberParser, internalValidatorMap, onSuggest, _onSuggest, getSyntaxTree, customTypes, parserConfig, }: SuggestionsExtensionProps) => Extension;
 /** @internal */
 export declare function getTokenBeforePastedContent(pastedRangeFrom: number, editorState: EditorState, pastedContentToken: FilterFieldNode): {
     token: FilterFieldNode;

package/filters/filter-field/suggestions/suggestions-extension.js

@@ -37,9 +37,7 @@ var import_tree_navigation = require("../utils/tree-navigation.js");
 const suggestionsExtension = ({
   overlayState,
   numberParser,
-  validatorMap,
-  fallbackKeys,
-  filterStatementKeysMap,
+  internalValidatorMap,
   onSuggest,
   _onSuggest,
   getSyntaxTree,
@@ -151,7 +149,7 @@ const suggestionsExtension = ({
       currentToken,
       currentTokenType,
       prevNode,
-      validatorMap,
+      internalValidatorMap,
       customTypes,
       showLogicalOperators,
       showInclusionOperators,
@@ -171,13 +169,13 @@ const suggestionsExtension = ({
       filterStatementSuggestions = (0, import_key_suggestions.getFilterStatementSuggestions)(
         currentToken,
         suggestionTypes,
-        filterStatementKeysMap
+        internalValidatorMap?.filterStatementKeysMap
       );
     }
     const fallbackKeySuggestions = (0, import_key_suggestions.getFallbackKeySuggestions)(
       currentToken,
       suggestionTypes,
-      fallbackKeys,
+      internalValidatorMap?.fallbackKeys,
       filterStatementSuggestions
     );
     _onSuggest({

package/filters/filter-field/types/filter-field-error.d.ts

@@ -7,16 +7,18 @@ export type FilterFieldError = {
     decoration?: Decoration;
     message: keyof FilterFieldErrorMessages | {
         type: keyof FilterFieldErrorMessages;
-        details?: string;
+        details?: string | string[];
     } | (string & {});
 };
 /** @internal */
 export type FilterFieldErrorMessages = {
-    [key in Exclude<keyof typeof filterFieldMessages.linting, 'invalidComparatorError' | 'unsupportedSearchWithLogicalOr' | 'incompleteStatementWithEnabledSearchError'>]: string;
+    [key in Exclude<keyof typeof filterFieldMessages.linting, 'invalidComparatorError' | 'unsupportedSearchWithLogicalOr' | 'incompleteStatementWithEnabledSearchError' | 'invalidValueErrorMultipleTypes' | 'typeLabels'>]: string;
 } & {
     invalidComparatorError: (comparators?: string) => string;
 } & {
     unsupportedSearchWithLogicalOr: (allowedOperator?: string) => string;
 } & {
     incompleteStatementWithEnabledSearchError: (operator?: string) => string;
+} & {
+    invalidValueErrorMultipleTypes: (allowedTypes?: string[]) => string;
 };

package/filters/filter-field/types/validation.d.ts

@@ -20,9 +20,12 @@ export type FilterFieldCustomTypes = Record<string, ((value: string) => boolean)
     valuePredicate: (value: string) => boolean;
     /** Icon to render for suggestions of this type. */
     icon?: ReactElement;
+    /** Label for the type name that is used in error messages. If no label is provided, the type name will be used. */
+    label?: string;
 }>;
 /**
  * FilterField Duration type.
+ * @deprecated Passing a duration as separate value and unit is deprecated. Pass a string value instead.
  * @public
  */
 export type FilterFieldDuration = Required<Pick<FilterFieldDurationNode, 'value' | 'unit'>>;
@@ -46,6 +49,7 @@ export type FilterFieldDuration = Required<Pick<FilterFieldDurationNode, 'value'
  *  }
  * }
  * ```
+ * @deprecated Use `valueType` on `FilterFieldKeySuggestionConfig` to restrict value types.
  * @public
  */
 export type FilterFieldValidatorMapTypePredicate = Record<'type', FilterFieldPrimitive | string | (FilterFieldPrimitive | string)[]>;
@@ -70,12 +74,11 @@ export type FilterFieldRichValuePredicate = {
     details?: string;
 };
 /**
- * Value predicate for restricting the valid values in the FilterField validatorMap.
+ * Primitive value item for restricting valid values in the FilterField validatorMap.
+ * Used as individual suggestions within a `FilterFieldValueSuggestionGroupConfig`.
  * @public
  */
-export type FilterFieldValuePredicate = 
-/** FilterFieldPrimitive allowed for the value of the given key. */
-FilterFieldValidatorMapTypePredicate
+export type FilterFieldValuePredicateItem = FilterFieldValidatorMapTypePredicate
 /** String literal allowed for the value of the given key. */
  | string
 /** Number value allowed for the value of the given key. */
@@ -83,9 +86,33 @@ FilterFieldValidatorMapTypePredicate
 /** Boolean value allowed for the value of the given key. */
  | boolean | FilterFieldDuration
 /** Value with optional displayValue and details. */
- | FilterFieldRichValuePredicate
-/** Value literals allowed for the value of the given key. */
- | Array<FilterFieldValidatorMapTypePredicate | string | number | boolean | FilterFieldDuration | FilterFieldRichValuePredicate>;
+ | FilterFieldRichValuePredicate;
+/**
+ * Configuration for a group of value suggestions in the FilterField validatorMap.
+ * @public
+ */
+export type FilterFieldValueSuggestionGroupConfig = {
+    /**
+     * Unique identifier for the group. Used as the key in groupedSuggestions.
+     * Falls back to label, then aria-label, then an auto-generated id.
+     */
+    id?: string;
+    /** Visible label for the suggestion group. */
+    label?: string;
+    /** Accessible label for screen readers. */
+    'aria-label'?: string;
+    /** Suggestions within this group. */
+    suggestions: FilterFieldValuePredicateItem[];
+};
+/**
+ * Value predicate for restricting the valid values in the FilterField validatorMap.
+ * @public
+ */
+export type FilterFieldValuePredicate = FilterFieldValuePredicateItem
+/** Grouped value suggestions for the value of the given key. */
+ | FilterFieldValueSuggestionGroupConfig
+/** Value literals or grouped value suggestions allowed for the value of the given key. */
+ | Array<FilterFieldValuePredicateItem | FilterFieldValueSuggestionGroupConfig>;
 /**
  * Function executed for validating the value of a filter field statement.
  * - Returning true, the value is considered valid.
@@ -103,11 +130,18 @@ export type FilterFieldValuePredicateFn = (state: {
 }) => boolean | string;
 /**
  * ValidatorMap to restrict allowed keys, comparison operators and their values in the FilterField.
+ *
+ * The object notation of the `keyPredicates` is deprecated in favor of the array notation using `FilterFieldKeySuggestionConfig` and `FilterFieldKeySuggestionGroupConfig`,
+ * which also supports grouping suggestions.
+ *
+ * Providing a `FilterFieldValidatorMapTypePredicate` directly in the `keyPredicates` object or as an item in the `valuePredicate` array is deprecated.
+ * Use `valueType` on `FilterFieldKeySuggestionConfig` instead to restrict value types.
  * @public
  */
 export type FilterFieldValidatorMap = {
     /** Object used for validating keys in the filter field. */
-    keyPredicates?: {
+    keyPredicates?: // DEPRECATION: [APPDEV-16872] BREAKING-CHANGE
+    {
         [key: string]: {
             comparisonOperators?: Array<FilterFieldComparisonOperators>;
             valuePredicate?: FilterFieldValuePredicate | FilterFieldValuePredicateFn;
@@ -118,11 +152,13 @@ export type FilterFieldValidatorMap = {
         } | FilterFieldValidatorMapTypePredicate;
     }
     /**
-     * Static set of strings for validating the keys in the filter field.
-     * No other keys will be valid, unless the exhaustive prop is set to false.
-     * No restrictions to operators / values apply.
+     * Array of key names, key configs, or grouped key configs.
+     * Supports grouping key suggestions under named section headers.
+     * Ungrouped string entries and `FilterFieldKeySuggestionConfig` items fall
+     * into the default key group. Mixed with the deprecated object format,
+     * the array format takes precedence.
      */
-     | string[];
+     | Array<string | FilterFieldKeySuggestionConfig | FilterFieldKeySuggestionGroupConfig>;
     /**
      * Whether the provided key predicates are exhaustive.
      * If set to true, all keys not included in the object will be considered as errors.
@@ -144,6 +180,48 @@ export type FilterFieldValidatorMap = {
      */
     sortSuggestions?: boolean;
 };
+/**
+ * Configuration for a single key suggestion in the FilterField validatorMap.
+ * @public
+ */
+export type FilterFieldKeySuggestionConfig = {
+    /** The key value used in the filter statement. */
+    key: string;
+    /** The type of values allowed for this key. Accepts built-in primitives or custom type names registered via `customTypes`. */
+    valueType?: FilterFieldPrimitive | (string & {}) | (FilterFieldPrimitive | (string & {}))[];
+    /** Allowed comparison operators for this key. */
+    comparisonOperators?: Array<FilterFieldComparisonOperators>;
+    /** Value predicate for restricting valid values. Use `valueType` to restrict value types instead of `FilterFieldValidatorMapTypePredicate`. */
+    valuePredicate?: FilterFieldValuePredicate | FilterFieldValuePredicateFn;
+    /** Whether this key acts as a fallback key. */
+    fallbackKey?: boolean | Array<Exclude<FilterFieldComparisonOperators, 'exists' | 'not-exists'>>;
+    /** Whether to suggest this key as a statement on value match. */
+    suggestStatementOnValueMatch?: boolean | FilterFieldValueMatchFn;
+    /**
+     * The display value to show for the value suggestion.
+     * If not set, the key is used.
+     */
+    displayValue?: string;
+    /** Additional information to render for the key suggestion. */
+    details?: string;
+};
+/**
+ * Configuration for a group of key suggestions in the FilterField validatorMap.
+ * @public
+ */
+export type FilterFieldKeySuggestionGroupConfig = {
+    /**
+     * Unique identifier for the group. Used as the key in groupedSuggestions.
+     * Falls back to label, then aria-label, then an auto-generated id.
+     */
+    id?: string;
+    /** Visible label for the suggestion group. */
+    label?: string;
+    /** Accessible label for screen readers. */
+    'aria-label'?: string;
+    /** Suggestions within this group. */
+    suggestions: Array<string | FilterFieldKeySuggestionConfig>;
+};
 /**
  * Function executed for checking whether the key should be suggested as a statement suggestion with the current token as a value.
  * @public

package/filters/filter-field/utils/conversion/lezer-tree-conversion/parent-node/group.d.ts

@@ -3,10 +3,11 @@ import type { FilterFieldProps } from '../../../../FilterField.types.js';
 import type { NumberFormatParser } from '../../../../parser/getNumberParser.js';
 import type { ConvertedLezerNode, FilterFieldFlatGroupNode } from '../../../../types/conversion-utils.js';
 import type { FilterFieldLezerNodeType } from '../../../../types/tree-nodes.js';
-import type { FilterFieldCustomTypes, FilterFieldValidatorMap } from '../../../../types/validation.js';
+import type { FilterFieldCustomTypes } from '../../../../types/validation.js';
+import type { InternalValidatorMap } from '../../../../utils/validation-utils/normalize-validator-map.js';
 /**
  * Convert a filter field group node.
  * The root 'Filter' node is also handled as group.
  * @internal
  */
-export declare function convertFilterGroup(node: SyntaxNodeRef, doc: string, numberParser: NumberFormatParser, validatorMap?: FilterFieldValidatorMap, customTypes?: FilterFieldCustomTypes, parserConfig?: FilterFieldProps['parserConfig'], context?: FilterFieldLezerNodeType): ConvertedLezerNode<FilterFieldFlatGroupNode>;
+export declare function convertFilterGroup(node: SyntaxNodeRef, doc: string, numberParser: NumberFormatParser, internalValidatorMap: InternalValidatorMap | undefined, customTypes?: FilterFieldCustomTypes, parserConfig?: FilterFieldProps['parserConfig'], context?: FilterFieldLezerNodeType): ConvertedLezerNode<FilterFieldFlatGroupNode>;

package/filters/filter-field/utils/conversion/lezer-tree-conversion/parent-node/group.js

@@ -27,7 +27,7 @@ var import_decoration_marks = require("../../../../decorations/decoration-marks.
 var import_validation_helper_functions = require("../../../validation-utils/validation-helper-functions.js");
 var import_logical_operator = require("../logical-operator.js");
 var import_error = require("../value/error.js");
-function convertFilterGroup(node, doc, numberParser, validatorMap, customTypes, parserConfig, context) {
+function convertFilterGroup(node, doc, numberParser, internalValidatorMap, customTypes, parserConfig, context) {
   const { from, to } = node;
   const cursor = node.node.cursor();
   const convertedNode = {
@@ -59,7 +59,7 @@ function convertFilterGroup(node, doc, numberParser, validatorMap, customTypes,
           childNode,
           doc,
           numberParser,
-          validatorMap,
+          internalValidatorMap,
           customTypes,
           parserConfig,
           "FilterGroup"
@@ -74,7 +74,7 @@ function convertFilterGroup(node, doc, numberParser, validatorMap, customTypes,
           childNode,
           doc,
           numberParser,
-          validatorMap,
+          internalValidatorMap,
           customTypes,
           parserConfig,
           context

package/filters/filter-field/utils/conversion/lezer-tree-conversion/parent-node/statement.d.ts

@@ -3,9 +3,10 @@ import type { FilterFieldProps } from '../../../../FilterField.types.js';
 import type { NumberFormatParser } from '../../../../parser/getNumberParser.js';
 import type { ConvertedLezerNode } from '../../../../types/conversion-utils.js';
 import type { FilterFieldLezerNodeType, FilterFieldStatementNode } from '../../../../types/tree-nodes.js';
-import type { FilterFieldCustomTypes, FilterFieldValidatorMap } from '../../../../types/validation.js';
+import type { FilterFieldCustomTypes } from '../../../../types/validation.js';
+import type { InternalValidatorMap } from '../../../../utils/validation-utils/normalize-validator-map.js';
 /**
  * Convert a filter field statement node.
  * @internal
  */
-export declare function convertFilterStatement(node: SyntaxNodeRef, doc: string, numberParser: NumberFormatParser, validatorMap?: FilterFieldValidatorMap, customTypes?: FilterFieldCustomTypes, parserConfig?: FilterFieldProps['parserConfig'], context?: FilterFieldLezerNodeType): ConvertedLezerNode<FilterFieldStatementNode>;
+export declare function convertFilterStatement(node: SyntaxNodeRef, doc: string, numberParser: NumberFormatParser, internalValidatorMap: InternalValidatorMap | undefined, customTypes?: FilterFieldCustomTypes, parserConfig?: FilterFieldProps['parserConfig'], context?: FilterFieldLezerNodeType): ConvertedLezerNode<FilterFieldStatementNode>;