ccc.txt

*ccc.txt*					Create Color Code in neovim.

==============================================================================
Contents                                                          *ccc-contents*


Introduction						|ccc-introduction|
Setup							|ccc-setup|
Option							|ccc-option|
Command							|ccc-command|
Key mapping						|ccc-key-mapping|
Variable						|ccc-variable|
Autocmd							|ccc-autocmd|
Action							|ccc-action|



==============================================================================
Introduction                                                  *ccc-introduction*


Use the colorful sliders to easily generate any desired color!

Features:
- No dependency.
- Dynamic highlighting of sliders.
- Supports more than 10 color spaces (RGB, HSL, CMYK, etc.).
- Seamless input/output mode change.
- Restore previously used colors.
- Transparent slider for css functions (e.g. `rgb()`, `hsl()`)
- Color Highlighter for many formats.
- Programmable modules (input/output/picker)

Requirements:
- Neovim 0.9.0+



==============================================================================
Setup                                                                *ccc-setup*


Enable |'termguicolors'| and call `require("ccc").setup()`.
See |ccc-options| for the options that can be used.
>lua
	-- Enable true color
	vim.opt.termguicolors = true

	local ccc = require("ccc")
	local mapping = ccc.mapping

	ccc.setup({
	  -- Your preferred settings
	  -- Example: enable highlighter
	  highlighter = {
	    auto_enable = true,
	    lsp = true,
	  },
	})
<



==============================================================================
Options                                                            *ccc-options*


                                                      *ccc-option-default-color*
default_color ~
string
Default: "#000000"
	The default color used when a color cannot be picked. It must be HEX
	format. See also |ccc-option-preserve|.


                                                           *ccc-option-bar-char*
bar_char ~
string
Default: "█"
	The character used for the sliders.


                                                         *ccc-option-point-char*
point_char ~
string
Default: "◊"
	The character used for the cursor point on the sliders.


                                                        *ccc-option-point-color*
point_color ~
string
Default: ""
	The color of the cursor point on the sliders. It must be HEX format.
	If it is empty string (""), like the other part of the sliders, it is
	dynamically highlighted.


                                                     *ccc-option-empty-point-bg*
empty_point_bg ~
boolean
Default: true
	Determine whether to display background of the points on the sliders.
	If it is false, the background color will be the color where the point
	steps on, which will make the bar look continuous.


                                                *ccc-option-point-color-on-dark*
point_color_on_dark ~
string
Default: "#ffffff"
	The color of the cursor point on the sliders when the background color
	is dark. It must be HEX format. If point_color is not empty, this
	value will be overridden.


                                               *ccc-option-point-color-on-light*
point_color_on_light ~
string
Default: "#000000"
	The color of the cursor point on the sliders when the background color
	is light. It must be HEX format. If point_color is not empty, this
	value will be overridden.


                                                            *ccc-option-bar-len*
bar_len ~
integer
Default: 30
	The length of the slider (not byte length). This value number of
	bar_chars form a slider.


                                                           *ccc-option-win-opts*
win_opts ~
table
Default: {
	relative = "cursor",
	row = 1,
	col = 1,
	style = "minimal",
	border = "rounded",
}
	The options passed to the |nvim_open_win|. 'width' and 'height' cannot
	be specified.


                                                         *ccc-option-auto-close*
auto_close ~
boolean
Default: true
	If true, then leaving the ccc UI will automatically close the window.


                                                           *ccc-option-preserve*
preserve ~
boolean
Default: false
	Whether to preserve the colors when the UI is closed. If this is true,
	you can start where you left off last time.


                                                       *ccc-option-save-on-quit*
save_on_quit ~
boolean
Default: false
	Whether to add colors to prev_colors when quit (|ccc-action-quit|).


                                                         *ccc-option-alpha-show*
alpha_show ~
"auto" | "show" | "hide"
Default: "auto"
	This option determines whether the alpha slider is displayed when the
	UI is opened. "show" and "hide" mean as they are. "auto" makes the
	slider appear only when the alpha value can be picked up.


                                                             *ccc-option-inputs*
