@retor/react-native 0.1.0 → 0.2.0

package/README.md

@@ -1,147 +1,207 @@
 # @retor/react-native
 
-Embed Retor 3D experiences in a React Native / Expo app via `react-native-webview`.
+Embed Retor 3D experiences in a React Native / Expo app — with composable bottom-sheet UI built on `@gorhom/bottom-sheet`.
 
 ## Installation
 
-Install the peer dependency:
-
 ```bash
 # Expo
-npx expo install react-native-webview
+npx expo install react-native-webview react-native-gesture-handler react-native-reanimated
+npm install @gorhom/bottom-sheet @retor/react-native
 
 # bare React Native
-npm install react-native-webview
+npm install react-native-webview react-native-gesture-handler react-native-reanimated @gorhom/bottom-sheet @retor/react-native
 cd ios && pod install
 ```
 
-Then install the SDK:
+You also need to wrap your app root in a `GestureHandlerRootView` (per `@gorhom/bottom-sheet` requirements):
 
-```bash
-npm install @retor/react-native
-# or
-pnpm add @retor/react-native
-# or
-yarn add @retor/react-native
+```tsx
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <YourApp />
+    </GestureHandlerRootView>
+  );
+}
 ```
 
-## Quick Start
+## Quick Start — Default UI
+
+The fastest way: drop in `<Hud>` with the three sheets and they'll work out of the box.
 
 ```tsx
 import { View } from "react-native";
-import { Viewer, Hud } from "@retor/react-native";
+import { Viewer, Hud, ProjectSheet, LineDetailSheet, AddNoteSheet } from "@retor/react-native";
 
 export default function Scene() {
   return (
     <View style={{ flex: 1 }}>
-      <Viewer projectId="abc123" style={{ flex: 1 }}>
-        <Hud />
+      <Viewer projectId="abc123">
+        <Hud>
+          <ProjectSheet />
+          <LineDetailSheet />
+          <AddNoteSheet />
+        </Hud>
       </Viewer>
     </View>
   );
 }
 ```
 
-## Custom Bottom Sheet
+What you get:
+- A bottom sheet showing the project name and a horizontal carousel of lines
+- Tap a line → second sheet opens with the tag list and a Done button
+- Tap a tag → camera scrolls to it
+- Done returns to the browse sheet
 
-Listen to events and drive a native UI on top of the viewer. Use the `useViewer` hook from any component to control the viewer without threading refs around.
+## Concepts
 
-```tsx
-import { useState } from "react";
-import { View, Text, Pressable, FlatList } from "react-native";
-import { Viewer, useViewer, type RetorLine } from "@retor/react-native";
+- **`<Viewer>`** wraps the WebView and exposes scene state via React context. Always vanilla — Retor itself shows no UI.
+- **`<Hud>`** sets up `BottomSheetModalProvider`. Place sheets and other overlays inside.
+- **Sheets** auto-present based on bridge state:
+  - `<ProjectSheet>` shows when no line is open
+  - `<LineDetailSheet>` shows when a line is open
+  - `<AddNoteSheet>` shows when `useAddNote().open()` is called
+- **Composition components** (`<LinesCarousel>`, `<LineTagList>`) take a render prop so you can replace the visuals while keeping the data wiring.
+
+## Customising the visuals
 
