From 8214a23e2c2aca99efd69e6cd07be5a2705b349d Mon Sep 17 00:00:00 2001 From: sravioli Date: Fri, 8 May 2026 21:25:29 +0200 Subject: [PATCH 1/3] feat(lantern): add type annotations --- README.md | 1 + doc/wezterm-types-plugin.lantern.txt | 15 + docs/README.md | 1 + docs/lantern.md | 11 + lua/wezterm/types/plugins/lantern.lua | 387 ++++++++++++++++++++++++++ 5 files changed, 415 insertions(+) create mode 100644 doc/wezterm-types-plugin.lantern.txt create mode 100644 docs/lantern.md create mode 100644 lua/wezterm/types/plugins/lantern.lua diff --git a/README.md b/README.md index 2e41952..4bedc2c 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,7 @@ This project also features type annotations for various WezTerm plugins. | [battery.wez](https://github.com/rootiest/battery.wez) | [docs/battery.md](./docs/battery.md) | [:h wezterm-types-plugin.battery.txt](./doc/wezterm-types-plugin.battery.txt) | | [dev.wezterm](https://github.com/ChrisGVE/dev.wezterm) | [docs/dev.md](./docs/dev.md) | [:h wezterm-types-plugin.dev.txt](./doc/wezterm-types-plugin.dev.txt) | | [kanagawa.wz](https://github.com/sravioli/kanagawa.wz) | [docs/kanagawa.md](./docs/kanagawa.md) | [:h wezterm-types-plugin.kanagawa.txt](./doc/wezterm-types-plugin.kanagawa.txt) | +| [lantern.wz](https://github.com/sravioli/lantern.wz) | [docs/lantern.md](./docs/lantern.md) | [:h wezterm-types-plugin.lantern.txt](./doc/wezterm-types-plugin.lantern.txt) | | [lib.wezterm](https://github.com/ChrisGVE/lib.wezterm) | [docs/lib.md](./docs/lib.md) | [:h wezterm-types-plugin.lib.txt](./doc/wezterm-types-plugin.lib.txt) | | [listeners.wezterm](https://github.com/ChrisGVE/listeners.wezterm) | [docs/listeners.md](./docs/listeners.md) | [:h wezterm-types-plugin.listeners.txt](./doc/wezterm-types-plugin.listeners.txt) | | [log.wz](https://github.com/sravioli/log.wz) | [docs/log.md](./docs/log.md) | [:h wezterm-types-plugin.log.txt](./doc/wezterm-types-plugin.log.txt) | diff --git a/doc/wezterm-types-plugin.lantern.txt b/doc/wezterm-types-plugin.lantern.txt new file mode 100644 index 0000000..6299e73 --- /dev/null +++ b/doc/wezterm-types-plugin.lantern.txt @@ -0,0 +1,15 @@ +*wezterm-types-plugin.lantern.txt* `lantern` types + +LANTERN.WZ ~ + +You can import type annotations for `sravioli/lantern.wz` + as shown below: + +>lua + ---@type Lantern + local lantern = wezterm.plugin.require("https://github.com/sravioli/lantern.wz") +< + +Generated by panvimdoc + +vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/docs/README.md b/docs/README.md index 33e3992..f5d1b1c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,6 +11,7 @@ We will keep adding more community plugins as we find them. - [battery.wez](./battery.md) - [dev.wezterm](./dev.md) - [kanagawa.wz](./kanagawa.md) +- [lantern.wz](./lantern.md) - [lib.wezterm](./lib.md) - [listeners.wezterm](./listeners.md) - [log.wz](./log.md) diff --git a/docs/lantern.md b/docs/lantern.md new file mode 100644 index 0000000..564435a --- /dev/null +++ b/docs/lantern.md @@ -0,0 +1,11 @@ +### `lantern.wz` + +You can import type annotations for +[`sravioli/lantern.wz`](https://github.com/sravioli/lantern.wz) as shown below: + +```lua +---@type Lantern +local lantern = wezterm.plugin.require("https://github.com/sravioli/lantern.wz") +``` + + diff --git a/lua/wezterm/types/plugins/lantern.lua b/lua/wezterm/types/plugins/lantern.lua new file mode 100644 index 0000000..1810fc9 --- /dev/null +++ b/lua/wezterm/types/plugins/lantern.lua @@ -0,0 +1,387 @@ +---@meta +---@diagnostic disable:unused-local + +---@enum (key) Lantern.ResetBehavior +local reset_behaviors = { clear = 1, persist = 1 } + +---@alias Lantern.FlameDir string|string[] + +---@alias Lantern.GlowResult Lantern.Choice|Lantern.Choice[]|string|number + +---@class Lantern.Choice +---@field id string +---@field label? string + +---@class Lantern.BuildContext +---@field window Window +---@field pane Pane + +---@class Lantern.Context +---@field window? Window +---@field pane? Pane +---@field choice Lantern.Choice +---@field wick? Lantern.Wick + +---@class Lantern.Flame +---Return one choice, multiple choices, or a scalar value that Lantern can normalize. +--- +---@field glow? fun(ctx?: Lantern.BuildContext): Lantern.GlowResult +---Apply a selected choice to the provided config table. +--- +---@field ignite? fun(config: Config|table, ctx: Lantern.Context) +---Legacy alias for `glow`. +--- +---@field get? fun(ctx?: Lantern.BuildContext): Lantern.GlowResult +---Legacy alias for `ignite`. +--- +---@field pick? fun(config: Config|table, ctx: Lantern.Context) + +---@class Lantern.GpuFlame: Lantern.Flame +---Choose the best detected GPU adapter. +--- +---@field best fun(): GpuInfo|nil + +---@class Lantern.InternalChoice +---@field flame Lantern.Flame +---@field module_path? string +---@field choice Lantern.Choice + +---@alias Lantern.FormatChoices fun(choices: table, ctx: Lantern.BuildContext): Lantern.Choice[] + +---@alias Lantern.FormatDescription fun(desc: string, fuzzy: boolean, icons: Lantern.Icons): string + +---@class Lantern.IconPair +---@field ico string +---@field punct string + +---@class Lantern.Icons +---@field lantern string +---@field fuzzy Lantern.IconPair +---@field exact Lantern.IconPair + +---@class Lantern.LogConfig +---@field enabled boolean + +---@class Lantern.LogOpts +---@field enabled? boolean + +---@class Lantern.PersistenceConfig +---@field enabled boolean +---@field path? string +---@field legacy_path? string +---@field reset_behavior Lantern.ResetBehavior + +---@class Lantern.PersistenceOpts +---@field enabled? boolean +---@field path? string +---@field legacy_path? string +---@field reset_behavior? Lantern.ResetBehavior + +---@class Lantern.ColorConfig +---@field opacity number + +---@class Lantern.ColorOpts +---@field opacity? number + +---@class Lantern.DefaultFontConfig +---@field font? TextStyle +---@field font_rules? FontRules[] +---@field font_size? number +---@field line_height? number + +---@class Lantern.DefaultConfig +---@field title string +---@field sort_by string +---@field fuzzy boolean +---@field description string +---@field fuzzy_description string +---@field alphabet string +---@field icons Lantern.Icons +---@field comp fun(sort_by: string): fun(a: Lantern.Choice, b: Lantern.Choice): boolean +---@field format_choices Lantern.FormatChoices +---@field format_description Lantern.FormatDescription + +---@class Lantern.DefaultOpts +---@field title? string +---@field sort_by? string +---@field fuzzy? boolean +---@field description? string +---@field fuzzy_description? string +---@field alphabet? string +---@field icons? Lantern.Icons +---@field comp? fun(sort_by: string): fun(a: Lantern.Choice, b: Lantern.Choice): boolean +---@field format_choices? Lantern.FormatChoices +---@field format_description? Lantern.FormatDescription + +---@class Lantern.Config +---@field log Lantern.LogConfig +---@field persistence Lantern.PersistenceConfig +---@field defaults Lantern.DefaultConfig +---@field default_font Lantern.DefaultFontConfig +---@field color Lantern.ColorConfig + +---@class Lantern.SetupOpts +---@field log? Lantern.LogOpts +---@field persistence? Lantern.PersistenceOpts +---@field defaults? Lantern.DefaultOpts +---@field default_font? Lantern.DefaultFontConfig +---@field color? Lantern.ColorOpts + +---@class Lantern.WickSpec +---@field name? string +---@field title? string +---@field flames? (string|Lantern.Flame)[] +---@field flame_dirs? Lantern.FlameDir[] +---@field sort_by? string +---@field fuzzy? boolean +---@field alphabet? string +---@field description? string +---@field fuzzy_description? string +---@field persist? boolean +---@field comp? fun(a: Lantern.Choice, b: Lantern.Choice): boolean +---@field format_choices? Lantern.FormatChoices +---@field format_description? Lantern.FormatDescription + +---@class Lantern.Wick +---@field title string +---@field sort_by string +---@field fuzzy boolean +---@field alphabet string +---@field description string +---@field fuzzy_description string +---@field persist boolean +local W = {} + +---Register an inline flame or flame module path on this wick. +--- +---@param flame_spec string|Lantern.Flame +function W:register(flame_spec) end + +---Apply one selected choice to a config override table. +--- +---@param config Config|table +---@param ctx Lantern.Context +function W:select(config, ctx) end + +---Return a WezTerm action that opens this wick. +--- +---@return Action action +function W:light() end + +---@class Lantern.LightApi +---@operator call(string): Action +local L = {} + +---Open any registered wick. +--- +---@param name string +---@return Action action +function L:__call(name) end + +---Open the built-in colorscheme wick. +--- +---@return Action action +function L.colorscheme() end + +---Open the built-in font wick. +--- +---@return Action action +function L.font() end + +---Open the built-in font-size wick. +--- +---@return Action action +function L.font_size() end + +---Open the built-in line-height wick. +--- +---@return Action action +function L.font_leading() end + +---Open the built-in GPU adapter wick. +--- +---@return Action action +function L.gpu() end + +---Open the built-in window-opacity wick. +--- +---@return Action action +function L.window_opacity() end + +---Open the built-in window-padding wick. +--- +---@return Action action +function L.window_padding() end + +---Open the built-in cursor-style wick. +--- +---@return Action action +function L.cursor_style() end + +---Open the built-in inactive-pane-opacity wick. +--- +---@return Action action +function L.inactive_pane_opacity() end + +---Open the built-in font-ligatures wick. +--- +---@return Action action +function L.font_ligatures() end + +---Open the built-in tab-bar-style wick. +--- +---@return Action action +function L.tab_bar_style() end + +---@class Lantern.FlamesApi +local F = {} + +---Return cached flame module paths from one directory. +--- +---Pass a string for an absolute/custom directory, or path segments for a +---built-in Lantern flame directory under `plugin/lantern/flames`. +--- +---@param dir Lantern.FlameDir +---@return string[] modules +function F.from_dir(dir) end + +---Return cached flame module paths from multiple directories. +--- +---@param dirs Lantern.FlameDir[] +---@return string[] modules +function F.from_dirs(dirs) end + +---@class Lantern.ColorApi +local C = {} + +---Set tab button style in a config table from a Lantern colorscheme. +--- +---@param config Config|table +---@param scheme Palette +function C.set_tab_button(config, scheme) end + +---Apply a colorscheme to a WezTerm config override table. +--- +---@param config Config|table +---@param scheme Palette +---@param name string +function C.apply_scheme(config, scheme, name) end + +---Return a built-in Lantern colorscheme table by name. +--- +---@param name string +---@return Palette|nil scheme +function C.scheme(name) end + +---@class Lantern.StateEntry +---@field id string +---@field label? string +---@field module? string +---@field wick? string + +---@class Lantern.StateApi +local S = {} + +---Persist current state to disk. +function S.flush() end + +---Save one wick selection. +--- +---@param wick_name string +---@param entry Lantern.StateEntry +function S.save(wick_name, entry) end + +---Return one saved wick selection. +--- +---@param wick_name string +---@return Lantern.StateEntry|nil entry +function S.get(wick_name) end + +---Clear all saved state, or one wick when `wick_name` is passed. +--- +---@param wick_name? string +function S.clear(wick_name) end + +---Return all saved Lantern state. +--- +---@return table state +function S.all() end + +---Return the active state file path. +--- +---@return string path +function S.path() end + +---Return the legacy picker state file path used for migration. +--- +---@return string path +function S.legacy_path() end + +---@class Lantern.ConfigApi +local Cfg = {} + +---Merge user configuration into Lantern defaults. +--- +---@param opts? Lantern.SetupOpts +---@return Lantern.Config config +function Cfg.setup(opts) end + +---Return the active Lantern configuration. +--- +---@return Lantern.Config config +function Cfg.get() end + +---Return a copy of the default Lantern configuration. +--- +---@return Lantern.Config config +function Cfg.defaults() end + +---@class Lantern +---Built-in and custom wick action helpers. +--- +---@field light Lantern.LightApi +---Helpers for discovering flame modules. +--- +---@field flames Lantern.FlamesApi +---Configuration helpers. +--- +---@field config Lantern.ConfigApi +---Colorscheme helpers. +--- +---@field color Lantern.ColorApi +---Persistence helpers. +--- +---@field state Lantern.StateApi +local M = {} + +---Configure Lantern. +--- +---@param opts? Lantern.SetupOpts +---@return Lantern.Config config +function M.setup(opts) end + +---Register a user-defined wick. +--- +---@param name string +---@param spec Lantern.WickSpec|Lantern.Wick +---@return Lantern.Wick wick +function M.add_wick(name, spec) end + +---Return a registered wick by name. +--- +---@param name string +---@return Lantern.Wick|nil wick +function M.wick(name) end + +---Restore persisted Lantern selections into a config table. +--- +---@param config? Config|table +---@return Config|table config +function M.rekindle(config) end + +---Return the built-in GPU flame module. +--- +---@return Lantern.GpuFlame flame +function M.gpu() end + +-- vim: set ts=2 sts=2 sw=2 et ai si sta: From f814013b4b34bf557577be4b848d13a797934063 Mon Sep 17 00:00:00 2001 From: Guennadi Maximov C Date: Mon, 11 May 2026 20:38:40 -0600 Subject: [PATCH 2/3] docs: empty helpdoc for later panvimdoc action Signed-off-by: Guennadi Maximov C --- doc/wezterm-types-plugin.lantern.txt | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/doc/wezterm-types-plugin.lantern.txt b/doc/wezterm-types-plugin.lantern.txt index 6299e73..e69de29 100644 --- a/doc/wezterm-types-plugin.lantern.txt +++ b/doc/wezterm-types-plugin.lantern.txt @@ -1,15 +0,0 @@ -*wezterm-types-plugin.lantern.txt* `lantern` types - -LANTERN.WZ ~ - -You can import type annotations for `sravioli/lantern.wz` - as shown below: - ->lua - ---@type Lantern - local lantern = wezterm.plugin.require("https://github.com/sravioli/lantern.wz") -< - -Generated by panvimdoc - -vim:tw=78:ts=8:noet:ft=help:norl: From b1c2db0b89d5143551f7476cb2aab11b44b1d8be Mon Sep 17 00:00:00 2001 From: sravioli Date: Tue, 12 May 2026 21:29:10 +0200 Subject: [PATCH 3/3] fix(lantern): address review comments --- lua/wezterm/types/plugins/lantern.lua | 29 +++++++++++++++++---------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/lua/wezterm/types/plugins/lantern.lua b/lua/wezterm/types/plugins/lantern.lua index 1810fc9..eb0d354 100644 --- a/lua/wezterm/types/plugins/lantern.lua +++ b/lua/wezterm/types/plugins/lantern.lua @@ -4,7 +4,7 @@ ---@enum (key) Lantern.ResetBehavior local reset_behaviors = { clear = 1, persist = 1 } ----@alias Lantern.FlameDir string|string[] +---@alias Lantern.FlameDir string[]|string ---@alias Lantern.GlowResult Lantern.Choice|Lantern.Choice[]|string|number @@ -28,18 +28,21 @@ local reset_behaviors = { clear = 1, persist = 1 } ---@field glow? fun(ctx?: Lantern.BuildContext): Lantern.GlowResult ---Apply a selected choice to the provided config table. --- ----@field ignite? fun(config: Config|table, ctx: Lantern.Context) +---@field ignite? fun(config: Config, ctx: Lantern.Context) ---Legacy alias for `glow`. --- ---@field get? fun(ctx?: Lantern.BuildContext): Lantern.GlowResult ---Legacy alias for `ignite`. --- ----@field pick? fun(config: Config|table, ctx: Lantern.Context) +---@field pick? fun(config: Config, ctx: Lantern.Context) ---@class Lantern.GpuFlame: Lantern.Flame ----Choose the best detected GPU adapter. +local G = {} + +---Choose the best detected GPU adapter, if any. --- ----@field best fun(): GpuInfo|nil +---@return GpuInfo|nil info +function G.best() end ---@class Lantern.InternalChoice ---@field flame Lantern.Flame @@ -97,9 +100,13 @@ local reset_behaviors = { clear = 1, persist = 1 } ---@field fuzzy_description string ---@field alphabet string ---@field icons Lantern.Icons ----@field comp fun(sort_by: string): fun(a: Lantern.Choice, b: Lantern.Choice): boolean ---@field format_choices Lantern.FormatChoices ---@field format_description Lantern.FormatDescription +local DC = {} + +---@param sort_by string +---@return fun(a: Lantern.Choice, b: Lantern.Choice): boolean +function DC.comp(sort_by) end ---@class Lantern.DefaultOpts ---@field title? string @@ -159,7 +166,7 @@ function W:register(flame_spec) end ---Apply one selected choice to a config override table. --- ----@param config Config|table +---@param config Config ---@param ctx Lantern.Context function W:select(config, ctx) end @@ -256,13 +263,13 @@ local C = {} ---Set tab button style in a config table from a Lantern colorscheme. --- ----@param config Config|table +---@param config Config ---@param scheme Palette function C.set_tab_button(config, scheme) end ---Apply a colorscheme to a WezTerm config override table. --- ----@param config Config|table +---@param config Config ---@param scheme Palette ---@param name string function C.apply_scheme(config, scheme, name) end @@ -375,8 +382,8 @@ function M.wick(name) end ---Restore persisted Lantern selections into a config table. --- ----@param config? Config|table ----@return Config|table config +---@param config? Config +---@return Config config function M.rekindle(config) end ---Return the built-in GPU flame module.