widgets

package
v0.24.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 30, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AreaScopeGlobal   = cmswidgets.AreaScopeGlobal
	AreaScopeTheme    = cmswidgets.AreaScopeTheme
	AreaScopeTemplate = cmswidgets.AreaScopeTemplate
)

Variables

View Source
var (
	ErrDefinitionNameRequired          = errors.New("widgets: definition name required")
	ErrDefinitionSchemaRequired        = errors.New("widgets: definition schema required")
	ErrDefinitionSchemaInvalid         = errors.New("widgets: definition schema invalid")
	ErrDefinitionExists                = errors.New("widgets: definition already exists")
	ErrDefinitionDefaultsInvalid       = errors.New("widgets: defaults contain unknown fields")
	ErrDefinitionInUse                 = errors.New("widgets: definition has active instances")
	ErrDefinitionSoftDeleteUnsupported = errors.New("widgets: soft delete not supported for definitions")

	ErrInstanceDefinitionRequired    = errors.New("widgets: definition id required")
	ErrInstanceCreatorRequired       = errors.New("widgets: created_by is required")
	ErrInstanceUpdaterRequired       = errors.New("widgets: updated_by is required")
	ErrInstanceIDRequired            = errors.New("widgets: instance id required")
	ErrInstancePositionInvalid       = errors.New("widgets: position cannot be negative")
	ErrInstanceConfigurationInvalid  = errors.New("widgets: configuration contains unknown fields")
	ErrInstanceScheduleInvalid       = errors.New("widgets: publish_on must be before unpublish_on")
	ErrVisibilityRulesInvalid        = errors.New("widgets: visibility_rules contains unsupported keys")
	ErrVisibilityScheduleInvalid     = errors.New("widgets: visibility schedule timestamps must be RFC3339")
	ErrInstanceSoftDeleteUnsupported = errors.New("widgets: soft delete not supported for instances")

	ErrTranslationContentRequired = errors.New("widgets: translation content required")
	ErrTranslationLocaleRequired  = errors.New("widgets: translation locale required")
	ErrTranslationExists          = errors.New("widgets: translation already exists for locale")
	ErrTranslationNotFound        = errors.New("widgets: translation not found")

	ErrAreaCodeRequired           = errors.New("widgets: area code required")
	ErrAreaCodeInvalid            = errors.New("widgets: area code must contain letters, numbers, dot, or underscore")
	ErrAreaNameRequired           = errors.New("widgets: area name required")
	ErrAreaDefinitionExists       = errors.New("widgets: area code already exists")
	ErrAreaDefinitionNotFound     = errors.New("widgets: area definition not found")
	ErrAreaFeatureDisabled        = errors.New("widgets: area repositories not configured")
	ErrAreaInstanceRequired       = errors.New("widgets: instance id required")
	ErrAreaPlacementExists        = errors.New("widgets: widget already assigned to area for locale")
	ErrAreaPlacementPosition      = errors.New("widgets: placement position must be zero or positive")
	ErrAreaPlacementNotFound      = errors.New("widgets: placement not found")
	ErrAreaWidgetOrderMismatch    = errors.New("widgets: reorder input must include every placement")
	ErrVisibilityLocaleRestricted = errors.New("widgets: locale not permitted for widget")
)
View Source
var ErrFeatureDisabled = errors.New("widgets: feature disabled")

ErrFeatureDisabled indicates the widget feature is disabled via configuration.

Functions

func Bootstrap

func Bootstrap(ctx context.Context, svc Service, cfg BootstrapConfig) error

Bootstrap registers widget definitions and areas, tolerating duplicates.

func EnsureAreaDefinitions

func EnsureAreaDefinitions(ctx context.Context, svc Service, areas []RegisterAreaDefinitionInput) error

EnsureAreaDefinitions idempotently registers widget area definitions.

func EnsureDefinitions

func EnsureDefinitions(ctx context.Context, svc Service, definitions []RegisterDefinitionInput) error

EnsureDefinitions idempotently registers widget definitions with the provided service.

func NewAreaDefinitionRepository

func NewAreaDefinitionRepository(db *bun.DB) repository.Repository[*AreaDefinition]

