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.
This commit is contained in:
slhx agent
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
Reference in New Issue
Block a user