@theseam/ui-common 1.0.2-beta.54 → 1.0.2-beta.57

package/graphql/index.d.ts

@@ -8,8 +8,10 @@ import * as apollo_angular from 'apollo-angular';
 import { QueryRef, WatchQueryOptions, Apollo } from 'apollo-angular';
 import { DataFilterState } from '@theseam/ui-common/data-filters';
 import * as i0 from '@angular/core';
-import { InjectionToken, EventEmitter, Provider } from '@angular/core';
+import { InjectionToken, Type, Provider, EventEmitter } from '@angular/core';
 import { OperationVariables } from '@apollo/client/core/types';
+import * as _fortawesome_fontawesome_common_types from '@fortawesome/fontawesome-common-types';
+import { IDataExporter } from '@theseam/ui-common/data-exporter';
 import * as _theseam_ui_common_graphql from '@theseam/ui-common/graphql';
 
 interface LogQueryLinkOptions {
@@ -55,17 +57,50 @@ declare function logQueryLink(inner: ApolloLink, options?: LogQueryLinkOptions):
  *   variable is not referenced anywhere in the (possibly already-transformed)
  *   query body.
  * - `variables.inline`: inline named variables into the query AST.
+ * - `variables.orderTiebreaker`: append a fallback sort field for deterministic
+ *   pagination.
  *
  * Hints are applied first, then config-based processing.
  */
 declare const queryProcessingLink: ApolloLink;
 
+/**
+ * Checks whether a GraphQL document or value node contains a reference to
+ * the named variable.
+ *
+ * This includes references inside variable definitions — a variable that is
+ * defined but not used as an argument will still be found. This behavior is
+ * relied on by `removeIfNotUsed` processing to avoid removing variables that
+ * may be needed after a later inline step.
+ */
 declare function containsVariable(node: DocumentNode | ValueNode, variableName: string): boolean;
 
+/**
+ * Creates a variable reference marker for use in filter objects that will be
+ * passed to `toGQL` and inlined into a query.
+ *
+ * When `toGQL` encounters an object with a `gqlVar` property, it emits the
+ * value as-is (e.g. `$search`), producing a GraphQL variable reference in the
+ * output rather than a string literal.
+ *
+ * @example
+ * ```typescript
+ * const filter = { name: { contains: gqlVar('search') } }
+ * // toGQL(filter) → '{name: {contains: $search}}'
+ * ```
+ */
 declare function gqlVar(varName: string): {
     gqlVar: string;
 };
 
+/**
+ * Replaces all references to a variable in the query body with a literal
+ * value. If the value represents `undefined`, the variable references are
+ * removed from the query instead.
+ *
+ * This does not remove the variable definition — use `removeVariableDefinition`
+ * separately if needed.
+ */
 declare function inlineVariable(query: DocumentNode$1, variableName: string, variableValue: ValueNode$1): DocumentNode$1;
 
 declare function parseComments(ast: DocumentNode): Token[];
@@ -105,15 +140,48 @@ interface HintDefinition {
 }
 
 declare const DEFAULT_TO_REMOVE_ON_UNDEFINED: string[];
+/**
+ * Configuration for how query variables are transformed before a GraphQL
+ * operation is sent. Used via `queryProcessingConfig` in Apollo context or
+ * passed directly to `processGql`.
+ */
 interface QueryProcessingVariablesConfig {
+    /**
+     * Variable names to remove from the query when their value is `null` or
+     * `undefined`. Removes both the variable definition and argument references.
+     */
     removeIfNotDefined?: string[];
+    /**
+     * Variable names whose definitions should be removed if the variable is not
+     * referenced anywhere in the query. A variable that still has its own
+     * definition is considered "present" and will not be removed — this is
+     * intentional because the variable may be needed after a later processing
+     * step (e.g. `$search` referenced inside a `$where` value that will be
+     * inlined).
+     */
     removeIfNotUsed?: string[];
+    /**
+     * Variable names to inline into the query. The variable's value is converted
+     * to a GraphQL literal and substituted directly into the query AST. The
+     * variable is then removed from both the definition and the variables map.
+     */
     inline?: string[];
+    /**
+     * If set, the order variable (expected to be an array of sort objects) will be
+     * checked and if this field name is not already present as a sort key, it will
+     * be appended with a default direction of DESC. This ensures deterministic
+     * ordering for paginated results.
+     */
+    orderTiebreaker?: string;
 }
+/**
+ * Top-level configuration for query processing. Passed via Apollo context
+ * under the key `queryProcessingConfig`, or to `processGql` directly.
+ */
 interface QueryProcessingConfig {
     variables: QueryProcessingVariablesConfig;
     /**
-     * If skip and take are found, they will be removed
+     * When enabled, paging is disabled and all records are returned.
      */
     disablePaging?: boolean;
 }
@@ -153,16 +221,62 @@ declare function createHintsToken(token: Token$1, node: HintsToken['node'], kind
 declare function getHintsToken(token: Token$1, ast: DocumentNode$1): HintsToken | null;
 declare function parseHints(ast: DocumentNode$1): HintsToken[];
 
+/**
+ * Removes a variable's definition from the query (e.g. `$where: String` in the
+ * operation signature). Does not remove argument references to that variable in
+ * the query body.
+ *
+ * To remove both the definition and argument references, use `removeVariable`.
+ */
 declare function removeVariableDefinition(query: DocumentNode$1, variableName: string): DocumentNode$1;
 
+/**
+ * Removes variable definitions from the specified operation when the variable
+ * does not have a corresponding value in the provided variables object (i.e.
+ * the value is `null` or `undefined`).
+ *
+ * Unlike `removeVariable`, this only removes the definitions — it does not
+ * remove argument references in the query body.
+ */
 declare function removeVariableDefinitionsNotDefined(query: DocumentNode$1, node: OperationDefinitionNode, variables: Operation['variables']): DocumentNode$1;
 
+/**
+ * Removes a variable from the query by removing both the variable definition
+ * (e.g. `$where: String` in the operation signature) and argument references
+ * with the same name (e.g. `where: $where` in the field arguments).
+ *
+ * To remove only the definition without touching arguments, use
+ * `removeVariableDefinition`.
+ */
 declare function removeVariable(query: DocumentNode$1, variableName: string): DocumentNode$1;
 
 declare function toGQL(json: any): string;
 
 declare function hintsTokensContainingHint(hintsTokens: HintsToken[], hint: string): HintsToken[];
 
+/**
+ * Transforms a GraphQL query and its variables according to the provided
+ * processing configuration.
+ *
+ * Two mechanisms are supported and can be combined freely:
+ *
+ * **Hint-based** — `# @gql-hint: <name>` comments in the query.
+ * - `remove-not-defined`: removes variables whose value is null/undefined.
+ * - `inline-variable`: substitutes variable values directly into the AST.
+ *
+ * **Config-based** — via `QueryProcessingConfig`:
+ * - `removeIfNotDefined`: remove named variables when null/undefined.
+ * - `removeIfNotUsed`: remove named variable definitions when unreferenced.
+ * - `inline`: inline named variables into the query AST.
+ * - `orderTiebreaker`: append a fallback sort field for deterministic pagination.
+ *
+ * Hints are applied first, then config-based processing, then cleanup.
+ */
+declare function processGql(query: DocumentNode$1, variables: Record<string, any>, queryProcessingConfig: QueryProcessingConfig): {
+    query: DocumentNode$1;
+    variables: Record<string, any>;
+};
+
 interface DatatableGraphQLDataMapperResult<TRow = EmptyObject> {
     rows: TRow[];
     /**
@@ -239,6 +353,20 @@ declare class DatatableGraphQLQueryRef<TData, TVariables extends DatatableGraphQ
      * Default error handler used when no subscriber is listening to `error$`.
      */
     _defaultErrorHandler?: DatatableGraphQLErrorHandler | undefined);
+    /**
+     * Returns an observable of mapped rows from the query result.
+     *
+     * The mapper transforms the raw GraphQL response data into the row format
+     * the datatable expects, and provides the total count for pagination.
+     *
+     * @example
+     * ```typescript
+     * this.rows$ = this._queryRef.rows((data) => ({
+     *   rows: data.items.items,
+     *   totalCount: data.items.totalCount,
+     * }))
+     * ```
+     */
     rows(mapper: DatatableGraphQLDataMapper<TData, TRow>): Observable<TRow[]>;
     private _rowsObservable;
     /**
@@ -446,6 +574,60 @@ declare const mapSearchNumericColumnsDataFilterStateToGql: (filterState: Columns
 
 declare const mapSearchTextColumnsDataFilterStateToGql: (filterState: ColumnsDataFilterState<TheSeamColumnsDataFilterTextSearchFormState>, context: MapperContext<any>) => FilterStateMapperResult;
 
+interface DatatableExportPayload {
+    graphQlQuery: {
+        queryString: string;
+        queryVariables: Record<string, any>;
+        operationName: string;
+        columns: TheSeamDatatableColumn[];
+    };
+    exportType: string;
+}
+/**
+ * Abstract transport for server-side datatable exports.
+ *
+ * THIS SHOULD BE IMPLEMENTED AND PROVIDED BY THE APPLICATION USING 'ui-common'.
+ *
+ * Example:
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDatatableExportTransport(AppDatatableExportTransport),
+ *   ],
+ * })
+ * ```
+ */
+declare abstract class DatatableExportTransport {
+    abstract export(data: DatatableExportPayload): Observable<File>;
+}
+/**
+ * Register the application's `DatatableExportTransport` implementation.
+ *
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDatatableExportTransport(AppDatatableExportTransport),
+ *   ],
+ * })
+ * ```
+ */
+declare function provideDatatableExportTransport(transportType: Type<DatatableExportTransport>): Provider;
+
+declare class DatatableGqlDataExporter<TData, TVariables extends DatatableGraphQLVariables = EmptyObject, TRow = EmptyObject> implements IDataExporter {
+    private readonly _exporterName;
+    private readonly _exporterLabel;
+    private readonly _columns;
+    private readonly _queryRef;
+    private readonly _transport;
+    private readonly _exportType;
+    get name(): string;
+    get label(): string;
+    icon: _fortawesome_fontawesome_common_types.IconDefinition;
+    readonly skipDataMapping: boolean;
+    constructor(_exporterName: string, _exporterLabel: string, _columns: TheSeamDatatableColumn[], _queryRef: DatatableGraphQLQueryRef<TData, TVariables, TRow>, _transport: DatatableExportTransport, _exportType: string);
+    export<T>(data: T[]): Observable<boolean>;
+}
+
 /**
  * Inlines the variable's current value directly into the query AST and removes
  * the variable definition from the parameter list. The variable is also
@@ -615,5 +797,5 @@ interface SimpleGqlTestVariables extends SimpleGqlTestExtraVariables {
     search?: string;
 }
 
-export { DATATABLE_GRAPHQL_SERVICE_CONFIG, DEFAULT_PAGE_SIZE, DEFAULT_TO_REMOVE_ON_UNDEFINED, DatatableGraphQLQueryRef, DatatableGraphqlService, GQLDirection, GQLVariable, HINT_NAMES_CAPTURE_REGEX, HINT_PREFIX_REGEX, HintsKind, MAX_ERROR_RECOVERY_ATTEMPTS, MockDatatable, SIMPLE_GQL_TEST_QUERY, SIMPLE_GQL_TEST_SEARCH_QUERY, baseSchemaFragment, checkRecordsHaveValue, containsVariable, createHintsToken, createMockApolloTestingProvider, createSimpleGqlTestRecord, createSimpleGqlTestRoot, createSortsMapper, filterWhere, filteredResults, getHintsToken, getPageInfo, getTokenAppliesTo, gqlVar, hintNamesFromHintToken, hintsTokensContainingHint, inlineVariable, inlineVariableHintDef, inlineVariableTransformer, isCommentToken, isHintToken, isInlineComment, logQueryLink, mapFilterStates, mapSearchDateColumnsDataFilterStateToGql, mapSearchNumericColumnsDataFilterStateToGql, mapSearchTextColumnsDataFilterStateToGql, mockGraphQLLink, observeRowsWithGqlInputsHandling, parseAst, parseComments, parseHints, queryProcessingLink, removeNotDefinedHintDef, removeNotDefinedTransformer, removeVariable, removeVariableDefinition, removeVariableDefinitionsNotDefined, skipAndTake, sortItems, toGQL };
-export type { CreateSortsMapperOptions, DatatableGraphQLDataMapper, DatatableGraphQLDataMapperResult, DatatableGraphQLErrorHandler, DatatableGraphQLVariables, DatatableGraphqlServiceConfig, DatatableQueryOptions, EmptyObject, FilterStateMapper, FilterStateMapperFilter, FilterStateMapperResult, FilterStateMapperVariables, FilterStateMappers, FilteredResults, FilteredResultsPageInfo, GqlDatatableAccessor, HintDefinition, HintTransformOperation, HintTransformer, HintsToken, LogQueryLinkOptions, MapperContext, MockApolloTestingProviderOptions, MockGraphQLLinkOptions, QueryProcessingConfig, QueryProcessingVariablesConfig, SimpleGqlTestExtraVariables, SimpleGqlTestRecord, SimpleGqlTestVariables, SortClause, SortsMapper, SortsMapperFieldEntry, SortsMapperFieldMap, SortsMapperResult, TypedFilterInput, TypedFilterStateMapperResult, WhereArg };
+export { DATATABLE_GRAPHQL_SERVICE_CONFIG, DEFAULT_PAGE_SIZE, DEFAULT_TO_REMOVE_ON_UNDEFINED, DatatableExportTransport, DatatableGqlDataExporter, DatatableGraphQLQueryRef, DatatableGraphqlService, GQLDirection, GQLVariable, HINT_NAMES_CAPTURE_REGEX, HINT_PREFIX_REGEX, HintsKind, MAX_ERROR_RECOVERY_ATTEMPTS, MockDatatable, SIMPLE_GQL_TEST_QUERY, SIMPLE_GQL_TEST_SEARCH_QUERY, baseSchemaFragment, checkRecordsHaveValue, containsVariable, createHintsToken, createMockApolloTestingProvider, createSimpleGqlTestRecord, createSimpleGqlTestRoot, createSortsMapper, filterWhere, filteredResults, getHintsToken, getPageInfo, getTokenAppliesTo, gqlVar, hintNamesFromHintToken, hintsTokensContainingHint, inlineVariable, inlineVariableHintDef, inlineVariableTransformer, isCommentToken, isHintToken, isInlineComment, logQueryLink, mapFilterStates, mapSearchDateColumnsDataFilterStateToGql, mapSearchNumericColumnsDataFilterStateToGql, mapSearchTextColumnsDataFilterStateToGql, mockGraphQLLink, observeRowsWithGqlInputsHandling, parseAst, parseComments, parseHints, processGql, provideDatatableExportTransport, queryProcessingLink, removeNotDefinedHintDef, removeNotDefinedTransformer, removeVariable, removeVariableDefinition, removeVariableDefinitionsNotDefined, skipAndTake, sortItems, toGQL };
+export type { CreateSortsMapperOptions, DatatableExportPayload, DatatableGraphQLDataMapper, DatatableGraphQLDataMapperResult, DatatableGraphQLErrorHandler, DatatableGraphQLVariables, DatatableGraphqlServiceConfig, DatatableQueryOptions, EmptyObject, FilterStateMapper, FilterStateMapperFilter, FilterStateMapperResult, FilterStateMapperVariables, FilterStateMappers, FilteredResults, FilteredResultsPageInfo, GqlDatatableAccessor, HintDefinition, HintTransformOperation, HintTransformer, HintsToken, LogQueryLinkOptions, MapperContext, MockApolloTestingProviderOptions, MockGraphQLLinkOptions, QueryProcessingConfig, QueryProcessingVariablesConfig, SimpleGqlTestExtraVariables, SimpleGqlTestRecord, SimpleGqlTestVariables, SortClause, SortsMapper, SortsMapperFieldEntry, SortsMapperFieldMap, SortsMapperResult, TypedFilterInput, TypedFilterStateMapperResult, WhereArg };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theseam/ui-common",
-  "version": "1.0.2-beta.54",
+  "version": "1.0.2-beta.57",
   "peerDependencies": {
     "@angular/cdk": "^20.2.3",
     "@angular/common": "^20.3.0",