updated documentation for v2.0.3.1028

CONTRIBUTING.md

@@ -78,6 +78,7 @@ src/
 ├── features/       # 特性模块，每个特性模块包含一组相关的功能。
 ├── ffmpeg/         # FFmpeg 相关代码。
 ├── hooks/          # 全局用的自定义 React Hooks。
+├── llms/           # 大语言模型相关代码。
 ├── migrations/     # 设定迁移脚本(从MV2到MV3)。
 ├── players/        # 直播解析器相关代码。
 ├── options/        # 设定库相关代码，包括对设定区块和功能设定区块的定义。
@@ -132,9 +133,9 @@ tests/
 
 完整测试: 从头开始测试所有测试用例，进行前需要先移除所有 `@scoped` 标签。
 
-- 当以下格式的分支被推送时，会触发快速测试：
-    - `feature/**`: 新功能分支
-    - `hotfix/**`: 修复分支
+- 当以下条件的分支被推送时，会触发快速测试：
+    - 所有格式为 `*/*` 的分支
+    - 非 `master` 或 `develop` 的分支
 
 - 当向 `develop` 分支提交 PR 时，以下条件会触发完整测试:
     - 当用户开启了 PR 时

docs/features.md

@@ -41,7 +41,7 @@ const handler: FeatureHookRender = async (settings, info) => {
     // 返回的则是在内容脚本中的每个部件渲染，支援 react portal 以使用与网页元素挂钩
     // 如果不使用portal, 则默认在扩展专用的 shadow-root 进行渲染
     // 如果你不想在内容脚本中渲染任何东西，可以返回空数组 []
-    // 如果你想基于条件禁用功能，可以返回 undefined
+    // 如果你想基于条件禁用功能，可以返回 undefined；如果要返回禁用信息提示，可返回 string
     return [
         <div>Hello, World!</div>, // 在 shadow-root 内渲染
         createPortal(<div>Hello, World!</div>, document.body) // 在网页元素内渲染

src/background/messages/open-tab.ts

@@ -1,10 +1,45 @@
 import type { PlasmoMessaging } from "@plasmohq/messaging"
 
+/**
+ * Represents the body of a request to open a new tab.
+ * 
+ * @example
+ * // Example of a request body to open a new tab with a specific URL
+ * const requestBody: RequestBody = {
+ *     url: "https://example.com",
+ *     active: true
+ * };
+ * 
+ * @example
+ * // Example of a request body with additional parameters and singleton criteria
+ * const requestBody: RequestBody = {
+ *     url: "https://example.com",
+ *     params: { ref: "newsletter" },
+ *     singleton: ["ref"]
+ * };
+ */
 export type RequestBody = {
+    /**
+     * The URL to open in the new tab.
+     */
     url?: string
+    /**
+     * The identifier of the tab to open.
+     */
     tab?: string
+    /**
+     * Whether the new tab should be active.
+     */
     active?: boolean
+    /**
+     * Additional parameters to include in the request.
+     */
     params?: Record<string, string>
+    /**
+     * Indicates if the tab should be a singleton. 
+     * If an array of strings is provided, it represents 
+     * only check the equality of those query params.
+     */
     singleton?: boolean | string[]
 }
 

src/features/recorder/components/RecorderButton.tsx

@@ -1,12 +1,12 @@
-import { IconButton, Tooltip } from "@material-tailwind/react"
+import { IconButton } from "@material-tailwind/react"
 import { useInterval } from "@react-hooks-library/core"
 import { useContext, useState, type MutableRefObject } from "react"
 import TailwindScope from "~components/TailwindScope"
 import ContentContext from "~contexts/ContentContexts"
 import RecorderFeatureContext from "~contexts/RecorderFeatureContext"
 import { useQuerySelector } from "~hooks/dom"
 import { useForceRender } from "~hooks/force-update"
-import { useComputedStyle, useContrast } from "~hooks/styles"
+import { useComputedStyle } from "~hooks/styles"
 import type { Recorder } from "~types/media"
 import { toTimer } from "~utils/misc"
 

src/hooks/form.ts

@@ -1,5 +1,33 @@
 import { useCallback, useRef } from "react";
 
+/**
+ * Custom hook to handle file input selection and processing.
+ *
+ * @param onFileChange - Callback function that processes the selected files. It should return a Promise.
+ * @param onError - Optional callback function to handle errors during file processing.
+ * @param deps - Dependency array for the `useCallback` hook.
+ *
+ * @returns An object containing:
+ * - `inputRef`: A reference to the file input element.
+ * - `selectFiles`: A function to trigger the file input dialog and handle file selection.
+ *
+ * @example
+ * ```typescript
+ * const { inputRef, selectFiles } = useFileInput(
+ *   async (files) => {
+ *     // Process the files
+ *     console.log(files);
+ *   },
+ *   (error) => {
+ *     // Handle the error
+ *     console.error(error);
+ *   }
+ * );
+ *
+ * // To trigger file selection
+ * selectFiles();
+ * ```
+ */
 export function useFileInput(onFileChange: (files: FileList) => Promise<void>, onError?: (e: Error | any) => void, deps: any[] = []) {
 
     const inputRef = useRef<HTMLInputElement>()

src/hooks/forwarder.ts

@@ -16,6 +16,7 @@ import { useEffect, useMemo } from 'react'
  *
  * @returns {Object} An object with two properties:
  * - `addHandler`: A function that takes a handler function as an argument. The handler function will be called with the data when a message with the specified command is received on the specified channel. The handler function is automatically removed when the component unmounts.
+ * - `addHandlerOnce`: A function that takes a handler function as an argument. The handler function will be called with the data when a message with the specified command is received on the specified channel. The handler function is automatically removed after it is called once.
  * - `sendForward`: A function that sends a message with the specified command to the specified channel. The message body is passed as an argument to this function.
  *
  * @example

src/hooks/life-cycle.ts

@@ -61,7 +61,27 @@ export const useAsyncEffect = <R = void>(
 };
 
 
-
+/**
+ * A React hook that switches between two JSX elements after a specified timeout.
+ *
+ * @param before - The initial JSX element to display before the timeout.
+ * @param after - The JSX element to display after the timeout.
+ * @param timeout - The duration (in milliseconds) to wait before switching to the `after` element.
+ * @returns The current JSX element, which will be `before` initially and `after` after the timeout.
+ *
+ * @example
+ * ```typescript
+ * const MyComponent = () => {
+ *   const element = useTimeoutElement(
+ *     <div>Loading...</div>,
+ *     <div>Loaded!</div>,
+ *     3000
+ *   );
+ *
+ *   return <div>{element}</div>;
+ * };
+ * ```
+ */
 export function useTimeoutElement(before: JSX.Element, after: JSX.Element, timeout: number) {
     const [element, setElement] = useState(before);
 

src/hooks/optimizer.ts

@@ -95,6 +95,28 @@ export function useRowOptimizer<E extends HTMLElement>(observerRef: React.Mutabl
 }
 
 
+/**
+ * Custom hook that manages a transaction-like process where data is collected and processed at specified intervals.
+ *
+ * @template T - The type of data being processed.
+ * @param {number} interval - The interval in milliseconds at which the callback is invoked.
+ * @param {(data: T) => void} callback - The callback function to process each piece of data.
+ * @returns {(data: T) => void} - A function to push data into the transaction queue.
+ *
+ * @example
+ * ```typescript
+ * const processTransaction = (data: string) => {
+ *   console.log('Processing:', data);
+ * };
+ *
+ * const pushData = useTransaction<string>(1000, processTransaction);
+ *
+ * pushData('data1');
+ * pushData('data2');
+ * // After 1 second, 'Processing: data1' will be logged.
+ * // After another second, 'Processing: data2' will be logged.
+ * ```
+ */
 export function useTransaction<T>(interval: number, callback: (data: T) => void) {
 
     const dataRef = useRef<T[]>([])

src/hooks/stream.ts

@@ -22,6 +22,27 @@ export type StreamContent = {
     blob: Blob | Blob[]
 }
 
+/**
+ * Hook to handle sending shard data through a forwarder channel.
+ *
+ * @param {ChannelType} channel - The channel to send data through.
+ * @returns {Function} A function to send stream content through the specified channel.
+ *
+ * @example
+ * const sendStreamContent = useShardSender(channel);
+ * 
+ * const streamContent = {
+ *   id: 'unique-id',
+ *   blob: new Blob(['data']),
+ *   duration: 120,
+ *   videoInfo: { title: 'Sample Video' },
+ *   filename: 'video.mp4'
+ * };
+ * 
+ * sendStreamContent(channel, streamContent)
+ *   .then(() => console.log('Stream content sent successfully'))
+ *   .catch(error => console.error('Failed to send stream content', error));
+ */
 export function useShardSender(channel: ChannelType) {
     const forwarder = useForwarder('stream-content', channel)
 
@@ -94,6 +115,31 @@ export type ReceiveInfo = {
     ready: (channel: ChannelType) => void
 }
 
+/**
+ * Custom hook to receive and manage stream data in chunks.
+ *
+ * @param id - The unique identifier for the stream.
+ * @param channel - The channel type for communication.
+ * @returns An object containing stream information, progress, error, and a ready function.
+ *
+ * @example
+ * const { info, progress, error, ready } = useShardReceiver('stream-id', 'channel-type');
+ * 
+ * useEffect(() => {
+ *   if (progress === 100) {
+ *     console.log('Stream fully received:', info);
+ *   }
+ * }, [progress]);
+ * 
+ * useEffect(() => {
+ *   if (error) {
+ *     console.error('Error receiving stream:', error);
+ *   }
+ * }, [error]);
+ * 
+ * // Send ready signal to start receiving stream data
+ * ready('channel-type');
+ */
 export function useShardReceiver(id: string, channel: ChannelType): ReceiveInfo {
 
     const forwarder = useForwarder('stream-content', channel)

src/hooks/styles.ts

@@ -1,10 +1,41 @@
 import { useMemo } from "react";
 
 
+/**
+ * Hook to get the computed style of a given DOM element.
+ *
+ * @param {Element} element - The DOM element to get the computed style for.
+ * @returns {CSSStyleDeclaration} The computed style of the given element.
+ *
+ * @example
+ * ```typescript
+ * const element = document.getElementById('myElement');
+ * const computedStyle = useComputedStyle(element);
+ * console.log(computedStyle.color); // Outputs the color style of the element
+ * ```
+ */
 export function useComputedStyle(element: Element): CSSStyleDeclaration {
     return useMemo(() => element ? window.getComputedStyle(element) : {} as CSSStyleDeclaration, [element]);
 }
 
+/**
+ * Calculates the contrast of a given background element and returns an object
+ * containing the brightness, appropriate text color, and a boolean indicating
+ * if the background is dark.
+ *
+ * @param {Element} background - The background element to compute the contrast for.
+ * @returns {Object} An object containing:
+ * - `brightness` {number} - The brightness value of the background color.
+ * - `color` {string} - The text color that contrasts with the background ('black' or 'white').
+ * - `dark` {boolean} - A boolean indicating if the background is dark (true if brightness > 125).
+ *
+ * @example
+ * const backgroundElement = document.getElementById('myElement');
+ * const contrast = useContrast(backgroundElement);
+ * console.log(contrast.brightness); // e.g., 150
+ * console.log(contrast.color); // 'black'
+ * console.log(contrast.dark); // true
+ */
 export function useContrast(background: Element) {
     const { backgroundColor: rgb } = useComputedStyle(background);
     return useMemo(() => {

src/options/fragments/llm.tsx

@@ -1,5 +1,5 @@
 import { Button, Input, Tooltip, Typography } from "@material-tailwind/react"
-import { Fragment, useEffect, useMemo, useRef, useState, type ChangeEvent, type ReactNode } from "react"
+import { Fragment, useMemo, useRef, useState, type ChangeEvent, type ReactNode } from "react"
 import { toast } from "sonner/dist"
 import type { StateProxy } from "~hooks/binding"
 import type { LLMTypes } from "~llms"