@lotics/app-sdk 0.35.0 → 0.36.1

package/AGENTS.md

@@ -43,6 +43,17 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
 - **Upload a file** — **`useFileUpload()`** → `{ upload, uploading, error }`. Mints a presigned URL
   and PUTs the bytes straight to storage; the file is inert until a workflow attaches it to a
   `files` field. Emits `app_file_uploaded`.
+- **Composer attachments (with instant preview)** — **`useAttachments()`** → `{ files, add, remove,
+  clear, uploading, fileIds }`. The chat's optimistic-preview UX in one hook: `add(File[])` shows a
+  local object-URL preview AT ONCE and uploads in the background; each `files[]` entry carries
+  `{ id, filename, mime_type, preview_url, status, file_id? }`; previews are revoked on remove/clear.
+  Picking is yours (button → `@lotics/ui` `pickFiles`, or paste/drop) — pass the `File[]` to `add`.
+  Wire to `@lotics/ui` `Composer`: `actionsButton` triggers the pick, then map each `AttachedFile`
+  to a `DisplayFile` (snake → camel — `mime_type`→`mimeType`, `preview_url`→`url` — the app owns this
+  data→UI adapter; the SDK never imports `@lotics/ui`) for
+  `<FileThumbnail file={{ id, filename, mimeType, url }} uploading={f.status === "uploading"} />`;
+  `sendDisabled` gates on `uploading` and the send payload is `fileIds`. Don't hand-roll
+  `createObjectURL`/upload/revoke per app.
 - **List members** — **`useMembers(opts?)`** → `{ members: {id,name,email,image}[], loading, error }`
   — the candidate set for an assign/picker. Gated: the app must declare a `member`-typed input
   (`opts.group` restricts to a declared group). Render with `@lotics/ui` `MemberSelect` / `MemberChip`.

package/dist/src/hooks.d.ts

@@ -314,6 +314,58 @@ interface FileUploadState {
  * ```
  */
 export declare function useFileUpload(): FileUploadState;
+/** A file attached to a composer — its local preview is available immediately,
+ *  its stored `file_id` once the background upload completes. */
+export interface AttachedFile {
+    /** Stable local id — the React key and the `remove(id)` handle. */
+    id: string;
+    filename: string;
+    mime_type: string;
+    /** Local object-URL preview, available the INSTANT the file is added (before upload). */
+    preview_url: string;
+    status: "uploading" | "ready" | "error";
+    /** The stored file id, set once `status` is `"ready"` — pass to a workflow/agent. */
+    file_id?: string;
+}
+interface AttachmentsState {
+    /** The current attachments, in the order added. */
+    files: AttachedFile[];
+    /** Add picked/pasted/dropped files — each shows its local preview at once and
+     *  uploads in the background. Picking is the app's choice: wire a button to
+     *  `@lotics/ui` `pickFiles`, or a paste/drop handler, then call this. */
+    add: (files: File[]) => void;
+    /** Remove one attachment and revoke its preview URL. */
+    remove: (id: string) => void;
+    /** Remove all attachments and revoke their preview URLs. */
+    clear: () => void;
+    /** True while any attachment is still uploading — gate Send on it. */
+    uploading: boolean;
+    /** Stored file ids of the completed uploads — the workflow/agent payload. */
+    fileIds: string[];
+}
+/**
+ * Composer attachments with the chat's optimistic-preview UX: a local object-URL
+ * preview shows the INSTANT a file is added, the upload runs in the background,
+ * and the stored `file_id` lands in `files` when it completes. Previews are
+ * revoked on remove/clear. Picking is the app's (button / paste / drop) — pass
+ * the resulting `File[]` to `add`; the hook owns the preview → upload → id →
+ * revoke lifecycle so apps don't re-implement it.
+ *
+ * ```tsx
+ * const { files, add, remove, clear, uploading, fileIds } = useAttachments();
+ * const design = useWorkflow("design");
+ * // attach:  <Button icon="paperclip" onPress={() => pickFiles({ accept: "image/*" }).then(add)} />
+ * // preview: map each AttachedFile to a @lotics/ui DisplayFile (snake_case → camelCase) — the
+ * //          app owns this data→UI adapter; the SDK never imports @lotics/ui:
+ * //   files.map((f) => (
+ * //     <FileThumbnail
+ * //       file={{ id: f.id, filename: f.filename, mimeType: f.mime_type, url: f.preview_url }}
+ * //       uploading={f.status === "uploading"} onRemove={() => remove(f.id)} />
+ * //   ))
+ * // send:    design({ photo: fileIds[0] }); clear();
+ * ```
+ */
+export declare function useAttachments(): AttachmentsState;
 interface MembersState {
     /** Members of the app's organization, for assign / member-picker UIs. */
     members: ResolvedMember[];

package/dist/src/hooks.js

@@ -246,6 +246,64 @@ export function useFileUpload() {
     }, []);
     return { upload, uploading: inFlight > 0, error };
 }
+let attachSeq = 0;
+/**
+ * Composer attachments with the chat's optimistic-preview UX: a local object-URL
+ * preview shows the INSTANT a file is added, the upload runs in the background,
+ * and the stored `file_id` lands in `files` when it completes. Previews are
+ * revoked on remove/clear. Picking is the app's (button / paste / drop) — pass
+ * the resulting `File[]` to `add`; the hook owns the preview → upload → id →
+ * revoke lifecycle so apps don't re-implement it.
+ *
+ * ```tsx
+ * const { files, add, remove, clear, uploading, fileIds } = useAttachments();
+ * const design = useWorkflow("design");
+ * // attach:  <Button icon="paperclip" onPress={() => pickFiles({ accept: "image/*" }).then(add)} />
+ * // preview: map each AttachedFile to a @lotics/ui DisplayFile (snake_case → camelCase) — the
+ * //          app owns this data→UI adapter; the SDK never imports @lotics/ui:
+ * //   files.map((f) => (
+ * //     <FileThumbnail
+ * //       file={{ id: f.id, filename: f.filename, mimeType: f.mime_type, url: f.preview_url }}
+ * //       uploading={f.status === "uploading"} onRemove={() => remove(f.id)} />
+ * //   ))
+ * // send:    design({ photo: fileIds[0] }); clear();
+ * ```
+ */
+export function useAttachments() {
+    const { upload } = useFileUpload();
+    const [files, setFiles] = useState([]);
+    const add = useCallback((incoming) => {
+        for (const file of incoming) {
+            const id = `att_${(attachSeq += 1)}`;
+            const previewUrl = URL.createObjectURL(file);
+            setFiles((prev) => [
+                ...prev,
+                { id, filename: file.name, mime_type: file.type, preview_url: previewUrl, status: "uploading" },
+            ]);
+            upload(file)
+                .then((uploaded) => setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "ready", file_id: uploaded.id } : f))))
+                .catch(() => setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "error" } : f))));
+        }
+    }, [upload]);
+    const remove = useCallback((id) => {
+        setFiles((prev) => {
+            const target = prev.find((f) => f.id === id);
+            if (target)
+                URL.revokeObjectURL(target.preview_url);
+            return prev.filter((f) => f.id !== id);
+        });
+    }, []);
+    const clear = useCallback(() => {
+        setFiles((prev) => {
+            for (const f of prev)
+                URL.revokeObjectURL(f.preview_url);
+            return [];
+        });
+    }, []);
+    const uploading = files.some((f) => f.status === "uploading");
+    const fileIds = files.flatMap((f) => (f.status === "ready" && f.file_id ? [f.file_id] : []));
+    return { files, add, remove, clear, uploading, fileIds };
+}
 /**
  * List the members of the app's organization — the candidate set for an
  * "assign to a member" picker. Each member is `{ id, name, email, image }`

package/dist/src/index.d.ts

@@ -16,8 +16,8 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
-export type { UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentRunStep, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
+export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentRunStep, 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";

package/dist/src/index.js

@@ -15,7 +15,7 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";

package/package.json

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