@ashwin_droid/notion-stream 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ashwin_droid
+
+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,418 @@
+# @ashwin_droid/notion-stream
+
+A React component that converts streaming markdown into editable Notion-like blocks with real-time rendering. Perfect for AI chat interfaces, collaborative editors, and any application that needs to display and edit markdown content in a beautiful, block-based format.
+
+## Features
+
+- **Streaming Support**: Renders markdown in real-time as it streams in (perfect for LLM responses)
+- **Notion-like Editing**: Click-to-edit blocks with familiar keyboard shortcuts
+- **Rich Block Types**: Paragraphs, headings (H1-H6), lists, blockquotes, code blocks, tables, images, math (LaTeX), Mermaid diagrams, and dividers
+- **Inline Formatting**: Bold, italic, strikethrough, inline code, links, and inline math
+- **Slash Commands**: Type `/` to quickly insert any block type
+- **Markdown Shortcuts**: Type `#`, `-`, `1.`, `>`, `` ``` ``, `---` etc. to convert blocks
+- **Dark Mode**: Built-in light/dark theme support with system preference detection
+- **Diff Review**: Built-in utilities for comparing and reviewing markdown changes
+- **Fully Typed**: Complete TypeScript support with exported types
+- **Customizable**: Hooks for custom block rendering and slash commands
+
+## Installation
+
+```bash
+npm install @ashwin_droid/notion-stream
+# or
+yarn add @ashwin_droid/notion-stream
+# or
+pnpm add @ashwin_droid/notion-stream
+```
+
+## Quick Start
+
+```tsx
+import { NotionStream } from '@ashwin_droid/notion-stream'
+import '@ashwin_droid/notion-stream/styles.css'
+
+function App() {
+  const [markdown, setMarkdown] = useState('# Hello World\n\nStart typing...')
+
+  return (
+    <NotionStream
+      markdown={markdown}
+      onMarkdownChange={setMarkdown}
+    />
+  )
+}
+```
+
+## Usage with Streaming (AI Chat)
+
+```tsx
+import { NotionStream } from '@ashwin_droid/notion-stream'
+import '@ashwin_droid/notion-stream/styles.css'
+
+function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
+  const [markdown, setMarkdown] = useState('')
+  const [isStreaming, setIsStreaming] = useState(true)
+
+  useEffect(() => {
+    async function consume() {
+      for await (const chunk of stream) {
+        setMarkdown(prev => prev + chunk)
+      }
+      setIsStreaming(false)
+    }
+    consume()
+  }, [stream])
+
+  return (
+    <NotionStream
+      markdown={markdown}
+      isStreaming={isStreaming}
+      onMarkdownChange={setMarkdown}
+    />
+  )
+}
+```
+
+## Props
+
+### `NotionStreamProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `markdown` | `string` | required | The markdown content to render |
+| `isStreaming` | `boolean` | `false` | Whether content is currently streaming in |
+| `onMarkdownChange` | `(markdown: string) => void` | - | Callback when content is edited |
+| `className` | `string` | `''` | Additional CSS classes |
+| `theme` | `'light' \| 'dark' \| 'system'` | auto-detect | Theme mode |
+| `readonly` | `boolean` | `false` | Disable editing (viewer mode) |
+| `hooks` | `BlockHooks` | - | Custom block hooks (see below) |
+
+## Block Types
+
+NotionStream supports the following block types:
+
+| Block | Markdown Syntax | Description |
+|-------|----------------|-------------|
+| Paragraph | Plain text | Default text block |
+| Heading 1-6 | `# ` to `###### ` | Section headings |
+| Bulleted List | `- ` or `* ` | Unordered list items |
+| Numbered List | `1. ` | Ordered list items |
+| Blockquote | `> ` | Quote blocks |
+| Code Block | ` ``` ` | Syntax-highlighted code |
+| Math Block | `$$` | LaTeX equations (KaTeX) |
+| Mermaid | ` ```mermaid ` | Diagrams and flowcharts |
+| Table | `\| ... \|` | Markdown tables |
+| Image | `![alt](url)` | Image blocks |
+| Divider | `---` | Horizontal rule |
+
+## Inline Formatting
+
+| Style | Markdown | Result |
+|-------|----------|--------|
+| Bold | `**text**` | **text** |
+| Italic | `*text*` or `_text_` | *text* |
+| Strikethrough | `~~text~~` | ~~text~~ |
+| Inline Code | `` `code` `` | `code` |
+| Link | `[text](url)` | [text](url) |
+| Inline Math | `$x^2$` | Rendered LaTeX |
+
+## Keyboard Shortcuts
+
+### Block Operations
+- `Enter` - Create new block below (in paragraphs/lists)
+- `Backspace` at start - Delete empty block or merge with previous
+- `Tab` / `Shift+Tab` - Indent/outdent list items
+- `/` on empty block - Open slash command menu
+
+### Markdown Shortcuts (type at start of empty block)
+- `# ` - Heading 1
+- `## ` - Heading 2
+- `### ` - Heading 3
+- `- ` or `* ` - Bulleted list
+- `1. ` - Numbered list
+- `> ` - Blockquote
+- `` ``` `` - Code block
+- `---` - Divider
+
+## Ref API
+
+Access the imperative API using a ref:
+
+```tsx
+import { useRef } from 'react'
+import { NotionStream, NotionStreamRef } from '@ashwin_droid/notion-stream'
+
+function Editor() {
+  const ref = useRef<NotionStreamRef>(null)
+
+  const addCodeBlock = () => {
+    ref.current?.insertBlockAfter(null, {
+      type: 'code',
+      language: 'typescript',
+      content: '// Your code here'
+    })
+  }
+
+  return (
+    <>
+      <button onClick={addCodeBlock}>Add Code Block</button>
+      <NotionStream ref={ref} markdown="" />
+    </>
+  )
+}
+```
+
+### `NotionStreamRef` Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `updateBlock` | `(blockId: string, value: string \| Span[]) => void` | Update block content |
+| `getBlock` | `(blockId: string) => Block \| null` | Get block by ID |
+| `getAllBlocks` | `() => Block[]` | Get all blocks |
+| `getMarkdown` | `() => string` | Get current markdown |
+| `insertBlockAfter` | `(blockId: string \| null, block: BlockInsert) => string` | Insert new block |
+| `deleteBlock` | `(blockId: string) => void` | Delete a block |
+| `setBlockType` | `(blockId: string, type: BlockType, options?) => void` | Change block type |
+| `indentListItem` | `(blockId: string) => void` | Indent list item |
+| `outdentListItem` | `(blockId: string) => void` | Outdent list item |
+
+## Custom Block Rendering
+
+Use hooks to customize block rendering:
+
+```tsx
+import { NotionStream, BlockHooks, Block } from '@ashwin_droid/notion-stream'
+
+const hooks: BlockHooks = {
+  renderBlock: (block: Block, defaultRender: () => React.ReactNode) => {
+    // Custom rendering for specific blocks
+    if (block.type === 'code' && block.language === 'custom') {
+      return <MyCustomCodeBlock code={block.content} />
+    }
+    // Fall back to default rendering
+    return defaultRender()
+  },
+
+  onBlockChange: (blockId: string, newValue: string | Span[], block: Block) => {
+    console.log('Block changed:', blockId, newValue)
+  }
+}
+
+function Editor() {
+  return <NotionStream markdown="" hooks={hooks} />
+}
+```
+
+## Custom Slash Commands
+
+Add your own slash commands:
+
+```tsx
+const hooks: BlockHooks = {
+  getSlashCommands: ({ block }) => [
+    {
+      id: 'callout',
+      title: 'Callout',
+      description: 'Highlighted callout box',
+      group: 'Custom',
+      aliases: ['info', 'warning'],
+      icon: <InfoIcon />,
+      execute: (api, { blockId }) => {
+        api.setBlockType(blockId, 'blockquote')
+        api.updateBlock(blockId, [{ text: 'Callout content', style: 'plain' }])
+      }
+    }
+  ]
+}
+```
+
+## Diff Review Utilities
+
+Compare and review markdown changes:
+
+```tsx
+import { useDiffReview } from '@ashwin_droid/notion-stream'
+
+function DiffReviewer({ original, modified }: { original: string; modified: string }) {
+  const {
+    items,          // Array of diff items
+    decisions,      // Current accept/reject decisions
+    accept,         // Accept a change
+    reject,         // Reject a change
+    resultMarkdown, // Final markdown after applying decisions
+    stats           // { added, removed, modified, accepted, rejected, pending }
+  } = useDiffReview({
+    baseMarkdown: original,
+    nextMarkdown: modified,
+    defaultDecision: 'unset'
+  })
+
+  return (
+    <div>
+      {items.map(item => (
+        <div key={item.id}>
+          {item.type === 'added' && <span className="text-green-500">+ {item.markdown}</span>}
+          {item.type === 'removed' && <span className="text-red-500">- {item.markdown}</span>}
+          {item.type !== 'unchanged' && (
+            <>
+              <button onClick={() => accept(item.id)}>Accept</button>
+              <button onClick={() => reject(item.id)}>Reject</button>
+            </>
+          )}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### Diff Utilities
+
+| Function | Description |
+|----------|-------------|
+| `computeDiff(a, b)` | Word-level diff between strings |
+| `computeCodeDiff(a, b)` | Line-level diff for code with inline highlights |
+| `computeMarkdownBlockDiff(a, b)` | Block-level markdown diff |
+| `computeMarkdownDiffReviewItems(a, b)` | Structured diff for review UI |
+| `applyMarkdownDiffReview(items, decisions)` | Apply review decisions to get final markdown |
+
+## Low-Level Hooks
+
+For advanced use cases, individual hooks are exported:
+
+```tsx
+import {
+  useStreamParser,       // Parse markdown into blocks
+  useBlockState,         // Manage block state
+  useMarkdownShortcuts,  // Handle markdown shortcuts
+  useDiffReview          // Diff review utilities
+} from '@ashwin_droid/notion-stream'
+```
+
+## Span Utilities
+
+Work with inline formatting:
+
+```tsx
+import {
+  parseMarkdownToSpans,  // Parse inline markdown to spans
+  spansToMarkdown,       // Convert spans back to markdown
+  spansToHtml,           // Convert spans to HTML
+  renderSpans,           // Render spans as React nodes
+  applyStyleToRange,     // Apply style to text range
+  toggleStyle            // Toggle inline style
+} from '@ashwin_droid/notion-stream'
+```
+
+## Block Components
+
+Individual block components are exported for custom layouts:
+
+```tsx
+import {
+  ParagraphBlock,
+  HeadingBlock,
+  CodeBlock,
+  ImageBlock,
+  MathBlock,
+  MermaidBlock,
+  ListBlock,
+  BlockquoteBlock,
+  DividerBlock
+} from '@ashwin_droid/notion-stream'
+```
+
+## Theming
+
+### Auto Theme Detection
+
+By default, NotionStream detects the theme from:
+1. `.dark` class on `<html>` or `<body>` elements
+2. System preference via `prefers-color-scheme`
+
+### Explicit Theme
+
+```tsx
+<NotionStream markdown="" theme="dark" />
+<NotionStream markdown="" theme="light" />
+<NotionStream markdown="" theme="system" />
+```
+
+### CSS Variables
+
+Customize colors using CSS variables:
+
+```css
+.notion-stream {
+  --notion-bg: #ffffff;
+  --notion-text: #1f2937;
+  --notion-text-secondary: #6b7280;
+  --notion-border: #e5e7eb;
+  /* ... see styles.css for all variables */
+}
+
+.notion-stream.dark {
+  --notion-bg: #1f2937;
+  --notion-text: #f3f4f6;
+  /* ... */
+}
+```
+
+## TypeScript Types
+
+All types are exported:
+
+```tsx
+import type {
+  Block,
+  BlockType,
+  InlineBlock,
+  Span,
+  InlineStyle,
+  ListType,
+  BlockInsert,
+  SlashCommand,
+  NotionStreamProps,
+  NotionStreamRef,
+  BlockHooks,
+  BlockProps,
+  Theme,
+  TableAlign,
+  TableBlock,
+  DiffSegment,
+  CodeDiff,
+  MarkdownDiffReviewItem,
+  DiffReviewDecision
+} from '@ashwin_droid/notion-stream'
+```
+
+## Peer Dependencies
+
+This package requires:
+- `react` >= 18.0.0
+- `react-dom` >= 18.0.0
+
+## Dependencies
+
+NotionStream uses:
+- [streamdown](https://npmjs.com/package/streamdown) - Streaming markdown rendering
+- [katex](https://katex.org/) - LaTeX math rendering
+- [nanoid](https://github.com/ai/nanoid) - Unique ID generation
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Acknowledgments
+
+Inspired by Notion's block-based editing experience.