@quadrokit/ui 0.3.11 → 0.3.13

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

@@ -1,4 +1,5 @@
-import type { CollectionHandle, CollectionOptions } from '@quadrokit/client/runtime';
+import type { CollectionHandle, CollectionOptions, QuadroErrorEvent, QuadroSuccessEvent } from '@quadrokit/client/runtime';
+import { QuadroHttpErrorKind } from '../lib/quadro-http-error-kind.js';
 export type QuadroPagedCollectionFactory<T> = (options: CollectionOptions) => CollectionHandle<T>;
 export type UseQuadroPagedCollectionOptions<T> = {
     page: number;
@@ -11,6 +12,10 @@ export type UseQuadroPagedCollectionOptions<T> = {
     entitySetResetKey?: unknown;
     /** Pass `quadro.SomeClass.all` (or wrap it); use a cast at the call site if `select` is path-typed. */
     all: QuadroPagedCollectionFactory<T>;
+    /** Fires when the page of rows finished loading; `event.body` is the row slice. */
+    onSuccess?: (event: QuadroSuccessEvent) => void;
+    /** Fires when iteration fails; same shape as the client {@link QuadroErrorEvent}. */
+    onError?: (event: QuadroErrorEvent) => void;
 } & Omit<CollectionOptions, 'page' | 'pageSize' | 'maxItems' | 'signal' | 'reuseEntitySet' | 'onEntitySetReady'>;
 /**
  * Loads one page from a QuadroKit collection with 4D entity-set reuse (`$top=0` once, then
@@ -28,6 +33,14 @@ export declare function useQuadroPagedCollection<T>(options: UseQuadroPagedColle
     hasNext: boolean;
     loading: boolean;
     error: string | null;
+    /**
+     * When the failure is tied to an HTTP status (including list/collection errors), a stable
+     * semantic bucket (e.g. {@link QuadroHttpErrorKind.UNAUTHENTICATED} for 401).
+     * {@link QuadroHttpErrorKind.UNKNOWN} when there is no error or status could not be mapped.
+     */
+    errorKind: QuadroHttpErrorKind;
+    /** HTTP status code when known; `null` for non-HTTP errors. */
+    httpStatus: number | null;
     collection: CollectionHandle<T> | null;
 };
 //# sourceMappingURL=use-quadro-paged-collection.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"use-quadro-paged-collection.d.ts","sourceRoot":"","sources":["../../src/hooks/use-quadro-paged-collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,mBAAmB,EAEpB,MAAM,kCAAkC,CAAA;AAMzC,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;IACpC,mFAAmF;IACnF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC/C,qFAAqF;IACrF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;CAC5C,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;;;;OAIG;IACH,SAAS,EAAE,mBAAmB,CAAA;IAC9B,+DAA+D;IAC/D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CACvC,CA4HA"}

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

@@ -1,4 +1,8 @@
 import { useEffect, useRef, useState } from 'react';
