@retor/react-native 0.1.0 → 0.2.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,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 };