najm-kit 2.7.1 → 2.7.3

package/dist/paginationLabels-DgHutNWz.d.ts

@@ -0,0 +1,143 @@
+import { ReactNode } from 'react';
+
+/**
+ * How the page controls present position within the result.
+ *
+ * `numbered` renders a windowed list of page buttons. `compact` renders the
+ * `Page X of Y` text with first/previous/next/last controls.
+ *
+ * `numbered` needs a trustworthy page count. Under `manualPagination` that
+ * means the application must pass a `pageCount` derived from a real result
+ * total, or — when its endpoint reports no total — pass `hasNextPage` and no
+ * `pageCount` at all, which renders the unbounded bar described on the NTable
+ * prop. With neither, the bar falls back to `compact` on its own rather than
+ * inviting clicks on pages that may not exist.
+ *
+ * What it must never be handed is a `pageCount` that is really a lower bound,
+ * such as `pageIndex + 2`. That reads as a two-page result on page one and a
+ * three-page result on page two, so the bar grows a number per click with
+ * nothing to say why. NTable warns in development when it catches a count
+ * moving in lockstep with the page index.
+ */
+type NTablePaginationVariant = "numbered" | "compact";
+/**
+ * Accessible names and visible copy for the page controls.
+ *
+ * Every field is optional and falls back to English. Supply them to localize —
+ * the numbered variant is mostly digits, but its controls still need names.
+ */
+interface NTablePaginationLabels {
+    /** Labels the rows-per-page select. Defaults to `"Rows/page"`. */
+    rowsPerPage?: string;
+    /** Accessible name of the whole page control group. Defaults to `"Pagination"`. */
+    pagination?: string;
+    /** Accessible name for one page button, given a 1-based page. */
+    goToPage?: (page: number) => string;
+    /** Accessible name of the current page button, given a 1-based page. */
+    currentPage?: (page: number) => string;
+    firstPage?: string;
+    previousPage?: string;
+    nextPage?: string;
+    lastPage?: string;
+    /** The `compact` variant's position text, given 1-based values. */
+    pageOf?: (page: number, pageCount: number) => string;
+    /**
+     * The position text when the result has no known total, given the 1-based
+     * page. Defaults to `"Page X"` — there is no `of Y` to state, and repeating
+     * the moving lower bound there would be the same lie the numbered bar avoids.
+     */
+    pageOfUnknown?: (page: number) => string;
+    /** The selection summary, given selected and total row counts. */
+    rowsSelected?: (selected: number, total: number) => string;
+}
+interface NTableLoadMorePagination {
+    /** Render the supplied rows as one card list with an explicit continuation control. */
+    mode: "load-more";
+    /** Whether the owning application has another server page available. */
+    hasNextPage: boolean;
+    /** True while the owning application is appending the next page. */
+    loadingMore?: boolean;
+    /** A controlled append error. Existing rows remain rendered and the control becomes Retry. */
+    loadMoreError?: ReactNode;
+    /** Fetch exactly one additional page. Najm Kit never constructs or owns the request. */
+    onLoadMore: () => unknown | Promise<unknown>;
+    loadMoreLabel?: string;
+    loadingMoreLabel?: string;
+    retryLabel?: string;
+    endLabel?: string;
+    loadMoreErrorLabel?: string;
+    /** Localize the polite announcement made after appended rows arrive. */
+    itemsLoadedLabel?: (count: number) => string;
+}
+interface NTableInfinitePagination {
+    /**
+     * Render the supplied rows as one card list that continues automatically when
+     * the end of the list scrolls into view. No control and no end-of-list
+     * element are rendered while the list is healthy; the continuation button
+     * appears only after an append failure, as the retry target.
+     */
+    mode: "infinite";
+    /** Whether the owning application has another server page available. */
+    hasNextPage: boolean;
+    /** True while the owning application is appending the next page. */
+    loadingMore?: boolean;
+    /** A controlled append error. Existing rows remain rendered and Retry appears. */
+    loadMoreError?: ReactNode;
+    /** Fetch exactly one additional page. Najm Kit never constructs or owns the request. */
+    onLoadMore: () => unknown | Promise<unknown>;
+    /**
+     * Distance ahead of the list end at which the next page is requested.
+     * Defaults to `"80px"`.
+     */
+    rootMargin?: string;
+    loadingMoreLabel?: string;
+    retryLabel?: string;
+    loadMoreErrorLabel?: string;
+    /** Localize the polite announcement made after appended rows arrive. */
+    itemsLoadedLabel?: (count: number) => string;
+}
+/**
+ * Presentation policy used while NTable is actually rendering cards.
+ *
+ * `paged` preserves the existing page controls. `all` renders every supplied
+ * row without a footer, in card and table modes alike. `load-more` renders
+ * every supplied row and adds a guarded, accessible continuation control.
+ * `infinite` renders every supplied row and continues on scroll instead.
+ *
+ * Applications remain responsible for fetching, accumulating, filtering,
+ * sorting, authorization, and privacy. `all` renders exactly the rows it is
+ * given and never fetches, so a caller that has not loaded the whole set must
+ * not select it.
+ */
+type NTableCardPagination = {
+    mode?: "paged";
+} | {
+    mode: "all";
+} | NTableLoadMorePagination | NTableInfinitePagination;
+
+/**
+ * The translator shape `NajmUIProvider` accepts.
+ *
+ * Deliberately structural rather than an import from `najm-i18n`: the kit
+ * depends on no `najm-*` package, and this signature is satisfied by every
+ * mainstream i18n library. The application keeps its catalog and its own
+ * language provider.
+ */
+type NajmTranslate = (key: string, params?: Record<string, string | number>) => string;
+declare const DEFAULT_PAGINATION_KEY_PREFIX = "common.pagination";
+/**
+ * Projects a translator onto the ten pagination labels.
+ *
+ * Keys are `<prefix>.<field>`, matching the `NTablePaginationLabels` field
+ * names one-for-one, so a catalog is readable next to the type. Interpolation
+ * params are named for what they are: `page`, `pageCount`, `selected`, `total`.
+ *
+ * No result is inspected or second-guessed. A translator that echoes missing
+ * keys will render those keys — that is the translator's contract to define,
+ * and quietly swapping in English would hide the missing entry rather than
+ * surface it. Applications that want the packaged English for a given label
+ * should omit the key from the prefix and override it via `tableDefaults`.
+ */
+declare function buildPaginationLabels(t: NajmTranslate, prefix?: string): NTablePaginationLabels;
+
+export { DEFAULT_PAGINATION_KEY_PREFIX as D, type NajmTranslate as N, type NTableCardPagination as a, type NTablePaginationLabels as b, type NTablePaginationVariant as c, type NTableInfinitePagination as d, type NTableLoadMorePagination as e, buildPaginationLabels as f };

