@factorialco/f0-react 2.55.3 → 2.57.0

package/dist/f0.d.ts

@@ -1416,6 +1416,14 @@ export declare type BaseDataAdapter<R extends RecordType, Filters extends Filter
      * side-effects on reactive adapters (e.g. Apollo watchQuery).
      */
     exportFetchData?: (options: Options) => FetchReturn | Promise<FetchReturn>;
+    /**
+     * Optional id-relative capability: fetch the immediate neighbours of an
+     * item under the current filters/sortings/search, without loading pages.
+     * Enables detail-page prev/next on direct links / hard refresh, where the
+     * item may not be in any loaded page window. One-shot semantics: when an
+     * Observable is returned, only the first settled emission is consumed.
+     */
+    fetchItemNeighbors?: (options: ItemNeighborsFetchOptions<Filters, Options>) => ItemNeighborsResponse<R> | Promise<ItemNeighborsResponse<R>> | Observable<PromiseState<ItemNeighborsResponse<R>>>;
 };
 
 /**
@@ -3958,6 +3966,8 @@ export declare type DataSourceDefinition<R extends RecordType = RecordType, Filt
     }) => number | undefined;
 };
 
+export declare type DataSourceItemId = string | number | symbol;
+
 /**
  * Wrapper component that conditionally renders a `data-testid` attribute.
  *
@@ -11732,6 +11742,44 @@ declare type ItemDefinition = {
     avatar?: AvatarVariant;
 };
 
+/**
+ * Options for an id-relative neighbours fetch. Derived from the adapter's own
+ * fetch options, so extended adapters (e.g. OneDataCollection's, which add
+ * `navigationFilters`) carry their extra context automatically. Pagination is
+ * stripped: the request is relative to an item id, not to a page.
+ */
+export declare type ItemNeighborsFetchOptions<Filters extends FiltersDefinition, Options extends BaseFetchOptions<Filters> = BaseFetchOptions<Filters>> = Omit<Options, "pagination"> & {
+    /** Id of the reference item (as produced by the source's idProvider) */
+    id: ItemNeighborsId;
+};
+
+/**
+ * Identifier used to reference an item in id-relative fetches.
+ * Symbols are excluded on purpose: the id must be serializable so it can
+ * cross a network boundary to a backend.
+ */
+export declare type ItemNeighborsId = string | number;
+
+/**
+ * Result of an id-relative neighbours fetch.
+ *
+ * `previous`/`next` are the immediate neighbours of the reference item under
+ * the given filters/sortings/search, or null at the collection edges. If the
+ * reference item itself does not match the current filters, return
+ * `{ previous: null, next: null }` (optionally with `total`) — consumers
+ * disable navigation in that case.
+ */
+export declare type ItemNeighborsResponse<R> = {
+    previous: R | null;
+    next: R | null;
+    /** 1-indexed position of the reference item in the filtered+sorted collection */
+    position?: number;
+    /** Total number of records matching the current filters/search */
+    total?: number;
+};
+
+export declare type ItemNeighborsResult<R> = ItemNeighborsResponse<R> | Promise<ItemNeighborsResponse<R>> | Observable<PromiseState<ItemNeighborsResponse<R>>>;
+
 /**
  * Profile data for a job posting entity (ATS opening), resolved asynchronously
  * and displayed in the entity reference hover card.
@@ -12330,6 +12378,20 @@ declare type NavigationProps = {
 
 declare type NavTarget = HTMLAttributeAnchorTarget;
 
+export declare type NeighborResolution<R extends RecordType> = {
+    /** Index of the active item within the loaded records, or -1 when not found */
+    activeIndex: number;
+    activeItem: R | null;
+    previousItem: R | null;
+    nextItem: R | null;
+    /**
+     * How the neighbours were resolved. "window" means they were located in the
+     * loaded records. Reserved extension point for id-relative adapter
+     * resolution (e.g. a `fetchItemNeighbors` capability).
+     */
+    resolvedBy: "window";
+};
+
 /**
  * Utility type to extract all possible paths from nested object.
  * Generates hyphenated paths from nested object structure
@@ -12980,6 +13042,14 @@ export declare type PaginatedDataAdapter<R extends RecordType, Filters extends F
      * side-effects on reactive adapters (e.g. Apollo watchQuery).
      */
     exportFetchData?: (options: Options) => FetchReturn | Promise<FetchReturn>;
+    /**
+     * Optional id-relative capability: fetch the immediate neighbours of an
+     * item under the current filters/sortings/search, without loading pages.
+     * Enables detail-page prev/next on direct links / hard refresh, where the
+     * item may not be in any loaded page window. One-shot semantics: when an
+     * Observable is returned, only the first settled emission is consumed.
+     */
+    fetchItemNeighbors?: (options: ItemNeighborsFetchOptions<Filters, Options>) => ItemNeighborsResponse<R> | Promise<ItemNeighborsResponse<R>> | Observable<PromiseState<ItemNeighborsResponse<R>>>;
 };
 
 export declare type PaginatedFetchOptions<Filters extends FiltersDefinition> = BaseFetchOptions<Filters> & {
@@ -13785,6 +13855,34 @@ export declare interface ResolvedStepAnswer {
     cancelled?: boolean;
 }
 
+/**
+ * Normalizes the three `fetchItemNeighbors` return channels (sync value,
+ * Promise, Observable of PromiseState) into a single one-shot Promise.
+ *
+ * Observables are consumed one-shot: the first emission carrying `data`
+ * resolves, the first emission carrying `error` rejects, and the
+ * subscription is closed either way — live updates are intentionally out of
+ * scope for neighbour resolution.
+ *
+ * `cancel()` unsubscribes/abandons the request: the returned promise then
+ * never settles, so a cancelled request can never reach consumer state.
+ */
+export declare function resolveItemNeighbors<R>(result: ItemNeighborsResult<R>): {
+    promise: Promise<ItemNeighborsResponse<R>>;
+    cancel: () => void;
+};
+
+/**
+ * Locates the active item and its immediate neighbours within the currently
+ * loaded records ("the window"). Pure — the single place neighbour resolution
+ * happens, so alternative resolution strategies can be merged at this point.
+ */
+export declare function resolveWindowNeighbors<R extends RecordType>({ records, activeItemId, idProvider, }: {
+    records: readonly R[];
+    activeItemId: DataSourceItemId | null;
+    idProvider: (item: R, index?: number) => DataSourceItemId;
+}): NeighborResolution<R>;
+
 declare type ResourceHeaderProps = Props_4;
 
 /** All styling props that can be overridden per breakpoint */
@@ -15361,13 +15459,21 @@ declare type UseChatHistoryReturn = {
  * - paginationInfo: Pagination state and metadata if available
  * - setPage: Function to navigate to a specific page
  */
-export declare function useData<R extends RecordType = RecordType, Filters extends FiltersDefinition = FiltersDefinition, Sortings extends SortingsDefinition = SortingsDefinition, Grouping extends GroupingDefinition<R> = GroupingDefinition<R>>(source: DataSource<R, Filters, Sortings, Grouping>, { filters, onError, fetchParamsProvider, onResponse, }?: UseDataOptions<R, Filters>, deps?: unknown[]): UseDataReturn<R>;
+export declare function useData<R extends RecordType = RecordType, Filters extends FiltersDefinition = FiltersDefinition, Sortings extends SortingsDefinition = SortingsDefinition, Grouping extends GroupingDefinition<R> = GroupingDefinition<R>>(source: DataSource<R, Filters, Sortings, Grouping>, { filters, enabled, onError, fetchParamsProvider, onResponse, }?: UseDataOptions<R, Filters>, deps?: unknown[]): UseDataReturn<R>;
 
 /**
  * Hook options for useData
  */
 export declare interface UseDataOptions<R extends RecordType, Filters extends FiltersDefinition> {
     filters?: Partial<FiltersState<Filters>>;
+    /**
+     * When false, suspends all data fetching: the initial fetch effect does not
+     * run until `enabled` becomes true. Useful to delay the first fetch until
+     * async state (e.g. persisted filters) has been applied to the source.
+     * `isInitialLoading` stays true while disabled.
+     * @default true
+     */
+    enabled?: boolean;
     /**
      * A function that is called when an error occurs during data fetching.
      * It is called with the error object.
@@ -15443,6 +15549,72 @@ export declare interface UseDataReturn<R extends RecordType> {
  */
 export declare function useDataSource<R extends RecordType = RecordType, FiltersSchema extends FiltersDefinition = FiltersDefinition, Sortings extends SortingsDefinition = SortingsDefinition, Grouping extends GroupingDefinition<R> = GroupingDefinition<R>>({ defaultFilters, currentFilters: externalCurrentFilters, defaultGrouping: externalDefaultGrouping, currentGrouping: externalCurrentGrouping, filters, search, defaultSortings, currentSortings: externalCurrentSortings, dataAdapter, grouping, ...rest }: DataSourceDefinition<R, FiltersSchema, Sortings, Grouping>, deps?: ReadonlyArray<unknown>): DataSource<R, FiltersSchema, Sortings, Grouping>;
 
+export declare function useDataSourceItemNavigation<R extends RecordType>(props: UseDataSourceItemNavigationProps<R>): UseDataSourceItemNavigationReturn<R>;
+
+export declare interface UseDataSourceItemNavigationProps<R extends RecordType> {
+    /** The data source returned by `useDataSource`. Used to extract `idProvider` */
+    dataSource: {
+        idProvider?: <Item extends R>(item: Item, index?: number) => DataSourceItemId;
+    };
+    /** The data returned by `useData` */
+    data: Data<R>;
+    /** Pagination info returned by `useData` */
+    paginationInfo: PaginationInfo | null;
+    /** Navigate to a specific page (from `useData`) */
+    setPage: UseDataReturn<R>["setPage"];
+    /** Load more items for infinite-scroll (from `useData`) */
+    loadMore: UseDataReturn<R>["loadMore"];
+    /** Whether `useData` is currently loading data */
+    isLoading: boolean;
+    /** Overrides `dataSource.idProvider`. Extracts a unique ID from a record. Falls back to `item.id` */
+    idProvider?: (item: R, index?: number) => DataSourceItemId;
+    /** Returns the URL for a given item. Used to derive `nextItemUrl` / `previousItemUrl` */
+    itemUrl?: (item: R) => string | undefined;
+    /** Controlled active item ID */
+    activeItemId?: DataSourceItemId | null;
+    /** Default active item ID (uncontrolled) */
+    defaultActiveItemId?: DataSourceItemId | null;
+    /** Callback when active item changes */
+    onActiveItemChange?: (id: DataSourceItemId | null) => void;
+}
+
+export declare interface UseDataSourceItemNavigationReturn<R extends RecordType> {
+    /** The currently active item ID */
+    activeItemId: DataSourceItemId | null;
+    /** The currently active item record, or null if not found in loaded data */
+    activeItem: R | null;
+    /** The active item index within the currently loaded records */
+    activeIndex: number;
+    /** The active item index within the full collection when it can be inferred */
+    absoluteIndex: number | null;
+    /** Number of records currently loaded into the datasource */
+    loadedItemsCount: number;
+    /** Total number of matching records when pagination exposes it */
+    totalItems: number | undefined;
+    /** The previous loaded item record, or null if unavailable */
+    previousItem: R | null;
+    /** The next loaded item record, or null if unavailable */
+    nextItem: R | null;
+    /** URL of the active item (derived via `itemUrl`), or null if unavailable */
+    activeItemUrl: string | null;
+    /** Navigate to the next item. Fetches next page if at boundary */
+    goToNext: () => void;
+    /** Navigate to the previous item. Fetches previous page if at boundary */
+    goToPrevious: () => void;
+    /** Whether there is a next item (or more pages to load) */
+    hasNext: boolean;
+    /** Whether there is a previous item (or previous pages to load) */
+    hasPrevious: boolean;
+    /** Directly set the active item ID */
+    setActiveItemId: (id: DataSourceItemId | null) => void;
+    /** True while waiting for a page transition to resolve the pending navigation */
+    isNavigating: boolean;
+    /** URL of the next loaded item (derived via `itemUrl`), or null if unavailable */
+    nextItemUrl: string | null;
+    /** URL of the previous loaded item (derived via `itemUrl`), or null if unavailable */
+    previousItemUrl: string | null;
+}
+
 export declare function useDndEvents(handler: (e: {
     phase: "start" | "over" | "drop" | "cancel";
     source: DragPayload;
@@ -15693,6 +15865,56 @@ export declare const useGroups: <R extends RecordType>(groups: GroupRecord<R>[],
     setGroupOpen: (key: string, open: boolean) => void;
 };
 
+/**
+ * Resolves the previous/next neighbours of an item through the adapter's
+ * optional id-relative `fetchItemNeighbors` capability.
+ *
+ * Built for detail-page navigation on direct links: when the active item is
+ * not in any loaded page window, this asks the backend for its immediate
+ * neighbours (plus position/total for the counter) under the current
+ * filters/sortings/search instead of walking pages.
+ *
+ * Semantics:
+ * - `neighbors` only ever reflects the current `{id, filters, sortings,
+ *   search}` — stale responses from superseded requests are dropped.
+ * - Responses are cached per request key, so navigating back and forth
+ *   between already-visited ids is instant. The cache is cleared whenever
+ *   filters/sortings/search change; errors are never cached.
+ * - When the capability is absent (`isSupported: false`), disabled, or the
+ *   id is null, nothing is fetched and `neighbors` stays null — consumers
+ *   keep their fallback behaviour.
+ */
+export declare function useItemNeighbors<R extends RecordType, Filters extends FiltersDefinition>({ dataAdapter, id, filters, sortings, search, enabled, onError, }: UseItemNeighborsOptions<R, Filters>): UseItemNeighborsReturn<R>;
+
+export declare interface UseItemNeighborsOptions<R extends RecordType, Filters extends FiltersDefinition> {
+    /** The adapter that may implement the `fetchItemNeighbors` capability */
+    dataAdapter: DataAdapter<R, Filters>;
+    /** Active item id. Null disables resolution (symbol ids cannot be used) */
+    id: ItemNeighborsId | null;
+    /** Current filters — same values `fetchData` receives */
+    filters: FiltersState<Filters>;
+    /** Current sortings — same composed array `fetchData` receives */
+    sortings: SortingsStateMultiple;
+    /** Current search — same value `fetchData` receives */
+    search?: string;
+    /**
+     * Gate: resolve only while true (e.g. only when the snapshot path failed
+     * to locate the item in the loaded window).
+     * @default true
+     */
+    enabled?: boolean;
+    onError?: (error: DataError) => void;
+}
+
+export declare interface UseItemNeighborsReturn<R extends RecordType> {
+    /** True when the adapter implements `fetchItemNeighbors` */
+    isSupported: boolean;
+    /** Resolved neighbours for the CURRENT id+context, or null while unresolved */
+    neighbors: ItemNeighborsResponse<R> | null;
+    isResolving: boolean;
+    error: DataError | null;
+}
+
 export declare const usePrivacyMode: () => {
     enabled: boolean;
     enable: () => void;