@railway/inkwell 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,375 @@
+import { ReactNode, JSX, RefObject, KeyboardEvent } from 'react';
+import { Plugin } from 'unified';
+import { Awareness } from 'y-protocols/awareness';
+import { XmlText } from 'yjs';
+import { BaseEditor, BaseElement, BaseText } from 'slate';
+import { HistoryEditor } from 'slate-history';
+import { ReactEditor } from 'slate-react';
+
+type RehypePlugin$1 = Plugin<any[], any>;
+type RehypePluginConfig$1 = RehypePlugin$1 | [RehypePlugin$1, Record<string, unknown>];
+/**
+ * Props for the InkwellEditor component.
+ */
+interface InkwellEditorProps {
+    /**
+     * Markdown content string
+     */
+    content: string;
+    /**
+     * Called with serialized markdown on every document change
+     */
+    onChange?: (content: string) => void;
+    /**
+     * Additional CSS class for the wrapper element
+     */
+    className?: string;
+    /**
+     * Placeholder text shown when editor is empty
+     */
+    placeholder?: string;
+    /**
+     * Editor plugins (bubble toolbar, snippets, custom)
+     */
+    plugins?: InkwellPlugin[];
+    /**
+     * Custom rehype plugins for the syntax highlighting pipeline
+     */
+    rehypePlugins?: RehypePluginConfig$1[];
+    /**
+     * Configure which block-level decorations the editor recognizes. All enabled by default.
+     */
+    decorations?: InkwellDecorations;
+    /**
+     * Enable real-time collaborative editing via Yjs
+     */
+    collaboration?: CollaborationConfig;
+    /**
+     * Include the built-in bubble menu plugin (default: true). Pass `false` to
+     * disable the built-in toolbar; consumers can still add their own via `plugins`.
+     */
+    bubbleMenu?: boolean;
+}
+/**
+ * Props for the InkwellRenderer component.
+ */
+interface InkwellRendererProps {
+    /**
+     * Markdown content string
+     */
+    content: string;
+    /**
+     * Additional CSS class for the wrapper element
+     */
+    className?: string;
+    /**
+     * Custom component overrides for rendered markdown elements
+     */
+    components?: InkwellComponents;
+    /**
+     * Custom rehype plugins for the markdown pipeline
+     */
+    rehypePlugins?: RehypePluginConfig$1[];
+    /**
+     * Show a copy button on fenced code blocks (default: true)
+     */
+    copyButton?: boolean;
+}
+/**
+ * Map of HTML element names to custom React components
+ */
+type InkwellComponents = Partial<{
+    [K in keyof JSX.IntrinsicElements]: (props: JSX.IntrinsicElements[K] & {
+        children?: ReactNode;
+    }) => ReactNode;
+}>;
+/**
+ * Keyboard trigger for a plugin.
+ *
+ * Uses tinykeys-style key strings:
+ * - `"Control+/"` — modifier combo, prevents default
+ * - `"@"` — single character, typed into editor (e.g. for mentions)
+ */
+interface PluginTrigger {
+    /**
+     * Key combo (tinykeys format)
+     */
+    key: string;
+}
+/**
+ * Props passed to every plugin's render function on every render
+ */
+interface PluginRenderProps {
+    /**
+     * Whether this plugin's trigger has fired (always true for plugins without triggers)
+     */
+    active: boolean;
+    /**
+     * Text typed after the trigger fired
+     */
+    query: string;
+    /**
+     * Insert text into the editor at the current cursor position
+     */
+    onSelect: (text: string) => void;
+    /**
+     * Deactivate this plugin (resets `active` to false)
+     */
+    onDismiss: () => void;
+    /**
+     * Cursor position when the trigger fired
+     */
+    position: {
+        top: number;
+        left: number;
+    };
+    /**
+     * Ref to the editor's contenteditable element
+     */
+    editorRef: RefObject<HTMLDivElement | null>;
+    /**
+     * Wrap the current selection with markdown markers
+     */
+    wrapSelection: (before: string, after: string) => void;
+}
+/**
+ * Context passed to a plugin's `onKeyDown` handler.
+ */
+interface PluginKeyDownContext {
+    /**
+     * Wrap the current selection with markdown markers
+     */
+    wrapSelection: (before: string, after: string) => void;
+}
+/**
+ * A Inkwell editor plugin.
+ *
+ * Every plugin is always rendered. Plugins with a `trigger` receive
+ * `active: true` when the trigger fires and `active: false` otherwise.
+ * Plugins without a trigger always receive `active: true`.
+ */
+interface InkwellPlugin {
+    /**
+     * Unique plugin name
+     */
+    name: string;
+    /**
+     * Optional keyboard trigger
+     */
+    trigger?: PluginTrigger;
+    /**
+     * Render the plugin UI. Return `null` when inactive.
+     */
+    render: (props: PluginRenderProps) => ReactNode;
+    /**
+     * Optional keydown handler. Runs for events on the editor before trigger
+     * matching, and is skipped while another plugin is active. Call
+     * `event.preventDefault()` to stop further dispatch for this event.
+     */
+    onKeyDown?: (event: KeyboardEvent, ctx: PluginKeyDownContext) => void;
+}
+/**
+ * Props passed to each bubble menu item component.
+ */
+interface BubbleMenuItemProps {
+    /**
+     * Wrap or unwrap the current selection with markdown markers. Toggles if already wrapped.
+     */
+    wrapSelection: (before: string, after: string) => void;
+}
+/**
+ * An item in the bubble menu.
+ */
+interface BubbleMenuItem {
+    /**
+     * Unique key for React reconciliation
+     */
+    key: string;
+    /**
+     * Optional keyboard shortcut (single key, used with Cmd/Ctrl).
+     */
+    shortcut?: string;
+    /**
+     * Action to run when the shortcut fires. Receives wrapSelection.
+     */
+    onShortcut?: (wrapSelection: (before: string, after: string) => void) => void;
+    /**
+     * React component to render in the menu. Receives `wrapSelection`.
+     */
+    render: (props: BubbleMenuItemProps) => ReactNode;
+}
+/**
+ * Snippet item for the snippets plugin
+ */
+interface Snippet {
+    /**
+     * Display title (searchable)
+     */
+    title: string;
+    /**
+     * Markdown content to insert
+     */
+    content: string;
+}
+/**
+ * Controls which markdown block elements the editor recognizes.
+ * All decorations are enabled by default. Pass `false` to disable.
+ */
+interface InkwellDecorations {
+    /**
+     * Recognize `# ` as h1 (default: true)
+     */
+    heading1?: boolean;
+    /**
+     * Recognize `## ` as h2 (default: true)
+     */
+    heading2?: boolean;
+    /**
+     * Recognize `### ` as h3 (default: true)
+     */
+    heading3?: boolean;
+    /**
+     * Recognize `#### ` as h4 (default: true)
+     */
+    heading4?: boolean;
+    /**
+     * Recognize `##### ` as h5 (default: true)
+     */
+    heading5?: boolean;
+    /**
+     * Recognize `###### ` as h6 (default: true)
+     */
+    heading6?: boolean;
+    /**
+     * Recognize `- `, `* `, `+ ` as list items (default: true)
+     */
+    lists?: boolean;
+    /**
+     * Recognize `> ` as blockquotes (default: true)
+     */
+    blockquotes?: boolean;
+    /**
+     * Recognize ``` fences as code blocks (default: true)
+     */
+    codeBlocks?: boolean;
+}
+/**
+ * Configuration for real-time collaborative editing via Yjs.
+ *
+ * The consumer owns the Yjs document and provider (WebSocket,
+ * WebRTC, Hocuspocus, etc.). Inkwell only needs the shared type
+ * and awareness instance.
+ */
+interface CollaborationConfig {
+    /**
+     * Yjs shared type for the document. Create via `doc.get("content", Y.XmlText)`.
+     */
+    sharedType: XmlText;
+    /**
+     * Awareness instance for remote cursor/presence sharing.
+     */
+    awareness: Awareness;
+    /**
+     * Local user metadata, displayed on remote cursors.
+     */
+    user: {
+        name: string;
+        color: string;
+    };
+}
+
+declare function InkwellEditor$1({ content, onChange, className, placeholder, plugins: userPlugins, rehypePlugins, decorations, collaboration, bubbleMenu, }: InkwellEditorProps): ReactNode;
+
+/**
+ * Element types in the Inkwell editor
+ */
+type ElementType = "paragraph" | "code-fence" | "code-line" | "blockquote" | "list-item" | "heading";
+/**
+ * A block-level element in the editor
+ */
+interface InkwellElement extends BaseElement {
+    type: ElementType;
+    /**
+     * Unique element identifier. Session-scoped, not persisted in markdown.
+     */
+    id: string;
+    /**
+     * Heading level (1-6). Only present on `heading` elements.
+     */
+    level?: number;
+    children: InkwellText[];
+}
+/**
+ * A text leaf node
+ */
+interface InkwellText extends BaseText {
+    text: string;
+    bold?: true;
+    italic?: true;
+    strikethrough?: true;
+    inlineCode?: true;
+    boldMarker?: true;
+    italicMarker?: true;
+    strikeMarker?: true;
+    codeMarker?: true;
+    hljs?: string;
+    remoteCursor?: string;
+    remoteCursorCaret?: boolean;
+}
+/**
+ * The composed Inkwell editor type
+ */
+type InkwellEditor = BaseEditor & ReactEditor & HistoryEditor;
+declare module "slate" {
+    interface CustomTypes {
+        Editor: InkwellEditor;
+        Element: InkwellElement;
+        Text: InkwellText;
+    }
+}
+
+/**
+ * Deserialize a markdown string into Slate decorations.
+ *
+ * Each line becomes its own element. Block-level patterns (code fences,
+ * blockquotes, list items, headings) get their own element types based
+ * on the `decorations` config. Everything else is a paragraph. Text content
+ * is stored verbatim — visual formatting is handled by decorations at
+ * render time, not in the data model.
+ */
+declare function deserialize(markdown: string, decorations?: InkwellDecorations): InkwellElement[];
+
+declare function pluginClass(pluginName: string): (component: string) => string;
+
+/**
+ * Default bubble menu items: bold, italic, strikethrough.
+ */
+declare const defaultBubbleMenuItems: BubbleMenuItem[];
+interface BubbleMenuOptions {
+    /**
+     * Menu items. Defaults to bold, italic, strikethrough.
+     */
+    items?: BubbleMenuItem[];
+}
+declare function createBubbleMenuPlugin(options?: BubbleMenuOptions): InkwellPlugin;
+
+declare function createSnippetsPlugin(options: {
+    snippets: Snippet[];
+    key?: string;
+}): InkwellPlugin;
+
+/**
+ * Convert an HTML string to a markdown string
+ */
+declare function serializeToMarkdown(html: string): string;
+
+declare function InkwellRenderer({ content, className, components, rehypePlugins, copyButton, }: InkwellRendererProps): ReactNode;
+
+type RehypePlugin = Plugin<any[], any>;
+type RehypePluginConfig = RehypePlugin | [RehypePlugin, Record<string, unknown>];
+/**
+ * Parse a markdown string into React elements synchronously
+ */
+declare function parseMarkdown(markdown: string, components?: InkwellComponents, rehypePlugins?: RehypePluginConfig[]): ReactNode;
+
+export { type BubbleMenuItem, type BubbleMenuItemProps, type CollaborationConfig, type InkwellComponents, type InkwellDecorations, InkwellEditor$1 as InkwellEditor, type InkwellEditorProps, type InkwellPlugin, InkwellRenderer, type InkwellRendererProps, type PluginKeyDownContext, type PluginRenderProps, type PluginTrigger, type RehypePluginConfig$1 as RehypePluginConfig, type Snippet, createBubbleMenuPlugin, createSnippetsPlugin, defaultBubbleMenuItems, deserialize, parseMarkdown, pluginClass, serializeToMarkdown };