NewAreaDefinitionRepository creates a repository for area definitions.

func NewAreaPlacementRepository

func NewAreaPlacementRepository(db *bun.DB) repository.Repository[*AreaPlacement]

NewAreaPlacementRepository creates a repository for area placements.

func NewDefinitionRepository

func NewDefinitionRepository(db *bun.DB) repository.Repository[*Definition]

NewDefinitionRepository creates a repository for widget definitions.

func NewInstanceRepository

func NewInstanceRepository(db *bun.DB) repository.Repository[*Instance]

NewInstanceRepository creates a repository for widget instances.

func NewTranslationRepository

func NewTranslationRepository(db *bun.DB) repository.Repository[*Translation]

NewTranslationRepository creates a repository for widget translations.

Types

type AddTranslationInput

type AddTranslationInput struct {
	InstanceID uuid.UUID
	LocaleID   uuid.UUID
	Content    map[string]any
}

AddTranslationInput describes the payload to add localized widget content.

type AreaDefinition

type AreaDefinition = cmswidgets.AreaDefinition

type AreaDefinitionRepository

type AreaDefinitionRepository interface {
	Create(ctx context.Context, definition *AreaDefinition) (*AreaDefinition, error)
	GetByCode(ctx context.Context, code string) (*AreaDefinition, error)
	List(ctx context.Context) ([]*AreaDefinition, error)
}

AreaDefinitionRepository manages widget area metadata.

func NewMemoryAreaDefinitionRepository

func NewMemoryAreaDefinitionRepository() AreaDefinitionRepository

NewMemoryAreaDefinitionRepository constructs an in-memory area definition repository.

type AreaPlacement

type AreaPlacement = cmswidgets.AreaPlacement

type AreaPlacementRepository

type AreaPlacementRepository interface {
	ListByAreaAndLocale(ctx context.Context, areaCode string, localeID *uuid.UUID) ([]*AreaPlacement, error)
	Replace(ctx context.Context, areaCode string, localeID *uuid.UUID, placements []*AreaPlacement) error
	DeleteByAreaLocaleInstance(ctx context.Context, areaCode string, localeID *uuid.UUID, instanceID uuid.UUID) error
	DeleteByInstance(ctx context.Context, instanceID uuid.UUID) error
}

AreaPlacementRepository manages widget placements within areas.

func NewMemoryAreaPlacementRepository

func NewMemoryAreaPlacementRepository() AreaPlacementRepository

NewMemoryAreaPlacementRepository constructs an in-memory area placement repository.

type AreaScope

type AreaScope = cmswidgets.AreaScope

type AreaWidgetOrder

type AreaWidgetOrder struct {
	PlacementID uuid.UUID
	Position    int
}

AreaWidgetOrder describes the desired order for a placement.

type AssignWidgetToAreaInput

type AssignWidgetToAreaInput struct {
	AreaCode   string
	LocaleID   *uuid.UUID
	InstanceID uuid.UUID
	Position   *int
	Metadata   map[string]any
}

AssignWidgetToAreaInput describes how to bind a widget instance to an area.

type BootstrapConfig

type BootstrapConfig struct {
	Definitions []RegisterDefinitionInput
	Areas       []RegisterAreaDefinitionInput
}

BootstrapConfig bundles the registration payloads applied during startup.

type BunAreaDefinitionRepository

type BunAreaDefinitionRepository struct {
	// contains filtered or unexported fields
}

BunAreaDefinitionRepository implements AreaDefinitionRepository.

func NewBunAreaDefinitionRepository

func NewBunAreaDefinitionRepository(db *bun.DB) *BunAreaDefinitionRepository

NewBunAreaDefinitionRepository creates an area definition repository.

func (*BunAreaDefinitionRepository) Create

func (*BunAreaDefinitionRepository) GetByCode

func (*BunAreaDefinitionRepository) List

type BunAreaPlacementRepository

type BunAreaPlacementRepository struct {
	// contains filtered or unexported fields
}

BunAreaPlacementRepository implements AreaPlacementRepository.

func NewBunAreaPlacementRepository

