Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ source and existing tests before editing; preserve unrelated working-tree change
authentication, sessions, persistence and request protection. HTMX is optional,
requires JavaScript, and is supplied by the consuming application.
- `examples/quickstart/` is the tested Go/templ starting point; `examples/html/`
is the plain HTML alternative. `examples/site/` and `internal/recipes/` power
is the plain HTML alternative; `examples/htmltemplate/` uses standard-library
Go templates with embedded CSS and no templ imports. `examples/site/` and `internal/recipes/` power
the demos and catalog. Keep downloadable recipes and compiled previews aligned.
- `api/public.json` is a reviewed API baseline. Do not overwrite it just to make
a failing check pass; explain intentional API changes and migration impact.
Expand Down
3 changes: 1 addition & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,7 @@ 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.
Use this repository's issues to propose library work or report library bugs.

1. Fork the repository and create a focused branch from current `main`.
2. Make the smallest complete change; keep unrelated cleanup separate.
Expand Down
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,9 @@ func main() {
}
```

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
Follow the [tested Go/templ quickstart](docs/quickstart.md), use
[Go html/template](examples/htmltemplate) with embedded CSS and no templ components,
or start with [plain HTML and CSS](examples/html) with no Go dependency. Run the full local
showcase with `go run ./examples/basic -open`.

## Explore your next step
Expand Down
4 changes: 4 additions & 0 deletions docs/accessibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,3 +99,7 @@ both themes. Keyboard, native overlays, narrow layouts, reduced motion and print
have focused coverage. See [release verification](release-verification.md).
The broader consumer matrix above, especially screen-reader output, zoom and
physical devices, still needs review for each assembled application.

Use the [manual session checklist and result template](manual-accessibility.md)
to record real screen-reader and physical-device observations for the public site.
It starts with untested results and must not be treated as evidence of a pass.
1 change: 1 addition & 0 deletions docs/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ templ. HTMX is an optional enhancement, not a requirement. Share your installed
TendUI version, relevant route and component, and the behavior you want to test.
Use the [quickstart](quickstart.md) and inspect the component source at the
installed version; the online catalog may describe a newer version.
For standard-library Go templates, use the [html/template example](../examples/htmltemplate).

Installing a Go module does not install project instructions into your app.
Merge the following section into your own root `AGENTS.md`; preserve your existing
Expand Down
75 changes: 75 additions & 0 deletions docs/manual-accessibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Manual accessibility session

Use this checklist with the actual website and assistive technology. Automated
axe checks, screenshots and browser emulation do not establish screen-reader or
physical-device results. This document is a protocol, **not a completed audit**.
Track observations in [issue #4](https://github.com/Tend-Stack/TendUI/issues/4).

## Before starting

Record the date, tester, device model, OS/version, browser/version, screen reader
and version, input method, and settings such as zoom or reduced motion. Record
the website build and library revision from [the version endpoint](https://tendui.com/version).
For a local build, record the Git commit and library version. If the deployed
revision changes during the session, split the results rather than combining them.

Aim for a desktop keyboard/screen-reader pass and a physical phone pass with
VoiceOver or TalkBack. State the combinations actually tested. Use sample data
such as `Alex` and `alex@example.com`; do not record personal information in
public evidence. Agree on the combination in the issue first to avoid duplicate work.

## Short walkthrough

| Check | Steps | Observe and record |
| --- | --- | --- |
| Shared navigation | On [home](https://tendui.com/), navigate by landmarks and headings, follow Docs, open Examples and choose a demo. On desktop, use Tab and the skip link. | Meaningful names and order; main content reachable; menu state conveyed; focus visible and not obscured by the header. |
| Catalog | On [catalog](https://tendui.com/catalog), find the search field, enter `button`, submit, open the result and return. | Field label, search action and results understandable; component page heading discoverable after navigation; no lost keyboard access. A full page load need not announce as a live region. |
| Forms and errors | On [form lab](https://tendui.com/forms), submit empty fields normally, then use **Test server validation**. Follow an error-summary link, fix fields and submit valid sample data. | Required state, native error and server error text available; summary links reach the right control; descriptions and existing values preserved; success discoverable after navigation. Record what is spoken, not only what is visible. |
| Dialog | On [interactions](https://tendui.com/interactions), activate **Review demo request**. Navigate inside, close, reopen, then dismiss using the platform's available dismiss action. | Dialog name/content announced, modal focus stays inside, closing returns focus to the opener. Record unsupported native opener behavior separately and test **Use the ordinary-page confirmation**. |
| Popover | On the same page, activate **Show project details**, reach its contents, then close it. Repeat with **Show pinned note** and its explicit close control. | Content reachable in reading/focus order; a nonmodal popover does not trap focus; dismissal leaves a sensible focus position. Record inline fallback behavior if unsupported. |
| Theme | Toggle the header theme, revisit Docs and Catalog, and repeat a control check in both modes. | Toggle has a meaningful name; preference persists; text, focus and control state stay distinguishable. Do not infer contrast compliance from visual inspection alone. |
| Physical phone and zoom | On a real phone, repeat navigation, search and form recovery in portrait/landscape with larger text. On desktop, inspect Catalog and Playground at 200% and 400% zoom. | No clipped controls, unreachable content, overlapping header or unnecessary two-direction scrolling; native gestures and touch targets usable. Record actual device and zoom separately from emulation. |
| Reduced motion | Enable the OS reduced-motion setting, reload [motion](https://tendui.com/motion), then compare its explicit Off option. | All content remains present and usable; decorative entrances, lift and skeleton pulses stop. |

If a check fails, note the exact route, settings, steps, expected behavior and
actual observation. Include a short spoken-output transcript when useful. Link a
focused library or website bug instead of hiding the failure behind a broad pass.
Native browser support limitations should have a tested fallback; mark them
**Unsupported** rather than **Pass** if the primary behavior could not be tested.

## Copyable result record

Use **Not run**, **Pass**, **Fail** or **Unsupported** for each row. Keep the initial
Not run values until a person performs that check. An unsupported or failed check
needs notes and a fallback result; omit claims about combinations not tested.

```text
Date/time (UTC):
Tester:
Website build / exact source revision:
Library version / revision:
Device model and physical or emulated:
OS and version:
Browser and version:
Screen reader and version:
Input method / zoom / larger-text / motion settings:

Navigation: Not run
Catalog: Not run
Forms and error recovery: Not run
Dialog and focus return: Not run
Popover and fallback: Not run
Light/dark theme: Not run
Physical phone / zoom / reflow: Not run
Reduced motion: Not run

Observed spoken output and focus behavior:
Limitations / unsupported features:
Bug links and minimal reproduction steps:
Evidence links (no personal data):
Revision unchanged at end of session:
```

Keep the issue open until the agreed manual coverage has actual results and
failures have been triaged. This scoped review does not certify WCAG conformance
or accessibility of applications that consume TendUI.
43 changes: 43 additions & 0 deletions examples/htmltemplate/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Go html/template quickstart

Use TendUI with Go's standard-library `html/template` and ordinary semantic HTML.
This example imports only the asset package: no templ components, generator,
Node.js, npm or client JavaScript are needed. The HTML template and CSS both ship
inside the executable through `go:embed`.

From a checkout containing this example:

```sh
go run ./examples/htmltemplate
```

Open <http://127.0.0.1:8080>. Submit a sample name and try angle brackets or quotes:
`html/template` escapes it in the heading and input value. Keep user data as
ordinary strings; do not convert it to `template.HTML` or build markup by string
concatenation. The GET form places the name in the URL; use sample data only.
The demo follows system light/dark preference. Set `data-theme="light"` or
`data-theme="dark"` on `<html>` for an explicit theme.

To use it in your own directory, copy `main.go` and `page.html`, then initialize
and pin the library:

```sh
go mod init example.com/my-tendui-app
go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2
go run .
```

The recipe is new on main; it uses the asset API already present in that preview.
Use Go 1.26 or newer. `AssetHandler()` is mounted at `tendui.AssetPath` without
`StripPrefix`, and the template links `tendui.StylesheetURL` so the route and
stylesheet stay aligned. The handler renders to a buffer before sending headers
and serves only the root page and embedded assets.

Run its focused HTTP checks with `go test ./examples/htmltemplate`. To ship it,
build with `go build -o tendui-demo ./examples/htmltemplate`; the resulting binary
does not need `page.html` or CSS files beside it. Your application supplies
persistence, authentication and request protection when those are needed.

Choose the [Go/templ quickstart](../../docs/quickstart.md) for typed component
composition, or [plain HTML/CSS](../html) for a page without Go. All three use the
same semantic stylesheet.
53 changes: 53 additions & 0 deletions examples/htmltemplate/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
// A standard-library HTML application with TendUI's CSS embedded in its binary.
package main

import (
"bytes"
_ "embed"
"html/template"
"log"
"net/http"
"time"

"github.com/Tend-Stack/TendUI/v2026"
)

//go:embed page.html
var pageHTML string

var page = template.Must(template.New("page").Parse(pageHTML))

type pageData struct {
Name string
StylesheetURL string
}

func handler() http.Handler {
mux := http.NewServeMux()
mux.Handle(tendui.AssetPath, tendui.AssetHandler())
mux.HandleFunc("GET /{$}", func(w http.ResponseWriter, r *http.Request) {
name := r.URL.Query().Get("name")
if name == "" {
name = "Go developer"
}
// Render before writing headers so an error cannot send a partial page.
var body bytes.Buffer
if err := page.Execute(&body, pageData{Name: name, StylesheetURL: tendui.StylesheetURL}); err != nil {
http.Error(w, "Unable to render page", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "text/html; charset=utf-8")
w.Header().Set("X-Content-Type-Options", "nosniff")
_, _ = w.Write(body.Bytes())
})
return mux
}

func main() {
server := &http.Server{
Addr: "127.0.0.1:8080",
Handler: handler(),
ReadHeaderTimeout: 5 * time.Second,
}
log.Fatal(server.ListenAndServe())
}
66 changes: 66 additions & 0 deletions examples/htmltemplate/main_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
package main

import (
"net/http"
"net/http/httptest"
"net/url"
"strings"
"testing"

"github.com/Tend-Stack/TendUI/v2026"
)

func TestPageAndEmbeddedStylesheet(t *testing.T) {
h := handler()
w := httptest.NewRecorder()
h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/", nil))
if w.Code != http.StatusOK || w.Header().Get("Content-Type") != "text/html; charset=utf-8" {
t.Fatalf("page status/type: %d %q", w.Code, w.Header().Get("Content-Type"))
}
for _, want := range []string{"Hello, Go developer.", `href="` + tendui.StylesheetURL + `"`, `action="/" method="get"`, `for="name"`} {
if !strings.Contains(w.Body.String(), want) {
t.Errorf("missing page content: %s", want)
}
}
w = httptest.NewRecorder()
h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, tendui.StylesheetURL, nil))
if w.Code != http.StatusOK || !strings.HasPrefix(w.Header().Get("Content-Type"), "text/css") || !strings.Contains(w.Body.String(), "--tendui-primary") {
t.Fatalf("stylesheet unavailable: status %d, type %q", w.Code, w.Header().Get("Content-Type"))
}
}

func TestNameIsEscapedInTextAndAttributeContexts(t *testing.T) {
name := `"><script>alert('x')</script><input autofocus onfocus="alert(1)">`
w := httptest.NewRecorder()
handler().ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/?name="+url.QueryEscape(name), nil))
if w.Code != http.StatusOK {
t.Fatalf("status: %d", w.Code)
}
body := w.Body.String()
if strings.Contains(body, "<script") || strings.Count(body, "<input") != 1 || strings.Contains(body, `onfocus="`) {
t.Fatal("user input escaped its text or attribute context")
}
for _, want := range []string{`<h1>Hello, &#34;&gt;&lt;script&gt;`, `value="&#34;&gt;&lt;script&gt;`, `&lt;/script&gt;`} {
if !strings.Contains(body, want) {
t.Errorf("missing escaped user text: %s", want)
}
}
}

func TestRouteAndMethodBoundaries(t *testing.T) {
h := handler()
for _, tc := range []struct {
method, path string
status int
}{
{http.MethodGet, "/missing", http.StatusNotFound},
{http.MethodPost, "/", http.StatusMethodNotAllowed},
{http.MethodGet, tendui.AssetPath + "missing.css", http.StatusNotFound},
} {
w := httptest.NewRecorder()
h.ServeHTTP(w, httptest.NewRequest(tc.method, tc.path, nil))
if w.Code != tc.status {
t.Errorf("%s %s: got %d, want %d", tc.method, tc.path, w.Code, tc.status)
}
}
}
25 changes: 25 additions & 0 deletions examples/htmltemplate/page.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Hello, TendUI — Go html/template</title>
<link rel="stylesheet" href="{{.StylesheetURL}}">
</head>
<body>
<main class="container">
<h1>Hello, {{.Name}}.</h1>
<p>Semantic HTML, Go templates, and embedded CSS. One executable.</p>
<article>
<header><h2>Make yourself at home</h2></header>
<form action="/" method="get">
<label for="name">Display name</label>
<input id="name" name="name" value="{{.Name}}" aria-describedby="name-hint">
<small id="name-hint">Use a sample name. It appears in the URL and is not stored by this demo.</small>
<button type="submit">Update greeting</button>
</form>
<footer>Try angle brackets in your name: Go renders them as text.</footer>
</article>
</main>
</body>
</html>
Loading