docs(skill): canonical vocabulary, trim SKILL.md, emphasize the partial loop#28
Merged
Conversation
…al loop
Establish canonical terms for recurring patterns (page, page group,
component, page component, partial, Props method / props struct,
handler method) with React/Next as cross-reference only, and apply
them consistently:
- Add Vocabulary and Request Lifecycle sections; retire Pattern A-D
letters in favor of named shapes
- Open §4 with the central partial-rendering loop: one method
reference drives composition id={ID(…)}, trigger
hx-target={IDTarget(…)}, and server sel.Is(…) (new Key Rule 14)
- Add §5c nested swap levels (Page → Content → Detail), upstreamed
and generalized; corrected to exact id match, not deepest-method
- Trim SKILL.md 612→486 lines: URL-validation listings move to
examples.md §14, lint details defer to reference.md §Lint Tool,
drop redundant code blocks, tersen Key Rules 5/10/11
- De-emphasize Content (naming convention, not framework concept);
drop local wrapper suggestion
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #28 +/- ##
=======================================
Coverage 94.66% 94.66%
=======================================
Files 15 15
Lines 1594 1594
=======================================
Hits 1509 1509
Misses 51 51
Partials 34 34 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Trim the Validating URLs section to two sentences: lint catches the static cases in CI; the boot-time validator and integration test in examples.md §14 are for what static analysis can't see.
…t placement Four pattern corrections from real-world usage: - Redirects: never http.Redirect from a handler — an HTMX XHR follows the 3xx and swaps the target page's body into the partial's swap target. Return a Redirect control-flow signal; WithErrorHandler sends HX-Redirect for HTMX, 303 otherwise (full wiring in examples.md §13; middleware does the check inline) - RenderComponent: pass a constructed component result, zero-value receiver for sibling pages (pages are stateless); the reflective method-expression form is reserved for DI-injected params, not 'when you don't have the receiver' - must(): only for plain-string contexts inside templ such as templ.Attributes values — attribute expressions take (string, error) - §4 loop example now shows all three sites in code, including the server-side sel.Is branch
…o _ discards must() stays only in its sanctioned spot: templ.Attributes values inside templ files. The middleware example handles the URLFor error properly, and the Props/template.Clone examples propagate errors instead of discarding them.
…odies http.Error now appears only as the documented anti-pattern (Rule 1) and one annotated middleware escape hatch outside structpages' error handling. The no-return API form shows a writeJSONError helper instead: text/plain fits neither an API client nor an HTMX swap.
Per the htmx 4 reference: HX-Location is ajax navigation (like a boosted link) and the right default within an htmx app; HX-Redirect forces a full browser load and is only for non-htmx endpoints or pages with different <head> content. Also document the 2xx requirement — htmx ignores response headers on 3xx.
Nested routes compose into one ServeMux pattern: duplicate wildcard
names panic at mount, and URLFor's map params couldn't distinguish two
{id}s. Examples across all three files now model specific names.
jackielii
added a commit
that referenced
this pull request
Jun 17, 2026
docs(skill): canonical vocabulary, trim SKILL.md, emphasize the partial loop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Establishes a canonical vocabulary for the structpages skill and applies it consistently through
SKILL.md, with React/Next terms used as cross-references only (Go wins where Go owns the concept:ServeHTTPis a handler method, not a "server action").Vocabulary
Partial rendering emphasized
MyPage.UserList) drives three agreeing sites — compositionid={ID(…)}, triggerhx-target={IDTarget(…)}, serversel.Is(…)— so renames can't desynchronize them. Backed by new Key Rule 14htmx.go, not "deepest method")Trims (SKILL.md 612 → 486 lines; it loads whole on every trigger)
url-attrallowlist there)Contentde-emphasized to what it is — a naming convention, not a framework concept