primitives

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Feb 27, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package primitives provides low-level layout primitives for ForgeUI.

Primitives are the building blocks for more complex components. They provide type-safe wrappers around common CSS layout patterns. All primitives return templ.Component and accept children as templ.Component.

Layout primitives:

  • Box: Polymorphic container element
  • Flex: Flexbox container
  • Grid: CSS Grid container

Stack helpers:

  • VStack: Vertical stack (flex column)
  • HStack: Horizontal stack (flex row)

Utility primitives:

  • Center: Centers content both horizontally and vertically
  • Container: Responsive container with max-width
  • Spacer: Flexible spacer that fills available space
  • Text: Typography primitive

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Box

func Box(opts ...BoxOption) templ.Component

Box creates a polymorphic container element. It's the most basic primitive for layout.

func Center

func Center(children ...templ.Component) templ.Component

Center creates a centered container using flexbox. Centers both horizontally and vertically.

func Container

func Container(children ...templ.Component) templ.Component

Container creates a responsive container with max-width constraints. Commonly used for page layouts.

func Flex

func Flex(opts ...FlexOption) templ.Component

Flex creates a flexbox container.

func Grid

func Grid(opts ...GridOption) templ.Component

Grid creates a CSS Grid container.

func HStack

func HStack(gap string, children ...templ.Component) templ.Component

HStack creates a horizontal stack (flex row). This is a convenience wrapper around Flex for horizontal layouts.

func Provider

func Provider(opts ...ProviderOption) templ.Component

Provider creates a provider context component that shares state with children.

func ProviderDispatch

func ProviderDispatch(providerName, eventName, data string) string

ProviderDispatch returns an Alpine expression to dispatch a provider event.

func ProviderMethod

func ProviderMethod(providerName, method string, args ...string) string

ProviderMethod returns an Alpine expression to call a provider method.

func ProviderScriptUtilities

func ProviderScriptUtilities() templ.Component

ProviderScriptUtilities returns a script tag with helper functions for working with providers.

func ProviderStack

func ProviderStack(providers ...templ.Component) templ.Component

ProviderStack creates a nested stack of providers.

func ProviderValue

func ProviderValue(providerName, key string) string

ProviderValue returns an Alpine expression to access a provider's state.

func Spacer

func Spacer() templ.Component

Spacer creates a flexible spacer that fills available space. Useful for pushing elements apart in flex layouts.

func Text

func Text(opts ...TextOption) templ.Component

Text creates a typography primitive.

func VStack

func VStack(gap string, children ...templ.Component) templ.Component

VStack creates a vertical stack (flex column). This is a convenience wrapper around Flex for vertical layouts.

Types

type BoxOption

type BoxOption func(*BoxProps)

BoxOption is a functional option for configuring Box

func WithAs

func WithAs(tag string) BoxOption

WithAs sets the HTML element type

func WithAttrs

func WithAttrs(attrs templ.Attributes) BoxOption

WithAttrs adds custom attributes

func WithBackground

func WithBackground(bg string) BoxOption

WithBackground sets background classes

func WithChildren

func WithChildren(children ...templ.Component) BoxOption

WithChildren adds child components

func WithClass

func WithClass(class string) BoxOption

WithClass adds custom classes

func WithHeight

func WithHeight(h string) BoxOption

WithHeight sets height classes

func WithMargin

func WithMargin(m string) BoxOption

WithMargin sets margin classes

func WithPadding

func WithPadding(padding string) BoxOption

WithPadding sets padding classes

func WithRounded

func WithRounded(rounded string) BoxOption

WithRounded sets border-radius classes

func WithShadow

func WithShadow(shadow string) BoxOption

WithShadow sets box-shadow classes

func WithWidth

func WithWidth(w string) BoxOption

WithWidth sets width classes

type BoxProps

type BoxProps struct {
	As         string // HTML tag (div, span, section, article, etc.)
	Class      string // custom classes
	P          string // padding
	M          string // margin
	Bg         string // background
	Rounded    string // border-radius
	Shadow     string // box-shadow
	W          string // width
	H          string // height
	Children   []templ.Component
	Attributes templ.Attributes
}

BoxProps defines properties for the Box component

type FlexOption

type FlexOption func(*FlexProps)

FlexOption is a functional option for configuring Flex

func FlexAlign

func FlexAlign(align string) FlexOption

FlexAlign sets the align-items

func FlexAttrs

func FlexAttrs(attrs templ.Attributes) FlexOption

FlexAttrs adds custom attributes

func FlexChildren

func FlexChildren(children ...templ.Component) FlexOption

FlexChildren adds child components

func FlexClass

func FlexClass(class string) FlexOption

FlexClass adds custom classes

func FlexDirection

func FlexDirection(direction string) FlexOption

FlexDirection sets the flex direction

func FlexGap

func FlexGap(gap string) FlexOption

FlexGap sets the gap

func FlexJustify

func FlexJustify(justify string) FlexOption

FlexJustify sets the justify-content

func FlexWrap

func FlexWrap(wrap string) FlexOption

FlexWrap sets the flex wrap

type FlexProps

type FlexProps struct {
	Direction  string // row, col, row-reverse, col-reverse
	Wrap       string // wrap, nowrap, wrap-reverse
	Justify    string // start, end, center, between, around, evenly
	Align      string // start, end, center, stretch, baseline
	Gap        string // gap size
	Class      string
	Children   []templ.Component
	Attributes templ.Attributes
}

FlexProps defines properties for the Flex component

type GridOption

type GridOption func(*GridProps)

GridOption is a functional option for configuring Grid

func GridAttrs

func GridAttrs(attrs templ.Attributes) GridOption

GridAttrs adds custom attributes

func GridChildren

func GridChildren(children ...templ.Component) GridOption

GridChildren adds child components

func GridClass

func GridClass(class string) GridOption

GridClass adds custom classes

func GridCols

func GridCols(cols int) GridOption

GridCols sets the number of columns

func GridColsLG

func GridColsLG(cols int) GridOption

GridColsLG sets columns at lg breakpoint

func GridColsMD

func GridColsMD(cols int) GridOption

GridColsMD sets columns at md breakpoint

func GridColsSM

func GridColsSM(cols int) GridOption

GridColsSM sets columns at sm breakpoint

func GridColsXL

func GridColsXL(cols int) GridOption

GridColsXL sets columns at xl breakpoint

func GridGap

func GridGap(gap string) GridOption

GridGap sets the gap

type GridProps

type GridProps struct {
	Cols       int    // number of columns
	ColsSM     int    // columns at sm breakpoint
	ColsMD     int    // columns at md breakpoint
	ColsLG     int    // columns at lg breakpoint
	ColsXL     int    // columns at xl breakpoint
	Gap        string // gap size
	Class      string
	Children   []templ.Component
	Attributes templ.Attributes
}

GridProps defines properties for the Grid component

type ProviderOption

type ProviderOption func(*ProviderProps)

ProviderOption is a functional option for configuring a Provider.

func WithProviderAttrs

func WithProviderAttrs(attrs templ.Attributes) ProviderOption

WithProviderAttrs adds custom HTML attributes to the provider wrapper.

func WithProviderChildren

func WithProviderChildren(children ...templ.Component) ProviderOption

WithProviderChildren sets the children that will have access to this provider.

func WithProviderClass

func WithProviderClass(class string) ProviderOption

WithProviderClass adds custom CSS classes to the provider wrapper.

func WithProviderDebug

func WithProviderDebug(debug bool) ProviderOption

WithProviderDebug enables debug mode for the provider.

func WithProviderHook

func WithProviderHook(name, code string) ProviderOption

WithProviderHook adds a lifecycle hook to the provider.

func WithProviderInit

func WithProviderInit(init string) ProviderOption

WithProviderInit sets initialization code for the provider.

func WithProviderMethods

func WithProviderMethods(methods string) ProviderOption

WithProviderMethods adds JavaScript methods to the provider.

func WithProviderName

func WithProviderName(name string) ProviderOption

WithProviderName sets the provider's unique identifier.

func WithProviderState

func WithProviderState(state map[string]any) ProviderOption

WithProviderState sets the provider's initial state.

type ProviderProps

type ProviderProps struct {
	// Name is the unique identifier for this provider (e.g., "sidebar", "theme")
	Name string

	// State is the initial state as a map of key-value pairs
	State map[string]any

	// Methods is raw JavaScript code defining provider methods
	Methods string

	// OnInit is JavaScript code that runs when the provider initializes
	OnInit string

	// Class adds custom CSS classes to the provider wrapper
	Class string

	// Attributes adds custom HTML attributes to the provider wrapper
	Attributes templ.Attributes

	// Children are the child components that will have access to this provider
	Children []templ.Component

	// Debug enables console logging for state changes
	Debug bool

	// Hooks define lifecycle hooks for the provider
	Hooks map[string]string
}

ProviderProps defines the configuration for a Provider component.

type TextOption

type TextOption func(*TextProps)

TextOption is a functional option for configuring Text

func TextAlign

func TextAlign(align string) TextOption

TextAlign sets the text alignment

func TextAs

func TextAs(tag string) TextOption

TextAs sets the HTML element type

func TextAttrs

func TextAttrs(attrs templ.Attributes) TextOption

TextAttrs adds custom attributes

func TextChildren

func TextChildren(children ...templ.Component) TextOption

TextChildren adds child components

func TextClass

func TextClass(class string) TextOption

TextClass adds custom classes

func TextColor

func TextColor(color string) TextOption

TextColor sets the text color

func TextSize

func TextSize(size string) TextOption

TextSize sets the text size

func TextWeight

func TextWeight(weight string) TextOption

TextWeight sets the font weight

type TextProps

type TextProps struct {
	As         string // HTML tag (p, span, div, h1-h6)
	Size       string // text size class
	Weight     string // font weight class
	Color      string // text color class
	Align      string // text alignment
	Class      string
	Children   []templ.Component
	Attributes templ.Attributes
}

TextProps defines properties for the Text component

Jump to

Keyboard shortcuts

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