design_knobs.hpp

Go to the documentation of this file.

#pragma once
 
// pulp::design — semantic knobs over a design's parameters.
//
// A knob is one expressive control whose value drives a *bundle* of parameter
// writes at once: a "minimalism" slider that moves spacing, borders, shadows and
// accent saturation together; a theme flip; a layout-variant switch. The value
// of a knob is not a pixel — it is a named position, and each position carries
// the exact set of writes that position means.
//
// Knobs are declared per-design (data-driven: adding a knob is a JSON edit, not
// a C++ change), resolved to concrete writes here, and each write is classified
// against the design's bound theme tokens:
//
//   * a write whose key names a real theme token is a THEME-TOKEN write — apply
//     it at the token layer so the whole design re-tints coherently;
//   * every other write is a LOCAL override — persist it into the artifact's
//     own EDITMODE block (see design_tweaks.hpp) so it survives a reload and
//     lands in the diff, with local overriding theme at render time.
//
// The bound theme is passed in as a flat set of token names, not a whole
// DesignManifest, on purpose: the knob model needs to know only which keys are
// theme tokens, so it stays decoupled from the manifest/component/view headers
// and is a pure, deterministic core — no I/O, no window, no render context —
// unit-testable directly. A caller with a DesignManifest passes
// `manifest.tokens[*].name`. The inspector panel and the send-to-agent
// affordance are UI layers that drive these primitives and live elsewhere.
 
#include <pulp/design/design_tweaks.hpp>  // TweakParam, read/rewrite EDITMODE block
 
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::design {

enum class KnobKind { Slider, Toggle, Enum };

struct KnobWrite {
    std::string key;
    std::string json_value;
};

struct KnobPosition {
    std::string label;
    double at = 0.0;
    std::vector<KnobWrite> writes;
};

struct KnobSpec {
    std::string id;
    std::string label;
    KnobKind kind = KnobKind::Enum;
    std::vector<KnobPosition> positions;
};

struct KnobSchema {
    std::vector<KnobSpec> knobs;
};

std::optional<KnobSchema> parse_knob_schema(std::string_view json);

std::string knob_schema_to_json(const KnobSchema& schema);

const KnobSpec* find_knob(const KnobSchema& schema, std::string_view id);

const KnobPosition* select_position(const KnobSpec& knob, std::string_view value);

enum class WriteTarget { ThemeToken, LocalBlock };

WriteTarget classify_write(const KnobWrite& write,
                           const std::vector<std::string>& theme_tokens);

struct KnobEffect {
    std::vector<KnobWrite> token_writes;  
    std::vector<KnobWrite> local_writes;  
};

std::optional<KnobEffect> resolve_knob(const KnobSpec& knob, std::string_view value,
                                       const std::vector<std::string>& theme_tokens);

struct KnobApply {
    std::string text;                     
    std::vector<KnobWrite> token_writes;  
};

std::optional<KnobApply> apply_knob(std::string_view artifact, const KnobSpec& knob,
                                    std::string_view value,
                                    const std::vector<std::string>& theme_tokens);

KnobSpec builtin_theme_flip();
 
}  // namespace pulp::design