func NewBunAreaPlacementRepository(db *bun.DB) *BunAreaPlacementRepository

NewBunAreaPlacementRepository creates an area placement repository.

func (*BunAreaPlacementRepository) DeleteByAreaLocaleInstance

func (r *BunAreaPlacementRepository) DeleteByAreaLocaleInstance(ctx context.Context, areaCode string, localeID *uuid.UUID, instanceID uuid.UUID) error

func (*BunAreaPlacementRepository) DeleteByInstance added in v0.2.0

func (r *BunAreaPlacementRepository) DeleteByInstance(ctx context.Context, instanceID uuid.UUID) error

func (*BunAreaPlacementRepository) ListByAreaAndLocale

func (r *BunAreaPlacementRepository) ListByAreaAndLocale(ctx context.Context, areaCode string, localeID *uuid.UUID) ([]*AreaPlacement, error)

func (*BunAreaPlacementRepository) Replace

func (r *BunAreaPlacementRepository) Replace(ctx context.Context, areaCode string, localeID *uuid.UUID, placements []*AreaPlacement) error

type BunDefinitionRepository

type BunDefinitionRepository struct {
	// contains filtered or unexported fields
}

BunDefinitionRepository implements DefinitionRepository with optional caching.

func NewBunDefinitionRepository

func NewBunDefinitionRepository(db *bun.DB) *BunDefinitionRepository

NewBunDefinitionRepository creates a definition repository without caching.

func NewBunDefinitionRepositoryWithCache

func NewBunDefinitionRepositoryWithCache(db *bun.DB, cacheService cache.CacheService, serializer cache.KeySerializer) *BunDefinitionRepository

NewBunDefinitionRepositoryWithCache creates a definition repository with caching.

func (*BunDefinitionRepository) Create

func (r *BunDefinitionRepository) Create(ctx context.Context, definition *Definition) (*Definition, error)

func (*BunDefinitionRepository) Delete added in v0.2.0

func (*BunDefinitionRepository) GetByID

func (*BunDefinitionRepository) GetByName

func (r *BunDefinitionRepository) GetByName(ctx context.Context, name string) (*Definition, error)

func (*BunDefinitionRepository) List

func (*BunDefinitionRepository) Update added in v0.2.0

func (r *BunDefinitionRepository) Update(ctx context.Context, definition *Definition) (*Definition, error)

type BunInstanceRepository

type BunInstanceRepository struct {
	// contains filtered or unexported fields
}

BunInstanceRepository implements InstanceRepository with optional caching.

func NewBunInstanceRepository

func NewBunInstanceRepository(db *bun.DB) *BunInstanceRepository

NewBunInstanceRepository creates an instance repository without caching.

func NewBunInstanceRepositoryWithCache

func NewBunInstanceRepositoryWithCache(db *bun.DB, cacheService cache.CacheService, serializer cache.KeySerializer) *BunInstanceRepository

NewBunInstanceRepositoryWithCache creates an instance repository with caching.

func (*BunInstanceRepository) Create

func (r *BunInstanceRepository) Create(ctx context.Context, instance *Instance) (*Instance, error)

func (*BunInstanceRepository) Delete added in v0.2.0

func (r *BunInstanceRepository) Delete(ctx context.Context, id uuid.UUID) error

func (*BunInstanceRepository) GetByID

func (r *BunInstanceRepository) GetByID(ctx context.Context, id uuid.UUID) (*Instance, error)

func (*BunInstanceRepository) ListAll

func (r *BunInstanceRepository) ListAll(ctx context.Context) ([]*Instance, error)

func (*BunInstanceRepository) ListByArea

func (r *BunInstanceRepository) ListByArea(ctx context.Context, areaCode string) ([]*Instance, error)

func (*BunInstanceRepository) ListByDefinition

func (r *BunInstanceRepository) ListByDefinition(ctx context.Context, definitionID uuid.UUID) ([]*Instance, error)

func (*BunInstanceRepository) Update

func (r *BunInstanceRepository) Update(ctx context.Context, instance *Instance) (*Instance, error)

type BunTranslationRepository

type BunTranslationRepository struct {
	// contains filtered or unexported fields
}

