Lumacs/documentation/THEME_IMPROVEMENTS.md

Theme System Improvements

Overview

The Lumacs UI has been enhanced with a comprehensive theme framework that provides:

• Remove tilde characters from empty lines for a cleaner look
• Configurable color schemes through Lua API
• Built-in Everforest dark theme
• Extensible theme system for custom themes

Features Added

1. Theme Framework (C++)

• Color class: RGB color representation with ncurses integration
• ThemeElement enum: Defines themed UI elements (Normal, Keyword, String, Comment, etc.)
• Theme class: Manages colors for different UI elements
• ThemeManager class: Handles multiple themes and switching between them

2. Built-in Themes

• Everforest Dark: Beautiful dark theme with carefully chosen colors
• Default Theme: Simple theme using basic colors as fallback

3. Lua API Integration

• Theme configuration through Lua scripts
• Runtime theme switching with editor:set_theme(name)
• Theme listing with editor:theme_manager():theme_names()
• Custom theme creation capabilities

4. UI Improvements

• Removed tilde characters from empty lines
• Themed status line, message line, cursor, and search highlighting
• Syntax highlighting colors now use theme system
• Consistent color scheme throughout the interface

Usage

Switching Themes from Lua

-- Switch to Everforest dark theme
editor:set_theme("everforest-dark")

-- Switch to default theme
editor:set_theme("default")

-- List available themes
local themes = editor:theme_manager():theme_names()
for _, name in ipairs(themes) do
    print("Available theme: " .. name)
end

Key Bindings (in themes.lua)

• C-x t e - Switch to Everforest theme
• C-x t d - Switch to default theme
  
• C-x t l - List all available themes

Creating Custom Themes

-- Example of how to customize theme colors via Lua
local theme = editor:active_theme()
if theme then
    theme:set_color(lumacs.ThemeElement.Keyword, lumacs.Color(255, 100, 100))
    theme:set_color(lumacs.ThemeElement.String, lumacs.Color(100, 255, 100))
end

Architecture

Theme Elements

The following UI elements are themeable:

Text Elements:

• Normal text
• Keywords, Strings, Comments
• Functions, Types, Numbers, Constants
• Error text

UI Elements:

• Status line (active/inactive)
• Message line
• Line numbers
• Cursor
• Search matches (success/fail)
• Window borders

Color System

• RGB colors with automatic ncurses color mapping
• Fallback to nearest basic colors when terminal doesn't support custom colors
• Efficient color pair caching

Files Modified/Added

New Files:

• include/lumacs/theme.hpp - Theme system headers
• src/theme.cpp - Theme implementation
• themes.lua - Example theme configuration

Modified Files:

• include/lumacs/editor_core.hpp - Added theme manager
• src/editor_core.cpp - Initialize themes
• include/lumacs/lua_api.hpp - Added theme support
• src/lua_api.cpp - Theme Lua bindings
• src/main_ncurses.cpp - Updated UI rendering
• CMakeLists.txt - Added theme.cpp to build

Everforest Theme Colors

The Everforest dark theme uses these color values:

• Background: #2d3139
• Foreground: #d3c6aa
• Keywords: #e67e80 (red)
• Strings: #a7c080 (green)
• Comments: #928374 (grey)
• Functions: #7fbbb3 (blue)
• Types: #dbbc7f (yellow)
• Numbers: #d699b5 (purple)

Next Steps

The theme system is ready for Phase 4 features and can be easily extended with:

• More built-in themes (light themes, other popular themes)
• Theme loading from external files
• Per-filetype color customization
• Advanced styling (bold, italic, underline)