@velo-sci/notebook-react 0.6.1

package/dist/index.d.cts

@@ -0,0 +1,312 @@
+import * as React from 'react';
+import React__default from 'react';
+import { EditorEngine, Cell as Cell$1, Notebook, EventPayload, SciNotebookPlugin, CellType, CellOutput } from '@velo-sci/notebook-core';
+import { RenderPipeline } from '@velo-sci/notebook-renderer';
+
+declare const NotebookContext: React.Context<EditorEngine | null>;
+declare function useSciNotebook(): EditorEngine;
+declare function useNotebook(): Readonly<Notebook>;
+declare function useCell(cellId: string): Readonly<Cell$1> | undefined;
+declare function useFocusedCell(): string | null;
+declare function useNotebookEvent(type: string, handler: (payload: EventPayload) => void): void;
+
+interface SciNotebookProps {
+    /** Pre-built notebook object */
+    notebook?: Notebook;
+    /** Pre-built engine (takes priority over notebook) */
+    engine?: EditorEngine;
+    /** Plugins to register */
+    plugins?: SciNotebookPlugin[];
+    /** Zero-config: just pass markdown content */
+    initialContent?: string;
+    /** Theme */
+    theme?: "light" | "dark" | string;
+    /** Callback when notebook changes */
+    onChange?: (notebook: Notebook) => void;
+    /** Callback when a cell is focused */
+    onCellFocus?: (cellId: string | null) => void;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** Show/hide the top toolbar */
+    showToolbar?: boolean;
+    /** CSS class */
+    className?: string;
+    /** Inline styles */
+    style?: React__default.CSSProperties;
+    /** Imperative engine access */
+    engineRef?: React__default.MutableRefObject<EditorEngine | null>;
+    /** Show TOC sidebar */
+    showTOC?: boolean;
+}
+declare const SciNotebook: React__default.FC<SciNotebookProps>;
+
+interface CellProps {
+    cellId: string;
+    pipeline: RenderPipeline;
+    index: number;
+    totalCells: number;
+}
+declare const Cell: React__default.FC<CellProps>;
+
+interface InsertHandleProps {
+    index: number;
+}
+declare const InsertHandle: React__default.FC<InsertHandleProps>;
+
+interface FloatingToolbarProps {
+    cellId: string;
+    textareaRef: React__default.RefObject<HTMLTextAreaElement | null>;
+}
+declare const FloatingToolbar: React__default.FC<FloatingToolbarProps>;
+
+interface MathEditorProps {
+    cellId: string;
+    source: string;
+    onExit: () => void;
+}
+declare const MathEditor: React__default.FC<MathEditorProps>;
+
+interface ImageCellProps {
+    cellId: string;
+    source: string;
+    metadata: Record<string, unknown>;
+    onExit: () => void;
+}
+declare const ImageCell: React__default.FC<ImageCellProps>;
+declare function renderImagePreview(source: string, metadata: Record<string, unknown>): string;
+
+interface EmbedCellProps {
+    cellId: string;
+    source: string;
+    metadata: Record<string, unknown>;
+    onExit: () => void;
+}
+declare const EmbedCell: React__default.FC<EmbedCellProps>;
+declare function renderEmbedPreview(source: string, metadata: Record<string, unknown>): string;
+
+interface SlashCommandItem {
+    type: CellType;
+    label: string;
+    description: string;
+    icon: string;
+    keywords: string[];
+}
+declare const DEFAULT_COMMANDS: SlashCommandItem[];
+interface SlashCommandProps {
+    /** Position relative to the textarea */
+    position: {
+        top: number;
+        left: number;
+    };
+    /** Filter query (text after /) */
+    query: string;
+    /** Called when a command is selected */
+    onSelect: (type: CellType) => void;
+    /** Called when the menu should close */
+    onClose: () => void;
+    /** Custom commands (optional, extends defaults) */
+    extraCommands?: SlashCommandItem[];
+}
+declare const SlashCommand: React__default.FC<SlashCommandProps>;
+
+interface TableCellProps {
+    cellId: string;
+    source: string;
+    metadata: Record<string, unknown>;
+    onExit: () => void;
+}
+declare const TableCell: React__default.FC<TableCellProps>;
+declare function renderTablePreview(source: string): string;
+
+interface TOCItem {
+    cellId: string;
+    level: number;
+    text: string;
+}
+declare const TOCSidebar: React__default.FC<{
+    focusedCellId?: string | null;
+}>;
+
+interface FindMatch {
+    cellId: string;
+    index: number;
+    length: number;
+}
+interface FindReplaceProps {
+    onClose: () => void;
+}
+declare const FindReplace: React__default.FC<FindReplaceProps>;
+
+declare const LATEX_COMMANDS: Array<{
+    cmd: string;
+    desc: string;
+    category: string;
+}>;
+interface LatexAutocompleteProps {
+    query: string;
+    position: {
+        top: number;
+        left: number;
+    };
+    onSelect: (cmd: string) => void;
+    onClose: () => void;
+}
+declare const LatexAutocomplete: React__default.FC<LatexAutocompleteProps>;
+
+interface CellOutputProps {
+    outputs: CellOutput[];
+}
+declare const CellOutputDisplay: React__default.FC<CellOutputProps>;
+
+/**
+ * Ghost Text overlay for AI inline completions.
+ *
+ * Renders a semi-transparent suggestion after the cursor position
+ * in a textarea. User presses Tab to accept, Escape to dismiss.
+ */
+
+interface GhostTextProps {
+    text: string;
+    textareaRef: React__default.RefObject<HTMLTextAreaElement | null>;
+    onAccept: () => void;
+    onDismiss: () => void;
+}
+declare const GhostText: React__default.FC<GhostTextProps>;
+
+/**
+ * AI Chat Sidebar for sci-notebook.
+ *
+ * Provides a conversational interface for interacting with AI providers.
+ * Supports sending messages, receiving streamed responses, and applying
+ * suggestions to cells.
+ */
+
+interface ChatMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp: number;
+    cellRefs?: string[];
+}
+interface ChatSidebarProps {
+    /** Function to send a message to the AI provider */
+    onSend?: (message: string, history: ChatMessage[]) => Promise<string>;
+    /** Initial system prompt */
+    systemPrompt?: string;
+    /** Callback when user wants to apply a suggestion to a cell */
+    onApply?: (content: string, cellId?: string) => void;
+    /** Close handler */
+    onClose?: () => void;
+}
+declare const ChatSidebar: React__default.FC<ChatSidebarProps>;
+
+/**
+ * Image Resize Handles for sci-notebook.
+ *
+ * Wraps an image element with draggable resize handles (SE corner).
+ * Reports new width back to the parent via onResize callback.
+ */
+
+interface ImageResizeProps {
+    src: string;
+    alt?: string;
+    initialWidth: string;
+    maxWidth?: string;
+    onResize: (newWidth: string) => void;
+    children?: React__default.ReactNode;
+}
+declare const ImageResize: React__default.FC<ImageResizeProps>;
+
+/**
+ * VirtualRenderer for sci-notebook.
+ *
+ * Renders only the cells visible in the viewport for large notebooks (50+ cells).
+ * Uses IntersectionObserver for efficient visibility tracking and a sentinel
+ * element approach for smooth scrolling.
+ */
+
+interface VirtualRendererProps {
+    cells: ReadonlyArray<Cell$1>;
+    pipeline: RenderPipeline;
+    /** Estimated cell height in px (default: 120) */
+    estimatedHeight?: number;
+    /** Number of cells to render above/below viewport (default: 5) */
+    overscan?: number;
+}
+declare const VirtualRenderer: React__default.FC<VirtualRendererProps>;
+
+/**
+ * MermaidCell — Renders Mermaid diagrams asynchronously.
+ *
+ * Uses globalThis.mermaid (consumer must import and expose mermaid).
+ * Handles async mermaid.render() from v10+.
+ */
+
+interface MermaidPreviewProps {
+    source: string;
+    onClick?: () => void;
+}
+declare const MermaidPreview: React__default.FC<MermaidPreviewProps>;
+/**
+ * Initialize mermaid globally. Call this once in your app entry point.
+ *
+ * @example
+ * ```ts
+ * import mermaid from "mermaid";
+ * import { initMermaid } from "@velo-sci/notebook-react";
+ * initMermaid(mermaid);
+ * ```
+ */
+declare function initMermaid(mermaidLib: any, config?: Record<string, unknown>): void;
+
+/**
+ * AI Rewrite Flow for sci-notebook.
+ *
+ * Flow: select text → prompt → preview diff → accept/reject
+ *
+ * This component renders as a floating panel near the selected text,
+ * allowing the user to provide a rewrite instruction and preview the result.
+ */
+
+interface AIRewriteProps {
+    /** The currently selected text to rewrite */
+    selectedText: string;
+    /** Position to render the panel */
+    position: {
+        top: number;
+        left: number;
+    };
+    /** Called with the rewrite instruction; should return rewritten text */
+    onRewrite: (instruction: string, selectedText: string) => Promise<string>;
+    /** Called when user accepts the rewrite */
+    onAccept: (newText: string) => void;
+    /** Called when user rejects / closes */
+    onReject: () => void;
+}
+declare const AIRewrite: React__default.FC<AIRewriteProps>;
+
+/**
+ * AI Cell Generation UI for sci-notebook.
+ *
+ * Flow: prompt → generate → preview → insert cells
+ *
+ * Renders as a modal/inline panel where the user types a prompt,
+ * the AI generates one or more cells, and the user can accept or reject.
+ */
+
+interface GeneratedCell {
+    type: CellType;
+    source: string;
+}
+interface AICellGenerateProps {
+    /** Called with the prompt; should return generated cells */
+    onGenerate: (prompt: string) => Promise<GeneratedCell[]>;
+    /** Called when user accepts the generated cells */
+    onAccept: (cells: GeneratedCell[]) => void;
+    /** Called when user closes without accepting */
+    onCancel: () => void;
+    /** Insert position index */
+    insertIndex: number;
+}
+declare const AICellGenerate: React__default.FC<AICellGenerateProps>;
+
+export { AICellGenerate, type AICellGenerateProps, AIRewrite, type AIRewriteProps, Cell, CellOutputDisplay, type CellProps, type ChatMessage, ChatSidebar, type ChatSidebarProps, DEFAULT_COMMANDS, EmbedCell, type FindMatch, FindReplace, FloatingToolbar, type GeneratedCell, GhostText, ImageCell, ImageResize, InsertHandle, LATEX_COMMANDS, LatexAutocomplete, MathEditor, MermaidPreview, NotebookContext, SciNotebook, type SciNotebookProps, SlashCommand, type SlashCommandItem, type TOCItem, TOCSidebar, TableCell, VirtualRenderer, initMermaid, renderEmbedPreview, renderImagePreview, renderTablePreview, useCell, useFocusedCell, useNotebook, useNotebookEvent, useSciNotebook };

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+import * as React from 'react';
+import React__default from 'react';
+import { EditorEngine, Cell as Cell$1, Notebook, EventPayload, SciNotebookPlugin, CellType, CellOutput } from '@velo-sci/notebook-core';
+import { RenderPipeline } from '@velo-sci/notebook-renderer';
+
+declare const NotebookContext: React.Context<EditorEngine | null>;
+declare function useSciNotebook(): EditorEngine;
+declare function useNotebook(): Readonly<Notebook>;
+declare function useCell(cellId: string): Readonly<Cell$1> | undefined;
+declare function useFocusedCell(): string | null;
+declare function useNotebookEvent(type: string, handler: (payload: EventPayload) => void): void;
+
+interface SciNotebookProps {
+    /** Pre-built notebook object */
+    notebook?: Notebook;
+    /** Pre-built engine (takes priority over notebook) */
+    engine?: EditorEngine;
+    /** Plugins to register */
+    plugins?: SciNotebookPlugin[];
+    /** Zero-config: just pass markdown content */
+    initialContent?: string;
+    /** Theme */
+    theme?: "light" | "dark" | string;
+    /** Callback when notebook changes */
+    onChange?: (notebook: Notebook) => void;
+    /** Callback when a cell is focused */
+    onCellFocus?: (cellId: string | null) => void;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** Show/hide the top toolbar */
+    showToolbar?: boolean;
+    /** CSS class */
+    className?: string;
+    /** Inline styles */
+    style?: React__default.CSSProperties;
+    /** Imperative engine access */
+    engineRef?: React__default.MutableRefObject<EditorEngine | null>;
+    /** Show TOC sidebar */
+    showTOC?: boolean;
+}
+declare const SciNotebook: React__default.FC<SciNotebookProps>;
+
+interface CellProps {
+    cellId: string;
+    pipeline: RenderPipeline;
+    index: number;
+    totalCells: number;
+}
+declare const Cell: React__default.FC<CellProps>;
+
+interface InsertHandleProps {
+    index: number;
+}
+declare const InsertHandle: React__default.FC<InsertHandleProps>;
+
+interface FloatingToolbarProps {
+    cellId: string;
+    textareaRef: React__default.RefObject<HTMLTextAreaElement | null>;
+}
+declare const FloatingToolbar: React__default.FC<FloatingToolbarProps>;
+
+interface MathEditorProps {
+    cellId: string;
+    source: string;
+    onExit: () => void;
+}
+declare const MathEditor: React__default.FC<MathEditorProps>;
+
+interface ImageCellProps {
+    cellId: string;
+    source: string;
+    metadata: Record<string, unknown>;
+    onExit: () => void;
+}
+declare const ImageCell: React__default.FC<ImageCellProps>;
+declare function renderImagePreview(source: string, metadata: Record<string, unknown>): string;
+
+interface EmbedCellProps {
+    cellId: string;
+    source: string;
+    metadata: Record<string, unknown>;
+    onExit: () => void;
+}
+declare const EmbedCell: React__default.FC<EmbedCellProps>;
+declare function renderEmbedPreview(source: string, metadata: Record<string, unknown>): string;
+
+interface SlashCommandItem {
+    type: CellType;
+    label: string;
+    description: string;
+    icon: string;
+    keywords: string[];
+}
+declare const DEFAULT_COMMANDS: SlashCommandItem[];
+interface SlashCommandProps {
+    /** Position relative to the textarea */
+    position: {
+        top: number;
+        left: number;
+    };
+    /** Filter query (text after /) */
+    query: string;
+    /** Called when a command is selected */
+    onSelect: (type: CellType) => void;
+    /** Called when the menu should close */
+    onClose: () => void;
+    /** Custom commands (optional, extends defaults) */
+    extraCommands?: SlashCommandItem[];
+}
+declare const SlashCommand: React__default.FC<SlashCommandProps>;
+
+interface TableCellProps {
+    cellId: string;
+    source: string;
+    metadata: Record<string, unknown>;
+    onExit: () => void;
+}
+declare const TableCell: React__default.FC<TableCellProps>;
+declare function renderTablePreview(source: string): string;
+
+interface TOCItem {
+    cellId: string;
+    level: number;
+    text: string;
+}
+declare const TOCSidebar: React__default.FC<{
+    focusedCellId?: string | null;
+}>;
+
+interface FindMatch {
+    cellId: string;
+    index: number;
+    length: number;
+}
+interface FindReplaceProps {
+    onClose: () => void;
+}
+declare const FindReplace: React__default.FC<FindReplaceProps>;
+
+declare const LATEX_COMMANDS: Array<{
+    cmd: string;
+    desc: string;
+    category: string;
+}>;
+interface LatexAutocompleteProps {
+    query: string;
+    position: {
+        top: number;
+        left: number;
+    };
+    onSelect: (cmd: string) => void;
+    onClose: () => void;
+}
+declare const LatexAutocomplete: React__default.FC<LatexAutocompleteProps>;
+
+interface CellOutputProps {
+    outputs: CellOutput[];
+}
+declare const CellOutputDisplay: React__default.FC<CellOutputProps>;
+
+/**
+ * Ghost Text overlay for AI inline completions.
+ *
+ * Renders a semi-transparent suggestion after the cursor position
+ * in a textarea. User presses Tab to accept, Escape to dismiss.
+ */
+
+interface GhostTextProps {
+    text: string;
+    textareaRef: React__default.RefObject<HTMLTextAreaElement | null>;
+    onAccept: () => void;
+    onDismiss: () => void;
+}
+declare const GhostText: React__default.FC<GhostTextProps>;
+
+/**
+ * AI Chat Sidebar for sci-notebook.
+ *
+ * Provides a conversational interface for interacting with AI providers.
+ * Supports sending messages, receiving streamed responses, and applying
+ * suggestions to cells.
+ */
+
+interface ChatMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp: number;
+    cellRefs?: string[];
+}
+interface ChatSidebarProps {
+    /** Function to send a message to the AI provider */
+    onSend?: (message: string, history: ChatMessage[]) => Promise<string>;
+    /** Initial system prompt */
+    systemPrompt?: string;
+    /** Callback when user wants to apply a suggestion to a cell */
+    onApply?: (content: string, cellId?: string) => void;
+    /** Close handler */
+    onClose?: () => void;
+}
+declare const ChatSidebar: React__default.FC<ChatSidebarProps>;
+
+/**
+ * Image Resize Handles for sci-notebook.
+ *
+ * Wraps an image element with draggable resize handles (SE corner).
+ * Reports new width back to the parent via onResize callback.
+ */
+
+interface ImageResizeProps {
+    src: string;
+    alt?: string;
+    initialWidth: string;
+    maxWidth?: string;
+    onResize: (newWidth: string) => void;
+    children?: React__default.ReactNode;
+}
+declare const ImageResize: React__default.FC<ImageResizeProps>;
+
+/**
+ * VirtualRenderer for sci-notebook.
+ *
+ * Renders only the cells visible in the viewport for large notebooks (50+ cells).
+ * Uses IntersectionObserver for efficient visibility tracking and a sentinel
+ * element approach for smooth scrolling.
+ */
+
+interface VirtualRendererProps {
+    cells: ReadonlyArray<Cell$1>;
+    pipeline: RenderPipeline;
+    /** Estimated cell height in px (default: 120) */
+    estimatedHeight?: number;
+    /** Number of cells to render above/below viewport (default: 5) */
+    overscan?: number;
+}
+declare const VirtualRenderer: React__default.FC<VirtualRendererProps>;
+
+/**
+ * MermaidCell — Renders Mermaid diagrams asynchronously.
+ *
+ * Uses globalThis.mermaid (consumer must import and expose mermaid).
+ * Handles async mermaid.render() from v10+.
+ */
+
+interface MermaidPreviewProps {
+    source: string;
+    onClick?: () => void;
+}
+declare const MermaidPreview: React__default.FC<MermaidPreviewProps>;
+/**
+ * Initialize mermaid globally. Call this once in your app entry point.
+ *
+ * @example
+ * ```ts
+ * import mermaid from "mermaid";
+ * import { initMermaid } from "@velo-sci/notebook-react";
+ * initMermaid(mermaid);
+ * ```
+ */
+declare function initMermaid(mermaidLib: any, config?: Record<string, unknown>): void;
+
+/**
+ * AI Rewrite Flow for sci-notebook.
+ *
+ * Flow: select text → prompt → preview diff → accept/reject
+ *
+ * This component renders as a floating panel near the selected text,
+ * allowing the user to provide a rewrite instruction and preview the result.
+ */
+
+interface AIRewriteProps {
+    /** The currently selected text to rewrite */
+    selectedText: string;
+    /** Position to render the panel */
+    position: {
+        top: number;
+        left: number;
+    };
+    /** Called with the rewrite instruction; should return rewritten text */
+    onRewrite: (instruction: string, selectedText: string) => Promise<string>;
+    /** Called when user accepts the rewrite */
+    onAccept: (newText: string) => void;
+    /** Called when user rejects / closes */
+    onReject: () => void;
+}
+declare const AIRewrite: React__default.FC<AIRewriteProps>;
+
+/**
+ * AI Cell Generation UI for sci-notebook.
+ *
+ * Flow: prompt → generate → preview → insert cells
+ *
+ * Renders as a modal/inline panel where the user types a prompt,
+ * the AI generates one or more cells, and the user can accept or reject.
+ */
+
+interface GeneratedCell {
+    type: CellType;
+    source: string;
+}
+interface AICellGenerateProps {
+    /** Called with the prompt; should return generated cells */
+    onGenerate: (prompt: string) => Promise<GeneratedCell[]>;
+    /** Called when user accepts the generated cells */
+    onAccept: (cells: GeneratedCell[]) => void;
+    /** Called when user closes without accepting */
+    onCancel: () => void;
+    /** Insert position index */
+    insertIndex: number;
+}
+declare const AICellGenerate: React__default.FC<AICellGenerateProps>;
+
+export { AICellGenerate, type AICellGenerateProps, AIRewrite, type AIRewriteProps, Cell, CellOutputDisplay, type CellProps, type ChatMessage, ChatSidebar, type ChatSidebarProps, DEFAULT_COMMANDS, EmbedCell, type FindMatch, FindReplace, FloatingToolbar, type GeneratedCell, GhostText, ImageCell, ImageResize, InsertHandle, LATEX_COMMANDS, LatexAutocomplete, MathEditor, MermaidPreview, NotebookContext, SciNotebook, type SciNotebookProps, SlashCommand, type SlashCommandItem, type TOCItem, TOCSidebar, TableCell, VirtualRenderer, initMermaid, renderEmbedPreview, renderImagePreview, renderTablePreview, useCell, useFocusedCell, useNotebook, useNotebookEvent, useSciNotebook };