@lotics/app-sdk 0.24.0 → 0.25.0

package/dist/src/hooks.d.ts

@@ -28,6 +28,36 @@ interface QueryState<R> {
     /** True while a `loadMore` request is in flight. */
     loadingMore: boolean;
 }
+/**
+ * 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
+ * un-projected `field_key` is rejected), so an app can sort by any column it
+ * actually selects without the query template declaring it.
+ */
+export interface QuerySortKey {
+    field_key: string;
+    order: "asc" | "desc";
+}
+/** A filter condition over one output column (wire shape of a filter node). */
+export interface QueryFilterCondition {
+    node_type: "condition";
+    field_key: string;
+    type?: string;
+    operator: string;
+    value?: unknown;
+}
+/** A boolean group of filter nodes (wire shape — recursive). */
+export interface QueryFilterGroup {
+    node_type: "group";
+    logic: "and" | "or";
+    children: Array<QueryFilterCondition | 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`).
+ */
+export type QueryFilter = QueryFilterCondition | QueryFilterGroup;
 /** Options for `useQuery`. */
 export interface QueryOptions {
     /**
@@ -53,6 +83,16 @@ export interface QueryOptions {
      * re-run is wasted work and a visible reload.
      */
     revalidateOnFocus?: boolean;
+    /**
+     * Sort the result by output columns at runtime. Changing it re-queries (it is
+     * part of the cache key). Empty/omitted leaves the query's own order intact.
+     */
+    sort?: QuerySortKey[];
+    /**
+     * Filter the result by output columns at runtime. Changing it re-queries.
+     * Compose from per-column UI filters via `columnFilterToConditions`.
+     */
+    filter?: QueryFilter;
 }
 /**
  * Trigger a workflow by alias from the app's manifest.

package/dist/src/hooks.js

@@ -36,6 +36,8 @@ 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
@@ -52,15 +54,19 @@ export function useQuery(alias, params, opts) {
         if (index > 0 && (pageSize == null || prev == null || prev.rows.length < pageSize)) {
             return null;
         }
-        return ["app-query", alias, params ?? {}, pageSize ?? null, index];
+        // 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];
     };
     const swr = useSWRInfinite(getKey, (key) => {
-        const index = Number(key[4]);
+        const index = Number(key[6]);
         return rpc("query", {
             alias,
             params: params ?? {},
             limit: pageSize,
             offset: pageSize != null ? index * pageSize : 0,
+            sort,
+            filter,
         });
     }, {
         // loadMore appends pages — don't re-fetch earlier pages when `size` grows.

package/dist/src/index.d.ts

@@ -17,7 +17,7 @@
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
-export type { UploadedFile, QueryOptions, WorkflowResult, MembersOptions } from "./hooks.js";
+export type { UploadedFile, QueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";

package/package.json

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