BunTranslationRepository implements TranslationRepository with optional caching.

func NewBunTranslationRepository

func NewBunTranslationRepository(db *bun.DB) *BunTranslationRepository

NewBunTranslationRepository creates a translation repository without caching.

func NewBunTranslationRepositoryWithCache

func NewBunTranslationRepositoryWithCache(db *bun.DB, cacheService cache.CacheService, serializer cache.KeySerializer) *BunTranslationRepository

NewBunTranslationRepositoryWithCache creates a translation repository with caching.

func (*BunTranslationRepository) Create

func (r *BunTranslationRepository) Create(ctx context.Context, translation *Translation) (*Translation, error)

func (*BunTranslationRepository) Delete added in v0.2.0

func (*BunTranslationRepository) GetByInstanceAndLocale

func (r *BunTranslationRepository) GetByInstanceAndLocale(ctx context.Context, instanceID uuid.UUID, localeID uuid.UUID) (*Translation, error)

func (*BunTranslationRepository) ListByInstance

func (r *BunTranslationRepository) ListByInstance(ctx context.Context, instanceID uuid.UUID) ([]*Translation, error)

func (*BunTranslationRepository) Update

func (r *BunTranslationRepository) Update(ctx context.Context, translation *Translation) (*Translation, error)

type CreateInstanceInput

type CreateInstanceInput struct {
	DefinitionID    uuid.UUID
	BlockInstanceID *uuid.UUID
	AreaCode        *string
	Placement       map[string]any
	Configuration   map[string]any
	VisibilityRules map[string]any
	PublishOn       *time.Time
	UnpublishOn     *time.Time
	Position        int
	CreatedBy       uuid.UUID
	UpdatedBy       uuid.UUID
}

CreateInstanceInput defines the payload required to create a widget instance.

type Definition

type Definition = cmswidgets.Definition

type DefinitionFactory

type DefinitionFactory func() RegisterDefinitionInput

DefinitionFactory returns the registration input for a widget definition.

type DefinitionRepository

type DefinitionRepository interface {
	Create(ctx context.Context, definition *Definition) (*Definition, error)
	GetByID(ctx context.Context, id uuid.UUID) (*Definition, error)
	GetByName(ctx context.Context, name string) (*Definition, error)
	List(ctx context.Context) ([]*Definition, error)
	Update(ctx context.Context, definition *Definition) (*Definition, error)
	Delete(ctx context.Context, id uuid.UUID) error
}

DefinitionRepository exposes persistence operations for widget definitions.

func NewMemoryDefinitionRepository

func NewMemoryDefinitionRepository() DefinitionRepository

NewMemoryDefinitionRepository constructs an in-memory widget definition repository.

type DeleteDefinitionRequest added in v0.2.0

type DeleteDefinitionRequest struct {
	ID         uuid.UUID
	HardDelete bool
}

type DeleteInstanceRequest added in v0.2.0

type DeleteInstanceRequest struct {
	InstanceID uuid.UUID
	DeletedBy  uuid.UUID
	HardDelete bool
}

type DeleteTranslationRequest added in v0.2.0

type DeleteTranslationRequest struct {
	InstanceID uuid.UUID
	LocaleID   uuid.UUID
}

type IDGenerator

type IDGenerator func() uuid.UUID

IDGenerator produces unique identifiers.

type Instance

type Instance = cmswidgets.Instance

type InstanceFactory

type InstanceFactory func(ctx context.Context, definition *Definition, input CreateInstanceInput) (map[string]any, error)

InstanceFactory can generate configuration payloads for a widget instance.

type InstanceRepository

type InstanceRepository interface {
	Create(ctx context.Context, instance *Instance) (*Instance, error)
	GetByID(ctx context.Context, id uuid.UUID) (*Instance, error)
	ListByDefinition(ctx context.Context, definitionID uuid.UUID) ([]*Instance, error)
	ListByArea(ctx context.Context, areaCode string) ([]*Instance, error)
	ListAll(ctx context.Context) ([]*Instance, error)
	Update(ctx context.Context, instance *Instance) (*Instance, error)
	Delete(ctx context.Context, id uuid.UUID) error
}

