core

Documentation

Overview

Package core provides shared types and errors for keel and engine.

The API is pre-release and may change without warning.

Index

• Variables
• func DebugContentProvider[KID KeelID](id KID, info FrameInfo) (string, error)
• type Axis
  • func (i Axis) String() string
• type ConfigError
  • func (e *ConfigError) Error() string
  • func (e *ConfigError) Is(target error) bool
  • func (e *ConfigError) Unwrap() error
• type ExtentConstraint
  • func (e ExtentConstraint) Extent() ExtentConstraint
• type ExtentError
  • func (e *ExtentError) Error() string
  • func (e *ExtentError) Is(target error) bool
  • func (e *ExtentError) Unwrap() error
• type ExtentKind
  • func (i ExtentKind) String() string
• type ExtentTooSmallError
  • func (e *ExtentTooSmallError) Error() string
  • func (e *ExtentTooSmallError) Unwrap() error
• type FitMode
  • func (i FitMode) String() string
• type FrameInfo
• type FrameSpec
• type KeelID
• type Size
• type SlotError
  • func (e *SlotError) Error() string
  • func (e *SlotError) Is(target error) bool
  • func (e *SlotError) Unwrap() error
• type Spec
• type StackSpec

Variables

var (
	// ErrExtentTooSmall indicates insufficient extent for an allocation.
	ErrExtentTooSmall = errors.New("extent too small")
	// ErrConfigurationInvalid indicates an invalid layout configuration.
	ErrConfigurationInvalid = errors.New("configuration invalid")
	// ErrUnknownSpec indicates a Spec with an unsupported type.
	ErrUnknownSpec = errors.New("unknown spec")
	// ErrInvalidAxis indicates an invalid axis value.
	ErrInvalidAxis = errors.New("invalid axis")
	// ErrNilSlot indicates a nil slot entry.
	ErrNilSlot = errors.New("nil slot")
	// ErrInvalidTotal indicates an invalid total allocation.
	ErrInvalidTotal = errors.New("invalid total")
	// ErrEmptyExtents indicates a missing set of extents.
	ErrEmptyExtents = errors.New("empty extents")
	// ErrInvalidExtentKind indicates an invalid extent kind.
	ErrInvalidExtentKind = errors.New("invalid extent kind")
	// ErrInvalidExtentUnits indicates invalid extent units.
	ErrInvalidExtentUnits = errors.New("invalid extent units")
	// ErrInvalidExtentMinCells indicates invalid minimum cells for an extent.
	ErrInvalidExtentMinCells = errors.New("invalid extent min cells")
	// ErrInvalidExtentMaxCells indicates invalid maximum cells for an extent.
	ErrInvalidExtentMaxCells = errors.New("invalid extent max cells")
	// ErrInvalidExtentMin indicates invalid minimum requirements for an extent.
	ErrInvalidExtentMin = errors.New("invalid extent min")
	// ErrInvalidExtentMax indicates invalid maximum requirements for an extent.
	ErrInvalidExtentMax = errors.New("invalid extent max")
)

Functions

func DebugContentProvider

func DebugContentProvider[KID KeelID](id KID, info FrameInfo) (string, error)

DebugContentProvider returns a debug content provider that fits the content box. It truncates lines to ContentWidth and caps the number of lines to ContentHeight.

Types

type Axis

type Axis uint8

Axis represents a layout axis used by stacks to split space.

const (
	// AxisHorizontal lays out content left-to-right.
	AxisHorizontal Axis = 0
	// AxisVertical lays out content top-to-bottom.
	AxisVertical Axis = 1
)

func (Axis) String

func (i Axis) String() string

type ConfigError

type ConfigError struct {
	Reason error
}

ConfigError wraps a configuration issue with a specific reason. It unwraps to the underlying reason and matches ErrConfigurationInvalid.

func (*ConfigError) Error

func (e *ConfigError) Error() string

func (*ConfigError) Is

func (e *ConfigError) Is(target error) bool

func (*ConfigError) Unwrap

func (e *ConfigError) Unwrap() error

type ExtentConstraint

type ExtentConstraint struct {
	Kind     ExtentKind
	Units    int
	MinCells int // Minimum total cells to reserve on this axis (0 = no min)
	MaxCells int // Maximum total cells to reserve on this axis (0 = no max)
}

ExtentConstraint defines how much total space a Spec should take along an axis. For frames, this is the allocation for content plus any frame (padding, border, margin). For stacks, this is the space available to distribute across slots.

func (ExtentConstraint) Extent

func (e ExtentConstraint) Extent() ExtentConstraint

Extent implements the Spec interface.

type ExtentError

type ExtentError struct {
	Index  int
	Reason error
}

ExtentError describes a validation issue for a specific extent. It wraps ErrConfigurationInvalid and the underlying reason.

func (*ExtentError) Error

func (e *ExtentError) Error() string

func (*ExtentError) Is

func (e *ExtentError) Is(target error) bool

func (*ExtentError) Unwrap

func (e *ExtentError) Unwrap() error

type ExtentKind

type ExtentKind uint8

ExtentKind represents whether an ExtentConstraint is fixed or flexible.

const (
	// ExtentFixed represents a fixed-size extent.
	ExtentFixed ExtentKind = iota
	// ExtentFlex represents a flexible extent.
	ExtentFlex
)

func (ExtentKind) String

func (i ExtentKind) String() string

type ExtentTooSmallError

type ExtentTooSmallError struct {
	Axis       Axis
	Need, Have int
	Source     string
	Reason     string
}

ExtentTooSmallError includes context about which allocation failed. It wraps ErrExtentTooSmall for errors.Is checks.

func (*ExtentTooSmallError) Error

func (e *ExtentTooSmallError) Error() string

func (*ExtentTooSmallError) Unwrap

func (e *ExtentTooSmallError) Unwrap() error

type FitMode

type FitMode uint8

FitMode represents how content should fit within a FrameSpec's content box.

const (
	// FitExact performs no fitting and errors if content exceeds the content box.
	// This is the zero-value default.
	FitExact FitMode = iota
	// FitWrapClip wraps to the content box width, then clips vertically to fit.
	FitWrapClip
	// FitWrapStrict wraps to the content box width and errors if the wrapped
	// content exceeds the content box height.
	FitWrapStrict
	// FitClip clips content to the content box in both dimensions.
	FitClip
	// FitOverflow allows content to overflow (lipgloss default behavior).
	FitOverflow
)

func (FitMode) String

func (i FitMode) String() string

type FrameInfo

type FrameInfo struct {
	Width, Height               int     // Total allocated size
	ContentWidth, ContentHeight int     // Inner content box size
	FrameWidth, FrameHeight     int     // Total frame size (padding + border + margin)
	Fit                         FitMode // Fit mode for content
}

FrameInfo describes the allocated space for a FrameSpec render pass.

type FrameSpec

type FrameSpec[KID KeelID] interface {
	Spec
	ID() KID
	Fit() FitMode // Returns the content fit mode.
}

FrameSpec is a Spec with an ID, used for content and styling. Frames are the only specs that produce output content.

type KeelID

type KeelID comparable

KeelID is a comparable type used as a stable identifier for frames and resources.

type Size

type Size struct {
	Width, Height int
}

Size describes a width/height pair in cells.

type SlotError

type SlotError struct {
	Index  int
	Reason error
}

SlotError describes a validation issue for a specific slot. It wraps ErrConfigurationInvalid and the underlying reason.

func (*SlotError) Error

func (e *SlotError) Error() string

func (*SlotError) Is

func (e *SlotError) Is(target error) bool

func (*SlotError) Unwrap

func (e *SlotError) Unwrap() error

type Spec

type Spec interface {
	Extent() ExtentConstraint // Returns the desired total extent along an axis.
}

Spec is an element that participates in the layout hierarchy. The extent returned is the total allocation along the stack axis, including any frame space for frames.

type StackSpec

type StackSpec interface {
	Spec
	Axis() Axis                  // Layout axis of the stack
	Len() int                    // Number of slots in the stack
	Slot(index int) (Spec, bool) // Slot access (ok=false when out of range); must be stable during an arrange pass
}

StackSpec is a Spec that splits its allocation across slots. Slot access must be stable for the duration of an arrange pass.