@lotics/app-sdk 0.33.0 → 0.34.0

package/dist/src/hooks.d.ts

@@ -1,5 +1,6 @@
 import type { AppWorkflows, AppWorkflowResults, AppQueries } from "./types.js";
 import type { ResolvedMember } from "./members.js";
+import type { ResolvedOption } from "./select.js";
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
     /**
@@ -189,6 +190,68 @@ type QueryArgs<K extends keyof AppQueries & string, O> = AppQueries[K] extends R
  */
 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>>;
+/** The resolved option set of one select column, plus an index for value
+ *  rendering. The companion to a query row, for select fields. */
+export interface FieldOptions {
+    /** The source field's display name — e.g. a picker/section label. */
+    label: string;
+    /**
+     * Every option of the field — `{ key, label, color }`. Includes options not
+     * present in any current row, so a freshly-added option appears in a picker
+     * without an app change, and a removed one drops out.
+     */
+    options: ResolvedOption[];
+    /**
+     * Resolve one option by key — for COLORING A STORED VALUE: pair with
+     * `readSelect(cell)[0]?.key`. `undefined` for an unknown key (option removed
+     * after the cell was written); render the cell's own label with a neutral
+     * badge in that case.
+     */
+    byKey: (key: string) => ResolvedOption | undefined;
+}
+/** Return value of `useFieldOptions`. */
+export interface FieldOptionsState {
+    /**
+     * Resolved option sets keyed by the query's OUTPUT column name. A select
+     * column the server couldn't resolve to a source field (a UNION output, a
+     * computed column) is simply absent — read defensively (`fields.status?`).
+     */
+    fields: Record<string, FieldOptions>;
+    loading: boolean;
+    isValidating: boolean;
+    error: string | null;
+    /** Re-fetch — after a known field-config change (rare). */
+    refetch: () => void;
+}
+/** Options for `useFieldOptions`. */
+export interface FieldOptionsOptions {
+    /** Defer the fetch until true — e.g. a picker that only needs options once an
+     *  edit drawer opens. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Resolve the full option set (key, label, color) of a named query's `select`
+ * columns — the picker companion to `useQuery`. Where a query CELL carries only
+ * the options a record actually holds (key + label, no color), this returns each
+ * select column's COMPLETE option list with colors, straight from the field
+ * config — so it populates a dropdown AND colors a stored value, and a freshly
+ * added/removed option flows through with no app change.
+ *
+ * Addressed by the same alias you query: the option sets resolve from the named
+ * query's output columns, scoped exactly like running it. A column the server
+ * can't map to a source select field (UNION output, computed column) is absent.
+ *
+ * ```tsx
+ * const { fields } = useFieldOptions("records");
+ * // populate + color a picker:
+ * <Picker options={fields.status?.options ?? []}
+ *   renderOptionContent={(o) => <OptionBadge value={o} />} />
+ * // color a stored value:
+ * <OptionBadge value={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
+ * ```
+ */
+export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState;
+export declare function useFieldOptions(alias: string, opts?: FieldOptionsOptions): FieldOptionsState;
 /**
  * Like `useQuery` but append/load-more: the first render loads one page and
  * `loadMore()` appends the next, accumulating into `rows` (infinite scroll).

package/dist/src/hooks.js

@@ -15,7 +15,7 @@
  * cache survives unmount/remount. Mutation / member hooks keep their own local
  * `useState` — they have nothing to share.
  */
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
 import { rpc } from "./rpc.js";
@@ -76,6 +76,33 @@ export function useQuery(alias, params, opts) {
         refetch,
     };
 }
+export function useFieldOptions(alias, opts) {
+    const enabled = opts?.enabled ?? true;
+    // Field config is slow-changing, so no focus/reconnect revalidation — the app
+    // calls `refetch()` after a known change. A null key defers the fetch.
+    const key = enabled ? ["app-field-options", alias] : null;
+    const swr = useSWR(key, () => rpc("field_options", { alias }), swrConfig(false));
+    const fields = useMemo(() => {
+        const raw = swr.data?.fields ?? {};
+        const out = {};
+        for (const [col, def] of Object.entries(raw)) {
+            const options = def.options ?? [];
+            const index = new Map(options.map((o) => [o.key, o]));
+            out[col] = { label: def.label, options, byKey: (k) => index.get(k) };
+        }
+        return out;
+    }, [swr.data]);
+    const refetch = useCallback(() => {
+        void swr.mutate();
+    }, [swr]);
+    return {
+        fields,
+        loading: swr.isLoading,
+        isValidating: 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;

package/dist/src/index.d.ts

@@ -16,8 +16,8 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.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 { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useMembers, } from "./hooks.js";
+export type { UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";

package/dist/src/index.js

@@ -15,7 +15,7 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useMembers, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";

package/dist/src/rpc.d.ts

@@ -18,7 +18,7 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "workflow" | "upload" | "members" | "context" | "openExternal" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "upload" | "members" | "context" | "openExternal" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /**
  * The app's identity, resolved once at startup to tag PostHog events.
  * Assembled by whichever transport is active:

package/dist/src/rpc.js

@@ -213,6 +213,8 @@ function rpcStandalone(op, payload) {
     switch (op) {
         case "query":
             return standaloneQuery(payload);
+        case "field_options":
+            return standaloneFieldOptions(payload);
         case "workflow":
             return standaloneWorkflow(payload);
         case "upload":
@@ -289,6 +291,11 @@ async function standaloneQuery(p) {
     const r = (await apiCall("POST", `/v1/apps/${app_id}/query`, { alias: p.alias, params: p.params, limit: p.limit, offset: p.offset }, { appId: app_id }));
     return { rows: r.rows ?? [] };
 }
+async function standaloneFieldOptions(p) {
+    const { app_id } = await boot();
+    const r = (await apiCall("POST", `/v1/apps/${app_id}/field-options`, { alias: p.alias }, { appId: app_id }));
+    return { fields: r.fields ?? {} };
+}
 async function standaloneWorkflow(p) {
     const { app_id } = await boot();
     return apiCall("POST", `/v1/apps/${app_id}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs }, { appId: app_id });

package/dist/src/select.d.ts

@@ -14,6 +14,14 @@ export interface ResolvedOption {
     /** Option display name. Falls back to the key when the option was deleted
      *  after the cell was written — surfaces the stale state explicitly. */
     label: string;
+    /**
+     * Named palette color token (e.g. `"blue"`, `"emerald"`). Populated by
+     * `useFieldOptions` (which reads the field config); absent on options read
+     * back from a query CELL via `readSelect` — a cell carries only key + label.
+     * Pass the resolved option straight to `@lotics/ui`'s `OptionBadge`, which
+     * degrades a missing/unknown token to a neutral badge.
+     */
+    color?: string;
 }
 /**
  * Parse a `useQuery` cell value into `ResolvedOption[]`. Returns `[]` for

package/package.json

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