@chaaanito/event-resource-calendar 1.0.2 → 1.2.0

package/README.md

@@ -1,17 +1,18 @@
 # EventResource
 
-A lightweight, high-performance vanilla JavaScript resource calendar library. Features O(1) internal event mapping, extensible rich HTML layout renderers, holiday detection, and scroll freezing.
+A lightweight, high-performance vanilla JavaScript resource calendar library. Features skeleton-first asynchronous rendering, O(1) internal event mapping, extensible rich HTML layout renderers, holiday detection, and scroll freezing.
 
 # Installation
 
 ```bash
-npm install event-resource-calendar
+npm install @chaaanito/event-resource-calendar
 ```
 
 # Quick Start
 
 ```javascript
-import EventResource from "event-resource-calendar";
+import EventResource from "@chaaanito/event-resource-calendar";
+import "@chaaanito/event-resource-calendar/style.css"; // Required for grid structural styling
 
 const calendar = new EventResource({
   container: "#calendar-root",
@@ -50,27 +51,32 @@ Pass these properties into the `EventResource` constructor to customize your cal
 
 | Property          | Type           | Default      | Description                                                           |
 | :---------------- | :------------- | :----------- | :-------------------------------------------------------------------- |
-| **container**     | `string\|Node` | _Required_   | CSS selector or DOM pointer mount node.                               |
+| **container**     | `string\|Node` | _Required_   | CSS selector or explicit DOM pointer mount node.                      |
 | **rooms**         | `Array`        | `[]`         | Master source list establishing rows along the vertical plane.        |
 | **timeSlots**     | `Array`        | `[]`         | Master source list defining columns mapped along the horizontal path. |
 | **initialEvents** | `Array`        | `[]`         | In-memory event array populating coordinates on load.                 |
 | **holidays**      | `Array`        | `[]`         | Configuration identifying structural exceptions and global days.      |
 | **customButtons** | `Array`        | `[]`         | Extensible collections rendering specialized tool structures.         |
-| **showControls**  | `boolean`      | `false`      | Visibility of structural management toolbars.                         |
-| **stickyHeaders** | `boolean`      | `true`       | Toggles CSS sticky double-axis tracking logic.                        |
-| **defaultView**   | `string`       | `'daily'`    | Default presentation layout. Must be 'daily' or 'weekly'.             |
+| **showControls**  | `boolean`      | `false`      | Visibility of structural management toolbars (Datepicker, arrows).    |
+| **stickyHeaders** | `boolean`      | `true`       | Toggles CSS sticky double-axis tracking logic across layout headers.  |
+| **defaultView**   | `string`       | `'daily'`    | Default presentation layout mode. Must be 'daily' or 'weekly'.        |
 | **defaultDate**   | `Date\|string` | `new Date()` | Frame configuration locking starting lifecycle boundaries.            |
 
 ### Callbacks & Renderers
 
-| Property                 | Type       | Description                                                        |
-| :----------------------- | :--------- | :----------------------------------------------------------------- |
-| **onCellClick**          | `Function` | Callback capturing clicks targeting empty coordinates.             |
-| **onEventClick**         | `Function` | Callback targeting allocated calendar card coordinates.            |
-| **fetchEvents**          | `Function` | Async method returning structural item sets based on date/view.    |
-| **renderRoomHeader**     | `Function` | HTML generator returning structural formatting for row slots.      |
-| **renderTimeSlotHeader** | `Function` | HTML generator returning structural formatting for column slots.   |
-| **renderEvent**          | `Function` | HTML generator returning custom markup for individual event cards. |
+| Property                 | Type       | Description                                                                  |
+| :----------------------- | :--------- | :--------------------------------------------------------------------------- |
+| **onCellClick**          | `Function` | Callback capturing clicks targeting empty coordinates.                       |
+| **onEventClick**         | `Function` | Callback targeting allocated calendar card coordinates.                      |
+| **fetchEvents**          | `Function` | Async method resolving to an array of `CalendarEvent` objects.               |
+| **fetchRooms**           | `Function` | Async method resolving to an array of `CalendarRoom` objects dynamically.    |
+| **fetchTimeSlots**       | `Function` | Async method resolving to an array of `TimeSlot` objects dynamically.        |
+| **fetchHolidays**        | `Function` | Async method resolving to an array of `CalendarHoliday` objects dynamically. |
+| **renderRoomHeader**     | `Function` | HTML generator returning structural formatting strings for row slots.        |
+| **renderTimeSlotHeader** | `Function` | HTML generator returning structural formatting strings for column slots.     |
+| **renderEvent**          | `Function` | HTML generator returning custom markup for individual event cards.           |
+
+---
 
 ## Data Models
 
@@ -92,7 +98,7 @@ Defines a timeline column structure partitioning the matrix grid workspace.
 | :-------- | :--------------- | :---------------------------------------------------------- |
 | **id**    | `string\|number` | **Required.** Unique identifier for the chronological slot. |
 | **label** | `string`         | **Required.** Fallback timeline display text.               |
-| **[key]** | `any`            | Optional custom properties (e.g., isLunchHour).             |
+| **[key]** | `any`            | Optional extensible properties (e.g., isLunchHour).         |
 
 ### CalendarEvent
 
@@ -105,28 +111,61 @@ Represents an allocated timeline event mapped directly into a specific intersect
 | **timeId** | `string\|number` | **Required.** Foreign key binding the item to a valid TimeSlot ID.    |
 | **title**  | `string`         | **Required.** Plain-text title injected inside the card element.      |
 | **color**  | `string`         | Optional CSS color value for the background card. Default: `#3b82f6`. |
