Scheduler API

Complete API reference for @oge-ui/scheduler. The layout kernel — view-model builders, the transitive-overlap column layout, lane packing, gesture math and the RFC 5545 RRULE-subset parser — is pure TypeScript in @oge-ui/scheduler-engine, shared with the React scheduler; live demos are on the overview page.

Properties Methods Events Types

OgeScheduler

oge-scheduler

Properties 31

Data

Name	Type	Default	Description
`dataSource`	`readonly T[] \| DataSource<T> \| null`	`null`	Appointment items: a plain array (copied into an internal working set — the input is never mutated) or any `@oge-ui/core` `DataSource`, whose `insert`/`update`/`remove` are used for CRUD when present.
`keyExpr`	`string \| ((item: T) => unknown)`	`'id'`	Key field or selector; items without a resolvable key fall back to their index.
`textExpr / startDateExpr / endDateExpr / allDayExpr / colorExpr / locationExpr / descriptionExpr / disabledExpr`	`string \| ((item: T) => unknown)`	`'text' / 'startDate' / …`	Field mapping: names (dotted paths reach nested objects) or getter functions. String dates parse as local wall time and write back in the same storage shape.
`recurrenceRuleExpr / recurrenceExceptionExpr`	`string \| ((item: T) => unknown)`	`'recurrenceRule' / 'recurrenceException'`	Recurrence fields: rules in the documented RFC 5545 subset expand into occurrence instances in every view; exceptions are comma-separated EXDATE stamps.
`reminderExpr`	`string \| ((item: T) => unknown)`	`'reminder'`	Minutes before the start a reminder fires (see `reminderTriggered`) — OGE extra (Outlook parity).
`resources`	`readonly OgeSchedulerResource[]`	`[]`	Resource kinds (`{ fieldExpr, items, label?, useColorAsDefault? }`): editor select fields, default appointment colors and timeline rows.
`groups`	`readonly string[]`	`[]`	Resource field grouping the views (first entry): timeline rows, and day/week columns split per resource — grouped cells prefill the resource on create, and drags across subcolumns/rows reassign it.
`recurrenceEditMode`	`'dialog' \| 'occurrence' \| 'series'`	`'dialog'`	How edits to a recurring occurrence apply: ask per action, always detach the occurrence (EXDATE + standalone copy), or always change the series.

Date & views

Name	Type	Default	Description
`currentDate`	`Date`	`new Date()`	Anchor date of the visible period. Two-way (`[(currentDate)]`); writes clamp into `[min, max]`.
`currentView`	`'day' \| 'week' \| 'workWeek' \| 'month' \| 'agenda' \| 'timelineDay' \| 'timelineWeek' \| 'year'`	`'week'`	The active view. Two-way (`[(currentView)]`).
`views`	`readonly (OgeSchedulerView \| OgeSchedulerViewOptions)[]`	`['day', 'week', 'month']`	View-switcher entries; option objects override `name`, `dayStartHour`, `dayEndHour` and `cellDuration` per view.
`adaptiveView`	`boolean \| { breakpoint?: number; view?: OgeSchedulerView }`	`false`	Switches the visible view to `view` (agenda) when the scheduler's own width — a `ResizeObserver`, never the window — drops below `breakpoint` (600px), and back to the previous view when it grows again. The switch writes `currentView` like a user pick, on crossings only, so the switcher keeps working at any width and a view picked while narrow wins.
`min / max`	`Date \| undefined`	—	Navigable date bounds: navigation buttons disable at the edges and every date write clamps.
`firstDayOfWeek`	`number \| undefined`	—	First day of week (0 = Sunday); `undefined` resolves from the locale via `Intl.Locale.weekInfo`.
`weekendDays`	`readonly number[] \| undefined`	—	Weekend days (0 = Sunday … 6 = Saturday) the day/week, month and timeline views shade and the `workWeek` view drops. `undefined` resolves from the locale via `Intl.Locale#getWeekInfo()` (Friday + Saturday in `he-IL`), falling back to Saturday + Sunday.
`hiddenWeekDays`	`readonly number[] \| undefined`	—	Weekdays removed from the week views; the `workWeek` view always drops the weekend on top.
`dayStartHour / dayEndHour / cellDuration`	`number`	`0 / 24 / 30`	Visible hour window and slot raster (minutes) of the time grids.
`agendaDuration`	`number`	`7`	Days the agenda view lists from the anchor date.
`scrollTime`	`number \| undefined`	—	Initial scroll position of the day/week body in hours (fractions allowed, e.g. `8.5`); re-applied on view/period changes.

