@lotics/app-sdk 0.63.2 → 0.64.1

package/AGENTS.md

@@ -16,7 +16,7 @@ signature; open the file.**
 |---|---|
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
 | [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, data discipline, the search-as-you-type + record-picker patterns. |
-| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`, read-after-write ordering (a re-read must not overtake an in-flight write). |
+| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + link descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |

package/dist/src/index.d.ts

@@ -40,6 +40,8 @@ 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";
+export { useNewRecord, newRecordId } from "./new_record.js";
+export type { NewRecordApi } from "./new_record.js";
 export { useRecents } from "./use_recents.js";
 export type { RecentsApi, RecentsOptions } from "./use_recents.js";
 export { useUrlState } from "./use_url_state.js";

package/dist/src/index.js

@@ -28,6 +28,7 @@ export { readMembers } from "./members.js";
 export { readSelect } from "./select.js";
 export { row, readLinks, readFiles, readLocked } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
+export { useNewRecord, newRecordId } from "./new_record.js";
 export { useRecents } from "./use_recents.js";
 export { useUrlState } from "./use_url_state.js";
 export { urlParam } from "./url_params.js";

package/dist/src/new_record.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Mint a record id locally, in the shape the platform mints.
+ *
+ * The generator is restated here rather than imported because the canonical one
+ * lives in a package that is not published, and this one is. The duplication is
+ * safe by construction rather than by discipline: the server validates the shape on
+ * every write, so a client that drifted would be rejected loudly at the first call
+ * instead of quietly persisting a malformed primary key.
+ *
+ * Uses `crypto.getRandomValues` — available in every browser this SDK runs in — and
+ * rejection-samples so each character is uniformly drawn from the alphabet. A plain
+ * `% 62` over bytes would bias the first 8 characters, which is a poor property for
+ * something used as a primary key.
+ */
+export declare function newRecordId(): string;
+export interface NewRecordApi<P> {
+    /**
+     * The id this surface writes under, stable from the first render — before the
+     * record exists, and unchanged by its creation.
+     */
+    id: string;
+    /**
+     * Persist a patch. The first call creates the record, every later one updates it.
+     * Calls are serialised, so firing several before the first resolves is safe.
+     *
+     * Rejects with whatever `create`/`update` rejected with; a failed create leaves the
+     * record uncreated and the next call will try again.
+     */
+    save: (patch: P) => Promise<void>;
+}
+/**
+ * A record that does not exist yet, named before it does.
+ *
+ * The problem this removes: when the server mints the id, a surface editing a new
+ * record has nothing to identify it by until the first write returns. Everything
+ * keyed on that id — the route, the drawer, a list selection — therefore changes
+ * identity mid-edit, which React resolves by remounting the surface the user is
+ * typing into. Minting the id locally makes it stable from the first render, so the
+ * create stops being an event the UI has to survive.
+ *
+ * Creation still happens on the first write, not on mount: a surface the user opens
+ * and abandons should leave nothing behind.
+ *
+ * The transport is the caller's. Like `useOptimistic`, this hook has no idea how the
+ * app persists anything — it takes `create` and `update` thunks and owns only the id
+ * and the ordering, which is the part that is easy to get wrong:
+ *
+ * - Two blur-saves fired before the first resolves must not both create. That is a
+ *   duplicate record, and it is the failure this exists to prevent.
+ * - A save arriving mid-create must wait for it, or it updates a row that is not
+ *   there yet.
+ * - A create that FAILS must not latch. Otherwise every later save updates a record
+ *   that was never written, and the user's work goes nowhere while looking saved.
+ *
+ * ```tsx
+ * const { id, save } = useNewRecord({
+ *   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
+ *   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
+ *   onCreated: refetch,
+ * });
+ * <InlineText onBlur={(name) => save({ name })} />
+ * ```
+ */
+export declare function useNewRecord<P>(opts: {
+    create: (id: string, patch: P) => Promise<unknown>;
+    update: (id: string, patch: P) => Promise<unknown>;
+    /** Runs once, after the record first exists. Pass a list `refetch` to reveal it. */
+    onCreated?: (id: string) => void;
+}): NewRecordApi<P>;

package/dist/src/new_record.js

@@ -0,0 +1,117 @@
+import { useCallback, useEffect, useRef } from "react";
+const ID_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const ID_LENGTH = 12;
+/**
+ * Mint a record id locally, in the shape the platform mints.
+ *
+ * The generator is restated here rather than imported because the canonical one
+ * lives in a package that is not published, and this one is. The duplication is
+ * safe by construction rather than by discipline: the server validates the shape on
+ * every write, so a client that drifted would be rejected loudly at the first call
+ * instead of quietly persisting a malformed primary key.
+ *
+ * Uses `crypto.getRandomValues` — available in every browser this SDK runs in — and
+ * rejection-samples so each character is uniformly drawn from the alphabet. A plain
+ * `% 62` over bytes would bias the first 8 characters, which is a poor property for
+ * something used as a primary key.
+ */
+export function newRecordId() {
+    const max = 256 - (256 % ID_ALPHABET.length);
+    let out = "";
+    const buf = new Uint8Array(ID_LENGTH * 2);
+    while (out.length < ID_LENGTH) {
+        crypto.getRandomValues(buf);
+        for (let i = 0; i < buf.length && out.length < ID_LENGTH; i++) {
+            if (buf[i] < max)
+                out += ID_ALPHABET[buf[i] % ID_ALPHABET.length];
+        }
+    }
+    return `rec_${out}`;
+}
+/**
+ * A record that does not exist yet, named before it does.
+ *
+ * The problem this removes: when the server mints the id, a surface editing a new
+ * record has nothing to identify it by until the first write returns. Everything
+ * keyed on that id — the route, the drawer, a list selection — therefore changes
+ * identity mid-edit, which React resolves by remounting the surface the user is
+ * typing into. Minting the id locally makes it stable from the first render, so the
+ * create stops being an event the UI has to survive.
+ *
+ * Creation still happens on the first write, not on mount: a surface the user opens
+ * and abandons should leave nothing behind.
+ *
+ * The transport is the caller's. Like `useOptimistic`, this hook has no idea how the
+ * app persists anything — it takes `create` and `update` thunks and owns only the id
+ * and the ordering, which is the part that is easy to get wrong:
+ *
+ * - Two blur-saves fired before the first resolves must not both create. That is a
+ *   duplicate record, and it is the failure this exists to prevent.
+ * - A save arriving mid-create must wait for it, or it updates a row that is not
+ *   there yet.
+ * - A create that FAILS must not latch. Otherwise every later save updates a record
+ *   that was never written, and the user's work goes nowhere while looking saved.
+ *
+ * ```tsx
+ * const { id, save } = useNewRecord({
+ *   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
+ *   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
+ *   onCreated: refetch,
+ * });
+ * <InlineText onBlur={(name) => save({ name })} />
+ * ```
+ */
+export function useNewRecord(opts) {
+    const idRef = useRef("");
+    if (idRef.current === "")
+        idRef.current = newRecordId();
+    // Callbacks are read through a ref so `save` keeps a stable identity across
+    // renders — it is typically handed to an `onBlur`, and a new function every render
+    // would re-bind every field on every keystroke.
+    //
+    // Updated in an effect rather than during render: React only sanctions writing a
+    // ref while rendering for one-time initialisation (as `idRef` above does), because
+    // a render that is discarded would otherwise leave the ref holding props that never
+    // committed. `save` runs from event handlers, which are always after commit, so the
+    // effect is early enough.
+    const optsRef = useRef(opts);
+    useEffect(() => {
+        optsRef.current = opts;
+    });
+    /** The in-flight or settled create. `null` means the record does not exist yet. */
+    const createdRef = useRef(null);
+    /** Tail of the write chain, so saves apply in the order the user made them. */
+    const queueRef = useRef(Promise.resolve());
+    const save = useCallback((patch) => {
+        const run = async () => {
+            const id = idRef.current;
+            const { create, update, onCreated } = optsRef.current;
+            if (createdRef.current === null) {
+                const attempt = (async () => {
+                    await create(id, patch);
+                })();
+                createdRef.current = attempt;
+                try {
+                    await attempt;
+                }
+                catch (error) {
+                    // Unlatch. The record was not written, so the next save has to be free to
+                    // create it — leaving the promise in place would send every later write to
+                    // a row that does not exist.
+                    createdRef.current = null;
+                    throw error;
+                }
+                onCreated?.(id);
+                return;
+            }
+            await createdRef.current;
+            await update(id, patch);
+        };
+        // Chained on both settle paths: one failed save must not strand the ones behind
+        // it, but they still have to run in order.
+        const result = queueRef.current.then(run, run);
+        queueRef.current = result.catch(() => undefined);
+        return result;
+    }, []);
+    return { id: idRef.current, save };
+}

package/docs/mutations.md

@@ -539,3 +539,40 @@ This is the full read → mutate → reconcile loop: `useQuery` reads, `row.*` c
 one workflow per (table, field) you mutate — typed and narrow, never a generic
 `setField(any_field)` that hands the client write access to every field
 ([security](./security.md)).
+
+## Editing a record that does not exist yet: `useNewRecord`
+
+A "new record" surface — a drawer, a detail page reached from a **New** button — has a problem
+before its first write: it has no id. If the server mints one, then everything keyed on that id
+(the route, the drawer, a list selection) *changes identity* the moment the first field saves,
+and React answers an identity change by remounting the surface the user is typing into.
+
+Mint the id on the client instead. `create_records` accepts caller-supplied `rec_*` ids, so the
+id is known from the first render and the create stops being an event the UI has to survive:
+
+```tsx
+const { id, save } = useNewRecord({
+  create: (id, patch) => createCustomer({ record_id: id, ...patch }),
+  update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
+  onCreated: list.refetch,
+});
+
+<InlineText onBlur={(name) => save({ name })} />
+```
+
+- **The record is still created on the first write, not on mount** — a surface the user opens
+  and abandons leaves nothing behind.
+- **`save` serialises.** The first call creates, every later one updates, and calls made before
+  the create resolves queue behind it. Two fields blurred in quick succession therefore produce
+  one record, not two. This is the whole reason to use the hook rather than a `useRef` latch:
+  hand-rolled, the racing-blur case creates a duplicate.
+- **A failed create does not latch.** The next `save` retries the create, rather than updating a
+  row that was never written while the UI looks like it saved.
+- `id` and `save` are stable across renders, so `save` can be bound directly to an `onBlur`.
+
+Your `create` workflow must pass the id through to `create_records` as `ids: [record_id]`.
+Creation is creation: an id that already exists is a conflict, never an overwrite — so the
+workflow cannot be used to clobber another record by guessing its id.
+
+Use `newRecordId()` directly if you need the id outside a hook (routing to the surface before
+mounting it, say). It mints the same `rec_*` shape the server validates.

package/docs/queries.md

@@ -431,7 +431,7 @@ derived surfaces share one implementation.
 
 | Field type | Column type | Source-layer operators | Derived-layer differences | Sort / group / aggregate notes |
 | --- | --- | --- | --- | --- |
-| text | `text` | `equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`, `is_any_of`, `is_none_of` | same set | Sort is lexicographic in the database's default collation — no locale control. Text comparisons normalize both sides (trim + case-insensitive). |
+| text | `text` | `equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`, `is_any_of`, `is_none_of` | same set | Sort is lexicographic in the database's default collation — no locale control. Text comparisons normalize both sides (trim + case-insensitive). The LIKE family (`contains`, `does_not_contain`, `starts_with`, `ends_with`) additionally folds **diacritics**, so `contains "ha noi"` matches `"Hà Nội"`; the identity operators (`equals`, `not_equals`, `is_any_of`, `is_none_of`) do **not** — they compare a stored value, and `mã` is not `ma`. |
 | number | `number` | `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` | same set | Full numeric aggregate set (§8). |
 | date / datetime | `date` / `datetime` (datetime when the field's format includes time) | `on`, `before`, `after`, `on_or_before`, `on_or_after`, `between`, `time_of_day`, `is_empty`, `is_not_empty` — values are `DateTimePoint`s (below) | same set | Day-level filters on datetime values expand to the full-day window. Sortable; bucketable in `group.by` (§8); `earliest`/`latest`/`min`/`max`/`date_range` aggregate. |
 | boolean | `boolean` | `equals` (value `true`/`false`; `false` matches NULL/missing) | same | `checked`/`unchecked`/`percent_*` aggregate (`unchecked` counts false **or** empty). |
@@ -596,11 +596,20 @@ It AND-s with `filter` (search *within* a scope) and is templatable
 (`"search": "{{params.q}}"`). An empty or whitespace-only term matches everything; an
 unresolved optional token prunes to match-all (§6).
 
-**Search-as-you-type uses `search`, never a `contains` OR-group.** Per-field `contains` is
-accent-*sensitive* and unindexed — a zero-match keystroke forces a full-partition scan that
-hangs the picker. Reserve an OR-group of `contains` for when you must bound exactly *which*
-fields match. Gate the fetch on a non-empty term client-side (`enabled`), or first paint dumps
-the table.
+**Search-as-you-type over a LARGE table uses `search`, never a `contains` OR-group.** Per-field
+`contains` is unindexed — a zero-match keystroke forces a full-partition scan that hangs the
+picker. (It is not accent-sensitive; the LIKE family folds diacritics, §5.) Gate the fetch on a
+non-empty term client-side (`enabled`), or first paint dumps the table.
+
+**But `search` matches the WHOLE record, and on an identity box that is usually wrong.** The
+search document indexes select option labels, member names, dates in three formats, and each
+linked record's cached display text — including the `Field=True/False` pill a boolean renders
+into. A box captioned "find a person" then matches rows that merely share a stage label or an
+owner, and folding makes near-homographs collide (`tiến` ≡ `tiền`). Measured on a real 88-row
+customer book, one such term returned **every row**. When the box means *find this person*, bound
+it: an OR-group of `contains` over the two or three identity fields (name, national id, phone),
+with the term param `required: false` so an empty box prunes the group to match-all. Use `search`
+when the box genuinely means *find this anywhere in the record*.
 
 ---
 
@@ -872,7 +881,9 @@ and is not — and a playbook rule applied to the wrong query costs effort while
 ### The authoring rules
 
 1. **Filter at the source.** Push every static predicate into `from_table.filter`.
-2. **Prefer `search`** for any free-text box; `contains` OR-groups only to bound the fields.
+2. **Match the operator to what the box MEANS.** *Find this anywhere in the record* → `search`.
+   *Find this person/order* → a `contains` OR-group over the identity fields (§7) — the
+   whole-record index will surface rows that only share an owner or a status.
 3. **Aggregate and bucket server-side.** A dashboard reads grouped rows, never raw rows it
    reduces in JS — raw-row shipping burns the 10k cap, the timeout, and bandwidth at once.
 4. **Project narrow.** Every un-rendered column is wasted bytes; every un-rendered `files`

package/package.json

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