nuxt-ui-tools 1.1.0 → 1.3.0

package/dist/runtime/table/composables/use-table-filter-options.js

@@ -1,5 +1,5 @@
-import { useQuery } from "@tanstack/vue-query";
-import { computed, unref } from "vue";
+import { useQueries, useQuery } from "@tanstack/vue-query";
+import { computed, unref, watch } from "vue";
 import {
   isBoolean,
   isFunction,
@@ -17,6 +17,7 @@ import {
   resolveOptionFilterUi,
   resolveTableFacetMode
 } from "../utils/index.js";
+import { useTableRemoteFilterOptions } from "./use-table-remote-filter-options.js";
 export function useTableFilterOptions(options) {
   const isActive = computed(() => options.active?.value ?? true);
   const isReady = computed(() => options.ready?.value ?? true);
@@ -52,29 +53,36 @@ export function useTableFilterOptions(options) {
     () => shouldDeriveCounts.value && isActive.value && isReady.value
   );
   const isRemoteTable = computed(() => options.schema.value.source.mode === "remote");
+  const remoteConfig = computed(() => optionDefinition.value?.source?.remote);
+  const hasRemotePages = computed(() => Boolean(remoteConfig.value));
   const hasRemoteOptionQuery = computed(
-    () => options.definition.kind === "option" && isFunction(options.definition.source?.query)
+    () => !hasRemotePages.value && options.definition.kind === "option" && isFunction(options.definition.source?.query)
   );
+  const hasServerOptions = computed(() => hasRemotePages.value || hasRemoteOptionQuery.value);
   const facetSpec = computed(() => options.definition.source?.facet);
   const facetConfig = computed(
     () => isFacetConfig(facetSpec.value) ? facetSpec.value : null
   );
   const hasPerFilterFacetQuery = computed(() => isFunction(facetConfig.value?.query));
   const usesFacetCounts = computed(
-    () => Boolean(facetSpec.value) && (options.schema.value.source.mode === "client" || hasPerFilterFacetQuery.value || isRemoteTable.value && Boolean(remoteSource.value?.facets))
+    () => Boolean(facetSpec.value) && (options.schema.value.source.mode === "client" || hasPerFilterFacetQuery.value || // The main request cannot count options it never lists: paged options need `facet.query`.
+    isRemoteTable.value && Boolean(remoteSource.value?.facets) && !hasRemotePages.value)
+  );
+  const countsPagesRemotely = computed(
+    () => hasRemotePages.value && isRemoteTable.value && hasPerFilterFacetQuery.value
   );
   const resolvedTreeSearchMode = computed(() => {
     if (optionUi.value?.presentation !== "tree") {
-      return hasRemoteOptionQuery.value ? "remote" : "local";
+      return hasServerOptions.value ? "remote" : "local";
     }
     const configured = optionUi.value.tree.searchMode;
     if (configured === "local" || configured === "remote") {
       return configured;
     }
-    return hasRemoteOptionQuery.value ? "remote" : "local";
+    return hasServerOptions.value ? "remote" : "local";
   });
   const querySearch = computed(() => {
-    if (!hasRemoteOptionQuery.value) {
+    if (!hasServerOptions.value) {
       return;
     }
     if (resolvedTreeSearchMode.value === "local") {
@@ -97,6 +105,30 @@ export function useTableFilterOptions(options) {
       key: options.definition.key
     })
   );
+  const remotePages = useTableRemoteFilterOptions({
+    config: remoteConfig,
+    enabled: computed(() => isActive.value && isReady.value),
+    search: computed(() => querySearch.value ?? "")
+  });
+  watch(
+    [remotePages.entries, selectedValues],
+    ([entries, values]) => {
+      if (!hasRemotePages.value || !values.length) return;
+      const picked = new Set(values.map(String));
+      options.filters.selectedOptions.remember(
+        options.definition.key,
+        flattenRawOptionEntries(entries).filter((entry) => picked.has(String(entry.value)))
+      );
+    },
+    { immediate: true }
+  );
+  const remotePageEntries = computed(() => {
+    const listed = new Set(
+      flattenRawOptionEntries(remotePages.entries.value).map((entry) => String(entry.value))
+    );
+    const selected = options.filters.selectedOptions.getSelectedOptions(options.definition.key).filter((entry) => !listed.has(String(entry.value)));
+    return [...selected, ...remotePages.entries.value];
+  });
   const optionQuery = useQuery(
     computed(() => {
       const activeDefinition = optionDefinition.value;
@@ -126,7 +158,7 @@ export function useTableFilterOptions(options) {
   );
   const perFilterFacetQuery = useQuery(
     computed(() => {
-      if (!isRemoteTable.value || !usesFacetCounts.value || !facetConfig.value?.query) {
+      if (!isRemoteTable.value || !usesFacetCounts.value || !facetConfig.value?.query || countsPagesRemotely.value) {
         return {
           enabled: false,
           queryFn: async () => ({ facets: [] }),
@@ -168,10 +200,62 @@ export function useTableFilterOptions(options) {
     }
     return result?.options ? [...result.options] : [];
   });
+  const pageFacetRequests = computed(() => {
+    if (!countsPagesRemotely.value || !shouldResolveCounts.value) return [];
+    const paged = remotePages.pageValues.value;
+    const listed = new Set(paged.flat().map(String));
+    const outside = options.filters.selectedOptions.getSelectedOptions(options.definition.key).map((entry) => entry.value).filter((value) => !listed.has(String(value)));
+    return [outside, ...paged].filter((values) => values.length > 0);
+  });
+  const pageFacetQueries = useQueries({
+    queries: computed(() => {
+      const config = facetConfig.value;
+      const query = config?.query;
+      if (!query) return [];
+      return pageFacetRequests.value.map((values) => {
+        const definition = unref(
+          query({
+            facets: [{ key: options.definition.key, mode: resolveTableFacetMode(config), values }],
+            table: options.queryContent.facetsBaseContext.value
+          })
+        );
+        return {
+          // The table's own cache entry: it keeps the requested values next to their counts.
+          queryFn: async (context) => {
+            if (!definition.queryFn) {
+              throw new Error("facet.query must return a query definition with a queryFn.");
+            }
+            const result = await definition.queryFn({
+              ...context,
+              direction: "forward",
+              pageParam: null,
+              queryKey: definition.queryKey
+            });
+            return { result, values };
+          },
+          queryKey: ["table-filter-page-facets", ...definition.queryKey],
+          refetchOnWindowFocus: QUERY_DEFAULTS.refetchOnWindowFocus,
+          staleTime: QUERY_DEFAULTS.staleTime.filterOptions
+        };
+      });
+    })
+  });
+  const pageFacetCounts = computed(
+    () => pageFacetQueries.value.flatMap((query) => {
+      if (!query.data) return [];
+      const counted = new Map(
+        query.data.result.facets.filter((facet) => facet.key === options.definition.key).flatMap((facet) => facet.options).map((option) => [String(option.value), option.count])
+      );
+      return query.data.values.map((value) => ({ count: counted.get(String(value)) ?? 0, value }));
+    })
+  );
   const facetCounts = computed(() => {
     if (!usesFacetCounts.value) {
       return [];
     }
+    if (countsPagesRemotely.value) {
+      return pageFacetCounts.value;
+    }
     const facets = isRemoteTable.value && hasPerFilterFacetQuery.value ? unref(perFilterFacetQuery.data)?.facets ?? [] : options.queryContent.facets.value.facets;
     return facets.find((facet) => facet.key === options.definition.key)?.options ?? [];
   });
@@ -185,8 +269,10 @@ export function useTableFilterOptions(options) {
       definition: options.definition,
       deriveCounts: false,
       facetCounts: resolvedFacetCounts.value,
-      missingCountFallback: shouldResolveCounts.value && usesFacetCounts.value ? 0 : void 0,
-      options: hasRemoteOptionQuery.value ? remoteEntries.value : staticEntries.value,
+      // Paged options without counts yet stay unknown (a placeholder) until their page is counted.
+      missingCountFallback: shouldResolveCounts.value && usesFacetCounts.value && !countsPagesRemotely.value ? 0 : void 0,
+      options: hasRemotePages.value ? remotePageEntries.value : hasRemoteOptionQuery.value ? remoteEntries.value : staticEntries.value,
+      authoritative: hasRemotePages.value,
       rows: [],
       selectedValues: selectedValues.value
     })
@@ -228,7 +314,7 @@ export function useTableFilterOptions(options) {
         (entry) => !isNullish(entry.value)
       );
     }
-    if (!normalizedSearch.value.length || hasRemoteOptionQuery.value) {
+    if (!normalizedSearch.value.length || hasServerOptions.value) {
       return selectableSourceEntries.value;
     }
     return selectableSourceEntries.value.filter(
@@ -236,28 +322,53 @@ export function useTableFilterOptions(options) {
     );
   });
   const isInitialLoading = computed(
-    () => optionQuery.isLoading.value && !optionQuery.isPlaceholderData.value
+    () => hasRemotePages.value ? remotePages.isLoading.value : optionQuery.isLoading.value && !optionQuery.isPlaceholderData.value
+  );
+  const isStaleLoading = computed(
+    () => hasRemotePages.value ? remotePages.isRefreshing.value : !isInitialLoading.value && optionQuery.isFetching.value
   );
-  const isStaleLoading = computed(() => !isInitialLoading.value && optionQuery.isFetching.value);
   const isCountLoading = computed(
-    () => isRemoteTable.value && shouldResolveCounts.value && perFilterFacetQuery.isFetching.value
+    () => isRemoteTable.value && shouldResolveCounts.value && !countsPagesRemotely.value && perFilterFacetQuery.isFetching.value
   );
   return {
-    error: computed(() => optionQuery.error.value ?? perFilterFacetQuery.error.value),
+    error: computed(
+      () => (hasRemotePages.value ? remotePages.error.value : optionQuery.error.value) ?? perFilterFacetQuery.error.value
+    ),
     facetCounts,
     filteredEntries,
     filteredTreeEntries: computed(() => filteredTreeState.value.entries),
     isCountLoading,
-    isError: computed(() => optionQuery.isError.value || perFilterFacetQuery.isError.value),
+    isError: computed(
+      () => (hasRemotePages.value ? remotePages.failed.value : optionQuery.isError.value) || perFilterFacetQuery.isError.value
+    ),
     isLoading: isInitialLoading,
     isStaleLoading,
-    refresh: () => Promise.all([optionQuery.refetch(), perFilterFacetQuery.refetch()]),
+    refresh: () => Promise.all([
+      hasRemotePages.value ? remotePages.retry() : optionQuery.refetch(),
+      perFilterFacetQuery.refetch()
+    ]),
+    /** Paging of `source.remote`: the editor list loads the next page ahead of the scroll. */
+    remote: {
+      enabled: hasRemotePages,
+      failed: remotePages.failed,
+      hasMore: remotePages.hasMore,
+      loadMore: remotePages.loadMore,
+      loadingMore: remotePages.loadingMore,
+      prefetchDistance: remotePages.prefetchDistance,
+      retry: remotePages.retry
+    },
     searchExpandedIds: computed(() => filteredTreeState.value.expandedIds),
     showCounts: computed(() => shouldDeriveCounts.value && usesFacetCounts.value),
     sourceEntries: selectableSourceEntries,
     sourceTreeEntries: resolvedSourceTreeEntries
   };
 }
+function flattenRawOptionEntries(entries) {
+  return entries.flatMap((entry) => [
+    ...isNullish(entry.value) ? [] : [entry],
+    ...flattenRawOptionEntries(entry.children ?? [])
+  ]);
+}
 function isFacetConfig(value) {
   return isObject(value);
 }

package/dist/runtime/table/composables/use-table-filter-selected-options.d.ts

@@ -0,0 +1,20 @@
+import type { ComputedRef } from 'vue';
+import type { TableFilterOptionEntry, TableFilterOptionValueEntry, TableQueryStateFilterRule, TableUiFilterDefinition } from '../types/index.js';
+export interface UseTableFilterSelectedOptionsParams {
+    definitions: ComputedRef<TableUiFilterDefinition[]>;
+    /** Committed filter rules. */
+    rules: ComputedRef<TableQueryStateFilterRule[]>;
+}
+/**
+ * Options of the committed values of remote option filters, so tags, panel chips, and the mobile
+ * sheet show labels instead of raw values. Options the editors loaded are recorded as values get
+ * picked; the rest (for example values restored from the URL) resolve through each filter's
+ * `source.remote.resolveSelected`, under the consumer's query key so a prefetched result is reused.
+ */
+export declare function useTableFilterSelectedOptions(params: UseTableFilterSelectedOptionsParams): {
+    getSelectedOptions: (key: string) => TableFilterOptionValueEntry[];
+    /** Options of committed values are resolving for this filter. */
+    isResolving: (key: string) => boolean;
+    remember: (key: string, options: readonly TableFilterOptionEntry[]) => void;
+};
+export type TableFilterSelectedOptions = ReturnType<typeof useTableFilterSelectedOptions>;

package/dist/runtime/table/composables/use-table-filter-selected-options.js

@@ -0,0 +1,99 @@
+import { useQuery, useQueryClient } from "@tanstack/vue-query";
+import { computed, shallowRef, watch } from "vue";
+import { isBoolean, isNullish, isNumber, isString } from "../../shared/utils/predicate.js";
+import { QUERY_DEFAULTS } from "../constants/query-state.js";
+export function useTableFilterSelectedOptions(params) {
+  const queryClient = useQueryClient();
+  const known = shallowRef(/* @__PURE__ */ new Map());
+  const remoteDefinitions = computed(
+    () => params.definitions.value.flatMap((definition) => {
+      const remote = definition.kind === "option" ? definition.source?.remote : void 0;
+      return remote ? [{ key: definition.key, remote }] : [];
+    })
+  );
+  function selectedValues(key) {
+    const rule = params.rules.value.find((entry) => entry.key === key);
+    const values = Array.isArray(rule?.value) ? rule.value : isNullish(rule?.value) ? [] : [rule.value];
+    return values.filter(isPrimitiveValue);
+  }
+  const requests = computed(
+    () => remoteDefinitions.value.flatMap(({ key, remote }) => {
+      const cached = known.value.get(key);
+      const missing = selectedValues(key).filter((value) => !cached?.has(String(value)));
+      const query = missing.length ? resolveSelectedQuery(remote, missing) : void 0;
+      return query ? [{ key, query }] : [];
+    })
+  );
+  const hydration = useQuery(
+    computed(() => {
+      const snapshot = requests.value;
+      return {
+        enabled: snapshot.length > 0,
+        queryFn: () => Promise.all(
+          snapshot.map(async ({ key, query }) => ({
+            key,
+            options: await queryClient.fetchQuery({
+              queryFn: (context) => {
+                if (!query.queryFn) {
+                  throw new Error(
+                    "resolveSelected must return a query definition with a queryFn."
+                  );
+                }
+                return query.queryFn({ ...context, direction: "forward", pageParam: null });
+              },
+              queryKey: query.queryKey,
+              staleTime: QUERY_DEFAULTS.staleTime.filterOptions
+            })
+          }))
+        ),
+        queryKey: [
+          "table-filter-selected-options",
+          snapshot.map(({ key, query }) => [key, query.queryKey])
+        ],
+        refetchOnWindowFocus: QUERY_DEFAULTS.refetchOnWindowFocus,
+        staleTime: QUERY_DEFAULTS.staleTime.filterOptions
+      };
+    })
+  );
+  watch(
+    () => hydration.data.value,
+    (results) => {
+      for (const result of results ?? []) remember(result.key, result.options);
+    }
+  );
+  function remember(key, options) {
+    const entries = flattenValueEntries(options);
+    if (!entries.length) return;
+    const current = known.value.get(key);
+    if (entries.every((entry) => current?.get(String(entry.value))?.label === entry.label)) return;
+    const next = new Map(current);
+    for (const entry of entries) next.set(String(entry.value), entry);
+    known.value = new Map(known.value).set(key, next);
+  }
+  function getSelectedOptions(key) {
+    const cached = known.value.get(key);
+    if (!cached) return [];
+    return selectedValues(key).flatMap((value) => {
+      const entry = cached.get(String(value));
+      return entry ? [entry] : [];
+    });
+  }
+  return {
+    getSelectedOptions,
+    /** Options of committed values are resolving for this filter. */
+    isResolving: (key) => hydration.isFetching.value && requests.value.some((request) => request.key === key),
+    remember
+  };
+}
+function resolveSelectedQuery(remote, values) {
+  return remote.resolveSelected?.({ values });
+}
+function flattenValueEntries(options) {
+  return options.flatMap((option) => [
+    ...isNullish(option.value) ? [] : [{ ...option, value: option.value }],
+    ...flattenValueEntries(option.children ?? [])
+  ]);
+}
+function isPrimitiveValue(value) {
+  return isString(value) || isNumber(value) || isBoolean(value);
+}

package/dist/runtime/table/composables/use-table-filters.d.ts

@@ -71,6 +71,11 @@ export declare function useTableFilters(params: UseTableFiltersParams): {
     }) => void;
     searchPlaceholder: ComputedRef<string>;
     searchQuery: import("vue").WritableComputedRef<string, string>;
+    selectedOptions: {
+        getSelectedOptions: (key: string) => import("../types/index.js").TableFilterOptionValueEntry[];
+        isResolving: (key: string) => boolean;
+        remember: (key: string, options: readonly TableFilterOptionEntry[]) => void;
+    };
     setFilterOperator: (input: {
         key: string;
         operator: TableFilterOperator;

package/dist/runtime/table/composables/use-table-filters.js

@@ -11,6 +11,7 @@ import {
   resolveTableFilterDefaultRules,
   resolveFilterOptionEntries
 } from "../utils/index.js";
+import { useTableFilterSelectedOptions } from "./use-table-filter-selected-options.js";
 import { useTableSearch } from "./use-table-search.js";
 export function useTableFilters(params) {
   const { t } = useUiToolsLocale();
@@ -34,6 +35,10 @@ export function useTableFilters(params) {
     })
   );
   const hasActiveUiFilters = computed(() => activeUiFilters.value.length > 0);
+  const selectedOptions = useTableFilterSelectedOptions({
+    definitions,
+    rules: effectiveUiFilters
+  });
   function getDefinition(input) {
     return definitions.value.find(
       (definition) => definition.key === input.key
@@ -87,7 +92,7 @@ export function useTableFilters(params) {
     }
     const preview = buildFilterPreview({
       definition,
-      optionEntries: input.entries,
+      optionEntries: withSelectedOptions(input.key, input.entries),
       rule: getFilterState({ key: input.key })
     });
     const rule = getFilterState({ key: input.key });
@@ -98,6 +103,19 @@ export function useTableFilters(params) {
       dirty: !isNullish(getActiveFilterState({ key: input.key }))
     };
   }
+  function withSelectedOptions(key, entries = []) {
+    const listed = new Set(entries.map((entry) => String(entry.value)));
+    const missing = selectedOptions.getSelectedOptions(key).filter((entry) => !listed.has(String(entry.value)));
+    return missing.length ? [
+      ...entries,
+      ...missing.map((entry) => ({
+        color: entry.color,
+        icon: entry.icon,
+        label: getFilterLabelText({ label: entry.label }),
+        value: entry.value
+      }))
+    ] : entries;
+  }
   function getFilterOperator(input) {
     const definition = getDefinition({ key: input.key });
     const rule = getFilterState({ key: input.key });
@@ -253,6 +271,7 @@ export function useTableFilters(params) {
     replaceFilters,
     searchPlaceholder: search.searchPlaceholder,
     searchQuery: search.searchQuery,
+    selectedOptions,
     setFilterOperator,
     setOptionFilterValues,
     setScalarFilterValue,

package/dist/runtime/table/composables/use-table-internals.d.ts

@@ -191,6 +191,11 @@ declare function createTableInternals<TSchema>(options: {
         }) => void;
         searchPlaceholder: import("vue").ComputedRef<string>;
         searchQuery: import("vue").WritableComputedRef<string, string>;
+        selectedOptions: {
+            getSelectedOptions: (key: string) => import("../types/index.js").TableFilterOptionValueEntry[];
+            isResolving: (key: string) => boolean;
+            remember: (key: string, options: readonly import("../types/index.js").TableFilterOptionEntry[]) => void;
+        };
         setFilterOperator: (input: {
             key: string;
             operator: import("../types/index.js").TableFilterOperator;
@@ -782,6 +787,11 @@ declare function useProvideTableInternals<TSchema>(options: {
         }) => void;
         searchPlaceholder: import("vue").ComputedRef<string>;
         searchQuery: import("vue").WritableComputedRef<string, string>;
+        selectedOptions: {
+            getSelectedOptions: (key: string) => import("../types/index.js").TableFilterOptionValueEntry[];
+            isResolving: (key: string) => boolean;
+            remember: (key: string, options: readonly import("../types/index.js").TableFilterOptionEntry[]) => void;
+        };
         setFilterOperator: (input: {
             key: string;
             operator: import("../types/index.js").TableFilterOperator;
@@ -1370,6 +1380,11 @@ declare function useTableInternals(): {
         }) => void;
         searchPlaceholder: import("vue").ComputedRef<string>;
         searchQuery: import("vue").WritableComputedRef<string, string>;
+        selectedOptions: {
+            getSelectedOptions: (key: string) => import("../types/index.js").TableFilterOptionValueEntry[];
+            isResolving: (key: string) => boolean;
+            remember: (key: string, options: readonly import("../types/index.js").TableFilterOptionEntry[]) => void;
+        };
         setFilterOperator: (input: {
             key: string;
             operator: import("../types/index.js").TableFilterOperator;

package/dist/runtime/table/composables/use-table-remote-filter-options.d.ts

@@ -0,0 +1,42 @@
+import type { InfiniteData } from '@tanstack/vue-query';
+import type { ComputedRef } from 'vue';
+import type { RemoteOptionsResult } from '../../shared/types/remote-options.js';
+import type { RemoteOptionsPageParam } from '../../shared/utils/remote-options.js';
+import type { TableFilterOptionEntry, TableFilterRemoteOptions } from '../types/index.js';
+type RemotePage = RemoteOptionsResult<TableFilterOptionEntry>;
+/** Defaults of `source.remote` on option filters, matching the form engine's remote options. */
+export declare const TABLE_REMOTE_FILTER_OPTIONS_DEFAULTS: {
+    readonly pageSize: 25;
+    readonly searchDebounce: 250;
+};
+export interface UseTableRemoteFilterOptionsParams {
+    config: ComputedRef<TableFilterRemoteOptions | undefined>;
+    /** Raw search input; it is trimmed and debounced before it reaches the source. */
+    search: ComputedRef<string>;
+    /** Pages load only while an editor shows the list. */
+    enabled: ComputedRef<boolean>;
+}
+/**
+ * Pages of a remote option filter. Nothing loads until an editor shows the list; each search term
+ * keeps its own pages in the TanStack Query cache, and the previous term's pages stay on screen
+ * while the next term loads.
+ */
+export declare function useTableRemoteFilterOptions(params: UseTableRemoteFilterOptionsParams): {
+    entries: ComputedRef<readonly TableFilterOptionEntry[]>;
+    error: import("vue").Ref<null, null> | import("vue").Ref<Error, Error>;
+    /** More pages exist after the loaded ones. */
+    hasMore: ComputedRef<boolean>;
+    /** The first page of the current term has not arrived yet. */
+    isLoading: ComputedRef<boolean>;
+    /** A new term, or a refetch, is loading while earlier options stay on screen. */
+    isRefreshing: ComputedRef<boolean>;
+    /** The next page is loading at the end of the list. */
+    loadingMore: ComputedRef<boolean>;
+    /** The last request failed: the next page (or the first) can be retried. */
+    failed: ComputedRef<boolean>;
+    loadMore: () => void;
+    pageValues: ComputedRef<(string | number | boolean)[][]>;
+    prefetchDistance: ComputedRef<number | "viewport">;
+    retry: () => Promise<import("@tanstack/vue-query").QueryObserverResult<InfiniteData<RemotePage, RemoteOptionsPageParam>, Error>>;
+};
+export {};

package/dist/runtime/table/composables/use-table-remote-filter-options.js

@@ -0,0 +1,102 @@
+import { useInfiniteQuery } from "@tanstack/vue-query";
+import { refDebounced } from "@vueuse/core";
+import { computed } from "vue";
+import {
+  REMOTE_OPTIONS_FIRST_PAGE,
+  resolveRemoteOptionsNextPage
+} from "../../shared/utils/remote-options.js";
+import { QUERY_DEFAULTS } from "../constants/query-state.js";
+export const TABLE_REMOTE_FILTER_OPTIONS_DEFAULTS = {
+  pageSize: 25,
+  searchDebounce: 250
+};
+export function useTableRemoteFilterOptions(params) {
+  const pageSize = computed(
+    () => Math.max(
+      1,
+      params.config.value?.pagination?.size ?? TABLE_REMOTE_FILTER_OPTIONS_DEFAULTS.pageSize
+    )
+  );
+  const minLength = computed(() => Math.max(0, params.config.value?.search?.minLength ?? 0));
+  const search = refDebounced(
+    computed(() => params.search.value.trim()),
+    () => params.config.value?.search?.debounce ?? TABLE_REMOTE_FILTER_OPTIONS_DEFAULTS.searchDebounce
+  );
+  const canFetch = computed(
+    () => search.value.length === 0 || search.value.length >= minLength.value
+  );
+  const pages = useInfiniteQuery(
+    computed(() => {
+      const config = params.config.value;
+      const term = search.value;
+      const size = pageSize.value;
+      const firstPage = config?.load({ page: { ...REMOTE_OPTIONS_FIRST_PAGE, size }, search: term });
+      return {
+        enabled: Boolean(config) && params.enabled.value && canFetch.value,
+        getNextPageParam: (lastPage, allPages) => resolveRemoteOptionsNextPage(lastPage, allPages.length),
+        initialPageParam: REMOTE_OPTIONS_FIRST_PAGE,
+        // Keeps the previous term's options on screen while the next term loads.
+        placeholderData: (previous) => previous,
+        async queryFn(queryContext) {
+          const definition = config?.load({
+            page: { ...queryContext.pageParam, size },
+            search: term
+          });
+          if (!definition?.queryFn) {
+            throw new Error("Remote option filters must return a query definition with a queryFn.");
+          }
+          return definition.queryFn({
+            ...queryContext,
+            direction: "forward",
+            pageParam: null,
+            queryKey: definition.queryKey
+          });
+        },
+        queryKey: [
+          ...firstPage?.queryKey ?? ["table-filter-remote-options", "disabled"],
+          { tableFilterOptionPages: size }
+        ],
+        refetchOnWindowFocus: QUERY_DEFAULTS.refetchOnWindowFocus,
+        staleTime: QUERY_DEFAULTS.staleTime.filterOptions
+      };
+    })
+  );
+  const entries = computed(
+    () => pages.data.value?.pages.flatMap((page) => page.options) ?? []
+  );
+  const pageValues = computed(
+    () => pages.data.value?.pages.map((page) => collectOptionValues(page.options)) ?? []
+  );
+  function loadMore() {
+    if (!pages.hasNextPage.value || pages.isFetchingNextPage.value || pages.isFetching.value) return;
+    void pages.fetchNextPage();
+  }
+  return {
+    entries,
+    error: pages.error,
+    /** More pages exist after the loaded ones. */
+    hasMore: computed(() => pages.hasNextPage.value),
+    /** The first page of the current term has not arrived yet. */
+    isLoading: computed(() => pages.isLoading.value && !pages.isPlaceholderData.value),
+    /** A new term, or a refetch, is loading while earlier options stay on screen. */
+    isRefreshing: computed(
+      () => pages.isFetching.value && !pages.isFetchingNextPage.value && !pages.isLoading.value
+    ),
+    /** The next page is loading at the end of the list. */
+    loadingMore: computed(() => pages.isFetchingNextPage.value),
+    /** The last request failed: the next page (or the first) can be retried. */
+    failed: computed(() => pages.isError.value || pages.isFetchNextPageError.value),
+    loadMore,
+    pageValues,
+    prefetchDistance: computed(
+      () => params.config.value?.pagination?.prefetchDistance ?? "viewport"
+    ),
+    retry: () => pages.isFetchNextPageError.value ? pages.fetchNextPage() : pages.refetch()
+  };
+}
+function collectOptionValues(options) {
+  return options.flatMap((option) => [
+    ...option.value === void 0 ? [] : [option.value],
+    ...collectOptionValues(option.children ?? [])
+  ]);
+}

package/dist/runtime/table/types/filters.d.ts

@@ -1,3 +1,4 @@
+import type { RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
 import type { TableFilterOperator, TableQueryStateFilterRule, TableQueryStateFilterValue } from './query-state.js';
 import type { TableFacetExecutionResult, TableFacetRequestDescriptor, TableFacetsContext, TableQueryDefinition } from './source.js';
 import type { GenericObject, RenderableType, TableFieldPath, TableKnownFieldPath, TableTextValue } from './utils.js';
@@ -538,6 +539,41 @@ export interface TableFilterOptionQueryContext {
     cursor?: string | null;
 }
 export type TableFilterOptionQueryResult<TValue = TableFilterPrimitiveValue> = TableFilterOptionQueryResultForPresentation<TValue, TableOptionFilterPresentation>;
+/** Page requested from a remote option filter source. */
+export interface TableFilterRemoteOptionsRequest {
+    /** Current debounced search term. Empty when the editor lists unfiltered options. */
+    search: string;
+    /** Requested page: `index` (1-based) for page pagination, `cursor` for cursor pagination. */
+    page: RemoteOptionsPageRequest;
+}
+/** Selected values a remote option filter needs options for. */
+export interface TableFilterRemoteSelectedRequest<TValue = TableFilterPrimitiveValue> {
+    /** Committed filter values that the options loaded so far do not contain. */
+    values: readonly TValue[];
+}
+/**
+ * Remote option source loaded page by page, following the form engine's remote options:
+ * server-side search, page or cursor pagination loaded ahead of the scroll, and options for
+ * selected values the loaded pages do not contain (for example values restored from the URL).
+ */
+export interface TableFilterRemoteOptions<TValue = TableFilterPrimitiveValue, TPresentation extends TableOptionFilterPresentation = TableOptionFilterPresentation> {
+    /** Query definition of one page of options for the current search term. */
+    load: (request: TableFilterRemoteOptionsRequest) => TableQueryDefinition<RemoteOptionsResult<TableOptionEntryForPresentation<TValue, TPresentation>>>;
+    /**
+     * Query definition resolving the options of selected values the loaded pages do not contain, so
+     * tags and editors show their labels. Without it, such values show as their raw value.
+     */
+    resolveSelected?: {
+        bivarianceHack(request: TableFilterRemoteSelectedRequest<TValue>): TableQueryDefinition<readonly TableOptionEntryForPresentation<TValue, TPresentation>[]>;
+    }['bivarianceHack'];
+    /**
+     * Page size, and how far before the list end the next page loads. Defaults to
+     * `{ type: 'page', size: 25 }` with the next page requested three viewport heights ahead.
+     */
+    pagination?: RemoteOptionsPagination;
+    /** Search debounce (default 250 ms) and minimum term length (default 0). */
+    search?: RemoteOptionsSearch;
+}
 export type TableFilterFacetMode = boolean | 'exclude-self' | 'include-self';
 export interface TableFilterFacetQueryContext<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> {
     table: Omit<TableFacetsContext<TRow, TContext, TKey>, 'facets'>;
@@ -596,7 +632,13 @@ export interface TableOptionFilterDefinition<TRow extends GenericObject = Generi
     kind: 'option';
     source?: {
         options?: readonly TableOptionEntryForPresentation<TValue, TPresentation>[];
+        /** Loads the whole option list in one query. For large lists, prefer `remote`. */
         query?: (context: TableFilterOptionQueryContext) => TableQueryDefinition<TableOptionEntryForPresentation<TValue, TPresentation>[] | TableFilterOptionQueryResultForPresentation<TValue, TPresentation>>;
+        /**
+         * Loads options page by page with server-side search, as the editor scrolls. Takes precedence
+         * over `options` and `query`.
+         */
+        remote?: TableFilterRemoteOptions<TValue, TPresentation>;
         facet?: TableFilterFacetSpec<TRow, TContext, TKey>;
         sort?: 'alpha' | 'count';
     };