Behavior

Name	Type	Default	Description
`allowAdding / allowUpdating / allowDeleting / allowDragging / allowResizing`	`boolean`	`true`	Per-capability editing gates.
`readOnly`	`boolean`	`false`	Display-only shorthand: overrides every `allow` flag at once and hides the editing affordances. The day/week and month grids then carry `aria-readonly="true"` (also when every `allow` flag is off).
`snapDuration`	`number \| undefined`	—	Drag/resize snap raster in minutes; defaults to `cellDuration`.
`workHours`	`OgeSchedulerWorkHours \| null`	`null`	Working-hours emphasis: cells outside `{ start, end, days? }` get the off-hours shading.
`showAddButton`	`boolean`	`true`	Shows the toolbar "new appointment" button (Outlook parity) — creation without double-click; hidden while `readOnly` or `allowAdding=false`.
`showAllDayPanel`	`boolean`	`true`	Shows the all-day strip in the day/week views.
`showCurrentTimeIndicator`	`boolean`	`true`	The accent now-line in today's column.
`shadeUntilCurrentTime`	`boolean`	`false`	Dims today's column above the now-line.
`maxAppointmentsPerCell`	`number \| 'auto'`	`'auto'`	Month-view lane budget per cell; the overflow folds into a "+N more" button that drills into the day view.
`locale`	`string \| undefined`	—	BCP 47 locale for every `Intl` format; defaults to the browser locale.
`messages`	`Partial<OgeSchedulerMessages>`	`{}`	Per-instance message overrides, merged over the DI config per top-level block.
`dateNavigatorText`	`(start: Date, end: Date, view: OgeSchedulerView) => string`	—	Custom period-title formatter for the toolbar.

Methods 11

Name	Type	Description
`addAppointment(appointmentData)`	`void`	Inserts programmatically through the same cancelable `appointmentAdding` pipeline as interactive creation.
`updateAppointment(appointmentData, patch)`	`void`	Applies a patch through the guarded update pipeline.
`deleteAppointment(appointmentData)`	`void`	Deletes through the guarded delete pipeline.
`showAppointmentPopup(appointmentData?, createNew?)`	`void`	Opens the editing form — prefilled create form with `createNew`/no data, edit form otherwise (dx parity: the method opens the form).
`hideAppointmentPopup()`	`void`	Closes the editor dialog and the summary popup.
`scrollToTime(hours, minutes?)`	`void`	Scrolls the day/week body to the given time of day.
`scrollTo(date)`	`void`	Navigates to `date` and scrolls to its time of day.
`getStartViewDate() / getEndViewDate()`	`Date`	First moment / exclusive end of the visible period.
`getDataSource()`	`readonly T[] \| DataSource<T> \| null`	The bound data source, as given.
`focus()`	`void`	Focuses the active view's grid (roving cell).
`goToday() / navigate(direction)`	`void`	Toolbar equivalents: jump to today / step one period (respects `min`/`max`).

Events 9

Editing (cancelable pipeline)

Name	Type	Description
`appointmentAdding / appointmentUpdating / appointmentDeleting`	`OgeSchedulerAppointment*ingEvent<T>`	Cancelable pre-events — set `cancel = true` to veto before the store changes.
`appointmentAdded / appointmentUpdated / appointmentDeleted`	`OgeSchedulerAppointment*edEvent<T>`	Fired only for applied changes — persist from these when binding plain arrays.
`editorShowing`	`OgeSchedulerEditorShowingEvent<T>`	Cancelable, before the editor opens; replace `formItems` to customize the form (dx `onAppointmentFormOpening` parity).

Reminders

Name	Type	Description
`reminderTriggered`	`OgeSchedulerReminderEvent<T>`	Fires once per occurrence when `start − reminder` minutes is reached (checked about every 30 s while mounted) — OGE extra.

Interaction

