najm-kit 2.7.0 → 2.7.2

package/dist/query.d.ts

@@ -0,0 +1,299 @@
+import * as _tanstack_query_core from '@tanstack/query-core';
+import { d as OffsetPageFetcher, O as OffsetPage, L as ListStrategy, R as ResolvedListMode } from './pagination-BvukSZir.js';
+export { A as ApiPage, C as CardPaginationLabels, a as CardPaginationState, b as DEFAULT_MAX_PAGE_SIZE, c as DEFAULT_PAGE_SIZE, e as OffsetPageOptions, f as OffsetPagination, Q as QueryValue, g as buildCardPaginationLabels, h as cleanQuery, i as createCardPagination, j as createOffsetPagination, k as fetchOffsetPage, l as getPageIndex } from './pagination-BvukSZir.js';
+import './paginationLabels-CY2PvbMj.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,131 @@
+import { fetchOffsetPage, useCardViewport, DEFAULT_MAX_PAGE_SIZE } from './chunk-7J7DWGKB.mjs';
+export { DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE, buildCardPaginationLabels, cleanQuery, createCardPagination, createOffsetPagination, fetchOffsetPage, getPageIndex } from './chunk-7J7DWGKB.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.0",
+  "version": "2.7.2",
   "license": "MIT",
   "type": "module",
   "description": "Reusable React UI component package for Najm framework",
@@ -33,6 +33,11 @@
       "default": "./dist/adapters/app.mjs"
     },
     "./package.json": "./package.json",
+    "./query": {
+      "types": "./dist/query.d.ts",
+      "import": "./dist/query.mjs",
+      "default": "./dist/query.mjs"
+    },
     "./json": {
       "types": "./dist/json.d.ts",
       "import": "./dist/json.mjs",
@@ -60,6 +65,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 +82,9 @@
     "najm-i18n": {
       "optional": true
     },
+    "@tanstack/react-query": {
+      "optional": true
+    },
     "@uiw/react-codemirror": {
       "optional": true
     },
@@ -147,6 +156,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",

package/dist/chunk-IGUQGT3G.mjs

@@ -1,24 +0,0 @@
-import { createContext, useContext, useMemo } from 'react';
-import { jsx } from 'react/jsx-runtime';
-
-// src/components/branding/NBrandingContext.tsx
-var NBrandingContext = createContext(null);
-function useNBranding() {
-  return useContext(NBrandingContext);
-}
-function NBrandingProvider({
-  children,
-  appName,
-  logoExpanded,
-  logoCollapsed,
-  logoFallback,
-  logoHref
-}) {
-  const value = useMemo(
-    () => ({ appName, logoExpanded, logoCollapsed, logoFallback, logoHref }),
-    [appName, logoExpanded, logoCollapsed, logoFallback, logoHref]
-  );
-  return /* @__PURE__ */ jsx(NBrandingContext.Provider, { value, children });
-}
-
-export { NBrandingProvider, useNBranding };