@lotics/app-sdk 0.12.0 → 0.13.0

package/dist/src/index.d.ts

@@ -3,11 +3,16 @@
  * app at build time. Apps `import { mount, useQuery, useWorkflow } from
  * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
  *
- * Curated UI primitive re-exports from `@lotics/ui` are deliberately NOT
- * included here. Users import them separately from a published `@lotics/ui`
- * package once that's ready, or compose with vanilla HTML/CSS in the
- * meantime. Splitting the package boundaries lets the SDK ship without
- * depending on packages/ui's React Native Web setup.
+ * This SDK is data + RPC only — it deliberately does NOT re-export any
+ * `@lotics/ui` components, so it ships without pulling in packages/ui's
+ * React Native Web dependency tree. That is a packaging choice, NOT a
+ * limitation on apps: apps import `@lotics/ui` directly as a normal dep.
+ * The starter scaffold (`packages/sdk/src/starter_template.ts`) wires the
+ * 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, …),
+ * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
@@ -19,3 +24,6 @@ export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";
 export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";
+export { row } from "./row.js";
+export { useOptimistic } from "./use_optimistic.js";
+export type { OptimisticApi } from "./use_optimistic.js";

package/dist/src/index.js

@@ -3,13 +3,20 @@
  * app at build time. Apps `import { mount, useQuery, useWorkflow } from
  * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
  *
- * Curated UI primitive re-exports from `@lotics/ui` are deliberately NOT
- * included here. Users import them separately from a published `@lotics/ui`
- * package once that's ready, or compose with vanilla HTML/CSS in the
- * meantime. Splitting the package boundaries lets the SDK ship without
- * depending on packages/ui's React Native Web setup.
+ * This SDK is data + RPC only — it deliberately does NOT re-export any
+ * `@lotics/ui` components, so it ships without pulling in packages/ui's
+ * React Native Web dependency tree. That is a packaging choice, NOT a
+ * limitation on apps: apps import `@lotics/ui` directly as a normal dep.
+ * The starter scaffold (`packages/sdk/src/starter_template.ts`) wires the
+ * 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, …),
+ * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export { readMembers } from "./members.js";
+export { row } from "./row.js";
+export { useOptimistic } from "./use_optimistic.js";

package/dist/src/row.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Accessors that coerce raw `useQuery` row values into typed values. Each cell
+ * of a query row is `unknown`: the query layer serializes a select column as its
+ * `opt_` id (and, for some shapes, a single-element array or a `{ id }` object),
+ * a date/datetime as a `YYYY-MM-DD[THH:mm…]` string, a number/boolean as itself.
+ *
+ * These live in app-sdk — next to `useQuery`, whose serialization contract they
+ * decode — so a change to that contract updates them in one place, and so apps
+ * stop re-implementing the same coercions. They are pure (`unknown` in, value
+ * out) and never throw.
+ */
+/** Select → option id. Handles a bare id, a single-element array, or `{ id }`. */
+declare function opt(v: unknown): string | null;
+/** Text/markdown/autonumber → string (numbers stringified; everything else ""). */
+declare function text(v: unknown): string;
+/** Number → number (NaN/Infinity and unparseable strings → 0). */
+declare function num(v: unknown): number;
+/** Checkbox/boolean → boolean (accepts the string "true"). */
+declare function bool(v: unknown): boolean;
+/**
+ * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
+ * calendar/gantt placement never shifts across timezones. Parses the leading
+ * `YYYY-MM-DD` of the serialized string; null if absent or unparseable. (Range
+ * fields are not handled here — they have no consumer yet.)
+ */
+declare function date(v: unknown): Date | null;
+export declare const row: {
+    opt: typeof opt;
+    text: typeof text;
+    num: typeof num;
+    bool: typeof bool;
+    date: typeof date;
+};
+export {};

package/dist/src/row.js

