@quadrokit/ui 0.2.13 → 0.3.0

package/dist/hooks/use-quadro-paged-collection.d.ts

@@ -0,0 +1,33 @@
+import type { CollectionHandle, CollectionOptions } from '@quadrokit/client/runtime';
+export type QuadroPagedCollectionFactory<T> = (options: CollectionOptions) => CollectionHandle<T>;
+export type UseQuadroPagedCollectionOptions<T> = {
+    page: number;
+    pageSize: number;
+    /**
+     * When this value changes, the cached entity-set URI is cleared.
+     * Defaults to `pageSize` (so changing rows-per-page starts a new entity set).
+     * Pass e.g. a filter revision when list filters change.
+     */
+    entitySetResetKey?: unknown;
+    /** Pass `quadro.SomeClass.all` (or wrap it); use a cast at the call site if `select` is path-typed. */
+    all: QuadroPagedCollectionFactory<T>;
+} & Omit<CollectionOptions, 'page' | 'pageSize' | 'maxItems' | 'signal' | 'reuseEntitySet' | 'onEntitySetReady'>;
+/**
+ * Loads one page from a QuadroKit collection with 4D entity-set reuse (`$top=0` once, then
+ * `__ENTITYSET` paging). Calls `release()` on unmount only.
+ *
+ * Other list options (`select`, `filter`, …) are read from a ref so `page` / `pageSize` can stay
+ * stable deps without stale closures; change `entitySetResetKey` when filters change.
+ *
+ * **`collection`** is the current `CollectionHandle` (e.g. `getFirst`, `release`, async iteration).
+ * It is `null` until the first handle is created for the active load, then cleared when the load
+ * effect cleans up (page / deps change or unmount).
+ */
+export declare function useQuadroPagedCollection<T>(options: UseQuadroPagedCollectionOptions<T>): {
+    rows: T[];
+    hasNext: boolean;
+    loading: boolean;
+    error: string | null;
+    collection: CollectionHandle<T> | null;
+};
+//# sourceMappingURL=use-quadro-paged-collection.d.ts.map

package/dist/hooks/use-quadro-paged-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-quadro-paged-collection.d.ts","sourceRoot":"","sources":["../../src/hooks/use-quadro-paged-collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAGpF,MAAM,MAAM,4BAA4B,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAA;AAEjG,MAAM,MAAM,+BAA+B,CAAC,CAAC,IAAI;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,uGAAuG;IACvG,GAAG,EAAE,4BAA4B,CAAC,CAAC,CAAC,CAAA;CACrC,GAAG,IAAI,CACN,iBAAiB,EACjB,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,gBAAgB,GAAG,kBAAkB,CACpF,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,+BAA+B,CAAC,CAAC,CAAC,GAAG;IACxF,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CACvC,CAqFA"}

package/dist/hooks/use-quadro-paged-collection.mjs