InstanceRepository exposes persistence operations for widget instances.

func NewMemoryInstanceRepository

func NewMemoryInstanceRepository() InstanceRepository

NewMemoryInstanceRepository constructs an in-memory widget instance repository.

type NotFoundError

type NotFoundError struct {
	Resource string
	Key      string
}

NotFoundError is returned when a widget resource cannot be located.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type RegisterAreaDefinitionInput

type RegisterAreaDefinitionInput struct {
	Code        string
	Name        string
	Description *string
	Scope       AreaScope
	ThemeID     *uuid.UUID
	TemplateID  *uuid.UUID
}

RegisterAreaDefinitionInput captures metadata for a widget area.

type RegisterDefinitionInput

type RegisterDefinitionInput struct {
	Name        string
	Description *string
	Schema      map[string]any
	Defaults    map[string]any
	Category    *string
	Icon        *string
}

RegisterDefinitionInput captures the information required to register a widget definition.

type Registration

type Registration struct {
	Definition      DefinitionFactory
	InstanceFactory InstanceFactory
}

Registration bundles a definition factory with an optional instance factory.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry stores built-in and host-defined widget registrations.

func NewRegistry

func NewRegistry() *Registry

NewRegistry constructs an empty registry.

func (*Registry) InstanceFactory

func (r *Registry) InstanceFactory(name string) InstanceFactory

InstanceFactory resolves a registered instance factory by widget name.

func (*Registry) List

func (r *Registry) List() []RegisterDefinitionInput

List returns all registered widget definition inputs.

func (*Registry) Register

func (r *Registry) Register(input RegisterDefinitionInput)

Register adds a static definition input to the registry

func (*Registry) RegisterFactory

func (r *Registry) RegisterFactory(key string, registration Registration)

RegisterFactory adds a definition factory (and optional instance factory) to the registry

type RemoveWidgetFromAreaInput

type RemoveWidgetFromAreaInput struct {
	AreaCode   string
	LocaleID   *uuid.UUID
	InstanceID uuid.UUID
}

RemoveWidgetFromAreaInput removes a widget instance from an area/locale combination.

type ReorderAreaWidgetsInput

type ReorderAreaWidgetsInput struct {
	AreaCode string
	LocaleID *uuid.UUID
	Items    []AreaWidgetOrder
}

ReorderAreaWidgetsInput updates ordering for widget placements within an area.

type ResolveAreaInput

type ResolveAreaInput struct {
	AreaCode          string
	LocaleID          *uuid.UUID
	FallbackLocaleIDs []uuid.UUID
	Audience          []string
	Segments          []string
	Now               time.Time
}

ResolveAreaInput controls how area widgets are resolved for rendering.

type ResolvedWidget

type ResolvedWidget = cmswidgets.ResolvedWidget

type Service

type Service interface {
	RegisterDefinition(ctx context.Context, input RegisterDefinitionInput) (*Definition, error)
	GetDefinition(ctx context.Context, id uuid.UUID) (*Definition, error)
	ListDefinitions(ctx context.Context) ([]*Definition, error)
	DeleteDefinition(ctx context.Context, req DeleteDefinitionRequest) error
	SyncRegistry(ctx context.Context) error

	CreateInstance(ctx context.Context, input CreateInstanceInput) (*Instance, error)
	UpdateInstance(ctx context.Context, input UpdateInstanceInput) (*Instance, error)
	GetInstance(ctx context.Context, id uuid.UUID) (*Instance, error)
	ListInstancesByDefinition(ctx context.Context, definitionID uuid.UUID) ([]*Instance, error)
	ListInstancesByArea(ctx context.Context, areaCode string) ([]*Instance, error)
	ListAllInstances(ctx context.Context) ([]*Instance, error)
	DeleteInstance(ctx context.Context, req DeleteInstanceRequest) error

	AddTranslation(ctx context.Context, input AddTranslationInput) (*Translation, error)
	UpdateTranslation(ctx context.Context, input UpdateTranslationInput) (*Translation, error)
	GetTranslation(ctx context.Context, instanceID uuid.UUID, localeID uuid.UUID) (*Translation, error)
	DeleteTranslation(ctx context.Context, req DeleteTranslationRequest) error

	RegisterAreaDefinition(ctx context.Context, input RegisterAreaDefinitionInput) (*AreaDefinition, error)
	ListAreaDefinitions(ctx context.Context) ([]*AreaDefinition, error)
	AssignWidgetToArea(ctx context.Context, input AssignWidgetToAreaInput) ([]*AreaPlacement, error)
	RemoveWidgetFromArea(ctx context.Context, input RemoveWidgetFromAreaInput) error
	ReorderAreaWidgets(ctx context.Context, input ReorderAreaWidgetsInput) ([]*AreaPlacement, error)
	ResolveArea(ctx context.Context, input ResolveAreaInput) ([]*ResolvedWidget, error)
	EvaluateVisibility(ctx context.Context, instance *Instance, input VisibilityContext) (bool, error)
}

Service exposes widget management capabilities.

func NewNoOpService

func NewNoOpService() Service

NewNoOpService returns a Service implementation that always reports the feature as disabled.

func NewService

func NewService(defRepo DefinitionRepository, instRepo InstanceRepository, trRepo TranslationRepository, opts ...ServiceOption) Service

NewService constructs a widget service instance.

type ServiceOption

type ServiceOption func(*service)

ServiceOption configures widget service behaviour.

func WithActivityEmitter added in v0.5.0

func WithActivityEmitter(emitter *activity.Emitter) ServiceOption

WithActivityEmitter wires the activity emitter used for activity records.

func WithAreaDefinitionRepository

func WithAreaDefinitionRepository(repo AreaDefinitionRepository) ServiceOption

WithAreaDefinitionRepository wires the area definition repository.

func WithAreaPlacementRepository

func WithAreaPlacementRepository(repo AreaPlacementRepository) ServiceOption

WithAreaPlacementRepository wires the area placement repository.

func WithClock

func WithClock(clock func() time.Time) ServiceOption

WithClock overrides the time source used by the service.

func WithIDGenerator

func WithIDGenerator(generator IDGenerator) ServiceOption

WithIDGenerator overrides the ID generator.

func WithRegistry

func WithRegistry(reg *Registry) ServiceOption

WithRegistry injects a widget registry that provides built-in and host-defined widgets.

func WithShortcodeService added in v0.2.0

func WithShortcodeService(svc interfaces.ShortcodeService) ServiceOption

WithShortcodeService wires the shortcode renderer used for widget translations.

type Translation

type Translation = cmswidgets.Translation

type TranslationRepository

type TranslationRepository interface {
	Create(ctx context.Context, translation *Translation) (*Translation, error)
	GetByInstanceAndLocale(ctx context.Context, instanceID uuid.UUID, localeID uuid.UUID) (*Translation, error)
	ListByInstance(ctx context.Context, instanceID uuid.UUID) ([]*Translation, error)
	Update(ctx context.Context, translation *Translation) (*Translation, error)
	Delete(ctx context.Context, id uuid.UUID) error
}

TranslationRepository exposes persistence operations for widget translations.

func NewMemoryTranslationRepository

func NewMemoryTranslationRepository() TranslationRepository

NewMemoryTranslationRepository constructs an in-memory widget translation repository.

type UpdateInstanceInput

type UpdateInstanceInput struct {
	InstanceID      uuid.UUID
	Configuration   map[string]any
	VisibilityRules map[string]any
	Placement       map[string]any
	PublishOn       *time.Time
	UnpublishOn     *time.Time
	Position        *int
	UpdatedBy       uuid.UUID
	AreaCode        *string
}

UpdateInstanceInput defines mutable fields for a widget instance.

type UpdateTranslationInput

type UpdateTranslationInput struct {
	InstanceID uuid.UUID
	LocaleID   uuid.UUID
	Content    map[string]any
}

UpdateTranslationInput updates the localized widget content.

type VisibilityContext

type VisibilityContext struct {
	Now         time.Time
	LocaleID    *uuid.UUID
	Audience    []string
	Segments    []string
	CustomRules map[string]any
}

VisibilityContext provides ambient information for visibility evaluation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL