diff --git a/.github/settings/README.md b/.github/settings/README.md index 928fd27..74430ad 100644 --- a/.github/settings/README.md +++ b/.github/settings/README.md @@ -1,21 +1,23 @@ # Owner-applied repository settings -This directory is a reviewable configuration, not proof that GitHub settings -are active. An owner with repository administration access should apply the -main ruleset once the contribution workflow is merged and its check names exist. +The **Reviewed main contributions** ruleset was applied and read back as active +on 2026-11-07 UTC ([view ruleset](https://github.com/Tend-Stack/TendUI/rules/26745168)). +This records the verified setup date; GitHub remains the source of truth for +current enforcement. Review the live rules before changing them. + +To update this existing ruleset after reviewing the JSON: ```sh -gh api --method POST repos/Tend-Stack/TendUI/rulesets --input .github/settings/main-ruleset.json +gh api --method PUT repos/Tend-Stack/TendUI/rulesets/26745168 --input .github/settings/main-ruleset.json ``` -Read existing rulesets first. If one already has this name, update it by its ID -with PUT rather than creating duplicates. The ruleset requires DCO and all CI, +Do not POST another copy. The ruleset requires DCO and all CI, one approving code-owner review, dismissal of stale approvals, approval of the latest push, resolved conversations and an up-to-date branch. It blocks force pushes and deletion. Repository admins have an explicit PR-only bypass for maintainer exceptions; record the reason in the PR and preserve contributor DCO. -Also enable GitHub private vulnerability reporting and web commit sign-off, +Separate settings still require verification: enable GitHub private vulnerability reporting and web commit sign-off, disable squash/rebase merges to preserve commit trailers, and allow merge commits. Require approval for fork workflows according to the organization's trust policy. Never run untrusted fork code on private self-hosted runners or with deployment diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 59e0495..f9c98cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,10 @@ Identify significant generated material or reused sources in the PR description. ## Workflow +Maintainers track both repositories in the shared [TendUI project](https://github.com/orgs/Tend-Stack/projects/2). +The board is currently private while publication review is completed; use this +repository's issues to propose work or report bugs. + 1. Fork the repository and create a focused branch from current `main`. 2. Make the smallest complete change; keep unrelated cleanup separate. 3. Add proportionate tests and update documentation for changed behavior. diff --git a/README.md b/README.md index 101bd5b..a754ce0 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,39 @@ -# TendUI - - - Tend UI + + Tend UI — Modern UI for Go -**Beautiful interfaces. No build pipeline.** +# Beautiful interfaces. No build pipeline. -Pure CSS. Semantic HTML. No Node.js, no npm, no bundled JavaScript. -First-class Go and templ support. +Pure CSS. Semantic HTML. **No Node.js, no npm, no bundled JavaScript.** +First-class Go and templ support, with styles embedded directly in your binary. -Use the stylesheet with any HTML stack. In Go, `//go:embed` bundles the CSS -inside your application: build and ship one executable, with no runtime asset -downloads. Typed templ components and optional HTMX attributes are ready when -you need them. +[Documentation](https://tendui.com/docs) · [Component catalog](https://tendui.com/catalog) · [Playground](https://tendui.com/playground) · [Examples](https://tendui.com/examples) -TendUI pairs original semantic CSS with composable Go components. Build -interfaces with native HTML, typed configuration, and application-owned behavior. +## Small pieces. A complete starting point. -See [migration notes](docs/tendui-migration.md) for the renamed Go module, CSS -namespace, and use with other HTML stacks. +| Build with | What you get | +| --- | --- | +| **Any HTML stack** | One semantic stylesheet for native elements, forms, cards and layouts. | +| **Go** | Embedded assets and a standard-library HTTP handler. Build and ship one executable. | +| **templ** | Typed component props and composable content slots; generated Go ships with the module. | +| **Optional HTMX** | Explicit request attributes and page/fragment helpers. Your app supplies the runtime. | -## Install and run +Light, dark and system themes. Responsive layouts. Configurable spacing and +surfaces. Native interactions, keyboard access and bounded CSS motion. -Requires **Go 1.26+**, matching the pinned `github.com/a-h/templ v0.3.1100` -runtime. The asset package imports only the standard library; the components -have one direct Go dependency, templ. It is not a literally dependency-free -module, and this version does not support Go 1.21. +## Get a page running -Install the pinned TendUI preview (API changes remain possible before a stable release): +Use **Go 1.26+** and the pinned preview: ```sh go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2 ``` -Generated `*_templ.go` files ship with the module, so consumers do not need -the templ CLI to use these components from Go. - -A complete `main.go`: +The asset package uses only Go's standard library. Components use **templ +v0.3.1100** as their one direct runtime dependency. No generator is required to +consume the included components from Go; writing your own `.templ` files needs +the matching templ generator. ```go package main @@ -55,12 +51,10 @@ func main() { mux := http.NewServeMux() mux.Handle(tendui.AssetPath, tendui.AssetHandler()) page := components.Layout(components.LayoutProps{ - Title: "My Go app", - Language: "en", - Theme: components.ThemeLight, + Title: "Hello, TendUI", Language: "en", Theme: components.ThemeLight, }, components.Card(components.CardProps{ Body: components.Button(components.ButtonProps{ - Text: "Hello from Go", Primary: true, + Text: "Build something thoughtful", Primary: true, }), })) mux.Handle("/", templ.Handler(page)) @@ -68,497 +62,36 @@ func main() { } ``` -For a complete, tested Go/templ application, see [the quickstart](docs/quickstart.md) -and [`examples/quickstart`](examples/quickstart). To use CSS with any stack, see -[the plain HTML example](examples/html); Go and templ are optional for that path. - -Run the local demos, including a component playground, form lab, dashboard, -appearance editor, workspace, native interactions, inline editing, motion and surfaces, and theme endpoint: - -```sh -go run ./examples/basic -open -``` - -The `-open` flag opens `http://127.0.0.1:8080/playground` in your default Linux -browser. See [the demo guide](examples/site/README.md) for all pages and test -scenarios. The example deliberately blocks scripts with its -Content Security Policy. Theme switching and the form work with JavaScript -disabled. - -## Packages and assets - -```text -tendui.go embedded CSS handler -static/tendui.css readable semantic stylesheet -components/ - layout.templ document, title, language, theme, stylesheet - theme.templ native POST theme form with optional HTMX hooks - buttons.templ buttons and button-styled links - cards.templ article with optional header, body, footer - forms.templ forms, inputs, selects, checkboxes, grids - fields.templ composable labels, help/error bindings and input addons - controls.templ textareas, radio groups, switches, file inputs - feedback.templ alerts, badges, linked error summaries - shell.templ application header, sidebar, main content - overlays.templ native dialog and popover panels - navigation.templ breadcrumbs and bounded pagination - tables.templ data tables with column/row contracts and state slots - wayfinding.templ page tabs, progress steps and native disclosures - motion.templ typed one-shot entrance effects - states.templ loading placeholders, empty states and metrics - appearance.go typed settings, attributes, and CSS exports - *_templ.go generated Go, included for consumers -render/ buffered page/fragment HTTP responses -examples/site/ thirteen demo pages, searchable catalog, preference cookies and downloads -``` - -Mount `AssetHandler()` directly at `/tendui/static/`. Do **not** apply -`http.StripPrefix`: the handler already recognizes the complete path. It serves -only `tendui.css`, supports GET/HEAD, conditional ETag requests and byte ranges, -and returns 404 for directories and unknown assets. Revalidation prevents a -browser from keeping stale CSS across binary upgrades. See the -[asset delivery guide](docs/assets.md) for cache/proxy behavior, range requests -and verification scope. - -## Components - -All text is escaped by templ. Link and form URLs use templ's safe URL handling. -Keep URL destinations and HTMX endpoints application-controlled. Labels wrap -controls, so an ID is optional and repeated components do not invent duplicate -IDs. Supply meaningful labels for every input. - -```templ -@components.Form(components.FormProps{ - Action: "/profile", Method: components.MethodPost, - HxPost: "/profile", HxTarget: "#result", HxSwap: "innerHTML", - HxIndicator: "#saving", -}) { - @components.Grid(components.GridProps{}) { - @components.Input(components.InputProps{ - Name: "email", Label: "Email", Type: components.InputEmail, - Required: true, Autocomplete: "email", - }) - @components.Select(components.SelectProps{ - Name: "locale", Label: "Language", Value: "en", - Options: []components.Option{ - {Label: "English", Value: "en"}, - {Label: "Español", Value: "es"}, - }, - }) - } - @components.Checkbox(components.CheckboxProps{ - Name: "updates", Label: "Receive updates", - }) - @components.Button(components.ButtonProps{ - Text: "Save", Type: components.ButtonTypeSubmit, Primary: true, - }) - Saving… -} -
-``` - -`ButtonProps`, `LinkProps`, and `FormProps` expose `HxGet`, `HxPost`, `HxTarget`, -`HxSwap`, and `HxIndicator` directly. Set either HxGet or HxPost for a request, -not both. Empty attributes are omitted. `Button` defaults to `type="button"` -to avoid accidental submission; `Form` defaults to GET. Primary and Outline -can be combined. Raw buttons use the primary color by default. - -`CardProps` accepts `Header`, `Body`, and `Footer` components. Cards also accept -templ children after Body. Forms and grids use templ children. Pass ordinary -components rather than `templ.Raw` for untrusted content. -Cards can optionally override the page's shadow with `ElevationFlat`, -`ElevationSubtle`, `ElevationRaised`, or `ElevationFloating`. The zero value -inherits the page setting. See [surface elevation](docs/motion.md#elevation) -for theme tokens, nesting, outlined cards and accessibility behavior. - -## Appearance and application components - -Appearance choices are independent. The zero value preserves the original -Indigo, comfortable, rounded defaults: - -```go -appearance := components.Appearance{ - Preset: components.PresetForest, - Density: components.DensityCompact, - Corners: components.CornersSoft, - Typography: components.TypographySans, - TextSize: components.TextStandard, - Width: components.WidthWide, - Elevation: components.ElevationFlat, -} -page := components.Layout(components.LayoutProps{ - Title: "My workspace", - Theme: components.ThemeDark, - Appearance: appearance, -}, body) -``` - -Available presets: Indigo, Neutral, Forest, Rose. Choose comfortable/compact -spacing, rounded/nearly-square/soft corners, system sans/serif/monospace fonts, -standard/large text, narrow/standard/wide content, and flat/subtle/raised/floating shadows. -No font downloads are needed. Light/dark/system mode remains an independent -`LayoutProps.Theme` setting. +Follow the [tested Go/templ quickstart](docs/quickstart.md), or start with +[plain HTML and CSS](examples/html) with no Go dependency. Run the full local +showcase with `go run ./examples/basic -open`. -`Appearance.Normalize()` validates preferences and falls back to defaults. -`Attributes()` produces native `data-*` attributes for applications that own -their document shell. `CSS()` exports overrides referencing TendUI's canonical -tokens, so it **requires tendui.css** and must be loaded after it. CSS exports -configure appearance; keep light/dark/system mode on the root HTML element. -`LayoutProps.Head` accepts trusted application components after the base -stylesheet, for custom stylesheet links or metadata. +## Explore your next step -Open `/settings` in the demo to preview, save, reset, and download appearance -settings. `/appearance.css` and `/appearance.go` export the selected settings. -The library owns no persistence; the example uses bounded, validated preference -cookies. Query previews take precedence over saved preferences without changing -them. Cookie data never controls authorization or application behavior. - -New components: - -| Component | Contract | +| I want to… | Start here | | --- | --- | -| `Badge(BadgeProps)` | Text plus neutral/info/success/warning/danger tone | -| `Alert(AlertProps)` | Title, message, optional children; `Live` opts into announcements | -| `ErrorSummary(ErrorSummaryProps)` | Error messages linked to application-supplied field IDs | -| `Textarea(TextareaProps)` | Label, value, rows, maximum length, required/disabled/read-only/error states | -| `RadioGroup(RadioGroupProps)` | Native fieldset/legend and labeled options sharing one name | -| `Switch(SwitchProps)` | Native checkbox with switch semantics and keyboard interaction | -| `FileInput(FileInputProps)` | Native file chooser with accept/multiple/required states | -| `AppShell(AppShellProps)` | Brand, actions, sidebar links, optional footer, and one main landmark | - -`CheckboxProps` now also supports `Invalid` and `DescribedBy`. Use -`FormProps{Method: components.MethodPost, Multipart: true}` for actual uploads. -Applications must validate file types, bound request sizes, and handle storage; -the `accept` attribute is only a browser hint. The playground file picker does -not upload data. - -Static alerts do not create live regions. Set `Live: true` for inserted feedback: -danger uses `role="alert"`; other tones use `role="status"`. These attributes -do not guarantee announcements on a full page navigation, so visible error -summaries and linked field errors remain available. - -Use `AppShell` as the body inside `Layout`, with page content as templ children. -It owns the main landmark; do not nest another main or application shell inside -it. `MainID` defaults to `main` and connects the skip link. Sidebar navigation -uses a native disclosure that works on desktop and mobile without JavaScript. -See `/workspace` and `examples/site/workspace.templ` for a complete example. - -## Native interactions and navigation - -`Dialog` and `Popover` use native HTML. Supply a nonempty ID with no whitespace; -invalid IDs return a render error. IDs must be unique within the document, and -their `-title` and `-description` suffixes are reserved for accessible labels. - -```templ -@components.Button(components.ButtonProps{ - Text: "Review request", - CommandFor: "review-request", - Command: components.DialogShowModal, -}) -@components.Dialog(components.DialogProps{ - ID: "review-request", Title: "Review request", - Description: "Check the details before submitting.", -}) { - @components.Form(components.FormProps{ - Action: "/requests/approve", Method: components.MethodPost, - }) { - @components.Button(components.ButtonProps{ - Text: "Approve", Type: components.ButtonTypeSubmit, - }) - } -} -``` - -Keep dialogs outside other forms. The dialog includes a native `method="dialog"` -close form and initially focuses that non-destructive close control. Closing a -dialog does not submit an application request; use a separate normal form for -an action that must reach Go. Native opener/closer fields on Button always force -`type="button"`, even if Type was set to submit. Unsupported command values -produce an inert button. Do not combine native commands and HTMX requests on -the same control. - -Modal opening uses the newer `commandfor`/`command="show-modal"` attributes. -Provide an ordinary-page alternative for unsupported browsers, as `/interactions` -does. No JavaScript fallback is injected. See the browser's -[native dialog commands](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#modal_dialogs_using_invoker_commands). - -For popovers, use `ButtonProps{PopoverTarget: "help"}` and -`Popover(PopoverProps{ID: "help", Title: "Help"})` with templ children. The default -automatic mode supports dismissal outside the panel; `Mode: PopoverManual` -requires an explicit close/toggle action. Both variants include a close button. -`PopoverAction` supports Toggle, Show, and Hide. Panels are non-modal, centered -by default, and do not claim ARIA menu semantics. Unsupported browsers may show -the content inline. See the [native popover attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover). - -`Breadcrumbs(BreadcrumbsProps{Items: ...})` renders ancestor links and a final, -non-linked current page. Separators are hidden from assistive technology. - -`Pagination(PaginationProps{Page: page, TotalPages: total, URLForPage: pageURL})` -renders normal links, current/disabled states, and a bounded page window with -ellipses. Zero/one-page results omit the navigation. Current page numbers are -clamped to range; a missing URL callback for multiple pages returns a render -error. The application supplies totals, page data, and URLs that retain its -filters. No database, router, or query convention is imposed by the component. -Labels can be localized through the props. - -The dashboard example demonstrates filter → sort → paginate on a request-owned -copy of sample records. Page URLs preserve search, status, sorting, page size, -and appearance query settings. Invalid or excessive page numbers are normalized; -empty results keep their recovery link. - -## Themes and the zero-JavaScript contract - -Set `LayoutProps.Theme` to `ThemeLight` or `ThemeDark` to emit the root -`data-theme` attribute. Leave it at `ThemeSystem` (the empty default) to follow -`prefers-color-scheme`. Override `--tendui-*` properties in your own CSS loaded -after TendUI. Dark tokens have no effect on explicitly light pages. - -`ThemeToggle()` renders a small native form that POSTs to `/api/theme/toggle`. -Place it **outside other forms**. You can pass `ThemeToggleProps` for a localized -label and your application's CSRF token. The consumer owns cookies, request -protection, routing, and page rendering; the library has no global theme state. - -The included endpoint alternates a validated `light`/`dark` cookie and returns -303 to the current demo when its same-origin Referer is available, otherwise to -the homepage. Cookies are HttpOnly, SameSite=Strict, and Secure over TLS; -the example uses Go's cross-origin request protection. Behind a TLS-terminating -proxy, configure your application's Secure-cookie policy explicitly. The first -example visit uses light so the server can deterministically toggle it; the -library's system theme remains available for applications that prefer it. - -The button preserves the requested `hx-post="/api/theme/toggle"`, -`hx-target="html"`, and `hx-swap="outerHTML"` attributes. These are inert without -HTMX. **HTMX itself is JavaScript** and is never included or loaded by TendUI. -Consumers that already use it can use the hooks without writing custom JS. - -A document root swap is not a reliable way to replace a page's root attributes -and head. The example detects `HX-Request: true` and sends **200 plus -`HX-Redirect` to the cleaned demo URL** after setting the cookie. This requests a -full navigation. Both native and HTMX paths remove the `theme` query parameter -so a previous preview cannot override the new cookie, while preserving other -settings. For HTMX, a validated same-origin `HX-Current-URL` takes precedence over -Referer; invalid values fall back to a validated Referer, then the homepage. -Only known demo pages are accepted. These headers control presentation, not access. -HTMX does not process its response headers on 3xx responses. See the upstream -[redirect header documentation](https://htmx.org/headers/hx-redirect/) and -[swap reference](https://htmx.org/attributes/hx-swap/). -The isolated browser consumer verifies this navigation with HTMX 2.0.11 in -Chromium, Firefox and WebKit. The runtime is a test dependency and is not bundled. - -## Full pages and optional HTMX fragments - -`render` is a standard-library-only package. Its small `Component` interface is -implemented by templ components; no adapter or additional dependency is needed. -Use the same route for ordinary navigation and partial updates: - -```go -import ( - "log" - "net/http" - - "github.com/Tend-Stack/TendUI/v2026/components" - "github.com/Tend-Stack/TendUI/v2026/render" -) - -func profileHandler(w http.ResponseWriter, r *http.Request) { - panel := components.Alert(components.AlertProps{Title: "Profile", Message: "Your profile is ready."}) - page := components.Layout(components.LayoutProps{Title: "Profile"}, panel) - w.Header().Set("Cache-Control", "private, no-store") - if err := render.HTML(w, r, http.StatusOK, page, panel); err != nil { - log.Printf("render profile: %v", err) - } -} -``` - -`HTML` chooses the fragment for `HX-Request: true`, but serves the full page for -history restoration or boosted navigation. A nil fragment always serves the page. -It preserves existing `Vary` values and adds the three headers that affect the -representation. Rendering is buffered so a component error produces a generic -500 instead of partially written HTML; errors are returned for logging. HEAD -has no body, including on failures. After calling it, do not write another error -response: a render failure has already sent 500, and a transport failure may -have committed the response. Only the selected component is rendered. - -The helper leaves authentication, CSRF protection, cache policy, CSP and status -selection to the application. HTMX headers are presentation hints, never proof -of identity or permission. For cacheable pages, use representation-specific ETags. -Buffering is intended for bounded UI pages/fragments, not streaming responses. - -The [inline editing example](examples/site/editing.go) pairs native form actions -and link destinations with `HxPost`/`HxGet`, `HxTarget` and `HxSwap`. It returns -303 after a successful native POST and 200 with the updated panel for an HTMX -request. Invalid native submissions return 422. Invalid HTMX submissions return -200 **with field errors and no save**, because default HTMX does not swap 422 -responses. This policy is explicit in the example, not imposed by `render.HTML`. -See the upstream [response handling](https://htmx.org/docs/#response-handling), -[history](https://htmx.org/docs/#history) and -[caching](https://htmx.org/docs/#caching) documentation. - -The included demo remains JavaScript-free and blocks scripts with CSP. Its native -flow and HTTP fragment contract are testable separately. Applications enabling -HTMX must supply their own runtime and appropriate CSP; this project neither -loads nor bundles it. The example cookie is unsigned cosmetic sample data, -validated and escaped on every read. It is not an account/session implementation. - -## Motion, surfaces and useful states - -Cards now accept typed `Surface`, `Entry`, `Delay` and `HoverLift` options. -Choose tinted, outlined or gradient borders; use fade, rise or scale entrances. -`Reveal` wraps other content with the same entrance system. `Skeleton`, -`EmptyState` and `Stat` cover loading, recovery and metric presentation. - -`Appearance.Motion` accepts `MotionSystem` (default) or `MotionOff`. System mode -respects OS reduced motion. Off also disables hover displacement; CSS/Go exports -include the choice. Entrances run once, and loading decoration stops after three -cycles. All styling stays in the embedded CSS, with no runtime dependency. - -See [the motion guide](docs/motion.md), try `/motion`, and track the broader -[product roadmap](ROADMAP.md). See the [recorded browser results](docs/release-verification.md). - -## Data tables and navigation patterns - -`DataTable` provides semantic headers/row scopes, application-owned sort URLs, -cell component slots, striped/compact styles, and loading/empty states. The -Dashboard uses it for bidirectional sorting and native checkbox selection review. -`Tabs` supplies ordinary page navigation; `Steps` labels application-owned -progress; `Disclosure` uses native details/summary with optional grouping. - -See the [data and navigation guide](docs/data-navigation.md) and `/patterns` -for composition rules, working examples and validation boundaries. - -## Composable fields and multi-step forms - -`Field` pairs a raw control with its label, description and error through typed -`FieldProps.ControlAttributes()`. `InputGroup` adds text prefixes/suffixes while -preserving native control behavior. `ButtonProps.FormNoValidate` supports Back -actions that submit edits without native constraints blocking navigation. - -The `/wizard` project-brief example preserves draft values across Back/Continue, -checks all submitted fields on completion, and shows a validated preview without -creating or storing a project. See [the form guide](docs/forms.md) for composition, -validation and workflow ownership rules. - -The `/uploads` example connects the native file chooser to a bounded Go CSV -preview: download a sample, upload up to 64 KiB/50 rows, and inspect validated -results or line-specific errors. Uploaded content stays in request memory; -nothing is saved or imported. See the form guide for limits and HTTP behavior. - -## Accessibility and print - -Palette checks cover all built-in presets across page, card and subtle surfaces. -Print uses a neutral palette independent of the screen theme, with readable -outlined actions and native checkbox rendering for switches. See the -[accessibility and print guide](docs/accessibility.md) for the measured scope, -customization rules and browser checks still required. - -## Layout composition - -`Stack` provides vertical rhythm; `Cluster` wraps actions and other related items -into rows. Typed gap and alignment props use a density-aware spacing scale, -preserve document order, and compose with Grid, Card and native forms. Existing -CSS utilities retain their behavior. Try `/patterns?section=composition` or read -[the layout guide](docs/layout.md) for spacing tokens, semantics and examples. - -## Reading content - -`Prose` styles application-owned HTML for help pages, guides and release notes. -Choose a typed reading measure, use native headings/lists/code, and opt embedded -widgets out of prose typography. Try `/patterns?section=reading` and see the -[reading-content guide](docs/prose.md) for tokens, semantics and examples. - -## Inline icons - -The Icon component provides 24 original SVG drawings, compiled into Go and -rendered inline. They inherit text color and use no external image or font files. -Button and Link accept optional `IconBefore`, `IconAfter` and `AriaLabel` fields. -Icon-only actions require an explicit accessible name; decorative icons stay -hidden from assistive technology. Explore `/catalog/icon` and the -[icon guide](docs/icons.md) for sizes, composition and verification limits. - -## Searchable component catalog - -Open `/catalog` to browse all 37 public templ components by name, category or -usage notes. Each entry provides a preview, guidance and a downloadable `.templ` -recipe drawn from the same source compiled for that preview. Layouts open as -standalone pages to preserve document landmarks. Search and pagination use Go -requests; no client runtime or external assets are added. - -Catalog-only CSS and recipe source are embedded in the example executable, not -the library stylesheet. See [the catalog guide](docs/catalog.md) for recipe -adaptation, coverage checks and validation boundaries. - -## Maintaining the library - -Only contributors changing `.templ` files need the generator: - -```sh -go install github.com/a-h/templ/cmd/templ@v0.3.1100 -templ fmt . -templ generate -go test -race ./... -go vet ./... -``` - -Commit generated Go alongside its source. A normal Go build consumes CSS -directly through `go:embed`; CSS editing needs no asset build step. Test output -belongs under `tests/results/` and is ignored except for its placeholder. - -The Go-only developer tool also checks generated-source consistency, compiles -all catalog downloads independently, records benchmarks and builds the versioned -review executable. See [the development guide](docs/development.md) and -[measured performance](docs/performance.md): - -```sh -go run ./cmd/tendui-dev check -go run ./cmd/tendui-dev api -go run ./cmd/tendui-dev generated -go run ./cmd/tendui-dev recipes -go run ./cmd/tendui-dev bench -go run ./cmd/tendui-dev build -./tests/results/demos/tendui-demo -version -``` - -`check` already includes `api`; the separate command is useful during API review. -The checked-in declaration baseline catches changed props, constants, signatures -and method sets. See [API review and migration](docs/api-compatibility.md) for -intentional updates and the limits of this check. - -The [CI matrix](docs/ci.md) checks native Linux, macOS and Windows with Go 1.26.0 -and 1.27.3, plus a vulnerability scan. Browser checks cover Chromium, Firefox and -WebKit. These jobs must pass on the preview source; see -[preview release notes](docs/releases/2026.2.0-preview.2.md). The older -[release verification](docs/release-verification.md) documents the pre-rename -release only and is not evidence for the current preview. - -Versions follow `YEAR.RELEASE.FIX`, with SemVer prerelease suffixes for previews: -`v2026.2.0-preview.2`. Install the explicit tag; a preview is not a stable API promise. -Development builds use `git describe --tags --long --dirty`. - -Go treats 2026 as the semantic major version, so the module path ends in -`/v2026`. A new annual line such as 2027 will need `/v2027` and consumer import -updates. Fixes and previews on the 2026 line retain `/v2026`. - -## Project links - -- Source and issues: https://github.com/Tend-Stack/TendUI -- Website source: https://github.com/Tend-Stack/TendUI-web - -Fetch and integrate GitHub `main` before contributing. See `HANDOFF.md` for the -current development entry points and remaining release checks. +| Find a component and copy a recipe | [Live catalog](https://tendui.com/catalog) | +| Customize themes, forms and layouts | [Library guide](docs/library-guide.md) | +| Test interactions and appearance | [Playground](https://tendui.com/playground) · [Motion and surfaces](https://tendui.com/motion) | +| Work with Codex or Claude Code | [Agent setup](docs/agents.md) | +| Add TendUI to an application | [Integration guide](docs/tendui-migration.md) | +| Understand compatibility and verification | [API policy](docs/api-compatibility.md) · [Development guide](docs/development.md) | -## License +## Preview, with clear boundaries -MIT. See [LICENSE](LICENSE). +This is a preview; APIs may change before a stable release. Install a fixed +version and review [release notes](docs/releases/2026.2.0-preview.2.md) when +upgrading. Versions follow `YEAR.RELEASE.FIX`, with `-preview.N` for previews. +The Go module uses `/v2026` for the 2026 major-version line. -## Contributing +Your application owns routing, authentication, request protection, persistence +and sessions. HTMX is optional and requires application-supplied JavaScript. -See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, review and MIT + DCO sign-off. -Report vulnerabilities privately using [SECURITY.md](SECURITY.md); community -participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). +## Build with us -## Coding agents +Contributions are welcome under **MIT + DCO**. Contributors retain copyright; +a human reviews and signs off every contribution. Start with +[CONTRIBUTING.md](CONTRIBUTING.md), [open issues](https://github.com/Tend-Stack/TendUI/issues), +or the [coding-agent instructions](AGENTS.md). `CLAUDE.md` imports the same guidance. -Repository contributors should read [AGENTS.md](AGENTS.md); `CLAUDE.md` imports -the same instructions for Claude Code. For applications using TendUI, see -[the coding-agent guide](https://tendui.com/docs/agents) and merge its suggested -section into your own project instructions. +[Security reports](SECURITY.md) · [Code of conduct](CODE_OF_CONDUCT.md) · [MIT license](LICENSE) · [Website source](https://github.com/Tend-Stack/TendUI-web) diff --git a/ROADMAP.md b/ROADMAP.md index 28ed687..b37248c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -70,7 +70,7 @@ stable-URL cache contract and distinguishes in-process checks from live delivery The current preview has a complete documentation website, shared component catalog, examples and playground, plus passing native, security and browser verification. See [release verification](docs/release-verification.md) -for historical pre-rename evidence. Current preview details are in +for the published preview evidence. Preview details are in [preview release notes](docs/releases/2026.2.0-preview.2.md). The development tracks below describe continuing product work beyond this baseline. diff --git a/docs/accessibility.md b/docs/accessibility.md index 32f528e..20a3167 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -69,8 +69,8 @@ separate complete document when that is needed. Custom print styling can override TendUI's important print palette with matching important declarations in a later print stylesheet. Review the result with both background-graphics settings. The tests guard source rules and palette ratios; -the v2026.1.0 dashboard PDF was also reviewed for pagination, readable controls -and background omission. This does not establish every page/theme combination. +review rendered PDFs for pagination, readable controls and background omission. +Automated source checks do not establish every page/theme combination. ## Consumer review matrix diff --git a/docs/brand/README.md b/docs/brand/README.md index 0028295..3444a59 100644 --- a/docs/brand/README.md +++ b/docs/brand/README.md @@ -10,3 +10,11 @@ The website repository prepares the favicon, social previews and downloadable web assets. See `https://tendui.com/brand/github-social-preview.png` for the 1280 × 640 GitHub social preview image. Uploading a social preview in repository settings is separate from displaying the README logo. + +## README banners + +The light and dark README banners are copied unchanged from the owner-supplied +Tend UI Gopher Brand Kit. Source names, byte sizes and SHA-256 hashes are recorded +in [readme-banners.json](readme-banners.json). They are documentation assets and +are not embedded into the runtime stylesheet or website executable. The README +uses a `picture` element to follow the reader's preferred color scheme. diff --git a/docs/brand/readme-banner-dark.png b/docs/brand/readme-banner-dark.png new file mode 100644 index 0000000..ef92e1c Binary files /dev/null and b/docs/brand/readme-banner-dark.png differ diff --git a/docs/brand/readme-banner-light.png b/docs/brand/readme-banner-light.png new file mode 100644 index 0000000..86ca331 Binary files /dev/null and b/docs/brand/readme-banner-light.png differ diff --git a/docs/brand/readme-banners.json b/docs/brand/readme-banners.json new file mode 100644 index 0000000..ebee64d --- /dev/null +++ b/docs/brand/readme-banners.json @@ -0,0 +1,16 @@ +[ + { + "file": "readme-banner-dark.png", + "source": "03_web_and_social/illustrated-header-dark-1800x420.png", + "processing": "Copied unchanged from the owner-supplied Tend UI Gopher Brand Kit", + "sha256": "abfccb9cfa2169c767a213eb8fd57c07fe18984d95f917ec1731941c89293eea", + "bytes": 129454 + }, + { + "file": "readme-banner-light.png", + "source": "03_web_and_social/illustrated-header-light-1600x400.png", + "processing": "Copied unchanged from the owner-supplied Tend UI Gopher Brand Kit", + "sha256": "7a3e7ecc43532cb70d2127efefe2ddb4d9174c0af377d9d94f7d5a9d7f70ecd3", + "bytes": 123912 + } +] diff --git a/docs/ci.md b/docs/ci.md index 7638025..d69d6ed 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -124,5 +124,5 @@ assets. The workflow retains its reports for seven days. Published-tag consumer installation and browser checks are independent release gates. In-process HTTP tests and cross-compilation do not replace browser review. -See [release verification](release-verification.md) for the v2026.1.0 exact-commit +See [release verification](release-verification.md) for the supported preview's exact-commit native, security, browser and published-tag installation results. diff --git a/docs/library-guide.md b/docs/library-guide.md new file mode 100644 index 0000000..f50a648 --- /dev/null +++ b/docs/library-guide.md @@ -0,0 +1,455 @@ +# TendUI library guide + +[Back to the project](../README.md) · [Quickstart](quickstart.md) · [Live catalog](https://tendui.com/catalog) + +## Packages and assets + +```text +tendui.go embedded CSS handler +static/tendui.css readable semantic stylesheet +components/ + layout.templ document, title, language, theme, stylesheet + theme.templ native POST theme form with optional HTMX hooks + buttons.templ buttons and button-styled links + cards.templ article with optional header, body, footer + forms.templ forms, inputs, selects, checkboxes, grids + fields.templ composable labels, help/error bindings and input addons + controls.templ textareas, radio groups, switches, file inputs + feedback.templ alerts, badges, linked error summaries + shell.templ application header, sidebar, main content + overlays.templ native dialog and popover panels + navigation.templ breadcrumbs and bounded pagination + tables.templ data tables with column/row contracts and state slots + wayfinding.templ page tabs, progress steps and native disclosures + motion.templ typed one-shot entrance effects + states.templ loading placeholders, empty states and metrics + appearance.go typed settings, attributes, and CSS exports + *_templ.go generated Go, included for consumers +render/ buffered page/fragment HTTP responses +examples/site/ thirteen demo pages, searchable catalog, preference cookies and downloads +``` + +Mount `AssetHandler()` directly at `/tendui/static/`. Do **not** apply +`http.StripPrefix`: the handler already recognizes the complete path. It serves +only `tendui.css`, supports GET/HEAD, conditional ETag requests and byte ranges, +and returns 404 for directories and unknown assets. Revalidation prevents a +browser from keeping stale CSS across binary upgrades. See the +[asset delivery guide](assets.md) for cache/proxy behavior, range requests +and verification scope. + +## Components + +All text is escaped by templ. Link and form URLs use templ's safe URL handling. +Keep URL destinations and HTMX endpoints application-controlled. Labels wrap +controls, so an ID is optional and repeated components do not invent duplicate +IDs. Supply meaningful labels for every input. + +```templ +@components.Form(components.FormProps{ + Action: "/profile", Method: components.MethodPost, + HxPost: "/profile", HxTarget: "#result", HxSwap: "innerHTML", + HxIndicator: "#saving", +}) { + @components.Grid(components.GridProps{}) { + @components.Input(components.InputProps{ + Name: "email", Label: "Email", Type: components.InputEmail, + Required: true, Autocomplete: "email", + }) + @components.Select(components.SelectProps{ + Name: "locale", Label: "Language", Value: "en", + Options: []components.Option{ + {Label: "English", Value: "en"}, + {Label: "Español", Value: "es"}, + }, + }) + } + @components.Checkbox(components.CheckboxProps{ + Name: "updates", Label: "Receive updates", + }) + @components.Button(components.ButtonProps{ + Text: "Save", Type: components.ButtonTypeSubmit, Primary: true, + }) + Saving… +} +
+``` + +`ButtonProps`, `LinkProps`, and `FormProps` expose `HxGet`, `HxPost`, `HxTarget`, +`HxSwap`, and `HxIndicator` directly. Set either HxGet or HxPost for a request, +not both. Empty attributes are omitted. `Button` defaults to `type="button"` +to avoid accidental submission; `Form` defaults to GET. Primary and Outline +can be combined. Raw buttons use the primary color by default. + +`CardProps` accepts `Header`, `Body`, and `Footer` components. Cards also accept +templ children after Body. Forms and grids use templ children. Pass ordinary +components rather than `templ.Raw` for untrusted content. +Cards can optionally override the page's shadow with `ElevationFlat`, +`ElevationSubtle`, `ElevationRaised`, or `ElevationFloating`. The zero value +inherits the page setting. See [surface elevation](motion.md#elevation) +for theme tokens, nesting, outlined cards and accessibility behavior. + +## Appearance and application components + +Appearance choices are independent. The zero value preserves the original +Indigo, comfortable, rounded defaults: + +```go +appearance := components.Appearance{ + Preset: components.PresetForest, + Density: components.DensityCompact, + Corners: components.CornersSoft, + Typography: components.TypographySans, + TextSize: components.TextStandard, + Width: components.WidthWide, + Elevation: components.ElevationFlat, +} +page := components.Layout(components.LayoutProps{ + Title: "My workspace", + Theme: components.ThemeDark, + Appearance: appearance, +}, body) +``` + +Available presets: Indigo, Neutral, Forest, Rose. Choose comfortable/compact +spacing, rounded/nearly-square/soft corners, system sans/serif/monospace fonts, +standard/large text, narrow/standard/wide content, and flat/subtle/raised/floating shadows. +No font downloads are needed. Light/dark/system mode remains an independent +`LayoutProps.Theme` setting. + +`Appearance.Normalize()` validates preferences and falls back to defaults. +`Attributes()` produces native `data-*` attributes for applications that own +their document shell. `CSS()` exports overrides referencing TendUI's canonical +tokens, so it **requires tendui.css** and must be loaded after it. CSS exports +configure appearance; keep light/dark/system mode on the root HTML element. +`LayoutProps.Head` accepts trusted application components after the base +stylesheet, for custom stylesheet links or metadata. + +Open `/settings` in the demo to preview, save, reset, and download appearance +settings. `/appearance.css` and `/appearance.go` export the selected settings. +The library owns no persistence; the example uses bounded, validated preference +cookies. Query previews take precedence over saved preferences without changing +them. Cookie data never controls authorization or application behavior. + +New components: + +| Component | Contract | +| --- | --- | +| `Badge(BadgeProps)` | Text plus neutral/info/success/warning/danger tone | +| `Alert(AlertProps)` | Title, message, optional children; `Live` opts into announcements | +| `ErrorSummary(ErrorSummaryProps)` | Error messages linked to application-supplied field IDs | +| `Textarea(TextareaProps)` | Label, value, rows, maximum length, required/disabled/read-only/error states | +| `RadioGroup(RadioGroupProps)` | Native fieldset/legend and labeled options sharing one name | +| `Switch(SwitchProps)` | Native checkbox with switch semantics and keyboard interaction | +| `FileInput(FileInputProps)` | Native file chooser with accept/multiple/required states | +| `AppShell(AppShellProps)` | Brand, actions, sidebar links, optional footer, and one main landmark | + +`CheckboxProps` now also supports `Invalid` and `DescribedBy`. Use +`FormProps{Method: components.MethodPost, Multipart: true}` for actual uploads. +Applications must validate file types, bound request sizes, and handle storage; +the `accept` attribute is only a browser hint. The playground file picker does +not upload data. + +Static alerts do not create live regions. Set `Live: true` for inserted feedback: +danger uses `role="alert"`; other tones use `role="status"`. These attributes +do not guarantee announcements on a full page navigation, so visible error +summaries and linked field errors remain available. + +Use `AppShell` as the body inside `Layout`, with page content as templ children. +It owns the main landmark; do not nest another main or application shell inside +it. `MainID` defaults to `main` and connects the skip link. Sidebar navigation +uses a native disclosure that works on desktop and mobile without JavaScript. +See `/workspace` and `examples/site/workspace.templ` for a complete example. + +## Native interactions and navigation + +`Dialog` and `Popover` use native HTML. Supply a nonempty ID with no whitespace; +invalid IDs return a render error. IDs must be unique within the document, and +their `-title` and `-description` suffixes are reserved for accessible labels. + +```templ +@components.Button(components.ButtonProps{ + Text: "Review request", + CommandFor: "review-request", + Command: components.DialogShowModal, +}) +@components.Dialog(components.DialogProps{ + ID: "review-request", Title: "Review request", + Description: "Check the details before submitting.", +}) { + @components.Form(components.FormProps{ + Action: "/requests/approve", Method: components.MethodPost, + }) { + @components.Button(components.ButtonProps{ + Text: "Approve", Type: components.ButtonTypeSubmit, + }) + } +} +``` + +Keep dialogs outside other forms. The dialog includes a native `method="dialog"` +close form and initially focuses that non-destructive close control. Closing a +dialog does not submit an application request; use a separate normal form for +an action that must reach Go. Native opener/closer fields on Button always force +`type="button"`, even if Type was set to submit. Unsupported command values +produce an inert button. Do not combine native commands and HTMX requests on +the same control. + +Modal opening uses the newer `commandfor`/`command="show-modal"` attributes. +Provide an ordinary-page alternative for unsupported browsers, as `/interactions` +does. No JavaScript fallback is injected. See the browser's +[native dialog commands](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#modal_dialogs_using_invoker_commands). + +For popovers, use `ButtonProps{PopoverTarget: "help"}` and +`Popover(PopoverProps{ID: "help", Title: "Help"})` with templ children. The default +automatic mode supports dismissal outside the panel; `Mode: PopoverManual` +requires an explicit close/toggle action. Both variants include a close button. +`PopoverAction` supports Toggle, Show, and Hide. Panels are non-modal, centered +by default, and do not claim ARIA menu semantics. Unsupported browsers may show +the content inline. See the [native popover attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover). + +`Breadcrumbs(BreadcrumbsProps{Items: ...})` renders ancestor links and a final, +non-linked current page. Separators are hidden from assistive technology. + +`Pagination(PaginationProps{Page: page, TotalPages: total, URLForPage: pageURL})` +renders normal links, current/disabled states, and a bounded page window with +ellipses. Zero/one-page results omit the navigation. Current page numbers are +clamped to range; a missing URL callback for multiple pages returns a render +error. The application supplies totals, page data, and URLs that retain its +filters. No database, router, or query convention is imposed by the component. +Labels can be localized through the props. + +The dashboard example demonstrates filter → sort → paginate on a request-owned +copy of sample records. Page URLs preserve search, status, sorting, page size, +and appearance query settings. Invalid or excessive page numbers are normalized; +empty results keep their recovery link. + +## Themes and the zero-JavaScript contract + +Set `LayoutProps.Theme` to `ThemeLight` or `ThemeDark` to emit the root +`data-theme` attribute. Leave it at `ThemeSystem` (the empty default) to follow +`prefers-color-scheme`. Override `--tendui-*` properties in your own CSS loaded +after TendUI. Dark tokens have no effect on explicitly light pages. + +`ThemeToggle()` renders a small native form that POSTs to `/api/theme/toggle`. +Place it **outside other forms**. You can pass `ThemeToggleProps` for a localized +label and your application's CSRF token. The consumer owns cookies, request +protection, routing, and page rendering; the library has no global theme state. + +The included endpoint alternates a validated `light`/`dark` cookie and returns +303 to the current demo when its same-origin Referer is available, otherwise to +the homepage. Cookies are HttpOnly, SameSite=Strict, and Secure over TLS; +the example uses Go's cross-origin request protection. Behind a TLS-terminating +proxy, configure your application's Secure-cookie policy explicitly. The first +example visit uses light so the server can deterministically toggle it; the +library's system theme remains available for applications that prefer it. + +The button preserves the requested `hx-post="/api/theme/toggle"`, +`hx-target="html"`, and `hx-swap="outerHTML"` attributes. These are inert without +HTMX. **HTMX itself is JavaScript** and is never included or loaded by TendUI. +Consumers that already use it can use the hooks without writing custom JS. + +A document root swap is not a reliable way to replace a page's root attributes +and head. The example detects `HX-Request: true` and sends **200 plus +`HX-Redirect` to the cleaned demo URL** after setting the cookie. This requests a +full navigation. Both native and HTMX paths remove the `theme` query parameter +so a previous preview cannot override the new cookie, while preserving other +settings. For HTMX, a validated same-origin `HX-Current-URL` takes precedence over +Referer; invalid values fall back to a validated Referer, then the homepage. +Only known demo pages are accepted. These headers control presentation, not access. +HTMX does not process its response headers on 3xx responses. See the upstream +[redirect header documentation](https://htmx.org/headers/hx-redirect/) and +[swap reference](https://htmx.org/attributes/hx-swap/). +The isolated browser consumer verifies this navigation with HTMX 2.0.11 in +Chromium, Firefox and WebKit. The runtime is a test dependency and is not bundled. + +## Full pages and optional HTMX fragments + +`render` is a standard-library-only package. Its small `Component` interface is +implemented by templ components; no adapter or additional dependency is needed. +Use the same route for ordinary navigation and partial updates: + +```go +import ( + "log" + "net/http" + + "github.com/Tend-Stack/TendUI/v2026/components" + "github.com/Tend-Stack/TendUI/v2026/render" +) + +func profileHandler(w http.ResponseWriter, r *http.Request) { + panel := components.Alert(components.AlertProps{Title: "Profile", Message: "Your profile is ready."}) + page := components.Layout(components.LayoutProps{Title: "Profile"}, panel) + w.Header().Set("Cache-Control", "private, no-store") + if err := render.HTML(w, r, http.StatusOK, page, panel); err != nil { + log.Printf("render profile: %v", err) + } +} +``` + +`HTML` chooses the fragment for `HX-Request: true`, but serves the full page for +history restoration or boosted navigation. A nil fragment always serves the page. +It preserves existing `Vary` values and adds the three headers that affect the +representation. Rendering is buffered so a component error produces a generic +500 instead of partially written HTML; errors are returned for logging. HEAD +has no body, including on failures. After calling it, do not write another error +response: a render failure has already sent 500, and a transport failure may +have committed the response. Only the selected component is rendered. + +The helper leaves authentication, CSRF protection, cache policy, CSP and status +selection to the application. HTMX headers are presentation hints, never proof +of identity or permission. For cacheable pages, use representation-specific ETags. +Buffering is intended for bounded UI pages/fragments, not streaming responses. + +The [inline editing example](../examples/site/editing.go) pairs native form actions +and link destinations with `HxPost`/`HxGet`, `HxTarget` and `HxSwap`. It returns +303 after a successful native POST and 200 with the updated panel for an HTMX +request. Invalid native submissions return 422. Invalid HTMX submissions return +200 **with field errors and no save**, because default HTMX does not swap 422 +responses. This policy is explicit in the example, not imposed by `render.HTML`. +See the upstream [response handling](https://htmx.org/docs/#response-handling), +[history](https://htmx.org/docs/#history) and +[caching](https://htmx.org/docs/#caching) documentation. + +The included demo remains JavaScript-free and blocks scripts with CSP. Its native +flow and HTTP fragment contract are testable separately. Applications enabling +HTMX must supply their own runtime and appropriate CSP; this project neither +loads nor bundles it. The example cookie is unsigned cosmetic sample data, +validated and escaped on every read. It is not an account/session implementation. + +## Motion, surfaces and useful states + +Cards now accept typed `Surface`, `Entry`, `Delay` and `HoverLift` options. +Choose tinted, outlined or gradient borders; use fade, rise or scale entrances. +`Reveal` wraps other content with the same entrance system. `Skeleton`, +`EmptyState` and `Stat` cover loading, recovery and metric presentation. + +`Appearance.Motion` accepts `MotionSystem` (default) or `MotionOff`. System mode +respects OS reduced motion. Off also disables hover displacement; CSS/Go exports +include the choice. Entrances run once, and loading decoration stops after three +cycles. All styling stays in the embedded CSS, with no runtime dependency. + +See [the motion guide](motion.md), try `/motion`, and track the broader +[product roadmap](../ROADMAP.md). See the [recorded browser results](release-verification.md). + +## Data tables and navigation patterns + +`DataTable` provides semantic headers/row scopes, application-owned sort URLs, +cell component slots, striped/compact styles, and loading/empty states. The +Dashboard uses it for bidirectional sorting and native checkbox selection review. +`Tabs` supplies ordinary page navigation; `Steps` labels application-owned +progress; `Disclosure` uses native details/summary with optional grouping. + +See the [data and navigation guide](data-navigation.md) and `/patterns` +for composition rules, working examples and validation boundaries. + +## Composable fields and multi-step forms + +`Field` pairs a raw control with its label, description and error through typed +`FieldProps.ControlAttributes()`. `InputGroup` adds text prefixes/suffixes while +preserving native control behavior. `ButtonProps.FormNoValidate` supports Back +actions that submit edits without native constraints blocking navigation. + +The `/wizard` project-brief example preserves draft values across Back/Continue, +checks all submitted fields on completion, and shows a validated preview without +creating or storing a project. See [the form guide](forms.md) for composition, +validation and workflow ownership rules. + +The `/uploads` example connects the native file chooser to a bounded Go CSV +preview: download a sample, upload up to 64 KiB/50 rows, and inspect validated +results or line-specific errors. Uploaded content stays in request memory; +nothing is saved or imported. See the form guide for limits and HTTP behavior. + +## Accessibility and print + +Palette checks cover all built-in presets across page, card and subtle surfaces. +Print uses a neutral palette independent of the screen theme, with readable +outlined actions and native checkbox rendering for switches. See the +[accessibility and print guide](accessibility.md) for the measured scope, +customization rules and browser checks still required. + +## Layout composition + +`Stack` provides vertical rhythm; `Cluster` wraps actions and other related items +into rows. Typed gap and alignment props use a density-aware spacing scale, +preserve document order, and compose with Grid, Card and native forms. Existing +CSS utilities retain their behavior. Try `/patterns?section=composition` or read +[the layout guide](layout.md) for spacing tokens, semantics and examples. + +## Reading content + +`Prose` styles application-owned HTML for help pages, guides and release notes. +Choose a typed reading measure, use native headings/lists/code, and opt embedded +widgets out of prose typography. Try `/patterns?section=reading` and see the +[reading-content guide](prose.md) for tokens, semantics and examples. + +## Inline icons + +The Icon component provides 24 original SVG drawings, compiled into Go and +rendered inline. They inherit text color and use no external image or font files. +Button and Link accept optional `IconBefore`, `IconAfter` and `AriaLabel` fields. +Icon-only actions require an explicit accessible name; decorative icons stay +hidden from assistive technology. Explore `/catalog/icon` and the +[icon guide](icons.md) for sizes, composition and verification limits. + +## Searchable component catalog + +Open `/catalog` to browse all 37 public templ components by name, category or +usage notes. Each entry provides a preview, guidance and a downloadable `.templ` +recipe drawn from the same source compiled for that preview. Layouts open as +standalone pages to preserve document landmarks. Search and pagination use Go +requests; no client runtime or external assets are added. + +Catalog-only CSS and recipe source are embedded in the example executable, not +the library stylesheet. See [the catalog guide](catalog.md) for recipe +adaptation, coverage checks and validation boundaries. + +## Maintaining the library + +Only contributors changing `.templ` files need the generator: + +```sh +go install github.com/a-h/templ/cmd/templ@v0.3.1100 +templ fmt . +templ generate +go test -race ./... +go vet ./... +``` + +Commit generated Go alongside its source. A normal Go build consumes CSS +directly through `go:embed`; CSS editing needs no asset build step. Test output +belongs under `tests/results/` and is ignored except for its placeholder. + +The Go-only developer tool also checks generated-source consistency, compiles +all catalog downloads independently, records benchmarks and builds the versioned +review executable. See [the development guide](development.md) and +[measured performance](performance.md): + +```sh +go run ./cmd/tendui-dev check +go run ./cmd/tendui-dev api +go run ./cmd/tendui-dev generated +go run ./cmd/tendui-dev recipes +go run ./cmd/tendui-dev bench +go run ./cmd/tendui-dev build +./tests/results/demos/tendui-demo -version +``` + +`check` already includes `api`; the separate command is useful during API review. +The checked-in declaration baseline catches changed props, constants, signatures +and method sets. See [API review and migration](api-compatibility.md) for +intentional updates and the limits of this check. + +The [CI matrix](ci.md) checks native Linux, macOS and Windows with Go 1.26.0 +and 1.27.3, plus a vulnerability scan. Browser checks cover Chromium, Firefox and +WebKit. These jobs must pass on the preview source; see +[preview release notes](releases/2026.2.0-preview.2.md) and +[release verification](release-verification.md) for the published preview evidence. + +Versions follow `YEAR.RELEASE.FIX`, with SemVer prerelease suffixes for previews: +`v2026.2.0-preview.2`. Install the explicit tag; a preview is not a stable API promise. +Development builds use `git describe --tags --long --dirty`. + +Go treats 2026 as the semantic major version, so the module path ends in +`/v2026`. A new annual line such as 2027 will need `/v2027` and consumer import +updates. Fixes and previews on the 2026 line retain `/v2026`. diff --git a/docs/release-verification.md b/docs/release-verification.md index d31a8af..80ac9bb 100644 --- a/docs/release-verification.md +++ b/docs/release-verification.md @@ -1,53 +1,53 @@ -> Historical evidence from before the TendUI rename. The immutable tag and original module path are unchanged. +# TendUI preview verification -# GothUI 2026.1.0 verification +The supported preview is `v2026.2.0-preview.2`. Install it explicitly: -Verified on 2026-11-06. The immutable `v2026.1.0` tag points to -`2f622c95fbf71df942822d6697093b15fc8270db`. Later documentation-only commits -record these results without moving the release tag. +```sh +go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2 +``` + +## Published preview + +The following GitHub Actions runs passed for the published preview. These links +identify the tested revision directly; later documentation updates do not extend +those results to unrelated code changes. | Gate | Evidence | Result | | --- | --- | --- | -| Native Go compatibility and security | [Verify GothUI](https://github.com/Tend-Stack/GothUI/actions/runs/42211995225) | Six native Linux/macOS/Windows jobs on Go 1.26.0/1.27.3, plus the vulnerability job, passed at the tagged commit. | -| Real browser behavior | [Browser verification](https://github.com/Tend-Stack/GothUI/actions/runs/42211995320) | 53 passed, zero failed/flaky; one unsupported WebKit forced-color emulation check skipped. | -| Installation from the actual tag | [Release GothUI](https://github.com/Tend-Stack/GothUI/actions/runs/42213916698) | Fresh consumer downloaded `v2026.1.0`, passed `TestPublishedModule` and `go mod verify`, with no replacement or templ generation. | -| Release publication | [v2026.1.0](https://github.com/Tend-Stack/GothUI/releases/tag/v2026.1.0) | Published as a regular release after the tag-installation check passed. | -| Documentation website | [Website browser checks](https://github.com/Tend-Stack/GothUI-Web/actions/runs/42212696656), [native/container checks](https://github.com/Tend-Stack/GothUI-Web/actions/runs/42212696776) | Eight browser checks passed on desktop Chromium and mobile WebKit at website commit `14874b6286e1d5cd77fc2b1628814c60a5212ae6`; native tests and the actual container smoke test passed. | - -## Browser scope - -The pinned Playwright 1.65.0 suite runs Chromium, Firefox and WebKit on the -Ubuntu CI runner. Native flows use scripts-disabled contexts. The separate -HTMX fixture loads a local, test-only HTMX 2.0.11 runtime and verifies fragment -editing, validation recovery and theme redirects. Neither project bundles this -runtime into its shipped application. - -Axe checks WCAG 2 A/AA and 2.1 AA rules on all 36 component detail pages in both -themes. Application containment is checked at 320, 768 and 1920 pixels. Focused -checks cover keyboard skip/focus, popovers, native modal focus and background -inertness, reduced motion, explicit motion off, forced colors and print tokens. -The Chromium dashboard PDF was reviewed: readable monochrome controls and table, -no horizontal clipping, and headings stay with their following content. - -The website suite checks nine documentation/home/example routes, native theme -navigation, catalog discovery, keyboard skip navigation, reduced motion, mobile -containment, and the 1920-pixel maximum at a 2560-pixel viewport. Code examples -are keyboard-focusable for horizontal scrolling. Screenshots and PDFs are -review evidence, not pixel-by-pixel regression baselines. +| Native Go compatibility and security | [Verify TendUI](https://github.com/Tend-Stack/TendUI/actions/runs/42313429148) | Linux, macOS and Windows on Go 1.26.0 and 1.27.3; independent vulnerability check passed. | +| Browser behavior | [Browser verification](https://github.com/Tend-Stack/TendUI/actions/runs/42313429136) | 59 checks passed; one unsupported WebKit forced-color emulation check skipped. | +| Installation from the published tag | [Release verification](https://github.com/Tend-Stack/TendUI/actions/runs/42313876893) | Published-tag consumer and quickstart checks passed. | +| Release notes | [TendUI preview](https://github.com/Tend-Stack/TendUI/releases/tag/v2026.2.0-preview.2) | Prerelease; APIs may change before stable release. | + +On 2026-11-07, anonymous GitHub source access and the Go proxy module download +were checked again. The downloaded module checksum matched the website's pinned +`go.sum`. Both repositories are public; installation does not require a GitHub +token or private-module configuration. + +## Website and browser coverage + +The website consumes the pinned preview. Its [publication-polish browser run](https://github.com/Tend-Stack/TendUI-web/actions/runs/42337550182) +passed 20 checks on desktop Chromium and mobile WebKit. These include native +navigation, theme changes, onboarding downloads, containment, and light/dark +hover and keyboard-focus treatments. The [website build checks](https://github.com/Tend-Stack/TendUI-web/actions/runs/42337550151) +also passed for that tested revision. CI success is separate from deployment; +verify the served content after a website change is merged. + +The library suite exercises Chromium, Firefox and WebKit. Native flows use +scripts-disabled contexts. Optional HTMX integration tests use a local, +test-only runtime; TendUI does not bundle that runtime with the library. +Automated checks cover accessibility rules, keyboard behavior, native overlays, +reduced motion, motion opt-out, responsive containment and print styles. ## Limits and repeatability -These results do not certify WCAG conformance, every screen reader, every -physical device, every zoom level, or every consumer customization. WebKit -forced-color emulation is explicitly unsupported. Assembled applications still -need testing with their target assistive technology and supported devices. - -The repositories currently require GitHub authorization. Tag installation was -verified with authorized credentials, not anonymous public access. Consumers -need normal Git credentials and `GOPRIVATE=github.com/Tend-Stack/GothUI` while -that visibility remains in effect. +These checks do not certify WCAG conformance, every screen reader, every physical +device, every zoom level, or every consumer customization. Manual assistive +technology and physical-device reviews remain necessary. WebKit forced-color +emulation is unsupported in the test environment and is reported as skipped. -Workflows and fixtures are committed for repeatability. CI artifacts expire -after seven days; focused local reports and representative render artifacts live -under ignored `tests/results/`. No credentials or private infrastructure details -are included in the repository or retained test reports. +Workflows and fixtures are committed for repeatability. CI artifacts expire after +seven days; maintainers retain concise release evidence separately. Screenshots +and PDFs are review evidence, not pixel-by-pixel regression baselines. See +[development](development.md), [CI](ci.md), and [accessibility](accessibility.md) +for the checks to run when changing components or applications. diff --git a/docs/releases/2026.1.0.md b/docs/releases/2026.1.0.md deleted file mode 100644 index 0b061f6..0000000 --- a/docs/releases/2026.1.0.md +++ /dev/null @@ -1,51 +0,0 @@ -> Historical evidence from before the TendUI rename. The immutable tag and original module path are unchanged. - -# GothUI 2026.1.0 - -The first GothUI release provides semantic CSS and 36 typed templ components, -embedded directly in a Go binary. It includes 24 inline SVG icons, configurable -appearance, native form and navigation patterns, bounded CSS motion, and -full-page/fragment HTTP helpers. - -## Install - -```sh -go get github.com/Tend-Stack/GothUI/v2026@v2026.1.0 -``` - -Go 1.26 or newer is required. Components use templ v0.3.1100; generated Go is -included. The asset and rendering packages use only the standard library. -There is no Node/npm requirement for building an application, no external -asset compilation, and no bundled client-side JavaScript or HTMX runtime. - -Repository access follows GitHub visibility. Private installations require -normal GitHub credentials and `GOPRIVATE=github.com/Tend-Stack/GothUI`. - -## Explore - -- [Installation guide](https://gothui.com/docs/install) -- [Component catalog and recipes](https://gothui.com/catalog) -- [Interactive playground](https://gothui.com/playground) -- [Application examples](https://gothui.com/examples) - -## Validation and scope - -Publication requires native Linux/macOS/Windows checks on Go 1.26.0 and 1.27.3, -the vulnerability scan, and the Chromium/Firefox/WebKit browser suite at the -exact tagged commit. A separate consumer installs the actual GitHub tag and -tests rendering and embedded CSS without a local replacement or a generator -before these notes are published. - -Browser coverage includes native forms with scripts disabled, component-page -accessibility rules in both themes, narrow layouts, keyboard interactions, -reduced motion, print, and an isolated HTMX consumer. WebKit forced-color -emulation is unsupported and explicitly skipped. Automated rules and engine -tests do not certify accessibility conformance, all screen-reader behavior, -or physical-device compatibility; review assembled applications with their -target devices and assistive technologies. - -Applications own routing, authentication, persistence, request protection, and -any HTMX runtime. Native overlay commands require browser support; the examples -include ordinary-page fallbacks. `examples/site` is reusable demonstration code, -not part of the stable component API. Versions use `YEAR.RELEASE.FIX` and the -2026 module line uses `/v2026`. diff --git a/docs/releases/2026.2.0-preview.1.md b/docs/releases/2026.2.0-preview.1.md index 2aceeb3..fe51e00 100644 --- a/docs/releases/2026.2.0-preview.1.md +++ b/docs/releases/2026.2.0-preview.1.md @@ -1,8 +1,7 @@ # TendUI 2026.2.0-preview.1 This is the first tagged preview under the TendUI module name, not a stable API -commitment. It introduces the renamed module and shared SiteHeader after the -historical pre-rename release. Old tags are not moved or rewritten. +commitment. It includes the TendUI module and shared SiteHeader component. ```sh go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.1 @@ -28,10 +27,5 @@ Automated browser checks include keyboard, reduced motion and accessibility rules; manual screen-reader and physical-device testing remain outstanding. One WebKit forced-color emulation case is unsupported and skipped. -The privacy review found no Gitleaks credential matches in reachable history. -Older library documentation still contains private infrastructure references. -Review or remediate that history before making the repository public. This -preview release does not change visibility or rewrite history. - -See [migration notes](../tendui-migration.md) for import, stylesheet, CSS token -and preference-cookie changes. Previous release reports are historical only. +See [integration guidance](../tendui-migration.md) for imports, stylesheet +setup, CSS tokens and preference cookies. diff --git a/docs/releases/2026.2.0-preview.2.md b/docs/releases/2026.2.0-preview.2.md index 136fc51..bdc57b3 100644 --- a/docs/releases/2026.2.0-preview.2.md +++ b/docs/releases/2026.2.0-preview.2.md @@ -2,8 +2,7 @@ This preview corrects the release consumer version check from preview.1, whose release publication was blocked by a stale test expectation. The earlier tag is -retained unchanged. This is not a stable API commitment. It introduces the renamed module and shared SiteHeader after the -historical pre-rename release. Old tags are not moved or rewritten. +retained unchanged. This is not a stable API commitment. It includes the TendUI module and shared SiteHeader component. ```sh go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2 @@ -29,10 +28,5 @@ Automated browser checks include keyboard, reduced motion and accessibility rules; manual screen-reader and physical-device testing remain outstanding. One WebKit forced-color emulation case is unsupported and skipped. -The privacy review found no Gitleaks credential matches in reachable history. -Older library documentation still contains private infrastructure references. -Review or remediate that history before making the repository public. This -preview release does not change visibility or rewrite history. - -See [migration notes](../tendui-migration.md) for import, stylesheet, CSS token -and preference-cookie changes. Previous release reports are historical only. +See [integration guidance](../tendui-migration.md) for imports, stylesheet +setup, CSS tokens and preference cookies. diff --git a/docs/tendui-migration.md b/docs/tendui-migration.md index d126486..bb47509 100644 --- a/docs/tendui-migration.md +++ b/docs/tendui-migration.md @@ -1,28 +1,26 @@ -# Moving to TendUI +# Integrating TendUI -TendUI is the new name of this library. Install the renamed preview explicitly: +Install the pinned preview: ```sh go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2 ``` -The historical `v2026.1.0` tag retains its original module path and is not a -TendUI installation target. It has not been rewritten. +Use `github.com/Tend-Stack/TendUI/v2026` for embedded assets and +`github.com/Tend-Stack/TendUI/v2026/components` for typed templ components. +The root Go package is `tendui`. Authoring your own templ files requires the +generator version listed in `go.mod`; consuming the shipped Go components does +not require generation. -Update Go imports to `github.com/Tend-Stack/TendUI/v2026` and the root package -identifier to `tendui`. Regenerate your own templ files after changing imports. -The component APIs remain available, with the additive `SiteHeader` component -and host-page options for the example handler. - -The asset endpoint is now `/tendui/static/tendui.css`. Prefer `tendui.AssetPath` +The asset endpoint is `/tendui/static/tendui.css`. Prefer `tendui.AssetPath` and `tendui.StylesheetURL` in Go code. CSS custom properties and prefixed utility -classes now use `tendui` rather than the previous prefix. Update application -overrides, downloaded recipes and appearance exports together with the stylesheet. +classes use `tendui`; keep application overrides and appearance exports aligned +with the stylesheet version you install. -The example site's preference cookies now use the `tendui_` prefix. Existing -demo preferences are not migrated; visitors can save their choices again. -The standalone examples retain their default appearance, while tendui.com -defaults to dark and shares its theme toggle across Home, Docs and the demos. +The demo site's preference cookies use the `tendui_` prefix. Consumer applications +own their preference storage and routing. The standalone examples retain their +default appearance; tendui.com defaults to dark and shares its theme toggle across +Home, Docs and the demos. ## CSS with any HTML stack