@import-ai/omnibox-editor 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 omnibox-editor contributors
+
+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,526 @@
+# @import-ai/omnibox-editor
+
+A production-ready React block editor built on Tiptap. It ships a complete editor UI, Markdown/JSON conversion helpers, table editing, image upload, math, diagrams, table of contents, optional AI writing hooks, and optional Yjs collaboration support.
+
+## Features
+
+- React component with a batteries-included Tiptap editor experience
+- Editable and read-only rendering modes
+- Markdown input, Tiptap JSON input, and Markdown export helpers
+- GitHub-like Markdown styling for headings, lists, links, code, blockquotes, tables, images, and math
+- Notion-like table editing with row/column handles, context menus, resizing, merge/split, sorting, alignment, and fit-to-width actions
+- Image upload pipeline with progress, abort, success, error, size, and count controls
+- KaTeX math rendering and in-editor formula editing
+- Mermaid/ECharts-style diagram rendering from code blocks
+- Optional table of contents sidebar
+- Optional AI writing integration through host-provided handlers
+- Optional Yjs collaboration and collaborative cursors
+- English and Simplified Chinese UI copy with translation overrides
+
+## Installation
+
+```bash
+npm install @import-ai/omnibox-editor
+```
+
+```bash
+pnpm add @import-ai/omnibox-editor
+```
+
+```bash
+yarn add @import-ai/omnibox-editor
+```
+
+`react` and `react-dom` are peer dependencies and must be installed by the consuming app.
+
+```bash
+npm install react react-dom
+```
+
+## Quick Start
+
+Import the component and the compiled CSS once in your app.
+
+```tsx
+import { OmniboxEditor } from "@import-ai/omnibox-editor"
+import "@import-ai/omnibox-editor/style.css"
+
+export function App() {
+  return (
+    <OmniboxEditor
+      placeholder="Start writing..."
+      onUpdate={({ json, html, markdown }) => {
+        console.log(json, html, markdown)
+      }}
+    />
+  )
+}
+```
+
+## Recommended Production Data Flow
+
+Use Tiptap JSON as the canonical format in production. It preserves editor-specific structures such as tables, math, images, alignment, colors, and custom nodes more reliably than plain Markdown.
+
+```tsx
+import { OmniboxEditor, contentToMarkdown } from "@import-ai/omnibox-editor"
+import "@import-ai/omnibox-editor/style.css"
+
+export function ResourceEditor({
+  initialContent,
+  saveResource,
+}: {
+  initialContent: string
+  saveResource: (content: unknown) => Promise<void>
+}) {
+  return (
+    <OmniboxEditor
+      content={initialContent}
+      onUpdate={({ json }) => {
+        void saveResource(json)
+      }}
+    />
+  )
+}
+
+export function exportMarkdown(savedContent: unknown) {
+  return contentToMarkdown(savedContent as Parameters<typeof contentToMarkdown>[0], {
+    debug: false,
+  })
+}
+```
+
+For backward compatibility, `content` accepts both existing Markdown strings and serialized JSON strings. New writes should store `json` from `onUpdate`.
+
+## Basic Usage
+
+### Markdown Input
+
+```tsx
+<OmniboxEditor content={"# Hello\n\nThis content starts as Markdown."} />
+```
+
+### Tiptap JSON Input
+
+```tsx
+<OmniboxEditor
+  content={{
+    type: "doc",
+    content: [
+      {
+        type: "heading",
+        attrs: { level: 1 },
+        content: [{ type: "text", text: "Hello" }],
+      },
+    ],
+  }}
+/>
+```
+
+### Serialized JSON String Input
+
+```tsx
+<OmniboxEditor content={JSON.stringify(savedTiptapJson)} />
+```
+
+### Read-Only Rendering
+
+```tsx
+<OmniboxEditor content={savedContent} editable={false} showHeader={false} />
+```
+
+### Embedded Mode
+
+Use `variant="embedded"` when the editor is rendered inside an existing page shell or panel.
+
+```tsx
+<OmniboxEditor
+  variant="embedded"
+  content={savedContent}
+  contentWidth="100%"
+  showHeader={false}
+  showToc={false}
+/>
+```
+
+## Component API
+
+```tsx
+import type { OmniboxEditorProps } from "@import-ai/omnibox-editor"
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `content` | `Content \| string` | demo content | Initial or externally controlled content. Accepts Markdown, serialized JSON, Tiptap JSON documents, or Tiptap node arrays. |
+| `editable` | `boolean` | `true` | Enables editing. Set to `false` for read-only rendering. |
+| `placeholder` | `string` | locale placeholder | Placeholder shown in empty editable blocks. |
+| `onUpdate` | `(payload) => void` | `undefined` | Called after editor content changes. Use `payload.json` as the preferred saved value. |
+| `imageUpload` | `UploadFunction` | built-in object URL fallback | Custom image uploader. Should return the final image URL. |
+| `imageUploadMaxSize` | `number` | package default | Maximum image size in bytes. |
+| `imageUploadLimit` | `number` | `3` | Maximum number of images accepted per upload operation. |
+| `onImageUploadError` | `(error: Error) => void` | logs to console | Called when image upload fails. |
+| `onImageUploadSuccess` | `(url: string) => void` | `undefined` | Called when image upload succeeds. |
+| `linkBase` | `string` | `undefined` | Base URL used to resolve relative links and image sources while parsing Markdown/content. |
+| `locale` | `"en" \| "zh-CN" \| string` | `"en"` | Built-in UI locale. |
+| `translations` | `OmniboxEditorTranslations` | `undefined` | Overrides individual UI labels. |
+| `theme` | `"light" \| "dark"` | `undefined` | Applies package dark-mode classes when set to `"dark"`. |
+| `variant` | `"page" \| "embedded"` | `"page"` | Page mode shows the default editor chrome; embedded mode is more compact. |
+| `contentWidth` | `number \| string` | CSS default | Sets the editor content width. Numbers are treated as pixels. |
+| `showHeader` | `boolean` | `true` in page mode | Controls the top editor header. |
+| `showToc` | `boolean` | `true` in page mode | Controls the table of contents sidebar. |
+| `mentionUsers` | `OmniboxEditorMentionUser[]` | `undefined` | Users shown in the mention dropdown. |
+| `user` | `OmniboxEditorCollaborationUser` | `undefined` | Current user identity for local UI and collaboration fallback. |
+| `collaboration` | `false \| object` | `undefined` | Yjs collaboration config. |
+| `ai` | `boolean \| OmniboxEditorAiConfig` | `undefined` | Enables the AI UI and optionally provides an AI submit handler. |
+
+## Update Payload
+
+`onUpdate` receives the live editor instance plus multiple content formats.
+
+```ts
+import type { OmniboxEditorUpdatePayload } from "@import-ai/omnibox-editor"
+
+type OmniboxEditorUpdatePayload = {
+  editor: Editor
+  json: JSONContent
+  html: string
+  markdown: string
+}
+```
+
+Recommended usage:
+
+- Save `json` to your backend.
+- Use `markdown` for export/download/copy workflows.
+- Use `html` only when your application explicitly needs HTML output.
+- Debounce or autosave outside the package if the backend should not receive every keystroke.
+
+## Markdown and JSON Helpers
+
+The package exports conversion helpers for import/export workflows.
+
+```ts
+import {
+  contentToMarkdown,
+  contentToTiptapJson,
+  htmlTableToTiptapNode,
+  markdownToTiptapJson,
+  markdownWithHtmlTablesToTiptapJson,
+  tiptapJsonToMarkdown,
+  type MarkdownParseOptions,
+  type TiptapJsonContent,
+} from "@import-ai/omnibox-editor"
+```
+
+| API | Description |
+| --- | --- |
+| `markdownToTiptapJson(markdown, options?)` | Parses Markdown into a Tiptap JSON document using Tiptap's official `MarkdownManager`, then applies package normalization for links, images, tables, and diagrams. |
+| `markdownWithHtmlTablesToTiptapJson(markdown, options?)` | Parses Markdown that may contain raw HTML `<table>` blocks. HTML tables are converted into Tiptap table nodes. |
+| `contentToTiptapJson(content, options?)` | Accepts Markdown, serialized JSON, or JSON content and returns a normalized Tiptap JSON document. Use this when the input format is unknown. |
+| `tiptapJsonToMarkdown(json, options?)` | Serializes Tiptap JSON back to Markdown. Merged tables are emitted as HTML tables when Markdown tables cannot represent them safely. |
+| `contentToMarkdown(content, options?)` | Accepts Markdown, serialized JSON, or JSON content and returns Markdown. Use this for export from saved server content. |
+| `htmlTableToTiptapNode(html)` | Converts a single HTML table string into a Tiptap table node. |
+
+### Markdown Parse Options
+
+```ts
+type MarkdownParseOptions = {
+  debug?: boolean
+  linkBase?: string
+}
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `debug` | `true` | Logs conversion input/output to the console. Set `debug: false` in production import/export paths. |
+| `linkBase` | `undefined` | Resolves relative links and image sources against a base URL. |
+
+Production example:
+
+```ts
+const json = contentToTiptapJson(serverContent, {
+  linkBase: "https://example.com/resources/current-folder",
+  debug: false,
+})
+
+const markdown = contentToMarkdown(json, { debug: false })
+```
+
+## Image Upload
+
+Provide `imageUpload` to connect the editor to your storage service.
+
+```tsx
+import { OmniboxEditor, type UploadFunction } from "@import-ai/omnibox-editor"
+import "@import-ai/omnibox-editor/style.css"
+
+const uploadImage: UploadFunction = async (file, onProgress, abortSignal) => {
+  const formData = new FormData()
+  formData.append("file", file)
+
+  const response = await fetch("/api/uploads", {
+    method: "POST",
+    body: formData,
+    signal: abortSignal,
+  })
+
+  if (!response.ok) {
+    throw new Error("Image upload failed")
+  }
+
+  onProgress?.({ progress: 100 })
+
+  const result = (await response.json()) as { url: string }
+  return result.url
+}
+
+export function Editor() {
+  return (
+    <OmniboxEditor
+      imageUpload={uploadImage}
+      imageUploadMaxSize={10 * 1024 * 1024}
+      imageUploadLimit={5}
+      onImageUploadError={(error) => {
+        console.error(error)
+      }}
+    />
+  )
+}
+```
+
+The upload function must resolve with the final URL that should be stored in the document.
+
+## AI Integration
+
+The package renders the AI UI only when `ai` is enabled. The host application owns the actual model call.
+
+```tsx
+import type { OmniboxEditorAiSubmitPayload } from "@import-ai/omnibox-editor"
+
+async function handleAiSubmit({
+  action,
+  prompt,
+  signal,
+  onChunk,
+}: OmniboxEditorAiSubmitPayload) {
+  const response = await fetch("/api/ai/write", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ action, prompt }),
+    signal,
+  })
+
+  if (!response.ok || !response.body) {
+    throw new Error("AI request failed")
+  }
+
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    onChunk?.(decoder.decode(value))
+  }
+}
+
+<OmniboxEditor
+  ai={{
+    enabled: true,
+    onSubmit: handleAiSubmit,
+  }}
+/>
+```
+
+`onSubmit` can stream plain Markdown through `onChunk`, or provide structured Tiptap JSON through `onContent` / `onContentPreview`.
+
+## Collaboration
+
+Collaboration uses Yjs through Tiptap's collaboration extensions. Pass a Yjs document and, optionally, a provider with awareness support.
+
+```tsx
+import * as Y from "yjs"
+import { OmniboxEditor } from "@import-ai/omnibox-editor"
+import "@import-ai/omnibox-editor/style.css"
+
+const document = new Y.Doc()
+
+<OmniboxEditor
+  collaboration={{
+    document,
+    provider,
+    user: {
+      id: "user-1",
+      name: "Ada",
+      color: "#3b82f6",
+      avatar: "https://example.com/avatar.png",
+    },
+  }}
+/>
+```
+
+When collaboration is enabled, the package disables StarterKit undo/redo and does not sync external `content` prop updates after initialization. Treat the Yjs document as the source of truth.
+
+## Mentions
+
+```tsx
+<OmniboxEditor
+  mentionUsers={[
+    {
+      id: "user-1",
+      name: "Ada Lovelace",
+      color: "#3b82f6",
+      avatar: "https://example.com/avatar.png",
+      position: "Engineer",
+    },
+  ]}
+/>
+```
+
+## Internationalization
+
+Use `locale` for the built-in language, and `translations` for targeted overrides.
+
+```tsx
+<OmniboxEditor
+  locale="zh-CN"
+  translations={{
+    placeholder: "开始写点什么...",
+    uploadFailed: "图片上传失败",
+  }}
+/>
+```
+
+You can also read the merged labels:
+
+```ts
+import { getEditorTranslations } from "@import-ai/omnibox-editor"
+
+const labels = getEditorTranslations("zh-CN", {
+  placeholder: "开始写点什么...",
+})
+```
+
+## Styling
+
+The package ships compiled CSS at:
+
+```ts
+import "@import-ai/omnibox-editor/style.css"
+```
+
+The CSS includes editor layout, toolbar UI, table controls, GitHub-like Markdown rules, image states, KaTeX styles, and component variables. It is generated from Tailwind CSS v4 layers and does not require Sass.
+
+Set dark mode with the component prop:
+
+```tsx
+<OmniboxEditor theme="dark" />
+```
+
+Constrain content width with `contentWidth`:
+
+```tsx
+<OmniboxEditor contentWidth={860} />
+<OmniboxEditor contentWidth="min(100%, 920px)" />
+```
+
+## Exported API
+
+### Components
+
+```ts
+export { OmniboxEditor }
+```
+
+### Conversion Helpers
+
+```ts
+export {
+  contentToMarkdown,
+  contentToTiptapJson,
+  htmlTableToTiptapNode,
+  markdownToTiptapJson,
+  markdownWithHtmlTablesToTiptapJson,
+  tiptapJsonToMarkdown,
+}
+```
+
+### Utilities
+
+```ts
+export { getEditorTranslations }
+```
+
+### Types
+
+```ts
+export type {
+  EditorProviderProps,
+  MarkdownParseOptions,
+  OmniboxEditorAiAction,
+  OmniboxEditorAiConfig,
+  OmniboxEditorAiFeature,
+  OmniboxEditorAiSubmitPayload,
+  OmniboxEditorCollaborationConfig,
+  OmniboxEditorCollaborationProvider,
+  OmniboxEditorCollaborationUser,
+  OmniboxEditorLocale,
+  OmniboxEditorMentionUser,
+  OmniboxEditorProps,
+  OmniboxEditorTheme,
+  OmniboxEditorTranslations,
+  OmniboxEditorUpdatePayload,
+  TiptapJsonContent,
+  UploadFunction,
+}
+```
+
+## Production Checklist
+
+- Import `@import-ai/omnibox-editor/style.css` once at the application entry.
+- Save `onUpdate().json` as the canonical document value.
+- Use `contentToMarkdown(content, { debug: false })` for Markdown export.
+- Set `debug: false` in conversion helpers used by production code.
+- Provide a real `imageUpload` implementation before enabling image uploads for users.
+- Enforce file size, MIME type, authentication, authorization, and malware scanning on the upload API.
+- Debounce autosave outside the editor if you persist on `onUpdate`.
+- Use `editable={false}` for read-only views.
+- Pass `linkBase` when rendering legacy Markdown with relative links or images.
+- Keep collaboration state in Yjs when `collaboration` is enabled.
+- Keep AI credentials and model calls on your server; never expose secrets in the browser.
+
+## Browser and SSR Notes
+
+`@import-ai/omnibox-editor` is a browser-facing React component. In SSR frameworks, render it only on the client.
+
+Next.js example:
+
+```tsx
+"use client"
+
+import { OmniboxEditor } from "@import-ai/omnibox-editor"
+import "@import-ai/omnibox-editor/style.css"
+
+export default function EditorPage() {
+  return <OmniboxEditor />
+}
+```
+
+## Local Development
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @import-ai/omnibox-editor test
+pnpm --filter @import-ai/omnibox-editor build
+```
+
+Create a local tarball:
+
+```bash
+pnpm --filter @import-ai/omnibox-editor pack:local
+```
+
+## License
+
+MIT

package/dist/components/tiptap-extension/ai-generation-widget-extension.d.ts

@@ -0,0 +1,41 @@
+import { Extension } from "@tiptap/core";
+import { PluginKey } from "@tiptap/pm/state";
+import type { AiGenerationStatus } from "@/components/tiptap-ui/ai-composer/ai-generation-state";
+import type { OmniboxEditorI18n } from "@/lib/i18n";
+type AiGenerationWidgetState = {
+    pos: number | null;
+    status: AiGenerationStatus;
+};
+type AiGenerationWidgetMeta = {
+    type: "set";
+    pos: number;
+    status: Exclude<AiGenerationStatus, "idle">;
+} | {
+    type: "clear";
+};
+type AiGenerationWidgetActions = {
+    labels?: Pick<OmniboxEditorI18n, "aiIsWriting" | "aiReviewPrompt" | "apply" | "discard" | "submitAiPrompt" | "stopAiGeneration" | "tryAgain">;
+    onApply?: () => void;
+    onDiscard?: () => void;
+    onRetry?: () => void;
+    onStop?: () => void;
+    onSubmitInstruction?: (instruction: string) => void;
+};
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        aiGenerationWidget: {
+            clearAiGenerationWidget: () => ReturnType;
+            setAiGenerationWidget: (payload: {
+                pos: number;
+                status: Exclude<AiGenerationStatus, "idle">;
+            }) => ReturnType;
+        };
+    }
+    interface Storage {
+        aiGenerationWidget: AiGenerationWidgetActions;
+    }
+}
+export declare const aiGenerationWidgetPluginKey: PluginKey<AiGenerationWidgetState>;
+export declare function getMappedAiGenerationWidgetState(previousState: AiGenerationWidgetState, meta: AiGenerationWidgetMeta | undefined, mapPosition: (pos: number) => number): AiGenerationWidgetState;
+export declare const AiGenerationWidget: Extension<AiGenerationWidgetActions, any>;
+export {};

package/dist/components/tiptap-extension/indent-extension.d.ts

@@ -0,0 +1,90 @@
+import { Extension } from "@tiptap/core";
+import { type EditorState } from "@tiptap/pm/state";
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        indent: {
+            /**
+             * Increase the indent level of the selected blocks by 1.
+             * In lists, nests the list item under the previous sibling.
+             */
+            indent: () => ReturnType;
+            /**
+             * Decrease the indent level of the selected blocks by 1.
+             * In lists, lifts the list item out of its parent.
+             */
+            outdent: () => ReturnType;
+            /**
+             * Set the indent level of the selected blocks to a specific value.
+             */
+            setIndent: (level: number) => ReturnType;
+            /**
+             * Remove indentation from the selected blocks.
+             */
+            unsetIndent: () => ReturnType;
+        };
+    }
+}
+export interface IndentOptions {
+    /**
+     * Block node types that support indentation.
+     * List items are handled separately via sinkListItem/liftListItem.
+     * @default ["paragraph", "heading", "blockquote"]
+     */
+    types: string[];
+    /**
+     * Node types that are treated as list items.
+     * When the cursor is inside one of these, indent/outdent delegates to
+     * sinkListItem/liftListItem instead of applying block-level indent.
+     * @default ["listItem", "taskItem"]
+     */
+    listItemTypes: string[];
+    /**
+     * Ancestor node types that should disable the Tab / Shift-Tab indent
+     * shortcut so the surrounding extension can handle Tab itself.
+     *
+     * Tables are the canonical example: ProseMirror's table plugin uses Tab to
+     * move the caret between cells. Without this opt-out, the Indent
+     * extension would consume Tab first and apply a paragraph indent inside
+     * the active cell instead of moving to the next cell.
+     *
+     * @default ["tableCell", "tableHeader"]
+     */
+    bypassAncestors: string[];
+    /**
+     * Minimum indent level.
+     * @default 0
+     */
+    minLevel: number;
+    /**
+     * Maximum indent level.
+     * @default 8
+     */
+    maxLevel: number;
+    /**
+     * Use inline style instead of data attribute.
+     * When false, only the `data-indent` attribute is set — use CSS to style indentation.
+     * When true, adds `style="margin-left: {level * indentUnit}px"` for immediate visual feedback.
+     * @default false
+     */
+    useStyle?: boolean;
+    /**
+     * Pixels per indent level when useStyle is enabled.
+     * @default 24
+     */
+    indentUnit: number;
+}
+/**
+ * Parse an indent level from an HTML element by checking:
+ * 1. Our own `data-indent` attribute (canonical source).
+ * 2. Common CSS properties used by external editors like Google Docs and Word
+ *    (`margin-left`, `padding-left`, `text-indent`).
+ *
+ * Returns 0 when no indentation is detected.
+ */
+export declare function parseIndentLevel(element: HTMLElement, minLevel: number, maxLevel: number, indentUnit: number): number;
+/**
+ * Walk up the document tree from the cursor and return the first list-item
+ * node name found, or `null` if the cursor is not inside a list.
+ */
+export declare function getListItemName(state: EditorState, listItemTypes: Set<string>): string | null;
+export declare const Indent: Extension<IndentOptions, any>;

package/dist/components/tiptap-extension/list-normalization-extension.d.ts

@@ -0,0 +1,30 @@
+import { Extension } from "@tiptap/core";
+/**
+ * ListNormalization Extension
+ *
+ * This extension solves the "stuck vertical spacing" problem that occurs when working
+ * with lists in Tiptap editor.
+ *
+ * ## The Problem
+ *
+ * By default, Tiptap treats each list as a separate structural node. When a user
+ * presses Enter twice at the end of a list item, they exit the list and a new
+ * paragraph is created between two list blocks:
+ *
+ * ```html
+ * <ul>
+ *   <li>Task A</li>
+ * </ul>
+ *
+ * <p></p>   <!-- Empty paragraph created on double-enter -->
+ *
+ * <ul>
+ *   <li>Task B</li>
+ * </ul>
+ * ```
+ *
+ * When the user tries to backspace this empty paragraph, Tiptap deletes the paragraph
+ * but does NOT automatically merge the two <ul> blocks back into one list. This results
+ * in visual "stuck" vertical spacing that users cannot remove, which feels broken.
+ */
+export declare const ListNormalizationExtension: Extension<any, any>;