package/dist/query.d.ts

@@ -0,0 +1,301 @@
+import * as _tanstack_query_core from '@tanstack/query-core';
+import { OffsetPageFetcher, OffsetPage } from './pagination.js';
+export { ApiPage, DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE, OffsetPageOptions, OffsetPagination, QueryValue, cleanQuery, createOffsetPagination, fetchOffsetPage, getPageIndex } from './pagination.js';
+import { L as ListStrategy, R as ResolvedListMode } from './cardPagination-A6h8vXuk.js';
+export { C as CardPaginationLabels, a as CardPaginationState, b as buildCardPaginationLabels, c as createCardPagination } from './cardPagination-A6h8vXuk.js';
+import './paginationLabels-DgHutNWz.js';
+import 'react';
+
+interface UseOffsetInfiniteQueryOptions<T> {
+    enabled?: boolean;
+    fetchPage: OffsetPageFetcher<T>;
+    queryKey: readonly unknown[];
+    /**
+     * The size of one *server request*, not of a displayed page.
+     *
+     * Deliberately decoupled: the display page size is measured from the rendered
+     * container and moves as the viewport, column count and card height settle.
+     * Tying a request to it would put a network round trip behind every
+     * measurement correction, and a second skeleton behind each round trip.
+     */
+    windowSize?: number;
+    /** The server's `limit` clamp. Defaults to `DEFAULT_MAX_PAGE_SIZE`. */
+    maxLimit?: number;
+}
+declare const DEFAULT_ROW_WINDOW_SIZE = 50;
+/**
+ * An accumulating row buffer over `fetchOffsetPage`.
+ *
+ * Every mode of `useResponsiveOffsetList` reads from one of these — numbered
+ * pages are a slice of the buffer rather than a request of their own.
+ */
+declare function useOffsetInfiniteQuery<T>({ enabled, fetchPage, queryKey, windowSize, maxLimit, }: UseOffsetInfiniteQueryOptions<T>): {
+    rows: T[];
+    hasNextPage: boolean;
+    total: number;
+    data: _tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_query_core.FetchPreviousPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    hasPreviousPage: boolean;
+    isFetchNextPageError: boolean;
+    isFetchingNextPage: boolean;
+    isFetchPreviousPageError: boolean;
+    isFetchingPreviousPage: boolean;
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>>;
+} | {
+    rows: T[];
+    hasNextPage: boolean;
+    total: number;
+    data: _tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_query_core.FetchPreviousPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>>;
+} | {
+    rows: T[];
+    hasNextPage: boolean;
+    total: number;
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_query_core.FetchPreviousPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>>;
+} | {
+    rows: T[];
+    hasNextPage: boolean;
+    total: number;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_query_core.FetchPreviousPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>>;
+} | {
+    rows: T[];
+    hasNextPage: boolean;
+    total: number;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_query_core.FetchPreviousPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>>;
+} | {
+    rows: T[];
+    hasNextPage: boolean;
+    total: number;
+    data: _tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    status: "success";
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_query_core.FetchPreviousPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    fetchStatus: _tanstack_query_core.FetchStatus;
+    promise: Promise<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>>;
+};
+
+interface PaginationState {
+    pageIndex: number;
+    pageSize: number;
+}
+type PaginationUpdater = PaginationState | ((current: PaginationState) => PaginationState);
+interface UseResponsiveOffsetListOptions<T> {
+    enabled?: boolean;
+    fetchPage: OffsetPageFetcher<T>;
+    pageSize?: number;
+    queryKey: readonly unknown[];
+    /** Defaults to `"paged"`. See `ListStrategy`. */
+    strategy?: ListStrategy;
+    /** The server's `limit` clamp. Defaults to `DEFAULT_MAX_PAGE_SIZE`. */
+    maxLimit?: number;
+    /** Below this width the list continues on scroll. Defaults to `lg`. */
+    cardBreakpoint?: number;
+}
+/**
+ * One offset-paginated list, in whichever presentation the viewport calls for.
+ *
+ * Feeds `NTable` directly: the return value carries `pagination`,
+ * `onPaginationChange` and `pageCount` for the page controls, and the fields
+ * `createCardPagination` reads for scroll continuation.
+ */
+declare function useResponsiveOffsetList<T>({ enabled, fetchPage, pageSize, queryKey, strategy, maxLimit, cardBreakpoint, }: UseResponsiveOffsetListOptions<T>): {
+    cardViewport: boolean;
+    mode: ResolvedListMode;
+    data: T[];
+    /** Rows matching the current filters on the server, or `null` if unknown. */
+    total: number;
+    error: Error;
+    hasNextPage: boolean;
+    loading: boolean;
+    loadingMore: boolean;
+    loadMoreError: Error;
+    onLoadMore: () => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+    onPaginationChange: (updater: PaginationUpdater) => void;
+    pageCount: number;
+    pagination: {
+        pageIndex: number;
+        pageSize: number;
+    };
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<OffsetPage<T>, unknown>, Error>>;
+};
+
+export { DEFAULT_ROW_WINDOW_SIZE, ListStrategy, OffsetPage, OffsetPageFetcher, ResolvedListMode, type UseOffsetInfiniteQueryOptions, type UseResponsiveOffsetListOptions, useOffsetInfiniteQuery, useResponsiveOffsetList };

package/dist/query.mjs

@@ -0,0 +1,133 @@
+import { useCardViewport } from './chunk-XGDMPI5U.mjs';
+export { buildCardPaginationLabels, createCardPagination } from './chunk-XGDMPI5U.mjs';
+import { fetchOffsetPage, DEFAULT_MAX_PAGE_SIZE } from './chunk-2NX2VKS2.mjs';
+export { DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE, cleanQuery, createOffsetPagination, fetchOffsetPage, getPageIndex } from './chunk-2NX2VKS2.mjs';
+import { useInfiniteQuery } from '@tanstack/react-query';
+import { useState, useRef, useEffect, useCallback } from 'react';
+
+var DEFAULT_ROW_WINDOW_SIZE = 50;
+function useOffsetInfiniteQuery({
+  enabled = true,
+  fetchPage,
+  queryKey,
+  windowSize = DEFAULT_ROW_WINDOW_SIZE,
+  maxLimit
+}) {
+  const query = useInfiniteQuery({
+    enabled,
+    initialPageParam: 0,
+    queryKey: [...queryKey, "buffer", windowSize],
+    queryFn: ({ pageParam }) => fetchOffsetPage(
+      fetchPage,
+      { limit: windowSize, offset: Number(pageParam) },
+      { maxLimit }
+    ),
+    getNextPageParam: (lastPage) => lastPage.hasNextPage ? lastPage.nextOffset : void 0
+  });
+  const pages = query.data?.pages;
+  return {
+    ...query,
+    rows: pages?.flatMap((page) => page.rows) ?? [],
+    hasNextPage: Boolean(query.hasNextPage),
+    // The newest window carries the freshest count. Reading the first page
+    // instead would keep reporting a total from before the latest mutation.
+    total: pages?.[pages.length - 1]?.total ?? null
+  };
+}
+function useResponsiveOffsetList({
+  enabled = true,
+  fetchPage,
+  pageSize = 25,
+  queryKey,
+  strategy = "paged",
+  maxLimit = DEFAULT_MAX_PAGE_SIZE,
+  cardBreakpoint
+}) {
+  const cardViewport = useCardViewport(cardBreakpoint);
+  const queryIdentity = JSON.stringify(queryKey);
+  const [paginationState, setPagination] = useState({
+    pageIndex: 0,
+    pageSize,
+    queryIdentity
+  });
+  const pagination = paginationState.queryIdentity === queryIdentity ? paginationState : { ...paginationState, pageIndex: 0};
+  const wantsAll = strategy === "all";
+  const wantsInfinite = strategy === "infinite" || strategy === "paged" && cardViewport;
+  const buffer = useOffsetInfiniteQuery({
+    enabled,
+    fetchPage,
+    queryKey,
+    maxLimit,
+    windowSize: wantsAll ? maxLimit : DEFAULT_ROW_WINDOW_SIZE
+  });
+  const rows = buffer.rows;
+  const allDowngraded = wantsAll && buffer.hasNextPage;
+  const warnedRef = useRef(false);
+  useEffect(() => {
+    if (!allDowngraded || warnedRef.current) return;
+    warnedRef.current = true;
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        `[najm-kit] List ${queryIdentity} requested strategy "all" but filled the ${maxLimit}-row ceiling, so its bound is not real. Falling back to infinite continuation; give this list a paged or infinite strategy.`
+      );
+    }
+  }, [allDowngraded, queryIdentity, maxLimit]);
+  const mode = wantsAll && !allDowngraded ? "all" : wantsInfinite || allDowngraded ? "infinite" : "paged";
+  const start = pagination.pageIndex * pagination.pageSize;
+  const data = mode === "paged" ? rows.slice(start, start + pagination.pageSize) : rows;
+  const { fetchNextPage, hasNextPage, isFetchingNextPage } = buffer;
+  useEffect(() => {
+    if (mode !== "paged") return;
+    if (!hasNextPage || isFetchingNextPage) return;
+    if (rows.length >= start + pagination.pageSize * 2) return;
+    void fetchNextPage();
+  }, [
+    mode,
+    hasNextPage,
+    isFetchingNextPage,
+    rows.length,
+    start,
+    pagination.pageSize,
+    fetchNextPage
+  ]);
+  const onPaginationChange = useCallback(
+    (updater) => {
+      setPagination((current) => ({
+        ...typeof updater === "function" ? updater(
+          current.queryIdentity === queryIdentity ? { pageIndex: current.pageIndex, pageSize: current.pageSize } : { pageIndex: 0, pageSize: current.pageSize }
+        ) : updater,
+        queryIdentity
+      }));
+    },
+    [queryIdentity]
+  );
+  const bufferedPages = Math.max(
+    1,
+    Math.ceil(rows.length / pagination.pageSize)
+  );
+  const pageCount = buffer.total !== null ? Math.max(1, Math.ceil(buffer.total / pagination.pageSize)) : buffer.hasNextPage ? bufferedPages + 1 : bufferedPages;
+  return {
+    cardViewport,
+    mode,
+    data,
+    /** Rows matching the current filters on the server, or `null` if unknown. */
+    total: buffer.total,
+    error: buffer.error,
+    hasNextPage: mode === "infinite" && buffer.hasNextPage,
+    // A background window extension is not a load. Paged readers keep the rows
+    // they are looking at; only having nothing at all is a loading state.
+    loading: buffer.isPending,
+    loadingMore: mode === "infinite" && buffer.isFetchingNextPage,
+    loadMoreError: buffer.isFetchNextPageError ? buffer.error : null,
+    onLoadMore: () => buffer.fetchNextPage(),
+    onPaginationChange,
+    pageCount,
+    pagination: {
+      pageIndex: pagination.pageIndex,
+      pageSize: pagination.pageSize
+    },
+    refetch: buffer.refetch
+  };
+}
+
+export { DEFAULT_ROW_WINDOW_SIZE, useOffsetInfiniteQuery, useResponsiveOffsetList };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-kit",
-  "version": "2.7.1",
+  "version": "2.7.3",
   "license": "MIT",
   "type": "module",
   "description": "Reusable React UI component package for Najm framework",
