From cb98358a409d4df2a2bcea9d2b38d3549608e196 Mon Sep 17 00:00:00 2001 From: Kevin Silvester Date: Mon, 20 Apr 2026 15:17:05 +0100 Subject: [PATCH 1/4] fix(font): fix types and function signatures for `Wezterm.font()` and `Wezterm.font_with_fallback()` type def changes: * added `FontStyle` * added `FontAttributesBase` * added `FontAttributesIn` * added `TextStyleAttributes` * updated `FontAttributes` * updated `Font` * renamed `Font` -> `TextStyle` --- lua/wezterm/types/wezterm.lua | 81 ++++++++++++++++++++++++----------- 1 file changed, 57 insertions(+), 24 deletions(-) diff --git a/lua/wezterm/types/wezterm.lua b/lua/wezterm/types/wezterm.lua index a1b7ccc..be96dc2 100644 --- a/lua/wezterm/types/wezterm.lua +++ b/lua/wezterm/types/wezterm.lua @@ -456,6 +456,13 @@ local font_stretch = { UltraExpanded = 1, } +---@enum (key) FontStyle +local font_style = { + Italic = 1, + Normal = 1, + Oblique = 1, +} + ---@enum (key) FreeTypeLoadFlags local freetype_load_flags = { DEFAUlT = 1, @@ -466,18 +473,6 @@ local freetype_load_flags = { NO_HINTING = 1, } ----@class FontAttributes ----@field is_fallback? boolean ----@field is_synthetic? boolean ----@field scale? number ----@field stretch? FontStretch ----Whether the font should be an italic variant. ---- ----@field style? "Normal"|"Italic"|"Oblique" ----Whether the font should be a bold variant. ---- ----@field weight? FontWeight - ---@enum (key) FreeTypeTarget local freetype_target = { HorizontalLcd = 1, @@ -487,10 +482,7 @@ local freetype_target = { VerticalLcd = 1, } ----`FontAttributes`-like class but with font family ----and other extensions included. ---- ----@class FontFamilyAttributes: FontAttributes +---@class FontAttributesBase ---@field assume_emoji_presentation? boolean ---@field family string ---you can combine the flags like `"NO_HINTING|MONOCHROME"` @@ -511,9 +503,47 @@ local freetype_target = { --- - [`config.font_shaper`](lua://Config.font_shaper) --- ---@field harfbuzz_features? HarfbuzzFeatures[] +---@field stretch? FontStretch +---This will only be respected if the `italic` field is `nil`. +--- +---@field style? FontStyle +---@field weight? FontWeight +---@field scale? number ----@class Fonts +---The one of the accepted argument types for `Wezterm.font()` +---and `Wezterm.font_with_fallback()`. +---@class FontAttributesInput: FontAttributesBase +---Setting this field to `true`, will overwrite the `style` field to `Italic`. +---Setting this field to `false` will overwrite the `style` field to `Normal`. +--- +---@field italic? boolean + +---The final set of attributes for a font after processing the inputs to `Wezterm.font()` +---and `Wezterm.font_with_fallback()`. +---@class FontAttributes: FontAttributesBase +---@field is_fallback? boolean +---@field is_synthetic? boolean + +---@class TextStyleAttributes +---@field bold? boolean +---If set, when rendering text that is set to the default +---foreground color, use this color instead. This is most +---useful in a `Config.font_rules` section to implement changing +---the text color for eg: bold text. +--- +---For more information and examples, see: +--- - [Font Rules](ttps://wezterm.org/config/lua/config/font_rules.html) +--- - [`config.font_rules`](lua://Config.font_rules) +--- +---@field foreground? string +---@field italic? boolean +---@field stretch? FontStretch +---@field style? FontStyle +---@field weight? FontWeight + +---@class TextStyle ---@field fonts FontAttributes[] +---@field foreground? string ---@class WindowFrameConfig ---@field active_titlebar_bg? string @@ -1247,8 +1277,8 @@ function M.enumerate_ssh_hosts(ssh_config_file_name) end --- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) --- ---@param name string ----@param attributes? FontAttributes ----@return Fonts|FontFamilyAttributes +---@param attributes? TextStyleAttributes +---@return TextStyle function M.font(name, attributes) end ---This function constructs a Lua table that corresponds to the internal @@ -1284,9 +1314,10 @@ function M.font(name, attributes) end --- See: --- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) --- ----@param attributes FontFamilyAttributes ----@return Fonts|FontFamilyAttributes fonts -function M.font(attributes) end +---@param font FontAttributesInput +---@param attributes TextStyleAttributes +---@return TextStyle +function M.font(font, attributes) end ---TODO: Complete description. --- @@ -1294,8 +1325,9 @@ function M.font(attributes) end ---function. --- ---@param fonts (string|FontAttributes)[] ----@return Fonts fallback_fonts -function M.font_with_fallback(fonts) end +---@param attributes? TextStyleAttributes +---@return TextStyle +function M.font_with_fallback(fonts, attributes) end ---Can be used to produce a formatted string with terminal graphic attributes ---such as `bold`, `italic` and `colors`. @@ -2330,3 +2362,4 @@ function M.utf16_to_utf8(s) end return M -- vim: set ts=2 sts=2 sw=2 et ai si sta: + From ed569b80c0205da108981a607692f3f885ca8bd2 Mon Sep 17 00:00:00 2001 From: Kevin Silvester Date: Tue, 21 Apr 2026 00:22:09 +0100 Subject: [PATCH 2/4] feat(font): clean up font related docs, rename `FontAttributesInput` back to `FontFamilyAttributes`, add docs for `Wezterm.font_with_fallback()` --- lua/wezterm/types/wezterm.lua | 102 ++++++++++++++++++++++------------ 1 file changed, 67 insertions(+), 35 deletions(-) diff --git a/lua/wezterm/types/wezterm.lua b/lua/wezterm/types/wezterm.lua index be96dc2..0633ef3 100644 --- a/lua/wezterm/types/wezterm.lua +++ b/lua/wezterm/types/wezterm.lua @@ -483,6 +483,9 @@ local freetype_target = { } ---@class FontAttributesBase +---To control whether a font is considered to have emoji (rather than text) +---presentation glyphs for emoji. +--- ---@field assume_emoji_presentation? boolean ---@field family string ---you can combine the flags like `"NO_HINTING|MONOCHROME"` @@ -504,22 +507,21 @@ local freetype_target = { --- ---@field harfbuzz_features? HarfbuzzFeatures[] ---@field stretch? FontStretch ----This will only be respected if the `italic` field is `nil`. +---This option will only be respected if the `italic` option is `nil`. --- ---@field style? FontStyle ---@field weight? FontWeight ---@field scale? number ----The one of the accepted argument types for `Wezterm.font()` ----and `Wezterm.font_with_fallback()`. ----@class FontAttributesInput: FontAttributesBase ----Setting this field to `true`, will overwrite the `style` field to `Italic`. ----Setting this field to `false` will overwrite the `style` field to `Normal`. +---Argument type for `Wezterm.font()` and `Wezterm.font_with_fallback()`. +---@class FontFamilyAttributes: FontAttributesBase +---Setting this option to `true`, will overwrite the `style` option to `Italic`. +---Setting this option to `false` will overwrite the `style` option to `Normal`. --- ---@field italic? boolean ----The final set of attributes for a font after processing the inputs to `Wezterm.font()` ----and `Wezterm.font_with_fallback()`. +---Corresponds to the internal `FontAttributes` struct that is used to +---select a single named font. ---@class FontAttributes: FontAttributesBase ---@field is_fallback? boolean ---@field is_synthetic? boolean @@ -1251,7 +1253,7 @@ function M.emit(event, ...) end function M.enumerate_ssh_hosts(ssh_config_file_name) end ---This function constructs a Lua table that corresponds to the internal ----`FontFamilyAttributes` struct that is used to select a single named font: +---`FontAttributes` struct that is used to select a single named font: --- ---```lua ---local wezterm = require 'wezterm' @@ -1272,24 +1274,32 @@ function M.enumerate_ssh_hosts(ssh_config_file_name) end --- - The postscript name, which is an ostensibly unique name identifying a given font and style --- that is encoded into the font by the font designer. --- ----See also: ---- - [`FontAttributes`](lua://FontAttributes) ---- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) +---When specifying a font using its family name, the second `attributes` parameter is +---an **optional** table that can be used to specify style attributes. --- ----@param name string +---See: +--- - [`TextStyleAttributes`](lua://TextStyleAttributes) +--- - [`TextStyle`](lua://TextStyle) +--- +---@param font string|FontFamilyAttributes ---@param attributes? TextStyleAttributes ---@return TextStyle -function M.font(name, attributes) end +function M.font(font, attributes) end ---This function constructs a Lua table that corresponds to the internal ----`FontFamilyAttributes` struct that is used to select a single named font. +---`FontAttributes` struct that is used to select a single named font. --- ----When specifying a font using its family name, the second attributes parameter is ----an **optional** table that can be used to specify style attributes. +---The first parameter is a table where the font family and the attributes are combined. --- ----You can use the expanded form mentioned above to override freetype and harfbuzz settings +---You can use this expanded table form to override freetype and harfbuzz settings ---just for the specified font. --- +---The second attributes parameter is an **optional** table that can also be used +---to specify style attributes. +--- +---**Note**, that the attributes specified in the second `attributes` parameter will take precedence over +---any attributes specified in the first `font` parameter. +--- ---This example shows how to disable the default ligature feature just for this particular font: --- ---```lua @@ -1302,29 +1312,51 @@ function M.font(name, attributes) end ---} ---``` --- ----The following options can be specified in the same way: ---- - [`harfbuzz_features`](lua://FontFamilyAttributes.harfbuzz_features) ---- - [`freetype_load_target`](lua://FontFamilyAttributes.freetype_load_target) ---- - [`freetype_render_target`](lua://FontFamilyAttributes.freetype_render_target) ---- - [`freetype_load_flags`](lua://FontFamilyAttributes.freetype_load_flags) ---- - [`assume_emoji_presentation`](lua://FontFamilyAttributes.assume_emoji_presentation) ---- to control whether a font is considered to have emoji (rather than text) presentation glyphs ---- for emoji ---- ---- See: ---- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) +---See: +--- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) +--- - [`TextStyleAttributes`](lua://TextStyleAttributes) +--- - [`TextStyle`](lua://TextStyle) --- ----@param font FontAttributesInput ----@param attributes TextStyleAttributes +---@param font FontFamilyAttributes +---@param attributes? TextStyleAttributes ---@return TextStyle function M.font(font, attributes) end ----TODO: Complete description. +---This function constructs a lua table that configures a font with fallback processing. +---Glyphs are looked up in the first font in the list but if missing the next font is checked and so on. --- ----Here's some [info](https://wezterm.org/config/lua/wezterm/font_with_fallback.html) on this ----function. +---The first parameter is a table listing the fonts in their preferred order. +---The fonts can be specified by the their family or using the alternative form where the family and attributes +---are specified as part of the same lua table: +--- +---```lua +---local wezterm = require 'wezterm' +---return { +--- font = wezterm.font_with_fallback { +--- { +--- family = 'JetBrains Mono' +--- harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }, +--- weight = 'Medium' +--- }, +--- { family = 'Terminus', weight = 'Bold' }, +--- 'Noto Color Emoji', +---} +---``` +--- +---WezTerm implicitly adds its default fallback to the list that you specify. +--- +---The second `attributes` parameter is an **optional** table that can also be used +---to specify style attributes. +--- +---**Note**, that the attributes specified in the second `attributes` parameter will take precedence over +---any attributes specified in the individual font tables and will affect all listed fonts. +--- +---See: +--- - [`FontFamilyAttributes`](lua://FontFamilyAttributes) +--- - [`TextStyleAttributes`](lua://TextStyleAttributes) +--- - [`TextStyle`](lua://TextStyle) --- ----@param fonts (string|FontAttributes)[] +---@param fonts (string|FontFamilyAttributes)[] ---@param attributes? TextStyleAttributes ---@return TextStyle function M.font_with_fallback(fonts, attributes) end From 2ac260f362d17f4020988c61d01c0a3756c21abc Mon Sep 17 00:00:00 2001 From: Kevin Silvester Date: Tue, 21 Apr 2026 00:51:06 +0100 Subject: [PATCH 3/4] fix(font): update font releted option types --- lua/wezterm/types/config.lua | 12 +++++------- lua/wezterm/types/wezterm.lua | 3 +-- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/lua/wezterm/types/config.lua b/lua/wezterm/types/config.lua index 0dbbcff..2f073f0 100644 --- a/lua/wezterm/types/config.lua +++ b/lua/wezterm/types/config.lua @@ -269,8 +269,6 @@ local horiz_align = { --- ---@field width? "Cover"|"Contain"|number|string ----@alias AllFontAttributes Fonts|FontAttributes|FontFamilyAttributes - ---@enum (key) FontRules.Blink local blink = { None = 1, @@ -280,7 +278,7 @@ local blink = { ---@class FontRules ---@field blink? FontRules.Blink ----@field font? AllFontAttributes +---@field font? TextStyle ---@field intensity? FormatItemAttribute.Intensity ---@field invisible? boolean ---@field italic? boolean @@ -613,7 +611,7 @@ local exit_behavior_messaging = { --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback) --- - [`wezterm.font()`](lua://Wezterm.font) --- ----@field char_select_font? Fonts|FontFamilyAttributes +---@field char_select_font? TextStyle ---Specifies the size of the font used with [`CharSelect`](https://wezterm.org/config/lua/keyassignment/CharSelect.html). --- ---@field char_select_font_size? number @@ -713,7 +711,7 @@ local exit_behavior_messaging = { --- - [`wezterm.font()`](lua://Wezterm.font) --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback) --- ----@field command_palette_font? AllFontAttributes +---@field command_palette_font? TextStyle ---Specifies the size of the font used with `ActivateCommandPalette`. --- ---See: @@ -1108,7 +1106,7 @@ local exit_behavior_messaging = { --- - [`wezterm.font()`](lua://Wezterm.font) --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback) --- ----@field font? AllFontAttributes +---@field font? TextStyle ---@field font_colr_rasterizer? FontRasterizer ---By default, wezterm will use an appropriate system-specific method ---for locating the fonts that you specify using the options below. @@ -1818,7 +1816,7 @@ local exit_behavior_messaging = { ---config.pane_select_font = wezterm.font 'Roboto' ---``` --- ----@field pane_select_font? AllFontAttributes +---@field pane_select_font? TextStyle ---@field pane_select_font_size? number ---If non-zero, specifies the period (in seconds) at which various statistics are logged. --- diff --git a/lua/wezterm/types/wezterm.lua b/lua/wezterm/types/wezterm.lua index 0633ef3..cc93f1e 100644 --- a/lua/wezterm/types/wezterm.lua +++ b/lua/wezterm/types/wezterm.lua @@ -563,7 +563,7 @@ local freetype_target = { ---@field button_fg? string ---@field button_hover_bg? string ---@field button_hover_fg? string ----@field font? AllFontAttributes +---@field font? TextStyle ---@field font_size? number ---@field inactive_titlebar_bg? string ---@field inactive_titlebar_border_bottom? string @@ -2394,4 +2394,3 @@ function M.utf16_to_utf8(s) end return M -- vim: set ts=2 sts=2 sw=2 et ai si sta: - From edc4f46e42207779fa211379471e60b73ec0d4cb Mon Sep 17 00:00:00 2001 From: KevinSilvester <56918431+KevinSilvester@users.noreply.github.com> Date: Tue, 21 Apr 2026 20:16:23 +0100 Subject: [PATCH 4/4] chore: apply format suggestions Co-authored-by: Guennadi Maximov C Signed-off-by: KevinSilvester <56918431+KevinSilvester@users.noreply.github.com> --- lua/wezterm/types/wezterm.lua | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lua/wezterm/types/wezterm.lua b/lua/wezterm/types/wezterm.lua index cc93f1e..62906fa 100644 --- a/lua/wezterm/types/wezterm.lua +++ b/lua/wezterm/types/wezterm.lua @@ -506,12 +506,12 @@ local freetype_target = { --- - [`config.font_shaper`](lua://Config.font_shaper) --- ---@field harfbuzz_features? HarfbuzzFeatures[] +---@field scale? number ---@field stretch? FontStretch ---This option will only be respected if the `italic` option is `nil`. --- ---@field style? FontStyle ---@field weight? FontWeight ----@field scale? number ---Argument type for `Wezterm.font()` and `Wezterm.font_with_fallback()`. ---@class FontFamilyAttributes: FontAttributesBase @@ -522,6 +522,7 @@ local freetype_target = { ---Corresponds to the internal `FontAttributes` struct that is used to ---select a single named font. +--- ---@class FontAttributes: FontAttributesBase ---@field is_fallback? boolean ---@field is_synthetic? boolean