theme.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/canvas/canvas.hpp>
#include <string>
#include <unordered_map>
#include <optional>
#include <cstdint>
 
namespace pulp::view {
 
// Use the canvas Color type throughout the view system
using Color = canvas::Color;
 
// Convenience helpers for hex color creation
inline Color color_from_hex(uint32_t hex) {
    return Color::rgba8(
        static_cast<uint8_t>((hex >> 16) & 0xFF),
        static_cast<uint8_t>((hex >> 8) & 0xFF),
        static_cast<uint8_t>(hex & 0xFF));
}
 
inline Color color_from_hex_alpha(uint32_t hex) {
    return Color::rgba8(
        static_cast<uint8_t>((hex >> 24) & 0xFF),
        static_cast<uint8_t>((hex >> 16) & 0xFF),
        static_cast<uint8_t>((hex >> 8) & 0xFF),
        static_cast<uint8_t>(hex & 0xFF));
}
 
// Design tokens define the visual language
// Tokens are named values — colors, dimensions, strings
struct Theme {
    // Token storage — flat map from token name to value
    std::unordered_map<std::string, Color> colors;
    std::unordered_map<std::string, float> dimensions;
    std::unordered_map<std::string, std::string> strings;
 
    // Look up a color token, returns nullopt if not found
    std::optional<Color> color(const std::string& name) const;
 
    // Look up a dimension token (spacing, radius, font size, etc.)
    std::optional<float> dimension(const std::string& name) const;
 
    // Look up a string token (font family, etc.)
    std::optional<std::string> string_token(const std::string& name) const;
 
    // Merge another theme on top (overrides values)
    void apply_overrides(const Theme& overrides);
 
    // ── Token-schema versioning ──────────────────────────────────────────────
    // Bumped when the *shape* of the token set changes in a non-additive way
    // (a token is renamed or made required), so saved themes / user reskins can
    // be migrated instead of silently breaking. Adding a new optional token is
    // additive and does NOT need a bump. to_json() stamps this; from_json()
    // reads it (a version-less document is treated as the current schema for
    // backward compatibility) and runs migrate_json() for older versions.
    static constexpr int kSchemaVersion = 1;
 
    // Reads the "schema_version" field from a theme document, or kSchemaVersion
    // when absent (legacy version-less themes are treated as current).
    static int schema_version_of(const std::string& json);
 
    // Forward-migrates an older theme document to the current schema. v1 is the
    // first versioned schema, so this is currently identity; future schema
    // changes add their migration step here. Unknown-future versions are
    // returned unchanged (parsed leniently — only known tokens are read).
    static std::string migrate_json(const std::string& json, int from_version);
 
    // Load from JSON string (choc::json format). Applies migrate_json() first.
    static Theme from_json(const std::string& json);
 
    // Serialize to JSON string (stamped with schema_version = kSchemaVersion).
    std::string to_json() const;
 
    // Built-in themes
    static Theme dark();
    static Theme light();
    static Theme pro_audio();
 
    // ── Import/Export ────────────────────────────────────────────────────────

    bool save_to_file(const std::string& path) const;

    static Theme load_from_file(const std::string& path);
 
    // ── Validation ──────────────────────────────────────────────────────────

    static const std::vector<std::string>& required_color_tokens();

    std::vector<std::string> missing_tokens() const;

    bool is_complete() const;

    void fill_from(const Theme& base);
};
 
} // namespace pulp::view