@lotics/app-sdk 0.32.0 → 0.34.0

package/dist/src/download.d.ts

@@ -0,0 +1 @@
+export declare function downloadFile(filename: string, data: Uint8Array | Blob | string, mimeType?: string): void;

package/dist/src/download.js

@@ -0,0 +1,54 @@
+/**
+ * Save bytes the app generated in the browser to the visitor's device.
+ *
+ * This is the client-side counterpart to `openExternal`. The platform's other
+ * download path is server-side: a workflow generates a file, it comes back in
+ * `WorkflowResult.files[]` with a `.url`, and the app opens that URL with
+ * `openExternal`. But data an app builds *in the browser* (an .xlsx exported
+ * from a query result, a CSV, a generated PDF) never gets a server URL — there
+ * was no primitive to save it. This is that primitive.
+ *
+ * It is pure DOM, not an RPC: the embed iframe is sandboxed with
+ * `allow-downloads` (see `app_iframe_host`), so a same-origin blob download
+ * triggered from a user gesture is permitted without host mediation. In
+ * standalone (public) mode the app is a normal top-level page, where downloads
+ * always work. Call it synchronously from the click handler that produced the
+ * bytes so the browser attributes the download to the user gesture.
+ *
+ * ```tsx
+ * import { downloadFile } from "@lotics/app-sdk";
+ * import { buildDataWorkbook, exportWorkbook } from "@lotics/xlsx";
+ *
+ * const wb = buildDataWorkbook({ columns, rows });
+ * downloadFile("report.xlsx", exportWorkbook(wb), XLSX_MIME);
+ * ```
+ */
+const DEFAULT_MIME = "application/octet-stream";
+function toBlob(data, mimeType) {
+    if (data instanceof Blob)
+        return data;
+    if (typeof data === "string")
+        return new Blob([data], { type: mimeType });
+    // Re-wrap the bytes: the DOM lib types a generic `Uint8Array<ArrayBufferLike>`
+    // as incompatible with `BlobPart`, and `new Uint8Array(data)` narrows it to a
+    // fresh `ArrayBuffer`-backed view (the pattern `save_workbook_version` uses).
+    return new Blob([new Uint8Array(data)], { type: mimeType });
+}
+export function downloadFile(filename, data, mimeType) {
+    const url = URL.createObjectURL(toBlob(data, mimeType ?? DEFAULT_MIME));
+    try {
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = filename;
+        a.rel = "noopener";
+        a.style.display = "none";
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+    }
+    finally {
+        // Revoke after the current task so the navigation to the blob URL has
+        // started — revoking synchronously can cancel the download in some browsers.
+        setTimeout(() => URL.revokeObjectURL(url), 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).
@@ -202,7 +265,7 @@ export declare function useInfiniteQuery<K extends keyof AppQueries & string>(al
 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
+ * table (pairs with `@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

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

@@ -11,13 +11,13 @@
  * full setup — `@lotics/ui` + react-native + react-native-web, the
  * react-native→react-native-web Vite alias, `@lotics/ui/index.css` +
  * `fonts.css`, and a `PortalHost` for overlays. Build dashboards by
- * composing `@lotics/ui` components (Card, KpiCard, charts, DataGrid, …),
+ * composing `@lotics/ui` components (Card, KpiCard, charts, Table, …),
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 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";
@@ -26,6 +26,7 @@ export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";
+export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";
 export { readSelect } from "./select.js";

package/dist/src/index.js

@@ -11,16 +11,17 @@
  * full setup — `@lotics/ui` + react-native + react-native-web, the
  * react-native→react-native-web Vite alias, `@lotics/ui/index.css` +
  * `fonts.css`, and a `PortalHost` for overlays. Build dashboards by
- * composing `@lotics/ui` components (Card, KpiCard, charts, DataGrid, …),
+ * composing `@lotics/ui` components (Card, KpiCard, charts, Table, …),
  * 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";
 export { rpc } from "./rpc.js";
 export { openExternal } from "./open_external.js";
+export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";
 export { readSelect } from "./select.js";
 export { row, readLinks, readFiles, readLocked } from "./row.js";

package/dist/src/row.d.ts

@@ -28,6 +28,16 @@ declare function bool(v: unknown): boolean;
  * fields are not handled here — they have no consumer yet.)
  */
 declare function date(v: unknown): Date | null;
+/**
+ * Date/datetime field → a LOCAL Date that KEEPS the stored wall-clock time, so
+ * `getHours()` / `toLocaleTimeString()` render the time as written. The stored
+ * value is a timezone-less workspace wall-clock (see the serialization note
+ * above), so it is read verbatim — no UTC conversion. Use this when the time
+ * matters (a check-in time, an appointment); `date` keeps only the calendar day.
+ * Parses `YYYY-MM-DD` with an optional `T`-or-space `HH:mm[:ss]`; a missing time
+ * is midnight. Null if absent or unparseable.
+ */
+declare function datetime(v: unknown): Date | null;
 /** A linked record cell entry — the target record's id + its display text. */
 export interface ResolvedLink {
     /** The linked record's id (e.g. "rec_…"). Use to correlate/filter. */
@@ -80,6 +90,7 @@ export declare const row: {
     num: typeof num;
     bool: typeof bool;
     date: typeof date;
+    datetime: typeof datetime;
     link: typeof link;
 };
 export {};

package/dist/src/row.js

@@ -60,6 +60,21 @@ function date(v) {
     const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(text(v));
     return m ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3])) : null;
 }
+/**
+ * Date/datetime field → a LOCAL Date that KEEPS the stored wall-clock time, so
+ * `getHours()` / `toLocaleTimeString()` render the time as written. The stored
+ * value is a timezone-less workspace wall-clock (see the serialization note
+ * above), so it is read verbatim — no UTC conversion. Use this when the time
+ * matters (a check-in time, an appointment); `date` keeps only the calendar day.
+ * Parses `YYYY-MM-DD` with an optional `T`-or-space `HH:mm[:ss]`; a missing time
+ * is midnight. Null if absent or unparseable.
+ */
+function datetime(v) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2}))?/.exec(text(v));
+    if (!m)
+        return null;
+    return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), m[4] ? Number(m[4]) : 0, m[5] ? Number(m[5]) : 0);
+}
 /** One `{ id, display }` object → ResolvedLink, or null if absent/malformed. */
 function asLink(v) {
     if (!v || typeof v !== "object")
@@ -131,4 +146,4 @@ export function readLocked(rowValue) {
         return false;
     return bool(rowValue["__source_locked"]);
 }
-export const row = { opt, text, num, bool, date, link };
+export const row = { opt, text, num, bool, date, datetime, link };

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.32.0",
+  "version": "0.34.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {