@lotics/app-sdk 0.26.0 → 0.28.0

package/dist/src/comments.js

@@ -24,6 +24,7 @@ import { useCallback } from "react";
 import useSWR from "swr";
 import { rpc } from "./rpc.js";
 import { captureAppEvent } from "./analytics.js";
+import { useAppContext } from "./viewer.js";
 /** The reduced storage shape the update endpoint accepts for `files`. */
 function toStorageFiles(files) {
     return (files ?? []).map((f) => ({
@@ -33,24 +34,6 @@ function toStorageFiles(files) {
         mime_type: f.mime_type,
     }));
 }
-/**
- * Read the app's context once, shared across every hook via a stable SWR key.
- * Comments need a signed-in member (members-only) AND the app's declared
- * `comments` capability — both come from here.
- */
-function useAppContext() {
-    const { data } = useSWR("app-context", () => rpc("context", {}), {
-        revalidateOnFocus: false,
-        revalidateIfStale: false,
-        revalidateOnReconnect: false,
-        shouldRetryOnError: false,
-    });
-    return {
-        memberId: data?.member_id ?? null,
-        commentsEnabled: data?.comments_enabled ?? false,
-        resolved: data !== undefined,
-    };
-}
 let optimisticCounter = 0;
 /**
  * ```tsx

package/dist/src/hooks.d.ts

@@ -1,7 +1,7 @@
 import type { AppWorkflows, AppQueries } from "./types.js";
 import type { ResolvedMember } from "./members.js";
-interface QueryState<R> {
-    rows: R[];
+/** Fields shared by every query hook's return value. */
+interface QueryStateBase {
     /**
      * True only on the initial load — a request is in flight and there are no
      * rows yet. Stays false during background revalidation and while typing a new
@@ -13,14 +13,22 @@ interface QueryState<R> {
     isValidating: boolean;
     error: string | null;
     /**
-     * Re-run the query from the first page. Use after a known mutation point —
-     * a successful `useWorkflow(alias)()` call — to pull the latest state.
+     * Re-run the query. Use after a known mutation point — a successful
+     * `useWorkflow(alias)()` call — to pull the latest state.
      */
     refetch: () => void;
+}
+/** Return value of `useQuery` — a single fetch, no pagination. */
+interface QueryState<R> extends QueryStateBase {
+    rows: R[];
+}
+/** Return value of `useInfiniteQuery` — append/load-more. */
+interface InfiniteQueryState<R> extends QueryStateBase {
+    /** All loaded pages, flattened and accumulated. */
+    rows: R[];
     /**
-     * Fetch the next page and append it to `rows`. No-op when `pageSize` was not
-     * set or there are no more rows (`hasMore` is false). `loadingMore` is true
-     * while it runs.
+     * Fetch the next page and append it to `rows`. No-op when there are no more
+     * rows (`hasMore` is false). `loadingMore` is true while it runs.
      */
     loadMore: () => void;
     /** True when the last page came back full, so more rows may exist. */
@@ -28,6 +36,23 @@ interface QueryState<R> {
     /** True while a `loadMore` request is in flight. */
     loadingMore: boolean;
 }
+/** Return value of `usePaginatedQuery` — page-model with a total. */
+interface PaginatedQueryState<R> extends QueryStateBase {
+    /** Rows of the current page only (≤ `pageSize`). */
+    rows: R[];
+    /** Total rows in the filtered set (across all pages). `undefined` until the
+     *  count resolves. */
+    total: number | undefined;
+    /** `ceil(total / pageSize)`, or `undefined` until the count resolves. */
+    totalPages: number | undefined;
+    /** Current 0-indexed page. */
+    page: number;
+    pageSize: number;
+    /** True when a next page exists. */
+    hasMore: boolean;
+    /** Jump to a page (0-indexed). Clamped at 0. */
+    setPage: (page: number) => void;
+}
 /**
  * One sort key — the wire shape of the query RPC's `sort`. The server applies
  * these AFTER the named query, bounded to the query's output columns (an
@@ -55,17 +80,11 @@ export interface QueryFilterGroup {
 /**
  * Runtime filter applied AFTER the named query, bounded to its output columns
  * (same exposure invariant as `sort`). Build a group from per-column filters
- * with `columnFilterToConditions` (`@lotics/ui/grid/column_filter`).
+ * with `columnFilterToConditions` (`@lotics/ui/column_filter`).
  */
 export type QueryFilter = QueryFilterCondition | QueryFilterGroup;
-/** Options for `useQuery`. */
-export interface QueryOptions {
-    /**
-     * Page size. Omit to fetch all rows in one request (the server still caps
-     * the maximum). Set it to paginate: the first render loads one page, and
-     * `loadMore()` appends the next.
-     */
-    pageSize?: number;
+/** Options shared by every query hook. */
+export interface BaseQueryOptions {
     /**
      * When `false`, the query does not run: `rows` stays empty, `loading` is
      * false, and no request is sent. Flip it back to `true` to fetch. This is the
@@ -94,6 +113,22 @@ export interface QueryOptions {
      */
     filter?: QueryFilter;
 }
+/** Options for `useQuery` — a single fetch. */
+export interface QueryOptions extends BaseQueryOptions {
+    /** Max rows to fetch in the one request (a cap, not pagination). The server
+     *  still clamps to its own maximum. Omit to fetch up to the server cap. */
+    pageSize?: number;
+}
+/** Options for `useInfiniteQuery` — append/load-more. */
+export interface InfiniteQueryOptions extends BaseQueryOptions {
+    /** Rows per page. `loadMore()` appends the next page. */
+    pageSize: number;
+}
+/** Options for `usePaginatedQuery` — page-model with a total. */
+export interface PaginatedQueryOptions extends BaseQueryOptions {
+    /** Rows per page. Default 25. */
+    pageSize?: number;
+}
 /**
  * Trigger a workflow by alias from the app's manifest.
  *
@@ -128,9 +163,11 @@ export interface WorkflowResult {
     message?: string;
     files?: UploadedFile[];
 }
-type UseQueryArgs<K extends keyof AppQueries & string> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: QueryOptions] : [params: AppQueries[K], opts?: QueryOptions];
+type QueryArgs<K extends keyof AppQueries & string, O> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: O] : [params: AppQueries[K], opts?: O];
 /**
- * Read rows from a query the app's author declared in `lotics.queries`.
+ * Read rows from a query the app's author declared in `lotics.queries` — a
+ * single fetch, no pagination. For long lists use `usePaginatedQuery`
+ * (numbered pages + total) or `useInfiniteQuery` (load-more).
  *
  * The app never sends a raw query AST — it invokes a named query by alias and
  * fills the template's declared `{{params.x}}` value holes. The server holds
@@ -145,8 +182,35 @@ type UseQueryArgs<K extends keyof AppQueries & string> = AppQueries[K] extends R
  * with the declared alias → param-type map, so an undeclared alias is a
  * compile-time error and params are typed per the manifest.
  */
-export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...args: UseQueryArgs<K>): QueryState<Record<string, unknown>>;
+export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, QueryOptions>): QueryState<Record<string, unknown>>;
 export declare function useQuery(alias: string, params?: Record<string, unknown>, opts?: QueryOptions): QueryState<Record<string, unknown>>;
+/**
+ * Like `useQuery` but append/load-more: the first render loads one page and
+ * `loadMore()` appends the next, accumulating into `rows` (infinite scroll).
+ * For numbered pages + a total, use `usePaginatedQuery`.
+ *
+ * ```tsx
+ * const { rows, loadMore, hasMore } = useInfiniteQuery("feed", {}, { pageSize: 30 });
+ * ```
+ */
+export declare function useInfiniteQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions>): InfiniteQueryState<Record<string, unknown>>;
+export declare function useInfiniteQuery(alias: string, params?: Record<string, unknown>, opts?: InfiniteQueryOptions): InfiniteQueryState<Record<string, unknown>>;
+/**
+ * Page-model query with a total — the data hook behind a numbered, jumpable
+ * table (`@lotics/ui/table_picker`, `@lotics/ui/pagination`). It owns the page
+ * cursor and fetches two things: the current page of rows, and a `count` over
+ * the filtered set (keyed independently of page + sort, so paging and
+ * re-sorting never recount). The `(params, filter)` tuple is the result-set
+ * identity: changing it resets to page 0 AND recounts; changing only `sort`
+ * does neither.
+ *
+ * ```tsx
+ * const { rows, total, page, setPage, hasMore } =
+ *   usePaginatedQuery("orders", { q }, { pageSize: 25, sort, filter });
+ * ```
+ */
+export declare function usePaginatedQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions>): PaginatedQueryState<Record<string, unknown>>;
+export declare function usePaginatedQuery(alias: string, params?: Record<string, unknown>, opts?: PaginatedQueryOptions): PaginatedQueryState<Record<string, unknown>>;
 /** A file the host has stored and resolved serving URLs for. */
 export interface UploadedFile {
     id: string;

package/dist/src/hooks.js

@@ -1,20 +1,22 @@
 /**
  * Typed React hooks for Lotics app data access.
  *
- * The SDK surface is three hooks: `useQuery` for reads, `useWorkflow` for
- * every mutation, and `useFileUpload` for attaching files. App code never
- * writes records directly — all writes flow through declared workflows, which
- * gives the app owner a typed, audited chokepoint and means a publicly-shared
- * app exposes no anonymous direct-write path. An uploaded file is inert until
- * a workflow attaches it, so file upload keeps that same property.
+ * Reads come in three shapes — `useQuery` (single fetch), `useInfiniteQuery`
+ * (append / load-more), and `usePaginatedQuery` (numbered pages + total) — and
+ * every mutation is a `useWorkflow`; `useFileUpload` attaches files. App code
+ * never writes records directly — all writes flow through declared workflows,
+ * which gives the app owner a typed, audited chokepoint and means a
+ * publicly-shared app exposes no anonymous direct-write path. An uploaded file
+ * is inert until a workflow attaches it, so file upload keeps that same property.
  *
  * Every hook is a thin wrapper over the postMessage RPC bridge — the parent
- * does the actual API calls, results stream back through `rpc()`. `useQuery`
- * caches through SWR keyed by (alias, params, pageSize): reads dedupe and the
+ * does the actual API calls, results stream back through `rpc()`. The read
+ * hooks cache through SWR keyed by (alias, params, …): reads dedupe and the
  * cache survives unmount/remount. Mutation / member hooks keep their own local
  * `useState` — they have nothing to share.
  */
 import { useCallback, useEffect, useState } from "react";
+import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
 import { rpc } from "./rpc.js";
 import { getMockRows } from "./mock.js";
@@ -32,31 +34,62 @@ export function useWorkflow(alias) {
         }
     }, [alias]);
 }
