@lotics/app-sdk 0.31.0 → 0.33.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

@@ -202,7 +202,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/index.d.ts

@@ -11,7 +11,7 @@
  * 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";
@@ -26,13 +26,14 @@ 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";
 export type { ResolvedOption } from "./select.js";
 export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";
-export { row, readLinks, readFiles } from "./row.js";
+export { row, readLinks, readFiles, readLocked } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export type { OptimisticApi } from "./use_optimistic.js";

package/dist/src/index.js

@@ -11,7 +11,7 @@
  * 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";
@@ -21,8 +21,9 @@ 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 } from "./row.js";
+export { row, readLinks, readFiles, readLocked } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.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. */
@@ -65,12 +75,22 @@ export interface AppFile {
  * an unservable file. Map to `@lotics/ui` `DisplayFile` for FileThumbnail/Gallery.
  */
 export declare function readFiles(v: unknown): AppFile[];
+/**
+ * Record lock state for a `useQuery` row. The query layer emits a row-level
+ * `__source_locked` addressing column (alongside `__source_record_id`). A locked
+ * record rejects direct writes, so an app reads this to show a locked state and
+ * route edits through a `request_locked_field_change` workflow instead of an
+ * `update_records` save. Pass the whole row (not a cell). False for any
+ * non-object / absent flag.
+ */
+export declare function readLocked(rowValue: unknown): boolean;
 export declare const row: {
     opt: typeof opt;
     text: typeof text;
     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")
@@ -118,4 +133,17 @@ export function readFiles(v) {
     }
     return out;
 }
-export const row = { opt, text, num, bool, date, link };
+/**
+ * Record lock state for a `useQuery` row. The query layer emits a row-level
+ * `__source_locked` addressing column (alongside `__source_record_id`). A locked
+ * record rejects direct writes, so an app reads this to show a locked state and
+ * route edits through a `request_locked_field_change` workflow instead of an
+ * `update_records` save. Pass the whole row (not a cell). False for any
+ * non-object / absent flag.
+ */
+export function readLocked(rowValue) {
+    if (!rowValue || typeof rowValue !== "object")
+        return false;
+    return bool(rowValue["__source_locked"]);
+}
+export const row = { opt, text, num, bool, date, datetime, link };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -46,4 +46,4 @@
     "url": "https://github.com/lotics/lotics.git",
     "directory": "packages/app-sdk"
   }
-}
+}