@lotics/app-sdk 0.23.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";
@@ -27,8 +27,8 @@ export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
 export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";
-export { row, readLinks } from "./row.js";
-export type { ResolvedLink } from "./row.js";
+export { row, readLinks, readFiles } from "./row.js";
+export type { ResolvedLink, AppFile } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export type { OptimisticApi } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.js";

package/dist/src/index.js

@@ -20,6 +20,6 @@ export { rpc } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { readMembers } from "./members.js";
 export { readSelect } from "./select.js";
-export { row, readLinks } from "./row.js";
+export { row, readLinks, readFiles } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.js";

package/dist/src/row.d.ts

@@ -44,6 +44,27 @@ export interface ResolvedLink {
 declare function link(v: unknown): ResolvedLink | null;
 /** select_record_link → ALL linked records as `{ id, display }[]` (empty if none). */
 export declare function readLinks(v: unknown): ResolvedLink[];
+/**
+ * A `files`-field cell entry, as the app query serializes it. The server
+ * presigns each file (24h) so `url`/`thumbnail_url` load directly — including
+ * from the sandboxed app iframe and for public apps — so the app can preview or
+ * download without deriving its own URL.
+ */
+export interface AppFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    /** Presigned serving URL — render in an <Image>/preview or pass to openExternal. */
+    url: string;
+    /** Presigned thumbnail URL for images, when the server produced one. */
+    thumbnail_url?: string;
+}
+/**
+ * files field → the attached files with their presigned `url` (empty if none).
+ * Skips entries the server didn't presign (no `url`) so a consumer never renders
+ * an unservable file. Map to `@lotics/ui` `DisplayFile` for FileThumbnail/Gallery.
+ */
+export declare function readFiles(v: unknown): AppFile[];
 export declare const row: {
     opt: typeof opt;
     text: typeof text;

package/dist/src/row.js

@@ -89,4 +89,33 @@ export function readLinks(v) {
     }
     return v.map(asLink).filter((x) => x !== null);
 }
+/**
+ * files field → the attached files with their presigned `url` (empty if none).
+ * Skips entries the server didn't presign (no `url`) so a consumer never renders
+ * an unservable file. Map to `@lotics/ui` `DisplayFile` for FileThumbnail/Gallery.
+ */
+export function readFiles(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const f of v) {
+        if (!f || typeof f !== "object")
+            continue;
+        const id = f.id;
+        const url = f.url;
+        if (typeof id !== "string" || !id || typeof url !== "string" || !url)
+            continue;
+        const filename = f.filename;
+        const mime = f.mime_type;
+        const thumb = f.thumbnail_url;
+        out.push({
+            id,
+            filename: typeof filename === "string" ? filename : "",
+            mime_type: typeof mime === "string" ? mime : "",
+            url,
+            thumbnail_url: typeof thumb === "string" ? thumb : undefined,
+        });
+    }
+    return out;
+}
 export const row = { opt, text, num, bool, date, link };

package/package.json

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