--- *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/).

---

--- Notes:

--- - 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 >

--- :lua MiniColors.get_colorscheme():<method goes here>:apply().

---

--- Recipes:

--- - Tweak lightness: >

---

--- -- 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: >

---

--- -- 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: >

---

--- -- 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: >

---

--- -- 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): >

---

--- 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): >

---

--- -- Repel red color

--- chan_repel('hue', 30, 45)

--- <

--- - Force equally spaced palette (remove ones with which you know you

--- have trouble): >

---

--- -- 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: >

---

--- chan_invert('temperature')

--- chan_invert('pressure')

--- <

--- - If all hope is lost, hue random generation might help if you are lucky: >

---

--- 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 roughly triangular 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'`.

---

--- Notes:

--- - 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()|: >

---

--- 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()|: >

---

--- -- 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: >

---

--- -- 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|).

---

--- Notes:

--- - 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: >

---

--- -- 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

---

--- *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: >

---

--- -- 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

--- end)

---

--- 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.

---

--- Notes:

--- - 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.

---

--- Notes:

--- - 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 `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 command

vim.api.nvim_create_user_command('Colorscheme', function(input)

local cs_array = vim.tbl_map(MiniColors.get_colorscheme, input.fargs)

MiniColors.animate(cs_array)

end, { nargs = '+', complete = 'color' })

end

--- 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

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.')

end

end

-- 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)

end

end

-- 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

end

--- 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(),

})

end

-- 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)

end,

})

local ok, _ = pcall(vim.cmd, 'colorscheme ' .. name)

if not ok then H.error(string.format('No color scheme named "%s".', name)) end

return res

end

--- 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: >

---

--- 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()

end)

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)

else

vim.api.nvim_buf_delete(buf_id, { force = true })

end

end)

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 })

end

)

end)

-- 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 })

end

--- 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 (vim.tbl_islist(cs_array) and H.all(cs_array, H.is_colorscheme)) then

H.error('Argument `cs_array` should be an array of color schemes.')

end

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)

end

H.animate_single_transition(cs_oklab_current, cs_oklab[1], after_action, opts)

end

--- 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 .. '.')

end

opts = vim.tbl_deep_extend('force', { gamut_clip = 'chroma' }, opts or {})

return H.converters[to_space](x, H.infer_color_space(x), opts)

end

--- 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)

end

--- 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".')

end

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')