luxtools-plugin/task.prompt.md

Calendar Improvements

Goal

Improve the calendar feature so that calendar sync is easier to trigger, day and event popups are more useful, and calendar events can be created, edited, and deleted from the UI.

This prompt is intended for an implementation agent. Before changing code, inspect the current implementation and keep changes aligned with existing Dokuwiki and plugin conventions.

Relevant Code Areas

• admin/main.php: admin page that already exposes a manual calendar sync button
• action.php: currently contains calendar AJAX handlers, including manual sync
• js/event-popup.js: current popup behavior for calendar events
• syntax/calendar.php: existing calendar syntax implementation and parsing style
• src/ChronologicalCalendarWidget.php: server-rendered calendar widget HTML and event/day markup
• README.md: should be updated if user-facing syntax or behavior changes

Current State

• Manual calendar sync already exists, but only through the admin page.
• Event popups currently open when clicking an event element, not when clicking empty space in a day cell.
• Event popup currently shows the date/time block.
• Calendar sync is currently handled in action.php.
• Sync is currently one-directional: remote CalDAV -> local .ics file.
• The README already notes that automatic sync is not implemented and would likely require cron.

Requested Work

1. Add a Manual Sync Syntax

Add a new wiki syntax that renders a manual sync control on normal pages, so sync is not limited to the admin page.

Requirements:

• Reuse the existing sync behavior instead of duplicating logic.
• Keep permission checks strict. The current sync endpoint is admin-only; preserve that unless a strong reason emerges to change it.
• Follow the existing syntax plugin style used in syntax/calendar.php.
• Update README.md with syntax usage and any permission limitations.

Preferred implementation direction:

• Move sync logic out of action.php into a dedicated class/service if that simplifies reuse and maintainability.
• The syntax should only provide UI/rendering; the actual sync work should remain centralized.

Clarification needed:

• The exact syntax name and parameters are not specified. If no better convention exists in the codebase, choose a minimal, explicit syntax and document it. -> Use the syntax name calendar_sync with no parameters.

2. Improve Event Popups

Update the event popup behavior in js/event-popup.js and related server-rendered markup.

Requirements:

• Do not show the date in the popup when the popup is opened from a specific day context.
• Clicking empty space inside a calendar day cell should open a popup for that day.
• That day-level popup should list all events for the clicked day.
• Preserve support for clicking an individual event to inspect that specific event.

Implementation notes:

• Inspect how day cells and event items are rendered in src/ChronologicalCalendarWidget.php and related output in action.php.
• Prefer attaching structured data to the rendered day cell rather than scraping text from the DOM.
• Keep the popup accessible: overlay close, escape key, and explicit close button should continue to work.

Clarification needed:

• The desired behavior when a day has no events is not specified. Reasonable default: show a popup with a short "no events" message plus the create action if event creation is implemented. -> yes, show a "no events" message with the create action if implemented.

3. Add Event Creation

Add a Create Event action to the day popup.

Requirements:

• The action should create a new calendar event for the selected day.
• After successful creation, the UI should reflect the change without requiring the user to manually refresh unrelated state.
• Keep the implementation maintainable and explicit.

Clarification needed:

• The request does not specify the input UI for creation. The agent should either:
  • implement a simple popup form, or
  • stop and ask for clarification if the appropriate form fields are unclear after inspecting the data model.
• The target calendar slot for newly created events is not specified.
• It is not specified whether creation should be admin-only, authenticated-user-only, or available to all viewers.
• It is not specified whether newly created events must be written only to the local .ics file or also to remote CalDAV immediately.

-> Implement a simple input ui as a popup with the same styling as the event popup, with fields for summary, date/time, location, and description. Show a dropdown to select the calendar slot, preselecting the first one. Restrict event creation to authenticated users. Write newly created events to the local .ics file only, after that perform the event creation via CalDAV if implemented to prevent a full re-sync.

4. Add Event Editing

Add an Edit action for existing events.

Requirements:

• The action should allow modification of an existing event from the popup.
• The correct event instance must be edited, including enough identifier data to distinguish recurring occurrences if necessary.
• After successful editing, refresh the affected day/event UI.

Clarification needed:

• The editable field set is not defined. At minimum, summary, date/time, location, and description appear relevant, but confirm against the current event model before implementing.
• Recurring event editing semantics are not defined: edit one occurrence vs. entire series.
• Remote write-back expectations are not defined.

-> re-use the same input UI as creation, but pre-populate fields with the existing event data. When trying to save a recurring event, ask the user if they want to edit just the selected occurrence or the entire series, or all future occurrences. The changes should be written to the local .ics file first, then if CalDAV write-back is implemented, perform the edit via CalDAV to prevent a full re-sync.

5. Add Event Deletion

Add a Delete action for existing events.

Requirements:

• Deletion should be available from the event popup.
• Use an explicit confirmation step to avoid accidental deletion.
• After deletion, update the UI and related calendar data.

Clarification needed:

• Recurring event deletion semantics are not defined: delete one occurrence vs. entire series.
• Remote write-back expectations are not defined.

-> When trying to delete a recurring event, ask the user if they want to delete just the selected occurrence or the entire series, or all future occurrences. Perform deletion on the local .ics file first, then if CalDAV write-back is implemented, perform the deletion via CalDAV to prevent a full re-sync.

6. Automatic Sync

Do not treat this as a mandatory coding task unless the implementation path is already obvious and safe.

Required output:

• Provide a short implementation proposal for automatic sync.
• Compare at least these approaches:
  • cron invoking a Dokuwiki entry point or plugin-specific script
  • cron calling the existing AJAX endpoint
• Recommend the most maintainable option for a long-lived personal Dokuwiki plugin.

Important context:

• The current README already suggests cron as the likely approach.
• A direct web or AJAX trigger from cron may work, but a CLI-oriented entry point may be more robust and easier to secure.

7. Direct Sync of Changed Events

When an event is created, edited, or deleted, the calendar should update promptly so the UI and stored data stay in sync.

Requirements:

• The local calendar data and rendered calendar state should reflect the change immediately after a successful mutation.
• If remote CalDAV write-back is implemented for create, edit, or delete, trigger it as part of the mutation flow rather than relying on a later full sync.
• Avoid introducing a design where a later full remote -> local sync silently overwrites recent local edits without warning.

Clarification needed:

• The current system only guarantees remote -> local full sync, with limited immediate remote write-back behavior for maintenance task completion. Create, edit, and delete may require a broader sync design decision before implementation.

-> Implement immediate local updates to the .ics file and calendar state for create, edit, and delete actions. If remote CalDAV write-back is implemented, perform that action immediately after the local update within the same user flow to ensure consistency. Avoid a design where local edits are at risk of being overwritten by a later remote sync without user awareness.

Refactoring Requirement

If calendar sync code is touched, strongly prefer moving reusable sync logic out of action.php into a dedicated class under src/.

Reason:

• action.php currently mixes hook registration, rendering-related behavior, and calendar sync handling.
• Reusable sync and event mutation logic will be easier to test, reuse, and extend from a dedicated class.

Expected Deliverables

1. Implement the clearly defined items that can be completed safely from the current codebase.
2. Mark any blocked items with precise clarification questions instead of guessing.
3. Update README.md for any new syntax, permissions, or workflow changes.
4. Run php -l on changed PHP files.
5. Summarize remaining design decisions, especially around permissions, recurring events, and remote CalDAV write-back.