diff --git a/.planning/phases/11-individual-planning/11-CONTEXT.md b/.planning/phases/11-individual-planning/11-CONTEXT.md new file mode 100644 index 0000000..33bffcd --- /dev/null +++ b/.planning/phases/11-individual-planning/11-CONTEXT.md @@ -0,0 +1,117 @@ +# Phase 11: Individual Planning - Context + +**Gathered:** 2026-05-16 +**Status:** Ready for planning + + +## 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. + + + + +## 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. + + + + +## 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. + + + + +## 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. + + + + +## 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. + + + + +## 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. + + + +--- + +*Phase: 11-Individual Planning* +*Context gathered: 2026-05-16* diff --git a/.planning/phases/11-individual-planning/11-DISCUSSION-LOG.md b/.planning/phases/11-individual-planning/11-DISCUSSION-LOG.md new file mode 100644 index 0000000..3d54200 --- /dev/null +++ b/.planning/phases/11-individual-planning/11-DISCUSSION-LOG.md @@ -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.