@aseity/idocs-preview 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @aseity/idocs-preview
 
+## 0.5.0
+
+### Minor Changes
+
+- Match the caret to the text being edited and move it to the next line after Shift+Enter. Keep edits and undo history when changing paragraph formatting, handle shorthand table rows, and focus newly inserted paragraphs, headings, and callouts. Improve excerpt selection, the narrow toolbar, and page thumbnails.
+
+## 0.4.0
+
+### Minor Changes
+
+- Add `openEditor` for stateful editing of iDocs source documents, with source snapshots, undo and redo, revision tracking, and DOCX export. Add `mountEditor` for Canvas text editing with Chinese IME input and `mountEditorWorkspace` for page thumbnails, an outline, formatting controls, and paragraph, table, and image edits. Existing preview APIs remain available. Hosts own source persistence and editor session disposal.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
-# iDocs preview
+# iDocs preview and editor
 
-Read-only browser preview for Word documents (`.docx`) and iDocs source documents
-(`.idoc`). A Web Worker measures browser-local fonts with Canvas and lays out
+Browser preview for Word documents (`.docx`) and iDocs source documents
+(`.idoc`), with an interactive editor for iDocs source documents. A Web Worker measures browser-local fonts with Canvas and lays out
 the document in WASM. Canvas draws text using the same font settings. No text
 font downloads or Local Font Access permissions are required. Different installed
 fonts can change line breaks and page counts.
@@ -55,6 +55,62 @@ during server rendering.
   owns a session and a view; `mountPreview(container, doc)` shows a document you
   opened yourself. Both re-export the core types.
 
+## Editing iDocs source documents
+
+Open an editor session and mount the workspace in a container with a height:
+
+```ts
+const { openEditor } = await import("@aseity/idocs-preview/core");
+const { mountEditorWorkspace } = await import("@aseity/idocs-preview/view");
+
+const session = await openEditor({ source, name: "report.idoc" });
+const workspace = mountEditorWorkspace(container, session, { railOpen: true });
+```
+
+`source` is an iDocs YAML string or a `Uint8Array`. Use `readResource` in
+`openEditor` to resolve referenced images. The workspace includes page thumbnails,
+an outline, formatting controls, and an icon-only insert dock. It supports text
+selection, Chinese IME input, undo and redo, paragraph styles, tables, and images.
+Table cells are editable in both array rows and rows written with `cells:`.
+Edits preserve the source form of each row.
+Inserting a paragraph, heading, or callout from the dock focuses the new text.
+A new callout uses the document's `theme.boxStyles.callout` when present.
+The default text is left-aligned, with no paragraph indents and compact paragraph spacing.
+For callout colors, the editor uses the box style, then `theme.colors.calloutBg`
+and `theme.colors.accent`. The host can supply fallback `calloutColors`
+as hex values. The selected style or colors are stored in the document.
+When the formatting controls overflow, use the toolbar arrows to scroll.
+In the narrowest panels, the arrows scroll the entire toolbar.
+The caret and IME composition use the font size and color at the insertion point.
+Press Shift+Enter for a line break within the paragraph. The caret moves to the start of the new line.
+The page rail updates its contents while open.
+Use `mountEditor(container, session)` for the page editor without workspace controls.
+
+Save the source snapshot through your host, then mark that revision as saved:
+
+```ts
+const snapshot = await session.snapshot();
+await saveSource(snapshot.source);
+await session.markSaved({ revision: snapshot.revision });
+const docx = await session.exportDocx();
+```
+
+`saveSource` is your application's persistence function. Subscribe to
+`session.subscribe(listener)` to observe revisions, unsaved changes, and layout
+state. Supply `onPickImage` to the workspace to enable image insertion.
+Supply `mountInsertButtons` to render the insert dock buttons using your host's
+tooltips. Render each button in its provided container, use its label and class
+name, call `bind` with the mounted button, and call `activate` on click.
+Return a cleanup function to unmount the buttons when the workspace is destroyed.
+Supply `onQuoteSelection` to enable **询问 AI**. The callback receives
+`{ text, path, page }` from the current layout, including unsaved edits. The
+page index starts at zero. An excerpt includes TeX for formulas in the selection.
+Clicking a read-only line or formula offers a quote when it has text or TeX.
+
+When closing the editor, call `workspace.destroy()` and `session.dispose()`.
+The workspace does not own the session. Existing preview APIs remain available.
+The development page enables the workspace with `?edit=1`.
+
 ## Opening documents
 
 `open(bytes, { name?, kind?, readResource? })` takes a `Uint8Array` or

package/dist/core/display.d.ts

@@ -150,6 +150,88 @@ export interface LineGlyph {
     /** UTF-16 offset within the line's text. */
     offset: number;
 }
