@washi-ui/react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Chavez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# @washi-ui/react
+
+React bindings for the Washi HTML commenting engine. Provides a context provider, hooks, and ready-made UI components for adding pin-based annotations to any iframe-rendered content.
+
+## Installation
+
+```bash
+npm install @washi-ui/react @washi-ui/core
+```
+
+---
+
+## Quick Start
+
+### Drop-in UI (`WashiProvider` + `WashiFrame` + `WashiUI`)
+
+The fastest path. `WashiUI` renders a floating tool bubble, a comments sidebar, and a pin dialog — no custom UI needed.
+
+```tsx
+import { useMemo } from 'react';
+import { WashiProvider, WashiFrame, WashiUI } from '@washi-ui/react';
+import { LocalStorageAdapter } from '@washi-ui/adapters';
+
+export default function App() {
+  const adapter = useMemo(() => new LocalStorageAdapter('my-page'), []);
+
+  return (
+    <WashiProvider adapter={adapter}>
+      <WashiFrame
+        src="/content.html"
+        style={{ width: '100%', height: '100vh', border: 'none' }}
+      />
+      <WashiUI position="bottom-right" />
+    </WashiProvider>
+  );
+}
+```
+
+### Custom UI (`useWashi` hook)
+
+For full control over the interface, use the `useWashi` hook directly:
+
+```tsx
+import { useWashi } from '@washi-ui/react';
+import { LocalStorageAdapter } from '@washi-ui/adapters';
+
+const adapter = new LocalStorageAdapter('my-page');
+
+function App() {
+  const { iframeRef, mode, setMode, comments, addComment } = useWashi({
+    adapter,
+    onPinPlaced: async ({ x, y }) => {
+      // Called when the user clicks the overlay in annotate mode.
+      // Show your own dialog, then call addComment.
+      const text = prompt('Add a comment:');
+      if (text) await addComment({ x, y, text });
+    },
+    onCommentClick: (comment) => {
+      console.log('Pin clicked:', comment.text);
+    },
+  });
+
+  return (
+    <div>
+      <button onClick={() => setMode(mode === 'annotate' ? 'view' : 'annotate')}>
+        {mode === 'annotate' ? 'Done' : 'Annotate'}
+      </button>
+      <div style={{ position: 'relative' }}>
+        <iframe
+          ref={iframeRef}
+          src="/content.html"
+          style={{ width: '100%', height: '600px', border: 'none' }}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Components
+
+### `<WashiProvider>`
+
+Context provider that creates and manages the Washi instance. Wrap your iframe and any Washi UI components inside it.
+
+```tsx
+<WashiProvider
+  adapter={adapter}
+  initialMode="view"
+  mountOptions={{ readOnly: false, disableBuiltinDialog: false }}
+>
+  {children}
+</WashiProvider>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `adapter` | `WashiAdapter` | required | Storage adapter |
+| `initialMode` | `'view' \| 'annotate'` | `'view'` | Starting mode |
+| `mountOptions` | `MountOptions` | — | Passed to `washi.mount()` |
+
+---
+
+### `<WashiFrame>`
+
+An `<iframe>` wrapper that auto-registers with the nearest `WashiProvider`. Accepts all standard iframe attributes.
+
+```tsx
+<WashiFrame
+  src="/content.html"
+  style={{ width: '100%', height: '100vh', border: 'none' }}
+/>
+
+{/* Or with inline HTML */}
+<WashiFrame
+  srcDoc={htmlString}
+  style={{ width: '100%', height: '100vh', border: 'none' }}
+/>
+```
+
+Must be used inside a `WashiProvider`.
+
+---
+
+### `<WashiUI>`
+
+All-in-one floating UI layer. Renders `WashiToolBubble`, `WashiCommentsSidebar`, and `WashiPinDialog` together, wired up and ready to use.
+
+```tsx
+<WashiUI position="bottom-right" accentColor="#667eea" />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `WashiToolBubblePosition` | `'bottom-right'` | Corner for the tool bubble and sidebar |
+| `accentColor` | `string` | `'#667eea'` | Accent color for buttons and pins |
+| `showLoader` | `boolean` | `true` | Show a loading spinner while the iframe initialises |
+
+Must be used inside a `WashiProvider`.
+
+---
+
+### `<WashiToolBubble>`
+
+The floating pill button that toggles annotate mode and opens the sidebar. Use this directly when building a custom layout with the other primitive components.
+
+```tsx
+<WashiToolBubble
+  position="bottom-right"
+  accentColor="#667eea"
+  sidebarOpen={sidebarOpen}
+  onSidebarToggle={() => setSidebarOpen(o => !o)}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `WashiToolBubblePosition` | `'bottom-right'` | Viewport corner |
+| `accentColor` | `string` | `'#667eea'` | Active state colour |
+| `sidebarOpen` | `boolean` | `false` | Whether sidebar is open (controls icon state) |
+| `onSidebarToggle` | `() => void` | — | Called when the sidebar button is clicked |
+
+---
+
+### `<WashiCommentsSidebar>`
+
+A slide-in panel listing all comments with resolve/delete actions.
+
+```tsx
+<WashiCommentsSidebar
+  open={sidebarOpen}
+  onClose={() => setSidebarOpen(false)}
+  position="bottom-right"
+  accentColor="#667eea"
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | required | Controls visibility |
+| `onClose` | `() => void` | required | Called when the close button is clicked |
+| `position` | `WashiToolBubblePosition` | `'bottom-right'` | Which side to slide in from |
+| `accentColor` | `string` | `'#667eea'` | Accent colour for resolved badges |
+
+---
+
+### `<WashiPinDialog>`
+
+A popover that appears when the user places a pin in annotate mode. Handles text input, calls `addComment`, and switches back to view mode on submit.
+
+```tsx
+<WashiPinDialog
+  accentColor="#667eea"
+  onComment={(comment) => console.log('Created:', comment.id)}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `accentColor` | `string` | `'#667eea'` | Submit button colour |
+| `onComment` | `(comment: Comment) => void` | — | Called after a comment is successfully created |
+
+---
+
+### `<CommentList>`
+
+Headless list component for rendering comments with custom UI. Reads from context and exposes `onResolve`, `onDelete`, and `onUpdate` action handlers.
+
+```tsx
+<CommentList
+  renderComment={(comment, { onResolve, onDelete }) => (
+    <div key={comment.id} className="comment">
+      <p>{comment.text}</p>
+      <button onClick={onResolve}>
+        {comment.resolved ? 'Unresolve' : 'Resolve'}
+      </button>
+      <button onClick={onDelete}>Delete</button>
+    </div>
+  )}
+  filter={(c) => !c.resolved}
+  sort={(a, b) => b.createdAt - a.createdAt}
+  emptyState={<p>No comments yet.</p>}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderComment` | `(comment, actions) => ReactNode` | Render function for each comment |
+| `filter` | `(comment) => boolean` | Optional filter predicate |
+| `sort` | `(a, b) => number` | Optional sort comparator |
+| `emptyState` | `ReactNode` | Rendered when no comments match |
+
+---
+
+## `useWashi(options)`
+
+Low-level hook for managing a Washi instance directly. Returns a ref to attach to a plain `<iframe>` element plus all state and methods.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `adapter` | `WashiAdapter` | required | Storage adapter |
+| `initialMode` | `WashiMode` | `'view'` | Starting mode |
+| `mountOptions` | `MountOptions` | — | Passed to `washi.mount()` |
+| `onPinPlaced` | `(event: PinPlacedEvent) => void` | — | Called when overlay is clicked in annotate mode |
+| `onCommentClick` | `(comment: Comment) => void` | — | Called when a pin is clicked |
+| `onCommentUpdate` | `(data) => void` | — | Called after a comment is updated |
+| `onCommentDelete` | `(id: string) => void` | — | Called after a comment is deleted |
+
+### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `iframeRef` | `RefObject<HTMLIFrameElement>` | Attach to your `<iframe>` element |
+| `mode` | `WashiMode` | Current mode (`'view'` or `'annotate'`) |
+| `setMode` | `(mode: WashiMode) => void` | Switch modes |
+| `comments` | `Comment[]` | All current comments |
+| `addComment` | `(input: NewComment) => Promise<Comment>` | Add a comment — `id` and `createdAt` are generated automatically |
+| `updateComment` | `(id, updates) => Promise<void>` | Update a comment |
+| `deleteComment` | `(id) => Promise<void>` | Delete a comment |
+| `isReady` | `boolean` | True once the iframe has loaded and Washi has mounted |
+| `error` | `Error \| null` | Any mount or operation error |
+
+---
+
+## `useWashiContext()`
+
+Access the Washi context from any component inside a `WashiProvider`.
+
+```tsx
+function StatusBar() {
+  const { mode, comments, isReady } = useWashiContext();
+
+  return (
+    <div>
+      {isReady ? `${comments.length} comments · ${mode} mode` : 'Loading…'}
+    </div>
+  );
+}
+```
+
+---
+
+## TypeScript
+
+All types are re-exported from `@washi-ui/react` for convenience:
+
+```typescript
+import type {
+  Comment,
+  NewComment,
+  WashiMode,
+  WashiEvent,
+  WashiAdapter,
+  MountOptions,
+  PinPlacedEvent,
+  CommentUpdatedEvent,
+  CommentDeletedEvent,
+  CommentClickedEvent,
+  ModeChangedEvent,
+  ErrorEvent,
+} from '@washi-ui/react';
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };