fluentui-extended 2026.2.5 → 2026.2.6

package/README.md

@@ -29,6 +29,8 @@ A searchable dropdown component styled after Dynamics 365 lookup fields. Support
 
 ### QueryBuilder
 
+> **🚧 Beta** - This component is in beta. Please report any issues on [GitHub](https://github.com/garethcheyne/npm-fluentui-extended/issues).
+
 An Advanced Find-style query builder for Dynamics 365. Build complex filter conditions with AND/OR logic, serialize to FetchXML or OData, and validate queries against the Dynamics 365 API.
 
 ![QueryBuilder Component](assets/screenshot-querybuilder.png)

package/dist/index.d.mts

@@ -63,23 +63,60 @@ interface QueryBuilderOption {
     label: string;
     value: string | number;
 }
+/** Target entity for lookup fields */
+interface QueryBuilderLookupTarget {
+    /** Logical name of the target entity (e.g., "contact") */
+    entityLogicalName: string;
+    /** Entity set name for OData queries (e.g., "contacts") */
+    entitySetName?: string;
+    /** Display name of the entity (e.g., "Contact") */
+    displayName?: string;
+    /** Primary name attribute for searching (e.g., "fullname") */
+    primaryNameAttribute?: string;
+}
 interface QueryBuilderField {
     id: string;
     label: string;
     dataType: QueryBuilderDataType;
     options?: QueryBuilderOption[];
+    /** Schema name (PascalCase attribute name, e.g., "CreatedOn") */
+    schemaName?: string;
+    /** Target entities for lookup fields (which entities can be referenced) */
+    targets?: QueryBuilderLookupTarget[];
 }
-type QueryBuilderOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'between' | 'contains' | 'notcontains' | 'startswith' | 'endswith' | 'containsdata' | 'null' | 'notnull';
+/**
+ * FetchXML condition operators.
+ *
+ * Common operators are explicitly listed for IDE autocomplete.
+ * Additional FetchXML operators are supported via the string type.
+ *
+ * @see QueryBuilder.operators.ts for full list of operators
+ */
+type QueryBuilderOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'null' | 'not-null' | 'notnull' | 'contains' | 'not-contain' | 'begins-with' | 'not-begin-with' | 'ends-with' | 'not-end-with' | 'like' | 'not-like' | 'notcontains' | 'startswith' | 'endswith' | 'containsdata' | 'in' | 'not-in' | 'between' | 'not-between' | 'contain-values' | 'not-contain-values' | 'on' | 'on-or-before' | 'on-or-after' | 'not-on' | 'today' | 'yesterday' | 'tomorrow' | 'this-week' | 'last-week' | 'next-week' | 'this-month' | 'last-month' | 'next-month' | 'this-year' | 'last-year' | 'next-year' | 'last-seven-days' | 'next-seven-days' | 'last-x-hours' | 'next-x-hours' | 'last-x-days' | 'next-x-days' | 'last-x-weeks' | 'next-x-weeks' | 'last-x-months' | 'next-x-months' | 'last-x-years' | 'next-x-years' | 'olderthan-x-minutes' | 'olderthan-x-hours' | 'olderthan-x-days' | 'olderthan-x-weeks' | 'olderthan-x-months' | 'olderthan-x-years' | 'this-fiscal-year' | 'this-fiscal-period' | 'last-fiscal-year' | 'last-fiscal-period' | 'next-fiscal-year' | 'next-fiscal-period' | 'last-x-fiscal-years' | 'last-x-fiscal-periods' | 'next-x-fiscal-years' | 'next-x-fiscal-periods' | 'in-fiscal-year' | 'in-fiscal-period' | 'in-fiscal-period-and-year' | 'in-or-before-fiscal-period-and-year' | 'in-or-after-fiscal-period-and-year' | 'eq-userid' | 'ne-userid' | 'eq-userteams' | 'eq-useroruserteams' | 'eq-useroruserhierarchy' | 'eq-useroruserhierarchyandteams' | 'eq-businessid' | 'ne-businessid' | 'eq-userlanguage' | 'above' | 'eq-or-above' | 'under' | 'eq-or-under' | 'not-under' | (string & {});
 interface QueryBuilderCondition {
     id: string;
     kind?: 'field' | 'relatedEntity';
     fieldId: string;
     operator: QueryBuilderOperator;
-    value?: string | number | boolean;
+    /** Single value or array of values (for in/not-in operators) */
+    value?: string | number | boolean | (string | number)[];
     value2?: string | number | boolean;
     /** Display name for lookup values (the GUID is stored in value) */
     valueDisplayName?: string;
+    /** Entity alias when condition references a link-entity (e.g., entityname="S" in FetchXML) */
+    entityAlias?: string;
+    /** The lookup field ID that creates this relationship (e.g., "ownerid") - used as "to" in link-entity */
     relatedEntityName?: string;
+    /** The target entity logical name (e.g., "systemuser") - used as "name" in link-entity */
+    relatedEntityTarget?: string;
+    /** Alias for the link-entity (e.g., "S" in alias="S") */
+    relatedEntityAlias?: string;
+    /** Nested conditions for related entity (link-entity filter) */
+    nestedConditions?: QueryBuilderCondition[];
+    /** Logic operator for nested conditions */
+    nestedLogic?: 'and' | 'or';
+    /** Fields available for the related entity (loaded dynamically) */
+    nestedFields?: QueryBuilderField[];
 }
 interface QueryBuilderGroup {
     id: string;
@@ -94,10 +131,20 @@ interface QueryBuilderApplyResult {
     fetchXmlFilter: string;
     fetchXml: string;
     odataFilter: string;
+    /** Full OData query URL (e.g., "accounts?$filter=...") - requires entitySetName */
+    odataQuery?: string;
 }
 interface QueryBuilderRelatedEntity {
+    /** Unique identifier - typically the lookup field name (e.g., "primarycontactid") */
     id: string;
+    /** Display label for the relationship (e.g., "Primary Contact (Contact)") */
     label: string;
+    /** The lookup field that creates this relationship */
+    lookupField?: string;
+    /** The target entity logical name (e.g., "contact") */
+    targetEntity?: string;
+    /** The target entity set name for OData (e.g., "contacts") */
+    targetEntitySetName?: string;
 }
 interface QueryBuilderLookupOption {
     /** Unique identifier (typically a GUID) */
@@ -109,8 +156,11 @@ interface QueryBuilderLookupOption {
 }
 interface QueryBuilderProps {
     entityName: string;
+    /** Entity set name for OData queries (e.g., "accounts"). If not provided, will be fetched from Xrm metadata. */
+    entitySetName?: string;
     entityDisplayName?: string;
     fields?: QueryBuilderField[];
+    /** Related entities for filtering. If not provided, will be auto-detected from lookup fields. */
     relatedEntities?: QueryBuilderRelatedEntity[];
     /** Initial query state object */
     initialState?: QueryBuilderState;
@@ -141,7 +191,17 @@ interface QueryBuilderProps {
     onLookupSearch?: (fieldId: string, searchText: string) => Promise<QueryBuilderLookupOption[]> | QueryBuilderLookupOption[];
 }
 
-declare const serializeQueryBuilderState: (state: QueryBuilderState, fields: QueryBuilderField[], entityName: string) => QueryBuilderApplyResult;
+/**
+ * QueryBuilder Serializer
+ *
+ * Converts QueryBuilder state to FetchXML and OData formats.
+ */
+
+/**
+ * Serialize QueryBuilder state to FetchXML and OData
+ */
+declare const serializeQueryBuilderState: (state: QueryBuilderState, fields: QueryBuilderField[], entityName: string, entitySetName?: string) => QueryBuilderApplyResult;
+
 declare const QueryBuilder: React.FC<QueryBuilderProps>;
 
 export { Lookup, type LookupOption, type LookupOptionDetail, type LookupProps, QueryBuilder, type QueryBuilderApplyResult, type QueryBuilderCondition, type QueryBuilderDataType, type QueryBuilderField, type QueryBuilderGroup, type QueryBuilderOperator, type QueryBuilderOption, type QueryBuilderProps, type QueryBuilderRelatedEntity, type QueryBuilderState, serializeQueryBuilderState };

package/dist/index.d.ts

@@ -63,23 +63,60 @@ interface QueryBuilderOption {
     label: string;
     value: string | number;
 }
+/** Target entity for lookup fields */
+interface QueryBuilderLookupTarget {
+    /** Logical name of the target entity (e.g., "contact") */
+    entityLogicalName: string;
+    /** Entity set name for OData queries (e.g., "contacts") */
+    entitySetName?: string;
+    /** Display name of the entity (e.g., "Contact") */
+    displayName?: string;
+    /** Primary name attribute for searching (e.g., "fullname") */
+    primaryNameAttribute?: string;
+}
 interface QueryBuilderField {
     id: string;
     label: string;
     dataType: QueryBuilderDataType;
     options?: QueryBuilderOption[];
+    /** Schema name (PascalCase attribute name, e.g., "CreatedOn") */
+    schemaName?: string;
+    /** Target entities for lookup fields (which entities can be referenced) */
+    targets?: QueryBuilderLookupTarget[];
 }
-type QueryBuilderOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'between' | 'contains' | 'notcontains' | 'startswith' | 'endswith' | 'containsdata' | 'null' | 'notnull';
+/**
+ * FetchXML condition operators.
+ *
+ * Common operators are explicitly listed for IDE autocomplete.
+ * Additional FetchXML operators are supported via the string type.
+ *
+ * @see QueryBuilder.operators.ts for full list of operators
+ */
+type QueryBuilderOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'null' | 'not-null' | 'notnull' | 'contains' | 'not-contain' | 'begins-with' | 'not-begin-with' | 'ends-with' | 'not-end-with' | 'like' | 'not-like' | 'notcontains' | 'startswith' | 'endswith' | 'containsdata' | 'in' | 'not-in' | 'between' | 'not-between' | 'contain-values' | 'not-contain-values' | 'on' | 'on-or-before' | 'on-or-after' | 'not-on' | 'today' | 'yesterday' | 'tomorrow' | 'this-week' | 'last-week' | 'next-week' | 'this-month' | 'last-month' | 'next-month' | 'this-year' | 'last-year' | 'next-year' | 'last-seven-days' | 'next-seven-days' | 'last-x-hours' | 'next-x-hours' | 'last-x-days' | 'next-x-days' | 'last-x-weeks' | 'next-x-weeks' | 'last-x-months' | 'next-x-months' | 'last-x-years' | 'next-x-years' | 'olderthan-x-minutes' | 'olderthan-x-hours' | 'olderthan-x-days' | 'olderthan-x-weeks' | 'olderthan-x-months' | 'olderthan-x-years' | 'this-fiscal-year' | 'this-fiscal-period' | 'last-fiscal-year' | 'last-fiscal-period' | 'next-fiscal-year' | 'next-fiscal-period' | 'last-x-fiscal-years' | 'last-x-fiscal-periods' | 'next-x-fiscal-years' | 'next-x-fiscal-periods' | 'in-fiscal-year' | 'in-fiscal-period' | 'in-fiscal-period-and-year' | 'in-or-before-fiscal-period-and-year' | 'in-or-after-fiscal-period-and-year' | 'eq-userid' | 'ne-userid' | 'eq-userteams' | 'eq-useroruserteams' | 'eq-useroruserhierarchy' | 'eq-useroruserhierarchyandteams' | 'eq-businessid' | 'ne-businessid' | 'eq-userlanguage' | 'above' | 'eq-or-above' | 'under' | 'eq-or-under' | 'not-under' | (string & {});
 interface QueryBuilderCondition {
     id: string;
     kind?: 'field' | 'relatedEntity';
     fieldId: string;
     operator: QueryBuilderOperator;
-    value?: string | number | boolean;
+    /** Single value or array of values (for in/not-in operators) */
+    value?: string | number | boolean | (string | number)[];
     value2?: string | number | boolean;
     /** Display name for lookup values (the GUID is stored in value) */
     valueDisplayName?: string;
+    /** Entity alias when condition references a link-entity (e.g., entityname="S" in FetchXML) */
+    entityAlias?: string;
+    /** The lookup field ID that creates this relationship (e.g., "ownerid") - used as "to" in link-entity */
     relatedEntityName?: string;
+    /** The target entity logical name (e.g., "systemuser") - used as "name" in link-entity */
+    relatedEntityTarget?: string;
+    /** Alias for the link-entity (e.g., "S" in alias="S") */
+    relatedEntityAlias?: string;
+    /** Nested conditions for related entity (link-entity filter) */
+    nestedConditions?: QueryBuilderCondition[];
+    /** Logic operator for nested conditions */
+    nestedLogic?: 'and' | 'or';
+    /** Fields available for the related entity (loaded dynamically) */
+    nestedFields?: QueryBuilderField[];
 }
 interface QueryBuilderGroup {
     id: string;
@@ -94,10 +131,20 @@ interface QueryBuilderApplyResult {
     fetchXmlFilter: string;
     fetchXml: string;
     odataFilter: string;
+    /** Full OData query URL (e.g., "accounts?$filter=...") - requires entitySetName */
+    odataQuery?: string;
 }
 interface QueryBuilderRelatedEntity {
+    /** Unique identifier - typically the lookup field name (e.g., "primarycontactid") */
     id: string;
+    /** Display label for the relationship (e.g., "Primary Contact (Contact)") */
     label: string;
+    /** The lookup field that creates this relationship */
+    lookupField?: string;
+    /** The target entity logical name (e.g., "contact") */
+    targetEntity?: string;
+    /** The target entity set name for OData (e.g., "contacts") */
+    targetEntitySetName?: string;
 }
 interface QueryBuilderLookupOption {
     /** Unique identifier (typically a GUID) */
@@ -109,8 +156,11 @@ interface QueryBuilderLookupOption {
 }
 interface QueryBuilderProps {
     entityName: string;
+    /** Entity set name for OData queries (e.g., "accounts"). If not provided, will be fetched from Xrm metadata. */
+    entitySetName?: string;
     entityDisplayName?: string;
     fields?: QueryBuilderField[];
+    /** Related entities for filtering. If not provided, will be auto-detected from lookup fields. */
     relatedEntities?: QueryBuilderRelatedEntity[];
     /** Initial query state object */
     initialState?: QueryBuilderState;
@@ -141,7 +191,17 @@ interface QueryBuilderProps {
     onLookupSearch?: (fieldId: string, searchText: string) => Promise<QueryBuilderLookupOption[]> | QueryBuilderLookupOption[];
 }
 
-declare const serializeQueryBuilderState: (state: QueryBuilderState, fields: QueryBuilderField[], entityName: string) => QueryBuilderApplyResult;
+/**
+ * QueryBuilder Serializer
+ *
+ * Converts QueryBuilder state to FetchXML and OData formats.
+ */
+
+/**
+ * Serialize QueryBuilder state to FetchXML and OData
+ */
+declare const serializeQueryBuilderState: (state: QueryBuilderState, fields: QueryBuilderField[], entityName: string, entitySetName?: string) => QueryBuilderApplyResult;
+
 declare const QueryBuilder: React.FC<QueryBuilderProps>;
 
 export { Lookup, type LookupOption, type LookupOptionDetail, type LookupProps, QueryBuilder, type QueryBuilderApplyResult, type QueryBuilderCondition, type QueryBuilderDataType, type QueryBuilderField, type QueryBuilderGroup, type QueryBuilderOperator, type QueryBuilderOption, type QueryBuilderProps, type QueryBuilderRelatedEntity, type QueryBuilderState, serializeQueryBuilderState };