arthur/xtablo-source
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions 5

docs(11): capture phase context

Browse source
This commit is contained in:
Arthur Belleville 2026-05-16 07:11:43 +02:00
parent 34d2c23e20
commit 9b32ef9378
No known key found for this signature in database
2 changed files with 166 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

117
.planning/phases/11-individual-planning/11-CONTEXT.md Normal file
View file

@ -0,0 +1,117 @@
# Phase 11: Individual Planning - Context
**Gathered:** 2026-05-16
**Status:** Ready for planning
<domain>
## Phase Boundary
Phase 11 delivers a protected personal planning page at `/planning` for each authenticated user. The page aggregates that user's scheduled events across accessible tablos, presents them as a chronological agenda, and links each event back to its tablo context. This phase does not add new event creation/editing semantics beyond using the Phase 10 event model and tablo Events tab.
</domain>
<decisions>
## Implementation Decisions
### Planning Navigation Window
- **D-01:** `/planning` defaults to an upcoming agenda view rather than a week or month calendar.
- **D-02:** The default agenda range is the next 14 days starting from today.
- **D-03:** Navigation uses fixed 14-day windows with `Today`, previous-window, and next-window controls.
- **D-04:** Past events are not shown by default, but users can reach past events intentionally through previous-window navigation.
- **D-05:** Keep the first planning view focused on agenda browsing. Do not recreate the Phase 10 tablo Events month calendar on the personal planning page.
### Agenda Row Content
- **D-06:** The agenda renders as a single continuous chronological list, not grouped by day or by tablo.
- **D-07:** Each event row shows time, title, tablo context, and location when present.
- **D-08:** Do not show description snippets in the first planning agenda rows; avoid noisy/tall rows.
- **D-09:** Tablo context appears as the tablo title plus a small color dot using `tablo_color` when present.
- **D-10:** Events without an end time display the start time only. Do not add "no end" copy or infer a default duration.
### the agent's Discretion
- Exact route handler names, template names, query parameter names, and HTMX fragment boundaries are planner discretion if they preserve the decisions above and match existing Go/HTMX patterns.
- Exact empty-state wording is planner discretion, but it must be functional and plain.
- Exact date label formatting is planner discretion, but the list must remain chronological and easy to scan.
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Product Scope
- `.planning/ROADMAP.md` - Phase 11 goal, MVP mode, success criteria, and user-in-loop decision about today/upcoming versus week navigation.
- `.planning/REQUIREMENTS.md` - PLAN-01 through PLAN-04 and Phase 11 traceability.
- `.planning/PROJECT.md` - v2 constraints: Go + HTMX, individual planning, plain functional UI, and no JS framework.
### Event Handoff
- `.planning/phases/10-events/10-CONTEXT.md` - Event date/time semantics, planning handoff decisions, and deep-link expectations.
- `.planning/phases/10-events/10-03-SUMMARY.md` - User-scoped event range query and navigation/prefill behavior delivered for planning.
- `.planning/phases/10-events/10-04-SUMMARY.md` - Final Phase 10 verification and browser UAT approval.
- `.planning/phases/10-events/10-VERIFICATION.md` - Evidence that EVENT-01..05 and planning handoff query passed.
### Go Backend Entry Points
- `backend/internal/db/queries/events.sql` - `ListUserEventsRange` query returns event fields plus `tablo_title` and `tablo_color` filtered by `tablos.user_id`.
- `backend/internal/web/router.go` - Protected route group and static route ordering pattern where `/planning` should mount.
- `backend/internal/web/handlers_events.go` - Event date/month parsing and event ownership conventions to reuse where relevant.
- `backend/templates/events_forms.go` - Event date/time formatting helpers and `EventTimeRange` behavior for no-end-time display.
- `backend/templates/layout.templ` - Authenticated shell and navigation integration point.
- `backend/templates/tablos.templ` - Existing server-rendered page/tab patterns and plain UI style.
- `backend/internal/web/handlers_events_test.go` - DB-backed event aggregation, ordering, ownership, and formatting tests to mirror for planning.
### Historical TypeScript Reference
- `apps/main/src/pages/planning.tsx` - Old planning page reference for possible agenda concepts only; do not recreate its imports/exports/month/week/day complexity in Phase 11.
- `packages/shared-types/src/events.types.ts` - Historical `EventAndTablo` shape for reference only.
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `ListUserEventsRange` already provides the core data needed for `/planning`: event date/time fields, title, location, description, `tablo_id`, `tablo_title`, and `tablo_color`.
- `templates.FormatEventDate`, `templates.FormatEventTime`, and `templates.EventTimeRange` provide event formatting behavior that keeps Phase 11 consistent with Phase 10.
- Existing `Layout` templates provide the authenticated page shell; `/planning` should be a normal protected page, not a tablo tab.
- Existing `ui.Button` and form/error helpers are enough for a plain toolbar with Today/previous/next navigation.
### Established Patterns
- Protected pages live inside the `auth.RequireAuth` route group and get the authenticated user from context.
- SQLC query files are canonical; generated Go files are reproduced by `just generate` and should not be hand-edited.
- DB-backed web tests use `setupTestDB`, `preInsertUser`, session cookies, and the full router to prove auth and query behavior.
- User-scoped aggregation must filter by `tablos.user_id`, not by trusting event IDs or client-supplied tablo IDs.
- Non-HTMX full-page behavior should work for primary pages; HTMX can be used for navigation fragments if the planner chooses.
### Integration Points
- Add a `/planning` route in the protected router group.
- Add a planning handler/dependency shape using `sqlc.Queries`.
- Add a planning template rendering the 14-day agenda, toolbar, empty state, and event rows.
- Use `ListUserEventsRange` with a calculated start/end date based on query params or defaults.
- Add handler tests for unauthenticated redirect, owned-only aggregation, chronological ordering, navigation links, empty state, and event links back to tablo context.
</code_context>
<specifics>
## Specific Ideas
- The first personal planning page should feel like an agenda, not another calendar.
- Default to the next 14 days from today.
- Keep rows compact: time, event title, tablo title/color, and location if present.
- Event links should carry users back to the tablo context; Phase 10 established `/tablos/{id}/events?month=YYYY-MM` as the planning deep-link shape.
</specifics>
<deferred>
## Deferred Ideas
- Week and month planning views.
- Date picker navigation.
- Grouped-by-day or grouped-by-tablo planning layouts.
- Description snippets in agenda rows.
- ICS import/export, external calendar sync, and recurrence.
</deferred>
---
*Phase: 11-Individual Planning*
*Context gathered: 2026-05-16*