+// Shared SWR config: surface a failed query immediately, keep the last good
+// rows (no retry loop that masks the error), and honor the focus/reconnect
+// opt-out.
+function swrConfig(revalidateOnFocus) {
+    return {
+        revalidateOnFocus,
+        revalidateOnReconnect: revalidateOnFocus,
+        shouldRetryOnError: false,
+    };
+}
 export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
     const enabled = opts?.enabled ?? true;
     const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
     const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
     const filter = opts?.filter;
-    // A registered fixture short-circuits the network in mock / dev mode.
     const mockRows = getMockRows(alias);
-    // The cache key is (alias, params, pageSize, pageIndex), built HERE so an app
-    // never constructs a key — it just calls `useQuery("hoSo")`. SWR canonicalizes
-    // the params object via its stable hash, so every `useQuery` with the same
-    // (alias, params, pageSize) dedupes to one request and one shared cache entry,
-    // and that entry survives unmount/remount — navigating back to a screen shows
-    // cached rows instantly and revalidates in the background (no flash). A `null`
-    // key disables the fetch (mock / disabled / past the last page).
+    // A `null` key disables the fetch (mock / disabled). SWR canonicalizes the
+    // params/sort/filter objects via its stable hash, so identical reads dedupe to
+    // one request + one cache entry that survives unmount/remount.
+    const key = mockRows || !enabled
+        ? null
+        : ["app-query", alias, params ?? {}, pageSize ?? null, sort ?? null, filter ?? null];
+    const swr = useSWR(key, () => rpc("query", {
+        alias,
+        params: params ?? {},
+        limit: pageSize,
+        offset: 0,
+        sort,
+        filter,
+    }), swrConfig(revalidateOnFocus));
+    const refetch = useCallback(() => {
+        void swr.mutate();
+    }, [swr]);
+    return {
+        rows: mockRows ?? swr.data?.rows ?? [],
+        loading: mockRows ? false : swr.isLoading,
+        isValidating: mockRows ? false : swr.isValidating,
+        error: swr.error ? swr.error.message : null,
+        refetch,
+    };
+}
+export function useInfiniteQuery(alias, params, opts) {
+    const pageSize = opts?.pageSize ?? 30;
+    const enabled = opts?.enabled ?? true;
+    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
+    const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
+    const filter = opts?.filter;
+    const mockRows = getMockRows(alias);
     const getKey = (index, prev) => {
         if (mockRows || !enabled)
             return null;
-        // Non-paginated has only page 0; paginated stops once a short page returns.
-        if (index > 0 && (pageSize == null || prev == null || prev.rows.length < pageSize)) {
+        // Stop once a short page returns.
+        if (index > 0 && (prev == null || prev.rows.length < pageSize))
             return null;
-        }
-        // sort/filter join the key so a re-sort or re-filter is a distinct cache
-        // entry — SWR refetches instead of serving the previous order/subset.
-        return ["app-query", alias, params ?? {}, pageSize ?? null, sort ?? null, filter ?? null, index];
+        return ["app-query-infinite", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, index];
     };
     const swr = useSWRInfinite(getKey, (key) => {
         const index = Number(key[6]);
@@ -64,42 +97,29 @@ export function useQuery(alias, params, opts) {
             alias,
             params: params ?? {},
             limit: pageSize,
-            offset: pageSize != null ? index * pageSize : 0,
+            offset: index * pageSize,
             sort,
             filter,
         });
-    }, {
-        // loadMore appends pages — don't re-fetch earlier pages when `size` grows.
-        revalidateFirstPage: false,
-        // The opt-out covers focus AND reconnect, per the documented contract.
-        revalidateOnFocus,
-        revalidateOnReconnect: revalidateOnFocus,
-        // Surface a failed query immediately and keep the last good rows — no
-        // silent retry loop that would mask the error from the app.
-        shouldRetryOnError: false,
-    });
-    // SWRInfinite leaves an in-flight page slot `undefined` until it resolves
-    // (the typed `QueryPage[]` understates this) — operate on resolved pages only,
-    // so a page being appended never crashes the flatten or skews the counts.
+    }, { revalidateFirstPage: false, ...swrConfig(revalidateOnFocus) });
+    // SWRInfinite leaves an in-flight page slot `undefined` until it resolves —
+    // operate on resolved pages only so a page being appended never crashes the
+    // flatten or skews the counts.
     const pages = (swr.data ?? []).filter((p) => p != null);
     const rows = mockRows ?? pages.flatMap((p) => p.rows ?? []);
     const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
