mini.nvim/lua/mini/colors.lua at main · augtheo/mini.nvim

Repository navigation

--- *mini.colors* Tweak and save any color scheme
--- *MiniColors*
--- MIT License Copyright (c) 2023 Evgeni Chasnovski
--- ==============================================================================
--- Features:
--- - Create colorscheme object: either manually (|MiniColors.as_colorscheme()|)
---   or by querying present color schemes (including currently active one; see
---   |MiniColors.get_colorscheme()|).
--- - Infer data about color scheme and/or modify based on it:
---     - Add transparency by removing background color (requires transparency
---       in terminal emulator).
---     - Infer cterm attributes (|cterm-colors|) based on gui colors making it
---       compatible with 'notermguicolors'.
---     - Resolve highlight group links (|:highlight-link|).
---     - Compress by removing redundant highlight groups.
---     - Extract palette of used colors and/or infer terminal colors
---       (|terminal-config|) based on it.
--- - Modify colors to better fit your taste and/or goals (see more in
---   |MiniColors-colorscheme-methods|):
---     - Apply any function to color hex string.
---     - Update channels (like lightness, saturation, hue, temperature, red,
---       green, blue, etc.; see more in |MiniColors-channels|).
---       Use either own function or one of the implemented methods:
---         - Add value to channel or multiply it by coefficient. Like "add 10
---           to saturation of every color" or "multiply saturation by 2" to
---           make colors more saturated (less gray).
---         - Invert. Like "invert lightness" to convert between dark/light theme.
---         - Set to one or more values (picks closest to current one). Like
---           "set to one or two hues" to make mono- or dichromatic color scheme.
---         - Repel from certain source(s) with stronger effect for closer values.
---           Like "repel from hue 30" to remove red color from color scheme.
---           Repel hue (how much is removed) is configurable.
---     - Simulate color vision deficiency.
--- - Once color scheme is ready, either apply it to see effects right away or
---   write it into a Lua file as a fully functioning separate color scheme.
--- - Experiment interactively with a feedback (|MiniColors.interactive()|).
--- - Animate transition between color schemes either with |MiniColors.animate()|
---   or with |:Colorscheme| user command.
--- - Convert within supported color spaces (|MiniColors.convert()|):
---     - Hex string.
---     - 8-bit number (terminal colors).
---     - RGB.
---     - Oklab, Oklch, Okhsl (https://bottosson.github.io/posts/oklab/).
--- - There is a collection of |MiniColors-recipes| with code snippets for some
---   common tasks.
--- - There is no goal to support as many color spaces as possible, only the
---   already present ones.
--- Tweak quick start ~
--- - Execute `:lua require('mini.colors').interactive()`.
--- - Experiment by writing calls to exposed color scheme methods and applying
---   them with `<M-a>`. For more information, see |MiniColors-colorscheme-methods|
---   and |MiniColors-recipes|.
--- - If you are happy with result, write color scheme with `<M-w>`. If not,
---   reset to initial color scheme with `<M-r>`.
--- - If only some highlight groups can be made better, adjust them manually
---   inside written color scheme file.
--- # Setup ~
--- This module doesn't need setup, but it can be done to improve usability.
--- Setup with `require('mini.colors').setup({})` (replace `{}` with your
--- `config` table). It will create global Lua table `MiniColors` which you can
--- use for scripting or manually (with `:lua MiniColors.*`).
--- See |MiniColors.config| for `config` structure and default values.
--- This module doesn't have runtime options, so using `vim.b.minicolors_config`
--- will have no effect here.
--- # Comparisons ~
--- - 'rktjmp/lush.nvim':
---     - Oriented towards tweaking separate highlight groups, while 'mini.colors'
---       is more designed to work with color scheme as a whole.
---     - Uses HSL and HSLuv color spaces, while 'mini.colors' uses Oklab, Oklch,
---       and Okhsl which have slightly better perceptual uniformity properties.
---     - Doesn't have functionality to infer and repair missing data in color
---       scheme (like cterm attributes, terminal colors, transparency, etc.),
---       while 'mini.colors' does.
---     - Doesn't implement animation of color scheme transition, while
---       'mini.colors' does.
--- - 'lifepillar/vim-colortemplate':
---     - Comparisons are similar to that of 'rktjmp/lush.nvim'.
--- - 'tjdevries/colorbuddy.nvim':
---     - Comparisons are similar to that of 'rktjmp/lush.nvim'.
--- Recipes for common tasks ~
--- All following code snippets assume to be executed inside interactive buffer
--- (|MiniColors.interactively()|). They are directly copy-pasteable.
--- To apply single method to current color scheme, use >vim
---   :lua MiniColors.get_colorscheme():<method goes here>:apply().
--- Recipes:
--- - Tweak lightness: >lua
---   -- Invert dark/light color scheme to be light/dark
---   chan_invert('lightness', { gamut_clip = 'cusp' })
---   -- Ensure constant contrast ratio
---   chan_set('lightness', 15, { filter = 'bg' })
---   chan_set('lightness', 85, { filter = 'fg' })
--- - Tweak saturation: >lua
---   -- Make background colors less saturated and foreground - more
---   chan_add('saturation', -20, { filter = 'bg' })
---   chan_add('saturation', 20,  { filter = 'fg' })
---   -- Convert to grayscale
---   chan_set('saturation', 0)
--- - Tweak hue: >lua
---   -- Create monochromatic variant (this uses green color)
---   chan_set('hue', 135)
---   -- Create dichromatic variant (this uses Neovim-themed hues)
---   chan_set('hue', { 140, 245 })
--- - Tweak temperature: >lua
---   -- Invert temperature (make cold theme become warm and vice versa)
---   chan_invert('temperature')
---   -- Make background colors colder and foreground warmer
---   chan_add('temperature', -40, { filter = 'bg' })
---   chan_add('temperature', 40,  { filter = 'fg' })
--- - Counter color vision deficiency (try combinations of these to see which
---   one works best for you):
---     - Improve text saturation contrast (usually the best starting approach): >lua
---       chan_set('saturation', { 10, 90 }, { filter = 'fg' })
---     - Remove certain hues from all colors (use 30 for red, 90 for yellow,
---       135 for green, 270 for blue): >lua
---       -- Repel red color
---       chan_repel('hue', 30, 45)
---     - Force equally spaced palette (remove ones with which you know you
---       have trouble): >lua
---       -- Might be a good choice for red-green color blindness
---       chan_set('hue', { 90, 180, 270})
---       -- Might be a good choice for blue-yellow color blindness
---       chan_set('hue', { 0, 90, 180 })
---     - Inverting temperature or pressure can sometimes improve readability: >lua
---       chan_invert('temperature')
---       chan_invert('pressure')
---     - If all hope is lost, hue random generation might help if you are lucky: >lua
---       chan_modify('hue', function() return math.random(0, 359) end)
--- - For color scheme creators use |MiniColors-colorscheme:simulate_cvd()| to
---   simulate various color vision deficiency types to see how color scheme
---   would look in the eyes of color blind person.
---@tag MiniColors-recipes
--- Color space is a way to quantitatively describe a color. In this module
--- color spaces are used both as source for |MiniColors-channels| and inputs
--- for |MiniColors.convert()|
--- List of supported color spaces (along with their id in parenthesis):
--- - 8-bit (`8-bit`) - integer between 16 and 255. Usually values 0-15 are also
---   supported, but they depend on terminal emulator theme which is not reliable.
---   See https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit .
--- - Hex (`hex`) - string of the form "#xxxxxx" where `x` is a hexadecimal number.
--- - RGB (`rgb`) - table with numeric fields `r` (red), `g` (green), `b` (blue).
---   Visible range is from 0 to 255.
--- - Oklab (`oklab`) - table with fields `l` (lightness; numeric in [0; 100]),
---   `a`, `b` (both are unbounded numeric; visible range is usually between
---   -30 to 30). Field `l` describes how light is color; `a` - how "green-red" it is;
---   `b` - how "blue-yellow" it is.
--- - Oklch (`oklch`) - table with fields `l` (same as in Oklab),
---   `c` (chroma; positive numeric, visible range usually lower than 32),
---   `h` (`nil` for grays or periodic numeric in [0, 360)). Field `c` describes how
---   colorful a color is; `h` is a value of "true color" on color circle/wheel.
---   NOTE: gray colors, being achromatic by nature, don't have hue.
--- - Okhsl (`okhsl`) - Oklch but with `c` replaced by `s` (saturation; numeric
---   in [0; 100]). Field `s` describes a percent of chroma relative to maximum
---   visible chroma for the particular lightness and hue combination. Note,
---   that mathematical model used to compute maximum visible chroma is
---   approximate which might lead to inaccuracies for highly saturated colors
---   with relatively low or high lightness.
--- Sources for Oklab/Oklch/Okhsl:
--- - https://bottosson.github.io/posts/oklab/ - initial derivation and
---   introduction of Oklab and Oklch.
--- - https://bottosson.github.io/misc/colorpicker - interactive color picker.
---   Great way for a hands-on introduction to concepts of lightness, chroma,
---   saturation, and hue.
---                                                          *MiniColors-gamut-clip*
--- Gamut clip ~
--- In Neovim highlight group colors are usually specified by their red, green,
--- and blue values from 0 to 255 in the form of HEX string (see |gui-colors|).
--- Although plenty, these are not all possible colors.
--- When performing color manipulation using |MiniColors-colorscheme-methods|,
--- it is possible to end up with "impossible" color (which can't be directly
--- converted to HEX string). For example, inverting lightness of color "#fce094"
--- will lead to a color `{ l = 10, c = 10, h = 90 }` in Oklch space, i.e.
--- "dark yellow" which is impossible to show in HEX.
--- **Gamut clipping** is an action of converting color outside of visible gamut
--- (colors representable with HEX string) to be inside it while preserving
--- certain perceptual characteristics as much as possible.
--- Gamut clipping in this module is done inside Oklch color space. The goal is to
--- preserve hue as much as possible while manipulating lightness and/or chroma.
--- List of supported gamut clip methods (along with their id in parenthesis):
--- - Clip chroma (`'chroma'`) - reduce chroma while preserving lightness until
---   color is inside visible gamut. Default method.
--- - Clip lightness (`'lightness'`) - reduce lightness while preserving chroma
---   until color is inside visible gamut.
--- - Clip according to "cusp" (`'cusp'`) - reduce both lightness and chroma in
---   a compromise way depending on hue.
---   Cusp is a color with the highest chroma inside slice of visible gamut
---   with the same hue (hue leaf). It is called that way because the slice has
---   a roughl
8
y triang
10BC8
ular shape with points at (0, 0) - (0, 100) - "cusp" in
---   (chroma, lightness) coordinates.
---   Gamut clipping using "cusp" as reference is done by changing color towards
---   (0, cusp_lightness) point (gray with lightness equal to that of a current
---   cusp) until color is inside visible gamut.
--- In short:
--- - Usually `'chroma'` is enough.
--- - If colors are too desaturated - try `'cusp'`.
--- - If still not colorful enough - try `'lightness'`.
--- - Currently implemented formulas are approximate (by design; to reduce code
---   complexity) so there might be problems for highly saturated colors with
---   relatively low or high lightness.
---@tag MiniColors-color-spaces
--- A color channel is a number describing one particular aspect of a color.
--- It is usually direct or modified coordinate of a color space. See
--- |MiniColors-color-spaces| for information on color spaces.
--- List of supported channels (along with their id in parenthesis):
--- - Lightness (`lightness`) - corrected `l` component of Oklch. Describes how
---   light is a color. Ranges from 0 (black dark) to 100 (white light).
--- - Chroma (`chroma`) - `c` component of Oklch. Describes how colorful is
---   a color in absolute units. Ranges from 0 (gray) to infinity (more like
---   around 30 in practice).
--- - Saturation (`saturation`) - `s` component of Okhsl. Describes how colorful
---   is color in relative units. Ranges from 0 (gray) to 100 (maximum saturation
---   for a given lightness-hue pair).
--- - Hue (`hue`) - `h` component of Oklch. Describes "true color value" (like
---   red/green/blue) as a number. It is a periodic value from 0 (included) to
---   360 (not included). Best perceived as a degree on a color circle/wheel.
---   Approximate values for common color names:
---     - 0   - pink.
---     - 30  - red.
---     - 60  - orange.
---     - 90  - yellow.
---     - 135 - green.
---     - 180 - cyan.
---     - 225 - light blue.
---     - 270 - blue.
---     - 315 - magenta/purple.
--- - Temperature (`temperature`) - circular distance from current hue to hue 270
---   angle (blue). Ranges from 0 (cool) to 180 (hot) anchored at hues 270 (blue)
---   and 90 (yellow). Similar to `b` channel but tries to preserve chroma.
--- - Pressure (`pressure`) - circular distance from current hue to hue 180.
---   Ranges from 0 (low; green-ish) to 180 (high; red-ish) anchored at hues
---   180 and 0. Similar to `a` channel but tries to preserve chroma.
---   Not widely used; added to have something similar to temperature.
--- - a (`a`) - `a` component of Oklab. Describes how "green-red" a color is.
---   Can have any value. Negative values are "green-ish", positive - "red-ish".
--- - b (`b`) - `b` component of Oklab. Describes how "blue-yellow" a color is.
---   Can have any value. Negative values are "blue-ish", positive - "yellow-ish".
--- - Red (`red`) - `r` component of RGB. Describes how much red a color has.
---   Ranges from 0 (no red) to 255 (full red).
--- - Green (`green`) - `g` component of RGB. Describes how much green a color has.
---   Ranges from 0 (no green) to 255 (full green).
--- - Blue (`blue`) - `b` component of RGB. Describes how much blue a color has.
---   Ranges from 0 (no blue) to 255 (full blue).
---@tag MiniColors-channels
---@alias __colors_channel `(string)` One of supported |MiniColors-channels|.
---@alias __colors_chan_opts `(table|nil)` Options. Possible fields:
---   - <filter> `(function|string)` - filter colors to update. Possible values:
---       - String representing target attributes. One of `'fg'`, `'bg'`, `'sp'`,
---         `'term'` (only terminal colors).
---       - Callable with signature as in |MiniColors-colorscheme:color_modify()|.
---     Default: `nil` to update all colors.
---   - <gamut_clip> `(string)` - gamut clipping method. One of `'chroma'`,
---     `'lightness'`, `'cusp'`. See |MiniColors-gamut-clip|. Default: `'chroma'`.
--- Colorscheme object is a central structure of this module. It contains all
--- data relevant to colors in fields and provides methods to modify it.
--- Create colorscheme object manually with |MiniColors.as_colorscheme()|: >lua
---   MiniColors.as_colorscheme({
---     name = 'my_cs',
---     groups = {
---       Normal   = { fg = '#dddddd', bg = '#222222' },
---       SpellBad = { sp = '#dd2222', undercurl = true },
---     terminal = { [0] = '#222222', [1] = '#dd2222' },
--- Get any registered color scheme (including currently active) as colorscheme
--- object with |MiniColors.get_colorscheme()|: >lua
---   -- Get current color scheme
---   MiniColors.get_colorscheme()
---   -- Get registered color scheme by name
---   MiniColors.get_colorscheme('minischeme', { new_name = 'maxischeme' })
---@class Colorscheme
---                                                  *MiniColors-colorscheme-fields*
---@field name string|nil Name of the color scheme (as in |g:colors_name|).
---@field groups table|nil Table with highlight groups data. Keys are group
---   names appropriate for `name` argument of |nvim_set_hl()|, values - tables
---   appropriate for its `val` argument. Note: gui colors are accepted only in
---   short form (`fg`, `bg`, `sp`).
---@field terminal table|nil Table with terminal colors data (|terminal-config|).
---   Keys are numbers from 0 to 15, values - strings representing color (hex
---   string or plain color name; see |nvim_get_color_by_name()|).
---                                                 *MiniColors-colorscheme-methods*
--- Notes about all methods:
--- - They never modify underlying colorscheme object instead returning deep
---   copy with modified fields.
--- - They accept `self` colorscheme object as first argument meaning they should be
---   called with `:` notation (like `cs:method()`).
--- Example calling methods: >lua
---   -- Get current color scheme, set hue of colors to 135, infer cterm
---   -- attributes and apply
---   local cs = MiniColors.get_colorscheme()
---   cs:chan_set('hue', 135):add_cterm_attributes():apply()
---                                  *MiniColors-colorscheme:add_cterm_attributes()*
--- Infer |cterm-colors| based on present |gui-colors|. It updates `ctermbg`/`ctermfg`
--- based on `fg`/`bg` by approximating in perceptually uniform distance in Oklab
--- space (|MiniColors-color-spaces|).
--- Parameters ~
--- {opts} `(table|nil)` Options. Possible fields:
---   - <force> `(boolean)` - Whether to replace already present cterm attributes
---     with inferred ones. Default: `true`.
---                                   *MiniColors-colorscheme:add_terminal_colors()*
--- Infer terminal colors (|terminal-config|) based on colorscheme palette
--- (see |MiniColors-colorscheme:get_palette()|). It updates `terminal` field
--- based on color scheme's palette by picking the most appropriate entry to
--- represent terminal color. Colors from 0 to 7 are attempted to be black,
--- red, green, yellow, blue, magenta, cyan, white. Colors from 8 to 15 are
--- the same as from 0 to 7.
--- Parameters ~
--- {opts} `(table|nil)` Options. Possible fields:
---   - <force> `(boolean)` - Whether to replace already present terminal colors
---     with inferred ones. Default: `true`.
---   - <palette_args> `(table)` - |MiniColors-colorscheme:get_palette()| arguments.
---                                      *MiniColors-colorscheme:add_transparency()*
--- Add transparency by removing background from a certain highlight groups.
--- Requires actual transparency from terminal emulator to experience visible
--- transparency.
--- Parameters ~
--- {opts} `(table|nil)` Options. Possible fields can be used to configure which
---   sets of highlight groups to update:
---   - <general> `(boolean)` - general groups (like `Normal`). Default: `true`.
---   - <float> `(boolean)` - built-in groups for floating windows. Default: `false`.
---   - <statuscolumn> `(boolean)` - groups related to 'statuscolumn' (signcolumn,
---     numbercolumn, foldcolumn). Also updates groups for all currently
---     defined signs. Default: `false`.
---   - <statusline> `(boolean)` - built-in groups for 'statusline'. Default: `false`.
---   - <tabline> `(boolean)` - built-in groups for 'tabline'. Default: `false`.
---   - <winbar> `(boolean)` - built-in groups for 'winbar'. Default: `false`.
---                                                 *MiniColors-colorscheme:apply()*
--- Apply colorscheme:
--- - Set |g:colors_name| to a `name` field.
--- - Apply highlight groups in a `groups` field.
--- - Set terminal colors from a `terminal` field.
--- Parameters ~
--- {opts} `(table|nil)` Options. Possible fields:
---   - <clear> `(boolean)` - whether to execute |:hi-clear| first. Default: `true`.
---                                              *MiniColors-colorscheme:chan_add()*
--- Add value to a channel (see |MiniColors-channels|).
--- Parameters ~
--- {channel} __colors_channel
--- {value} `(number)` Number to add (can be negative).
--- {opts} __colors_chan_opts
---                                           *MiniColors-colorscheme:chan_invert()*
--- Invert value in a channel (see |MiniColors-channels|).
--- - Most Oklab/Oklch inversions are not exactly invertible: applying it twice
---   might lead to slightly different colors depending on gamut clip method
---   (|MiniColors-gamut-clip|) like smaller chroma with default `'chroma'` method.
--- Parameters ~
--- {channel} __colors_channel
--- {opts} __colors_chan_opts
---                                           *MiniColors-colorscheme:chan_modify()*
--- Modify channel with a callable.
--- Parameters ~
--- {channel} __colors_channel
--- {f} `(function)` - callable which defines modification. Should take current
---   value of a channel and return a new one.
--- {opts} __colors_chan_opts
---                                         *MiniColors-colorscheme:chan_multiply()*
--- Multiply value of a channel (see |MiniColors-channels|).
--- Parameters ~
--- {channel} __colors_channel
--- {coef} `(number)` Number to multiply with (can be negative).
--- {opts} __colors_chan_opts
---                                            *MiniColors-colorscheme:chan_repel()*
--- Repel from certain sources.
--- Given an array of repel centers (`sources`) and repel degree (`coef`) add to
--- current channel value some amount ("nudge") with the following properties:
--- - Nudges from several sources are added together.
--- - Nudge is directly proportional to `coef`: bigger `coef` means bigger nudge.
--- - Nudge is inversely proportional to the distance between current value and
---   source: for positive `coef` bigger distance means smaller nudge, i.e.
---   repel effect weakens with distance.
--- - With positive `coef` nudges close to source are computed in a way to remove
---   whole `[source - coef; source + coef]` range.
--- - Negative `coef` results into attraction to source. Nudges in
---   `[source - coef; source + coef]` range are computed to completely collapse it
---   into `source`.
--- Examples: >lua
---   -- Repel hue from red color removing hue in range from 20 to 40
---   chan_repel('hue', 30, 10)
---   -- Attract hue to red color collapsing [20; 40] range into 30.
---   chan_repel('hue', 30, -10)
--- Parameters ~
--- {channel} __colors_channel
--- {sources} `(table|number)` Single or multiple source from which to repel.
--- {coef} `(number)` Repel degree (can be negative to attract).
--- {opts} __colors_chan_opts
---       
10BC8
                                       *MiniColors-colorscheme:chan_set()*
--- Set channel to certain value(s). This can be used to ensure that channel has
--- value(s) only within supplied set. If more than one is supplied, closest
--- element to current value is used.
--- Parameters ~
--- {channel} __colors_channel
--- {values} `(table|number)` Single or multiple values to set.
--- {opts} __colors_chan_opts
---                                          *MiniColors-colorscheme:color_modify()*
--- Modify all colors with a callable. It should return new color value (hex
--- string or `nil` to remove attribute) base on the following input:
--- - Current color as hex string.
--- - Data about the color: a table with fields:
---     - <attr> - one of `'fg'`, `'bg'`, `'sp'`, and `'term'` for terminal color.
---     - <name> - name of color source. Either a name of highlight group or
---       string of the form `terminal_color_x` for terminal color (as in
---       |terminal-config|).
--- Example: >lua
---   -- Set to '#dd2222' all foreground colors for groups starting with "N"
---   color_modify(function(hex, data)
---     if data.attr == 'fg' and data.name:find('^N') then
---       return '#dd2222'
---     end
---     return hex
--- Parameters ~
--- {f} `(function)` Callable returning new color value.
---                                              *MiniColors-colorscheme:compress()*
--- Remove redundant highlight groups. These are one of the two kinds:
--- - Having values identical to ones after |:hi-clear| (meaning they usually
---   don't add new information).
--- - Coming from a curated list of plugins with highlight groups usually not
---   worth keeping around. Current list of such plugins:
---     - 'nvim-tree/nvim-web-devicons'
---     - 'norcalli/nvim-colorizer.lua'
--- This method is useful to reduce size of color scheme before writing into
--- the file with |MiniColors-colorscheme:write()|.
--- Parameters ~
--- {opts} `(table|nil)` Options. Possible fields:
---   - <plugins> `(boolean)` - whether to remove highlight groups from a curated
---     list of plugins. Default: `true`.
---                                           *MiniColors-colorscheme:get_palette()*
--- Get commonly used colors. This basically counts number of all color
--- occurrences and filter out rare ones.
--- It is usually a good idea to apply both |MiniColors-colorscheme:compress()|
--- and |MiniColors-colorscheme:resolve_links()| before applying this.
--- Parameters ~
--- {opts} `(table|nil)` Options. Possible fields:
---   - <threshold> `(number)` - relative threshold for groups to keep. A group
---     is not included in output if it has less than this many occurrences
---     relative to a total number of colors. Default: 0.01.
---                                         *MiniColors-colorscheme:resolve_links()*
--- Resolve links (|:highlight-link|). This makes all highlight groups with `link`
--- attribute have data from a linked one.
--- - Resolves nested links.
--- - If some group is linked to a group missing in current colorscheme object,
---   it is not resolved.
---                                          *MiniColors-colorscheme:simulate_cvd()*
--- Simulate color vision deficiency (CVD, color blindness). This is basically
--- a wrapper using |MiniColors.simulate_cvd()| as a part of
--- call to |MiniColors-colorscheme:color_modify()| method.
--- Parameters ~
--- {cvd_type} `(string)` One of `'protan'`, `'deutan'`, `'tritan'`, `'mono'`.
--- {severity} `(number|nil)` Severity of CVD, number between 0 and 1. Default: 1.
---                                                 *MiniColors-colorscheme:write()*
--- Write color scheme to a file. It will be a Lua script readily usable as
--- a regular color scheme. Useful to both save results of color scheme tweaking
--- and making local snapshot of some other color scheme.
--- Sourcing this file on startup usually leads to a better performance that
--- sourcing initial color scheme, as it is essentially a conditioned
--- |:hi-clear| call followed by a series of |nvim_set_hl()| calls.
--- Default writing location is a "colors" directory of your Neovim config
--- directory (see |base-directories|). After writing, it should be available
--- for sourcing with |:colorscheme| or |:Colorscheme|.
--- Name of the file by default is taken from `name` field (`'mini_colors'` is
--- used if it is `nil`). If color scheme with this name already exists, it
--- appends prefix based on current time to make it unique.
--- - If colors were updated, it is usually a good idea to infer cterm attributes
---   with |MiniColors-colorscheme:add_cterm_attributes()| prior to writing.
--- Parameters ~
--- {opts} `(table|nil)` Options. Possible fields:
---   - <compress> `(boolean)` - whether to call |MiniColors-colorscheme:compress()|
---     prior to writing. Default: `true`.
---   - <name> `(string|nil)` - basename of written file. Default: `nil` to infer
---     from `name` field.
---   - <directory> `(string)` - directory to where file should be saved.
---     Default: "colors" subdirectory of Neovim home config (`stdpath("config")`).
---@tag MiniColors-colorscheme
---@diagnostic disable:undefined-field
---@diagnostic disable:discard-returns
---@diagnostic disable:unused-local
-- Module definition ==========================================================
local MiniColors = {}
local H = {}
--- Module setup
---                                                                   *:Colorscheme*
--- Calling this function creates a `:Colorscheme` user command. It takes one or
--- more registered color scheme names and performs animated transition between
--- them (starting from currently active color scheme).
--- It uses |MiniColors.animte()| with default options.
---@param config table|nil Module config table. See |MiniColors.config|.
---@usage >lua
---   require('mini.colors').setup() -- use default config
---   -- OR
---   require('mini.colors').setup({}) -- replace {} with your config table
MiniColors.setup = function(config)
  -- Export module
  _G.MiniColors = MiniColors
  -- Setup config
  config = H.setup_config(config)
  -- Apply config
  H.apply_config(config)
  -- Create user commands
  H.create_user_commands()
--- Module config
--- Default values:
---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
MiniColors.config = {}
--minidoc_afterlines_end
--- Create colorscheme object
---@param x table Table to be transformed into |MiniColors-colorscheme| object.
---@return table Copy of `x` transformed into a colorscheme object.
MiniColors.as_colorscheme = function(x)
  -- Validate input
  if not H.is_table(x) then H.error('Input of `as_colorscheme()` should be table.') end
  if x.groups ~= nil then
    if not H.is_table(x.groups) then H.error('Field `groups` of colorscheme should be table or nil.') end
    if not H.all(x.groups, H.is_table) then H.error('All elements of `groups` colorscheme field should be tables.') end
  if x.terminal ~= nil then
    if not H.is_table(x.terminal) then H.error('Field `terminal` of colorscheme should be table or nil.') end
    if not H.all(x.terminal, H.is_string) then
      H.error('All elements of `terminal` colorscheme field should be strings.')
  -- Create a proper copy
  local res = vim.deepcopy(x)
  -- - Ensure that tables for highlight groups are independent (can not be the
  --   case if some point to literally the same table)
  if H.is_table(res.groups) then
    for key, val in pairs(res.groups) do
      res.groups[key] = vim.deepcopy(val)
  -- Fields
  res.groups = res.groups or {}
  res.name = res.name
  res.terminal = res.terminal or {}
  -- Methods
  res.add_cterm_attributes = H.cs_add_cterm_attributes
  res.add_terminal_colors = H.cs_add_terminal_colors
  res.add_transparency = H.cs_add_transparency
  res.apply = H.cs_apply
  res.chan_add = H.cs_chan_add
  res.chan_invert = H.cs_chan_invert
  res.chan_modify = H.cs_chan_modify
  res.chan_multiply = H.cs_chan_multiply
  res.chan_repel = H.cs_chan_repel
  res.chan_set = H.cs_chan_set
  res.color_modify = H.cs_color_modify
  res.compress = H.cs_compress
  res.get_palette = H.cs_get_palette
  res.resolve_links = H.cs_resolve_links
  res.simulate_cvd = H.cs_simulate_cvd
  res.write = H.cs_write
  return res
--- Get colorscheme object from registered color scheme
---@param name string|nil Name of color scheme to use. If `nil` (default) creates
---  colorscheme object based on currently active data (|g:colors_name|,
---  highlight groups, terminal colors). If string, converts color scheme with
---  that name to a colorscheme object.
---@param opts table|nil Options. Possible fields:
---   - <new_name> `(string|nil)` - new name of colorscheme object.
---@return table Colorscheme object |(MiniColors-colorscheme|).
MiniColors.get_colorscheme = function(name, opts)
  if not (name == nil or type(name) == 'string') then H.error('Argument `name` should be string or `nil`.') end
  opts = vim.tbl_deep_extend('force', { new_name = nil }, opts or {})
  -- Return current color scheme if no `name` is supplied
  if name == nil then
    return MiniColors.as_colorscheme({
      name = opts.new_name or vim.g.colors_name,
      groups = H.get_current_groups(),
      terminal = H.get_current_terminal(),
  -- Source supplied color scheme, collect it and return back
  local current_cs = MiniColors.get_colorscheme()
  local res, au_id
  au_id = vim.api.nvim_create_autocmd('ColorScheme', {
    callback = function()
      res = MiniColors.get_colorscheme(nil, opts)
      -- Apply right now to avoid flickering
      current_cs:apply()
      -- Explicitly delete autocommand to account for error in `:colorscheme`
      vim.api.nvim_del_autocmd(au_id)
  local ok, _ = pcall(vim.cmd, 'colorscheme ' .. name)
  if not ok then H.error(string.format('No color scheme named "%s".', name)) end
  return res
--- Start interactive experiments
--- Create a special buffer in which user can write plain Lua code to tweak
--- color scheme and apply to get visual feedback.
--- General principles ~
--- - Initial colorscheme object is fixed to interactive buffer on its creation.
--- - There are special buffer convenience mappings:
---     - Apply (source) current buffer content.
---     - Reset color scheme (make initial colorscheme the current one).
---     - Write to a file the result of applying current buffer content.
---       This sources current content and calls |MiniColors-colorscheme:write()|.
---     - Quit interactive buffer.
--- - User is expected to iteratively tweak color scheme by writing general Lua
---   code in interactive buffer and applying it using convenience mapping.
--- - Application of interactive buffer is essentially these steps:
---     - Expose `self` as initial colorscheme object on any application.
---       It is always the same for every application.
---     - Expose initial colorscheme methods as standalone functions. So instead
---       of writing `self = self:add_transparency()` user can only write
---       `add_transparency()`.
---     - Source buffer content as plain Lua code.
--- Example of interactive buffer content: >lua
---   chan_modify('hue', function() return math.random(0, 359) end)
---   simulate_cvd('protan')
---   add_cterm_attributes()
---   add_terminal_colors()
---@param opts table|nil Options. Possible fields:
---   - <colorscheme> `(table|nil)` - |MiniColors-colorscheme| object to be
---     used as initial colorscheme for executed code. By default uses current
---     color scheme.
---   - <mappings> `table` - buffer mappings for actions. Possible fields:
---       - <Apply> `(string)` - apply buffer code. Default: `'<M-a>'`.
---       - <Reset> `(string)` - apply initial color scheme as is. Default: `'<M-r>'`.
---       - <Quit> `(string)` - close interactive buffer. Default: `'<M-q>'`.
---       - <Write> `(string)` - write result of buffer code into a file.
---         Prompts for file name with |vim.ui.input()| and then
---         uses |MiniColors-colorscheme:write()| with other options being default.
---         Default: `'<M-w>'`.
MiniColors.interactive = function(opts)
  opts = vim.tbl_deep_extend(
    'force',
    { colorscheme = nil, mappings = { Apply = '<M-a>', Reset = '<M-r>', Quit = '<M-q>', Write = '<M-w>' } },
    opts or {}
  local maps = opts.mappings
  -- Prepare
  local init_cs = opts.colorscheme == nil and MiniColors.get_colorscheme()
    or MiniColors.as_colorscheme(opts.colorscheme)
  local buf_id = vim.api.nvim_create_buf(true, true)
  -- Write header lines
  local header_lines = {
    [[-- Experiment with color scheme using 'mini.colors']],
    '-- Treat this as regular Lua file',
    '-- Methods of initial color scheme can be called directly',
    '-- See more in `:h MiniColors.interactive()`',
    '-- Initial color scheme: ' .. (init_cs.name or '<unnamed>'),
    '-- Buffer-local mappings (Normal mode):',
    '--   Apply: ' .. maps.Apply,
    '--   Reset: ' .. maps.Reset,
    '--   Quit:  ' .. maps.Quit,
    '--   Write: ' .. maps.Write,
    '-- Examples:',
    '-- Invert dark/light color scheme to be light/dark',
    "-- chan_invert('lightness', { gamut_clip = 'cusp' })",
    '-- Make foreground text more saturated',
    "-- chan_add('saturation', 20,  { filter = 'fg' })",
  vim.api.nvim_buf_set_lines(buf_id, 0, -1, true, header_lines)
  -- Make local mappings
  local m = function(action, rhs) vim.keymap.set('n', maps[action], rhs, { desc = action, buffer = buf_id }) end
  m('Apply', function()
    local new_cs = H.apply_interactive_buffer(buf_id, init_cs)
    new_cs:apply()
  m('Reset', function() init_cs:apply() end)
  m('Quit', function()
    local ok, bufremove = pcall(require, 'mini.bufremove')
    if ok then
      bufremove.wipeout(buf_id, true)
      vim.api.nvim_buf_delete(buf_id, { force = true })
  m('Write', function()
    vim.ui.input(
      { prompt = [[Write to 'colors/' of your config under this name: ]], default = init_cs.name },
      function(input)
        if input == nil then return end
        local new_cs = H.apply_interactive_buffer(buf_id, init_cs)
        new_cs.name = input
        new_cs:write({ name = input })
  -- Set local options
  vim.bo[buf_id].filetype = 'lua'
  -- Make current
  vim.api.nvim_set_current_buf(buf_id)
  vim.api.nvim_win_set_cursor(0, { vim.api.nvim_buf_line_count(buf_id), 0 })
--- Animate color scheme change
--- Start from currently active color scheme and loop through `cs_array`.
--- Powers |:Colorscheme| user command created in |MiniColors.setup()|.
---@param cs_array `(table)` Array of |MiniColors-colorscheme| objects.
---@param opts table|nil Options. Possible fields:
---   - <transition_steps> `(number)` - number of intermediate steps to show
---     during transition between two color schemes. Bigger values result in
---     smoother visual feedback but require more computational power.
---     Default: 25.
---   - <transition_duration> `(number)` - number of milliseconds to spend
---     showing transition. Default: 1000.
---   - <show_duration> `(number)` - number of milliseconds to show intermediate
---     color schemes (all but last in `cs_array`). Default: 1000.
MiniColors.animate = function(cs_array, opts)
  if not (H.islist(cs_array) and H.all(cs_array, H.is_colorscheme)) then
    H.error('Argument `cs_array` should be an array of color schemes.')
  opts = vim.tbl_deep_extend(
    'force',
    { transition_steps = 25, transition_duration = 1000, show_duration = 1000 },
    opts or {}
  if #cs_array == 0 then return end
  -- Pre-compute common data
  local cs_oklab = vim.tbl_map(function(cs) return H.cs_hex_to_oklab(vim.deepcopy(cs)) end, cs_array)
  local cs_oklab_current = H.cs_hex_to_oklab(MiniColors.get_colorscheme())
  -- Make "chain after action" which animates transitions one by one
  local cs_id, after_action = 1, nil
  after_action = function(data)
    -- Ensure authentic color scheme is active
    cs_array[cs_id]:apply()
    -- Advance if possible
    cs_id = cs_id + 1
    if #cs_array < cs_id then return end
    -- Wait before starting another animation
    local callback = function() H.animate_single_transition(cs_oklab[cs_id - 1], cs_oklab[cs_id], after_action, opts) end
    vim.defer_fn(callback, opts.show_duration)
  H.animate_single_transition(cs_oklab_current, cs_oklab[1], after_action, opts)
--- Convert between color spaces
--- For a list of supported colors spaces see |MiniColors-color-spaces|.
---@param x table|string|number|nil Color to convert from. Its color space is
---   inferred automatically.
---@param to_space string Id of allowed color space.
---@param opts table|nil Options. Possible fields:
---   - <gamut_clip> `(string)` - method for |MiniColors-gamut-clip|.
---     Default: `'chroma'`.
---@return table|string|number|nil Color in space `to_space` or `nil` if input is `nil`.
MiniColors.convert = function(x, to_space, opts)
  if x == nil then return nil end
  if not vim.tbl_contains(H.allowed_spaces, to_space) then
    local spaces = table.concat(vim.tbl_map(vim.inspect, H.allowed_spaces), ', ')
    H.error('Argument `to_space` should be one of ' .. spaces .. '.')
  opts = vim.tbl_deep_extend('force', { gamut_clip = 'chroma' }, opts or {})
  return H.converters[to_space](x, H.infer_color_space(x), opts)
--- Modify channel
---@param x table|string|number|nil Color which channel will be modified. Color
---   space is inferred automatically.
---@param channel string One of supported |MiniColors-channels|.
---@param f function Callable which defines modification. Should take current
---   value of a channel and return a new one.
---@param opts table|nil Options. Possible fields:
---   - <gamut_clip> `(string)` - method for |MiniColors-gamut-clip|.
---     Default: `'chroma'`.
---@return string|nil Hex string of color with modified channel or `nil` if input is `nil`.
MiniColors.modify_channel = function(x, channel, f, opts)
  channel = H.normalize_channel(channel)
  f = H.normalize_f(f)
  opts = vim.tbl_deep_extend('force', { gamut_clip = 'chroma' }, opts or {})
  local modify_channel = H.channel_modifiers[channel]
  return modify_channel(x, f, opts.gamut_clip)
--- Simulate color vision deficiency
---@param x table|string|number|nil Color to convert from. Its color space is
---   inferred automatically.
---@param cvd_type string Type of CVD. One of `'protan'`, `'deutan'`,
---`'tritan'`, or `'mono'` (equivalent to converting to graysacle).
---@param severity number|nil Severity of CVD. A number between 0 and 1 (default).
---@return string|nil Hex string of simulated color or `nil` if input is `nil`.
MiniColors.simulate_cvd = function(x, cvd_type, severity)
  if x == nil then return nil end
  if not (cvd_type == 'protan' or cvd_type == 'deutan' or cvd_type == 'tritan' or cvd_type == 'mono') then
    H.error('Argument `cvd_type` should be one of "protan", "deutan", "tritan", "mono".')
  severity = severity or 1
  if not H.is_number(severity) then H.error('Argument `severity` should be number.') end
  -- Simulate monochromacy by setting zero 'crhoma'
  if cvd_type == 'mono' then
    local lch = MiniColors.convert(x, 'oklch')
    lch.c, lch.h = 0, nil
    ---@diagnostic disable:return-type-mismatch
    return MiniColors.convert(lch, 'hex')

View remainder of file in raw view

FilesExpand file tree

colors.lua

Latest commit

History

colors.lua

File metadata and controls