Svelte promotion prep: add @svelte-notes annotations to all playground pages #96

New issue

Closed

opened 2026-03-27 00:34:01 +00:00 by forgejo_admin · 5 comments

forgejo_admin commented 2026-03-27 00:34:01 +00:00

Owner

Copy link

Type

Feature

Lineage

Part of public site evolution. Parent note: westside-playground-overhaul

Repo

forgejo_admin/westside-playground

User Story

As a dev agent promoting playground HTML to SvelteKit, I want each page to document exactly how its HTML/JS patterns translate to Svelte 5 so that promotion is mechanical copy-paste + rune wiring, not guesswork.

story:agent-promote

Context

The playground pages have @route, @auth, @nav, @api doc comments. These tell agents WHAT the page is. Missing: @state and @svelte-notes that tell agents HOW to translate it.

Every page needs annotations covering:

• @state — reactive state variables (e.g. program: 'kings' | 'queens')
• @api — expanded to show actual endpoint signatures the SvelteKit +page.server.ts will call
• @svelte-notes — line-by-line translation guide for non-obvious patterns

Translation patterns to document

HTML Playground	Svelte 5
localStorage.getItem('program')	let program = $state(localStorage.getItem('program') ?? 'kings')
localStorage.setItem('program', p)	$effect(() => localStorage.setItem('program', program))
document.body.classList.toggle('queens-active')	<svelte:body class:queens-active={program === 'queens'} />
data-program-content="kings" show/hide	{#if program === 'kings'}...{/if}
initKQToggle() in DOMContentLoaded	Gone — Svelte reactivity replaces it
Hardcoded mock data in HTML	+page.server.ts load function → basketball-api
initFilterList() search/filter	Svelte $derived filtering on reactive array
initTabs() tab switching	let activeTab = $state('roster') + {#if} blocks
initRegister() form logic	Svelte form bindings + $state
Mobile nav toggle JS	Svelte let menuOpen = $state(false)
Shared nav HTML duplicated across pages	+layout.svelte component (rendered once)
Shared footer HTML duplicated	+layout.svelte component

File Targets

Files to modify — ALL playground HTML pages. Add @state and @svelte-notes to the existing component doc comment block at the top of each file.

Example for tryouts.html:

<!--
  @route /tryouts
  @auth public
  @nav Tryouts (active)
  @api GET /api/tryouts — past tryout history (date, location, player_count, teams_formed)
  @api GET /api/tryouts/upcoming — next scheduled tryout or null
  @state program: 'kings' | 'queens' — persisted localStorage, shared across toggled pages
  @svelte-notes
    - KQ toggle → $state('kings') rune, $effect for localStorage sync
    - data-program-content → {#if program === 'kings'} / {:else} blocks
    - Past tryout cards → {#each tryouts as tryout} with server data
    - "View Teams" link → href="/teams?program={program}"
    - .queens-active → <svelte:body class:queens-active={program === 'queens'}>
    - Nav + Footer → inherited from +layout.svelte (remove from this page)
-->

Acceptance Criteria

• Every playground HTML page has @state annotation (or "none" if no state)
• Every page has @api expanded with endpoint signatures
• Every page with JS interactivity has @svelte-notes translation guide
• Toggle pages (tryouts, teams, schedule, gear) document the shared program state
• Authenticated pages document their role-specific data contracts
• Nav/footer duplication noted as "+layout.svelte" on every page

Test Expectations

• grep for '@svelte-notes' returns a hit on every page with JS interactivity
• grep for '@state' returns a hit on every page
• No automated tests — these are documentation comments

Constraints

• Do NOT change any HTML structure or CSS — annotations only
• Do NOT change any JS behavior
• This is the bridge between playground (Stage 1) and Svelte (Stage 2)
• Depends on all public pages being created first (#91-#95)

Checklist

• All public pages annotated
• All authenticated pages annotated
• Translation guide is mechanically followable
• Lucas review

Related

• westside-playground-overhaul — parent note
• project-svelte-playground — Stage 2 target
• arch-sitemap-westside-basketball — page inventory

### Type Feature ### Lineage Part of public site evolution. Parent note: `westside-playground-overhaul` ### Repo `forgejo_admin/westside-playground` ### User Story As a dev agent promoting playground HTML to SvelteKit, I want each page to document exactly how its HTML/JS patterns translate to Svelte 5 so that promotion is mechanical copy-paste + rune wiring, not guesswork. story:agent-promote ### Context The playground pages have `@route`, `@auth`, `@nav`, `@api` doc comments. These tell agents WHAT the page is. Missing: `@state` and `@svelte-notes` that tell agents HOW to translate it. Every page needs annotations covering: - `@state` — reactive state variables (e.g. `program: 'kings' | 'queens'`) - `@api` — expanded to show actual endpoint signatures the SvelteKit `+page.server.ts` will call - `@svelte-notes` — line-by-line translation guide for non-obvious patterns ### Translation patterns to document | HTML Playground | Svelte 5 | |---|---| | `localStorage.getItem('program')` | `let program = $state(localStorage.getItem('program') ?? 'kings')` | | `localStorage.setItem('program', p)` | `$effect(() => localStorage.setItem('program', program))` | | `document.body.classList.toggle('queens-active')` | `<svelte:body class:queens-active={program === 'queens'} />` | | `data-program-content="kings"` show/hide | `{#if program === 'kings'}...{/if}` | | `initKQToggle()` in DOMContentLoaded | Gone — Svelte reactivity replaces it | | Hardcoded mock data in HTML | `+page.server.ts` load function → basketball-api | | `initFilterList()` search/filter | Svelte `$derived` filtering on reactive array | | `initTabs()` tab switching | `let activeTab = $state('roster')` + `{#if}` blocks | | `initRegister()` form logic | Svelte form bindings + `$state` | | Mobile nav toggle JS | Svelte `let menuOpen = $state(false)` | | Shared nav HTML duplicated across pages | `+layout.svelte` component (rendered once) | | Shared footer HTML duplicated | `+layout.svelte` component | ### File Targets Files to modify — ALL playground HTML pages. Add `@state` and `@svelte-notes` to the existing component doc comment block at the top of each file. Example for tryouts.html: ```html <!-- @route /tryouts @auth public @nav Tryouts (active) @api GET /api/tryouts — past tryout history (date, location, player_count, teams_formed) @api GET /api/tryouts/upcoming — next scheduled tryout or null @state program: 'kings' | 'queens' — persisted localStorage, shared across toggled pages @svelte-notes - KQ toggle → $state('kings') rune, $effect for localStorage sync - data-program-content → {#if program === 'kings'} / {:else} blocks - Past tryout cards → {#each tryouts as tryout} with server data - "View Teams" link → href="/teams?program={program}" - .queens-active → <svelte:body class:queens-active={program === 'queens'}> - Nav + Footer → inherited from +layout.svelte (remove from this page) --> ``` ### Acceptance Criteria - [ ] Every playground HTML page has @state annotation (or "none" if no state) - [ ] Every page has @api expanded with endpoint signatures - [ ] Every page with JS interactivity has @svelte-notes translation guide - [ ] Toggle pages (tryouts, teams, schedule, gear) document the shared program state - [ ] Authenticated pages document their role-specific data contracts - [ ] Nav/footer duplication noted as "+layout.svelte" on every page ### Test Expectations - [ ] grep for '@svelte-notes' returns a hit on every page with JS interactivity - [ ] grep for '@state' returns a hit on every page - No automated tests — these are documentation comments ### Constraints - Do NOT change any HTML structure or CSS — annotations only - Do NOT change any JS behavior - This is the bridge between playground (Stage 1) and Svelte (Stage 2) - Depends on all public pages being created first (#91-#95) ### Checklist - [ ] All public pages annotated - [ ] All authenticated pages annotated - [ ] Translation guide is mechanically followable - [ ] Lucas review ### Related - `westside-playground-overhaul` — parent note - `project-svelte-playground` — Stage 2 target - `arch-sitemap-westside-basketball` — page inventory

forgejo_admin commented 2026-03-27 00:38:28 +00:00

Author

Owner

Copy link

Scope Review: NEEDS_REFINEMENT

Review note: review-416-2026-03-25
Well-structured Feature ticket with all template sections present and excellent translation pattern table, but two fixable issues found.

• Repo placement mismatch — Issue filed on westside-app but ### Repo says westside-playground and all work targets playground HTML files. Either refile on westside-playground or update the body.
• Story label mismatch — Issue body says story:agent-promote but board item label is story:WS-S26 (matching the parent note). Update issue body to story:WS-S26.
• Dependencies — 3 of 5 dependencies still open (#93, #94, #95). Dependency labels are correct; ticket must stay in todo until those close. gear.html doesn't exist yet (#94).

## Scope Review: NEEDS_REFINEMENT Review note: `review-416-2026-03-25` Well-structured Feature ticket with all template sections present and excellent translation pattern table, but two fixable issues found. - **Repo placement mismatch** — Issue filed on `westside-app` but `### Repo` says `westside-playground` and all work targets playground HTML files. Either refile on `westside-playground` or update the body. - **Story label mismatch** — Issue body says `story:agent-promote` but board item label is `story:WS-S26` (matching the parent note). Update issue body to `story:WS-S26`. - **Dependencies** — 3 of 5 dependencies still open (#93, #94, #95). Dependency labels are correct; ticket must stay in `todo` until those close. `gear.html` doesn't exist yet (#94).

forgejo_admin commented 2026-03-27 01:58:00 +00:00

Author

Owner

Copy link

Scope Review: NEEDS_REFINEMENT (re-review)

Review note: review-416-2026-03-26

Re-review of prior review-416-2026-03-25. Two of three prior findings resolved, two remain.

Resolved since prior review:

• All 5 dependencies (#91-#95) now closed
• gear.html now exists (created by #94)

Still open:

• Repo placement mismatch — Issue filed on westside-app but ### Repo says westside-playground and all work targets playground HTML files. Agent will clone wrong repo.
• Story label mismatch — Issue body says story:agent-promote but board item label is story:WS-S26. Update body to match.

Once these two items are corrected, ticket is READY.

## Scope Review: NEEDS_REFINEMENT (re-review) Review note: `review-416-2026-03-26` Re-review of prior `review-416-2026-03-25`. Two of three prior findings resolved, two remain. **Resolved since prior review:** - All 5 dependencies (#91-#95) now closed - `gear.html` now exists (created by #94) **Still open:** - **Repo placement mismatch** — Issue filed on `westside-app` but `### Repo` says `westside-playground` and all work targets playground HTML files. Agent will clone wrong repo. - **Story label mismatch** — Issue body says `story:agent-promote` but board item label is `story:WS-S26`. Update body to match. Once these two items are corrected, ticket is READY.

forgejo_admin commented 2026-03-27 02:13:34 +00:00

Author

Owner

Copy link

Scope Update (2026-03-26)

Fixes from review-416-2026-03-26:

1. Repo placement: This issue is filed on westside-app but the work targets forgejo_admin/westside-playground. The ### Repo section already states this correctly. Agent should clone westside-playground, not westside-app.
2. Story label: Changed from story:agent-promote to story:WS-S26 to align with board item labels.

Progress from PR #45 (site-overhaul branch):

All 8 public pages now have complete @svelte-notes annotations:

• @api endpoints with signatures
• @state reactive variables
• @svelte-notes translation guide (toggle→runes, sections→{#each}, etc.)
• @data-philosophy on teams.html (render partial data gracefully)
• @data-sources on schedule.html

Remaining scope for #96: Authenticated pages (admin, coach, player-profile, parent, team, billing, checkout, jersey, register, login, etc.) still need annotations. Public pages are done pending PR #45 merge.

Dependencies

All 5 dependencies (#91-#95) are now closed.

## Scope Update (2026-03-26) ### Fixes from review-416-2026-03-26: 1. **Repo placement**: This issue is filed on `westside-app` but the work targets `forgejo_admin/westside-playground`. The `### Repo` section already states this correctly. Agent should clone `westside-playground`, not `westside-app`. 2. **Story label**: Changed from `story:agent-promote` to `story:WS-S26` to align with board item labels. ### Progress from PR #45 (site-overhaul branch): All 8 public pages now have complete `@svelte-notes` annotations: - `@api` endpoints with signatures - `@state` reactive variables - `@svelte-notes` translation guide (toggle→runes, sections→{#each}, etc.) - `@data-philosophy` on teams.html (render partial data gracefully) - `@data-sources` on schedule.html **Remaining scope for #96:** Authenticated pages (admin, coach, player-profile, parent, team, billing, checkout, jersey, register, login, etc.) still need annotations. Public pages are done pending PR #45 merge. ### Dependencies All 5 dependencies (#91-#95) are now closed.

forgejo_admin commented 2026-03-27 02:16:35 +00:00

Author

Owner

Copy link

Scope Review: READY (re-review #3)

Review note: review-416-2026-03-26 (updated)

Both prior findings adequately mitigated via scope update comment:

• Repo placement — ### Repo section says westside-playground (correct). Comment clarifies clone target. Refiling would break references. Adequate.
• Story label — Body still says story:agent-promote but board item label (authoritative source) is story:WS-S26. Comment corrects it. Adequate.

All 5 dependencies closed. All 27 HTML files exist. 8 public pages already annotated (PR #45). Remaining scope: 19 authenticated pages. Acceptance criteria grep-verifiable. Low blast radius (comments only).

Ticket is READY for todo → next_up.

## Scope Review: READY (re-review #3) Review note: `review-416-2026-03-26` (updated) Both prior findings adequately mitigated via scope update comment: - **Repo placement** — `### Repo` section says `westside-playground` (correct). Comment clarifies clone target. Refiling would break references. Adequate. - **Story label** — Body still says `story:agent-promote` but board item label (authoritative source) is `story:WS-S26`. Comment corrects it. Adequate. All 5 dependencies closed. All 27 HTML files exist. 8 public pages already annotated (PR #45). Remaining scope: 19 authenticated pages. Acceptance criteria grep-verifiable. Low blast radius (comments only). Ticket is **READY** for todo → next_up.

forgejo_admin commented 2026-03-27 02:18:06 +00:00

Author

Owner

Copy link

Scope Narrowing

Reduced scope to 8 public pages only. Authenticated pages (admin, coach, player-profile, parent, etc.) are Phase 15 work and out of scope for this ticket.

Public pages already annotated in PR forgejo_admin/westside-playground#45:

• index.html, about.html, staff.html, tryouts.html, teams.html, schedule.html, gear.html, sponsors.html

All have @api, @state, @svelte-notes. Teams has @data-philosophy and @player-card. Schedule has @data-sources.

This ticket is effectively complete pending PR #45 merge.

## Scope Narrowing **Reduced scope to 8 public pages only.** Authenticated pages (admin, coach, player-profile, parent, etc.) are Phase 15 work and out of scope for this ticket. Public pages already annotated in PR forgejo_admin/westside-playground#45: - index.html, about.html, staff.html, tryouts.html, teams.html, schedule.html, gear.html, sponsors.html All have `@api`, `@state`, `@svelte-notes`. Teams has `@data-philosophy` and `@player-card`. Schedule has `@data-sources`. **This ticket is effectively complete pending PR #45 merge.**

forgejo_admin referenced this issue 2026-03-27 03:12:55 +00:00

SvelteKit public site — layout shell + all 8 pages from playground #98

forgejo_admin referenced this issue from a commit 2026-03-28 05:11:05 +00:00

docs: add @state and @svelte-notes annotations to all 19 authenticated pages

forgejo_admin referenced this issue from a pull request from forgejo_admin/westside-playground that will close it, 2026-03-28 05:11:42 +00:00

docs: @svelte-notes annotations on all playground pages #48

forgejo_admin closed this issue 2026-03-28 05:28:48 +00:00

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

142-validate-coach-login-and-read-only-roste

139-fix-admin-dashboard-stats-showing-all-ze

129-validate-girls-draft-board-coach-login-a

204-auto-tag-update

deploy-update-image-tag

110-fix-harbor-push-target

No results found.

Labels

Clear labels   

domain:backend

  

domain:devops

  

domain:frontend

No labels

domain:backend

domain:devops

domain:frontend

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

forgejo_admin/westside-app#96

No description provided.