Nuxt Module

// With options
const { block } = useFronticBlock("ProductCard", productId, {
  contextKey: contextToken,
  staleTime: 1000 * 60 * 10, // 10 minutes
});

// Reactive key - automatically refetches when key changes
const productKey = ref("product-123");
const { block } = useFronticBlock("ProductCard", productKey);

import type { Ref, ShallowRef, MaybeRef } from "vue";
import type { BlockName, ResponseOf } from "@frontic/nuxt/types";

function useFronticBlock<T extends BlockName>(
  name: T,
  key: MaybeRef<string>,
  options?: {
    contextKey?: MaybeRef<string | undefined>;
    contextDomain?: MaybeRef<string | undefined>;
    requestUrl?: MaybeRef<string | false | undefined>;
    staleTime?: number;
    gcTime?: number;
    enabled?: MaybeRef<boolean> | (() => boolean);
    keepPreviousData?: boolean;
  },
): {
  block: Ref<ResponseOf<T> | undefined>;
  status: Ref<"pending" | "error" | "success">;
  asyncStatus: Ref<"idle" | "loading">;
  isLoading: Ref<boolean>;
  error: ShallowRef<Error | null>;
  refresh: () => Promise<void>;
  refetch: () => Promise<void>;
};

// Reactive params - refetches when category changes
const categoryKey = ref("shoes");

const { listing } = useFronticListing(
  "CategoryProducts",
  computed(() => ({ key: categoryKey.value })),
);

// No parameters - ProductSearch has no required ones
const { listing } = useFronticListing("ProductSearch");

// Static query - featured-products carousel with a fixed limit
const { listing } = useFronticListing(
  "ProductSearch",
  {},
  { query: { limit: 10 } },
);

// Typed filter + sort
const { listing } = useFronticListing(
  "ProductSearch",
  {},
  {
    query: {
      filter: [{ type: "equals", field: "properties.color", value: "red" }],
      sort: { field: "price.amount", order: "asc" },
      limit: 20,
    },
  },
);

// Reactive query - refetches when page changes
const page = ref(1);
const { listing } = useFronticListing(
  "ProductSearch",
  {},
  { query: computed(() => ({ limit: 20, page: page.value })) },
);

import type { Ref, ShallowRef, MaybeRef } from "vue";
import type {
  ListingName,
  ListingParamsOf,
  ListingQuery,
  ResponseOf,
} from "@frontic/nuxt/types";

// `params` is optional when every field of ListingParamsOf<T> is optional
function useFronticListing<T extends ListingName>(
  name: T,
  params?: MaybeRef<ListingParamsOf<T>>,
  options?: {
    query?: MaybeRef<ListingQuery<T> | undefined>;
    contextKey?: MaybeRef<string | undefined>;
    contextDomain?: MaybeRef<string | undefined>;
    requestUrl?: MaybeRef<string | false | undefined>;
    staleTime?: number;
    gcTime?: number;
    enabled?: MaybeRef<boolean> | (() => boolean);
    keepPreviousData?: boolean;
    initialData?: () => ResponseOf<T> | undefined;
    initialDataUpdatedAt?: number | (() => number);
  },
): {
  listing: Ref<ResponseOf<T> | undefined>;
  status: Ref<"pending" | "error" | "success">;
  asyncStatus: Ref<"idle" | "loading">;
  isLoading: Ref<boolean>;
  error: ShallowRef<Error | null>;
  refresh: () => Promise<void>;
  refetch: () => Promise<void>;
};

<script setup lang="ts">
const { result, state, searchTerm, addFilter, removeFilter, sortResult, loadNext } = useFronticSearch(
  'CategoryProducts',
  { key: 'shoes' },
  {
    orFilter: ['properties.color', 'properties.size'],
    filter: {
      select: ['properties.color', 'properties.size', 'properties.brand', 'price.amount'],
      label: {
        'properties.color': 'Color',
        'properties.size': 'Size',
        'properties.brand': 'Brand',
        'price.amount': 'Price',
      },
      type: {
        'price.amount': 'range',
      },
    },
    sorting: {
      label: {
        default: 'Relevance',
        'name:asc': 'Name A-Z',
        'name:desc': 'Name Z-A',
        'price.amount:asc': 'Price: Low to High',
        'price.amount:desc': 'Price: High to Low',
      },
    },
  }
)

