diff --git a/.planning/phases/10-events/10-CONTEXT.md b/.planning/phases/10-events/10-CONTEXT.md new file mode 100644 index 0000000..a291bc9 --- /dev/null +++ b/.planning/phases/10-events/10-CONTEXT.md @@ -0,0 +1,144 @@ +# Phase 10: Events - Context + +**Gathered:** 2026-05-16 +**Status:** Ready for planning + + +## Phase Boundary + +Phase 10 delivers scheduled events attached to tablos. Users can create, edit, delete, and browse events inside a tablo with the same authorization expectations as tasks, files, and etapes. The first UI is a functional Events tab with a simple month calendar, not a polished calendar product. Phase 10 should also expose enough query surface for Phase 11 to build an individual planning page without reworking the event model. + + + + +## Implementation Decisions + +### Time Model +- **D-01:** Use local date/time semantics in the first version; do not add timezone selection or timezone conversion UI. +- **D-02:** Event start date and start time are required. +- **D-03:** End time is optional and same-day only. +- **D-04:** If an event has no end time, display only the start time. Do not infer or store a default duration. +- **D-05:** Store event time as separate `event_date`, `start_time`, and nullable `end_time` columns. Do not use `timestamptz` for Phase 10 event scheduling. + +### Events Tab Shape +- **D-06:** Add an `Events` tab to the existing tablo detail tabs beside Overview, Tasks, and Files. +- **D-07:** The first Events tab view is a simple month grid. +- **D-08:** Include previous/next month navigation. +- **D-09:** Users can create events from both a general `New event` button and by clicking a day cell with that date prefilled. +- **D-10:** Day cells show event titles only, not start times. +- **D-11:** When a day has more events than fit cleanly, show the first few titles plus a `+N more` indicator. + +### Create/Edit Flow +- **D-12:** Render create/edit forms inline inside the Events tab using HTMX fragments. +- **D-13:** The form fields are: required title, date, start time; optional end time, description, and location. +- **D-14:** Clicking an event title in the calendar opens the inline edit form. +- **D-15:** Create, edit, and delete operations refresh the whole Events tab/calendar rather than only one day cell. + +### Event Lifecycle +- **D-16:** Delete is hard delete after confirmation. Do not add `deleted_at`, archive, cancel, or restore semantics in Phase 10. +- **D-17:** Past events remain visible when browsing past months. +- **D-18:** Events within a day are ordered by start time ascending, then title. +- **D-19:** Do not add a special empty state beyond the calendar and the `New event` action. + +### Phase 11 Handoff +- **D-20:** Phase 10 should include a user-scoped query surface for events across tablos the authenticated user can access, even if Phase 10 only renders tablo-local events. +- **D-21:** Planning links should target the tablo Events tab with month query params, e.g. `/tablos/{id}/events?month=YYYY-MM`. +- **D-22:** User-scoped event rows should include event fields plus tablo title and tablo color. +- **D-23:** User-scoped query surface should support date-range filtering so Phase 11 can implement planning navigation cleanly. + +### the agent's Discretion +- Exact route names, query names, and HTMX fragment boundaries are planner discretion if they preserve the decisions above and match existing local patterns. +- Exact calendar CSS and mobile layout are planner discretion; the result should remain functional and restrained until the user supplies a richer UI later. +- Exact validation copy is planner discretion, but it must clearly explain that an end time must be after the start time when provided. + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Product Scope +- `.planning/ROADMAP.md` - Phase 10 goal, MVP mode, success criteria, and user-in-loop checkpoint. +- `.planning/REQUIREMENTS.md` - EVENT-01 through EVENT-05 and Phase 11 PLAN requirements that depend on event aggregation. +- `.planning/PROJECT.md` - v2 constraints: Go + HTMX, Postgres, plain functional UI, events belong to tablos, planning is individual. + +### Prior Phase Patterns +- `.planning/phases/09-etapes/09-CONTEXT.md` - Recent tablo-scoped child-resource decisions, Tasks tab integration, and HTMX fragment patterns. +- `.planning/phases/09-etapes/09-04-SUMMARY.md` - Most recent UAT lessons around HTMX tab refreshes and filter/form precedence. + +### Go Backend Entry Points +- `backend/migrations/0003_tablos.sql` - Current `tablos` ownership model and FK target. +- `backend/migrations/0007_etapes.sql` - Recent example of adding a tablo-owned child table and indices. +- `backend/internal/db/queries/tablos.sql` - Existing owner-scoped tablo query shape. +- `backend/internal/db/queries/tasks.sql` - Existing tablo-scoped list/create/update/delete query style. +- `backend/templates/tablos.templ` - Current tab navigation and tab fragment integration point for adding Events. +- `backend/internal/web/router.go` - Protected route mounting order and static-before-parametric route pattern. +- `backend/internal/web/handlers_tablos.go` - Tablo detail/tab handlers and `loadOwnedTablo` authorization pattern. +- `backend/internal/web/handlers_tasks.go` - Task child-resource create/update/delete patterns to mirror for events. +- `backend/internal/web/handlers_etapes.go` - Recent full-tab refresh pattern for child-resource mutations. +- `backend/internal/web/handlers_tasks_test.go` - DB-backed authorization and HTMX regression testing style. + +### Historical TypeScript Reference +- `packages/tablo-views/src/TabloEventsSection.tsx` - Old product reference for event display, upcoming filtering, and empty-state wording; use as reference only, not a visual contract. +- `packages/shared-types/src/events.types.ts` - Old event domain type names and event-with-tablo shape. +- `packages/shared-types/src/database.types.ts` - Old schema had `start_date`, `start_time`, `end_time`, `created_by`, and `deleted_at`; Phase 10 intentionally keeps date/time split but chooses hard delete and no `deleted_at`. +- `apps/main/src/hooks/events.ts` - Old event query/mutation surface and aggregation ideas; use as behavior reference only. +- `apps/main/src/pages/planning.tsx` - Old planning page reference for why Phase 10 should expose user-scoped date-range queries. + + + + +## Existing Code Insights + +### Reusable Assets +- `TabloDetailPage` already renders tab navigation with HTMX links targeting `#tab-content`; Events should follow the same tab pattern. +- `TasksTabFragment` and `FilesTabFragment` show the current pattern for standalone tab fragments returned by HTMX tab routes. +- `loadOwnedTablo` and existing child-resource handlers enforce ownership through the parent tablo and return 404 for inaccessible resources. +- `ui.Button`, `ui.Card`, and existing form field/error patterns are enough for the first functional Events UI. + +### Established Patterns +- Tablo-owned resources mount under `/tablos/{id}/...` protected by `auth.RequireAuth`. +- Static child routes are declared before parametric child routes in `router.go`. +- SQLC query files are canonical; generated Go files are reproduced by `just generate` and not hand-edited. +- Mutations that affect a whole tab can return the full tab fragment for reliability. +- DB-backed tests use `setupTestDB`, `newTaskTestRouter`/similar router helpers, session cookies, and CSRF tokens. +- Unauthorized access to resources owned by another user's tablo should return 404 rather than 403. + +### Integration Points +- Add a migration after `0007_etapes.sql` for a tablo-owned `events` table. +- Add `backend/internal/db/queries/events.sql` with tablo-scoped CRUD, month/date-range list queries, and user-scoped aggregation query including tablo title/color. +- Add event dependencies to `web.NewRouter` similarly to `TasksDeps`, `EtapesDeps`, and `FilesDeps`. +- Extend `TabloDetailPage` with an Events tab and render Events tab content when active. +- Add event handlers and templates under the existing `backend/internal/web` and `backend/templates` patterns. +- Add tests proving owner-only read/create/update/delete and end-time validation. + + + + +## Specific Ideas + +- The Events tab should be a simple month calendar grid, not an agenda list. +- Day-cell clicks should prefill the create form date. +- Event titles are enough inside calendar cells for Phase 10. +- Planning deep links should preserve month context with `?month=YYYY-MM`. + + + + +## Deferred Ideas + +- Timezone selection or conversion. +- Multi-day events. +- Date-only/all-day events. +- Event colors, categories, archive/cancel states, or soft-delete restore flows. +- Week/day calendar views. +- Rich day-detail panels. +- Full individual planning UI; Phase 11 owns that screen. + + + +--- + +*Phase: 10-Events* +*Context gathered: 2026-05-16* diff --git a/.planning/phases/10-events/10-DISCUSSION-LOG.md b/.planning/phases/10-events/10-DISCUSSION-LOG.md new file mode 100644 index 0000000..fbd1efa --- /dev/null +++ b/.planning/phases/10-events/10-DISCUSSION-LOG.md @@ -0,0 +1,83 @@ +# Phase 10: Events - 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:** 10-Events +**Areas discussed:** Time Model, Events Tab Shape, Create/Edit Flow, Event Lifecycle, Phase 11 Handoff + +--- + +## Time Model + +| Option | Description | Selected | +|--------|-------------|----------| +| Local date/time, no timezone field | User enters date + time and Xtablo displays the same date + time everywhere. | ✓ | +| UTC timestamps with timezone conversion | Store exact instants and convert for display. | | +| Date-only allowed | Support all-day/date-only or timed events. | | + +**User's choice:** Local date/time, no timezone field. +**Notes:** Start date/time required. End time is optional, same-day only, and must be after start when provided. If no end time exists, display only the start time. Store separate `event_date`, `start_time`, and nullable `end_time` columns. + +--- + +## Events Tab Shape + +| Option | Description | Selected | +|--------|-------------|----------| +| Agenda/list-first tab | Chronological list inside a new Events tab. | | +| Compact upcoming section on Overview | Small upcoming-events block on overview. | | +| Calendar grid | Month/week style calendar surface. | ✓ | + +**User's choice:** Calendar grid. +**Notes:** Scope is a simple month grid only. Include previous/next month navigation. Users can create events from both a `New event` button and day-cell clicks with the clicked date prefilled. Day cells show event titles only. Crowded days show first few titles plus `+N more`. + +--- + +## Create/Edit Flow + +| Option | Description | Selected | +|--------|-------------|----------| +| Inline panel inside the Events tab | HTMX swaps a form inside the Events tab. | ✓ | +| Separate event form page | Full-page form and validation flow. | | +| Modal-like dialog fragment | Dialog-style fragment with more custom interaction state. | | + +**User's choice:** Inline panel inside the Events tab. +**Notes:** Form fields are required title/date/start time plus optional end time/description/location. Clicking an event title opens inline edit. Create, edit, and delete refresh the whole Events tab/calendar. + +--- + +## Event Lifecycle + +| Option | Description | Selected | +|--------|-------------|----------| +| Hard delete | Remove the row after confirmation. | ✓ | +| Soft delete with `deleted_at` | Preserve rows and filter deleted events. | | +| Archive/cancel state | Add a richer lifecycle state. | | + +**User's choice:** Hard delete. +**Notes:** Past events remain visible when browsing past months. Events inside a day are ordered by start time, then title. No special empty state is needed beyond the calendar and the `New event` action. + +--- + +## Phase 11 Handoff + +| Option | Description | Selected | +|--------|-------------|----------| +| User-scoped query surface | Query events across accessible tablos for the authenticated user. | ✓ | +| Tablo-only query surface | Keep Phase 10 strictly tablo-local. | | +| Full planning route now | Start the Phase 11 screen during Phase 10. | | + +**User's choice:** User-scoped query surface. +**Notes:** Planning links should target `/tablos/{id}/events?month=YYYY-MM`. User-scoped results should include event fields plus tablo title/color, and support date-range filtering. + +--- + +## the agent's Discretion + +- Exact route names, query names, fragment boundaries, calendar CSS, mobile layout, and validation copy are left to planner/executor discretion within the captured decisions. + +## Deferred Ideas + +- Timezone selection/conversion, multi-day events, all-day/date-only events, event categories/colors, soft delete/archive/cancel lifecycle, week/day views, richer day details, and the full individual planning page.