From 9dd8e4a9445b4718ad62397a1f4b9bb803ace889 Mon Sep 17 00:00:00 2001 From: slhx agent Date: Fri, 26 Jun 2026 08:18:21 +0200 Subject: [PATCH] docs(work): map html examples navigation slices Add a northstar and ready vertical slices for making html_examples start at an index, splitting implemented examples into focused pages, proving infinite-scroll by scrolling, and keeping smoke/docs/requirements aligned. --- .../NS-0004-html-examples-navigation.md | 52 ++++++++++++++++ .../SLICE-0013-html-examples-index-landing.md | 59 ++++++++++++++++++ ...CE-0014-html-examples-per-example-pages.md | 60 +++++++++++++++++++ ...CE-0015-infinite-scroll-standalone-page.md | 60 +++++++++++++++++++ ...ICE-0016-html-examples-smoke-and-readme.md | 55 +++++++++++++++++ ...17-html-examples-requirement-governance.md | 57 ++++++++++++++++++ 6 files changed, 343 insertions(+) create mode 100644 work/northstars/NS-0004-html-examples-navigation.md create mode 100644 work/slices/SLICE-0013-html-examples-index-landing.md create mode 100644 work/slices/SLICE-0014-html-examples-per-example-pages.md create mode 100644 work/slices/SLICE-0015-infinite-scroll-standalone-page.md create mode 100644 work/slices/SLICE-0016-html-examples-smoke-and-readme.md create mode 100644 work/slices/SLICE-0017-html-examples-requirement-governance.md diff --git a/work/northstars/NS-0004-html-examples-navigation.md b/work/northstars/NS-0004-html-examples-navigation.md new file mode 100644 index 0000000..9837a26 --- /dev/null +++ b/work/northstars/NS-0004-html-examples-navigation.md @@ -0,0 +1,52 @@ +--- +id: NS-0004 +type: northstar +status: ready +title: html_examples index and per-example pages +refs: + - AGENTS.md + - REQUIREMENTS.md + - examples/html_examples/README.md + - examples/html_examples/src/main.rs + - examples/html_examples/templates/app_shell.heml + - examples/html_examples/templates/gallery.heml + - hemx-xtask/src/main.rs +--- + +## Objective + +Make `examples/html_examples` behave like a copy-pasteable pattern gallery instead of one long demo page: `/` is an index with navigation, each implemented htmx-style pattern has a focused page using the exact htmx slug as the visible name, and `infinite-scroll` is proved by real scrolling rather than a click-only load-more control. + +## Authority + +- `AGENTS.md` says `examples/html_examples` is the copy-paste HTML pattern gallery for htmx-style examples, with exact htmx URL slugs visible and behavior translated to boring `.heml`, generated resources, and server-owned Rust state. req: htmx_equivalents/001 req: htmx_equivalents/003 req: htmx_equivalents/005 req: examples/005 req: examples/007 req: examples/012 req: page_swap/007 req: page_swap/008 +- `examples/html_examples/README.md` defines the pattern matrix, current implemented/deferred/refused boundaries, and the stable run/open command. +- `examples/html_examples/src/main.rs` and `templates/gallery.heml` currently render all implemented examples on `/`, including `infinite-scroll` as a revealed form with a visible `Reveal more rows` button. +- `hemx-xtask/src/main.rs` owns the focused browser smoke command that must prove no-reload dynamic interactions and the html_examples runtime path. req: test/006 + +## Close when + +- `/` is an index/landing page, not the long live example gallery. +- Implemented examples have focused routes/pages whose visible names preserve the htmx example slugs from the README matrix. +- `infinite-scroll` lives on its own focused page and is primarily exercised by scrolling to a sentinel, not by clicking a load-more button. +- README, smoke, and any requirement/doc changes keep the run command, pattern matrix, and verification authority honest. +- Any real product decision needed before implementation is captured as a blocked slice with the exact missing decision. + +## Verification + +- `workledger check` +- `workledger list` +- `cargo test -p hemx-html-examples` +- `cargo test -p hemx-xtask` +- `cargo run -p hemx-xtask -- html-examples-smoke` +- `redgate health --strict && redgate lint` + +## Non-goals + +- Do not create a router framework, docs generator, client component runtime, selector-targeting model, or second browser runner. +- Do not promote deferred/integration-owned/refused README rows unless a later slice proves the full vertical behavior. +- Do not hide click-to-load behavior inside `infinite-scroll`; keep click-triggered loading and scroll-triggered loading as distinct examples. + +## Evidence + +- Work mapping created at HEAD `379ed02`; implementation slices should update this section only when they complete or block. diff --git a/work/slices/SLICE-0013-html-examples-index-landing.md b/work/slices/SLICE-0013-html-examples-index-landing.md new file mode 100644 index 0000000..5587555 --- /dev/null +++ b/work/slices/SLICE-0013-html-examples-index-landing.md @@ -0,0 +1,59 @@ +--- +id: SLICE-0013 +type: slice +status: ready +parent: NS-0004 +title: Make html_examples root an index landing page +refs: + - AGENTS.md + - REQUIREMENTS.md + - examples/html_examples/README.md + - examples/html_examples/src/main.rs + - examples/html_examples/templates/app_shell.heml + - examples/html_examples/templates/gallery.heml + - hemx-xtask/src/main.rs +--- + +## Objective + +Change `http://127.0.0.1:3029/` from the long live gallery into a clear index page that links to implemented htmx-style examples by slug, so the starting page is navigation and orientation rather than every interaction mounted at once. + +## Authority + +- `AGENTS.md` requires exact htmx URL slugs to stay visible while translating behavior to boring `.heml`, generated resources, and server-owned Rust state. req: htmx_equivalents/001 req: htmx_equivalents/005 req: examples/007 +- `examples/html_examples/README.md` is the pattern matrix and run-command authority for implemented/deferred/refused example status. +- `examples/html_examples/src/main.rs` currently serves `/` as the mounted gallery page; `templates/app_shell.heml` and `templates/gallery.heml` own the visible root shape. + +## Close when + +- `/` shows a heading, short explanation, and navigation links for implemented examples from the README pattern matrix. +- Link text keeps exact htmx example slugs visible, including `click-to-edit`, `click-to-load`, `infinite-scroll`, `progress-bar`, and the other currently implemented rows. +- `/` does not eagerly mount live example forms/tables for the focused example pages. +- Native link behavior remains boring: links are real anchors to repo-owned same-origin pages; external htmx reference URLs, if shown, remain ordinary links. + +## Allowed files + +- `examples/html_examples/src/main.rs` +- `examples/html_examples/templates/app_shell.heml` +- `examples/html_examples/templates/gallery.heml` or a replacement index `.heml` template under `examples/html_examples/templates/` +- `examples/html_examples/README.md` only for run/navigation documentation if needed +- `hemx-xtask/src/main.rs` only to keep smoke coverage aligned with the index +- `REQUIREMENTS.md` only if the change creates or changes a durable product obligation + +## Verification + +- `cargo test -p hemx-html-examples` +- `cargo test -p hemx-xtask` +- `cargo run -p hemx-xtask -- html-examples-smoke` +- `redgate health --strict && redgate lint` if `REQUIREMENTS.md` changes +- Manual check if needed: run `cargo run -p hemx-html-examples`, open `http://127.0.0.1:3029/`, and confirm the root page is an index with real links rather than the long live gallery. + +## Non-goals + +- Do not implement or restructure every example page in this slice except the minimum route/link needed to prove index navigation. +- Do not add styling framework, docs generator, client-side router, or JavaScript navigation layer. +- Do not promote deferred/integration-owned/refused README rows into live links. + +## Evidence + +Ready; no implementation evidence yet. diff --git a/work/slices/SLICE-0014-html-examples-per-example-pages.md b/work/slices/SLICE-0014-html-examples-per-example-pages.md new file mode 100644 index 0000000..cd3f7f0 --- /dev/null +++ b/work/slices/SLICE-0014-html-examples-per-example-pages.md @@ -0,0 +1,60 @@ +--- +id: SLICE-0014 +type: slice +status: ready +parent: NS-0004 +title: Split implemented html_examples into focused per-example pages +refs: + - AGENTS.md + - REQUIREMENTS.md + - examples/html_examples/README.md + - examples/html_examples/src/main.rs + - examples/html_examples/templates/app_shell.heml + - examples/html_examples/templates/gallery.heml + - hemx-xtask/src/main.rs +--- + +## Objective + +Give each currently implemented html_examples pattern a focused page/route so contributors can open, copy, and test one pattern at a time while preserving generated-resource, server-owned-state behavior. + +## Authority + +- `AGENTS.md` says `examples/html_examples` is the copy-paste HTML pattern gallery for htmx-style examples and should keep exact htmx slugs visible without HTMX syntax, selector targeting, or user-authored browser JavaScript. req: htmx_equivalents/001 req: htmx_equivalents/005 req: examples/007 +- `REQUIREMENTS.md` page swap and navigation rows preserve real anchors/history semantics and progressive enhancement boundaries. req: page_swap/007 req: page_swap/008 +- Existing generated templates and handlers in `examples/html_examples/src/main.rs` own the implemented dynamic behavior. + +## Close when + +- Implemented README rows have stable same-origin pages with exact slug names visible in the URL or page heading: `click-to-edit`, `click-to-load`, `delete-row`, `edit-row`, `lazy-load`, `inline-validation`, `active-search`, `progress-bar`, `value-select`, `reset-user-input`, `update-other-content` where represented by existing behavior, and `infinite-scroll` owned by `SLICE-0015`. +- Each page renders only the relevant example content plus minimal navigation back to the index/neighboring examples. +- Existing handlers continue to use generated forms/resources and server-owned Rust state; route splitting must not introduce selector-targeted swaps, user-authored browser JavaScript, or duplicated app state truth. +- Existing implemented interactions continue to work without full-page reload during the interaction itself. + +## Allowed files + +- `examples/html_examples/src/main.rs` +- `examples/html_examples/templates/app_shell.heml` +- Existing or new `.heml` templates under `examples/html_examples/templates/` +- Existing partial templates under `examples/html_examples/templates/partials/` only if moving markup requires local template boundaries +- `examples/html_examples/README.md` for updated route/page documentation +- `hemx-xtask/src/main.rs` for focused smoke route coverage +- `REQUIREMENTS.md` only if route/page behavior changes durable obligations + +## Verification + +- `cargo test -p hemx-html-examples` +- `cargo test -p hemx-xtask` +- `cargo run -p hemx-xtask -- html-examples-smoke` +- `redgate health --strict && redgate lint` if `REQUIREMENTS.md` changes +- Manual spot check if needed: from `/`, open several example links directly and verify their heading/slug and dynamic behavior. + +## Non-goals + +- Do not implement deferred examples such as `bulk-update`, `modal-custom`, or `tabs-hateoas`. +- Do not replace axum routes with a framework-owned router abstraction. +- Do not combine click-triggered `click-to-load` semantics with scroll-triggered `infinite-scroll`; keep their page behavior distinct. + +## Evidence + +Ready; no implementation evidence yet. diff --git a/work/slices/SLICE-0015-infinite-scroll-standalone-page.md b/work/slices/SLICE-0015-infinite-scroll-standalone-page.md new file mode 100644 index 0000000..eba24a2 --- /dev/null +++ b/work/slices/SLICE-0015-infinite-scroll-standalone-page.md @@ -0,0 +1,60 @@ +--- +id: SLICE-0015 +type: slice +status: ready +parent: NS-0004 +title: Make infinite-scroll a real scroll-triggered standalone page +refs: + - AGENTS.md + - REQUIREMENTS.md + - examples/html_examples/README.md + - examples/html_examples/src/main.rs + - examples/html_examples/templates/gallery.heml + - hemx-xtask/src/main.rs +--- + +## Objective + +Move `infinite-scroll` out of the crowded root gallery context and prove it as a standalone page where scrolling to a sentinel triggers loading more rows, instead of relying on a click-oriented `Reveal more rows` interaction. + +## Authority + +- `examples/html_examples/README.md` labels `infinite-scroll` implemented and currently describes a revealed sentinel form that posts to the server-owned loading model. +- `templates/gallery.heml` currently renders `infinite-scroll` as one section in the root gallery with `data-hemx-revealed="true"` and a visible `Reveal more rows` button. +- `AGENTS.md` and `REQUIREMENTS.md` keep examples HTML-shaped, server-owned, progressive, and covered by focused browser smoke. req: htmx_equivalents/001 req: examples/012 req: test/006 + +## Close when + +- `/infinite-scroll` or the chosen same-origin slug route opens a focused page headed `infinite-scroll`. +- The page starts with enough vertical space/rows or sentinel placement that the user/browser can scroll to trigger the next batch. +- Loading more rows is primarily driven by the existing revealed/intersection behavior when the sentinel enters view; the smoke proves rows increase after scrolling, not after clicking a visible load-more button. +- A fallback submit control may exist only as progressive enhancement/recovery, but it must not be the primary proof path or make the example look like `click-to-load`. +- The server remains the owner of row count/state and returns generated keyed `infinite_row` effects; no selector-targeted rerendering or user-authored browser JavaScript is introduced. + +## Allowed files + +- `examples/html_examples/src/main.rs` +- `examples/html_examples/templates/app_shell.heml` +- `examples/html_examples/templates/gallery.heml` or a new focused infinite-scroll `.heml` template under `examples/html_examples/templates/` +- `examples/html_examples/templates/partials/loaded_row.heml` only if a shared row partial remains the local generated-resource boundary +- `examples/html_examples/README.md` only to keep the matrix proof anchor honest +- `hemx-xtask/src/main.rs` for the scroll-based smoke proof +- `REQUIREMENTS.md` only if the behavior changes durable obligations + +## Verification + +- `cargo test -p hemx-html-examples` +- `cargo test -p hemx-xtask` +- `cargo run -p hemx-xtask -- html-examples-smoke` +- `redgate health --strict && redgate lint` if `REQUIREMENTS.md` changes +- Manual check if needed: open the infinite-scroll page directly, scroll until the sentinel enters view, and confirm additional rows appear without clicking `Reveal more rows`. + +## Non-goals + +- Do not implement virtual scrolling, pagination framework, client cache, or stored DOM patches. +- Do not make `click-to-load` scroll-triggered; it should remain the separate click example. +- Do not add bespoke browser JavaScript for this example when the runtime's revealed behavior can carry the proof. + +## Evidence + +Ready; no implementation evidence yet. diff --git a/work/slices/SLICE-0016-html-examples-smoke-and-readme.md b/work/slices/SLICE-0016-html-examples-smoke-and-readme.md new file mode 100644 index 0000000..2d047df --- /dev/null +++ b/work/slices/SLICE-0016-html-examples-smoke-and-readme.md @@ -0,0 +1,55 @@ +--- +id: SLICE-0016 +type: slice +status: ready +parent: NS-0004 +title: Update html_examples smoke and README for index/page navigation +refs: + - AGENTS.md + - REQUIREMENTS.md + - examples/html_examples/README.md + - examples/html_examples/src/main.rs + - hemx-xtask/src/main.rs +--- + +## Objective + +Keep the public documentation and focused browser smoke aligned with the new html_examples structure so contributors can trust `/` as an index, focused pages as copyable examples, and `infinite-scroll` as a scroll-triggered interaction. + +## Authority + +- `AGENTS.md` identifies `cargo run -p hemx-xtask -- html-examples-smoke` as the focused repo-owned browser verification for the HTML pattern gallery and no-reload dynamic interactions. req: test/006 req: test/013 req: test/014 +- `examples/html_examples/README.md` is the public run command and pattern matrix. +- `hemx-xtask/src/main.rs` owns smoke scripts, diagnostics, and no-navigation/no-reload guards. + +## Close when + +- `examples/html_examples/README.md` still explains the run command and pattern matrix, but its proof anchors and navigation notes match the new index/per-page structure. +- `cargo run -p hemx-xtask -- html-examples-smoke` starts from the index, follows real example links/routes, and proves representative no-reload dynamic behavior on focused pages. +- The smoke includes a scroll-based infinite-scroll proof and keeps the existing no-navigation/no-reload guard for dynamic interactions. +- Smoke failures identify the named example route/path so a broken page split is easy to diagnose. + +## Allowed files + +- `examples/html_examples/README.md` +- `hemx-xtask/src/main.rs` +- `examples/html_examples/src/main.rs` only for testability hooks or route names already owned by implementation slices +- `REQUIREMENTS.md` only if smoke/documentation duties become durable requirements +- `AGENTS.md` only if the stable command guidance must change; otherwise do not touch it + +## Verification + +- `cargo test -p hemx-xtask` +- `cargo run -p hemx-xtask -- html-examples-smoke` +- `cargo test -p hemx-html-examples` if route names/templates changed in the same slice +- `redgate health --strict && redgate lint` if `REQUIREMENTS.md` or `AGENTS.md` changes + +## Non-goals + +- Do not add a second smoke runner, Playwright/Selenium dependency, `/tmp` smoke scripts, or untracked proof files. +- Do not use smoke updates to implement new examples. +- Do not weaken existing dynamic checks for click-to-edit, edit-row, validation, search, lazy-load, click-to-load, progress, value-select, reset, or revealed fallback. + +## Evidence + +Ready; no implementation evidence yet. diff --git a/work/slices/SLICE-0017-html-examples-requirement-governance.md b/work/slices/SLICE-0017-html-examples-requirement-governance.md new file mode 100644 index 0000000..2f16a97 --- /dev/null +++ b/work/slices/SLICE-0017-html-examples-requirement-governance.md @@ -0,0 +1,57 @@ +--- +id: SLICE-0017 +type: slice +status: ready +parent: NS-0004 +title: Keep html_examples requirements and docs aligned with page restructuring +refs: + - AGENTS.md + - REQUIREMENTS.md + - examples/html_examples/README.md +--- + +## Objective + +After the index, per-page routes, and true scroll-triggered infinite-scroll behavior are implemented, make the durable requirement/doc authority match the shipped behavior or explicitly record that requirements were unaffected. + +## Authority + +- `AGENTS.md` requires behavior changes to update `REQUIREMENTS.md` in the same change when durable product obligations, acceptance, safety/recovery behavior, or verification duties change. +- `REQUIREMENTS.md` already contains constraints for htmx-equivalent examples, enhanced page navigation, and browser smoke. req: htmx_equivalents/001 req: htmx_equivalents/003 req: htmx_equivalents/005 req: page_swap/007 req: page_swap/008 req: test/006 +- Workledger evidence should reflect implemented or blocked state once the restructuring slices complete. + +## Close when + +- If restructuring changes durable obligations for the pattern gallery, `REQUIREMENTS.md` is updated in the same change with stable requirement IDs and redgate-valid rows. +- If no durable obligation changes, the implementation handoff says `REQUIREMENT IMPACT: none` and explains why the existing `htmx_equivalents/*`, `examples/*`, `page_swap/*`, and `test/*` requirements already cover the behavior. +- README and workledger evidence point to the actual page/route/smoke proof rather than the old single-page gallery shape. +- No requirement row is added only to satisfy tooling; requirements remain checkable obligations, not implementation notes. + +## Allowed files + +- `REQUIREMENTS.md` +- `AGENTS.md` only if stable agent guidance truly changes +- `examples/html_examples/README.md` +- `work/northstars/NS-0004-html-examples-navigation.md` +- `work/slices/SLICE-0013-html-examples-index-landing.md` +- `work/slices/SLICE-0014-html-examples-per-example-pages.md` +- `work/slices/SLICE-0015-infinite-scroll-standalone-page.md` +- `work/slices/SLICE-0016-html-examples-smoke-and-readme.md` + +## Verification + +- `redgate list` +- `redgate refs` +- `redgate health --strict` +- `redgate lint` if `REQUIREMENTS.md` changes or the slice claims maintainability cleanup +- `workledger check && workledger list` + +## Non-goals + +- Do not perform broad redgate lint cleanup outside html_examples/page navigation requirements. +- Do not rewrite existing requirements just because wording can be polished. +- Do not add new product commitments for deferred/integration-owned/refused examples. + +## Evidence + +Ready; no implementation evidence yet.