-    const hasMore = pageSize != null && lastPage != null && (lastPage.rows?.length ?? 0) === pageSize;
-    // Appending a page: more pages are requested than have resolved.
+    const hasMore = lastPage != null && (lastPage.rows?.length ?? 0) === pageSize;
     const loadingMore = swr.isValidating && swr.size > pages.length;
     const refetch = useCallback(() => {
         void swr.mutate();
     }, [swr]);
     const loadMore = useCallback(() => {
-        if (pageSize == null || !hasMore || loadingMore)
+        if (!hasMore || loadingMore)
             return;
         void swr.setSize((n) => n + 1);
-    }, [pageSize, hasMore, loadingMore, swr]);
+    }, [hasMore, loadingMore, swr]);
     return {
         rows,
-        // `loading` = initial load (validating with nothing to show yet);
-        // `isValidating` = any request in flight. Gating a skeleton on `loading`
-        // never flashes on revalidation; use `isValidating` for a subtle indicator.
         loading: mockRows ? false : swr.isLoading,
         isValidating: mockRows ? false : swr.isValidating,
         error: swr.error ? swr.error.message : null,
@@ -109,6 +129,61 @@ export function useQuery(alias, params, opts) {
         loadingMore,
     };
 }
+export function usePaginatedQuery(alias, params, opts) {
+    const pageSize = opts?.pageSize ?? 25;
+    const enabled = opts?.enabled ?? true;
+    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
+    const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
+    const filter = opts?.filter;
+    const mockRows = getMockRows(alias);
+    // The result-set identity. When it changes, `page` derives back to 0 (not via
+    // an effect, so the stale page never fires a wasted fetch) and the count key
+    // changes (recount). `setPage` re-stamps the current identity.
+    const resetKey = JSON.stringify([params ?? {}, filter ?? null]);
+    const [pageState, setPageState] = useState({ key: resetKey, page: 0 });
+    const page = pageState.key === resetKey ? pageState.page : 0;
+    const setPage = useCallback((p) => setPageState({ key: resetKey, page: Math.max(0, p) }), [resetKey]);
+    const rowsKey = mockRows || !enabled
+        ? null
+        : ["app-query-page", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, page];
+    const rowsSwr = useSWR(rowsKey, () => rpc("query", {
+        alias,
+        params: params ?? {},
+        limit: pageSize,
+        offset: page * pageSize,
+        sort,
+        filter,
+    }), 
+    // Keep the previous page's rows on screen while the next page loads.
+    { keepPreviousData: true, ...swrConfig(revalidateOnFocus) });
+    // Count key omits page AND sort — one count per result-set identity, reused
+    // across page clicks and re-sorts.
+    const countKey = mockRows || !enabled
+        ? null
+        : ["app-query-count", alias, params ?? {}, filter ?? null];
+    const countSwr = useSWR(countKey, () => rpc("query", { alias, params: params ?? {}, filter, count: true }), swrConfig(revalidateOnFocus));
+    const rows = mockRows ?? rowsSwr.data?.rows ?? [];
+    const total = mockRows ? mockRows.length : countSwr.data?.total;
+    const totalPages = total != null ? Math.max(1, Math.ceil(total / pageSize)) : undefined;
+    const hasMore = total != null ? (page + 1) * pageSize < total : rows.length === pageSize;
+    const refetch = useCallback(() => {
+        void rowsSwr.mutate();
+        void countSwr.mutate();
+    }, [rowsSwr, countSwr]);
+    return {
+        rows,
+        total,
+        totalPages,
+        page,
+        pageSize,
+        hasMore,
+        setPage,
+        loading: mockRows ? false : rowsSwr.isLoading,
+        isValidating: mockRows ? false : rowsSwr.isValidating || countSwr.isValidating,
+        error: rowsSwr.error?.message ?? countSwr.error?.message ?? null,
+        refetch,
+    };
+}
 /**
  * Upload files from an app. The bytes are stored via a presigned
  * direct-to-storage upload the host mediates; the API server never proxies

package/dist/src/index.d.ts

@@ -16,10 +16,11 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
-export type { UploadedFile, QueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
+export type { UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, } from "./hooks.js";
 export { useComments } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs } from "./comments.js";
+export { useViewer } from "./viewer.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";

package/dist/src/index.js

@@ -15,8 +15,9 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
 export { useComments } from "./comments.js";
+export { useViewer } from "./viewer.js";
 export { rpc } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { readMembers } from "./members.js";

package/dist/src/viewer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read the app's context once, shared across every hook via a stable SWR key.
+ * The host (the product iframe, or `lotics app dev`) supplies the signed-in
+ * member and the app's declared capabilities.
+ */
+export declare function useAppContext(): {
+    memberId: string | null;
+    commentsEnabled: boolean;
+    resolved: boolean;
+};
+/**
+ * The signed-in member currently viewing the app — the **view-as target** under
+ * an admin's "View as" (product UI or `lotics app dev --view-as`), the
+ * authenticated member otherwise, and `null` for a public/standalone visitor or
+ * until the context resolves (gate viewer-dependent UI on `loading`).
+ *
+ * Use it to personalize (greet the member, default an assignment to them) or to
+ * pass the viewer into a workflow that must attribute to them. **Per-row data
+ * scoping does NOT need this** — put an `is_current_member` filter in the query
+ * template and the server resolves it to the same member (honoring view-as).
+ */
+export declare function useViewer(): {
+    memberId: string | null;
+    loading: boolean;
+};

