colour

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 31, 2025 License: MIT Imports: 4 Imported by: 2

Documentation

Overview

Package colour provides public types and utilities for working with color palettes.

Package colour provides public types and utilities for working with color palettes.

Package colour provides public types and utilities for working with color palettes.

Package colour provides public types and utilities for working with color palettes.

Package colour provides public types and utilities for working with color palettes. This package is designed for use by external plugins that need to access and format categorized color data from tinct.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ANSIColorInfo

func ANSIColorInfo(colorName string) (name string, r, g, b uint8, isBright, found bool)

ANSIColorInfo returns information about an ANSI color name. Returns the canonical name, RGB values, and whether it's a bright variant.

func GetANSIColorNames

func GetANSIColorNames() []string

GetANSIColorNames returns all supported ANSI color names. Useful for documentation and autocomplete.

Types

type ANSIColor

type ANSIColor struct {
	Name     string
	R, G, B  uint8
	Aliases  []string
	IsBright bool
}

ANSIColor represents a standard ANSI terminal color name and its typical RGB value.

type ANSIColors

type ANSIColors struct {
	// Standard colors (0-7).
	Black   RGBA `json:"black"`
	Red     RGBA `json:"red"`
	Green   RGBA `json:"green"`
	Yellow  RGBA `json:"yellow"`
	Blue    RGBA `json:"blue"`
	Magenta RGBA `json:"magenta"`
	Cyan    RGBA `json:"cyan"`
	White   RGBA `json:"white"`

	// Bright colors (8-15).
	BrightBlack   RGBA `json:"bright_black"`
	BrightRed     RGBA `json:"bright_red"`
	BrightGreen   RGBA `json:"bright_green"`
	BrightYellow  RGBA `json:"bright_yellow"`
	BrightBlue    RGBA `json:"bright_blue"`
	BrightMagenta RGBA `json:"bright_magenta"`
	BrightCyan    RGBA `json:"bright_cyan"`
	BrightWhite   RGBA `json:"bright_white"`
}

ANSIColors represents the 16-color ANSI palette for terminal emulators.

type CategorisedColour

type CategorisedColour struct {
	Colour      color.Color `json:"-"`
	Role        Role        `json:"role"`
	Hex         string      `json:"hex"`  // #RRGGBB format (backwards compatible)
	RGB         RGB         `json:"rgb"`  // RGB without alpha (backwards compatible)
	RGBA        RGBA        `json:"rgba"` // RGBA with alpha channel (defaults to 255/opaque)
	Luminance   float64     `json:"luminance"`
	IsLight     bool        `json:"is_light"`
	Hue         float64     `json:"hue,omitempty"`          // HSL hue (0-360)
	Saturation  float64     `json:"saturation,omitempty"`   // HSL saturation (0-1)
	Index       int         `json:"index,omitempty"`        // Index in AllColours array (sorted by luminance)
	IsGenerated bool        `json:"is_generated,omitempty"` // True if colour was generated/enhanced, not extracted
	Weight      float64     `json:"weight,omitempty"`       // Original weight from palette (0.0-1.0, 0 if generated)
}

CategorisedColour represents a colour with its assigned role and metadata.

type CategorisedPalette

type CategorisedPalette struct {
	Colours    map[Role]CategorisedColour `json:"colours"`
	ThemeType  ThemeType                  `json:"theme_type"`
	AllColours []CategorisedColour        `json:"all_colours,omitempty"`
	ANSI       *ANSIColors                `json:"ansi,omitempty"` // ANSI terminal colors
}

CategorisedPalette represents a palette with categorised colours.

type ColorFormat

type ColorFormat int

ColorFormat represents different color string formats.

const (
	FormatHex         ColorFormat = iota // #RRGGBB
	FormatHexAlpha                       // #RRGGBBAA
	FormatRGB                            // rgb(r,g,b)
	FormatRGBA                           // rgba(r,g,b,a)
	FormatHexNoHash                      // RRGGBB (for Hyprland)
	FormatRGBDecimal                     // "r,g,b" (for Hyprland)
	FormatRGBADecimal                    // "r,g,b,a" decimal format
)

type ColorValue

type ColorValue struct {
	// contains filtered or unexported fields
}

ColorValue provides multiple format accessors for a single color. This is the primary type templates and plugins will interact with.

func NewColorValue

func NewColorValue(rgba RGBA, role Role, index int) ColorValue

NewColorValue creates a ColorValue from RGBA with optional metadata.

