07advanced
API reference
Every export of the copied kloq source — the root module, themes, settings and design-mode — grouped by area.
Every export, grouped by area — the component and its chrome, then the pure layers underneath, then the three companion modules. Types ship alongside the values they describe.
<Kloq> props
view?"day" | "week" | "month" | "agenda" | "year" | "timeline" | numberControlled view. A number is an n-day span (2–14). Pair with onViewChange.
defaultView?KloqViewdefault "week"Uncontrolled starting view. Ignored when view is set.
onViewChange?(view: KloqView) => voidFired whenever something asks to change the view, controlled or not.
date?DateControlled anchor date. Navigation only reports via onDateChange.
defaultDate?DateUncontrolled starting anchor; defaults to today.
onDateChange?(date: Date) => voidFired whenever something asks to move the anchor date.
events?CalEvent[]Controlled events. Switches the internal store off — pair with onEventsChange.
onEventsChange?(events: CalEvent[]) => voidThe full next event list on every committed change (controlled mode).
defaultEvents?CalEvent[]default sample eventsUncontrolled starting events. Omit for the sample events; pass [] to start empty.
lanes?readonly Lane[]default []Rows for view="timeline". Ignored by every other view. Empty by default — nothing renders without lanes.
persistence?false | PersistenceAdapterdefault localStorageUncontrolled persistence: false is ephemeral, omit is localStorage, or bring an adapter.
storage?StorageSettingdefault "kloq"Everything kloq keeps in localStorage. false keeps it in memory; a string namespaces the keys.
onCommit?OnCommitOptimistic seam — called on every committed change; a rejected promise reverts it.
onUndo?() => voidControlled-mode undo — ⌘Z calls it.
onRedo?() => voidControlled-mode redo — ⇧⌘Z calls it.
onRangeChange?(start: Date, end: Date) => voidThe visible range changed — [start, end). Fires once on mount, then on every view or date change.
rangePadding?number | { before: number; after: number }default 0Days to widen the range onRangeChange reports.
density?"comfortable" | "compact"default "comfortable"Hour height, event type size and padding together.
zoom?numberdefault 4Live zoom as an index into ZOOM_STEPS (0–10; 4 = 100%).
hourHeight?numberpx per hour, clamped to 8–480. Omit and density picks the base.
dayStartHour?numberdefault 0First hour the grid draws (0–23); with dayEndHour this clips the day.
dayEndHour?numberdefault 24Last hour the grid draws (exclusive).
snapMinutes?numberdefault 15Drag and keyboard snap grid.
snapFineMinutes?numberdefault 5Snap grid while ⌥ is held.
minEventMinutes?numberdefault 15Shortest event a resize can produce.
weekStartsOn?0 | 1 | 2 | 3 | 4 | 5 | 6default 10 = Sunday … 6 = Saturday.
constraints?KloqConstraintsBounds (minDate/maxDate), a per-slot refusal and a per-event veto. Refused time draws as a hatch; every gesture honours it.
workingHours?{ start: number; end: number } | falsedefault { start: 9, end: 17 }Working-hours tint boundaries; false disables the tint.
showWeekNumbers?booleandefault falseISO 8601 week numbers in the gutter corner (time-grid views).
responsive?ResponsiveSettingdefault trueCollapse to a single-day view when the box is too narrow. view is never rewritten.
locale?stringdefault "en-US"BCP 47 tag for every date and time label.
hour12?booleanForce a 12- or 24-hour clock; omit and the locale decides.
displayTimeZone?stringDraw the calendar in this IANA zone instead of the browser's.
timeZones?(string | TimeZoneColumn)[]Extra gutter zone columns, in order.
designMode?boolean | { hint?: boolean }default trueFigma-style design mode (⌥D). { hint: false } hides the pill.
commandPalette?boolean | { commands?: string[] }default true⌘K. false removes the binding and the menu; { commands } narrows the built-ins — spread BUILT_IN_COMMANDS and filter.
globalShortcuts?booleandefault falseLet ⌘K / ⌘Z / ⌥D fire when focus is outside the calendar.
navigationKeys?"range" | "day"default "range"What ←/→ move by. PageUp/PageDown always step the range.
currentUserEmail?stringWho "you" are. Enables RSVP, per-person conflicts and showDeclinedEvents.
showDeclinedEvents?booleandefault trueDraw events you have declined.
keymap?KeymapOverrides for the remappable mnemonics.
theme?stringScope a theme to this calendar and its portals — no <html> attribute, no localStorage. Omit to follow the page (setTheme). See Theming.
scheme?"light" | "dark"Pin this calendar's colour scheme regardless of the page's .dark. Omit to follow the page.
components?Partial<KloqComponents>Slot overrides — swap any visual piece; the engine keeps the physics.
makeId?() => stringdefault random UUIDId factory for everything the calendar creates.
ssr?booleandefault falseRender the event layer on the server too. Only hydration-safe with controlled events, a date and displayTimeZone.
laneAdapter?LaneAdapterdefault byResourceId()How an event maps onto a lane, for view="timeline". See Resources & lanes.
timelineWindow?TimelineWindowConfigThe timeline's visible span and slot size — controlled (pass start and end) or derived from the anchor date. See Resource timeline.
onEventClick?(event: CalEvent, placementId: string) => voidAn event was clicked, not dragged.
onEventDoubleClick?(event: CalEvent, placementId: string) => voidDouble-click on an event; fires after onEventClick.
onSlotClick?(slot: { start: Date; end: Date; allDay: boolean }) => voidAn empty slot was clicked, snapped like drag-create.
onSelectionChange?(events: CalEvent[]) => voidThe selection changed, in reading order.
onTimeZonesClick?() => voidThe gutter-corner zone labels were pressed; providing it renders them as a button.
onCustomizeKeybinds?() => void"Customize shortcuts…" was pressed in the ? sheet.
Component & chrome
| Export | Kind | Notes |
|---|---|---|
| Kloq | component | The calendar. Also carries Kloq.Toolbar / Kloq.Nav / Kloq.Reset. Props: KloqProps. |
| KloqToolbar / KloqNav / KloqReset | components | The chrome parts as named exports — identical to the dotted forms, and the ones to use from a server component (dotted access doesn't cross the client boundary). |
| useKloq() | hook | Live view state (view, date, range, navigation) inside <Kloq> children. |
| KloqProps / KloqChrome / KloqToolbarProps | types | The prop surfaces above. |
Configuration
| Export | Kind | Notes |
|---|---|---|
| createSettings / DEFAULT_CONFIG / DEFAULT_SETTINGS | function + constants | Resolve a KloqConfig (props) into a validated KloqSettings (geometry + formatting). |
| useKloqSettings() | hook | The resolved settings, inside slots and chrome. |
| EVENT_COLORS | constant | The five palette keys and their token mappings. |
| springLinear | function | The damped spring sampled into a CSS linear() easing — the settle/cancel curve, exported. |
| KloqConfig / KloqSettings | types | Props in, resolved numbers out. |
Slots & store
| Export | Kind | Notes |
|---|---|---|
| DEFAULT_COMPONENTS | constant | The original slot implementations, so an override can wrap instead of replace. |
| KloqComponents + per-slot prop types | types | EventBlockProps, AllDayChipProps, EventPanelProps, TimeGutterProps, DayHeaderProps, NowIndicatorProps, TimelineBlockProps, ResourceGutterProps, TimelineHeaderProps, TimelineRowProps. |
| useKloqStore() | hook | The event store, inside slots. |
| localStorageAdapter / STORAGE_KEY | adapter + constant | The default persistence and its key. |
| SEED_EVENTS / buildSeedEvents / newEventId | data + functions | The sample events and the id factory. |
| PersistenceAdapter / OnCommit / KloqChange / KloqStore / KloqBatchOp | types | The store's contracts — see Persistence and Optimistic sync. |
| isV2Event / migrateV1 / readPayload / PAYLOAD_VERSION / PayloadV2 | functions + constants | The versioned localStorage payload and its migration. |
Event model & instants
| Export | Kind | Notes |
|---|---|---|
| CalEvent / TimedCalEvent / AllDayCalEvent / CalEventPatch | types | The store event — a discriminated union on allDay. |
| Attendee / AttendeeStatus / EventColor / Instant / Reminder / ReminderMethod | types | The field types on an event. |
| KloqView / KloqViewKind / ViewDescriptor / PlacedEvent / PlacedOccurrence / PlacementId / StoreId / WorkingHours | types | Views, placements and their branded ids. PlacedEvent.laneIndex / endLaneIndex are the row a placement sits on — a visible column in the calendar, a lane in a timeline. dayIndex / endDayIndex are the same values under their old name, kept for one release: @deprecated, removed next release. |
| DEFAULT_EVENT_COLOR / asPlacementId / isBusy / continuesBefore / continuesAfter | constants + functions | Color fallback, id branding, free/busy default, cross-midnight segment predicates. |
| instantAt / instantPlus / parseInstant / dateOnlyAt / dateOnlyAfter / toDateOnlyString / isDateOnly / daysBetween / minutesOfDate / wallMinutesBetween | functions | Building and reading instants, wall-clock-correct. |
| formatMinutes / formatRange / minutesToPx / pxToMinutes / resolveView | functions | Time labels and px↔minute geometry; TimeFormatOptions alongside. |
| HOUR_HEIGHT / SNAP_MIN / SNAP_FINE_MIN / MIN_EVENT_MIN | constants | The default geometry numbers. |
Attendees & conflicts
| Export | Kind | Notes |
|---|---|---|
| addAttendee / addAttendees / removeAttendee / findAttendee | functions | List mutations; email is the dedupe key. |
| setAttendeeStatus / setAttendeeOptional / toggleAttendeeOptional / attendeeStatus / RSVP_CHOICES | functions + constant | RSVP state. |
| organizerOf / isOrganizer / attendeeLabel / initialsFor / isValidEmail / summarize / summaryLabel / AttendeeSummary | functions + type | Reading and summarising an invite. |
| conflictBetween / isConflicting / findConflicts / conflictsFor / conflictClusters / describeConflicts | functions | Busy-time collisions, attendee-aware; ConflictOptions / ConflictPair alongside. |
| eventInterval / intervalsOverlap / overlapMs / isBlocking / participantsOf / sharedParticipants | functions | The interval layer under conflicts. |
Commands, quick add, search, keyboard
| Export | Kind | Notes |
|---|---|---|
| registerCommands / clearCommands / getCommands / subscribeCommands / KloqCommand | functions + type | The open ⌘K registry — see Command palette. |
| COMMAND_GROUPS / DEFAULT_COMMAND_GROUP / groupCommands / matchesQuery / normalizeQuery | constants + functions | The palette's grouping and ranking model. |
| BUILT_IN_COMMANDS / commandAllowed / BuiltInCommand | constant + function + type | Every built-in ⌘K id (families as :*) and the allowlist matcher behind commandPalette.commands. |
| parseQuickAdd / quickAddPreview / highlightSegments / UNTITLED / DEFAULT_QUICK_ADD_MIN | functions + constants | Natural-language event entry — see Quick add. |
| searchEvents / EventSearchOptions / EventSearchResult | function + types | Whole-store search, as ⌘K uses it. |
| formatWhen / formatEventWhen / formatDayLabel / formatDurationShort / allDayDisplayEnd | functions | The shared "when" formatters. |
| KEY_ACTIONS / resolveKeymap / actionForEvent / bindingFromEvent / displayKey / isBindableKey | constants + functions | The remappable keyboard layer; Keymap / KeyActionId / ResolvedKeymap alongside. |
| parseMoveTarget / describeMove | functions | "Move to…" in plain language; MoveTarget / MoveToOptions alongside. |
| selectionFrom / selectOnly / toggleSelection / extendSelection / selectAll / eventsInMarquee / … | functions | The whole pure selection model (SelectionState) — click, ⇧-click, marquee. |
| writeEventsToClipboard / readEventsFromClipboard / eventsToICS / eventsToText / parseClipboardEvents / rebaseEvents / looksLikeICS / buildClipboardPayload | functions | Copy/paste, speaking ICS. |
Views, navigation & layout
| Export | Kind | Notes |
|---|---|---|
| viewKind / isTimeGridView / startOfWeek / MIN_N_DAY_VIEW / MAX_N_DAY_VIEW / MONTH_WEEKS / MONTH_DAYS / AGENDA_DAYS / YEAR_MONTHS | functions + constants | View classification and bounds. |
| stepAnchor / todayAnchor / rangeOfView / formatViewTitle / stepLabel / isoWeek / isoWeekYear | functions | Range stepping and titles; NavigationKeys / StepDirection alongside. |
| layoutMonth / hiddenOn / compareForDay | functions | The month grid's chip layout (MonthChip / MonthLayout). |
| groupAgenda | function | The agenda grouping (Agenda / AgendaDay / AgendaEntry). |
| buildYearGrid / densityByDay / densityBucket / densityFill / describeLoad / loadOn / weekdayColumns | functions | The year view's twelve mini-months and the heat-map density behind them. |
| YearView | component | The year surface, standalone. |
| projectEvents | function | Placing store events into visible columns (Projection / DayBounds). |
| useIsClient() | hook | False on the server and the first client render — the SSR seam. |
| craftBus / CraftEvent / DragFrame / DragKind | pub/sub + types | The zero-render frame stream design mode reads. |
Resource timeline
<Kloq> takes three more props for view="timeline", alongside KLOQ_PROPS
above: lanes (readonly Lane[], empty by default — nothing renders without
rows), laneAdapter (LaneAdapter, defaults to byResourceId()), and
timelineWindow (TimelineWindowConfig, see Resource
timeline for its two modes).
The exports underneath:
| Export | Kind | Notes |
|---|---|---|
| Lane / LaneAdapter | types | The row-binding seam — see Resources & lanes. |
| byResourceId | function | The default adapter: reads event.resourceId (or a named field) as the lane id. |
| resolveWindow | function | Props in (TimelineWindowConfig + the anchor date), a concrete TimelineWindow out. |
| TimelineWindow / TimelineWindowConfig | types | The resolved window and what a host passes for it. |
| KloqAxis | type | The shared px↔minute axis shape, used both vertically (the calendar) and horizontally (the timeline). |
| TimelineGrid / TimelineGridProps | component + type | The row-laying-out grid beneath TimelineRow, exported for a standalone timeline outside <Kloq>. |
Time zones, recurrence, ICS, reminders
These four areas have their own pages; the exports are enumerated there. Time zones: the full pure layer from wallClockIn to searchZones, plus MultiTimeZoneGutter and the authored-zone helpers. Recurrence: the RRULE library, the expansion seam, the this/following/all plans, RRuleBuilder and RecurrenceScopeDialog. ICS: toICS / downloadICS out, parseICS and its structural layer in. Reminders: normalization, descriptions and fire-time math from normalizeReminders to nextReminderAcross, plus the ReminderField control — kloq computes fire times, the host delivers.
Multi-calendar & accounts
| Export | Kind | Notes |
|---|---|---|
| registerCalendarSources / registerCalendarAccounts / registerCalendarAccount / clearCalendarSources | functions | A host registers whatever calendars it has connected — the component never owns provider auth. |
| getCalendarSources / getCalendarAccounts / subscribeCalendarSources / useCalendarSources | functions + hook | Reading the registry, imperatively or reactively. |
| setCalendarVisible / toggleCalendarVisible / isVisible / visibleCalendarIds / isEventVisible / filterVisibleEvents | functions | Visibility toggles and the filters they drive. |
| setDefaultCalendar / defaultCalendar / defaultCalendarId / newEventCalendarId / resolveDefaultCalendar / defaultAccount / accountDefaultCalendar / findAccount / findCalendar | functions | Where a new event lands. |
| resolveEventColor / groupByAccount | functions | Calendar-tinted colors and the account grouping. |
| CalendarList / CalendarField | components | The sidebar list and the panel's calendar picker, standalone. |
| CalendarSource / CalendarAccount / CalendarAccountGroup / CalendarColor | types | The registry's shapes. |
@/components/kloq/lib/themes
| Export | Kind | Notes |
|---|---|---|
| THEMES / getTheme / setTheme | data + functions | Nineteen KloqThemes and the persisted apply. Most of this is re-exported from the package root too. |
| getScheme / setScheme / toggleScheme / resolveScheme / watchSystemScheme | functions | "light" | "dark" | "system" — and the system watcher. |
| THEME_RESTORE_SCRIPT | constant | Inline <script> text that restores theme + scheme before first paint — zero-flash SSR. |
| THEME_STORAGE_KEY / SCHEME_STORAGE_KEY | constants | The localStorage keys. |
| KloqTheme / KloqScheme | types | Theme metadata and the scheme union. |
@/components/kloq/settings
| Export | Kind | Notes |
|---|---|---|
| SettingsDialog | component | The optional preferences dialog (SettingsDialogProps, SettingsSection). Stores nothing — the host owns the state. |
| DEFAULT_PREFERENCES / LANGUAGE_OPTIONS | constants | The KloqPreferences model — maps onto <Kloq> props — and the locale menu. |
| KloqPreferences / NavigationKeys / WeekStart | types | The preference shapes. |
| disconnectAccount / setAccountConferencing / setAccountDefaultCalendar / setDefaultAccount / conferencingLabel / providerLabel / CONFERENCING_PROVIDERS | functions + constant | Account-level mutations and labels for the accounts section. |
| SegmentedChoice | component | The segmented control the dialog is built from — there is no Select. |
@/components/kloq/design-mode
| Export | Kind | Notes |
|---|---|---|
| KloqDesignMode | component | The whole ⌥D surface, standalone. |
| DesignModeProvider / useDesignMode / DesignModeOverlay / DesignModeHint | components + hook | The pieces, for custom tooling. |
| registerNetworkSim / getNetworkSim / subscribeNetworkSim | functions | The Network panel's latency/failure simulator (NetworkSimHandle) — how the demo's FakeServer shows up in the inspector. |