primitives

package
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Jan 15, 2026 License: MIT Imports: 8 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 only import from the root forgeui package to avoid circular dependencies. They should not import from other component packages.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Box 

func Box(opts ...BoxOption) g.Node

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

func Center 

func Center(children ...g.Node) g.Node

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

func Container 

func Container(children ...g.Node) g.Node

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

func Flex 

func Flex(opts ...FlexOption) g.Node

Flex creates a flexbox container

func Grid 

func Grid(opts ...GridOption) g.Node

Grid creates a CSS Grid container

func HStack 

func HStack(gap string, children ...g.Node) g.Node

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

func Provider 

func Provider(opts ...ProviderOption) g.Node

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

The Provider pattern enables deeply nested components to access shared state without prop drilling. It uses Alpine.js's x-data for scoped state and events for cross-component communication.

Example: 

primitives.Provider(
    primitives.WithProviderName("sidebar"),
    primitives.WithProviderState(map[string]any{
        "collapsed": false,
        "mobileOpen": false,
    }),
    primitives.WithProviderMethods(`
        toggle() {
            this.collapsed = !this.collapsed;
            this.$dispatch('sidebar:toggled', { collapsed: this.collapsed });
        }
    `),
    primitives.WithProviderChildren(
        // child components can access provider via $provider.sidebar
    ),
)

Children can access provider state using: - Alpine expressions: $el.closest('[data-provider="sidebar"]').__x.$data.collapsed - Helper function: getProvider($el, 'sidebar') - Magic property (if registered globally): $provider.sidebar

func ProviderDispatch 

func ProviderDispatch(providerName, eventName, data string) string

ProviderDispatch returns an Alpine expression to dispatch a provider event. This is useful for cross-provider communication.

Example: 

alpine.XClick(primitives.ProviderDispatch("sidebar", "toggle", "{ open: true }"))

func ProviderMethod 

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

ProviderMethod returns an Alpine expression to call a provider method.

Example: 

alpine.XClick(primitives.ProviderMethod("sidebar", "toggle"))
// Generates: @click="$el.closest('[data-provider=\"sidebar\"]').__x.$data.toggle()"

func ProviderScriptUtilities 

func ProviderScriptUtilities() g.Node

ProviderScriptUtilities returns a script tag with helper functions for working with providers. Include this once in your page head or before Alpine.js initialization.

Provides global functions: - getProvider(el, name): Get provider state object - providerValue(el, name, key): Get specific provider state value - providerCall(el, name, method, ...args): Call provider method - providerDispatch(el, name, event, data): Dispatch provider event

func ProviderStack 

func ProviderStack(providers ...g.Node) g.Node

ProviderStack creates a nested stack of providers. This is useful when you need multiple providers in a component tree.

Example: 

primitives.ProviderStack(
    primitives.Provider(primitives.WithProviderName("theme"), ...),
    primitives.Provider(primitives.WithProviderName("sidebar"), ...),
    primitives.Provider(primitives.WithProviderName("auth"), ...),
)

func ProviderValue 

func ProviderValue(providerName, key string) string

ProviderValue returns an Alpine expression to access a provider's state. Use this in x-bind, x-show, x-text, etc. to access provider state.

Example: 

g.Attr("x-show", primitives.ProviderValue("sidebar", "collapsed"))
// Generates: x-show="$el.closest('[data-provider=\"sidebar\"]').__x.$data.collapsed"

func Spacer 

func Spacer() g.Node

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

func Text 

func Text(opts ...TextOption) g.Node

Text creates a typography primitive

func VStack 

func VStack(gap string, children ...g.Node) g.Node

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 ...g.Node) BoxOption

WithAttrs adds custom attributes

func WithBackground 

func WithBackground(bg string) BoxOption

WithBackground sets background classes

func WithChildren 

func WithChildren(children ...g.Node) BoxOption

WithChildren adds child nodes

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(p 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
	P        string // padding
	M        string // margin
	Bg       string // background
	Rounded  string // border-radius
	Shadow   string // box-shadow
	W        string // width
	H        string // height
	Children []g.Node
	Attrs    []g.Node
}

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 ...g.Node) FlexOption

FlexAttrs adds custom attributes

func FlexChildren 

func FlexChildren(children ...g.Node) FlexOption

FlexChildren adds child nodes

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  []g.Node
	Attrs     []g.Node
}

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 ...g.Node) GridOption

GridAttrs adds custom attributes

func GridChildren 

func GridChildren(children ...g.Node) GridOption

GridChildren adds child nodes

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 []g.Node
	Attrs    []g.Node
}

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 ...g.Node) ProviderOption

WithProviderAttrs adds custom HTML attributes to the provider wrapper.

func WithProviderChildren 

func WithProviderChildren(children ...g.Node) 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. Common hooks: "onMount", "onUpdate", "onDestroy"

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. Methods have access to 'this' (the provider state) and Alpine magic properties.

Example: 

WithProviderMethods(`
    toggle() {
        this.open = !this.open;
        this.$dispatch('provider:toggled', { open: this.open });
    }
`)

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 will be merged with the state object and have access to 'this'
	// Example: "toggle() { this.open = !this.open; }"
	Methods string

	// OnInit is JavaScript code that runs when the provider initializes
	// Useful for setup logic, event listeners, etc.
	OnInit string

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

	// Attrs adds custom HTML attributes to the provider wrapper
	Attrs []g.Node

	// Children are the child nodes that will have access to this provider
	Children []g.Node

	// 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 ...g.Node) TextOption

TextAttrs adds custom attributes

func TextChildren 

func TextChildren(children ...g.Node) TextOption

TextChildren adds child nodes

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 []g.Node
	Attrs    []g.Node
}

TextProps defines properties for the Text component

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.