initial plugin implementation - v0.1.0 (#1)

* Default configs and basic implementation

This commit contains the basic functionality for this plugin: force user
out of Insert mode after an amount of time, defined by user, of
inactivity.

* feat: added auto doc generation with panvimdoc

* Simplify and clean up

* Update linter/formatter rules to match LuaRocks standards

3 space tab instead of 4

* Add documentations

* Add empty doc/ directory for vimdoc later

* Updated panvimdoc workflow to include develop branch

experiment with github workflows

* Chores: Auto generate docs

* Clean up README

* Chores: Auto generate docs

* Remove develop branch from panvimdoc workflow

Revert 7304be

* Enable the ability to exclude specific filetypes

* Quick improvement in creating autocommand

nvim_create_augroup helps with preventing adding dulicated autocommand
everytime a buffer enters insert mode

* feat: Create user commands to toggle plugin current state

:StopInsertPlug enable/disable/toggle

---------

Co-authored-by: csessh <csessh@users.noreply.github.com>

.editorconfig

@@ -2,4 +2,4 @@ root = true
 
 [*.lua]
 indent_style = space
-indent_size = 4
+indent_size = 3

.github/workflows/panvimdoc.yml

@@ -0,0 +1,25 @@
+name: panvimdoc
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - README.md
+      - .github/workflows/panvimdoc.yml
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    name: pandoc to vimdoc
+    steps:
+      - uses: actions/checkout@v2
+      - uses: kdheepak/panvimdoc@main
+        with:
+          vimdoc: ${{ github.event.repository.name }}
+      - uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          commit_message: "Chores: Auto generate docs"
+          branch: ${{ github.head_ref }}

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing
+
+All contributions are most welcome! Please open a PR or create an [issue](https://github.com/csessh/stopinsert.nvim/issues).
+
+## Coding Style
+
+- Follow the coding style of [LuaRocks](https://github.com/luarocks/lua-style-guide).
+- Make sure you format the code with [StyLua](https://github.com/JohnnyMorganz/StyLua) before PR.

README.md

@@ -1 +1,55 @@
-# stopinsert.nvim
+## Intro
+
+`stopinsert` is a vim command (see [vimdoc](https://vimdoc.sourceforge.net/htmldoc/insert.html)) that works like hitting `<Esc>` in Insert mode.
+
+This plugin automatically kicks you out of Insert mode after certain amount of time of inactivity.
+
+## Installation
+
+1. Let your favourite package manager do the work:
+
+```lua
+-- lazy.nvim
+{
+    "csessh/stopinsert.nvim",
+    opts = {}
+},
+```
+
+2. Setup the plugin in your `init.lua`. This step is not needed with lazy.nvim if `opts` is set.
+
+```lua
+require("stopinsert").setup()
+```
+
+## Configuration
+
+| Items                 | Type      | Default Value      | Description    |
+| --------------------- | --------- | ------------------ | -------------- |
+| `idle_time_ms`        | number    | `5000` (5 seconds) | Maximum time (in milliseconds) before you are forced out of Insert mode back to Normal mode. |
+| `disabled_filetypes`  | list     | `{ "TelescopePrompt", "checkhealth", "help", "lspinfo", "mason", "neo%-tree*", }` | List of filetypes to exclude the effect of this plugin. |
+
+**NOTE:**
+By default, `stopinsert.nvim` excludes a list of filetypes, as shown in the table above. 
+
+If you configure this attribute in `opts` with your package manager, like so, your list will replace `stopinsert.nvim` defaults.
+
+Filetypes can also be listed as regex, such as `neo%-tree*`.
+
+## User command 
+
+`stopinsert.nvim` is enabled by default. You can toggle its state on the fly with the following commands:
+
+```
+:StopInsertPlug enable
+:StopInsertPlug disable
+:StopInsertPlug toggle
+```
+
+Each of them does exactly what it says on the tin.
+
+<!-- panvimdoc-ignore-start -->
+## Contribution
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+<!-- panvimdoc-ignore-end -->

doc/stopinsert.nvim.txt

@@ -0,0 +1,65 @@
+*stopinsert.nvim.txt*       For NVIM v0.8.0       Last change: 2024 October 05
+
+==============================================================================
+Table of Contents                          *stopinsert.nvim-table-of-contents*
+
+  - Intro                                              |stopinsert.nvim-intro|
+  - Installation                                |stopinsert.nvim-installation|
+  - Configuration                              |stopinsert.nvim-configuration|
+
+INTRO                                                  *stopinsert.nvim-intro*
+
+`stopinsert` is a vim command (see vimdoc
+<https://vimdoc.sourceforge.net/htmldoc/insert.html>) that works like typing
+`<Esc>` in Insert mode.
+
+This plugin automatically kicks you out of Insert mode after certain amount of
+time of inactivity.
+
+
+INSTALLATION                                    *stopinsert.nvim-installation*
+
+1. Let your favourite package manager do the work:
+
+>lua
+    -- lazy.nvim
+    {
+        "csessh/stopinsert.nvim",
+        opts = {}
+    },
+<
+
+1. Setup the plugin in your `init.lua`. This step is not needed with lazy.nvim if `opts` is set.
+
+>lua
+    require("stopinsert").setup()
+<
+
+
+CONFIGURATION                                  *stopinsert.nvim-configuration*
+
+  --------------------------------------------------------------------------------------------------------------------------------------
+  Items                    Type       Default Value                                                                     Description
+  ------------------------ ---------- --------------------------------------------------------------------------------- ----------------
+  idle_time_ms             number     5000 (5 seconds)                                                                  Maximum time (in
+                                                                                                                        milliseconds)
+                                                                                                                        before you are
+                                                                                                                        forced out of
+                                                                                                                        Insert mode back
+                                                                                                                        to Normal mode.
+
+  disabled_filetypes       list       { "TelescopePrompt", "checkhealth", "help", "lspinfo", "mason", "neo%-tree*", }   List of
+                                                                                                                        filetypes to
+                                                                                                                        exclude the
+                                                                                                                        effect of this
+                                                                                                                        plugin.
+  --------------------------------------------------------------------------------------------------------------------------------------
+**NOTE:** By default, `stopinsert.nvim` excludes a list of filetypes, as shown
+in the table above.
+
+If you configure this attribute in `opts` with your package manager, like so,
+your list will replace `stopinsert.nvim` defaults.
+
+Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
+
+vim:tw=78:ts=8:noet:ft=help:norl:

lua/stopinsert/config.lua

@@ -0,0 +1,23 @@
+local M = {}
+
+M.config = {
+   idle_time_ms = 5000,
+   disabled_filetypes = {
+      "TelescopePrompt",
+      "checkhealth",
+      "help",
+      "lspinfo",
+      "mason",
+      "neo%-tree*",
+   },
+}
+
+---@param user_config table
+---@return nil
+function M.set(user_config)
+   for key, value in pairs(user_config) do
+      M.config[key] = value
+   end
+end
+
+return M

lua/stopinsert/init.lua

@@ -0,0 +1,57 @@
+local M = {}
+local util = require("stopinsert.util")
+M.enable = true
+
+local commands = {
+   enable = function()
+      M.enable = true
+   end,
+   disable = function()
+      M.enable = false
+   end,
+   toggle = function()
+      M.enable = not M.enable
+   end,
+}
+
+---@param opts table
+---@return nil
+function M.setup(opts)
+   opts = opts or {}
+   require("stopinsert.config").set(opts)
+
+   vim.api.nvim_create_autocmd("InsertEnter", {
+      group = vim.api.nvim_create_augroup("InsertEnterListener", { clear = true }),
+      callback = function()
+         if not M.enable and not util.is_filetype_disabled(vim.bo.ft) then
+            return
+         end
+         util.reset_timer()
+      end,
+   })
+
+   vim.on_key(function(_, _)
+      if not M.enable and not util.is_filetype_disabled(vim.bo.ft) then
+         return
+      end
+
+      if vim.fn.mode() ~= "i" then
+         return
+      end
+
+      util.reset_timer()
+   end)
+
+   vim.api.nvim_create_user_command("StopInsertPlug", function(cmd)
+      if commands[cmd.args] then
+         commands[cmd.args]()
+      end
+   end, {
+      nargs = 1,
+      complete = function()
+         return { "enable", "disable", "toggle" }
+      end,
+   })
+end
+
+return M

lua/stopinsert/util.lua

@@ -0,0 +1,31 @@
+local M = {}
+local timer = nil
+local config = require("stopinsert.config").config
+
+---@return nil
+function M.force_exit_insert_mode()
+   if vim.fn.mode() == "i" then
+      vim.cmd("stopinsert")
+   end
+end
+
+---@return nil
+function M.reset_timer()
+   if timer then
+      timer:stop()
+   end
+   timer = vim.defer_fn(M.force_exit_insert_mode, config.idle_time_ms)
+end
+
+---@param ft string
+---@return boolean
+function M.is_filetype_disabled(ft)
+   for _, value in pairs(config.disabled_filetypes) do
+      if ft:match(value) then
+         return true
+      end
+   end
+   return false
+end
+
+return M

stylua.toml

@@ -1,3 +1,3 @@
 indent_type = "Spaces"
-indent_width = 4
+indent_width = 3
 column_width = 90