-| **[key]**  | `any`            | Optional custom meta data attributes.                                 |
+| **[key]**  | `any`            | Optional custom meta data attributes parsed down to click payloads.   |
+
+### CalendarHoliday
+
+Maps specific dates to holiday statuses, shifting backgrounds and appending context data.
+
+| Property  | Type                   | Description                                                            |
+| :-------- | :--------------------- | :--------------------------------------------------------------------- |
+| **date**  | `string\|Date\|number` | **Required.** Parsable temporal timestamp mapping the milestone.       |
+| **name**  | `string`               | **Required.** Human-readable label injected into global notice badges. |
+| **[key]** | `any`                  | Optional open-ended customer specific holiday data.                    |
+
+---
 
 ## Interaction Payloads
 
-When interacting with the grid, the library fires callbacks with contextual payloads.
+When interacting with the grid, the library fires callbacks with comprehensive contextual payloads.
 
 ### ClickContextPayload (Empty Cell Click)
 
+Shared universally across grid click response lifecycles.
+
 | Property    | Type           | Description                                                        |
 | :---------- | :------------- | :----------------------------------------------------------------- |
 | **date**    | `Date`         | Chronological state baseline actively mounted inside the viewport. |
-| **view**    | `string`       | Current structural mode index ('daily' or 'weekly').               |
-| **holiday** | `Object\|null` | Associated holiday data object if applicable.                      |
-| **row**     | `Object`       | Track metadata coordinates (`index` and `data`).                   |
-| **col**     | `Object`       | Timeline metadata coordinates (`index` and `data`).                |
+| **view**    | `string`       | Current structural mode index configuration ('daily' or 'weekly'). |
+| **holiday** | `Object\|null` | Associated holiday data object if applicable to current date.      |
+| **row**     | `Object`       | Track metadata coordinates (`index` and `data` objects).           |
+| **col**     | `Object`       | Timeline metadata coordinates (`index` and `data` objects).        |
 | **cell**    | `Object`       | Target cell contents (`roomId`, `timeId`, and `events` array).     |
 
 ### EventClickPayload (Event Card Click)
 
-Inherits everything from `ClickContextPayload` and adds:
+Inherits all properties from `ClickContextPayload` and adds:
 
 | Property        | Type         | Description                                                                 |
 | :-------------- | :----------- | :-------------------------------------------------------------------------- |
-| **event**       | `Object`     | **Required.** The unique target event parameters bound to the clicked card. |
-| **nativeEvent** | `MouseEvent` | **Required.** Raw browser click interaction data.                           |
+| **event**       | `Object`     | **Required.** The explicit, unique target event parameters clicked.         |
+| **nativeEvent** | `MouseEvent` | **Required.** Raw browser click interaction data used for element tracking. |
+
+---
+
+## Public API Methods
+
+Once instantiated, the calendar instance exposes methods to control the grid programmatically.
+
+| Method                     | Description                                                                                     |
+| :------------------------- | :---------------------------------------------------------------------------------------------- |
+| **`addEvent(event)`**      | Injects a new event and performs an isolated, high-speed DOM append without layout thrashing.   |
+| **`removeEvent(eventId)`** | Purges a specific event by ID from memory and removes it from the UI instantly.                 |
+| **`clearAllEvents()`**     | Wipes all events from the board while preserving the layout skeleton rules.                     |
+| **`setDate(newDate)`**     | Jumps the calendar to a specific date. Automatically triggers `fetch` hooks if configured.      |
+| **`setView(newView)`**     | Mutates the layout granularity between daily and weekly modes.                                  |
+| **`Maps(direction)`**      | Steps the timeline forward or backward based on the current view multiplier.                    |
+| **`forceRender()`**        | Triggers a manual full data replenishment cycle, drawing the skeleton and resolving all asyncs. |
+| **`destroy()`**            | Unmounts the DOM, clears memory caches, and drops listener closures to prevent leaks.           |
+
+---

