design_gallery.hpp

Go to the documentation of this file.

#pragma once
 
// pulp::design — design-system gallery: card model + review-artifact emitters.
//
// A "gallery card" is any example/kit source file that opts in with a first-line
// magic comment. There is no registry to keep in sync — the tag lives in the
// file, so a card is discovered by a grep of the source tree and survives a
// move or rename:
//
//   // @dsCard group=knobs viewport=120x120
//   // @startingPoint
//
// `pulp design gallery` walks a root, parses these tags, renders each card at
// its declared viewport (via the screenshot tool, Skia backend), and emits one
// review artifact per pass — a deterministic JSON manifest plus a self-contained
// HTML grid grouped by `group`. That standing artifact replaces hunting loose
// PNGs after an import/design pass, and doubles as a visual-regression inventory.
//
// This translation unit is deliberately pure: it parses the card model and
// serializes the manifest/HTML, but does no filesystem or render work. The CLI
// owns the walk, the render shell-out, and the content-hash cache; it hands the
// emitters a `png_rel` callback so this layer never learns about paths on disk.
// Kept separate for the same reason design_fidelity_ledger.cpp is separate from
// the checks: the pure model stays trivially testable and free of GPU/IO.
 
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::design {

inline constexpr std::string_view kGalleryFormatVersion = "2026.07-design-gallery-v1";

inline constexpr std::string_view kGalleryUngrouped = "ungrouped";

struct GalleryCard {
    std::string file;             
    std::string group;            
    int width = 0;                
    int height = 0;               
    bool starting_point = false;  
    std::string content_hash;     
};

std::optional<GalleryCard> parse_gallery_card(std::string_view file_head,
                                              std::string_view path);

std::string gallery_content_hash(std::string_view bytes);

void sort_cards(std::vector<GalleryCard>& cards);

std::string gallery_manifest_json(
    const std::vector<GalleryCard>& cards,
    const std::function<std::string(const GalleryCard&)>& png_rel);

std::string gallery_html(
    const std::vector<GalleryCard>& cards,
    const std::function<std::string(const GalleryCard&)>& png_rel);
 
}  // namespace pulp::design