@liturgical-calendar/components-js

A reusable ES6/JavaScript component library for the Liturgical Calendar API. Build liturgical calendar interfaces without a build step.

Quick Start

<script type="module">
import {
    ApiClient,
    CalendarSelect,
    LiturgyOfTheDay
} from 'https://cdn.jsdelivr.net/npm/@liturgical-calendar/components-js@latest/+esm';

ApiClient.init().then((apiClient) => {
    if (!(apiClient instanceof ApiClient)) return;

    const calendarSelect = new CalendarSelect('en-US')
        .class('form-select')
        .allowNull();
    calendarSelect.appendTo('#calendar-container');

    const liturgy = new LiturgyOfTheDay('en-US')
        .class('liturgy-widget')
        .showReadings(true)
        .listenTo(apiClient);
    liturgy.appendTo('#liturgy-container');

    apiClient.listenTo(calendarSelect);
    apiClient.fetchCalendar('en');
});
</script>

Components

| Component | Description | |-----------|-------------| | ApiClient | Manages API communication and data fetching | | CalendarSelect | Dropdown for selecting liturgical calendars | | ApiOptions | Form controls for API parameters | | WebCalendar | Full calendar table with customizable display | | LiturgyOfTheDay / LiturgyOfAnyDay | Daily liturgy widgets | | PathBuilder | API URL builder tool | | Utils | Utility functions for locale detection and validation |

Documentation

• Installation & Usage - CDN usage, import maps, local development
• Storybook & Development - Running Storybook, Docker setup
• Enums Reference - All available enum values
• Examples - Working example applications

Examples

The examples/ folder contains complete working examples:

| Example | Description | |---------|-------------| | LiturgyOfTheDay | Today's liturgy with calendar/locale selection | | LiturgyOfAnyDay | Browse any date with lectionary readings | | WebCalendar | Full calendar table with display options | | PathBuilder | Interactive API URL builder |

To run examples:

1. Start the Liturgical Calendar API on localhost:8000
2. Serve the project: python3 -m http.server 3001
3. Open http://localhost:3001/examples/LiturgyOfTheDay/

Exports

export {
    // Components
    ApiClient,
    CalendarSelect,
    ApiOptions,
    WebCalendar,
    LiturgyOfTheDay,
    LiturgyOfAnyDay,
    PathBuilder,
    Input,
    Utils,

    // Enums
    Grouping,
    ColorAs,
    Column,
    ColumnOrder,
    DateFormat,
    GradeDisplay,
    ApiOptionsFilter,
    CalendarSelectFilter,
    YearType,
    LatinInterface
}

Key Features

• No build step required - Use directly from CDN with ES6 imports
• Chainable configuration - Fluent API for all components
• Automatic caching - Reduces redundant API requests
• Locale support - 13 languages supported
• Bootstrap compatible - Easy integration with Bootstrap 5
• TypeScript definitions - Full type support in dist/index.d.ts

Browser Support

Modern browsers with ES6 module support. Requires <script type="module">.

Development

yarn install          # Install dependencies
yarn compile          # Compile TypeScript
yarn test             # Run tests
yarn storybook        # Launch Storybook

See Storybook documentation for detailed setup.

License

ISC