inputs ~
table
Default: {
	ccc.input.rgb,
	ccc.input.hsl,
	ccc.input.cmyk,
}
	List of color system to be activated. |ccc-action-toggle_input_mode|
	toggles in this order. The first one is the default used at the first
	startup. Once activated, it will keep the previous input mode.
	The presets currently available are as follows:
		- RGB    ccc.input.rgb
		- HSL    ccc.input.hsl
		- HWB    ccc.input.hwb
		- Lab    ccc.input.lab
		- LCH    ccc.input.lch
		- OKLab  ccc.input.oklab
		- OKLCH  ccc.input.oklch
		- CMYK   ccc.input.cmyk
		- HSLuv  ccc.input.hsluv
		- OKHSL  ccc.input.okhsl
		- HSV    ccc.input.hsv
		- OKHSV  ccc.input.okhsv
		- XYZ    ccc.input.xyz


                                                            *ccc-option-outputs*
outputs ~
table
Default: {
	ccc.output.hex,
	ccc.output.hex_short,
	ccc.output.css_rgb,
	ccc.output.css_hsl,
}
	List of output format to be activated. |ccc-action-toggle_ouotput_mode|
	toggles in this order. The first one is the default used at the first
	startup. Once activated, it will keep the previous output mode.
	The presets currently available are as follows:
		- HEX (6/8 digits)  ccc.output.hex
		      (3/4 digits)  ccc.output.hex_short
		- CssRGB            ccc.output.css_rgb
		- CssHSL            ccc.output.css_hsl
		- CssHWB            ccc.output.css_hwb
		- CssLab            ccc.output.css_lab
		- CssLCH            ccc.output.css_lch
		- CssOKLab          ccc.output.css_oklab
		- CssOKLCH          ccc.output.css_oklch
		- Float             ccc.output.float

	ccc.output.hex and ccc.output.hex_short use lowercase (e.g. #ffffff)
	by default, but can be set to use uppercase letters.
>lua
	ccc.output.hex.setup({ uppercase = true })
	ccc.output.hex_short.setup({ uppercase = true })
<


                                                            *ccc-option-pickers*
pickers ~
table
Default: {
	ccc.picker.hex,
	ccc.picker.css_rgb,
	ccc.picker.css_hsl,
	ccc.picker.css_hwb,
	ccc.picker.css_lab,
	ccc.picker.css_lch,
	ccc.picker.css_oklab,
	ccc.picker.css_oklch,
}
	List of formats that can be detected by |:CccPick| to be activated.
	The presets currently available are as follows:
		- HEX       ccc.picker.hex
		            ccc.picker.hex_long (#RRGGBB, #RRGGBBAA)
		            ccc.picker.hex_short (#RGB, #RGBA)
		- CssRGB    ccc.picker.css_rgb
		- CssHSL    ccc.picker.css_hsl
		- CssHWB    ccc.picker.css_hwb
		- CssLab    ccc.picker.css_lab,
		- CssLCH    ccc.picker.css_lch,
		- CssOKLab  ccc.picker.css_oklab,
		- CssOKLCH  ccc.picker.css_oklch,
		- CssName   ccc.picker.css_name
		- Defaults  ccc.picker.defaults (Neovim default colorscheme)
	Css* conforms to CSS Color Module Level 4.
	https://www.w3.org/TR/css-color-4/


					     *ccc-option-pickers-custom_entries*
	There is a special picker named `ccc.picker.custom_entries`. You can
	define a table to convert from any word to a specific RGB color.
>lua
	ccc.setup({
	  pickers = {
	    ccc.picker.custom_entries({
	      red = "#ff0000",
	      green = "#00ff00",
	    }),
	  },
	})
<
	This makes it highlight words both `red` and `green` to supplied RGB
	colors. Also you can use them in |:CccPick|.

	It detects word boundaries not to highlight words including supplied
	characters. So it does not highlight `red` in `Alfred`. This is achieved
	by Vim's |/\<| and |/\>| patterns, so it is affected by |'iskeyword'|.

	You cannot use any special character for RegExp patterns. When you use
	them such as `%`, `[]`, and `^$`, it detects the characters as they are.


					*ccc-option-pickers-trailing_whitespace*
	There is a special picker named `ccc.picker.trailing_whitespace`. As
	the name suggests, it picks trailing white spaces.
	NOTE: This picker is only used for highlights. The reason is to pick
	is meaningless.
>lua
	ccc.setup({
	  pickers = {
	    ccc.picker.trailing_whitespace({
	      ---@type table<string, string>
	      --- Keys are filetypes, values are colors (6-digit hex)
	      palette = {},
	      ---@type string
	      --- Default color. 6-digit hex representation.
	      default_color = "#db7093",
	      ---@type string[]|true
	      --- List of filetypes for which highlighting is enabled or true.
	      enable = true,
	      ---@type string[]|fun(bufnr: number): boolean
	      --- Used only when enable is true. List of filetypes to disable
	      --- highlighting or a function that returns true when you want
	      --- to disable it.
	      disable = {},
	    }),
	  },
	})
<


						*ccc-option-pickers-ansi_escape*
	There is a special picker named `ccc.picker.ansi_escape`. You can
	define colors corresponding to ANSI escape code (16 colors).
	Note: This picker is only used for highlights. The reason is that
	foreground and background colors can be set at the same time, and the
	color to be picked cannot be determined.
>lua
	ccc.setup({
	  pickers = {
	    ccc.picker.ansi_escape({
	      foreground = "#cccccc",
	      background = "#0c0c0c",
	      black = "#0c0c0c",
	      red = "#c50f1f",
	      green = "#13a10e",
	      yellow = "#c19c00",
	      blue = "#0037da",
	      magenta = "#881798",
	      cyan = "#3a96dd",
	      white = "#cccccc",
	      bright_black = "#767676",
	      bright_red = "#e74856",
	      bright_green = "#16c60c",
	      bright_yellow = "#f9f1a5",
	      bright_blue = "#3b78ff",
	      bright_magenta = "#b4009e",
	      bright_cyan = "#61d6d6",
	      bright_white = "#f2f2f2",
	    }, {
	      -- `\e[31;1m` means whether `red + bold` or `bright red`.
	      ---@type "bold"|"bright" Meaning of code 1. default: "bright"
	      meaning1 = "bright",
	    })
	  }
	})
<


                                                        *ccc-option-output-line*
output_line ~
function
Default: ccc.output_line
	This function is used to create a row below the slider that displays
	the colors before and after the change. See source code for details.


                                                     *ccc-option-highlight-mode*
highlight_mode ~
"fg" | "bg" | "foreground" | "background" | "virtual"
Default: "bg"
	Option to highlight text foreground or background. It is used to
	output_line and highlighter.
	If "virtual", use colored virtual texts.


                                                     *ccc-option-virtual_symbol*
virtual_symbol ~
string
Default: " ● "
	When |ccc-options-highlight_mode| is "virtual", this option controls
	the text of the virt_text.


                                                        *ccc-option-virtual_pos*
virtual_pos ~
"inline-left" | "inline-right" | "eol"
Default: "inline-left"
	When |ccc-options-highlight_mode| is "virtual", this option controls
	where to put it out. You can choose whether to put the color inline on
	the left or right side of the color, or at the end of the line.


                                                                *ccc-option-lsp*
lsp ~
boolean
Default: true
	Whether to enable nvim-lsp support. The color information is updated
	in the background and the result is used by |:CccPick| and
	highlighter.


                                                        *ccc-option-highlighter*
highlighter ~
table
	These are settings for CccHighlighter.


                                            *ccc-option-highlighter-auto_enable*
highlighter.auto_enable ~
boolean
Default: false
	Whether to enable automatically on BufEnter.


                                               *ccc-option-highlighter-max_byte*
highlighter.max_byte ~
integer
Default: 100 * 1024 (100 KB)
	The maximum buffer size for which highlight is enabled by
	|ccc-option-highlighter-auto-enable|.


                                              *ccc-option-highlighter-filetypes*
highlighter.filetypes ~
string[]
Default: {}
	File types for which highlighting is enabled. It is only used for
	automatic highlighting by |ccc-option-highlighter-auto-enable|, and is
	ignored for manual activation. An empty table means all file types.


                                               *ccc-option-highlighter-excludes*
highlighter.excludes ~
string[]
Default: {}
	Used only when |ccc-option-highlighter-filetypes| is empty table. You
	can specify file types to be excludes.


                                                    *ccc-option-highlighter-lsp*
highlighter.lsp ~
boolean
Default: true
	If true, highlight using nvim-lsp. If LS with the color provider is
	not attached to a buffer, it falls back to highlight with pickers.
	See also |ccc-option-lsp|.


                                          *ccc-option-highlighter-update_insert*
highlighter.update_insert ~
boolean
Default: true
	If true, highlights will be updated during insert mode. If false,
	highlights will not be updated during editing in insert mode , but
	will be updated on |InsertLeave|.


                                                            *ccc-option-convert*
convert ~
table
Default: {
	{ ccc.picker.hex, ccc.output.css_rgb },
	{ ccc.picker.css_rgb, ccc.output.css_hsl },
	{ ccc.picker.css_hsl, ccc.output.hex },
}
	Specify the correspondence between picker and output. The default
	setting converts the color to css_rgb if it is in hex format, to
	css_hsl if it is in css_rgb format, and to hex if it is in css_hsl
	format.


                                                          *ccc-option-recognize*
recognize ~
table
	These are settings for recognize color format.


                                                    *ccc-option-recognize-input*
recognize.input ~
boolean
Default: false
	If true, doing |:CccPick|, it recognizes the color format and
	automatically adjusts the input to it. If that format is not
	registered in |ccc-option-inputs|, it will fall back to the first one.


                                                   *ccc-option-recognize-output*
recognize.output ~
boolean
Default: false
	If true, doing |:CccPick|, it recognizes the color format and
	automatically adjusts the output to it. If that format is not
	registered in |ccc-option-outputs|, it will fall back to the first one.


                                                  *ccc-option-recognize-pattern*
recognize.pattern ~
table
Default: {
	[picker.css_rgb]   = { input.rgb,   output.rgb       },
	[picker.css_name]  = { input.rgb,   output.rgb       },
	[picker.hex]       = { input.rgb,   output.hex       },
	[picker.css_hsl]   = { input.hsl,   output.css_hsl   },
	[picker.css_hwb]   = { input.hwb,   output.css_hwb   },
	[picker.css_lab]   = { input.lab,   output.css_lab   },
	[picker.css_lch]   = { input.lch,   output.css_lch   },
	[picker.css_oklab] = { input.oklab, output.css_oklab },
	[picker.css_oklch] = { input.oklch, output.css_oklch },
}
	Define the correspondence between the picker and input, output.


                                           *ccc-option-disable-default-mappings*
disable_default_mappings ~
boolean
Default: false
	If true, all default mappings are disabled.


                                                           *ccc-option-mappings*
mappings ~
table
Default: See |ccc-action|
	The mappings are set in the UI of ccc. The table where lhs is key and
	rhs is value. To disable all default mappings, use
	|ccc-option-disable-default-mappings|. To disable only some of the
	default mappings, set ccc.mapping.none.
>lua
	local ccc = require("ccc")
	local mapping = ccc.mapping

	ccc.setup({
	  -- Disable all default mappings
	  -- disable_default_mappings = true
	  mappings = {
	    -- Disable only 'q' (|ccc-action-quit|)
	    q = mapping.none
	  }
	})
<



==============================================================================
Command                                                            *ccc-command*


                                                                      *:CccPick*
:CccPick
	Detects and replaces the color under the cursor. Detectable formats
	are defined in |ccc-option-pickers|. If nothing is detected, the color
	is inserted at a cursor position.


                                                                   *:CccConvert*
:CccConvert
	Convert color formats directly without opening the UI. The conversion
	rules are specified in |ccc-option-convert|.


                                                         *:CccHighlighterEnable*
:CccHighlighterEnable [{bufnr}]
	Highlight colors in the buffer {bufnr}. If {bufnr} is omitted, the
	target is the current buffer. The colors to be highlighted are those
	returned by textDocument/documentColor request or those registered in
	|ccc-option-pickers|.
	Highlight is managed on a buffer-by-buffer basis, so you must use this
	command each time to enable highlight on a new buffer. You can use
	|ccc-option-highlighter-auto-enable| to enable automatically on
	|BufEnter|.
	The following options are available.
		|ccc-option-highlighter-auto-enable|
		|ccc-option-highlighter-filetypes|
		|ccc-option-highlighter-excludes|
		|ccc-option-highlighter-lsp|


                                                        *:CccHighlighterDisable*
:CccHighlighterDisable [{bufnr}]
	Disable highlight.


                                                         *:CccHighlighterToggle*
:CccHighlighterToggle [{bufnr}]
	Toggle highlight.



==============================================================================
Key mapping                                                    *ccc-key-mapping*


                                                            *<Plug>(ccc-insert)*
<Plug>(ccc-insert) ~
	Defined in |Insert-mode|. Insert the color without detection.

						      *<Plug>(ccc-select-color)*
<Plug>(ccc-select-color)
	Defined in |Visual-mode| and |Operator-pending-mode|. Select the color
	under the cursor.


==============================================================================
Variable                                                          *ccc-variable*


                                                                   *g:ccc_color*
g:ccc_color ~
	The color currently being edited is stored in HEX format. If the ccc
	UI is not open, it is empty string ("").



==============================================================================
Autocmd                                                            *ccc-autocmd*


                                                               *CccColorChanged*
CccColorChanged ~
	After changing |g:ccc_color|.



==============================================================================
Highlight                                                        *ccc-highlight*


                                              *CccFloatNormal* *hl-CccFloatNormal*
CccFloatNormal ~
	The highlight for float window.


                                              *CccFloatBorder* *hl-CccFloatBorder*
CccFloatBorder ~
	The highlight for float window border.



==============================================================================
Action                                                              *ccc-action*


All actions are implemented as lua functions.
To customize, use |ccc-option-mappings|.
>lua
	local ccc = require("ccc")
	local mapping = ccc.mapping
<


                                                           *ccc-action-complete*
complete ~
mapping.complete()
Default mapping: <CR>
	Close the UI and perform a replace or insert.
	If open the previous colors palette, select the color under the cursor.


                                                               *ccc-action-quit*
quit ~
mapping.quit()
Default mapping: q
	Alias of |:quit|. Cancel and close the UI without replace or insert.


                                                   *ccc-action-cycle_input_mode*
cycle_input_mode ~
mapping.cycle_input_mode()
Default mapping: i
	Cycles input modes. See |ccc-option-inputs|.


                                                 *ccc-action-cycle_ouotput_mode*
cycle_output_mode ~
mapping.cycle_output_mode()
Default mapping: o
	Cycles output modes. See |ccc-option-outputs|.


							*ccc-action-reset_mode*
reset_mode ~
mapping.reset_mode()
Default mapping: r
	Reset input and output to default, and hide alpha slider and previous
	colors palette.


                                                       *ccc-action-toggle_alpha*
toggle_alpha ~
mapping.toggle_alpha()
Default mapping: a
	Toggle show/hide alpha (transparency) slider.


                                                 *ccc-action-toggle_prev_colors*
toggle_prev_colors ~
mapping.toggle_prev_colors()
Default mapping: g
	Toggle show and hide the previous colors palette.
	Use the following to move colors.
		- |ccc-action-goto-next|
		- |ccc-action-goto-prev|
		- |ccc-action-goto-tail|
		- |ccc-action-goto-head|


                                                   *ccc-action-show_prev_colors*
show_prev_colors ~
mapping.show_prev_colors()
Default mapping is nothing.
	Show the previous colors palette.


                                                   *ccc-action-hide_prev_colors*
hide_prev_colors ~
mapping.hide_prev_colors()
Default mapping is nothing.
	Hide the previous colors palette.


                                                          *ccc-action-goto-next*
goto_next ~
mapping.goto_next()
Default mapping: w
	Go to next (right) color.


                                                          *ccc-action-goto-prev*
goto_prev ~
mapping.goto_prev()
Default mapping: b
	Go to previous (left) color.


                                                          *ccc-action-goto-tail*
goto_tail ~
mapping.goto_tail()
Default mapping: W
	Go to the last color.


                                                          *ccc-action-goto-head*
goto_head ~
mapping.goto_head()
Default mapping: B
	Go to the first color.


                                      *ccc-action-increase* *ccc-action-increase1*
                                    *ccc-action-increase5* *ccc-action-increase10*
increase ~
mapping.increase1()
mapping.increase5()
mapping.increase10()
mapping.delta(intger)
Default mapping: l / d / , (1 / 5 / 10)
	Increase the value times delta of the slider.
	The delta is defined each color system, e.g. RGB is 1.


                                      *ccc-action-decrease* *ccc-action-decrease1*
                                    *ccc-action-decrease5* *ccc-action-decrease10*
decrease ~
mapping.decrease1()
mapping.decrease5()
mapping.decrease10()
mapping.delta(intger)
Default mapping: h / s / m (1 / 5 / 10)
	Decrease the value times delta of the slider.
	The delta is defined each color system, e.g. RGB is 1.


                                                *ccc-action-set* *ccc-action-set0*
	                                    *ccc-action-set50* *ccc-action-set100*
set ~
mapping.set0()
mapping.set50()
mapping.set100()
ccc.set_percent(integer)
Default mapping: H / M / L (0 / 50 / 100), 1 - 9 (10% - 90%)
	Set the value of the slider as a percentage.


vim:tw=78:ts=8:noet:ft=help:norl: