@lotics/app-sdk 0.69.0 → 0.70.0

package/dist/src/hooks.d.ts

@@ -103,6 +103,18 @@ interface PaginatedQueryState<R> extends QueryStateBase {
 export interface QuerySortKey {
     field_key: string;
     order: "asc" | "desc";
+    /**
+     * Where rows BLANK in this column sit — `"bottom"` when omitted, which is what
+     * you want for "the ones with a value first".
+     *
+     * It earns its place on a MULTI-KEY sort over columns that are blank by
+     * position rather than by accident — a pipeline's per-step date stamps, say,
+     * where the first non-blank column IS the row's rank. Reading such a ladder
+     * from the top with blanks at the bottom orders it furthest-along-first; the
+     * reverse reading needs blanks on TOP, and with only the default there is no
+     * way to express it, so the column can be sorted one way and not the other.
+     */
+    blank_position?: "top" | "bottom";
 }
 /** A filter condition over one output column (wire shape of a filter node). */
 export interface QueryFilterCondition {

package/docs/queries.md

@@ -770,10 +770,13 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
   it. Record-link membership (`has_any_of` by id) **works** here; so does `is_current_member`
   on a member column. Traversals / `locked` / `current_member` do not — bake those into the
   template.
-- **`sort`** — `[{ field_key, order }]` over output columns — the typed `QuerySortKey` the hooks
-  accept. The wire sort node also honors `blank_position?: "top" | "bottom"` (blanks default to
-  bottom), but that field is **not** on the typed hook option; reach it only through a raw
-  `rpc("query", { sort })` call.
+- **`sort`** — `[{ field_key, order, blank_position? }]` over output columns — the typed
+  `QuerySortKey` the hooks accept. `blank_position` is `"top" | "bottom"`, defaulting to
+  `"bottom"`. It matters on a **multi-key** sort over columns whose blankness IS the ranking —
+  a pipeline's per-step date stamps, where the first non-blank column gives the row's rung.
+  Listing the ladder top-down with blanks at the bottom orders it furthest-along-first; the
+  ascending reading needs `blank_position: "top"` on every key, and without it that direction
+  cannot be expressed at all.
 - **`limit` / `offset` / keyset `cursor`** — pagination. `useQuery` / `usePaginatedQuery` page by
   `offset` (`limit` clamped to the 10,000-row cap, §10); `useInfiniteQuery` opts into **keyset
   (seek)** by sending `keyset: true` + the prior page's `cursor`, and the server returns the next

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.69.0",
-  "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
+  "version": "0.70.0",
+  "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
     ".": {