deepsky 2.54.3 → 2.54.11

package/dist/index.d.ts

@@ -33,7 +33,7 @@ declare namespace IText {
 }
 
 declare namespace ICommandCube {
-    type Names = "cube:reset" | "cube:delete" | "cube:insert" | "cube:insert-child" | "cube:delete-child" | "cube:delete-adjacent" | "cube:set-selection-css" | "cube:partition" | "cube:reorder" | "cube:set-css" | "cube:set-attr" | "cube:move" | "cube:merge" | "cube:postil-add" | "cube:postil-remove" | "code:change-lang" | "code:change-active" | "code:change-theme" | "code:update" | "code:add" | "code:remove" | "code:rename" | "detail-list:insert-row" | "detail-list:remove-row" | "detail-list:change-width-col1" | "formula:update" | "datetime:update" | "datetime:set-format" | "badge:select" | "badge:update" | "rating:select" | "rating:update" | "check:set" | "check:set-appearance" | "counter:set" | "counter:update" | "timeline:insert" | "timeline:remove" | "timeline:move" | "timeline:update-item" | "timeline:update" | "timeline:reorder" | "key:update" | "linker:update" | "list:add" | "list:remove" | "list:indent" | "list:reset" | "list:transform" | "list-ordered:add" | "list-ordered:remove" | "list-ordered:indent" | "list-ordered:reset" | "rt:reset" | "table:add-title" | "table:remove-title" | "table:add-cell" | "table:remove-cell" | "table:add-row" | "table:remove-row" | "table:add-col" | "table:remove-col" | "table:add-grid-col" | "table:remove-grid-col" | "table:add-grid-row" | "table:remove-grid-row" | "table:merge" | "table:moveto" | "table:update-area" | "table:reorder" | "table:col-resize" | "text:reset" | "text:break" | "link:update" | "text-link:update" | "todo:add" | "todo:remove" | "todo:indent" | "todo:status" | "todo:reset" | "node:layout-update" | "node:append-child" | "map:node-add" | "map:node-remove" | "map:node-remove-only" | "map:node-wrap-siblings" | "map:linker-add" | "map:linker-remove" | "map:update-attrs" | "map:node-drag" | "map:sibling-reorder" | "cursor:in-head" | "cursor:in-tail" | "cursor:loc" | (string & {});
+    type Names = "cube:reset" | "cube:delete" | "cube:insert" | "cube:insert-child" | "cube:delete-child" | "cube:delete-adjacent" | "cube:set-selection-css" | "cube:partition" | "cube:reorder" | "cube:set-css" | "cube:set-attr" | "cube:move" | "cube:merge" | "cube:postil-add" | "cube:postil-remove" | "code:change-lang" | "code:change-active" | "code:change-theme" | "code:update" | "code:add" | "code:remove" | "code:rename" | "detail-list:insert-row" | "detail-list:remove-row" | "detail-list:change-width-col1" | "formula:update" | "datetime:update" | "datetime:set-format" | "badge:select" | "rating:select" | "rating:update" | "check:set" | "check:set-appearance" | "counter:set" | "counter:update" | "timeline:insert" | "timeline:remove" | "timeline:move" | "timeline:update-item" | "timeline:update" | "timeline:reorder" | "key:update" | "linker:update" | "list:add" | "list:remove" | "list:indent" | "list:reset" | "list:transform" | "list-ordered:add" | "list-ordered:remove" | "list-ordered:indent" | "list-ordered:reset" | "rt:reset" | "table:add-title" | "table:remove-title" | "table:add-cell" | "table:remove-cell" | "table:add-row" | "table:remove-row" | "table:add-col" | "table:remove-col" | "table:add-grid-col" | "table:remove-grid-col" | "table:add-grid-row" | "table:remove-grid-row" | "table:merge" | "table:moveto" | "table:update-area" | "table:reorder" | "table:col-resize" | "text:reset" | "text:break" | "link:update" | "text-link:update" | "todo:add" | "todo:remove" | "todo:indent" | "todo:status" | "todo:reset" | "node:layout-update" | "node:append-child" | "map:node-add" | "map:node-remove" | "map:node-remove-only" | "map:node-wrap-siblings" | "map:linker-add" | "map:linker-remove" | "map:update-attrs" | "map:node-drag" | "map:sibling-reorder" | "cursor:in-head" | "cursor:in-tail" | "cursor:loc" | (string & {});
     type DeleteDir = "forward" | "backward";
     type CursorFrom = "left" | "right" | "none";
     interface BaseCommand {
@@ -264,13 +264,14 @@ declare abstract class NoteBase {
 declare class DialogBase extends NoteBase {
     protected _show: vue.Ref<boolean, boolean>;
     protected _cursor_info?: INoteCursor.CursorInfo;
+    protected _hotkey_suspend_token?: symbol;
     constructor(note: Note);
     get show(): boolean;
     set show(v: boolean);
     get cursor_info(): INoteCursor.CursorInfo | undefined;
     save_cursor_info(): void;
     clear_cursor_info(): void;
-    open(): void;
+    open(cursor_info?: INoteCursor.CursorInfo): void;
     close(return_cursor?: boolean): void;
 }
 
@@ -299,21 +300,42 @@ declare class DialogCatalogue extends DialogBase {
     dialog_add_bookmark(): NodeJS.Timeout | undefined;
 }
 
+interface BadgeLayoutItem {
+    id: string;
+    x: number;
+    y: number;
+}
 declare class DialogBadge extends DialogBase {
     protected _cube: Ref<CubeBadge | null>;
-    protected _items: Ref<IBadge.Item[]>;
-    protected _item_id: Ref<string, string>;
+    protected _on_insert: ((value: IBadge.Value) => void) | undefined;
+    protected _custom_items: Ref<IBadge.Value[]>;
+    protected _search: Ref<string, string>;
+    protected _active_id: Ref<string, string>;
+    protected _layout: BadgeLayoutItem[];
     constructor(note: Note);
     get cube(): CubeBadge | null;
-    get items(): IBadge.Item[];
-    get item_id(): string;
-    set item_id(value: string);
-    edit_badge(cube: CubeBadge): void;
-    add_item(): void;
-    remove_item(index: number): Function | undefined;
-    move_item(index: number, direction: -1 | 1): void;
-    save(): void;
+    get custom_items(): IBadge.Value[];
+    get search(): string;
+    set search(value: string);
+    get active_id(): string;
+    get active(): IBadge.Value;
+    get categories(): IBadge.PresetCategory[];
+    get items(): IBadge.Value[];
+    open_badge(cube: CubeBadge): void;
+    /** Opens the picker before a badge exists; selection creates the badge at the saved cursor. */
+    open_insert(cursor_info: INoteCursor.CursorInfo, on_insert: (value: IBadge.Value) => void): void;
+    select(value?: IBadge.Value | IBadge.PresetItem): void;
+    create_custom(label: string, color: string): Function | undefined;
+    /** Updated by the Vue view after layout changes; key navigation only reads this cache. */
+    update_layout(layout: BadgeLayoutItem[]): void;
+    move_active(direction: "left" | "right" | "up" | "down"): void;
+    reset_active(): void;
+    export(): {
+        custom_items: IBadge.Value[];
+    };
     close(return_cursor?: boolean): void;
+    protected to_value(item: IBadge.PresetItem | IBadge.Value): IBadge.Value;
+    protected normalize_custom_items(values: unknown): IBadge.Value[];
 }
 
 declare class DialogPreset extends DialogBase {
@@ -528,6 +550,9 @@ declare class UIDialog extends UiBase {
     get adapter(): {
         get data(): {
             cubelist: IUiDialogCubeList.V1;
+            badge: {
+                custom_items: never[];
+            };
         };
         get meta(): IUi.Meta;
         update_data(data: any): any;
@@ -685,6 +710,9 @@ declare const AdapterUiStatusbar: {
 declare const AdapterUiDialog: {
     get data(): {
         cubelist: IUiDialogCubeList.V1;
+        badge: {
+            custom_items: never[];
+        };
     };
     get meta(): IUi.Meta;
     update_data(data: any): any;
@@ -816,6 +844,9 @@ declare const AdapterUi: {
     get dialog(): {
         get data(): {
             cubelist: IUiDialogCubeList.V1;
+            badge: {
+                custom_items: never[];
+            };
         };
         get meta(): IUi.Meta;
         update_data(data: any): any;
@@ -1740,6 +1771,13 @@ declare class NoteClipBoard extends NoteBase {
     copy_scope(data: DataTransfer): Promise<boolean>;
     set_clipboard_cubedata(text: string, cubedata: ICubeBase.Data[]): Promise<boolean>;
     paste(data: DataTransfer): Promise<Recorder>;
+    protected is_note_data(data: unknown): data is INoteClipboard.NoteData;
+    protected parse_paste_data(data: DataTransfer): Promise<{
+        cubedata: ICubeBase.Data[];
+        versions?: INote.CubesVersion;
+        source?: INoteClipboard.NoteData;
+    } | undefined>;
+    protected prepare_image_data(images: File[]): Promise<ICubeBase.Data[] | undefined>;
     get_cubedata_from_text(text: string): ICubeBase.Data<INote.Cubes>[];
     paste_cubes(data: ICubeBase.Data[], data_versions?: INote.CubesVersion | undefined): Recorder | undefined;
     paste_img(blob: Blob): Promise<Recorder | undefined>;
@@ -1905,12 +1943,18 @@ declare class NoteFlag extends NoteBase {
 }
 
 declare class NoteListener extends NoteBase {
-    protected timer_float_check: boolean;
+    protected _disposed: boolean;
+    protected _float_check_frame?: number;
+    protected readonly handle_keyup: (e: KeyboardEvent) => void;
+    protected readonly handle_selection_change: (e: Event) => Promise<any[]>;
+    protected readonly handle_esc: () => void;
     constructor(note: Note);
     protected listen(): void;
     protected listen_keyup(): void;
     protected listen_selection_change(): void;
     protected listen_esc(): void;
+    /** Releases document-level listeners and any scheduled float refresh. */
+    dispose(): void;
     check_float(): void;
 }
 
@@ -2010,12 +2054,23 @@ declare abstract class NoteHotkeyBase extends NoteBase {
 declare class NoteInteraction extends NoteBase {
     protected _hotkeys: Map<string, NoteHotkeyBase>;
     protected _inited: boolean;
+    /**
+     * 当前持有“暂停笔记快捷键”资格的弹窗令牌。scope 是全局状态，因此必须等
+     * 最后一个弹窗释放令牌后才能恢复，避免嵌套弹窗的内层关闭时提前恢复。
+     */
+    protected _hotkey_suspend_tokens: Set<symbol>;
+    protected _scope_before_hotkey_suspend?: INoteInteraction.Scope;
     data: Reactive<Record<string, INoteInteraction.HotkeyConfig>>;
     constructor(note: Note);
     get meta(): INote.CoreMeta;
     disable_hotkey(): void;
     enable_hotkey(): void;
-    get_scope(): string;
+    get_scope(): INoteInteraction.Scope;
+    /**
+     * 暂停笔记快捷键并返回释放令牌。令牌可按任意顺序释放，重复释放无副作用。
+     */
+    suspend_hotkey(): symbol;
+    resume_hotkey(token: symbol): void;
     set_scope(scope: INoteInteraction.Scope): void;
     listen(dom: HTMLElement): void;
     init(config?: Partial<INoteInteraction.Data>): void;
@@ -2250,6 +2305,8 @@ declare class Note {
     render_readonly(dom: HTMLElement): void;
     /** Releases the Vue tree created by [render_readonly]. */
     unmount_readonly(): void;
+    /** Releases document-level resources when this Note instance is no longer used. */
+    dispose(): void;
     render_pdf(dom: HTMLElement): void;
     emit_event_after_render(): void;
     find_cube(type: INote.Cubes): any;
@@ -2335,23 +2392,21 @@ declare class CubeImg extends CubeChild<IImg.Data> {
 declare class AdapterCubeBadge extends CubeAdapterBase {
     get supports_inline_scale(): boolean;
     get meta(): INote.CubeMeta;
-    get_default_items(): IBadge.Item[];
-    get_data(item_id?: string, css?: Record<string, string>, attrs?: Partial<IBadge.Attrs>): IBadge.Data;
+    get_default_value(): IBadge.Value;
+    get_data(value?: IBadge.Value, css?: Record<string, string>, attrs?: Partial<IBadge.Attrs>): IBadge.Data;
     replace_id(versions: INote.CubesVersion, data: IBadge.Data, map?: Record<string, string>): ICubeBase.ReplaceIdResult<IBadge.Data>;
     update_data(versions: INote.CubesVersion, data: IBadge.Data): ICubeBase.CubeUpdateResult<IBadge.Data>;
-    normalize_items(items: unknown): IBadge.Item[];
-    normalize_item_id(item_id: unknown, items: IBadge.Item[]): string;
+    normalize_value(value: unknown): IBadge.Value;
 }
 
 declare class BadgeStatus extends CubeStatusBase<IBadge.Data> {
-    protected _item: vue.ComputedRef<IBadge.Item>;
+    protected _value: vue.ComputedRef<IBadge.Value>;
     get cube(): CubeBadge;
-    get item(): IBadge.Item;
+    get value(): IBadge.Value;
 }
 
 declare class ReceiverBadge extends ReceiverChild<CubeBadge> {
     protected select(command: ICommandBadge.Select): Recorder | undefined;
-    protected update(command: ICommandBadge.Update): Recorder;
 }
 
 declare class CubeBadge extends CubeChild<IBadge.Data> {
@@ -2360,12 +2415,8 @@ declare class CubeBadge extends CubeChild<IBadge.Data> {
     get adapter(): AdapterCubeBadge;
     get status(): BadgeStatus;
     get component(): any;
-    get items(): IBadge.Item[];
-    get item_id(): string;
-    get item(): IBadge.Item;
+    get value(): IBadge.Value;
     get text(): string;
-    get_item(item_id: string): IBadge.Item;
-    get_next_item_id(): string;
     protected build_child(data: IBadge.Data): void;
     export(): IBadge.Data;
     gc(): void;
@@ -3312,16 +3363,19 @@ declare class NodeShape {
 
 declare class AdapterCubeApi extends CubeAdapterBase {
     get meta(): INote.CubeMeta;
-    get type_argument(): Record<string, string>;
-    get type_funciton(): Record<string, string>;
     get_line_function(funcname?: string): ILine.Data;
-    get_text_function_type(): IText.Data;
     get_text_function(funcname?: string): IText.Data;
     get_text_argument(argname?: string): IText.Data;
-    get_text_argument_type(): IText.Data;
     get_data(css?: INote.Css, attrs?: INote.Attrs): IApi.Data;
     update_data(versions: INote.CubesVersion, data: any): ICubeBase.CubeUpdateResult<IApi.Data>;
     to_v2(versions: INote.CubesVersion, data: IApi.V1): IApi.V2;
+    /** Convert the fixed v2 type text slot into an optional badge. */
+    to_v3(versions: INote.CubesVersion, data: IApi.V2): IApi.V3;
+    protected convert_type_text_to_badge(list: IList.Data, background: string): void;
+    protected get_type_badge(label: string): IBadge.Data;
+    /** Legacy v2 type-text styles, retained only to identify migration targets. */
+    get type_argument(): Record<string, string>;
+    get type_funciton(): Record<string, string>;
     replace_id(versions: INote.CubesVersion, data: IApi.Data, map?: Record<string, string>): ICubeBase.ReplaceIdResult<IApi.Data>;
 }
 
@@ -5344,32 +5398,37 @@ interface _CubeTextAnnotation extends ICubeBase.Data {
 }
 
 declare namespace IBadge {
+    type BadgeId = `${string}:${string}`;
+    type Source = "builtin" | "custom";
     interface Data extends ICubeBase.Data {
         type: "badge";
-        /** The id of the currently displayed badge item. */
-        info: string;
+        /** Complete display snapshot.  The preset library is only a selection source. */
+        info: Value;
         attrs: Attrs;
     }
     interface Attrs extends ICubeBase.InlineAttrs {
-        items: Item[];
         [key: string]: any;
     }
-    interface Item {
-        id: string;
+    interface Value {
+        id: BadgeId;
         label: string;
         color: string;
+        source: Source;
+    }
+    interface PresetItem extends Omit<Value, "source"> {
+        keywords?: string[];
+    }
+    interface PresetCategory {
+        id: string;
+        label: string;
+        items: PresetItem[];
     }
 }
 
 declare namespace ICommandBadge {
     interface Select extends ICommandCube.BaseCommand {
         name: "badge:select";
-        item_id: string;
-    }
-    interface Update extends ICommandCube.BaseCommand {
-        name: "badge:update";
-        item_id: string;
-        items: IBadge.Item[];
+        value: IBadge.Value;
     }
 }
 
@@ -5733,7 +5792,11 @@ declare namespace ICommandList {
 }
 
 declare namespace IApi {
-    type Data = V2;
+    type Data = V3;
+    interface V3 extends ICubeBase.Data {
+        type: "api";
+        info: Info;
+    }
     interface V2 extends ICubeBase.Data {
         type: "api";
         info: Info;
@@ -5744,6 +5807,11 @@ declare namespace IApi {
         text: CubeText;
     }
     interface Info {
+        /**
+         * The first line of each function/argument item begins with its name text.
+         * A type is represented by an optional inline `badge`; absence means no type
+         * has been declared.
+         */
         functions: IList.Data;
         arguments?: IList.Data;
         exceptions?: IList.Data;
@@ -6990,10 +7058,16 @@ declare namespace IUiDialogCubeList {
 declare namespace IUiDialog {
     type Types = "preset" | "catalogue" | "css" | "cubelist";
     type formulaType = "preset" | "symbol" | "bracket" | "relation" | "sup" | "arrow" | "operator" | "matrix" | "expression";
-    type Data = V1;
+    type Data = V2;
     interface V1 {
         cubelist: IUiDialogCubeList.Data;
     }
+    interface V2 extends V1 {
+        /** Custom badge candidates belong to the note UI data, not to an individual cube. */
+        badge: {
+            custom_items: IBadge.Value[];
+        };
+    }
 }
 
 declare namespace IUi {
@@ -7114,8 +7188,7 @@ declare class CommandApi {
 }
 
 declare class CommandBadge {
-    static select(id: ICubeBase.CubeId, item_id: string): ICommandBadge.Select;
-    static update(id: ICubeBase.CubeId, items: IBadge.Item[], item_id: string): ICommandBadge.Update;
+    static select(id: ICubeBase.CubeId, value: IBadge.Value): ICommandBadge.Select;
 }
 
 declare class CommandBoxFolder {
@@ -7290,6 +7363,7 @@ declare abstract class MenuBase<TCube extends CubeBase = CubeBase> {
 
 declare class MenusCubeRegistry {
     protected readonly menus: Map<INote.Cubes, MenuBase<CubeBase<any>>>;
+    protected _dialog_hotkey_suspend_token?: symbol;
     protected _note: Note;
     readonly dialog: Reactive<ICubesMenu.MenuDialog>;
     constructor();