Improve docs/supplemental files for plugins (#5047)

Co-authored-by: Mm2PL <mm2pl+gh@kotmisia.pl>

CHANGELOG.md

@@ -16,7 +16,7 @@
 - Minor: Add an option to use new experimental smarter emote completion. (#4987)
 - Minor: Add `--safe-mode` command line option that can be used for troubleshooting when Chatterino is misbehaving or is misconfigured. It disables hiding the settings button & prevents plugins from loading. (#4985)
 - Minor: Updated the flatpakref link included with nightly builds to point to up-to-date flathub-beta builds. (#5008)
-- Minor: Add a new completion API for experimental plugins feature. (#5000)
+- Minor: Add a new completion API for experimental plugins feature. (#5000, #5047)
 - Minor: Re-enabled _Restart on crash_ option on Windows. (#5012)
 - Bugfix: Fixed an issue where certain emojis did not send to Twitch chat correctly. (#4840)
 - Bugfix: Fixed capitalized channel names in log inclusion list not being logged. (#4848)

docs/chatterino.d.ts

@@ -26,7 +26,7 @@ declare module c2 {
   }
 
   enum EventType {
-    RegisterCompletions = "RegisterCompletions",
+    CompletionRequested = "CompletionRequested",
   }
 
   type CbFuncCompletionsRequested = (
@@ -35,7 +35,7 @@ declare module c2 {
     cursor_position: number,
     is_first_word: boolean
   ) => CompletionList;
-  type CbFunc<T> = T extends EventType.RegisterCompletions
+  type CbFunc<T> = T extends EventType.CompletionRequested
     ? CbFuncCompletionsRequested
     : never;
 

docs/plugin-info.schema.json

@@ -43,7 +43,8 @@
       "type": "string",
       "description": "A small description of your license.",
       "examples": ["MIT", "GPL-2.0-or-later"]
-    }
+    },
+    "$schema": { "type": "string" }
   },
   "required": ["name", "description", "authors", "version", "license"]
 }

docs/plugin-meta.lua

@@ -0,0 +1,50 @@
+---@meta Chatterino2
+
+-- This file is intended to be used with LuaLS (https://luals.github.io/).
+-- Add the folder this file is in to "Lua.workspace.library".
+
+---@alias LogLevel integer
+
+---@class CommandContext
+---@field words string[] The words typed when executing the command. For example `/foo bar baz` will result in `{"/foo", "bar", "baz"}`.
+---@field channel_name string The name of the channel the command was executed in.
+
+---@class CompletionList
+---@field values string[] The completions
+---@field hide_others boolean Whether other completions from Chatterino should be hidden/ignored.
+
+c2 = {}
+
+---@type { Debug: LogLevel, Info: LogLevel, Warning: LogLevel, Critical: LogLevel }
+c2.LogLevel = {}
+
+--- Writes a message to the Chatterino log.
+---@param level LogLevel The desired level.
+---@param ... any Values to log. Should be convertible to a string with `tostring()`.
+function c2.log(level, ...) end
+
+--- Registers a new command called `name` which when executed will call `handler`.
+---@param name string The name of the command.
+---@param handler fun(ctx: CommandContext) The handler to be invoked when the command gets executed.
+---@return boolean ok  Returns `true` if everything went ok, `false` if a command with this name exists.
+function c2.register_command(name, handler) end
+
+--- Sends a message to `channel` with the specified text. Also executes commands.
+---
+--- **Warning**: It is possible to trigger your own Lua command with this causing a potentially infinite loop.
+---
+---@param channel string The name of the Twitch channel
+---@param text string The text to be sent
+---@return boolean ok
+function c2.send_msg(channel, text) end
+
+--- Creates a system message (gray message) and adds it to the Twitch channel specified by `channel`.
+---@param channel string
+---@param text string
+---@return boolean ok
+function c2.system_msg(channel, text) end
+
+--- Registers a callback to be invoked when completions for a term are requested.
+---@param type "CompletionRequested"
+---@param func fun(query: string, full_text_content: string, cursor_position: integer, is_first_word: boolean): CompletionList The callback to be invoked.
+function c2.register_callback(type, func) end

docs/wip-plugins.md

@@ -113,6 +113,42 @@ Limitations/known issues:
   rebuilding the window content caused by reloading another plugin will solve this.
 - Spaces in command names aren't handled very well (https://github.com/Chatterino/chatterino2/issues/1517).
 
+#### `register_callback("CompletionRequested", handler)`
+
+Registers a callback (`handler`) to process completions. The callback gets the following parameters:
+
+- `query`: The queried word.
+- `full_text_content`: The whole input.
+- `cursor_position`: The position of the cursor in the input.
+- `is_first_word`: Flag whether `query` is the first word in the input.
+
+Example:
+
+| Input      | `query` | `full_text_content` | `cursor_position` | `is_first_word` |
+| ---------- | ------- | ------------------- | ----------------- | --------------- |
+| `foo│`     | `foo`   | `foo`               | 3                 | `true`          |
+| `fo│o`     | `fo`    | `foo`               | 2                 | `true`          |
+| `foo bar│` | `bar`   | `foo bar`           | 7                 | `false`         |
+| `foo │bar` | `foo`   | `foo bar`           | 4                 | `false`         |
+
+```lua
+function string.startswith(s, other)
+    return string.sub(s, 1, string.len(other)) == other
+end
+
+c2.register_callback(
+    "CompletionRequested",
+    function(query, full_text_content, cursor_position, is_first_word)
+        if ("!join"):startswith(query) then
+            ---@type CompletionList
+            return { hide_others = true, values = { "!join" } }
+        end
+        ---@type CompletionList
+        return { hide_others = false, values = {} }
+    end
+)
+```
+
 #### `send_msg(channel, text)`
 
 Sends a message to `channel` with the specified text. Also executes commands.