// `sortResult` takes `'field:order'` or `'default'`, not any string, and a DOM value is a plain
// string. The options come from `state.available.sorting`, so the value is known-good - assert it
// against the parameter's own type rather than widening the signature.
function onSortChange(event: Event) {
  sortResult((event.target as HTMLSelectElement).value as Parameters<typeof sortResult>[0])
}

function toggleFilter(field: string, value: string, isSelected: boolean) {
  if (isSelected) {
    removeFilter(field, value)
  } else {
    addFilter(field, value)
  }
}

function setPriceMax(event: Event) {
  addFilter('price.amount', { to: Number((event.target as HTMLInputElement).value) })
}
</script>

<template>
  <div class="search-page">
    <!-- Search Input -->
    <input v-model="searchTerm" type="search" placeholder="Search products..." />

    <!-- Sort Dropdown -->
    <select @change="onSortChange">
      <option v-for="sort in state.available.sorting" :key="sort.key" :value="sort.key" :selected="state.active.sorting?.field === sort.key.split(':')[0]">
        {{ sort.label }}
      </option>
    </select>

    <!-- Filter Sidebar -->
    <aside>
      <div v-for="filter in state.available.filter" :key="filter.key">
        <h4>{{ filter.label }}</h4>

        <!-- `type` comes from the `filter.type` config; bounds come from `data` -->
        <input
          v-if="filter.type === 'range'"
          type="range"
          :min="filter.data?.total.min"
          :max="filter.data?.total.max"
          @change="setPriceMax"
        />

        <template v-else>
          <label v-for="option in filter.options" :key="option.value">
            <input type="checkbox" :checked="option.selected" @change="toggleFilter(filter.key, option.value, option.selected)" />
            {{ option.option }} ({{ option.count }})
          </label>
        </template>
      </div>
    </aside>

    <!-- Results -->
    <main>
      <p>{{ state.available.count.result }} products found</p>
      <div class="product-grid">
        <article v-for="item in result?.items" :key="item.key">
          <h3>{{ item.name }}</h3>
          <p>{{ item.price.formatted }}</p>
        </article>
      </div>
      <button v-if="result?.page?.next" @click="loadNext">Load More</button>
    </main>
  </div>
</template>

import type { Ref, ShallowRef, MaybeRef } from "vue";
import type {
  ListingName,
  ListingParamsOf,
  ListingFiltersOf,
  ListingSortsOf,
  ResponseOf,
  FilterOption,
  AggregationGroup,
} from "@frontic/nuxt/types";

// Typed filter for UI rendering
interface UiFilter<TFilters = Record<string, unknown>> {
  key: keyof TFilters & string;
  label: string;
  options: FilterOption[];
  type: string;
  data?: AggregationGroup;
}

// A range accepted by `addFilter`, `filterResult` and `initialFilters`
interface RangeFilterValue {
  from?: number;
  to?: number;
}

// A sort accepted by `sortResult`, `initialSort` and the `sorting` config.
// `SortString<"ProductSearch">` is the same type looked up by listing name.
type SortStringOf<TSorts> =
  | "default"
  | `${keyof TSorts & string}:${"asc" | "desc"}`;

// Typed sort for UI rendering
interface UiSort<TSorts = Record<string, unknown>> {
  key: SortStringOf<TSorts>;
  label: string;
  value: SortStringOf<TSorts>;
}

// Fully typed search state
interface SearchState<
  TFilters = Record<string, unknown>,
  TSorts = Record<string, unknown>,
> {
  active: {
    filter: Partial<Record<keyof TFilters & string, unknown>>;
    sorting:
      | { field: keyof TSorts & string; order: "asc" | "desc" }
      | undefined;
    search: string;
    page: number;
    count: {
      filter: number;
      sorting: number;
    };
  };
  available: {
    filter: UiFilter<TFilters>[];
    sorting: UiSort<TSorts>[];
    nextPage: boolean;
    prevPage: boolean;
    count: {
      filter: number;
      sorting: number;
      result: number;
      page: number;
    };
  };
}