+export type Affinity = 'upstream' | 'downstream';
+export type GeneratedRole = 'listMarker' | 'headingNumber' | 'captionLabel' | 'equationNumber' | 'noteNumber';
+export type ReadOnlyReason = 'aliasShared' | 'generated' | 'repeatedHeader' | 'unsupportedStory' | 'unsupportedStructure' | 'protectedInline';
+export type Revision = string & {
+    readonly __brand: 'Revision';
+};
+export type SessionId = string & {
+    readonly __brand: 'SessionId';
+};
+export type FlowId = string & {
+    readonly __brand: 'FlowId';
+};
+export type BlockId = string & {
+    readonly __brand: 'BlockId';
+};
+export type DisplayUtf16 = number & {
+    readonly __brand: 'DisplayUtf16';
+};
+export type ScalarUtf16 = number & {
+    readonly __brand: 'ScalarUtf16';
+};
+export type FlowOffset = number & {
+    readonly __brand: 'FlowOffset';
+};
+export interface Anchor {
+    readonly session: SessionId;
+    readonly flow: FlowId;
+    readonly offset: FlowOffset;
+    readonly affinity: Affinity;
+}
+export interface CaretStop {
+    readonly displayOffset: DisplayUtf16;
+    readonly anchor: Anchor;
+}
+export type BlockStyle = 'body' | 'heading1' | 'heading2' | 'heading3';
+export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+export type LineSource = {
+    readonly kind: 'editable';
+    readonly path: string;
+    readonly sourceStart: ScalarUtf16;
+    readonly sourceEnd: ScalarUtf16;
+    readonly stops: readonly CaretStop[];
+    readonly blockStyle?: BlockStyle;
+    readonly align?: TextAlign;
+} | {
+    readonly kind: 'atomic';
+    readonly path?: string;
+    readonly reason: ReadOnlyReason;
+    readonly role?: GeneratedRole;
+    readonly before?: Anchor;
+    readonly after?: Anchor;
+};
+export interface LineSourceSegment {
+    readonly start: DisplayUtf16;
+    readonly end: DisplayUtf16;
+    readonly source: LineSource;
+}
+export type LineOccurrence = {
+    readonly kind: 'original';
+} | {
+    readonly kind: 'repeatedHeader';
+    readonly canonicalPath: string;
+} | {
+    readonly kind: 'readOnlyStory';
+};
+export interface CaretStyle {
+    readonly family: string;
+    readonly declaredFamily: string;
+    readonly role: string;
+    readonly size: number;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly color: string;
+    readonly ascent: number;
+    readonly descent: number;
+    readonly rise: number;
+}
+export interface CaretStyleSpan {
+    readonly start: number;
+    readonly end: number;
+    readonly style: CaretStyle;
+}
 /** One laid-out line's glyph table, for hit testing. */
 export interface TextLine {
     story: Story;
@@ -169,6 +251,14 @@ export interface TextLine {
     /** Read-only in opened previews; indexed glyph objects are snapshots. */
     glyphs: readonly LineGlyph[];
     turn?: [number, number];
+    sourceSegments?: readonly LineSourceSegment[];
+    occurrence?: LineOccurrence;
+    caretStyle?: CaretStyle;
+    caretStyles?: readonly CaretStyleSpan[];
+    formulas?: readonly {
+        readonly offset: DisplayUtf16;
+        readonly tex: string;
+    }[];
 }
 export interface DisplayPage {
     number: number;

package/dist/core/editor.d.ts

@@ -0,0 +1,180 @@
+import { type Affinity, type Anchor, type BlockId, type BlockStyle, type CaretStop, type DisplayUtf16, type FlowId, type FlowOffset, type GeneratedRole, type LineOccurrence, type LineSource, type LineSourceSegment, type ReadOnlyReason, type Revision, type ScalarUtf16, type SessionId, type TextAlign, type TextLine } from './display.js';
+import { type Endpoint, type PreviewDiagnostic, type PreviewDocument, type Read, type SessionOptions } from './protocol.js';
+export type { Affinity, Anchor, BlockId, CaretStop, DisplayUtf16, FlowId, FlowOffset, GeneratedRole, LineOccurrence, LineSource, LineSourceSegment, ReadOnlyReason, Revision, ScalarUtf16, SessionId, };
+export interface EditRange {
+    readonly revision: Revision;
+    readonly start: Anchor;
+    readonly end: Anchor;
+}
+export interface Selection {
+    readonly revision: Revision;
+    readonly range: EditRange;
+    readonly reversed: boolean;
+}
+export type Mark = 'bold' | 'italic' | 'underline' | 'strike';
+export interface CalloutColors {
+    readonly fill: string;
+    readonly border: string;
+}
+export type InsertBlock = {
+    kind: 'paragraph';
+    text?: string;
+} | {
+    kind: 'heading';
+    level: 1 | 2 | 3;
+    text?: string;
+} | {
+    kind: 'callout';
+    text?: string;
+    colors?: CalloutColors;
+} | {
+    kind: 'table';
+    rows: number;
+    cols: number;
+} | {
+    kind: 'image';
+    src: string;
+    alt?: string;
+    widthRatio?: number;
+} | {
+    kind: 'pageBreak';
+};
+export type TableAction = 'insertRowAbove' | 'insertRowBelow' | 'insertColumnLeft' | 'insertColumnRight' | 'deleteRow' | 'deleteColumn' | 'toggleHeaderRow';
+export type ImageAlign = 'left' | 'center' | 'right';
+export type Edit = {
+    kind: 'replaceText';
+    range: EditRange;
+    text: string;
+} | {
+    kind: 'setMark';
+    range: EditRange;
+    mark: Mark;
+    enabled: boolean;
+} | {
+    kind: 'splitBlock';
+    at: Anchor;
+} | {
+    kind: 'mergeBackward';
+    at: Anchor;
+} | {
+    kind: 'setBlockStyle';
+    at: Anchor;
+    style: BlockStyle;
+} | {
+    kind: 'setAlignment';
+    at: Anchor;
+    align: TextAlign;
+} | {
+    kind: 'insertBlock';
+    after?: Anchor;
+    block: InsertBlock;
+} | {
+    kind: 'editTable';
+    at: Anchor;
+    action: TableAction;
+} | {
+    kind: 'editImage';
+    path: string;
+    widthRatio?: number;
+    align?: ImageAlign;
+    src?: string;
+    alt?: string;
+};
+export interface SourceSnapshot {
+    readonly revision: Revision;
+    readonly source: string;
+}
+export interface RenderStats {
+    readonly localResolve: boolean;
+    readonly paragraphsLaid: number;
+    readonly paragraphsReused: number;
+    readonly passes: number;
+}
+export interface Commit {
+    readonly revision: Revision;
+    readonly selection: Selection | null;
+    readonly changedBlocks: readonly BlockId[];
+    readonly localResolve: boolean;
+    readonly diagnostics: readonly PreviewDiagnostic[];
+}
+export interface EditorFrame {
+    readonly revision: Revision;
+    readonly document: PreviewDocument;
+    readonly stats: RenderStats;
+}
+export type LayoutState = {
+    kind: 'pending';
+    previous: EditorFrame | null;
+} | {
+    kind: 'ready';
+    frame: EditorFrame;
+} | {
+    kind: 'failed';
+    revision: Revision;
+    message: string;
+    diagnostics: readonly PreviewDiagnostic[];
+    previous: EditorFrame | null;
+};
+export interface EditorState {
+    readonly revision: Revision;
+    readonly dirty: boolean;
+    readonly selection: Selection | null;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly layout: LayoutState;
+}
+export interface OpenEditorOptions {
+    source: string | Uint8Array;
+    name?: string;
+    readResource?: Read;
+    runtime?: SessionOptions;
+}
+export interface EditorSession {
+    state(): EditorState;
+    subscribe(listener: (state: EditorState) => void): () => void;
+    range(input: {
+        revision: Revision;
+        start: Anchor;
+        end: Anchor;
+    }): Promise<EditRange>;
+    apply(input: {
+        base: Revision;
+        edit: Edit;
+    }): Promise<Commit>;
+    undo(input: {
+        base: Revision;
+    }): Promise<Commit>;
+    redo(input: {
+        base: Revision;
+    }): Promise<Commit>;
+    snapshot(): Promise<SourceSnapshot>;
+    markSaved(input: {
+        revision: Revision;
+    }): Promise<void>;
+    refresh(input: {
+        base: Revision;
+        source: string | Uint8Array;
+    }): Promise<Commit>;
+    exportDocx(): Promise<Uint8Array>;
+    dispose(): void;
+}
+export type LineHit = {
+    kind: 'editable';
+    anchor: Anchor;
+    displayOffset: DisplayUtf16;
+    x: number;
+} | {
+    kind: 'atomic';
+    reason: ReadOnlyReason;
+    role?: GeneratedRole;
+    before?: Anchor;
+    after?: Anchor;
+    segment?: LineSourceSegment;
+} | {
+    kind: 'unmapped';
+};
+export declare function caretXForOffset(line: TextLine, target: number): number;
+export declare function locateLineSource(line: TextLine, xPt: number): LineHit;
+export declare function lineCaretStop(line: TextLine, anchor: Anchor): CaretStop | null;
+export declare function lineCaretX(line: TextLine, anchor: Anchor): number | null;
+export declare function openEditorWith(worker: Endpoint, options: OpenEditorOptions): Promise<EditorSession>;