Add docs for events and event opts + document web.json

3 files changed, 112 insertions, 3 deletions

diff --git a/lua/null-browser/api.lua b/lua/null-browser/api.lua
index ee861f0..0625869 100644
--- a/lua/null-browser/api.lua
+++ b/lua/null-browser/api.lua
@@ -187,10 +187,12 @@ end
 --- @param opts table                       Options
 --- @param opts.callback fun(opts:any):nil  Callback called when that event occurs
 ---
+--- @see WebEvents
+---
 --- @usage
 --- web.event.add_listener('UrlChanged', {
 ---   callback = function(opts)
----     print(opts.url, opts.tab, opts.win)
+---     print(opts.url, opts.view, opts.win)
 ---   end,
 --- })
 function web.event.add_listener(events, opts)
diff --git a/lua/null-browser/events.lua b/lua/null-browser/events.lua
new file mode 100644
index 0000000..1e55999
--- /dev/null
+++ b/lua/null-browser/events.lua
@@ -0,0 +1,79 @@
+---@diagnostic disable: doc-field-no-class, undefined-doc-param, undefined-doc-name
+--- Lua api for configuring null browser.
+--- @module web
+
+-- TODO: Make all opts naming consistent
+
+--- Events that can be listened to with web.events.add_listener
+---
+--- @table WebEvents
+--- @see KeyPressedEventOpts
+--- @see ModeChangedEventOpts
+--- @see NotificationReceivedEventOpts
+--- @see PermissionRequestedEventOpts
+--- @see UrlChangedEventOpts
+--- @see ViewClosedEventOpts
+--- @see ViewCreatedEventOpts
+--- @see ViewSelectedEventOpts
+--- @see WinCreatedEventOpts
+--- @see web.event.add_listener
+---
+--- @usage
+--- web.events.add_listener('UrlChanged', {
+---   callback = function(opts)
+---     print(opts.url)
+---   },
+--- end)
+
+--- @table WinCreatedEventOpts
+--- @field type 'WinCreated'
+--- @field view integer
+--- @field win integer
+
+--- @table ViewCreatedEventOpts
+--- @field type 'ViewCreated'
+--- @field view integer
+--- @field win integer
+
+--- @table ViewSelectedEventOpts
+--- @field type 'ViewSelected'
+--- @field view integer
+--- @field win integer
+
+--- @table ViewClosedEventOpts
+--- @field type 'ViewClosed'
+--- @field view integer
+--- @field win integer
+
+--- @table UrlChangedEventOpts
+--- @field type 'UrlChanged'
+--- @field view_id integer
+--- @field win_id integer
+--- @field url string
+
+--- @table PermissionRequestedEventOpts
+--- @field type 'PermissionRequested'
+--- @field premission_type 'MediaAudioCapture' | 'MediaVideoCapture' | 'MediaAudioVideoCapture' | 'DesktopVideoCapture' | 'DesktopAudioVideoCapture' | 'MouseLock' | 'Notifications' | 'Geolocation' | 'ClipboardReadWrite' | 'LocalFontsAccess' | 'Unsupported'
+--- @field webview_id integer
+--- @field win_id integer
+--- @field accept fun():nil
+--- @field reject fun():nil
+
+--- @table ModeChangedEventOpts
+--- @field type 'ModeChanged'
+--- @field mode string
+
+--- @table KeyPressedEventOpts
+--- @field type 'KeyPressed'
+--- @field key string
+
+--- @table NotificationReceivedEventOpts
+--- @field type 'NotificationReceived'
+--- @field title string
+--- @field message string
+--- @field tag string
+--- @field origin string
+--- @field click fun():nil
+--- @field show fun():nil
+--- @field close fun():nil
+
diff --git a/lua/null-browser/utils.lua b/lua/null-browser/utils.lua
index 2c9aba4..907f20c 100644
--- a/lua/null-browser/utils.lua
+++ b/lua/null-browser/utils.lua
@@ -17,10 +17,38 @@ local inspector = require 'null-browser.inspect'
 --- @return string
 web.inspect = inspector.inspect
 
+--- Print a lua object to inspect
+--- @param value any
+function web.print(value)
+  print(web.inspect(value))
+end
+
 web.json = web.json or {}
 local json = require 'null-browser.json'
-web.json.encode = json.encode
-web.json.decode = json.decode
+
+--- Encodes lua object as json into a string
+--- @param obj any                Value to encode into json string
+--- @param opts table?            Options
+--- @param opts.indent boolean?   Whether to enable indentation (default: false)
+--- @return string
+web.json.encode = function(obj, opts)
+  opts = opts or {}
+  local state = { indent = opts.indent or false }
+  return tostring(json.encode(obj, state))
+end
+
+--- Decodes a string into a lua object
+--- @diagnostic disable-next-line: undefined-doc-param
+--- @param json_str string        Json string to decode
+--- @param opts table             Options
+--- @param opts.null any          What to use as null value (default: nil)
+--- @return any
+web.json.decode = function(json_str, opts)
+  opts = opts or {}
+  local value, _, err = json.decode(json_str, nil, opts.null)
+  if err then error(err) end
+  return value
+end
 
 --- Trim whitespace from start and end of a string
 --- @param str string