// `params` is optional when every field of ListingParamsOf<TSearch> is optional
function useFronticSearch<
  TSearch extends ListingName,
  TFilters = ListingFiltersOf<TSearch>,
  TSorts = ListingSortsOf<TSearch>,
>(
  name: TSearch,
  params?: MaybeRef<ListingParamsOf<TSearch>>,
  options?: {
    contextKey?: MaybeRef<string | undefined>;
    contextDomain?: MaybeRef<string | undefined>;
    requestUrl?: MaybeRef<string | false | undefined>;
    staleTime?: number;
    gcTime?: number;
    enabled?: MaybeRef<boolean> | (() => boolean);
    keepPreviousData?: boolean;
    initialData?: () => ResponseOf<TSearch> | undefined;
    initialDataUpdatedAt?: number | (() => number);
    cacheKey?: string;
    searchTermThreshold?: number;
    searchDebounce?: number;
    analytics?: {
      searchCommitMs?: number;
      searchMinChars?: number;
    };
    orFilter?: Array<keyof TFilters & string>;
    disableSearch?: boolean;
    disableFilter?: boolean;
    disableSorting?: boolean;
    limit?: MaybeRef<number | undefined>;
    infinite?: boolean;
    initialPage?: number;
    initialSearch?: string;
    initialFilters?: Partial<Record<keyof TFilters & string, unknown>>;
    initialSort?: SortStringOf<TSorts>;
    urlQuerySync?:
      | boolean
      | {
          prefix?: string; // Namespace for this instance's params
          include?: Array<"search" | "sort" | "filter" | "page">;
          params?: Record<string, string>; // Rename: slice name or filter field → param
          history?: "replace" | "push";
        };
    filter?: {
      select?: Array<keyof TFilters & string>;
      mode?: "include" | "exclude";
      label?: Partial<Record<keyof TFilters & string, string>>;
      sort?: Array<keyof TFilters & string>; // Display order for filters
      type?: Partial<Record<keyof TFilters & string, string>>; // Display type, or 'default'
    };
    sorting?: {
      select?: Array<SortStringOf<TSorts>>;
      mode?: "include" | "exclude";
      label?: Partial<Record<SortStringOf<TSorts>, string>>;
      sort?: Array<SortStringOf<TSorts>>; // Display order for sorts
    };
  },
): {
  result: ShallowRef<ResponseOf<TSearch> | undefined>; // Full listing response
  status: Ref<"pending" | "error" | "success">;
  asyncStatus: Ref<"idle" | "loading">;
  isLoading: Ref<boolean>;
  error: ShallowRef<Error | null>;
  state: Ref<SearchState<TFilters, TSorts>>; // Fully typed state
  searchTerm: Ref<string>;
  loadNext: () => Promise<ResponseOf<TSearch> | undefined>;
  loadPrev: () => Promise<ResponseOf<TSearch> | undefined>;
  loadPage: (page: number) => Promise<ResponseOf<TSearch> | undefined>;
  refresh: () => Promise<void>;
  refetch: () => Promise<void>;
  sortResult: (sortBy?: SortStringOf<TSorts>) => Promise<void>;
  resetSorting: () => Promise<void>;
  filterResult: <K extends keyof TFilters>(
    field: K,
    values: Array<TFilters[K] | RangeFilterValue>,
  ) => Promise<void>;
  addFilter: <K extends keyof TFilters>(
    field: K,
    value: TFilters[K] | RangeFilterValue,
  ) => Promise<void>;
  removeFilter: <K extends keyof TFilters>(
    field: K,
    value?: TFilters[K],
  ) => Promise<void>;
  resetFilter: (field?: keyof TFilters & string) => Promise<void>;
  resetSearch: () => Promise<void>;
  reset: () => Promise<void>; // Reset all state (search, filters, sorting)
};