Using Kalendus as a Library

This document explains how to consume the lms-calendar web component that ships with @jpahd/kalendus, with emphasis on package structure, runtime contracts, and integration patterns for application developers embedding the calendar inside their own products.

Package overview

• artefacts: published as pure ESM with main/module pointing at dist/kalendus.js and runtime type definitions exposed through dist/lms-calendar.d.ts plus custom-elements.json for IDE tooling.
• peer dependencies: lit and luxon are declared as peers; your application must provide them at compatible versions (see package.json). Everything else is bundled.
• component tree: <lms-calendar> composes header, month/week/day grids, entry cards, and the contextual <lms-menu> overlay. Internal helpers such as LayoutCalculator, SlotManager, and ViewStateController are private but determine layout and state.

Installation

npm install @jpahd/kalendus lit luxon

Kalendus targets modern evergreen browsers with native Custom Elements, Shadow DOM, ResizeObserver, and CSS container queries. For legacy browsers you must supply the relevant polyfills yourself.

Importing and registration

src/lms-calendar.ts registers the element via @customElement('lms-calendar'), so importing the package once per bundle is enough:

// anywhere in your app entry point
import '@jpahd/kalendus';

// later in templates / JSX / HTML
const template = html`<lms-calendar></lms-calendar>`;

When tree-shaking, keep the side-effect import (e.g. add it to the sideEffects allow list if your bundler strips bare CSS imports).

Data contracts

TypeScript definitions ship with the package, but the essential shapes are below for quick reference:

type CalendarDate = { day: number; month: number; year: number };
type CalendarTime = { hour: number; minute: number };
type CalendarTimeInterval = { start: CalendarTime; end: CalendarTime };
type CalendarDateInterval = { start: CalendarDate; end: CalendarDate };

type CalendarEntry = {
    date: CalendarDateInterval;
    time: CalendarTimeInterval; // span 00:00-23:59 for all-day blocks
    heading: string;
    content: string;
    color: string; // any valid CSS color
    isContinuation: boolean; // the component recalculates this
    continuation?: Continuation; // auto-injected for multi-day entries
};

Constraints enforced inside willUpdate:

1. Entries with invalid date/time ranges (end before start) are dropped using luxon.Interval validation.
2. Arrays are sorted by start time so you do not need to pre-sort.
3. Multi-day entries are automatically expanded into per-day slices, and continuation metadata is injected for styling.

<lms-calendar> API surface

Public properties

Methods & Getters

• openMenu(eventDetails) opens the built-in lms-menu overlay with { heading, content, time?, displayTime, date?, anchorRect? }. Use this to integrate your own action surfaces (e.g., call openMenu when a host-side list item is clicked so the same menu renders).
• localeReady: Promise<void> — resolves when the current locale's translations are loaded. For English this resolves immediately. Use it to gate downstream work that depends on translated UI strings.

Reactive updates

• Reassign the entries array to trigger updates (calendar.entries = [...calendar.entries, newEntry]). Mutating in place without reassignment will not notify Lit.
• activeDate is mutable; consider persisting it in application state if deep-linking.
• The component maintains an internal viewMode state (month | week | day | year). Currently this is not exposed as a property; respond to the DOM events below if you need to stay in sync with user actions.

Custom DOM events

All events bubble and are composed, so you can listen directly on <lms-calendar> in any framework.

Note: The expand event payload varies by source — Month and Week views omit drillTarget, while Year view always includes it. See the Events Reference for full details.

You can stop propagation to replace built-in behavior. For example, intercept open-menu, call event.preventDefault(), and show your own drawer while leaving the rest of the component untouched.

For complete event documentation including payload types, source components, and code examples, see the Events Reference.

Year view integration

• The <lms-calendar-year> child receives a pre-computed entrySumByDay map (keys such as 2026-04-21) so density indicators remain O(1) per cell, even with thousands of entries.
• year-density-mode toggles how that count is rendered (dot, heatmap buckets, or explicit counts). Pair this with the CSS tokens described in README.md if you need brand-specific palettes.
• year-drill-target switches the default navigation when a user clicks any day: day jumps straight to the 24-hour view, month zooms into the grid of that month. Month headers in the year view always set drillTarget: 'month'.
• Listen for the expand event to synchronize external routers or analytics: event.detail.drillTarget mirrors the target you configured, so you can differentiate day-level vs. month-level navigation in your host app.

Entry ingestion and layout

1. Validation: willUpdate rejects entries whose date or time ranges are invalid per luxon Interval. Feed valid ISO-like data only.
2. Day splitting: _expandEntryMaybe uses DateTime.plus({ days: index }) to clone multi-day events. Continuation metadata is added so entry chips can indicate start, middle, or end segments.
3. All-day detection: Any entry without time, or whose time interval runs 00:00–23:59, is rendered in the dedicated all-day row using allocateAllDayRows logic.
4. Responsive month mode: if the observed width is <768px, month cells collapse to aggregated dots (displayMode = 'month-dot'). Above that threshold, full entry chips render inside each day.
5. Week/day stacking: LayoutCalculator and SlotManager determine vertical positioning (minuteHeight = 1 pixel) and horizontal cascading with progressive width reduction and offset. Overlapping events share column slots with opacity adjustments.

Styling and theming

The element exposes 151 CSS custom properties. Common entry points:

Apply tokens on the host element:

lms-calendar {
    --primary-color: #1976d2;
    --background-color: #fefefe;
    --entry-font-size: 0.85rem;
}

All styles live inside the component’s shadow root, so global CSS will not leak in unless you override the provided tokens.

Localization

• Set locale per instance to any of the built-in codes: en, ar, bn, cs, da, de, de-DE, el, es, fi, fr, he, hi, id, it, ja, ko, nb, nl, pl, pt, ru, sv, th, tr, uk, vi, zh-Hans.
• The component auto-detects from <html lang> when locale is unset.
• Day and month names come from Luxon/Intl; UI strings come from src/lib/messages.ts.
• Override the week structure via firstDayOfWeek (0=Sunday … 6=Saturday) to match local conventions independently of locale.
• No flash-of-English: when a non-English locale is set, the component hides its UI chrome (visibility: hidden) until the translation chunk loads, preventing a flash of English fallback text. The locale-ready event and localeReady promise let you coordinate with this loading if needed. English is zero-cost — translations are built-in, so no hiding or async loading occurs.

Accessibility behavior

• Header controls use semantic <button> elements with ARIA labels and aria-pressed states for the current view.
• Entry chips expose role="button", aria-selected, and keyboard handlers for Space/Enter activation.
• Focus management: when an entry opens the menu, focus moves into <lms-menu>; closing the menu restores focus to the triggering entry.
• aria-live="polite" wraps the main content so screen readers announce view changes.

Integration patterns

Vanilla JS

const calendar = document.querySelector('lms-calendar');
calendar.entries = buildEntriesFromApi(data);
calendar.addEventListener('switchview', (event) => {
    console.log('View changed to', event.detail.view);
});

React wrapper

import { useEffect, useRef } from 'react';
import '@jpahd/kalendus';

export function Calendar({ entries }: { entries: CalendarEntry[] }) {
    const ref = useRef<HTMLElement>(null);

    useEffect(() => {
        if (ref.current) {
            ref.current.entries = entries;
        }
    }, [entries]);

    return <lms-calendar ref={ref as React.RefObject<any>} heading="Schedule" />;
}

Vue 3 example

For Angular or Lit apps, treat <lms-calendar> as any other custom element; Angular 14+ supports standalone custom elements automatically, and Lit components can include it via unsafeStatic('lms-calendar') if needed.

Performance and state tips

• Immutable updates: always assign new arrays/objects so Lit notices changes.
• Chunked data: when streaming hundreds of events, pre-group by day server side to limit client work. The component handles large lists but layout work scales linearly with expanded entries.
• All-day events: omit the time block entirely for true all-day spans; this skips unnecessary minute grid calculations.
• Menu override: intercept open-menu for bulk updates instead of reading DOM to figure out which event was clicked.
• Resize awareness: the calendar uses ResizeObserver; keep it in a visible container so the observer can measure actual width.

Testing hooks

• Import @jpahd/kalendus inside your test harness once, then use @open-wc/testing fixtures to instantiate the element.
• Assert properties rather than DOM text when possible (e.g., expect(el.activeDate.year).to.equal(2026);).
• Dispatch DOM events to simulate navigation (el.shadowRoot.querySelector('lms-calendar-header')?.dispatchEvent(new CustomEvent('switchview', { detail: { view: 'week' }, bubbles: true, composed: true }));).

Troubleshooting

• Nothing renders: confirm lit and luxon peer deps are resolved once; duplicate copies can break instanceof checks.
• Entries not updating: ensure you reassign calendar.entries instead of mutating the existing array.
• Menu stuck open: check for listeners that swallow menu-close. If you replace the built-in menu, call clearSelection() on the triggering <lms-calendar-entry> to reset ARIA state.
• Incorrect locale: pass locale explicitly when embedding calendars inside documents whose <html lang> differs from the desired language.

Further Reading

• Events Reference — complete event documentation with payload types and code examples.
• CSS Token Reference — all 151 CSS custom properties.
• Layout & Positioning — height requirements, responsive behavior, all-day events.
• Troubleshooting — solutions for common issues.
• Rendering Calculations — slot math that powers week/day positioning.