css_animation.hpp

Go to the documentation of this file.

// CSS-spec types — `transition` shorthand parser, easing curves
// matching the CSS Animations Module Level 1 vocabulary, the
// AnimatableProperty enum the dispatcher consults, and the
// KeyframesRegistry that holds @keyframes blocks. Sits alongside the
// existing animation.hpp (which holds Pulp's AnimationManager — used
// for native UI animations driven via the FrameClock) without
// colliding: this file is the CSS-driven side, that file is the
// host-app-driven side.
//
#pragma once
 
#include <cctype>
#include <cmath>
#include <cstdint>
#include <cstdlib>
#include <string>
#include <utility>
#include <vector>
 
#include <pulp/view/motion.hpp>
#include <pulp/view/motion_preferences.hpp>
 
namespace pulp::view {

struct CssEasing {
    enum class Kind {
        linear,
        ease,             // cubic-bezier(0.25, 0.1, 0.25, 1)
        ease_in,          // cubic-bezier(0.42, 0, 1, 1)
        ease_out,         // cubic-bezier(0, 0, 0.58, 1)
        ease_in_out,      // cubic-bezier(0.42, 0, 0.58, 1)
        cubic_bezier,     // custom 4-control-point bezier
        steps_start,      // steps(N, jump-start)
        steps_end,        // steps(N, jump-end)
    };

    Kind kind = Kind::ease;
    float p1x = 0.25f, p1y = 0.1f, p2x = 0.25f, p2y = 1.0f; // cubic-bezier
    int steps_count = 1;                                   // steps()

    float at(float t) const {
        if (t <= 0.0f) return 0.0f;
        if (t >= 1.0f) return 1.0f;
        switch (kind) {
            case Kind::linear:
                return t;
            case Kind::ease:
                return cubic_bezier_y(t, 0.25f, 0.1f, 0.25f, 1.0f);
            case Kind::ease_in:
                return cubic_bezier_y(t, 0.42f, 0.0f, 1.0f, 1.0f);
            case Kind::ease_out:
                return cubic_bezier_y(t, 0.0f, 0.0f, 0.58f, 1.0f);
            case Kind::ease_in_out:
                return cubic_bezier_y(t, 0.42f, 0.0f, 0.58f, 1.0f);
            case Kind::cubic_bezier:
                return cubic_bezier_y(t, p1x, p1y, p2x, p2y);
            case Kind::steps_start: {
                const float step = 1.0f / static_cast<float>(steps_count);
                const float v = std::floor(t / step) * step + step;
                return v > 1.0f ? 1.0f : v;
            }
            case Kind::steps_end: {
                const float step = 1.0f / static_cast<float>(steps_count);
                return std::floor(t / step) * step;
            }
        }
        return t;
    }

    static float cubic_bezier_y(float x, float p1x, float p1y, float p2x, float p2y) {
        const float cx = 3.0f * p1x;
        const float bx = 3.0f * (p2x - p1x) - cx;
        const float ax = 1.0f - cx - bx;
        const float cy = 3.0f * p1y;
        const float by = 3.0f * (p2y - p1y) - cy;
        const float ay = 1.0f - cy - by;
        float u = x;
        for (int i = 0; i < 6; ++i) {
            const float xu = ((ax * u + bx) * u + cx) * u;
            const float dxu = (3.0f * ax * u + 2.0f * bx) * u + cx;
            if (dxu == 0.0f) break;
            const float du = (xu - x) / dxu;
            u -= du;
            if (std::abs(du) < 1e-5f) break;
        }
        return ((ay * u + by) * u + cy) * u;
    }

