feat(ics): adds property management, alarms

Adds helper methods to add and remove properties from ICS files.
Implements dedicated methods for adding VALARM entries. Properly exports
types.

BREAKING CHANGE: renames IOptions to type CalendarOptions, IRecurrence
to CalendarRecurrence.

README.md

@@ -49,23 +49,44 @@ yarn add datebook
 ### Example Usage
 
 ```js
-import { ICalendar } from 'datebook'
-
-const icalendar = new ICalendar({
+const config = {
   title: 'Happy Hour',
   location: 'The Bar, New York, NY',
   description: 'Let\'s blow off some steam with a tall cold one!',
   start: new Date('2022-07-08T19:00:00'),
   end: new Date('2022-07-08T23:30:00'),
+  // an event that recurs every two weeks:
   recurrence: {
     frequency: 'WEEKLY',
     interval: 2
   }
-})
+}
+```
+
+#### iCalendar
+
+```js
+const icalendar = new ICalendar(config)
 
 icalendar.download()
 ```
 
+This will download `Happy Hour.ics` onto the user's device. On most mobile devices, this will open the default calendar app with the event.
+
+#### Google Calendar
+
+```js
+const googleCalendar = new GoogleCalendar(config)
+
+googleCalendar.render()
+```
+
+`googleCalendar.render()` will return a URL that the user can navigate to and pre-fill event details:
+
+```
+https://calendar.google.com/calendar/render?action=TEMPLATE&text=Happy%20Hour&details=Let's%20blow%20off%20some%20steam%20with%20a%20tall%20cold%20one!&location=The%20Bar%2C%20New%20York%2C%20NY&dates=20220708T190000%2F20220708T230000&recur=RRULE%3AFREQ%3DWEEKLY%3BINTERVAL%3D1
+```
+
 ## Browser Support
 
 The latest versions of all major browsers are supported.

docs/docs/config.md

@@ -30,28 +30,20 @@ A summary description of the event location. Line breaks are automatically strip
 
 ### start
 
-* Type: [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), or `string` (deprecated)
+* Type: [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) (<Badge text=">= 5.0.0"/>), or `string` (deprecated)
 * Required: **yes**
 * Valid value: a valid `Date` reference, or any [ISO 8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) value (deprecated).
 
 The event start timestamp. See [date formats](date.md) for more information.
 
-:::warning Note
-Specifying dates as strings is deprecated and will be removed in version **5.0.0**.
-:::
-
 ### end
 
-* Type: [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), or `string` (deprecated)
+* Type: [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) (<Badge text=">= 5.0.0"/>), or `string` (deprecated)
 * Required: **yes**, if not an all-day event
 * Valid value: a valid `Date` reference, or any [ISO 8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) value (deprecated).
 
 The event end timestamp. For all-day events, this field should be omitted. See [date formats](date.md) for more information.
 
-:::warning Deprecation Notice
-Specifying dates as strings is deprecated and will be removed in version **5.0.0**.
-:::
-
 ## Recurrence
 
 The recurrence of an event is how often the event is supposed to occur. Some examples of this could be:
@@ -62,7 +54,7 @@ The recurrence of an event is how often the event is supposed to occur. Some exa
 
 Recurrence is **optional**.
 
-:::warning Deprecation Notice
+:::warning Note
 This feature is not supported in Outlook online calendars.
 :::
 
