kindy-editor 1.0.1 → 2.0.0

package/dist/types/core/adapters/legacy.d.ts

@@ -0,0 +1,9 @@
+import type { DocumentApiAdapter, KindyDocumentState } from '../types';
+export interface LegacyCallbackOptions {
+    onSave?: (payload: {
+        json: KindyDocumentState['content'];
+        state: KindyDocumentState;
+    }, page: KindyDocumentState['page']) => Promise<unknown>;
+    onFileUpload?: (file: File | Blob) => Promise<unknown>;
+}
+export declare function createLegacyCallbackAdapter(options?: LegacyCallbackOptions): DocumentApiAdapter;

package/dist/types/core/adapters/memory.d.ts

@@ -0,0 +1,87 @@
+import type { CreateDocumentInput, DocumentApiAdapter, DocumentQuery, DocumentRecord, DocumentSnapshot, DocumentVersion, Folder, ImportDocumentInput, Page, SaveResult, SaveStateInput, StoreArtifactInput } from '../types';
+export declare class MemoryDocumentAdapter implements DocumentApiAdapter {
+    private documents;
+    private states;
+    private versions;
+    private versionStates;
+    private artifacts;
+    private folders;
+    constructor(seed?: {
+        documents?: DocumentSnapshot[];
+        folders?: Folder[];
+    });
+    private seed;
+    private requireDocument;
+    listDocuments(query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentRecord>>;
+    getDocument(documentId: string, signal?: AbortSignal): Promise<DocumentRecord>;
+    createDocument(input: CreateDocumentInput, signal?: AbortSignal): Promise<DocumentRecord>;
+    importDocument(input: ImportDocumentInput, signal?: AbortSignal): Promise<{
+        id: string;
+        updatedAt: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+        originalSource?: import("..").OriginalDocxSource;
+        title: string;
+        fileName: string;
+        folderId?: string | null;
+        tags?: string[];
+        currentVersionId?: string;
+        currentRevisionId?: string;
+        isTemplate?: boolean;
+        createdAt?: string;
+        capabilities?: import("..").DocumentCapabilities;
+    }>;
+    updateDocument(documentId: string, patch: Partial<DocumentRecord>, signal?: AbortSignal): Promise<{
+        id: string;
+        updatedAt: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+        originalSource?: import("..").OriginalDocxSource;
+        title: string;
+        fileName: string;
+        folderId?: string | null;
+        tags?: string[];
+        currentVersionId?: string;
+        currentRevisionId?: string;
+        isTemplate?: boolean;
+        createdAt?: string;
+        capabilities?: import("..").DocumentCapabilities;
+    }>;
+    loadState(documentId: string, versionId?: string, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    saveState(documentId: string, input: SaveStateInput, signal?: AbortSignal): Promise<SaveResult>;
+    listVersions(documentId: string, query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentVersion>>;
+    restoreVersion(documentId: string, versionId: string, signal?: AbortSignal): Promise<{
+        document: DocumentRecord;
+        state: import("..").KindyDocumentState;
+        revisionId: string;
+        version: DocumentVersion;
+    }>;
+    listFolders(_query?: DocumentQuery, signal?: AbortSignal): Promise<Folder[]>;
+    listTemplates(query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentRecord>>;
+    storeArtifact(documentId: string, input: StoreArtifactInput, signal?: AbortSignal): Promise<{
+        blob: Blob | undefined;
+        id: string;
+        documentId: string;
+        versionId?: string;
+        format: import("..").ArtifactFormat;
+        fileName: string;
+        mimeType: string;
+        size?: number;
+        url?: string;
+        createdAt: string;
+    }>;
+    getArtifact(documentId: string, artifactId: string, signal?: AbortSignal): Promise<{
+        blob: Blob | undefined;
+        id: string;
+        documentId: string;
+        versionId?: string;
+        format: import("..").ArtifactFormat;
+        fileName: string;
+        mimeType: string;
+        size?: number;
+        url?: string;
+        createdAt: string;
+    }>;
+    private makeVersion;
+}
+export declare const createMemoryDocumentAdapter: (seed?: ConstructorParameters<typeof MemoryDocumentAdapter>[0]) => MemoryDocumentAdapter;

package/dist/types/core/adapters/rest.d.ts

@@ -0,0 +1,27 @@
+import type { CreateDocumentInput, DocumentApiAdapter, DocumentArtifact, DocumentQuery, DocumentRecord, DocumentSnapshot, DocumentSummary, DocumentVersion, Folder, ImportDocumentInput, Page, SaveResult, SaveStateInput, StoreArtifactInput } from '../types';
+export type DocumentTransport = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface RestDocumentAdapterOptions {
+    baseUrl: string;
+    transport?: DocumentTransport;
+}
+export declare class RestDocumentAdapter implements DocumentApiAdapter {
+    private readonly baseUrl;
+    private readonly transport;
+    constructor(options: RestDocumentAdapterOptions);
+    private request;
+    private json;
+    listDocuments(query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentSummary>>;
+    getDocument(documentId: string, signal?: AbortSignal): Promise<DocumentRecord>;
+    createDocument(input: CreateDocumentInput, signal?: AbortSignal): Promise<DocumentRecord>;
+    importDocument(input: ImportDocumentInput, signal?: AbortSignal): Promise<DocumentRecord>;
+    updateDocument(documentId: string, patch: Partial<DocumentRecord>, signal?: AbortSignal): Promise<DocumentRecord>;
+    loadState(documentId: string, versionId?: string, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    saveState(documentId: string, input: SaveStateInput, signal?: AbortSignal): Promise<SaveResult>;
+    listVersions(documentId: string, query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentVersion>>;
+    restoreVersion(documentId: string, versionId: string, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    listFolders(query?: DocumentQuery, signal?: AbortSignal): Promise<Folder[]>;
+    listTemplates(query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentSummary>>;
+    storeArtifact(documentId: string, input: StoreArtifactInput, signal?: AbortSignal): Promise<DocumentArtifact>;
+    getArtifact(documentId: string, artifactId: string, signal?: AbortSignal): Promise<DocumentArtifact>;
+}
+export declare const createRestDocumentAdapter: (options: RestDocumentAdapterOptions) => RestDocumentAdapter;

package/dist/types/core/client.d.ts

@@ -0,0 +1,47 @@
+import { TypedEventEmitter } from './emitter';
+import type { CreateDocumentInput, DocumentApiAdapter, DocumentQuery, DocumentSnapshot, ImportDocumentInput, KindyDocumentState, SaveReason, StoreArtifactInput, EditorEngineAdapter } from './types';
+export interface DocumentLibraryClientOptions {
+    adapter: DocumentApiAdapter;
+    autosave?: {
+        enabled?: boolean;
+        delay?: number;
+    };
+    codecs?: Record<string, unknown>;
+    engine?: EditorEngineAdapter;
+    locale?: string;
+    theme?: Record<string, string>;
+}
+export declare class DocumentLibraryClient extends TypedEventEmitter {
+    readonly adapter: DocumentApiAdapter;
+    readonly codecs?: Record<string, unknown>;
+    readonly engine?: EditorEngineAdapter;
+    readonly locale: string;
+    readonly theme: Record<string, string>;
+    private autosaveEnabled;
+    private autosaveDelay;
+    private autosaveTimer;
+    private saveController;
+    private savePromise;
+    private snapshot;
+    private dirty;
+    private conflicted;
+    private mutation;
+    constructor(options: DocumentLibraryClientOptions);
+    get current(): DocumentSnapshot | null;
+    get hasUnsavedChanges(): boolean;
+    get hasConflict(): boolean;
+    listDocuments(query?: DocumentQuery, signal?: AbortSignal): Promise<import("./types").Page<import("./types").DocumentSummary>>;
+    open(documentId: string, versionId?: string, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    create(input: CreateDocumentInput, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    import(input: ImportDocumentInput, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    updateState(state: KindyDocumentState): DocumentSnapshot;
+    save(reason?: SaveReason): Promise<import("./types").SaveResult>;
+    private performSave;
+    restore(versionId: string, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    storeArtifact(input: StoreArtifactInput, signal?: AbortSignal): Promise<import("./types").DocumentArtifact>;
+    resolveConflict(snapshot: DocumentSnapshot): void;
+    destroy(): void;
+    private scheduleAutosave;
+    private cancelPendingSave;
+}
+export declare const createDocumentLibrary: (options: DocumentLibraryClientOptions) => DocumentLibraryClient;

package/dist/types/core/collaboration.d.ts

@@ -0,0 +1,30 @@
+import type { CollaborationAdapter, CollaborationSession } from './types';
+export interface YjsProviderLike {
+    connect?(): void;
+    disconnect?(): void;
+    destroy?(): void;
+    awareness?: {
+        getStates?(): Map<unknown, unknown>;
+    };
+}
+export interface YjsCollaborationAdapterOptions {
+    providerFactory(context: {
+        documentId: string;
+        user?: {
+            id?: string;
+            name?: string;
+            color?: string;
+        };
+        editor: unknown;
+    }): YjsProviderLike | Promise<YjsProviderLike>;
+}
+/**
+ * Host-provided Yjs provider boundary. The SDK deliberately does not create a
+ * WebSocket connection or ship a collaboration server.
+ */
+export declare class YjsCollaborationAdapter implements CollaborationAdapter {
+    private readonly options;
+    constructor(options: YjsCollaborationAdapterOptions);
+    connect(context: Parameters<CollaborationAdapter['connect']>[0]): Promise<CollaborationSession>;
+}
+export declare const createYjsCollaborationAdapter: (options: YjsCollaborationAdapterOptions) => YjsCollaborationAdapter;

package/dist/types/core/editor-state.d.ts

@@ -0,0 +1,47 @@
+import type { JSONContent } from '@tiptap/core';
+import type { AssetReference, KindyDocumentState, KindyHeaderFooterState, KindyPageMargin, KindySectionState } from './types';
+type LegacyHeaderFooter = {
+    enable?: boolean;
+    enabled?: boolean;
+    text?: string;
+    leftText?: string;
+    content?: JSONContent;
+    variants?: {
+        first?: {
+            text?: string;
+            content?: JSONContent;
+        };
+        even?: {
+            text?: string;
+            content?: JSONContent;
+        };
+    };
+    differentFirstPage?: boolean;
+    differentOddEven?: boolean;
+};
+type LegacyPage = {
+    size?: {
+        width?: number;
+        height?: number;
+    };
+    orientation?: 'portrait' | 'landscape';
+    margin?: Partial<KindyPageMargin>;
+    background?: string;
+    watermark?: Record<string, unknown>;
+    header?: LegacyHeaderFooter;
+    footer?: LegacyHeaderFooter;
+    sections?: Array<LegacySection>;
+};
+type LegacySection = LegacyPage & {
+    id?: string;
+    fromBlockId?: string;
+    pageNumberStart?: number;
+};
+export declare function toCanonicalHeaderFooter(value?: LegacyHeaderFooter): KindyHeaderFooterState | undefined;
+export declare function toCanonicalSection(section: LegacySection, page: LegacyPage): KindySectionState;
+export declare function createEditorDocumentState(input: {
+    content: JSONContent;
+    page?: LegacyPage;
+    assets?: AssetReference[];
+}): KindyDocumentState;
+export {};

package/dist/types/core/emitter.d.ts

@@ -0,0 +1,19 @@
+export type DocumentLibraryEventMap = {
+    ready: unknown;
+    opened: unknown;
+    changed: unknown;
+    'save-started': unknown;
+    saved: unknown;
+    'save-failed': unknown;
+    imported: unknown;
+    'compatibility-warning': unknown;
+    'version-restored': unknown;
+    printed: unknown;
+    error: unknown;
+};
+export declare class TypedEventEmitter<Events extends Record<string, unknown> = DocumentLibraryEventMap> {
+    private listeners;
+    on<K extends keyof Events>(event: K, listener: (payload: Events[K]) => void): () => boolean;
+    emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+    clear(): void;
+}

package/dist/types/core/errors.d.ts

@@ -0,0 +1,13 @@
+export declare const DOCUMENT_ERROR_CODES: readonly ["DOCX_INVALID", "DOCX_UNSUPPORTED", "IMPORT_FAILED", "EXPORT_FAILED", "ADAPTER_ERROR", "NETWORK_ERROR", "VERSION_CONFLICT", "DOCUMENT_NOT_FOUND", "OPERATION_CANCELLED"];
+export type DocumentErrorCode = (typeof DOCUMENT_ERROR_CODES)[number];
+export declare class DocumentLibraryError extends Error {
+    readonly code: DocumentErrorCode;
+    readonly status?: number;
+    readonly details?: unknown;
+    constructor(code: DocumentErrorCode, message: string, options?: {
+        status?: number;
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+export declare function toDocumentLibraryError(error: unknown, fallback?: DocumentErrorCode): DocumentLibraryError;

package/dist/types/core/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export * from './errors';
+export * from './state';
+export * from './editor-state';
+export * from './emitter';
+export * from './client';
+export * from './collaboration';
+export * from './adapters/rest';
+export * from './adapters/memory';
+export * from './adapters/legacy';

package/dist/types/core/state.d.ts

@@ -0,0 +1,9 @@
+import type { JSONContent } from '@tiptap/core';
+import { type KindyDocumentState, type KindyPageState } from './types';
+export declare const DEFAULT_PAGE_STATE: KindyPageState;
+export declare function cloneDocumentState<T>(value: T): T;
+export declare function createEmptyDocumentState(overrides?: Partial<KindyDocumentState>): KindyDocumentState;
+export declare function migrateDocumentState(input: unknown): KindyDocumentState;
+export declare function stateFromEditor(editor: {
+    getJSON(): JSONContent;
+}, page?: Partial<KindyPageState>): KindyDocumentState;

package/dist/types/core/types.d.ts

@@ -0,0 +1,235 @@
+import type { JSONContent } from '@tiptap/core';
+export declare const KINDY_DOCUMENT_SCHEMA_VERSION: "2.0";
+export type KindyDocumentSchemaVersion = typeof KINDY_DOCUMENT_SCHEMA_VERSION;
+export type SaveReason = 'autosave' | 'manual';
+export type ArtifactFormat = 'docx' | 'pdf' | 'original-docx';
+export interface KindyPageMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export interface KindyHeaderFooterState {
+    enabled: boolean;
+    content?: JSONContent;
+    text?: string;
+    firstContent?: JSONContent;
+    firstText?: string;
+    evenContent?: JSONContent;
+    evenText?: string;
+    differentFirstPage?: boolean;
+    differentOddEven?: boolean;
+}
+export interface KindySectionState {
+    id: string;
+    fromBlockId?: string;
+    pageNumberStart?: number;
+    size: {
+        width: number;
+        height: number;
+    };
+    orientation: 'portrait' | 'landscape';
+    margin: KindyPageMargin;
+    header?: KindyHeaderFooterState;
+    footer?: KindyHeaderFooterState;
+}
+export interface KindyPageState {
+    size: {
+        width: number;
+        height: number;
+    };
+    orientation: 'portrait' | 'landscape';
+    margin: KindyPageMargin;
+    background?: string;
+    watermark?: Record<string, unknown>;
+    header?: KindyHeaderFooterState;
+    footer?: KindyHeaderFooterState;
+    sections?: KindySectionState[];
+}
+export interface AssetReference {
+    id: string;
+    kind: 'image' | 'video' | 'audio' | 'file' | 'other';
+    url?: string;
+    mimeType?: string;
+    fileName?: string;
+    size?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface KindyDocumentState {
+    schemaVersion: KindyDocumentSchemaVersion;
+    content: JSONContent;
+    page: KindyPageState;
+    assets: AssetReference[];
+}
+export interface DocumentCapabilities {
+    view?: boolean;
+    edit?: boolean;
+    comment?: boolean;
+    review?: boolean;
+    download?: boolean;
+    restore?: boolean;
+    manage?: boolean;
+}
+export interface DocumentSummary {
+    id: string;
+    title: string;
+    fileName: string;
+    folderId?: string | null;
+    tags?: string[];
+    currentVersionId?: string;
+    currentRevisionId?: string;
+    isTemplate?: boolean;
+    updatedAt: string;
+    createdAt?: string;
+    capabilities?: DocumentCapabilities;
+}
+export interface OriginalDocxSource {
+    artifactId: string;
+    revisionId: string;
+    format: 'original-docx';
+    fileName: string;
+    compatibilityReport?: CompatibilityReport;
+}
+export interface DocumentRecord extends DocumentSummary {
+    description?: string;
+    metadata?: Record<string, unknown>;
+    originalSource?: OriginalDocxSource;
+}
+export interface DocumentVersion {
+    id: string;
+    documentId: string;
+    number: number;
+    revisionId: string;
+    reason: SaveReason | 'create' | 'import' | 'restore' | 'template';
+    createdAt: string;
+    createdBy?: {
+        id?: string;
+        name?: string;
+    };
+    label?: string;
+}
+export interface DocumentSnapshot {
+    document: DocumentRecord;
+    state: KindyDocumentState;
+    revisionId: string;
+    version?: DocumentVersion;
+}
+export interface DocumentArtifact {
+    id: string;
+    documentId: string;
+    versionId?: string;
+    format: ArtifactFormat;
+    fileName: string;
+    mimeType: string;
+    size?: number;
+    url?: string;
+    blob?: Blob;
+    createdAt: string;
+}
+export interface Folder {
+    id: string;
+    name: string;
+    parentId?: string | null;
+}
+export interface Page<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export interface DocumentQuery {
+    search?: string;
+    folderId?: string | null;
+    tags?: string[];
+    page?: number;
+    pageSize?: number;
+    templatesOnly?: boolean;
+}
+export interface CreateDocumentInput {
+    title: string;
+    fileName?: string;
+    folderId?: string | null;
+    tags?: string[];
+    templateId?: string;
+    state?: KindyDocumentState;
+    metadata?: Record<string, unknown>;
+}
+export interface ImportDocumentInput extends CreateDocumentInput {
+    file: File | Blob;
+    state: KindyDocumentState;
+    compatibilityReport?: CompatibilityReport;
+}
+export interface SaveStateInput {
+    state: KindyDocumentState;
+    baseRevisionId: string;
+    reason: SaveReason;
+    clientMutationId: string;
+}
+export interface SaveResult {
+    revisionId: string;
+    savedAt: string;
+    version?: DocumentVersion;
+}
+export interface StoreArtifactInput {
+    format: ArtifactFormat;
+    blob: Blob;
+    fileName: string;
+    versionId?: string;
+    compatibilityReport?: CompatibilityReport;
+}
+export type CompatibilitySeverity = 'info' | 'warning' | 'error';
+export interface CompatibilityIssue {
+    code: string;
+    feature: string;
+    message: string;
+    severity: CompatibilitySeverity;
+    location?: string;
+}
+export interface CompatibilityReport {
+    profile: 'kindy-docx-v2.0' | 'kindy-docx-v2.1' | 'kindy-docx-v2.2';
+    supported: boolean;
+    issues: CompatibilityIssue[];
+}
+export interface DocumentApiAdapter {
+    listDocuments(query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentSummary>>;
+    getDocument(documentId: string, signal?: AbortSignal): Promise<DocumentRecord>;
+    createDocument(input: CreateDocumentInput, signal?: AbortSignal): Promise<DocumentRecord>;
+    importDocument(input: ImportDocumentInput, signal?: AbortSignal): Promise<DocumentRecord>;
+    updateDocument(documentId: string, patch: Partial<DocumentRecord>, signal?: AbortSignal): Promise<DocumentRecord>;
+    loadState(documentId: string, versionId?: string, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    saveState(documentId: string, input: SaveStateInput, signal?: AbortSignal): Promise<SaveResult>;
+    listVersions(documentId: string, query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentVersion>>;
+    restoreVersion(documentId: string, versionId: string, signal?: AbortSignal): Promise<DocumentSnapshot>;
+    listFolders(query?: DocumentQuery, signal?: AbortSignal): Promise<Folder[]>;
+    listTemplates(query?: DocumentQuery, signal?: AbortSignal): Promise<Page<DocumentSummary>>;
+    storeArtifact(documentId: string, input: StoreArtifactInput, signal?: AbortSignal): Promise<DocumentArtifact>;
+    getArtifact(documentId: string, artifactId: string, signal?: AbortSignal): Promise<DocumentArtifact>;
+}
+export interface EditorEngineHandle {
+    load(state: KindyDocumentState): Promise<void> | void;
+    getState(): KindyDocumentState;
+    setReadOnly(readOnly: boolean): void;
+    focus(): void;
+    destroy(): void;
+    onChange(listener: (state: KindyDocumentState) => void): () => void;
+}
+export interface EditorEngineAdapter {
+    readonly id: string;
+    mount(container: HTMLElement, options?: Record<string, unknown>): Promise<EditorEngineHandle> | EditorEngineHandle;
+}
+export interface CollaborationSession {
+    disconnect(): void;
+    getUsers?(): unknown[];
+}
+export interface CollaborationAdapter {
+    connect(context: {
+        documentId: string;
+        revisionId: string;
+        user?: {
+            id?: string;
+            name?: string;
+            color?: string;
+        };
+        editor: unknown;
+    }): Promise<CollaborationSession> | CollaborationSession;
+}

package/docs/README.md

@@ -0,0 +1,15 @@
+# Kindy Editor v2 documentation
+
+Tài liệu chính của SDK:
+
+1. [Getting started](./getting-started.md)
+2. [UI engine](./ui-engine.md)
+3. [API reference](./api-reference.md)
+4. [Backend integration, security và adapter](../GUIDE.md)
+5. [DOCX compatibility matrix](../CAPABILITIES.md)
+6. [Performance và tài liệu dài](./performance.md)
+7. [Migration v1 → v2](../MIGRATION.md)
+8. [REST OpenAPI](../openapi/document-api.yaml)
+9. [Completion roadmap và release gates](./completion-roadmap.md)
+
+Các thư mục `architecture/`, `adr/`, `packages/`, `research/` và `epic-story-task/` ghi lại nghiên cứu/prototype cũ của codebase. Chúng không phải public contract của `kindy-editor@2`; khi có khác biệt, tài liệu trong danh sách trên và TypeScript declarations là nguồn chính xác.