    static CssEasing from_keyword(const std::string& s) {
        CssEasing e;
        if (s == "ease")             e.kind = Kind::ease;
        else if (s == "ease-in")     e.kind = Kind::ease_in;
        else if (s == "ease-out")    e.kind = Kind::ease_out;
        else if (s == "ease-in-out") e.kind = Kind::ease_in_out;
        else                          e.kind = Kind::linear;
        return e;
    }
};

enum class AnimatableProperty {
    opacity,
    background_color,
    color,
    border_color,
    translate_x,
    translate_y,
    rotate_deg,
    scale,
    width,
    height,
    margin_top,
    margin_right,
    margin_bottom,
    margin_left,
    padding_top,
    padding_right,
    padding_bottom,
    padding_left,
    top,
    right,
    bottom,
    left,
    none,
};

struct TransitionSpec {
    AnimatableProperty property = AnimatableProperty::none;
    std::string property_name;
    float duration_seconds = 0.0f;
    float delay_seconds = 0.0f;
    CssEasing easing{};

    std::string source_file;
    int source_line = 0;

    bool is_snap() const { return duration_seconds <= 0.0f; }

    motion::Provenance motion_provenance() const {
        motion::Provenance p;
        if (source_file.empty() && source_line == 0 && property_name.empty()) {
            return p;
        }
        p.source_kind = "css-transition";
        p.source_id = property_name.empty() ? std::string{"all"} : property_name;
        p.source_file = source_file;
        p.source_line = source_line;
        return p;
    }
};

struct CssAnimation {
    AnimatableProperty property = AnimatableProperty::none;
    TransitionSpec spec{};
    float start_value = 0.0f;
    float end_value = 0.0f;
    float elapsed_seconds = 0.0f;
    bool active = true;

    bool motion_policy_applied_ = false;

    void apply_motion_policy() {
        if (motion_policy_applied_) return;
        motion_policy_applied_ = true;
        if (motion_policy_is_off()) {
            // Snap to the end value on the next tick.
            spec.duration_seconds = 0.0f;
            spec.delay_seconds = 0.0f;
            return;
        }
        if (MotionPreferences::current() == MotionPolicy::Reduced) {
            const double scale =
                MotionPreferences::current_duration_scale();
            spec.duration_seconds *= static_cast<float>(scale);
        }
    }

    float tick(float dt) {
        if (!motion_policy_applied_) apply_motion_policy();
        elapsed_seconds += dt;
        const float total = spec.delay_seconds + spec.duration_seconds;
        if (elapsed_seconds >= total) {
            active = false;
            return end_value;
        }
        if (elapsed_seconds < spec.delay_seconds) {
            return start_value;
        }
        const float local = elapsed_seconds - spec.delay_seconds;
        const float t = spec.duration_seconds > 0.0f
                        ? local / spec.duration_seconds
                        : 1.0f;
        const float p = spec.easing.at(t);
        return start_value + (end_value - start_value) * p;
    }

    void publish(std::string view_name,
                 std::string metric_name,
                 motion::PublishOptions opts = {}) const {
        auto p = spec.motion_provenance();
        if (p.is_set() && !opts.provenance.is_set()) {
            opts.provenance = std::move(p);
        }
        // Re-evaluate the eased value at the current elapsed time
        // without mutating internal state — the host already called
        // `tick()` to advance, so reading the spec is enough.
        float t = 0.0f;
        const float local = elapsed_seconds - spec.delay_seconds;
        if (local > 0.0f && spec.duration_seconds > 0.0f) {
            t = local / spec.duration_seconds;
            if (t > 1.0f) t = 1.0f;
        }
        const float eased = spec.easing.at(t);
        const float current = start_value + (end_value - start_value) * eased;
        motion::publish_value(std::move(view_name), std::move(metric_name),
                              static_cast<double>(current), opts);
    }
};

struct CssKeyframe {
    float offset = 0.0f;
    std::vector<std::pair<std::string /*prop*/, std::string /*raw value*/>> properties;
};

struct CssKeyframesBlock {
    std::string name;
    std::vector<CssKeyframe> stops;
};

struct CssKeyframesRegistry {
    std::vector<CssKeyframesBlock> blocks;
 
    void define(CssKeyframesBlock block) {
        for (auto& b : blocks) {
            if (b.name == block.name) {
                b = std::move(block);
                return;
            }
        }
        blocks.push_back(std::move(block));
    }
 