func (ColorValue) A

func (cv ColorValue) A() uint8

func (ColorValue) AlphaFloat

func (cv ColorValue) AlphaFloat() float64

func (ColorValue) B

func (cv ColorValue) B() uint8

func (ColorValue) Format

func (cv ColorValue) Format(format ColorFormat) string

Format returns the color in the specified format.

func (ColorValue) G

func (cv ColorValue) G() uint8

func (ColorValue) Hex

func (cv ColorValue) Hex() string

Convenience accessors for common formats.

func (ColorValue) HexAlpha

func (cv ColorValue) HexAlpha() string

func (ColorValue) HexNoHash

func (cv ColorValue) HexNoHash() string

func (ColorValue) Index

func (cv ColorValue) Index() int

func (ColorValue) R

func (cv ColorValue) R() uint8

Component accessors (for advanced template use).

func (ColorValue) RGB

func (cv ColorValue) RGB() string

func (ColorValue) RGBA

func (cv ColorValue) RGBA() string

func (ColorValue) RGBDecimal

func (cv ColorValue) RGBDecimal() string

func (ColorValue) Role

func (cv ColorValue) Role() Role

Metadata accessors.

func (ColorValue) WithAlpha

func (cv ColorValue) WithAlpha(alpha float64) ColorValue

WithAlpha returns a copy of the ColorValue with custom alpha (0.0-1.0). This is useful for creating transparent variants in templates.

type PaletteHelper

type PaletteHelper struct {
	// contains filtered or unexported fields
}

PaletteHelper provides utilities for output plugins to access palette colors. This eliminates code duplication across all output plugins.

func NewPaletteHelper

func NewPaletteHelper(themeType ThemeType, colors map[Role]ColorValue, indexed []ColorValue) *PaletteHelper

NewPaletteHelper creates a helper for the given theme type and color map. This should be called once per plugin Generate() invocation.

func (*PaletteHelper) AllColors

func (ph *PaletteHelper) AllColors() []ColorValue

AllColors returns all colors indexed by palette order (AllColours array).

func (*PaletteHelper) AllRoles

func (ph *PaletteHelper) AllRoles() []Role

AllRoles returns all roles in deterministic order (core → accents → semantic → surface → variants).

func (*PaletteHelper) Count

func (ph *PaletteHelper) Count() int

Count returns total number of colors in the palette.

func (*PaletteHelper) FindClosestANSIColor

func (ph *PaletteHelper) FindClosestANSIColor(colorName string) (ColorValue, bool)

FindClosestANSIColor finds the color in the palette that most closely matches the given ANSI color name using perceptual color distance. Returns the ColorValue and true if found, or ColorValue{} and false if not found.

Supported color names include:

  • Standard ANSI: black, red, green, yellow, blue, magenta, cyan, white
  • Bright variants: brightblack, brightred, brightgreen, etc.
  • Aliases: color0-color15, gray, grey, purple, darkgray, etc.
  • Extended: orange, pink, brown, lime, navy, teal, maroon, olive, violet, indigo

Name matching is case-insensitive.

func (*PaletteHelper) Get

func (ph *PaletteHelper) Get(role Role) ColorValue

Get returns color by role. Panics if role doesn't exist - use Has() first to check.

func (*PaletteHelper) GetByIndex

func (ph *PaletteHelper) GetByIndex(index int) (ColorValue, bool)

GetByIndex returns color by index in the AllColours array. Returns false if index is out of bounds.

func (*PaletteHelper) GetSafe

func (ph *PaletteHelper) GetSafe(role Role) (ColorValue, bool)

GetSafe returns color by role with a boolean indicating if it exists.

func (*PaletteHelper) GetWithFallback

func (ph *PaletteHelper) GetWithFallback(role Role, fallbackHex string) ColorValue

GetWithFallback returns color by role or parses a fallback hex string if missing.

func (*PaletteHelper) Has

func (ph *PaletteHelper) Has(role Role) bool

Has checks if a role exists in the palette.

func (*PaletteHelper) ThemeType

func (ph *PaletteHelper) ThemeType() ThemeType

ThemeType returns the detected or specified theme type.

func (*PaletteHelper) ThemeTypeString

func (ph *PaletteHelper) ThemeTypeString() string

ThemeTypeString returns the theme type as a string ("dark" or "light").

type RGB

type RGB struct {
	R uint8 `json:"r"`
	G uint8 `json:"g"`
	B uint8 `json:"b"`
}