@@ -0,0 +1,93 @@
+import { useEffect, useRef, useState } from 'react';
+/**
+ * Loads one page from a QuadroKit collection with 4D entity-set reuse (`$top=0` once, then
+ * `__ENTITYSET` paging). Calls `release()` on unmount only.
+ *
+ * Other list options (`select`, `filter`, …) are read from a ref so `page` / `pageSize` can stay
+ * stable deps without stale closures; change `entitySetResetKey` when filters change.
+ *
+ * **`collection`** is the current `CollectionHandle` (e.g. `getFirst`, `release`, async iteration).
+ * It is `null` until the first handle is created for the active load, then cleared when the load
+ * effect cleans up (page / deps change or unmount).
+ */
+export function useQuadroPagedCollection(options) {
+    const { page, pageSize, entitySetResetKey, all, ...listOptions } = options;
+    const resetKey = entitySetResetKey ?? pageSize;
+    const [rows, setRows] = useState([]);
+    const [hasNext, setHasNext] = useState(false);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [collection, setCollection] = useState(null);
+    const entitySetPathRef = useRef(null);
+    const releaseRef = useRef(null);
+    const prevResetKeyRef = useRef(resetKey);
+    const optsRef = useRef({ all, listOptions });
+    optsRef.current = { all, listOptions };
+    useEffect(() => {
+        if (prevResetKeyRef.current !== resetKey) {
+            entitySetPathRef.current = null;
+            prevResetKeyRef.current = resetKey;
+        }
+    }, [resetKey]);
+    useEffect(() => {
+        return () => {
+            void releaseRef.current?.();
+            releaseRef.current = null;
+            entitySetPathRef.current = null;
+        };
+    }, []);
+    useEffect(() => {
+        // In React 18+ dev + Strict Mode, effects run twice (cleanup aborts the first in-flight
+        // request). Production does not double-invoke; expect one `$top=0` + entity-set fetches.
+        // Re-run when `entitySetResetKey` / default `pageSize` changes (e.g. filters), not only page.
+        void resetKey;
+        const ac = new AbortController();
+        setLoading(true);
+        setError(null);
+        void (async () => {
+            const { all: create, listOptions: lo } = optsRef.current;
+            const col = create({
+                ...lo,
+                page,
+                pageSize,
+                maxItems: pageSize,
+                signal: ac.signal,
+                ...(entitySetPathRef.current != null ? { reuseEntitySet: entitySetPathRef.current } : {}),
+                onEntitySetReady: (path) => {
+                    entitySetPathRef.current = path;
+                },
+            });
+            releaseRef.current = () => col.release();
+            setCollection(col);
+            try {
+                const buffer = [];
+                for await (const row of col) {
+                    buffer.push(row);
+                    if (buffer.length >= pageSize)
+                        break;
+                }
+                if (ac.signal.aborted)
+                    return;
+                const slice = buffer.slice(0, pageSize);
+                setRows(slice);
+                setHasNext(slice.length === pageSize);
+            }
+            catch (e) {
+                if (ac.signal.aborted)
+                    return;
+                setError(e instanceof Error ? e.message : String(e));
+                setRows([]);
+                setHasNext(false);
+            }
+            finally {
+                if (!ac.signal.aborted)
+                    setLoading(false);
+            }
+        })();
+        return () => {
+            ac.abort();
+            setCollection(null);
+        };
+    }, [page, pageSize, resetKey]);
+    return { rows, hasNext, loading, error, collection };
+}

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { Label } from './components/label.js';
 export { ThemeToolbar } from './components/theme-toolbar.js';
 export type { UseDismissOnInteractOutsideOptions } from './hooks/use-dismiss-on-interact-outside.js';
 export { useDismissOnInteractOutside } from './hooks/use-dismiss-on-interact-outside.js';
+export type { QuadroPagedCollectionFactory, UseQuadroPagedCollectionOptions, } from './hooks/use-quadro-paged-collection.js';
+export { useQuadroPagedCollection } from './hooks/use-quadro-paged-collection.js';
 export { cn } from './lib/utils.js';
 export { type ColorMode, ThemeProvider, useTheme, } from './theme/theme-provider.js';
 export { type QuadroThemePreset, quadroThemes, themeLabels, } from './theme/themes.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EACL,IAAI,EACJ,WAAW,EACX,eAAe,EACf,UAAU,EACV,SAAS,GACV,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAC5D,YAAY,EAAE,kCAAkC,EAAE,MAAM,4CAA4C,CAAA;AACpG,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAA;AACxF,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAA;AACnC,OAAO,EACL,KAAK,SAAS,EACd,aAAa,EACb,QAAQ,GACT,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,KAAK,iBAAiB,EACtB,YAAY,EACZ,WAAW,GACZ,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EACL,IAAI,EACJ,WAAW,EACX,eAAe,EACf,UAAU,EACV,SAAS,GACV,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAC5D,YAAY,EAAE,kCAAkC,EAAE,MAAM,4CAA4C,CAAA;AACpG,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAA;AACxF,YAAY,EACV,4BAA4B,EAC5B,+BAA+B,GAChC,MAAM,wCAAwC,CAAA;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAA;AACjF,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAA;AACnC,OAAO,EACL,KAAK,SAAS,EACd,aAAa,EACb,QAAQ,GACT,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,KAAK,iBAAiB,EACtB,YAAY,EACZ,WAAW,GACZ,MAAM,mBAAmB,CAAA"}

package/dist/index.mjs

@@ -4,6 +4,7 @@ export { Input } from './components/input.mjs';
 export { Label } from './components/label.mjs';
 export { ThemeToolbar } from './components/theme-toolbar.mjs';
 export { useDismissOnInteractOutside } from './hooks/use-dismiss-on-interact-outside.mjs';
+export { useQuadroPagedCollection } from './hooks/use-quadro-paged-collection.mjs';
 export { cn } from './lib/utils.mjs';
 export { ThemeProvider, useTheme, } from './theme/theme-provider.mjs';
 export { quadroThemes, themeLabels, } from './theme/themes.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadrokit/ui",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.mjs",
@@ -34,10 +34,12 @@
     "tailwind-merge": "^3.5.0"
   },
   "peerDependencies": {
+    "@quadrokit/client": "workspace:*",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
   },
   "devDependencies": {
+    "@quadrokit/client": "workspace:*",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.4",