refactor: update component modules

Author: lambdalisue

denops/fall/component/_component.ts

@@ -3,69 +3,125 @@ import * as popup from "jsr:@denops/std@^7.3.2/popup";
 import type { Border } from "jsr:@vim-fall/std@^0.4.0/theme";
 import type { Dimension } from "jsr:@vim-fall/std@^0.4.0/coordinator";
 
+const HIGHLIGHT_NORMAL = "FallNormal";
+const HIHGLIGHT_BORDER = "FallBorder";
+
+/**
+ * Properties that define the appearance and behavior of a component.
+ */
 export type ComponentProperties = {
-  title?: string;
-  border?: Border;
-  zindex?: number;
+  /** The title of the component */
+  readonly title?: string;
+
+  /** The border style for the component */
+  readonly border?: Border;
+
+  /** The z-index of the component */
+  readonly zindex?: number;
 };
 
+/**
+ * Information about the component's current state, including window ID and buffer number.
+ */
 export type ComponentInfo = {
-  bufnr: number;
-  winid: number;
-  dimension: Readonly<Dimension>;
+  /** The buffer number associated with the component */
+  readonly bufnr: number;
+
+  /** The window ID associated with the component */
+  readonly winid: number;
+
+  /** The dimension (size and position) of the component */
+  readonly dimension: Readonly<Dimension>;
 };
 
+/**
+ * Options for interacting with the component, such as abort signals.
+ */
+export type ComponentOptions = {
+  /** Signal used to abort operations */
+  signal?: AbortSignal;
+};
+
+/**
+ * The base interface for a component that can be opened, moved, updated, rendered, and closed.
+ * Provides methods to manipulate the component's window and update its properties.
+ */
 export type Component = AsyncDisposable & {
+  /**
+   * Opens the component window with the specified dimensions.
+   * @param denops The Denops instance.
+   * @param dimension The dimensions of the component.
+   * @param options Additional options such as the abort signal.
+   * @returns A disposable object to manage the component window's lifecycle.
+   */
   open(
     denops: Denops,
-    dimension: Readonly<Partial<Dimension>>,
-    option?: { signal?: AbortSignal },
+    dimension: Readonly<Dimension>,
+    options?: ComponentOptions,
   ): Promise<AsyncDisposable>;
 
+  /**
+   * Moves the component window to new dimensions.
+   * @param denops The Denops instance.
+   * @param dimension The new dimensions of the component.
+   * @param options Additional options such as the abort signal.
+   */
   move(
     denops: Denops,
     dimension: Readonly<Partial<Dimension>>,
-    options?: { signal?: AbortSignal },
+    options?: ComponentOptions,
   ): Promise<void>;
 
+  /**
+   * Updates the component's properties.
+   * @param denops The Denops instance.
+   * @param properties The new properties of the component.
+   * @param options Additional options such as the abort signal.
+   */
   update(
     denops: Denops,
     properties: Readonly<ComponentProperties>,
-    options?: { signal?: AbortSignal },
+    options?: ComponentOptions,
   ): Promise<void>;
 
+  /**
+   * Renders the component.
+   * @param denops The Denops instance.
+   * @param options Additional options such as the abort signal.
+   * @returns A promise that resolves to `true` or `void` when rendering is complete.
+   *        If the component does not need to render anything, it can resolve with `void`.
+   */
   render(
     denops: Denops,
-    options?: { signal?: AbortSignal },
+    options?: ComponentOptions,
   ): Promise<true | void>;
 
+  /**
+   * Closes the component.
+   */
   close(): Promise<void>;
 };
 
 /**
- * ```
- *                 width
- *  ┌───────────────────────────────────┐
- * ╭─────────────────────────────────────╮
- * │                                     │ ┐
- * │                                     │ │
- * │                                     │ │height
- * │                                     │ │
- * │                                     │ ┘
- * ╰─────────────────────────────────────╯
- * ```
+ * A base class for a component that can be opened, moved, updated, rendered, and closed.
+ * This class uses the `popup` module to manage the window and display the component.
  */
 export class BaseComponent implements Component {
   #opened?: {
     readonly window: popup.PopupWindow;
     readonly dimension: Readonly<Dimension>;
   };
+
   protected properties: Readonly<ComponentProperties>;
 
   constructor(properties: Readonly<ComponentProperties> = {}) {
     this.properties = properties;
   }
 