RGB represents a color in RGB format (without alpha).

func ToRGB

func ToRGB(c color.Color) RGB

ToRGB converts a color.Color to RGB.

func (RGB) Hex

func (rgb RGB) Hex() string

Hex returns the RGB color as a hex string (e.g., "#1a2b3c").

func (RGB) String

func (rgb RGB) String() string

String returns the RGB color as a string in the format "rgb(r, g, b)".

type RGBA

type RGBA struct {
	R uint8 `json:"r"`
	G uint8 `json:"g"`
	B uint8 `json:"b"`
	A uint8 `json:"a"` // 0-255 (0 = transparent, 255 = opaque)
}

RGBA represents a color with alpha channel.

func ToRGBA

func ToRGBA(c color.Color) RGBA

ToRGBA converts a color.Color to RGBA.

func (RGBA) AlphaFloat

func (rgba RGBA) AlphaFloat() float64

AlphaFloat returns the alpha channel as a float in the range 0.0-1.0.

func (RGBA) CSSRgb

func (rgba RGBA) CSSRgb() string

CSSRgb returns the color in CSS rgb() format (e.g., "rgb(26, 43, 60)").

func (RGBA) CSSRgba

func (rgba RGBA) CSSRgba() string

CSSRgba returns the color in CSS rgba() format (e.g., "rgba(26, 43, 60, 1.00)"). This format is used by CSS and applications like SwayOSD.

func (RGBA) Hex

func (rgba RGBA) Hex() string

Hex returns the RGB color as a hex string without alpha (e.g., "#1a2b3c"). This maintains backwards compatibility with RGB.Hex().

func (RGBA) HexAlpha

func (rgba RGBA) HexAlpha() string

HexAlpha returns the RGBA color as a hex string with alpha (e.g., "#1a2b3cff"). This format is used by some applications like Dunst.

func (RGBA) String

func (rgba RGBA) String() string

String returns the RGBA color as a string in the format "rgba(r, g, b, a)".

func (RGBA) ToRGB

func (rgba RGBA) ToRGB() RGB

ToRGB converts RGBA to RGB by dropping the alpha channel.

type Role

type Role string

Role represents the semantic role of a colour in a theme.

