@factorialco/f0-react 2.55.2 → 2.56.0

package/dist/f0.d.ts

@@ -3958,6 +3958,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.
  *
@@ -12330,6 +12332,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
@@ -13785,6 +13801,17 @@ export declare interface ResolvedStepAnswer {
     cancelled?: boolean;
 }
 
+/**
+ * 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 +15388,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 +15478,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;
@@ -16144,6 +16245,11 @@ declare module "gridstack" {
 }
 
 
+declare namespace Calendar {
+    var displayName: string;
+}
+
+
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         aiBlock: {
@@ -16193,11 +16299,6 @@ declare module "@tiptap/core" {
 }
 
 
-declare namespace Calendar {
-    var displayName: string;
-}
-
-
 declare namespace F0GraphNodeWrapperInner {
     var displayName: string;
 }