-function Sheet({ lines, activeLine, closestTagId }: {
-  lines: RetorLine[];
-  activeLine: RetorLine | null;
-  closestTagId: string | null;
-}) {
-  const { openLine, exitLine, scrollToTag } = useViewer();
+Each sheet accepts:
+- `snapPoints` — override the default snap points
+- `renderHeader` — replace the header
+- `children` — replace the body (typically a render-prop list)
 
+```tsx
+import { Pressable, Text } from "react-native";
+import { ProjectSheet, LinesCarousel, LineDetailSheet, LineTagList, useViewer } from "@retor/react-native";
+
+function MyLineCard({ line }: { line: RetorLine }) {
+  const { openLine } = useViewer();
   return (
-    <View style={{ position: "absolute", bottom: 32, left: 16, right: 16 }}>
-      {activeLine ? (
-        <View style={{ backgroundColor: "rgba(0,0,0,0.85)", borderRadius: 24, padding: 16 }}>
-          <Text style={{ color: "white", fontSize: 18, fontWeight: "600" }}>{activeLine.name}</Text>
-          <FlatList
-            data={activeLine.tags}
-            keyExtractor={(t) => t._id}
-            renderItem={({ item }) => (
-              <Pressable onPress={() => scrollToTag(item._id)}>
-                <Text style={{ color: item._id === closestTagId ? "white" : "gray" }}>
-                  {item.name}
-                </Text>
-              </Pressable>
-            )}
-          />
-          <Pressable onPress={() => exitLine()}>
-            <Text style={{ color: "white" }}>Done</Text>
-          </Pressable>
-        </View>
-      ) : (
-        <FlatList
-          horizontal
-          data={lines}
-          keyExtractor={(l) => l._id}
-          renderItem={({ item }) => (
-            <Pressable onPress={() => openLine(item._id)}>
-              <Text style={{ color: "white", padding: 16 }}>{item.name}</Text>
-            </Pressable>
-          )}
-        />
-      )}
-    </View>
+    <Pressable
+      onPress={() => openLine(line._id)}
+      style={{ width: 200, padding: 16, backgroundColor: "#222", borderRadius: 16 }}
+    >
+      <Text style={{ color: "white", fontWeight: "600" }}>{line.name}</Text>
+    </Pressable>
   );
 }
 
+<ProjectSheet snapPoints={["20%", "50%"]}>
+  <LinesCarousel>
+    {(line) => <MyLineCard line={line} />}
+  </LinesCarousel>
+</ProjectSheet>
+
+<LineDetailSheet>
+  <LineTagList>
+    {(tag, isActive) => (
+      <Pressable style={{ padding: 12 }}>
+        <Text style={{ color: isActive ? "white" : "gray" }}>{tag.name}</Text>
+      </Pressable>
+    )}
+  </LineTagList>
+</LineDetailSheet>
+```
+
+## 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>`.
+
+```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>;
+}
+
 export default function Scene() {
-  const [lines, setLines] = useState<RetorLine[]>([]);
-  const [activeLine, setActiveLine] = useState<RetorLine | null>(null);
-  const [closestTagId, setClosestTagId] = useState<string | null>(null);
+  const [notes, setNotes] = useState<RetorTag[]>([]);
 
   return (
-    <View style={{ flex: 1 }}>
-      <Viewer
-        projectId="abc123"
-        style={{ flex: 1 }}
-        onInit={(data) => setLines(data.lines)}
-        onLineOpen={({ lineId }) => {
-          const line = lines.find((l) => l._id === lineId);
-          if (line) setActiveLine(line);
-        }}
-        onLineClose={() => setActiveLine(null)}
-        onLineProgress={({ closestTagId }) => setClosestTagId(closestTagId)}
-      />
-      <Sheet lines={lines} activeLine={activeLine} closestTagId={closestTagId} />
-    </View>
+    <Viewer
+      projectId="abc123"
+      onNoteSubmit={({ text, isPrivate, tagId, lineId, position }) => {
+        if (!position) return;
+        setNotes((prev) => [
+          ...prev,
+          {
+            _id: `note-${Date.now()}`,
+            name: text,
+            position,
+            objectId: lineId ?? undefined,
+          },
+        ]);
+      }}
+    >
+      <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>
+        <AddNoteSheet />
+      </Hud>
+    </Viewer>
   );
 }
 ```
 
-## Notes on WebView setup
+## Hooks
 
-- The SDK sets `originWhitelist=["*"]`, `javaScriptEnabled`, and `domStorageEnabled` automatically
-- Inline media playback is enabled without user gesture
-- Messages are JSON-stringified across the bridge — handled transparently
-- On Android, inbound messages are dispatched via `injectJavaScript`
+All hooks read from the bridge context provided by the parent `<Viewer>`.
 
-## Passing in Notes
+| Hook | Returns |
+|------|---------|
+| `useProject()` | The current `RetorProject` (or null) |
+| `useLines()` | Array of `RetorLine` |
+| `useActiveLine()` | The currently open line (or null) |
+| `useLineProgress()` | `{ progress, closestTagId }` |
+| `useAutoplay()` | `{ isPlaying, toggle, play, pause }` |
+| `useAddNote()` | `{ isOpen, tagId, open, close, submit }` |
+| `useViewer()` | Imperative controls (`openLine`, `exitLine`, `scrollToTag`, ...) |
 
-Use `<Notes>` as a child of the Viewer to push user-generated tags into the 3D scene. Same API as the React SDK — re-render with an updated array to sync changes.
+## Imperative API
+
+The `useViewer` hook also supports controlling a specific viewer by ID:
 
 ```tsx
-import { Viewer, Notes, type RetorTag } from "@retor/react-native";
+<Viewer id="left" projectId="..." />
+<Viewer id="right" projectId="..." />
+
+const left = useViewer("left");
+left.openLine("line-a");
+```
 
-const [notes, setNotes] = useState<RetorTag[]>([]);
+Or pass a ref directly:
 
-<Viewer projectId="..." style={{ flex: 1 }}>
-  <Notes notes={notes} />
-</Viewer>
+```tsx
+const ref = useRef<ViewerHandle>(null);
+<Viewer ref={ref} projectId="..." />
+ref.current?.openLine("...");
 ```
 
-## API
+## Cover photo
 
-Identical to the [React SDK](https://www.npmjs.com/package/@retor/react) — same props, same imperative methods, same `useViewer` hook.
+A static thumbnail of a project's start view — no 3D, no bridge:
+
+```tsx
+import { CoverPhoto } from "@retor/react-native";
+
+<CoverPhoto projectId="abc123" style={{ width: 200, height: 120 }} />
+```
 
 ## License
 

package/dist/index.d.mts

@@ -16,6 +16,7 @@ interface RetorTag {
     color?: string;
     tagType?: string;
     iconName?: string;
+    objectId?: string;
 }
 interface RetorLine {
     _id: string;
@@ -50,12 +51,106 @@ interface ViewerHandle {
     toggleAutoplay: () => void;
     setAutoplay: (playing: boolean) => void;
 }
+
+interface NoteSubmitPayload {
+    text: string;
+    isPrivate: boolean;
+    tagId: string | null;
+    lineId: string | null;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+}
+interface RetorBridgeContextValue {
+    project: RetorProject | null;
+    lines: RetorLine[];
+    activeLineId: string | null;
+    activeLine: RetorLine | null;
+    closestTagId: string | null;
+    progress: number;
+    isPlaying: boolean;
+    isAddNoteOpen: boolean;
+    addNoteTagId: string | null;
+    controls: ViewerHandle;
+    openAddNote: (tagId?: string) => void;
+    closeAddNote: () => void;
+    submitNote: (text: string, isPrivate?: boolean) => void;
+    onNoteSubmit?: (payload: NoteSubmitPayload) => void;
+}
+declare function useRetorBridge(): RetorBridgeContextValue;
+/** Returns the array of all lines in the current project. */
+declare function useLines(): RetorLine[];
+/** Returns the project metadata once `init` has fired. */
+declare function useProject(): RetorProject | null;
+/**
+ * Returns the line that's currently open (after the user enters a scroll path),
+ * or null when in browse mode.
+ */
+declare function useActiveLine(): RetorLine | null;
+/**
+ * Returns scroll progress (0..1) and the id of the closest tag along the
+ * currently active line. Both are null when no line is open.
+ */
+declare function useLineProgress(): {
+    progress: number;
+    closestTagId: string | null;
+};
+/**
+ * Returns the autoplay state and controls.
+ */
+declare function useAutoplay(): {
+    isPlaying: boolean;
+    toggle: () => void;
+    play: () => void;
+    pause: () => void;
+};
+/**
+ * Returns the current add-note flow state and actions.
+ */
+declare function useAddNote(): {
+    isOpen: boolean;
+    tagId: string | null;
+    open: (tagId?: string) => void;
+    close: () => void;
+    submit: (text: string, isPrivate?: boolean) => void;
+};
+
+/**
+ * Hook for controlling a Viewer from anywhere in your tree.
+ *
+ * Default usage (single viewer):
+ * ```tsx
+ * const { openLine, exitLine } = useViewer();
+ * ```
+ *
+ * Multiple viewers:
+ * ```tsx
+ * <Viewer id="left" projectId="..." />
+ * const left = useViewer("left");
+ * ```
+ *
+ * With a ref:
+ * ```tsx
+ * const ref = useRef<ViewerHandle>(null);
+ * const { openLine } = useViewer(ref);
+ * ```
+ */
+declare function useViewer(target?: string | React.RefObject<ViewerHandle | null>): ViewerHandle;
+interface NotesProps {
+    /** Array of notes (same shape as RetorTag) to push into the 3D scene. */
+    notes: RetorTag[];
+}
+declare function Notes(_props: NotesProps): React.ReactElement | null;
 interface ViewerProps {
     projectId: string;
     /** Identifier for this viewer instance. Used by `useViewer(id)`. Defaults to "default". */
     id?: string;
     /** Base URL where Retor is hosted. Defaults to https://retor.app */
     baseUrl?: string;
+    /** Called when a note is submitted via `<AddNoteSheet>`. Receives the text + position. */
+    onNoteSubmit?: (note: NoteSubmitPayload) => void;
     onInit?: (data: InitPayload) => void;
     onLineOpen?: (data: {
         lineId: string;
@@ -66,48 +161,132 @@ interface ViewerProps {
     style?: StyleProp<ViewStyle>;
     children?: React.ReactNode;
 }
+declare const Viewer: React.ForwardRefExoticComponent<ViewerProps & React.RefAttributes<ViewerHandle>>;
+
+interface HudProps {
+    children: React.ReactNode;
+}
 /**
- * Hook that returns a destructured set of viewer controls.
+ * Sets up the bottom-sheet provider tree for the SDK's UI components
+ * (`<ProjectSheet>`, `<LineDetailSheet>`, `<AddNoteSheet>`).
  *
- * Usage with an ID (default "default"):
- * ```tsx
- * <Viewer projectId="..." />            // id defaults to "default"
- * const { openLine, exitLine } = useViewer();
- * ```
+ * Place inside `<Viewer>` so the sheets can read scene state from the bridge:
  *
- * With an explicit ID (multiple viewers on one screen):
  * ```tsx
- * <Viewer id="left" projectId="..." />
- * <Viewer id="right" projectId="..." />
- * const left = useViewer("left");
- * left.openLine("...");
+ * <Viewer projectId="...">
+ *   <Hud>
+ *     <ProjectSheet />
+ *     <LineDetailSheet />
+ *     <AddNoteSheet />
+ *   </Hud>
+ * </Viewer>
  * ```
+ */
+declare function Hud({ children }: HudProps): React.JSX.Element;
+
+interface ProjectSheetProps {
+    /**
+     * Snap points for the sheet. Defaults to ["20%", "60%"].
+     */
+    snapPoints?: (string | number)[];
+    /**
+     * Override the default header (project name + description).
+     * Receives the project metadata.
+     */
+    renderHeader?: (project: {
+        name?: string;
+        description?: string;
+    }) => React.ReactNode;
+    /**
+     * Children to render below the header. Typically a `<LinesCarousel>`.
+     * If omitted, a default LinesCarousel is rendered.
+     */
+    children?: React.ReactNode;
+}
+/**
+ * The browse-mode bottom sheet. Auto-presents whenever no line is open.
  *
- * With a ref (if you prefer imperative style):
  * ```tsx
- * const ref = useRef<ViewerHandle>(null);
- * <Viewer ref={ref} projectId="..." />
- * const { openLine } = useViewer(ref);
+ * <ProjectSheet>
+ *   <LinesCarousel>
+ *     {(line) => <MyLineCard line={line} />}
+ *   </LinesCarousel>
+ * </ProjectSheet>
  * ```
  */
-declare function useViewer(target?: string | React.RefObject<ViewerHandle | null>): ViewerHandle;
+declare function ProjectSheet({ snapPoints, renderHeader, children }: ProjectSheetProps): React.JSX.Element;
+interface LinesCarouselProps {
+    children: (line: RetorLine, index: number) => React.ReactNode;
+    /** Optional gap between items. Defaults to 12. */
+    gap?: number;
+    /** Optional horizontal padding. Defaults to 16. */
+    paddingHorizontal?: number;
+}
 /**
- * Include as a child of `<Viewer>` to show Retor's built-in UI
- * (info card, tag list, autoplay controls). Without it, the viewer runs in
- * vanilla mode — you build your own UI around the 3D scene using the props.
+ * Renders a horizontally scrolling list of lines using a render prop.
+ * Place inside `<ProjectSheet>`.
+ *
+ * Pressing an item is up to your render — use `useViewer().openLine(line._id)`.
  */
-declare function Hud(): React.ReactElement | null;
-interface NotesProps {
-    /** Array of notes (same shape as RetorTag) to pass into the 3D scene. */
-    notes: RetorTag[];
+declare function LinesCarousel({ children, gap, paddingHorizontal }: LinesCarouselProps): React.JSX.Element | null;
+
+interface LineDetailSheetProps {
+    /** Snap points. Defaults to ["25%", "75%"]. */
+    snapPoints?: (string | number)[];
+    /** Override the header. Receives the active line. */
+    renderHeader?: (line: RetorLine) => React.ReactNode;
+    /** Custom content (typically a `<LineTagList>`). Defaults to a built-in tag list. */
+    children?: React.ReactNode;
 }
 /**
- * Pass user-generated notes into the Retor scene as a child of `<Viewer>`.
- * The notes use the same shape as a RetorTag — Retor will render them in
- * the scene and tag lists. Persistence is handled entirely by your app:
- * re-render with an updated `notes` array to sync changes.
+ * Sheet that auto-presents when the user enters a line. Shows the line's
+ * tags and a Done button. Pass `<LineTagList>` as a child to customise items.
  */
-declare function Notes(_props: NotesProps): React.ReactElement | null;
-declare const Viewer: React.ForwardRefExoticComponent<ViewerProps & React.RefAttributes<ViewerHandle>>;
+declare function LineDetailSheet({ snapPoints, renderHeader, children }: LineDetailSheetProps): React.JSX.Element;
+interface LineTagListProps {
+    children: (tag: RetorTag, isActive: boolean) => React.ReactNode;
+}
+/**
+ * Renders the tags of the active line as a vertical list. Re-renders the
+ * active item when the camera scrolls to it. Empty when no line is open.
+ */
+declare function LineTagList({ children }: LineTagListProps): React.JSX.Element | null;
+
+interface AddNoteSheetProps {
+    /** Snap points. Defaults to ["50%"]. */
+    snapPoints?: (string | number)[];
+    /** Max characters allowed. Defaults to 280. */
+    maxLength?: number;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Override the entire form. Receives helpers + state. */
+    renderForm?: (api: AddNoteFormApi) => React.ReactNode;
+}
+interface AddNoteFormApi {
+    text: string;
+    setText: (v: string) => void;
+    isPrivate: boolean;
+    setPrivate: (v: boolean) => void;
+    submit: () => void;
+    close: () => void;
+    maxLength: number;
+}
+/**
+ * Sheet for adding a note. Auto-presents when `useAddNote().open()` is called.
+ * On submit, fires `onNoteSubmit` on the parent `<Viewer>` with the text + position.
+ */
+declare function AddNoteSheet({ snapPoints, maxLength, placeholder, renderForm, }: AddNoteSheetProps): React.JSX.Element;
+
+interface CoverPhotoProps {
+    projectId: string;
+    /** Base URL where Retor is hosted. Defaults to https://retor.app */
+    baseUrl?: string;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Renders a Retor project's start view as a static cover image.
+ * No 3D rendering, no bridge — use as a thumbnail or hero.
+ */
+declare function CoverPhoto({ projectId, baseUrl, style }: CoverPhotoProps): React.JSX.Element;
 
-export { Hud, type InitPayload, type LineProgressPayload, Notes, type NotesProps, type RetorLine, type RetorProject, type RetorTag, Viewer, type ViewerHandle, type ViewerProps, useViewer };
+export { type AddNoteFormApi, AddNoteSheet, type AddNoteSheetProps, CoverPhoto, type CoverPhotoProps, Hud, type HudProps, type InitPayload, LineDetailSheet, type LineDetailSheetProps, type LineProgressPayload, LineTagList, type LineTagListProps, LinesCarousel, type LinesCarouselProps, type NoteSubmitPayload, Notes, type NotesProps, ProjectSheet, type ProjectSheetProps, type RetorBridgeContextValue, type RetorLine, type RetorProject, type RetorTag, Viewer, type ViewerHandle, type ViewerProps, useActiveLine, useAddNote, useAutoplay, useLineProgress, useLines, useProject, useRetorBridge, useViewer };