@@ -0,0 +1,56 @@
+/**
+ * Accessors that coerce raw `useQuery` row values into typed values. Each cell
+ * of a query row is `unknown`: the query layer serializes a select column as its
+ * `opt_` id (and, for some shapes, a single-element array or a `{ id }` object),
+ * a date/datetime as a `YYYY-MM-DD[THH:mm…]` string, a number/boolean as itself.
+ *
+ * These live in app-sdk — next to `useQuery`, whose serialization contract they
+ * decode — so a change to that contract updates them in one place, and so apps
+ * stop re-implementing the same coercions. They are pure (`unknown` in, value
+ * out) and never throw.
+ */
+/** Select → option id. Handles a bare id, a single-element array, or `{ id }`. */
+function opt(v) {
+    if (typeof v === "string")
+        return v || null;
+    if (Array.isArray(v))
+        return v.length ? opt(v[0]) : null;
+    if (v && typeof v === "object") {
+        const id = v.id;
+        return typeof id === "string" ? id : null;
+    }
+    return null;
+}
+/** Text/markdown/autonumber → string (numbers stringified; everything else ""). */
+function text(v) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    return "";
+}
+/** Number → number (NaN/Infinity and unparseable strings → 0). */
+function num(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : 0;
+    if (typeof v === "string" && v.trim()) {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : 0;
+    }
+    return 0;
+}
+/** Checkbox/boolean → boolean (accepts the string "true"). */
+function bool(v) {
+    return v === true || v === "true";
+}
+/**
+ * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
+ * calendar/gantt placement never shifts across timezones. Parses the leading
+ * `YYYY-MM-DD` of the serialized string; null if absent or unparseable. (Range
+ * fields are not handled here — they have no consumer yet.)
+ */
+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;
+}
+export const row = { opt, text, num, bool, date };

package/dist/src/use_optimistic.d.ts

@@ -0,0 +1,22 @@
+export interface OptimisticApi<T> {
+    /** `base` with any pending optimistic patches applied. */
+    items: T[];
+    /**
+     * Optimistically merge `next` into the item keyed `id`, then run `persist`.
+     * On resolve → `onSettled?.()` (pass your query's `refetch`); the patch is
+     * kept (it already matches the refetched value, so no flicker). On reject →
+     * the patch is reverted.
+     */
+    patch: (id: string, next: Partial<T>, persist: () => Promise<unknown>, opts?: {
+        onSettled?: () => void;
+    }) => void;
+}
+/**
+ * Optimistic list overrides for a `useQuery` result feeding an interactive view
+ * (calendar drag, gantt resize, kanban move). Pure React state: it takes the
+ * already-mapped items + a key function + a caller-supplied `persist` thunk, so
+ * it has no coupling to any specific mutation transport (the app threads its own
+ * `useWorkflow` call + `refetch`). It lives in app-sdk as the *reconcile* leg of
+ * the read (`useQuery`) → mutate (`useWorkflow`) → reconcile loop.
+ */
+export declare function useOptimistic<T>(base: T[], keyOf: (item: T) => string): OptimisticApi<T>;

package/dist/src/use_optimistic.js

@@ -0,0 +1,27 @@
+import { useCallback, useMemo, useState } from "react";
+/**
+ * Optimistic list overrides for a `useQuery` result feeding an interactive view
+ * (calendar drag, gantt resize, kanban move). Pure React state: it takes the
+ * already-mapped items + a key function + a caller-supplied `persist` thunk, so
+ * it has no coupling to any specific mutation transport (the app threads its own
+ * `useWorkflow` call + `refetch`). It lives in app-sdk as the *reconcile* leg of
+ * the read (`useQuery`) → mutate (`useWorkflow`) → reconcile loop.
+ */
+export function useOptimistic(base, keyOf) {
+    const [overrides, setOverrides] = useState({});
+    const items = useMemo(() => base.map((item) => {
+        const o = overrides[keyOf(item)];
+        return o ? { ...item, ...o } : item;
+    }), [base, overrides, keyOf]);
+    const patch = useCallback((id, next, persist, opts) => {
+        setOverrides((m) => ({ ...m, [id]: { ...m[id], ...next } }));
+        persist().then(() => opts?.onSettled?.(), () => setOverrides((m) => {
+            if (!(id in m))
+                return m;
+            const cleared = { ...m };
+            delete cleared[id];
+            return cleared;
+        }));
+    }, []);
+    return { items, patch };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -14,6 +14,7 @@
   "scripts": {
     "build": "tsgo",
     "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {