@everysk/apps-sdk 0.2.0 → 0.3.0-beta-20261016180126

package/README.md

@@ -63,7 +63,7 @@ to nested JSX in the right slot.
 | `theme` | A MUI theme. Omitted, the app mounts the Everysk dark theme |
 | `queryClient` | Defaults to a fresh `createQueryClient()`, created once per mount |
 | `appId`, `appEnvironmentVar` | Override `window.APP_ID` / `window.APP_CONFIG`, for tests and hosts that resolve configuration themselves |
-| `providers` | Optional providers, mounted inside the core tree |
+| `providers` | Optional providers, mounted inside the core tree. One configured by props goes in through `withProps(Provider, props)` |
 
 ## What it exports
 
@@ -83,10 +83,57 @@ a list rendered.
 | File | `useFetchFile` | `useFetchFiles` | `useFileMutations` |
 | Workspace | `useFetchWorkspace` | `useFetchWorkspaces` | — |
 | Profile | `useFetchProfile` | — | — |
-| Workflow | `useFetchWorkflow` | `useFetchWorkflows` | `useRunWorkflow` |
+| Workflow | `useFetchWorkflow` | `useFetchWorkflows` | `useTriggerWorkflow`, `useRunWorkflow` |
 
 Workflow carries four more for the run side: `useFetchWorkflowExecution(s)` and
-`useFetchWorkerExecution(s)`.
+`useFetchWorkerExecution(s)`. `useFetchWorkflowExecutions` pages by cursor and takes the
+endpoint's own filters, `workerId` and `withResume`, not a `filters` list.
+`useFetchWorkerExecutions` is not paginated: the API returns every worker of one execution at
+once, grouped by worker, so it returns `{ data, …, queryKey }` like a single-entity hook. Narrow
+each group on `is_parallel_execution`: a worker that ran in parallel carries `executions`, any
+other one `execution`.
+
+`useFetchWorkflows` and `useFetchWorkspaces` take a text `search` rather than filters: their
+endpoints search by name prefix (and, for workflows, by `#tag` or id). `useFetchWorkflows`
+requires a `workspace`, like every other hook — without one the API would read `main`.
+`useFetchWorkspaces` takes none: it lists the account's workspaces.
+
+A file's content comes as base64 in `data`, a third larger than the file, so `useFetchFile` and
+`useFetchFiles` leave it out unless `withData: true` asks for it (the list through the projection
+`-data`, added to a `projection` of the app's own that only excludes fields; one that includes
+fields is sent as given, and the content is still removed). To
+show or download a file, use its `url` (`/file/<hash>`) in an `<iframe>`, an `<img>` or an
+`<a href download>`: the platform serves it inline with the user's permissions, and the
+`@everysk/apps-devkit` dev server and `vite preview` serve it too. Do not build a `blob:` URL
+from the content: the app page's CSP blocks `blob:` frames, images and media. To upload,
+`fileToBase64(file)` turns a `File` from an `<input type="file">` into the raw base64
+`createFile` and `updateFile` take, and which they insist on: a data URL is refused, since the
+API would store its prefix as part of the file. `base64ToBlob(data, contentType)` decodes one, to
+work on the bytes in code (a CSV, a zip); given a file read without its content, it warns and
+gives an empty blob. An app uploads
+in one JSON request: the app's `/api` reads no multipart body.
+
+```tsx
+const { data: file } = useFetchFile({ id, workspace });
+
+return file ? <iframe src={file.url} title={file.name} /> : null;
+```
+
+`useTriggerWorkflow` starts a run and resolves with the started `WorkflowExecution`; it needs no
+websocket. `useRunWorkflow` starts one and waits for it to end **over the websocket**,
+resolving with `{ execution, workerExecution, result }`, so it needs `WebSocketProvider` (from
+`@everysk/apps-sdk/socket`) in `EveryskApp`'s `providers`, and throws on render without it.
+
+The backend announces each worker and the run's end on the app's channel; the end itself is
+then read from the API, and the Ender's output with it. Because those events are not replayed,
+it also reads the execution after a minute without any event of the run
+(`waitOptions.silenceMs`) and whenever the socket reconnects, and gives up after five minutes
+(`waitOptions.timeoutMs`). It fails when the socket stays unavailable for 30 seconds
+(`waitOptions.unavailableAfterMs`), since the end cannot be followed without it, and does not
+start the run before the socket is connected. Leaving the
+screen, or aborting `waitOptions.signal`, stops it without an error alert; the mutation then fails
+with a `WorkflowRunAbortedError`, so `error instanceof WorkflowRunAbortedError` tells a stop from
+a failure.
 
 ```tsx
 const { query, queryKey } = useFetchPortfolios({
@@ -103,6 +150,197 @@ directly, so `const { data, isLoading, queryKey } = useFetchPortfolio({ id, work
 Mutations return `{ create, update, remove }`, each a React Query mutation that shows an alert on
 success and failure through `useAppAlert`.
 
+#### Using a list hook without wrapping it
+
+The six list hooks (`useFetchDatastores`, `useFetchFiles`, `useFetchPortfolios`,
+`useFetchWorkflows`, `useFetchWorkflowExecutions`, `useFetchWorkspaces`) share one set of props, meant to cover what apps used to write a hook of
+their own for:
+
+| Prop | Default | |
+|---|---|---|
+| `select` | — | Shapes the merged list: `query.data` is what it returns. Applied after the pages are merged |
+| `fetchAllPages` | `false` | Reads to the last page before reporting success |
+| `pageSize` | `10` | Items per request |
+| `queryOptions` | — | Passed through to `useInfiniteQuery`, except `select`, which is the prop above |
+
+```tsx
+// Module scope, so the reference is stable: TanStack reruns a select whose reference changes.
+const toRows = (datastores: ParsedDatastore[]) =>
+  datastores.filter(isTableDatastore).flatMap((datastore) => datastore.data);
+
+const { query, queryKey } = useFetchDatastores({
+  filters: [{ field: "workspace", value: workspace }],
+  select: toRows, // query.data: AnyRecord[]
+});
+```
+
+- **`select` shapes what one caller sees; the cache keeps the pages.** Write to it with the
+  returned `queryKey` and the hook's cache type (`DatastoresCache`, `FilesCache`, …), and every
+  `select` reruns on the new data:
+
+  ```ts
+  queryClient.setQueryData<DatastoresCache>(queryKey, (cache) => cache && {
+    ...cache,
+    pages: cache.pages.map((page) => ({
+      ...page,
+      datastores: page.datastores.map((datastore) =>
+        isTableDatastore(datastore)
+          ? { ...datastore, data: datastore.data.map((row) => (row.UID === uid ? { ...row, ...patch } : row)) }
+          : datastore,
+      ),
+    })),
+  });
+  ```
+
+- **`fetchAllPages` is for a view that consolidates the whole set**, where a partial read is a
+  wrong answer rather than a shorter one. Without it the hook reads one page and stops, which a
+  screen that never asks for more shows as silently missing data. It fails rather than stop short
+  after 100 pages, so raise `pageSize` with it — the limit counts requests, not items — and it
+  stops requesting the moment the screen that asked unmounts, so a user leaving mid-read does not
+  keep the backend walking the cursor.
+- **Leaving a screen aborts its request.** Every list hook hands the query's `AbortSignal` to its
+  `api/` function, which passes it to axios: the HTTP request in flight is cancelled, not only the
+  query state. The `api/` list functions take it as an optional last argument.
+- **The key holds everything that changes the response** — filters (field, operator and value),
+  `order`, `projection`, `pageSize` and `fetchAllPages` — after the base keys, so a metadata read
+  (`projection: "-data"`) and a full read of the same workspace never share an entry, and prefix
+  invalidation (`["workflow_executions", workflowId]`) still reaches every page size and filter.
+- **`projection` takes one field or a list.** `["name", "date"]` returns only those; `["-data"]`
+  everything but `data`. Don't mix the two, and name only fields the entity has: the API answers
+  either with a 500. That is also why `"name,date"` fails — it reads as one field of that name. Filters take
+  `IN` and `NOT_IN` with a list as the value.
+- **A missing workspace fails loudly.** Without a `workspace` filter, or with an empty one, the
+  hooks that take filters fail at once with an error naming the hook, log it with
+  `console.error` (once, in every environment), and send no request. The app config is in
+  `window.APP_CONFIG` before the app renders, so an empty workspace is a wrong or misspelled
+  config key — never a state to wait out, and not one to hide behind an empty screen.
+- **A datastore is tabular or JSON, and a list can mix them.** The API does not say which, so the
+  shape of `data` decides: an array of rows is a table; an object or an array of objects is JSON.
+  They come back told apart by `format`:
+
+  | `format` | `data` | Also |
+  |---|---|---|
+  | `"table"` | row objects, one per matrix row — or, with `dataFormat: "matrix"`, the matrix unconverted | `fields`: the header row, in the datastore's order |
+  | `"json"` | the object or array of objects, untouched | — |
+
+  Narrow before reading rows — `isTableDatastore(datastore)` or `datastore.format === "table"`.
+  A table keeps its column order in `fields`, so saving back is `toDatastoreMatrix(datastore)`,
+  which returns a new matrix the caller owns, however the datastore was read — rebuilt from the
+  rows, patches included, or copied after a `dataFormat: "matrix"` read. `query.data` itself is
+  the query cache: do not edit it in place. A read that projects `data` away has nothing to tell
+  the kinds apart and comes back as an empty table, so do not save its result.
+- **`dataFormat: "matrix"` skips the conversion** in `useFetchDatastores` and `useFetchDatastore`:
+  a tabular datastore's `data` stays the matrix, header row included, typed as such in
+  `query.data` and in `select`. Use it for a grid that takes arrays, an export, or a datastore too
+  large to convert one object per row. The default, `"object"`, is what lets an app patch a row
+  as `{ ...row, ...patch }`. The option is part of the cache key, so the two reads never share an
+  entry.
+- **Paging on grid scroll** is `handleRowsScrollEnd`, in [`/ag-grid`](#paging-an-ag-grid-on-scroll),
+  kept out of the hooks so that it works with any of them.
+
+#### A list hook for an endpoint the SDK does not cover
+
+Compose `useEntityInfiniteQuery`, the hook the seven are built on, rather than copying one of
+them. You say how to request a page and where its items are; it brings the rest — pages merged,
+`select`, `fetchAllPages` (up to `FETCH_ALL_PAGES_LIMIT` pages), and a `query` that
+`handleRowsScrollEnd` pages. Two ways to hold a request back: `configError` for what must always
+be there (it fails loudly), `enabled` for what legitimately is not there yet, like a selection
+(it stays idle).
+
+```ts
+export const useFetchReports = <TData = Report[]>({ workspace, select, fetchAllPages = false }: Props<TData>) => {
+  const { api } = useAxios();
+  const filters = [{ field: "workspace", value: workspace }];
+  // Everything that changes the response goes in the key, fetchAllPages included.
+  const queryKey = buildQueryKey(["reports"], filters, { fetchAllPages });
+
+  const query = useEntityInfiniteQuery<ReportListResponse, "reports", TData>({
+    queryKey,
+    itemsKey: "reports", // ReportListResponse = { next_page_token: string | null; reports: Report[] }
+    fetchPage: (pageToken) => listReports(api, workspace, pageToken),
+    select,
+    fetchAllPages,
+    configError: hasWorkspaceFilter(filters) ? undefined : missingWorkspaceError("useFetchReports"),
+  });
+
+  return { query, queryKey };
+};
+```
+
+The key is the one thing it cannot check for you: two reads under the same key share one cache
+entry, whatever each asked for. `buildQueryKey` builds it from the same parts as the request.
+
+`fetchPage` also receives an `AbortSignal`, aborted when no screen reads the query any more.
+Pass it on (`api.get(url, { signal })`) and a request in flight is cancelled too; ignore it and
+the hook still stops `fetchAllPages` between pages.
+
+#### Single-entity hooks
+
+The eight (`useFetchDatastore`, `useFetchFile`, `useFetchPortfolio`, `useFetchWorkflow`,
+`useFetchWorkflowExecution`, `useFetchWorkerExecution`, `useFetchWorkspace`, `useFetchProfile`),
+and `useFetchWorkerExecutions`, which has the same shape,
+share one set of doors with the lists:
+
+| Prop | |
+|---|---|
+| `select` | Shapes the entity: `data` is what it returns, and is typed so |
+| `queryOptions` | Passed through to `useQuery`, **merged over** the hook's defaults, except `select` |
+
+- **Options are merged, not swapped.** Passing `queryOptions: { enabled }` keeps the defaults
+  (`refetchOnMount: "always"`, `staleTime: 0`, `gcTime: 0`; for the profile, fetched once per
+  session). The hooks used to replace them with whatever was passed, which fell back to
+  TanStack's own and cached for five minutes.
+- **An empty id waits; an empty workspace fails.** An id usually comes from a selection the user
+  has not made yet, so while it is empty the hook stays idle — the guard apps wrote as
+  `queryOptions: { enabled: Boolean(id && workspace) }`, no longer needed. The workspace comes from
+  the app config, in place before the app renders, so an empty one is a misconfigured app: the
+  hook fails at once, without a request, with an error naming it, logged once with
+  `console.error` and shown as the alert — even when the id is empty too. `useFetchWorkspace` is
+  the exception that follows from the API: a workspace is identified by its name, so its `name`
+  is the id, and an empty one waits.
+- **A failure shows an error alert**, through `useAppAlert`, as it always has.
+
+For an endpoint the SDK does not cover, compose `useEntityQuery`, the hook the eight are built
+on:
+
+```ts
+export const useFetchReport = <TData = Report>({ id, workspace, select, queryOptions }: Props<TData>) => {
+  const { api } = useAxios();
+  const queryKey = ["report", id, workspace];
+
+  const query = useEntityQuery<Report, TData>({
+    queryKey,
+    fetchEntity: (signal) => getReport(api, id, workspace, signal),
+    select,
+    enabled: Boolean(id), // a selection not made yet: wait
+    configError: workspace ? undefined : missingWorkspaceError("useFetchReport"), // misconfigured: fail
+    queryOptions,
+  });
+
+  return { ...query, queryKey };
+};
+```
+
+`defaultQueryOptions` replaces the SDK's defaults for a hook whose data does not change, as the
+profile's does. `fetchEntity` receives the query's `AbortSignal`: the SDK's hooks hand it to
+their `api/` get function, which passes it to axios, so leaving a screen aborts the request.
+
+#### Mutation hooks
+
+`useDatastoreMutations`, `useFileMutations` and `usePortfolioMutations` are built on
+`useEntityMutation`. For a write the SDK does not cover, compose it too: it invalidates
+`queryKey` after a success (awaited, so code after `mutateAsync` sees fresh data) and shows the
+success alert, or the failure's own message as an error alert, falling back to `errorMessage`.
+
+```ts
+const share = useEntityMutation({
+  mutationFn: ({ id, workspace }: ShareReportProps) => shareReport(api, id, workspace),
+  queryKey, // optional: invalidated after a success
+  successMessage: "Report shared successfully.",
+  errorMessage: "Unable to share the report. Please try again.",
+});
+```
+
 ### Components
 
 Five, all MUI underneath.
@@ -110,7 +348,7 @@ Five, all MUI underneath.
 | Component | Props | |
 |---|---|---|
 | `PageContainer` | `header?`, `footer?`, `contentClassName?` | The page frame: chrome around a scrolling content area |
-| `Toolbar` | `className?` | Top bar. Renders `EveryskIcon` and its children |
+| `Toolbar` | `title?`, `subheader?`, `action?`, `startAction?`, `logo?`, `hideLogo?`, `position?`, `className?` | Top bar: `startAction`, logo (`EveryskIcon` unless replaced or hidden), title, children, then `action` at the far end. `position` defaults to `relative` |
 | `Footer` | `className?` | Bottom bar |
 | `GlobalLoading` | `isLoading`, `backdrop?`, `message?` | Full-page spinner. `backdrop` defaults to `true` |
 | `EveryskIcon` | every `SvgIconProps` except `color` | The brand mark |
@@ -119,8 +357,15 @@ Five, all MUI underneath.
 but a utility loses to MUI's own styles in the cascade, so reach for `sx` when one is dropped.
 `GlobalLoading` takes no `className`, and `EveryskIcon` gets one through `SvgIconProps`.
 
+A shell that renders the `Toolbar` for its pages holds a `ToolbarContent` — `title`, `subheader`,
+`action` and `children`, the part a page supplies — and adds `startAction`, the logo and
+`position` itself.
+
 ```tsx
-<PageContainer header={<Toolbar>Trade Allocation</Toolbar>} footer={<Footer />}>
+<PageContainer
+  header={<Toolbar title="Trade Allocation" action={<DateFilter />} />}
+  footer={<Footer />}
+>
   <GlobalLoading isLoading={query.isLoading} message="Loading portfolios…" />
   {/* the page */}
 </PageContainer>
@@ -139,14 +384,19 @@ but a utility loses to MUI's own styles in the cascade, so reach for `sx` when o
 `EveryskDarkTheme`, `EveryskLightTheme`, `DefaultDarkTheme`, `DefaultLightTheme` and
 `MidnightEmberTheme`, plus `getTheme(name)` to resolve one by the name the CLI writes, and
 `getBrandTheme(mode)` / `getDefaultTheme(mode)` for the pair. `EveryskApp` mounts the brand dark
-theme unless given a `theme` prop.
+theme unless given a `theme` prop. `componentOverrides` is the MUI component overrides every one
+of them applies, for an app that builds its own theme.
 
 ### Query client and helpers
 
 `createQueryClient(config?)` builds the QueryClient `EveryskApp` mounts — a factory rather than a
 shared instance, because two apps or two tests sharing one client share its cache.
-`getQueryFn`, `toFilterTuple`, `buildQueryObject` and `buildQueryKey` are the pieces the entity
-hooks are built from, exported for a query the slices do not cover.
+`buildQueryObject`, `buildQueryKey`, `hasWorkspaceFilter`, `missingWorkspaceError`,
+`useEntityQuery`, `useEntityInfiniteQuery` and `useEntityMutation` are the pieces the entity hooks are built from,
+exported for a query the slices do not cover. `parseDatastore` is the
+conversion the datastore hooks apply to each datastore, for an app that seeds their cache, and
+`isTableDatastore` narrows its result to a tabular one. `toDatastoreMatrix` gives a tabular
+datastore's matrix back, and `matrixToObjects` / `objectsToMatrix` convert a matrix either way. They were `tableToObjects` / `objectsToTable` in 0.2.0.
 
 `useAxios`'s interceptor is worth knowing about if you write one of those: on `GET` and `DELETE`
 it parses the request's query object into the shape the platform API expects. It is attached in
@@ -176,13 +426,25 @@ nothing but `createQueryClient`. The subpath is what makes the peer genuinely op
 
 ## The AG Grid licence is a parameter
 
-```ts
-// src/main.tsx
-import { setAgGridLicense } from "@everysk/apps-sdk/ag-grid";
+```tsx
+// src/App.tsx
+import { EveryskApp, withProps } from "@everysk/apps-sdk";
+import { AgGridLicenseProvider } from "@everysk/apps-sdk/ag-grid";
 
-setAgGridLicense(import.meta.env.VITE_AG_GRID_LICENSE_KEY);
+const agGridLicense = withProps(AgGridLicenseProvider, {
+    licenseKey: import.meta.env.VITE_AG_GRID_LICENSE_KEY,
+});
+
+export function App() {
+    return <EveryskApp providers={[agGridLicense]}>…</EveryskApp>;
+}
 ```
 
+`providers` mounts a bare component with no props, so a bare `AgGridLicenseProvider` there
+registers nothing; `withProps` is what carries the key, checked against the provider's props. It describes
+the provider rather than wrapping it, so calling it inside a render does not remount the app.
+`setAgGridLicense(key)`, called once in `main.tsx`, does the same without a provider.
+
 This package never reads your environment. Vite replaces `import.meta.env.VITE_*` with a literal
 at the build of whoever compiles the file — for a published package that is this package's own
 CI, where the variable does not exist, so the value would freeze as `undefined` and your
@@ -193,6 +455,30 @@ is the AG Grid watermark.
 any theme — including one the app creates — gets a matching grid without a second table of
 colours.
 
+## Paging an AG Grid on scroll
+
+```tsx
+import { handleRowsScrollEnd } from "@everysk/apps-sdk/ag-grid";
+
+const { query } = useFetchDatastores({ filters, select: toRows });
+
+<AgGridReact
+  rowData={query.data}
+  onBodyScrollEnd={(event) => handleRowsScrollEnd(event.api, query)}
+  onModelUpdated={(event) => handleRowsScrollEnd(event.api, query)}
+/>
+```
+
+It requests the next page when the grid is scrolled within `scrollEndThreshold` pixels of its
+last row, or shows no rows — the second event is what keeps a grid whose rows a filter hid
+entirely loading. The names are MUI X DataGrid's (`onRowsScrollEnd`, `scrollEndThreshold`, default
+`80`), and so is the unit: pixels, which hold when rows differ in height.
+
+A function rather than part of a hook: it takes any infinite query's `hasNextPage`,
+`isFetchingNextPage` and `fetchNextPage`, so it pages any list hook or a `useInfiniteQuery` of the
+app's own. Grid events arrive in bursts, so it asks with `cancelRefetch: false` and a repeat
+while the first request is in flight does nothing.
+
 ## Testing an app against it
 
 ```ts

package/dist/EveryskApp.d.ts

@@ -1,9 +1,39 @@
-import { type ComponentType, type PropsWithChildren } from "react";
+import { type ComponentType, type PropsWithChildren, type ReactNode } from "react";
 import { type QueryClient } from "@tanstack/react-query";
 import type { AnyRecord } from "./types/anyRecord.d.ts";
 import type { Theme } from "@mui/material/styles";
 /** A provider is any component that renders its children. */
 export type ProviderComponent = ComponentType<PropsWithChildren>;
+/** A provider with the props it is mounted with, as `withProps` describes it. */
+export type ConfiguredProvider = {
+    readonly component: ComponentType<PropsWithChildren<AnyRecord>>;
+    readonly props: AnyRecord;
+};
+/** What `providers` takes: a provider, or one with its props. */
+export type ProviderEntry = ProviderComponent | ConfiguredProvider;
+/**
+ * withProps
+ *
+ * A provider for `EveryskApp`'s `providers`, mounted with these props. `providers` mounts a bare
+ * component as `<Provider>{children}</Provider>`, so a provider configured by a prop — AG Grid's
+ * license key — needs its props said here:
+ *
+ * ```tsx
+ * <EveryskApp
+ *     providers={[
+ *         withProps(AgGridLicenseProvider, { licenseKey: import.meta.env.VITE_AG_GRID_LICENSE_KEY }),
+ *         WebSocketProvider,
+ *     ]}
+ * >
+ * ```
+ *
+ * It describes the provider rather than returning a wrapper component: a wrapper made in `App`'s
+ * render is a new component type each time, and React would remount the whole app under it on
+ * every render. The props are checked against the component's own.
+ */
+export declare const withProps: <P extends {
+    children?: ReactNode;
+}>(component: ComponentType<P>, props: NoInfer<Omit<P, "children">>) => ConfiguredProvider;
 export type EveryskAppProps = PropsWithChildren<{
     /**
      * The client every `useQuery` in the tree talks to. Defaults to a fresh
@@ -28,8 +58,10 @@ export type EveryskAppProps = PropsWithChildren<{
      * `modules.json` kept an explicit `providerOrder` only because the app owned the tree and
      * each module had to be hand-wired into the right slot; owning the tree here is what
      * retires that contract.
+     *
+     * A provider configured by props goes in through `withProps`.
      */
-    providers?: ProviderComponent[];
+    providers?: ProviderEntry[];
 }>;
 /**
  * EveryskApp

package/dist/EveryskApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EveryskApp.d.ts","sourceRoot":"","sources":["../src/EveryskApp.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAkB,MAAM,OAAO,CAAC;AAE5F,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAM9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAC;AAEjE,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;IAC5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,SAAS,CAAC;IAC9B;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACnC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,UAAU,GAAI,wEAOxB,eAAe,gCAoBjB,CAAC"}
+{"version":3,"file":"EveryskApp.d.ts","sourceRoot":"","sources":["../src/EveryskApp.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE5F,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAM9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAC;AAEjE,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,GAAG;IAC7B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC7B,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,EACxD,WAAW,aAAa,CAAC,CAAC,CAAC,EAC3B,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,KACpC,kBAGD,CAAC;AAcH,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;IAC5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,SAAS,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;CAC/B,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,UAAU,GAAI,wEAOxB,eAAe,gCAoBjB,CAAC"}

package/dist/EveryskApp.js

@@ -7,6 +7,39 @@ import { QueryClientProvider } from "@tanstack/react-query";
 import { jsx } from "react/jsx-runtime";
 //#region src/EveryskApp.tsx
 /**
+* withProps
+*
+* A provider for `EveryskApp`'s `providers`, mounted with these props. `providers` mounts a bare
+* component as `<Provider>{children}</Provider>`, so a provider configured by a prop — AG Grid's
+* license key — needs its props said here:
+*
+* ```tsx
+* <EveryskApp
+*     providers={[
+*         withProps(AgGridLicenseProvider, { licenseKey: import.meta.env.VITE_AG_GRID_LICENSE_KEY }),
+*         WebSocketProvider,
+*     ]}
+* >
+* ```
+*
+* It describes the provider rather than returning a wrapper component: a wrapper made in `App`'s
+* render is a new component type each time, and React would remount the whole app under it on
+* every render. The props are checked against the component's own.
+*/
+var withProps = (component, props) => ({
+	component,
+	props
+});
+var isConfigured = (entry) => typeof entry === "object" && entry !== null && "component" in entry && "props" in entry;
+var mount = (entry, children) => {
+	if (!isConfigured(entry)) return /* @__PURE__ */ jsx(entry, { children });
+	const { component: Provider, props } = entry;
+	return /* @__PURE__ */ jsx(Provider, {
+		...props,
+		children
+	});
+};
+/**
 * EveryskApp
 *
 * The provider tree every Everysk app mounts, composed in one fixed order:
@@ -47,7 +80,7 @@ import { jsx } from "react/jsx-runtime";
 var EveryskApp = ({ children, queryClient, theme, appId, appEnvironmentVar, providers }) => {
 	const fallbackQueryClient = useMemo(() => createQueryClient(), []);
 	const client = queryClient ?? fallbackQueryClient;
-	const wrapped = (providers ?? []).reduceRight((inner, Provider) => /* @__PURE__ */ jsx(Provider, { children: inner }), children);
+	const wrapped = (providers ?? []).reduceRight((inner, entry) => mount(entry, inner), children);
 	return /* @__PURE__ */ jsx(ThemeProvider, {
 		theme,
 		children: /* @__PURE__ */ jsx(AppConfigProvider, {
@@ -61,6 +94,6 @@ var EveryskApp = ({ children, queryClient, theme, appId, appEnvironmentVar, prov
 	});
 };
 //#endregion
-export { EveryskApp };
+export { EveryskApp, withProps };
 
 //# sourceMappingURL=EveryskApp.js.map

package/dist/EveryskApp.js.map

@@ -1 +1 @@
-{"version":3,"file":"EveryskApp.js","names":[],"sources":["../src/EveryskApp.tsx"],"sourcesContent":["import { useMemo, type ComponentType, type PropsWithChildren, type ReactNode } from \"react\";\n\nimport { QueryClientProvider, type QueryClient } from \"@tanstack/react-query\";\n\nimport { ThemeProvider } from \"@/theme/ThemeProvider\";\nimport { AppConfigProvider } from \"@/contexts/appConfigContext/provider\";\nimport { AppAlertProvider } from \"@/contexts/appAlertContext/provider\";\nimport { createQueryClient } from \"@/lib/queryClient\";\nimport type { AnyRecord } from \"@/types/anyRecord\";\nimport type { Theme } from \"@mui/material/styles\";\n\n/** A provider is any component that renders its children. */\nexport type ProviderComponent = ComponentType<PropsWithChildren>;\n\nexport type EveryskAppProps = PropsWithChildren<{\n    /**\n     * The client every `useQuery` in the tree talks to. Defaults to a fresh\n     * `createQueryClient()` created once per mount. Pass one to seed the cache, to share it\n     * with code outside the tree, or to assert on it from a test.\n     */\n    queryClient?: QueryClient;\n    /** Overrides `window.APP_ID`. */\n    appId?: string | null;\n    /**\n     * The MUI theme. Omitted, the app gets the Everysk dark theme — see `ThemeProvider`.\n     */\n    theme?: Theme;\n    /** Overrides `window.APP_CONFIG` wholesale. */\n    appEnvironmentVar?: AnyRecord;\n    /**\n     * Optional providers, applied innermost — inside every core provider and directly around\n     * `children`, in array order, so the first entry is outermost of the group.\n     *\n     * They go innermost rather than into named slots because that is the only position from\n     * which a provider can read every core context (theme, app config, query client, alerts).\n     * `modules.json` kept an explicit `providerOrder` only because the app owned the tree and\n     * each module had to be hand-wired into the right slot; owning the tree here is what\n     * retires that contract.\n     */\n    providers?: ProviderComponent[];\n}>;\n\n/**\n * EveryskApp\n *\n * The provider tree every Everysk app mounts, composed in one fixed order:\n *\n * ```\n * ThemeProvider\n *   AppConfigProvider\n *     QueryClientProvider\n *       AppAlertProvider\n *         …providers\n *           children\n * ```\n *\n * The order is not arbitrary. `AppAlertProvider` renders MUI's `Snackbar`, so it must sit\n * inside `ThemeProvider`; and `QueryClientProvider` sits inside `AppConfigProvider` because\n * entity hooks build their Axios instance from `useAppConfig()`.\n *\n * `BroadcastChannelProvider` used to sit between theme and app configuration. It is gone: the\n * optional socket layer supersedes it for cross-tab and server-push messaging (as\n * `modules.json` already stated), and the one production path that still used it — app\n * configuration arriving over the channel — was replaced by `window.APP_CONFIG`.\n *\n * `src/test/renderWithProviders` renders through this same component, so a test and the real\n * app can never see different trees.\n *\n * @example\n * ```tsx\n * // src/App.tsx — the entire file\n * export function App() {\n *   return (\n *     <EveryskApp>\n *       <Routes />\n *     </EveryskApp>\n *   );\n * }\n * ```\n */\nexport const EveryskApp = ({\n    children,\n    queryClient,\n    theme,\n    appId,\n    appEnvironmentVar,\n    providers,\n}: EveryskAppProps) => {\n    // Only used when the caller passes no client. Created once per mount so a re-render\n    // never swaps the cache out from under the tree.\n    const fallbackQueryClient = useMemo(() => createQueryClient(), []);\n    const client = queryClient ?? fallbackQueryClient;\n\n    const wrapped = (providers ?? []).reduceRight<ReactNode>(\n        (inner, Provider) => <Provider>{inner}</Provider>,\n        children,\n    );\n\n    return (\n        <ThemeProvider theme={theme}>\n            <AppConfigProvider appId={appId} appEnvironmentVar={appEnvironmentVar}>\n                <QueryClientProvider client={client}>\n                    <AppAlertProvider>{wrapped}</AppAlertProvider>\n                </QueryClientProvider>\n            </AppConfigProvider>\n        </ThemeProvider>\n    );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgFA,IAAa,cAAc,EACvB,UACA,aACA,OACA,OACA,mBACA,gBACmB;CAGnB,MAAM,sBAAsB,cAAc,kBAAkB,GAAG,CAAC,CAAC;CACjE,MAAM,SAAS,eAAe;CAE9B,MAAM,WAAW,aAAa,CAAC,EAAA,CAAG,aAC7B,OAAO,aAAa,oBAAC,UAAD,EAAA,UAAW,MAAgB,CAAA,GAChD,QACJ;CAEA,OACI,oBAAC,eAAD;EAAsB;EAClB,UAAA,oBAAC,mBAAD;GAA0B;GAA0B;GAChD,UAAA,oBAAC,qBAAD;IAA6B;IACzB,UAAA,oBAAC,kBAAD,EAAA,UAAmB,QAA0B,CAAA;GAC5B,CAAA;EACN,CAAA;CACR,CAAA;AAEvB"}
+{"version":3,"file":"EveryskApp.js","names":[],"sources":["../src/EveryskApp.tsx"],"sourcesContent":["import { useMemo, type ComponentType, type PropsWithChildren, type ReactNode } from \"react\";\n\nimport { QueryClientProvider, type QueryClient } from \"@tanstack/react-query\";\n\nimport { ThemeProvider } from \"@/theme/ThemeProvider\";\nimport { AppConfigProvider } from \"@/contexts/appConfigContext/provider\";\nimport { AppAlertProvider } from \"@/contexts/appAlertContext/provider\";\nimport { createQueryClient } from \"@/lib/queryClient\";\nimport type { AnyRecord } from \"@/types/anyRecord\";\nimport type { Theme } from \"@mui/material/styles\";\n\n/** A provider is any component that renders its children. */\nexport type ProviderComponent = ComponentType<PropsWithChildren>;\n\n/** A provider with the props it is mounted with, as `withProps` describes it. */\nexport type ConfiguredProvider = {\n    readonly component: ComponentType<PropsWithChildren<AnyRecord>>;\n    readonly props: AnyRecord;\n};\n\n/** What `providers` takes: a provider, or one with its props. */\nexport type ProviderEntry = ProviderComponent | ConfiguredProvider;\n\n/**\n * withProps\n *\n * A provider for `EveryskApp`'s `providers`, mounted with these props. `providers` mounts a bare\n * component as `<Provider>{children}</Provider>`, so a provider configured by a prop — AG Grid's\n * license key — needs its props said here:\n *\n * ```tsx\n * <EveryskApp\n *     providers={[\n *         withProps(AgGridLicenseProvider, { licenseKey: import.meta.env.VITE_AG_GRID_LICENSE_KEY }),\n *         WebSocketProvider,\n *     ]}\n * >\n * ```\n *\n * It describes the provider rather than returning a wrapper component: a wrapper made in `App`'s\n * render is a new component type each time, and React would remount the whole app under it on\n * every render. The props are checked against the component's own.\n */\nexport const withProps = <P extends { children?: ReactNode }>(\n    component: ComponentType<P>,\n    props: NoInfer<Omit<P, \"children\">>,\n): ConfiguredProvider => ({\n    component: component as ComponentType<PropsWithChildren<AnyRecord>>,\n    props: props as AnyRecord,\n});\n\nconst isConfigured = (entry: ProviderEntry): entry is ConfiguredProvider =>\n    typeof entry === \"object\" && entry !== null && \"component\" in entry && \"props\" in entry;\n\nconst mount = (entry: ProviderEntry, children: ReactNode): ReactNode => {\n    if (!isConfigured(entry)) {\n        const Provider = entry;\n        return <Provider>{children}</Provider>;\n    }\n    const { component: Provider, props } = entry;\n    return <Provider {...props}>{children}</Provider>;\n};\n\nexport type EveryskAppProps = PropsWithChildren<{\n    /**\n     * The client every `useQuery` in the tree talks to. Defaults to a fresh\n     * `createQueryClient()` created once per mount. Pass one to seed the cache, to share it\n     * with code outside the tree, or to assert on it from a test.\n     */\n    queryClient?: QueryClient;\n    /** Overrides `window.APP_ID`. */\n    appId?: string | null;\n    /**\n     * The MUI theme. Omitted, the app gets the Everysk dark theme — see `ThemeProvider`.\n     */\n    theme?: Theme;\n    /** Overrides `window.APP_CONFIG` wholesale. */\n    appEnvironmentVar?: AnyRecord;\n    /**\n     * Optional providers, applied innermost — inside every core provider and directly around\n     * `children`, in array order, so the first entry is outermost of the group.\n     *\n     * They go innermost rather than into named slots because that is the only position from\n     * which a provider can read every core context (theme, app config, query client, alerts).\n     * `modules.json` kept an explicit `providerOrder` only because the app owned the tree and\n     * each module had to be hand-wired into the right slot; owning the tree here is what\n     * retires that contract.\n     *\n     * A provider configured by props goes in through `withProps`.\n     */\n    providers?: ProviderEntry[];\n}>;\n\n/**\n * EveryskApp\n *\n * The provider tree every Everysk app mounts, composed in one fixed order:\n *\n * ```\n * ThemeProvider\n *   AppConfigProvider\n *     QueryClientProvider\n *       AppAlertProvider\n *         …providers\n *           children\n * ```\n *\n * The order is not arbitrary. `AppAlertProvider` renders MUI's `Snackbar`, so it must sit\n * inside `ThemeProvider`; and `QueryClientProvider` sits inside `AppConfigProvider` because\n * entity hooks build their Axios instance from `useAppConfig()`.\n *\n * `BroadcastChannelProvider` used to sit between theme and app configuration. It is gone: the\n * optional socket layer supersedes it for cross-tab and server-push messaging (as\n * `modules.json` already stated), and the one production path that still used it — app\n * configuration arriving over the channel — was replaced by `window.APP_CONFIG`.\n *\n * `src/test/renderWithProviders` renders through this same component, so a test and the real\n * app can never see different trees.\n *\n * @example\n * ```tsx\n * // src/App.tsx — the entire file\n * export function App() {\n *   return (\n *     <EveryskApp>\n *       <Routes />\n *     </EveryskApp>\n *   );\n * }\n * ```\n */\nexport const EveryskApp = ({\n    children,\n    queryClient,\n    theme,\n    appId,\n    appEnvironmentVar,\n    providers,\n}: EveryskAppProps) => {\n    // Only used when the caller passes no client. Created once per mount so a re-render\n    // never swaps the cache out from under the tree.\n    const fallbackQueryClient = useMemo(() => createQueryClient(), []);\n    const client = queryClient ?? fallbackQueryClient;\n\n    const wrapped = (providers ?? []).reduceRight<ReactNode>(\n        (inner, entry) => mount(entry, inner),\n        children,\n    );\n\n    return (\n        <ThemeProvider theme={theme}>\n            <AppConfigProvider appId={appId} appEnvironmentVar={appEnvironmentVar}>\n                <QueryClientProvider client={client}>\n                    <AppAlertProvider>{wrapped}</AppAlertProvider>\n                </QueryClientProvider>\n            </AppConfigProvider>\n        </ThemeProvider>\n    );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,IAAa,aACT,WACA,WACsB;CACX;CACJ;AACX;AAEA,IAAM,gBAAgB,UAClB,OAAO,UAAU,YAAY,UAAU,QAAQ,eAAe,SAAS,WAAW;AAEtF,IAAM,SAAS,OAAsB,aAAmC;CACpE,IAAI,CAAC,aAAa,KAAK,GAEnB,OAAO,oBAAC,OAAD,EAAW,SAAmB,CAAA;CAEzC,MAAM,EAAE,WAAW,UAAU,UAAU;CACvC,OAAO,oBAAC,UAAD;EAAU,GAAI;EAAQ;CAAmB,CAAA;AACpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsEA,IAAa,cAAc,EACvB,UACA,aACA,OACA,OACA,mBACA,gBACmB;CAGnB,MAAM,sBAAsB,cAAc,kBAAkB,GAAG,CAAC,CAAC;CACjE,MAAM,SAAS,eAAe;CAE9B,MAAM,WAAW,aAAa,CAAC,EAAA,CAAG,aAC7B,OAAO,UAAU,MAAM,OAAO,KAAK,GACpC,QACJ;CAEA,OACI,oBAAC,eAAD;EAAsB;EAClB,UAAA,oBAAC,mBAAD;GAA0B;GAA0B;GAChD,UAAA,oBAAC,qBAAD;IAA6B;IACzB,UAAA,oBAAC,kBAAD,EAAA,UAAmB,QAA0B,CAAA;GAC5B,CAAA;EACN,CAAA;CACR,CAAA;AAEvB"}

package/dist/agGrid/handleRowsScrollEnd.d.ts

@@ -0,0 +1,53 @@
+import type { GridApi } from "ag-grid-community";
+/**
+ * The part of an infinite query this needs. Structural, so it takes any list hook's `query`,
+ * or a `useInfiniteQuery` an app writes itself.
+ */
+export type InfiniteQueryPaging = {
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    fetchNextPage: (options?: {
+        cancelRefetch?: boolean;
+    }) => Promise<unknown>;
+};
+export type HandleRowsScrollEndOptions = {
+    /**
+     * Distance in pixels from the end of the rows at which the next page is requested. Named and
+     * measured as MUI X DataGrid's `scrollEndThreshold`, whose default it shares. Pixels rather
+     * than rows, so it holds with rows of different heights.
+     */
+    scrollEndThreshold?: number;
+};
+/**
+ * handleRowsScrollEnd
+ *
+ * Requests the next page when an AG Grid is scrolled near its last row, or shows none — the
+ * grid paging on demand. The handler for what MUI X DataGrid calls `onRowsScrollEnd`; wire it
+ * to AG Grid's `onBodyScrollEnd` and `onModelUpdated`, the second so that a grid whose rows a
+ * client-side filter hid entirely keeps loading.
+ *
+ * A function, not part of any hook: the data hook does not know a grid exists, and the grid
+ * does not know where its rows come from. It lives in this subpath because it needs `GridApi`,
+ * and AG Grid is an optional peer.
+ *
+ * Events fire in bursts, before `isFetchingNextPage` has flipped, so the request is made with
+ * `cancelRefetch: false`: TanStack then ignores a repeat while the first one is in flight,
+ * instead of cancelling it and asking for the same page again.
+ *
+ * @param {GridApi} gridApi - The grid, from the event (`event.api`).
+ * @param {InfiniteQueryPaging} query - The infinite query feeding the grid.
+ * @param {HandleRowsScrollEndOptions} [options] - `scrollEndThreshold`, in pixels (default 80).
+ *
+ * Example:
+ * ```tsx
+ * const { query } = useFetchDatastores({ filters, select: toRows });
+ *
+ * <AgGridReact
+ *   rowData={query.data}
+ *   onBodyScrollEnd={(event) => handleRowsScrollEnd(event.api, query)}
+ *   onModelUpdated={(event) => handleRowsScrollEnd(event.api, query)}
+ * />
+ * ```
+ */
+export declare const handleRowsScrollEnd: (gridApi: GridApi, query: InfiniteQueryPaging, { scrollEndThreshold }?: HandleRowsScrollEndOptions) => void;
+//# sourceMappingURL=handleRowsScrollEnd.d.ts.map

package/dist/agGrid/handleRowsScrollEnd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleRowsScrollEnd.d.ts","sourceRoot":"","sources":["../../src/agGrid/handleRowsScrollEnd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACrC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,mBAAmB,GAC5B,SAAS,OAAO,EAChB,OAAO,mBAAmB,EAC1B,yBAA6B,0BAA+B,KAC7D,IAcF,CAAC"}

package/dist/agGrid/handleRowsScrollEnd.js

@@ -0,0 +1,47 @@
+//#region src/agGrid/handleRowsScrollEnd.ts
+/**
+* handleRowsScrollEnd
+*
+* Requests the next page when an AG Grid is scrolled near its last row, or shows none — the
+* grid paging on demand. The handler for what MUI X DataGrid calls `onRowsScrollEnd`; wire it
+* to AG Grid's `onBodyScrollEnd` and `onModelUpdated`, the second so that a grid whose rows a
+* client-side filter hid entirely keeps loading.
+*
+* A function, not part of any hook: the data hook does not know a grid exists, and the grid
+* does not know where its rows come from. It lives in this subpath because it needs `GridApi`,
+* and AG Grid is an optional peer.
+*
+* Events fire in bursts, before `isFetchingNextPage` has flipped, so the request is made with
+* `cancelRefetch: false`: TanStack then ignores a repeat while the first one is in flight,
+* instead of cancelling it and asking for the same page again.
+*
+* @param {GridApi} gridApi - The grid, from the event (`event.api`).
+* @param {InfiniteQueryPaging} query - The infinite query feeding the grid.
+* @param {HandleRowsScrollEndOptions} [options] - `scrollEndThreshold`, in pixels (default 80).
+*
+* Example:
+* ```tsx
+* const { query } = useFetchDatastores({ filters, select: toRows });
+*
+* <AgGridReact
+*   rowData={query.data}
+*   onBodyScrollEnd={(event) => handleRowsScrollEnd(event.api, query)}
+*   onModelUpdated={(event) => handleRowsScrollEnd(event.api, query)}
+* />
+* ```
+*/
+var handleRowsScrollEnd = (gridApi, query, { scrollEndThreshold = 80 } = {}) => {
+	if (!query.hasNextPage || query.isFetchingNextPage) return;
+	const rowCount = gridApi.getDisplayedRowCount();
+	const lastRow = rowCount > 0 ? gridApi.getDisplayedRowAtIndex(rowCount - 1) : void 0;
+	if (lastRow) {
+		const rowsEnd = (lastRow.rowTop ?? 0) + (lastRow.rowHeight ?? 0);
+		const { bottom } = gridApi.getVerticalPixelRange();
+		if (rowsEnd - bottom > scrollEndThreshold) return;
+	}
+	query.fetchNextPage({ cancelRefetch: false });
+};
+//#endregion
+export { handleRowsScrollEnd };
+
+//# sourceMappingURL=handleRowsScrollEnd.js.map

package/dist/agGrid/handleRowsScrollEnd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleRowsScrollEnd.js","names":[],"sources":["../../src/agGrid/handleRowsScrollEnd.ts"],"sourcesContent":["import type { GridApi } from \"ag-grid-community\";\n\n/**\n * The part of an infinite query this needs. Structural, so it takes any list hook's `query`,\n * or a `useInfiniteQuery` an app writes itself.\n */\nexport type InfiniteQueryPaging = {\n    hasNextPage: boolean;\n    isFetchingNextPage: boolean;\n    fetchNextPage: (options?: { cancelRefetch?: boolean }) => Promise<unknown>;\n};\n\nexport type HandleRowsScrollEndOptions = {\n    /**\n     * Distance in pixels from the end of the rows at which the next page is requested. Named and\n     * measured as MUI X DataGrid's `scrollEndThreshold`, whose default it shares. Pixels rather\n     * than rows, so it holds with rows of different heights.\n     */\n    scrollEndThreshold?: number;\n};\n\n/**\n * handleRowsScrollEnd\n *\n * Requests the next page when an AG Grid is scrolled near its last row, or shows none — the\n * grid paging on demand. The handler for what MUI X DataGrid calls `onRowsScrollEnd`; wire it\n * to AG Grid's `onBodyScrollEnd` and `onModelUpdated`, the second so that a grid whose rows a\n * client-side filter hid entirely keeps loading.\n *\n * A function, not part of any hook: the data hook does not know a grid exists, and the grid\n * does not know where its rows come from. It lives in this subpath because it needs `GridApi`,\n * and AG Grid is an optional peer.\n *\n * Events fire in bursts, before `isFetchingNextPage` has flipped, so the request is made with\n * `cancelRefetch: false`: TanStack then ignores a repeat while the first one is in flight,\n * instead of cancelling it and asking for the same page again.\n *\n * @param {GridApi} gridApi - The grid, from the event (`event.api`).\n * @param {InfiniteQueryPaging} query - The infinite query feeding the grid.\n * @param {HandleRowsScrollEndOptions} [options] - `scrollEndThreshold`, in pixels (default 80).\n *\n * Example:\n * ```tsx\n * const { query } = useFetchDatastores({ filters, select: toRows });\n *\n * <AgGridReact\n *   rowData={query.data}\n *   onBodyScrollEnd={(event) => handleRowsScrollEnd(event.api, query)}\n *   onModelUpdated={(event) => handleRowsScrollEnd(event.api, query)}\n * />\n * ```\n */\nexport const handleRowsScrollEnd = (\n    gridApi: GridApi,\n    query: InfiniteQueryPaging,\n    { scrollEndThreshold = 80 }: HandleRowsScrollEndOptions = {},\n): void => {\n    if (!query.hasNextPage || query.isFetchingNextPage) return;\n\n    const rowCount = gridApi.getDisplayedRowCount();\n    const lastRow = rowCount > 0 ? gridApi.getDisplayedRowAtIndex(rowCount - 1) : undefined;\n\n    if (lastRow) {\n        const rowsEnd = (lastRow.rowTop ?? 0) + (lastRow.rowHeight ?? 0);\n        const { bottom } = gridApi.getVerticalPixelRange();\n\n        if (rowsEnd - bottom > scrollEndThreshold) return;\n    }\n\n    void query.fetchNextPage({ cancelRefetch: false });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,IAAa,uBACT,SACA,OACA,EAAE,qBAAqB,OAAmC,CAAC,MACpD;CACP,IAAI,CAAC,MAAM,eAAe,MAAM,oBAAoB;CAEpD,MAAM,WAAW,QAAQ,qBAAqB;CAC9C,MAAM,UAAU,WAAW,IAAI,QAAQ,uBAAuB,WAAW,CAAC,IAAI,KAAA;CAE9E,IAAI,SAAS;EACT,MAAM,WAAW,QAAQ,UAAU,MAAM,QAAQ,aAAa;EAC9D,MAAM,EAAE,WAAW,QAAQ,sBAAsB;EAEjD,IAAI,UAAU,SAAS,oBAAoB;CAC/C;CAEA,MAAW,cAAc,EAAE,eAAe,MAAM,CAAC;AACrD"}

package/dist/agGrid/index.d.ts

@@ -1,4 +1,6 @@
 export { setAgGridLicense, AgGridLicenseProvider } from "../contexts/agGridLicenseContext/provider.js";
 export type { AgGridLicenseProviderProps } from "../contexts/agGridLicenseContext/provider.js";
 export { getAgGridTheme, useAgGridTheme, agGridThemeParams } from "./agGridTheme";
+export { handleRowsScrollEnd } from "./handleRowsScrollEnd";
+export type { HandleRowsScrollEndOptions, InfiniteQueryPaging } from "./handleRowsScrollEnd";
 //# sourceMappingURL=index.d.ts.map

package/dist/agGrid/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agGrid/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACnG,YAAY,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AAE3F,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agGrid/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACnG,YAAY,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AAE3F,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}