+  /**
+   * Returns information about the component's current state (buffer number, window ID, and dimensions).
+   * If the component is not opened, returns `undefined`.
+   */
   get info(): Readonly<ComponentInfo> | undefined {
     if (!this.#opened) {
       return undefined;
@@ -77,7 +133,7 @@ export class BaseComponent implements Component {
   async open(
     denops: Denops,
     dimension: Readonly<Dimension>,
-    { signal }: { signal?: AbortSignal } = {},
+    { signal }: ComponentOptions = {},
   ): Promise<AsyncDisposable> {
     if (this.#opened) {
       return this;
@@ -90,8 +146,8 @@ export class BaseComponent implements Component {
         relative: "editor",
         anchor: "NW",
         highlight: {
-          normal: "FallNormal",
-          border: "FallBorder",
+          normal: HIGHLIGHT_NORMAL,
+          border: HIHGLIGHT_BORDER,
         },
         noRedraw: true,
       }),
@@ -103,7 +159,7 @@ export class BaseComponent implements Component {
   async move(
     denops: Denops,
     dimension: Readonly<Partial<Dimension>>,
-    { signal }: { signal?: AbortSignal } = {},
+    { signal }: ComponentOptions = {},
   ): Promise<void> {
     if (this.#opened) {
       this.#opened = {
@@ -125,7 +181,7 @@ export class BaseComponent implements Component {
   async update(
     denops: Denops,
     properties: Readonly<ComponentProperties>,
-    { signal }: { signal?: AbortSignal } = {},
+    { signal }: ComponentOptions = {},
   ): Promise<void> {
     this.properties = {
       ...this.properties,
@@ -142,7 +198,7 @@ export class BaseComponent implements Component {
 
   render(
     _denops: Denops,
-    _option?: { signal?: AbortSignal },
+    _options: ComponentOptions = {},
   ): Promise<true | void> {
     return Promise.resolve(true);
   }

denops/fall/component/help.ts

@@ -8,20 +8,36 @@ import type { Dimension } from "jsr:@vim-fall/std@^0.4.0/coordinator";
 import { BaseComponent } from "./_component.ts";
 import { ItemBelt } from "../lib/item_belt.ts";
 
+/**
+ * Represents a page in the HelpComponent.
+ * Contains content and optional decorations for the page.
+ */
 export type Page = {
-  readonly title?: string;
+  /** The content to be displayed on the page */
   readonly content: readonly string[];
+
+  /** The decorations to be applied on the page (optional) */
   readonly decorations?: readonly Decoration[];
 };
 
+/**
+ * A component to display help content, extendable for navigation, rendering, and updating pages.
+ */
 export class HelpComponent extends BaseComponent {
   readonly #pages = new ItemBelt<Page>([]);
   #modifiedContent = true;
 
+  /**
+   * Returns the current page number (1-based).
+   */
   get page(): number {
     return this.#pages.index + 1;
   }
 
+  /**
+   * Sets the page number or sets it to the last page ("$").
+   * @param page - The page number to set or "$" to set to the last page.
+   */
   set page(page: number | "$") {
     if (page === "$") {
       page = this.#pages.count;
@@ -30,15 +46,25 @@ export class HelpComponent extends BaseComponent {
     this.#modifiedContent = true;
   }
 
+  /**
+   * Returns the list of all pages.
+   */
   get pages(): readonly Page[] {
     return this.#pages.items;
   }
 
+  /**
+   * Sets the list of pages and marks the content as modified.
+   * @param pages - An array of pages to set.
+   */
   set pages(pages: readonly Page[]) {
     this.#pages.items = pages;
     this.#modifiedContent = true;
   }
 
+  /**
+   * Forces the component to re-render by marking the content as modified.
+   */
   forceRender(): void {
     this.#modifiedContent = true;
   }

denops/fall/component/help_test.ts

@@ -0,0 +1,82 @@
+import "../lib/polyfill.ts";
+
+import { test } from "jsr:@denops/test@^3.0.4";
+import * as fn from "jsr:@denops/std@^7.3.2/function";
+import { fromFileUrl } from "jsr:@std/path@^1.0.8/from-file-url";
+import { assertEquals } from "jsr:@std/assert@^1.0.6";
+
+import { HelpComponent } from "./help.ts";
+
+const dimension = {
+  col: 1,
+  row: 1,
+  width: 10,
+  height: 5,
+};
+
+const runtimepath = fromFileUrl(new URL("../../../", import.meta.url));
+
+test({
+  mode: "all",
+  name: "HelpComponent",
+  prelude: [
+    `set runtimepath+=${runtimepath}`,
+    `runtime plugin/fall/*.vim`,
+  ],
+  fn: async (denops, t) => {
+    await t.step("render", async () => {
+      await using component = new HelpComponent();
+      await component.open(denops, dimension);
+      await component.render(denops);
+      await denops.cmd("redraw");
+
+      const info = component.info!;
+      assertEquals(await fn.getbufline(denops, info.bufnr, 1, "$"), [
+        "Page 1/0  ",
+      ]);
+
+      component.pages = [
+        {
+          content: [
+            "**Help Page 1**",
+            "**Introduction**",
+          ],
+        },
+      ];
+      await component.render(denops);
+      await denops.cmd("redraw");
+
+      // Verify the rendered content
+      assertEquals(await fn.getbufline(denops, info.bufnr, 1, "$"), [
+        "Page 1/1  ",
+        "**Help Page 1**",
+        "**Introduction**",
+      ]);
+
+      component.pages = [
+        {
+          content: [
+            "**Help Page 1**",
+            "**Introduction**",
+          ],
+        },
+        {
+          content: [
+            "**Help Page 2**",
+            "**Details**",
+          ],
+        },
+      ];
+      component.page = 2;
+      await component.render(denops);
+      await denops.cmd("redraw");
+
+      // Verify the content after page update
+      assertEquals(await fn.getbufline(denops, info.bufnr, 1, "$"), [
+        "Page 2/2  ",
+        "**Help Page 2**",
+        "**Details**",
+      ]);
+    });
+  },
+});