@@ -102,15 +94,14 @@ If this parameter is specified in conjunction with [`end`](#recurrence-end), the
 
 ### recurrence.end
 
-* Type: [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), or `string` (deprecated)
+* Type: [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) (<Badge text=">= 5.0.0"/>), or `string` (deprecated)
 * Required: no
 * Valid value: a valid `Date` reference, or any [ISO 8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) value (deprecated).
 
 The latest date that this event may occur on. See [time formats](date.md) for more information.
 
 :::warning Important
-* Specifying dates as strings is deprecated and will be removed in version **5.0.0**.
-* If this parameter is specified in conjunction with [`end`](#recurrence-end), the recurrence will end either when `count` is completed, or when `end` occurs, whichever happens first.
+If this parameter is specified in conjunction with [`end`](#recurrence-end), the recurrence will end either when `count` is completed, or when `end` occurs, whichever happens first.
 :::
 
 ### recurrence.weekdays
@@ -206,4 +197,4 @@ This will generate recurrences on the following dates:
 
 * January 15 and 30
 * February 15
-* March 15, 30
+* March 15, 30

docs/docs/date.md

@@ -2,21 +2,21 @@
 
 Dates, including `options.start`, `options.end`, and `recurrence.end`, should be passed in as JavaScript [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) objects. This provides full control over the date, including the specification of timezones.
 
-## Legacy date support (deprecated)
+## Legacy date support <Badge text="deprecated" type="warning" /> <Badge text="<= 4.1.11" />
 
 For backwards compatibility, you may still provide the date as a `string` formatted as [ISO 8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString). Dates not formatted this way will result in `NaN` returned as start and/or end times.
 
 From the [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString):
 
 > [The] simplified extended ISO format (ISO 8601), is always 24 or 27 characters long (`YYYY-MM-DDTHH:mm:ss.sssZ` or `±YYYYYY-MM-DDTHH:mm:ss.sssZ`, respectively). The timezone is always zero UTC offset, as denoted by the suffix "Z."
 
-:::warning Deprecation Notice
-Specifying dates as strings is deprecated and will be removed in version **5.0.0**.
+:::danger Deprecation Notice
+Specifying dates as strings is deprecated and has been removed in version **5.0.0**.
 :::
 
 ## Valid date examples
 
 * `2021-07-04T21:20:15:00.000Z`
 * `2021-07-04T21:20:15:00.000+05:00` (+500 timezone)
 * `2021-07-04T21:20:15`
-* `2021-07-04`
+* `2021-07-04`

src/CalendarBase.ts

@@ -1,6 +1,6 @@
-import ICalendarBase from './interfaces/ICalendarBase'
-import IRecurrence from './interfaces/IRecurrence'
-import IOptions from './interfaces/IOptions'
+import ICalendarBase from './types/ICalendarBase'
+import CalendarRecurrence from './types/CalendarRecurrence'
+import CalendarOptions from './types/CalendarOptions'
 import time from './utils/time'
 
 /**
@@ -50,28 +50,28 @@ class CalendarBase implements ICalendarBase {
   end = new Date()
 
   /**
-   * Event recurrence specification. See {@link IRecurrence}
+   * Event recurrence specification. See {@link CalendarRecurrence}
    *
-   * @type {IRecurrence}
+   * @type {CalendarRecurrence}
    */
-  recurrence?: IRecurrence
+  recurrence?: CalendarRecurrence
 
   /**
    * Constructor.
    *
-   * @param {IOptions} options
+   * @param {CalendarOptions} options
    */
-  constructor (options: IOptions) {
+  constructor (options: CalendarOptions) {
     this.setText(options)
     this.setTimestamps(options)
   }
 
   /**
    * Sets the description, title and location.
    *
-   * @param {IOptions} options
+   * @param {CalendarOptions} options
    */
-  setText (options: IOptions): void {
+  public setText (options: CalendarOptions): void {
     this.description = options.description || ''
     this.title = options.title || ''
     this.location = options.location || ''
@@ -80,9 +80,9 @@ class CalendarBase implements ICalendarBase {
   /**
    * Sets the time and recurrence parameters.
    *
-   * @param {IOptions} options
+   * @param {CalendarOptions} options
    */
-  setTimestamps (options: IOptions): void {
+  public setTimestamps (options: CalendarOptions): void {
     this.allday = !options.end
     this.start = options.start
 
@@ -95,6 +95,15 @@ class CalendarBase implements ICalendarBase {
 
     this.recurrence = options.recurrence
   }
+
+  /**
+   * Render stub.
+   *
+   * @throws {Error}
+   */
+  public render (): string {
+    throw new Error('Render not implemented')
+  }
 }
 
 export default CalendarBase

src/GoogleCalendar.ts

@@ -1,5 +1,5 @@
 import CalendarBase from './CalendarBase'
-import IOptions from './interfaces/IOptions'
+import CalendarOptions from './types/CalendarOptions'
 import data from './utils/data'
 import ics from './utils/ics'
 import time from './utils/time'
@@ -12,7 +12,7 @@ export default class GoogleCalendar extends CalendarBase {
   /**
    * @inheritDoc
    */
-  constructor (options: IOptions) {
+  constructor (options: CalendarOptions) {
     super(options)
   }
 
@@ -21,7 +21,7 @@ export default class GoogleCalendar extends CalendarBase {
    *
    * @returns {string}
    */
-  render (): string {
+  public render (): string {
     let timestampFormat = FORMAT.DATE
 
     if (!this.allday) {