package/jsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist/types",
+    "strict": false
+  },
+  "include": ["src/**/*"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaaanito/event-resource-calendar",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chaaanito/event-resource-calendar.git"
@@ -11,7 +11,14 @@
   "homepage": "https://github.com/chaaanito/event-resource-calendar#readme",
   "type": "module",
   "main": "src/index.js",
+  "types": "dist/types/index.d.ts",
+  "style": "src/styles.css",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./style.css": "./src/styles.css"
   }
 }

package/src/event-resource.types.js

@@ -0,0 +1,98 @@
+/**
+ * @typedef {Object} CalendarRoom
+ * @description Defines a resource row within the calendar matrix grid layout.
+ * @property {string|number} id - REQUIRED: Unique identifier for the room or resource. Must be absolutely unique across all room rows.
+ * @property {string} name - REQUIRED: Fallback display title of the room/resource used if `renderRoomHeader` is omitted.
+ * @property {*} [key: string] - OPTIONAL: Any additional open-ended properties used for custom filtering or rich rendering templates.
+ */
+
+/**
+ * @typedef {Object} TimeSlot
+ * @description Defines a timeline column structure partitioning the matrix grid workspace.
+ * @property {string|number} id - REQUIRED: Unique identifier for the chronological slot. Must be unique across all columns.
+ * @property {string} label - REQUIRED: Fallback timeline display text used if `renderTimeSlotHeader` is omitted.
+ * @property {*} [key: string] - OPTIONAL: Any additional extensible properties used for custom filtering or rich rendering templates.
+ */
+
+/**
+ * @typedef {Object} CalendarEvent
+ * @description Represents an allocated timeline event mapped directly into a specific intersection cell.
+ * @property {string|number} id - REQUIRED: Unique identifier for the scheduled event element.
+ * @property {string|number} roomId - REQUIRED: Relational foreign key binding the item to a valid {@link CalendarRoom.id}.
+ * @property {string|number} timeId - REQUIRED: Relational foreign key binding the item to a valid {@link TimeSlot.id}.
+ * @property {string} title - REQUIRED: Plain-text title injected inside the DOM node element card.
+ * @property {string} [color='#3b82f6'] - OPTIONAL: Valid CSS color value (hex, rgb, hsl, keyword) for the background tracking card.
+ * @property {*} [key: string] - OPTIONAL: Custom meta data attributes parsed down to click event callback streams.
+ */
+
+/**
+ * @typedef {Object} CalendarHoliday
+ * @description Maps specific dates to holiday statuses, shifting backgrounds and appending context data to interaction payloads.
+ * @property {string|Date|number} date - REQUIRED: Parsable temporal timestamp mapping the holiday milestone. Must be resolvable by `new Date()`.
+ * @property {string} name - REQUIRED: The human-readable label injected into global notice badges and cell descriptors.
+ * @property {*} [key: string] - OPTIONAL: Open-ended customer specific holiday data.
+ */
+
+/**
+ * @typedef {Object} CustomButton
+ * @description Injectable client control appended directly onto the right-hand toolbar grouping matrix.
+ * @property {string} label - REQUIRED: Text descriptor rendered inside the interactive control button element frame.
+ * @property {function(MouseEvent): void} onClick - REQUIRED: Action handler fired immediately upon client interactions.
+ * @property {string} [className] - OPTIONAL: Space-delimited functional CSS style modifiers for custom visual overrides.
+ */
+
+/**
+ * @typedef {Object} ClickContextPayload
+ * @description Consolidated operational telemetry shared universally across grid click response lifecycles.
+ * @property {Date} date - Chronological state baseline actively mounted inside the viewport template frame.
+ * @property {'daily'|'weekly'} view - Current structural mode index configuration.
+ * @property {CalendarHoliday|null} holiday - Associated holiday data object if the current frame falls on a configured day milestone.
+ * @property {Object} row - Track metadata coordinates.
+ * @property {number} row.index - Vertical index array placement coordinate.
+ * @property {CalendarRoom} row.data - Complete root object data context passed down from initialization.
+ * @property {Object} col - Timeline metadata coordinates.
+ * @property {number} col.index - Horizontal layout coordinate tracking indexes.
+ * @property {TimeSlot} col.data - Complete root chronological object parameters.
+ * @property {Object} cell - Operational target cell contents.
+ * @property {string|number} cell.roomId - Unique cell row lookup index.
+ * @property {string|number} cell.timeId - Unique cell column chronological coordinate index.
+ * @property {CalendarEvent[]} cell.events - Contextual array containing all events currently occupying this grid location.
+ */
+
+/**
+ * @typedef {Object} EventClickPayload
+ * @description Multi-layered payload shared exclusively with the `onEventClick` subscriber method.
+ * @extends ClickContextPayload
+ * @property {CalendarEvent} event - REQUIRED: The explicit, unique target event parameters bound to the clicked card element.
+ * @property {MouseEvent} nativeEvent - REQUIRED: Raw browser click interaction data used for analytical intercept positioning or element tracking.
+ */
+
+/**
+ * @typedef {Object} EventResourceOptions
+ * @description Input operational context map parsing standard parameters through class factories.
+ * @property {string|HTMLElement|Node} container - REQUIRED: CSS selector engine target or explicit DOM pointer mount node.
+ * @property {CalendarRoom[]} [rooms=[]] - OPTIONAL: Master source list establishing rows along the vertical plane matrix mapping layout.
+ * @property {TimeSlot[]} [timeSlots=[]] - OPTIONAL: Master source list defining columns mapped along the horizontal path lane.
+ * @property {CalendarEvent[]} [initialEvents=[]] - OPTIONAL: In-memory event array populating coordinates during setup initialization workflows.
+ * @property {CalendarHoliday[]} [holidays=[]] - OPTIONAL: Array configuration identifying structural exceptions and specialized global days.
+ * @property {CustomButton[]} [customButtons=[]] - OPTIONAL: Extensible collections rendering specialized tool structures within toolbars.
+ * @property {boolean} [showControls=false] - OPTIONAL: Flag managing initialization visibility of structural management toolbars.
+ * @property {boolean} [stickyHeaders=true] - OPTIONAL: Toggles CSS sticky double-axis tracking logic across layout headers on load.
+ * @property {'daily'|'weekly'} [defaultView='daily'] - OPTIONAL: Default presentation structure layout selection state. Must be 'daily' or 'weekly'.
+ * @property {Date|string|number} [defaultDate=new Date()] - OPTIONAL: Frame configuration locking starting lifecycle boundaries.
+ * @property {function(ClickContextPayload): void} [onCellClick] - OPTIONAL: Interaction callback capturing clicks targeting empty coordinates.
+ * @property {function(EventClickPayload): void} [onEventClick] - OPTIONAL: Interaction callback targeting allocated calendar card coordinates.
+ * @property {function(Date, 'daily'|'weekly'): Promise<CalendarEvent[]>} [fetchEvents] - OPTIONAL: Data fetching intercept. Async method returning structural item sets.
+ * @property {function(CalendarRoom): string} [renderRoomHeader] - OPTIONAL: HTML generator intercept returning structural formatting strings for row slots.
+ * @property {function(TimeSlot): string} [renderTimeSlotHeader] - OPTIONAL: HTML generator intercept returning structural formatting strings for column slots.
+ * @property {function(CalendarEvent): string} [renderEvent] - OPTIONAL: HTML generator intercept returning custom markup for individual event cards. Overrides default title text.
+ * @property {function(Date, 'daily'|'weekly'): Promise<CalendarEvent[]>} [fetchEvents] - OPTIONAL: Async method returning events.
+ * @property {function(Date, 'daily'|'weekly'): Promise<CalendarRoom[]>} [fetchRooms] - OPTIONAL: Async method returning rooms dynamically.
+ * @property {function(Date, 'daily'|'weekly'): Promise<TimeSlot[]>} [fetchTimeSlots] - OPTIONAL: Async method returning timeline columns dynamically.
+ * @property {function(Date, 'daily'|'weekly'): Promise<CalendarHoliday[]>} [fetchHolidays] - OPTIONAL: Async method returning holidays dynamically.
+ * * @property {function(CalendarRoom): string} [renderRoomHeader] - OPTIONAL: HTML generator intercept.
+ * @property {function(TimeSlot): string} [renderTimeSlotHeader] - OPTIONAL: HTML generator intercept.
+ * @property {function(CalendarEvent): string} [renderEvent] - OPTIONAL: HTML generator intercept.
+ */
+
+export {};