    const CssKeyframesBlock* find(const std::string& name) const {
        for (const auto& b : blocks) {
            if (b.name == name) return &b;
        }
        return nullptr;
    }
};

inline AnimatableProperty animatable_property_from_css_name(const std::string& name) {
    if (name == "opacity")            return AnimatableProperty::opacity;
    if (name == "background-color")   return AnimatableProperty::background_color;
    if (name == "color")              return AnimatableProperty::color;
    if (name == "border-color")       return AnimatableProperty::border_color;
    if (name == "translate-x")        return AnimatableProperty::translate_x;
    if (name == "translate-y")        return AnimatableProperty::translate_y;
    if (name == "rotate")             return AnimatableProperty::rotate_deg;
    if (name == "scale")              return AnimatableProperty::scale;
    if (name == "width")              return AnimatableProperty::width;
    if (name == "height")             return AnimatableProperty::height;
    if (name == "margin-top")         return AnimatableProperty::margin_top;
    if (name == "margin-right")       return AnimatableProperty::margin_right;
    if (name == "margin-bottom")      return AnimatableProperty::margin_bottom;
    if (name == "margin-left")        return AnimatableProperty::margin_left;
    if (name == "padding-top")        return AnimatableProperty::padding_top;
    if (name == "padding-right")      return AnimatableProperty::padding_right;
    if (name == "padding-bottom")     return AnimatableProperty::padding_bottom;
    if (name == "padding-left")       return AnimatableProperty::padding_left;
    if (name == "top")                return AnimatableProperty::top;
    if (name == "right")              return AnimatableProperty::right;
    if (name == "bottom")             return AnimatableProperty::bottom;
    if (name == "left")               return AnimatableProperty::left;
    return AnimatableProperty::none;
}

inline float parse_css_time_seconds(const std::string& s) {
    if (s.empty()) return 0.0f;
    char* end = nullptr;
    float v = std::strtof(s.c_str(), &end);
    if (end == s.c_str() || !std::isfinite(v)) return 0.0f;
    std::string unit = end;
    while (!unit.empty() && std::isspace(static_cast<unsigned char>(unit.front()))) unit.erase(0, 1);
    while (!unit.empty() && std::isspace(static_cast<unsigned char>(unit.back()))) unit.pop_back();
    if (unit == "ms") return v / 1000.0f;
    if (unit == "s")  return v;
    if (unit.empty()) return v; // bare number → seconds (lenient)
    return 0.0f;
}
 
inline bool parse_css_float_token(const std::string& token, float& out) {
    if (token.empty()) return false;
    char* end = nullptr;
    float v = std::strtof(token.c_str(), &end);
    if (end == token.c_str() || !std::isfinite(v)) return false;
    while (*end != '\0') {
        if (!std::isspace(static_cast<unsigned char>(*end))) return false;
        ++end;
    }
    out = v;
    return true;
}

inline std::vector<TransitionSpec> parse_transition_shorthand(const std::string& css) {
    std::vector<TransitionSpec> out;
    if (css.empty() || css == "none") return out;
 
    // Split on commas at depth 0 (cubic-bezier(...) has commas inside
    // parens; need to skip those).
    std::vector<std::string> entries;
    {
        std::string acc;
        int depth = 0;
        for (char c : css) {
            if (c == '(') ++depth;
            else if (c == ')') --depth;
            if (c == ',' && depth == 0) {
                entries.push_back(acc);
                acc.clear();
            } else {
                acc += c;
            }
        }
        if (!acc.empty()) entries.push_back(acc);
    }
 
    for (const auto& entry : entries) {
        // Tokenize on whitespace (preserving cubic-bezier(...) and
        // steps(...) parens).
        std::vector<std::string> tokens;
        {
            std::string acc;
            int depth = 0;
            for (char c : entry) {
                if (c == '(') { ++depth; acc += c; continue; }
                if (c == ')') { --depth; acc += c; continue; }
                if (depth == 0 && std::isspace(static_cast<unsigned char>(c))) {
                    if (!acc.empty()) { tokens.push_back(acc); acc.clear(); }
                    continue;
                }
                acc += c;
            }
            if (!acc.empty()) tokens.push_back(acc);
        }
 
        if (tokens.empty()) continue;
 
        TransitionSpec spec{};
        bool saw_duration = false;
        for (const auto& tok : tokens) {
            // Time tokens — `200ms` or `0.3s` (but NOT `ease`).
            const bool ends_ms = (tok.size() >= 2 && tok.substr(tok.size() - 2) == "ms");
            const bool ends_s_only = (!ends_ms && tok.size() >= 2 && tok.back() == 's'
                                      && (std::isdigit(static_cast<unsigned char>(tok[tok.size() - 2]))
                                          || tok[tok.size() - 2] == '.'));
            if (ends_ms || ends_s_only) {
                if (!saw_duration) { spec.duration_seconds = parse_css_time_seconds(tok); saw_duration = true; }
                else                spec.delay_seconds = parse_css_time_seconds(tok);
                continue;
            }
            // Easing keyword
            if (tok == "linear" || tok == "ease" || tok == "ease-in"
                || tok == "ease-out" || tok == "ease-in-out") {
                spec.easing = CssEasing::from_keyword(tok);
                continue;
            }
            // cubic-bezier(p1x, p1y, p2x, p2y)
            if (tok.rfind("cubic-bezier(", 0) == 0 && tok.back() == ')') {
                std::string inner = tok.substr(13, tok.size() - 14);
                std::vector<float> nums;
                std::string acc;
                auto flush = [&]() {
                    if (!acc.empty()) {
                        float parsed = 0.0f;
                        if (parse_css_float_token(acc, parsed)) nums.push_back(parsed);
                        acc.clear();
                    }
                };
                for (char c : inner) {
                    if (c == ',') flush();
                    else if (!std::isspace(static_cast<unsigned char>(c))) acc += c;
                }
                flush();
                if (nums.size() == 4) {
                    spec.easing.kind = CssEasing::Kind::cubic_bezier;
                    spec.easing.p1x = nums[0]; spec.easing.p1y = nums[1];
                    spec.easing.p2x = nums[2]; spec.easing.p2y = nums[3];
                }
                continue;
            }
            // steps(N) / steps(N, end|start)
            if (tok.rfind("steps(", 0) == 0 && tok.back() == ')') {
                std::string inner = tok.substr(6, tok.size() - 7);
                size_t comma = inner.find(',');
                std::string n_str = comma == std::string::npos ? inner : inner.substr(0, comma);
                char* end = nullptr;
                long steps = std::strtol(n_str.c_str(), &end, 10);
                if (end == n_str.c_str()) continue;
                bool valid_steps = true;
                while (*end != '\0') {
                    if (!std::isspace(static_cast<unsigned char>(*end))) {
                        valid_steps = false;
                        break;
                    }
                    ++end;
                }
                if (!valid_steps) continue;
                spec.easing.steps_count = static_cast<int>(steps);
                spec.easing.kind = CssEasing::Kind::steps_end;
                if (comma != std::string::npos) {
                    std::string mode = inner.substr(comma + 1);
                    while (!mode.empty() && std::isspace(static_cast<unsigned char>(mode.front()))) mode.erase(0, 1);
                    if (mode.rfind("jump-start", 0) == 0 || mode == "start") {
                        spec.easing.kind = CssEasing::Kind::steps_start;
                    }
                }
                continue;
            }
            // Otherwise — property name. Last property name wins (CSS
            // spec: the last unparsed token is the property).
            spec.property_name = tok;
            spec.property = animatable_property_from_css_name(tok);
        }
        if (spec.property_name.empty()) spec.property_name = "all";
        out.push_back(std::move(spec));
    }
    return out;
}

inline std::vector<TransitionSpec> parse_transition_shorthand_with_provenance(
    const std::string& css,
    std::string source_file,
    int source_line) {
    auto specs = parse_transition_shorthand(css);
    for (auto& s : specs) {
        s.source_file = source_file;
        s.source_line = source_line;
    }
    return specs;
}
 
} // namespace pulp::view