@retor/react-native 0.4.5 → 0.4.6

package/README.md

@@ -111,24 +111,43 @@ function MyLineCard({ line }: { line: RetorLine }) {
 
 ## Notes
 
-`<AddNoteSheet>` triggers when you call `useAddNote().open(tagId?)` — for example from a "+" button on the active tag in your `LineTagList`. It collects text + private/public, then calls `onNoteSubmit` on the parent `<Viewer>`. **Persistence is your responsibility** — store the note however you like, then re-pass updated notes back to Retor via `<Notes>`.
+`<AddNoteSheet>` triggers when you call `useAddNote().open(tagId?)`. It collects text + private/public, then either:
+- calls `onNoteSubmit` on the parent `<Viewer>` (if set) — **persistence is your responsibility**
+- or falls back to persisting via Retor's own backend (Convex) when no `onNoteSubmit` is provided
+
+Re-pass saved notes back to the 3D scene via `<Notes>`.
+
+### Note fields for proper rendering
+
+When passing notes via `<Notes>`, each note should include:
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `_id` | yes | Unique identifier |
+| `name` | yes | The note text (displayed in the tag list and 3D scene) |
+| `position` | yes | `{ x, y, z }` — where the note sits on the line |
+| `objectId` | yes | Set to the `lineId` so the note associates with the correct line |
+| `progress` | yes | `0..1` position along the line (from the submit payload) — used for sort order and scroll-to |
+| `avatarUrl` | recommended | Profile image URL — renders as a circular avatar in the tag pill and list item |
+| `authorName` | recommended | Display name — used as initial-letter fallback when no `avatarUrl` |
+| `tagType` | recommended | Set to `"icon"` for the standard note pill appearance |
+| `userId` | for deletion | The note author's user ID — compared against `Viewer.userId` to show the delete button |
+
+### Creating + deleting notes
 
 ```tsx
 import { useState } from "react";
-import { Viewer, Hud, ProjectSheet, LineDetailSheet, AddNoteSheet, Notes, useAddNote, type RetorTag } from "@retor/react-native";
-
-function AddButton() {
-  const { open } = useAddNote();
-  return <Pressable onPress={() => open()}><Text>+</Text></Pressable>;
-}
+import { Viewer, Hud, ProjectSheet, LineDetailSheet, AddNoteSheet, Notes, type RetorTag } from "@retor/react-native";
 
 export default function Scene() {
   const [notes, setNotes] = useState<RetorTag[]>([]);
+  const currentUserId = "user_abc"; // your auth system's user ID
 
   return (
     <Viewer
       projectId="abc123"
-      onNoteSubmit={({ text, isPrivate, tagId, lineId, position }) => {
+      userId={currentUserId}
+      onNoteSubmit={({ text, isPrivate, lineId, position, progress }) => {
         if (!position) return;
         setNotes((prev) => [
           ...prev,
@@ -136,24 +155,24 @@ export default function Scene() {
             _id: `note-${Date.now()}`,
             name: text,
             position,
+            progress,
             objectId: lineId ?? undefined,
+            tagType: "icon",
+            avatarUrl: "https://example.com/avatar.jpg",
+            authorName: "Jane",
+            userId: currentUserId,
           },
         ]);
       }}
+      onNoteDelete={(noteId) => {
+        setNotes((prev) => prev.filter((n) => n._id !== noteId));
+        // also delete from your backend
+      }}
     >
       <Notes notes={notes} />
       <Hud>
         <ProjectSheet />
-        <LineDetailSheet>
-          <LineTagList>
-            {(tag, isActive) => (
-              <View style={{ flexDirection: "row", padding: 12 }}>
-                <Text style={{ flex: 1, color: isActive ? "white" : "gray" }}>{tag.name}</Text>
-                {isActive && <AddButton />}
-              </View>
-            )}
-          </LineTagList>
-        </LineDetailSheet>
+        <LineDetailSheet />
         <AddNoteSheet />
       </Hud>
     </Viewer>
@@ -161,6 +180,12 @@ export default function Scene() {
 }
 ```
 
+When `onNoteSubmit` is **not** provided, the SDK sends the note to Retor's backend automatically (using the signed-in Clerk session inside the WebView). No `<Notes>` re-injection needed in that case.
+
+When a user deletes a note, the SDK:
+1. Optimistically removes it from the local tag list
+2. Fires `onNoteDelete(noteId)` so you can delete from your backend
+
 ## Hooks
 
 All hooks read from the bridge context provided by the parent `<Viewer>`.
@@ -173,7 +198,7 @@ All hooks read from the bridge context provided by the parent `<Viewer>`.
 | `useLineProgress()` | `{ progress, closestTagId }` |
 | `useAutoplay()` | `{ isPlaying, toggle, play, pause }` |
 | `useAddNote()` | `{ isOpen, tagId, open, close, submit }` |
-| `useViewer()` | Imperative controls (`openLine`, `exitLine`, `scrollToTag`, ...) |
+| `useViewer()` | Imperative controls (`openLine`, `exitLine`, `scrollToTag`, `scrollToProgress`, ...) |
 
 ## Imperative API
 

package/dist/index.d.mts

@@ -36,6 +36,8 @@ interface RetorLine {
     scrollType?: "track" | "observe";
     closed?: boolean;
     notesSupported?: boolean;
+    /** User-defined key/value fields set in the line editor. */
+    metadata?: Record<string, string | number | boolean>;
     tags: RetorTag[];
 }
 interface RetorProject {

package/dist/index.d.ts

@@ -36,6 +36,8 @@ interface RetorLine {
     scrollType?: "track" | "observe";
     closed?: boolean;
     notesSupported?: boolean;
+    /** User-defined key/value fields set in the line editor. */
+    metadata?: Record<string, string | number | boolean>;
     tags: RetorTag[];
 }
 interface RetorProject {

package/dist/index.js

@@ -667,7 +667,7 @@ function LineDetailSheet({ snapPoints = ["35%", "75%"], topInset, renderHeader,
       backgroundComponent: BlurBackground,
       topInset: effectiveTopInset
     },
-    activeLine && (children ?? /* @__PURE__ */ import_react6.default.createElement(DefaultLineTagList, { listHeader: header }))
+    activeLine && (children ? /* @__PURE__ */ import_react6.default.createElement(import_bottom_sheet3.BottomSheetScrollView, { contentContainerStyle: styles3.customContent }, children) : /* @__PURE__ */ import_react6.default.createElement(DefaultLineTagList, { listHeader: header }))
   );
 }
 function DefaultHeader({
@@ -792,6 +792,7 @@ function DefaultTagItem({ tag, isActive }) {
 }
 var styles3 = import_react_native5.StyleSheet.create({
   handle: { backgroundColor: "rgba(255,255,255,0.3)" },
+  customContent: { paddingBottom: 120 },
   header: {
     flexDirection: "row",
     alignItems: "flex-start",

package/dist/index.mjs

@@ -628,7 +628,7 @@ function LineDetailSheet({ snapPoints = ["35%", "75%"], topInset, renderHeader,
       backgroundComponent: BlurBackground,
       topInset: effectiveTopInset
     },
-    activeLine && (children ?? /* @__PURE__ */ React6.createElement(DefaultLineTagList, { listHeader: header }))
+    activeLine && (children ? /* @__PURE__ */ React6.createElement(BottomSheetScrollView, { contentContainerStyle: styles3.customContent }, children) : /* @__PURE__ */ React6.createElement(DefaultLineTagList, { listHeader: header }))
   );
 }
 function DefaultHeader({
@@ -753,6 +753,7 @@ function DefaultTagItem({ tag, isActive }) {
 }
 var styles3 = StyleSheet5.create({
   handle: { backgroundColor: "rgba(255,255,255,0.3)" },
+  customContent: { paddingBottom: 120 },
   header: {
     flexDirection: "row",
     alignItems: "flex-start",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retor/react-native",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "React Native SDK for embedding Retor 3D experiences",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",