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, MaybeRef } from "vue";
import type { Blocks, Responses } from "@frontic/stack/generated-types";

function useFronticBlock<T extends keyof Blocks>(
  name: T,
  key: MaybeRef<string>,
  options?: {
    contextKey?: MaybeRef<string | undefined>;
    contextDomain?: MaybeRef<string | undefined>;
    requestUrl?: MaybeRef<string | undefined>;
    staleTime?: number;
  },
): {
  block: Ref<Responses[T] | undefined>;
  status: Ref<"pending" | "error" | "success">;
  refresh: () => Promise<void>;
  refetch: () => Promise<void>;
};

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

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

// 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, MaybeRef } from "vue";
import type {
  Listings,
  ListingParameters,
  ListingQueryFilters,
  ListingQuerySorts,
  Responses,
} from "@frontic/stack/generated-types";
import type { Query } from "@frontic/stack/query-types";

// Typed Query<filter, sort> for a given listing name — exposed for convenience
type ListingQuery<T extends keyof Listings = keyof Listings> = Query<
  T extends keyof ListingQueryFilters ? ListingQueryFilters[T] : unknown,
  T extends keyof ListingQuerySorts ? ListingQuerySorts[T] : unknown
>;

function useFronticListing<T extends keyof Listings>(
  name: T,
  params: MaybeRef<ListingParameters[T]>,
  options?: {
    query?: MaybeRef<ListingQuery<T> | undefined>;
    contextKey?: MaybeRef<string | undefined>;
    contextDomain?: MaybeRef<string | undefined>;
    requestUrl?: MaybeRef<string | undefined>;
    staleTime?: number;
  },
): {
  listing: Ref<Responses[T] | undefined>;
  status: Ref<"pending" | "error" | "success">;
  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'],
      label: {
        'properties.color': 'Color',
        'properties.size': 'Size',
        'properties.brand': 'Brand',
      },
    },
    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',
      },
    },
  }
)

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

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

    <!-- Sort Dropdown -->
    <select @change="sortResult(($event.target as HTMLSelectElement).value)">
      <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>
        <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.label }} ({{ option.count }})
        </label>
      </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, MaybeRef } from "vue";
import type {
  Listings,
  ListingParameters,
  Responses,
} from "@frontic/stack/generated-types";

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

// Typed sort for UI rendering
interface UiSort<TSorts = Record<string, unknown>> {
  key: (keyof TSorts & string) | "default";
  label: string;
  value: (keyof TSorts & string) | "default";
}

// 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;
    };
  };
}

function useFronticSearch<
  TSearch extends keyof Listings,
  TFilters extends Record<string, unknown>,
  TSorts extends Record<string, unknown>,
>(
  name: TSearch,
  params: MaybeRef<ListingParameters[TSearch]>,
  options?: {
    contextKey?: MaybeRef<string | undefined>;
    contextDomain?: MaybeRef<string | undefined>;
    requestUrl?: MaybeRef<string | undefined>;
    staleTime?: number;
    cacheKey?: string;
    searchTermThreshold?: number;
    searchDebounce?: number;
    orFilter?: Array<keyof TFilters & string>;
    disableSearch?: boolean;
    disableFilter?: boolean;
    disableSorting?: boolean;
    limit?: number;
    infinite?: boolean;
    initialPage?: number;
    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
    };
    sorting?: {
      select?: Array<keyof TSorts & string>;
      mode?: "include" | "exclude";
      label?: Record<string, string>;
      sort?: Array<keyof TSorts & string>; // Display order for sorts
    };
  },
): {
  result: Ref<Responses[TSearch] | undefined>; // Full listing response
  status: Ref<"pending" | "error" | "success">;
  state: Ref<SearchState<TFilters, TSorts>>; // Fully typed state
  searchTerm: Ref<string>;
  loadNext: () => Promise<void>;
  loadPrev: () => Promise<void>;
  loadPage: (page: number) => Promise<void>;
  refresh: () => Promise<void>;
  refetch: () => Promise<void>;
  sortResult: (sortBy?: string) => Promise<void>;
  resetSorting: () => Promise<void>;
  filterResult: <K extends keyof TFilters>(
    field: K,
    values: TFilters[K][],
  ) => Promise<void>;
  addFilter: <K extends keyof TFilters>(
    field: K,
    value: TFilters[K],
  ) => 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)
};

// Subtree rooted at a specific node
const { items } = useFronticTree("CategoryNavigation", { key: "shop" });

// Reactive starting key — refetches whenever the user expands a different branch
const expandedKey = ref<string | undefined>(undefined);
const { items } = useFronticTree("CategoryNavigation", {
  key: expandedKey,
  depth: 2,
});

// With custom cache duration
const { tree } = useFronticTree("CategoryNavigation", {
  staleTime: 1000 * 60 * 30, // 30 minutes
});

import type { Ref, ComputedRef, MaybeRef } from "vue";
import type { Trees, Responses } from "@frontic/stack/generated-types";

// Internal helper — extracts the typed `items` array from a tree response
type TreeItems<TResponse> = [TResponse] extends [{ items?: infer I }]
  ? (unknown extends I ? unknown[] : Exclude<I, undefined>)
  : unknown[];

function useFronticTree<T extends keyof Trees>(
  name: T,
  options?: {
    key?: MaybeRef<string | undefined>;
    depth?: MaybeRef<number | undefined>;
    contextKey?: MaybeRef<string | undefined>;
    contextDomain?: MaybeRef<string | undefined>;
    requestUrl?: MaybeRef<string | undefined>;
    staleTime?: number;
  },
): {
  tree: Ref<Responses[T] | undefined>;
  items: ComputedRef<TreeItems<Responses[T]> | undefined>;
  status: Ref<"pending" | "error" | "success">;
  refresh: () => Promise<void>;
  refetch: () => Promise<void>;
};

// With explicit slug
const { page } = useFronticPage("demo-shop.com/uk/products/shoes");

// Disable redirect for manual handling
const { page, route } = useFronticPage(undefined, { redirectOn301: false });

if (route.value?.redirect) {
  navigateTo(route.value.redirect.path);
}

// Disable 404 throwing for custom error handling
const { page, route } = useFronticPage(undefined, { throwOn404: false });

if (route.value?.code === 404) {
  // Custom 404 handling
}

import type { Ref, ComputedRef, MaybeRef } from "vue";

interface Page {
  id?: string;
  slug?: string;
  title?: string;
  meta?: Record<string, unknown>;
  data?: Record<string, unknown>;
  route?: PageRoute;
}

interface PageRoute {
  code?: number;
  redirect?: { path: string };
  alternates?: AlternateRoute[];
  context?: { suggested?: string };
}

interface AlternateRoute {
  locale?: string;
  lang?: string;
  href: string;
}

function useFronticPage(
  slug?: MaybeRef<string>,
  options?: {
    redirectOn301?: boolean;
    throwOn404?: boolean;
    contextKey?: MaybeRef<string | undefined>;
    contextDomain?: MaybeRef<string | undefined>;
    requestUrl?: MaybeRef<string | undefined>;
    staleTime?: number;
  },
): {
  page: Ref<Page | undefined>;
  data: ComputedRef<Page["data"] | undefined>;
  type: ComputedRef<string | undefined>;
  block: ComputedRef<string | undefined>;
  route: ComputedRef<PageRoute | undefined>;
  alternates: ComputedRef<AlternateRoute[] | undefined>;
  status: Ref<"pending" | "error" | "success">;
  refresh: () => Promise<void>;
  refetch: () => Promise<void>;
};