artalk 2.8.0 → 2.8.1

package/dist/main.d.cts

@@ -237,6 +237,26 @@ declare class Api_2<SecurityDataType extends unknown> extends HttpClient<Securit
         createComment: (comment: HandlerParamsCommentCreate, params?: RequestParams) => Promise<HttpResponse<HandlerResponseCommentCreate, HandlerMap & {
             msg?: string | undefined;
         }>>;
+        /**
+         * @description Get the detail of a comment by comment id
+         *
+         * @tags Comment
+         * @name GetComment
+         * @summary Get a comment
+         * @request GET:/comments/{id}
+         * @response `200` `HandlerResponseCommentGet` OK
+         * @response `404` `(HandlerMap & {
+         msg?: string,
+
+         })` Not Found
+         * @response `500` `(HandlerMap & {
+         msg?: string,
+
+         })` Internal Server Error
+         */
+        getComment: (id: number, params?: RequestParams) => Promise<HttpResponse<HandlerResponseCommentGet, HandlerMap & {
+            msg?: string | undefined;
+        }>>;
         /**
          * @description Update a specific comment
          *
@@ -1227,6 +1247,8 @@ declare namespace ArtalkType {
         ContextApi,
         EditorState,
         EditorApi,
+        ListErrorData,
+        ListFetchedArgs,
         EventPayloadMap,
         ArtalkPlugin,
         SidebarShowPayload
@@ -1293,9 +1315,9 @@ declare interface CheckerStore {
 
 declare class CommentActions {
     private comment;
-    private get ctx();
     private get data();
-    private get cConf();
+    private get opts();
+    private getApi;
     constructor(comment: CommentNode);
     /** 投票操作 */
     vote(type: 'up' | 'down'): void;
@@ -1307,17 +1329,6 @@ declare class CommentActions {
     goToReplyComment(): void;
 }
 