@@ -33,6 +33,21 @@
       "default": "./dist/adapters/app.mjs"
     },
     "./package.json": "./package.json",
+    "./query": {
+      "types": "./dist/query.d.ts",
+      "import": "./dist/query.mjs",
+      "default": "./dist/query.mjs"
+    },
+    "./format": {
+      "types": "./dist/format.d.ts",
+      "import": "./dist/format.mjs",
+      "default": "./dist/format.mjs"
+    },
+    "./pagination": {
+      "types": "./dist/pagination.d.ts",
+      "import": "./dist/pagination.mjs",
+      "default": "./dist/pagination.mjs"
+    },
     "./json": {
       "types": "./dist/json.d.ts",
       "import": "./dist/json.mjs",
@@ -60,6 +75,7 @@
     "zod": ">=4",
     "next": ">=14",
     "najm-i18n": ">=2",
+    "@tanstack/react-query": "^5",
     "@uiw/react-codemirror": "^4.25.0",
     "@codemirror/state": "^6.6.0",
     "@codemirror/view": "^6.42.0",
@@ -76,6 +92,9 @@
     "najm-i18n": {
       "optional": true
     },
+    "@tanstack/react-query": {
+      "optional": true
+    },
     "@uiw/react-codemirror": {
       "optional": true
     },
@@ -147,6 +166,7 @@
     "@hookform/resolvers": "^5",
     "@lezer/highlight": "^1.2.0",
     "@tailwindcss/postcss": "^4",
+    "@tanstack/react-query": "^5",
     "@testing-library/react": "^16",
     "@testing-library/user-event": "^14.6.1",
     "@types/culori": "^4.0.1",