@lotics/app-sdk 0.122.9 → 0.123.1

package/dist/queries.d.ts

@@ -3,7 +3,7 @@ import type { AppQueries, AppQueryColumns } from "./types.js";
 import type { ResolvedOption } from "./select.js";
 import type { ReportLanguage } from "./shared_types.js";
 import type { ExportedFile } from "./shared_types.js";
-import type { ReportColumn, ReportReading } from "./shared_types.js";
+import type { ReportColumn, ReportLabels, ReportReading } from "./shared_types.js";
 /**
  * One row of a query whose columns codegen could not read (a dynamic alias, a
  * bare `from_table`). Values stay `unknown` — the cell readers narrow them.
@@ -249,6 +249,9 @@ export interface ExportCall {
     tabs?: readonly ExportTab[];
     report: ExportReport;
     file: ExportFile;
+    /** The words each option key of a select column prints as, by the column, in either file: a cell the server names
+     *  by its field's option prints as that. */
+    labels?: ReportLabels;
 }
 /**
  * Every row a declared query matches — narrowed by `filter` and ordered by `sort` as a page of it is — made into one

package/dist/shared_types.d.ts

@@ -35,9 +35,12 @@ export type ReportColumn = {
   header: string;
   /** A `date` cell is an ISO day or moment. */
   type: "number" | "date" | "text";
-  /** A select whose cells hold bare option keys, no field of the query naming them: the words each key prints as. */
-  labels?: { readonly [x: string]: string; };
 };
+/**
+ * The words each option key of a select column prints as, by the column: a cell no field of the query names arrives
+ * as its bare key.
+ */
+export type ReportLabels = { readonly [x: string]: Readonly<Record<string, string>>; };
 export type ReportLanguage = "vi" | "en";
 export type ReportPart = {
   label: string;
@@ -73,7 +76,7 @@ export type ReportReadingHead = {
   /** The read behind it was cut: its figures stand, every total over them is left out (`null`). */
   truncated: boolean;
 };
-export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "date" | "files" | "text" | "select" | "select_member" | "select_record_link" | "rollup" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "date" | "files" | "text" | "select" | "select_member" | "select_record_link" | "rollup" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; lookup_field_autonumber?: boolean | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; link?: true | undefined; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; options?: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[] | undefined; output_type?: "number" | "boolean" | "date" | "text" | "datetime" | "select" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
+export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; default_from?: { link_field_key: string; field_key: string; options?: Record<string, string> | undefined; } | null | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "date" | "files" | "text" | "select" | "select_member" | "select_record_link" | "rollup" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "date" | "files" | "text" | "select" | "select_member" | "select_record_link" | "rollup" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; lookup_field_autonumber?: boolean | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; link?: true | undefined; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; options?: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[] | undefined; output_type?: "number" | "boolean" | "date" | "text" | "datetime" | "select" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
 export type TableRecordFilters = TableRecordFiltersConditionNode | TableRecordFiltersTraversalNode | TableRecordFiltersGroupNode;
 export type TableRecordFiltersConditionNode = { node_type: "condition"; field_key?: string | undefined; type?: string | undefined; operator: string; value?: unknown; unit_option?: string | undefined; };
 export type TableRecordFiltersGroupNode = { node_type: "group"; logic: "and" | "or"; children: (TableRecordFilters)[]; };

package/dist/store.d.ts

@@ -1,5 +1,11 @@
 /** How a key is read: from when the request was sent and the answer it holds now (a feed grows from it). */
 export type Fetcher<T> = (askedAt: number, current: T | undefined) => Promise<T>;
+/**
+ * A focus or reconnect within this long of a key's last ask asks nothing: returns to the tab a minute apart are one
+ * visit. A push asks at once whatever this says, so what this bounds is only what no push carries — a dead channel, a
+ * value the clock moves.
+ */
+export declare const FOCUS_THROTTLE_MS = 60000;
 /** The read clock: every request stamps when it was sent, so an answer is known to carry what settled before it. */
 export declare function tick(): number;
 /** Ask again every key reading one of `aliases` — every query key where none is named; an unmounted one on its next mount. */

package/docs/data_fetching.md

@@ -24,7 +24,7 @@ untyped. It is written from the app's live bindings by `lotics app create --cust
 | `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` or `total: { where: { name: filter } }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
 | `useQueries(calls, opts?)` | one state per `{ alias, params?, filter?, sort?, aggregate?, total?, rows? }`, in order — a `sort` orders that call's rows before the cap cuts them | reads that are DATA — a list known only at render, one read per item, or one count per stage (`rows: false, total: true`, each state's `.total`); the deploy's alias scan reads a list as dynamic, so every alias in it is still declared. With `aggregate` a call answers the groups of its filtered rows instead of the rows ([queries](./queries.md)) |
 | `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set in the browser (the ids an act runs on): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
-| `exportQuery(alias, { params, filter, sort, tabs?, report, file })` | a promise of an `ExportedFile`: `{ filename, mime_type, url, size, created_at }` | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type, labels? }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; `labels` the words each bare option key of a `select` column no field names prints as, refused on any other column and for a key it lacks; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file has no `id` — it is a download, not a workspace file a workflow or a field takes: its `url` is signed for the caller for at most an hour, so open it with `openExternal` when the promise resolves; the server deletes the file a day after it is made |
+| `exportQuery(alias, { params, filter, sort, tabs?, report, file, labels? })` | a promise of an `ExportedFile`: `{ filename, mime_type, url, size, created_at }` | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). `labels`, by `select` output column, the words each option key prints as in either file — a cell no field of the query names (a union's literal column) arrives as its bare key; a cell its field's option names prints as that, a key the map lacks as itself, and a column no select of the query holds as it is. Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file has no `id` — it is a download, not a workspace file a workflow or a field takes: its `url` is signed for the caller for at most an hour, so download it with `downloadFileFromUrl(url, filename)` (`@lotics/ui/download`) when the promise resolves — a tab `openExternal` opens seconds after the click is a pop-up the browser blocks; the server deletes the file a day after it is made |
 
 Every hook answers the same `QueryState`: `rows`, `truncated`, `total`, `counts`, `loading`,
 `isValidating`, `answeredAt`, `error`, `pending`, `refetch`, `page`, `setPage`, `pageCount`, `hasMore`,
@@ -146,7 +146,7 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
   renders the cached rows instantly *and* re-reads them in the background, so a list reflects what
   another screen changed while you were away. Identical concurrent reads share one request, and reads asked within a few milliseconds of each other go to the server together, each answered or refused on its own.
   Freshness comes from four places — arrival, window focus / tab return / network reconnect
-  (`revalidateOnFocus`, default on; a read asked within the last few seconds is not asked again,
+  (`revalidateOnFocus`, default on; a read asked within the last minute is not asked again,
   and the reads it asks again re-render together, as a push's do — so what changed while the tab
   was hidden or offline lands in one piece), a **realtime push**, and **this app's own successful
   write**, which re-reads the mounted queries over the tables its body names without being asked
@@ -375,7 +375,7 @@ Wire shapes per output column type:
 | `datetime` | `"YYYY-MM-DDTHH:mm"` — workspace wall-clock, minute precision |
 | `select` | `Array<{ key, label }>` — one entry per selected option |
 | `select_member` | `Array<{ id, name, email?, image?, groups? }>` — the last three only for authenticated viewers of the app's own org; `image` presigned |
-| `select_record_link` | `Array<{ id, display }>` — target record id + its display text |
+| `select_record_link` | `Array<{ id, display }>` — target record id + the row's name: the field its table names rows by |
 | `files` | `Array<{ id, filename, mime_type, url, thumbnail_url?, size?, created_at?, document_template_id? }>` — presigned |
 
 Row-level (non-grouped) queries additionally carry system columns: `__source_record_id` /

package/docs/files.md

@@ -247,7 +247,7 @@ Decode with `readFiles(cell)` → `AppFile[]` (`dist/row.d.ts`):
 | `id` | `string` | The stored file id |
 | `filename` | `string` | Original filename (post-optimization name for converted images) |
 | `mime_type` | `string` | |
-| `url` | `string` | Presigned serving URL — render, or pass to `openExternal` |
+| `url` | `string` | Presigned serving URL — render it, or download it with `downloadFileFromUrl` |
 | `thumbnail_url` | `string?` | Presigned image thumbnail (see the 404 note below) |
 | `size` | `number?` | Byte size — **absent on older files not yet backfilled**; render only when present |
 | `created_at` | `string?` | ISO upload timestamp |
@@ -320,22 +320,25 @@ dedupes them, and returns them on the execute response as `WorkflowResult.files?
 with `files` absent.
 
 ```tsx
+import { downloadFileFromUrl } from "@lotics/ui/download";
+
 const generate = useWorkflow("generateInvoice");
 // `__source_record_id` is `null` on a grouped row — so narrow it rather than
 // handing the workflow no id where it declares a record.
 if (!row.__source_record_id) return;
 const result = await generate({ record_id: row.__source_record_id });
-if (result.status === "success" && result.files?.length) {
-  await openExternal(result.files[0].url);
-}
+const [file] = result.status === "success" ? (result.files ?? []) : [];
+if (file?.url) await downloadFileFromUrl(file.url, file.filename);
 ```
 
 - **Don't hand back a `url` or `file_id` via `return({ data })`** — extraction is automatic, and
   the extracted entry is presigned while a hand-returned id is not.
 - The presigned URLs work for **anonymous public-app viewers** — a public visitor can download a
   document the workflow generated for them.
-- Open one with `openExternal(url)`, never `window.open`; bytes the app builds *in the browser*
-  leave through `downloadFile` — both [runtime](./runtime.md).
+- Download one with `downloadFileFromUrl(url, filename)` (`@lotics/ui/download`): it fetches the
+  presigned URL and saves it, and the iframe allows downloads. A tab `openExternal` opens once the
+  run answers is a pop-up the browser blocks. Bytes the app builds *in the browser* leave through
+  `downloadFile` ([runtime](./runtime.md)).
 
 ### Naming what goes into a zip
 

package/docs/members_and_options.md

@@ -428,8 +428,9 @@ const { reverted, kept } = await undoRecordChange("job", recordId, entry.id);
   before is in neither. The write is the viewer's own save: they hold `write_data` on the table as
   the call arrives, on a row their own row rule covers, and the record's lock, the table's checks
   and its write rules answer as for any save of theirs. `undoable` is `false`, and the call
-  refused, for the entry that made the record, an entry that is an undo, one already put back, and
-  a viewer who may not write the record; a record in the trash is refused until it is restored.
+  refused, for the entry that made the record, an entry that is an undo, one already put back, a
+  viewer who may not write the record, and a JSON app that saves no record of the entity (an undo is
+  a save); a record in the trash is refused until it is restored.
   The undo is an entry of its own; the answer arrives once the record's reads are read anew.
 - **Pages**: newest first, about thirty entries each; `next` is where the trail goes on —
   `undefined` at its end. A page may hold fewer entries and still say `next` where the trail it read

package/docs/mutations.md

@@ -142,13 +142,15 @@ Any step in the run whose tool output carries a `file_id` (most commonly
 `generate_document`) is collected automatically into
 `result.files[]` — each an `UploadedFile`
 `{ id, filename, mime_type, url?, thumbnail_url? }` with a presigned `url` (24-hour TTL) the
-app can open directly:
+app downloads directly — a tab opened once the run answers is a pop-up the browser blocks:
 
 ```tsx
+import { downloadFileFromUrl } from "@lotics/ui/download";
+
 const gen = useWorkflow("generateInvoice");
 const { status, files } = await gen({ order_id });
-const url = files?.[0]?.url;
-if (status === "success" && url) await openExternal(url);
+const file = files?.[0];
+if (status === "success" && file?.url) await downloadFileFromUrl(file.url, file.filename);
 ```
 
 The same run reached through the `run_app_workflow` tool — from chat, from MCP, from an app

package/docs/recipes.md

@@ -28,19 +28,21 @@ return({ status: "success", message: `Đã tạo ${code}` });   // the file is e
 ```
 
 ```tsx
-import { useWorkflow, openExternal } from "@lotics/app-sdk";
+import { useWorkflow } from "@lotics/app-sdk";
+import { downloadFileFromUrl } from "@lotics/ui/download";
 
 const gen = useWorkflow("genDebit");
 const { files } = await gen({ record_id: rid });
-const url = files?.[0]?.url;
-if (url) await openExternal(url);
+const file = files?.[0];
+if (file?.url) await downloadFileFromUrl(file.url, file.filename);
 ```
 
 The `dtl_…` is a template you registered **once**, ahead of the app, through the CLI — see
 `lotics docs document_templates` for the five types and how each is created. An app fills
 templates; it never authors them.
 
-**`openExternal` is the download primitive, not `window.open`**, which the sandbox drops silently
+**A generated file downloads with `downloadFileFromUrl`, never a tab.** The sandbox drops `window.open`
+silently, and a tab `openExternal` opens seconds after the click is a pop-up the browser blocks
 ([runtime](./runtime.md)).
 
 ## Return structured data from a workflow

package/docs/runtime.md

@@ -293,7 +293,7 @@ nobody stated.
 
 ```tsx
 import { openExternal } from "@lotics/app-sdk";
-await openExternal(result.files[0].url);
+await openExternal(invoiceUrl);
 ```
 
 `openExternal(url: string): Promise<void>` (`dist/open_external.d.ts`). The
@@ -376,7 +376,7 @@ function onExportClick() {
 string): void` (`dist/download.d.ts`) saves bytes the app generated **in the
 browser** (an exported .xlsx, a CSV, generated text) to the visitor's device.
 It is the client-side counterpart to the server path (workflow generates a file
-→ `WorkflowResult.files[].url` → `openExternal`).
+→ `WorkflowResult.files[].url` → `downloadFileFromUrl` from `@lotics/ui/download`).
 
 - **Pure DOM, no RPC.** The embed sandbox includes `allow-downloads`, so a
   same-origin blob download triggered from a user gesture needs no host

package/docs/security.md

@@ -103,7 +103,7 @@ A publicly-shared app (its own origin, or its public link) is reachable by **any
 | Agent runs (`useAgentRun`) | **No** — rejected: agent runs require an authenticated member, and each member's run history is private to them (a guessed session id cannot read another member's thread) |
 | Comments (`useComments`) | **No** — members-only |
 | Record activity (`useRecordActivity`) | **No** — the app's organization's members only |
-| Undo of a record's change (`undoRecordChange`) | **No** — a member of the app's organization holding `write_data` on the record's table, on a row their own row rule covers |
+| Undo of a record's change (`undoRecordChange`) | **No** — a member of the app's organization holding `write_data` on the record's table, on a row their own row rule covers, in an app that saves records of that entity |
 | Member roster (`useMembers`) | **No** — same-org members only (below) |
 
 **Warning — `is_current_member` on a public app resolves to the app owner.** An anonymous request has no viewer to bind, so both `is_current_member` and `current_member in_any_group` fall back to the owner's identity and the owner's groups. A "my items" query shows every anonymous visitor the *owner's* items, and a manager-only read template gated on a group the owner belongs to **passes for every anonymous visitor**. Never rely on viewer-bound predicates in a public app.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.122.9",
+  "version": "0.123.1",
   "description": "The SDK a Lotics custom-code app reads and writes through — typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {