diff --git a/AGENTS.md b/AGENTS.md index 8292281..3267629 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9c98cf..e2f8063 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index a754ce0..242e017 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/accessibility.md b/docs/accessibility.md index 20a3167..b926fe9 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -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. diff --git a/docs/agents.md b/docs/agents.md index b3d703a..565cf57 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -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 diff --git a/docs/manual-accessibility.md b/docs/manual-accessibility.md new file mode 100644 index 0000000..5f837d5 --- /dev/null +++ b/docs/manual-accessibility.md @@ -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. diff --git a/examples/htmltemplate/README.md b/examples/htmltemplate/README.md new file mode 100644 index 0000000..d08ceca --- /dev/null +++ b/examples/htmltemplate/README.md @@ -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 . 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 `` 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. diff --git a/examples/htmltemplate/main.go b/examples/htmltemplate/main.go new file mode 100644 index 0000000..6e518a2 --- /dev/null +++ b/examples/htmltemplate/main.go @@ -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()) +} diff --git a/examples/htmltemplate/main_test.go b/examples/htmltemplate/main_test.go new file mode 100644 index 0000000..ee5e93c --- /dev/null +++ b/examples/htmltemplate/main_test.go @@ -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 := `">` + 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, "Hello, "><script>`, `value=""><script>`, `</script>`} { + 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) + } + } +} diff --git a/examples/htmltemplate/page.html b/examples/htmltemplate/page.html new file mode 100644 index 0000000..4312516 --- /dev/null +++ b/examples/htmltemplate/page.html @@ -0,0 +1,25 @@ + + + + + + Hello, TendUI — Go html/template + + + +
+

Hello, {{.Name}}.

+

Semantic HTML, Go templates, and embedded CSS. One executable.

+
+

Make yourself at home

+
+ + + Use a sample name. It appears in the URL and is not stored by this demo. + +
+ +
+
+ +