Name	Type	Description
`appointmentClick / appointmentDblClick`	`OgeSchedulerAppointmentClickEvent<T>`	Chip clicks; single click also opens the popup, double click the editor.
`cellClick / cellDblClick`	`OgeSchedulerCellClickEvent`	Empty-cell clicks; double click also opens the prefilled create editor.
`appointmentContextMenu / cellContextMenu`	`OgeSchedulerAppointmentClickEvent<T> / OgeSchedulerCellClickEvent`	Right-clicks with full payloads. A built-in context menu also opens (chip: edit/delete through the guarded pipelines incl. recurrence scope; cell: new appointment prefilled at that slot — labels in `messages.menu`); listen to these events to add your own entries alongside it.
`rangeSelected`	`OgeSchedulerRangeSelectedEvent`	A drag-to-create cell-range selection landed; the prefilled create editor opens next.
`currentDateChange / currentViewChange`	`Date / OgeSchedulerView`	The two-way model outputs.

Types 6

Name	Type	Description
`OgeSchedulerAppointment<T>`	`interface`	The normalized appointment: `key`, `source` (the original item), `text`, `startDate`/`endDate`, `allDay`, `color`, `description`, recurrence fields and `disabled`.
`OgeSchedulerViewOptions`	`interface`	Per-view overrides: `type`, `name`, `dayStartHour`, `dayEndHour`, `cellDuration`.
`OgeSchedulerWorkHours`	`interface`	`{ start, end, days? }` — the emphasized working hours.
`[ogeAppointmentTemplate]`	`structural directive`	Replaces the chip content; context `{ $implicit: OgeSchedulerAppointment<T>, view }`.
`OgeSchedulerCellTemplate`	`structural directive [ogeCellTemplate]`	OGE extra — custom empty-cell content; context `{ $implicit: Date, view, allDay }`.
`OgeDateHeaderTemplate`	`structural directive [ogeDateHeaderTemplate]`	OGE extra — custom date-header content; context `{ $implicit: Date, view }`.

Configuration

Properties 3

Name	Type	Default	Description
`provideOgeSchedulerConfig(config)`	`Provider`	—	Configures every scheduler below the provider; shallow merge per top-level key (a partial `messages` replaces whole nested blocks).
`messages`	`OgeSchedulerMessages`	—	Every user-facing string, aria labels included: `toolbar` (labels, view names, date-navigator), `popup`, `editor` (titles, field labels, validation), `grid` (aria templates with `{token}` placeholders, "+{count} more") and `announcements` (live-region templates).
`minAppointmentMinutes`	`number`	`15`	Minimum rendered chip height in minutes — zero-length reminders stay clickable.

Notes

Dates are plain local Dates throughout (Intl-only house rule — no date library, no adapter, no timezone database). RRULE stamps without a suffix are local wall time; …Z stamps are UTC and convert to the matching local instant. The supported RFC 5545 subset is FREQ DAILY/WEEKLY/MONTHLY/YEARLY, INTERVAL, COUNT ⊕ UNTIL, BYDAY, BYMONTHDAY, BYMONTH, BYHOUR, BYMINUTE, BYSETPOS and WKST, plus DTSTART/RDATE/EXDATE lines when the rule field holds an iCalendar property block. TZID, BYYEARDAY, BYWEEKNO, BYSECOND and EXRULE reject the whole rule rather than truncating it.
No WAI-ARIA APG scheduler pattern exists. The widget composes the calendar-grid pattern: the view body is a role="grid" whose first row holds role="columnheader" cells (the full date, plus the resource when grouped; weekday names in the month view), and one roving-tabindex cell (arrows, Home/End, Enter/Space creates) that is also the aria-selected cell — selection follows focus, and a live drag-to-create range selects the slots it covers. A read-only scheduler sets aria-readonly on the grid. The appointment chips form a second tab stop of role="button" elements — Left/Right cycles chronologically, Enter opens the popup, Delete deletes, and Ctrl+Arrow moves / Ctrl+Shift+Up/Down resizes as the keyboard equivalent of drag, announced through a polite live region.
Binding a plain array never mutates it — edits land in an internal working set and the past-tense events carry the data to persist. A DataSource with insert/update/ remove is written through and reloaded instead.