package/dist/src/viewer.js

@@ -0,0 +1,35 @@
+import useSWR from "swr";
+import { rpc } from "./rpc.js";
+/**
+ * Read the app's context once, shared across every hook via a stable SWR key.
+ * The host (the product iframe, or `lotics app dev`) supplies the signed-in
+ * member and the app's declared capabilities.
+ */
+export function useAppContext() {
+    const { data } = useSWR("app-context", () => rpc("context", {}), {
+        revalidateOnFocus: false,
+        revalidateIfStale: false,
+        revalidateOnReconnect: false,
+        shouldRetryOnError: false,
+    });
+    return {
+        memberId: data?.member_id ?? null,
+        commentsEnabled: data?.comments_enabled ?? false,
+        resolved: data !== undefined,
+    };
+}
+/**
+ * The signed-in member currently viewing the app — the **view-as target** under
+ * an admin's "View as" (product UI or `lotics app dev --view-as`), the
+ * authenticated member otherwise, and `null` for a public/standalone visitor or
+ * until the context resolves (gate viewer-dependent UI on `loading`).
+ *
+ * Use it to personalize (greet the member, default an assignment to them) or to
+ * pass the viewer into a workflow that must attribute to them. **Per-row data
+ * scoping does NOT need this** — put an `is_current_member` filter in the query
+ * template and the server resolves it to the same member (honoring view-as).
+ */
+export function useViewer() {
+    const ctx = useAppContext();
+    return { memberId: ctx.memberId, loading: !ctx.resolved };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {