uiToolset

package
v0.2.7 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 7 Imported by: 0

README

Toolset

Toolset of Infinite UI. It provides a JavaScript utility object, a Go minifier, and shared Go text and style helpers. Part of Infinite UI.

Style tokens

Shared token-to-class resolvers. Components accept a token and apply the matching Tailwind class. Each resolver takes the fallback class the caller wants when the token is empty or unknown. The fixed-value constants (BorderRadius*, Shape*, ShadowSize*, RingThickness*, PaddingSize*, and GapSize*) live here; color tokens stay free-form strings.

  • BackgroundColorClassResolver(backgroundColor, fallbackClass): returns bg- plus the token, or the fallback.
  • TextColorClassResolver(textColor, fallbackClass): returns text- plus the token, or the fallback.
  • BorderColorClassResolver(borderColor, fallbackClass): returns border- plus the token, or the fallback.
  • BorderRadiusTokenResolver(borderRadius, fallbackToken): returns the token when it is one of the shared BorderRadius* values, or the fallback token.
  • BorderRadiusClassResolver(borderRadius, fallbackClass): maps the shared BorderRadius* tokens to the class that matches the token name, so md returns rounded-md, or the fallback.
  • ShapeClassResolver(shape, fallbackClass): maps the shared ShapeCircular, ShapeRounded, and ShapeSquare tokens to rounded-full, rounded, and rounded-none, or the fallback.
  • ShadowClassResolver(shadowSize, fallbackClass): maps the shared ShadowSize* tokens none through xl to the shadow-* class, or the fallback.
  • RingThicknessClassResolver(ringThickness, fallbackClass): maps the shared RingThickness* tokens xs through xl to the ring-* thickness classes, or the fallback.
  • RingClassResolver(ringColor, ringThickness): returns the thickness and color classes, or an empty string when either is missing.
  • CompactRingClassResolver(ringColor, ringThickness): the thinner ring scale that tooltips use; returns ring-0.5 through ring-2.5 plus the color, defaults to ring-1 when the thickness is empty, and returns an empty string when the color is empty.
  • PaddingClassResolver(paddingSize, fallbackClass): maps the shared PaddingSize* tokens none through xl to the p-* class, or the fallback.
  • CompactPaddingClassResolver(paddingSize, fallbackClass): the tighter padding scale for compact chips and list items; maps the shared PaddingSize* tokens none through xl to the p-* class, or the fallback.
  • GapClassResolver(gapSize, fallbackClass): maps the shared GapSize* tokens none through xl to the gap-* class, or the fallback.
  • NonEmptyClassJoiner(classList): joins the non-empty entries with a single space. Use it to append optional class tokens without a += loop.

Component id

Shared helpers that build the DOM id a component exposes. Id lets one page hold several copies of the same component without colliding on element ids, radio group names, or input names.

ComponentIdPrefixGenerator mints a unique per-render id prefix from a component name and a counter. It serves components that render once and do not refresh, such as the tabs and the accordion.

  • NewComponentIdPrefixGenerator(componentName): creates a generator for one component name.
  • GenerateNext(): returns <componentName>-<n>, where n increments per call.

HashComponentIdParts hashes the inputs that identify a component. Components that refresh derive their id from this hash, so the id stays the same across the page render and every refresh render.

  • HashComponentIdParts(idParts...): returns a stable hash of the parts.

Text case

Shared text-case values and a class resolver. Components accept one of these values and apply the matching CSS transform.

  • TextCaseNone: no transform (the default).
  • TextCaseLower, TextCaseUpper, TextCaseCapitalize: lower, upper, or capitalized.
  • TextCaseClassResolver(textCase): returns the Tailwind class for a value, or an empty string for TextCaseNone and unknown values.

Tooltip

Shared pieces for hover tooltips. A component sets x-data to the tooltip Alpine component, puts x-ref="trigger" on the trigger, and renders the tooltip node inside <template x-teleport="body">. The tooltip lands on the document body with fixed coordinates, so a scroll container, a transformed track, or a modal cannot clip it.

  • TooltipAlpineStateOnce: the once-handle that embeds tooltipState.js. Render @uiToolset.TooltipAlpineStateOnce.Once() above every component that opens a tooltip.
  • TooltipSurfaceClassesResolver(TooltipSurfaceSettings{...}): returns the shared fixed-layer tooltip class string. Empty colors take the default bg-neutral-800/95 and text-neutral-50. The ring uses the compact ring scale. MinWidthClass, MaxWidthClass, MinHeightClass, and MaxHeightClass cap the tooltip size; MaxWidthClass defaults to max-w-96 so a long text wraps instead of running off screen.
  • TooltipPositionTop, TooltipPositionBottom, TooltipPositionLeft, TooltipPositionRight: the shared placement values every tooltip component passes to the Alpine component.

The Alpine component reads position (top, bottom, left, or right; empty means top), and exposes showTooltip() and hideTooltip() for the trigger's mouse and focus events. showTooltip() waits 200ms before it reveals, so a pointer that crosses the trigger does not flash the tooltip; hideTooltip() cancels a pending reveal. Keep every declaration of tooltipState.js inside the RegisterAlpineState callback: a second embed in a new render context must not redeclare a top-level const, which would abort the script with a SyntaxError.

JavaScript toolset

The JavaScript files live in src/import/toolset/. Include them with @uiImport.HeadTagsFullJs() or @uiImport.HeadTagsToolset().

Call the utilities through the UiToolset object.

  • UiToolset.CreateRandomPassword(options): creates a random password. options carries length (default 16), minLength (default 6), maxLength (default 64), and one include* flag per character class. With no arguments it keeps the 16-character behavior.
  • UiToolset.ResolveApiResponseDisplay(apiResponse, httpStatusCode): Resolves the message and outcome (success, partialSuccess, or error) from an Infinite API response envelope.
  • UiToolset.ToggleLoadingOverlay(): Toggles the loading overlay element with the id loading-overlay.
  • UiToolset.JsonAjax(method, url, payload, toast): Makes a JSON AJAX request. It shows the loading overlay and can display a toast from the response envelope.
  • UiToolset.RegisterAlpineState(stateFunction): Registers stateFunction to run on alpine:init, or immediately when Alpine is already initialized. Call Alpine.data() inside the callback. Use it instead of raw Alpine.data() calls so navigation does not register the same listener twice.
UiToolset.RegisterAlpineState(() => {
  Alpine.data("dataTable", (settingsScriptId) => ({ ... }));
});

When the Toast component is present, API responses can display messages with the recommended envelope:

{
    "status": 200,
    "readableMessage": "Operation completed successfully.",
    "body": {}
}

readableMessage is a string. body can hold any JSON value. Toast styling follows the HTTP status. A humanReadableMessage object with error, partialSuccess, and success fields is also supported. readableMessage takes precedence when it is not empty. Otherwise the matching humanReadableMessage field is used. A string body is the last fallback. The toast stays hidden when the response carries no message.

Go minifier

Based on esbuild, the minifier shrinks JavaScript and CSS before the page receives them. The MinifierSettings struct overrides the defaults when they break your code.

  • Minifier(MinifierSettings): Minifies JavaScript or CSS and returns a string pointer.
  • MinifierJs(unminifiedContent): Minifies JavaScript.
  • MinifierCss(unminifiedContent): Minifies CSS.
  • MinifierTemplate(MinifierSettings): Returns a templ.Component instead of a string.
  • MinifierTemplateJs(unminifiedContent): Wraps the result in a <script> tag.
  • MinifierTemplateCss(unminifiedContent): Wraps the result in a <style> tag.

Embed the source file and inject it minified:

//go:embed accountsState.js
var accountsAlpineState string
@uiToolset.MinifierTemplateJs(&accountsAlpineState)
@uiToolset.MinifierTemplateCss(&accountsCustomCss)

Documentation

Index

Constants

View Source
const (
	MinifierContentTypeJavaScript string = "application/javascript"
	MinifierContentTypeCss        string = "text/css"
)
View Source
const (
	BorderRadiusNone string = "none"
	BorderRadiusXs   string = "xs"
	BorderRadiusSm   string = "sm"
	BorderRadiusMd   string = "md"
	BorderRadiusLg   string = "lg"
	BorderRadiusXl   string = "xl"
	BorderRadius2xl  string = "2xl"
	BorderRadius3xl  string = "3xl"
	BorderRadiusFull string = "full"

	ShapeCircular string = "circular"
	ShapeRounded  string = "rounded"
	ShapeSquare   string = "square"

	ShadowSizeNone string = "none"
	ShadowSizeXs   string = "xs"
	ShadowSizeSm   string = "sm"
	ShadowSizeMd   string = "md"
	ShadowSizeLg   string = "lg"
	ShadowSizeXl   string = "xl"

	RingThicknessXs string = "xs"
	RingThicknessSm string = "sm"
	RingThicknessMd string = "md"
	RingThicknessLg string = "lg"
	RingThicknessXl string = "xl"

	PaddingSizeNone string = "none"
	PaddingSizeXs   string = "xs"
	PaddingSizeSm   string = "sm"
	PaddingSizeMd   string = "md"
	PaddingSizeLg   string = "lg"
	PaddingSizeXl   string = "xl"

	GapSizeNone string = "none"
	GapSizeXs   string = "xs"
	GapSizeSm   string = "sm"
	GapSizeMd   string = "md"
	GapSizeLg   string = "lg"
	GapSizeXl   string = "xl"
)
View Source
const (
	TextCaseNone       string = "none"
	TextCaseLower      string = "lower"
	TextCaseUpper      string = "upper"
	TextCaseCapitalize string = "capitalize"
)
View Source
const (
	TooltipPositionTop    string = "top"
	TooltipPositionBottom string = "bottom"
	TooltipPositionLeft   string = "left"
	TooltipPositionRight  string = "right"
)

Variables

View Source
var TooltipAlpineStateOnce = templ.NewOnceHandle(
	templ.WithComponent(MinifierTemplateJs(&tooltipAlpineState)),
)

Functions

func BackgroundColorClassResolver added in v0.2.5

func BackgroundColorClassResolver(backgroundColor, fallbackClass string) string

func BorderColorClassResolver added in v0.2.5

func BorderColorClassResolver(borderColor, fallbackClass string) string

func BorderRadiusClassResolver added in v0.2.5

func BorderRadiusClassResolver(borderRadius, fallbackClass string) string

func BorderRadiusTokenResolver added in v0.2.6

func BorderRadiusTokenResolver(borderRadius, fallbackToken string) string

func CompactPaddingClassResolver added in v0.2.5

func CompactPaddingClassResolver(paddingSize, fallbackClass string) string

func CompactRingClassResolver added in v0.2.5

func CompactRingClassResolver(ringColor, ringThickness string) string

func GapClassResolver added in v0.2.5

func GapClassResolver(gapSize, fallbackClass string) string

func HashComponentIdParts added in v0.2.5

func HashComponentIdParts(componentIdParts ...string) uint64

func Minifier

func Minifier(componentSettings MinifierSettings) *string

func MinifierCss

func MinifierCss(unminifiedContent *string) *string

func MinifierJs

func MinifierJs(unminifiedContent *string) *string

func MinifierTemplate

func MinifierTemplate(componentSettings MinifierSettings) templ.Component

func MinifierTemplateCss

func MinifierTemplateCss(unminifiedContent *string) templ.Component

func MinifierTemplateJs

func MinifierTemplateJs(unminifiedContent *string) templ.Component

func NonEmptyClassJoiner added in v0.2.6

func NonEmptyClassJoiner(classList []string) string

func PaddingClassResolver added in v0.2.5

func PaddingClassResolver(paddingSize, fallbackClass string) string

func RingClassResolver added in v0.2.5

func RingClassResolver(ringColor, ringThickness string) string

func RingThicknessClassResolver added in v0.2.5

func RingThicknessClassResolver(ringThickness, fallbackClass string) string

func ShadowClassResolver added in v0.2.5

func ShadowClassResolver(shadowSize, fallbackClass string) string

func ShapeClassResolver added in v0.2.5

func ShapeClassResolver(shape, fallbackClass string) string

func TextCaseClassResolver added in v0.2.2

func TextCaseClassResolver(textCase string) string

func TextColorClassResolver added in v0.2.5

func TextColorClassResolver(textColor, fallbackClass string) string

func TooltipSurfaceClassesResolver added in v0.2.5

func TooltipSurfaceClassesResolver(settings TooltipSurfaceSettings) string

Types

type ComponentIdPrefixGenerator added in v0.2.5

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

func NewComponentIdPrefixGenerator added in v0.2.5

func NewComponentIdPrefixGenerator(componentName string) *ComponentIdPrefixGenerator

func (*ComponentIdPrefixGenerator) GenerateNext added in v0.2.5

func (generator *ComponentIdPrefixGenerator) GenerateNext() string

type MinifierSettings

type MinifierSettings struct {
	ContentType       string
	UnminifiedContent *string
	MinifyWhitespace  bool
	MinifyIdentifiers bool
	MinifySyntax      bool
}

type TooltipSurfaceSettings added in v0.2.5

type TooltipSurfaceSettings struct {
	BackgroundColor string
	TextColor       string
	RingColor       string
	RingThickness   string

	// OptionalFields
	MinWidthClass  string
	MaxWidthClass  string
	MinHeightClass string
	MaxHeightClass string
}

Jump to

Keyboard shortcuts

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