@washi-ui/react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+import { WashiAdapter, WashiMode, MountOptions, PinPlacedEvent, Comment, NewComment, Washi } from '@washi-ui/core';
+export { Comment, CommentClickedEvent, CommentDeletedEvent, CommentUpdatedEvent, ErrorEvent, ModeChangedEvent, MountOptions, NewComment, PinPlacedEvent, WashiAdapter, WashiEvent, WashiMode } from '@washi-ui/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1, { ReactNode, IframeHTMLAttributes } from 'react';
+
+/**
+ * Options for the useWashi hook
+ */
+interface UseWashiOptions {
+    /** Required: The storage adapter for persisting comments */
+    adapter: WashiAdapter;
+    /** Optional: Initial mode ('view' or 'annotate'). Defaults to 'view' */
+    initialMode?: WashiMode;
+    /** Optional: Mount options for the Washi instance */
+    mountOptions?: MountOptions;
+    /** Optional: Callback when a pin is placed on the overlay in annotate mode */
+    onPinPlaced?: (event: PinPlacedEvent) => void;
+    /** Optional: Callback when a pin is clicked */
+    onCommentClick?: (comment: Comment) => void;
+    /** Optional: Callback when a comment is updated */
+    onCommentUpdate?: (data: {
+        id: string;
+        updates: Partial<Comment>;
+    }) => void;
+    /** Optional: Callback when a comment is deleted */
+    onCommentDelete?: (id: string) => void;
+}
+/**
+ * Return type of the useWashi hook
+ */
+interface UseWashiReturn {
+    /** Ref to attach to the iframe element */
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    /** Current mode */
+    mode: WashiMode;
+    /** Function to change the mode */
+    setMode: (mode: WashiMode) => void;
+    /** Array of all comments */
+    comments: Comment[];
+    /** Add a new comment. Returns the completed Comment with generated id and createdAt. */
+    addComment: (input: NewComment) => Promise<Comment>;
+    /** Update an existing comment */
+    updateComment: (id: string, updates: Partial<Comment>) => Promise<void>;
+    /** Delete a comment */
+    deleteComment: (id: string) => Promise<void>;
+    /** Whether the Washi instance is mounted and ready */
+    isReady: boolean;
+    /** Any error that occurred during mounting or operations */
+    error: Error | null;
+}
+/**
+ * React hook for using Washi comment system.
+ *
+ * @param options - Configuration options
+ * @returns Object with iframe ref, state, and methods
+ *
+ * @example
+ * ```tsx
+ * function CommentableContent() {
+ *   const {
+ *     iframeRef,
+ *     mode,
+ *     setMode,
+ *     comments,
+ *     addComment,
+ *     isReady
+ *   } = useWashi({
+ *     adapter: new MyAdapter(),
+ *     onPinPlaced: ({ x, y }) => {
+ *       // Show comment input dialog at position
+ *     },
+ *     onCommentClick: (comment) => {
+ *       // Show comment details
+ *     }
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setMode(mode === 'view' ? 'annotate' : 'view')}>
+ *         Toggle Mode
+ *       </button>
+ *       <div style={{ position: 'relative' }}>
+ *         <iframe ref={iframeRef} src="/content.html" />
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useWashi(options: UseWashiOptions): UseWashiReturn;
+
+/**
+ * Context value provided by WashiProvider
+ */
+interface WashiContextValue {
+    /** The Washi instance (null if not mounted) */
+    washi: Washi | null;
+    /** The registered iframe element (null if not mounted) */
+    iframeEl: HTMLIFrameElement | null;
+    /** Current mode */
+    mode: WashiMode;
+    /** Function to change the mode */
+    setMode: (mode: WashiMode) => void;
+    /** Array of all comments */
+    comments: Comment[];
+    /** Add a new comment. Returns the completed Comment with generated id and createdAt. */
+    addComment: (input: NewComment) => Promise<Comment>;
+    /** Update an existing comment */
+    updateComment: (id: string, updates: Partial<Comment>) => Promise<void>;
+    /** Delete a comment */
+    deleteComment: (id: string) => Promise<void>;
+    /** Refresh comments from adapter */
+    refreshComments: () => void;
+    /** Whether the Washi instance is mounted and ready */
+    isReady: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Register an iframe element for mounting */
+    registerIframe: (iframe: HTMLIFrameElement | null) => void;
+    /** Subscribe to pin placement events (overlay clicked in annotate mode) */
+    onPinPlaced: (callback: (event: PinPlacedEvent) => void) => () => void;
+    /** Subscribe to comment click events */
+    onCommentClick: (callback: (comment: Comment) => void) => () => void;
+    /** Set the active pin for highlighting */
+    setActivePin: (commentId: string | null) => void;
+    /** Get the index of a comment (sorted by createdAt) */
+    getCommentIndex: (commentId: string) => number;
+    /** Currently selected/active comment (for custom dialog rendering) */
+    activeComment: Comment | null;
+    /** Set the active comment (for custom dialog rendering) */
+    setActiveComment: (comment: Comment | null) => void;
+}
+/**
+ * Props for WashiProvider
+ */
+interface WashiProviderProps {
+    /** Required: The storage adapter for persisting comments */
+    adapter: WashiAdapter;
+    /** Optional: Initial mode ('view' or 'annotate'). Defaults to 'view' */
+    initialMode?: WashiMode;
+    /** Optional: Mount options for the Washi instance */
+    mountOptions?: MountOptions;
+    /** Child components */
+    children: ReactNode;
+}
+/**
+ * Provider component for Washi context.
+ * Use with WashiFrame and useWashiContext.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <WashiProvider adapter={new MyAdapter()}>
+ *       <WashiFrame src="/content.html" />
+ *       <CommentSidebar />
+ *     </WashiProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function WashiProvider({ adapter, initialMode, mountOptions, children, }: WashiProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access Washi context.
+ * Must be used within a WashiProvider.
+ *
+ * @throws Error if used outside of WashiProvider
+ *
+ * @example
+ * ```tsx
+ * function CommentSidebar() {
+ *   const { comments, deleteComment } = useWashiContext();
+ *
+ *   return (
+ *     <ul>
+ *       {comments.map(c => (
+ *         <li key={c.id}>
+ *           {c.text}
+ *           <button onClick={() => deleteComment(c.id)}>Delete</button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useWashiContext(): WashiContextValue;
+
+/**
+ * Props for WashiFrame component
+ */
+interface WashiFrameProps extends Omit<IframeHTMLAttributes<HTMLIFrameElement>, 'ref'> {
+    /** URL to load in the iframe. Omit when using srcDoc to pass an HTML string. */
+    src?: string;
+    /** Optional: Additional CSS class name */
+    className?: string;
+    /** Optional: Inline styles */
+    style?: React$1.CSSProperties;
+}
+/**
+ * Iframe wrapper component that automatically registers with WashiProvider.
+ * Must be used within a WashiProvider.
+ *
+ * @example
+ * ```tsx
+ * <WashiProvider adapter={adapter}>
+ *   <WashiFrame
+ *     src="/content.html"
+ *     style={{ width: '100%', height: '600px', border: 'none' }}
+ *   />
+ * </WashiProvider>
+ * ```
+ */
+declare function WashiFrame({ src, className, style, ...props }: WashiFrameProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for CommentList component
+ */
+interface CommentListProps {
+    /**
+     * Render function for each comment.
+     * Receives the comment and action handlers.
+     */
+    renderComment: (comment: Comment, actions: {
+        onResolve: () => Promise<void>;
+        onDelete: () => Promise<void>;
+        onUpdate: (updates: Partial<Comment>) => Promise<void>;
+    }) => ReactNode;
+    /**
+     * Optional: Filter function to show only certain comments
+     */
+    filter?: (comment: Comment) => boolean;
+    /**
+     * Optional: Sort function for comments
+     */
+    sort?: (a: Comment, b: Comment) => number;
+    /**
+     * Optional: Component to render when there are no comments
+     */
+    emptyState?: ReactNode;
+    /**
+     * Optional: CSS class name for the list container
+     */
+    className?: string;
+    /**
+     * Optional: Inline styles for the list container
+     */
+    style?: React$1.CSSProperties;
+}
+/**
+ * Helper component for rendering a list of comments.
+ * Must be used within a WashiProvider.
+ *
+ * @example
+ * ```tsx
+ * <CommentList
+ *   renderComment={(comment, { onResolve, onDelete }) => (
+ *     <div key={comment.id} className="comment-item">
+ *       <p>{comment.text}</p>
+ *       <div className="actions">
+ *         <button onClick={onResolve}>
+ *           {comment.resolved ? 'Unresolve' : 'Resolve'}
+ *         </button>
+ *         <button onClick={onDelete}>Delete</button>
+ *       </div>
+ *     </div>
+ *   )}
+ *   filter={(c) => !c.resolved}
+ *   sort={(a, b) => b.createdAt - a.createdAt}
+ *   emptyState={<p>No comments yet</p>}
+ * />
+ * ```
+ */
+declare function CommentList({ renderComment, filter, sort, emptyState, className, style, }: CommentListProps): react_jsx_runtime.JSX.Element;
+
+type WashiToolBubblePosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+interface WashiToolBubbleProps {
+    position?: WashiToolBubblePosition;
+    sidebarOpen?: boolean;
+    onSidebarToggle?: () => void;
+    accentColor?: string;
+}
+declare function WashiToolBubble({ position, sidebarOpen, onSidebarToggle, accentColor, }: WashiToolBubbleProps): react_jsx_runtime.JSX.Element;
+
+interface WashiCommentsSidebarProps {
+    open: boolean;
+    onClose: () => void;
+    /** Which corner the tool bubble is anchored to. Panel slides in from that side and stops above the bubble. Default: 'bottom-right' */
+    position?: WashiToolBubblePosition;
+    accentColor?: string;
+}
+declare function WashiCommentsSidebar({ open, onClose, position, accentColor, }: WashiCommentsSidebarProps): react_jsx_runtime.JSX.Element | null;
+
+interface WashiPinDialogProps {
+    accentColor?: string;
+    /** Optional callback fired after a comment is successfully created */
+    onComment?: (comment: Comment) => void;
+}
+/**
+ * Self-contained pin comment dialog.
+ *
+ * Subscribes to `pin:placed` events from the context and renders a small
+ * popover anchored to the clicked position. On submit it calls `addComment`
+ * and switches the mode back to 'view' automatically.
+ *
+ * Drop this anywhere inside a `<WashiProvider>` — no props required.
+ */
+declare function WashiPinDialog({ accentColor, onComment }: WashiPinDialogProps): react_jsx_runtime.JSX.Element | null;
+
+interface WashiUIProps {
+    /** Corner where the tool bubble (and sidebar) are anchored. Default: 'bottom-right' */
+    position?: WashiToolBubblePosition;
+    accentColor?: string;
+    /** Show a loading spinner while the iframe initialises. Default: true */
+    showLoader?: boolean;
+}
+/**
+ * All-in-one Washi UI layer.
+ *
+ * Renders the tool bubble, comments sidebar, pin dialog, and an optional
+ * loading overlay — all wired together. Drop it inside a `<WashiProvider>`.
+ *
+ * @example
+ * ```tsx
+ * <WashiProvider adapter={adapter}>
+ *   <div style={{ position: 'fixed', inset: 0 }}>
+ *     <WashiFrame src="/content.html" style={{ width: '100%', height: '100%', border: 'none' }} />
+ *   </div>
+ *   <WashiUI />
+ * </WashiProvider>
+ * ```
+ */
+declare function WashiUI({ position, accentColor, showLoader, }: WashiUIProps): react_jsx_runtime.JSX.Element;
+
+export { CommentList, type CommentListProps, type UseWashiOptions, type UseWashiReturn, WashiCommentsSidebar, type WashiCommentsSidebarProps, type WashiContextValue, WashiFrame, type WashiFrameProps, WashiPinDialog, type WashiPinDialogProps, WashiProvider, type WashiProviderProps, WashiToolBubble, type WashiToolBubblePosition, type WashiToolBubbleProps, WashiUI, type WashiUIProps, useWashi, useWashiContext };