[jackielii]

Problem

A component rendered once per item (a table row, a card) had one id for every instance. Apps hand-built @{Page.Row |> id}-@{key} ids (EOS has 14). A request targeting one instance matched no component and swapped the whole Page into the row, and Props had no way to tell which item was wanted, so each keyed component needed its own route.

API (additive)

func Key(ctx context.Context, v any, key string) (string, error)       // "list-row--s3"
func KeyTarget(ctx context.Context, v any, key string) (string, error) // "#list-row--s3"
func (sp *StructPages) Key(v any, key string) (string, error)
func (sp *StructPages) KeyTarget(v any, key string) (string, error)
func KeyOf(t RenderTarget) string // "" when the target isn't keyed

key       = "github.com/jackielii/structpages.Key"
keytarget = "github.com/jackielii/structpages.KeyTarget"

<tr id={ Page.Row |> key(row.ID.String()) }>
  <button hx-get={ Page{} |> url } hx-target={ Page.Row |> keytarget(row.ID.String()) }>Reload</button>
</tr>

case t.Is(p.Row):
	id, err := uuid.Parse(structpages.KeyOf(t)) // client input: parse it, then authorise it

Like React's key, the key is the item's identity. Unlike React's, Props can read it back.

Behaviour

• Id format: the component's id, then --, then the key. Bytes outside [A-Za-z0-9-] are written as _XX, _ included. Only canonical escapes decode, so each key has exactly one id.
• Errors: an empty key, or a plain string in place of a component.
• Length budget: the key doesn't count toward it.
• Selectors: both htmx selectors share htmxTarget. A keyed id matches only exactly: the part before -- must be a generated id.
  • For one of the served page's components, the target Is that component and carries the key.
  • For another page's component or a standalone function, the target is unmatched but Is that component and carries the key.
  • Keyed ids skip the loose name and suffix passes, which would match a key ending in a component's name to that component.
• KeyOf: the RenderTarget interface is unchanged. The built-in targets hold the key in a field and gain no method, so Props' dynamic-type injection fills parameters as before. A custom target opts in with Key() string.

Compatibility

• Unkeyed ids: they match exactly as before.
• Hand-written ids of keyed form: this covers anything with a valid key after --, BEM-style card--active included. They now match only exactly, so one that used to match a component loosely renders Page.
• Function ids: a function's id takes its prefix from the last element of its import path. When that element has hyphens of its own (my-Lib kebab-cased to my--lib), the new idSegment collapses the runs and trims the ends. This changes the ids of functions in such packages only, so that generated ids never contain --.

Lint

structpages-lint checks Key/KeyTarget (package functions, sp. methods, and the key/keytarget filters) the same way it checks ID/IDTarget, for both idfor and region.

Testing

• Root module: the suite passes, and the new and changed functions are fully covered.
  • Round trips through both selectors, including keys with --, -, _ and non-ASCII bytes.
  • Keyed ids of shared regions (another page's component, a standalone function).
  • Exact-only matching, malformed and non-canonical keys, and a package whose path kebab-cases to --.
  • Unchanged injection for interface parameters asking for Key() string.
• tools/lint: adds Key fixtures to testdata/region (gsx) and testdata/render. TestRegion_Integration was already failing on main because 8 .templ findings are missing. It fails on exactly the same 8 here, and all the new gsx findings are present.
• Independent review: found three defects, all fixed with tests:
  • target injection for Key() interfaces;
  • -- in function ids from hyphenated package paths;
  • non-canonical escapes being accepted.

Release

After merge, release v0.11.0 and tools/lint/v0.1.19.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.72%. Comparing base (eb01e55) to head (bdc622b).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #41      +/-   ##
==========================================
+ Coverage   95.45%   95.72%   +0.26%     
==========================================
  Files          18       20       +2     
  Lines        1759     1870     +111     
==========================================
+ Hits         1679     1790     +111     
  Misses         48       48              
  Partials       32       32              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.