+import { QuadroHttpErrorKind, quadroErrorKindFromUnknown, } from '../lib/quadro-http-error-kind.mjs';
+function newPagedLoadOperationId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
 /**
  * Loads one page from a QuadroKit collection with 4D entity-set reuse (`$top=0` once, then
  * `__ENTITYSET` paging). Calls `release()` on unmount only.
@@ -11,12 +15,18 @@ import { useEffect, useRef, useState } from 'react';
  * effect cleans up (page / deps change or unmount).
  */
 export function useQuadroPagedCollection(options) {
-    const { page, pageSize, entitySetResetKey, all, ...listOptions } = options;
+    const { page, pageSize, entitySetResetKey, all, onSuccess, onError, ...listOptions } = options;
     const resetKey = entitySetResetKey ?? pageSize;
+    const onSuccessRef = useRef(onSuccess);
+    const onErrorRef = useRef(onError);
+    onSuccessRef.current = onSuccess;
+    onErrorRef.current = onError;
     const [rows, setRows] = useState([]);
     const [hasNext, setHasNext] = useState(false);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
+    const [errorKind, setErrorKind] = useState(QuadroHttpErrorKind.UNKNOWN);
+    const [httpStatus, setHttpStatus] = useState(null);
     const [collection, setCollection] = useState(null);
     const entitySetPathRef = useRef(null);
     const releaseRef = useRef(null);
@@ -44,7 +54,11 @@ export function useQuadroPagedCollection(options) {
         const ac = new AbortController();
         setLoading(true);
         setError(null);
+        setErrorKind(QuadroHttpErrorKind.UNKNOWN);
+        setHttpStatus(null);
         void (async () => {
+            const loadStarted = Date.now();
+            const operationId = newPagedLoadOperationId();
             const { all: create, listOptions: lo } = optsRef.current;
             const col = create({
                 ...lo,
@@ -71,13 +85,41 @@ export function useQuadroPagedCollection(options) {
                 const slice = buffer.slice(0, pageSize);
                 setRows(slice);
                 setHasNext(slice.length === pageSize);
+                onSuccessRef.current?.({
+                    type: 'success',
+                    operationId,
+                    context: {
+                        operation: 'collection.list',
+                        attributes: { page, pageSize },
+                    },
+                    path: '',
+                    durationMs: Date.now() - loadStarted,
+                    body: slice,
+                });
             }
             catch (e) {
                 if (ac.signal.aborted)
                     return;
-                setError(e instanceof Error ? e.message : String(e));
+                const { kind, httpStatus: st } = quadroErrorKindFromUnknown(e);
+                setErrorKind(kind);
+                setHttpStatus(st);
+                const message = e instanceof Error ? e.message : String(e);
+                setError(message);
                 setRows([]);
                 setHasNext(false);
+                onErrorRef.current?.({
+                    type: 'error',
+                    operationId,
+                    context: {
+                        operation: 'collection.list',
+                        attributes: { page, pageSize },
+                    },
+                    path: '',
+                    durationMs: Date.now() - loadStarted,
+                    message,
+                    error: e,
+                    status: st ?? undefined,
+                });
             }
             finally {
                 if (!ac.signal.aborted)
@@ -89,5 +131,5 @@ export function useQuadroPagedCollection(options) {
             setCollection(null);
         };
     }, [page, pageSize, resetKey]);
-    return { rows, hasNext, loading, error, collection };
+    return { rows, hasNext, loading, error, errorKind, httpStatus, collection };
 }

package/dist/index.d.ts

@@ -6,7 +6,9 @@ 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 type { QuadroErrorEvent, QuadroSuccessEvent } from '@quadrokit/client/runtime';
 export { useQuadroPagedCollection } from './hooks/use-quadro-paged-collection.js';
+export { QuadroHttpErrorKind, quadroErrorKindFromUnknown, quadroHttpStatusToErrorKind, } from './lib/quadro-http-error-kind.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,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"}
+{"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,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAA;AACjF,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,iCAAiC,CAAA;AACxC,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

@@ -5,6 +5,7 @@ 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 { QuadroHttpErrorKind, quadroErrorKindFromUnknown, quadroHttpStatusToErrorKind, } from './lib/quadro-http-error-kind.mjs';
 export { cn } from './lib/utils.mjs';
 export { ThemeProvider, useTheme, } from './theme/theme-provider.mjs';
 export { quadroThemes, themeLabels, } from './theme/themes.mjs';

package/dist/lib/quadro-http-error-kind.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Semantic category for HTTP failures from the Quadro REST client and collection layer.
+ * Use with {@link quadroHttpStatusToErrorKind} or {@link quadroErrorKindFromUnknown}.
+ */
+export declare enum QuadroHttpErrorKind {
+    /** Status could not be determined, or error is not HTTP-related (e.g. network). */
+    UNKNOWN = "UNKNOWN",
+    BAD_REQUEST = "BAD_REQUEST",
+    /** 401 — missing or invalid authentication. */
+    UNAUTHENTICATED = "UNAUTHENTICATED",
+    /** 403 — authenticated but not permitted for this resource. */
+    FORBIDDEN = "FORBIDDEN",
+    NOT_FOUND = "NOT_FOUND",
+    METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED",
+    CONFLICT = "CONFLICT",
+    UNPROCESSABLE_ENTITY = "UNPROCESSABLE_ENTITY",
+    TOO_MANY_REQUESTS = "TOO_MANY_REQUESTS",
+    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR",
+    BAD_GATEWAY = "BAD_GATEWAY",
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    GATEWAY_TIMEOUT = "GATEWAY_TIMEOUT"
+}
+export declare function quadroHttpStatusToErrorKind(status: number): QuadroHttpErrorKind;
+/**
+ * Derive HTTP status and {@link QuadroHttpErrorKind} from a thrown value.
+ * Handles {@link QuadroHttpError} and plain `Error` messages from the collection runtime.
+ */
+export declare function quadroErrorKindFromUnknown(error: unknown): {
+    kind: QuadroHttpErrorKind;
+    httpStatus: number | null;
+};
+//# sourceMappingURL=quadro-http-error-kind.d.ts.map

package/dist/lib/quadro-http-error-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadro-http-error-kind.d.ts","sourceRoot":"","sources":["../../src/lib/quadro-http-error-kind.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,oBAAY,mBAAmB;IAC7B,mFAAmF;IACnF,OAAO,YAAY;IACnB,WAAW,gBAAgB;IAC3B,+CAA+C;IAC/C,eAAe,oBAAoB;IACnC,+DAA+D;IAC/D,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,kBAAkB,uBAAuB;IACzC,QAAQ,aAAa;IACrB,oBAAoB,yBAAyB;IAC7C,iBAAiB,sBAAsB;IACvC,qBAAqB,0BAA0B;IAC/C,WAAW,gBAAgB;IAC3B,mBAAmB,wBAAwB;IAC3C,eAAe,oBAAoB;CACpC;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAc/E;AAKD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG;IAC1D,IAAI,EAAE,mBAAmB,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,CAoBA"}

package/dist/lib/quadro-http-error-kind.mjs

@@ -0,0 +1,78 @@
+import { QuadroHttpError } from '@quadrokit/client/runtime';
+/**
+ * Semantic category for HTTP failures from the Quadro REST client and collection layer.
+ * Use with {@link quadroHttpStatusToErrorKind} or {@link quadroErrorKindFromUnknown}.
+ */
+export var QuadroHttpErrorKind;
+(function (QuadroHttpErrorKind) {
+    /** Status could not be determined, or error is not HTTP-related (e.g. network). */
+    QuadroHttpErrorKind["UNKNOWN"] = "UNKNOWN";
+    QuadroHttpErrorKind["BAD_REQUEST"] = "BAD_REQUEST";
+    /** 401 — missing or invalid authentication. */
+    QuadroHttpErrorKind["UNAUTHENTICATED"] = "UNAUTHENTICATED";
+    /** 403 — authenticated but not permitted for this resource. */
+    QuadroHttpErrorKind["FORBIDDEN"] = "FORBIDDEN";
+    QuadroHttpErrorKind["NOT_FOUND"] = "NOT_FOUND";
+    QuadroHttpErrorKind["METHOD_NOT_ALLOWED"] = "METHOD_NOT_ALLOWED";
+    QuadroHttpErrorKind["CONFLICT"] = "CONFLICT";
+    QuadroHttpErrorKind["UNPROCESSABLE_ENTITY"] = "UNPROCESSABLE_ENTITY";
+    QuadroHttpErrorKind["TOO_MANY_REQUESTS"] = "TOO_MANY_REQUESTS";
+    QuadroHttpErrorKind["INTERNAL_SERVER_ERROR"] = "INTERNAL_SERVER_ERROR";
+    QuadroHttpErrorKind["BAD_GATEWAY"] = "BAD_GATEWAY";
+    QuadroHttpErrorKind["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    QuadroHttpErrorKind["GATEWAY_TIMEOUT"] = "GATEWAY_TIMEOUT";
+})(QuadroHttpErrorKind || (QuadroHttpErrorKind = {}));
+export function quadroHttpStatusToErrorKind(status) {
+    if (status === 400)
+        return QuadroHttpErrorKind.BAD_REQUEST;
+    if (status === 401)
+        return QuadroHttpErrorKind.UNAUTHENTICATED;
+    if (status === 403)
+        return QuadroHttpErrorKind.FORBIDDEN;
+    if (status === 404)
+        return QuadroHttpErrorKind.NOT_FOUND;
+    if (status === 405)
+        return QuadroHttpErrorKind.METHOD_NOT_ALLOWED;
+    if (status === 409)
+        return QuadroHttpErrorKind.CONFLICT;
+    if (status === 422)
+        return QuadroHttpErrorKind.UNPROCESSABLE_ENTITY;
+    if (status === 429)
+        return QuadroHttpErrorKind.TOO_MANY_REQUESTS;
+    if (status === 500)
+        return QuadroHttpErrorKind.INTERNAL_SERVER_ERROR;
+    if (status === 502)
+        return QuadroHttpErrorKind.BAD_GATEWAY;
+    if (status === 503)
+        return QuadroHttpErrorKind.SERVICE_UNAVAILABLE;
+    if (status === 504)
+        return QuadroHttpErrorKind.GATEWAY_TIMEOUT;
+    return QuadroHttpErrorKind.UNKNOWN;
+}
+const ENTITY_SET_FAILED = /Entity set creation failed (\d+):/;
+const LIST_FAILED = /List failed (\d+):/;
+/**
+ * Derive HTTP status and {@link QuadroHttpErrorKind} from a thrown value.
+ * Handles {@link QuadroHttpError} and plain `Error` messages from the collection runtime.
+ */
+export function quadroErrorKindFromUnknown(error) {
+    if (error instanceof QuadroHttpError) {
+        return {
+            httpStatus: error.status,
+            kind: quadroHttpStatusToErrorKind(error.status),
+        };
+    }
+    if (error instanceof Error) {
+        const m1 = ENTITY_SET_FAILED.exec(error.message);
+        if (m1) {
+            const status = Number(m1[1]);
+            return { httpStatus: status, kind: quadroHttpStatusToErrorKind(status) };
+        }
+        const m2 = LIST_FAILED.exec(error.message);
+        if (m2) {
+            const status = Number(m2[1]);
+            return { httpStatus: status, kind: quadroHttpStatusToErrorKind(status) };
+        }
+    }
+    return { kind: QuadroHttpErrorKind.UNKNOWN, httpStatus: null };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadrokit/ui",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "private": false,
   "type": "module",
   "main": "./dist/index.mjs",
@@ -34,7 +34,7 @@
     "tailwind-merge": "^3.5.0"
   },
   "peerDependencies": {
-    "@quadrokit/client": "^0.3.11",
+    "@quadrokit/client": "^0.3.13",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
   },