const (
	// Core roles.
	RoleBackground      Role = "background"
	RoleBackgroundMuted Role = "backgroundMuted"
	RoleForeground      Role = "foreground"
	RoleForegroundMuted Role = "foregroundMuted"

	// Accent roles.
	RoleAccent1      Role = "accent1"
	RoleAccent1Muted Role = "accent1Muted"
	RoleAccent2      Role = "accent2"
	RoleAccent2Muted Role = "accent2Muted"
	RoleAccent3      Role = "accent3"
	RoleAccent3Muted Role = "accent3Muted"
	RoleAccent4      Role = "accent4"
	RoleAccent4Muted Role = "accent4Muted"

	// Semantic roles.
	RoleDanger       Role = "danger"
	RoleWarning      Role = "warning"
	RoleSuccess      Role = "success"
	RoleInfo         Role = "info"
	RoleNotification Role = "notification"

	// Surface and container roles (Priority 1 - Material Design 3).
	RoleSurface   Role = "surface"   // Base surface for cards, sheets, dialogs
	RoleOnSurface Role = "onSurface" // Text/icons on surface
	RoleOutline   Role = "outline"   // Borders, dividers, outlines
	RoleBorder    Role = "border"    // Primary border color

	// Surface and border variants (Priority 2).
	RoleSurfaceVariant   Role = "surfaceVariant"   // Alternate surface color
	RoleOnSurfaceVariant Role = "onSurfaceVariant" // Text on surface variant
	RoleBorderMuted      Role = "borderMuted"      // Inactive/muted borders
	RoleOutlineVariant   Role = "outlineVariant"   // Secondary outline

	// On-colors for accents (Priority 2).
	RoleOnAccent1 Role = "onAccent1" // Text on accent1 background
	RoleOnAccent2 Role = "onAccent2" // Text on accent2 background
	RoleOnAccent3 Role = "onAccent3" // Text on accent3 background
	RoleOnAccent4 Role = "onAccent4" // Text on accent4 background

	// On-colors for semantic roles (Priority 2).
	RoleOnDanger  Role = "onDanger"  // Text on danger background
	RoleOnWarning Role = "onWarning" // Text on warning background
	RoleOnSuccess Role = "onSuccess" // Text on success background
	RoleOnInfo    Role = "onInfo"    // Text on info background

	// Inverse colors for overlays (Priority 3).
	RoleInverseSurface   Role = "inverseSurface"   // Inverse surface (tooltip backgrounds)
	RoleInverseOnSurface Role = "inverseOnSurface" // Text on inverse surface
	RoleInversePrimary   Role = "inversePrimary"   // Inverse accent color

	// Scrim and shadow with alpha (Priority 3).
	RoleScrim  Role = "scrim"  // Modal backdrop overlay (with alpha)
	RoleShadow Role = "shadow" // Elevation shadows (with alpha)

	// Surface container elevation variants (Priority 3 - Material Design 3).
	RoleSurfaceContainerLowest  Role = "surfaceContainerLowest"  // Lowest elevation
	RoleSurfaceContainerLow     Role = "surfaceContainerLow"     // Low elevation
	RoleSurfaceContainer        Role = "surfaceContainer"        // Default container
	RoleSurfaceContainerHigh    Role = "surfaceContainerHigh"    // High elevation
	RoleSurfaceContainerHighest Role = "surfaceContainerHighest" // Highest elevation

	// Positional roles for ambient lighting.
	// Core 8 positions (corners + mid-edges).
	RolePositionTopLeft     Role = "positionTopLeft"
	RolePositionTop         Role = "positionTop"
	RolePositionTopRight    Role = "positionTopRight"
	RolePositionRight       Role = "positionRight"
	RolePositionBottomRight Role = "positionBottomRight"
	RolePositionBottom      Role = "positionBottom"
	RolePositionBottomLeft  Role = "positionBottomLeft"
	RolePositionLeft        Role = "positionLeft"

	// Extended positions for 12+ region configurations.
	RolePositionTopLeftInner     Role = "positionTopLeftInner"
	RolePositionTopCenter        Role = "positionTopCenter"
	RolePositionTopRightInner    Role = "positionTopRightInner"
	RolePositionRightTop         Role = "positionRightTop"
	RolePositionRightBottom      Role = "positionRightBottom"
	RolePositionBottomRightInner Role = "positionBottomRightInner"
	RolePositionBottomCenter     Role = "positionBottomCenter"
	RolePositionBottomLeftInner  Role = "positionBottomLeftInner"
	RolePositionLeftBottom       Role = "positionLeftBottom"
	RolePositionLeftTop          Role = "positionLeftTop"

	// Ultra-extended positions for 16+ region configurations.
	RolePositionTopLeftOuter      Role = "positionTopLeftOuter"
	RolePositionTopLeftCenter     Role = "positionTopLeftCenter"
	RolePositionTopRightCenter    Role = "positionTopRightCenter"
	RolePositionTopRightOuter     Role = "positionTopRightOuter"
	RolePositionRightTopOuter     Role = "positionRightTopOuter"
	RolePositionRightBottomOuter  Role = "positionRightBottomOuter"
	RolePositionBottomRightOuter  Role = "positionBottomRightOuter"
	RolePositionBottomRightCenter Role = "positionBottomRightCenter"
	RolePositionBottomLeftCenter  Role = "positionBottomLeftCenter"
	RolePositionBottomLeftOuter   Role = "positionBottomLeftOuter"
	RolePositionLeftBottomOuter   Role = "positionLeftBottomOuter"
	RolePositionLeftTopOuter      Role = "positionLeftTopOuter"
)

type ThemeData

type ThemeData struct {
	*PaletteHelper
	WallpaperPath string
	ThemeName     string
}

ThemeData wraps a categorised palette with additional metadata for plugins. This is the primary data structure passed to templates and external plugins.

func NewThemeData

func NewThemeData(palette *CategorisedPalette, wallpaperPath, themeName string) *ThemeData

NewThemeData creates a ThemeData wrapper from a CategorisedPalette. This is called by tinct when preparing data for plugins.

func (*ThemeData) GetPaletteHelper added in v0.1.1

func (td *ThemeData) GetPaletteHelper() *PaletteHelper

GetPaletteHelper returns the embedded PaletteHelper. This method allows ThemeData to satisfy the PaletteProvider interface.

type ThemeType

type ThemeType int

ThemeType represents whether a theme is light or dark.

const (
	// ThemeDark represents a dark theme.
	ThemeDark ThemeType = iota
	// ThemeLight represents a light theme.
	ThemeLight
)

func (ThemeType) String

func (t ThemeType) String() string

String returns the string representation of the theme type.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL