uiStructural

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Sep 22, 2026 License: MIT Imports: 12 Imported by: 1

README

Structural

Structural layer of Infinite UI. It composes form and display components into page-level structures. Part of Infinite UI.

DataTable

@uiStructural.DataTable renders rows from your data and refreshes them from your server. Every sort, page, filter, or search change requests the URL template you provide. The table uses htmx.ajax when HTMX is present and falls back to fetch otherwise.

The component requires a server that answers each request. The static demo serves fixed pages, so sorting, filtering, and search update the request only. Serve it over HTTP; browsers block refresh requests from file:// pages.

@uiStructural.DataTable(uiStructural.DataTableSettings[Record]{
    Columns: columns,
    Rows:    records,
    QueryUrlTemplate: "/records?page=" + uiStructural.DataTableUrlPlaceholderPageNumber +
        "&sort=" + uiStructural.DataTableUrlPlaceholderSortKey +
        "&direction=" + uiStructural.DataTableUrlPlaceholderSortDirection +
        "&search=" + uiStructural.DataTableUrlPlaceholderSearch,

    // OptionalFields
    Filters:              filters,
    RowIdResolver:        func(record Record) string { return record.Id },
    RefreshOnEvents:      []string{"refresh:records-table"},
    InitialSortKey:       "name",
    InitialSortDirection: uiStructural.DataTableSortDirectionAsc,
})

Each column takes a Label, a CellRenderer function, and optional SortKey, Alignment, WidthPercent, width classes, and CellClass. Alignment takes a DataTableAlignment value: DataTableAlignmentLeft, DataTableAlignmentCenter, or DataTableAlignmentRight. HeaderTextCase takes a DataTableHeaderTextCase value: DataTableHeaderTextCaseLower (the default) or DataTableHeaderTextCaseUpper. Density takes a DataTableDensity value: DataTableDensityComfortable (the default) or DataTableDensityDense. InitialSortDirection takes a DataTableSortDirection value: DataTableSortDirectionAsc or DataTableSortDirectionDesc. ItemsPerPage and each entry in ItemsPerPageSizeChoices are DataTablePageSize values. Set PaginationAriaLabel when a page holds more than one table, so each pagination landmark keeps a unique name.

The Initial* fields seed the client state at render time: InitialFilterValues, InitialSearchQuery, InitialSortKey, and InitialSortDirection. The server renders the matching rows. PageNumber and ItemsPerPage also seed the client, but the component reads them to render the pagination readout.

HeaderClass adds classes to the header row, CellClass adds classes to one column's cells, RowClassResolver returns classes for each row from its data, and IsStriped adds a zebra stripe. These classes append to elements that already carry base utilities, so when two utilities set the same property the generated stylesheet order decides the winner, not the field order. A cell component that sets its own color wins over the row color, so use RowClassResolver for cells that leave the color to the row. When IsHeaderSticky is set, the sticky header paints its own background, so a HeaderClass background does not show. The table renders a default search box when the query URL template carries the search placeholder; pass SearchBox to replace it. SearchBoxAlignment takes a DataTableAlignment value and places the search box left (the default), center, or right within the toolbar. CheckboxShape accepts uiForm.CheckboxInputShapeSquare (the default), uiForm.CheckboxInputShapeRounded, or uiForm.CheckboxInputShapeCircular; CheckboxSize accepts the uiForm.CheckboxInputSize* values and defaults to the medium size; CheckboxCheckedColor and CheckboxUncheckedColor take a color token and default to secondary-500 and neutral-50/20.

The query URL template uses fixed placeholders. Build it from the DataTableUrlPlaceholder* constants and name the query keys:

QueryUrlTemplate: "/records?page=" + uiStructural.DataTableUrlPlaceholderPageNumber +
    "&size=" + uiStructural.DataTableUrlPlaceholderItemsPerPage +
    "&sort=" + uiStructural.DataTableUrlPlaceholderSortKey +
    "&direction=" + uiStructural.DataTableUrlPlaceholderSortDirection +
    "&q=" + uiStructural.DataTableUrlPlaceholderSearch

Filter values append to the URL as key=value pairs. Number and date ranges append as keyMin and keyMax. Empty values are omitted. Set QueryParamName on a filter to send a different query key.

The server response must contain one element with the data-ui-data-table attribute. The component swaps only that element, so the filter bar, search box, and selection stay in place.

Client state lives in the component root: pageNumber, itemsPerPage, sortKey, sortDirection, searchQuery, filterValues, and selectedRowIds. The search box and the bulk action slot bind to those paths.

RefreshOnEvents lists window event names. Dispatching one of them refreshes the table. This matches the form-to-display refresh pattern.

A failed refresh shows an inline error row with a retry button. A refresh in flight dims the table and disables the controls.

Pass filter keys, state paths, and the query URL template from code, never from request data. The component embeds them into client-side expressions. HeaderClass, CellClass, the RowClassResolver result, CheckboxCheckedColor, and CheckboxUncheckedColor become HTML class attributes, so keep untrusted data out of them too.

FilterBar

Standalone filter bar. It renders one editor per declared filter and shows active filters as removable chips.

@uiStructural.FilterBar(uiStructural.FilterBarSettings{
    Filters: []uiStructural.FilterSettings{
        {Key: "name", Label: "Name", Kind: uiStructural.FilterKindTextContains},
        {Key: "status", Label: "Status", Kind: uiStructural.FilterKindEnumSelect, Options: statusOptions},
        {Key: "cpu", Label: "CPU", Kind: uiStructural.FilterKindNumberRange},
    },
    ValuesTwoWayStatePath: "filterValues",

    // OptionalFields
    OnChangeFunc: "refreshTable()",
})
  • Kind accepts FilterKindTextContains, FilterKindEnumSelect, FilterKindNumberRange, or FilterKindDateRange.
  • ValuesTwoWayStatePath names a top-level property on the surrounding Alpine scope, for example filterValues.
  • Enum filters read Options. Range filters write {min, max} objects under the filter key.
  • A chip appears when its filter holds a value. The chip remove button clears that filter.
  • The clear-all button appears when any filter is active.
  • Set EnumSelectRadioGroupNamePrefix when a page holds more than one filter bar with the same enum keys. The prefix keeps each enum dropdown's radio group name unique. The DataTable prefixes it with the table id.

Pagination

Page controls with a readout, a page-number strip, and an items-per-page selector.

@uiStructural.Pagination(uiStructural.PaginationSettings{
    PageNumberTwoWayStatePath:   "pageNumber",
    ItemsPerPageTwoWayStatePath: "itemsPerPage",
    ItemsTotal:                  240,
    PagesTotal:                  24,

    // OptionalFields
    OnChangeFunc: "requestRefresh()",
})
  • The readout follows the state paths. It shows the current range and the total.
  • The strip shows the first page, the last page, the pages around the current one, and ellipses for gaps. The current page carries aria-current="page".
  • ItemsPerPageSizeChoices overrides the default page sizes.
  • Set ItemsPerPageInputName when a page holds more than one pagination bound to the same state path, so the two items-per-page radio groups stay independent.
  • IsDisabledOneWayStatePath disables every control while the path is truthy.
  • AriaLabel names the navigation landmark. Set a distinct label when a page holds more than one pagination.

Sidebar

Vertical navigation panel. It renders inline or fixed, and it can collapse or slide off canvas.

@uiStructural.Sidebar(uiStructural.SidebarSettings{
    MiddleContent: SidebarNavigation(),

    // OptionalFields
    HeaderContent:                 SidebarHeader(),
    FooterContent:                 SidebarFooter(),
    IsCollapsedTwoWayStatePath:    "isSidebarCollapsed",
    AttachmentMode:                uiStructural.SidebarAttachmentModeInline,
    Side:                          uiStructural.SidebarSideLeft,
})
  • BackgroundColor takes a full Tailwind class, for example "bg-neutral-800/50", unlike the color tokens other components take.
  • AttachmentMode accepts SidebarAttachmentModeInline or SidebarAttachmentModeFixed.
  • IsOffCanvas and IsOffCanvasTwoWayStatePath slide the panel over the content.
  • Width sets the expanded width.

Documentation

Overview

templ: version: v0.3.1020

templ: version: v0.3.1020

templ: version: v0.3.1020

templ: version: v0.3.1020

Index

Constants

View Source
const (
	DataTableUrlPlaceholderPageNumber    string = "{pageNumber}"
	DataTableUrlPlaceholderItemsPerPage  string = "{itemsPerPage}"
	DataTableUrlPlaceholderSortKey       string = "{sortKey}"
	DataTableUrlPlaceholderSortDirection string = "{sortDirection}"
	DataTableUrlPlaceholderSearch        string = "{search}"
)
View Source
const (
	FilterKindTextContains string = "textContains"
	FilterKindEnumSelect   string = "enumSelect"
	FilterKindNumberRange  string = "numberRange"
	FilterKindDateRange    string = "dateRange"
)
View Source
const (
	SidebarSideLeft  string = "left"
	SidebarSideRight string = "right"

	SidebarAttachmentModeInline string = "inline"
	SidebarAttachmentModeFixed  string = "fixed"
)

Variables

This section is empty.

Functions

func DataTable

func DataTable[Row any](componentSettings DataTableSettings[Row]) templ.Component

func DataTableDefaultEmptyState

func DataTableDefaultEmptyState() templ.Component

func DataTableDefaultSearchBox

func DataTableDefaultSearchBox() templ.Component

func FilterBar

func FilterBar(componentSettings FilterBarSettings) templ.Component

func Pagination

func Pagination(componentSettings PaginationSettings) templ.Component
func Sidebar(componentSettings SidebarSettings) templ.Component

Types

type DataTableAlignment

type DataTableAlignment string
const (
	DataTableAlignmentLeft   DataTableAlignment = "left"
	DataTableAlignmentCenter DataTableAlignment = "center"
	DataTableAlignmentRight  DataTableAlignment = "right"
)

type DataTableColumnSettings

type DataTableColumnSettings[Row any] struct {
	Label        string
	CellRenderer func(row Row) templ.Component

	// OptionalFields
	Alignment     DataTableAlignment
	CellClass     string
	MaxWidthClass string
	MinWidthClass string
	SortKey       string
	WidthPercent  uint8
}

type DataTableDensity

type DataTableDensity string
const (
	DataTableDensityComfortable DataTableDensity = "comfortable"
	DataTableDensityDense       DataTableDensity = "dense"
)

type DataTableHeaderTextCase

type DataTableHeaderTextCase string
const (
	DataTableHeaderTextCaseLower DataTableHeaderTextCase = "lower"
	DataTableHeaderTextCaseUpper DataTableHeaderTextCase = "upper"
)

type DataTablePageSize

type DataTablePageSize uint

type DataTableSettings

type DataTableSettings[Row any] struct {
	Columns []DataTableColumnSettings[Row]
	Rows    []Row

	// OptionalFields
	BulkActions             templ.Component
	CheckboxCheckedColor    string
	CheckboxShape           string
	CheckboxSize            string
	CheckboxUncheckedColor  string
	Density                 DataTableDensity
	EmptyState              templ.Component
	Filters                 []FilterSettings
	HeaderActions           templ.Component
	HeaderClass             string
	HeaderTextCase          DataTableHeaderTextCase
	Id                      string
	InitialFilterValues     map[string]any
	InitialSearchQuery      string
	InitialSortDirection    DataTableSortDirection
	InitialSortKey          string
	IsHeaderSticky          bool
	IsStriped               bool
	ItemsPerPage            DataTablePageSize
	ItemsPerPageSizeChoices []DataTablePageSize
	ItemsTotal              uint
	PageNumber              uint
	PaginationAriaLabel     string
	PagesTotal              uint
	QueryUrlTemplate        string
	RefreshDebounceMs       uint
	RefreshOnEvents         []string
	RowClassResolver        func(row Row) string
	RowIdResolver           func(row Row) string
	RowLabelResolver        func(row Row) string
	SearchBox               templ.Component
	SearchBoxAlignment      DataTableAlignment
}

type DataTableSortDirection

type DataTableSortDirection string
const (
	DataTableSortDirectionAsc  DataTableSortDirection = "asc"
	DataTableSortDirectionDesc DataTableSortDirection = "desc"
)

type FilterBarSettings

type FilterBarSettings struct {
	Filters               []FilterSettings
	ValuesTwoWayStatePath string

	// OptionalFields
	EnumSelectRadioGroupNamePrefix string
	OnChangeFunc                   string
}

type FilterSettings

type FilterSettings struct {
	Key   string
	Label string
	Kind  string

	// OptionalFields
	Options        []uiForm.SelectLabelValueOption
	QueryParamName string
}

type PaginationSettings

type PaginationSettings struct {
	PageNumberTwoWayStatePath   string
	ItemsPerPageTwoWayStatePath string
	ItemsTotal                  uint
	PagesTotal                  uint

	// OptionalFields
	AriaLabel                 string
	IsDisabledOneWayStatePath string
	ItemsPerPageInputName     string
	ItemsPerPageSizeChoices   []uint
	OnChangeFunc              string
}

type SidebarSettings

type SidebarSettings struct {
	MiddleContent templ.Component

	// OptionalFields
	HeaderContent                 templ.Component
	FooterContent                 templ.Component
	Width                         string
	BackgroundColor               string
	IsVisibleTwoWayStatePath      string
	IsCollapsed                   bool
	IsCollapsedTwoWayStatePath    string
	AttachmentMode                string
	AttachmentModeTwoWayStatePath string
	Side                          string
	SideTwoWayStatePath           string
	IsOffCanvas                   bool
	IsOffCanvasTwoWayStatePath    string
}

Jump to

Keyboard shortcuts

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