@ai-matrx/office 0.4.0 → 0.5.3

package/dist/docs-io.d.cts

@@ -0,0 +1,147 @@
+import { IDocumentData } from '@univerjs/core';
+
+/**
+ * markdown-to-univer-doc — convert a markdown string into a Univer
+ * `IDocumentData` snapshot that the document editor (preset-docs-core) can
+ * hydrate directly.
+ *
+ * Why this exists: the document system stores opaque Univer `IDocumentData`
+ * (see `document-service.ts` + `components/DocumentEditor.tsx`). To send any
+ * markdown surface (an assistant message, a note, a scraper result) into a
+ * cloud document, we need markdown → IDocumentData. There was no converter, so
+ * "Add to docs" was a stub. This is the missing primitive — reuse it for every
+ * markdown → document export, never re-implement a one-off.
+ *
+ * The output is RENDERED content, not raw markdown text: `**bold**` becomes a
+ * bold text run, `# Heading` becomes a larger bold paragraph, `- item` becomes
+ * a bulleted line. The document never contains literal markdown syntax.
+ *
+ * Univer body model (the part we build):
+ *   - `dataStream`  — the text. `\r` terminates a paragraph; a trailing `\n`
+ *                     terminates the (single) section. Mirrors the empty doc
+ *                     `"\r\n"` shape in DocumentEditor.defaultEmptyDocument().
+ *   - `paragraphs`  — one entry per `\r`, `startIndex` = the `\r` offset.
+ *   - `textRuns`    — `{ st, ed, ts }` style overlays on character ranges.
+ *   - `sectionBreaks` — the trailing `\n`.
+ *
+ * Scope: headings, paragraphs, bold/italic/strikethrough/inline-code, links
+ * (Univer hyperlink ranges keep the address), unordered/ordered lists, blockquotes, fenced code
+ * blocks, horizontal rules, and GFM tables (real Univer tables). Nested
+ * emphasis is supported. Anything exotic degrades to plain readable text rather
+ * than leaking syntax.
+ */
+
+/**
+ * Convert markdown to a Univer `IDocumentData` snapshot. Pure — no I/O. Pass
+ * the result straight to `saveDocumentSnapshot`.
+ */
+declare function markdownToUniverDoc(markdown: string, title?: string): Partial<IDocumentData>;
+/**
+ * Derive a sensible document name from markdown: first heading, else first
+ * non-empty line, trimmed of markdown syntax. Falls back to a dated default.
+ */
+declare function deriveDocumentName(markdown: string): string;
+
+/**
+ * univerDocToMarkdown — the reverse of `markdown-to-univer-doc.ts`.
+ *
+ * Why it exists: the canvas pane for a cloud document (`udt_document`) offers a
+ * `Source` tab, and the rule in `features/canvas/core/canvasSource.ts` is that
+ * Source shows THE ITEM'S OWN SOURCE — for a document, its markdown — never the
+ * redux envelope. A document's content lives as an opaque Univer
+ * `IDocumentData` snapshot in `workbench.udt_document_snapshots`, so something
+ * has to read it back out. This is that something, and it is the ONLY one:
+ * never re-implement a second snapshot reader.
+ *
+ * What it reads (the half `markdownToUniverDoc` writes):
+ *   - `body.dataStream`  — the text; `\r` terminates a paragraph, a trailing
+ *                          `\n` terminates the section.
+ *   - `body.paragraphs`  — one entry per `\r` (`startIndex` = the `\r` offset).
+ *   - `body.textRuns`    — `{ st, ed, ts }` style overlays. `ts.bl` + a heading
+ *                          font size is how `markdownToUniverDoc` encodes
+ *                          `#`..`######`, so the level is recovered from `fs`.
+ *
+ * Fidelity is deliberately MODEST and honest: headings, bold, italic,
+ * strikethrough and inline/monospace code round-trip; everything else comes
+ * back as the plain text the user actually sees. A document typed by hand in
+ * Univer never had markdown syntax in the first place — printing its text is
+ * the truthful answer, not a reconstruction.
+ *
+ * PURE — no React, no Redux, no IO.
+ */
+/** Inverse of markdown-to-univer-doc's HEADING_FONT_SIZE. */
+declare const HEADING_LEVEL_BY_FONT_SIZE: Record<number, number>;
+interface DrawingLike {
+    source?: unknown;
+    title?: unknown;
+    description?: unknown;
+    docTransform?: {
+        size?: {
+            width?: unknown;
+            height?: unknown;
+        };
+    };
+}
+/**
+ * A picture's markdown source. Our own pictures are `matrx-file:<id>`; the
+ * drawn size rides as a `#WxH` fragment so a round trip keeps the shape.
+ */
+declare function imageMarkdownSource(drawing: DrawingLike): string | null;
+/** Every picture in a snapshot, as its markdown source (`matrx-file:<id>#WxH` or a URL). */
+declare function documentImageSources(snapshot: unknown): string[];
+interface DocToMarkdownOptions {
+    /**
+     * Where a picture's markdown points. Return null to leave it out (the caller
+     * names what was left out). Default: the stored source.
+     */
+    imageUrl?: (source: string) => string | null;
+}
+/**
+ * Read a Univer document snapshot back as markdown. Returns `""` for an empty
+ * or unreadable snapshot so the caller can say "no source" honestly rather than
+ * printing an envelope.
+ */
+declare function univerDocToMarkdown(snapshot: unknown, options?: DocToMarkdownOptions): string;
+
+declare const DOCUMENT_UPLOAD_ACCEPT = ".docx,.md,.markdown,.txt,.html,.htm";
+type Source = "imported_docx" | "imported_md" | "imported_txt";
+declare function documentFileKind(name: string): "docx" | "md" | "txt" | "html" | null;
+/** Word's document.xml -> markdown: headings, bold/italic runs, list paragraphs, tables as rows. */
+declare function docxXmlToMarkdown(xml: string): string;
+/** HTML -> markdown for the blocks a document keeps (headings, paragraphs, lists, emphasis, links). */
+declare function htmlToDocumentMarkdown(html: string): string;
+declare function documentFileToMarkdown(file: File): Promise<{
+    markdown: string;
+    source: Source;
+}>;
+/** Create a document from an uploaded file; returns its id. */
+declare function importDocumentFile(file: File, organizationId: string): Promise<{
+    id: string;
+    name: string;
+}>;
+
+/**
+ * File → Download → EPUB / OpenDocument (.odt) / Rich Text (.rtf).
+ *   EPUB    the print package's EPUB engine, straight from the live text.
+ *   ODT/RTF the same engine writes the .docx, then aidream's LibreOffice route
+ *           (`POST /office/convert-document`) converts it. Nothing is stored.
+ * Engine, converter and saver are injected so the forcing test runs the real logic.
+ */
+type OpenFormat = "epub" | "odt" | "rtf";
+declare const OPEN_FORMATS: Record<OpenFormat, {
+    label: string;
+    extension: string;
+    mime: string;
+}>;
+interface OpenFormatDeps {
+    engine: (markdown: string, format: "docx" | "epub", fileName: string) => Promise<{
+        bytes: Uint8Array;
+        fileName: string;
+    }>;
+    convert: (docx: Uint8Array, fileName: string, target: "odt" | "rtf") => Promise<Uint8Array>;
+    save: (fileName: string, bytes: Uint8Array, mime: string) => void;
+}
+declare function exportOpenFormat(markdown: string, format: OpenFormat, title: string | null | undefined, deps: OpenFormatDeps): Promise<string>;
+declare function downloadOpenFormat(markdown: string, format: OpenFormat, title: string | null | undefined): Promise<string>;
+
+export { DOCUMENT_UPLOAD_ACCEPT, type DocToMarkdownOptions, HEADING_LEVEL_BY_FONT_SIZE, OPEN_FORMATS, type OpenFormat, type OpenFormatDeps, deriveDocumentName, documentFileKind, documentFileToMarkdown, documentImageSources, docxXmlToMarkdown, downloadOpenFormat, exportOpenFormat, htmlToDocumentMarkdown, imageMarkdownSource, importDocumentFile, markdownToUniverDoc, univerDocToMarkdown };

package/dist/docs-io.d.ts

@@ -0,0 +1,147 @@
+import { IDocumentData } from '@univerjs/core';
+
+/**
+ * markdown-to-univer-doc — convert a markdown string into a Univer
+ * `IDocumentData` snapshot that the document editor (preset-docs-core) can
+ * hydrate directly.
+ *
+ * Why this exists: the document system stores opaque Univer `IDocumentData`
+ * (see `document-service.ts` + `components/DocumentEditor.tsx`). To send any
+ * markdown surface (an assistant message, a note, a scraper result) into a
+ * cloud document, we need markdown → IDocumentData. There was no converter, so
+ * "Add to docs" was a stub. This is the missing primitive — reuse it for every
+ * markdown → document export, never re-implement a one-off.
+ *
+ * The output is RENDERED content, not raw markdown text: `**bold**` becomes a
+ * bold text run, `# Heading` becomes a larger bold paragraph, `- item` becomes
+ * a bulleted line. The document never contains literal markdown syntax.
+ *
+ * Univer body model (the part we build):
+ *   - `dataStream`  — the text. `\r` terminates a paragraph; a trailing `\n`
+ *                     terminates the (single) section. Mirrors the empty doc
+ *                     `"\r\n"` shape in DocumentEditor.defaultEmptyDocument().
+ *   - `paragraphs`  — one entry per `\r`, `startIndex` = the `\r` offset.
+ *   - `textRuns`    — `{ st, ed, ts }` style overlays on character ranges.
+ *   - `sectionBreaks` — the trailing `\n`.
+ *
+ * Scope: headings, paragraphs, bold/italic/strikethrough/inline-code, links
+ * (Univer hyperlink ranges keep the address), unordered/ordered lists, blockquotes, fenced code
+ * blocks, horizontal rules, and GFM tables (real Univer tables). Nested
+ * emphasis is supported. Anything exotic degrades to plain readable text rather
+ * than leaking syntax.
+ */
+
+/**
+ * Convert markdown to a Univer `IDocumentData` snapshot. Pure — no I/O. Pass
+ * the result straight to `saveDocumentSnapshot`.
+ */
+declare function markdownToUniverDoc(markdown: string, title?: string): Partial<IDocumentData>;
+/**
+ * Derive a sensible document name from markdown: first heading, else first
+ * non-empty line, trimmed of markdown syntax. Falls back to a dated default.
+ */
+declare function deriveDocumentName(markdown: string): string;
+
+/**
+ * univerDocToMarkdown — the reverse of `markdown-to-univer-doc.ts`.
+ *
+ * Why it exists: the canvas pane for a cloud document (`udt_document`) offers a
+ * `Source` tab, and the rule in `features/canvas/core/canvasSource.ts` is that
+ * Source shows THE ITEM'S OWN SOURCE — for a document, its markdown — never the
+ * redux envelope. A document's content lives as an opaque Univer
+ * `IDocumentData` snapshot in `workbench.udt_document_snapshots`, so something
+ * has to read it back out. This is that something, and it is the ONLY one:
+ * never re-implement a second snapshot reader.
+ *
+ * What it reads (the half `markdownToUniverDoc` writes):
+ *   - `body.dataStream`  — the text; `\r` terminates a paragraph, a trailing
+ *                          `\n` terminates the section.
+ *   - `body.paragraphs`  — one entry per `\r` (`startIndex` = the `\r` offset).
+ *   - `body.textRuns`    — `{ st, ed, ts }` style overlays. `ts.bl` + a heading
+ *                          font size is how `markdownToUniverDoc` encodes
+ *                          `#`..`######`, so the level is recovered from `fs`.
+ *
+ * Fidelity is deliberately MODEST and honest: headings, bold, italic,
+ * strikethrough and inline/monospace code round-trip; everything else comes
+ * back as the plain text the user actually sees. A document typed by hand in
+ * Univer never had markdown syntax in the first place — printing its text is
+ * the truthful answer, not a reconstruction.
+ *
+ * PURE — no React, no Redux, no IO.
+ */
+/** Inverse of markdown-to-univer-doc's HEADING_FONT_SIZE. */
+declare const HEADING_LEVEL_BY_FONT_SIZE: Record<number, number>;
+interface DrawingLike {
+    source?: unknown;
+    title?: unknown;
+    description?: unknown;
+    docTransform?: {
+        size?: {
+            width?: unknown;
+            height?: unknown;
+        };
+    };
+}
+/**
+ * A picture's markdown source. Our own pictures are `matrx-file:<id>`; the
+ * drawn size rides as a `#WxH` fragment so a round trip keeps the shape.
+ */
+declare function imageMarkdownSource(drawing: DrawingLike): string | null;
+/** Every picture in a snapshot, as its markdown source (`matrx-file:<id>#WxH` or a URL). */
+declare function documentImageSources(snapshot: unknown): string[];
+interface DocToMarkdownOptions {
+    /**
+     * Where a picture's markdown points. Return null to leave it out (the caller
+     * names what was left out). Default: the stored source.
+     */
+    imageUrl?: (source: string) => string | null;
+}
+/**
+ * Read a Univer document snapshot back as markdown. Returns `""` for an empty
+ * or unreadable snapshot so the caller can say "no source" honestly rather than
+ * printing an envelope.
+ */
+declare function univerDocToMarkdown(snapshot: unknown, options?: DocToMarkdownOptions): string;
+
+declare const DOCUMENT_UPLOAD_ACCEPT = ".docx,.md,.markdown,.txt,.html,.htm";
+type Source = "imported_docx" | "imported_md" | "imported_txt";
+declare function documentFileKind(name: string): "docx" | "md" | "txt" | "html" | null;
+/** Word's document.xml -> markdown: headings, bold/italic runs, list paragraphs, tables as rows. */
+declare function docxXmlToMarkdown(xml: string): string;
+/** HTML -> markdown for the blocks a document keeps (headings, paragraphs, lists, emphasis, links). */
+declare function htmlToDocumentMarkdown(html: string): string;
+declare function documentFileToMarkdown(file: File): Promise<{
+    markdown: string;
+    source: Source;
+}>;
+/** Create a document from an uploaded file; returns its id. */
+declare function importDocumentFile(file: File, organizationId: string): Promise<{
+    id: string;
+    name: string;
+}>;
+
+/**
+ * File → Download → EPUB / OpenDocument (.odt) / Rich Text (.rtf).
+ *   EPUB    the print package's EPUB engine, straight from the live text.
+ *   ODT/RTF the same engine writes the .docx, then aidream's LibreOffice route
+ *           (`POST /office/convert-document`) converts it. Nothing is stored.
+ * Engine, converter and saver are injected so the forcing test runs the real logic.
+ */
+type OpenFormat = "epub" | "odt" | "rtf";
+declare const OPEN_FORMATS: Record<OpenFormat, {
+    label: string;
+    extension: string;
+    mime: string;
+}>;
+interface OpenFormatDeps {
+    engine: (markdown: string, format: "docx" | "epub", fileName: string) => Promise<{
+        bytes: Uint8Array;
+        fileName: string;
+    }>;
+    convert: (docx: Uint8Array, fileName: string, target: "odt" | "rtf") => Promise<Uint8Array>;
+    save: (fileName: string, bytes: Uint8Array, mime: string) => void;
+}
+declare function exportOpenFormat(markdown: string, format: OpenFormat, title: string | null | undefined, deps: OpenFormatDeps): Promise<string>;
+declare function downloadOpenFormat(markdown: string, format: OpenFormat, title: string | null | undefined): Promise<string>;
+
+export { DOCUMENT_UPLOAD_ACCEPT, type DocToMarkdownOptions, HEADING_LEVEL_BY_FONT_SIZE, OPEN_FORMATS, type OpenFormat, type OpenFormatDeps, deriveDocumentName, documentFileKind, documentFileToMarkdown, documentImageSources, docxXmlToMarkdown, downloadOpenFormat, exportOpenFormat, htmlToDocumentMarkdown, imageMarkdownSource, importDocumentFile, markdownToUniverDoc, univerDocToMarkdown };