@retor/react-native 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -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,104 @@ 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();
- * ```
- *
- * With an explicit ID (multiple viewers on one screen):
- * ```tsx
- * <Viewer id="left" projectId="..." />
- * <Viewer id="right" projectId="..." />
- * const left = useViewer("left");
- * left.openLine("...");
- * ```
+ * Place inside `<Viewer>` so the sheets can read scene state from the bridge:
  *
- * With a ref (if you prefer imperative style):
  * ```tsx
- * const ref = useRef<ViewerHandle>(null);
- * <Viewer ref={ref} projectId="..." />
- * const { openLine } = useViewer(ref);
+ * <Viewer projectId="...">
+ *   <Hud>
+ *     <ProjectSheet />
+ *     <LineDetailSheet />
+ *     <AddNoteSheet />
+ *   </Hud>
+ * </Viewer>
  * ```
  */
-declare function useViewer(target?: string | React.RefObject<ViewerHandle | null>): ViewerHandle;
+declare function Hud({ children }: HudProps): React.JSX.Element;
+
+interface ProjectSheetProps {
+    /** Snap points. Defaults to ["35%", "85%"]. */
+    snapPoints?: (string | number)[];
+    /** Override the default header (project name + description + arrow button). */
+    renderHeader?: (project: {
+        name?: string;
+        description?: string;
+    }) => React.ReactNode;
+    /** Children to render inside. Defaults to a built-in `<LinesCarousel>`. */
+    children?: React.ReactNode;
+}
 /**
- * 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.
+ * Browse-mode bottom sheet — auto-presents whenever no line is open.
  */
-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 ProjectSheet({ snapPoints, renderHeader, children }: ProjectSheetProps): React.JSX.Element;
+interface LinesCarouselProps {
+    children: (line: RetorLine, index: number) => React.ReactNode;
+    gap?: number;
+    paddingHorizontal?: number;
+}
+declare function LinesCarousel({ children, gap, paddingHorizontal }: LinesCarouselProps): React.JSX.Element | null;
+
+interface LineDetailSheetProps {
+    /** Snap points. Defaults to ["35%", "85%"]. */
+    snapPoints?: (string | number)[];
+    /** Override the header. */
+    renderHeader?: (line: RetorLine) => React.ReactNode;
+    /** Custom content (typically a `<LineTagList>`). */
+    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 shown when a line is open. Includes a default header with the
+ * autoplay button + minimize arrow, the tag list, and a Done footer.
  */
-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;
+}
+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 };