-declare interface CommentConf {
-    isUnread?: boolean;
-    openURL?: string;
-    isFlatMode: boolean;
-    replyTo?: CommentData;
-    afterRender?: () => void;
-    openEvt?: () => void;
-    onReplyBtnClick?: Function;
-    onDelete?: Function;
-}
-
 export declare interface CommentData {
     /** 评论 ID */
     id: number;
@@ -1347,7 +1358,7 @@ export declare interface CommentData {
     badge_name?: string;
     /** 徽章颜色 */
     badge_color?: string;
-    /** IP 归属地 */
+    /** IP 属地 */
     ip_region?: string;
     /** 是否允许回复 */
     is_allow_reply: boolean;
@@ -1365,16 +1376,16 @@ export declare interface CommentData {
     vote_down: number;
 }
 
-declare class CommentNode extends Component {
+declare class CommentNode {
+    $el?: HTMLElement;
     private renderInstance;
     private actionInstance;
     private data;
-    private cConf;
+    private opts;
     private parent;
     private children;
     private nestCurt;
-    private nestMax;
-    constructor(ctx: ContextApi, data: CommentData, conf: CommentConf);
+    constructor(data: CommentData, opts: CommentOptions);
     /** 渲染 UI */
     render(): void;
     /** 获取评论操作实例对象 */
@@ -1396,13 +1407,29 @@ declare class CommentNode extends Component {
     /** 获取评论 ID */
     getID(): number;
     /** 置入子评论 */
-    putChild(childC: CommentNode, insertMode?: 'append' | 'prepend'): void;
+    putChild(childNode: CommentNode, insertMode?: 'append' | 'prepend'): void;
     /** 获取存放子评论的元素对象 */
-    getChildrenEl(): HTMLElement;
+    getChildrenWrapEl(): HTMLElement;
     /** 获取所有父评论 */
     getParents(): CommentNode[];
-    /** 获取评论元素对象 */
+    /**
+     * Get the element of the comment
+     *
+     * The `getEl()` will always return the latest $el after calling `render()`.
+     * Please be aware of the memory leak if you use the $el reference directly.
+     */
     getEl(): HTMLElement;
+    /**
+     * Focus on the comment
+     *
+     * Scroll to the comment and perform flash animation
+     */
+    focus(): void;
+    scrollIntoView(): void;
+    /**
+     * Remove the comment node
+     */
+    remove(): void;
     /** 获取 Gravatar 头像 URL */
     getGravatarURL(): string;
     /** 获取评论 markdown 解析后的内容 */
@@ -1415,7 +1442,7 @@ declare class CommentNode extends Component {
         os: string;
     };
     /** 获取配置 */
-    getConf(): CommentConf;
+    getOpts(): CommentOptions;
 }
 
 declare type CommentNode_2 = {
@@ -1426,6 +1453,25 @@ declare type CommentNode_2 = {
     level: number;
 };
 
+declare interface CommentOptions {
+    onAfterRender?: () => void;
+    onDelete?: Function;
+    /** The comment being replied to (linked comment) */
+    replyTo?: CommentData;
+    flatMode: boolean;
+    vote: boolean;
+    voteDown: boolean;
+    uaBadge: boolean;
+    nestMax: number;
+    gravatar: ArtalkConfig['gravatar'];
+    heightLimit: ArtalkConfig['heightLimit'];
+    avatarURLBuilder: ArtalkConfig['avatarURLBuilder'];
+    scrollRelativeTo: ArtalkConfig['scrollRelativeTo'];
+    getApi: () => Api;
+    replyComment: ContextApi['replyComment'];
+    editComment: ContextApi['editComment'];
+}
+
 declare interface CommonApiVersionData {
     app: string;
     commit_hash: string;
@@ -1451,6 +1497,7 @@ declare abstract class Component {
     $el: HTMLElement;
     get conf(): ArtalkConfig;
     constructor(ctx: ContextApi);
+    getEl(): HTMLElement;
 }
 
 declare enum ContentType {
@@ -1644,7 +1691,7 @@ export declare interface EditorApi extends Component {
      */
     hideLoading(): void;
     /**
-     * Start replaying a comment
+     * Start replying a comment
      */
     setReply(commentData: CommentData, $comment: HTMLElement, scroll?: boolean): void;
     /**
@@ -1879,11 +1926,6 @@ declare interface EntityCookedUserForAdmin {
     receive_email: boolean;
 }
 
-declare interface ErrorData {
-    msg: string;
-    data?: any;
-}
-
 declare type EventHandler<T> = (payload: T) => void;
 
 declare class EventManager<PayloadMap> implements EventManagerFuncs<PayloadMap> {
@@ -1923,7 +1965,7 @@ export declare interface EventPayloadMap {
     'list-fetched': ListFetchedArgs;
     'list-load': CommentData[];
     'list-loaded': CommentData[];
-    'list-failed': ErrorData;
+    'list-failed': ListErrorData;
     'list-goto-first': undefined;
     'list-reach-bottom': undefined;
     'comment-inserted': CommentData;
@@ -2188,6 +2230,13 @@ declare interface HandlerResponseCommentCreate {
     vote_up: number;
 }
 
+declare interface HandlerResponseCommentGet {
+    /** The comment detail */
+    comment: EntityCookedComment;
+    /** The reply comment if exists (like reply) */
+    reply_comment: EntityCookedComment;
+}
+
 declare interface HandlerResponseCommentList {
     comments: EntityCookedComment[];
     count: number;
@@ -2427,13 +2476,13 @@ declare interface LayerOptions {
 }
 
 declare interface LayoutOptions {
+    /** The comments wrap of list */
     $commentsWrap: HTMLElement;
     nestSortBy: ListNest.SortByType;
     nestMax: number;
     flatMode: boolean;
-    createCommentNode(comment: CommentData, ctxComments: CommentData[]): CommentNode;
+    createCommentNode(comment: CommentData, replyComment?: CommentData): CommentNode;
     findCommentNode(id: number): CommentNode | undefined;
-    getCommentDataList(): CommentData[];
 }
 
 declare class List extends Component {
@@ -2443,7 +2492,9 @@ declare class List extends Component {
     protected commentNodes: CommentNode[];
     getCommentNodes(): CommentNode[];
     constructor(ctx: ContextApi);
-    getListLayout(): ListLayout;
+    getListLayout({ forceFlatMode }?: {
+        forceFlatMode?: boolean;
+    }): ListLayout;
     private initCrudEvents;
 }
 
@@ -2458,10 +2509,15 @@ export declare interface ListData {
     page: PageData;
 }
 
-declare interface ListFetchedArgs {
+export declare interface ListErrorData {
+    msg: string;
+    data?: any;
+}
+
+export declare interface ListFetchedArgs {
     params: Partial<ListFetchParams>;
     data?: ListData;
-    error?: ErrorData;
+    error?: ListErrorData;
 }
 
 export declare interface ListFetchParams {
@@ -2481,13 +2537,9 @@ export declare interface ListLastFetchData {
 declare class ListLayout {
     private options;
     constructor(options: LayoutOptions);
+    private getStrategy;
     import(comments: CommentData[]): void;
-    insert(comment: CommentData): void;
-    private importCommentsNestMode;
-    /** 导入评论 · 平铺模式 */
-    private putCommentFlatMode;
-    private insertCommentNest;
-    private insertCommentFlatMode;
+    insert(comment: CommentData, replyComment?: CommentData): void;
 }
 
 declare namespace ListNest {
@@ -2612,10 +2664,8 @@ declare type QueryParamsType = Record<string | number, any>;
 
 declare class Render {
     comment: CommentNode;
-    get ctx(): ContextApi;
     get data(): CommentData;
-    get conf(): ArtalkConfig;
-    get cConf(): CommentConf;
+    get opts(): CommentOptions;
     $el: HTMLElement;
     $main: HTMLElement;
     $header: HTMLElement;
@@ -2630,6 +2680,15 @@ declare class Render {
     $replyTo?: HTMLElement;
     $replyAt?: HTMLElement;
     constructor(comment: CommentNode);
+    /**
+     * Render the comment ui
+     *
+     * If comment data is updated, call this method to re-render the comment ui.
+     * The method will be called multiple times, so it should be idempotent.
+     *
+     * Renders may add event listeners to the comment ui, so it should be called only once or override the original.
+     * Please be aware of the memory leak caused by the event listener.
+     */
     render(): HTMLElement;
     /** 内容限高检测 */
     checkHeightLimit(): void;
@@ -2639,12 +2698,10 @@ declare class Render {
     playFadeAnim(): void;
     /** 渐出动画 · 评论内容区域 */
     playFadeAnimForBody(): void;
+    /** Perform the flash animation */
+    playFlashAnim(): void;
     /** 获取子评论 Wrap */
-    getChildrenWrap(): HTMLElement | null;
-    /** 初始化子评论区域 Wrap */
-    renderChildrenWrap(): HTMLElement;
-    /** 恢复原有的子评论区域 Wrap */
-    recoveryChildrenWrap(): void;
+    getChildrenWrap(): HTMLElement;
     /** 设置已读 */
     setUnread(val: boolean): void;
     /** 设置为可点击的评论 */

package/dist/main.d.ts

@@ -237,6 +237,26 @@ declare class Api_2<SecurityDataType extends unknown> extends HttpClient<Securit
         createComment: (comment: HandlerParamsCommentCreate, params?: RequestParams) => Promise<HttpResponse<HandlerResponseCommentCreate, HandlerMap & {
             msg?: string | undefined;
         }>>;
+        /**
+         * @description Get the detail of a comment by comment id
+         *
+         * @tags Comment
+         * @name GetComment
+         * @summary Get a comment
+         * @request GET:/comments/{id}
+         * @response `200` `HandlerResponseCommentGet` OK
+         * @response `404` `(HandlerMap & {
+         msg?: string,
+
+         })` Not Found
+         * @response `500` `(HandlerMap & {
+         msg?: string,
+
+         })` Internal Server Error
+         */
+        getComment: (id: number, params?: RequestParams) => Promise<HttpResponse<HandlerResponseCommentGet, HandlerMap & {
+            msg?: string | undefined;
+        }>>;
         /**
          * @description Update a specific comment
          *
@@ -1227,6 +1247,8 @@ declare namespace ArtalkType {
         ContextApi,
         EditorState,
         EditorApi,
+        ListErrorData,
+        ListFetchedArgs,
         EventPayloadMap,
         ArtalkPlugin,
         SidebarShowPayload
@@ -1293,9 +1315,9 @@ declare interface CheckerStore {
 
 declare class CommentActions {
     private comment;
-    private get ctx();
     private get data();
-    private get cConf();
+    private get opts();
+    private getApi;
     constructor(comment: CommentNode);
     /** 投票操作 */
     vote(type: 'up' | 'down'): void;
@@ -1307,17 +1329,6 @@ declare class CommentActions {
     goToReplyComment(): void;
 }
 
-declare interface CommentConf {
-    isUnread?: boolean;
-    openURL?: string;
-    isFlatMode: boolean;
-    replyTo?: CommentData;
-    afterRender?: () => void;
-    openEvt?: () => void;
-    onReplyBtnClick?: Function;
-    onDelete?: Function;
-}
-
 export declare interface CommentData {
     /** 评论 ID */
     id: number;
@@ -1347,7 +1358,7 @@ export declare interface CommentData {
     badge_name?: string;
     /** 徽章颜色 */
     badge_color?: string;
-    /** IP 归属地 */
+    /** IP 属地 */
     ip_region?: string;
     /** 是否允许回复 */
     is_allow_reply: boolean;
@@ -1365,16 +1376,16 @@ export declare interface CommentData {
     vote_down: number;
 }
 
-declare class CommentNode extends Component {
+declare class CommentNode {
+    $el?: HTMLElement;
     private renderInstance;
     private actionInstance;
     private data;
-    private cConf;
+    private opts;
     private parent;
     private children;
     private nestCurt;
-    private nestMax;
-    constructor(ctx: ContextApi, data: CommentData, conf: CommentConf);
+    constructor(data: CommentData, opts: CommentOptions);
     /** 渲染 UI */
     render(): void;
     /** 获取评论操作实例对象 */
@@ -1396,13 +1407,29 @@ declare class CommentNode extends Component {
     /** 获取评论 ID */
     getID(): number;
     /** 置入子评论 */
-    putChild(childC: CommentNode, insertMode?: 'append' | 'prepend'): void;
+    putChild(childNode: CommentNode, insertMode?: 'append' | 'prepend'): void;
     /** 获取存放子评论的元素对象 */
-    getChildrenEl(): HTMLElement;
+    getChildrenWrapEl(): HTMLElement;
     /** 获取所有父评论 */
     getParents(): CommentNode[];
-    /** 获取评论元素对象 */
+    /**
+     * Get the element of the comment
+     *
+     * The `getEl()` will always return the latest $el after calling `render()`.
+     * Please be aware of the memory leak if you use the $el reference directly.
+     */
     getEl(): HTMLElement;
+    /**
+     * Focus on the comment
+     *
+     * Scroll to the comment and perform flash animation
+     */
+    focus(): void;
+    scrollIntoView(): void;
+    /**
+     * Remove the comment node
+     */
+    remove(): void;
     /** 获取 Gravatar 头像 URL */
     getGravatarURL(): string;
     /** 获取评论 markdown 解析后的内容 */
@@ -1415,7 +1442,7 @@ declare class CommentNode extends Component {
         os: string;
     };
     /** 获取配置 */
-    getConf(): CommentConf;
+    getOpts(): CommentOptions;
 }
 
 declare type CommentNode_2 = {
@@ -1426,6 +1453,25 @@ declare type CommentNode_2 = {
     level: number;
 };
 
+declare interface CommentOptions {
+    onAfterRender?: () => void;
+    onDelete?: Function;
+    /** The comment being replied to (linked comment) */
+    replyTo?: CommentData;
+    flatMode: boolean;
+    vote: boolean;
+    voteDown: boolean;
+    uaBadge: boolean;
+    nestMax: number;
+    gravatar: ArtalkConfig['gravatar'];
+    heightLimit: ArtalkConfig['heightLimit'];
+    avatarURLBuilder: ArtalkConfig['avatarURLBuilder'];
+    scrollRelativeTo: ArtalkConfig['scrollRelativeTo'];
+    getApi: () => Api;
+    replyComment: ContextApi['replyComment'];
+    editComment: ContextApi['editComment'];
+}
+
 declare interface CommonApiVersionData {
     app: string;
     commit_hash: string;
@@ -1451,6 +1497,7 @@ declare abstract class Component {
     $el: HTMLElement;
     get conf(): ArtalkConfig;
     constructor(ctx: ContextApi);
+    getEl(): HTMLElement;
 }
 
 declare enum ContentType {
@@ -1644,7 +1691,7 @@ export declare interface EditorApi extends Component {
      */
     hideLoading(): void;
     /**
-     * Start replaying a comment
+     * Start replying a comment
      */
     setReply(commentData: CommentData, $comment: HTMLElement, scroll?: boolean): void;
     /**
@@ -1879,11 +1926,6 @@ declare interface EntityCookedUserForAdmin {
     receive_email: boolean;
 }
 
-declare interface ErrorData {
-    msg: string;
-    data?: any;
-}
-
 declare type EventHandler<T> = (payload: T) => void;
 
 declare class EventManager<PayloadMap> implements EventManagerFuncs<PayloadMap> {
@@ -1923,7 +1965,7 @@ export declare interface EventPayloadMap {
     'list-fetched': ListFetchedArgs;
     'list-load': CommentData[];
     'list-loaded': CommentData[];
-    'list-failed': ErrorData;
+    'list-failed': ListErrorData;
     'list-goto-first': undefined;
     'list-reach-bottom': undefined;
     'comment-inserted': CommentData;
@@ -2188,6 +2230,13 @@ declare interface HandlerResponseCommentCreate {
     vote_up: number;
 }
 
+declare interface HandlerResponseCommentGet {
+    /** The comment detail */
+    comment: EntityCookedComment;
+    /** The reply comment if exists (like reply) */
+    reply_comment: EntityCookedComment;
+}
+
 declare interface HandlerResponseCommentList {
     comments: EntityCookedComment[];
     count: number;
@@ -2427,13 +2476,13 @@ declare interface LayerOptions {
 }
 
 declare interface LayoutOptions {
+    /** The comments wrap of list */
     $commentsWrap: HTMLElement;
     nestSortBy: ListNest.SortByType;
     nestMax: number;
     flatMode: boolean;
-    createCommentNode(comment: CommentData, ctxComments: CommentData[]): CommentNode;
+    createCommentNode(comment: CommentData, replyComment?: CommentData): CommentNode;
     findCommentNode(id: number): CommentNode | undefined;
-    getCommentDataList(): CommentData[];
 }
 
 declare class List extends Component {
@@ -2443,7 +2492,9 @@ declare class List extends Component {
     protected commentNodes: CommentNode[];
     getCommentNodes(): CommentNode[];
     constructor(ctx: ContextApi);
-    getListLayout(): ListLayout;
+    getListLayout({ forceFlatMode }?: {
+        forceFlatMode?: boolean;
+    }): ListLayout;
     private initCrudEvents;
 }
 
@@ -2458,10 +2509,15 @@ export declare interface ListData {
     page: PageData;
 }
 
-declare interface ListFetchedArgs {
+export declare interface ListErrorData {
+    msg: string;
+    data?: any;
+}
+
+export declare interface ListFetchedArgs {
     params: Partial<ListFetchParams>;
     data?: ListData;
-    error?: ErrorData;
+    error?: ListErrorData;
 }
 
 export declare interface ListFetchParams {
@@ -2481,13 +2537,9 @@ export declare interface ListLastFetchData {
 declare class ListLayout {
     private options;
     constructor(options: LayoutOptions);
+    private getStrategy;
     import(comments: CommentData[]): void;
-    insert(comment: CommentData): void;
-    private importCommentsNestMode;
-    /** 导入评论 · 平铺模式 */
-    private putCommentFlatMode;
-    private insertCommentNest;
-    private insertCommentFlatMode;
+    insert(comment: CommentData, replyComment?: CommentData): void;
 }
 
 declare namespace ListNest {
@@ -2612,10 +2664,8 @@ declare type QueryParamsType = Record<string | number, any>;
 
 declare class Render {
     comment: CommentNode;
-    get ctx(): ContextApi;
     get data(): CommentData;
-    get conf(): ArtalkConfig;
-    get cConf(): CommentConf;
+    get opts(): CommentOptions;
     $el: HTMLElement;
     $main: HTMLElement;
     $header: HTMLElement;
@@ -2630,6 +2680,15 @@ declare class Render {
     $replyTo?: HTMLElement;
     $replyAt?: HTMLElement;
     constructor(comment: CommentNode);
+    /**
+     * Render the comment ui
+     *
+     * If comment data is updated, call this method to re-render the comment ui.
+     * The method will be called multiple times, so it should be idempotent.
+     *
+     * Renders may add event listeners to the comment ui, so it should be called only once or override the original.
+     * Please be aware of the memory leak caused by the event listener.
+     */
     render(): HTMLElement;
     /** 内容限高检测 */
     checkHeightLimit(): void;
@@ -2639,12 +2698,10 @@ declare class Render {
     playFadeAnim(): void;
     /** 渐出动画 · 评论内容区域 */
     playFadeAnimForBody(): void;
+    /** Perform the flash animation */
+    playFlashAnim(): void;
     /** 获取子评论 Wrap */
-    getChildrenWrap(): HTMLElement | null;
-    /** 初始化子评论区域 Wrap */
-    renderChildrenWrap(): HTMLElement;
-    /** 恢复原有的子评论区域 Wrap */
-    recoveryChildrenWrap(): void;
+    getChildrenWrap(): HTMLElement;
     /** 设置已读 */
     setUnread(val: boolean): void;
     /** 设置为可点击的评论 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artalk",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "A self-hosted comment system",
   "keywords": [
     "comment-system",