Advanced events editor API

[ChristophWurst]

Is your feature request related to a problem? Please describe.

As a Nextcloud app developer I want to be able to extend the event editors with custom inputs and influence the ICS generation.

Describe the solution you'd like

TBD

Describe alternatives you've considered

TBD

Additional context

Part of #812

[ChristophWurst]

Note: This design proposal was drafted with AI assistance (Claude Code, model claude-opus-4-8) and is posted for discussion. Details are subject to review and change.

Proposed design: a framework-agnostic event editor plugin API

A concrete proposal for this ticket. The goal: let any Nextcloud app add custom inputs to the event editor and read/modify the event being edited — both the standard editor properties and arbitrary custom ICS properties — without depending on Calendar's internals or its frontend framework.

Scope (this iteration)

• ✅ Custom editor fields (UI injected into the event editor)
• ✅ First-class access to the editor's working model (standard properties)
• ✅ An ICS serialization hook (influence the generated iCalendar data)
• ❌ Out of scope for now: event context-menu actions, calendar-grid/view plugins, settings hooks. These can reuse the same registry later (see APIs for other apps #812).

Design decisions

1. Framework-agnostic UI — plugin UI is a Web Component (custom element). Calendar only renders <your-tag> and assigns it a context object. The plugin can be written in vanilla JS, Lit, Svelte, React, Vue — anything that compiles to a custom element. No coupling to Calendar's Vue version. (Same mechanism the Files app uses for sidebar tabs.)
2. Framework-agnostic registration — a tiny published package whose functions only write to a window global. Plugins never import Calendar code.
3. The editor model is the primary surface — plugins operate on a stable, reactive projection of the event (the same data the built-in fields edit), not the Pinia store and not (primarily) raw ICS strings.
4. No restriction on property names — plugins may read/write any ICS property; docs recommend an X-<APPID>-… prefix but it is not enforced.
5. Load-order-proof — a drained queue (Viewer pattern) + a live registry (Files pattern), so registration works whether the plugin script runs before or after Calendar boots.

Public API

Working package name (TBD — see open questions): @nextcloud/calendar-plugin. Zero runtime deps; ships types + thin functions writing to window globals. EventComponent re-exported type-only from @nextcloud/calendar-js.

Register a custom field

import { registerEventEditorField } from '@nextcloud/calendar-plugin'

interface EventEditorField {
  id: string                                   // unique; prefix with your app id
  tagName: string                              // custom element tag (needs a hyphen); prefix with app id
  order?: number                               // sort among plugin fields
  variants?: Array<'full' | 'simple'>          // default ['full']
  enabled?: (ctx: EventContext) => boolean     // re-evaluated on change
  onInit?: () => void | Promise<void>          // define the custom element once (lazy import)
}

registerEventEditorField(field: EventEditorField): void

Calendar renders the element and assigns the context as a property (el.context = ctx) — which is what lets us hand over a rich object with callbacks rather than just string attributes.

Register a UI-less ICS hook

interface EventSerializeHook {
  id: string
  // called once per VEVENT, synchronously, immediately before toICS()
  serialize: (component: EventComponent, ctx: EventContext, scope: SaveScope) => void
}
registerEventSerializeHook(hook: EventSerializeHook): void

The context — centered on the live event model

type SaveScope = 'this' | 'thisAndFuture' | 'all'

interface EventContext {
  /**
   * Live view of the editor's working model — the SAME data the built-in editor edits.
   * Reads return the current value. Writes route through the same store actions the
   * built-in fields use, so the default UI updates reactively (and vice versa).
   */
  readonly event: EventModel

  /** Subscribe to editor lifecycle. Returns an unsubscribe fn; auto-cleaned on close. */
  on(type: 'change' | 'beforeSave' | 'close', cb: () => void): () => void

  /** Escape hatch for custom/advanced ICS (X-*, parameters, multi-value, sub-components). */
  getProperty(name: string): string | null
  getPropertyValues(name: string): string[]
  setProperty(name: string, value: string | null): void   // null deletes; marks dirty
  getComponent(): EventComponent                           // raw calendar-js component
}

interface EventModel {
  // identity / recurrence (read-only)
  readonly uid: string
  readonly isNew: boolean
  readonly recurring: boolean
  readonly instanceType: 'master' | 'occurrence' | 'exception'

  // standard scalar fields — READ & WRITE (write-through to the built-in UI)
  summary: string
  location: string
  description: string
  status: 'CONFIRMED' | 'TENTATIVE' | 'CANCELLED' | null
  accessClass: 'PUBLIC' | 'PRIVATE' | 'CONFIDENTIAL' | null
  timeTransparency: 'OPAQUE' | 'TRANSPARENT' | null
  color: string | null

  // time — READ & WRITE
  allDay: boolean
  start: Date
  end: Date
  startTimezone: string
  endTimezone: string

  // collections — READ always; WRITE via mutators (v1: categories + attendees)
  readonly categories: readonly string[]
  addCategory(value: string): void
  removeCategory(value: string): void

  readonly attendees: readonly AttendeeView[]
  addAttendee(a: { email: string, commonName?: string, role?: string, rsvp?: boolean }): void
  removeAttendee(email: string): void

  // read-only in v1 (use getComponent() for advanced writes)
  readonly organizer: { email: string, commonName: string } | null
  readonly alarms: readonly AlarmView[]
  readonly attachments: readonly AttachmentView[]
  readonly recurrenceRule: RecurrenceView | null
}

event accessors map to the reactive calendarObjectInstance store state (read) and store actions (write) — the same path the built-in fields use, so everything stays consistent and reactive. getComponent()/get/setProperty map to the raw calendar-js eventComponent for anything the model doesn't cover.

Recurrence semantics

The model is O(1) per open editor — it does not grow with occurrence count. Opening an instance resolves a single component via getObjectAtRecurrenceId() → recurrenceManager.getOccurrenceAtExactly() (src/utils/calendarObject.js:34), projected into the single reactive calendarObjectInstance. A weekly-forever series is stored as master VEVENT + a handful of RECURRENCE-ID exceptions; other occurrences are computed, never stored. So there is no per-occurrence plugin state.

• The event model and setProperty are scoped to the instance being edited, exactly like the built-in fields. For the common case ("add a field to this event"), a plugin needs zero recurrence awareness — the existing this-only / this-and-future save flow applies automatically (saveCalendarObjectInstance → eventComponent.createRecurrenceException(thisAndAllFuture), src/store/calendarObjectInstance.js:1519).
• Reads see inherited values: an un-exceptioned occurrence is forked from the master (primaryItem), so getProperty() returns the master's value.
• The raw accessor (getComponent()) is the escape hatch for genuinely cross-instance / series-level work: target the master while editing one occurrence (getComponent().primaryItem), enumerate the whole series/all exceptions (parent calendarComponent), or touch RRULE/RECURRENCE-ID structure (not in the v1 model).
• For recurrence-aware plugins without dropping to raw, the context exposes event.instanceType / event.recurring and passes the chosen save scope into beforeSave/serialize, so a plugin can decide series-vs-occurrence placement (and observe that this-and-future creates a brand-new master with a new UID).

Runtime architecture (Calendar side)

• Registration: the register* functions write to window._nc_calendar_editor_fields / _nc_calendar_serialize_hooks Maps and notify window.OCA.Calendar if it is already up. On boot, Calendar creates window.OCA.Calendar (façade + version + an EventTarget), drains the queues, and dispatches register:* for late registrations so an open editor updates live.
• Editor zone: add one extension zone to EditFull.vue (bottom of the right column) and a compact one in EditSimple.vue (above SaveButtons, 'simple' variants only). A small host-internal wrapper runs onInit(), creates each enabled element, assigns el.context, and watches the calendarObjectInstance store to fire the context's change — the reactivity bridge to the framework-agnostic element.
• Save/serialize pass: in saveCalendarObjectInstance(), before updateCalendarObject(): emit beforeSave, apply staged setProperty writes, run all serialize hooks on the (post-fork) eventComponent, then markDirty() if anything changed (so the isDirty() gate does not skip the save). updateCalendarObject() then does the single toICS() + PUT (src/store/calendarObjects.js:107).

Loading & timing (PHP)

• Add an init-script entry point in rspack.config.js (Viewer-style main + init) so window.OCA.Calendar exists early.
• ViewController dispatches a new OCA\Calendar\Event\LoadAdditionalScriptsEvent before render (mirrors the Files app). Plugin apps subscribe and call \OCP\Util::addInitScript('myapp', '…') → runs before the editor mounts, and only on calendar pages.

Correctness considerations

• Custom-property preservation: the recurrence fork on save (createRecurrenceException) splits at the component level and preserves unknown/X-* properties (worth a regression test). However, the Duplicate event action goes through copyCalendarObjectInstanceIntoEventComponent() (src/models/event.js:192, called at calendarObjectInstance.js:1563), which copies only a whitelist and would drop custom properties. Fix: carry over all otherwise-unhandled properties there.
• Two writers to standard fields: since plugins can write summary, location, etc., a plugin and the user can touch the same field. Routing through store actions keeps state consistent (last-writer-wins, UI updates live). Consider a dev-mode warning.
• No namespace restriction (by design): setProperty/getComponent can overwrite RFC/core properties. Not enforced; docs recommend an X-<APPID>-… prefix.
• Sync serialize only (v1): fetch remote data while the editor is open; write synchronously on beforeSave.
• Trust: the element runs first-party in Calendar's origin (same trust level as a Files sidebar tab); the plugin owns sanitization of values it writes to ICS that other clients/invitees will parse.
• Out of scope v1: public booking / embedded views; alarm/attachment/recurrence writes (read-only, with the raw-component escape hatch available).

Worked example

A plugin that reads standard fields (attendees) and writes a derived custom property, re-rendering when the user edits the rest of the event:

// registration (loaded via OCP\Util::addInitScript on calendar pages)
import { registerEventEditorField } from '@nextcloud/calendar-plugin'

registerEventEditorField({
  id: 'myapp-approval',
  tagName: 'myapp-approval-field',
  order: 10,
  variants: ['full', 'simple'],
  async onInit() {
    const { MyApprovalField } = await import('./MyApprovalField.ts')
    if (!customElements.get('myapp-approval-field')) {
      customElements.define('myapp-approval-field', MyApprovalField)
    }
  },
})

// the custom element — no framework
export class MyApprovalField extends HTMLElement {
  private ctx!: import('@nextcloud/calendar-plugin').EventContext

  connectedCallback() {
    const render = () => {
      const needsApproval = this.ctx.event.attendees.length > 10
      this.innerHTML = `<label><input type="checkbox" ${needsApproval ? 'checked' : ''}>
        Requires manager approval (${this.ctx.event.attendees.length} guests)</label>`
      this.querySelector('input')!.addEventListener('change', (e) => {
        const on = (e.target as HTMLInputElement).checked
        this.ctx.setProperty('X-MYAPP-NEEDS-APPROVAL', on ? 'TRUE' : null)
      })
    }
    render()
    this.ctx.on('change', render)   // re-render when the user edits other fields
  }
}

Prior art

• Viewer (@nextcloud/viewer): framework-agnostic registration via a tiny npm package that writes handlers to a window._oca_viewer_handlers Map queue, drained by the app on init (loaded via addInitScript).
• Files (@nextcloud/files): sidebar tabs declare a tagName and register a Web Component (customElements.define) — the framework-agnostic content pattern — plus a reactive getFilesRegistry() EventTarget for post-load registration.

This proposal combines both: Viewer's queue + npm registration, Files' Web-Component content + reactive registry, plus a calendar-js serialize hook specific to the "influence ICS generation" requirement.

Open questions

1. Distribution: in-repo api_package/ (Viewer-style, versioned with the app) first, vs. a dedicated @nextcloud/calendar-plugin repo now.
2. Final package + global names (@nextcloud/calendar-plugin, window.OCA.Calendar, the queue globals).
3. variants default — ['full'] only, or also 'simple' (popover is space-constrained)?
4. Dev-mode warning when a plugin overwrites a standard/RFC property — yes/no?
5. Scope of write access to standard fields in v1 (proposed: scalars + categories + attendees; alarms/attachments/recurrence read-only).

Rollout (focused, independently reviewable PRs)

1. Custom-property preservation fix in the Duplicate path (copyCalendarObjectInstanceIntoEventComponent) + unit tests.
2. window.OCA.Calendar façade + queue/registry + init entry point.
3. Editor extension zone + the reactive context (event model) in EditFull.vue / EditSimple.vue.
4. Serialize / beforeSave pass in saveCalendarObjectInstance.
5. Publish the API package + docs + a reference example plugin.
6. LoadAdditionalScriptsEvent.

---

Assisted-by: ClaudeCode:claude-opus-4-8