49
.planning/phases/11-individual-planning/11-DISCUSSION-LOG.md Normal file
View file

@ -0,0 +1,49 @@
# Phase 11: Individual Planning - Discussion Log
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
**Date:** 2026-05-16
**Phase:** 11-individual-planning
**Areas discussed:** Planning navigation window, Agenda row content
---
## Planning Navigation Window
| Option | Description | Selected |
|--------|-------------|----------|
| Upcoming agenda | Starts at today and lists the next events across tablos; simplest and most useful for a first working planning page. | ✓ |
| Current week | Bounded week window with previous/next week navigation; more structured, but empty weeks may feel sparse. | |
| Current month | Matches the Events tab's month concept, but risks becoming a second calendar UI. | |
**User's choice:** Upcoming agenda.
**Notes:** Default range was narrowed to the next 14 days. Navigation should include Today plus previous/next fixed 14-day windows. Past events are available only through previous-window navigation, not shown by default.
---
## Agenda Row Content
| Option | Description | Selected |
|--------|-------------|----------|
| Group by day | Clear scanning with each date heading containing that day's events in chronological order. | |
| Single continuous list | Simpler agenda that keeps time as the primary structure. | ✓ |
| Group by tablo | Useful workspace context, but weaker for personal planning because time is no longer primary. | |
**User's choice:** Single continuous chronological list.
**Notes:** Each row should show time, title, tablo context, and location if present. Tablo context should be title plus a small color dot. Events without an end time show start time only.
---
## the agent's Discretion
- Exact handler/template names, query parameter names, and HTMX fragment boundaries.
- Exact empty-state copy and date label formatting, as long as the result stays functional and plain.
## Deferred Ideas
- Week and month planning views.
- Date picker navigation.
- Grouped-by-day or grouped-by-tablo planning layouts.
- Description snippets in agenda rows.
- ICS import/export, external calendar sync, and recurrence.