props

Documentation

Overview

Package props implements the composable presentation subsystem.

Props provides typed, discoverable, validated, schema-aware presentation items. Users declare presentation items in config; StageFreight resolves them through typed, validated, schema-aware resolvers.

Two-level dispatch: format (how it renders) + type (which resolver). Badges are the first prop format; the shape accommodates future formats.

Index

• func FormatMarkdown(p ResolvedProp, variant Variant) string
• func Register(def Definition)
• func ValidateParams(def Definition, params map[string]string) error
• func ValidateVariant(v Variant) error
• type CategoryCount
  • func Categories() []CategoryCount
• type Definition
  • func All() []Definition
  • func Get(id string) (Definition, bool)
  • func List(category string) []Definition
• type ParamSpec
• type PropResolver
• type PropSchema
• type Provider
• type RenderOptions
• type ResolvedProp
  • func ResolveDefinition(def Definition, params map[string]string, opts RenderOptions) (ResolvedProp, error)
• type ShieldsResolver
  • func (s ShieldsResolver) Resolve(params map[string]string, opts RenderOptions) (ResolvedProp, error)
  • func (s ShieldsResolver) Schema() PropSchema
• type StaticResolver
  • func (s StaticResolver) Resolve(params map[string]string, opts RenderOptions) (ResolvedProp, error)
  • func (s StaticResolver) Schema() PropSchema
• type ValidationError
  • func (e *ValidationError) Error() string
• type Variant

Functions

func FormatMarkdown

func FormatMarkdown(p ResolvedProp, variant Variant) string

FormatMarkdown formats a resolved prop as inline markdown. Used by both narrator PropsModule and `props render` CLI. Returns empty string if ImageURL is empty. Panics on unknown variant — callers must validate via ValidateVariant first.

func Register

func Register(def Definition)

Register adds a prop definition to the global registry. Panics on duplicate ID (caught at init time).

func ValidateParams

func ValidateParams(def Definition, params map[string]string) error

ValidateParams checks params against a resolver's Schema(). Missing required params and unknown params produce errors.

func ValidateVariant

func ValidateVariant(v Variant) error

ValidateVariant returns an error if the variant is not recognized. Empty string is accepted as an alias for VariantClassic.

Types

type CategoryCount

type CategoryCount struct {
	Name  string
	Count int
}

CategoryCount holds a category name and the number of types in it.

func Categories

func Categories() []CategoryCount

Categories returns all categories with their type counts, sorted by name.

type Definition

type Definition struct {
	ID          string
	Format      string // "badge" (future: "image", "callout", etc.)
	Category    string // grouping for list/docs (e.g. "docker", "security")
	Description string
	Provider    Provider
	DefaultAlt  string // human-readable name — single source of truth
	Resolver    PropResolver
}

Definition is the registry entry for a prop type.

func All

func All() []Definition

All returns all registered definitions in registration order.

func Get

func Get(id string) (Definition, bool)

Get returns a definition by type ID, or false if not found.

func List

func List(category string) []Definition

List returns definitions filtered by category. Empty category returns all.

type ParamSpec

type ParamSpec struct {
	Name     string
	Required bool
	Default  string // empty = no default
	Help     string // shown in `props show`
}

ParamSpec describes a single parameter for docs and validation.

type PropResolver

type PropResolver interface {
	Resolve(params map[string]string, opts RenderOptions) (ResolvedProp, error)
	Schema() PropSchema
}

PropResolver is the core interface every resolver implements.

type PropSchema

type PropSchema struct {
	Params  []ParamSpec
	Example map[string]string // example params for `props show`
}

PropSchema exposes docs/validation metadata for a resolver.

type Provider

type Provider string

Provider source — lightweight metadata for docs/list output, not routing.

const (
	ProviderShields Provider = "shields" // img.shields.io
	ProviderNative  Provider = "native"  // service's own badge URL
	ProviderStatic  Provider = "static"  // fixed image, no dynamic params
)

type RenderOptions

type RenderOptions struct {
	Label   string  // override Alt text
	Link    string  // override LinkURL
	Style   string  // shields.io style (flat, flat-square, etc.)
	Logo    string  // shields.io logo name
	Variant Variant // render variant — default: classic
}

RenderOptions are presentation overrides supplied by narrator items. Assembled from narrator fields (label, link, style, logo) before resolution.

type ResolvedProp

type ResolvedProp struct {
	ImageURL string
	LinkURL  string
	Alt      string // human-readable, e.g. "Docker Pulls", "Go Report Card"
}

ResolvedProp is the normalized output from any resolver — structured data, not markdown.

func ResolveDefinition

func ResolveDefinition(def Definition, params map[string]string, opts RenderOptions) (ResolvedProp, error)

ResolveDefinition is the single safe entry point for narrator and CLI.

1. ValidateParams
2. Resolver.Resolve(params, opts)
3. Sanity-check output (no unresolved {placeholder} tokens)
4. Fill Alt from Definition.DefaultAlt if resolver returned empty
5. Apply RenderOptions overrides (Label->Alt, Link->LinkURL)

type ShieldsResolver

type ShieldsResolver struct {
	PathTemplate string // e.g. "docker/pulls/{image}"
	LinkTemplate string // e.g. "https://hub.docker.com/r/{image}"
	DefaultLogo  string // e.g. "docker"
	Params       []ParamSpec
	Example      map[string]string
}

ShieldsResolver is a shared resolver for shields.io badge types. PathTemplate and LinkTemplate use {param_name} placeholders.

func (ShieldsResolver) Resolve

func (s ShieldsResolver) Resolve(params map[string]string, opts RenderOptions) (ResolvedProp, error)

Resolve constructs shields.io image and link URLs from params.

func (ShieldsResolver) Schema

func (s ShieldsResolver) Schema() PropSchema

Schema returns param metadata for docs and validation.

type StaticResolver

type StaticResolver struct {
	ImageURL string
	LinkURL  string
	Params   []ParamSpec
	Example  map[string]string
}

StaticResolver handles fixed badges with no dynamic provider params. The image URL and link URL are templates expanded with user params.

func (StaticResolver) Resolve

func (s StaticResolver) Resolve(params map[string]string, opts RenderOptions) (ResolvedProp, error)

Resolve returns the static image/link URLs, expanded with params.

func (StaticResolver) Schema

func (s StaticResolver) Schema() PropSchema

Schema returns param metadata for docs and validation.

type ValidationError

type ValidationError struct {
	TypeID  string
	Param   string
	Message string
}

ValidationError reports a problem with prop params or resolution.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type Variant

type Variant string

Variant controls the visual style of rendered output. v1 implements classic only. Other values are reserved and rejected at validation.

const (
	// VariantClassic is the standard markdown badge — v1 default and only implementation.
	VariantClassic Variant = "classic"
)